beads/docs/workflows/gates.md
Bee a6fcf915c0
fix(gate): resolve a bead gate whose awaited bead no longer exists (#6395)
* fix(gate): resolve a bead gate whose awaited bead no longer exists (wy-dgfuiu)

A gate with await_type=bead whose awaited bead has been purged could never
resolve: GetIssue returns storage.ErrNotFound (or a wrapped sql.ErrNoRows)
against real storage, checkBeadGate returned (false, "bead gate %q: %v"), the
bead arm of evaluateGates never sets r.err, and applyGateCheckResults fell to
the "pending" arm with exit 0. The gate stayed pending forever.

Treat a missing bead as resolution, reusing the existing gateProxiedNotFound
predicate so a genuine backend or transport failure still stays pending.
close.go shares checkBeadGate and inherits the fix.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MjQHZQoR8qZTaNj2QTZokr

* fix(gate): resolve a deleted bead gate target only after a local sighting

Review fixes for #6395 (adopt-pr iterations 1 to 5).

The PR resolves a bead gate when its awaited bead no longer exists, but
the lookups it relies on turned a routing failure into not-found: the
direct getter (getIssueWithRouting) and the proxied getter both returned
the local miss when a prefix-routed rig could not be read, so an OPEN
bead in an unreachable rig resolved its gate and unblocked the step. An
await_id that never named a real bead (a typo, a short ID) also resolved
on the first check.

- A miss outside this rig's own store is errBeadGateTargetUnconfirmed: a
  matched routes.jsonl route whose rig fails or does not return the bead,
  an unreadable routes.jsonl, or the contributor auto-routed store. The
  gate stays pending and the reason names the cause. inspectBeadGate
  tests it before not-found, because the wrapped routing error can itself
  be a not-found. Only this rig's own absence counts as gone.
- bd gate check resolves a gone target only if an earlier check saw it in
  this rig. The first local sighting stamps await_seen=<await_id> in the
  gate's metadata (an OpSetMetadata merge, so other keys survive, and
  retargeting the gate invalidates it). A target that is gone and was
  never seen stays pending with "no earlier gate check saw it; check the
  await_id, or close the gate with bd gate resolve". A bead read through
  a route is never stamped, so a misdirected route cannot arm a later
  local miss. A failed stamp write is an error row, like a failed gh:run
  await_id persist.
- The proxied getter reads the target with workapi.GetIssueOrWisp (the
  issue use case alone never returns a wisp), stamps inside the apply
  transaction, and never auto-routes.
- bd close applies the same rule (evaluateBeadGate, recording no
  sighting): a gone bead satisfies the gate only if an earlier check saw
  it, so closing a gate on a typo'd await_id still needs --force.
- bd close reads the awaited bead from the store that owns the gate
  (RoutedResult.Store), as bd gate check in that rig would. Read from the
  launcher's store, a routed gate whose awaited bead only its own rig can
  reach (no route for it from the launcher) saw that open bead as missing
  and, its sighting recorded, closed without --force. The proxied-server
  route keeps the fresh-read getter (#5861).
- bd rename and bd rename-prefix (both the rename loop and --repair) point
  a bead gate at its bead's new ID, keeping a <rig>: prefix and carrying
  the sighting. UpdateIssueID rewrites text references but never
  await_id, so a seen bead's rename read as a deletion and resolved the
  gate on its next check.
- UpdateIssueID also commits on its own, so a retarget written after it
  left a window, or after a failure a lasting state, where the gate held
  a sighting of an ID that no longer existed and resolved while its bead
  was open under the new ID. All three paths now rename through
  renameIssueKeepingBeadGates, which orders the writes so no state in
  between resolves a gate: it moves await_id to the new ID while the
  sighting still names the old one (dropping, in the same write, a
  sighting that already names the new ID), renames the bead, and then
  records the sighting under the new ID. A check in between finds a
  never-seen ID and stays pending. If moving a gate or renaming the bead
  fails, the gates are pointed back at the old ID without a sighting,
  since a failed write may still have landed, and the rename fails:
  bd rename exits non-zero instead of warning from its text-reference
  loop. Losing only the final sighting write is a warning; the next
  check records the sighting again.
- A check lists the gate before it looks the bead up, so a rename landing
  in between left it holding a copy that still waited on the old ID with
  its sighting: the old ID was gone, and the check closed the gate while
  the bead was open under its new ID. Once the bead is found gone,
  evaluateBeadGate reads the gate back from its own store
  (rereadBeadGate) and resolves only if the stored gate still waits on
  the same await_id and still records the sighting. The rename moves the
  gate before the bead takes the new ID, so a read made after the miss
  sees the move. This covers bd gate check, its proxied route and
  bd close; a gate that cannot be read back, or is found only through a
  route, stays pending.
- checkBeadGate, the target lookup without the sighting rule, had no
  production caller left and read like the bead-gate rule, which is how
  bd close came to skip the sighting. It moves into the tests;
  inspectBeadGate carries the lookup contract and points callers at
  evaluateBeadGate.
- The gate check help, docs/workflows/gates.md and the CHANGELOG describe
  the rule, including that a rename does not read as a deletion to a
  check or bd close that read the gate before it, and that a rename that
  fails partway leaves the gate pending without a sighting; the #6404
  entry no longer says a routed read failure reads as not-found. The
  CHANGELOG also warns that a rename by an older bd does not move the
  gate, so once a check has seen the bead, the next check or bd close
  after that rename closes the gate while the bead is still open:
  upgrade the clients that rename beads together with the ones that
  check gates. docs/cli-reference is pinned to v1.2.2, so it is
  unchanged (generate-cli-docs.sh --check passes).

Tests: TestCheckBeadGate_UnconfirmedMissStaysPending,
TestEvaluateGates_BeadGateSightingRule, TestEvaluateBeadGate_*,
TestBeadGateSeenUpdate_KeepsOtherMetadata, TestBeadGateTargetSeen,
TestProxiedFreshReadGetter_LocalMissFollowsRoutes,
TestRoutedBeadGateGetter_ReportsWhereTheAnswerCameFrom,
TestCheckGateSatisfaction_BeadGateNeedsASighting,
TestCloseDirectPreflight_BeadGateReadsTheGatesOwnStore,
TestCloseBeadGateGetter_RouteSelection, TestBeadGateRetargetUpdate,
TestPlanBeadGateMoves, TestRenameIssueKeepingBeadGates and
TestRenameIssueKeepingBeadGates_FailedWritesResolveNoGate, which fails
each write of a rename in turn, landed or not, and evaluates every gate
after each write, both as stored and as a concurrent check listed it
before the rename (unit); the unreadable-rig step of
TestCheckBeadGateCrossRigPrefixRoute,
TestRepairPrefixesRetargetsBeadGates (gates renamed before and after
their bead) and TestRenameFailureLeavesBeadGatesPending (bd rename,
--repair and rename-prefix with a failing UpdateIssueID, landed or not)
(cgo);
TestEmbeddedGateCreate/check_bead_gate_resolves_only_a_missing_target_it_saw
and /rename_keeps_a_bead_gate_on_its_target (embedded);
TestProxiedServerGateCheck/bead_gate_resolves_when_seen_target_is_deleted
and /bead_gate_never_seen_target_stays_pending (proxied). Reordering the
unconfirmed case after not-found, dropping the sighting condition,
swallowing the routed error, stamping routed sightings, or matching any
stamp regardless of await_id each fails these tests, as do closing with
the sighting-blind lookup, reading the launcher's store on close,
dropping the carried sighting or the rig prefix on a retarget, dropping
the retarget from bd rename, the rename-prefix loop or --repair,
renaming the bead before moving its gates, keeping the sighting when
moving a gate back, keeping a stale sighting of the new ID, skipping
the final sighting write, resolving a gone bead without reading the gate
back or from a gate read back that moved, lost its sighting or was found
only through a route, or reporting an unconfirmed read-back as an error
or an unreadable gate as pending.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
2026-10-08 17:10:33 +00:00

8.5 KiB

title description
Gates Async wait conditions that park a workflow step until the world catches up — a human decision, a timer, or a GitHub run or PR.

Some workflow steps can't proceed on code alone: a release needs CI to go green, a deploy needs a human sign-off, a cleanup should wait 24 hours. A gate is an issue that represents that wait. It blocks a step the same way any blocker does — the step leaves the ready frontier until the gate closes — so agents never need to poll or spin.

How a gate works

A gate is a bead like any other: created open, it blocks its waiters through a normal dependency edge, and the step becomes ready the moment the gate closes. Gates close in one of two ways:

  • Manually — bd gate resolve <gate-id> (human gates always close this way).
  • Via bd gate check — evaluates open timer, GitHub, and bead gates against the real world and closes the ones whose condition is met.
bd gate list                 # open gates
bd gate list --all           # include closed
bd gate show <gate-id>       # details and waiters
bd gate check                # evaluate open gates, close satisfied ones
bd gate check --dry-run      # report without closing
bd gate resolve <gate-id>    # close a gate manually

Gate types

Type Waits for Closed by
human a person's decision bd gate resolve only
timer a duration after gate creation bd gate check once the timeout elapses
gh:run a GitHub Actions workflow to complete successfully bd gate check (uses gh run view)
gh:pr a pull request to merge bd gate check (uses gh pr view)
bead a bead to close, or to be deleted once a check has seen it — a plain ID names a bead in this rig, the cross-rig form is <rig>:<bead-id> bd gate check for plain local IDs; cross-rig values cannot be checked — resolve those manually

A bead gate also closes when its awaited bead is deleted, as long as an earlier bd gate check saw that bead in this rig; the check records the sighting in the gate's await_seen metadata. An await ID that no check has seen, such as a typo or a bead deleted before the first check, keeps the gate pending with a diagnostic: correct the await ID or close the gate with bd gate resolve. Renaming the awaited bead with bd rename or bd rename-prefix moves the gate's await ID and sighting to the new ID, so a rename does not count as a deletion, even to a bd gate check or bd close that read the gate before the rename; a rename that fails partway leaves the gate pending without a sighting, never resolved.

Timeouts use Go duration syntax: 30m, 1h, 24h (there is no d unit — write 24h, not 1d).

GitHub gates use the current Git repository by default. To evaluate a PR or workflow run in another repository, set the gate's string metadata.repo value to OWNER/REPO or HOST/OWNER/REPO. An ad-hoc gh:run/gh:pr gate created with bd gate create takes that value from --repo, or, without the flag, inherits a valid metadata.repo value from the issue it blocks; human/timer/bead gates do neither (--repo is refused on them), since metadata.repo is unrelated, ordinary metadata for those types. bd gate check rejects malformed repository values instead of falling back to the current repository, and when a PR number does not resolve, the escalation names the repository it was looked up in. A gate for a PR in another repository whose blocked issue carries no metadata.repo needs --repo: without it the number is looked up in the current repository and escalates as not found on every check.

bd gate create --type=gh:pr --blocks bd-abc --await-id=42 --repo=owner/other-repo

Known limitations: multi-rig and proxied-server topologies

Bead gates and prefix routing (routes.jsonl) do not work in every topology. Two limitations to expect, both tracked in #5861:

  • Cross-rig bead gates never resolve on their own. A <rig>:<bead-id> await value reports cannot be checked (multi-rig routing removed) and stays pending regardless of the awaited bead's status. Close it with bd gate resolve.
  • Prefix routing cannot open a proxied-server target rig. A routed lookup into a rig that is itself in proxied-server mode fails with proxy server store needs to be uow provider, so an all-proxied shared-server topology cannot resolve routed targets at all.

Gates in formulas

A formula step declares a gate with a [steps.gate] block. When the formula is instantiated, bd creates the gate issue and wires it as a blocker of that step. The schema has five fields: type, id, await_id, timeout, and repo.

This is the release gate from beads' own release formula — the step that waits for the GitHub release workflow:

[[steps]]
id = "wait-for-ci"
title = "Wait for release workflow"

[steps.gate]
type = "gh:run"
id = "release.yml"       # which workflow to watch
timeout = "30m"          # escalate if it takes longer

For a gh:run or gh:pr gate that watches another repository, set repo the same way a metadata.repo value works for an ad-hoc gate — OWNER/REPO or HOST/OWNER/REPO. Malformed values are rejected when the gate is checked:

[[steps]]
id = "wait-for-downstream"
title = "Wait for downstream release"

[steps.gate]
type = "gh:run"
id = "release.yml"
repo = "org/downstream-repo"   # check gh:run against this repo, not the current one

repo accepts a {{var}} placeholder (e.g. repo = "{{gate_repo}}"); for a formula persisted with bd cook --persist, the placeholder is substituted when the proto is later poured with bd mol pour --var gate_repo=..., the same as every other var-bearing step field (title, description, design, acceptance_criteria, notes, assignee, labels, await_id, and the string values inside metadata).

bd gate discover (auto-discovery of a gh:run gate's run ID) requires a workflow name hint (await_id/id, not left blank) for a gate targeting another repository — without one, the local commit/branch heuristics that narrow a same-repo match don't apply across repos, so nothing but the workflow name can identify the right run. A cross-repo gate discovery also ignores the local checkout's branch unless --branch is passed explicitly; an auto-detected local branch has no relationship to the target repo's branches.

A human sign-off gate:

[[steps]]
id = "approve-deploy"
title = "Human approves the deploy"

[steps.gate]
type = "human"

And a cooling-off timer:

[[steps]]
id = "wait-24h"
title = "Let the release bake"

[steps.gate]
type = "timer"
timeout = "24h"

Verify what the parser actually understood before pouring — unknown keys in TOML are dropped silently:

bd formula show <formula> --json   # inspect the parsed gate blocks

Creating gates outside formulas

bd gate create attaches a gate to existing work:

# Block bd-abc until a PR merges
bd gate create --type=gh:pr --blocks bd-abc --await-id=42

# Block bd-abc until a human resolves the gate
bd gate create --type=human --blocks bd-abc --reason "Design sign-off"

# Add another waiter to an existing gate
bd gate add-waiter <gate-id> <issue-id>

Fan-in: waiting on other steps

Waiting on other steps is not a gate — it's a dependency. Use needs to fan in on named steps, and waits_for when a step must wait for dynamically-created children:

[[steps]]
id = "merge-results"
title = "Merge results"
needs = ["test-a", "test-b"]     # fan-in on named steps

[[steps]]
id = "fan-out"
title = "Spawn a worker per shard"

[[steps]]
id = "summarize"
title = "Summarize all spawned work"
needs = ["fan-out"]              # the spawner whose children to wait for
waits_for = "all-children"       # or "any-children", or "children-of(fan-out)"

all-children and any-children wait for the children of needs[0], so a step using them must declare needs; children-of(step-id) names the spawner itself and does not. A bare gate with neither is rejected when the formula is cooked, because it would wait for no one.

Working with gated molecules

bd ready --gated        # molecules where a gate just closed (ready to resume)
bd blocked              # what's waiting, and on which gates

Automation patterns: run bd gate check on a schedule (cron, CI, or an orchestrator loop) so timer and GitHub gates close without a human in the loop; keep human gates for the decisions that should never auto-close.