* 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>
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 reportscannot be checked (multi-rig routing removed)and stays pending regardless of the awaited bead's status. Close it withbd 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.