@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/tests/fm-afk-pi-herdr-return-e2e.test.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env bash
+# Real Pi/Herdr end-to-end regression for the 2026-07-14 two-owner incident.
+#
+# Opt-in because it launches a real interactive Pi primary, a real away daemon,
+# and a real isolated Herdr lab session. Every explicit and production-adapter
+# Herdr call is routed through fm-herdr-lab.sh. The scenario proves:
+#   - a live blocked status is classified and durably queued while away;
+#   - a pending Pi composer refuses injection and receives no forced Enter;
+#   - the existing wedge alarm remains observable and deduped;
+#   - clearing the draft makes the genuinely idle Pi composer injectable;
+#   - verified submit preserves the terminal-safe marker and clears delivery state;
+#   - an unmarked return request opens the catch-up gate before Bearings;
+#   - remediation/resolution clears the gate, and re-entry is idempotent.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+# shellcheck source=/dev/null
+. "$ROOT/bin/fm-supervise-daemon.sh"
+# shellcheck source=/dev/null
+. "$ROOT/bin/fm-backend.sh"
+
+if [ "${FM_AFK_PI_HERDR_E2E:-0}" != 1 ]; then
+  echo "skip: set FM_AFK_PI_HERDR_E2E=1 to run the real Pi/Herdr away-return regression"
+  exit 0
+fi
+
+for tool in herdr jq pi python3; do
+  command -v "$tool" >/dev/null 2>&1 || { echo "skip: $tool not found"; exit 0; }
+done
+
+LAB_HELPER=${HERDR_LAB_HELPER:-$ROOT/bin/fm-herdr-lab.sh}
+SESSION=$("$LAB_HELPER" name fm-afk-pi-return-e2e)
+TMP_ROOT=$(fm_test_tmproot fm-afk-pi-return-e2e)
+HOME_DIR="$TMP_ROOT/home"
+STATE="$HOME_DIR/state"
+PROJECT="$TMP_ROOT/project"
+PI_DIR="$TMP_ROOT/pi-agent"
+FAKEBIN="$TMP_ROOT/fakebin"
+CAPTURE="$TMP_ROOT/pi-prompts.jsonl"
+NOTIFY_LOG="$TMP_ROOT/wedge-notify.log"
+ORIGINAL_PATH=$PATH
+PRIMARY_PANE=
+CHILD_PANE=
+PRIMARY_TARGET=
+DAEMON_STARTED=0
+
+cleanup() {
+  local rc=$?
+  trap - EXIT
+  if [ "$DAEMON_STARTED" -eq 1 ]; then
+    PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" FM_HOME="$HOME_DIR" FM_STATE_OVERRIDE="$STATE" \
+      FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="$PRIMARY_TARGET" \
+      "$ROOT/bin/fm-afk-launch.sh" stop >/dev/null 2>&1 || true
+  fi
+  if ! "$LAB_HELPER" teardown "$SESSION"; then
+    rc=1
+  fi
+  rm -rf "$TMP_ROOT"
+  exit "$rc"
+}
+trap cleanup EXIT
+"$LAB_HELPER" provision "$SESSION"
+
+mkdir -p "$HOME_DIR"/{state,data,config,projects} "$PROJECT" "$PI_DIR" "$FAKEBIN"
+printf '# Synthetic isolated Firstmate primary\n' > "$PROJECT/AGENTS.md"
+
+# A task-local extension grants session-only trust, captures exact prompt bytes,
+# and aborts before provider work. No production supervision extension is loaded
+# in this synthetic primary, so nothing except the test can mutate fleet state.
+# Herdr still observes Pi's real idle->working transition, so production submit
+# verification is exercised without making a model request.
+CAPTURE_EXT="$TMP_ROOT/capture-extension.ts"
+cat > "$CAPTURE_EXT" <<'EOF'
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendFileSync } from "node:fs";
+const capturePath = process.env.FM_PI_CAPTURE_PATH!;
+export default function (pi: ExtensionAPI) {
+  pi.on("project_trust", () => ({ trusted: "yes", remember: false }));
+  pi.on("before_agent_start", (event, ctx) => {
+    appendFileSync(capturePath, `${JSON.stringify({ prompt: event.prompt, hex: Buffer.from(event.prompt, "utf8").toString("hex") })}\n`);
+    ctx.abort();
+  });
+}
+EOF
+
+# Route production adapter invocations through the guarded helper too. The shim
+# removes only the adapter's validated trailing pair, then the helper appends it.
+cat > "$FAKEBIN/herdr" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+helper='$LAB_HELPER'
+session='$SESSION'
+real_path='$ORIGINAL_PATH'
+args=("\$@")
+n=\${#args[@]}
+if [ "\$n" -ge 2 ] && [ "\${args[\$((n-2))]}" = --session ]; then
+  [ "\${args[\$((n-1))]}" = "\$session" ] || { echo 'wrapper refused foreign session' >&2; exit 97; }
+  args=("\${args[@]:0:\$((n-2))}")
+else
+  [ "\${HERDR_SESSION:-}" = "\$session" ] || { echo 'wrapper requires isolated session' >&2; exit 98; }
+fi
+PATH="\$real_path" exec "\$helper" run "\$session" "\${args[@]}"
+EOF
+chmod +x "$FAKEBIN/herdr"
+
+cat > "$TMP_ROOT/wedge-recorder" <<EOF
+#!/usr/bin/env bash
+printf '%s\t%s\n' "\$1" "\$2" >> '$NOTIFY_LOG'
+EOF
+chmod +x "$TMP_ROOT/wedge-recorder"
+
+cat > "$TMP_ROOT/daemon-entry" <<EOF
+#!/usr/bin/env bash
+export PATH='$FAKEBIN:$ORIGINAL_PATH'
+export HERDR_SESSION='$SESSION'
+export FM_STATE_OVERRIDE='$STATE'
+export FM_ESCALATE_BATCH_SECS=0
+export FM_HOUSEKEEPING_TICK=1
+export FM_POLL=1
+export FM_SIGNAL_GRACE=1
+export FM_HEARTBEAT=999999
+export FM_CHECK_INTERVAL=999999
+export FM_MAX_DEFER_SECS=3
+export FM_STALE_ESCALATE_SECS=999999
+export FM_WEDGE_ALARM_EXEC='$TMP_ROOT/wedge-recorder'
+exec '$ROOT/bin/fm-afk-start.sh'
+EOF
+chmod +x "$TMP_ROOT/daemon-entry"
+
+PRIMARY_OUT=$("$LAB_HELPER" run "$SESSION" workspace create --cwd "$PROJECT" --label synthetic-primary --no-focus)
+WORKSPACE=$(printf '%s' "$PRIMARY_OUT" | jq -r '.result.workspace.workspace_id')
+PRIMARY_PANE=$(printf '%s' "$PRIMARY_OUT" | jq -r '.result.root_pane.pane_id')
+PRIMARY_TARGET="$SESSION:$PRIMARY_PANE"
+EXT="$CAPTURE_EXT"
+PI_CMD=$(printf 'exec env PI_CODING_AGENT_DIR=%q FM_HOME=%q FM_PI_CAPTURE_PATH=%q pi -e %q --no-context-files --no-session' "$PI_DIR" "$HOME_DIR" "$CAPTURE" "$EXT")
+"$LAB_HELPER" run "$SESSION" pane run "$PRIMARY_PANE" "$PI_CMD" >/dev/null
+
+wait_for_idle() {
+  local stable=0 status _
+  for _ in $(seq 1 240); do
+    status=$("$LAB_HELPER" run "$SESSION" agent get "$PRIMARY_PANE" 2>/dev/null \
+      | jq -r '.result.agent.agent_status // empty' 2>/dev/null || true)
+    case "$status" in
+      idle|done|blocked) stable=$((stable + 1)); [ "$stable" -ge 4 ] && return 0 ;;
+      *) stable=0 ;;
+    esac
+    sleep 0.25
+  done
+  return 1
+}
+
+wait_for_prompt() {  # <jq predicate>
+  local predicate=$1 _
+  for _ in $(seq 1 240); do
+    if [ -s "$CAPTURE" ] && jq -s -e "$predicate" "$CAPTURE" >/dev/null 2>&1; then
+      return 0
+    fi
+    sleep 0.25
+  done
+  return 1
+}
+
+wait_for_idle || fail "real Pi primary did not become stably idle"
+
+assert_blocker_open() {
+  local at=$1 open
+  open=$(status_open_decisions "$STATE/repair-task.status")
+  printf '%s' "$open" | grep -F $'synthetic-dependency\tblocked\t' >/dev/null \
+    || fail "live blocked decision disappeared $at: status=$(cat "$STATE/repair-task.status" 2>/dev/null)"
+}
+
+CHILD_OUT=$("$LAB_HELPER" run "$SESSION" tab create --workspace "$WORKSPACE" --cwd "$PROJECT" --label fm-repair-task --no-focus)
+CHILD_PANE=$(printf '%s' "$CHILD_OUT" | jq -r '.result.root_pane.pane_id')
+CHILD_TARGET="$SESSION:$CHILD_PANE"
+cat > "$STATE/repair-task.meta" <<EOF
+window=$CHILD_TARGET
+backend=herdr
+kind=ship
+mode=no-mistakes
+worktree=$PROJECT
+project=synthetic-project
+EOF
+cat > "$HOME_DIR/data/backlog.md" <<'EOF'
+## In flight
+- [ ] repair-task - Repair the synthetic dependency (repo: synthetic-project, since 2026-07-14)
+
+## Queued
+
+## Done
+EOF
+
+PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" FM_HOME="$HOME_DIR" FM_STATE_OVERRIDE="$STATE" \
+  FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="$PRIMARY_TARGET" FM_AFK_LAUNCH_ENTRY="$TMP_ROOT/daemon-entry" \
+  "$ROOT/bin/fm-afk-launch.sh" start >/dev/null
+DAEMON_STARTED=1
+for _ in $(seq 1 100); do [ -s "$STATE/.supervise-daemon.pid" ] && break; sleep 0.1; done
+[ -s "$STATE/.supervise-daemon.pid" ] || fail "away daemon did not start"
+
+# Pending input is never an injection target. Leave a real draft in Pi before
+# the live child emits blocked:, then wait through max-defer.
+"$LAB_HELPER" run "$SESSION" pane send-text "$PRIMARY_PANE" 'privacy safe human draft' >/dev/null
+sleep 0.5
+composer=$(PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" fm_backend_composer_state herdr "$PRIMARY_TARGET")
+[ "$composer" = pending ] || fail "real Pi draft did not classify pending (got $composer)"
+CHILD_CMD=$(printf "printf 'blocked [key=synthetic-dependency]: firstmate can refresh the synthetic token\\n' >> %q; exec sleep 120" "$STATE/repair-task.status")
+"$LAB_HELPER" run "$SESSION" pane run "$CHILD_PANE" "$CHILD_CMD" >/dev/null
+for _ in $(seq 1 160); do [ -s "$STATE/.subsuper-inject-wedged" ] && break; sleep 0.1; done
+[ -s "$STATE/.subsuper-inject-wedged" ] || fail "persistently pending real Pi composer did not raise the defense-in-depth alarm"
+[ -s "$STATE/.subsuper-escalations" ] || fail "pending real Pi composer lost the buffered blocker"
+[ ! -s "$CAPTURE" ] || fail "daemon submitted into Pi while the real human draft was pending"
+plain=$("$LAB_HELPER" run "$SESSION" pane read "$PRIMARY_PANE" --source recent --lines 200)
+printf '%s' "$plain" | grep -F 'privacy safe human draft' >/dev/null || fail "pending Pi draft was modified or forcibly submitted"
+for _ in $(seq 1 50); do [ -s "$NOTIFY_LOG" ] && break; sleep 0.1; done
+[ -s "$NOTIFY_LOG" ] || fail "wedge alarm marker appeared but its active notifier did not finish"
+[ "$(wc -l < "$NOTIFY_LOG" | tr -d ' ')" -eq 1 ] || fail "wedge alarm was not observed exactly once before recovery"
+assert_blocker_open 'while the Pi composer was pending'
+pass "real Pi/Herdr pending composer refuses injection without forced submit and raises one observable fallback"
+
+# Clear, never submit, the synthetic human draft. The same exact target now has
+# native idle state plus a complete Pi separator composer and must accept quickly.
+"$LAB_HELPER" run "$SESSION" pane send-keys "$PRIMARY_PANE" ctrl+c >/dev/null
+wait_for_idle || fail "real Pi did not return idle after clearing the draft"
+for _ in $(seq 1 80); do
+  composer=$(PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" fm_backend_composer_state herdr "$PRIMARY_TARGET")
+  [ "$composer" = empty ] && break
+  sleep 0.1
+done
+[ "$composer" = empty ] || fail "genuinely idle Pi separator composer did not classify empty (got $composer)"
+wait_for_prompt 'any(.[]; .prompt | startswith("\u2063Supervisor escalate"))' \
+  || fail "real Pi did not receive the buffered escalation after becoming safely idle"
+INJECT_HEX=$(jq -r 'select(.prompt | startswith("\u2063Supervisor escalate")) | .hex' "$CAPTURE" | tail -1)
+case "$INJECT_HEX" in e281a3*) ;; *) fail "real Pi escalation lost the terminal-safe marker: $INJECT_HEX" ;; esac
+for _ in $(seq 1 80); do [ ! -s "$STATE/.subsuper-escalations" ] && break; sleep 0.1; done
+[ ! -s "$STATE/.subsuper-escalations" ] || fail "confirmed real Pi delivery did not clear the escalation buffer"
+[ ! -e "$STATE/.subsuper-inject-wedged" ] || fail "confirmed real Pi delivery did not clear the old wedge marker"
+sleep 4
+[ "$(wc -l < "$NOTIFY_LOG" | tr -d ' ')" -eq 1 ] || fail "successful delivery emitted a duplicate wedge alert"
+INJECT_PROMPT=$(jq -r 'select(.prompt | startswith("\u2063Supervisor escalate")) | .prompt' "$CAPTURE" | tail -1)
+message_is_injection "$INJECT_PROMPT" || fail "terminal-delivered Pi escalation was not recognized as an internal marker"
+assert_blocker_open 'after successful marked injection'
+pass "real idle Pi/Herdr accepts one marked escalation promptly, verifies submit, clears wedge state, and emits no duplicate alert"
+
+# The captain returns with an ordinary unmarked Bearings request. The request is
+# captured byte-exact, then the public return owner must gate it on the blocker.
+wait_for_idle || fail "real Pi did not settle after the injected catch-up"
+for _ in $(seq 1 80); do
+  composer=$(PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" fm_backend_composer_state herdr "$PRIMARY_TARGET")
+  [ "$composer" = empty ] && break
+  sleep 0.1
+done
+[ "$composer" = empty ] || fail "real Pi composer was not ready for the unmarked return request"
+"$LAB_HELPER" run "$SESSION" pane send-text "$PRIMARY_PANE" 'Synthetic Bearings request' >/dev/null
+"$LAB_HELPER" run "$SESSION" pane send-keys "$PRIMARY_PANE" enter >/dev/null
+wait_for_prompt 'any(.[]; .prompt == "Synthetic Bearings request")' || fail "real Pi did not receive the unmarked return request"
+RETURN_PROMPT=$(jq -r 'select(.prompt == "Synthetic Bearings request") | .prompt' "$CAPTURE" | tail -1)
+should_exit_afk "$STATE" "$RETURN_PROMPT" || fail "unmarked Pi return request did not trigger the away exit contract"
+assert_blocker_open 'before return catch-up'
+[ -f "$STATE/repair-task.meta" ] || fail "live blocker metadata disappeared before return catch-up"
+
+set +e
+RETURN_OUT=$(PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" FM_ROOT_OVERRIDE="$PROJECT" FM_HOME="$HOME_DIR" FM_STATE_OVERRIDE="$STATE" \
+  FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="$PRIMARY_TARGET" "$ROOT/bin/fm-afk-return.sh" begin 2>&1)
+RETURN_RC=$?
+set -e
+DAEMON_STARTED=0
+[ "$RETURN_RC" -eq 3 ] || fail "return catch-up did not gate the still-live blocker (rc=$RETURN_RC): $RETURN_OUT"
+assert_contains "$RETURN_OUT" 'firstmate-actionable blocker: repair-task [key=synthetic-dependency]' "return gate did not assign remediation"
+set +e
+BEARINGS_OUT=$(PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" FM_ROOT_OVERRIDE="$PROJECT" FM_HOME="$HOME_DIR" FM_STATE_OVERRIDE="$STATE" \
+  "$ROOT/bin/fm-bearings-snapshot.sh" --json 2>&1)
+BEARINGS_RC=$?
+set -e
+[ "$BEARINGS_RC" -eq 3 ] || fail "Bearings bypassed the return gate (rc=$BEARINGS_RC): $BEARINGS_OUT"
+pass "real unmarked Pi return opens catch-up and blocks Bearings before the unresolved blocker can be deferred"
+
+printf 'resolved [key=synthetic-dependency]: refreshed the synthetic token and resumed the task\n' >> "$STATE/repair-task.status"
+PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" FM_ROOT_OVERRIDE="$PROJECT" FM_HOME="$HOME_DIR" FM_STATE_OVERRIDE="$STATE" \
+  "$ROOT/bin/fm-afk-return.sh" check >/dev/null || fail "remediated blocker did not clear return catch-up"
+PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" FM_ROOT_OVERRIDE="$PROJECT" FM_HOME="$HOME_DIR" FM_STATE_OVERRIDE="$STATE" \
+  "$ROOT/bin/fm-bearings-snapshot.sh" --json >/dev/null || fail "Bearings remained gated after blocker remediation"
+
+# A clean re-entry creates no stale delivery or alert, and an immediate return is
+# idempotently clear because the keyed blocker is resolved.
+PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" FM_HOME="$HOME_DIR" FM_STATE_OVERRIDE="$STATE" \
+  FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="$PRIMARY_TARGET" FM_AFK_LAUNCH_ENTRY="$TMP_ROOT/daemon-entry" \
+  "$ROOT/bin/fm-afk-launch.sh" start >/dev/null
+DAEMON_STARTED=1
+PATH="$FAKEBIN:$ORIGINAL_PATH" HERDR_SESSION="$SESSION" FM_ROOT_OVERRIDE="$PROJECT" FM_HOME="$HOME_DIR" FM_STATE_OVERRIDE="$STATE" \
+  FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="$PRIMARY_TARGET" "$ROOT/bin/fm-afk-return.sh" begin >/dev/null \
+  || fail "clean away re-entry/return was not idempotent"
+DAEMON_STARTED=0
+[ "$(wc -l < "$NOTIFY_LOG" | tr -d ' ')" -eq 1 ] || fail "clean re-entry duplicated the historical wedge alert"
+pass "resolved return catch-up allows Bearings and a clean idempotent away re-entry"
+
+printf 'evidence: herdr=%s pi=%s target=%s inject-hex-prefix=%s notifier-count=1\n' \
+  "$(herdr --version)" "$(pi --version)" "$PRIMARY_TARGET" "${INJECT_HEX:0:6}"

package/.agents/tests/fm-afk-return.test.sh

@@ -0,0 +1,283 @@
+#!/usr/bin/env bash
+# Deterministic return-catch-up gate regression.
+#
+# Covers the second half of the 2026-07-14 incident: an away-mode blocked event
+# survived in durable state, but the ordinary return request could proceed to
+# Bearings before Firstmate owned remediation. The shared script now stops,
+# drains, preserves evidence, and refuses ordinary work until every live open
+# `blocked:` event is resolved or durably reclassified.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+TMP_ROOT=$(fm_test_tmproot fm-afk-return-tests)
+
+install_runner() {  # <case-dir>
+  local dir=$1
+  mkdir -p "$dir/bin" "$dir/home/state" "$dir/home/data" "$dir/home/config"
+  cp "$ROOT/bin/fm-afk-return.sh" "$dir/bin/"
+  cp "$ROOT/bin/fm-wake-lib.sh" "$dir/bin/"
+  cp "$ROOT/bin/fm-classify-lib.sh" "$dir/bin/"
+  # fm-timeout-lib.sh: the shared hard bound fm-classify-lib.sh sources for the
+  # wedge detector's bounded worktree write probe.
+  cp "$ROOT/bin/fm-timeout-lib.sh" "$dir/bin/"
+  cat > "$dir/bin/fm-afk-launch.sh" <<'SH'
+#!/usr/bin/env bash
+[ "${1:-}" = stop ] || exit 2
+printf 'stop\n' >> "$FM_HOME/stop.log"
+rm -f "$FM_HOME/state/.afk"
+if [ -e "$FM_HOME/state/.fail-terminal-stop-once" ]; then
+  rm -f "$FM_HOME/state/.fail-terminal-stop-once"
+  exit 1
+fi
+rm -f "$FM_HOME/state/.afk-daemon-terminal"
+SH
+  cat > "$dir/bin/fm-wake-drain.sh" <<'SH'
+#!/usr/bin/env bash
+file="$FM_HOME/state/.fake-drain"
+if [ "${1:-}" = --ack-through ]; then
+  [ "${3:-}" = --recovery-generation ] && [ "${4:-}" = fixture-generation ] || exit 2
+  printf '%s\n' "$2" >> "$FM_HOME/state/.fake-drain-acks"
+  : > "$file"
+  exit 0
+fi
+if [ -s "$file" ]; then
+  cat "$file"
+  sequence=$(awk -F '\t' '$2 ~ /^[0-9]+$/ && $2 > max { max=$2 } END { print max + 0 }' "$file")
+  printf 'WAKE_ACK_REQUIRED: after handling completes run bin/fm-wake-drain.sh --ack-through %s --recovery-generation fixture-generation\n' "$sequence" >&2
+fi
+SH
+  chmod +x "$dir/bin/"*.sh
+}
+
+run_return() {  # <case-dir> <mode>
+  local dir=$1 mode=$2
+  FM_HOME="$dir/home" FM_STATE_OVERRIDE="$dir/home/state" "$dir/bin/fm-afk-return.sh" "$mode" 2>&1
+}
+
+ack_return() {  # <case-dir> <return-output>
+  local dir=$1 output=$2 sequence generation
+  sequence=$(printf '%s\n' "$output" | sed -n 's/^WAKE_ACK_REQUIRED:.*--ack-through \([0-9][0-9]*\) --recovery-generation [A-Za-z0-9._-][A-Za-z0-9._-]*$/\1/p' | tail -1)
+  generation=$(printf '%s\n' "$output" | sed -n 's/^WAKE_ACK_REQUIRED:.*--ack-through [0-9][0-9]* --recovery-generation \([A-Za-z0-9._-][A-Za-z0-9._-]*\)$/\1/p' | tail -1)
+  [ -n "$sequence" ] && [ -n "$generation" ] || fail "return output lacked a generation-bound post-handling acknowledgement: $output"
+  FM_HOME="$dir/home" FM_STATE_OVERRIDE="$dir/home/state" \
+    "$dir/bin/fm-wake-drain.sh" --ack-through "$sequence" --recovery-generation "$generation"
+}
+
+seed_live_blocker() {  # <case-dir> <backend> <key>
+  local dir=$1 backend=$2 key=$3 target
+  case "$backend" in
+    tmux) target='synthetic:fm-repair-task' ;;
+    herdr) target='fm-lab-synthetic:w1:p2' ;;
+  esac
+  cat > "$dir/home/state/repair-task.meta" <<EOF
+window=$target
+backend=$backend
+kind=ship
+EOF
+  printf 'blocked [key=%s]: firstmate can refresh the synthetic token\n' "$key" > "$dir/home/state/repair-task.status"
+}
+
+test_return_gate_orders_catchup_before_bearings() {
+  local dir out rc gate wake_count
+  dir="$TMP_ROOT/ordering"
+  install_runner "$dir"
+  seed_live_blocker "$dir" herdr synthetic-dependency
+  date +%s > "$dir/home/state/.afk"
+  printf 'repair-task.status: blocked synthetic dependency\n' > "$dir/home/state/.subsuper-escalations"
+  printf 'fm away-mode inject WEDGED: 4555s undelivered\n' > "$dir/home/state/.subsuper-inject-wedged"
+  {
+    printf '1784074271\t2\tsignal\trepair-task.status\tsignal: synthetic status\n'
+    printf 'wake annotation: latest wake-EVENT observed at drain, not current state: repair-task.status: blocked synthetic dependency\n'
+  } > "$dir/home/state/.fake-drain"
+
+  set +e
+  out=$(run_return "$dir" begin)
+  rc=$?
+  set -e
+  [ "$rc" -eq 3 ] || fail "return begin should gate on a live blocker (rc=$rc): $out"
+  gate="$dir/home/state/.afk-return-catchup"
+  [ -s "$gate" ] || fail "return begin did not persist its fail-closed catch-up gate"
+  assert_contains "$out" 'firstmate-actionable blocker: repair-task [key=synthetic-dependency]' "return output did not assign blocker remediation to Firstmate"
+  grep -F $'evidence\twake\t1784074271' "$gate" >/dev/null || fail "drained wake evidence was not retained in the durable gate"
+  grep -F $'evidence\twake\twake annotation: latest wake-EVENT observed at drain, not current state: repair-task.status: blocked synthetic dependency' "$gate" >/dev/null \
+    || fail "the separate drain annotation was not retained as away-return evidence"
+  grep -F $'evidence\twedge\tfm away-mode inject WEDGED: 4555s undelivered' "$gate" >/dev/null || fail "wedge evidence was not retained in the durable gate"
+  grep -F $'evidence\tescalation\trepair-task.status: blocked synthetic dependency' "$gate" >/dev/null || fail "buffered escalation evidence was not retained in the durable gate"
+  [ "$(wc -l < "$dir/home/stop.log" | tr -d ' ')" -eq 1 ] || fail "return begin did not stop away mode exactly once"
+  [ -s "$dir/home/state/.fake-drain" ] || fail "blocked return acknowledged its emitted wake before handling completed"
+  [ ! -e "$dir/home/state/.fake-drain-acks" ] || fail "blocked return crossed the post-handling acknowledgement boundary"
+
+  # The exact incident regression: Bearings is an ordinary request and must
+  # refuse before reading/rendering while this shared gate remains open.
+  set +e
+  out=$(FM_HOME="$dir/home" FM_STATE_OVERRIDE="$dir/home/state" "$ROOT/bin/fm-bearings-snapshot.sh" --json 2>&1)
+  rc=$?
+  set -e
+  [ "$rc" -eq 3 ] || fail "Bearings should refuse behind the return gate (rc=$rc): $out"
+  assert_contains "$out" 'return catch-up is pending' "Bearings refusal did not point to the shared return owner"
+
+  # Restart/re-entry is idempotent: no second stop, no duplicate catch-up line,
+  # and the same unresolved blocker remains authoritative.
+  set +e
+  out=$(run_return "$dir" begin)
+  rc=$?
+  set -e
+  [ "$rc" -eq 3 ] || fail "repeated begin should preserve the unresolved gate"
+  [ "$(wc -l < "$dir/home/stop.log" | tr -d ' ')" -eq 1 ] || fail "repeated begin stopped an already-stopped daemon twice"
+  wake_count=$(grep -c $'^evidence\twake\t1784074271' "$gate" || true)
+  [ "$wake_count" -eq 1 ] || fail "repeated begin duplicated retained wake evidence ($wake_count copies)"
+  [ "$(grep -c $'^evidence\twedge\t' "$gate" || true)" -eq 1 ] || fail "repeated begin duplicated retained wedge evidence"
+  [ "$(grep -c $'^evidence\tescalation\t' "$gate" || true)" -eq 1 ] || fail "repeated begin duplicated retained escalation evidence"
+
+  printf 'resolved [key=synthetic-dependency]: refreshed the synthetic token and resumed the task\n' >> "$dir/home/state/repair-task.status"
+  out=$(run_return "$dir" check) || fail "resolved blocker did not clear return catch-up: $out"
+  assert_contains "$out" 'catch-up clear' "successful check did not announce that ordinary work may proceed"
+  [ ! -e "$gate" ] || fail "successful check left the return gate behind"
+  [ ! -e "$dir/home/state/.subsuper-escalations" ] || fail "successful check left delivered escalation state behind"
+  [ ! -e "$dir/home/state/.subsuper-inject-wedged" ] || fail "successful check left the wedge marker behind"
+  [ -s "$dir/home/state/.fake-drain" ] || fail "successful return consumed its wake before handling completed"
+  [ ! -e "$dir/home/state/.fake-drain-acks" ] || fail "successful return acknowledged its wake inside evidence publication"
+  assert_contains "$out" 'WAKE_ACK_REQUIRED: after handling completes' "successful return did not hand acknowledgement to the handling turn"
+  ack_return "$dir" "$out" || fail "post-handling acknowledgement failed"
+  [ ! -s "$dir/home/state/.fake-drain" ] || fail "explicit post-handling acknowledgement left the handled wake durable"
+  [ "$(cat "$dir/home/state/.fake-drain-acks" 2>/dev/null || true)" = 2 ] \
+    || fail "explicit post-handling acknowledgement used the wrong wake sequence"
+
+  out=$(run_return "$dir" check) || fail "an already-clear repeated check should be idempotent: $out"
+  [ ! -e "$gate" ] || fail "idempotent clear check recreated a gate"
+  pass "return catch-up precedes Bearings, owns live blocker remediation, preserves evidence once, and clears idempotently"
+}
+
+test_explicit_reclassification_requires_durable_reason() {
+  local backend dir out rc
+  for backend in tmux herdr; do
+    dir="$TMP_ROOT/reclassify-$backend"
+    install_runner "$dir"
+    seed_live_blocker "$dir" "$backend" vendor-release
+    date +%s > "$dir/home/state/.afk"
+    : > "$dir/home/state/.fake-drain"
+    set +e
+    out=$(run_return "$dir" begin)
+    rc=$?
+    set -e
+    [ "$rc" -eq 3 ] || fail "$backend blocker did not open the return gate"
+
+    # A pause alone cannot mask the keyed blocker. The old concern must be
+    # explicitly resolved with the durable reclassification reason first.
+    printf 'paused [key=vendor-release]: waiting for the synthetic vendor window\n' >> "$dir/home/state/repair-task.status"
+    set +e
+    out=$(run_return "$dir" check)
+    rc=$?
+    set -e
+    [ "$rc" -eq 3 ] || fail "$backend pause silently masked an unresolved blocked key"
+
+    printf 'resolved [key=vendor-release]: reclassified as an external wait because the synthetic vendor owns the next event\n' >> "$dir/home/state/repair-task.status"
+    printf 'paused [key=vendor-release]: waiting for the synthetic vendor window\n' >> "$dir/home/state/repair-task.status"
+    out=$(run_return "$dir" check) || fail "$backend durable reclassification did not clear the return gate: $out"
+    [ ! -e "$dir/home/state/.afk-return-catchup" ] || fail "$backend reclassification left a gate behind"
+  done
+  pass "tmux and Herdr blockers require the same explicit durable reclassification before ordinary work"
+}
+
+test_captain_decision_does_not_masquerade_as_firstmate_blocker() {
+  local dir out
+  dir="$TMP_ROOT/captain-decision"
+  install_runner "$dir"
+  cat > "$dir/home/state/decision-task.meta" <<'EOF'
+window=synthetic:fm-decision-task
+backend=tmux
+kind=ship
+EOF
+  printf 'needs-decision [key=api-shape]: captain must choose the synthetic API shape\n' > "$dir/home/state/decision-task.status"
+  date +%s > "$dir/home/state/.afk"
+  printf '1784074271\t1\tsignal\tdecision-task.status\tsignal: synthetic decision\n' > "$dir/home/state/.fake-drain"
+  out=$(run_return "$dir" begin) || fail "approval decision should not be treated as a firstmate blocker: $out"
+  assert_contains "$out" 'catch-up wake:' "approval decision notification was not surfaced in catch-up"
+  [ ! -e "$dir/home/state/.afk-return-catchup" ] || fail "approval decision incorrectly opened a firstmate blocker gate"
+  pass "needs-decision remains reportable without masquerading as a firstmate-actionable blocker"
+}
+
+test_evidence_publication_failure_preserves_wake_for_redrain() {
+  local dir out rc gate
+  dir="$TMP_ROOT/evidence-publication-failure"
+  install_runner "$dir"
+  gate="$dir/home/state/.afk-return-catchup"
+  printf '1784074271\t7\tsignal\trecovery-task.status\tsignal: recover after output failure\n' \
+    > "$dir/home/state/.fake-drain"
+  : > "$dir/read-only-output"
+
+  set +e
+  FM_HOME="$dir/home" FM_STATE_OVERRIDE="$dir/home/state" \
+    "$dir/bin/fm-afk-return.sh" begin 3< "$dir/read-only-output" >&3 2> "$dir/failed.err"
+  rc=$?
+  set -e
+  [ "$rc" -eq 3 ] || fail "evidence publication failure should retain catch-up (rc=$rc)"
+  [ -s "$dir/home/state/.fake-drain" ] || fail "publication failure removed the unhandled durable wake"
+  [ ! -e "$dir/home/state/.fake-drain-acks" ] || fail "publication failure acknowledged the wake before delivery"
+  [ -s "$gate" ] || fail "publication failure did not retain the catch-up gate"
+
+  out=$(run_return "$dir" check) || fail "publication retry did not complete catch-up: $out"
+  assert_contains "$out" 'catch-up wake: 1784074271' "publication retry did not re-drain the durable wake"
+  assert_contains "$out" 'WAKE_ACK_REQUIRED: after handling completes' "publication retry did not return acknowledgement to the handling turn"
+  [ -s "$dir/home/state/.fake-drain" ] || fail "successful evidence publication consumed the wake before handling"
+  [ ! -e "$dir/home/state/.fake-drain-acks" ] || fail "successful evidence publication acknowledged the wake before handling"
+  [ ! -e "$gate" ] || fail "successful publication retry left the catch-up gate pending"
+
+  out=$(run_return "$dir" check) || fail "return did not recover after interruption before acknowledgement: $out"
+  assert_contains "$out" 'catch-up wake: 1784074271' "interrupted handling did not re-drain the published wake"
+  [ -s "$dir/home/state/.fake-drain" ] || fail "interrupted handling lost the published wake"
+  ack_return "$dir" "$out" || fail "explicit acknowledgement after replay failed"
+  [ ! -s "$dir/home/state/.fake-drain" ] || fail "explicit acknowledgement did not consume the replayed wake"
+  [ "$(cat "$dir/home/state/.fake-drain-acks" 2>/dev/null || true)" = 7 ] \
+    || fail "explicit acknowledgement after replay used the wrong wake sequence"
+  pass "AFK return re-drains published wakes until handling acknowledges"
+}
+
+test_away_reentry_refuses_pending_return_gate() {
+  local dir out rc
+  dir="$TMP_ROOT/reentry"
+  mkdir -p "$dir/home/state" "$dir/home/data" "$dir/home/config"
+  printf 'schema\tfm-afk-return.v1\nphase\tblocked\n' > "$dir/home/state/.afk-return-catchup"
+  set +e
+  out=$(FM_HOME="$dir/home" FM_STATE_OVERRIDE="$dir/home/state" "$ROOT/bin/fm-afk-launch.sh" start-native 2>&1)
+  rc=$?
+  set -e
+  [ "$rc" -ne 0 ] || fail "away re-entry succeeded while return catch-up was pending"
+  assert_contains "$out" 'return catch-up is still pending' "away re-entry refusal did not explain the pending owner"
+  [ ! -e "$dir/home/state/.afk" ] || fail "away re-entry wrote .afk despite the pending return gate"
+  pass "away-mode re-entry fails closed while the prior return catch-up is pending"
+}
+
+test_check_retries_recorded_terminal_teardown() {
+  local dir gate out rc
+  dir="$TMP_ROOT/terminal-teardown"
+  install_runner "$dir"
+  gate="$dir/home/state/.afk-return-catchup"
+  date +%s > "$dir/home/state/.afk"
+  printf 'herdr\tsynthetic:pane\tsynthetic-workspace\n' > "$dir/home/state/.afk-daemon-terminal"
+  touch "$dir/home/state/.fail-terminal-stop-once"
+
+  set +e
+  out=$(run_return "$dir" begin)
+  rc=$?
+  set -e
+  [ "$rc" -eq 3 ] || fail "failed terminal teardown should keep return catch-up gated (rc=$rc): $out"
+  [ -e "$gate" ] || fail "failed terminal teardown cleared the return gate"
+  [ -e "$dir/home/state/.afk-daemon-terminal" ] || fail "failed terminal teardown discarded its durable record"
+  [ ! -e "$dir/home/state/.afk" ] || fail "failed terminal teardown did not preserve stop ordering"
+
+  out=$(run_return "$dir" check) || fail "check did not retry recorded terminal teardown: $out"
+  [ ! -e "$dir/home/state/.afk-daemon-terminal" ] || fail "successful check left the terminal teardown record behind"
+  [ ! -e "$gate" ] || fail "successful terminal teardown retry left the return gate behind"
+  [ "$(wc -l < "$dir/home/stop.log" | tr -d ' ')" -eq 2 ] || fail "check did not retry terminal teardown exactly once"
+  pass "check retries recorded terminal teardown and keeps catch-up gated until success"
+}
+
+test_return_gate_orders_catchup_before_bearings
+test_explicit_reclassification_requires_durable_reason
+test_captain_decision_does_not_masquerade_as_firstmate_blocker
+test_evidence_publication_failure_preserves_wake_for_redrain
+test_away_reentry_refuses_pending_return_gate
+test_check_retries_recorded_terminal_teardown