@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/tests/fm-supervision-events.test.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# tests/fm-supervision-events.test.sh - unit tests for the watcher's native
+# event-wait splice (event_wait_or_sleep in bin/fm-watch.sh and
+# handle_push_transition in bin/fm-push-transition-lib.sh). The watcher's source
+# guard lets this file source it to load
+# the functions WITHOUT acquiring the singleton lock or entering the blocking
+# loop; wake/sleep and the backend dispatchers are overridden so the exemptions,
+# capability memo, and fail-closed disable are asserted deterministically with no
+# real herdr, watcher process, or blocking sleeps.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+TMP=$(fm_test_tmproot fm-supervision-events)
+STATE_DIR="$TMP/state"
+mkdir -p "$STATE_DIR"
+
+# Source the watcher with an isolated state/home. The guard returns before the
+# lock/loop, so only the functions load.
+export FM_STATE_OVERRIDE="$STATE_DIR"
+export FM_ROOT_OVERRIDE="$ROOT"
+# Production modules are independently linted canonical roots. Keep this test's
+# ShellCheck context local while preserving its unchanged runtime source path.
+# shellcheck source=/dev/null
+. "$ROOT/bin/fm-watch.sh"
+
+# Overrides: capture wake reasons and neutralize real sleeps (POLL is 15s).
+WAKE_LOG="$TMP/wakes"
+SLEEP_LOG="$TMP/sleeps"
+wake() { printf '%s\n' "$1" >> "$WAKE_LOG"; return 0; }
+sleep() { printf 'SLEEP\n' >> "$SLEEP_LOG"; }
+
+reset_state() {
+  rm -f "$STATE_DIR"/*.meta "$STATE_DIR"/*.status "$STATE_DIR"/.wake-queue \
+    "$STATE_DIR"/.wake-queue.seq "$STATE_DIR"/.watch-triage.log \
+    "$STATE_DIR"/.herdr-escalated-* "$TMP"/panes "$TMP"/wtcalls "$TMP"/wtcalled 2>/dev/null || true
+  : > "$WAKE_LOG"
+  : > "$SLEEP_LOG"
+  _event_cap_key=""
+  _event_cap_ok=0
+  _event_cap_fails=0
+}
+
+mkrec() {  # <pane_id> <status>
+  fm_transition_record "$1" "wG" "" "$2" claude
+}
+
+# --- handle_push_transition: enqueue + wake for a non-paused blocked crew -----
+
+reset_state
+fm_write_meta "$STATE_DIR/tk1.meta" "window=default:wG:pQ" "backend=herdr" "kind=ship"
+handle_push_transition herdr default "$(mkrec wG:pQ blocked)"
+[ -e "$STATE_DIR/.wake-queue" ] || fail "handle_push_transition should enqueue a wake for a blocked crew"
+grep -q 'stale' "$STATE_DIR/.wake-queue" || fail "the enqueued wake must be a stale record: $(cat "$STATE_DIR/.wake-queue")"
+grep -q 'default:wG:pQ' "$STATE_DIR/.wake-queue" || fail "the stale record must name the crew's window"
+grep -q 'herdr: agent blocked' "$STATE_DIR/.wake-queue" || fail "the stale payload must name the herdr-blocked cause"
+[ -s "$WAKE_LOG" ] || fail "handle_push_transition must wake the supervisor for a blocked crew"
+[ -e "$STATE_DIR/.herdr-escalated-default_wG_pQ" ] || fail "handle_push_transition must commit dedupe only after enqueue"
+pass "handle_push_transition: a blocked crew enqueues a stale wake naming its window and wakes the supervisor"
+
+reset_state
+fm_write_meta "$STATE_DIR/tk1.meta" "window=default:wG:pQ" "backend=herdr" "kind=ship"
+(
+  # shellcheck disable=SC2329 # Runtime override called by the isolated production owner.
+  fm_wake_append() { return 1; }
+  handle_push_transition herdr default "$(mkrec wG:pQ blocked)"
+) >/dev/null 2>&1 || true
+[ ! -e "$STATE_DIR/.herdr-escalated-default_wG_pQ" ] || fail "a failed durable enqueue must leave the blocked edge eligible for reconnect reconciliation"
+pass "handle_push_transition: enqueue failure cannot commit the Herdr dedupe marker"
+
+# --- handle_push_transition: absorb (no wake, no enqueue) for a declared pause -
+
+reset_state
+fm_write_meta "$STATE_DIR/tk2.meta" "window=default:wG:pQ" "backend=herdr" "kind=ship"
+printf 'paused: waiting on the upstream release\n' > "$STATE_DIR/tk2.status"
+handle_push_transition herdr default "$(mkrec wG:pQ blocked)"
+if [ -e "$STATE_DIR/.wake-queue" ] && grep -q 'stale' "$STATE_DIR/.wake-queue"; then
+  fail "a declared-pause crew must NOT be fast-escalated: $(cat "$STATE_DIR/.wake-queue")"
+fi
+[ ! -s "$WAKE_LOG" ] || fail "a declared-pause crew must not wake the supervisor from the event fast-path"
+grep -q 'absorbed push' "$STATE_DIR/.watch-triage.log" 2>/dev/null || fail "the paused absorb should be logged to the triage log"
+pass "handle_push_transition: a declared-pause crew is absorbed (no fast wake), left to the poll loop's long cadence"
+
+# --- handle_push_transition: absorb for a verified captain-held transfer -------
+
+reset_state
+fm_write_meta "$STATE_DIR/tk2h.meta" "window=default:wG:pQ" "backend=herdr" "kind=ship"
+printf 'captain-held [key=route]: tracked by task-decision-route\n' > "$STATE_DIR/tk2h.status"
+handle_push_transition herdr default "$(mkrec wG:pQ blocked)"
+if [ -e "$STATE_DIR/.wake-queue" ] && grep -q 'stale' "$STATE_DIR/.wake-queue"; then
+  fail "a captain-held crew must NOT be fast-escalated: $(cat "$STATE_DIR/.wake-queue")"
+fi
+[ ! -s "$WAKE_LOG" ] || fail "a captain-held crew must not wake the supervisor from the event fast-path"
+grep -q 'absorbed push' "$STATE_DIR/.watch-triage.log" 2>/dev/null || fail "the captain-held absorb should be logged to the triage log"
+pass "handle_push_transition: a captain-held crew is absorbed (no fast wake), left to the poll loop's long cadence"
+
+# --- event_wait_or_sleep: secondmate windows are excluded from the pane list --
+
+reset_state
+fm_write_meta "$STATE_DIR/tk3.meta" "window=default:wG:pQ" "backend=herdr" "kind=ship"
+fm_write_meta "$STATE_DIR/sm1.meta" "window=default:wA:pS" "backend=herdr" "kind=secondmate"
+# shellcheck disable=SC2329 # Runtime overrides called by the isolated watcher.
+fm_backend_events_capable() { return 0; }
+# shellcheck disable=SC2329 # Runtime overrides called by the isolated watcher.
+fm_backend_wait_transition() { shift 4; printf '%s\n' "$*" > "$TMP/panes"; return 1; }
+event_wait_or_sleep
+PANES=$(cat "$TMP/panes" 2>/dev/null || true)
+case "$PANES" in *"default:wG:pQ"*) : ;; *) fail "the ship window must be in the event pane list, got '$PANES'" ;; esac
+case "$PANES" in *"default:wA:pS"*) fail "a kind=secondmate window must be EXCLUDED from the event pane list, got '$PANES'" ;; *) : ;; esac
+pass "event_wait_or_sleep: herdr windows go on the event pane list, but kind=secondmate endpoints are excluded"
+
+reset_state
+fm_write_meta "$STATE_DIR/tk3.meta" "window=default:wG:pQ" "backend=herdr" "kind=ship"
+CAP_CALLS=0
+# shellcheck disable=SC2329 # Runtime overrides called by the isolated watcher.
+fm_backend_events_capable() { CAP_CALLS=$((CAP_CALLS + 1)); return 0; }
+# shellcheck disable=SC2329 # Runtime overrides called by the isolated watcher.
+fm_backend_wait_transition() {
+  [ "${FM_BACKEND_EVENTS_CAPABILITY_CONFIRMED:-0}" = 1 ] || fail "cached capability verdict was not passed to the wait"
+  return 1
+}
+event_wait_or_sleep
+event_wait_or_sleep
+[ "$CAP_CALLS" = 1 ] || fail "capability probe must be memoized across waits, got $CAP_CALLS calls"
+pass "event_wait_or_sleep: one cached capability probe owns validation across bounded waits"
+
+# --- event_wait_or_sleep: a tmux-only home never runs the event path ----------
+
+reset_state
+fm_write_meta "$STATE_DIR/tk4.meta" "window=fmses:fm-tk4" "kind=ship"   # no backend= -> tmux
+# shellcheck disable=SC2329 # Runtime override called by the isolated watcher.
+fm_backend_wait_transition() { printf 'CALLED\n' > "$TMP/wtcalled"; return 1; }
+event_wait_or_sleep
+[ ! -e "$TMP/wtcalled" ] || fail "a tmux-only home must never invoke the event wait path"
+grep -q 'SLEEP' "$SLEEP_LOG" || fail "a tmux-only home must sleep POLL exactly as before"
+pass "event_wait_or_sleep: a home with no push-capable window is inert (sleeps POLL, never touches the event path)"
+
+# --- event_wait_or_sleep: runtime failures disable the event path (fail-closed)
+
+reset_state
+fm_write_meta "$STATE_DIR/tk5.meta" "window=default:wG:pQ" "backend=herdr" "kind=ship"
+export EVENT_CAP_FAIL_MAX=2
+# shellcheck disable=SC2329 # Runtime overrides called by the isolated watcher.
+fm_backend_events_capable() { return 0; }
+# shellcheck disable=SC2329 # Runtime overrides called by the isolated watcher.
+fm_backend_wait_transition() { printf 'WT\n' >> "$TMP/wtcalls"; return 2; }
+: > "$TMP/wtcalls"
+event_wait_or_sleep   # fails=1
+event_wait_or_sleep   # fails=2 -> disable
+event_wait_or_sleep   # disabled: sleeps without calling wait_transition
+WTN=$(wc -l < "$TMP/wtcalls" | tr -d '[:space:]')
+[ "$WTN" = 2 ] || fail "after EVENT_CAP_FAIL_MAX connect failures the event path must be disabled for the process (expected 2 wait_transition calls, got $WTN)"
+pass "event_wait_or_sleep: consecutive event-path failures disable the fast-path and revert to pure polling (fail-closed)"
+
+echo "# fm-supervision-events.test.sh: all assertions passed"

package/.agents/tests/fm-supervision-instructions.test.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+# Tests for harness-aware supervision instruction rendering.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+TMP_ROOT=$(fm_test_tmproot fm-supervision-instructions)
+RENDER="$ROOT/bin/fm-supervision-instructions.sh"
+
+test_selected_harness_block_only() {
+  local out
+  out=$("$RENDER" --harness codex)
+  assert_contains "$out" "SUPERVISION OPERATING INSTRUCTIONS - primary harness: codex" "codex heading missing"
+  assert_contains "$out" "Mode: Codex foreground checkpoint." "codex snippet missing"
+  assert_contains "$out" "bin/fm-watch-checkpoint.sh" "codex checkpoint helper missing"
+  assert_not_contains "$out" "Mode: Claude Stop-hook-owned supervision." "renderer printed the claude snippet too"
+  assert_not_contains "$out" "Mode: Pi extension background wake." "renderer printed the pi snippet too"
+  pass "renderer prints exactly the selected harness block"
+}
+
+test_unknown_fallback() {
+  local out
+  out=$("$RENDER" --harness not-real)
+  assert_contains "$out" "primary harness: unknown" "unknown heading missing"
+  assert_contains "$out" "Mode: Unknown harness fallback." "unknown fallback snippet missing"
+  pass "renderer falls back to unknown.md for unverified harness names"
+}
+
+test_conditional_stanzas() {
+  local home config out
+  home="$TMP_ROOT/conditional-home"
+  config="$TMP_ROOT/conditional-config"
+  mkdir -p "$home/state" "$home/config" "$config"
+  out=$(FM_HOME="$home" FM_CONFIG_OVERRIDE="$config" "$RENDER" --harness codex --read-only 1 --afk 1 --x-mode 1)
+  assert_contains "$out" "- Lock: read-only" "read-only stanza missing"
+  assert_contains "$out" "- Away mode: active" "afk stanza missing"
+  assert_contains "$out" "- X mode: active" "x-mode stanza missing"
+  assert_contains "$out" "$config/x-mode.env" "x-mode stanza did not render the effective config path"
+  assert_contains "$out" 'Mode: Codex foreground checkpoint.' "codex snippet missing"
+  assert_not_contains "$out" "Source \`config/x-mode.env\`" "snippet kept the repo-relative x-mode config path"
+  pass "renderer includes read-only, afk, and effective x-mode current-state stanzas"
+}
+
+test_repair_lines() {
+  local home out
+  home="$TMP_ROOT/repair-home"
+  mkdir -p "$home/state" "$home/config"
+  out=$(FM_HOME="$home" FM_CODEX_WATCH_CHECKPOINT=7 "$RENDER" --harness codex --repair-line)
+  assert_contains "$out" "bin/fm-watch-checkpoint.sh --seconds 7" "codex repair line did not use checkpoint helper and env override"
+
+  out=$(FM_HOME="$home" "$RENDER" --harness claude --queue-pending 1 --repair-line)
+  assert_contains "$out" "After draining queued wakes" "queue-pending prefix missing"
+  assert_contains "$out" "watcher supervision needs Stop-owned automatic recovery" "claude pre-verification repair line is not neutral"
+  assert_not_contains "$out" "is broken" "claude pre-verification repair line claimed a verified mechanism failure"
+  assert_not_contains "$out" "FAILED" "claude pre-verification repair line emitted a verified failure notice"
+  assert_not_contains "$out" "manual background" "claude pre-verification repair line directed a manual background arm"
+  assert_not_contains "$out" "bin/fm-watch-arm.sh" "claude pre-verification repair line directed an arm command"
+
+  : > "$home/config/x-mode.env"
+  out=$(FM_HOME="$home" FM_CODEX_WATCH_CHECKPOINT=7 "$RENDER" --harness codex --x-mode 1 --repair-line)
+  assert_contains "$out" "source '$home/config/x-mode.env' first" "x-mode repair line did not source the effective cadence config"
+  assert_contains "$out" "bin/fm-watch-checkpoint.sh --seconds 7" "x-mode codex repair line lost the checkpoint helper"
+
+  out=$(FM_HOME="$home" "$RENDER" --harness opencode --read-only 1 --repair-line)
+  assert_contains "$out" "session holding the fleet lock" "read-only repair line missing"
+
+  out=$(FM_HOME="$home" "$RENDER" --harness pi --repair-line)
+  assert_contains "$out" "Pi tool fm_watch_arm_pi" "pi repair line does not direct the model to the extension-owned tool"
+  assert_not_contains "$out" "extension command /fm-watch-arm-pi" "pi repair line still directs the model to the human slash command"
+  pass "renderer repair-line mode is harness-aware and honors conditional state"
+}
+
+test_cross_harness_ordinary_continuation_and_repair_matrix() {
+  local ordinary out
+
+  out=$("$RENDER" --harness pi)
+  ordinary=$(printf '%s\n' "$out" | grep -F -- '- Ordinary wake:')
+  assert_contains "$ordinary" "Pi extension already owns watcher continuity" "pi ordinary-wake line does not leave continuity to the extension"
+  assert_not_contains "$ordinary" "fm_watch_arm_pi" "pi ordinary-wake line incorrectly calls the recovery tool"
+  out=$("$RENDER" --harness pi --repair-line)
+  assert_contains "$out" "fm_watch_arm_pi" "pi recovery line lost the extension-owned repair tool"
+
+  out=$("$RENDER" --harness opencode)
+  ordinary=$(printf '%s\n' "$out" | grep -F -- '- Ordinary wake:')
+  assert_contains "$ordinary" "plugin already owns watcher continuity" "opencode ordinary-wake line does not leave continuity to the plugin"
+  assert_not_contains "$ordinary" "bin/fm-watch-arm.sh" "opencode ordinary-wake line incorrectly calls the recovery probe"
+  out=$("$RENDER" --harness opencode --repair-line)
+  assert_contains "$out" "manual recovery probe" "opencode recovery line lost its manual probe"
+
+  out=$("$RENDER" --harness claude)
+  ordinary=$(printf '%s\n' "$out" | grep -F -- '- Ordinary wake:')
+  assert_contains "$ordinary" "Stop-owned auto-arm" "claude ordinary-wake line does not leave continuity to the Stop hook"
+  assert_contains "$ordinary" "bin/fm-claude-stop-autoarm.sh" "claude ordinary-wake line lost the auto-arm script name"
+  assert_contains "$ordinary" "do not arm another cycle" "claude ordinary-wake line does not forbid a model re-arm"
+  assert_not_contains "$ordinary" "bin/fm-watch-arm.sh" "claude ordinary-wake line incorrectly calls the manual arm"
+  out=$("$RENDER" --harness claude --repair-line)
+  assert_contains "$out" "watcher supervision needs Stop-owned automatic recovery" "claude recovery line lost its neutral automatic-recovery guidance"
+  assert_not_contains "$out" "is broken" "claude recovery line claimed failure before verification"
+  assert_not_contains "$out" "bin/fm-watch-arm.sh" "claude recovery line must not create a repeatable manual arm loop"
+
+  out=$("$RENDER" --harness grok)
+  ordinary=$(printf '%s\n' "$out" | grep -F -- '- Ordinary wake:')
+  assert_contains "$ordinary" "re-arm" "grok ordinary-wake line does not tell the model to re-arm"
+  assert_contains "$ordinary" "Grok tracked background task" "grok ordinary-wake line lost tracked background ownership"
+  assert_contains "$ordinary" "bin/fm-watch-arm.sh" "grok ordinary-wake line lost the background arm command"
+  out=$("$RENDER" --harness grok --repair-line)
+  assert_contains "$out" "Grok tracked background task" "grok recovery line lost its tracked background repair"
+  assert_contains "$out" "bin/fm-watch-arm.sh" "grok recovery line lost the arm command"
+
+  out=$("$RENDER" --harness codex)
+  ordinary=$(printf '%s\n' "$out" | grep -F -- '- Ordinary wake:')
+  assert_contains "$ordinary" "next foreground" "codex ordinary-wake line lost its foreground checkpoint"
+  assert_contains "$ordinary" "bin/fm-watch-checkpoint.sh" "codex ordinary-wake line lost the checkpoint command"
+  assert_not_contains "$ordinary" "bin/fm-watch-arm.sh" "codex ordinary-wake line incorrectly uses a background arm"
+  out=$("$RENDER" --harness codex --repair-line)
+  assert_contains "$out" "foreground checkpoint" "codex recovery line lost its checkpoint repair"
+  assert_contains "$out" "bin/fm-watch-checkpoint.sh" "codex recovery line lost the checkpoint command"
+
+  pass "renderer preserves every harness ordinary-continuation and missing-cycle repair path"
+}
+
+test_pi_signed_preserves_identity_with_pi_supervision_protocol() {
+  local out ordinary
+  out=$("$RENDER" --harness pi-signed)
+  assert_contains "$out" "primary harness: pi-signed" \
+    "pi-signed supervision normalized the visible runtime identity to pi"
+  assert_contains "$out" "Mode: Pi extension background wake." \
+    "pi-signed did not reuse Pi's authoritative supervision protocol"
+  ordinary=$(printf '%s\n' "$out" | grep -F -- '- Ordinary wake:')
+  assert_contains "$ordinary" "Pi extension already owns watcher continuity" \
+    "pi-signed ordinary-wake semantics diverged from Pi"
+  out=$("$RENDER" --harness pi-signed --repair-line)
+  assert_contains "$out" "Pi tool fm_watch_arm_pi" \
+    "pi-signed repair semantics diverged from Pi"
+  pass "pi-signed keeps its identity while sharing Pi's supervision protocol"
+}
+
+test_grok_is_background_notify() {
+  local out
+  out=$("$RENDER" --harness grok)
+  assert_contains "$out" "Mode: Grok background-notify supervision." "grok snippet missing background-notify mode"
+  assert_contains "$out" "background: true" "grok snippet missing tracked background tool instruction"
+  assert_contains "$out" "synthetic_reason: task_completed" "grok snippet missing auto-wake synthetic prompt detail"
+  assert_contains "$out" "bin/fm-watch-arm.sh" "grok snippet missing watcher arm"
+  assert_not_contains "$out" "__FM_X_MODE_ENV" "renderer leaked an x-mode path placeholder"
+  assert_not_contains "$out" "foreground checkpoint" "grok snippet must not be Codex-style foreground checkpoint"
+  out=$("$RENDER" --harness grok --repair-line)
+  assert_contains "$out" "Grok tracked background task" "grok repair line is not background-notify shaped"
+  pass "grok supervision is Claude-shaped background notify with passive Stop-hook backstop"
+}
+
+test_grok_command_sources_effective_config() {
+  local home config out
+  home="$TMP_ROOT/grok-home"
+  config="$TMP_ROOT/grok-config"
+  mkdir -p "$home/state" "$config"
+  out=$(FM_HOME="$home" FM_CONFIG_OVERRIDE="$config" "$RENDER" --harness grok --x-mode 1)
+  assert_contains "$out" "[ -f '$config/x-mode.env' ] && . '$config/x-mode.env'; exec bin/fm-watch-arm.sh" "grok arm command did not use the effective x-mode config path"
+  pass "grok rendered command sources the effective x-mode config"
+}
+
+test_pi_snippet_uses_effective_extension_path() {
+  local home out turnend watch
+  home="$TMP_ROOT/pi-home"
+  turnend="$ROOT/.pi/extensions/fm-primary-turnend-guard.ts"
+  watch="$ROOT/.pi/extensions/fm-primary-pi-watch.ts"
+  mkdir -p "$home/state" "$home/config"
+  out=$(FM_HOME="$home" "$RENDER" --harness pi)
+  assert_contains "$out" "-e $turnend -e $watch" "pi snippet did not render both effective extension launch paths"
+  assert_contains "$out" "The turn-end guard extension lives at \`$turnend\`" "pi snippet did not render the turn-end guard extension path"
+  assert_contains "$out" "The watcher extension lives at \`$watch\`" "pi snippet did not render the watcher extension path"
+  assert_contains "$out" "MAIN must not re-drain, re-run, or acknowledge it" "pi snippet lost merged-event ownership"
+  assert_contains "$out" "MAIN applies judgment about whether and how to surface, summarize, reference, or incorporate a merged sailboat outcome" "pi snippet imposed a mechanical sailboat treatment"
+  assert_not_contains "$out" "__FM_PI_EXT__" "renderer leaked the Pi extension path placeholder"
+  assert_not_contains "$out" "__FM_PI_TURNEND_EXT__" "renderer leaked the Pi turn-end extension path placeholder"
+  assert_not_contains "$out" "state/fm-primary-pi-watch.ts" "pi snippet kept the old generated state-relative extension path"
+  pass "pi supervision snippet renders the effective extension path"
+}
+
+test_selected_harness_block_only
+test_unknown_fallback
+test_conditional_stanzas
+test_repair_lines
+test_cross_harness_ordinary_continuation_and_repair_matrix
+test_pi_signed_preserves_identity_with_pi_supervision_protocol
+test_grok_is_background_notify
+test_grok_command_sources_effective_config
+test_pi_snippet_uses_effective_extension_path

package/.agents/tests/fm-tangle-guard.test.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# Behavior tests for the worktree-tangle guards.
+#
+# Firstmate is a treehouse-pooled git repo of itself: linked worktrees and
+# secondmate homes all sit at a detached HEAD on the default branch, while the
+# PRIMARY checkout (FM_ROOT) is a normal checkout on a real branch. The "tangle"
+# is a crewmate branching/committing in the primary instead of its own worktree,
+# stranding the primary on a feature branch. Two guards cover it:
+#   GUARD 1 (prevention) - the brief asserts isolation before its branch step, and
+#            fm-spawn refuses to launch unless the resolved worktree is isolated.
+#   GUARD 2 (detection)  - fm-guard and fm-bootstrap alarm when the primary is on
+#            a feature branch, and stay silent on the default branch or detached.
+# These cases pin: the shared lib's branch classification, the fm-guard banner,
+# the fm-bootstrap problem line, the brief assertion ordering, and the fm-spawn
+# abort - all hermetic over temp git repos and fakebins.
+set -u
+
+# shellcheck source=tests/fixtures.sh
+. "$(dirname "${BASH_SOURCE[0]}")/fixtures.sh"
+
+# shellcheck source=/dev/null
+. "$ROOT/bin/fm-tangle-lib.sh"
+
+TMP_ROOT=$(fm_test_tmproot fm-tangle-guard)
+fm_git_identity fmtest fmtest@example.invalid
+
+# A fresh git repo on `main` with one commit and a local origin. Echoes its path.
+make_repo() {
+  local dir=$1
+  git init -q -b main "$dir"
+  git -C "$dir" commit -q --allow-empty -m init
+  fm_git_add_origin "$dir" "$dir.origin.git"
+  printf '%s\n' "$dir"
+}
+
+# --- shared lib: branch classification --------------------------------------
+
+# fm_primary_tangle_branch is the whole scoping decision: a NAMED non-default
+# branch is the tangle; the default branch and detached HEAD are healthy.
+test_lib_classification() {
+  local repo n=0 label state branch expect out
+  repo=$(make_repo "$TMP_ROOT/lib-repo")
+  while IFS='|' read -r label state branch expect; do
+    [ -n "$label" ] || continue
+    n=$((n + 1))
+    case "$state" in
+      default)  git -C "$repo" checkout -q main ;;
+      feature)  git -C "$repo" checkout -q -B "$branch" ;;
+      detached) git -C "$repo" checkout -q main; git -C "$repo" checkout -q --detach ;;
+    esac
+    out=$(fm_primary_tangle_branch "$repo" || true)
+    [ "$out" = "$expect" ] || fail "$label: expected tangle='$expect', got '$out'"
+  done <<'ROWS'
+on the default branch is healthy|default||
+on a feature branch is the tangle|feature|fm/readme-restructure-d3|fm/readme-restructure-d3
+detached HEAD on default is healthy (worktrees, secondmate homes)|detached||
+ROWS
+  # A non-git directory is not a tangle and must not error.
+  out=$(fm_primary_tangle_branch "$TMP_ROOT" || true)
+  [ -z "$out" ] || fail "non-git dir wrongly reported a tangle: '$out'"
+  pass "fm_primary_tangle_branch: feature branch alarms; default/detached/non-git stay silent"
+}
+
+# --- GUARD 2a: fm-guard banner ----------------------------------------------
+
+run_guard() {
+  # Scope the guard to a temp repo as the primary checkout; state lives under it.
+  FM_ROOT_OVERRIDE="$1" FM_HOME="$1" "$ROOT/bin/fm-guard.sh" 2>&1
+}
+
+test_guard_banner() {
+  local repo out
+  repo=$(make_repo "$TMP_ROOT/guard-repo")
+
+  out=$(run_guard "$repo")
+  assert_not_contains "$out" "WORKTREE TANGLE" "guard alarmed while primary was on main"
+
+  git -C "$repo" checkout -q --detach
+  out=$(run_guard "$repo")
+  assert_not_contains "$out" "WORKTREE TANGLE" "guard alarmed on a detached HEAD (legitimate worktree state)"
+
+  git -C "$repo" checkout -q -B fm/tangle-aa1
+  out=$(run_guard "$repo")
+  assert_contains "$out" "WORKTREE TANGLE" "guard did not alarm on a feature branch in the primary"
+  assert_contains "$out" "fm/tangle-aa1" "guard banner did not name the offending branch"
+  assert_contains "$out" "checkout main" "guard banner did not print the restore remediation"
+  out=$(FM_GUARD_READ_ONLY=1 run_guard "$repo")
+  assert_contains "$out" "WORKTREE TANGLE" "read-only guard did not keep the tangle alarm"
+  assert_contains "$out" "read-only session must leave restore work" "read-only guard did not explain restore ownership"
+  assert_not_contains "$out" "checkout main" "read-only guard printed a state-changing restore command"
+  pass "fm-guard: bordered tangle banner fires only for a feature branch and suppresses repair commands in read-only mode"
+}
+
+# --- GUARD 2b: fm-bootstrap problem line ------------------------------------
+
+run_bootstrap() {
+  # No projects/ under the home keeps fleet sync inert; grep isolates the line.
+  FM_ROOT_OVERRIDE="$1" FM_HOME="$1" "$ROOT/bin/fm-bootstrap.sh" 2>/dev/null
+}
+
+test_bootstrap_line() {
+  local repo out
+  repo=$(make_repo "$TMP_ROOT/bootstrap-repo")
+
+  out=$(run_bootstrap "$repo" | grep '^TANGLE:' || true)
+  [ -z "$out" ] || fail "bootstrap emitted a TANGLE line while on main: $out"
+
+  git -C "$repo" checkout -q --detach
+  out=$(run_bootstrap "$repo" | grep '^TANGLE:' || true)
+  [ -z "$out" ] || fail "bootstrap emitted a TANGLE line on a detached HEAD: $out"
+
+  git -C "$repo" checkout -q -B fm/tangle-bb2
+  out=$(run_bootstrap "$repo" | grep '^TANGLE:' || true)
+  assert_contains "$out" "fm/tangle-bb2" "bootstrap did not report the tangled branch"
+  assert_contains "$out" "checkout main" "bootstrap TANGLE line lacked the restore remediation"
+  out=$(FM_ROOT_OVERRIDE="$repo" FM_HOME="$repo" FM_BOOTSTRAP_DETECT_ONLY=1 "$ROOT/bin/fm-bootstrap.sh" 2>/dev/null | grep '^TANGLE:' || true)
+  assert_contains "$out" "fm/tangle-bb2" "detect-only bootstrap did not report the tangled branch"
+  assert_contains "$out" "read-only session must leave restore work" "detect-only bootstrap did not explain restore ownership"
+  assert_not_contains "$out" "checkout main" "detect-only bootstrap printed a state-changing restore command"
+  pass "fm-bootstrap: TANGLE problem line fires only for a feature branch and suppresses repair commands in detect-only mode"
+}
+
+# --- GUARD 1a: brief isolation assertion ------------------------------------
+
+# The generated ship brief must carry the isolation assertion AHEAD of the
+# `git checkout -b` step, so the crewmate verifies its worktree before branching.
+test_brief_assertion_precedes_branch() {
+  local home brief iso br
+  home="$TMP_ROOT/brief-home"
+  mkdir -p "$home/data"
+  FM_HOME="$home" "$ROOT/bin/fm-brief.sh" tangle-brief-cc3 alpha --mode no-mistakes >/dev/null 2>&1
+  brief="$home/data/tangle-brief-cc3/brief.md"
+  assert_present "$brief" "brief was not scaffolded"
+  assert_grep "blocked: launched in primary checkout, not an isolated worktree" "$brief" \
+    "brief is missing the isolation blocked-status contract"
+  assert_grep "The path check is authoritative" "$brief" \
+    "brief must make the path check authoritative"
+  assert_no_grep "A reliable test that you are in a linked worktree" "$brief" \
+    "brief must not present git-dir/common-dir as decisive"
+  assert_no_grep "they are identical in the primary checkout" "$brief" \
+    "brief must not claim the primary checkout has identical git dirs"
+  iso=$(grep -n 'launched in primary checkout, not an isolated worktree' "$brief" | head -1 | cut -d: -f1)
+  br=$(grep -n 'git checkout -b fm/' "$brief" | head -1 | cut -d: -f1)
+  if [ -z "$iso" ] || [ -z "$br" ]; then
+    fail "brief missing assertion ($iso) or branch step ($br)"
+  fi
+  [ "$iso" -lt "$br" ] || fail "isolation assertion (line $iso) must precede the branch step (line $br)"
+  pass "fm-brief: ship brief asserts worktree isolation before the branch step"
+}
+
+# --- GUARD 1b: fm-spawn isolation abort -------------------------------------
+
+# Spawn isolation uses the shared spawn fakebin (pane path + window ops).
+run_spawn() {
+  local home=$1 id=$2 proj=$3 pane=$4 fakebin=$5
+  fm_test_spawn_brief "$home" "$id" brief
+  fm_test_run_spawn "$home" "$pane" "$fakebin" \
+    "$id" "$proj" codex --mode no-mistakes --yolo off
+}
+
+test_spawn_isolation_abort() {
+  local home proj fakebin out status
+  home="$TMP_ROOT/spawn-home"
+  mkdir -p "$home/data"
+  proj=$(make_repo "$TMP_ROOT/spawn-proj")
+  fakebin=$(make_spawn_fakebin "$TMP_ROOT/spawn-fake")
+  # A genuine isolated linked worktree of the project, detached on the default.
+  git -C "$proj" worktree add -q --detach "$TMP_ROOT/spawn-wt" >/dev/null 2>&1
+  mkdir -p "$TMP_ROOT/spawn-notgit" "$proj/sub"
+
+  # Abort: the pane resolves to a plain non-git directory (not a worktree at all).
+  out=$(run_spawn "$home" abort-notgit-dd4 "$proj" "$TMP_ROOT/spawn-notgit" "$fakebin"); status=$?
+  expect_code 1 "$status" "spawn into a non-worktree dir should abort"
+  assert_contains "$out" "did not yield an isolated worktree" "non-worktree spawn lacked the isolation error"
+  assert_absent "$home/state/abort-notgit-dd4.meta" "aborted spawn must not record meta"
+
+  # Abort: the pane resolves INTO the primary checkout (a subdir of PROJ_ABS).
+  out=$(run_spawn "$home" abort-primary-ee5 "$proj" "$proj/sub" "$fakebin"); status=$?
+  expect_code 1 "$status" "spawn landing inside the primary checkout should abort"
+  assert_contains "$out" "did not yield an isolated worktree" "primary-checkout spawn lacked the isolation error"
+
+  # Proceed: the pane resolves to a genuine, isolated worktree.
+  out=$(run_spawn "$home" ok-isolated-ff6 "$proj" "$TMP_ROOT/spawn-wt" "$fakebin"); status=$?
+  expect_code 0 "$status" "spawn into a genuine isolated worktree should succeed"
+  assert_contains "$out" "spawned ok-isolated-ff6" "isolated spawn did not report success"
+  assert_not_contains "$out" "did not yield an isolated worktree" "isolated spawn wrongly tripped the guard"
+  pass "fm-spawn: aborts unless the resolved worktree is a genuine, isolated worktree"
+}
+
+# --- GUARD 1c: fm-spawn tmux window construction ----------------------------
+
+# The prevention guard also depends on fm-spawn building robust tmux commands
+# under a non-default tmux config (base-index 1, automatic-rename on). A RECORDING
+# fake tmux logs every invocation and returns a sentinel window id, so these
+# assertions pin the command construction deterministically, with no live tmux:
+#   - window creation targets the session with a trailing colon (append form), so
+#     tmux appends at the next free index instead of the active window index, which
+#     collides under base-index 1;
+#   - the window id is captured (-P -F #{window_id}) and automatic-rename/allow-rename
+#     are disabled so the fm-<id> name survives treehouse cd'ing into the worktree;
+#   - the treehouse-get send-keys and the worktree wait loop target that stable
+#     window id, never the (possibly-renamed) name - a lost name would let
+#     display-message fall back to the active client's window and misread firstmate's
+#     OWN pane as the worktree, tangling a hook into the primary checkout.
+make_spawn_record_fakebin() {
+  local dir=$1 fakebin
+  fakebin=$(fm_fakebin "$dir")
+  cat > "$fakebin/tmux" <<'SH'
+#!/usr/bin/env bash
+set -u
+[ -n "${FM_TMUX_REC:-}" ] && printf 'tmux %s\n' "$*" >> "$FM_TMUX_REC"
+case "$*" in
+  *"#{pane_current_path}"*) printf '%s\n' "${FM_FAKE_PANE_PATH:-}"; exit 0 ;;
+esac
+case "${1:-}" in
+  display-message) printf 'firstmate\n'; exit 0 ;;
+  new-window) printf '%s\n' "@spawnwid"; exit 0 ;;
+  list-windows) exit 0 ;;
+  has-session|new-session|send-keys|set-window-option) exit 0 ;;
+esac
+exit 0
+SH
+  chmod +x "$fakebin/tmux"
+  fm_fake_exit0 "$fakebin" treehouse
+  printf '%s\n' "$fakebin"
+}
+
+run_spawn_record() {
+  local home=$1 id=$2 proj=$3 pane=$4 fakebin=$5 rec=$6
+  fm_test_spawn_brief "$home" "$id" brief
+  FM_TMUX_REC="$rec" \
+    fm_test_run_spawn "$home" "$pane" "$fakebin" \
+    "$id" "$proj" codex --mode no-mistakes --yolo off
+}
+
+test_spawn_tmux_window_construction() {
+  local home proj fakebin rec wt out status
+  home="$TMP_ROOT/spawn-rec-home"
+  mkdir -p "$home/data"
+  proj=$(make_repo "$TMP_ROOT/spawn-rec-proj")
+  fakebin=$(make_spawn_record_fakebin "$TMP_ROOT/spawn-rec-fake")
+  rec="$TMP_ROOT/spawn-rec.log"
+  : > "$rec"
+  wt="$TMP_ROOT/spawn-rec-wt"
+  git -C "$proj" worktree add -q --detach "$wt" >/dev/null 2>&1
+
+  out=$(run_spawn_record "$home" rec-win-gg7 "$proj" "$wt" "$fakebin" "$rec"); status=$?
+  expect_code 0 "$status" "spawn into a genuine worktree should succeed"
+  assert_contains "$out" "spawned rec-win-gg7" "recording spawn did not report success"
+
+  # Bug 1 fix: append-form window creation (trailing colon on the session target).
+  assert_grep "new-window -dP -F #{window_id} -t firstmate: -n fm-rec-win-gg7" "$rec" \
+    "new-window must append at the session (trailing colon) and capture the window id"
+  assert_no_grep "new-window -dP -F #{window_id} -t firstmate -n" "$rec" \
+    "new-window must not target the bare session name (collides under base-index 1)"
+
+  # Bug 2 fix (a): pin the window name against automatic-rename / allow-rename.
+  assert_grep "set-window-option -t @spawnwid automatic-rename off" "$rec" \
+    "must disable automatic-rename on the spawned window"
+  assert_grep "set-window-option -t @spawnwid allow-rename off" "$rec" \
+    "must disable allow-rename on the spawned window"
+
+  # Bug 2 fix (b): treehouse-get and the worktree wait loop target the stable id.
+  assert_grep "send-keys -t @spawnwid treehouse get Enter" "$rec" \
+    "treehouse get must be sent to the stable window id"
+  assert_grep "display-message -p -t @spawnwid #{pane_current_path}" "$rec" \
+    "the worktree wait loop must query the stable window id, not the name"
+
+  pass "fm-spawn: appends windows by session-colon, pins the name, and targets the window id"
+}
+
+test_lib_classification
+test_guard_banner
+test_bootstrap_line
+test_brief_assertion_precedes_branch
+test_spawn_isolation_abort
+test_spawn_tmux_window_construction