@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/tests/fm-herdr-session-cleanup-e2e.test.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# Real restored-shell E2E for home-local session-start Herdr projection cleanup.
+# Every CLI operation is routed through one guarded named non-default lab, and
+# lab teardown verifies that the default fleet session is byte-identical.
+set -u
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+HERDR_LAB_HELPER=${HERDR_LAB_HELPER:-$ROOT/bin/fm-herdr-lab.sh}
+
+fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; }
+pass() { printf 'ok - %s\n' "$1"; }
+
+command -v herdr >/dev/null 2>&1 || { echo 'skip: herdr not found'; exit 0; }
+command -v jq >/dev/null 2>&1 || { echo 'skip: jq not found'; exit 0; }
+command -v python3 >/dev/null 2>&1 || { echo 'skip: python3 not found'; exit 0; }
+[ -x "$HERDR_LAB_HELPER" ] || { echo "skip: Herdr lab helper not executable at $HERDR_LAB_HELPER"; exit 0; }
+
+REAL_HERDR=$(command -v herdr)
+HERDR_ORIGINAL_PATH=$PATH
+TMP_ROOT=$(mktemp -d "$(cd "${TMPDIR:-/tmp}" && pwd -P)/fm-herdr-session-cleanup-e2e.XXXXXX")
+FAKEBIN="$TMP_ROOT/fakebin"
+HOME_DIR="$TMP_ROOT/home"
+mkdir -p "$FAKEBIN" "$HOME_DIR/state" "$HOME_DIR/config"
+touch "$HOME_DIR/config/herdr-presentation-spaces"
+printf '%s\n' herdr > "$HOME_DIR/config/backend"
+
+HERDR_LAB_SESSION=$("$HERDR_LAB_HELPER" name fm-herdr-session-start-stale-projection-cleanup-r1)
+export HERDR_LAB_HELPER HERDR_LAB_SESSION REAL_HERDR HERDR_ORIGINAL_PATH
+cleanup() {
+  local status=$?
+  env PATH="$HERDR_ORIGINAL_PATH" "$HERDR_LAB_HELPER" teardown "$HERDR_LAB_SESSION" || status=1
+  rm -rf "$TMP_ROOT"
+  exit "$status"
+}
+trap cleanup EXIT
+"$HERDR_LAB_HELPER" provision "$HERDR_LAB_SESSION"
+
+# Keep the lab helper as the only CLI transport. Production adapter calls have
+# already appended the exact session; this shim strips that pair, refuses every
+# other caller-supplied session, and delegates the command to helper run.
+cat > "$FAKEBIN/herdr" <<'SH'
+#!/usr/bin/env bash
+set -u
+args=("$@")
+last=$((${#args[@]} - 1))
+flag=$((last - 1))
+if [ "${#args[@]}" -ge 2 ] \
+  && [ "${args[$flag]}" = --session ] \
+  && [ "${args[$last]}" = "$HERDR_LAB_SESSION" ]; then
+  unset "args[$last]" "args[$flag]"
+fi
+set -- "${args[@]}"
+for arg in "$@"; do
+  case "$arg" in --session|--session=*) exit 9 ;; esac
+done
+if [ "${1:-}" = --version ]; then
+  exec env PATH="$HERDR_ORIGINAL_PATH" "$REAL_HERDR" "$@" --session "$HERDR_LAB_SESSION"
+fi
+exec env PATH="$HERDR_ORIGINAL_PATH" "$HERDR_LAB_HELPER" run "$HERDR_LAB_SESSION" "$@"
+SH
+chmod +x "$FAKEBIN/herdr"
+
+lab() { env PATH="$HERDR_ORIGINAL_PATH" "$HERDR_LAB_HELPER" run "$HERDR_LAB_SESSION" "$@"; }
+production_process_proof() {
+  FM_HOME="$HOME_DIR" FM_BACKEND=herdr HERDR_SESSION="$HERDR_LAB_SESSION" \
+    FM_HERDR_SESSION_CLEANUP_SOURCE_ONLY=1 PATH="$FAKEBIN:$HERDR_ORIGINAL_PATH" \
+    bash -c '. "$1"; fm_backend_herdr_pane_idle_shell_pid "$2" "$3" >/dev/null' \
+      _ "$ROOT/bin/fm-herdr-session-cleanup.sh" "$HERDR_LAB_SESSION" "$PANE"
+}
+focus_snapshot() {
+  local list workspace tab tabs
+  list=$(lab workspace list) || return 1
+  workspace=$(printf '%s' "$list" | jq -er '[.result.workspaces[] | select(.focused == true)] | select(length == 1) | .[0].workspace_id') || return 1
+  tab=$(printf '%s' "$list" | jq -er --arg workspace "$workspace" '[.result.workspaces[] | select(.workspace_id == $workspace)] | select(length == 1) | .[0].active_tab_id') || return 1
+  tabs=$(lab tab list --workspace "$workspace") || return 1
+  printf '%s' "$tabs" | jq -e --arg tab "$tab" '([.result.tabs[] | select(.focused == true)] | length) == 1 and ([.result.tabs[] | select(.focused == true)][0].tab_id == $tab)' >/dev/null || return 1
+  printf '%s\t%s' "$workspace" "$tab"
+}
+
+ANCHOR=$(lab workspace create --cwd "$ROOT" --label captain-anchor --focus) || fail 'could not create focus anchor'
+ANCHOR_TAB=$(printf '%s' "$ANCHOR" | jq -r '.result.tab.tab_id')
+TOKEN=AbCdEfGhIjKlMnOpQrStUv
+ID=restored-idle-shell
+TITLE="└ $ID · p:$TOKEN"
+CANDIDATE=$(lab workspace create --cwd "$ROOT" --label "$TITLE" --no-focus) || fail 'could not create projected child fixture'
+WS=$(printf '%s' "$CANDIDATE" | jq -r '.result.workspace.workspace_id')
+PANE=$(printf '%s' "$CANDIDATE" | jq -r '.result.root_pane.pane_id')
+{
+  printf 'version=1\n'
+  printf 'task_id=%s\n' "$ID"
+  printf 'projection_id=%s\n' "$TOKEN"
+} > "$HOME_DIR/state/$ID.herdr-presentation"
+
+"$HERDR_LAB_HELPER" stop "$HERDR_LAB_SESSION" >/dev/null || fail 'could not stop named lab for restored-shell reproduction'
+"$HERDR_LAB_HELPER" provision "$HERDR_LAB_SESSION" || fail 'could not restore named lab layout'
+lab tab focus "$ANCHOR_TAB" >/dev/null || fail 'could not restore the anchor focus after lab restart'
+BEFORE_FOCUS=$(focus_snapshot) || fail 'could not capture exact pre-cleanup focus'
+[ "$BEFORE_FOCUS" = "$(printf '%s\t%s' "$(printf '%s' "$ANCHOR" | jq -r '.result.workspace.workspace_id')" "$ANCHOR_TAB")" ] \
+  || fail 'anchor focus does not match the exact intended workspace and tab'
+
+WORKSPACES=$(lab workspace list) || fail 'could not inspect restored workspaces'
+TABS=$(lab tab list --workspace "$WS") || fail 'could not inspect restored tabs'
+PANES=$(lab pane list --workspace "$WS") || fail 'could not inspect restored panes'
+[ "$(printf '%s' "$WORKSPACES" | jq --arg title "$TITLE" '[.result.workspaces[] | select(.label == $title)] | length')" = 1 ] \
+  || fail 'restored projected title is not unique'
+[ "$(printf '%s' "$TABS" | jq '.result.tabs | length')" = 1 ] || fail 'restored child is not one tab'
+[ "$(printf '%s' "$PANES" | jq '.result.panes | length')" = 1 ] || fail 'restored child is not one pane'
+if lab agent get "$PANE" >/dev/null 2>&1; then
+  fail 'restored child unexpectedly retained a registered agent'
+fi
+attempt=0
+while [ "$attempt" -lt 50 ]; do
+  if production_process_proof; then
+    break
+  fi
+  sleep 0.1
+  attempt=$((attempt + 1))
+done
+[ "$attempt" -lt 50 ] || fail 'restored child did not converge to the exact childless idle-shell process-group shape'
+pass 'real named lab reproduced the exact restored one-tab one-pane childless no-agent shell shape'
+
+FM_HOME="$HOME_DIR" FM_BACKEND=herdr HERDR_SESSION="$HERDR_LAB_SESSION" \
+  PATH="$FAKEBIN:$HERDR_ORIGINAL_PATH" "$ROOT/bin/fm-herdr-session-cleanup.sh" \
+  || fail 'session-start cleanup command failed'
+AFTER_FOCUS=$(focus_snapshot) || fail 'could not capture exact post-cleanup focus'
+[ "$AFTER_FOCUS" = "$BEFORE_FOCUS" ] || fail 'exact workspace/tab focus changed during cleanup'
+if lab pane get "$PANE" >/dev/null 2>&1; then
+  fail 'exact stale pane survived cleanup'
+fi
+if lab workspace get "$WS" >/dev/null 2>&1; then
+  fail 'last-pane side effect did not remove the stale projected child workspace'
+fi
+[ ! -e "$HOME_DIR/state/$ID.herdr-presentation" ] || fail 'matching journal survived confirmed exact pane closure'
+pass 'real named lab cleanup closes only the exact stale pane and preserves exact focus'
+
+FM_HOME="$HOME_DIR" FM_BACKEND=herdr HERDR_SESSION="$HERDR_LAB_SESSION" \
+  PATH="$FAKEBIN:$HERDR_ORIGINAL_PATH" "$ROOT/bin/fm-herdr-session-cleanup.sh" \
+  || fail 'idempotent repeat failed'
+[ "$(focus_snapshot)" = "$BEFORE_FOCUS" ] || fail 'idempotent repeat changed focus'
+lab pane get "$(printf '%s' "$ANCHOR" | jq -r '.result.root_pane.pane_id')" >/dev/null \
+  || fail 'anchor pane was touched by cleanup'
+STATUS=$(lab status --json) || fail 'could not read final named-lab version evidence'
+pass 'real named lab cleanup is idempotent and leaves the default fleet session to the teardown tripwire'
+printf 'evidence: herdr=%s protocol=%s default-session-tripwire=armed\n' \
+  "$(printf '%s' "$STATUS" | jq -r '.client.version')" \
+  "$(printf '%s' "$STATUS" | jq -r '.server.protocol')"

package/.agents/tests/fm-herdr-session-cleanup.test.sh

@@ -0,0 +1,329 @@
+#!/usr/bin/env bash
+# Focused safety tests for bin/fm-herdr-session-cleanup.sh.
+# Covers one exact cleanup, every title/journal/topology/agent/process refusal,
+# locked revalidation races, focus refusal, read errors, and repeat idempotence.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+TMP_ROOT=$(fm_test_tmproot fm-herdr-session-cleanup)
+FM_TEST_CLEANUP_DIRS+=("$TMP_ROOT")
+trap fm_test_cleanup EXIT
+
+export FM_HOME="$TMP_ROOT/home"
+export FM_STATE_OVERRIDE="$FM_HOME/state"
+export FM_CONFIG_OVERRIDE="$FM_HOME/config"
+mkdir -p "$FM_STATE_OVERRIDE" "$FM_CONFIG_OVERRIDE"
+touch "$FM_CONFIG_OVERRIDE/herdr-presentation-spaces"
+printf '%s\n' herdr > "$FM_CONFIG_OVERRIDE/backend"
+FAKEBIN=$(fm_fakebin "$TMP_ROOT")
+fm_fake_exit0 "$FAKEBIN" herdr
+export PATH="$FAKEBIN:$PATH"
+export FM_HERDR_SESSION_CLEANUP_SOURCE_ONLY=1
+# shellcheck source=/dev/null
+. "$ROOT/bin/fm-herdr-session-cleanup.sh"
+unset FM_HERDR_SESSION_CLEANUP_SOURCE_ONLY
+
+# The idle-shell proof now lives in the backend as
+# fm_backend_herdr_pane_idle_shell_pid; prove it still reads Linux argv
+# arrays (no argv0 field) and rejects malformed executable identities.
+FAKE_PS="$TMP_ROOT/fake-ps"
+cat > "$FAKE_PS" <<'SH'
+#!/usr/bin/env bash
+case "$*" in
+  "-axo pid=,ppid=") printf '1 0\n67 1\n' ;;
+  "-p 67 -o stat=") printf 'Ss\n' ;;
+  *) exit 1 ;;
+esac
+SH
+chmod +x "$FAKE_PS"
+LINUX_PROCESS_INFO='{"result":{"type":"pane_process_info","process_info":{"pane_id":"w2:p1","shell_pid":67,"foreground_process_group_id":67,"foreground_processes":[{"argv":["/bin/sh"],"name":"sh","pid":67}]}}}'
+argv_pid=$(
+  # shellcheck disable=SC2329 # invoked indirectly by the idle-shell proof.
+  fm_backend_herdr_cli() { printf '%s\n' "$LINUX_PROCESS_INFO"; }
+  FM_HERDR_PS_BIN="$FAKE_PS" fm_backend_herdr_pane_idle_shell_pid test w2:p1
+) || fail "Linux Herdr process argv array was not accepted"
+[ "$argv_pid" = 67 ] || fail "idle-shell proof printed the wrong shell pid: $argv_pid"
+if (
+  # shellcheck disable=SC2329 # invoked indirectly by the idle-shell proof.
+  fm_backend_herdr_cli() { printf '%s\n' '{"result":{"type":"pane_process_info","process_info":{"pane_id":"w2:p1","shell_pid":67,"foreground_process_group_id":67,"foreground_processes":[{"argv":[67],"name":"sh","pid":67}]}}}'; }
+  FM_HERDR_PS_BIN="$FAKE_PS" FM_BACKEND_HERDR_IDLE_SHELL_PROOF_POLLS=1 \
+    fm_backend_herdr_pane_idle_shell_pid test w2:p1
+) >/dev/null 2>&1; then
+  fail "non-string Herdr process argv was accepted"
+fi
+pass "process proof reads Linux Herdr argv arrays and rejects malformed executable identities"
+
+TOKEN=AbCdEfGhIjKlMnOpQrStUv
+ID=task
+WS=w2
+TAB=w2:t1
+PANE=w2:p1
+TITLE="└ task · p:$TOKEN"
+FIXTURE_DIR="$TMP_ROOT/fixture"
+LOCK_LOG="$TMP_ROOT/locks.log"
+CLOSE_LOG="$TMP_ROOT/closes.log"
+mkdir -p "$FIXTURE_DIR"
+
+fm_backend_name() { printf herdr; }
+fm_backend_herdr_session() { printf test; }
+fm_backend_herdr_presentation_session_lock_path() { printf '%s/presentation.lock' "$TMP_ROOT"; }
+fm_lock_try_acquire() {
+  printf '%s\n' "$1" >> "$LOCK_LOG"
+  mkdir "$1" 2>/dev/null
+}
+fm_lock_release() { rm -rf -- "$1"; }
+fm_backend_herdr_pane_idle_shell_pid() { [ ! -e "$FIXTURE_DIR/process-unsafe" ] && printf '67\n'; }
+fm_backend_herdr_projection_focus_snapshot() {
+  [ ! -e "$FIXTURE_DIR/focus-unreadable" ] || return 1
+  printf 'w1\t%s' "$(cat "$FIXTURE_DIR/active-tab")"
+}
+
+fixture_workspace_json() {
+  local title=$1 tabs=$2 panes=$3 focused=false active=$TAB
+  [ "$(cat "$FIXTURE_DIR/active-tab")" = "$TAB" ] && focused=true
+  printf '{"workspace_id":"%s","label":"%s","focused":%s,"active_tab_id":"%s","tab_count":%s,"pane_count":%s}' \
+    "$WS" "$title" "$focused" "$active" "$tabs" "$panes"
+}
+
+fixture_workspaces() {
+  local title tabs panes
+  title=$(cat "$FIXTURE_DIR/title")
+  tabs=$(cat "$FIXTURE_DIR/tabs")
+  panes=$(cat "$FIXTURE_DIR/panes")
+  printf '[{"workspace_id":"w1","label":"firstmate","focused":%s,"active_tab_id":"w1:t1","tab_count":1,"pane_count":1},' \
+    "$( [ "$(cat "$FIXTURE_DIR/active-tab")" = w1:t1 ] && printf true || printf false )"
+  fixture_workspace_json "$title" "$tabs" "$panes"
+  if [ -e "$FIXTURE_DIR/duplicate-token" ]; then
+    printf ',{"workspace_id":"w3","label":"└ copy · p:%s","focused":false,"active_tab_id":"w3:t1","tab_count":1,"pane_count":1}' "$TOKEN"
+  fi
+  printf ']'
+}
+
+fixture_tabs() {
+  local count i
+  count=$(cat "$FIXTURE_DIR/tabs")
+  printf '['
+  i=1
+  while [ "$i" -le "$count" ]; do
+    [ "$i" -eq 1 ] || printf ','
+    printf '{"tab_id":"%s:t%s","workspace_id":"%s","focused":false,"label":"fm-task"}' "$WS" "$i" "$WS"
+    i=$((i + 1))
+  done
+  printf ']'
+}
+
+fixture_panes() {
+  local count i
+  count=$(cat "$FIXTURE_DIR/panes")
+  printf '['
+  i=1
+  while [ "$i" -le "$count" ]; do
+    [ "$i" -eq 1 ] || printf ','
+    printf '{"pane_id":"%s:p%s","tab_id":"%s:t%s","workspace_id":"%s","agent_status":"unknown"}' \
+      "$WS" "$i" "$WS" "$i" "$WS"
+    i=$((i + 1))
+  done
+  printf ']'
+}
+
+fm_backend_herdr_cli() {
+  local _session=$1 first=${2:-} second=${3:-} title tabs panes
+  shift
+  [ ! -e "$FIXTURE_DIR/error-${first}-${second}" ] || return 1
+  if [ -e "$FIXTURE_DIR/closed" ]; then
+    case "$first $second" in
+      "pane get") printf '%s\n' '{"error":{"code":"pane_not_found"}}' >&2; return 1 ;;
+      "workspace list") printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate","focused":true,"active_tab_id":"w1:t1","tab_count":1,"pane_count":1}]}}'; return 0 ;;
+    esac
+  fi
+  if [ -e "$FIXTURE_DIR/race" ] && [ -e "$FIXTURE_DIR/snapshotted" ] && [ "$first $second" = "workspace list" ]; then
+    printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate","focused":true,"active_tab_id":"w1:t1","tab_count":1,"pane_count":1},{"workspace_id":"w2","label":"renamed","focused":false,"active_tab_id":"w2:t1","tab_count":1,"pane_count":1}]}}'
+    return 0
+  fi
+  title=$(cat "$FIXTURE_DIR/title")
+  tabs=$(cat "$FIXTURE_DIR/tabs")
+  panes=$(cat "$FIXTURE_DIR/panes")
+  case "$first $second" in
+    "workspace list")
+      printf '{"result":{"workspaces":'; fixture_workspaces; printf '}}\n'
+      ;;
+    "workspace get")
+      printf '{"result":{"workspace":'; fixture_workspace_json "$title" "$tabs" "$panes"; printf '}}\n'
+      ;;
+    "tab list")
+      printf '{"result":{"tabs":'; fixture_tabs; printf '}}\n'
+      ;;
+    "pane list")
+      printf '{"result":{"panes":'; fixture_panes; printf '}}\n'
+      ;;
+    "pane get")
+      printf '{"result":{"pane":{"pane_id":"%s","tab_id":"%s","workspace_id":"%s"}}}\n' "$PANE" "$TAB" "$WS"
+      ;;
+    "agent get")
+      case "$(cat "$FIXTURE_DIR/agent")" in
+        absent) printf '%s\n' '{"error":{"code":"agent_not_found"}}' >&2; return 1 ;;
+        live) printf '%s\n' '{"result":{"agent":{"agent_status":"idle"}}}' ;;
+        unknown) printf '%s\n' '{"error":{"code":"internal_error"}}' >&2; return 1 ;;
+      esac
+      ;;
+    "api snapshot")
+      : > "$FIXTURE_DIR/snapshotted"
+      printf '{"result":{"snapshot":{"focused_workspace_id":"w1","focused_tab_id":"%s","focused_pane_id":"w1:p1","workspaces":' "$(cat "$FIXTURE_DIR/active-tab")"
+      fixture_workspaces
+      printf ',"tabs":'; fixture_tabs
+      printf ',"panes":'; fixture_panes
+      printf '}}}\n'
+      ;;
+    "session list")
+      printf '%s\n' '{"sessions":[{"name":"test","running":true,"socket_path":"/tmp/fake.sock"}]}'
+      ;;
+    "pane close")
+      : > "$FIXTURE_DIR/closed"
+      ;;
+    *) return 1 ;;
+  esac
+}
+
+fm_backend_herdr_projection_close_pane_focus_preserving() {
+  [ ! -e "$FIXTURE_DIR/focus-refuse" ] || return 1
+  [ "${3:-}" = no-agent ] || return 1
+  printf '%s\n' "$*" >> "$CLOSE_LOG"
+  : > "$FIXTURE_DIR/closed"
+}
+
+write_v1() { # <id> [token]
+  local id=$1 token=${2:-$TOKEN}
+  {
+    printf 'version=1\n'
+    printf 'task_id=%s\n' "$id"
+    printf 'projection_id=%s\n' "$token"
+  } > "$FM_STATE_OVERRIDE/$id.herdr-presentation"
+}
+
+write_v2() { # <home> <workspace> <tab> <pane>
+  local home=$1 workspace=$2 tab=$3 pane=$4
+  {
+    printf 'version=2\n'
+    printf 'task_id=%s\n' "$ID"
+    printf 'projection_id=%s\n' "$TOKEN"
+    printf 'home=%s\n' "$home"
+    printf 'session=test\nworkspace_id=%s\ntab_id=%s\npane_id=%s\n' "$workspace" "$tab" "$pane"
+    printf 'parent_workspace_id=w1\nparent_label=firstmate\nworkspace_label=%s\ntask_label=fm-%s\n' "$TITLE" "$ID"
+  } > "$FM_STATE_OVERRIDE/$ID.herdr-presentation"
+}
+
+write_cross_home_v2() {
+  mkdir -p "$TMP_ROOT/other-home"
+  write_v2 "$TMP_ROOT/other-home" "$WS" "$TAB" "$PANE"
+}
+
+reset_fixture() {
+  rm -rf "$FIXTURE_DIR" "$TMP_ROOT"/*.lock "${FM_STATE_OVERRIDE:?}/"*
+  mkdir -p "$FIXTURE_DIR"
+  : > "$LOCK_LOG"; : > "$CLOSE_LOG"
+  printf '%s\n' "$TITLE" > "$FIXTURE_DIR/title"
+  printf '1\n' > "$FIXTURE_DIR/tabs"
+  printf '1\n' > "$FIXTURE_DIR/panes"
+  printf 'w1:t1\n' > "$FIXTURE_DIR/active-tab"
+  printf 'absent\n' > "$FIXTURE_DIR/agent"
+  write_v1 "$ID"
+}
+
+assert_preserved() { # <case>
+  local name=$1 had_journal=0
+  [ -f "$FM_STATE_OVERRIDE/$ID.herdr-presentation" ] && had_journal=1
+  fm_herdr_session_cleanup >/dev/null 2>&1
+  if [ "$had_journal" -eq 1 ]; then
+    [ -f "$FM_STATE_OVERRIDE/$ID.herdr-presentation" ] || fail "$name retired the journal"
+  fi
+  [ ! -s "$CLOSE_LOG" ] || fail "$name closed the pane"
+  pass "$name preserves the candidate"
+}
+
+reset_fixture
+fm_herdr_session_cleanup >/dev/null 2>&1
+[ ! -e "$FM_STATE_OVERRIDE/$ID.herdr-presentation" ] || fail "positive cleanup kept the journal"
+[ "$(wc -l < "$CLOSE_LOG" | tr -d ' ')" = 1 ] || fail "positive cleanup did not close exactly once"
+[ "$(sed -n '1p' "$LOCK_LOG")" = "$FM_STATE_OVERRIDE/.spawn-$ID.lock" ] || fail "task lock was not acquired first"
+[ "$(sed -n '2p' "$LOCK_LOG")" = "$TMP_ROOT/presentation.lock" ] || fail "presentation lock was not acquired second"
+pass "exact stale projection closes one exact pane under task then presentation locks"
+fm_herdr_session_cleanup >/dev/null 2>&1
+[ "$(wc -l < "$CLOSE_LOG" | tr -d ' ')" = 1 ] || fail "repeat cleanup closed again"
+pass "successful cleanup is idempotent on repeat"
+
+reset_fixture; printf '%s\n' '└ malformed p:AbCdEfGhIjKlMnOpQrStUv' > "$FIXTURE_DIR/title"; assert_preserved "malformed title"
+reset_fixture; printf '%s\n' '└ missing-token' > "$FIXTURE_DIR/title"; assert_preserved "missing token"
+reset_fixture; printf 'version=1\ntask_id=%s\nprojection_id=short\n' "$ID" > "$FM_STATE_OVERRIDE/$ID.herdr-presentation"; assert_preserved "malformed journal"
+reset_fixture; : > "$FIXTURE_DIR/duplicate-token"; assert_preserved "duplicate token"
+reset_fixture; printf '%s\n' "└ task · p:$TOKEN p:$TOKEN" > "$FIXTURE_DIR/title"; assert_preserved "duplicate title token"
+reset_fixture; rm -f "$FM_STATE_OVERRIDE/$ID.herdr-presentation"; assert_preserved "zero journal match"
+reset_fixture; write_v1 fm-task; assert_preserved "multiple journal matches"
+reset_fixture; rm -f "$FM_STATE_OVERRIDE/$ID.herdr-presentation"; write_cross_home_v2; assert_preserved "cross-home journal"
+reset_fixture; write_v2 "$FM_HOME" w9 "$TAB" "$PANE"; assert_preserved "v2 workspace binding mismatch"
+reset_fixture; write_v2 "$FM_HOME" "$WS" w9:t1 "$PANE"; assert_preserved "v2 tab binding mismatch"
+reset_fixture; write_v2 "$FM_HOME" "$WS" "$TAB" w9:p1; assert_preserved "v2 pane binding mismatch"
+reset_fixture; write_v2 "$FM_HOME" "$WS" "$TAB" "$PANE"
+fm_herdr_session_cleanup >/dev/null 2>&1
+[ ! -e "$FM_STATE_OVERRIDE/$ID.herdr-presentation" ] || fail "matching v2 cleanup kept the journal"
+[ "$(wc -l < "$CLOSE_LOG" | tr -d ' ')" = 1 ] || fail "matching v2 cleanup did not close exactly once"
+pass "v2 cleanup requires and accepts the exact journal endpoint binding"
+reset_fixture; : > "$FM_STATE_OVERRIDE/$ID.meta"; assert_preserved "current task metadata"
+reset_fixture; printf 'live\n' > "$FIXTURE_DIR/agent"; assert_preserved "registered agent"
+reset_fixture; printf 'unknown\n' > "$FIXTURE_DIR/agent"; assert_preserved "unknown agent"
+reset_fixture; printf '2\n' > "$FIXTURE_DIR/tabs"; printf '2\n' > "$FIXTURE_DIR/panes"; assert_preserved "multiple tabs"
+reset_fixture; printf '2\n' > "$FIXTURE_DIR/panes"; assert_preserved "multiple panes"
+reset_fixture; : > "$FIXTURE_DIR/process-unsafe"; assert_preserved "non-idle shell"
+reset_fixture; : > "$FIXTURE_DIR/process-unsafe"; assert_preserved "child process or shell job"
+reset_fixture; : > "$FIXTURE_DIR/error-api-snapshot"; assert_preserved "unreadable snapshot"
+reset_fixture; : > "$FIXTURE_DIR/error-workspace-get"; assert_preserved "unreadable topology check"
+reset_fixture; : > "$FIXTURE_DIR/race"; assert_preserved "revalidation race"
+reset_fixture; printf '%s\n' "$TAB" > "$FIXTURE_DIR/active-tab"; assert_preserved "active target"
+reset_fixture; : > "$FIXTURE_DIR/focus-refuse"; assert_preserved "focus refusal"
+
+INTEGRATION_ROOT="$TMP_ROOT/bootstrap-integration"
+mkdir -p "$INTEGRATION_ROOT/home/state" "$INTEGRATION_ROOT/home/data" "$INTEGRATION_ROOT/home/config"
+cp -R "$ROOT/bin" "$INTEGRATION_ROOT/bin"
+TRACE="$INTEGRATION_ROOT/cleanup.trace"
+cat > "$INTEGRATION_ROOT/bin/fm-herdr-session-cleanup.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' "${FM_HOME:?}" >> "${FM_HERDR_CLEANUP_TRACE:?}"
+SH
+chmod +x "$INTEGRATION_ROOT/bin/fm-herdr-session-cleanup.sh"
+printf '%s\n' manual > "$INTEGRATION_ROOT/home/config/backlog-backend"
+FM_HOME="$INTEGRATION_ROOT/home" FM_HERDR_CLEANUP_TRACE="$TRACE" FM_BOOTSTRAP_DETECT_ONLY=1 \
+  "$INTEGRATION_ROOT/bin/fm-bootstrap.sh" >/dev/null 2>&1
+[ ! -e "$TRACE" ] || fail "detect-only bootstrap ran stale projection cleanup"
+FM_HOME="$INTEGRATION_ROOT/home" FM_HERDR_CLEANUP_TRACE="$TRACE" \
+  "$INTEGRATION_ROOT/bin/fm-bootstrap.sh" >/dev/null 2>&1
+[ ! -e "$TRACE" ] || fail "standalone bootstrap ran lock-owned stale projection cleanup"
+pass "standalone bootstrap cannot run lock-owned stale projection cleanup"
+
+cat > "$INTEGRATION_ROOT/bin/fm-lock.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' 'lock acquired'
+SH
+chmod +x "$INTEGRATION_ROOT/bin/fm-lock.sh"
+FM_HOME="$INTEGRATION_ROOT/home" FM_ROOT_OVERRIDE="$INTEGRATION_ROOT" \
+  FM_HERDR_CLEANUP_TRACE="$TRACE" \
+  "$INTEGRATION_ROOT/bin/fm-session-start.sh" >/dev/null 2>&1 \
+  || fail "lock-owning session start failed"
+[ "$(cat "$TRACE")" = "$INTEGRATION_ROOT/home" ] \
+  || fail "lock-owning session start did not run cleanup for its exact home"
+
+: > "$TRACE"
+cat > "$INTEGRATION_ROOT/bin/fm-lock.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' 'error: another live firstmate session holds the lock' >&2
+exit 1
+SH
+chmod +x "$INTEGRATION_ROOT/bin/fm-lock.sh"
+FM_HOME="$INTEGRATION_ROOT/home" FM_ROOT_OVERRIDE="$INTEGRATION_ROOT" \
+  FM_HERDR_CLEANUP_TRACE="$TRACE" \
+  "$INTEGRATION_ROOT/bin/fm-session-start.sh" >/dev/null 2>&1 \
+  || fail "read-only session start failed"
+[ ! -s "$TRACE" ] || fail "read-only session start ran stale projection cleanup"
+pass "session start runs cleanup only after acquiring its home lock"
+
+printf 'all fm-herdr-session-cleanup tests passed\n'

package/.agents/tests/fm-herdr-submit-confirm-live-e2e.test.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Live Herdr submit-confirmation guard (live-harness-optin family).
+#
+# Herdr's native agent_status can stay idle for a whole landed Claude turn, and
+# a busy-queued Enter can keep proven pending text visible. A stub cannot prove
+# either signal. This guard launches real Claude Code in an isolated Herdr lab
+# and requires fm_backend_herdr_send_text_submit to report empty for a landed
+# idle steer. It fails naming the harness and version rather than degrading
+# quietly.
+#
+# Run explicitly with FM_HERDR_SUBMIT_CONFIRM_LIVE=1 after a Herdr or Claude
+# upgrade, and before trusting a refreshed docs/verification/runtime-backends.md
+# "Herdr submit confirmation" entry.
+# Every Herdr call, including adapter calls, is routed through bin/fm-herdr-lab.sh.
+set -u
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LAB_HELPER=${HERDR_LAB_HELPER:-$ROOT/bin/fm-herdr-lab.sh}
+
+fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; }
+pass() { printf 'ok - %s\n' "$1"; }
+
+if [ "${FM_HERDR_SUBMIT_CONFIRM_LIVE:-0}" != 1 ]; then
+  echo "skip: set FM_HERDR_SUBMIT_CONFIRM_LIVE=1 to run the live Herdr submit-confirmation guard"
+  exit 0
+fi
+
+command -v herdr >/dev/null 2>&1 || fail "FM_HERDR_SUBMIT_CONFIRM_LIVE=1 but herdr is not installed"
+command -v jq >/dev/null 2>&1 || fail "FM_HERDR_SUBMIT_CONFIRM_LIVE=1 but jq is not installed"
+command -v claude >/dev/null 2>&1 || fail "FM_HERDR_SUBMIT_CONFIRM_LIVE=1 but Claude Code is not installed"
+[ -x "$LAB_HELPER" ] || fail "FM_HERDR_SUBMIT_CONFIRM_LIVE=1 but the Herdr lab helper is not executable at $LAB_HELPER"
+
+# shellcheck source=tests/herdr-test-safety.sh
+. "$ROOT/tests/herdr-test-safety.sh"
+herdr_forget_inherited_pane
+
+ORIGINAL_PATH=$PATH
+SESSION=$("$LAB_HELPER" name herdr-submit-confirm-live)
+TMP_ROOT=$(mktemp -d "$(cd "${TMPDIR:-/tmp}" && pwd -P)/fm-herdr-submit-confirm-live.XXXXXX")
+FAKEBIN="$TMP_ROOT/fakebin"
+mkdir -p "$FAKEBIN"
+CHECKED=0
+
+cleanup() {
+  local rc=$?
+  trap - EXIT
+  if ! PATH="$ORIGINAL_PATH" "$LAB_HELPER" teardown "$SESSION"; then
+    rc=1
+  fi
+  rm -rf "$TMP_ROOT"
+  exit "$rc"
+}
+trap cleanup EXIT
+
+cat > "$FAKEBIN/herdr" <<EOF
+#!/usr/bin/env bash
+set -u
+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
+  echo "wrapper requires trailing --session $SESSION" >&2
+  exit 98
+fi
+exec env PATH="$ORIGINAL_PATH" "$LAB_HELPER" run "$SESSION" "\${args[@]}"
+EOF
+chmod +x "$FAKEBIN/herdr"
+
+"$LAB_HELPER" provision "$SESSION" || fail "could not provision the isolated Herdr lab"
+export PATH="$FAKEBIN:$ORIGINAL_PATH"
+
+# shellcheck source=/dev/null
+. "$ROOT/bin/backends/herdr.sh"
+
+lab() { env PATH="$ORIGINAL_PATH" "$LAB_HELPER" run "$SESSION" "$@"; }
+WS_JSON=$(lab workspace create --cwd "$ROOT" --label fm-submitlive --no-focus) \
+  || fail "could not create the isolated submit-confirm workspace"
+PANE=$(printf '%s' "$WS_JSON" | jq -er '.result.root_pane.pane_id') \
+  || fail "workspace create did not return a pane id"
+TARGET="$SESSION:$PANE"
+VERSION=$(PATH="$ORIGINAL_PATH" claude --version 2>/dev/null | head -1 || printf 'version-unknown')
+HERDR_VER=$(PATH="$ORIGINAL_PATH" herdr --version 2>/dev/null | head -1 || printf 'herdr-unknown')
+
+lab pane run "$PANE" "CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false claude --dangerously-skip-permissions" >/dev/null \
+  || fail "could not launch Claude Code ($VERSION) in the isolated Herdr pane"
+
+idle=0
+i=0
+while [ "$i" -lt 45 ]; do
+  st=$(lab agent get "$PANE" 2>/dev/null | jq -r '.result.agent.agent_status // empty')
+  case "$st" in idle|done|blocked) idle=1; break ;; esac
+  i=$((i + 1))
+  sleep 1
+done
+[ "$idle" = 1 ] || fail "Claude Code ($VERSION) on $HERDR_VER never registered an idle agent in the lab pane"
+
+TOKEN="FMHERDRPONG$$_$RANDOM"
+verdict=$(fm_backend_herdr_send_text_submit "$TARGET" "Reply with exactly $TOKEN and nothing else." 3 0.4 0.4) \
+  || fail "send_text_submit failed to run against Claude Code ($VERSION) on $HERDR_VER"
+CHECKED=1
+[ "$verdict" = empty ] \
+  || fail "Claude Code ($VERSION) on $HERDR_VER: a landed idle steer must confirm empty, got '$verdict'"
+
+# Confirm the instruction reached Claude, not merely that the composer cleared.
+# The token occurs once in the submitted prompt and once in Claude's reply.
+landed=0
+i=0
+screen=''
+while [ "$i" -lt 45 ]; do
+  screen=$(lab pane read "$PANE" --source recent --lines 200 2>/dev/null || true)
+  occurrences=$(printf '%s\n' "$screen" | grep -F -c "$TOKEN" || true)
+  if [ "$occurrences" -ge 2 ]; then
+    landed=1
+    break
+  fi
+  i=$((i + 1))
+  sleep 1
+done
+[ "$landed" = 1 ] \
+  || fail "Claude Code ($VERSION) on $HERDR_VER: submit reported '$verdict' but the expected reply never rendered"
+pass "live Herdr submit confirm: Claude Code ($VERSION) on $HERDR_VER reports empty and renders the requested reply in isolated session $SESSION"
+
+[ "$CHECKED" -gt 0 ] || fail "FM_HERDR_SUBMIT_CONFIRM_LIVE=1 checked no harness"