beads/docs
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
..
architecture Fix ResolveServerMode ambient port-var handling and the KillStaleServers regression it introduced (#5934) 2026-09-30 07:13:57 -07:00
cli-reference docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
core-concepts Refuse reserved words and fuzzy id matches on bd comment writes (#5393) 2026-10-01 05:04:32 -07:00
diagrams docs: port the Excalidraw diagram pipeline (machinery only) 2026-07-12 10:37:17 -07:00
getting-started Beads 1.2 remediation: migration-consent gate — bd never migrates an existing database without explicit consent (#5764) 2026-10-08 08:21:31 +00:00
images docs: port user docs into the Mintlify site tree under docs/ 2026-07-12 10:37:07 -07:00
integrations docs(cursor): re-review docs/integrations/cursor.md against cmd/bd/setup/cursor.go (#7333) 2026-10-08 08:20:31 +00:00
multi-agent fix(reclaim): correct the heartbeat re-home invariant's scope in the new docs (wy-sp2l4) 2026-08-13 04:30:30 -07:00
recovery Beads 1.2 remediation: migration-consent gate — bd never migrates an existing database without explicit consent (#5764) 2026-10-08 08:21:31 +00:00
reference show/list: render a derived GATED decoration when an open gate holds the bead (#6606) 2026-10-08 10:37:51 +00:00
workflows fix(gate): resolve a bead gate whose awaited bead no longer exists (#6395) 2026-10-08 17:10:33 +00:00
cli-docs.pin chore(release): forward-port v1.2.2 to main (version record, retracts, recovery guide, gate record) (#5782) 2026-08-14 21:45:02 -07:00
CLI_REFERENCE.md docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
community-tools.md docs: scope the shared-server read failure to pre-1.2.0 schemas; add eight community tools (#7301) 2026-10-06 10:56:39 -07:00
docs.json Beads 1.2 remediation: migration-consent gate — bd never migrates an existing database without explicit consent (#5764) 2026-10-08 08:21:31 +00:00
index.md release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038) 2026-08-30 22:19:35 -07:00
RECOVERY.md docs(recovery): reduce the stub to a pure pointer 2026-07-17 18:56:33 -07:00
related-projects.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00