beads/docs/cli-reference/merge-slot.md
Chris Sells de0200ff77 docs(emitter): Cobra-accurate usage lines, published global flags, MDX ESM guard
Three generated-content defects from the adversarial review, all
structurally invisible to the drift gate (generated-vs-generated):

- Usage lines now mirror Cobra's help template: a runnable command shows
  its UseLine, a command with subcommands shows '<path> [command]', both
  when both apply. Previously bare UseLine() stamped 'bd mol [flags]' on
  30 parent pages — a line the binary never prints.
- The generated CLI index publishes the Global Flags block; the binary
  prints it on every --help but no page carried it.
- docsmint neutralizes prose lines that Mintlify's prebuild would dedent
  into MDX ESM blocks (a line beginning 'export'/'import' outside a
  fence gets wrapped in a code span). This is why /cli-reference/mail
  returned HTTP 200 while rendering only a parse-error placeholder —
  reproduced, fixed, and covered by a planted-hazard test; fenced
  content stays verbatim.

Also rewords check-cli-docs-drift.sh's early-PASS message, which
asserted 'the supplied binary differs' as the cause when uncommitted
local edits produce the same result.

All 113 pages + docs/CLI_REFERENCE.md regenerated through the pipeline;
TDD'd in cmd/bd/help_all_test.go and tools/docsmint/docsmint_test.go.
Verified live: /cli-reference/mail renders real content, zero parse
errors; generate-cli-docs.sh --check, docsync, freshness, and
mint broken-links all pass on this tree.
2026-07-12 10:37:17 -07:00

2.4 KiB

title description
bd merge-slot Manage merge-slot gates for serialized conflict resolution

{/* AUTO-GENERATED: do not edit manually */}

Generated from bd help --doc merge-slot.

Merge-slot gates serialize conflict resolution in the merge queue.

A merge slot is an exclusive access primitive: only one agent can hold it at a time. This prevents "monkey knife fights" where multiple polecats race to resolve conflicts and create cascading conflicts.

Each rig has one merge slot bead: <prefix>-merge-slot (labeled gt:slot). The slot uses:

  • status=open: slot is available
  • status=in_progress: slot is held
  • metadata.holder: who currently holds the slot
  • metadata.waiters: priority-ordered queue of waiters

Examples: bd merge-slot create # Create merge slot for current rig bd merge-slot check # Check if slot is available bd merge-slot acquire # Try to acquire the slot bd merge-slot release # Release the slot

bd merge-slot [command]

bd merge-slot acquire

Attempt to acquire the merge slot for exclusive access.

If the slot is available (status=open), it will be acquired:

  • status set to in_progress
  • holder set to the requester

If the slot is held (status=in_progress), the command fails unless --wait is passed, which adds the requester to the waiters queue.

Use --holder to specify who is acquiring (default: BEADS_ACTOR env var).

bd merge-slot acquire [flags]

Flags:

      --holder string   Who is acquiring the slot (default: BEADS_ACTOR)
      --wait            Add to waiters list if slot is held

bd merge-slot check

Check if the merge slot is available or held.

Returns:

  • available: slot can be acquired
  • held by <holder>: slot is currently held
  • not found: no merge slot exists for this rig
bd merge-slot check [flags]

bd merge-slot create

Create a merge slot bead for serialized conflict resolution.

The slot ID is automatically generated based on the beads prefix (e.g., gt-merge-slot). The slot is created with status=open (available).

bd merge-slot create [flags]

bd merge-slot release

Release the merge slot after conflict resolution is complete.

Sets status back to open and clears the holder field. If there are waiters, the highest-priority waiter should then acquire.

bd merge-slot release [flags]

Flags:

      --holder string   Who is releasing the slot (for verification)