From 362c508666432e35c8608b6c526464acba366307 Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Sun, 16 Aug 2026 20:22:49 -0700
Subject: [PATCH 01/12] fix(decisions): close decision holds at answer time via
 one general keyed-answer path (#2490)

* fix(decisions): close captain holds at answer time

Firstmate had two "a decision is open" ledgers with asymmetric closing
mechanics. The live status-log ledger closes atomically at answer time,
because bin/fm-send.sh --resolve-key makes answering a decision be the
act that closes it. The durable backlog hold ledger had no such coupling:
answering and recording were two separate acts, and only the first was
forced by the workflow.

That asymmetry lost four real captain decisions. Their answers were
captured durably to disk, keyed character for character by the hold
decision keys, acknowledged, and even implemented and shipped, yet the
holds stayed open for two days and the captain was asked to re-answer
decisions already on his own disk.

Give the hold ledger the same answer-time-closure property:

- bin/fm-decision-hold.sh gains an `answer` subcommand, the hold ledger's
  counterpart to --resolve-key. It shares one unrouted close
  implementation with `decline`, so it carries every existing guard - the
  captain decision file, the active-hold requirement, retry identity, and
  the refusal to release still-routed work - and differs only in the
  resolution mode it records. `decline` keeps its stronger meaning that
  the answer routes no follow-up work at all.
- bin/fm-procevent-lavish.sh wires the channel that actually carried the
  lost answers. `arm --decisions-origin` binds a deck to the origin whose
  holds it carries, `answers` reads the structured choices out of a
  captured poll result, `close-decisions` maps each key to its hold and
  closes it through the command above, and `autohandle` lets the runner
  apply that at capture time.

Safety is preserved rather than traded away. Only rows tagged `choice`
are read, so freeform captain prose cannot forge a decision key. Closure
is confined to the one bound origin. The decision text is a pure function
of the captured result, so a replayed capture is idempotent. A hold that
is absent, already closed, or still blocking routed work is skipped and
left for `resolve`, never forced. A deck armed without the binding
touches no hold at all. And autohandle deliberately never reports full
handling, because recording an answer is transcription while acting on it
is firstmate's judgement - so the check wake still reaches the handler.

fm-send --resolve-key is untouched.

* no-mistakes(document): document state/lavish-decisions binding dir in AGENTS.md state inventory

* refactor(decisions): make keyed-answer closure one general capability

The previous pass gave holds answer-time closure but built it as bespoke
Lavish wiring: the review adapter carried the source-to-origin binding,
mapped keys to hold identities, wrote decision records, decided what to
skip, and closed holds itself. That treated a review deck as a special
decision source. It is not - it is an ephemeral discussion format that
happens to carry answers.

Collapse it into ONE general capability with one owner.

bin/fm-decision-hold.sh now owns the whole of "a keyed answer closes its
matching hold":
- `answers <origin> --source <provenance>` is the channel-agnostic
  intake. It reads key/answer/label lines on stdin, maps each key to its
  hold, and closes it through the same `answer` path, so every guard
  applies identically whatever channel the answer came from. --source is
  provenance recorded in the decision, never a behavior switch; there is
  no per-channel branch and no knowledge of chat, decks, or transports.
- `bind`/`unbind`/`binding` own the source-to-origin binding for any
  channel whose answers arrive detached from their origin.

Every channel is now an ordinary caller that only turns what it received
into keyed lines:
- bin/fm-send.sh (chat) feeds the intake for a key that names an active
  hold. This also fixes a real gap: once `complete` transfers a decision
  to its hold it closes the live status copy, so --resolve-key alone
  could never answer a transferred decision.
- bin/fm-procevent.sh feeds it generically. A bound source's captured
  result goes to `<adapter> answers <result-file>` and whatever that
  prints is piped into the intake. The runner names no adapter, parses
  no result, and carries no decision rule, so any future adapter with an
  `answers` command works with no change here.
- bin/fm-procevent-lavish.sh keeps only `answers`, which reports the
  structured choices a review captured and stops. It maps nothing to a
  hold and closes nothing; it lost ~160 lines of decision logic.

Feeding is independent of handling, so it never acknowledges a result
and never suppresses a wake - recording an answer is transcription,
acting on it stays firstmate's judgement.

The regression that proves closure now drives a FIXTURE adapter that is
not the review adapter, so what is proven is that any bound channel
reaches the intake rather than that one channel is wired specially. A
new regression drives the real fm-send over a stubbed transport for the
chat side. Every prior guarantee still holds, and fm-send's status-log
behavior is unchanged.

* no-mistakes(review): test(decisions): drop source-content grep from hold-closure regression
---
 .../skills/decision-hold-lifecycle/SKILL.md   |   9 +-
 .agents/skills/process-event-sources/SKILL.md |  10 +
 AGENTS.md                                     |   1 +
 bin/fm-decision-hold.sh                       | 216 ++++++++++-
 bin/fm-procevent-lavish.sh                    |  87 ++++-
 bin/fm-procevent.sh                           |  47 ++-
 bin/fm-send.sh                                |  75 +++-
 docs/configuration.md                         |   7 +
 docs/decision-hold-lifecycle.md               |  57 ++-
 docs/verification/process-event-sources.md    |   2 +
 tests/fm-decision-hold-lifecycle.test.sh      | 348 ++++++++++++++++++
 11 files changed, 828 insertions(+), 31 deletions(-)

diff --git a/.agents/skills/decision-hold-lifecycle/SKILL.md b/.agents/skills/decision-hold-lifecycle/SKILL.md
index cacc0948fe9..43e327dd623 100644
--- a/.agents/skills/decision-hold-lifecycle/SKILL.md
+++ b/.agents/skills/decision-hold-lifecycle/SKILL.md
@@ -23,6 +23,12 @@ Run the command in the originating work's authoritative `FM_HOME`; main-home wor
 Do not close a hold merely because the originating investigation completed, its report was archived, its visual review ended, or its task was torn down.
 When the captain's answer authorizes follow-up work, the hold remains the authoritative Captain's Call item until that answer is durably recorded, dependent work is created in the same backlog and blocked by the hold, and `bin/fm-decision-hold.sh resolve` routes the answer by clearing those dependency edges before closing the hold.
 When the captain's answer routes no follow-up work at all, such as a declined proposal, `bin/fm-decision-hold.sh decline` records that answer and closes the hold; it never substitutes for routing work the captain did authorize.
+When the captain simply answers a hold that has no follow-up work routed behind it yet, `bin/fm-decision-hold.sh answer` records that answer and closes the hold, so answering is closing rather than a separate later act that can be forgotten.
+"A keyed answer closes its matching hold" is one capability with one owner, `bin/fm-decision-hold.sh answers`, and every channel that carries a captain answer feeds it the same `<decision-key>` and answer.
+A channel never maps a key to a hold, records a decision, or closes anything itself, so no channel is special and a new one needs no new closing logic.
+Chat already feeds it: `bin/fm-send.sh --resolve-key` answers a decision in whichever ledger still holds it open, including a decision already transferred to its durable hold.
+A captured-answer source feeds it too once bound with `bin/fm-decision-hold.sh bind <source-id> <origin-id>`; bind before arming the source, and key each structured question by the hold's own decision key.
+An unbound source and a question slug that is not a decision key both simply feed nothing: the answer is still captured and firstmate is still woken, and closing falls back to the commands above.
 A hold closed outside this owner leaves no durable answer, so the completion gate keeps failing until `bin/fm-decision-hold.sh repair` records the decision the captain actually gave; neither unrouted path may stand in for an answer the captain has not given.
 Resolved findings, recommendations that need no captain choice, and prose that merely sounds decision-like do not create holds.
 Bearings reads the resulting structured state and must never compensate by scraping historical reports, visual-review artifacts, terminal output, chat, or other prose.
@@ -35,7 +41,8 @@ Bearings reads the resulting structured state and must never compensate by scrap
 4. Run the script's `complete` command with the full unresolved-key inventory for that review pass.
 5. Relay the choices to the captain as decisions from Bearings' Captain's Call section under `AGENTS.md` section 9; do not use the word hold in captain chat.
 6. If the captain authorizes dependent work, record it with normal tasks-axi commands and block it by the hold identity.
-7. Put the captain's exact durable decision in a file and close the hold with the script's `resolve` command and every routed task, its `decline` command when the answer routes no work, or its `repair` command when the hold was already closed outside the script.
+7. Put the captain's exact durable decision in a file and close the hold with the script's `resolve` command and every routed task, its `answer` command when the captain answered a hold with no routed work behind it, its `decline` command when the answer routes no work at all, or its `repair` command when the hold was already closed outside the script.
+   A hold that a channel already closed by feeding its keyed answer needs none of these; confirm it in step 8 instead.
 8. Confirm Bearings no longer shows the closed hold and that any routed work remains in structured backlog state.
 
 `bin/fm-decision-hold.sh --help` owns command syntax, identity construction, completion attestation, retry behavior, and close ordering.
diff --git a/.agents/skills/process-event-sources/SKILL.md b/.agents/skills/process-event-sources/SKILL.md
index 093272c41a2..e5fd0c9b1c0 100644
--- a/.agents/skills/process-event-sources/SKILL.md
+++ b/.agents/skills/process-event-sources/SKILL.md
@@ -31,6 +31,16 @@ For a Lavish review artifact:
 bin/fm-procevent-lavish.sh arm <artifact.html>
 ```
 
+When a source carries captain answers to decisions that already have durable holds, bind it to their origin BEFORE arming it, so it can never produce an answer that has nowhere to go:
+
+```sh
+bin/fm-decision-hold.sh bind <source-id> <origin-id>
+```
+
+The runner then passes each captured result to that source's own adapter `answers` command and pipes the keyed answers it prints into the one keyed-answer intake, which owns every rule about what they mean.
+This is generic: any adapter with an `answers` command works, and the runner still wakes you to act on the result.
+`decision-hold-lifecycle` owns when a binding is required and what the keys must be.
+
 A configured remote secondmate reply source is armed and handled through `bin/fm-procevent-remote-reply.sh`.
 Its header owns exact commands, while the adapter owns cursor continuity, validated deduplicated status ingest, path-confined document fetch, acknowledgement, and re-arming after a good delta.
 A continuity break is escalated once and stays unarmed until an operator deliberately rebases it.
diff --git a/AGENTS.md b/AGENTS.md
index 0d06b4229b8..b0d4f7688bd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -107,6 +107,7 @@ state/               runtime records and signals; gitignored
   pending-replies/   parent-owned secondmate pending-reply records (correlation id, delivery vs reply, recovery, escalation); fm-pending-reply-lib.sh
   procevent/         registered process-to-event sources, one private record per canonical source id; written only by bin/fm-procevent.sh, and their presence alone keeps supervision required (section 13)
   procevent-inbox/   private captured results and their durable handled-acknowledgement markers; source output lives here and never in an event line
+  decision-bindings/ private bindings from a captured-answer source id to the captain-hold origin its keyed answers close; written only by bin/fm-decision-hold.sh bind, dropped by unbind and by source retirement (section 13; docs/decision-hold-lifecycle.md)
   when/              private condition->action watch specs, their trust bindings, and single-fire markers; written only by bin/fm-procevent-when.sh (section 13's process-event-sources trigger)
   x-inbox/           generated Relay pending mention payloads; fmx-respond drains it (section 14)
   x-context/         generated Relay durable per-request reply context and one-wake offer markers, keyed by request_id; survives inbox cleanup and expires within seven days (section 14; bin/fm-x-lib.sh)
diff --git a/bin/fm-decision-hold.sh b/bin/fm-decision-hold.sh
index 523fef60847..6f82e0676d8 100755
--- a/bin/fm-decision-hold.sh
+++ b/bin/fm-decision-hold.sh
@@ -24,6 +24,11 @@
 #   fm-decision-hold.sh verify <origin-id>
 #   fm-decision-hold.sh resolve <origin-id> <decision-key> \
 #     --decision-file <path> --routed-to <task-id> [--routed-to <task-id>...]
+#   fm-decision-hold.sh answer <origin-id> <decision-key> --decision-file <path>
+#   fm-decision-hold.sh answers <origin-id> --source <provenance>   (keyed answers on stdin)
+#   fm-decision-hold.sh bind <source-id> <origin-id>
+#   fm-decision-hold.sh unbind <source-id>
+#   fm-decision-hold.sh binding <source-id>
 #   fm-decision-hold.sh decline <origin-id> <decision-key> --decision-file <path>
 #   fm-decision-hold.sh repair <origin-id> <decision-key> --decision-file <path>
 #
@@ -35,18 +40,62 @@
 # `verify` is read-only and is called by scout teardown so teardown cannot erase a
 # source before this gate has succeeded.
 #
-# `resolve` and `decline` close active holds; `repair` attests a hold already closed
-# outside this script. All three paths require a non-empty captain decision file of
-# at most 8192 bytes, record the same durable resolution block in the hold body, and
-# store the decision digest plus routed identities so an exact retry is idempotent
-# while a changed decision or, for `resolve`, routed set is rejected. New records
-# include a `Resolution mode:` naming their path; older routed records remain valid.
+# `resolve`, `answer`, and `decline` close active holds; `repair` attests a hold
+# already closed outside this script. All four paths require a non-empty captain
+# decision file of at most 8192 bytes, record the same durable resolution block in
+# the hold body, and store the decision digest plus routed identities so an exact
+# retry is idempotent while a changed decision or, for `resolve`, routed set is
+# rejected. New records include a `Resolution mode:` naming their path; older
+# routed records remain valid.
 #
 # `resolve` is the routed path. It requires every --routed-to task to exist and to
 # be blocked by the hold. It writes the captain decision and routed identities into
 # the hold body, clears those dependency edges, and only then marks the hold Done.
 # A failure before the final step leaves the captain hold open.
 #
+# `answer` is the answer-time closure path, the hold ledger's counterpart to
+# `fm-send.sh --resolve-key`: it exists so the act that carries the captain's
+# answer is the act that closes the hold, instead of leaving closure to a
+# separate later call nobody is forced to make. It records the captain's answer
+# on an actively held hold, records `(none)` as the routed identities because no
+# follow-up work has been routed behind the hold yet, and closes it. It shares
+# every guard `decline` has, including the refusal while any task is still
+# blocked by the hold, so a decision whose follow-up work is already routed still
+# goes through `resolve` and the routed-vs-unrouted distinction survives. It says
+# only that the captain answered; `decline` still says the captain answered with
+# no follow-up work at all.
+#
+# ONE KEYED-ANSWER INTAKE, FED BY EVERY CHANNEL.
+# "A keyed answer closes its matching hold" is a single capability, owned here
+# and nowhere else. `answers` is its channel-agnostic entry point: it reads
+# `<decision-key>\t<answer>\t<label>` lines on stdin, maps each key to this
+# origin's `<origin-id>-decision-<key>` hold, and closes it through the very same
+# `answer` path above, so every guard applies identically no matter which channel
+# the answer arrived on. `--source` is provenance text recorded in the durable
+# decision, never a behavior switch: this command has no per-channel branch and
+# no knowledge of chat, review decks, or any transport.
+#
+# A channel's ONLY job is to turn whatever it received into those keyed lines and
+# pipe them here. It must never map keys to holds, build decision records, decide
+# resolve-versus-decline, or close a hold itself. A future channel needs no change
+# here at all.
+#
+# The decision text is a pure function of (source, key, answer, label), which is
+# what makes a replayed delivery an idempotent no-op rather than a rejected
+# "different captain decision". A key whose hold is absent, already closed, or
+# still blocking routed work is reported as `skipped:` and left for `resolve`;
+# skipping is never forced closure, and the command exits nonzero when any key
+# was skipped.
+#
+# `bind`, `unbind`, and `binding` record which origin a captured-answer SOURCE
+# belongs to, for any channel whose answers arrive detached from the origin (a
+# process-event source id, for example). The binding is a private record under
+# `state/decision-bindings/`; a source with no binding feeds nothing, so this
+# whole path is opt-in per source and an unbound source behaves as if it did not
+# exist. `bind` deliberately does not require the source to exist yet, so a
+# channel can be bound BEFORE it is armed and never produce an answer that has
+# nowhere to go.
+#
 # `decline` is the unrouted path for a decision the captain answered with no
 # follow-up work. It takes no --routed-to task, records `(none)` as the routed
 # identities, and closes an actively held hold. It refuses while any task is still
@@ -573,10 +622,14 @@ parse_decision_only_flags() {  # <args...>; prints the --decision-file value
   printf '%s' "$decision_file"
 }
 
-command_decline() {
-  local origin=${1:-} key=${2:-} decision_file id body hold_show hold_body state dependents
-  [ "$#" -ge 2 ] || { usage >&2; exit 2; }
-  shift 2
+# The one unrouted close path, shared by `answer` and `decline`. They differ only
+# in the resolution mode they record and the outcome word they print; every
+# guard - the captain decision file, the active-hold requirement, the retry
+# identity, and the refusal to release still-routed work - is identical, so
+# neither can drift into a weaker close than the other.
+close_unrouted_hold() {  # <mode> <outcome-word> <origin-id> <decision-key> <flag-args...>
+  local mode=$1 outcome=$2 origin=$3 key=$4 decision_file id body hold_show hold_body state dependents
+  shift 4
   decision_file=$(parse_decision_only_flags "$@") || exit 2
   validate_slug origin-id "$origin"
   validate_slug decision-key "$key"
@@ -587,7 +640,7 @@ command_decline() {
     hold_show=$(task_show "$id")
     hold_body=$(show_field "$hold_show" body)
     verify_resolution_identity "$id" "$hold_body" "$DECISION_DIGEST" "$ROUTED_NONE"
-    printf 'declined: %s\n' "$id"
+    printf '%s: %s\n' "$outcome" "$id"
     return 0
   fi
   hold_show=$(task_show "$id") || fail "captain hold $id is absent from $FM_HOME/data/backlog.md"
@@ -604,12 +657,142 @@ command_decline() {
   dependents=$(tasks_blocked_by "$id") || exit 1
   [ -z "$dependents" ] \
     || fail "captain hold $id still blocks routed work ($dependents); use resolve to record that work"
-  body=$(resolution_body declined "$ROUTED_NONE")
+  body=$(resolution_body "$mode" "$ROUTED_NONE")
   tasks_axi update "$id" --body "$body" >/dev/null \
     || fail "could not record the captain decision on $id"
-  tasks_axi "done" "$id" >/dev/null || fail "could not close declined captain hold $id"
+  tasks_axi "done" "$id" >/dev/null || fail "could not close $mode captain hold $id"
   verify_hold_resolved "$id" || fail "captain hold $id did not retain its durable resolution record"
-  printf 'declined: %s\n' "$id"
+  printf '%s: %s\n' "$outcome" "$id"
+}
+
+command_answer() {
+  [ "$#" -ge 2 ] || { usage >&2; exit 2; }
+  close_unrouted_hold answered answered "$@"
+}
+
+# --- the one keyed-answer intake, and the source bindings that feed it --------
+
+BINDING_DIR="$STATE/decision-bindings"
+BINDING_SCHEMA=fm-decision-binding.v1
+
+validate_source_id() {  # <source-id>
+  validate_slug source-id "$1"
+  [ "${#1}" -le 64 ] || fail "source-id must be at most 64 characters: $1"
+}
+
+binding_path() { printf '%s/%s.origin\n' "$BINDING_DIR" "$1"; }
+
+# The origin a captured-answer source belongs to, or empty when it is unbound.
+# An unreadable or wrong-schema record is a hard error rather than a silent
+# "unbound": feeding nothing is the safe direction only when it is a deliberate
+# choice, never when it is a corrupted record.
+read_binding() {  # <source-id>
+  local path origin schema
+  path=$(binding_path "$1")
+  [ -e "$path" ] || return 0
+  [ -f "$path" ] && [ ! -L "$path" ] || fail "decision binding is unsafe: $path"
+  schema=$(sed -n 's/^schema=//p' "$path" | head -1)
+  [ "$schema" = "$BINDING_SCHEMA" ] || fail "decision binding has an incompatible schema: $path"
+  origin=$(sed -n 's/^origin=//p' "$path" | head -1)
+  case "$origin" in
+    ''|*[!A-Za-z0-9._-]*) fail "decision binding has an invalid origin id: $path" ;;
+  esac
+  printf '%s\n' "$origin"
+}
+
+command_bind() {
+  local source=${1:-} origin=${2:-} dest tmp
+  [ "$#" -eq 2 ] || { usage >&2; exit 2; }
+  validate_source_id "$source"
+  validate_slug origin-id "$origin"
+  (umask 077; mkdir -p "$BINDING_DIR") || fail "cannot create $BINDING_DIR"
+  [ -d "$BINDING_DIR" ] && [ ! -L "$BINDING_DIR" ] || fail "decision binding dir is unsafe: $BINDING_DIR"
+  dest=$(binding_path "$source")
+  tmp=$(umask 077; mktemp "$BINDING_DIR/.origin.XXXXXX") || fail "cannot stage the decision binding"
+  if ! { printf 'schema=%s\norigin=%s\n' "$BINDING_SCHEMA" "$origin" > "$tmp" \
+    && chmod 0600 "$tmp" && mv -f -- "$tmp" "$dest"; }; then
+    rm -f -- "$tmp"
+    fail "cannot record the decision binding for $source"
+  fi
+  printf 'bound: %s -> %s\n' "$source" "$origin"
+}
+
+command_unbind() {
+  local source=${1:-}
+  [ "$#" -eq 1 ] || { usage >&2; exit 2; }
+  validate_source_id "$source"
+  rm -f -- "$(binding_path "$source")"
+  printf 'unbound: %s\n' "$source"
+}
+
+command_binding() {
+  local source=${1:-} origin
+  [ "$#" -eq 1 ] || { usage >&2; exit 2; }
+  validate_source_id "$source"
+  origin=$(read_binding "$source") || exit 1
+  [ -n "$origin" ] || return 1
+  printf '%s\n' "$origin"
+}
+
+# The durable captain decision one keyed answer records. Pure function of its
+# inputs, so the same answer delivered twice is idempotent rather than a
+# conflicting decision.
+keyed_decision_text() {  # <source> <key> <answer> <label>
+  printf 'Captain answered this decision through %s.\n' "$1"
+  printf 'Decision key: %s\n' "$2"
+  printf 'Answer: %s\n' "$3"
+  [ -z "$4" ] || printf 'Answer as shown to the captain: %s\n' "$4"
+}
+
+sanitize_field() {  # <text>
+  printf '%s' "$1" | tr '\n\r\t' '   ' | LC_ALL=C tr -d '\000-\037\177' | cut -c1-512
+}
+
+command_answers() {
+  local origin=${1:-} source='' key answer label hold tmp err closed=0 skipped=0 reason
+  [ "$#" -ge 1 ] || { usage >&2; exit 2; }
+  shift
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --source) shift; source=${1:-} ;;
+      *) usage >&2; exit 2 ;;
+    esac
+    shift
+  done
+  validate_slug origin-id "$origin"
+  [ -n "$source" ] || fail "--source provenance is required so the durable decision records where the answer came from"
+  source=$(sanitize_field "$source")
+  require_tasks_axi
+  tmp=$(umask 077; mktemp "${TMPDIR:-/tmp}/fm-keyed-decision.XXXXXX") || fail "cannot stage the captain decision"
+  err=$(umask 077; mktemp "${TMPDIR:-/tmp}/fm-keyed-decision-err.XXXXXX") \
+    || { rm -f -- "$tmp"; fail "cannot stage the captain decision diagnostics"; }
+  while IFS=$'\t' read -r key answer label; do
+    [ -n "${key:-}" ] || continue
+    case "$key" in *[!A-Za-z0-9._-]*) continue ;; esac
+    [ "${#key}" -le 64 ] || continue
+    answer=$(sanitize_field "${answer:-}")
+    [ -n "$answer" ] || continue
+    label=$(sanitize_field "${label:-}")
+    hold="$origin-decision-$key"
+    keyed_decision_text "$source" "$key" "$answer" "$label" > "$tmp" \
+      || fail "cannot stage the captain decision for $hold"
+    if "$0" answer "$origin" "$key" --decision-file "$tmp" >/dev/null 2>"$err"; then
+      printf 'closed: %s\n' "$hold"
+      closed=$((closed + 1))
+    else
+      reason=$(tr -d '\n' < "$err" | sed 's/^fm-decision-hold: //')
+      printf 'skipped: %s (%s)\n' "$hold" "$reason"
+      skipped=$((skipped + 1))
+    fi
+  done
+  rm -f -- "$tmp" "$err"
+  printf 'answers: closed=%s skipped=%s origin=%s\n' "$closed" "$skipped" "$origin"
+  [ "$skipped" -eq 0 ]
+}
+
+command_decline() {
+  [ "$#" -ge 2 ] || { usage >&2; exit 2; }
+  close_unrouted_hold declined declined "$@"
 }
 
 command_repair() {
@@ -655,6 +838,11 @@ case "${1:-}" in
   complete) shift; command_complete "$@" ;;
   verify) shift; command_verify "$@" ;;
   resolve) shift; command_resolve "$@" ;;
+  answer) shift; command_answer "$@" ;;
+  answers) shift; command_answers "$@" ;;
+  bind) shift; command_bind "$@" ;;
+  unbind) shift; command_unbind "$@" ;;
+  binding) shift; command_binding "$@" ;;
   decline) shift; command_decline "$@" ;;
   repair) shift; command_repair "$@" ;;
   -h|--help) usage ;;
diff --git a/bin/fm-procevent-lavish.sh b/bin/fm-procevent-lavish.sh
index 2561828d70f..827a225f5a6 100755
--- a/bin/fm-procevent-lavish.sh
+++ b/bin/fm-procevent-lavish.sh
@@ -5,6 +5,7 @@
 #   fm-procevent-lavish.sh arm <artifact.html>
 #   fm-procevent-lavish.sh classify <result-file>
 #   fm-procevent-lavish.sh terminal <result-file>
+#   fm-procevent-lavish.sh answers <result-file>
 #   fm-procevent-lavish.sh source-id <artifact.html>
 #   fm-procevent-lavish.sh retire <artifact.html>
 #
@@ -20,6 +21,17 @@
 # and how to read a completed result. Ownership, durable capture, publication,
 # and restart recovery all belong to bin/fm-procevent.sh.
 #
+# `answers` is this adapter's half of the generic keyed-answer contract in
+# bin/fm-procevent.sh. It reports what the captain actually chose, as
+# `<decision-key>\t<answer>\t<label>` lines, and stops there. It maps nothing to a
+# hold, records no decision, and closes nothing: a captain answer is not special to
+# Lavish, so every rule about what a keyed answer DOES belongs to the one intake in
+# bin/fm-decision-hold.sh, which the runner feeds. A Lavish review is just an
+# ephemeral discussion format that happens to carry answers.
+#
+# Only rows tagged `choice` are read. A freeform captain message is prose that may
+# contain anything, and must never be able to forge a decision key.
+#
 # It wraps ONLY the currently published interface, verified against 0.1.45:
 #   Usage: lavish-axi poll <html-file> [--agent-reply "..."]
 # and that command "long-polls indefinitely" server-side. The adapter therefore
@@ -47,7 +59,7 @@ FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
 . "$SCRIPT_DIR/fm-procevent-lib.sh"
 
 die() { printf 'error: %s\n' "$1" >&2; exit 1; }
-usage() { sed -n '2,35p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 2; }
+usage() { sed -n '2,47p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 2; }
 
 # Canonical identity is physical, not the path string: Lavish itself keys a
 # session on the realpath of the artifact, so two names for one file are one
@@ -69,6 +81,7 @@ cmd_source_id() {
 cmd_arm() {
   local artifact=${1-} id real
   [ -n "$artifact" ] || usage
+  [ "$#" -eq 1 ] || usage
   command -v lavish-axi >/dev/null 2>&1 || die "lavish-axi is not installed"
   id=$(cmd_source_id "$artifact") || exit 1
   real=$(perl -MCwd=realpath -e '$p = realpath($ARGV[0]); defined($p) or exit 1; print "$p\n"' "$artifact" 2>/dev/null) \
@@ -145,12 +158,84 @@ cmd_terminal() {
   return 1
 }
 
+# Print `key<TAB>answer<TAB>label` for every structured choice the captain
+# submitted in a captured result. The published response frames queued feedback as
+# a `prompts[N]{field,...}:` header followed by exactly N indented CSV rows whose
+# quoted fields carry JSON-style escapes, so this reads the declared field ORDER
+# rather than assuming a fixed column, and takes only rows whose `tag` field is
+# `choice`. A freeform `message` row is captain prose and is deliberately never a
+# source of decision keys. A row that does not carry both a slug-shaped `question`
+# and an `answer` inside its `Context data:` block is skipped, so a deck that does
+# not key its forms by decision key simply yields nothing.
+cmd_answers() {
+  local file=${1-}
+  [ -n "$file" ] || usage
+  [ -f "$file" ] && [ ! -L "$file" ] || die "result file does not exist: $file"
+  perl -e '
+    use strict; use warnings;
+    my ($path) = @ARGV;
+    open my $fh, "<", $path or exit 1;
+    my (@fields, $want, @rows);
+    while (my $line = <$fh>) {
+      if (!@fields) {
+        next unless $line =~ /^prompts\[(\d+)\]\{([^}]*)\}:\s*$/;
+        ($want, @fields) = ($1, split /,/, $2);
+        next;
+      }
+      last unless $line =~ /^\s/;
+      last if @rows >= $want;
+      chomp $line;
+      push @rows, $line;
+    }
+    close $fh;
+    my %seen;
+    my @out;
+    for my $row (@rows) {
+      $row =~ s/^\s+//;
+      my @vals;
+      while (length $row) {
+        if ($row =~ s/^"((?:[^"\\]|\\.)*)"//) {
+          my $v = $1;
+          $v =~ s/\\(.)/$1 eq "n" ? "\n" : $1 eq "t" ? "\t" : $1 eq "r" ? "\r" : $1/ge;
+          push @vals, $v;
+        } else {
+          $row =~ s/^([^,]*)//;
+          push @vals, $1;
+        }
+        last unless $row =~ s/^,//;
+      }
+      my %f;
+      $f{$fields[$_]} = $vals[$_] for 0 .. $#fields;
+      next unless defined $f{tag} && $f{tag} eq "choice";
+      my $prompt = $f{prompt};
+      next unless defined $prompt && $prompt =~ /Context data:\s*(\{.*\})/s;
+      my $ctx = $1;
+      next unless $ctx =~ /"question"\s*:\s*"((?:[^"\\]|\\.)*)"/;
+      my $key = $1;
+      next unless $ctx =~ /"answer"\s*:\s*"((?:[^"\\]|\\.)*)"/;
+      my $answer = $1;
+      $_ =~ s/\\(.)/$1/g for ($key, $answer);
+      next unless $key =~ /\A[A-Za-z0-9._-]{1,64}\z/;
+      next unless length $answer && length($answer) <= 512;
+      my $label = defined $f{text} ? $f{text} : "";
+      s/[\x00-\x1f\x7f]/ /g for ($answer, $label);
+      $label = substr($label, 0, 512);
+      # A re-answered form appears again later in the queue; the last submission wins.
+      if (defined $seen{$key}) { $out[$seen{$key}] = undef }
+      $seen{$key} = scalar @out;
+      push @out, "$key\t$answer\t$label";
+    }
+    print "$_\n" for grep { defined } @out;
+  ' "$file"
+}
+
 case "${1-}" in
   arm)       shift; cmd_arm "$@" ;;
   retire)    shift; cmd_retire "$@" ;;
   source-id) shift; cmd_source_id "$@" ;;
   classify)  shift; cmd_classify "$@" ;;
   terminal)  shift; cmd_terminal "$@" ;;
+  answers)   shift; cmd_answers "$@" ;;
   ''|-h|--help|help) usage ;;
   *) die "unknown command: $1" ;;
 esac
diff --git a/bin/fm-procevent.sh b/bin/fm-procevent.sh
index 58d604a929e..1061859e3ce 100755
--- a/bin/fm-procevent.sh
+++ b/bin/fm-procevent.sh
@@ -75,6 +75,23 @@
 # go silent. An unhandled result stays eligible for bounded re-announcement on
 # every reconcile in both modes, exactly as before.
 #
+# Keyed captain answers are adapter-owned through one more seam of the same kind,
+# and this runner still decides nothing about them. Some sources carry the
+# captain's answer to a durable decision. What such an answer MEANS is owned once,
+# by bin/fm-decision-hold.sh's keyed-answer intake, and reaching it must not
+# depend on an agent remembering. So after capture, a source that has been bound
+# to a decision origin has its result passed to
+# `bin/fm-procevent-<adapter>.sh answers <result-file>`, and whatever that prints
+# is piped straight into that one intake. The adapter reports only what the
+# captain chose; the intake owns every rule about what happens next. This runner
+# names no adapter, parses no result, and knows no decision rule, so a future
+# source needs nothing here beyond an `answers` command and a binding.
+#
+# Feeding is deliberately independent of handling: it never acknowledges a result
+# and never suppresses a wake. Recording the captain's answer is transcription,
+# while ACTING on it is firstmate's judgement, so the capture stays unacknowledged
+# and its `check` wake reaches the handler exactly as it would have anyway.
+#
 # Ownership is machine-wide per canonical source, because separate Firstmate
 # homes can share one underlying source store. A live owner is never displaced;
 # only a claim whose whole generation is gone is reclaimed. A runner leads its
@@ -103,7 +120,7 @@ REG=$(fm_procevent_registry_dir "$STATE")
 MAX_OUTPUT_BYTES=${FM_PROCEVENT_MAX_OUTPUT_BYTES:-1048576}
 
 die() { printf 'error: %s\n' "$1" >&2; exit 1; }
-usage() { sed -n '2,87p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 2; }
+usage() { sed -n '2,104p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 2; }
 
 adapter_script() { printf '%s/bin/fm-procevent-%s.sh\n' "$FM_ROOT" "$1"; }
 
@@ -154,6 +171,24 @@ adapter_autohandle() {  # <adapter> <source-id> <result-file>
   "$script" autohandle "$id" "$seq" "$result" >/dev/null 2>&1
 }
 
+# Pass a bound source's captured result to the one keyed-answer intake. The
+# adapter turns its own format into keyed lines; the intake owns everything those
+# lines mean. Silenced and best-effort exactly like the seams above: an unbound
+# source, an adapter with no `answers` command, and a failure on either side all
+# leave the capture untouched and still announced, because this never
+# acknowledges anything (see the keyed-answer note in the header).
+feed_keyed_answers() {  # <adapter> <source-id> <result-file>
+  local adapter=$1 id=$2 result=$3 script origin seq
+  script=$(adapter_script "$adapter")
+  [ -f "$script" ] && [ ! -L "$script" ] || return 1
+  origin=$("$SCRIPT_DIR/fm-decision-hold.sh" binding "$id" 2>/dev/null) || return 1
+  [ -n "$origin" ] || return 1
+  seq=$(fm_procevent_result_sequence "$result") || return 1
+  "$script" answers "$result" 2>/dev/null \
+    | "$SCRIPT_DIR/fm-decision-hold.sh" answers "$origin" \
+        --source "the captured result $id sequence $seq" >/dev/null 2>&1
+}
+
 read_adapter() {  # <source-id>
   local f; f=$(source_file "$1")
   [ -f "$f" ] && [ ! -L "$f" ] || return 1
@@ -376,6 +411,12 @@ cmd_start() {
   STAGED_OUTPUT=
   [ "$truncated" -eq 1 ] && printf 'truncated: %s at %s bytes\n' "$id" "$MAX_OUTPUT_BYTES" >&2
 
+  # Independent of publication and acknowledgement, so it runs once per capture
+  # for every adapter and cannot change what the handler receives.
+  if feed_keyed_answers "$adapter" "$id" "$durable"; then
+    printf 'answers-fed: %s\n' "$id"
+  fi
+
   # A self-announcing adapter's autohandle announces through its own durable
   # downstream channel, so publication waits until after application and covers
   # only what remains unhandled; every other adapter keeps the strict
@@ -666,6 +707,10 @@ cmd_retire() {
   rm -f -- "$(source_file "$id")"
   rm -f -- "$(runner_file "$id")"
   fm_procevent_source_lock_release "$id"
+  # A retired source produces no further answer, so drop any decision binding it
+  # carried. Generic and idempotent: the binding owner is asked to forget this
+  # source id, and an unbound source is unaffected.
+  "$SCRIPT_DIR/fm-decision-hold.sh" unbind "$id" >/dev/null 2>&1 || true
   printf 'retired: %s\n' "$id"
 }
 
diff --git a/bin/fm-send.sh b/bin/fm-send.sh
index 4b7aa9eee73..c46c55a340f 100755
--- a/bin/fm-send.sh
+++ b/bin/fm-send.sh
@@ -48,10 +48,22 @@
 # remote secondmate alike - because the open-decision ledger fm-wake-drain
 # folds lives in this home's own state dir (a remote mate's escalations reach
 # it through the parent-replies ingest); only the answer message crosses the
-# backend or remote transport. Each named key must currently be open in that
-# ledger per status_open_decisions (bin/fm-classify-lib.sh) or fm-send refuses
-# before sending, so a mistyped key cannot deliver an answer while silently
-# orphaning the decision. A failed or unconfirmed send never closes a key; a
+# backend or remote transport.
+#
+# Chat is also a channel that carries keyed captain answers, so the same flag
+# feeds bin/fm-decision-hold.sh's one keyed-answer intake for any key that names
+# a durable decision hold on the target task. fm-send maps nothing to a hold and
+# closes nothing itself; it hands the intake `<key>\t<answer>\t<label>` exactly
+# as every other channel does, and the intake owns what that means. This is what
+# lets an answer reach a decision that has already been transferred from the live
+# status log to its durable hold, which the status ledger alone can no longer
+# close.
+#
+# Each named key must therefore currently be open in ONE of the two ledgers: open
+# in this home's status log per status_open_decisions (bin/fm-classify-lib.sh), or
+# an active captain hold for the target task. A key in neither is refused before
+# sending, so a mistyped key cannot deliver an answer while silently orphaning the
+# decision. A failed or unconfirmed send never closes a key; a
 # delivered answer whose closing append fails exits nonzero with the exact
 # manual close command, leaving the decision open to re-surface (the safe
 # direction). A send without the flag never closes anything: a routine steer,
@@ -350,6 +362,25 @@ fi
 # send, is what keeps a mistyped key loud instead of delivering an answer that
 # silently leaves its decision open.
 RESOLVE_STATUS_FILE=
+# Which ledger each answered key belongs to. A key still open in the status log
+# is owned by the status log: fm-decision-hold's `complete` closes that live copy
+# at the moment it transfers a decision to its durable hold, so "still open in
+# status" and "already a hold" are the two sides of one transfer, never both at
+# once. Checking the hold only for keys the status log no longer owns also keeps
+# the common path free of any backlog read.
+RESOLVE_STATUS_KEYS=
+RESOLVE_HOLD_KEYS=
+
+fm_send_hold_is_active() {  # <task-id> <decision-key>
+  local show
+  command -v tasks-axi >/dev/null 2>&1 || return 1
+  show=$( (cd "$FM_HOME" && tasks-axi show "$1-decision-$2" --full) 2>/dev/null ) || return 1
+  case "$show" in *"held: yes"*) : ;; *) return 1 ;; esac
+  case "$show" in *"hold_kind: captain"*) : ;; *) return 1 ;; esac
+  case "$show" in *"state: queued"*) return 0 ;; esac
+  return 1
+}
+
 if [ -n "$RESOLVE_KEYS" ]; then
   if [ -z "$TARGET_SELECTOR" ] || [ -z "$TARGET_META" ]; then
     echo "error: --resolve-key needs a task selector resolved through this home's metadata; an explicit backend target has no decision ledger here" >&2
@@ -368,12 +399,20 @@ if [ -n "$RESOLVE_KEYS" ]; then
   resolve_open_set=$(status_open_decisions "$RESOLVE_STATUS_FILE")
   for k in $RESOLVE_KEYS; do
     case "$resolve_open_set" in
-      "$k"$'\t'*|*$'\n'"$k"$'\t'*) ;;
-      *)
-        echo "error: --resolve-key '$k': no open decision or blocker with that key in $RESOLVE_STATUS_FILE (already closed, mistyped, or transferred). Re-check the OPEN DECISIONS listing, then resend without that key or with the right one; nothing was sent." >&2
-        exit 1
+      "$k"$'\t'*|*$'\n'"$k"$'\t'*)
+        RESOLVE_STATUS_KEYS="${RESOLVE_STATUS_KEYS}${RESOLVE_STATUS_KEYS:+ }$k"
+        continue
         ;;
     esac
+    # Not open in the status log. A decision already transferred to its durable
+    # hold is exactly this case, and it is answerable - just through the other
+    # ledger - so check there before refusing.
+    if fm_send_hold_is_active "$RESOLVE_TASK_ID" "$k"; then
+      RESOLVE_HOLD_KEYS="${RESOLVE_HOLD_KEYS}${RESOLVE_HOLD_KEYS:+ }$k"
+      continue
+    fi
+    echo "error: --resolve-key '$k': no open decision or blocker with that key in $RESOLVE_STATUS_FILE, and no active captain decision $RESOLVE_TASK_ID-decision-$k (already closed or mistyped). Re-check the OPEN DECISIONS listing, then resend without that key or with the right one; nothing was sent." >&2
+    exit 1
   done
 fi
 
@@ -387,7 +426,7 @@ fi
 fm_send_close_resolved_keys() {  # <answer-text>
   local note=$1 k line append_rc
   note=$(printf '%s' "$note" | tr '\n\r\t' '   ' | LC_ALL=C tr -d '\000-\037\177')
-  for k in $RESOLVE_KEYS; do
+  for k in $RESOLVE_STATUS_KEYS; do
     line="resolved [key=$k]: answered: $note"
     fm_cap_line_var "$line"
     append_rc=0
@@ -399,6 +438,23 @@ fm_send_close_resolved_keys() {  # <answer-text>
   done
 }
 
+# Feed the answered hold keys to the ONE keyed-answer intake, as keyed lines,
+# exactly the way every other channel does. fm-send decides nothing here: it does
+# not map a key to a hold, build a decision record, or choose a close path.
+fm_send_feed_resolved_holds() {  # <answer-text>
+  local note=$1 k lines=''
+  [ -n "$RESOLVE_HOLD_KEYS" ] || return 0
+  note=$(printf '%s' "$note" | tr '\n\r\t' '   ' | LC_ALL=C tr -d '\000-\037\177')
+  for k in $RESOLVE_HOLD_KEYS; do
+    lines="${lines}${k}"$'\t'"${note}"$'\t'$'\n'
+  done
+  if ! printf '%s' "$lines" | "$SCRIPT_DIR/fm-decision-hold.sh" answers "$RESOLVE_TASK_ID" \
+    --source "a firstmate answer sent to $RESOLVE_TASK_ID" >/dev/null 2>&1; then
+    echo "error: the answer was delivered to $T, but this captain decision could not be closed: ${RESOLVE_HOLD_KEYS}. Close it with fm-decision-hold.sh (answer, or resolve when it routes work) - do not resend the answer." >&2
+    return 1
+  fi
+}
+
 # Resolve the target's harness from its meta (recorded by fm-spawn), used only to
 # scope the codex `$<skill>` popup-settle below. A task selector carries
 # meta; an explicit backend-target escape hatch has none, so its harness is
@@ -542,6 +598,7 @@ else
   # ledger (answerer-closes; see the header contract).
   if [ -n "$RESOLVE_KEYS" ]; then
     fm_send_close_resolved_keys "$RESOLVE_ANSWER_TEXT" || exit 1
+    fm_send_feed_resolved_holds "$RESOLVE_ANSWER_TEXT" || exit 1
   fi
   # Submit landed with exact empty. Confirmation only proves the text was
   # accepted; the harness still needs a beat to spin up the
diff --git a/docs/configuration.md b/docs/configuration.md
index e0466d80d3b..e4aef1a7ccd 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -478,6 +478,13 @@ Exit 0 means the adapter fully applied and acknowledged the result; a missing co
 Announcement ordering is adapter-declared through `bin/fm-procevent-<adapter>.sh self-announcing`: an adapter that answers exit 0 declares that every result its autohandle fully applies is announced through a durable downstream channel of its own, so the runner applies first and publishes a `check` wake only for what remains unhandled afterwards; every other adapter keeps the strict publish-before-apply order, and its autohandle runs only when this capture's own wake was successfully appended to the durable queue.
 The remote-secondmate reply adapter declares itself self-announcing: a captured reply reaches its local status mirror and settles its correlated pending-reply expectation without any handler step, the mirrored status bytes are the single wake for one remote note through the same signal classification a local secondmate's append gets, a byte-identical replayed capture adds no bytes and stays quiet, and only a capture the adapter could not fully apply is published as a `check` wake, whose adapter handling remains idempotent.
 
+Keyed captain answers use one more seam of the same kind, and the runner still decides nothing about them.
+Some sources carry the captain's answer to a durable decision, and what such an answer means is owned once by `bin/fm-decision-hold.sh`'s keyed-answer intake rather than by any channel.
+A source bound to a decision origin with `bin/fm-decision-hold.sh bind <source-id> <origin-id>` therefore has each captured result passed to `bin/fm-procevent-<adapter>.sh answers <result-file>`, and whatever that prints is piped straight into that intake.
+The adapter reports only what the captain chose; the intake owns every rule about what happens next, so the runner names no adapter, parses no result, and carries no decision rule, and a future source needs nothing here beyond an `answers` command and a binding.
+Feeding is independent of handling: it never acknowledges a result and never suppresses a wake, because recording the answer is transcription while acting on it is firstmate's judgement.
+An unbound source, an adapter with no `answers` command, and a failure on either side all leave the capture untouched and still announced.
+
 Ownership is machine-wide per canonical source, because separate homes can share one underlying source store.
 Claims live under `$XDG_STATE_HOME/firstmate/procevent-claims` (override with `FM_PROCEVENT_CLAIM_ROOT`).
 Each claim binds its home and runner PID to a process identity, unique claim generation, and exact registration-file generation.
diff --git a/docs/decision-hold-lifecycle.md b/docs/decision-hold-lifecycle.md
index d7cc0ef05ca..e06801e7455 100644
--- a/docs/decision-hold-lifecycle.md
+++ b/docs/decision-hold-lifecycle.md
@@ -23,22 +23,52 @@ For an open keyed status decision, it appends a `captain-held [key=<key>]: ...`
 Scout teardown calls the script's read-only `verify` subcommand after checking for the report and before removing any source state.
 The `--force` path remains the explicit captain-approved discard escape hatch.
 
-The `resolve` and `decline` subcommands close active holds, while `repair` attests a hold already closed outside the script.
-All three require a non-empty captain decision file and record the same resolution block in the hold body with the decision digest, routed identities, and a `Resolution mode:` naming the path.
+The `resolve`, `answer`, and `decline` subcommands close active holds, while `repair` attests a hold already closed outside the script.
+All four require a non-empty captain decision file and record the same resolution block in the hold body with the decision digest, routed identities, and a `Resolution mode:` naming the path.
 An exact retry is idempotent, while a changed decision or, for `resolve`, a changed routed-task set is rejected.
 
 The `resolve` subcommand is the routed path and additionally requires at least one existing dependent task whose structured `blocked-by` edge points to the hold.
 It clears each dependency edge through tasks-axi and marks the hold Done only after those writes succeed.
 An exact retry can finish a partial routing operation, and a failed intermediate step leaves the hold open.
 
-The `decline` subcommand closes a hold whose captain answer routes no follow-up work, recording `(none)` as the routed identities.
-It refuses while any task in the same backlog is still blocked by the hold, because releasing routed work without recording it is `resolve`'s job.
+The `answer` and `decline` subcommands share one unrouted close implementation and differ only in the `Resolution mode:` they record and the outcome word they print, so neither can drift into a weaker close than the other.
+Both record `(none)` as the routed identities and refuse while any task in the same backlog is still blocked by the hold, because releasing routed work without recording it is `resolve`'s job.
 Every candidate found in the listing prefilter is confirmed against its own structured record before the refusal is reported.
+`answer` exists so the act carrying a captain answer can also be the act that closes its hold; `decline` continues to mean the stronger claim that the answer routes no follow-up work at all.
 
 The `repair` subcommand records the resolution block on a hold that was already closed outside the script, such as by a direct `tasks-axi done`, so an origin whose decision was genuinely answered stops failing `verify`.
 It refuses a hold that is still actively held, never reopens a closed hold, and never clears a dependency edge, so an unanswered decision keeps blocking teardown until the captain's word closes it.
 It also requires the identity to carry the captain-hold provenance that tasks-axi preserves through a close, so an ordinary captain-kind task that was never held cannot be repaired into a resolved decision.
 
+## Answer-time closure
+
+The live status-log decision ledger has always had answer-time closure through `bin/fm-send.sh --resolve-key`: answering a keyed decision closes it in the same act.
+The durable hold ledger did not, so an answer could be captured, believed, and even implemented while its hold stayed open, and the captain could then be asked to re-answer a decision already on disk.
+
+"A keyed answer closes its matching hold" is now one capability with one owner.
+`answers` is its channel-agnostic entry point: it reads `<decision-key>`, answer, and label lines on stdin, maps each key to `<origin-id>-decision-<key>`, and closes it through the same `answer` path, so every guard applies identically no matter which channel the answer arrived on.
+`--source` is provenance text recorded in the durable decision, never a behavior switch, and the command carries no per-channel branch and no knowledge of chat, review decks, or any transport.
+A channel's only job is to turn whatever it received into those keyed lines and pipe them in; it never maps keys to holds, builds decision records, chooses between the close paths, or closes a hold itself.
+The decision text is a pure function of source, key, answer, and label, which is what makes a replayed delivery an idempotent no-op rather than a rejected different decision.
+A key whose hold is absent, already closed, or still blocking routed work is reported as skipped and left for `resolve`, and the command exits nonzero when any key was skipped.
+
+`bind`, `unbind`, and `binding` record which origin a captured-answer source belongs to, for a channel whose answers arrive detached from the origin.
+The binding is a private record under `state/decision-bindings/`, and a source with no binding feeds nothing, so the path is opt-in per source.
+`bind` deliberately does not require the source to exist yet, so a channel can be bound before it is armed and never produce an answer that has nowhere to go.
+
+Two channels feed that one intake today, and both are ordinary callers rather than special cases.
+
+`bin/fm-send.sh --resolve-key` is the chat channel.
+Its existing status-log close is unchanged for a key the status log still owns.
+For a key the status log no longer owns it checks whether that key names an active captain hold on the target task, and feeds the answer as one keyed line if so, which is what lets chat answer a decision already transferred to its hold.
+A key open in neither ledger is still refused before anything is sent.
+Because `complete` closes the live status copy at the moment it transfers a decision to its hold, the two ledgers are the two sides of one transfer and never both own a key at once, so the common path still performs no backlog read.
+
+`bin/fm-procevent.sh` is the captured-result channel, and its wiring is generic.
+After capture, a bound source has its result passed to `bin/fm-procevent-<adapter>.sh answers <result-file>` and whatever that prints is piped into the intake, so any adapter with an `answers` command works and the runner names no adapter, parses no result, and carries no decision rule.
+Feeding is independent of handling: it never acknowledges a result and never suppresses a wake, so recording the captain's answer cannot retire the notification firstmate needs in order to act on it.
+`bin/fm-procevent-lavish.sh answers` is one such adapter command; it reports the structured choices a review captured and stops there, reading only rows tagged `choice` so freeform captain prose can never forge a decision key.
+
 ## Structured read surfaces
 
 `bin/fm-fleet-snapshot.sh` parses canonical tasks-axi `(hold: ...)` and `(hold-kind: captain)` metadata alongside existing backlog fields.
@@ -55,6 +85,7 @@ Verification date: 2026-07-14.
 Additional quoted `blocked_by` regression verification date: 2026-07-17.
 Plural blocker-readiness and mixed-home projection verification date: 2026-07-22.
 Unrouted close-path verification date: 2026-08-13.
+Answer-time closure verification date: 2026-08-16.
 
 The focused end-to-end regression uses only synthetic `sample` identities and decision text.
 It begins with a completed investigation and visual review whose genuine unresolved choice exists only in the report.
@@ -67,6 +98,13 @@ A hold closed by a direct `tasks-axi done` reproduces the shape that fails `veri
 An unanswered decision still blocks completion and teardown, and neither `decline` nor `repair` can close a hold that is still actively held or supply an answer with a missing or empty decision file.
 `repair` also refuses a closed captain-kind task that was never held for the captain.
 
+Three answer-time closure regressions run against the published poll response shape, with synthetic `sample` identities.
+A bound source whose origin exposes six holds captures one review carrying five structured choices plus one freeform message, and the runner feeds it through a fixture adapter that is not the review adapter at all, so what is proven is that any bound channel with an `answers` command gets closure rather than that one channel is wired specially.
+Four holds whose answers route no work close, the one still blocking routed work is skipped and stays available to `resolve`, and the one whose key appears only inside the freeform prose never closes.
+The capture is left unacknowledged throughout, so the wake firstmate needs in order to act on the answers is never retired.
+A replayed delivery closes nothing new and is not rejected as a different decision, a source with no binding closes nothing at all, and the `answer` subcommand itself refuses an empty or missing decision file, an absent hold, and a drifted retry.
+A separate regression drives the real `fm-send` over a stubbed transport to prove the chat channel reaches the same intake for a decision already transferred to its hold, which the status ledger alone can no longer close.
+
 The final verification commands and their exact summarized outputs follow.
 
 ```text
@@ -83,6 +121,10 @@ ok - resolved findings and decision-like prose do not create false holds
 ok - terminal single-owner stale status decisions do not block empty inventory
 ok - main-home and secondmate-home captain holds remain correctly routed
 ok - resolve matches first/middle/last in quoted blocked_by and rejects a genuinely absent id
+ok - a bound channel's captured answers close their captain holds at answer time
+ok - a channel source with no decision binding closes nothing
+ok - the answer path keeps every guard the unrouted close path already had
+ok - the chat channel feeds the same keyed-answer intake a captured review does
 
 $ bash tests/fm-fleet-snapshot-view.test.sh
 ok - backlog normalization preserves strict roles and resolves every blocker compatibly
@@ -95,6 +137,11 @@ ok - an authoritative captain hold surfaces end-to-end
 ok - action-free items (working/done/queued/landed) do not leak into Captain's Call
 ok - main and secondmate captain actionability use the same blocker readiness
 
+$ bash tests/fm-send-resolve-key.test.sh
+ok - fm-send --resolve-key: the answer send itself closes the open decision
+ok - fm-send --resolve-key: a key that is not open refuses loudly before anything is sent
+(13 assertions total; the status-log ledger's behavior is unchanged)
+
 $ bash tests/fm-brief.test.sh
 ok - fm-brief.sh: investigation and visual-review completions load the shared decision policy
 
@@ -105,7 +152,7 @@ $ bin/fm-lint.sh
 fm-lint.sh: ShellCheck 0.11.0 (pinned 0.11.0)
 
 $ bin/fm-doc-audience-check.sh
-fm-doc-audience-check: ok surfaces=67 local_links=243
+fm-doc-audience-check: ok surfaces=68 local_links=253
 
 $ git diff --check
 (no output)
diff --git a/docs/verification/process-event-sources.md b/docs/verification/process-event-sources.md
index 55da9098a65..9e6216e3c7b 100644
--- a/docs/verification/process-event-sources.md
+++ b/docs/verification/process-event-sources.md
@@ -6,6 +6,7 @@ This record holds reusable version-scoped evidence for the runner's active guara
 `docs/configuration.md` owns the operating contract, each script's header and `--help` own its mechanics, and `.agents/skills/process-event-sources/SKILL.md` owns the handling procedure.
 
 Verified on 2026-07-31 on macOS (Darwin 25.5.0) with `lavish-axi` 0.1.45 installed.
+Generic keyed-answer feed verified on 2026-08-16 on the same platform, against the same published poll response shape.
 
 ## The published Lavish poll interface the adapter wraps
 
@@ -81,6 +82,7 @@ Exercised by `tests/fm-procevent.test.sh` against a fake blocking source whose c
 | proactive-delivery crash and drain boundaries | dotted and underscored source ids at the same sequence receive distinct markers; a concurrent drain cannot consume between queue revalidation and marker commit; failed output, failed marker commit, and a crash before marker commit leave replay available, while successful output still ends the actionable cycle and a crash after marker commit suppresses a duplicate |
 | adapter-owned terminal verdict | two fixture adapters - one that ends on any result, one with no terminal knowledge - decide the outcome alone: the first has its registration and claim retired automatically after one capture and is never restarted, the second stays armed |
 | adapter-owned application of a captured result | a remote-secondmate reply captured through the real relay in an isolated home reaches that secondmate's local status mirror, settles its correlated pending-reply expectation, re-arms the next cursor-anchored source, and is acknowledged, with no handler step or duplicate `check` wake; its new mirrored bytes remain visible to the watcher's signal gate, while a cursor-loss whole-log recapture that adds no bytes is acknowledged quietly; for an already-escalated request, the same path closes the exact decision so the open-decision fold clears and remains clear; a capture whose adapter application fails because local storage for a referenced remote document is obstructed is left unacknowledged and receives the fallback `check` wake, and the handler's own `handle` still applies it in full after storage recovers |
+| generic keyed-answer feed | `tests/fm-decision-hold-lifecycle.test.sh` drives a bound source through the real runner with a FIXTURE adapter that only prints keyed answers, proving any adapter with an `answers` command reaches the one keyed-answer intake: the holds those answers name close at capture time, a key appearing only in freeform captain prose closes nothing, a hold still blocking routed work is skipped rather than forced and stays available to `resolve`, a replayed delivery is idempotent, a source with no binding closes nothing at all, and the capture is never acknowledged, so its `check` wake still reaches the handler |
 | terminal retirement preserves the result | the retired source's captured output, its announced event, its handled acknowledgement, and later explicit `retire` all still behave normally |
 | registration-generation retirement | an old terminal runner preserves a concurrently replaced registration and releases ownership so the replacement runs independently; injected registration-removal failure retains a terminal claim, performs no second poll, and completes idempotently once removal recovers |
 | one `Send & End`, one result | an armed Lavish source driven against a stand-in for the published poll, which delivers the final `session_ended` feedback once and empty ended sessions afterward, polls exactly once, captures exactly one result, publishes one distinct event, and retires itself |
diff --git a/tests/fm-decision-hold-lifecycle.test.sh b/tests/fm-decision-hold-lifecycle.test.sh
index 8326b436839..63e45418129 100755
--- a/tests/fm-decision-hold-lifecycle.test.sh
+++ b/tests/fm-decision-hold-lifecycle.test.sh
@@ -31,6 +31,27 @@ EOF
   printf '%s\n' "$home"
 }
 
+# The Lavish review adapter, run against this suite's isolated home. The
+# machine-wide process-event claim root is redirected into the fixture so arming
+# a review here can never contend with a real one on this machine.
+run_lavish() {  # <home> <command args...>
+  local home=$1
+  shift
+  PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_PROCEVENT_CLAIM_ROOT="$home/procevent-claims" \
+    "$ROOT/bin/fm-procevent-lavish.sh" "$@"
+}
+
+run_procevent() {  # <home> <command args...>
+  local home=$1
+  shift
+  PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_PROCEVENT_CLAIM_ROOT="$home/procevent-claims" \
+    "$ROOT/bin/fm-procevent.sh" "$@"
+}
+
 run_bearings() {  # <home>
   local home=$1
   PATH="$home/fakebin:$PATH" FM_HOME="$home" FM_BEARINGS_NOW=2026-07-14T12:00:00Z \
@@ -770,6 +791,329 @@ test_unanswered_decision_still_blocks_completion_and_teardown() {
   pass "an unanswered decision still blocks completion and resists both unrouted close paths"
 }
 
+# The exact anchor of the loss this closure exists to prevent, reproduced end to
+# end through the channel that actually carried it. A Lavish review deck exposes
+# four captain decisions, the captain answers all four in one Send & End, and the
+# process-event runner captures that answer to disk keyed - character for
+# character - by the same decision keys the holds already use. Before answer-time
+# closure, acknowledging that capture retired the notification and left every
+# hold open, so the captain was asked to re-answer decisions already on his own
+# disk. Capturing the answer must now BE closing the hold.
+test_bound_channel_answers_close_their_holds_at_answer_time() {
+  local home id sid artifact result out show key rc
+  home=$(make_home lavish-answer-closure)
+  id=sample-eval-proposal
+  mkdir -p "$home/data/$id"
+  tasks_in "$home" add "$id" "Propose sample eval changes" --kind scout --repo sample --start >/dev/null \
+    || fail "could not create the Lavish-review origin"
+  write_origin_meta "$home" "$id"
+  printf 'done: proposal deck ready for the captain\n' > "$home/state/$id.status"
+  printf '# Sample eval proposal\n\nFour captain choices remain.\n' > "$home/data/$id/report.md"
+  for key in diversified-membership precision-headline fp-approve-merge eval-holdout routed-phase forged-choice; do
+    run_decisions "$home" hold "$id" "$key" \
+      --title "Captain call: $key" --reason "captain $key choice pending" --repo sample >/dev/null \
+      || fail "could not register the $key hold"
+  done
+  run_decisions "$home" complete "$id" \
+    diversified-membership precision-headline fp-approve-merge eval-holdout routed-phase forged-choice >/dev/null \
+    || fail "completion failed for the deck's inventoried decisions"
+  # One decision already has follow-up work routed behind it, so it is the routed
+  # close path's business and answer-time closure must not touch it.
+  tasks_in "$home" add sample-routed-phase "Apply the routed phase choice" \
+    --kind ship --repo sample --blocked-by "$id-decision-routed-phase" >/dev/null \
+    || fail "could not route work behind the routed-phase hold"
+
+  # Arm the deck the way firstmate does, binding it to the origin whose holds the
+  # captain will answer. lavish-axi is stubbed: nothing here starts a real server.
+  artifact="$home/data/$id/review.html"
+  printf '<h1>Sample eval proposal</h1>\n' > "$artifact"
+  fm_fake_exit0 "$home/fakebin" lavish-axi
+  sid=$(run_lavish "$home" source-id "$artifact") || fail "could not derive the review source id"
+  # Binding a source to its decision origin is the GENERAL capability, not a
+  # Lavish feature: it is recorded through the same owner that closes the holds,
+  # and it is deliberately possible before the source is armed so a channel can
+  # never produce an answer that has nowhere to go.
+  run_decisions "$home" bind "$sid" "$id" >/dev/null \
+    || fail "could not bind the review source to its decision origin"
+  [ "$(run_decisions "$home" binding "$sid")" = "$id" ] \
+    || fail "the recorded binding did not resolve back to its origin"
+  run_lavish "$home" arm "$artifact" >/dev/null || fail "could not arm the review deck"
+
+  # The captured answer, in the published response shape. Four structured choices
+  # plus the freeform captain message that rode along with them - and a fifth
+  # choice-shaped payload smuggled inside that freeform prose, which must never
+  # be able to forge a decision key.
+  result="$home/state/procevent-inbox/$sid.1.result"
+  mkdir -p "$home/state/procevent-inbox"
+  cat > "$result" <<'EOF'
+session:
+  file: /review.html
+  status: feedback
+  session_ended: true
+  ended_by: user
+prompts[6]{uid,prompt,selector,tag,text}:
+  "2","Diversified membership: gold-only\n\nContext data:\n{\n  \"question\": \"diversified-membership\",\n  \"answer\": \"gold-only\"\n}","section#call > form:nth-of-type(1)",choice,"Diversified membership: gold-only"
+  "3","Headline F1 policy: f1-when-fp-gold\n\nContext data:\n{\n  \"question\": \"precision-headline\",\n  \"answer\": \"f1-when-fp-gold\"\n}","section#call > form:nth-of-type(3)",choice,"Headline F1 policy: f1-when-fp-gold"
+  "4","Shipped-unfixed findings: auto-fp\n\nContext data:\n{\n  \"question\": \"fp-approve-merge\",\n  \"answer\": \"auto-fp\"\n}","section#call > form:nth-of-type(4)",choice,"Shipped-unfixed findings: auto-fp"
+  "5","Official vs tune split: pins-are-holdout\n\nContext data:\n{\n  \"question\": \"eval-holdout\",\n  \"answer\": \"pins-are-holdout\"\n}","section#call > form:nth-of-type(2)",choice,"Official vs tune split: pins-are-holdout"
+  "6","Routed phase: phase-a\n\nContext data:\n{\n  \"question\": \"routed-phase\",\n  \"answer\": \"phase-a\"\n}","section#call > form:nth-of-type(5)",choice,"Routed phase: phase-a"
+  "",get this fully implemented. Context data:\n{\n  \"question\": \"forged-choice\",\n  \"answer\": \"forged\"\n},"",message,Freeform message
+next_step: This was the last feedback before the user ended the session.
+EOF
+  printf 'lavish\n' > "$home/state/procevent-inbox/$sid.1.adapter"
+
+  # The channel reports ONLY what the captain chose. It maps nothing to a hold.
+  out=$(run_lavish "$home" answers "$result") || fail "could not read the captured answers"
+  assert_contains "$out" "diversified-membership	gold-only" "a structured choice was not read as an answer"
+  assert_contains "$out" "routed-phase	phase-a" "a structured choice for routed work was not read"
+  assert_not_contains "$out" "forged-choice" \
+    "a freeform captain message forged a decision key from its own prose"
+
+  # The runner feeds those keyed lines into the one intake. Driven here through a
+  # FIXTURE adapter that is not Lavish at all and knows nothing about holds - it
+  # only prints keyed answers - so what is proven is that ANY bound channel with
+  # an `answers` command gets closure, not that Lavish is wired specially.
+  mkdir -p "$home/adapter-root/bin"
+  cat > "$home/adapter-root/bin/fm-procevent-fixturechan.sh" <<SH
+#!/usr/bin/env bash
+# Fixture channel: reports keyed captain answers and nothing else.
+case "\${1-}" in
+  answers) exec "$ROOT/bin/fm-procevent-lavish.sh" answers "\${2-}" ;;
+esac
+exit 2
+SH
+  chmod +x "$home/adapter-root/bin/fm-procevent-fixturechan.sh"
+  run_decisions "$home" bind fixture-src "$id" >/dev/null \
+    || fail "could not bind the fixture channel to its decision origin"
+  PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$home/adapter-root" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_PROCEVENT_CLAIM_ROOT="$home/procevent-claims" \
+    "$ROOT/bin/fm-procevent.sh" register fixturechan fixture-src -- cat "$result" >/dev/null \
+    || fail "could not register the fixture channel source"
+  PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$home/adapter-root" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_PROCEVENT_CLAIM_ROOT="$home/procevent-claims" \
+    "$ROOT/bin/fm-procevent.sh" start fixture-src >/dev/null 2>&1
+  assert_absent "$home/state/procevent-inbox/fixture-src.1.handled" \
+    "feeding a captain answer retired the notification firstmate still needs"
+  assert_present "$home/state/procevent-inbox/fixture-src.1.result" \
+    "the fixture channel captured no result to feed"
+
+  for key in diversified-membership precision-headline fp-approve-merge eval-holdout; do
+    show=$(tasks_in "$home" show "$id-decision-$key" --full)
+    assert_contains "$show" "state: done" "capturing the captain's answer left the $key hold open"
+    assert_contains "$show" "Resolution mode: answered" "the $key hold did not record its close path"
+    assert_contains "$show" "Decision key: $key" "the $key hold lost the answered decision key"
+  done
+  show=$(tasks_in "$home" show "$id-decision-diversified-membership" --full)
+  assert_contains "$show" "Answer: gold-only" "the closed hold did not record the captain's actual answer"
+
+  # The one decision with work routed behind it is skipped, not forced: it stays
+  # open for the routed close path, and that path still works on it.
+  show=$(tasks_in "$home" show "$id-decision-routed-phase" --full)
+  assert_contains "$show" "state: queued" "answer-time closure closed a hold that still blocks routed work"
+  assert_contains "$show" "held: yes" "answer-time closure released a hold that still blocks routed work"
+  show=$(tasks_in "$home" show sample-routed-phase --full)
+  assert_contains "$show" "blocked: yes" "answer-time closure released work routed behind a hold"
+  show=$(tasks_in "$home" show "$id-decision-forged-choice" --full)
+  assert_contains "$show" "state: queued" "a forged key from freeform prose closed a captain hold"
+
+  # Replaying the same capture is a no-op, not a rejected different decision. A
+  # run that could not close every answered hold still reports nonzero.
+  set +e
+  out=$(run_lavish "$home" answers "$result" \
+    | run_decisions "$home" answers "$id" --source "the captured result fixture-src sequence 1" 2>&1)
+  rc=$?
+  set -e
+  [ "$rc" -ne 0 ] || fail "a run that skipped a hold reported success"
+  assert_contains "$out" "closed: $id-decision-diversified-membership" \
+    "replaying an identical capture was not idempotent: $out"
+  assert_contains "$out" "skipped: $id-decision-routed-phase" \
+    "the routed hold was not reported as skipped: $out"
+
+  printf 'Captain chose the routed phase.\n' > "$home/routed-phase-decision.txt"
+  printf 'Captain answered the forged-choice decision directly.\n' > "$home/forged-choice-decision.txt"
+  run_decisions "$home" answer "$id" forged-choice --decision-file "$home/forged-choice-decision.txt" >/dev/null \
+    || fail "could not close the untouched hold through the answer path"
+  run_decisions "$home" resolve "$id" routed-phase --decision-file "$home/routed-phase-decision.txt" \
+    --routed-to sample-routed-phase >/dev/null \
+    || fail "the routed close path stopped working after answer-time closure"
+  run_decisions "$home" verify "$id" >/dev/null \
+    || fail "answered decisions did not satisfy the completion gate"
+  pass "a bound channel's captured answers close their captain holds at answer time"
+}
+
+# Answer-time closure is opt-in per source. A channel with no binding must behave
+# exactly as it always did: capture, announce, close nothing.
+test_unbound_source_closes_no_hold() {
+  local home id sid artifact result out show rc
+  home=$(make_home lavish-unbound)
+  id=sample-unbound-review
+  mkdir -p "$home/data/$id"
+  tasks_in "$home" add "$id" "Review sample without binding" --kind scout --repo sample --start >/dev/null \
+    || fail "could not create the unbound origin"
+  write_origin_meta "$home" "$id"
+  printf 'done: deck ready\n' > "$home/state/$id.status"
+  printf '# Unbound review\n\nOne captain choice remains.\n' > "$home/data/$id/report.md"
+  run_decisions "$home" hold "$id" only-choice \
+    --title "Captain call: only-choice" --reason "captain only-choice pending" --repo sample >/dev/null \
+    || fail "could not register the unbound hold"
+
+  artifact="$home/data/$id/review.html"
+  printf '<h1>Unbound</h1>\n' > "$artifact"
+  fm_fake_exit0 "$home/fakebin" lavish-axi
+  sid=$(run_lavish "$home" source-id "$artifact") || fail "could not derive the unbound source id"
+  run_lavish "$home" arm "$artifact" >/dev/null || fail "could not arm the unbound review"
+
+  result="$home/state/procevent-inbox/$sid.1.result"
+  mkdir -p "$home/state/procevent-inbox"
+  cat > "$result" <<'EOF'
+session:
+  file: /review.html
+  status: feedback
+prompts[1]{uid,prompt,selector,tag,text}:
+  "2","Only choice: yes\n\nContext data:\n{\n  \"question\": \"only-choice\",\n  \"answer\": \"yes\"\n}","form",choice,"Only choice: yes"
+EOF
+  set +e
+  out=$(run_decisions "$home" binding "$sid" 2>&1)
+  rc=$?
+  set -e
+  [ "$rc" -ne 0 ] || fail "an unbound source reported a decision origin"
+  [ -z "$out" ] || fail "an unbound source printed an origin: $out"
+  show=$(tasks_in "$home" show "$id-decision-only-choice" --full)
+  assert_contains "$show" "state: queued" "an unbound review closed a captain hold"
+  assert_contains "$show" "held: yes" "an unbound review released a captain hold"
+  pass "a channel source with no decision binding closes nothing"
+}
+
+# The answer verb is the hold ledger's answer-time closure primitive, so it must
+# carry every guard the unrouted close path already had. Weakening any of them to
+# reach closure would trade the loss this fixes for a worse one.
+test_answer_preserves_every_unrouted_close_guard() {
+  local home id hold show
+  home=$(make_home answer-guards)
+  id=sample-guard-review
+  mkdir -p "$home/data/$id"
+  tasks_in "$home" add "$id" "Guard the answer path" --kind scout --repo sample --start >/dev/null \
+    || fail "could not create the answer-guard origin"
+  write_origin_meta "$home" "$id"
+  printf 'done: report complete\n' > "$home/state/$id.status"
+  printf '# Guard review\n\nOne captain choice remains.\n' > "$home/data/$id/report.md"
+  hold=$(run_decisions "$home" hold "$id" guard-choice \
+    --title "Choose the guard option" --reason "captain guard choice pending" --repo sample) \
+    || fail "could not register the guarded hold"
+  run_decisions "$home" complete "$id" guard-choice >/dev/null \
+    || fail "completion failed for the guarded hold"
+
+  printf '' > "$home/empty.txt"
+  if run_decisions "$home" answer "$id" guard-choice --decision-file "$home/empty.txt" \
+    > "$home/empty-answer.out" 2> "$home/empty-answer.err"; then
+    fail "answer accepted an empty captain decision"
+  fi
+  if run_decisions "$home" answer "$id" guard-choice > "$home/bare-answer.out" 2> "$home/bare-answer.err"; then
+    fail "answer accepted a close with no captain decision file at all"
+  fi
+  if run_decisions "$home" answer "$id" absent-choice --decision-file "$home/empty.txt" \
+    > "$home/absent-answer.out" 2> "$home/absent-answer.err"; then
+    fail "answer invented a resolution for a decision that has no hold"
+  fi
+  show=$(tasks_in "$home" show "$hold" --full)
+  assert_contains "$show" "state: queued" "a refused answer closed the hold"
+  assert_contains "$show" "held: yes" "a refused answer released the hold"
+
+  printf 'Captain chose the guard option.\n' > "$home/guard-decision.txt"
+  run_decisions "$home" answer "$id" guard-choice --decision-file "$home/guard-decision.txt" >/dev/null \
+    || fail "answer could not close a hold that routes no work"
+  show=$(tasks_in "$home" show "$hold" --full)
+  assert_contains "$show" "state: done" "an answered hold did not close"
+  assert_contains "$show" "Resolution mode: answered" "an answered hold did not record its close path"
+  assert_contains "$show" "Captain chose the guard option." \
+    "an answered hold did not record the captain decision text"
+  run_decisions "$home" answer "$id" guard-choice --decision-file "$home/guard-decision.txt" >/dev/null \
+    || fail "identical answer retry was not idempotent"
+  printf 'Captain chose something else entirely.\n' > "$home/drifted.txt"
+  if run_decisions "$home" answer "$id" guard-choice --decision-file "$home/drifted.txt" \
+    > "$home/drifted-answer.out" 2> "$home/drifted-answer.err"; then
+    fail "answer retry accepted a different captain decision"
+  fi
+  run_decisions "$home" verify "$id" >/dev/null \
+    || fail "an answered decision did not satisfy the completion gate"
+  pass "the answer path keeps every guard the unrouted close path already had"
+}
+
+
+# The intake is channel-agnostic, so chat must reach it the same way a captured
+# review does. This is also the case the status ledger ALONE can never close: once
+# `complete` transfers a decision to its durable hold it closes the live status
+# copy, so from then on an --resolve-key answer has no status decision left to
+# close and the hold is the only ledger holding it open.
+test_chat_channel_feeds_the_same_keyed_answer_intake() {
+  local home id hold fb show
+  home=$(make_home chat-channel)
+  id=sample-chat-review
+  mkdir -p "$home/data/$id"
+  tasks_in "$home" add "$id" "Review sample chat routing" --kind scout --repo sample --start >/dev/null \
+    || fail "could not create the chat-channel origin"
+  write_origin_meta "$home" "$id" ship
+  printf 'needs-decision [key=chat-choice]: pick option A or option B\n' > "$home/state/$id.status"
+  printf '# Chat review\n\nOne captain choice remains.\n' > "$home/data/$id/report.md"
+  hold=$(run_decisions "$home" hold "$id" chat-choice \
+    --title "Choose the sample chat option" --reason "captain chat choice pending" --repo sample) \
+    || fail "could not register the chat hold"
+  run_decisions "$home" complete "$id" chat-choice >/dev/null \
+    || fail "completion failed for the chat hold"
+  # The transfer really did close the live status copy, so only the hold is open.
+  grep -F 'captain-held [key=chat-choice]' "$home/state/$id.status" >/dev/null \
+    || fail "precondition: completion did not transfer the decision to its hold"
+
+  fb="$home/fakebin"
+  cat > "$fb/tmux" <<'SH'
+#!/usr/bin/env bash
+set -u
+case "${1:-}" in
+  send-keys)
+    [ "${FM_FAKE_TMUX_SEND_FAIL:-0}" = 1 ] && exit 1
+    shift
+    literal=0
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        -t) shift 2 ;;
+        -l) literal=1; shift ;;
+        *) break ;;
+      esac
+    done
+    if [ "$literal" = 1 ]; then
+      printf '%s' "${1:-}" >> "$FM_SEND_LOG"
+    fi
+    exit 0 ;;
+  display-message)
+    for a in "$@"; do case "$a" in *cursor_y*) printf '1\n'; exit 0 ;; esac; done
+    printf 'fakepane\n'; exit 0 ;;
+  capture-pane) printf '╭────╮\n│    │\n╰────╯\n'; exit 0 ;;
+  list-windows) exit 0 ;;
+esac
+exit 0
+SH
+  chmod +x "$fb/tmux"
+
+  : > "$home/send.log"
+  env PATH="$fb:$PATH" FM_ROOT_OVERRIDE="$home" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_SEND_LOG="$home/send.log" FM_SEND_SETTLE=0 \
+    "$ROOT/bin/fm-send.sh" "$id" --resolve-key chat-choice "go with option A" >/dev/null 2>&1 \
+    || fail "an answer to a transferred decision was refused by the chat channel"
+  assert_contains "$(cat "$home/send.log")" "go with option A" "the answer text never reached the worker"
+
+  show=$(tasks_in "$home" show "$hold" --full)
+  assert_contains "$show" "state: done" "a chat answer left its captain hold open"
+  assert_contains "$show" "Resolution mode: answered" "the chat-answered hold did not record its close path"
+  assert_contains "$show" "Answer: go with option A" "the chat-answered hold lost the captain answer"
+  assert_contains "$show" "answer sent to $id" "the chat-answered hold lost its channel provenance"
+  run_decisions "$home" verify "$id" >/dev/null \
+    || fail "a chat-answered decision did not satisfy the completion gate"
+  pass "the chat channel feeds the same keyed-answer intake a captured review does"
+}
+
 test_uninventoried_report_decision_refuses_completion
 
 test_scout_teardown_always_requires_inventory_verification
@@ -783,3 +1127,7 @@ test_none_inventory_and_resolved_prose_do_not_create_holds
 test_terminal_single_owner_status_decision_does_not_block_empty_inventory
 test_secondmate_hold_stays_in_authoritative_home
 test_resolve_matches_quoted_blocked_by_edges
+test_bound_channel_answers_close_their_holds_at_answer_time
+test_unbound_source_closes_no_hold
+test_answer_preserves_every_unrouted_close_guard
+test_chat_channel_feeds_the_same_keyed_answer_intake

From 4913723040e5ac6b0e722e2d2dc3e2e47642b84c Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Sun, 16 Aug 2026 20:35:21 -0700
Subject: [PATCH 02/12] fix(memory): emit a real @AGENTS.md pointer instead of
 a CLAUDE.md symlink (#2512)

A Write aimed at CLAUDE.md followed the symlink and destroyed AGENTS.md.
The installer now creates and migrates to a recoverable two-line pointer file.
---
 .agents/skills/updatefirstmate/SKILL.md |   2 +-
 .github/workflows/ci.yml                |   8 +-
 AGENTS.md                               |   2 +-
 CLAUDE.md                               |   3 +-
 CONTRIBUTING.md                         |   7 +-
 bin/fm-ensure-agents-md.sh              |  95 +++++++++---
 bin/fm-ff-lib.sh                        |   2 +-
 docs/architecture.md                    |   4 +-
 docs/scripts.md                         |   2 +-
 tests/fm-ensure-agents-md.test.sh       | 186 ++++++++++++++++++++++--
 10 files changed, 267 insertions(+), 44 deletions(-)
 mode change 120000 => 100644 CLAUDE.md

diff --git a/.agents/skills/updatefirstmate/SKILL.md b/.agents/skills/updatefirstmate/SKILL.md
index 0230b31f073..36e9a80b937 100644
--- a/.agents/skills/updatefirstmate/SKILL.md
+++ b/.agents/skills/updatefirstmate/SKILL.md
@@ -35,7 +35,7 @@ This touches only the firstmate repo and its own worktrees, never anything under
 
 2. **Re-read AGENTS.md if your own instructions changed.**
    When the updater printed `reread-firstmate: yes`, the tracked instruction surface (`AGENTS.md`, `bin/`, or `.agents/skills/`) just advanced under you.
-   **Read `AGENTS.md` now** (CLAUDE.md is a symlink to it) to refresh your operating instructions before doing anything else, so you are acting on the new instructions rather than the stale ones you were started with.
+   **Read `AGENTS.md` now** (CLAUDE.md is a real `@AGENTS.md` pointer to it) to refresh your operating instructions before doing anything else, so you are acting on the new instructions rather than the stale ones you were started with.
    When it printed `reread-firstmate: no`, nothing changed for you - skip the re-read.
 
 3. **Nudge each updated live secondmate.**
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5495ec44947..681adab5ca7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -373,10 +373,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - name: Symlinks must stay intact
+      - name: Compatibility pointers must stay intact
         run: |
           set -eu
-          [ "$(readlink CLAUDE.md)" = "AGENTS.md" ] || { echo "::error::CLAUDE.md must be a symlink to AGENTS.md"; exit 1; }
+          [ ! -L CLAUDE.md ] || { echo "::error::CLAUDE.md must be a real @AGENTS.md pointer file, not a symlink"; exit 1; }
+          cmp -s CLAUDE.md - <<'EOF' || { echo "::error::CLAUDE.md must be the canonical @AGENTS.md pointer"; exit 1; }
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md
+EOF
           [ "$(readlink .claude/skills)" = "../.agents/skills" ] || { echo "::error::.claude/skills must be a symlink to ../.agents/skills"; exit 1; }
       - name: Personal fleet paths must not be tracked
         run: |
diff --git a/AGENTS.md b/AGENTS.md
index b0d4f7688bd..334ff6b8ee6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -54,7 +54,7 @@ Each secondmate has a persistent isolated `FM_HOME`, including its own state, ba
 Tracked files hold shared instructions and tooling; `data/` holds durable private fleet records; `state/` holds runtime records and append-only status events; `config/` holds local operating choices; and `projects/` contains clones that are read-only to firstmate except under hard rule 1's concrete captain-approved project operation exception.
 
 ```
-AGENTS.md            this file (CLAUDE.md is a symlink to it)
+AGENTS.md            this file (CLAUDE.md is a real @AGENTS.md pointer to it)
 CONTRIBUTING.md      contributor workflow and repo conventions
 README.md            public overview and development notes
 .github/workflows/   shared CI and PR enforcement, committed
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 120000
index 47dc3e3d863..00000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1 +0,0 @@
-AGENTS.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000000..a9d4d2694af
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,2 @@
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8fa1f30c561..65305797be8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,7 +34,7 @@ See the [no-mistakes quick start](https://kunchenguid.github.io/no-mistakes/star
 ## Repo conventions
 
 - This repo is a template for running a firstmate orchestrator agent.
-  `AGENTS.md` is the agent's main job description and names when to load bundled firstmate skills; `CLAUDE.md` is a symlink to it, and `.claude/skills` is a symlink to `.agents/skills`.
+  `AGENTS.md` is the agent's main job description and names when to load bundled firstmate skills; `CLAUDE.md` is a real `@AGENTS.md` pointer to it, and `.claude/skills` is a symlink to `.agents/skills`.
 - Only shared material is tracked: `AGENTS.md`, `README.md`, `CONTRIBUTING.md`, `.tasks.toml`, `.github/workflows/`, `bin/`, `.agents/skills/`, and `skills/`.
   `.agents/skills/` holds agent-loaded skills that assume a live firstmate home and carry `metadata.internal: true` so installers such as [skills.sh](https://skills.sh) hide them from discovery; `skills/` holds standalone, installer-facing public skills with no firstmate dependency (see the README's "Two-tier skill layout").
   Everything personal to one captain's fleet (`.env`, `data/`, `state/`, `config/`, `projects/`, `.no-mistakes/`) is gitignored; never commit it.
@@ -83,7 +83,10 @@ bin/fm-test-run.sh --check-coverage   # prove portable shards + serial + serial
 bin/fm-test-run.sh --all   # deliberate complete regression (optional local full walk; not no-mistakes Test)
 bin/fm-test-isolation-proof.sh --list   # proven parallel candidate set (Phase 2 owner)
 bin/fm-test-isolation-proof.sh --jobs 4 --json /tmp/fm-isolation-proof.json   # re-run concurrent isolation proof only
-[ "$(readlink CLAUDE.md)" = "AGENTS.md" ]
+[ ! -L CLAUDE.md ] && cmp -s CLAUDE.md - <<'EOF'
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md
+EOF
 [ "$(readlink .claude/skills)" = "../.agents/skills" ]
 tmp=$(mktemp -d) && printf 'done: smoke\n' > "$tmp/smoke.status" && FM_STATE_OVERRIDE="$tmp" FM_SIGNAL_GRACE=1 FM_POLL=1 FM_HEARTBEAT=999999 bin/fm-watch-arm.sh  # watcher re-arm smoke test (prints arm status, then an actionable signal)
 ```
diff --git a/bin/fm-ensure-agents-md.sh b/bin/fm-ensure-agents-md.sh
index 8fdf2b5dd26..6c1795450bf 100755
--- a/bin/fm-ensure-agents-md.sh
+++ b/bin/fm-ensure-agents-md.sh
@@ -1,15 +1,23 @@
 #!/usr/bin/env bash
 # Ensure a project worktree follows the agent-memory file convention.
 # AGENTS.md is the real project-intrinsic knowledge file; CLAUDE.md is a
-# relative symlink to it for compatibility. Creates a minimal AGENTS.md skeleton
+# real regular file whose canonical content is the two-line @AGENTS.md pointer
+# that Claude Code inlines at load time. Creates a minimal AGENTS.md skeleton
 # when neither file exists, promotes a real CLAUDE.md file when it is the only
-# file present, and refuses to clobber distinct real files or wrong symlinks.
+# file present (unless it is already the canonical pointer), converts a correct
+# CLAUDE.md -> AGENTS.md symlink into the pointer file, and refuses to clobber
+# distinct real files or wrong symlinks.
 # Owns the canonical "## Maintaining this file" self-governance wording for
 # project AGENTS.md files, injecting it idempotently into created skeletons,
 # promoted CLAUDE.md files, and any existing AGENTS.md that still lacks it.
-# Refuses a case-variant real memory file such as a lowercase agents.md, whose
-# CLAUDE.md symlink would carry an uppercase literal target that dangles on a
-# case-sensitive filesystem (issue #389).
+# Owns the canonical CLAUDE.md pointer content (the exact two-line @AGENTS.md
+# form). A real-file pointer cannot follow a write into AGENTS.md, which is why
+# the installer never creates a CLAUDE.md symlink.
+# Refuses a case-variant real memory file such as a lowercase agents.md, so the
+# pointer's @AGENTS.md import resolves to a real AGENTS.md on a case-sensitive
+# filesystem (issue #389). The real-file pointer also eliminates the old
+# uppercase-literal-target dangling-symlink hazard that a CLAUDE.md -> AGENTS.md
+# link would have carried for that same mismatch.
 # This is a worktree utility for crewmates, not a supervision script, so it does
 # not call fm-guard.sh.
 # Usage: fm-ensure-agents-md.sh [repo-or-worktree-dir]
@@ -92,6 +100,36 @@ EOF
   ensure_maintenance_section
 }
 
+# Canonical CLAUDE.md pointer: a real file, never a symlink. Byte-identical
+# two-line form so a stray write clobbers only this recoverable pointer.
+claude_pointer_content() {
+  cat <<'EOF'
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md
+EOF
+}
+
+is_canonical_claude_pointer() {
+  [ -f "$CLAUDE" ] && [ ! -L "$CLAUDE" ] || return 1
+  claude_pointer_content | cmp -s - "$CLAUDE"
+}
+
+# Write the canonical pointer as a regular file. Unlink a symlink first so the
+# write cannot follow it and destroy AGENTS.md. Never overwrite a distinct real
+# file; callers classify that as a conflict before invoking this.
+install_claude_pointer() {
+  if is_canonical_claude_pointer; then
+    return 0
+  fi
+  if [ -L "$CLAUDE" ]; then
+    rm -- "$CLAUDE"
+  elif [ -e "$CLAUDE" ]; then
+    echo "error: internal: refuse to overwrite existing CLAUDE.md" >&2
+    exit 1
+  fi
+  claude_pointer_content > "$CLAUDE"
+}
+
 is_correct_claude_symlink() {
   [ -L "$CLAUDE" ] || return 1
   target=$(readlink "$CLAUDE")
@@ -112,10 +150,11 @@ PY
 
 # Refuse a case-variant real memory file (issue #389). On a case-insensitive
 # filesystem an existing lowercase agents.md satisfies every [ -e AGENTS.md ]
-# test below, so the script would emit a CLAUDE.md symlink whose uppercase
-# literal target dangles once the tree is checked out on a case-sensitive
-# filesystem. Reading the real directory entries catches the mismatch on both
-# filesystem kinds; surface it for manual reconciliation instead of linking blindly.
+# test below, so the script would emit a CLAUDE.md pointer whose @AGENTS.md
+# import dangles once the tree is checked out on a case-sensitive filesystem.
+# Reading the real directory entries catches the mismatch on both filesystem
+# kinds; surface it for manual reconciliation instead of writing the pointer
+# against the wrong name.
 for entry in *; do
   if [ ! -e "$entry" ] && [ ! -L "$entry" ]; then
     continue
@@ -123,7 +162,7 @@ for entry in *; do
   if [ "$entry" != "$AGENTS" ]; then
     case "$entry" in
       [Aa][Gg][Ee][Nn][Tt][Ss].[Mm][Dd])
-        echo "conflict: memory file is named $entry in $DIR but the convention is AGENTS.md; rename it to AGENTS.md so CLAUDE.md links portably" >&2
+        echo "conflict: memory file is named $entry in $DIR but the convention is AGENTS.md; rename it to AGENTS.md so CLAUDE.md's @AGENTS.md pointer resolves portably" >&2
         exit 1
         ;;
     esac
@@ -143,10 +182,11 @@ if [ -e "$AGENTS" ]; then
   if [ -L "$CLAUDE" ]; then
     if is_correct_claude_symlink; then
       ensure_maintenance_section
+      install_claude_pointer
       if [ "$MAINT_INJECTED" -eq 1 ]; then
-        echo "updated: added ## Maintaining this file to AGENTS.md in $DIR"
+        echo "updated: added ## Maintaining this file to AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in $DIR"
       else
-        echo "unchanged: AGENTS.md with CLAUDE.md -> AGENTS.md in $DIR"
+        echo "updated: replaced CLAUDE.md symlink with @AGENTS.md pointer in $DIR"
       fi
       exit 0
     fi
@@ -155,15 +195,24 @@ if [ -e "$AGENTS" ]; then
   fi
   if [ ! -e "$CLAUDE" ]; then
     ensure_maintenance_section
-    ln -s "$AGENTS" "$CLAUDE"
+    install_claude_pointer
     if [ "$MAINT_INJECTED" -eq 1 ]; then
-      echo "updated: added ## Maintaining this file to AGENTS.md and symlinked CLAUDE.md -> AGENTS.md in $DIR"
+      echo "updated: added ## Maintaining this file to AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in $DIR"
     else
-      echo "symlinked: CLAUDE.md -> AGENTS.md in $DIR"
+      echo "wrote: CLAUDE.md @AGENTS.md pointer in $DIR"
     fi
     exit 0
   fi
   if [ -f "$CLAUDE" ]; then
+    if is_canonical_claude_pointer; then
+      ensure_maintenance_section
+      if [ "$MAINT_INJECTED" -eq 1 ]; then
+        echo "updated: added ## Maintaining this file to AGENTS.md in $DIR"
+      else
+        echo "unchanged: AGENTS.md with CLAUDE.md @AGENTS.md pointer in $DIR"
+      fi
+      exit 0
+    fi
     echo "conflict: both AGENTS.md and CLAUDE.md are real files in $DIR; reconcile them manually" >&2
     exit 1
   fi
@@ -174,7 +223,8 @@ fi
 if [ -L "$CLAUDE" ]; then
   if is_correct_claude_symlink; then
     write_skeleton
-    echo "created: AGENTS.md and kept CLAUDE.md -> AGENTS.md in $DIR"
+    install_claude_pointer
+    echo "created: AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in $DIR"
     exit 0
   fi
   echo "conflict: CLAUDE.md is a symlink in $DIR but AGENTS.md is missing and the link does not point to AGENTS.md" >&2
@@ -183,10 +233,15 @@ fi
 
 if [ -e "$CLAUDE" ]; then
   if [ -f "$CLAUDE" ]; then
+    if is_canonical_claude_pointer; then
+      write_skeleton
+      echo "created: AGENTS.md and kept CLAUDE.md @AGENTS.md pointer in $DIR"
+      exit 0
+    fi
     mv "$CLAUDE" "$AGENTS"
     ensure_maintenance_section
-    ln -s "$AGENTS" "$CLAUDE"
-    echo "promoted: moved CLAUDE.md to AGENTS.md and symlinked CLAUDE.md -> AGENTS.md in $DIR"
+    install_claude_pointer
+    echo "promoted: moved CLAUDE.md to AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in $DIR"
     exit 0
   fi
   echo "conflict: CLAUDE.md exists in $DIR but is not a regular file or symlink" >&2
@@ -194,5 +249,5 @@ if [ -e "$CLAUDE" ]; then
 fi
 
 write_skeleton
-ln -s "$AGENTS" "$CLAUDE"
-echo "created: AGENTS.md and CLAUDE.md -> AGENTS.md in $DIR"
+install_claude_pointer
+echo "created: AGENTS.md and CLAUDE.md @AGENTS.md pointer in $DIR"
diff --git a/bin/fm-ff-lib.sh b/bin/fm-ff-lib.sh
index 438f10f0b10..77d87cf6a9c 100644
--- a/bin/fm-ff-lib.sh
+++ b/bin/fm-ff-lib.sh
@@ -211,7 +211,7 @@ fetch_once() {
 
 # Which watched instruction paths changed between HEAD and BASE (comma list).
 # These are the files a running agent actually reads or runs: its instructions
-# (AGENTS.md, which CLAUDE.md symlinks), its agent-loaded skills
+# (AGENTS.md, which CLAUDE.md imports via @AGENTS.md), its agent-loaded skills
 # (.agents/skills/), and its tooling (bin/). Public skills/ is installer-facing
 # and intentionally not part of this watched instruction surface.
 changed_instr() {
diff --git a/docs/architecture.md b/docs/architecture.md
index ee6749827f2..b7356858228 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -294,10 +294,10 @@ The [Relay configuration reference](configuration.md#promised-public-replies-sta
 
 ## Project memory belongs to projects
 
-Durable project-intrinsic agent knowledge lives in each project's committed `AGENTS.md`, with `CLAUDE.md` as a symlink.
+Durable project-intrinsic agent knowledge lives in each project's committed `AGENTS.md`, with `CLAUDE.md` as a real `@AGENTS.md` import pointer.
 Ship briefs prompt crewmates to create or update those files through the normal delivery path; `data/projects.md` stays a thin private registry.
 Each project `AGENTS.md` carries a short `## Maintaining this file` self-governance section; `bin/fm-ensure-agents-md.sh` owns the canonical wording and injects it idempotently when creating the skeleton, promoting an existing `CLAUDE.md`, or reconciling an existing `AGENTS.md` that still lacks it.
-It refuses a case-variant real memory file such as a lowercase `agents.md`, whose `CLAUDE.md` symlink would carry an uppercase literal target that dangles on a case-sensitive filesystem, and surfaces the mismatch for manual reconciliation.
+It refuses a case-variant real memory file such as a lowercase `agents.md`, so the pointer's `@AGENTS.md` import resolves to a real `AGENTS.md` on a case-sensitive filesystem, and surfaces the mismatch for manual reconciliation.
 The full ownership rule - what is project-intrinsic versus fleet-private, and how firstmate keeps the two apart without writing into project clones - is owned by [`AGENTS.md`](../AGENTS.md) (project and knowledge management).
 
 ## Operational memory routing
diff --git a/docs/scripts.md b/docs/scripts.md
index 484911c380b..e94ccb0e16a 100644
--- a/docs/scripts.md
+++ b/docs/scripts.md
@@ -33,7 +33,7 @@ The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarize
 | `fm-herdr-ci-cleanup.sh` | Snapshot and tear down only job-owned `fm-lab-*` sessions in the Herdr CI lane       |
 | `fm-test-run.sh`         | Behavior-test runner: selection, portable lanes, proven-isolated `--jobs`, coverage guard, timing/JSON |
 | `fm-test-isolation-proof.sh` | Concurrent isolation proof and proven-isolated candidate set owner |
-| `fm-ensure-agents-md.sh` | Ensure a project's real `AGENTS.md`, its `CLAUDE.md` symlink, and the canonical self-governance section |
+| `fm-ensure-agents-md.sh` | Ensure a project's real `AGENTS.md`, its `CLAUDE.md` `@AGENTS.md` pointer, and the canonical self-governance section |
 | `fm-guard.sh`            | Warn on primary-checkout tangles, pending queued wakes, and unhealthy supervision    |
 | `fm-primary-scope-lib.sh` | Shared marker-or-plain-checkout primary-home predicate for tracked hooks             |
 | `fm-session-lock-lib.sh` | Shared session-lock harness identity (ancestry walk and holder liveness) for fm-lock.sh and the Claude Stop auto-arm |
diff --git a/tests/fm-ensure-agents-md.test.sh b/tests/fm-ensure-agents-md.test.sh
index 2b74b03e1e6..eec0ed2f25d 100755
--- a/tests/fm-ensure-agents-md.test.sh
+++ b/tests/fm-ensure-agents-md.test.sh
@@ -7,6 +7,25 @@ set -u
 
 TMP_ROOT=$(fm_test_tmproot fm-ensure-agents-md)
 
+# Public contract: CLAUDE.md is this exact two-line pointer, never a symlink.
+assert_claude_pointer() {
+  local path=$1
+  [ -e "$path" ] || fail "CLAUDE.md is missing"
+  [ ! -L "$path" ] || fail "CLAUDE.md is a symlink; expected a real @AGENTS.md pointer file"
+  [ -f "$path" ] || fail "CLAUDE.md is not a regular file"
+  cmp -s "$path" - <<'EOF' || fail "CLAUDE.md is not the canonical @AGENTS.md pointer"
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md
+EOF
+}
+
+write_fixture_claude_pointer() {
+  cat > "$1/CLAUDE.md" <<'EOF'
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md
+EOF
+}
+
 test_created_agents_md_includes_self_governance() {
   local repo agents
   repo="$TMP_ROOT/new-project"
@@ -14,8 +33,7 @@ test_created_agents_md_includes_self_governance() {
   "$ROOT/bin/fm-ensure-agents-md.sh" "$repo" >/dev/null 2>&1 || fail "fm-ensure-agents-md.sh failed for empty project"
   agents="$repo/AGENTS.md"
   assert_present "$agents" "AGENTS.md was not created"
-  assert_present "$repo/CLAUDE.md" "CLAUDE.md symlink was not created"
-  [ -L "$repo/CLAUDE.md" ] || fail "CLAUDE.md is not a symlink"
+  assert_claude_pointer "$repo/CLAUDE.md"
   assert_grep "## Maintaining this file" "$agents" "self-governance section heading missing"
   assert_grep "Keep this file for knowledge useful to almost every future agent session in this project." "$agents" \
     "self-governance section lost the future-session bar"
@@ -28,6 +46,18 @@ test_created_agents_md_includes_self_governance() {
   pass "fm-ensure-agents-md.sh: created AGENTS.md includes self-governance section"
 }
 
+test_fresh_setup_writes_real_claude_pointer() {
+  local repo out
+  repo="$TMP_ROOT/fresh-pointer-project"
+  mkdir -p "$repo"
+  out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1) \
+    || fail "fm-ensure-agents-md.sh failed creating a fresh pointer"
+  assert_contains "$out" "created:" "fresh setup did not report created"
+  assert_claude_pointer "$repo/CLAUDE.md"
+  [ ! -L "$repo/CLAUDE.md" ] || fail "fresh setup created a CLAUDE.md symlink"
+  pass "fm-ensure-agents-md.sh: fresh setup writes a real @AGENTS.md pointer"
+}
+
 test_promoted_claude_md_includes_self_governance() {
   local repo agents count
   repo="$TMP_ROOT/claude-project"
@@ -40,7 +70,7 @@ EOF
   "$ROOT/bin/fm-ensure-agents-md.sh" "$repo" >/dev/null 2>&1 || fail "fm-ensure-agents-md.sh failed for CLAUDE.md promotion"
   agents="$repo/AGENTS.md"
   assert_present "$agents" "AGENTS.md was not created during promotion"
-  [ -L "$repo/CLAUDE.md" ] || fail "CLAUDE.md is not a symlink after promotion"
+  assert_claude_pointer "$repo/CLAUDE.md"
   assert_grep "Run tests with \`make test\`." "$agents" \
     "promotion lost existing CLAUDE.md content"
   count=$(grep -Fc "## Maintaining this file" "$agents")
@@ -63,6 +93,7 @@ test_promoted_claude_md_without_trailing_newline_keeps_blank_separator() {
     "newline-less promotion did not append the self-governance section"
   before=$(grep -B1 -Fx '## Maintaining this file' "$agents" | head -n 1)
   [ -z "$before" ] || fail "self-governance heading not preceded by a blank line (got: $before)"
+  assert_claude_pointer "$repo/CLAUDE.md"
   pass "fm-ensure-agents-md.sh: newline-less promotion keeps a blank separator line"
 }
 
@@ -80,18 +111,49 @@ test_existing_agents_md_with_symlink_gains_self_governance() {
   assert_grep "## Maintaining this file" "$agents" "existing AGENTS.md did not gain the self-governance section"
   count=$(grep -Fc "## Maintaining this file" "$agents")
   [ "$count" -eq 1 ] || fail "injection wrote $count self-governance sections"
-  [ -L "$repo/CLAUDE.md" ] || fail "CLAUDE.md is no longer a symlink after injection"
+  assert_claude_pointer "$repo/CLAUDE.md"
   # Re-run must be a byte-exact no-op reporting unchanged.
   cp "$agents" "$repo/.after-first"
+  cp "$repo/CLAUDE.md" "$repo/.claude-after-first"
   out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1) \
     || fail "fm-ensure-agents-md.sh failed on idempotent re-run"
   assert_contains "$out" "unchanged:" "idempotent re-run did not report unchanged"
   diff "$repo/.after-first" "$agents" >/dev/null \
     || fail "idempotent re-run modified AGENTS.md"
+  cmp -s "$repo/.claude-after-first" "$repo/CLAUDE.md" \
+    || fail "idempotent re-run modified CLAUDE.md"
   pass "fm-ensure-agents-md.sh: existing symlinked AGENTS.md gains the section idempotently"
 }
 
-test_existing_agents_md_without_claude_gains_section_and_symlink() {
+test_correct_symlink_migrates_to_pointer_without_clobbering_agents() {
+  local repo agents out
+  repo="$TMP_ROOT/symlink-migrate-project"
+  mkdir -p "$repo"
+  printf '# Unique agent memory\n\nDo not clobber this payload.\n\n## Maintaining this file\n\nKeep this file for knowledge useful to almost every future agent session in this project.\nDo not repeat what the codebase already shows; point to the authoritative file or command instead.\nPrefer rewriting or pruning existing entries over appending new ones.\nWhen updating this file, preserve this bar for all agents and keep entries concise.\n' > "$repo/AGENTS.md"
+  ln -s AGENTS.md "$repo/CLAUDE.md"
+  agents="$repo/AGENTS.md"
+  cp "$agents" "$repo/.before"
+  out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1) \
+    || fail "fm-ensure-agents-md.sh failed migrating a correct CLAUDE.md symlink"
+  assert_contains "$out" "updated:" "symlink migration did not report an update"
+  assert_claude_pointer "$repo/CLAUDE.md"
+  cmp -s "$repo/.before" "$agents" \
+    || fail "symlink migration clobbered AGENTS.md"
+  assert_grep "Do not clobber this payload." "$agents" \
+    "symlink migration lost unique AGENTS.md content"
+  cp "$agents" "$repo/.after-first"
+  cp "$repo/CLAUDE.md" "$repo/.claude-after-first"
+  out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1) \
+    || fail "fm-ensure-agents-md.sh failed on post-migration re-run"
+  assert_contains "$out" "unchanged:" "post-migration re-run did not report unchanged"
+  cmp -s "$repo/.after-first" "$agents" \
+    || fail "post-migration re-run modified AGENTS.md"
+  cmp -s "$repo/.claude-after-first" "$repo/CLAUDE.md" \
+    || fail "post-migration re-run modified CLAUDE.md"
+  pass "fm-ensure-agents-md.sh: correct symlink migrates to pointer without clobbering AGENTS.md"
+}
+
+test_existing_agents_md_without_claude_gains_section_and_pointer() {
   local repo agents out count
   repo="$TMP_ROOT/existing-bare-project"
   mkdir -p "$repo"
@@ -100,27 +162,31 @@ test_existing_agents_md_without_claude_gains_section_and_symlink() {
   out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1) \
     || fail "fm-ensure-agents-md.sh failed for existing AGENTS.md without CLAUDE.md"
   assert_contains "$out" "updated:" "injection without CLAUDE.md did not report an update"
-  [ -L "$repo/CLAUDE.md" ] || fail "CLAUDE.md symlink was not created"
+  assert_claude_pointer "$repo/CLAUDE.md"
   assert_grep "Deploy with kubectl." "$agents" "injection dropped existing AGENTS.md content"
   count=$(grep -Fc "## Maintaining this file" "$agents")
   [ "$count" -eq 1 ] || fail "injection wrote $count self-governance sections"
-  pass "fm-ensure-agents-md.sh: existing AGENTS.md without CLAUDE.md gains section and symlink"
+  pass "fm-ensure-agents-md.sh: existing AGENTS.md without CLAUDE.md gains section and pointer"
 }
 
 test_existing_agents_md_with_section_reports_unchanged() {
   local repo agents out
   repo="$TMP_ROOT/fully-formed-project"
   mkdir -p "$repo"
-  # Build a fully-formed project (AGENTS.md with the section + correct symlink).
+  # Build a fully-formed project (AGENTS.md with the section + canonical pointer).
   "$ROOT/bin/fm-ensure-agents-md.sh" "$repo" >/dev/null 2>&1 \
     || fail "fm-ensure-agents-md.sh failed building the fully-formed fixture"
   agents="$repo/AGENTS.md"
+  assert_claude_pointer "$repo/CLAUDE.md"
   cp "$agents" "$repo/.before"
+  cp "$repo/CLAUDE.md" "$repo/.claude-before"
   out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1) \
     || fail "fm-ensure-agents-md.sh failed on already-formed project"
   assert_contains "$out" "unchanged:" "already-formed project was not reported unchanged"
   diff "$repo/.before" "$agents" >/dev/null \
     || fail "already-formed AGENTS.md was modified"
+  cmp -s "$repo/.claude-before" "$repo/CLAUDE.md" \
+    || fail "already-formed CLAUDE.md was modified"
   pass "fm-ensure-agents-md.sh: AGENTS.md that already has the section stays unchanged"
 }
 
@@ -137,14 +203,17 @@ test_existing_crlf_agents_md_with_section_stays_unchanged() {
     'Do not repeat what the codebase already shows; point to the authoritative file or command instead.' \
     'Prefer rewriting or pruning existing entries over appending new ones.' \
     'When updating this file, preserve this bar for all agents and keep entries concise.' > "$repo/AGENTS.md"
-  ln -s AGENTS.md "$repo/CLAUDE.md"
+  write_fixture_claude_pointer "$repo"
   agents="$repo/AGENTS.md"
   cp "$agents" "$repo/.before"
+  cp "$repo/CLAUDE.md" "$repo/.claude-before"
   out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1) \
     || fail "fm-ensure-agents-md.sh failed on CRLF AGENTS.md with the section"
   assert_contains "$out" "unchanged:" "complete CRLF AGENTS.md was not reported unchanged"
   cmp -s "$repo/.before" "$agents" \
     || fail "complete CRLF AGENTS.md was modified"
+  cmp -s "$repo/.claude-before" "$repo/CLAUDE.md" \
+    || fail "complete CRLF project's CLAUDE.md was modified"
   count=$(LC_ALL=C grep -a -c '## Maintaining this file' "$agents")
   [ "$count" -eq 1 ] || fail "complete CRLF AGENTS.md has $count self-governance sections"
   pass "fm-ensure-agents-md.sh: CRLF AGENTS.md with the section stays unchanged"
@@ -176,15 +245,99 @@ test_existing_crlf_agents_md_without_section_preserves_crlf() {
     'When updating this file, preserve this bar for all agents and keep entries concise.' > "$repo/.expected"
   cmp -s "$repo/.expected" "$agents" \
     || fail "CRLF AGENTS.md injection did not preserve CRLF line endings"
+  assert_claude_pointer "$repo/CLAUDE.md"
   cp "$agents" "$repo/.after-first"
+  cp "$repo/CLAUDE.md" "$repo/.claude-after-first"
   "$ROOT/bin/fm-ensure-agents-md.sh" "$repo" >/dev/null 2>&1 \
     || fail "fm-ensure-agents-md.sh failed on idempotent CRLF re-run"
   cmp -s "$repo/.after-first" "$agents" \
     || fail "idempotent CRLF re-run modified AGENTS.md"
+  cmp -s "$repo/.claude-after-first" "$repo/CLAUDE.md" \
+    || fail "idempotent CRLF re-run modified CLAUDE.md"
   pass "fm-ensure-agents-md.sh: CRLF injection preserves line endings idempotently"
 }
 
-test_lowercase_agents_md_refuses_case_fragile_symlink() {
+test_canonical_pointer_is_accepted_when_both_are_real_files() {
+  local repo out
+  repo="$TMP_ROOT/both-real-pointer-project"
+  mkdir -p "$repo"
+  printf '# Existing agent memory\n\n## Maintaining this file\n\nKeep this file for knowledge useful to almost every future agent session in this project.\nDo not repeat what the codebase already shows; point to the authoritative file or command instead.\nPrefer rewriting or pruning existing entries over appending new ones.\nWhen updating this file, preserve this bar for all agents and keep entries concise.\n' > "$repo/AGENTS.md"
+  write_fixture_claude_pointer "$repo"
+  out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1) \
+    || fail "fm-ensure-agents-md.sh refused a canonical real CLAUDE.md pointer"
+  assert_contains "$out" "unchanged:" "canonical pointer plus AGENTS.md was not reported unchanged"
+  assert_claude_pointer "$repo/CLAUDE.md"
+  pass "fm-ensure-agents-md.sh: canonical real CLAUDE.md pointer is not a conflict"
+}
+
+test_distinct_real_files_are_refused() {
+  local repo out rc
+  repo="$TMP_ROOT/distinct-real-files-project"
+  mkdir -p "$repo"
+  printf '# Agents memory\n' > "$repo/AGENTS.md"
+  printf '# Claude memory\n' > "$repo/CLAUDE.md"
+  cp "$repo/AGENTS.md" "$repo/.agents-before"
+  cp "$repo/CLAUDE.md" "$repo/.claude-before"
+  out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1)
+  rc=$?
+  [ "$rc" -ne 0 ] || fail "expected a non-zero exit for distinct real AGENTS.md and CLAUDE.md"
+  assert_contains "$out" "conflict:" "distinct real files did not report a conflict"
+  cmp -s "$repo/.agents-before" "$repo/AGENTS.md" \
+    || fail "distinct-real-files refusal modified AGENTS.md"
+  cmp -s "$repo/.claude-before" "$repo/CLAUDE.md" \
+    || fail "distinct-real-files refusal modified CLAUDE.md"
+  [ ! -L "$repo/CLAUDE.md" ] || fail "distinct-real-files refusal turned CLAUDE.md into a symlink"
+  pass "fm-ensure-agents-md.sh: refuses distinct real AGENTS.md and CLAUDE.md"
+}
+
+test_agents_md_symlink_is_refused() {
+  local repo out rc
+  repo="$TMP_ROOT/agents-symlink-project"
+  mkdir -p "$repo"
+  printf '# payload\n' > "$repo/payload.md"
+  ln -s payload.md "$repo/AGENTS.md"
+  out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1)
+  rc=$?
+  [ "$rc" -ne 0 ] || fail "expected a non-zero exit when AGENTS.md is a symlink"
+  assert_contains "$out" "conflict:" "AGENTS.md symlink did not report a conflict"
+  [ -L "$repo/AGENTS.md" ] || fail "AGENTS.md symlink refusal disturbed the symlink"
+  assert_absent "$repo/CLAUDE.md" "AGENTS.md symlink refusal created CLAUDE.md"
+  pass "fm-ensure-agents-md.sh: refuses AGENTS.md when it is a symlink"
+}
+
+test_wrong_target_symlink_is_refused() {
+  local repo out rc
+  repo="$TMP_ROOT/wrong-target-project"
+  mkdir -p "$repo"
+  printf '# Agents memory\n' > "$repo/AGENTS.md"
+  printf '# other\n' > "$repo/OTHER.md"
+  ln -s OTHER.md "$repo/CLAUDE.md"
+  cp "$repo/AGENTS.md" "$repo/.agents-before"
+  out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1)
+  rc=$?
+  [ "$rc" -ne 0 ] || fail "expected a non-zero exit for a CLAUDE.md symlink that does not point to AGENTS.md"
+  assert_contains "$out" "conflict:" "wrong-target CLAUDE.md symlink did not report a conflict"
+  [ -L "$repo/CLAUDE.md" ] || fail "wrong-target refusal removed the CLAUDE.md symlink"
+  [ "$(readlink "$repo/CLAUDE.md")" = "OTHER.md" ] || fail "wrong-target refusal retargeted CLAUDE.md"
+  cmp -s "$repo/.agents-before" "$repo/AGENTS.md" \
+    || fail "wrong-target refusal modified AGENTS.md"
+  pass "fm-ensure-agents-md.sh: refuses a CLAUDE.md symlink that does not point to AGENTS.md"
+}
+
+test_non_regular_claude_md_is_refused() {
+  local repo out rc
+  repo="$TMP_ROOT/non-regular-claude-project"
+  mkdir -p "$repo" "$repo/CLAUDE.md"
+  printf '# Agents memory\n' > "$repo/AGENTS.md"
+  out=$("$ROOT/bin/fm-ensure-agents-md.sh" "$repo" 2>&1)
+  rc=$?
+  [ "$rc" -ne 0 ] || fail "expected a non-zero exit when CLAUDE.md is a directory"
+  assert_contains "$out" "conflict:" "non-regular CLAUDE.md did not report a conflict"
+  [ -d "$repo/CLAUDE.md" ] || fail "non-regular CLAUDE.md refusal disturbed the directory"
+  pass "fm-ensure-agents-md.sh: refuses a non-regular CLAUDE.md"
+}
+
+test_lowercase_agents_md_refuses_case_fragile_pointer() {
   local repo out rc
   repo="$TMP_ROOT/lowercase-project"
   mkdir -p "$repo"
@@ -194,18 +347,25 @@ test_lowercase_agents_md_refuses_case_fragile_symlink() {
   [ "$rc" -ne 0 ] || fail "expected a non-zero exit for a lowercase agents.md"
   assert_contains "$out" "conflict:" "lowercase agents.md did not report a conflict"
   assert_contains "$out" "agents.md" "conflict message did not name the offending file"
-  assert_absent "$repo/CLAUDE.md" "a case-fragile CLAUDE.md symlink was created for lowercase agents.md"
+  assert_absent "$repo/CLAUDE.md" "a case-fragile CLAUDE.md pointer was created for lowercase agents.md"
   [ ! -L "$repo/CLAUDE.md" ] || fail "a case-fragile CLAUDE.md symlink was created for lowercase agents.md"
   assert_present "$repo/agents.md" "the real lowercase agents.md was disturbed"
   pass "fm-ensure-agents-md.sh: refuses a case-variant lowercase agents.md (issue #389)"
 }
 
 test_created_agents_md_includes_self_governance
+test_fresh_setup_writes_real_claude_pointer
 test_promoted_claude_md_includes_self_governance
 test_promoted_claude_md_without_trailing_newline_keeps_blank_separator
 test_existing_agents_md_with_symlink_gains_self_governance
-test_existing_agents_md_without_claude_gains_section_and_symlink
+test_correct_symlink_migrates_to_pointer_without_clobbering_agents
+test_existing_agents_md_without_claude_gains_section_and_pointer
 test_existing_agents_md_with_section_reports_unchanged
 test_existing_crlf_agents_md_with_section_stays_unchanged
 test_existing_crlf_agents_md_without_section_preserves_crlf
-test_lowercase_agents_md_refuses_case_fragile_symlink
+test_canonical_pointer_is_accepted_when_both_are_real_files
+test_distinct_real_files_are_refused
+test_agents_md_symlink_is_refused
+test_wrong_target_symlink_is_refused
+test_non_regular_claude_md_is_refused
+test_lowercase_agents_md_refuses_case_fragile_pointer

From bdae21ed09d2cca4f57caed4bda9d30d8f9d9be8 Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Mon, 17 Aug 2026 01:13:24 -0700
Subject: [PATCH 03/12] fix(ci): keep CLAUDE.md pointer check valid (#2515)

---
 .github/workflows/ci.yml | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 681adab5ca7..90c5d6e895d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -377,10 +377,12 @@ jobs:
         run: |
           set -eu
           [ ! -L CLAUDE.md ] || { echo "::error::CLAUDE.md must be a real @AGENTS.md pointer file, not a symlink"; exit 1; }
-          cmp -s CLAUDE.md - <<'EOF' || { echo "::error::CLAUDE.md must be the canonical @AGENTS.md pointer"; exit 1; }
-<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
-@AGENTS.md
-EOF
+          tmp=$(mktemp)
+          trap 'rm -f "$tmp"' EXIT
+          printf '%s\n' \
+            '<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->' \
+            '@AGENTS.md' >"$tmp"
+          cmp -s CLAUDE.md "$tmp" || { echo "::error::CLAUDE.md must be the canonical @AGENTS.md pointer"; exit 1; }
           [ "$(readlink .claude/skills)" = "../.agents/skills" ] || { echo "::error::.claude/skills must be a symlink to ../.agents/skills"; exit 1; }
       - name: Personal fleet paths must not be tracked
         run: |

From 0ae14afc17d12a4301a8171c71fc98031dd6c913 Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Mon, 17 Aug 2026 13:34:17 -0700
Subject: [PATCH 04/12] ci: gate GitHub workflows with pinned actionlint
 (#2517)

* fix(lint): catch malformed GitHub workflows before merge

A self-broken ci.yml cannot report its own breakage, so parse every
workflow in the local lint path that no-mistakes already runs.

* fix(lint): pin actionlint instead of Ruby for workflow lint

A self-broken ci.yml still has to fail in the local lint path, and the
named tool for that gate is actionlint, not a new Ruby runtime.

* no-mistakes(document): Clarify pinned workflow lint documentation
---
 .../firstmate-coding-guidelines/SKILL.md      |   3 +-
 .github/workflows/ci.yml                      |  28 +-
 .no-mistakes.yaml                             |   5 +-
 CONTRIBUTING.md                               |   8 +-
 bin/fm-install-actionlint.sh                  |  36 +++
 bin/fm-lint-workflows.sh                      | 137 ++++++++
 bin/fm-lint.sh                                |  32 +-
 bin/fm-test-run.sh                            |   4 +-
 tests/fm-lint-workflows.test.sh               | 298 ++++++++++++++++++
 tests/fm-lint.test.sh                         |   2 +
 10 files changed, 537 insertions(+), 16 deletions(-)
 create mode 100755 bin/fm-install-actionlint.sh
 create mode 100755 bin/fm-lint-workflows.sh
 create mode 100755 tests/fm-lint-workflows.test.sh

diff --git a/.agents/skills/firstmate-coding-guidelines/SKILL.md b/.agents/skills/firstmate-coding-guidelines/SKILL.md
index 2d434932997..a9e21543077 100644
--- a/.agents/skills/firstmate-coding-guidelines/SKILL.md
+++ b/.agents/skills/firstmate-coding-guidelines/SKILL.md
@@ -118,7 +118,8 @@ Run `bin/fm-doc-audience-check.sh`; it enforces classification, README setup rou
 - Plain dash `-`, never an em dash.
 - Never add an agent name as a commit co-author.
 - `bin/*.sh` and `bin/backends/*.sh` must pass `shellcheck`.
-- Run `bin/fm-lint.sh` before treating a script change as done; it is the single owner of the lint definition (file set, config, and pinned shellcheck version) that CI and the no-mistakes pre-push gate both invoke, and it refuses to run under any other shellcheck version.
+- Run `bin/fm-lint.sh` before treating a script change as done; it is the single owner of the lint definition (file set, config, pinned shellcheck version, and pinned actionlint workflow lint) that CI and the no-mistakes pre-push gate both invoke, and it refuses to run under any other version of either linter.
+- When a task names a specific tool, implement the work with that tool, or explicitly flag the substitution and its new dependency footprint for review before shipping.
 - Colocate tests with the existing pattern in `tests/`, name them `<subject>.test.sh`, and extend an existing script rather than inventing a new runner.
 - Tests must exercise behavior through an executable or public interface and must never assert implementation-source bytes, including through parsers, regexes, snapshots, or indirect wrappers.
 - A maintainer-verification record under `docs/verification/` records active empirical facts, not assumptions or task chronology.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 90c5d6e895d..fcfc4cb2dfc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -11,7 +11,7 @@ permissions:
 
 jobs:
   lint:
-    name: Lint shell scripts
+    name: Lint
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -20,8 +20,15 @@ jobs:
           set -eu
           bin/fm-install-shellcheck.sh "$RUNNER_TEMP/bin"
           echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
-      # Single owner of the lint definition (file set + config + version). Do not
-      # re-spell the shellcheck command here; keep CI and the pre-push gate on it.
+      - name: Install pinned actionlint
+        run: |
+          set -eu
+          bin/fm-install-actionlint.sh "$RUNNER_TEMP/bin"
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+      # Single owner of the lint definition (shell file set, config, version,
+      # and GitHub workflow lint). Do not re-spell the checks here; keep CI
+      # and the pre-push gate on this script so a self-broken ci.yml still
+      # fails locally before merge.
       - run: bin/fm-lint.sh
 
   # Deterministic proof that portable parallel shards + portable serial + Herdr
@@ -52,6 +59,11 @@ jobs:
           set -eu
           bin/fm-install-shellcheck.sh "$RUNNER_TEMP/bin"
           echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+      - name: Install pinned actionlint
+        run: |
+          set -eu
+          bin/fm-install-actionlint.sh "$RUNNER_TEMP/bin"
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
       - name: Install tasks-axi
         run: |
           set -eu
@@ -84,6 +96,11 @@ jobs:
           set -eu
           bin/fm-install-shellcheck.sh "$RUNNER_TEMP/bin"
           echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+      - name: Install pinned actionlint
+        run: |
+          set -eu
+          bin/fm-install-actionlint.sh "$RUNNER_TEMP/bin"
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
       - name: Install tasks-axi
         run: |
           set -eu
@@ -130,6 +147,11 @@ jobs:
           set -eu
           bin/fm-install-shellcheck.sh "$RUNNER_TEMP/bin"
           echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+      - name: Install pinned actionlint
+        run: |
+          set -eu
+          bin/fm-install-actionlint.sh "$RUNNER_TEMP/bin"
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
       - name: Require tmux for e2e tests
         run: |
           set -eu
diff --git a/.no-mistakes.yaml b/.no-mistakes.yaml
index 62bb9e72849..219c39b794f 100644
--- a/.no-mistakes.yaml
+++ b/.no-mistakes.yaml
@@ -24,9 +24,10 @@ document:
 
 # Pin lint to the same owner CI runs instead of leaving it to no-mistakes'
 # default handling, which does not invoke the repository's canonical lint gate.
-# `bin/fm-lint.sh` owns the complete lint definition and
+# `bin/fm-lint.sh` owns the complete lint definition, including GitHub workflow
+# lint via pinned actionlint in `bin/fm-lint-workflows.sh`, and
 # `.github/workflows/ci.yml` invokes it directly, with parity asserted by
-# `tests/fm-lint.test.sh`.
+# `tests/fm-lint.test.sh` and `tests/fm-lint-workflows.test.sh`.
 #
 # Do not set commands.test to a complete tests/*.test.sh walk. Local no-mistakes
 # Test is intent-targeted validation of whether the change meets its brief;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65305797be8..c9431bc59ec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -45,8 +45,10 @@ See the [no-mistakes quick start](https://kunchenguid.github.io/no-mistakes/star
 - Helper scripts in `bin/` are plain bash.
   Each starts with a usage header comment; keep it accurate when you change behavior.
   Test scripts and helpers in `tests/` are plain bash too.
-  `bin/fm-lint.sh` must pass: it is the single owner of the lint definition (the shellcheck file set, config, and pinned shellcheck version), and both CI and the no-mistakes pre-push gate run it, so local and CI can never diverge.
-  It pins one exact shellcheck version and refuses to run under any other; print it with `bin/fm-lint.sh --required-version` and install that build locally.
+  `bin/fm-lint.sh` must pass: it is the single owner of the lint definition (the shellcheck file set, config, pinned shellcheck version, and pinned actionlint workflow lint), and both CI and the no-mistakes pre-push gate run it, so local and CI can never diverge.
+  A malformed `.github/workflows/*.yml`, including a self-broken `ci.yml`, fails that local lint path before merge because a broken workflow cannot report its own breakage.
+  It pins one exact shellcheck version and one exact actionlint version and refuses to run under any other.
+  Print the shellcheck pin with `bin/fm-lint.sh --required-version` and the actionlint pin with `bin/fm-lint-workflows.sh --required-version`, then install those builds locally.
 - Harness-adapter ownership spans detection in `bin/fm-harness.sh`, launch and hook mechanics in `bin/fm-spawn.sh`, semantic busy sources and trust gates in `bin/fm-busy-lib.sh`, delivery-only rendered guards in `bin/fm-composer-lib.sh`, cleanup in `bin/fm-teardown.sh`, and facts in `.agents/skills/harness-adapters/SKILL.md`; the `firstmate-coding-guidelines` skill owns the validation policy for checks that depend on those harnesses.
 - Changes to runtime session backends (`bin/fm-backend.sh`, `bin/backends/`, and the scripts that dispatch through them) keep current setup and limits in the relevant backend guide and active empirical evidence in [`docs/verification/runtime-backends.md`](docs/verification/runtime-backends.md).
 - [`docs/documentation-audiences.md`](docs/documentation-audiences.md) and its machine-consumed inventory own prose classification; run `bin/fm-doc-audience-check.sh` after documentation changes.
@@ -72,7 +74,7 @@ Check and test the toolbelt before pushing:
 
 ```sh
 while IFS= read -r script; do /bin/bash -n "$script" || exit; done < <(bin/fm-lint.sh --list-files)   # syntax-check the shell surface fm-lint.sh will cover (changed files locally, full set in CI/on main)
-bin/fm-lint.sh   # lint that same surface; the single owner CI and the no-mistakes gate both run, full set in CI
+bin/fm-lint.sh   # lint that shell surface plus GitHub workflows via pinned actionlint; the single owner CI and the no-mistakes gate both run
 bin/fm-test-run.sh tests/<subject>.test.sh   # one script (primary local focus path, timed)
 bin/fm-test-run.sh --family pure-contract-unit   # ordinary family-scoped local path (serial, timed)
 bin/fm-test-run.sh --changed   # conservative changed-file-informed set (never silent full suite)
diff --git a/bin/fm-install-actionlint.sh b/bin/fm-install-actionlint.sh
new file mode 100755
index 00000000000..d313d506392
--- /dev/null
+++ b/bin/fm-install-actionlint.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# fm-install-actionlint.sh - install CI's pinned, verified actionlint build.
+#
+# Usage:
+#   fm-install-actionlint.sh <destination-directory>
+set -eu
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VERSION="$("$ROOT/bin/fm-lint-workflows.sh" --required-version)"
+SHA256=8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
+ARCHIVE="actionlint_${VERSION}_linux_amd64.tar.gz"
+URL="https://github.com/rhysd/actionlint/releases/download/v${VERSION}/${ARCHIVE}"
+DESTINATION=${1:?usage: fm-install-actionlint.sh <destination-directory>}
+TMP=$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/fm-actionlint.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT
+
+DOWNLOAD_ATTEMPTS=6
+download_attempt=1
+while ! curl -fsSL "$URL" -o "$TMP/$ARCHIVE"; do
+  [ "$download_attempt" -lt "$DOWNLOAD_ATTEMPTS" ] || {
+    printf 'fm-install-actionlint.sh: download failed after %s attempts\n' "$DOWNLOAD_ATTEMPTS" >&2
+    exit 1
+  }
+  printf 'fm-install-actionlint.sh: download attempt %s failed; retrying\n' "$download_attempt" >&2
+  sleep $((1 << (download_attempt - 1)))
+  download_attempt=$((download_attempt + 1))
+done
+ACTUAL_SHA256=$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')
+[ "$ACTUAL_SHA256" = "$SHA256" ] || {
+  printf 'fm-install-actionlint.sh: checksum mismatch for %s\n' "$ARCHIVE" >&2
+  exit 1
+}
+tar -xzf "$TMP/$ARCHIVE" -C "$TMP"
+mkdir -p "$DESTINATION"
+install -m 0755 "$TMP/actionlint" "$DESTINATION/actionlint"
+"$DESTINATION/actionlint" -version
diff --git a/bin/fm-lint-workflows.sh b/bin/fm-lint-workflows.sh
new file mode 100755
index 00000000000..0e2d7b07e19
--- /dev/null
+++ b/bin/fm-lint-workflows.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# fm-lint-workflows.sh - owner of firstmate's GitHub workflow lint.
+#
+# Runs pinned actionlint on every .github/workflows/*.{yml,yaml} so a malformed
+# workflow, including a self-broken ci.yml, fails in the local and no-mistakes
+# lint lane before merge. A broken ci.yml cannot report its own breakage, so
+# this check must not live only as a step inside that workflow. bin/fm-lint.sh
+# invokes this owner on its default (no explicit-path) path, which CI and
+# commands.lint both use.
+#
+# Usage:
+#   fm-lint-workflows.sh                 lint workflows under this repo
+#   fm-lint-workflows.sh --root <dir>    lint workflows under <dir>
+#   fm-lint-workflows.sh <path>...       lint explicit workflow files
+#   fm-lint-workflows.sh --required-version
+#   fm-lint-workflows.sh --help
+set -eu
+
+REQUIRED_ACTIONLINT=1.7.12
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SELF="$SELF_DIR/fm-lint-workflows.sh"
+ROOT="$(cd "$SELF_DIR/.." && pwd)"
+
+if [ "${1:-}" = "--required-version" ]; then
+  printf '%s\n' "$REQUIRED_ACTIONLINT"
+  exit 0
+fi
+
+fm_lint_workflows_usage() {
+  sed -n '2,16{s/^# \{0,1\}//;p;}' "$SELF"
+}
+
+EXPLICIT_ROOT=
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --root)
+      [ "$#" -ge 2 ] || {
+        printf 'fm-lint-workflows.sh: --root requires a directory.\n' >&2
+        exit 2
+      }
+      EXPLICIT_ROOT=$2
+      shift 2
+      ;;
+    --root=*)
+      EXPLICIT_ROOT=${1#*=}
+      shift
+      ;;
+    --help|-h)
+      fm_lint_workflows_usage
+      exit 0
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      printf 'fm-lint-workflows.sh: unknown option: %s\n' "$1" >&2
+      exit 2
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+if [ -n "$EXPLICIT_ROOT" ]; then
+  [ -d "$EXPLICIT_ROOT" ] || {
+    printf 'fm-lint-workflows.sh: --root is not a directory: %s\n' "$EXPLICIT_ROOT" >&2
+    exit 2
+  }
+  ROOT="$(cd "$EXPLICIT_ROOT" && pwd)"
+fi
+
+collect_workflow_files() {
+  local dir=$1
+  [ -d "$dir" ] || return 0
+  find "$dir" -maxdepth 1 \( -name '*.yml' -o -name '*.yaml' \) -type f \
+    | LC_ALL=C sort
+}
+
+FILES=()
+if [ "$#" -gt 0 ]; then
+  for path in "$@"; do
+    case "$path" in
+      *.yml|*.yaml) ;;
+      *)
+        printf 'fm-lint-workflows.sh: not a workflow YAML file: %s\n' "$path" >&2
+        exit 2
+        ;;
+    esac
+    [ -f "$path" ] || {
+      printf 'fm-lint-workflows.sh: workflow file not found: %s\n' "$path" >&2
+      exit 2
+    }
+    FILES+=("$path")
+  done
+else
+  workflow_dir="$ROOT/.github/workflows"
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    FILES+=("$path")
+  done < <(collect_workflow_files "$workflow_dir")
+  if [ "${#FILES[@]}" -eq 0 ]; then
+    printf 'fm-lint-workflows.sh: no GitHub workflow files found under %s\n' \
+      "$workflow_dir" >&2
+    exit 1
+  fi
+fi
+
+if ! command -v actionlint >/dev/null 2>&1; then
+  printf 'fm-lint-workflows.sh: actionlint not found; install actionlint %s for CI parity.\n' \
+    "$REQUIRED_ACTIONLINT" >&2
+  exit 127
+fi
+ACTIONLINT_BIN=$(command -v actionlint)
+resolved=$("$ACTIONLINT_BIN" -version | awk 'NR==1 {print; exit}')
+printf 'fm-lint-workflows.sh: actionlint %s (pinned %s)\n' "$resolved" "$REQUIRED_ACTIONLINT" >&2
+if [ "$resolved" != "$REQUIRED_ACTIONLINT" ]; then
+  printf 'fm-lint-workflows.sh: actionlint %s required for CI parity, found %s. Install %s.\n' \
+    "$REQUIRED_ACTIONLINT" "$resolved" "$REQUIRED_ACTIONLINT" >&2
+  exit 1
+fi
+
+# fm-lint.sh owns ShellCheck of the canonical shell set. Disable actionlint's
+# extra shell and Python subprocess linters so this gate is the named workflow
+# linter, not a second shell lint of `run:` blocks.
+set +e
+"$ACTIONLINT_BIN" -no-color -shellcheck= -pyflakes= -- "${FILES[@]}"
+rc=$?
+set -e
+
+if [ "$rc" -ne 0 ]; then
+  exit "$rc"
+fi
+
+printf 'fm-lint-workflows.sh: %s workflow files valid\n' "${#FILES[@]}"
+exit 0
diff --git a/bin/fm-lint.sh b/bin/fm-lint.sh
index 5c3bebcb21b..d848a2ac83f 100755
--- a/bin/fm-lint.sh
+++ b/bin/fm-lint.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# fm-lint.sh - the single owner of firstmate's shell-lint definition.
+# fm-lint.sh - the single owner of firstmate's lint definition.
 #
 # Runs its file set with ShellCheck's default severity, extended analysis,
 # ambient configuration disabled, and one exact ShellCheck version. CI and
@@ -7,6 +7,9 @@
 # version, bounded execution, and diagnostics ordering cannot drift.
 # Tests stop source analysis at imported production modules because every
 # production shell is already a canonical, source-aware root of this same run.
+# The default (no explicit-path) path also runs bin/fm-lint-workflows.sh so a
+# malformed GitHub workflow, including a self-broken ci.yml, fails locally
+# before merge instead of only failing to run as CI.
 #
 # With no explicit paths, the file set depends on context:
 #   - In CI (GITHUB_ACTIONS=true or CI=true), on the main branch, or when no
@@ -16,10 +19,10 @@
 #   - Otherwise (an ordinary local branch with a real merge-base) it lints
 #     only the canonical-set files changed since that merge-base, including
 #     uncommitted local edits, via plain local `git diff` (no network, no
-#     `gh`). A branch with zero matching changed files exits 0 and prints a
-#     "no changed lint targets" note instead of running ShellCheck.
+#     `gh`). A branch with zero matching changed files skips ShellCheck and
+#     prints a "no changed lint targets" note, then still validates workflows.
 # Explicit paths always bypass this file-set selection and lint exactly the
-# given paths, matching the same config.
+# given paths, matching the same config, without the workflow YAML check.
 #
 # Canonical lint defaults to two bounded workers over two stable logical shards.
 # Each shard writes separate diagnostics, and the parent replays those outputs in
@@ -97,7 +100,14 @@ if [ "${1:-}" = "--required-version" ]; then
 fi
 
 fm_lint_usage() {
-  sed -n '2,39{s/^# \{0,1\}//;p;}' "$SELF"
+  sed -n '2,42{s/^# \{0,1\}//;p;}' "$SELF"
+}
+
+# Default no-args lint also validates GitHub workflows. Explicit paths stay a
+# ShellCheck-only override so callers can target one shell root.
+fm_lint_run_workflows() {
+  [ "$EXPLICIT_PATHS" -eq 0 ] || return 0
+  "$SELF_DIR/fm-lint-workflows.sh"
 }
 
 JOBS=${FM_LINT_JOBS:-2}
@@ -180,7 +190,9 @@ fm_lint_is_canonical_root() {
 }
 
 CHANGED_MODE=0
+EXPLICIT_PATHS=0
 if [ "$#" -gt 0 ]; then
+  EXPLICIT_PATHS=1
   ROOTS=("$@")
 else
   full_lint=1
@@ -238,7 +250,9 @@ fi
 
 if [ "$CHANGED_MODE" -eq 1 ] && [ "$ROOT_COUNT" -eq 0 ]; then
   printf 'fm-lint.sh: no changed lint targets\n'
-  exit 0
+  overall_rc=0
+  fm_lint_run_workflows || overall_rc=$?
+  exit "$overall_rc"
 fi
 
 if [ -n "$TELEMETRY" ]; then
@@ -538,4 +552,10 @@ EOF
   fi
 fi
 
+if [ "$overall_rc" -eq 0 ]; then
+  fm_lint_run_workflows || overall_rc=$?
+else
+  fm_lint_run_workflows || true
+fi
+
 exit "$overall_rc"
diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh
index 4ca26c865e6..24ced990888 100755
--- a/bin/fm-test-run.sh
+++ b/bin/fm-test-run.sh
@@ -140,6 +140,7 @@ family_for_basename() {
     fm-crew-state.test.sh|fm-decision-hold-lifecycle.test.sh|\
     fm-documentation-audiences.test.sh|fm-ensure-agents-md.test.sh|fm-grok-harness.test.sh|\
     fm-kimi-harness.test.sh|fm-muse-harness.test.sh|fm-herdr-lab.test.sh|fm-lint.test.sh|\
+    fm-lint-workflows.test.sh|\
     fm-operational-input.test.sh|fm-pi-primary-types.test.sh|\
     fm-send-popup-settle.test.sh|fm-send-settle.test.sh|\
     fm-subagent-pretool-check.test.sh|\
@@ -960,7 +961,8 @@ families_for_changed_path() {
       # lane's contract coverage re-runs.
       printf '%s\n' real-herdr-gated
       ;;
-    bin/fm-lint.sh|bin/fm-install-shellcheck.sh|\
+    bin/fm-lint.sh|bin/fm-lint-workflows.sh|bin/fm-install-shellcheck.sh|\
+    bin/fm-install-actionlint.sh|\
     bin/fm-brief.sh|bin/fm-ensure-agents-md.sh|bin/fm-crew-state.sh|\
     bin/fm-decision-hold.sh|bin/fm-supervision*|bin/fm-transition-lib.sh|\
     bin/fm-tmux-lib.sh|bin/fm-marker-lib.sh|bin/fm-operational-input.sh|bin/fm-tasks-axi-lib.sh|\
diff --git a/tests/fm-lint-workflows.test.sh b/tests/fm-lint-workflows.test.sh
new file mode 100755
index 00000000000..c7e918d6786
--- /dev/null
+++ b/tests/fm-lint-workflows.test.sh
@@ -0,0 +1,298 @@
+#!/usr/bin/env bash
+# GitHub workflow lint gate owned by bin/fm-lint-workflows.sh.
+#
+# A malformed .github/workflows/*.yml, including a self-broken ci.yml, must fail
+# in the local/no-mistakes lint path before merge. Regression origin: #2512 put
+# a column-0 heredoc body inside a `run: |` block in ci.yml; there was no
+# workflow YAML lint, and the broken workflow could not report its own breakage.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+LINT_WF="$ROOT/bin/fm-lint-workflows.sh"
+LINT="$ROOT/bin/fm-lint.sh"
+INSTALLER="$ROOT/bin/fm-install-actionlint.sh"
+REQUIRED=$("$LINT_WF" --required-version)
+
+write_valid_workflow() {
+  local path=$1
+  cat > "$path" <<'YAML'
+name: CI
+on: push
+jobs:
+  x:
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          set -eu
+          echo ok
+YAML
+}
+
+# #2512-class breakage: a heredoc body at column 0 inside a `run: |` block.
+write_col0_heredoc_workflow() {
+  local path=$1
+  cat > "$path" <<'YAML'
+name: CI
+on: push
+jobs:
+  x:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Compatibility pointers must stay intact
+        run: |
+          set -eu
+          cmp -s CLAUDE.md - <<'EOF' || exit 1
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md
+EOF
+          echo ok
+YAML
+}
+
+test_current_workflows_pass() {
+  local out rc
+  rc=0
+  out=$("$LINT_WF" 2>&1) || rc=$?
+  [ "$rc" -eq 0 ] || fail "current workflows must parse, got $rc"$'\n'"$out"
+  assert_contains "$out" "workflow files valid" \
+    "current-workflow lint did not report a valid count"
+  pass "current .github/workflows YAML files parse"
+}
+
+test_col0_heredoc_fails_with_clear_error() {
+  local tmp out rc
+  tmp=$(fm_test_tmproot fm-lint-wf-col0)
+  mkdir -p "$tmp/.github/workflows"
+  write_col0_heredoc_workflow "$tmp/.github/workflows/ci.yml"
+  rc=0
+  out=$("$LINT_WF" --root "$tmp" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "column-0 heredoc workflow unexpectedly passed"$'\n'"$out"
+  assert_contains "$out" "could not parse as YAML" \
+    "column-0 heredoc failure did not report actionlint's YAML syntax error"
+  assert_contains "$out" "ci.yml" \
+    "column-0 heredoc failure did not name the workflow file"
+  pass "column-0 heredoc workflow fails validation with a clear error"
+}
+
+test_valid_fixture_passes() {
+  local tmp out rc
+  tmp=$(fm_test_tmproot fm-lint-wf-ok)
+  mkdir -p "$tmp/.github/workflows"
+  write_valid_workflow "$tmp/.github/workflows/ci.yml"
+  rc=0
+  out=$("$LINT_WF" --root "$tmp" 2>&1) || rc=$?
+  [ "$rc" -eq 0 ] || fail "valid fixture workflow failed"$'\n'"$out"
+  assert_contains "$out" "1 workflow files valid" \
+    "valid fixture did not report one valid file"
+  pass "valid fixture workflow passes"
+}
+
+test_empty_workflows_dir_fails() {
+  local tmp out rc
+  tmp=$(fm_test_tmproot fm-lint-wf-empty)
+  mkdir -p "$tmp/.github/workflows"
+  rc=0
+  out=$("$LINT_WF" --root "$tmp" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "empty workflows dir unexpectedly passed"$'\n'"$out"
+  assert_contains "$out" "no GitHub workflow files found" \
+    "empty workflows dir did not report the missing files"
+  pass "empty workflows directory fails closed"
+}
+
+test_explicit_broken_path_fails() {
+  local tmp broken out rc
+  tmp=$(fm_test_tmproot fm-lint-wf-path)
+  broken="$tmp/broken.yml"
+  write_col0_heredoc_workflow "$broken"
+  rc=0
+  out=$("$LINT_WF" "$broken" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "explicit broken path unexpectedly passed"$'\n'"$out"
+  assert_contains "$out" "could not parse as YAML" \
+    "explicit broken path did not report actionlint's YAML syntax error"
+  pass "explicit malformed workflow path fails validation"
+}
+
+test_non_mapping_root_fails() {
+  local tmp out rc
+  tmp=$(fm_test_tmproot fm-lint-wf-scalar)
+  mkdir -p "$tmp/.github/workflows"
+  printf 'just-a-string\n' > "$tmp/.github/workflows/ci.yml"
+  rc=0
+  out=$("$LINT_WF" --root "$tmp" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "scalar YAML root unexpectedly passed"$'\n'"$out"
+  assert_contains "$out" "mapping node is expected" \
+    "scalar YAML root did not report actionlint's mapping-node error"
+  pass "non-mapping workflow YAML root fails"
+}
+
+test_missing_actionlint_fails_closed() {
+  local tmp fakebin out rc tool
+  tmp=$(fm_test_tmproot fm-lint-wf-noactionlint)
+  fakebin=$(fm_fakebin "$tmp")
+  mkdir -p "$tmp/.github/workflows"
+  write_valid_workflow "$tmp/.github/workflows/ci.yml"
+  for tool in bash dirname find sort awk; do
+    ln -s "$(command -v "$tool")" "$fakebin/$tool"
+  done
+  rc=0
+  out=$(PATH="$fakebin" "$LINT_WF" --root "$tmp" 2>&1) || rc=$?
+  [ "$rc" -eq 127 ] || fail "missing actionlint expected exit 127, got $rc"$'\n'"$out"
+  assert_contains "$out" "actionlint not found" \
+    "missing actionlint did not name the required linter"
+  assert_contains "$out" "$REQUIRED" \
+    "missing actionlint did not name the pinned version"
+  pass "missing actionlint fails closed"
+}
+
+test_pins_an_explicit_version() {
+  [ -n "$REQUIRED" ] || fail "fm-lint-workflows.sh --required-version printed nothing"
+  assert_contains "$REQUIRED" "1.7.12" "fm-lint-workflows.sh must pin actionlint 1.7.12"
+  pass "fm-lint-workflows.sh pins an explicit actionlint version ($REQUIRED)"
+}
+
+test_rejects_wrong_actionlint_version() {
+  local tmp fakebin out rc
+  tmp=$(fm_test_tmproot fm-lint-wf-ver)
+  fakebin=$(fm_fakebin "$tmp")
+  mkdir -p "$tmp/.github/workflows"
+  write_valid_workflow "$tmp/.github/workflows/ci.yml"
+  cat > "$fakebin/actionlint" <<'SH'
+#!/usr/bin/env bash
+if [ "$1" = "-version" ]; then
+  printf '0.0.0\n'
+  exit 0
+fi
+exit 0
+SH
+  chmod +x "$fakebin/actionlint"
+  rc=0
+  out=$(PATH="$fakebin:$PATH" "$LINT_WF" --root "$tmp" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "fm-lint-workflows.sh accepted an actionlint version other than the pin"$'\n'"$out"
+  assert_contains "$out" "$REQUIRED" "fm-lint-workflows.sh did not name the required version on mismatch"
+  assert_contains "$out" "0.0.0" "fm-lint-workflows.sh did not report the resolved (wrong) version"
+  pass "fm-lint-workflows.sh refuses to lint under a non-pinned actionlint version"
+}
+
+test_installer_retries_transient_download_failure() {
+  local tmp fakebin destination out
+  tmp=$(fm_test_tmproot fm-actionlint-download)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+
+  cat > "$fakebin/curl" <<'SH'
+#!/usr/bin/env bash
+count=0
+[ ! -f "$CURL_COUNT" ] || count=$(cat "$CURL_COUNT")
+count=$((count + 1))
+printf '%s\n' "$count" > "$CURL_COUNT"
+[ "$count" -gt 3 ] || exit 22
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "-o" ]; then
+    : > "$2"
+    exit 0
+  fi
+  shift
+done
+exit 2
+SH
+  cat > "$fakebin/sha256sum" <<'SH'
+#!/usr/bin/env bash
+printf '8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8  %s\n' "$1"
+SH
+  cat > "$fakebin/tar" <<'SH'
+#!/usr/bin/env bash
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "-C" ]; then
+    cat > "$2/actionlint" <<'EOF'
+#!/usr/bin/env bash
+printf '1.7.12\n'
+EOF
+    chmod +x "$2/actionlint"
+    exit 0
+  fi
+  shift
+done
+exit 2
+SH
+  cat > "$fakebin/sleep" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+  chmod +x "$fakebin/curl" "$fakebin/sha256sum" "$fakebin/tar" "$fakebin/sleep"
+
+  out=$(CURL_COUNT="$tmp/curl-count" PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) \
+    || fail "installer did not recover from a transient download failure"$'\n'"$out"
+  [ "$(cat "$tmp/curl-count")" -eq 4 ] || fail "installer did not recover after three failed downloads"
+  assert_contains "$out" "download attempt 3 failed; retrying" "installer did not disclose its third retry"
+  [ -x "$destination/actionlint" ] || fail "installer did not install actionlint after retrying"
+  pass "actionlint installer retries a transient download failure"
+}
+
+# Prove the no-mistakes/local owner (bin/fm-lint.sh with no paths) catches a
+# self-broken ci.yml. Copy the lint scripts into a fake repo so the default
+# workflow root is the fixture, not this worktree.
+test_fm_lint_default_path_catches_broken_ci_yml() {
+  local tmp fakebin log diff_file out rc
+  tmp=$(fm_test_tmproot fm-lint-wf-default)
+  mkdir -p "$tmp/bin" "$tmp/.github/workflows"
+  cp "$LINT" "$tmp/bin/fm-lint.sh"
+  cp "$LINT_WF" "$tmp/bin/fm-lint-workflows.sh"
+  chmod +x "$tmp/bin/fm-lint.sh" "$tmp/bin/fm-lint-workflows.sh"
+  write_col0_heredoc_workflow "$tmp/.github/workflows/ci.yml"
+
+  fakebin=$(fm_fakebin "$tmp")
+  log="$tmp/shellcheck.log"
+  cat > "$fakebin/git" <<'SH'
+#!/usr/bin/env bash
+case "$*" in
+  "rev-parse --is-inside-work-tree") printf 'true\n'; exit 0 ;;
+  "rev-parse --abbrev-ref HEAD") printf 'feature\n'; exit 0 ;;
+  "rev-parse --verify -q origin/main") exit 0 ;;
+  "merge-base "*) printf 'fakebase123\n'; exit 0 ;;
+  "diff --name-only --diff-filter=ACMR -z fakebase123 --")
+    [ -n "${FM_TEST_GIT_DIFF_FILE:-}" ] && cat "${FM_TEST_GIT_DIFF_FILE}"
+    exit 0
+    ;;
+  *) exit 0 ;;
+esac
+SH
+  chmod +x "$fakebin/git"
+  : > "$log"
+  cat > "$fakebin/shellcheck" <<SH
+#!/usr/bin/env bash
+if [ "\${1:-}" = --version ]; then
+  printf 'ShellCheck - shell script analysis tool\nversion: 0.11.0\n'
+  exit 0
+fi
+shift 3
+printf '%s\n' "\$@" >> "$log"
+exit 0
+SH
+  chmod +x "$fakebin/shellcheck"
+  diff_file="$tmp/diff.nul"
+  : > "$diff_file"
+
+  rc=0
+  out=$(PATH="$fakebin:$PATH" GITHUB_ACTIONS='' CI='' FM_LINT_JOBS=1 \
+    FM_TEST_GIT_DIFF_FILE="$diff_file" "$tmp/bin/fm-lint.sh" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "fm-lint.sh default path missed a broken ci.yml"$'\n'"$out"
+  assert_contains "$out" "could not parse as YAML" \
+    "fm-lint.sh default path did not surface the workflow YAML error"
+  assert_contains "$out" "ci.yml" \
+    "fm-lint.sh default path did not name the broken workflow"
+  pass "fm-lint.sh default path catches a self-broken ci.yml"
+}
+
+test_pins_an_explicit_version
+test_current_workflows_pass
+test_col0_heredoc_fails_with_clear_error
+test_valid_fixture_passes
+test_empty_workflows_dir_fails
+test_explicit_broken_path_fails
+test_non_mapping_root_fails
+test_missing_actionlint_fails_closed
+test_rejects_wrong_actionlint_version
+test_installer_retries_transient_download_failure
+test_fm_lint_default_path_catches_broken_ci_yml
diff --git a/tests/fm-lint.test.sh b/tests/fm-lint.test.sh
index 46e5d3178d5..99eba0f8abf 100755
--- a/tests/fm-lint.test.sh
+++ b/tests/fm-lint.test.sh
@@ -208,6 +208,8 @@ test_zero_changed_files_exits_clean() {
   [ "$rc" -eq 0 ] || fail "zero changed lint targets must exit 0, got $rc"$'\n'"$out"
   assert_contains "$out" "ShellCheck 0.11.0" "zero-changed run did not print the ShellCheck version line"
   assert_contains "$out" "no changed lint targets" "zero-changed run did not note the empty target set"
+  assert_contains "$out" "workflow files valid" \
+    "zero-changed run skipped workflow YAML validation"
   pass "fm-lint.sh exits 0 with a note when the local branch has no changed lint targets"
 }
 

From ac55d39a5bb355308f608b9ff2d033592232826c Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Mon, 17 Aug 2026 14:42:37 -0700
Subject: [PATCH 05/12] fix: install pinned lint tools across supported
 platforms (#2546)

* fix: install pinned shellcheck and actionlint on macOS and linux arm64

The installers were hardcoded to linux amd64 and sha256sum, so a Mac
dev could not satisfy the refuse-on-mismatch lint gate. Select the
official per-platform archive and checksum, and fall back to shasum -a 256.

* no-mistakes(document): Document cross-platform pinned lint installers
---
 CONTRIBUTING.md                 |   3 +-
 bin/fm-install-actionlint.sh    |  58 +++++-
 bin/fm-install-shellcheck.sh    |  58 +++++-
 tests/fm-lint-workflows.test.sh | 314 ++++++++++++++++++++++++++----
 tests/fm-lint.test.sh           | 330 +++++++++++++++++++++++++++-----
 5 files changed, 666 insertions(+), 97 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c9431bc59ec..97442a450f8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -48,7 +48,8 @@ See the [no-mistakes quick start](https://kunchenguid.github.io/no-mistakes/star
   `bin/fm-lint.sh` must pass: it is the single owner of the lint definition (the shellcheck file set, config, pinned shellcheck version, and pinned actionlint workflow lint), and both CI and the no-mistakes pre-push gate run it, so local and CI can never diverge.
   A malformed `.github/workflows/*.yml`, including a self-broken `ci.yml`, fails that local lint path before merge because a broken workflow cannot report its own breakage.
   It pins one exact shellcheck version and one exact actionlint version and refuses to run under any other.
-  Print the shellcheck pin with `bin/fm-lint.sh --required-version` and the actionlint pin with `bin/fm-lint-workflows.sh --required-version`, then install those builds locally.
+  Print the shellcheck pin with `bin/fm-lint.sh --required-version` and the actionlint pin with `bin/fm-lint-workflows.sh --required-version`.
+  Use `bin/fm-install-shellcheck.sh` and `bin/fm-install-actionlint.sh` to install those exact builds locally; each installer's header owns its destination usage and supported platforms.
 - Harness-adapter ownership spans detection in `bin/fm-harness.sh`, launch and hook mechanics in `bin/fm-spawn.sh`, semantic busy sources and trust gates in `bin/fm-busy-lib.sh`, delivery-only rendered guards in `bin/fm-composer-lib.sh`, cleanup in `bin/fm-teardown.sh`, and facts in `.agents/skills/harness-adapters/SKILL.md`; the `firstmate-coding-guidelines` skill owns the validation policy for checks that depend on those harnesses.
 - Changes to runtime session backends (`bin/fm-backend.sh`, `bin/backends/`, and the scripts that dispatch through them) keep current setup and limits in the relevant backend guide and active empirical evidence in [`docs/verification/runtime-backends.md`](docs/verification/runtime-backends.md).
 - [`docs/documentation-audiences.md`](docs/documentation-audiences.md) and its machine-consumed inventory own prose classification; run `bin/fm-doc-audience-check.sh` after documentation changes.
diff --git a/bin/fm-install-actionlint.sh b/bin/fm-install-actionlint.sh
index d313d506392..77eaf7e2695 100755
--- a/bin/fm-install-actionlint.sh
+++ b/bin/fm-install-actionlint.sh
@@ -1,16 +1,56 @@
 #!/usr/bin/env bash
 # fm-install-actionlint.sh - install CI's pinned, verified actionlint build.
 #
+# Downloads the official GitHub release archive for the host OS/arch, verifies
+# its per-archive SHA-256 pin, and installs the binary into the destination
+# directory. Supported platforms: linux amd64/x86_64, linux arm64/aarch64,
+# darwin amd64/x86_64, darwin arm64/aarch64. Pins come from the official
+# actionlint release checksums file. Verification uses sha256sum when present,
+# otherwise shasum -a 256. An unsupported OS/arch or a missing pin fails
+# without downloading.
+#
 # Usage:
 #   fm-install-actionlint.sh <destination-directory>
 set -eu
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 VERSION="$("$ROOT/bin/fm-lint-workflows.sh" --required-version)"
-SHA256=8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
-ARCHIVE="actionlint_${VERSION}_linux_amd64.tar.gz"
-URL="https://github.com/rhysd/actionlint/releases/download/v${VERSION}/${ARCHIVE}"
+
+die() {
+  printf 'fm-install-actionlint.sh: %s\n' "$*" >&2
+  exit 1
+}
+
 DESTINATION=${1:?usage: fm-install-actionlint.sh <destination-directory>}
+
+os=$(uname -s)
+arch=$(uname -m)
+# SHA-256 pins are from actionlint_1.7.12_checksums.txt on the official
+# v1.7.12 release (https://github.com/rhysd/actionlint/releases/tag/v1.7.12).
+case "${os}-${arch}" in
+  Linux-x86_64|Linux-amd64)
+    ARCHIVE="actionlint_${VERSION}_linux_amd64.tar.gz"
+    SHA256=8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
+    ;;
+  Linux-aarch64|Linux-arm64)
+    ARCHIVE="actionlint_${VERSION}_linux_arm64.tar.gz"
+    SHA256=325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6
+    ;;
+  Darwin-x86_64|Darwin-amd64)
+    ARCHIVE="actionlint_${VERSION}_darwin_amd64.tar.gz"
+    SHA256=5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644
+    ;;
+  Darwin-arm64|Darwin-aarch64)
+    ARCHIVE="actionlint_${VERSION}_darwin_arm64.tar.gz"
+    SHA256=aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f
+    ;;
+  *)
+    die "unsupported platform ${os}-${arch}; need linux or darwin on amd64/x86_64 or arm64/aarch64"
+    ;;
+esac
+[ -n "$SHA256" ] || die "no pinned checksum for ${os}-${arch}"
+
+URL="https://github.com/rhysd/actionlint/releases/download/v${VERSION}/${ARCHIVE}"
 TMP=$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/fm-actionlint.XXXXXX")
 trap 'rm -rf "$TMP"' EXIT
 
@@ -25,9 +65,17 @@ while ! curl -fsSL "$URL" -o "$TMP/$ARCHIVE"; do
   sleep $((1 << (download_attempt - 1)))
   download_attempt=$((download_attempt + 1))
 done
-ACTUAL_SHA256=$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')
+
+if command -v sha256sum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')
+elif command -v shasum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(shasum -a 256 "$TMP/$ARCHIVE" | awk '{print $1}')
+else
+  die "need sha256sum or shasum to verify the actionlint archive"
+fi
 [ "$ACTUAL_SHA256" = "$SHA256" ] || {
-  printf 'fm-install-actionlint.sh: checksum mismatch for %s\n' "$ARCHIVE" >&2
+  printf 'fm-install-actionlint.sh: checksum mismatch for %s (expected %s, got %s)\n' \
+    "$ARCHIVE" "$SHA256" "$ACTUAL_SHA256" >&2
   exit 1
 }
 tar -xzf "$TMP/$ARCHIVE" -C "$TMP"
diff --git a/bin/fm-install-shellcheck.sh b/bin/fm-install-shellcheck.sh
index b947b3faabf..694211e4d2b 100755
--- a/bin/fm-install-shellcheck.sh
+++ b/bin/fm-install-shellcheck.sh
@@ -1,16 +1,56 @@
 #!/usr/bin/env bash
 # fm-install-shellcheck.sh - install CI's pinned, verified ShellCheck build.
 #
+# Downloads the official GitHub release archive for the host OS/arch, verifies
+# its per-archive SHA-256 pin, and installs the binary into the destination
+# directory. Supported platforms: linux amd64/x86_64, linux arm64/aarch64,
+# darwin amd64/x86_64, darwin arm64/aarch64. Pins come from the official
+# ShellCheck release asset digests. Verification uses sha256sum when present,
+# otherwise shasum -a 256. An unsupported OS/arch or a missing pin fails
+# without downloading.
+#
 # Usage:
 #   fm-install-shellcheck.sh <destination-directory>
 set -eu
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 VERSION="$("$ROOT/bin/fm-lint.sh" --required-version)"
-SHA256=8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198
-ARCHIVE="shellcheck-v${VERSION}.linux.x86_64.tar.xz"
-URL="https://github.com/koalaman/shellcheck/releases/download/v${VERSION}/${ARCHIVE}"
+
+die() {
+  printf 'fm-install-shellcheck.sh: %s\n' "$*" >&2
+  exit 1
+}
+
 DESTINATION=${1:?usage: fm-install-shellcheck.sh <destination-directory>}
+
+os=$(uname -s)
+arch=$(uname -m)
+# SHA-256 pins are the GitHub release asset digests for shellcheck v0.11.0
+# .tar.xz archives (https://github.com/koalaman/shellcheck/releases/tag/v0.11.0).
+case "${os}-${arch}" in
+  Linux-x86_64|Linux-amd64)
+    ARCHIVE="shellcheck-v${VERSION}.linux.x86_64.tar.xz"
+    SHA256=8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198
+    ;;
+  Linux-aarch64|Linux-arm64)
+    ARCHIVE="shellcheck-v${VERSION}.linux.aarch64.tar.xz"
+    SHA256=12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588
+    ;;
+  Darwin-x86_64|Darwin-amd64)
+    ARCHIVE="shellcheck-v${VERSION}.darwin.x86_64.tar.xz"
+    SHA256=3c89db4edcab7cf1c27bff178882e0f6f27f7afdf54e859fa041fca10febe4c6
+    ;;
+  Darwin-arm64|Darwin-aarch64)
+    ARCHIVE="shellcheck-v${VERSION}.darwin.aarch64.tar.xz"
+    SHA256=56affdd8de5527894dca6dc3d7e0a99a873b0f004d7aabc30ae407d3f48b0a79
+    ;;
+  *)
+    die "unsupported platform ${os}-${arch}; need linux or darwin on amd64/x86_64 or arm64/aarch64"
+    ;;
+esac
+[ -n "$SHA256" ] || die "no pinned checksum for ${os}-${arch}"
+
+URL="https://github.com/koalaman/shellcheck/releases/download/v${VERSION}/${ARCHIVE}"
 TMP=$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/fm-shellcheck.XXXXXX")
 trap 'rm -rf "$TMP"' EXIT
 
@@ -25,9 +65,17 @@ while ! curl -fsSL "$URL" -o "$TMP/$ARCHIVE"; do
   sleep $((1 << (download_attempt - 1)))
   download_attempt=$((download_attempt + 1))
 done
-ACTUAL_SHA256=$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')
+
+if command -v sha256sum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')
+elif command -v shasum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(shasum -a 256 "$TMP/$ARCHIVE" | awk '{print $1}')
+else
+  die "need sha256sum or shasum to verify the ShellCheck archive"
+fi
 [ "$ACTUAL_SHA256" = "$SHA256" ] || {
-  printf 'fm-install-shellcheck.sh: checksum mismatch for %s\n' "$ARCHIVE" >&2
+  printf 'fm-install-shellcheck.sh: checksum mismatch for %s (expected %s, got %s)\n' \
+    "$ARCHIVE" "$SHA256" "$ACTUAL_SHA256" >&2
   exit 1
 }
 tar -xJf "$TMP/$ARCHIVE" -C "$TMP"
diff --git a/tests/fm-lint-workflows.test.sh b/tests/fm-lint-workflows.test.sh
index c7e918d6786..ef611fbaa8b 100755
--- a/tests/fm-lint-workflows.test.sh
+++ b/tests/fm-lint-workflows.test.sh
@@ -15,6 +15,121 @@ LINT="$ROOT/bin/fm-lint.sh"
 INSTALLER="$ROOT/bin/fm-install-actionlint.sh"
 REQUIRED=$("$LINT_WF" --required-version)
 
+# Official sha256 values from actionlint_1.7.12_checksums.txt on the v1.7.12
+# release (https://github.com/rhysd/actionlint/releases/tag/v1.7.12). Tests
+# compare installer behavior against these published digests, not script source.
+ACTIONLINT_SHA_LINUX_AMD64=8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
+ACTIONLINT_SHA_LINUX_ARM64=325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6
+ACTIONLINT_SHA_DARWIN_AMD64=5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644
+ACTIONLINT_SHA_DARWIN_ARM64=aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f
+
+fm_install_stub_uname() {
+  local fakebin=$1
+  cat > "$fakebin/uname" <<'SH'
+#!/usr/bin/env bash
+case "${1:-}" in
+  -s) printf '%s\n' "${FM_TEST_UNAME_S:-Linux}" ;;
+  -m) printf '%s\n' "${FM_TEST_UNAME_M:-x86_64}" ;;
+  *) printf '%s\n' "${FM_TEST_UNAME_S:-Linux}" ;;
+esac
+SH
+  chmod +x "$fakebin/uname"
+}
+
+fm_install_stub_curl() {
+  local fakebin=$1
+  cat > "$fakebin/curl" <<'SH'
+#!/usr/bin/env bash
+count=0
+[ ! -f "${CURL_COUNT:-}" ] || count=$(cat "$CURL_COUNT")
+count=$((count + 1))
+[ -z "${CURL_COUNT:-}" ] || printf '%s\n' "$count" > "$CURL_COUNT"
+url=
+out=
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    -o)
+      out=$2
+      shift 2
+      ;;
+    -*)
+      shift
+      ;;
+    *)
+      url=$1
+      shift
+      ;;
+  esac
+done
+[ -z "${CURL_URL_LOG:-}" ] || printf '%s\n' "$url" >> "$CURL_URL_LOG"
+fail_until=${CURL_FAIL_UNTIL:-0}
+[ "$count" -gt "$fail_until" ] || exit 22
+: > "$out"
+exit 0
+SH
+  chmod +x "$fakebin/curl"
+}
+
+fm_install_stub_hasher() {
+  local fakebin=$1 name=$2
+  cat > "$fakebin/$name" <<'SH'
+#!/usr/bin/env bash
+self=${0##*/}
+if [ -n "${HASHER_LOG:-}" ]; then
+  printf '%s\n' "$self $*" >> "$HASHER_LOG"
+fi
+file=$1
+if [ "$self" = shasum ]; then
+  algo=
+  file=
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      -a)
+        algo=$2
+        shift 2
+        ;;
+      *)
+        file=$1
+        shift
+        ;;
+    esac
+  done
+  [ "$algo" = 256 ] || exit 1
+fi
+printf '%s  %s\n' "${SHA256_STUB_HASH:?}" "$file"
+SH
+  chmod +x "$fakebin/$name"
+}
+
+fm_install_stub_tar_actionlint() {
+  local fakebin=$1
+  cat > "$fakebin/tar" <<'SH'
+#!/usr/bin/env bash
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "-C" ]; then
+    cat > "$2/actionlint" <<'EOF'
+#!/usr/bin/env bash
+printf '1.7.12\n'
+EOF
+    chmod +x "$2/actionlint"
+    exit 0
+  fi
+  shift
+done
+exit 2
+SH
+  chmod +x "$fakebin/tar"
+}
+
+fm_install_stub_sleep() {
+  local fakebin=$1
+  cat > "$fakebin/sleep" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+  chmod +x "$fakebin/sleep"
+}
+
 write_valid_workflow() {
   local path=$1
   cat > "$path" <<'YAML'
@@ -181,48 +296,16 @@ test_installer_retries_transient_download_failure() {
   fakebin=$(fm_fakebin "$tmp")
   destination="$tmp/bin"
 
-  cat > "$fakebin/curl" <<'SH'
-#!/usr/bin/env bash
-count=0
-[ ! -f "$CURL_COUNT" ] || count=$(cat "$CURL_COUNT")
-count=$((count + 1))
-printf '%s\n' "$count" > "$CURL_COUNT"
-[ "$count" -gt 3 ] || exit 22
-while [ "$#" -gt 0 ]; do
-  if [ "$1" = "-o" ]; then
-    : > "$2"
-    exit 0
-  fi
-  shift
-done
-exit 2
-SH
-  cat > "$fakebin/sha256sum" <<'SH'
-#!/usr/bin/env bash
-printf '8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8  %s\n' "$1"
-SH
-  cat > "$fakebin/tar" <<'SH'
-#!/usr/bin/env bash
-while [ "$#" -gt 0 ]; do
-  if [ "$1" = "-C" ]; then
-    cat > "$2/actionlint" <<'EOF'
-#!/usr/bin/env bash
-printf '1.7.12\n'
-EOF
-    chmod +x "$2/actionlint"
-    exit 0
-  fi
-  shift
-done
-exit 2
-SH
-  cat > "$fakebin/sleep" <<'SH'
-#!/usr/bin/env bash
-exit 0
-SH
-  chmod +x "$fakebin/curl" "$fakebin/sha256sum" "$fakebin/tar" "$fakebin/sleep"
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" sha256sum
+  fm_install_stub_tar_actionlint "$fakebin"
+  fm_install_stub_sleep "$fakebin"
 
-  out=$(CURL_COUNT="$tmp/curl-count" PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) \
+  out=$(CURL_COUNT="$tmp/curl-count" CURL_FAIL_UNTIL=3 \
+    SHA256_STUB_HASH="$ACTIONLINT_SHA_LINUX_AMD64" \
+    FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=x86_64 \
+    PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) \
     || fail "installer did not recover from a transient download failure"$'\n'"$out"
   [ "$(cat "$tmp/curl-count")" -eq 4 ] || fail "installer did not recover after three failed downloads"
   assert_contains "$out" "download attempt 3 failed; retrying" "installer did not disclose its third retry"
@@ -230,6 +313,150 @@ SH
   pass "actionlint installer retries a transient download failure"
 }
 
+test_installer_selects_platform_archive_url_and_checksum() {
+  local tmp fakebin destination out url_log uname_s uname_m archive sha
+  tmp=$(fm_test_tmproot fm-actionlint-platform)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+  url_log="$tmp/curl-url.log"
+
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" sha256sum
+  fm_install_stub_tar_actionlint "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  while IFS=$'\t' read -r uname_s uname_m archive sha; do
+    [ -n "$uname_s" ] || continue
+    rm -rf "$destination"
+    : > "$url_log"
+    out=$(CURL_URL_LOG="$url_log" SHA256_STUB_HASH="$sha" \
+      FM_TEST_UNAME_S="$uname_s" FM_TEST_UNAME_M="$uname_m" \
+      PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) \
+      || fail "installer failed for ${uname_s}/${uname_m}"$'\n'"$out"
+    assert_contains "$(cat "$url_log")" "$archive" \
+      "installer did not download $archive for ${uname_s}/${uname_m}"
+    assert_contains "$(cat "$url_log")" \
+      "https://github.com/rhysd/actionlint/releases/download/v${REQUIRED}/${archive}" \
+      "installer used the wrong URL for ${uname_s}/${uname_m}"
+    [ -x "$destination/actionlint" ] || fail "installer did not install actionlint for ${uname_s}/${uname_m}"
+  done <<EOF
+Linux	x86_64	actionlint_${REQUIRED}_linux_amd64.tar.gz	$ACTIONLINT_SHA_LINUX_AMD64
+Linux	amd64	actionlint_${REQUIRED}_linux_amd64.tar.gz	$ACTIONLINT_SHA_LINUX_AMD64
+Linux	aarch64	actionlint_${REQUIRED}_linux_arm64.tar.gz	$ACTIONLINT_SHA_LINUX_ARM64
+Linux	arm64	actionlint_${REQUIRED}_linux_arm64.tar.gz	$ACTIONLINT_SHA_LINUX_ARM64
+Darwin	x86_64	actionlint_${REQUIRED}_darwin_amd64.tar.gz	$ACTIONLINT_SHA_DARWIN_AMD64
+Darwin	amd64	actionlint_${REQUIRED}_darwin_amd64.tar.gz	$ACTIONLINT_SHA_DARWIN_AMD64
+Darwin	arm64	actionlint_${REQUIRED}_darwin_arm64.tar.gz	$ACTIONLINT_SHA_DARWIN_ARM64
+Darwin	aarch64	actionlint_${REQUIRED}_darwin_arm64.tar.gz	$ACTIONLINT_SHA_DARWIN_ARM64
+EOF
+  pass "actionlint installer selects the official archive, URL, and checksum per OS/arch"
+}
+
+test_installer_rejects_wrong_checksum() {
+  local tmp fakebin destination out rc
+  tmp=$(fm_test_tmproot fm-actionlint-badsum)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" sha256sum
+  fm_install_stub_tar_actionlint "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  rc=0
+  out=$(SHA256_STUB_HASH=0000000000000000000000000000000000000000000000000000000000000000 \
+    FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=x86_64 \
+    PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "installer accepted a wrong checksum"$'\n'"$out"
+  assert_contains "$out" "checksum mismatch" "installer did not report a checksum mismatch"
+  assert_contains "$out" "actionlint_${REQUIRED}_linux_amd64.tar.gz" \
+    "mismatch did not name the selected archive"
+  assert_contains "$out" "$ACTIONLINT_SHA_LINUX_AMD64" \
+    "mismatch did not name the pinned linux/amd64 checksum"
+  [ ! -e "$destination/actionlint" ] || fail "installer installed actionlint after a checksum mismatch"
+  pass "actionlint installer rejects a wrong checksum"
+}
+
+test_installer_falls_back_to_shasum() {
+  local tmp fakebin destination out hasher_log tool
+  tmp=$(fm_test_tmproot fm-actionlint-shasum)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+  hasher_log="$tmp/hasher.log"
+
+  for tool in bash dirname mktemp rm awk mkdir install cat chmod; do
+    ln -s "$(command -v "$tool")" "$fakebin/$tool"
+  done
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" shasum
+  fm_install_stub_tar_actionlint "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  : > "$hasher_log"
+  out=$(CURL_URL_LOG="$tmp/curl-url.log" HASHER_LOG="$hasher_log" \
+    SHA256_STUB_HASH="$ACTIONLINT_SHA_LINUX_AMD64" \
+    FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=x86_64 \
+    PATH="$fakebin" "$INSTALLER" "$destination" 2>&1) \
+    || fail "installer did not fall back to shasum -a 256"$'\n'"$out"
+  assert_grep 'shasum -a 256' "$hasher_log" "installer did not invoke shasum -a 256"
+  [ -x "$destination/actionlint" ] || fail "installer did not install actionlint via shasum"
+  pass "actionlint installer falls back to shasum -a 256 when sha256sum is absent"
+}
+
+test_installer_prefers_sha256sum_over_shasum() {
+  local tmp fakebin destination hasher_log
+  tmp=$(fm_test_tmproot fm-actionlint-sha256sum-pref)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+  hasher_log="$tmp/hasher.log"
+
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" sha256sum
+  fm_install_stub_hasher "$fakebin" shasum
+  fm_install_stub_tar_actionlint "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  : > "$hasher_log"
+  PATH="$fakebin:$PATH" HASHER_LOG="$hasher_log" \
+    SHA256_STUB_HASH="$ACTIONLINT_SHA_LINUX_AMD64" \
+    FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=x86_64 \
+    "$INSTALLER" "$destination" >/dev/null \
+    || fail "installer failed when both hashers were present"
+  assert_grep 'sha256sum' "$hasher_log" "installer did not prefer sha256sum"
+  if grep -q 'shasum' "$hasher_log"; then
+    fail "installer invoked shasum even though sha256sum was present"$'\n'"$(cat "$hasher_log")"
+  fi
+  pass "actionlint installer prefers sha256sum when both hashers are present"
+}
+
+test_installer_rejects_unsupported_platform() {
+  local tmp fakebin destination out rc
+  tmp=$(fm_test_tmproot fm-actionlint-unsupported)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+
+  rc=0
+  out=$(FM_TEST_UNAME_S=FreeBSD FM_TEST_UNAME_M=amd64 \
+    PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "installer accepted an unsupported OS"$'\n'"$out"
+  assert_contains "$out" "unsupported platform" "installer did not name the unsupported platform"
+  assert_contains "$out" "FreeBSD-amd64" "installer did not report the detected OS/arch"
+
+  rc=0
+  out=$(FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=ppc64le \
+    PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "installer accepted an unsupported architecture"$'\n'"$out"
+  assert_contains "$out" "unsupported platform" "installer did not reject linux/ppc64le"
+  pass "actionlint installer rejects an unsupported OS or architecture"
+}
+
 # Prove the no-mistakes/local owner (bin/fm-lint.sh with no paths) catches a
 # self-broken ci.yml. Copy the lint scripts into a fake repo so the default
 # workflow root is the fixture, not this worktree.
@@ -295,4 +522,9 @@ test_non_mapping_root_fails
 test_missing_actionlint_fails_closed
 test_rejects_wrong_actionlint_version
 test_installer_retries_transient_download_failure
+test_installer_selects_platform_archive_url_and_checksum
+test_installer_rejects_wrong_checksum
+test_installer_falls_back_to_shasum
+test_installer_prefers_sha256sum_over_shasum
+test_installer_rejects_unsupported_platform
 test_fm_lint_default_path_catches_broken_ci_yml
diff --git a/tests/fm-lint.test.sh b/tests/fm-lint.test.sh
index 99eba0f8abf..e7fd94fc955 100755
--- a/tests/fm-lint.test.sh
+++ b/tests/fm-lint.test.sh
@@ -22,6 +22,128 @@ INSTALLER="$ROOT/bin/fm-install-shellcheck.sh"
 # The pinned version, read from the single source (the one owner itself).
 REQUIRED=$("$LINT" --required-version)
 
+# Official GitHub release asset sha256 values for shellcheck v0.11.0 .tar.xz
+# archives (https://github.com/koalaman/shellcheck/releases/tag/v0.11.0). Tests
+# compare installer behavior against these published digests, not script source.
+SHELLCHECK_SHA_LINUX_X86_64=8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198
+SHELLCHECK_SHA_LINUX_AARCH64=12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588
+SHELLCHECK_SHA_DARWIN_X86_64=3c89db4edcab7cf1c27bff178882e0f6f27f7afdf54e859fa041fca10febe4c6
+SHELLCHECK_SHA_DARWIN_AARCH64=56affdd8de5527894dca6dc3d7e0a99a873b0f004d7aabc30ae407d3f48b0a79
+
+# fm_install_stub_uname <fakebin>: uname -s / uname -m from FM_TEST_UNAME_S/M.
+fm_install_stub_uname() {
+  local fakebin=$1
+  cat > "$fakebin/uname" <<'SH'
+#!/usr/bin/env bash
+case "${1:-}" in
+  -s) printf '%s\n' "${FM_TEST_UNAME_S:-Linux}" ;;
+  -m) printf '%s\n' "${FM_TEST_UNAME_M:-x86_64}" ;;
+  *) printf '%s\n' "${FM_TEST_UNAME_S:-Linux}" ;;
+esac
+SH
+  chmod +x "$fakebin/uname"
+}
+
+# fm_install_stub_curl <fakebin>: log the URL, fail CURL_FAIL_UNTIL times, then
+# write an empty file at -o. CURL_COUNT and CURL_URL_LOG are paths the stub
+# updates when invoked.
+fm_install_stub_curl() {
+  local fakebin=$1
+  cat > "$fakebin/curl" <<'SH'
+#!/usr/bin/env bash
+count=0
+[ ! -f "${CURL_COUNT:-}" ] || count=$(cat "$CURL_COUNT")
+count=$((count + 1))
+[ -z "${CURL_COUNT:-}" ] || printf '%s\n' "$count" > "$CURL_COUNT"
+url=
+out=
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    -o)
+      out=$2
+      shift 2
+      ;;
+    -*)
+      shift
+      ;;
+    *)
+      url=$1
+      shift
+      ;;
+  esac
+done
+[ -z "${CURL_URL_LOG:-}" ] || printf '%s\n' "$url" >> "$CURL_URL_LOG"
+fail_until=${CURL_FAIL_UNTIL:-0}
+[ "$count" -gt "$fail_until" ] || exit 22
+: > "$out"
+exit 0
+SH
+  chmod +x "$fakebin/curl"
+}
+
+# fm_install_stub_hasher <fakebin> <name>: sha256sum or shasum stub that prints
+# SHA256_STUB_HASH and records the invocation on HASHER_LOG. shasum requires -a 256.
+fm_install_stub_hasher() {
+  local fakebin=$1 name=$2
+  cat > "$fakebin/$name" <<'SH'
+#!/usr/bin/env bash
+self=${0##*/}
+if [ -n "${HASHER_LOG:-}" ]; then
+  printf '%s\n' "$self $*" >> "$HASHER_LOG"
+fi
+file=$1
+if [ "$self" = shasum ]; then
+  algo=
+  file=
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      -a)
+        algo=$2
+        shift 2
+        ;;
+      *)
+        file=$1
+        shift
+        ;;
+    esac
+  done
+  [ "$algo" = 256 ] || exit 1
+fi
+printf '%s  %s\n' "${SHA256_STUB_HASH:?}" "$file"
+SH
+  chmod +x "$fakebin/$name"
+}
+
+fm_install_stub_tar_shellcheck() {
+  local fakebin=$1
+  cat > "$fakebin/tar" <<'SH'
+#!/usr/bin/env bash
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "-C" ]; then
+    mkdir -p "$2/shellcheck-v0.11.0"
+    cat > "$2/shellcheck-v0.11.0/shellcheck" <<'EOF'
+#!/usr/bin/env bash
+printf 'ShellCheck - shell script analysis tool\nversion: 0.11.0\n'
+EOF
+    chmod +x "$2/shellcheck-v0.11.0/shellcheck"
+    exit 0
+  fi
+  shift
+done
+exit 2
+SH
+  chmod +x "$fakebin/tar"
+}
+
+fm_install_stub_sleep() {
+  local fakebin=$1
+  cat > "$fakebin/sleep" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+  chmod +x "$fakebin/sleep"
+}
+
 # True only when the resolved shellcheck is exactly the pinned version, so the
 # lint-running tests below match what CI enforces instead of a runner default.
 pinned_ready() {
@@ -247,51 +369,19 @@ test_installer_retries_transient_download_failure() {
   fakebin=$(fm_fakebin "$tmp")
   destination="$tmp/bin"
 
-  cat > "$fakebin/curl" <<'SH'
-#!/usr/bin/env bash
-count=0
-[ ! -f "$CURL_COUNT" ] || count=$(cat "$CURL_COUNT")
-count=$((count + 1))
-printf '%s\n' "$count" > "$CURL_COUNT"
-# Reproduce the CI incident: the release endpoint returned 503 for all three
-# formerly configured attempts before recovering.
-[ "$count" -gt 3 ] || exit 22
-while [ "$#" -gt 0 ]; do
-  if [ "$1" = "-o" ]; then
-    : > "$2"
-    exit 0
-  fi
-  shift
-done
-exit 2
-SH
-  cat > "$fakebin/sha256sum" <<'SH'
-#!/usr/bin/env bash
-printf '8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198  %s\n' "$1"
-SH
-  cat > "$fakebin/tar" <<'SH'
-#!/usr/bin/env bash
-while [ "$#" -gt 0 ]; do
-  if [ "$1" = "-C" ]; then
-    mkdir -p "$2/shellcheck-v0.11.0"
-    cat > "$2/shellcheck-v0.11.0/shellcheck" <<'EOF'
-#!/usr/bin/env bash
-printf 'ShellCheck - shell script analysis tool\nversion: 0.11.0\n'
-EOF
-    chmod +x "$2/shellcheck-v0.11.0/shellcheck"
-    exit 0
-  fi
-  shift
-done
-exit 2
-SH
-  cat > "$fakebin/sleep" <<'SH'
-#!/usr/bin/env bash
-exit 0
-SH
-  chmod +x "$fakebin/curl" "$fakebin/sha256sum" "$fakebin/tar" "$fakebin/sleep"
-
-  out=$(CURL_COUNT="$tmp/curl-count" PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) \
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" sha256sum
+  fm_install_stub_tar_shellcheck "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  # Reproduce the CI incident: the release endpoint returned 503 for all three
+  # formerly configured attempts before recovering. Force linux/x86_64 so the
+  # retry path stays the CI archive even when this suite runs on macOS.
+  out=$(CURL_COUNT="$tmp/curl-count" CURL_FAIL_UNTIL=3 \
+    SHA256_STUB_HASH="$SHELLCHECK_SHA_LINUX_X86_64" \
+    FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=x86_64 \
+    PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) \
     || fail "installer did not recover from a transient download failure"$'\n'"$out"
   [ "$(cat "$tmp/curl-count")" -eq 4 ] || fail "installer did not recover after three failed downloads"
   assert_contains "$out" "download attempt 3 failed; retrying" "installer did not disclose its third retry"
@@ -299,6 +389,151 @@ SH
   pass "ShellCheck installer retries a transient download failure"
 }
 
+test_installer_selects_platform_archive_url_and_checksum() {
+  local tmp fakebin destination out url_log uname_s uname_m archive sha
+  tmp=$(fm_test_tmproot fm-shellcheck-platform)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+  url_log="$tmp/curl-url.log"
+
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" sha256sum
+  fm_install_stub_tar_shellcheck "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  while IFS=$'\t' read -r uname_s uname_m archive sha; do
+    [ -n "$uname_s" ] || continue
+    rm -rf "$destination"
+    : > "$url_log"
+    out=$(CURL_URL_LOG="$url_log" SHA256_STUB_HASH="$sha" \
+      FM_TEST_UNAME_S="$uname_s" FM_TEST_UNAME_M="$uname_m" \
+      PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) \
+      || fail "installer failed for ${uname_s}/${uname_m}"$'\n'"$out"
+    assert_contains "$(cat "$url_log")" "$archive" \
+      "installer did not download $archive for ${uname_s}/${uname_m}"
+    assert_contains "$(cat "$url_log")" \
+      "https://github.com/koalaman/shellcheck/releases/download/v${REQUIRED}/${archive}" \
+      "installer used the wrong URL for ${uname_s}/${uname_m}"
+    [ -x "$destination/shellcheck" ] || fail "installer did not install ShellCheck for ${uname_s}/${uname_m}"
+  done <<EOF
+Linux	x86_64	shellcheck-v${REQUIRED}.linux.x86_64.tar.xz	$SHELLCHECK_SHA_LINUX_X86_64
+Linux	amd64	shellcheck-v${REQUIRED}.linux.x86_64.tar.xz	$SHELLCHECK_SHA_LINUX_X86_64
+Linux	aarch64	shellcheck-v${REQUIRED}.linux.aarch64.tar.xz	$SHELLCHECK_SHA_LINUX_AARCH64
+Linux	arm64	shellcheck-v${REQUIRED}.linux.aarch64.tar.xz	$SHELLCHECK_SHA_LINUX_AARCH64
+Darwin	x86_64	shellcheck-v${REQUIRED}.darwin.x86_64.tar.xz	$SHELLCHECK_SHA_DARWIN_X86_64
+Darwin	amd64	shellcheck-v${REQUIRED}.darwin.x86_64.tar.xz	$SHELLCHECK_SHA_DARWIN_X86_64
+Darwin	arm64	shellcheck-v${REQUIRED}.darwin.aarch64.tar.xz	$SHELLCHECK_SHA_DARWIN_AARCH64
+Darwin	aarch64	shellcheck-v${REQUIRED}.darwin.aarch64.tar.xz	$SHELLCHECK_SHA_DARWIN_AARCH64
+EOF
+  pass "ShellCheck installer selects the official archive, URL, and checksum per OS/arch"
+}
+
+test_installer_rejects_wrong_checksum() {
+  local tmp fakebin destination out rc
+  tmp=$(fm_test_tmproot fm-shellcheck-badsum)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" sha256sum
+  fm_install_stub_tar_shellcheck "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  rc=0
+  out=$(SHA256_STUB_HASH=0000000000000000000000000000000000000000000000000000000000000000 \
+    FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=x86_64 \
+    PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "installer accepted a wrong checksum"$'\n'"$out"
+  assert_contains "$out" "checksum mismatch" "installer did not report a checksum mismatch"
+  assert_contains "$out" "shellcheck-v${REQUIRED}.linux.x86_64.tar.xz" \
+    "mismatch did not name the selected archive"
+  assert_contains "$out" "$SHELLCHECK_SHA_LINUX_X86_64" \
+    "mismatch did not name the pinned linux/x86_64 checksum"
+  [ ! -e "$destination/shellcheck" ] || fail "installer installed ShellCheck after a checksum mismatch"
+  pass "ShellCheck installer rejects a wrong checksum"
+}
+
+test_installer_falls_back_to_shasum() {
+  local tmp fakebin destination out hasher_log tool
+  tmp=$(fm_test_tmproot fm-shellcheck-shasum)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+  hasher_log="$tmp/hasher.log"
+
+  for tool in bash dirname mktemp rm awk mkdir install cat chmod; do
+    ln -s "$(command -v "$tool")" "$fakebin/$tool"
+  done
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" shasum
+  fm_install_stub_tar_shellcheck "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  # Restricted PATH: shasum is present, sha256sum is not.
+  : > "$hasher_log"
+  out=$(CURL_URL_LOG="$tmp/curl-url.log" HASHER_LOG="$hasher_log" \
+    SHA256_STUB_HASH="$SHELLCHECK_SHA_LINUX_X86_64" \
+    FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=x86_64 \
+    PATH="$fakebin" "$INSTALLER" "$destination" 2>&1) \
+    || fail "installer did not fall back to shasum -a 256"$'\n'"$out"
+  assert_grep 'shasum -a 256' "$hasher_log" "installer did not invoke shasum -a 256"
+  [ -x "$destination/shellcheck" ] || fail "installer did not install ShellCheck via shasum"
+  pass "ShellCheck installer falls back to shasum -a 256 when sha256sum is absent"
+}
+
+test_installer_prefers_sha256sum_over_shasum() {
+  local tmp fakebin destination hasher_log
+  tmp=$(fm_test_tmproot fm-shellcheck-sha256sum-pref)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+  hasher_log="$tmp/hasher.log"
+
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+  fm_install_stub_hasher "$fakebin" sha256sum
+  fm_install_stub_hasher "$fakebin" shasum
+  fm_install_stub_tar_shellcheck "$fakebin"
+  fm_install_stub_sleep "$fakebin"
+
+  : > "$hasher_log"
+  PATH="$fakebin:$PATH" HASHER_LOG="$hasher_log" \
+    SHA256_STUB_HASH="$SHELLCHECK_SHA_LINUX_X86_64" \
+    FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=x86_64 \
+    "$INSTALLER" "$destination" >/dev/null \
+    || fail "installer failed when both hashers were present"
+  assert_grep 'sha256sum' "$hasher_log" "installer did not prefer sha256sum"
+  if grep -q 'shasum' "$hasher_log"; then
+    fail "installer invoked shasum even though sha256sum was present"$'\n'"$(cat "$hasher_log")"
+  fi
+  pass "ShellCheck installer prefers sha256sum when both hashers are present"
+}
+
+test_installer_rejects_unsupported_platform() {
+  local tmp fakebin destination out rc
+  tmp=$(fm_test_tmproot fm-shellcheck-unsupported)
+  fakebin=$(fm_fakebin "$tmp")
+  destination="$tmp/bin"
+
+  fm_install_stub_uname "$fakebin"
+  fm_install_stub_curl "$fakebin"
+
+  rc=0
+  out=$(FM_TEST_UNAME_S=FreeBSD FM_TEST_UNAME_M=amd64 \
+    PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "installer accepted an unsupported OS"$'\n'"$out"
+  assert_contains "$out" "unsupported platform" "installer did not name the unsupported platform"
+  assert_contains "$out" "FreeBSD-amd64" "installer did not report the detected OS/arch"
+
+  rc=0
+  out=$(FM_TEST_UNAME_S=Linux FM_TEST_UNAME_M=ppc64le \
+    PATH="$fakebin:$PATH" "$INSTALLER" "$destination" 2>&1) || rc=$?
+  [ "$rc" -ne 0 ] || fail "installer accepted an unsupported architecture"$'\n'"$out"
+  assert_contains "$out" "unsupported platform" "installer did not reject linux/ppc64le"
+  pass "ShellCheck installer rejects an unsupported OS or architecture"
+}
+
 test_rejects_wrong_shellcheck_version() {
   # Version-independent: a fake shellcheck reporting a different version must be
   # refused before any lint, proving local and CI cannot silently diverge.
@@ -626,6 +861,11 @@ SH
 test_list_files_reports_the_shell_inventory
 test_pins_an_explicit_version
 test_installer_retries_transient_download_failure
+test_installer_selects_platform_archive_url_and_checksum
+test_installer_rejects_wrong_checksum
+test_installer_falls_back_to_shasum
+test_installer_prefers_sha256sum_over_shasum
+test_installer_rejects_unsupported_platform
 test_rejects_wrong_shellcheck_version
 test_catches_a_real_lint_defect
 test_ignores_ambient_shellcheck_opts

From 312871d1c768c2252630d4f5f2737664e2fb3345 Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Mon, 17 Aug 2026 15:47:45 -0700
Subject: [PATCH 06/12] docs: reconcile test-evidence docs with store_in_repo:
 true (#2548)

.no-mistakes.yaml has set test.evidence.store_in_repo: true since #2355, but
CONTRIBUTING.md, docs/configuration.md, and docs/architecture.md still described
the old policy of keeping evidence out of the repo in a temp directory.

The current no-mistakes behavior for store_in_repo: true is to publish each run's
test evidence to the orphan no-mistakes/evidence branch and link it from the PR
body. That branch shares no history with code branches, so evidence never enters
a pushed feature branch or the default branch, and CI's tracked personal fleet
paths rule stays accurate.

Docs only. No change to .no-mistakes.yaml or any workflow.
---
 CONTRIBUTING.md       | 4 ++--
 docs/architecture.md  | 4 ++--
 docs/configuration.md | 5 +++--
 3 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 97442a450f8..cef1f1180f1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -67,9 +67,9 @@ A crewmate picking up such a brief should load the skill even if the brief preda
 When supervising live crewmates, keep firstmate's own long validation or build commands in the background so watcher wakes can still be handled.
 Crewmate validation follows the installed no-mistakes version's SKILL.md and live `axi` help instead of duplicating gate mechanics in firstmate docs.
 Firstmate's wrapper still matters: crewmates route every `ask-user` finding to firstmate, which applies the authority contract in `AGENTS.md`, and crewmates avoid `--yes` because it would bypass that check and any required captain escalation.
-Local `.no-mistakes/` state and test evidence stay out of this repo; `.no-mistakes.yaml` keeps evidence in a temp directory and pins the gate's lint command to `bin/fm-lint.sh`, matching the Linux CI lint job.
+`.no-mistakes.yaml` publishes test evidence to the orphan `no-mistakes/evidence` branch, which shares no history with code branches, and pins the gate's lint command to `bin/fm-lint.sh`, matching the Linux CI lint job.
 Local no-mistakes Test is intent-targeted and must not re-run every `tests/*.test.sh`; `.github/workflows/ci.yml` owns the broad behavior suite plus platform-specific compatibility lanes.
-That is firstmate-specific; do not commit `.no-mistakes/evidence/` here even when another no-mistakes-managed target project keeps committed PR evidence.
+The pipeline publishes that evidence itself, so never hand-commit `.no-mistakes/` paths onto a feature branch; CI rejects them as tracked personal fleet paths.
 
 Check and test the toolbelt before pushing:
 
diff --git a/docs/architecture.md b/docs/architecture.md
index b7356858228..b07da27b98d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -244,8 +244,8 @@ A ship brief records its mode as a fixed machine-readable line and the spawn ref
 `data/projects.md` records each project's standing posture and optional `+yolo` flag as the captain's default and as context for that decision, including the conditional `no-mistakes-prod-only` policy; a ship spawn that drops below the registered rigor prints a deviation notice and continues.
 `bin/fm-project-mode.sh` remains the one registry parser for the mechanical consumers that have no task in hand: fleet sync's `local-only` skip and home seeding's refusal and no-mistakes initialization.
 When a selected delivery path calls for a diff, `bin/fm-review-diff.sh` refreshes the authoritative base and, when task meta records `pr=`, always fetches and compares against `refs/pull/<n>/head` by default (recorded `pr_head=` is only an offline fallback) before falling back to the local branch with a warning.
-For target project repos shipped through their own no-mistakes pipeline, commits under `.no-mistakes/evidence/` are the pipeline's PR-viewable validation evidence and are expected to stay in the crew branch until the evidence-hosting design changes.
-The firstmate repo itself is the exception: its `.no-mistakes/` directory is local state, stays gitignored, and is rejected by CI if tracked.
+Where a no-mistakes pipeline stores evidence in the repo, it publishes that PR-viewable validation evidence to an orphan evidence branch that shares no history with code branches, so it never enters the crew branch or the default branch.
+This repo uses that setting, and its own `.no-mistakes/` directory remains local state that stays gitignored and is rejected by CI if tracked; [`configuration.md`](configuration.md) owns the setting.
 PR-based task merges go through `bin/fm-pr-merge.sh`, which records `pr=` and any available `pr_head=` through `bin/fm-pr-check.sh` before calling `gh-axi pr merge`.
 The helper requires a full `https://github.com/<owner>/<repo>/pull/<n>` URL, invokes `gh-axi pr merge <n> --repo <owner>/<repo>`, defaults to `--squash`, preserves explicit merge-method flags, and rejects malformed URLs or repo override flags before recording merge state; a well-formed GitLab merge request URL (see [docs/gitlab-merge-watch.md](gitlab-merge-watch.md)) is refused too, explicitly, rather than sent to the wrong forge.
 Teardown is fail-closed for ship worktrees: dirty worktrees refuse, and committed work must be landed before the worktree is returned.
diff --git a/docs/configuration.md b/docs/configuration.md
index e4aef1a7ccd..415c113991b 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -129,8 +129,9 @@ See [`trace-context.md`](trace-context.md) for carrier semantics, supported rout
 
 ## Gate defaults (.no-mistakes.yaml)
 
-The tracked `.no-mistakes.yaml` keeps test evidence outside the repo and pins `commands.lint` to `bin/fm-lint.sh` so local lint matches CI.
-That evidence policy is specific to the firstmate repo: target projects may legitimately commit `.no-mistakes/evidence/` from their own no-mistakes pipeline, but firstmate keeps `.no-mistakes/` local and CI rejects tracked entries under that path.
+The tracked `.no-mistakes.yaml` sets `test.evidence.store_in_repo: true` and pins `commands.lint` to `bin/fm-lint.sh` so local lint matches CI.
+Storing evidence in the repo publishes each run's test artifacts to the orphan `no-mistakes/evidence` branch and links them from the PR body, instead of keeping them on local disk under the no-mistakes home.
+That branch shares no history with code branches, so evidence never enters a pushed feature branch or the default branch; the worktree's `.no-mistakes/` stays local and CI rejects tracked entries under that path.
 It does not set `commands.test` to a complete `tests/*.test.sh` walk.
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for the firstmate-specific local test policy and entry points.
 Portable shard evidence and coverage rules are in [fm-test-portable-shards.md](fm-test-portable-shards.md); [herdr-backend.md](herdr-backend.md#destructive-lab-safety) owns the real-Herdr lane's isolation boundary, and [runtime-backends.md](verification/runtime-backends.md#herdr) owns active evidence.

From 64d61aed84373e02b1a28c4e6b262908ed8128d5 Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Mon, 17 Aug 2026 16:08:26 -0700
Subject: [PATCH 07/12] docs: clarify test evidence branch storage (#2549)

* docs: correct test evidence storage comment in .no-mistakes.yaml

* no-mistakes: apply CI fixes
---
 .no-mistakes.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.no-mistakes.yaml b/.no-mistakes.yaml
index 219c39b794f..f825543372d 100644
--- a/.no-mistakes.yaml
+++ b/.no-mistakes.yaml
@@ -37,7 +37,8 @@ document:
 commands:
   lint: 'bin/fm-lint.sh'
 
-# Store test evidence in this repo so it is committed alongside the change instead of kept in a temp dir.
+# Publish each run's test evidence to the orphan no-mistakes/evidence branch linked from the PR.
+# The evidence is not committed to the feature or default branch.
 test:
   evidence:
     store_in_repo: true

From d023c451e00fb64f9845b27fa949c02beed8c551 Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Mon, 17 Aug 2026 20:16:15 -0700
Subject: [PATCH 08/12] docs: hint that live scouts may host their own Lavish
 review loop (#2563)

Make that a first-class option in always-loaded instructions so firstmate does not default to mediating and tearing the scout down between iteration rounds.
---
 .agents/skills/process-event-sources/SKILL.md | 2 +-
 AGENTS.md                                     | 1 +
 bin/fm-brief.sh                               | 1 +
 tests/fm-brief.test.sh                        | 2 ++
 4 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/.agents/skills/process-event-sources/SKILL.md b/.agents/skills/process-event-sources/SKILL.md
index e5fd0c9b1c0..793ac546126 100644
--- a/.agents/skills/process-event-sources/SKILL.md
+++ b/.agents/skills/process-event-sources/SKILL.md
@@ -25,7 +25,7 @@ Firstmate registers a source, keeps working, and is woken when that process comp
 ## Arming a source
 
 Use the adapter, not the generic runner, for a real source.
-For a Lavish review artifact:
+For a Lavish review artifact firstmate owns (a live investigating scout should host its own loop):
 
 ```sh
 bin/fm-procevent-lavish.sh arm <artifact.html>
diff --git a/AGENTS.md b/AGENTS.md
index 334ff6b8ee6..6d6c9552288 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -372,6 +372,7 @@ Retire one only on an explicit captain or main-firstmate decision, after loading
 A completed scout must leave a self-contained report before its scratch worktree can be discarded; read and relay its findings, record the report as the Done artifact, and re-evaluate the queue.
 A report may recommend implementation but does not authorize it.
 Before treating the investigation or any visual review as complete, load `decision-hold-lifecycle`; teardown enforces that shared completion gate.
+When a scout's deliverable is a visual artifact the captain will iterate on, prefer keeping that scout alive to host its own Lavish loop rather than tearing it down and mediating from firstmate, so the scout keeps its investigation context and the captain iterates in one continuous session.
 When implementation is separately authorized, promote the existing scout through `bin/fm-promote.sh` rather than creating a duplicate task.
 The promoted worker must inventory scratch state, return to a clean default-branch base, carry over only intended fix changes, create the ship branch, and follow the project's selected delivery path while leaving scratch commits and debug edits behind and turning a reproduced bug into the regression test.
 
diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh
index a873c840517..206e5a947ae 100755
--- a/bin/fm-brief.sh
+++ b/bin/fm-brief.sh
@@ -339,6 +339,7 @@ The report is the only thing that survives, so anything worth keeping must be in
 # Definition of done
 Write your findings to \`$DATA/$ID/report.md\`.
 The report must stand alone: what you did, what you found, the evidence (commands run, output, file:line references), and what you recommend.
+If your deliverable is a visual artifact the captain will review and iterate on, you may host the Lavish review loop yourself (poll, revise, re-serve, staying alive) instead of handing it back to firstmate.
 Before reporting done, read and follow \`$FM_ROOT/.agents/skills/decision-hold-lifecycle/SKILL.md\` and pass its shared completion gate for the report and any visual review.
 When the report is complete, append \`done: {one-line conclusion}\` to the status file and stop.
 If your findings reveal work that should ship (e.g. you reproduced a bug and the fix is clear), say so in the report; firstmate may promote this task in place, and you would then receive mode-specific ship instructions as a follow-up message.
diff --git a/tests/fm-brief.test.sh b/tests/fm-brief.test.sh
index a348e2d345e..c5ee3d00f05 100755
--- a/tests/fm-brief.test.sh
+++ b/tests/fm-brief.test.sh
@@ -699,6 +699,8 @@ test_scout_and_secondmate_scaffold() {
   assert_present "$brief" "scout brief was not scaffolded"
   assert_grep "SCOUT task" "$brief" "scout brief must declare itself a scout task"
   assert_grep "report.md" "$brief" "scout brief must point at the report deliverable"
+  assert_grep "you may host the Lavish review loop yourself" "$brief" \
+    "scout brief must mention the option to host a Lavish review loop"
 
   FM_SECONDMATE_CHARTER='Supervise the alpha domain.' \
     FM_HOME="$BRIEF_HOME" "$ROOT/bin/fm-brief.sh" brief-sm-q6 --secondmate alpha >/dev/null 2>&1 \

From d843712808658f26a7a3f248e632cb999864ca50 Mon Sep 17 00:00:00 2001
From: Kun Chen <3233006+kunchenguid@users.noreply.github.com>
Date: Tue, 18 Aug 2026 00:05:02 -0700
Subject: [PATCH 09/12] fix(bin): report remote secondmate delivery and state
 truthfully (#2570)

* fix(bin): report remote secondmate delivery and state truthfully

A steer to a remote secondmate crosses fm-on.sh to a host-local fm-send
leg whose unconfirmed submit read-back (verdict=pending, typically a busy
mate whose harness queues the steer) was flattened into exit 1, so the
parent printed "error: text not submitted" / "error: text not sent" and
discarded the pending-reply expectation for a steer that had actually
landed. fm-send now carries the verdict across the ssh boundary as a
documented delivered-unconfirmed exit 3: the parent reports the steer as
delivered with confirmation pending, exits 0, keeps the expectation armed
(awaiting_report), and closes --resolve-key decisions, while transport
loss (ssh 255) and real remote failures keep failing loudly with the
remote leg's stderr attached. A local unconfirmed submit now also exits 3
with an honest non-error message and still never closes a decision key.

fm-crew-state.sh and fm-peek.sh no longer read a remote mate's endpoint
through local probes (which misreported a healthy mate as "worktree gone"
/ "can't find session: remote"): both now use the true remote source over
fm-on.sh, and an unreachable or unreadable remote reads as unknown-remote,
never as gone or dead.

* no-mistakes(document): Document remote delivery and state truth

* no-mistakes: apply CI fixes
---
 .../skills/stuck-crewmate-recovery/SKILL.md   |   2 +-
 bin/fm-crew-state.sh                          |  57 +++-
 bin/fm-peek.sh                                |  23 +-
 bin/fm-remote-secondmate-control.sh           |   6 +
 bin/fm-send.sh                                |  62 +++-
 docs/remote-secondmates.md                    |   8 +
 docs/tmux-backend.md                          |   2 +-
 tests/fm-crew-state.test.sh                   | 103 +++++++
 tests/fm-daemon.test.sh                       |  30 +-
 tests/fm-peek-remote.test.sh                  | 110 +++++++
 tests/fm-send-remote-delivery.test.sh         | 285 ++++++++++++++++++
 11 files changed, 668 insertions(+), 20 deletions(-)
 create mode 100755 tests/fm-peek-remote.test.sh
 create mode 100755 tests/fm-send-remote-delivery.test.sh

diff --git a/.agents/skills/stuck-crewmate-recovery/SKILL.md b/.agents/skills/stuck-crewmate-recovery/SKILL.md
index cf741b9d95f..b9b94b27d43 100644
--- a/.agents/skills/stuck-crewmate-recovery/SKILL.md
+++ b/.agents/skills/stuck-crewmate-recovery/SKILL.md
@@ -23,7 +23,7 @@ The target window's harness is recorded as `harness=` in `state/<id>.meta`.
 This procedure covers ordinary `kind=ship` and `kind=scout` direct reports.
 Load `secondmate-provisioning` instead for `kind=secondmate` recovery.
 
-For a REMOTE secondmate, `fm-crew-state`'s `unknown`/`worktree gone` and `fm-send`'s `remote send failed`/`delivery unconfirmed` verdicts are unreliable and routinely false-negative; do not conclude the mate is dead or the send failed from those alone, confirm against the actual remote pane first.
+For a REMOTE secondmate, `fm-crew-state` and `fm-peek` read the actual remote endpoint over `fm-on.sh`, and `fm-send` reports a delivered-with-pending-confirmation steer as delivered (their headers own the contracts); an `unknown-remote` read or unreachable-host failure means the remote state could not be read, never that the mate is dead or the send failed.
 Recover a genuinely stuck remote mate only through `bin/fm-spawn.sh <id> --secondmate`, never raw herdr pane close/kill surgery, which strands the endpoint binding.
 
 Treat the digest's endpoint result as a presence signal, not proof that the task's work or validation run is gone.
diff --git a/bin/fm-crew-state.sh b/bin/fm-crew-state.sh
index 2cb290373cb..df627b487f2 100755
--- a/bin/fm-crew-state.sh
+++ b/bin/fm-crew-state.sh
@@ -16,10 +16,17 @@
 # fixed mapping logic, no heuristics and no LLM. Output is one stable, parseable,
 # token-tight line firstmate can read every heartbeat:
 #
-#   state: <working|parked|done|blocked|paused|failed|unknown> · source: <run-step|pane|status-log|none> · <detail>
+#   state: <working|parked|done|blocked|paused|failed|unknown> · source: <run-step|pane|status-log|remote-endpoint|none> · <detail>
 #
 # Logic, in order:
-#   1. Resolve worktree + backend target + kind from state/<id>.meta.
+#   1. Resolve worktree + backend target + kind from state/<id>.meta. A meta
+#      recording remote_host= is a remote secondmate: its worktree and endpoint
+#      live on that host, so the local worktree and pane reads are skipped and
+#      the remote host is asked for the endpoint's recovery-grade state
+#      (fm-on.sh + fm-remote-secondmate-control.sh state). alive falls through
+#      to the routed status log; dead/missing report the remote verdict; an
+#      unreachable or unreadable remote reports unknown-remote, never a false
+#      gone/dead.
 #   2. Matching no-mistakes run for this crew's branch AND current code identity,
 #      active or terminal (from `axi status`, or the coarse `no-mistakes runs`
 #      fallback)? Branch name alone is not enough: a historical run on a reused
@@ -101,10 +108,13 @@ meta_value() {  # <key>
 WT=$(meta_value worktree)
 KIND=$(meta_value kind)
 HARNESS=$(meta_value harness)
+REMOTE_HOST=$(meta_value remote_host)
 [ -n "$KIND" ] || KIND=ship
 
-# A torn-down (or never-created) worktree has no current state to read.
-if [ -z "$WT" ] || [ ! -d "$WT" ]; then
+# A torn-down (or never-created) worktree has no current state to read. A
+# remote secondmate's recorded worktree is a path on ITS host, so the local
+# probe proves nothing for it - the remote arm below reads the true source.
+if [ -z "$REMOTE_HOST" ] && { [ -z "$WT" ] || [ ! -d "$WT" ]; }; then
   emit unknown none "worktree gone (torn down?)"
 fi
 
@@ -138,6 +148,45 @@ map_log_state() {  # <line>
 LOG_LINE=$(log_last_line || true)
 LOG_VERB=$(status_line_verb "$LOG_LINE")
 
+# --- remote secondmate: the true source is the remote endpoint ---------------
+# A remote mate's recorded worktree and backend target live on its own host, so
+# the local worktree probe above and the local pane reads below would misreport
+# a healthy remote mate as gone or dead. Ask the remote host for the endpoint's
+# recovery-grade state over the same fm-on.sh transport fm-send uses, then read
+# current activity from the routed status log exactly as for a local
+# secondmate (an idle endpoint is healthy for a secondmate either way). An
+# unreachable host or unreadable endpoint is reported as unknown-remote -
+# explicitly NOT proof of death - so a transport blip never reads as a torn
+# down or dead mate; only the remote host's own dead/missing verdict may say
+# the endpoint is actually gone.
+if [ -n "$REMOTE_HOST" ]; then
+  if ! REMOTE_STATE=$(FM_HOME="$FM_HOME" "$SCRIPT_DIR/fm-on.sh" "$ID" \
+    fm-remote-secondmate-control.sh state "$ID" < /dev/null 2>/dev/null); then
+    REMOTE_STATE=
+  fi
+  REMOTE_STATE=$(printf '%s\n' "$REMOTE_STATE" | tail -1)
+  case "$REMOTE_STATE" in
+    alive)
+      if [ -n "$LOG_VERB" ]; then
+        LOG_STATE=$(map_log_state "$LOG_LINE")
+        if [ "$LOG_STATE" != unknown ]; then
+          emit "$LOG_STATE" status-log "$(status_line_note "$LOG_LINE")${SEP}remote endpoint alive on $REMOTE_HOST"
+        fi
+      fi
+      emit unknown remote-endpoint "alive on $REMOTE_HOST (an idle secondmate is healthy)"
+      ;;
+    dead|missing)
+      emit unknown remote-endpoint "remote endpoint $REMOTE_STATE on $REMOTE_HOST"
+      ;;
+    '')
+      emit unknown remote-endpoint "unknown-remote: $REMOTE_HOST unreachable or endpoint unreadable (not proof of death)"
+      ;;
+    *)
+      emit unknown remote-endpoint "unknown-remote: endpoint state '$REMOTE_STATE' on $REMOTE_HOST (not proof of death)"
+      ;;
+  esac
+fi
+
 # pane_readable is consulted ONLY in the no-run fallback below. The run-step path
 # stays authoritative regardless of pane liveness - judge by the run-step, not the
 # shell - so a finished crew whose endpoint has closed still reports its run-step
diff --git a/bin/fm-peek.sh b/bin/fm-peek.sh
index 97d2ffe2d25..e3156f66ed4 100755
--- a/bin/fm-peek.sh
+++ b/bin/fm-peek.sh
@@ -3,6 +3,11 @@
 # Usage: fm-peek.sh <target> [lines=40]
 #   <target> may be an exact task id, a legacy fm-<id> task label resolved
 #   through this home's state/<id>.meta, or an explicit backend target.
+# A selector whose meta records remote_host= is a remote secondmate: its pane
+# lives on that host, so the capture routes over fm-on.sh to the host-local
+# capture (fm-remote-secondmate-control.sh), clamped to that command's
+# 100-line cap. An unreachable host or unreadable endpoint fails loudly naming
+# the host; the local backend adapters are never asked to read a remote target.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -16,9 +21,25 @@ STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
 "$SCRIPT_DIR/fm-guard.sh" || true
 
 RAW_TARGET=$1
-T=$(fm_backend_resolve_selector "$RAW_TARGET" "$STATE")
 N=${2:-40}
 
+REMOTE_META=$(fm_backend_meta_for_selector "$RAW_TARGET" "$STATE" 2>/dev/null || true)
+if [ -n "$REMOTE_META" ] && [ -n "$(fm_meta_get "$REMOTE_META" remote_host)" ]; then
+  REMOTE_ID=${REMOTE_META##*/}
+  REMOTE_ID=${REMOTE_ID%.meta}
+  REMOTE_HOST=$(fm_meta_get "$REMOTE_META" remote_host)
+  case "$N" in ''|*[!0-9]*|0) N=40 ;; esac
+  [ "$N" -le 100 ] || N=100
+  if ! FM_HOME="$FM_HOME" "$SCRIPT_DIR/fm-on.sh" "$REMOTE_ID" \
+    fm-remote-secondmate-control.sh capture "$REMOTE_ID" "$N" < /dev/null; then
+    echo "error: could not read the remote pane of $REMOTE_ID on $REMOTE_HOST (host unreachable or endpoint unreadable; the mate is not thereby dead)" >&2
+    exit 1
+  fi
+  exit 0
+fi
+
+T=$(fm_backend_resolve_selector "$RAW_TARGET" "$STATE")
+
 BACKEND=$(fm_backend_of_selector "$RAW_TARGET" "$T" "$STATE")
 EXPECTED_LABEL=$(fm_backend_expected_label_of_selector "$RAW_TARGET" "$STATE")
 
diff --git a/bin/fm-remote-secondmate-control.sh b/bin/fm-remote-secondmate-control.sh
index f2edb32a7bb..aa17c952860 100755
--- a/bin/fm-remote-secondmate-control.sh
+++ b/bin/fm-remote-secondmate-control.sh
@@ -188,6 +188,12 @@ cmd_send() {
   validate_id "$id"
   validate_home "$id"
   remote_endpoint_require "$id"
+  # fm-send's exit status is the delivery verdict the parent home acts on
+  # (0 = confirmed, 3 = delivered with the submit read-back unconfirmed, other
+  # nonzero = failed; see bin/fm-send.sh's header). The job worker, entrypoint,
+  # and ssh all preserve it, so no mapping may happen here: flattening exit 3
+  # into a generic failure is exactly the false-negative the parent's remote
+  # send path exists to avoid.
   FM_HOME="$TARGET_HOME" FM_ROOT_OVERRIDE="$FM_ROOT" FM_STATE_OVERRIDE="$TARGET_HOME/state" \
     "$SCRIPT_DIR/fm-send.sh" "$REMOTE_ENDPOINT_TARGET" "$message"
 }
diff --git a/bin/fm-send.sh b/bin/fm-send.sh
index c46c55a340f..1da45d86f46 100755
--- a/bin/fm-send.sh
+++ b/bin/fm-send.sh
@@ -15,6 +15,12 @@
 # submit or reports an inconclusive send. If a swallowed Enter is positively
 # confirmed, fm-send exits NON-ZERO so the caller knows the steer did not land
 # instead of silently leaving an unsubmitted instruction.
+# Exit status contract: 0 = submit confirmed (or, for a remote secondmate
+# target, delivered with confirmation pending - see the remote paragraph);
+# 3 = the text was typed into the live endpoint and Enter was sent, but the
+# submit read-back stayed unconfirmed (verify the pane before any resend, and
+# never re-type blindly); any other nonzero = the send failed and nothing may
+# be assumed delivered.
 # Submission dispatches through the target's recorded backend; the tmux adapter
 # shares its composer/submit core with the away-mode daemon via bin/fm-tmux-lib.sh.
 # Tune with FM_SEND_RETRIES (default 3) / FM_SEND_SLEEP (0.4).
@@ -37,6 +43,20 @@
 # re-sending a recovery request for an already-open expectation so a second
 # record is not created. Direct unmarked captain input never creates one.
 #
+# Remote secondmate delivery: the send crosses fm-on.sh to a host-local leg
+# (bin/fm-remote-secondmate-control.sh cmd_send) that runs this same verified
+# submit against the recorded remote Herdr pane and relays its exit status
+# unchanged. A leg that delivered the text into the live verified pane but
+# could not synchronously confirm the submit (exit 3 - typically a busy mate
+# whose harness queues the steer and keeps rendering it) is reported here as
+# DELIVERED with confirmation pending: fm-send prints a non-error notice,
+# exits 0, marks the pending-reply expectation delivered, and closes any
+# --resolve-key decisions. Empirically that pattern is a delivered steer, a
+# resend duplicates the instruction, and the parent's pending-reply
+# recovery/escalation still surfaces the rare genuinely lost request. Transport
+# loss (ssh exit 255, completion unknown) and every real remote failure keep
+# failing loudly with the remote leg's own stderr attached.
+#
 # Decision closure (answerer-closes): pass --resolve-key <key> (repeatable,
 # before the message) when this send answers an open keyed needs-decision: or
 # blocked: record in the target task's state/<id>.status. After the submit is
@@ -63,7 +83,9 @@
 # in this home's status log per status_open_decisions (bin/fm-classify-lib.sh), or
 # an active captain hold for the target task. A key in neither is refused before
 # sending, so a mistyped key cannot deliver an answer while silently orphaning the
-# decision. A failed or unconfirmed send never closes a key; a
+# decision. A failed or unconfirmed send never closes a key (a remote
+# delivered-with-pending-confirmation outcome counts as delivered - see the
+# remote paragraph above); a
 # delivered answer whose closing append fails exits nonzero with the exact
 # manual close command, leaving the decision open to re-surface (the safe
 # direction). A send without the flag never closes anything: a routine steer,
@@ -537,12 +559,27 @@ else
   # Type once, submit, verify. Only exact empty confirms delivery; every other
   # verdict preserves the loud refusal boundary.
   send_rc=0
+  REMOTE_DELIVERY_NOTICE=0
   if [ "$TARGET_BACKEND" = remote ]; then
-    if "$SCRIPT_DIR/fm-on.sh" "$TARGET_REMOTE_ID" fm-remote-secondmate-control.sh send "$TARGET_REMOTE_ID" "$MESSAGE" < /dev/null >/dev/null; then
+    # The remote leg is this same script running host-locally against the
+    # recorded Herdr pane (cmd_send in fm-remote-secondmate-control.sh), so its
+    # submit verification IS the local one, and fm-on/the remote worker relay
+    # its exit status unchanged. Exit 3 is the delivered-unconfirmed contract
+    # (see this script's header) crossing the ssh boundary: the text reached
+    # the live verified pane and Enter was sent; only the synchronous read-back
+    # stayed unconfirmed. The remote stderr is held back and replayed only for
+    # a real failure, so a delivered outcome does not surface the inner leg's
+    # diagnostics as alarm.
+    remote_err=$("$SCRIPT_DIR/fm-on.sh" "$TARGET_REMOTE_ID" fm-remote-secondmate-control.sh send "$TARGET_REMOTE_ID" "$MESSAGE" < /dev/null 2>&1 >/dev/null) || send_rc=$?
+    if [ "$send_rc" -eq 0 ]; then
+      verdict=empty
+    elif [ "$send_rc" -eq 3 ]; then
       verdict=empty
+      send_rc=0
+      REMOTE_DELIVERY_NOTICE=1
     else
-      send_rc=$?
       verdict=send-failed
+      [ -z "$remote_err" ] || printf '%s\n' "$remote_err" >&2
     fi
   elif verdict=$(fm_backend_send_text_submit "$TARGET_BACKEND" "$T" "$MESSAGE" "$retries" "$sleep_s" "$settle" "$EXPECTED_LABEL"); then
     :
@@ -571,6 +608,19 @@ else
       echo "error: text not sent to $T ($TARGET_BACKEND send failed; tried $RESOLUTION_TRIED)" >&2
       exit 1
       ;;
+    pending)
+      # The text was typed into the live target and Enter was sent; only the
+      # submit read-back stayed unconfirmed (e.g. a busy harness queues the
+      # steer and keeps rendering it). That is not a proven failure, so never
+      # re-type the message: verify the pane instead. Exit 3 is the documented
+      # delivered-unconfirmed status, and the remote send leg above depends on
+      # it crossing the ssh boundary intact.
+      if [ "$PENDING_REPLY_CREATED" = 1 ] && [ -n "$PENDING_REPLY_CORR" ]; then
+        fm_pending_reply_discard_undelivered "$STATE" "$PENDING_REPLY_CORR" || true
+      fi
+      echo "fm-send: text delivered to $T but submission is unconfirmed (verdict=pending; tried $RESOLUTION_TRIED); do not retype or blindly resend - verify with fm-peek.sh, then re-send '--key Enter' only if the composer still holds the text" >&2
+      exit 3
+      ;;
     *)
       if [ "$PENDING_REPLY_CREATED" = 1 ] && [ -n "$PENDING_REPLY_CORR" ]; then
         fm_pending_reply_discard_undelivered "$STATE" "$PENDING_REPLY_CORR" || true
@@ -600,6 +650,12 @@ else
     fm_send_close_resolved_keys "$RESOLVE_ANSWER_TEXT" || exit 1
     fm_send_feed_resolved_holds "$RESOLVE_ANSWER_TEXT" || exit 1
   fi
+  # Remote delivered-with-pending-confirmation: the outcome above is treated as
+  # delivered (expectation marked, keys closed), and this one non-error notice
+  # carries the remaining nuance so nobody re-sends the steer.
+  if [ "$REMOTE_DELIVERY_NOTICE" = 1 ]; then
+    echo "fm-send: delivered to remote secondmate $TARGET_REMOTE_ID; the remote pane accepted the text and Enter, and only the synchronous submit confirmation is still pending. This is not a failure - do not resend; the pending-reply expectation stays armed." >&2
+  fi
   # Submit landed with exact empty. Confirmation only proves the text was
   # accepted; the harness still needs a beat to spin up the
   # turn before its busy footer shows. Pause so an immediate peek catches the
diff --git a/docs/remote-secondmates.md b/docs/remote-secondmates.md
index 5a38d48e52b..a1560e20b5d 100644
--- a/docs/remote-secondmates.md
+++ b/docs/remote-secondmates.md
@@ -168,6 +168,11 @@ Send routed requests normally:
 FM_HOME=<primary-home> bin/fm-send.sh fm-<id> '<request>'
 ```
 
+The [`fm-send.sh` header](../bin/fm-send.sh) owns the exact delivery-status contract.
+When the verified remote endpoint accepts the text and Enter but synchronous submit confirmation remains pending, the primary reports the request as delivered rather than failed; do not resend it, because its pending-reply expectation remains armed.
+`fm-peek.sh` and `fm-crew-state.sh` route remote-secondmate reads to the endpoint's host instead of consulting local worktree or backend state.
+An unreachable or unreadable remote read is unknown, not evidence that the endpoint is dead.
+
 Marked requests keep the existing correlation contract.
 The remote charter appends replies to `state/parent-replies.status` in the remote home.
 A process-event source performs a non-destructive, cursor-anchored delta read, fetches only referenced `data/*.md` documents through the confined reader, mirrors every content-bearing line at most once into the primary status channel, and does not carry blank separators.
@@ -231,6 +236,9 @@ The lifecycle test covers seeding a registered project that this machine has nev
 
 ```sh
 bin/fm-test-run.sh tests/fm-on.test.sh
+bin/fm-test-run.sh tests/fm-send-remote-delivery.test.sh
+bin/fm-test-run.sh tests/fm-peek-remote.test.sh
+bin/fm-test-run.sh tests/fm-crew-state.test.sh
 bin/fm-test-run.sh tests/fm-remote-job.test.sh
 bin/fm-test-run.sh tests/fm-remote-doctor.test.sh
 bin/fm-test-run.sh tests/fm-project-origin.test.sh
diff --git a/docs/tmux-backend.md b/docs/tmux-backend.md
index 4d8c3e75feb..c2acead0c2f 100644
--- a/docs/tmux-backend.md
+++ b/docs/tmux-backend.md
@@ -85,7 +85,7 @@ The supervisor guard selects only the detected primary harness's signature rathe
 It types a message once and retries Enter only until the composer clears.
 Only a proven empty composer is a positive delivery acknowledgement.
 Text left in established structure remains `pending`, text in ambiguous structure remains unproven, and unreadable or unsafe state remains unknown.
-`fm-send.sh` reports every unconfirmed verdict as a failure instead of retyping or assuming delivery.
+`fm-send.sh` never retypes or assumes a confirmed submit for an unconfirmed verdict; its header owns the distinct delivered-unconfirmed exit status and operator response.
 
 OpenCode 1.18.4 has one busy-queue exception.
 While OpenCode is mid-turn, Enter queues the message but leaves its text visible until the turn completes.
diff --git a/tests/fm-crew-state.test.sh b/tests/fm-crew-state.test.sh
index 8f986b6139e..602b3e5cfc3 100755
--- a/tests/fm-crew-state.test.sh
+++ b/tests/fm-crew-state.test.sh
@@ -1150,6 +1150,105 @@ test_torn_down_worktree() {
   pass "torn-down worktree is handled gracefully"
 }
 
+# --- remote secondmate arm ---------------------------------------------------
+# A meta recording remote_host= must never be read through the local worktree
+# probe or a local backend adapter: the recorded worktree and pane live on the
+# remote host, and the old local reads misreported a healthy remote mate as
+# "worktree gone". These cases drive the real helper over the real fm-on.sh
+# route with a stubbed ssh transport (FM_SSH_BIN seam): the stub prints
+# FM_FAKE_REMOTE_STATE_OUT as the remote endpoint's recovery-grade state and
+# exits FM_FAKE_SSH_RC.
+
+setup_remote_case() {  # <name> -> echoes case dir with remote meta + registry
+  local d
+  d=$(new_case "$1")
+  mkdir -p "$d/data" "$d/fakebin"
+  fm_write_meta "$d/state/rsm.meta" \
+    "window=remote:rsm" \
+    "endpoint_task_id=rsm" \
+    "worktree=/remote/home/never-locally-present" \
+    "harness=claude" \
+    "kind=secondmate" \
+    "mode=secondmate" \
+    "remote_host=remote-mac" \
+    "remote_root=/remote/root" \
+    "remote_backend=herdr" \
+    "remote_herdr_session=fm-remote" \
+    "remote_target=fm-remote:w1:p1"
+  cat > "$d/data/secondmates.md" <<EOF
+- rsm - remote test domain (host: remote-mac; root: /remote/root; home: /remote/home; scope: remote testing; projects: alpha; added 2026-08-02)
+EOF
+  cat > "$d/fakebin/fake-ssh" <<'SH'
+#!/usr/bin/env bash
+cat > /dev/null
+[ -z "${FM_FAKE_REMOTE_STATE_OUT:-}" ] || printf '%s\n' "$FM_FAKE_REMOTE_STATE_OUT"
+exit "${FM_FAKE_SSH_RC:-0}"
+SH
+  chmod +x "$d/fakebin/fake-ssh"
+  printf '%s\n' "$d"
+}
+
+run_remote_crew_state() {  # <case-dir> <id>
+  PATH="$1/fakebin:$PATH" FM_HOME="$1" FM_STATE_OVERRIDE="$1/state" \
+    FM_SSH_BIN="$1/fakebin/fake-ssh" "$CREW_STATE" "$2"
+}
+
+test_remote_alive_with_log_uses_status_log() {
+  reset_fakes
+  local d out rc
+  d=$(setup_remote_case remote-alive-log)
+  make_fakebin "$d" >/dev/null
+  printf 'working: refactoring the quota adapter\n' > "$d/state/rsm.status"
+  out=$(FM_FAKE_REMOTE_STATE_OUT=alive FM_FAKE_SSH_RC=0 run_remote_crew_state "$d" rsm); rc=$?
+  expect_code 0 "$rc" "remote alive exits 0"
+  assert_contains "$out" "state: working" "alive remote mate with a working log reads working"
+  assert_contains "$out" "source: status-log" "alive remote mate reads current activity from the routed log"
+  assert_contains "$out" "remote endpoint alive on remote-mac" "the remote liveness read should be visible"
+  assert_not_contains "$out" "worktree gone" "a healthy remote mate must never read as torn down"
+  pass "fm-crew-state remote: alive endpoint falls through to the routed status log"
+}
+
+test_remote_alive_idle_is_healthy_not_gone() {
+  reset_fakes
+  local d out rc
+  d=$(setup_remote_case remote-alive-idle)
+  make_fakebin "$d" >/dev/null
+  out=$(FM_FAKE_REMOTE_STATE_OUT=alive FM_FAKE_SSH_RC=0 run_remote_crew_state "$d" rsm); rc=$?
+  expect_code 0 "$rc" "remote alive-idle exits 0"
+  assert_contains "$out" "source: remote-endpoint" "the remote endpoint is the reported source"
+  assert_contains "$out" "alive on remote-mac" "an idle remote mate reads alive"
+  assert_not_contains "$out" "worktree gone" "a healthy remote mate must never read as torn down"
+  assert_not_contains "$out" "backend target gone" "a healthy remote mate must never read as a dead target"
+  pass "fm-crew-state remote: an idle alive endpoint reads alive, never gone or dead"
+}
+
+test_remote_unreachable_is_unknown_remote_not_dead() {
+  reset_fakes
+  local d out rc
+  d=$(setup_remote_case remote-unreachable)
+  make_fakebin "$d" >/dev/null
+  printf 'working: refactoring the quota adapter\n' > "$d/state/rsm.status"
+  out=$(FM_FAKE_SSH_RC=255 run_remote_crew_state "$d" rsm); rc=$?
+  expect_code 0 "$rc" "unreachable remote exits 0"
+  assert_contains "$out" "unknown-remote" "an unreachable remote must be labeled unknown-remote"
+  assert_contains "$out" "not proof of death" "an unreachable remote must not read as dead"
+  assert_not_contains "$out" "worktree gone" "an unreachable remote must never read as torn down"
+  assert_not_contains "$out" "backend target gone" "an unreachable remote must never read as a dead target"
+  pass "fm-crew-state remote: an unreachable host reads unknown-remote, never gone or dead"
+}
+
+test_remote_dead_reports_remote_verdict() {
+  reset_fakes
+  local d out rc
+  d=$(setup_remote_case remote-dead)
+  make_fakebin "$d" >/dev/null
+  out=$(FM_FAKE_REMOTE_STATE_OUT=dead FM_FAKE_SSH_RC=0 run_remote_crew_state "$d" rsm); rc=$?
+  expect_code 0 "$rc" "remote dead exits 0"
+  assert_contains "$out" "remote endpoint dead on remote-mac" \
+    "a genuinely dead remote endpoint reports the remote host's own verdict"
+  pass "fm-crew-state remote: the remote host's own dead verdict is reported truthfully"
+}
+
 test_missing_meta() {
   reset_fakes
   local d; d=$(new_case nometa)
@@ -1350,6 +1449,10 @@ test_dead_window_still_reports_active_run_step
 test_no_timeout_uses_perl_bound
 test_scout_skips_run_lookup
 test_torn_down_worktree
+test_remote_alive_with_log_uses_status_log
+test_remote_alive_idle_is_healthy_not_gone
+test_remote_unreachable_is_unknown_remote_not_dead
+test_remote_dead_reports_remote_verdict
 test_missing_meta
 test_provably_working_via_runs_list_fallback
 test_not_provably_working_when_stopped
diff --git a/tests/fm-daemon.test.sh b/tests/fm-daemon.test.sh
index 2fe02fb4318..ad0925be4d4 100755
--- a/tests/fm-daemon.test.sh
+++ b/tests/fm-daemon.test.sh
@@ -1569,27 +1569,37 @@ test_inject_wedge_alarm_throttles_when_marker_cannot_be_written() {
   pass "in-process wedge throttle prevents alert spam when the marker cannot persist"
 }
 
-test_fm_send_exits_nonzero_on_confirmed_swallow() {
-  # fm-send.sh must exit NON-ZERO when a steer's Enter is positively swallowed
-  # (text left in the composer), so firstmate learns the instruction did not land
-  # — and exit ZERO on a clean submit.
-  local dir fakebin err
+test_fm_send_reports_delivered_unconfirmed_submit() {
+  # When text was typed and Enter sent but the submit read-back remains pending,
+  # fm-send must return its documented delivered-unconfirmed status and prevent
+  # a duplicate resend reflex. A synchronously confirmed submit remains zero.
+  local dir fakebin err rc
   dir=$(make_bordered_case send-swallow)
   fakebin="$dir/fakebin"; err="$dir/send.err"
   # Clean submit -> exit 0.
   PATH="$fakebin:$PATH" FM_HOME="$dir" FM_STATE_OVERRIDE="$dir/state" FM_FAKE_COMPOSER="$dir/composer" \
     FM_SEND_SLEEP=0.05 "$ROOT/bin/fm-send.sh" sess:win 'route this work' >/dev/null 2>"$err" \
     || fail "fm-send exited non-zero on a clean submit: $(cat "$err")"
-  # Persistent swallow -> exit non-zero with a clear message.
+  # Persistent composer text after Enter -> delivered-unconfirmed exit 3 with
+  # a non-error warning that explicitly tells the operator not to resend.
   printf '╭─────╮\n│ >   │\n╰─────╯\n' > "$dir/composer"
   touch "$dir/.swallow"
   if PATH="$fakebin:$PATH" FM_HOME="$dir" FM_STATE_OVERRIDE="$dir/state" FM_FAKE_COMPOSER="$dir/composer" \
     FM_FAKE_SWALLOW="$dir/.swallow" FM_FAKE_PERSIST_SWALLOW=1 FM_SEND_SLEEP=0.05 \
     "$ROOT/bin/fm-send.sh" sess:win 'fix findings 1 and 3, skip 2' >/dev/null 2>"$err"; then
-    fail "fm-send exited zero despite a swallowed Enter (silent unsubmitted instruction)"
+    rc=0
+  else
+    rc=$?
+  fi
+  [ "$rc" -eq 3 ] || fail "fm-send returned $rc instead of delivered-unconfirmed exit 3: $(cat "$err")"
+  grep -F 'submission is unconfirmed' "$err" >/dev/null \
+    || fail "fm-send did not explain the pending confirmation: $(cat "$err")"
+  grep -F 'do not retype or blindly resend' "$err" >/dev/null \
+    || fail "fm-send did not prevent a duplicate resend: $(cat "$err")"
+  if grep -F 'error:' "$err" >/dev/null; then
+    fail "fm-send mislabeled delivered-unconfirmed as an error: $(cat "$err")"
   fi
-  grep -F 'not submitted' "$err" >/dev/null || fail "fm-send did not explain the swallowed submit: $(cat "$err")"
-  pass "fm-send exits non-zero on a confirmed swallow, zero on a clean submit"
+  pass "fm-send returns 3 with a non-error no-resend warning when confirmation stays pending"
 }
 
 test_fm_send_exits_nonzero_on_initial_send_failure() {
@@ -1916,7 +1926,7 @@ test_wedge_alarm_hung_override_times_out_and_falls_through
 test_wedge_alarm_shutdown_stops_active_notifier_group
 test_inject_wedge_alarm_fires_active_alert_on_non_tmux_backend
 test_inject_wedge_alarm_throttles_when_marker_cannot_be_written
-test_fm_send_exits_nonzero_on_confirmed_swallow
+test_fm_send_reports_delivered_unconfirmed_submit
 test_fm_send_exits_nonzero_on_initial_send_failure
 test_fm_send_exits_nonzero_on_unproven_submit
 test_discover_supervisor_backend_precedence
diff --git a/tests/fm-peek-remote.test.sh b/tests/fm-peek-remote.test.sh
new file mode 100755
index 00000000000..7ef7286fb23
--- /dev/null
+++ b/tests/fm-peek-remote.test.sh
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# fm-peek remote-secondmate capture routing.
+#
+# A remote secondmate's pane lives on its own host. The old path resolved the
+# meta's "remote:<id>" window through the local backend adapters and handed it
+# to tmux, which failed with "can't find session: remote" - a healthy remote
+# mate misreported as an unreadable endpoint. These tests drive the real
+# fm-peek + fm-on executables with a stubbed ssh transport (FM_SSH_BIN seam)
+# and a poisoned local tmux, pinning:
+#   1. A remote selector routes the capture over the remote transport and
+#      prints the remote pane tail; the local adapters are never consulted.
+#   2. An unreachable host fails loudly naming the host, without claiming the
+#      mate is dead.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+PEEK="$ROOT/bin/fm-peek.sh"
+
+TMP_ROOT=$(fm_test_tmproot fm-peek-remote)
+
+# fake-ssh prints the canned remote capture; the poisoned tmux records any
+# local read attempt so the "never consulted" property is a real assertion.
+make_stubs() {  # <dir> -> echoes fakebin dir
+  local dir=$1 fb="$1/fakebin"
+  mkdir -p "$fb"
+  cat > "$fb/fake-ssh" <<'SH'
+#!/usr/bin/env bash
+cat > /dev/null
+[ -z "${FM_FAKE_REMOTE_CAPTURE:-}" ] || printf '%s\n' "$FM_FAKE_REMOTE_CAPTURE"
+exit "${FM_FAKE_SSH_RC:-0}"
+SH
+  chmod +x "$fb/fake-ssh"
+  cat > "$fb/tmux" <<'SH'
+#!/usr/bin/env bash
+printf 'tmux\n' >> "${FM_FAKE_TMUX_TOUCHED:?}"
+exit 1
+SH
+  chmod +x "$fb/tmux"
+  printf '%s\n' "$fb"
+}
+
+setup_remote_home() {  # <name> -> echoes home dir with remote meta + registry
+  local home="$TMP_ROOT/$1-$RANDOM"
+  mkdir -p "$home/state" "$home/data"
+  fm_write_meta "$home/state/rsm.meta" \
+    "window=remote:rsm" \
+    "endpoint_task_id=rsm" \
+    "harness=claude" \
+    "kind=secondmate" \
+    "mode=secondmate" \
+    "remote_host=remote-mac" \
+    "remote_root=/remote/root" \
+    "remote_backend=herdr" \
+    "remote_herdr_session=fm-remote" \
+    "remote_target=fm-remote:w1:p1"
+  cat > "$home/data/secondmates.md" <<EOF
+- rsm - remote test domain (host: remote-mac; root: /remote/root; home: /remote/home; scope: remote testing; projects: alpha; added 2026-08-02)
+EOF
+  printf '%s\n' "$home"
+}
+
+test_remote_peek_reads_remote_pane() {
+  local dir fb home touched rc out
+  dir="$TMP_ROOT/peek-ok"; mkdir -p "$dir"
+  fb=$(make_stubs "$dir")
+  home=$(setup_remote_home peek-ok)
+  touched="$dir/tmux-touched"; : > "$touched"
+
+  out=$(env PATH="$fb:$PATH" \
+    FM_HOME="$home" FM_STATE_OVERRIDE="$home/state" \
+    FM_SSH_BIN="$fb/fake-ssh" FM_FAKE_SSH_RC=0 \
+    FM_FAKE_REMOTE_CAPTURE='● the remote mate is mid-refactor' \
+    FM_FAKE_TMUX_TOUCHED="$touched" \
+    "$PEEK" rsm 20 2>"$dir/err"); rc=$?
+  expect_code 0 "$rc" "a healthy remote peek should succeed"
+  assert_contains "$out" "the remote mate is mid-refactor" \
+    "the remote pane tail should be printed"
+  assert_not_contains "$out" "can't find session" \
+    "a remote peek must not fall into a local session lookup"
+  [ ! -s "$touched" ] || fail "the local tmux adapter was consulted for a remote target"
+  pass "fm-peek remote: the capture routes over the remote transport, local adapters untouched"
+}
+
+test_remote_peek_unreachable_fails_loudly_without_death_claim() {
+  local dir fb home touched rc err
+  dir="$TMP_ROOT/peek-down"; mkdir -p "$dir"
+  fb=$(make_stubs "$dir")
+  home=$(setup_remote_home peek-down)
+  touched="$dir/tmux-touched"; : > "$touched"
+
+  env PATH="$fb:$PATH" \
+    FM_HOME="$home" FM_STATE_OVERRIDE="$home/state" \
+    FM_SSH_BIN="$fb/fake-ssh" FM_FAKE_SSH_RC=255 \
+    FM_FAKE_TMUX_TOUCHED="$touched" \
+    "$PEEK" rsm >"$dir/out" 2>"$dir/err"; rc=$?
+  err=$(cat "$dir/err")
+  [ "$rc" -ne 0 ] || fail "an unreachable remote peek must exit nonzero"
+  assert_contains "$err" "remote pane of rsm on remote-mac" \
+    "the failure must name the remote mate and host"
+  assert_contains "$err" "not thereby dead" \
+    "an unreadable remote pane must not be presented as a dead mate"
+  pass "fm-peek remote: an unreachable host fails loudly without a false death claim"
+}
+
+test_remote_peek_reads_remote_pane
+test_remote_peek_unreachable_fails_loudly_without_death_claim
+
+echo "all fm-peek-remote tests passed"
diff --git a/tests/fm-send-remote-delivery.test.sh b/tests/fm-send-remote-delivery.test.sh
new file mode 100755
index 00000000000..af546fbb4a4
--- /dev/null
+++ b/tests/fm-send-remote-delivery.test.sh
@@ -0,0 +1,285 @@
+#!/usr/bin/env bash
+# fm-send remote-secondmate delivery reporting.
+#
+# The remote send leg (fm-on.sh -> fm-remote-secondmate-control.sh cmd_send)
+# runs fm-send's own verified submit host-locally on the remote machine and
+# relays its exit status unchanged. A leg that delivered the text into the
+# live verified pane but could not synchronously confirm the submit exits 3
+# (the delivered-unconfirmed contract in bin/fm-send.sh's header); flattening
+# that into a generic failure produced the false "error: text not sent"
+# report that tempted duplicate resends of steers that had actually landed.
+# These tests pin the delivery-reporting contract over the real fm-send +
+# fm-on executables with a stubbed ssh transport (FM_SSH_BIN seam - the same
+# process boundary tests/fm-on.test.sh proves preserves exit status):
+#   1. Remote delivered-unconfirmed (ssh exit 3) is NOT a failure: exit 0, a
+#      non-error delivered notice, the inner leg's stderr held back, and the
+#      pending-reply expectation marked delivered (awaiting_report).
+#   2. A real remote failure (nonzero, not 3/255) still fails loudly with the
+#      remote stderr replayed and the undelivered expectation discarded.
+#   3. Transport-unknown (ssh exit 255) still refuses loudly and preserves the
+#      expectation as delivery_unknown.
+#   4. A delivered-unconfirmed remote answer still closes its --resolve-key
+#      decision (delivered-with-pending-confirmation counts as delivered).
+#   5. A LOCAL send whose submit read-back stays pending exits 3 with an
+#      honest non-error message (text delivered, submission unconfirmed).
+#   6. That local unconfirmed send still never closes a --resolve-key
+#      decision (the local ledger boundary is unchanged).
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+SEND="$ROOT/bin/fm-send.sh"
+DRAIN="$ROOT/bin/fm-wake-drain.sh"
+
+TMP_ROOT=$(fm_test_tmproot fm-send-remote-delivery)
+
+# Stub tmux for the local legs: logs literal typed text to FM_SEND_LOG. The
+# default composer reads empty (clean submit); FM_FAKE_TMUX_PENDING=1 keeps a
+# proven pending composer with no busy footer, so the real submit core
+# exhausts its Enter budget and reports the pending verdict. The ssh stub
+# records the invocation, emits FM_FAKE_SSH_STDERR as the remote leg's stderr,
+# and exits FM_FAKE_SSH_RC - the exact relay contract the real transport
+# preserves.
+make_stubs() {  # <dir> -> echoes fakebin dir
+  local dir=$1 fb="$1/fakebin"
+  mkdir -p "$fb"
+  cat > "$fb/tmux" <<'SH'
+#!/usr/bin/env bash
+set -u
+case "${1:-}" in
+  send-keys)
+    shift
+    literal=0
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        -t) shift 2 ;;
+        -l) literal=1; shift ;;
+        *) break ;;
+      esac
+    done
+    if [ "$literal" = 1 ]; then
+      printf '%s' "${1:-}" >> "$FM_SEND_LOG"
+    fi
+    exit 0 ;;
+  display-message)
+    for a in "$@"; do case "$a" in *cursor_y*) printf '1\n'; exit 0 ;; esac; done
+    printf 'fakepane\n'; exit 0 ;;
+  capture-pane)
+    if [ "${FM_FAKE_TMUX_PENDING:-0}" = 1 ]; then
+      printf '╭────────────╮\n│ > steer    │\n╰────────────╯\n'
+    else
+      printf '╭────╮\n│    │\n╰────╯\n'
+    fi
+    exit 0 ;;
+  list-windows) exit 0 ;;
+esac
+exit 0
+SH
+  chmod +x "$fb/tmux"
+  cat > "$fb/sleep" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+  chmod +x "$fb/sleep"
+  cat > "$fb/fake-ssh" <<'SH'
+#!/usr/bin/env bash
+cat > /dev/null
+printf '%s\n' "$*" >> "$FM_SSH_LOG"
+[ -z "${FM_FAKE_SSH_STDERR:-}" ] || printf '%s\n' "$FM_FAKE_SSH_STDERR" >&2
+exit "${FM_FAKE_SSH_RC:-0}"
+SH
+  chmod +x "$fb/fake-ssh"
+  printf '%s\n' "$fb"
+}
+
+setup_home() {  # <name> -> echoes a fresh home dir with an empty state/
+  local home="$TMP_ROOT/$1-$RANDOM"
+  mkdir -p "$home/state"
+  printf '%s\n' "$home"
+}
+
+# A home with a remote-secondmate task meta plus the registry row fm-on.sh
+# resolves the ssh route from - the same shape a live remote mate records.
+setup_remote_home() {  # <name> -> echoes home dir
+  local home
+  home=$(setup_home "$1")
+  mkdir -p "$home/data"
+  fm_write_meta "$home/state/rsm.meta" \
+    "window=fm-remote:w1:p1" \
+    "endpoint_task_id=rsm" \
+    "harness=claude" \
+    "kind=secondmate" \
+    "mode=secondmate" \
+    "yolo=off" \
+    "remote_host=remote-mac" \
+    "remote_root=/remote/root" \
+    "remote_backend=herdr" \
+    "remote_herdr_session=fm-remote" \
+    "remote_target=fm-remote:w1:p1"
+  cat > "$home/data/secondmates.md" <<EOF
+- rsm - remote test domain (host: remote-mac; root: /remote/root; home: /remote/home; scope: remote testing; projects: alpha; added 2026-08-02)
+EOF
+  printf '%s\n' "$home"
+}
+
+# The single non-dot pending-reply record in <home>, or empty.
+pending_record() {  # <home>
+  find "$1/state/pending-replies" -maxdepth 1 -type f ! -name '.*' 2>/dev/null | head -1
+}
+
+drain_out() {  # <home>
+  FM_STATE_OVERRIDE="$1/state" "$DRAIN" 2>/dev/null
+}
+
+test_remote_delivered_unconfirmed_is_not_failure() {
+  local dir fb log ssh_log home rc err rec
+  dir="$TMP_ROOT/remote-du"; mkdir -p "$dir"
+  fb=$(make_stubs "$dir"); log="$dir/send.log"; ssh_log="$dir/ssh.log"; : > "$ssh_log"
+  home=$(setup_remote_home remote-du)
+
+  : > "$log"
+  env PATH="$fb:$PATH" \
+    FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" FM_SEND_LOG="$log" FM_SEND_SETTLE=0 \
+    FM_SSH_BIN="$fb/fake-ssh" FM_SSH_LOG="$ssh_log" FM_FAKE_SSH_RC=3 \
+    FM_FAKE_SSH_STDERR='fm-send: text delivered to fm-remote:w1:p1 but submission is unconfirmed (verdict=pending; tried meta=/remote/home/state/fm-remote:w1:p1.meta; metadata window/terminal lookup; backend=herdr; endpoint=verified)' \
+    "$SEND" rsm "please rename the metric" >"$dir/out" 2>"$dir/err"; rc=$?
+  err=$(cat "$dir/err")
+  expect_code 0 "$rc" "a delivered-unconfirmed remote send must not exit as a failure"
+  assert_grep 'fm-remote-entrypoint.sh' "$ssh_log" "the steer should cross the remote transport"
+  assert_contains "$err" "delivered to remote secondmate rsm" \
+    "the outcome must be reported as delivered"
+  assert_not_contains "$err" "text not sent" "a delivered steer must not read as not sent"
+  assert_not_contains "$err" "not submitted" "a delivered steer must not read as not submitted"
+  assert_not_contains "$err" "error: text" "a delivered steer must not carry an error-styled report"
+  assert_not_contains "$err" "verdict=pending" \
+    "the inner leg's unconfirmed diagnostics must be held back on a delivered outcome"
+
+  rec=$(pending_record "$home")
+  [ -n "$rec" ] || fail "the pending-reply expectation must survive a delivered-unconfirmed send"
+  [ -n "$(grep '^delivered_epoch=' "$rec" | cut -d= -f2-)" ] \
+    || fail "a delivered-unconfirmed send must mark the expectation delivered: $(cat "$rec")"
+  [ "$(grep '^phase=' "$rec" | tail -1 | cut -d= -f2-)" = awaiting_report ] \
+    || fail "a delivered-unconfirmed send must leave the expectation awaiting its report: $(cat "$rec")"
+  pass "fm-send remote: delivered-unconfirmed reports delivered, exits 0, keeps the expectation armed"
+}
+
+test_remote_real_failure_still_fails() {
+  local dir fb log ssh_log home rc err
+  dir="$TMP_ROOT/remote-fail"; mkdir -p "$dir"
+  fb=$(make_stubs "$dir"); log="$dir/send.log"; ssh_log="$dir/ssh.log"; : > "$ssh_log"
+  home=$(setup_remote_home remote-fail)
+
+  : > "$log"
+  env PATH="$fb:$PATH" \
+    FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" FM_SEND_LOG="$log" FM_SEND_SETTLE=0 \
+    FM_SSH_BIN="$fb/fake-ssh" FM_SSH_LOG="$ssh_log" FM_FAKE_SSH_RC=1 \
+    FM_FAKE_SSH_STDERR='error: remote secondmate rsm endpoint metadata is invalid; refusing access until it is explicitly migrated' \
+    "$SEND" rsm "please rename the metric" >"$dir/out" 2>"$dir/err"; rc=$?
+  err=$(cat "$dir/err")
+  [ "$rc" -ne 0 ] || fail "a genuinely failed remote send must exit nonzero"
+  assert_contains "$err" "error: text not sent to remote:rsm" \
+    "a real remote failure must still report a real error"
+  assert_contains "$err" "endpoint metadata is invalid" \
+    "a real remote failure must replay the remote leg's own stderr"
+  [ -z "$(pending_record "$home")" ] \
+    || fail "a failed send must discard its undelivered expectation"
+  pass "fm-send remote: a real remote failure still fails loudly with the remote diagnostics"
+}
+
+test_remote_transport_unknown_preserves_expectation() {
+  local dir fb log ssh_log home rc err rec
+  dir="$TMP_ROOT/remote-255"; mkdir -p "$dir"
+  fb=$(make_stubs "$dir"); log="$dir/send.log"; ssh_log="$dir/ssh.log"; : > "$ssh_log"
+  home=$(setup_remote_home remote-255)
+
+  : > "$log"
+  env PATH="$fb:$PATH" \
+    FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" FM_SEND_LOG="$log" FM_SEND_SETTLE=0 \
+    FM_SSH_BIN="$fb/fake-ssh" FM_SSH_LOG="$ssh_log" FM_FAKE_SSH_RC=255 \
+    "$SEND" rsm "please rename the metric" >"$dir/out" 2>"$dir/err"; rc=$?
+  err=$(cat "$dir/err")
+  [ "$rc" -ne 0 ] || fail "an unknown-completion transport loss must exit nonzero"
+  assert_contains "$err" "delivery to remote secondmate rsm is unknown" \
+    "transport loss must be reported as unknown delivery, not silently dropped"
+  rec=$(pending_record "$home")
+  [ -n "$rec" ] || fail "transport loss must preserve the expectation for reconciliation"
+  [ "$(grep '^phase=' "$rec" | tail -1 | cut -d= -f2-)" = delivery_unknown ] \
+    || fail "transport loss must move the expectation to delivery_unknown: $(cat "$rec")"
+  pass "fm-send remote: ssh 255 still refuses loudly and preserves the expectation as delivery_unknown"
+}
+
+test_remote_delivered_unconfirmed_closes_resolve_key() {
+  local dir fb log ssh_log home rc out
+  dir="$TMP_ROOT/remote-key"; mkdir -p "$dir"
+  fb=$(make_stubs "$dir"); log="$dir/send.log"; ssh_log="$dir/ssh.log"; : > "$ssh_log"
+  home=$(setup_remote_home remote-key)
+  printf 'needs-decision [key=upgrade-window]: tonight or the weekend\n' > "$home/state/rsm.status"
+
+  : > "$log"
+  env PATH="$fb:$PATH" \
+    FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" FM_SEND_LOG="$log" FM_SEND_SETTLE=0 \
+    FM_SSH_BIN="$fb/fake-ssh" FM_SSH_LOG="$ssh_log" FM_FAKE_SSH_RC=3 \
+    "$SEND" rsm --resolve-key upgrade-window "the weekend, freeze Friday" >/dev/null 2>&1; rc=$?
+  expect_code 0 "$rc" "a delivered-unconfirmed remote answer must not exit as a failure"
+  grep -F 'resolved [key=upgrade-window]: answered: the weekend, freeze Friday' "$home/state/rsm.status" >/dev/null \
+    || fail "a delivered-unconfirmed remote answer must close the decision: $(cat "$home/state/rsm.status")"
+  out=$(drain_out "$home")
+  if printf '%s' "$out" | grep -F 'OPEN DECISIONS' >/dev/null; then
+    fail "the answered decision still lists as open after a delivered-unconfirmed answer: $out"
+  fi
+  pass "fm-send remote: a delivered-unconfirmed answer closes its --resolve-key decision"
+}
+
+test_local_pending_reports_delivered_unconfirmed() {
+  local dir fb log home rc err
+  dir="$TMP_ROOT/local-pending"; mkdir -p "$dir"
+  fb=$(make_stubs "$dir"); log="$dir/send.log"
+  home=$(setup_home local-pending)
+  fm_write_meta "$home/state/t1.meta" "window=sess:fm-t1" "kind=ship"
+
+  : > "$log"
+  env PATH="$fb:$PATH" FM_FAKE_TMUX_PENDING=1 \
+    FM_ROOT_OVERRIDE="$home" FM_HOME="$home" FM_SEND_LOG="$log" FM_SEND_SETTLE=0 \
+    "$SEND" t1 "steer text" >"$dir/out" 2>"$dir/err"; rc=$?
+  err=$(cat "$dir/err")
+  expect_code 3 "$rc" "an unconfirmed local submit must exit with the delivered-unconfirmed status"
+  assert_contains "$err" "submission is unconfirmed" \
+    "the unconfirmed local submit must be described honestly"
+  assert_not_contains "$err" "not submitted" \
+    "an unconfirmed local submit must not claim the text was not submitted"
+  assert_not_contains "$err" "error:" \
+    "an unconfirmed local submit must not carry an error-styled report"
+  pass "fm-send local: an unconfirmed submit exits 3 with an honest non-error report"
+}
+
+test_local_pending_does_not_close_resolve_key() {
+  local dir fb log home rc out
+  dir="$TMP_ROOT/local-pending-key"; mkdir -p "$dir"
+  fb=$(make_stubs "$dir"); log="$dir/send.log"
+  home=$(setup_home local-pending-key)
+  fm_write_meta "$home/state/t2.meta" "window=sess:fm-t2" "kind=ship"
+  printf 'blocked [key=creds]: need the deploy token\n' > "$home/state/t2.status"
+
+  : > "$log"
+  env PATH="$fb:$PATH" FM_FAKE_TMUX_PENDING=1 \
+    FM_ROOT_OVERRIDE="$home" FM_HOME="$home" FM_SEND_LOG="$log" FM_SEND_SETTLE=0 \
+    "$SEND" t2 --resolve-key creds "token is in the vault now" >/dev/null 2>&1; rc=$?
+  expect_code 3 "$rc" "an unconfirmed local answer must exit with the delivered-unconfirmed status"
+  if grep -F 'resolved' "$home/state/t2.status" >/dev/null; then
+    fail "an unconfirmed local answer must not close the decision: $(cat "$home/state/t2.status")"
+  fi
+  out=$(drain_out "$home")
+  printf '%s' "$out" | grep -F '[key=creds]' >/dev/null \
+    || fail "the blocker must stay open after an unconfirmed local answer: $out"
+  pass "fm-send local: an unconfirmed submit still never closes a --resolve-key decision"
+}
+
+test_remote_delivered_unconfirmed_is_not_failure
+test_remote_real_failure_still_fails
+test_remote_transport_unknown_preserves_expectation
+test_remote_delivered_unconfirmed_closes_resolve_key
+test_local_pending_reports_delivered_unconfirmed
+test_local_pending_does_not_close_resolve_key
+
+echo "all fm-send-remote-delivery tests passed"

From 918709db0e0c534ce5ff81d4ee8c614fb0008f94 Mon Sep 17 00:00:00 2001
From: Zeeshan Ahmed <ahmad.zeeshaan@gmail.com>
Date: Mon, 24 Aug 2026 18:20:11 +0300
Subject: [PATCH 10/12] no-mistakes(review): Fix stdin leak in keyed-answer
 replay and forward corrupted-binding diagnostics

---
 bin/fm-decision-hold.sh |  2 +-
 bin/fm-procevent.sh     | 20 ++++++++++++++------
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/bin/fm-decision-hold.sh b/bin/fm-decision-hold.sh
index 1414107d559..28c6d8ddb1b 100755
--- a/bin/fm-decision-hold.sh
+++ b/bin/fm-decision-hold.sh
@@ -784,7 +784,7 @@ command_answers() {
     hold="$origin-decision-$key"
     keyed_decision_text "$source" "$key" "$answer" "$label" > "$tmp" \
       || fail "cannot stage the captain decision for $hold"
-    if "$0" answer "$origin" "$key" --decision-file "$tmp" >/dev/null 2>"$err"; then
+    if "$0" answer "$origin" "$key" --decision-file "$tmp" < /dev/null >/dev/null 2>"$err"; then
       printf 'closed: %s\n' "$hold"
       closed=$((closed + 1))
     else
diff --git a/bin/fm-procevent.sh b/bin/fm-procevent.sh
index 1061859e3ce..32c17e94666 100755
--- a/bin/fm-procevent.sh
+++ b/bin/fm-procevent.sh
@@ -173,15 +173,23 @@ adapter_autohandle() {  # <adapter> <source-id> <result-file>
 
 # Pass a bound source's captured result to the one keyed-answer intake. The
 # adapter turns its own format into keyed lines; the intake owns everything those
-# lines mean. Silenced and best-effort exactly like the seams above: an unbound
-# source, an adapter with no `answers` command, and a failure on either side all
-# leave the capture untouched and still announced, because this never
-# acknowledges anything (see the keyed-answer note in the header).
+# lines mean. Best-effort exactly like the seams above: an unbound source, an
+# adapter with no `answers` command, and a failure on either side all leave the
+# capture untouched and still announced, because this never acknowledges
+# anything (see the keyed-answer note in the header). The binding lookup itself
+# stays loud on a corrupted record rather than silenced, per read_binding's own
+# contract in fm-decision-hold.sh.
 feed_keyed_answers() {  # <adapter> <source-id> <result-file>
-  local adapter=$1 id=$2 result=$3 script origin seq
+  local adapter=$1 id=$2 result=$3 script origin seq err
   script=$(adapter_script "$adapter")
   [ -f "$script" ] && [ ! -L "$script" ] || return 1
-  origin=$("$SCRIPT_DIR/fm-decision-hold.sh" binding "$id" 2>/dev/null) || return 1
+  err=$(mktemp "${TMPDIR:-/tmp}/fm-procevent-binding-err.XXXXXX") || return 1
+  if ! origin=$("$SCRIPT_DIR/fm-decision-hold.sh" binding "$id" 2>"$err"); then
+    [ -s "$err" ] && cat -- "$err" >&2
+    rm -f -- "$err"
+    return 1
+  fi
+  rm -f -- "$err"
   [ -n "$origin" ] || return 1
   seq=$(fm_procevent_result_sequence "$result") || return 1
   "$script" answers "$result" 2>/dev/null \

From 54a52d48830852b9f29c4b4b3e24c14b518458ee Mon Sep 17 00:00:00 2001
From: Zeeshan Ahmed <ahmad.zeeshaan@gmail.com>
Date: Mon, 24 Aug 2026 18:27:37 +0300
Subject: [PATCH 11/12] no-mistakes(review): Harden binding-error tempfile
 permissions with umask 077

---
 bin/fm-procevent.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bin/fm-procevent.sh b/bin/fm-procevent.sh
index 32c17e94666..04412c6583a 100755
--- a/bin/fm-procevent.sh
+++ b/bin/fm-procevent.sh
@@ -183,7 +183,7 @@ feed_keyed_answers() {  # <adapter> <source-id> <result-file>
   local adapter=$1 id=$2 result=$3 script origin seq err
   script=$(adapter_script "$adapter")
   [ -f "$script" ] && [ ! -L "$script" ] || return 1
-  err=$(mktemp "${TMPDIR:-/tmp}/fm-procevent-binding-err.XXXXXX") || return 1
+  err=$(umask 077; mktemp "${TMPDIR:-/tmp}/fm-procevent-binding-err.XXXXXX") || return 1
   if ! origin=$("$SCRIPT_DIR/fm-decision-hold.sh" binding "$id" 2>"$err"); then
     [ -s "$err" ] && cat -- "$err" >&2
     rm -f -- "$err"

From d4fa71ecc8ecc72b33f2a9fc63edf3bae53af598 Mon Sep 17 00:00:00 2001
From: Zeeshan Ahmed <ahmad.zeeshaan@gmail.com>
Date: Mon, 24 Aug 2026 18:53:26 +0300
Subject: [PATCH 12/12] no-mistakes(document): Add corrupted-binding regression
 to decision-hold-lifecycle verification record

---
 docs/decision-hold-lifecycle.md          |  3 +
 tests/fm-decision-hold-lifecycle.test.sh | 93 ++++++++++++++++++++++++
 2 files changed, 96 insertions(+)

diff --git a/docs/decision-hold-lifecycle.md b/docs/decision-hold-lifecycle.md
index 67ddc5ce555..6df2992cde8 100644
--- a/docs/decision-hold-lifecycle.md
+++ b/docs/decision-hold-lifecycle.md
@@ -87,6 +87,7 @@ Additional quoted `blocked_by` regression verification date: 2026-07-17.
 Plural blocker-readiness and mixed-home projection verification date: 2026-07-22.
 Unrouted close-path verification date: 2026-08-13.
 Answer-time closure verification date: 2026-08-16.
+Corrupted-binding diagnostic forwarding verification date: 2026-08-24.
 
 The focused end-to-end regression uses only synthetic `sample` identities and decision text.
 It begins with a completed investigation and visual review whose genuine unresolved choice exists only in the report.
@@ -104,6 +105,7 @@ A bound source whose origin exposes six holds captures one review carrying five
 Four holds whose answers route no work close, the one still blocking routed work is skipped and stays available to `resolve`, and the one whose key appears only inside the freeform prose never closes.
 The capture is left unacknowledged throughout, so the wake firstmate needs in order to act on the answers is never retired.
 A replayed delivery closes nothing new and is not rejected as a different decision, a source with no binding closes nothing at all, and the `answer` subcommand itself refuses an empty or missing decision file, an absent hold, and a drifted retry.
+A further regression corrupts a binding record's schema on disk and proves the binding lookup fails loud with a forwarded diagnostic instead of masquerading as an unbound source, while a genuinely unbound source alongside it still prints no diagnostic at all.
 A separate regression drives the real `fm-send` over a stubbed transport to prove the chat channel reaches the same intake for a decision already transferred to its hold, which the status ledger alone can no longer close.
 
 The final verification commands and their exact summarized outputs follow.
@@ -124,6 +126,7 @@ ok - main-home and secondmate-home captain holds remain correctly routed
 ok - resolve matches first/middle/last in quoted blocked_by and rejects a genuinely absent id
 ok - a bound channel's captured answers close their captain holds at answer time
 ok - a channel source with no decision binding closes nothing
+ok - a corrupted binding record forwards its diagnostic instead of silently acting as unbound
 ok - the answer path keeps every guard the unrouted close path already had
 ok - the chat channel feeds the same keyed-answer intake a captured review does
 
diff --git a/tests/fm-decision-hold-lifecycle.test.sh b/tests/fm-decision-hold-lifecycle.test.sh
index 9763de1c27d..da4dab17a01 100755
--- a/tests/fm-decision-hold-lifecycle.test.sh
+++ b/tests/fm-decision-hold-lifecycle.test.sh
@@ -994,6 +994,98 @@ EOF
   pass "a channel source with no decision binding closes nothing"
 }
 
+# read_binding's own contract (fm-decision-hold.sh) treats an unreadable or
+# wrong-schema binding record as a hard error, never a silent "unbound" -
+# feeding nothing is the safe direction only when it is a deliberate choice.
+# The captured-result channel (fm-procevent.sh feed_keyed_answers) must forward
+# that diagnostic instead of swallowing it, while a genuinely unbound source
+# alongside it stays exactly as silent as before, so the loud path is specific
+# to corruption and does not leak into the ordinary unbound case.
+test_corrupted_binding_forwards_its_diagnostic() {
+  local home id result out err show
+  home=$(make_home procevent-corrupted-binding)
+  id=sample-corrupted-binding
+  mkdir -p "$home/data/$id"
+  tasks_in "$home" add "$id" "Review sample with a corrupted binding" --kind scout --repo sample --start >/dev/null \
+    || fail "could not create the corrupted-binding origin"
+  write_origin_meta "$home" "$id"
+  printf 'done: deck ready\n' > "$home/state/$id.status"
+  printf '# Corrupted binding review\n\nOne captain choice remains.\n' > "$home/data/$id/report.md"
+  run_decisions "$home" hold "$id" only-choice \
+    --title "Captain call: only-choice" --reason "captain only-choice pending" --repo sample >/dev/null \
+    || fail "could not register the hold"
+
+  run_decisions "$home" bind fixture-src "$id" >/dev/null \
+    || fail "could not bind the fixture source to its origin"
+  [ "$(run_decisions "$home" binding fixture-src)" = "$id" ] \
+    || fail "the binding did not resolve before it was corrupted"
+  # Corrupt the record on disk the way a stale or incompatible schema would,
+  # not by removing it - removal is the already-covered unbound case.
+  printf 'schema=fm-decision-binding.v0\norigin=%s\n' "$id" > "$home/state/decision-bindings/fixture-src.origin"
+
+  mkdir -p "$home/state/procevent-inbox"
+  result="$home/state/procevent-inbox/fixture-src.1.result"
+  cat > "$result" <<'EOF'
+session:
+  file: /review.html
+  status: feedback
+prompts[1]{uid,prompt,selector,tag,text}:
+  "2","Only choice: yes\n\nContext data:\n{\n  \"question\": \"only-choice\",\n  \"answer\": \"yes\"\n}","form",choice,"Only choice: yes"
+EOF
+
+  mkdir -p "$home/adapter-root/bin"
+  cat > "$home/adapter-root/bin/fm-procevent-fixturechan.sh" <<SH
+#!/usr/bin/env bash
+# Fixture channel: reports keyed captain answers and nothing else.
+case "\${1-}" in
+  answers) exec "$ROOT/bin/fm-procevent-lavish.sh" answers "\${2-}" ;;
+esac
+exit 2
+SH
+  chmod +x "$home/adapter-root/bin/fm-procevent-fixturechan.sh"
+
+  PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$home/adapter-root" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_PROCEVENT_CLAIM_ROOT="$home/procevent-claims" \
+    "$ROOT/bin/fm-procevent.sh" register fixturechan fixture-src -- cat "$result" >/dev/null \
+    || fail "could not register the fixture channel source"
+  out=$(PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$home/adapter-root" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_PROCEVENT_CLAIM_ROOT="$home/procevent-claims" \
+    "$ROOT/bin/fm-procevent.sh" start fixture-src 2>"$home/start.err")
+  err=$(cat "$home/start.err")
+
+  assert_not_contains "$out" "answers-fed: fixture-src" \
+    "a corrupted binding record still fed an answer"
+  assert_contains "$err" "decision binding has an incompatible schema" \
+    "the corrupted binding's diagnostic was not forwarded: $err"
+  show=$(tasks_in "$home" show "$id-decision-only-choice" --full)
+  assert_contains "$show" "state: queued" "a corrupted binding closed a captain hold anyway"
+  assert_contains "$show" "held: yes" "a corrupted binding released a captain hold"
+
+  # A genuinely unbound source processed the same way must stay silent: no
+  # diagnostic at all, proving the forwarding above is specific to corruption.
+  result2="$home/state/procevent-inbox/fixture-src-unbound.1.result"
+  cp "$result" "$result2"
+  PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$home/adapter-root" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_PROCEVENT_CLAIM_ROOT="$home/procevent-claims" \
+    "$ROOT/bin/fm-procevent.sh" register fixturechan fixture-src-unbound -- cat "$result2" >/dev/null \
+    || fail "could not register the unbound fixture source"
+  PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$home/adapter-root" FM_HOME="$home" \
+    FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \
+    FM_PROCEVENT_CLAIM_ROOT="$home/procevent-claims" \
+    "$ROOT/bin/fm-procevent.sh" start fixture-src-unbound >"$home/unbound.out" 2>"$home/unbound.err"
+  assert_not_contains "$(cat "$home/unbound.out")" "answers-fed: fixture-src-unbound" \
+    "an unbound source fed an answer"
+  assert_not_contains "$(cat "$home/unbound.err")" "decision binding" \
+    "a genuinely unbound source printed a binding diagnostic"
+  assert_not_contains "$(cat "$home/unbound.err")" "fm-decision-hold:" \
+    "a genuinely unbound source forwarded any fm-decision-hold diagnostic"
+
+  pass "a corrupted binding record forwards its diagnostic instead of silently acting as unbound"
+}
+
 # The answer verb is the hold ledger's answer-time closure primitive, so it must
 # carry every guard the unrouted close path already had. Weakening any of them to
 # reach closure would trade the loss this fixes for a worse one.
@@ -1137,5 +1229,6 @@ test_secondmate_hold_stays_in_authoritative_home
 test_resolve_matches_quoted_blocked_by_edges
 test_bound_channel_answers_close_their_holds_at_answer_time
 test_unbound_source_closes_no_hold
+test_corrupted_binding_forwards_its_diagnostic
 test_answer_preserves_every_unrouted_close_guard
 test_chat_channel_feeds_the_same_keyed_answer_intake