fix(bin): preserve captain calls during teardown

[kunchenguid]

Intent

Captain's intent: Yeah similar to the other PR, have the crewmate do a clean slate minimal sufficient PR to supersede it. Meaning: do not land #3502. Implement the smallest sufficient fix from a clean origin/main, then supersede 3502 with the new PR.

Context: the bug is that bin/fm-teardown.sh closed a captain-held scout task with no recorded captain answer. The captain-hold-lifecycle policy prefers holding the very work item a question gates, and says a captain-held task must only ever close through fm-captain-hold.sh answer; but teardown's automatic backlog transition ran tasks-axi done on that row, which silently closes a held row and drops its hold. PR 3502 fixed this with a parallel retention-record family (a state/.backlog-retain record, a recover-retain command, a second bootstrap replay loop, and a lock handoff from teardown to a child process); an independent audit found that machinery mostly pipeline-induced and asked for the smallest sufficient fix from a clean main.

Deliberate decisions in this change, all intended: (1) fm-captain-hold.sh gains a read-only open predicate with exit 0 (open captain call), 1 (not), 2 (cannot tell), and any read error is a 2 so a mechanical closer never treats 'cannot tell' as permission to close. (2) Teardown asks open before any destructive step and refuses on 2; on 0 only the close changes: after cleanup and still under the task's own meta lock, teardown appends one 'Deliverable of the finished work: ...' line to the task body and runs tasks-axi reopen, so the row returns to Queued with its hold intact and appears in Bearings' Captain's Call; --force deliberately does not lift this because it authorizes discarding unlanded work, never the captain's question. (3) The deliverable is written into the body rather than through tasks-axi update --report/--pr, because on a row that is not Done that flag rewrites the task title (verified with the installed tasks-axi). (4) The crash window reuses the existing pending-close record with a new optional mode=retain line, so the existing validator, stale-generation check, cleanup-incomplete marking, bootstrap replay loop, and its non-blocking try-lock all apply unchanged; replay in retain mode records the deliverable and reopens instead of closing, and a row the captain already answered and closed simply retires the record. No parallel record type, no recover command, no second bootstrap loop, no lock handoff: that omission is the point of the change, not an oversight. (5) fm-captain-hold.sh now addresses the configured data directory (FM_DATA_OVERRIDE, relocated data dirs) the same way bin/fm-backlog-transition-lib.sh does for every command, and reads rows through the library's backend-aware show helper; before this it ran tasks-axi from FM_HOME and ignored a relocated data directory, which would have made open return 'not found' and closed the call. (6) The ordinary non-captain-held teardown path is behaviorally unchanged. (7) Tests exercise the real executables only: the captain-held scout case including --force, ordinary scout, and answer-only closure; an interrupted cleanup leaving the row untouched and the next session start retaining it; a relocated backlog; and a ship-kind row whose hold cannot be read refusing before anything destructive. Race tests with paused fake binaries were deliberately not added. (8) tests/fm-teardown.test.sh has one case (herdr-preflight-missing-adapter) that fails identically on unmodified origin/main on this Mac where a real herdr is installed; it is pre-existing and out of scope. Constraints: bash 3.2 safe, bin/fm-lint.sh clean, one sentence per line and plain dashes in tracked Markdown, no agent co-author trailer, single-owner contracts with docs/captain-hold-lifecycle.md and the script headers updated rather than duplicated.

What Changed

• Add a backend-aware, tri-state open predicate for captain-held tasks that honors configured and relocated data directories.
• Retain open captain calls during teardown by recording the deliverable, reopening the row as Queued with its hold intact, and replaying interrupted retention through the existing pending-close record.
• Refuse destructive cleanup when hold state cannot be read, including with --force, and expand lifecycle documentation and executable regression coverage.

Risk Assessment

✅ Low: The per-task control lock now serializes teardown and replay with captain hold/answer transitions, and backend-aware listing resolves the previously identified relocated non-Markdown read risk without introducing a substantiated regression.

Testing

The focused Bash 3.2 lifecycle suite passed, covering held and forced teardown, ordinary teardown, answer-only closure, interrupted-cleanup replay, relocated backlog handling, and fail-closed read errors; a real CLI transcript additionally demonstrated that teardown preserves the queued captain-held row and deliverable until the captain answer closes it.

Evidence: Captain-held teardown and answer end-to-end CLI transcript

Source: Captain-held teardown and answer end-to-end CLI transcript

$ fm-teardown.sh evidence-retain
teardown evidence-retain complete (window firstmate:fm-evidence-retain, worktree /private/var/folders/0k/bf8mwt2n5qddzk24r20gfk0c0000gn/T/evidence-captain-retain.G2BrED/projects/missing-evidence-retain)
Backlog: evidence-retain stays open in /private/var/folders/0k/bf8mwt2n5qddzk24r20gfk0c0000gn/T/evidence-captain-retain.G2BrED/data/backlog.md, still held for the captain with its deliverable recorded. Relay the question and close it only with bin/fm-captain-hold.sh answer.

$ tasks-axi show evidence-retain --full  # after teardown
task:
  id: evidence-retain
  title: Investigate attachment delivery
  state: queued
  blocked: no
  blocked_by: none
  held: yes
  hold_reason: captain must choose attachment delivery
  hold_kind: captain
  hold_until: "-"
  kind: scout
  repo: sample
  priority: "-"
  created: 2026-09-02
  closed: "-"
  deps: none
  links: none
  body: "Deliverable of the finished work: report data/evidence-retain/report.md"

$ fm-bearings-snapshot.sh --json | jq captain-call
{
  "id": "evidence-retain",
  "key": "evidence-retain",
  "verb": "captain-hold",
  "summary": "Investigate attachment delivery: captain must choose attachment delivery",
  "owner": "(main)"
}

$ fm-captain-hold.sh answer evidence-retain --decision-file answer.txt
answered: evidence-retain

$ tasks-axi show evidence-retain --full  # after captain answer
task:
  id: evidence-retain
  title: Investigate attachment delivery
  state: done
  blocked: no
  blocked_by: none
  held: no
  hold_reason: captain must choose attachment delivery
  hold_kind: captain
  hold_until: "-"
  kind: scout
  repo: sample
  priority: "-"
  created: "-"
  closed: 2026-09-02
  deps: none
  links: none
  body: "Resolution recorded by fm-captain-hold.\nDecision digest: 0b85fed6b8b107b1fd17d5999f01c6407e13bf167407dcf18f059002bda115d0\nResolution mode: answered\n\nCaptain decision:\nUse by-reference attachments.\n\nDeliverable of the finished work: report data/evidence-retain/report.md"

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed ✅

• 🚨 bin/fm-teardown.sh:324 - The open result is a TOCTOU snapshot rather than a durable invariant. After it returns 1, a concurrent fm-captain-hold.sh hold can establish a captain call before teardown runs tasks-axi done, reproducing the forbidden answerless close. Conversely, after it returns 0, a concurrent answer can close the row before fm_backlog_retain reopens it; replay has the same probe-to-transition race. Serialize hold/answer and teardown/replay with the existing per-task lifecycle/control lock across the predicate and final transition.
• ⚠️ bin/fm-captain-hold.sh:241 - The relocated-data helper says it owns mutations, but open_task_ids also uses it, causing tasks-axi list --file .... Non-Markdown backends must be read from their configured addressing root without --file (the immediately preceding backend fix establishes this contract), so diverged can silently see no Beads rows. Route list reads through a backend-aware helper while retaining --file for mutations.

🔧 Fix: Serialize captain holds and fix backend-aware listing
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-captain-hold-lifecycle.test.sh
• In an isolated home using real executables, ran fm-teardown.sh evidence-retain, inspected the row with tasks-axi show --full, confirmed it remained in Bearings' Captain's Call, answered it through fm-captain-hold.sh answer, and inspected the final closed row.

🔧 **Document** - 1 issue found → auto-fixed ✅

• ⚠️ bin/fm-captain-hold.sh:384 - Three failure messages still name FM_HOME/data/backlog.md even when FM_DATA_OVERRIDE selects a relocated backlog; executable-message edits were outside this documentation-only phase.

🔧 Fix: Fix relocated captain-hold backlog diagnostics
✅ Re-checked - no issues remain.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge because the captain-call state check, destructive teardown, and recovery transition are serialized and fail closed when the hold state cannot be determined.

The changed lifecycle preserves open captain calls through normal and interrupted teardown, avoids reopening calls already answered by the captain, and retains the existing ordinary close behavior without an accepted correctness or security defect.

_{Reviews (1): Last reviewed commit: "no-mistakes(document): Fix relocated cap..." | Re-trigger Greptile}