From 69023626c39b8bde20ca777e78ae4ae91f541094 Mon Sep 17 00:00:00 2001 From: Khai Nguyen Date: Tue, 3 Nov 2026 03:34:16 -0800 Subject: [PATCH 01/34] fix(bin): share timed background launch and isolate terminal stdin (#8099) * fix(timeout): keep redirected stdin on backgrounded runners Non-interactive bash assigns /dev/null to an async command, so the external timeout and bash runners dropped a piped payload before it reached the command. Restore that stdin with an explicit redirection, leave a terminal or closed stdin on the old assignment, and cover every mechanism the host can select. * no-mistakes(test): Give terminal stdin /dev/null in timed background runs * no-mistakes(ci): No new code change is needed. The fix for ci-1 is already in commit db61d47a, which is HEAD, and the working tree is clean. Greptile pointed out that the old fd 3 check could never fail: fm_run_timed ran inside a pipeline subshell while `echo still >&3` ran in the parent shell. The committed test now calls the runner directly, with stdin redirected from a file, in the same shell that then writes to fd 3. It covers the external-timeout mechanism when one is installed and always covers the bash override. It checks the exit status, that the fd 3 write landed, and that the payload came through. Following the driver's instructions, I kept that commit and did not rework it. I re-ran `bash tests/fm-timeout-lib.test.sh` and it exited 0 with every case passing. The Greptile check is still failing only because the earlier push to the PR hit a GitHub Internal Server Error and never landed. The test code is not the cause. Re-publishing the existing commit through the pipeline will resolve it, and that step belongs to the outer executor --- bin/fm-timeout-lib.sh | 50 +++++++++++---- tests/fm-timeout-lib.test.sh | 119 +++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+), 11 deletions(-) diff --git a/bin/fm-timeout-lib.sh b/bin/fm-timeout-lib.sh index 26bb08f199e..777a374bc1f 100644 --- a/bin/fm-timeout-lib.sh +++ b/bin/fm-timeout-lib.sh @@ -27,7 +27,10 @@ # exit, and is reported as 124 too. Only 137 raised by GNU/BSD timeout's # own KILL escalation, with no status recorded by the bounded command, # also collapses into 124: there it means the bound fired, not that the -# command chose to die. +# command chose to die. A pipe or file on standard input reaches the +# command on every mechanism. The timeout and bash mechanisms background +# the command and restore that redirected stdin afterwards; they do not +# attach a terminal, and a closed stdin does not fail the call. # # fm_exec_timed [args...] # Replaces the calling shell with the bounded command, so it must be the @@ -105,6 +108,36 @@ fm_timeout_mechanism() { fi } +# True when stdin is a pipe or file. A terminal is not a redirected payload, +# and a closed stdin cannot be duplicated. +fm_timeout_stdin_is_redirected() { + [ ! -t 0 ] && ( exec 3<&0 ) 2>/dev/null +} + +# Background "$@" and keep a redirected stdin. A non-interactive bash assigns +# /dev/null to an async command's stdin, then applies explicit redirections, so +# 0<&3 restores the dup. The group redirection is undone when the group ends, +# and 3<&- keeps the spare fd out of the child. A terminal or closed stdin gets +# an explicit /dev/null: under set -m (the bash mechanism) bash skips its +# implicit one, which would hand the terminal to a background process group. +fm_timeout_background() { + if fm_timeout_stdin_is_redirected; then + { "$@" 0<&3 3<&- & } 3<&0 + else + "$@" "$status_file" + exit "$command_rc" +} + fm_run_bash_timeout() { local seconds=$1 command_status deadline_status child_pid watchdog_pid command_rc recorded_rc monitor_was_on=0 shift @@ -112,13 +145,7 @@ fm_run_bash_timeout() { deadline_status="${command_status}.deadline" case $- in *m*) monitor_was_on=1 ;; esac set -m - ( - set +m - "$@" - command_rc=$? - printf '%s\n' "$command_rc" > "$command_status" - exit "$command_rc" - ) <&0 & + fm_timeout_background fm_bash_timeout_child "$command_status" "$@" child_pid=$! ( set +m @@ -157,19 +184,20 @@ fm_run_external_timeout() { # Run the executable path asynchronously (never a bare name: that is the omp # timeout builtin, and backgrounding it leaves $! empty) so its pid - also # the process-group id created by GNU/BSD timeout without --foreground - - # remains available for cleanup. + # remains available for cleanup. fm_timeout_background keeps a redirected + # stdin across that async assignment. # A shell wrapper can exit promptly on TERM while one of its descendants # ignores TERM; timeout then considers the command finished and does not send # its configured KILL. Explicitly reap that leftover group on a real timeout. # shellcheck disable=SC2016 # Expansion is deliberately deferred to the child shell. - "$runner" -k 1 "$seconds" bash -c ' + fm_timeout_background "$runner" -k 1 "$seconds" bash -c ' status_file=$1 shift "$@" command_rc=$? printf "%s\n" "$command_rc" > "$status_file" exit "$command_rc" - ' _ "$status_file" "$@" <&0 & + ' _ "$status_file" "$@" runner_pid=$! if wait "$runner_pid"; then runner_rc=0 diff --git a/tests/fm-timeout-lib.test.sh b/tests/fm-timeout-lib.test.sh index 42c08b9d00a..f1f034c8d3e 100755 --- a/tests/fm-timeout-lib.test.sh +++ b/tests/fm-timeout-lib.test.sh @@ -448,6 +448,124 @@ test_run_timed_passes_a_natural_exit_through_a_fired_bound() { # and a bare call runs the shadow, which drops the command's stdout and # replaces its status. gtimeout is shadowed the same way, so a host whose # external runner is gtimeout is covered without installing one. +# A non-interactive bash assigns /dev/null to an async command's stdin. The +# external timeout and bash mechanisms background their command, so a pipe or +# file must be restored or a remote steer payload arrives empty. A terminal is +# not attached, and a closed stdin still runs the command. +test_run_timed_delivers_piped_stdin_on_every_mechanism() { + local payload=piped-stdin-payload out rc mechanism timeout_path perl_bin dir + dir="$TMP_ROOT/stdin" + perl_bin="$dir/perl-bin" + mkdir -p "$perl_bin" + for tool in perl bash cat; do + ln -s "$(command -v "$tool")" "$perl_bin/$tool" || fail "could not link $tool for the stdin case" + done + printf '%s' "$payload" > "$dir/file" + + rc=0 + out=$(printf '%s' "$payload" | bash -c '. "$1"; fm_run_timed 10 cat' _ "$ROOT/bin/fm-timeout-lib.sh") || rc=$? + [ "$rc" -eq 0 ] || fail "fm_run_timed did not pass cat's status (rc=$rc out=$out)" + [ "$out" = "$payload" ] || fail "fm_run_timed lost piped stdin (out=$out)" + + timeout_path=$(. "$ROOT/bin/fm-timeout-lib.sh"; fm_external_timeout_path || true) + if [ -n "$timeout_path" ]; then + rc=0 + out=$(printf '%s' "$payload" | bash -c ' + . "$1" + fm_run_external_timeout "$2" 10 cat + ' _ "$ROOT/bin/fm-timeout-lib.sh" "$timeout_path") || rc=$? + [ "$rc" -eq 0 ] || fail "external timeout did not pass cat's status (rc=$rc out=$out)" + [ "$out" = "$payload" ] || fail "external timeout lost piped stdin (out=$out)" + + rc=0 + out=$(bash -c ' + . "$1" + fm_run_external_timeout "$2" 10 cat + ' _ "$ROOT/bin/fm-timeout-lib.sh" "$timeout_path" < "$dir/file") || rc=$? + [ "$rc" -eq 0 ] || fail "external timeout did not pass a file stdin status (rc=$rc out=$out)" + [ "$out" = "$payload" ] || fail "external timeout lost file stdin (out=$out)" + + rc=0 + out=$(bash -c ' + . "$1" + fm_run_external_timeout "$2" 5 bash -c "printf ok" + ' _ "$ROOT/bin/fm-timeout-lib.sh" "$timeout_path" <&-) || rc=$? + [ "$rc" -eq 0 ] || fail "external timeout failed with closed stdin (rc=$rc out=$out)" + [ "$out" = ok ] || fail "external timeout did not run with closed stdin (out=$out)" + fi + + mechanism=$(FM_TIMEOUT_MECHANISM_OVERRIDE=bash bash -c '. "$1"; fm_timeout_mechanism' _ "$ROOT/bin/fm-timeout-lib.sh") + [ "$mechanism" = bash ] || fail "bash override selected $mechanism" + rc=0 + out=$(printf '%s' "$payload" | FM_TIMEOUT_MECHANISM_OVERRIDE=bash bash -c ' + . "$1" + fm_run_timed 10 bash -c "cat; exit 9" + ' _ "$ROOT/bin/fm-timeout-lib.sh") || rc=$? + [ "$rc" -eq 9 ] || fail "bash timeout lost the command status after reading stdin (rc=$rc out=$out)" + [ "$out" = "$payload" ] || fail "bash timeout lost piped stdin (out=$out)" + + rc=0 + out=$(FM_TIMEOUT_MECHANISM_OVERRIDE=bash bash -c ' + . "$1" + fm_run_timed 5 bash -c "printf ok" + ' _ "$ROOT/bin/fm-timeout-lib.sh" <&-) || rc=$? + [ "$rc" -eq 0 ] || fail "bash timeout failed with closed stdin (rc=$rc out=$out)" + [ "$out" = ok ] || fail "bash timeout did not run with closed stdin (out=$out)" + + mechanism=$(PATH="$perl_bin" bash -c '. "$1"; fm_timeout_mechanism' _ "$ROOT/bin/fm-timeout-lib.sh") + [ "$mechanism" = perl ] || fail "a PATH without timeout selected $mechanism" + rc=0 + out=$(printf '%s' "$payload" | PATH="$perl_bin" bash -c ' + . "$1" + fm_run_timed 10 cat + ' _ "$ROOT/bin/fm-timeout-lib.sh") || rc=$? + [ "$rc" -eq 0 ] || fail "perl timeout did not pass cat's status (rc=$rc out=$out)" + [ "$out" = "$payload" ] || fail "perl timeout lost piped stdin (out=$out)" + + if ( : /dev/null; then + rc=0 + out=$(FM_TIMEOUT_MECHANISM_OVERRIDE=bash bash -c ' + . "$1" + fm_run_timed 5 bash -c "if [ -t 0 ]; then echo tty; else echo notty; fi" + ' _ "$ROOT/bin/fm-timeout-lib.sh" "$2" + if [ "$5" = external ]; then + fm_run_external_timeout "$6" 10 cat < "$3" > "$4" + else + FM_TIMEOUT_MECHANISM_OVERRIDE=bash fm_run_timed 10 cat < "$3" > "$4" + fi + echo still >&3 + ' _ "$ROOT/bin/fm-timeout-lib.sh" "$dir/fd3" "$dir/file" "$dir/out" "$mechanism" "$timeout_path" 2>&1) || rc=$? + [ "$rc" -eq 0 ] || fail "caller fd 3 was not usable after the $mechanism mechanism (rc=$rc out=$out)" + [ "$(cat "$dir/fd3")" = still ] || fail "the $mechanism mechanism disturbed the caller's fd 3" + [ "$(cat "$dir/out")" = "$payload" ] || fail "the $mechanism fd 3 case lost file stdin" + done + + pass "fm_run_timed delivers piped stdin through every available mechanism" +} + test_run_timed_keeps_stdout_and_nonzero_status_when_a_function_shadows_timeout() { local out rc=0 # The functions live in this subshell so they cannot leak into later cases. @@ -471,6 +589,7 @@ test_system_bash_preserves_completion_and_signal_statuses test_run_timed_reports_the_bound_when_the_wrapper_records_a_signal_death test_run_timed_passes_a_natural_exit_through_a_fired_bound test_run_timed_keeps_stdout_and_nonzero_status_when_a_function_shadows_timeout +test_run_timed_delivers_piped_stdin_on_every_mechanism test_term_ends_a_cooperative_command_at_the_bound test_kill_ends_a_term_ignoring_command_after_the_grace test_the_bound_replaces_the_calling_shell From bf50f290b5ccf8b34cf2c5403ee728950f19cf65 Mon Sep 17 00:00:00 2001 From: WTF Am I Doing ? Date: Tue, 3 Nov 2026 10:29:23 -0500 Subject: [PATCH 02/34] fix: isolate interrupted auto-arm failures by session (#7921) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Bind interrupted auto-arm notices to their producing session * no-mistakes(document): Document session-bound auto-arm interruption recovery * no-mistakes(ci): Fixed all three lint-inventory expectations to exclude hidden scripts, matching the documented shell globs. Tier 2 test correction; production behavior was correct. fm-lint.test.sh passes, with four platform capability skips. Targeted ShellCheck and git diff --check pass * no-mistakes(ci): Repair blocked: the command guard rejected test authoring as “Indirect command execution not allowed.” Stopped dependent work without switching tools. Independently untracked exactly the six authorized files with git rm --cached; verified every physical file remains and every ignore pattern still matches. ci-1, ci-2, and ci-3 remain unresolved. Neither reproduction nor verification ran. No commit, push, or new scratch files were created * Preserve interrupted auto-arm episodes by session identity * no-mistakes(document): Clarify session-bound auto-arm failure documentation * test: keep the exhausted-interruption fixture on one session The integrated Stop driver starts a new fake-claude pid per Stop. Bind those Stops to one recorded session id so a session-scoped interrupted episode can still exhaust its budget and commit the attended alarm. Co-authored-by: Kun Chen --------- Co-authored-by: Cursor Agent Co-authored-by: Kun Chen --- bin/fm-claude-stop-autoarm.sh | 39 +++-- bin/fm-wake-lib.sh | 50 +++++- docs/turnend-guard.md | 12 +- docs/watcher-continuity.md | 4 +- tests/fm-claude-stop-autoarm.test.sh | 227 ++++++++++++++++++++++++++- tests/fm-lint.test.sh | 7 +- tests/fm-turnend-guard.test.sh | 5 + 7 files changed, 312 insertions(+), 32 deletions(-) diff --git a/bin/fm-claude-stop-autoarm.sh b/bin/fm-claude-stop-autoarm.sh index 4b84a83c775..71745c717cb 100755 --- a/bin/fm-claude-stop-autoarm.sh +++ b/bin/fm-claude-stop-autoarm.sh @@ -40,12 +40,12 @@ # waits on inside this hook-owned process tree (never a fire-and-forget # shell &); Claude owns the process group, so its timeout/session teardown # kills arm and watcher together, and the hook TERMs the arm with itself. -# HUP, TERM, and INT are translated through the ordinary durable failure -# handoff instead of leaving the generation frozen at arming. Claude does -# not deliver the exit 2 of a hook it terminated at the configured timeout +# HUP, TERM, and INT follow the session-aware interruption contract in +# docs/turnend-guard.md. Claude does not deliver the exit 2 of a hook it +# terminated at the configured timeout # as a rewake (measured on Claude Code 2.1.278 and 2.1.281, # docs/verification/supervision.md), so a park that outlives that timeout -# records the failure durably without waking an idle primary; nothing here +# records the failure durably without waking an idle primary. Nothing # shortens a quiet park, because no-change heartbeats are absorbed without # closing the arm. # - Handling successor: Pi, omp, and OpenCode start the next arm before they @@ -250,6 +250,9 @@ if [ "$RECOVER_SESSION_LOCK" -eq 1 ]; then fi # --- single-flight generation claim -------------------------------------------- +SESSION_PID=$(sed -n '1p' "$STATE/.lock" 2>/dev/null || true) +SESSION_IDENTITY=$(fm_session_pid_identity "$SESSION_PID" 2>/dev/null || true) +SESSION_ID=$(fm_session_lock_recorded_session_id "$STATE" 2>/dev/null || true) # Claude runs one background process per firing with no dedupe. Exactly one # generation owner arms and translates per event epoch: every firing defers to # a live open claim, and a stuck, dead, identity-mismatched, or finished claim @@ -281,8 +284,8 @@ MY_GEN=$FM_AUTOARM_MY_GEN # the same hold. Failure means refused or unverifiable: the caller goes silent # (cleanup, exit 0) - the harness discards the collected stderr on exit 0, so # even an already-printed banner is never delivered by a losing generation. -autoarm_commit() { # [marker-file] - local outcome=$1 marker=${2:-} session_pid recovery +autoarm_commit() { # [marker-file] [interrupted-session-identity] + local outcome=$1 marker=${2:-} marker_identity=${3:-} session_pid recovery if [ "$outcome" = rewake ]; then fm_session_lock_owned_by_self "$STATE" || return 2 session_pid=$(sed -n '1p' "$STATE/.lock" 2>/dev/null || true) @@ -292,10 +295,8 @@ autoarm_commit() { # [marker-file] *) return 2 ;; esac fm_autoarm_write_owned "$STATE" "$MY_GEN" "$outcome" "$marker" "$session_pid" "$recovery" - elif [ -n "$marker" ]; then - fm_autoarm_write_owned "$STATE" "$MY_GEN" "$outcome" "$marker" else - fm_autoarm_write_owned "$STATE" "$MY_GEN" "$outcome" + fm_autoarm_write_owned "$STATE" "$MY_GEN" "$outcome" "$marker" '' '' "$marker_identity" "$SESSION_ID" fi } @@ -392,8 +393,13 @@ autoarm_alarm_banner() { # decided: an already-alarmed episode schedules no Stop-owned retry (exit 0), # anything else keeps it alive (exit 2). Text already on stderr, such as the # host's actionable wake lines, is delivered with whichever rewake wins. -autoarm_exit_suppressed() { # - local cause=$1 rc +autoarm_exit_suppressed() { # [interrupted-session-identity] + local cause=$1 marker_identity=${2:-} rc + if [ -n "$marker_identity" ] && ! fm_autoarm_session_matches "$STATE" "$marker_identity" "$SESSION_ID"; then + autoarm_record session-ended + [ -z "${OUT:-}" ] || rm -f "$OUT" 2>/dev/null || true + exit 0 + fi autoarm_commit_attended_alarm rc=$? if [ "$rc" -eq 0 ]; then @@ -411,7 +417,7 @@ autoarm_exit_suppressed() { # fi cause='firstmate watcher auto-arm could not clear the resolved failure episode - a verified healthy watcher is running, but the episode reset was refused' fi - if ! autoarm_commit failed-suppressed; then + if ! autoarm_commit failed-suppressed '' "$marker_identity"; then [ -z "${OUT:-}" ] || rm -f "$OUT" 2>/dev/null || true exit 0 fi @@ -431,6 +437,7 @@ autoarm_exit_suppressed() { # # failure protocol instead: the winning generation records a terminal outcome, # creates the episode marker, and exits 2 so Claude delivers a recovery turn - # except after Claude's own timeout kill, whose exit 2 is dropped (header). +# Without a matching session, the hook closes silently as session-ended. # A superseded generation remains silent, and an episode whose attended # fail-open was already consumed must not restart automatic continuation. # shellcheck disable=SC2329 # Invoked indirectly by the signal traps below. @@ -442,6 +449,10 @@ handle_autoarm_signal() { wait "$ARM_PID" 2>/dev/null || true fi [ -z "${OUT:-}" ] || rm -f "$OUT" 2>/dev/null || true + if ! fm_autoarm_session_matches "$STATE" "$SESSION_IDENTITY" "$SESSION_ID"; then + autoarm_record session-ended + exit 0 + fi if [ "$AUTOARM_COMMITTED_ALARM" -eq 1 ]; then autoarm_alarm_banner exit 2 @@ -454,10 +465,10 @@ handle_autoarm_signal() { if [ ! -e "$FAILURE_NOTICE" ]; then printf 'firstmate watcher auto-arm INTERRUPTED by %s - the Stop-owned automatic supervision mechanism did not reach a terminal watcher outcome.\n' "$signal" >&2 printf 'Do not launch a manual background arm from this notice; investigate the automatic Stop hook and watcher startup before ending blind.\n' >&2 - autoarm_commit failed "$FAILURE_NOTICE" && exit 2 + autoarm_commit failed "$FAILURE_NOTICE" "$SESSION_IDENTITY" && exit 2 exit 0 fi - autoarm_exit_suppressed "firstmate watcher auto-arm interrupted by $signal - the failure episode notice was already consumed" + autoarm_exit_suppressed "firstmate watcher auto-arm interrupted by $signal - the failure episode notice was already consumed" "$SESSION_IDENTITY" } trap 'handle_autoarm_signal HUP' HUP diff --git a/bin/fm-wake-lib.sh b/bin/fm-wake-lib.sh index 7461702b87b..a31d2382461 100755 --- a/bin/fm-wake-lib.sh +++ b/bin/fm-wake-lib.sh @@ -2303,13 +2303,29 @@ fm_autoarm_midturn_healthy() { # [grace] [ "$epoch_mtime" -ge "$beacon_mtime" ] } +# Match an interrupted episode to the current lock's process identity AND +# recorded session id. A changed anchor is still the same session only when +# the existing trusted-session ownership proof verifies that recorded id. +fm_autoarm_session_matches() { # [recorded-session-id] + local state=$1 identity=$2 session_id=${3:-} lock_pid current recorded + [ -n "$identity" ] || return 1 + _fm_wake_require_session_lock + lock_pid=$(sed -n '1p' "$state/.lock" 2>/dev/null || true) + current=$(fm_session_pid_identity "$lock_pid" 2>/dev/null) || return 1 + [ -n "$current" ] || return 1 + recorded=$(fm_session_lock_recorded_session_id "$state" 2>/dev/null || true) + [ "$session_id" = "$recorded" ] || return 1 + [ "$identity" = "$current" ] && return 0 + [ -n "$session_id" ] && fm_session_lock_same_session "$state" +} + # Atomically publish this process as the owner of generation N+1, under one # short micro-mutex hold. Returns 0 with FM_AUTOARM_MY_GEN set on success, 2 # when a competing claimant won the race (the ledger holds an open claim), and # 1 when the micro-mutex is contended, the mandatory identity cannot be # computed, or the write failed. fm_autoarm_claim_next() { # [grace] - local state=$1 grace=${2:-${FM_GUARD_GRACE:-300}} lock epoch pid gen identity session_id lock_pid lock_identity tmp + local state=$1 grace=${2:-${FM_GUARD_GRACE:-300}} lock epoch pid gen identity session_id lock_pid lock_identity tmp interrupted_identity interrupted_session lock="$state/.claude-autoarm.lock" epoch="$state/.claude-autoarm-epoch" FM_AUTOARM_MY_GEN= @@ -2332,6 +2348,18 @@ fm_autoarm_claim_next() { # [grace] fm_lock_release "$lock" return 2 fi + # Only interrupted hooks bind their notice to a session. A new lock holder + # retires that episode before its first claim, so a teardown cannot consume + # the replacement's real failure notice. Empty legacy markers stay unchanged. + interrupted_identity=$(sed -n 's/^session_identity=//p' "$state/.claude-autoarm-failure-notified" 2>/dev/null || true) + interrupted_session=$(sed -n 's/^session_id=//p' "$state/.claude-autoarm-failure-notified" 2>/dev/null || true) + if [ -n "$interrupted_identity" ] && [ -n "$lock_identity" ] \ + && ! fm_autoarm_session_matches "$state" "$interrupted_identity" "$interrupted_session"; then + if ! fm_failure_episode_reset "$state"; then + fm_lock_release "$lock" + return 1 + fi + fi gen=$(_fm_autoarm_epoch_field "$epoch" epoch 2>/dev/null || true) case "$gen" in ''|*[!0-9]*) gen=0 ;; @@ -2361,10 +2389,13 @@ fm_autoarm_claim_next() { # [grace] # owned critical section (the once-per-episode failure notice). A marker failure # refuses the commit even though its terminal ledger entry remains; marker-first # ordering could permanently suppress a notice whose ledger write never won. +# The optional interrupted-session identity and recorded id are checked under +# the hold and written into the marker, allowing claim_next to retire it when +# another session takes the lock without resetting a verified same-session move. # Returns 0 committed, 2 refused (superseded or required-marker failure), and 1 # unable (bounded contention or ledger-write failure). -fm_autoarm_write_owned() { # [marker-file] [session-pid] [recovery-generation] - local state=$1 gen=$2 outcome=$3 marker=${4:-} session=${5:-} recovery=${6:-} lock i rc +fm_autoarm_write_owned() { # [marker-file] [session-pid] [recovery-generation] [interrupted-session-identity] [interrupted-session-id] + local state=$1 gen=$2 outcome=$3 marker=${4:-} session=${5:-} recovery=${6:-} marker_identity=${7:-} marker_session=${8:-} lock i rc lock="$state/.claude-autoarm.lock" i=0 while ! fm_lock_try_acquire "$lock"; do @@ -2372,7 +2403,7 @@ fm_autoarm_write_owned() { # [marker-file] [session sleep 0.02 i=$((i + 1)) done - _fm_autoarm_write_owned_locked "$state" "$gen" "$outcome" "$marker" "$session" "$recovery" + _fm_autoarm_write_owned_locked "$state" "$gen" "$outcome" "$marker" "$session" "$recovery" "$marker_identity" "$marker_session" rc=$? fm_lock_release "$lock" return "$rc" @@ -2383,8 +2414,8 @@ fm_autoarm_write_owned() { # [marker-file] [session # ledger write and marker create share one owned critical section with # whatever the caller already serialized. Returns 0 on commit, 1 on a failed # write, 2 on refusal (superseded generation or failed required marker). -_fm_autoarm_write_owned_locked() { # [marker-file] [session-pid] [recovery-generation] - local state=$1 gen=$2 outcome=$3 marker=${4:-} session=${5:-} recovery=${6:-} epoch pid identity tmp +_fm_autoarm_write_owned_locked() { # [marker-file] [session-pid] [recovery-generation] [interrupted-session-identity] [interrupted-session-id] + local state=$1 gen=$2 outcome=$3 marker=${4:-} session=${5:-} recovery=${6:-} marker_identity=${7:-} marker_session=${8:-} epoch pid identity tmp marker_content epoch="$state/.claude-autoarm-epoch" pid=${BASHPID:-$$} if ! fm_autoarm_ledger_read "$state" \ @@ -2392,6 +2423,9 @@ _fm_autoarm_write_owned_locked() { # [marker-file] return 2 fi identity=$FM_AUTOARM_IDENTITY + if [ -n "$marker_identity" ] && ! fm_autoarm_session_matches "$state" "$marker_identity" "$marker_session"; then + return 2 + fi tmp="$epoch.tmp.$pid" if ! { printf 'epoch=%s owner_pid=%s outcome=%s updated_at=%s' \ @@ -2404,7 +2438,9 @@ _fm_autoarm_write_owned_locked() { # [marker-file] rm -f "$tmp" 2>/dev/null || true return 1 fi - [ -z "$marker" ] || : > "$marker" 2>/dev/null || return 2 + marker_content= + [ -z "$marker_identity" ] || printf -v marker_content 'session_identity=%s\nsession_id=%s\n' "$marker_identity" "$marker_session" + [ -z "$marker" ] || printf '%s' "$marker_content" > "$marker" 2>/dev/null || return 2 return 0 } diff --git a/docs/turnend-guard.md b/docs/turnend-guard.md index 0e209979776..3fac0db0e28 100644 --- a/docs/turnend-guard.md +++ b/docs/turnend-guard.md @@ -404,7 +404,13 @@ Fresh `failed` and `failed-suppressed` outcomes enter or advance the failure pro The auto-arm itself rechecks the healthy watcher predicate and retries a bounded number of times before reporting a genuine failure. The foreground arm legitimately follows a healthy watcher until its next wake. -The hook therefore catches HUP, TERM, and INT from host timeout or teardown and routes interruptions through the same failure-episode decisions as other terminal failures, including the [attended exhaustion decision](#attended-fail-open). +The hook catches HUP, TERM, and INT from host timeout or teardown. +If the producing session no longer matches the lock's process identity and recorded session id, the hook records `session-ended` and exits 0 silently without creating a failure notice. +The existing trusted-session ownership proof preserves that match across a verified same-session lock re-anchor. +While that session remains current, interruptions use the ordinary failure progression, including its notice deduplication, attended-alarm limits, and the [attended exhaustion decision](#attended-fail-open). +An interruption notice carries the producing session's lock-holder identity and recorded session id, which are rechecked under the auto-arm owner lock before committing the failure. +Before taking its first generation, a replacement that no longer matches that session clears the interrupted episode's notice, attended alarm, and block budget, so its first genuine failure can notify even if a process number and executable path are reused. +Empty legacy markers and ordinary failure notices retain their existing behavior. Claude drops that exit 2 when it terminated the hook at the configured timeout itself, so a park that outlives the timeout ends without a rewake (`bin/fm-claude-stop-autoarm.sh` header). The first fresh exhausted-failure epoch preserves its handoff without consuming a blocked-stop count. @@ -438,10 +444,10 @@ Two writers can commit `state/.claude-autoarm-failure-alarmed`, both under the s - The Stop auto-arm's own terminal failure: the exhausted continuation is the one participant that knows no automatic continuation remains, so when this session's consumed block count is already over budget it commits the alarm in the same owned critical section as its `failed-suppressed` ledger write and delivers the one loud final rewake. Every failed-suppressed continuation - an ordinary exhausted failure, a lost supervision-host hand-back, an interrupted hook, or a refused healthy-watcher reset - takes this one exhaustion decision before it commits another retry, because the guard's claim-open step-aside would otherwise leave the alarm unwritten on every Stop. -After that alarm, the Stop auto-arm suppresses further exit-2 continuations until positive watcher recovery, so the final fail-open remains reachable. +After that alarm, the Stop auto-arm suppresses further exit-2 continuations until the episode resets, so the final fail-open remains reachable. +[Failure progression and block budget](#failure-progression-and-block-budget) owns the reset boundaries, including positive watcher recovery and replacement-session isolation of an interrupted episode. The alarm cannot repeat during that failure episode, and a later unhealthy stop blocks again. Every suppressed continuation in the episode emits one reason line instead of an empty rewake body, stating why no operator notice repeats and whether a Stop-owned retry stays scheduled. -A positively verified healthy watcher clears the failure notice, alarm, and block budget for a future independent episode. A Claude failure notice describes the automatic mechanism as broken and does not direct a routine manual background arm. ### Passive adapters diff --git a/docs/watcher-continuity.md b/docs/watcher-continuity.md index 2c3144c5dda..7fd4464b82d 100644 --- a/docs/watcher-continuity.md +++ b/docs/watcher-continuity.md @@ -115,7 +115,7 @@ The beacon is `state/.last-watcher-beat`, which only the watcher process touches - A cycle-end failure is benign when that live-watcher predicate is true. In that case the hook suppresses the arm output and continues silently. -[`turnend-guard.md`](turnend-guard.md#failure-progression-and-block-budget) owns the failure-notice commit contract, monotonic failure progression, attended-alarm writers, suppression reasons, and positive recovery reset. +[`turnend-guard.md`](turnend-guard.md#failure-progression-and-block-budget) owns the failure-notice commit contract, monotonic failure progression, attended-alarm writers, suppression reasons, positive recovery reset, and session-bound interruption isolation. ### Supervision host @@ -536,7 +536,7 @@ It checks that a newly appended keyed decision is classified without rereading e - Exit-2 translation. - The handling successor an ended attached cycle starts with the closed arm as its predecessor and that outlives the rewake. - An unconfirmed successor reported in the banner without withholding the wake. -- Host-timeout HUP/TERM/INT translation into the same durable failure handoff. +- The [session-bound HUP/TERM/INT failure handoff](turnend-guard.md#failure-progression-and-block-budget) and replacement-session notice isolation. It also covers generation-claim single-flight, stuck-claim supersession, superseded-owner silence, notice-marker refusal and retry, ownership-atomic episode reset, and the legacy upgrade shim. [`turnend-guard.md`](turnend-guard.md) owns those behavior contracts. diff --git a/tests/fm-claude-stop-autoarm.test.sh b/tests/fm-claude-stop-autoarm.test.sh index 913597716ca..0f66cd0d81c 100755 --- a/tests/fm-claude-stop-autoarm.test.sh +++ b/tests/fm-claude-stop-autoarm.test.sh @@ -35,6 +35,7 @@ install_autoarm_scripts() { cp "$ROOT/bin/fm-cursor-lib.sh" "$dir/bin/fm-cursor-lib.sh" cp "$ROOT/bin/fm-hook-host-lib.sh" "$dir/bin/fm-hook-host-lib.sh" cp "$ROOT/bin/fm-lock.sh" "$dir/bin/fm-lock.sh" + cp "$ROOT/bin/fm-lease-lib.sh" "$dir/bin/fm-lease-lib.sh" cp "$ROOT/bin/fm-afk-contract.sh" "$dir/bin/fm-afk-contract.sh" cp "$ROOT/bin/fm-classify-lib.sh" "$dir/bin/fm-classify-lib.sh" cp "$ROOT/bin/fm-timeout-lib.sh" "$dir/bin/fm-timeout-lib.sh" @@ -251,12 +252,22 @@ epoch_outcome() { # caller can `wait` on it for the hook's exit status). RUN_AUTOARM_BG_PID= run_autoarm_bg() { - local dir=$1 out=$2 + local dir=$1 out=$2 session_id=${3:-} printf '%s\n' '{"session_id":"sess-autoarm","stop_hook_active":false}' \ - | FM_HOME="$dir" "$FAKE_CLAUDE" -c ' + | FM_HOME="$dir" python3 -c ' +import os, signal, sys +# Noninteractive bash backgrounds inherit ignored SIGINT. Restore the host +# signal disposition before exec so the fixture can exercise the INT trap too. +signal.signal(signal.SIGINT, signal.SIG_DFL) +os.execv(sys.argv[1], sys.argv[1:]) +' "$FAKE_CLAUDE" -c ' printf "%s\n" "$$" > "$FM_HOME/state/.lock" + if [ -n "$1" ]; then + export CLAUDE_CODE_SESSION_ID=$1 CLAUDE_PID=$$ + printf "%s\n" "$1" > "$FM_HOME/state/.lock-session" + fi "$FM_HOME/bin/fm-claude-stop-autoarm.sh" - ' > "$out" 2>&1 & + ' _ "$session_id" > "$out" 2>&1 & RUN_AUTOARM_BG_PID=$! } @@ -857,6 +868,211 @@ test_term_mid_arm_commits_failure_and_rewakes() { pass "auto-arm: TERM mid-arm commits a durable failure and exits 2 for rewake" } +# Session teardown can signal the hook before its harness dies. The replacement +# must retire that notice rather than spend its own first real failure silently. +test_replacement_retires_interrupted_session_episode() { + local signal dir out hook_pid i status replacement + for signal in HUP TERM INT; do + dir=$(make_primary_dir "$TMP_ROOT/replaced-$signal") + : > "$dir/state/task.meta" + write_arm_fixture "$dir" blocking-actionable + out="$dir/state/interrupted.out" + run_autoarm_bg "$dir" "$out" sess-producing + hook_pid= + i=0 + while [ "$i" -lt 100 ]; do + hook_pid=$(epoch_field "$dir" owner_pid) + [ -n "$hook_pid" ] && [ -e "$dir/state/arm-ran" ] && break + sleep 0.02 + i=$((i + 1)) + done + [ -n "$hook_pid" ] && [ -e "$dir/state/arm-ran" ] || fail "$signal hook did not park" + kill -"$signal" "$hook_pid" || fail "could not signal $signal hook" + status=0 + wait "$RUN_AUTOARM_BG_PID" || status=$? + expect_code 2 "$status" "$signal in a live session must retain timeout recovery" + assert_contains "$(cat "$out")" 'auto-arm INTERRUPTED' "$signal omitted its current-session notice" + assert_present "$dir/state/.claude-autoarm-failure-notified" "$signal lost its durable notice" + assert_contains "$(cat "$dir/state/.claude-autoarm-failure-notified")" 'session_id=sess-producing' \ + "$signal did not bind its notice to the recorded session id" + + write_arm_fixture "$dir" actionable + replacement=$(printf '%s\n' '{"session_id":"replacement"}' \ + | FM_HOME="$dir" "$FAKE_CLAUDE" -c ' + printf "%s\n" "$$" > "$FM_HOME/state/.lock" + "$FM_HOME/bin/fm-claude-stop-autoarm.sh"; rc=$? + . "$FM_HOME/bin/fm-wake-lib.sh" + fm_autoarm_midturn_healthy "$FM_HOME/state" || exit 11 + exit "$rc" + ' 2>&1); status=$? + expect_code 2 "$status" "$signal replacement inherited a phantom mid-turn failure" + assert_absent "$dir/state/.claude-autoarm-failure-notified" "$signal replacement retained the old notice" + [ "$(epoch_outcome "$dir")" = rewake ] || fail "$signal replacement retained the old failure" + + # Its first real failure must still notify and retain bounded retries. + write_arm_fixture "$dir" failed + replacement=$(run_autoarm "$dir" 2>/dev/null); status=$? + expect_code 2 "$status" "$signal replacement must report its real failure" + assert_contains "$replacement" 'automatic supervision mechanism is broken' \ + "$signal replacement inherited the previous session's consumed notice" + [ "$(epoch_outcome "$dir")" = failed ] || fail "$signal replacement suppressed its first failure" + [ "$(wc -l < "$dir/state/arm-ran" | tr -d ' ')" -eq 4 ] || fail "$signal replacement lost bounded retries" + done + pass "auto-arm: HUP, TERM and INT episodes do not consume the replacement session's notice" +} + +# An interrupted failure belongs to the session, including when fm-lock moves +# its live anchor to the current model process within that same session. +test_same_session_lock_move_preserves_interrupted_episode() { + local dir status=0 + dir=$(make_primary_dir "$TMP_ROOT/interrupted-lock-move") + FM_HOME="$dir" "$FAKE_CLAUDE" -c ' + export CLAUDE_CODE_SESSION_ID=sess-moving CLAUDE_PID=$$ + . "$FM_HOME/bin/fm-wake-lib.sh" + . "$FM_HOME/bin/fm-session-lock-lib.sh" + "$FAKE_CLAUDE" -c "while :; do sleep 1; done" & + holder=$! + trap '\''kill "$holder" 2>/dev/null; wait "$holder" 2>/dev/null'\'' EXIT + printf "%s\n" "$holder" > "$FM_HOME/state/.lock" + printf "%s\n" "$CLAUDE_CODE_SESSION_ID" > "$FM_HOME/state/.lock-session" + fm_autoarm_claim_next "$FM_HOME/state" || exit 90 + identity=$(fm_session_pid_identity "$holder") || exit 91 + fm_autoarm_write_owned "$FM_HOME/state" "$FM_AUTOARM_MY_GEN" failed \ + "$FM_HOME/state/.claude-autoarm-failure-notified" "" "" "$identity" "$CLAUDE_CODE_SESSION_ID" || exit 92 + printf "alarmed\n" > "$FM_HOME/state/.claude-autoarm-failure-alarmed" + printf "2\n" > "$FM_HOME/state/.turnend-claude-blocks" + "$FAKE_CLAUDE" -c '\'' + export CLAUDE_PID=$$ + old_pid=$(cat "$FM_HOME/state/.lock") + "$FM_HOME/bin/fm-lock.sh" || exit 93 + [ "$(cat "$FM_HOME/state/.lock")" = "$$" ] || exit 94 + [ "$old_pid" != "$$" ] || exit 95 + . "$FM_HOME/bin/fm-wake-lib.sh" + fm_autoarm_claim_next "$FM_HOME/state" || exit 96 + [ -e "$FM_HOME/state/.claude-autoarm-failure-notified" ] || exit 11 + [ "$(cat "$FM_HOME/state/.claude-autoarm-failure-alarmed")" = alarmed ] || exit 12 + [ "$(cat "$FM_HOME/state/.turnend-claude-blocks")" = 2 ] || exit 13 + '\'' + ' > "$dir/state/probe.out" 2>&1 || status=$? + expect_code 0 "$status" "ci-1: verified same-session lock move must preserve the interrupted notice, alarm and budget" + pass "auto-arm: verified same-session lock moves preserve the interrupted episode" +} + +# Model the Windows identity collision: the same process identity answers for +# a replacement, but the lock sidecar and trusted session id name a new session. +test_reused_identity_with_new_session_retires_interrupted_episode() { + local dir status=0 + dir=$(make_primary_dir "$TMP_ROOT/interrupted-reused-identity") + FM_HOME="$dir" "$FAKE_CLAUDE" -c ' + export CLAUDE_CODE_SESSION_ID=sess-old CLAUDE_PID=$$ + . "$FM_HOME/bin/fm-wake-lib.sh" + . "$FM_HOME/bin/fm-session-lock-lib.sh" + printf "%s\n" "$$" > "$FM_HOME/state/.lock" + printf "%s\n" "$CLAUDE_CODE_SESSION_ID" > "$FM_HOME/state/.lock-session" + fm_autoarm_claim_next "$FM_HOME/state" || exit 90 + identity=$(fm_session_pid_identity "$$") || exit 91 + fm_autoarm_write_owned "$FM_HOME/state" "$FM_AUTOARM_MY_GEN" failed \ + "$FM_HOME/state/.claude-autoarm-failure-notified" "" "" "$identity" "$CLAUDE_CODE_SESSION_ID" || exit 92 + printf "alarmed\n" > "$FM_HOME/state/.claude-autoarm-failure-alarmed" + printf "2\n" > "$FM_HOME/state/.turnend-claude-blocks" + export CLAUDE_CODE_SESSION_ID=sess-replacement + printf "%s\n" "$CLAUDE_CODE_SESSION_ID" > "$FM_HOME/state/.lock-session" + [ "$identity" = "$(fm_session_pid_identity "$$")" ] || exit 93 + fm_autoarm_claim_next "$FM_HOME/state" || exit 94 + [ ! -e "$FM_HOME/state/.claude-autoarm-failure-notified" ] || exit 11 + [ ! -e "$FM_HOME/state/.claude-autoarm-failure-alarmed" ] || exit 12 + [ ! -e "$FM_HOME/state/.turnend-claude-blocks" ] || exit 13 + ' > "$dir/state/probe.out" 2>&1 || status=$? + expect_code 0 "$status" "ci-2: replacement session with an identical process identity must retire the old interrupted episode" + pass "auto-arm: a new session id retires an interrupted episode despite process identity reuse" +} + +test_missing_lock_interruption_is_silent() { + local signal dir out hook_pid i status + for signal in HUP TERM INT; do + dir=$(make_primary_dir "$TMP_ROOT/ended-$signal") + : > "$dir/state/task.meta" + write_arm_fixture "$dir" blocking-actionable + out="$dir/state/interrupted.out" + run_autoarm_bg "$dir" "$out" + hook_pid= + for i in $(seq 1 100); do + hook_pid=$(epoch_field "$dir" owner_pid) + [ -n "$hook_pid" ] && [ -e "$dir/state/arm-ran" ] && break + sleep 0.02 + done + [ -n "$hook_pid" ] && [ -e "$dir/state/arm-ran" ] || fail "$signal hook did not park before lock loss" + mv "$dir/state/.lock" "$dir/state/retired-lock" + kill -"$signal" "$hook_pid" || fail "could not signal ended $signal hook" + status=0 + wait "$RUN_AUTOARM_BG_PID" || status=$? + expect_code 0 "$status" "$signal after lock loss must exit silently" + [ ! -s "$out" ] || fail "$signal after lock loss produced output: $(cat "$out")" + [ "$(epoch_outcome "$dir")" = session-ended ] || fail "$signal after lock loss left a nonterminal session" + assert_absent "$dir/state/.claude-autoarm-failure-notified" "$signal after lock loss consumed a notice" + assert_absent "$dir/state/.claude-autoarm-failure-alarmed" "$signal after lock loss created an alarm" + done + pass "auto-arm: HUP, TERM and INT after lock loss close silently as session-ended" +} + +# Exercise both sides of the session proof in the real signal handler and its +# owned notice commit, while the process identities remain live and inspectable. +test_signal_session_identity_proof() { + local mode signal dir out hook_pid i status + for mode in reanchor replacement-id; do + for signal in HUP TERM INT; do + dir=$(make_primary_dir "$TMP_ROOT/signal-$mode-$signal") + : > "$dir/state/task.meta" + write_arm_fixture "$dir" blocking-actionable + out="$dir/state/interrupted.out" + run_autoarm_bg "$dir" "$out" sess-signal + hook_pid= + for i in $(seq 1 100); do + hook_pid=$(epoch_field "$dir" owner_pid) + [ -n "$hook_pid" ] && [ -e "$dir/state/arm-ran" ] && break + sleep 0.02 + done + [ -n "$hook_pid" ] && [ -e "$dir/state/arm-ran" ] || fail "$mode $signal hook did not park" + if [ "$mode" = reanchor ]; then + FM_HOME="$dir" "$FAKE_CLAUDE" -c ' + export CLAUDE_CODE_SESSION_ID=sess-signal CLAUDE_PID=$$ + old=$(cat "$FM_HOME/state/.lock") + "$FM_HOME/bin/fm-lock.sh" || exit 90 + [ "$(cat "$FM_HOME/state/.lock")" = "$$" ] && [ "$old" != "$$" ] || exit 91 + kill -"$2" "$1" || exit 92 + for _ in $(seq 1 500); do + kill -0 "$1" 2>/dev/null || exit 0 + sleep 0.02 + done + exit 93 + ' _ "$hook_pid" "$signal" > "$dir/state/reanchor.out" 2>&1 \ + || fail "$signal could not hold a verified same-session re-anchor" + else + # Keep the lock pid and its identity unchanged, varying only the + # independently recorded session id, as on Windows process-number reuse. + printf 'sess-replacement\n' > "$dir/state/.lock-session" + kill -"$signal" "$hook_pid" || fail "could not signal replacement-id $signal hook" + fi + status=0 + wait "$RUN_AUTOARM_BG_PID" || status=$? + if [ "$mode" = reanchor ]; then + expect_code 2 "$status" "$signal after verified same-session re-anchor must retain timeout recovery" + assert_contains "$(cat "$out")" 'auto-arm INTERRUPTED' "$signal re-anchor lost its failure notice" + assert_contains "$(cat "$dir/state/.claude-autoarm-failure-notified")" 'session_id=sess-signal' \ + "$signal re-anchor lost its recorded session id" + [ "$(epoch_outcome "$dir")" = failed ] || fail "$signal re-anchor did not commit its failure" + else + expect_code 0 "$status" "$signal after session-id replacement must close silently" + [ ! -s "$out" ] || fail "$signal after session-id replacement produced output" + [ "$(epoch_outcome "$dir")" = session-ended ] || fail "$signal session-id replacement did not end its session" + assert_absent "$dir/state/.claude-autoarm-failure-notified" "$signal replacement consumed a notice" + assert_absent "$dir/state/.claude-autoarm-failure-alarmed" "$signal replacement created an alarm" + fi + done + done + pass "auto-arm: all interruption signals preserve verified re-anchors and reject replacement session ids" +} + # --- abandoned single-flight claim recovery (legacy shim) ---------------------- # The 2026-08-14 lapse: one cycle armed, beat its beacon, delivered a single # rewake, and exited, leaving its owner lock behind with a live pid. The single @@ -2023,6 +2239,11 @@ test_arms_for_x_mode_poll_need_without_inflight test_arms_for_registered_custom_check_without_inflight test_single_flight_admits_exactly_one_owner test_term_mid_arm_commits_failure_and_rewakes +test_replacement_retires_interrupted_session_episode +test_reused_identity_with_new_session_retires_interrupted_episode +test_same_session_lock_move_preserves_interrupted_episode +test_missing_lock_interruption_is_silent +test_signal_session_identity_proof test_abandoned_owner_claim_is_reclaimed_and_rearms test_abandoned_claim_reclaim_reaps_dead_steal_without_nesting test_arming_claim_with_fresh_beacon_is_never_reclaimed diff --git a/tests/fm-lint.test.sh b/tests/fm-lint.test.sh index 624f916b6d8..e6c6edf5f94 100755 --- a/tests/fm-lint.test.sh +++ b/tests/fm-lint.test.sh @@ -170,8 +170,9 @@ test_list_files_reports_the_shell_inventory() { # CI=true forces the full canonical set regardless of the ambient branch or # working-tree diff a local test run happens to have, so this stays a pure # inventory check independent of fm-lint.sh's own changed-file mode below. + # Hidden scripts are outside the documented shell-glob inventory. listed=$(CI=true "$LINT" --list-files) - expected=$(find bin bin/backends tests -maxdepth 1 -type f -name '*.sh' -print | LC_ALL=C sort) + expected=$(find bin bin/backends tests -maxdepth 1 -type f -name '*.sh' ! -name '.*' -print | LC_ALL=C sort) [ "$(printf '%s\n' "$listed" | LC_ALL=C sort)" = "$expected" ] \ || fail "fm-lint.sh --list-files did not return the complete shell inventory" pass "fm-lint.sh --list-files reports the complete shell inventory" @@ -528,7 +529,7 @@ test_ci_forces_full_lint_even_with_empty_diff() { # No git stub: CI=true must short-circuit fm-lint.sh's mode selection before # it ever consults git, so this proves CI wins regardless of local diff state. listed=$(CI=true "$LINT" --list-files) - expected=$(find bin bin/backends tests -maxdepth 1 -type f -name '*.sh' -print | LC_ALL=C sort) + expected=$(find bin bin/backends tests -maxdepth 1 -type f -name '*.sh' ! -name '.*' -print | LC_ALL=C sort) [ "$(printf '%s\n' "$listed" | LC_ALL=C sort)" = "$expected" ] \ || fail "CI=true did not force the full canonical file set" pass "fm-lint.sh forces a full lint in CI even when the local diff would be empty" @@ -544,7 +545,7 @@ test_main_branch_forces_full_lint() { # not the ambient CI signal a real CI run would otherwise supply. listed=$(PATH="$fakebin:$PATH" GITHUB_ACTIONS='' CI='' \ FM_TEST_GIT_BRANCH=main "$LINT" --list-files) - expected=$(find bin bin/backends tests -maxdepth 1 -type f -name '*.sh' -print | LC_ALL=C sort) + expected=$(find bin bin/backends tests -maxdepth 1 -type f -name '*.sh' ! -name '.*' -print | LC_ALL=C sort) [ "$(printf '%s\n' "$listed" | LC_ALL=C sort)" = "$expected" ] \ || fail "fm-lint.sh did not force a full lint when HEAD is on main" pass "fm-lint.sh forces a full lint when HEAD is on main" diff --git a/tests/fm-turnend-guard.test.sh b/tests/fm-turnend-guard.test.sh index 809bc7ee66e..786e6610f01 100755 --- a/tests/fm-turnend-guard.test.sh +++ b/tests/fm-turnend-guard.test.sh @@ -2059,7 +2059,12 @@ SH # lock as its own session's however the test itself is launched. cat > "$dir/stop-driver.sh" <<'SH' i=$1 variant=$2 +# Each Stop is a new fake-claude pid, as a real Stop is a new hook process. +# The session lock sidecar is what makes those Stops the same session, so an +# interrupted episode can still exhaust its budget instead of resetting. +export CLAUDECODE=1 CLAUDE_CODE_SESSION_ID=sess-claude-mode CLAUDE_PID=$$ printf '%s\n' "$$" > "$FM_HOME/state/.lock" +printf '%s\n' "$CLAUDE_CODE_SESSION_ID" > "$FM_HOME/state/.lock-session" printf '{"session_id":"sess-claude-mode","stop_hook_active":false}\n' \ | FM_CLAUDE_AUTOARM_ATTEMPTS=1 "$FM_HOME/bin/fm-claude-stop-autoarm.sh" > "$FM_HOME/auto-$i.out" 2>&1 & auto_pid=$! From 4ee956ed2d53c3f9cc86e292901d7f6649a603e2 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 3 Nov 2026 15:29:51 +0000 Subject: [PATCH 03/34] feat(bin): choose a Claude account per ship or scout from a declared list (#8121) * feat(bin): choose a Claude account per ship or scout from a declared list Add an opt-in config/claude-accounts list of Claude config directories. When it is present, every Claude ship or scout spawn names one declared entry with --account; that entry passes the same root, raw-command, and stripped-environment `claude auth status` refusals as config/claude-account, and is recorded as account= on the spawn line and in the task record. A relaunch or recovery keeps the recorded account, and only an explicit `fm-control.sh relaunch --account ` moves a task to another declared account. Without the list nothing changes and --account refuses. bin/fm-claude-account-quota.sh measures each declared account in isolation with `quota-axi --provider claude --profile-only` and shows the highest known spendPriority, escalating on a tie or when nothing is rankable, so the existing quota-array-dispatch procedure can rank accounts. Refs #7638 * fix(bin): keep quota-axi's reason when an account read is rate-limited quota-axi exits nonzero when it cannot measure a provider, such as when the Claude quota endpoint rate-limits a burst of reads, but still prints a valid snapshot naming that state. fm-claude-account-quota.sh now keeps that snapshot, so the account is reported unmeasured with the vendor's reason instead of as an unreadable root. * no-mistakes(review): Make Claude account quota helper data-only; skill chooses account * fix(bin): close account-list review gaps on --account, runway, and secondmates - Refuse an --account value holding a control character, and match it against each whole declared entry, so a newline can no longer pass membership on one line or split the account= record. - Print each scope's usableRunwaySeconds and the runway's projectionConfidence in fm-claude-account-quota.sh rows, so the runway floor has the time it needs; confidence was previously always dropped because the snapshot carries it under runway. - Refuse --account on every secondmate spawn before the remote route, which previously accepted and ignored it. --------- Co-authored-by: Omkar Bhale --- .../references/harness/claude.md | 2 +- .../skills/operational-home-layout/SKILL.md | 1 + .agents/skills/quota-array-dispatch/SKILL.md | 13 +- .../skills/secondmate-provisioning/SKILL.md | 2 +- AGENTS.md | 4 +- bin/fm-claude-account-quota.sh | 147 +++++++++++++ bin/fm-control.sh | 25 ++- bin/fm-spawn.sh | 60 +++++- bin/fm-test-run.sh | 6 + bin/fm-worker-account-lib.sh | 173 ++++++++++++++-- docs/agent-control.md | 1 + docs/configuration.md | 33 ++- docs/fm-test-portable-shards.md | 1 + tests/fm-claude-account-quota.test.sh | 194 ++++++++++++++++++ tests/fm-control-relaunch.test.sh | 88 ++++++++ tests/fm-worker-account.test.sh | 150 ++++++++++++++ 16 files changed, 861 insertions(+), 39 deletions(-) create mode 100755 bin/fm-claude-account-quota.sh create mode 100644 tests/fm-claude-account-quota.test.sh diff --git a/.agents/skills/harness-adapters/references/harness/claude.md b/.agents/skills/harness-adapters/references/harness/claude.md index e802cd3c33c..f852b76b475 100644 --- a/.agents/skills/harness-adapters/references/harness/claude.md +++ b/.agents/skills/harness-adapters/references/harness/claude.md @@ -25,7 +25,7 @@ Every Claude spawn therefore pre-registers its launch directory before launch, a A second, separate dialog - "Allow external CLAUDE.md file imports?" - renders whenever a loaded CLAUDE.md chain reaches outside the project tree, which every crewmate's does through the captain's own `~/.claude/CLAUDE.md` importing `~/.claude/RTK.md`. `--setting-sources project,local`, which only `../../../bin/fm-live-lab.sh` passes (an `fm-spawn.sh` worker loads the user settings too), does not suppress it either, and it gates the session exactly like the trust dialog: cursor on "No, disable external imports", no way to move the selection from firstmate's steering plane. -`../../../bin/fm-claude-trust.sh` records `hasTrustDialogAccepted` for both the worktree and its primary checkout in `${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json`, where a home's worker account pin decides `CLAUDE_CONFIG_DIR` (`../../../docs/configuration.md` "Worker account pin"), for a ship or scout spawn; a secondmate spawn registers only its own home entry, since a secondmate home has no separate primary-checkout entry to carry import consent forward from. +`../../../bin/fm-claude-trust.sh` records `hasTrustDialogAccepted` for both the worktree and its primary checkout in `${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json`, where a home's worker account pin or the declared account a spawn names decides `CLAUDE_CONFIG_DIR` (`../../../docs/configuration.md` "Worker account pin"), for a ship or scout spawn; a secondmate spawn registers only its own home entry, since a secondmate home has no separate primary-checkout entry to carry import consent forward from. For a ship or scout spawn, the external-imports flags (`hasClaudeMdExternalIncludesApproved`, `hasClaudeMdExternalIncludesWarningShown`) are carried forward alongside the trust flag only when the primary checkout's project entry already carries an explicit `hasClaudeMdExternalIncludesApproved===true` from a prior interactive session - the common first-spawn case is a project claude has never been asked about, so those two flags are left unwritten and the import dialog still renders, even though trust registers normally. When the project entry instead already carries an explicit decline (`hasClaudeMdExternalIncludesApproved===false` with `hasClaudeMdExternalIncludesWarningShown===true`), the whole registration refuses - including the trust flag - rather than manufacture consent the human never gave, so that spawn wedges on the trust dialog before it would even reach the import one. Both flags `false` is Claude Code's default entry for a project never asked, not a decline, and is treated like an absent flag: trust registers and the import dialog still renders. diff --git a/.agents/skills/operational-home-layout/SKILL.md b/.agents/skills/operational-home-layout/SKILL.md index 208bf9318b4..ead74f00d92 100644 --- a/.agents/skills/operational-home-layout/SKILL.md +++ b/.agents/skills/operational-home-layout/SKILL.md @@ -24,6 +24,7 @@ config/crew-harness crewmate harness override; LOCAL, gitignored; absent or "de config/claude-permission-mode optional worker permission posture; LOCAL, gitignored; schema and failover: docs/configuration.md "Claude permission mode" and "Persistent managed-policy failover" config/codex-approval-mode optional worker approval posture; LOCAL, gitignored; schema and failover: docs/configuration.md "Codex automatic approval review" and "Persistent managed-policy failover" config/claude-account config/pi-account optional per-home worker account pin for Claude and Pi launches; LOCAL, gitignored, not inherited; absent keeps today's ambient account; present refuses a launch unless the pinned account resolves and is signed in (section 4 owns the refusal rule); see docs/configuration.md "Worker account pin" +config/claude-accounts optional list of Claude accounts a home's ships and scouts may launch on, one per line; LOCAL, gitignored, not inherited; absent changes nothing; present needs --account on every Claude ship or scout spawn and excludes config/claude-account; see docs/configuration.md "Several Claude accounts" config/secondmate-accounts//claude-account config/secondmate-accounts//pi-account optional PRIMARY-home account pin for one local secondmate's own agent, in the worker account pin format; LOCAL, gitignored, not inherited; absent keeps the home-wide pin; see docs/configuration.md "Per-secondmate account pins" config/secondmate-accounts//omp-profile optional PRIMARY-home omp profile name for one local omp secondmate's own agent (`omp --profile `); LOCAL, gitignored, not inherited; absent adds no flag; see docs/configuration.md "Per-secondmate omp profile" config/crew-dispatch.json optional crewmate dispatch profiles; LOCAL, gitignored; firstmate-maintained but human-editable natural-language rules that choose a per-task harness/model/effort profile (section 4). Inherited by secondmate homes diff --git a/.agents/skills/quota-array-dispatch/SKILL.md b/.agents/skills/quota-array-dispatch/SKILL.md index fb5cacfaa6d..30732d21596 100644 --- a/.agents/skills/quota-array-dispatch/SKILL.md +++ b/.agents/skills/quota-array-dispatch/SKILL.md @@ -1,7 +1,7 @@ --- name: quota-array-dispatch description: >- - Load when a crew-dispatch rule or default resolves to more than one profile candidate. + Load when a crew-dispatch rule or default resolves to more than one profile candidate, or a Claude ship or scout is dispatched from a home that declares config/claude-accounts. user-invocable: false metadata: internal: true @@ -41,6 +41,17 @@ Firstmate can optionally arm `bin/fm-procevent-quota.sh` for a recurring mid-tas The opt-in [typed resolver](../../../docs/configuration.md#typed-dispatch-resolution-env-fm_dispatch_provider-fm_dispatch_model) has its own documented gates. It never removes this skill's authority, and its `ambiguous`, `escalate`, and `error` outcomes return here. +## Claude account list + +When the home declares `config/claude-accounts`, each Claude candidate is one candidate per declared account, and the spawn needs the chosen account as `--account `. +Measure them with `bin/fm-claude-account-quota.sh [--model ]` instead of the default TOON's single `claude` row, which reads only the ambient account; its header owns the per-account read and output. +It prints data only, never a choice: each account's applicable scopes and any uncertainty it could not measure. +Apply the three gates below to each account's rows, taking a projected runway's time from the row's own `usableRunwaySeconds`, rank the eligible ones by their limiting scope's `spendPriority` exactly as for profiles, and pass the chosen entry as `--account `. +A genuine tie or no rankable account is the same terminal case as below: decide in the open from the rows or ask the captain, never by file order. +Account for every declared account in the rationale, including unmeasured ones. +A typed-resolver `clear` profile for Claude still needs this step's `--account`. +The account is chosen once, at intake: a relaunch keeps the recorded one, and only an explicit `--account` relaunch moves a task ([`docs/configuration.md`](../../../docs/configuration.md#several-claude-accounts-configclaude-accounts) owns the contract). + ## Read the default TOON When the home declares the [shared-quota opt-out](#shared-quota-opt-out), skip this section's quota reading and every quota-derived check built on it (quota rows, floors, runway, and `spendPriority`); catalog eligibility and reasoning-class fit still apply. diff --git a/.agents/skills/secondmate-provisioning/SKILL.md b/.agents/skills/secondmate-provisioning/SKILL.md index 23c299ec0b0..a06ed5d48da 100644 --- a/.agents/skills/secondmate-provisioning/SKILL.md +++ b/.agents/skills/secondmate-provisioning/SKILL.md @@ -109,7 +109,7 @@ The declared `config/supervision-host-off` opt-out follows the same primary-auth `config/secondmate-harness` is not inherited because it is only the primary's knob for launching secondmate agents. `config/firstmate-role` is inherited under the additional [resolved-role and receipt policy](../../../docs/configuration.md#firstmate-role-configfirstmate-role), not as a raw copy of the primary file. Account pins are not inherited. -[`Worker account pin`](../../../docs/configuration.md#worker-account-pin-configclaude-account-configpi-account) owns `config/claude-account` and `config/pi-account` inheritance and backend limits; [`T3 provider instances`](../../../docs/t3code-backend.md#provider-instances-and-models) owns T3 account selection. +[`Worker account pin`](../../../docs/configuration.md#worker-account-pin-configclaude-account-configpi-account) owns `config/claude-account`, `config/claude-accounts`, and `config/pi-account` inheritance and backend limits; [`T3 provider instances`](../../../docs/t3code-backend.md#provider-instances-and-models) owns T3 account selection. [`docs/configuration.md` "Per-secondmate account pins"](../../../docs/configuration.md#per-secondmate-account-pins) owns the explicit `config/secondmate-accounts//` override and the independent worker pins inside each mate's home. `data/captain-shared.md` is main-authoritative in the primary home and read-only in secondmate homes. Its primary file header must state that the file is main-authoritative, read-only in secondmate homes, must not be edited there, and that new captain-preference discoveries are routed to the main firstmate through marked status or a document pointer. diff --git a/AGENTS.md b/AGENTS.md index 670989a4b00..91671884731 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,7 +91,7 @@ Load `session-start-recovery` when the digest reports unfinished checks, actiona - Load `harness-adapters` before every spawn or recovery and before trust handling, skill invocation, interrupt, exit, resume, or adapter verification. - The verified harnesses are `claude`, `codex`, `opencode`, `pi`, `pi-signed`, `grok`, `kimi`, `cursor`, `omp`, and `agy`, plus `muse`, `gemini`, `rovo`, `devin`, `commandcode` (Command Code), `polytoken`, `cortex`, `kiro`, and `hermes` for crewmates and scouts only; never dispatch on an unverified adapter. - If static `config/crew-harness` or `config/secondmate-harness` names an unverified adapter, report it and fall back only to a verified adapter rather than launching it. -- Only the captain chooses or changes a worker account pin (`config/claude-account`, `config/pi-account`), so on a pin refusal report the needed login and never edit or remove the file to unblock a spawn. +- Only the captain chooses or changes a worker account pin or declared account list (`config/claude-account`, `config/pi-account`, `config/claude-accounts`), so on a pin refusal report the needed login and never edit or remove the file to unblock a spawn. `docs/configuration.md` owns dispatch-profile and runtime-backend schemas, `bin/fm-harness.sh` owns static resolution, and `bin/fm-spawn.sh` owns launch flags and fail-closed validation. When dispatch profiles exist, consult them at every crewmate or scout intake and pass the resolved concrete profile required by `fm-spawn`. @@ -106,7 +106,7 @@ Preserve malformed profile configuration as an actionable error rather than sele When every candidate is tight, preserve the captain's strongest-reasoning class rather than silently downgrading it solely to conserve quota; stop and report the tight choice if that class cannot proceed. Break genuine evidence ties without array-order or harness bias. `quota-axi` owns how model or product windows relate to bounding account windows and remains data-only. -Load `quota-array-dispatch` before choosing among a matched profile array; that skill is the single owner of the TOON-first spendPriority selection procedure. +Load `quota-array-dispatch` before choosing among a matched profile array or a Claude spawn's declared accounts; that skill is the single owner of the TOON-first spendPriority selection procedure. Run `bin/fm-dispatch-resolve.sh` directly on the written brief in the same turn, with no preflight, and on `clear` pass its `profile:` line to `fm-spawn` unless you state a reason to override; `ambiguous`, `escalate`, `error`, and off all mean the intake above, unchanged (contract: `docs/configuration.md` "Typed dispatch resolution"). The generic effort fallback and its precedence are owned by `harness-adapters`: explicit captain and standing configured effort win; otherwise use low for well-understood explicit work, xhigh for ambiguous investigation or design, intermediate levels proportionally, and never max without explicit captain preference. Do not add model-specific versions of that policy. diff --git a/bin/fm-claude-account-quota.sh b/bin/fm-claude-account-quota.sh new file mode 100755 index 00000000000..b3540f5746f --- /dev/null +++ b/bin/fm-claude-account-quota.sh @@ -0,0 +1,147 @@ +#!/usr/bin/env bash +# fm-claude-account-quota.sh - measure each Claude account a home declares in +# config/claude-accounts, in isolation, and print each one's quota facts. +# +# Usage: +# fm-claude-account-quota.sh [--model ] +# +# For every declared entry, in file order, runs +# CLAUDE_CONFIG_DIR= quota-axi --provider claude --profile-only --json +# where is the entry's own directory, or ~/.claude for `ordinary`. +# --profile-only reads only that root's credential file (no Keychain, refresh, +# fallback, or cache), so each row is that account's own quota and never the +# ambient account's; a root quota-axi cannot read there, such as an `ordinary` +# login kept in the macOS Keychain, is reported unmeasured. QUOTA_AXI_SNAPSHOT +# is removed from each read so a fixture for one account cannot answer for all. +# quota-axi exits nonzero when it cannot measure a provider, for example when +# the vendor rate-limits the quota endpoint, yet still prints a valid snapshot +# naming that state; such a snapshot is kept, so the account is reported +# unmeasured with the vendor's own reason rather than as an unreadable root. +# +# Each entry binds to its own snapshot's claude row and to the scopes that bound +# --model: all_models/all_products plus model: and product: for the +# bare id. This prints facts only; it never judges eligibility or picks an +# account. The quota-array-dispatch skill applies its gates and spendPriority +# ranking to these rows and chooses the --account to pass. +# +# Output (stdout, TOON-style block), one or more lines per declared entry in +# file order: +# claude-account-quota: +# row: root= scope= status=.. remaining=..% spendPriority=.. runway=.. usableRunwaySeconds=.. confidence=.. +# row: root= uncertainty: +# usableRunwaySeconds is that scope's own runway time from the same snapshot, +# printed whenever quota-axi reports it and always for projected_exhaustion, +# where `-` means the snapshot gave no finite time. confidence is the +# runway's projectionConfidence, the default TOON's confidence column. +# Uncertainty names a failed or invalid read, quota-axi's own unknown or +# rate-limited state and reason, a missing claude row, or no applicable scope. +# A missing quota-axi prints `error: quota-axi not installed` in the block. +# Readings exit 0. Exit 2 for a usage error, an absent list, or a list that +# bin/fm-worker-account-lib.sh refuses, which is actionable, never selected +# around. +# +# Data only: this never launches Claude, checks a sign-in, writes a credential, +# or changes any home or account file. bin/fm-spawn.sh runs the sign-in check +# for the account a launch names. +set -u + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}" +FM_HOME="${FM_HOME:-$FM_ROOT}" +CONFIG="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}" + +# shellcheck source=bin/fm-worker-account-lib.sh +. "$SCRIPT_DIR/fm-worker-account-lib.sh" +# shellcheck source=bin/fm-quota-axi-lib.sh +. "$SCRIPT_DIR/fm-quota-axi-lib.sh" + +FM_CLAUDE_ACCOUNT_QUOTA_SECONDS=${FM_CLAUDE_ACCOUNT_QUOTA_SECONDS:-60} + +die() { printf 'error: %s\n' "$1" >&2; exit 2; } +usage() { + awk ' + NR == 1 { next } + /^#/ { sub(/^# ?/, ""); print; next } + { exit } + ' "${BASH_SOURCE[0]}" +} + +MODEL= +while [ "$#" -gt 0 ]; do + case "$1" in + --model) + [ -n "${2-}" ] || die "--model needs a value" + MODEL=$2 + shift 2 + ;; + --model=*) + MODEL=${1#--model=} + [ -n "$MODEL" ] || die "--model needs a value" + shift + ;; + -h|--help|help) usage; exit 0 ;; + *) die "unexpected argument: $1" ;; + esac +done +[ "$MODEL" != default ] || MODEL= + +command -v jq >/dev/null 2>&1 || die "jq is required" +LISTED=$(fm_worker_account_list claude "$CONFIG") || exit 2 +[ -n "$LISTED" ] || die "this home declares no config/claude-accounts; there is nothing to measure" + +if ! command -v quota-axi >/dev/null 2>&1; then + printf 'claude-account-quota:\n error: quota-axi not installed\n' + exit 0 +fi + +WORK=$(mktemp -d "${TMPDIR:-/tmp}/fm-claude-account-quota.XXXXXX") || die "cannot create a scratch directory" +trap 'rm -rf "$WORK"' EXIT + +# Every entry becomes {account, root, snapshot} or {account, root, error}. +: > "$WORK/accounts.jsonl" +while IFS= read -r entry; do + root=$entry + [ "$entry" != ordinary ] || root="${HOME:?HOME is required to measure the ordinary account}/.claude" + error= + if fm_run_timed "$FM_CLAUDE_ACCOUNT_QUOTA_SECONDS" env -u QUOTA_AXI_SNAPSHOT CLAUDE_CONFIG_DIR="$root" \ + quota-axi --provider claude --profile-only --json > "$WORK/snapshot.json" 2>/dev/null > "$WORK/accounts.jsonl" || die "cannot record the quota reading for $entry" +done <<< "$LISTED" + +jq -rs --arg model "$MODEL" ' + def flat: tostring | gsub("[\t\r\n]"; " "); + def show($value): ($value // "-") | flat; + def bare($m): ($m | split("/") | last); + def applicable($row): + bare($model) as $b | + [$row.quotaSemantics.effectiveAvailability[]? | select( + .scope == "all_models" or .scope == "all_products" or + ($model != "" and (.scope == ("model:" + $b) or .scope == ("product:" + $b))) + )]; + "claude-account-quota:", + (.[] | " row: \(.account | flat) root=\(.root | flat)" as $head | + if .error then "\($head) uncertainty: \(.error | flat)" + else + ([.snapshot.providers[]? | select(.provider == "claude")] | first) as $row | + if $row == null then "\($head) uncertainty: no claude quota row" + else + applicable($row) as $rows | + (if (["known", "partial"] | index($row.quotaSemantics.status)) == null then + "\($head) uncertainty: quota \(show($row.quotaSemantics.status))\(if $row.state.status then " (\($row.state.status | flat): \(show($row.state.error)))" else "" end)" + else empty end), + (if ($rows | length) == 0 then "\($head) uncertainty: no applicable quota scope" else empty end), + ($rows[] | "\($head) scope=\(.scope | flat) status=\(show(.status)) remaining=\(show(.effectivePercentRemaining))% spendPriority=\(show(.selection.spendPriority)) runway=\(show(.runway.status))" + + (if .runway.usableRunwaySeconds != null or .runway.status == "projected_exhaustion" + then " usableRunwaySeconds=\(show(.runway.usableRunwaySeconds))" else "" end) + + ((.runway.projectionConfidence // .confidence) as $c | if $c then " confidence=\($c | flat)" else "" end)) + end + end) +' "$WORK/accounts.jsonl" || die "cannot format the quota readings" diff --git a/bin/fm-control.sh b/bin/fm-control.sh index 3405ee65196..ab9919abdf6 100755 --- a/bin/fm-control.sh +++ b/bin/fm-control.sh @@ -5,7 +5,7 @@ # Usage: fm-control.sh interrupt # fm-control.sh exit # fm-control.sh relaunch [--harness ] [--model ] -# [--effort ] +# [--effort ] [--account ] # (--note | --note-file ) # # Why this exists, and how it differs from fm-send.sh. bin/fm-send.sh is the @@ -84,7 +84,10 @@ # A replacement Claude or Pi profile must also pass this home's # worker account pin (bin/fm-worker-account-lib.sh) here, so a pin # that no longer resolves or is signed out refuses before the old -# agent stops. +# agent stops. Under a declared config/claude-accounts list, a +# Claude ship or scout keeps the account its record names, and +# only an explicit --account moves it to another +# declared one, checked here the same way. # A replacement omp secondmate likewise passes its per-secondmate # omp profile pin (bin/fm-omp-profile-lib.sh) before the old agent # stops. @@ -265,9 +268,11 @@ fi NEW_HARNESS= NEW_MODEL= NEW_EFFORT= +NEW_ACCOUNT= HARNESS_SET=0 MODEL_SET=0 EFFORT_SET=0 +ACCOUNT_SET=0 NOTE= NOTE_SET=0 control_want_value= @@ -280,6 +285,7 @@ for control_arg in "$@"; do harness) NEW_HARNESS=$control_arg; HARNESS_SET=1 ;; model) NEW_MODEL=$control_arg; MODEL_SET=1 ;; effort) NEW_EFFORT=$control_arg; EFFORT_SET=1 ;; + account) NEW_ACCOUNT=$control_arg; ACCOUNT_SET=1 ;; note) NOTE=$control_arg; NOTE_SET=1 ;; note_file) [ -f "$control_arg" ] || die "--note-file '$control_arg' is not a readable file" @@ -297,6 +303,8 @@ for control_arg in "$@"; do --model=*) NEW_MODEL=${control_arg#--model=}; MODEL_SET=1 ;; --effort) control_want_value=effort ;; --effort=*) NEW_EFFORT=${control_arg#--effort=}; EFFORT_SET=1 ;; + --account) control_want_value=account ;; + --account=*) NEW_ACCOUNT=${control_arg#--account=}; ACCOUNT_SET=1 ;; --note) control_want_value=note ;; --note=*) NOTE=${control_arg#--note=}; NOTE_SET=1 ;; --note-file) control_want_value=note_file ;; @@ -314,9 +322,10 @@ if [ -n "$control_want_value" ]; then fi if [ "$VERB" != relaunch ]; then - [ "$HARNESS_SET" = 0 ] && [ "$MODEL_SET" = 0 ] && [ "$EFFORT_SET" = 0 ] && [ "$NOTE_SET" = 0 ] \ - || die "--harness, --model, --effort, and --note apply to 'relaunch' only" + [ "$HARNESS_SET" = 0 ] && [ "$MODEL_SET" = 0 ] && [ "$EFFORT_SET" = 0 ] && [ "$ACCOUNT_SET" = 0 ] && [ "$NOTE_SET" = 0 ] \ + || die "--harness, --model, --effort, --account, and --note apply to 'relaunch' only" fi +[ "$ACCOUNT_SET" = 0 ] || [ -n "$NEW_ACCOUNT" ] || die "--account requires a non-empty value" [ "$HARNESS_SET" = 0 ] || [ -n "$NEW_HARNESS" ] || die "--harness requires a non-empty value" [ "$MODEL_SET" = 0 ] || [ -n "$NEW_MODEL" ] || die "--model requires a non-empty value" [ "$EFFORT_SET" = 0 ] || [ -n "$NEW_EFFORT" ] || die "--effort requires a non-empty value" @@ -874,6 +883,7 @@ PRIOR_EFFORT= TARGET_HARNESS=$HARNESS TARGET_MODEL= TARGET_EFFORT= +TARGET_ACCOUNT= journal_write() { # [extra-line]... local phase=$1 @@ -1072,11 +1082,15 @@ resolve_relaunch_profile() { # The launch owner applies this home's worker account pin too, but only after # the old agent has been stopped, so a pin that no longer resolves or is # signed out must refuse here, while nothing has changed yet. + # Under a declared Claude account list, the replacement stays on the + # account the task records unless --account explicitly moves it. local account_model=$TARGET_MODEL account_mate= [ "$account_model" != default ] || account_model= [ "$KIND" != secondmate ] || account_mate=$ID + TARGET_ACCOUNT=$(fm_worker_account_relaunch_request "$TARGET_HARNESS" "${FM_CONFIG_OVERRIDE:-$FM_HOME/config}" \ + "$PRIOR_HARNESS" "$(fm_meta_get "$META" account)" "$NEW_ACCOUNT" "$account_mate") || return 1 fm_worker_account_select "$TARGET_HARNESS" "${FM_CONFIG_OVERRIDE:-$FM_HOME/config}" \ - "$account_model" "$TARGET_HARNESS" "" "$account_mate" >/dev/null || return 1 + "$account_model" "$TARGET_HARNESS" "" "$account_mate" "$TARGET_ACCOUNT" >/dev/null || return 1 fm_omp_profile_select "$TARGET_HARNESS" "${FM_CONFIG_OVERRIDE:-$FM_HOME/config}" \ "$account_mate" >/dev/null || return 1 # Likewise polytoken's launch profile and wiring refusals @@ -1253,6 +1267,7 @@ do_relaunch() { spawn_args=("$ID" --relaunch --harness "$TARGET_HARNESS") [ "$TARGET_MODEL" = default ] || spawn_args+=(--model "$TARGET_MODEL") [ "$TARGET_EFFORT" = default ] || spawn_args+=(--effort "$TARGET_EFFORT") + [ -z "$TARGET_ACCOUNT" ] || spawn_args+=(--account "$TARGET_ACCOUNT") if FM_CONTROL_RELAUNCH_TX="$RELAUNCH_TX" \ "$SCRIPT_DIR/fm-spawn.sh" "${spawn_args[@]}" >/dev/null; then RELAUNCH_META_PUBLISHED=1 diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh index 795dbaa6420..7f91ff72315 100755 --- a/bin/fm-spawn.sh +++ b/bin/fm-spawn.sh @@ -1,8 +1,8 @@ #!/usr/bin/env bash # Spawn a direct report: a crewmate in a treehouse or Orca worktree, or a # secondmate in its isolated firstmate home. -# Usage: fm-spawn.sh --mode --yolo [--branch-prefix ] [--base-branch ] [--harness |harness|launch-command] [--model ] [--effort ] [--hermes-profile ] [--backend ] [--herdr-resume-lock-wait] -# fm-spawn.sh --scout [--base-branch ] [--harness |harness|launch-command] [--model ] [--effort ] [--hermes-profile ] [--backend ] [--herdr-resume-lock-wait] +# Usage: fm-spawn.sh --mode --yolo [--branch-prefix ] [--base-branch ] [--harness |harness|launch-command] [--model ] [--effort ] [--hermes-profile ] [--account ] [--backend ] [--herdr-resume-lock-wait] +# fm-spawn.sh --scout [--base-branch ] [--harness |harness|launch-command] [--model ] [--effort ] [--hermes-profile ] [--account ] [--backend ] [--herdr-resume-lock-wait] # fm-spawn.sh [] [--harness |harness|launch-command] [--model ] [--effort ] [--backend ] --secondmate # --mode and --yolo are this task's delivery contract, REQUIRED for every ship # spawn and refused on --scout and --secondmate spawns. Firstmate resolves both @@ -64,7 +64,7 @@ # first in the private launch-brief overlay, including the exact task-owned # steering inbox. This never rewrites a project's instruction files or a # secondmate's charter. -# fm-spawn.sh --relaunch [--harness ] [--model ] [--effort ] +# fm-spawn.sh --relaunch [--harness ] [--model ] [--effort ] [--account ] # --relaunch launches a replacement agent for an EXISTING task into that # task's own recorded worktree, reusing its recorded endpoint when that # endpoint still exists, instead of creating either from scratch. It is @@ -75,13 +75,14 @@ # backend, kind, project or home, worktree, endpoint - comes from the task's # validated state/.meta, so --backend, --scout, --secondmate, a project # positional, and batch pairs are all refused alongside it; only harness, -# model, and effort may change, which is what makes a harness switch one -# ordinary relaunch. It refuses unless the recorded endpoint is positively -# agent-free on a backend with both a recovery-grade agent-state classifier -# and replacement-agent support (tmux or herdr), and clears the previous -# harness's per-task wiring before arming the new incarnation. T3 Code has -# the classifier but refuses relaunch because a thread keeps its conversation -# across turns and provider changes. Two verdicts are agent-free: a `dead` +# model, effort, and a declared Claude account may change, which is what +# makes a harness switch one ordinary relaunch. It refuses unless the +# recorded endpoint is positively agent-free on a backend with both a +# recovery-grade agent-state classifier and replacement-agent support +# (tmux or herdr), and clears the previous harness's per-task wiring +# before arming the new incarnation. T3 Code has the classifier but refuses +# relaunch because a thread keeps its conversation across turns and provider +# changes. Two verdicts are agent-free: a `dead` # endpoint is ADOPTED as-is, while an endpoint PROVEN gone is RE-CREATED in the recorded # worktree and the republished record rebinds the task to it. That proof is # its own step, because a backend's `missing` also covers an endpoint that is @@ -506,6 +507,13 @@ # Pins are never inherited; remote per-mate overrides refuse locally. # T3 Code refuses a pin because its provider instance owns the account. # bin/fm-worker-account-lib.sh owns parsing, the check, and the shed list. +# Claude account list (config/claude-accounts, --account ): +# Opt-in and Claude-only. When the list is present, a Claude ship or scout +# spawn must name one declared entry with --account, chosen at intake, and +# that entry is checked, launched, and recorded exactly like a pin; a +# relaunch reuses the recorded entry unless --account moves it. Without the +# list, --account refuses and nothing else changes. docs/configuration.md +# "Several Claude accounts" owns the contract. # Per-secondmate omp profile (config/secondmate-accounts//omp-profile): # Opt-in, and read only for a local secondmate's own omp agent; # bin/fm-omp-profile-lib.sh owns the file and its refusals. A pinned launch @@ -995,6 +1003,8 @@ BASE_BRANCH_SET=0 UPSTREAM_CONSENT= UPSTREAM_CONSENT_SET=0 TRACEPARENT_SET=0 +ACCOUNT_ARG= +ACCOUNT_SET=0 RELAUNCH=0 # Opt-in only: exact-resume presentation-order lock waits instead of refusing. # Absent/unset keeps upstream refuse-on-contention. See header. @@ -1054,6 +1064,10 @@ for a in "$@"; do TRACEPARENT_ARG=$a TRACEPARENT_SET=1 ;; + account) + ACCOUNT_ARG=$a + ACCOUNT_SET=1 + ;; *) echo "error: internal parser state for --$want_value" >&2 exit 1 @@ -1125,6 +1139,11 @@ for a in "$@"; do TRACEPARENT_ARG=${a#--traceparent=} TRACEPARENT_SET=1 ;; + --account) want_value=account ;; + --account=*) + ACCOUNT_ARG=${a#--account=} + ACCOUNT_SET=1 + ;; *) POS+=("$a") ;; esac done @@ -1172,6 +1191,16 @@ fi echo "error: --traceparent requires a non-empty value" >&2 exit 1 } +[ "$ACCOUNT_SET" -eq 0 ] || [ -n "$ACCOUNT_ARG" ] || { + echo "error: --account requires a non-empty value" >&2 + exit 1 +} +# A secondmate, local or remote, launches on its own per-mate pin, so --account +# is refused here, before the remote route could ignore it. +[ "$ACCOUNT_SET" -eq 0 ] || [ "$KIND" != secondmate ] || { + echo "error: --account applies to ships and scouts; secondmate ${POS[0]:-} launches on its own config/secondmate-accounts//claude-account pin" >&2 + exit 1 +} # A parent-delivered carrier replaces this home's own resolution, so it is # refused unless it is a secondmate spawn carrying a strictly valid W3C value. # Nothing else may reach the pane's TRACEPARENT export. @@ -2125,6 +2154,7 @@ if [ "${#POS[@]}" -gt 0 ] && [ "${POS[0]}" != "$idpart" ] && case "$idpart" in * [ "$BRANCH_PREFIX_SET" -eq 0 ] || shared_args+=(--branch-prefix "$BRANCH_PREFIX") [ "$BASE_BRANCH_SET" -eq 0 ] || shared_args+=(--base-branch "$BASE_BRANCH") [ "$HERDR_RESUME_LOCK_WAIT" -eq 0 ] || shared_args+=(--herdr-resume-lock-wait) + [ "$ACCOUNT_SET" -eq 0 ] || shared_args+=(--account "$ACCOUNT_ARG") for pair in "${POS[@]}"; do case "$pair" in *=*) : ;; @@ -3404,7 +3434,15 @@ RAW_COMMAND= [ "$RAW_LAUNCH" = 0 ] || RAW_COMMAND=$ARG3 WORKER_ACCOUNT_MATE= [ "$KIND" != secondmate ] || WORKER_ACCOUNT_MATE=$ID -WORKER_ACCOUNT=$(fm_worker_account_select "$HARNESS" "$CONFIG" "$MODEL" "${PI_BIN:-$HARNESS}" "$RAW_COMMAND" "$WORKER_ACCOUNT_MATE") || exit 1 +# A declared Claude account list (config/claude-accounts) needs the entry this +# launch spends: --account on a fresh spawn, and on a relaunch that flag or +# else the account the task already records. +WORKER_ACCOUNT_REQUEST=$ACCOUNT_ARG +if [ "$RELAUNCH" -eq 1 ]; then + WORKER_ACCOUNT_REQUEST=$(fm_worker_account_relaunch_request "$HARNESS" "$CONFIG" "$RELAUNCH_PRIOR_HARNESS" \ + "$(fm_meta_get "$RELAUNCH_META" account)" "$ACCOUNT_ARG" "$WORKER_ACCOUNT_MATE") || exit 1 +fi +WORKER_ACCOUNT=$(fm_worker_account_select "$HARNESS" "$CONFIG" "$MODEL" "${PI_BIN:-$HARNESS}" "$RAW_COMMAND" "$WORKER_ACCOUNT_MATE" "$WORKER_ACCOUNT_REQUEST") || exit 1 WORKER_ACCOUNT_DECLARED=${WORKER_ACCOUNT%%$'\t'*} WORKER_ACCOUNT_ROOT=${WORKER_ACCOUNT#*$'\t'} WORKER_ACCOUNT_PROVIDER=${WORKER_ACCOUNT_ROOT#*$'\t'} diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh index 5e746fca121..ad5779ad0f0 100755 --- a/bin/fm-test-run.sh +++ b/bin/fm-test-run.sh @@ -445,6 +445,7 @@ family_for_basename() { ;; fm-branch-supervision.test.sh|fm-busy-adapter-wiring.test.sh|\ fm-busy-state.test.sh|fm-capacity.test.sh|fm-classify-corr-token.test.sh|\ + fm-claude-account-quota.test.sh|\ fm-claude-stop-autoarm.test.sh|fm-cursor-harness.test.sh|\ fm-dispatch-resolve.test.sh|\ fm-extension-binding.test.sh|fm-gitignore-config.test.sh|\ @@ -768,6 +769,7 @@ tests/fm-check-unregister.test.sh 469 tests/fm-ci-workflow.test.sh 5833 tests/fm-classify-corr-token.test.sh 23085 tests/fm-classify-decision-key.test.sh 4362 +tests/fm-claude-account-quota.test.sh 2492 tests/fm-claude-stop-autoarm-live-e2e.test.sh 73 tests/fm-claude-stop-autoarm.test.sh 61189 tests/fm-claude-trust.test.sh 12010 @@ -1630,6 +1632,7 @@ families_for_changed_path() { printf '%s\n' "__script__:fm-procevent-quota.test.sh" printf '%s\n' "__script__:fm-quota-choose.test.sh" printf '%s\n' "__script__:fm-dispatch-resolve.test.sh" + printf '%s\n' "__script__:fm-claude-account-quota.test.sh" ;; bin/fm-procevent-quota.sh) printf '%s\n' "__script__:fm-procevent-quota.test.sh" @@ -1637,6 +1640,9 @@ families_for_changed_path() { bin/fm-quota-choose.sh) printf '%s\n' "__script__:fm-quota-choose.test.sh" ;; + bin/fm-claude-account-quota.sh) + printf '%s\n' "__script__:fm-claude-account-quota.test.sh" + ;; bin/fm-dispatch-resolve.sh) printf '%s\n' "__script__:fm-dispatch-resolve.test.sh" ;; diff --git a/bin/fm-worker-account-lib.sh b/bin/fm-worker-account-lib.sh index b064821d04f..3ecb7b72f45 100644 --- a/bin/fm-worker-account-lib.sh +++ b/bin/fm-worker-account-lib.sh @@ -52,6 +52,20 @@ # the pin. Pi ranks a root's stored credentials above environment variables, # and the check refuses a provider the root has not stored, so a pinned Pi # launch unsets nothing. +# +# A home that spends several Claude subscriptions declares them instead in +# config/claude-accounts: one entry per line, each `ordinary` or an absolute +# path exactly as config/claude-account would hold it, with no blank lines, +# duplicates, or control characters, and an optional final newline. The list is +# opt-in in the same way: absent, nothing here changes. Present, it replaces the +# home-wide pin, which must then be absent, and every Claude ship or scout +# launch names one declared entry with --account; Firstmate chooses it at +# intake (bin/fm-claude-account-quota.sh measures each entry) and never +# defaults to the first entry, another entry, or the ambient account. The named +# entry passes the same root, raw-command, and sign-in refusals as a pin and is +# recorded as account=, which a ship or scout relaunch reuses unless an +# explicit --account moves it. A local secondmate's agent never draws from the +# list: it needs its own per-secondmate pin. # shellcheck source=bin/fm-timeout-lib.sh . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/fm-timeout-lib.sh" @@ -173,6 +187,70 @@ fm_worker_account_resolve() { printf '%s\t%s\t%s\n' "$declared" "$root" "${token#*$'\t'}" } +# fm_worker_account_list +# Prints the entries config/claude-accounts declares, one per line, for a +# Claude launch. Prints nothing and returns 0 for another runner or when the +# list is absent. On a malformed or unreadable list prints one error naming the +# file and returns 1. +fm_worker_account_list() { + local harness=$1 cfg="$2/claude-accounts" out rc + [ "$harness" = claude ] || return 0 + out=$(perl -MErrno=ENOENT -e ' + my ($f) = @ARGV; + unless (lstat $f) { + exit 3 if $! == ENOENT; + print STDERR "error: cannot inspect configuration source at $f: $!\n"; + exit 4; + } + (-f $f && -r _) or exit 5; + open(my $fh, "<", $f) or exit 5; + my $body = do { local $/; <$fh> } // ""; + $body =~ /\A(?:(?:ordinary|\/[^\x00-\x1f\x7f]*)\n)*(?:ordinary|\/[^\x00-\x1f\x7f]*)\n?\z/ or exit 6; + my %seen; + for my $entry (split /\n/, $body) { + exit 7 if $seen{$entry}++; + print $entry, "\n"; + } + ' -- "$cfg") + rc=$? + case "$rc" in + 0) printf '%s\n' "$out" ;; + 3) return 0 ;; + 4) return 1 ;; + 5) + echo "error: config/claude-accounts must be a readable regular file: $cfg" >&2 + return 1 + ;; + 7) + echo "error: config/claude-accounts declares the same account twice: $cfg" >&2 + return 1 + ;; + *) + echo "error: config/claude-accounts must hold one account per line, each 'ordinary' or an absolute path, with no blank lines or control characters: $cfg" >&2 + return 1 + ;; + esac +} + +# fm_worker_account_relaunch_request [] +# Prints the declared account a relaunch asks fm_worker_account_select for: +# the explicit one when given, otherwise the task's recorded account when the +# home declares config/claude-accounts and a Claude ship or scout stays on +# Claude. Prints nothing otherwise, so a relaunch without a list re-reads the +# pin exactly as before. Returns 1 when the explicit account holds a control +# character or the list cannot be read. +fm_worker_account_relaunch_request() { + local harness=$1 config=$2 prior=$3 recorded=$4 explicit=$5 mate=${6:-} listed + fm_worker_account_request_valid "$explicit" || return 1 + if [ -n "$explicit" ] || [ -n "$mate" ]; then + printf '%s\n' "$explicit" + return 0 + fi + listed=$(fm_worker_account_list "$harness" "$config") || return 1 + [ -n "$listed" ] && [ "$prior" = claude ] || return 0 + printf '%s\n' "$recorded" +} + # fm_worker_account_pi_provider # Prints the provider an explicit Pi --model / names. Returns 1, # silently, for anything else, so no caller can fall back to a guess. @@ -239,30 +317,91 @@ fm_worker_account_check() { return 0 } -# fm_worker_account_select [] [] +# fm_worker_account_request_valid +# Refuses an --account value holding a control character. Declared entries +# never hold one, and a newline would otherwise split the value before the +# whole-entry membership check or the account= record sees it. +fm_worker_account_request_valid() { + case "$1" in + *[[:cntrl:]]*) + echo "error: --account must name one config/claude-accounts entry exactly, with no control characters" >&2 + return 1 + ;; + esac +} + +# fm_worker_account_select [] [] [] # The whole launch-time decision. Prints nothing for an unpinned runner, so -# the caller keeps today's launch unchanged. For a pinned one prints -# "declaredrootprovider", where provider is the Pi launch model's -# own (empty for Claude), after the model guard and the sign-in check pass. On -# refusal prints one error and returns 1. bin/fm-spawn.sh runs it before any -# endpoint exists, and bin/fm-control.sh before a relaunch stops the live -# agent. +# the caller keeps today's launch unchanged. For a pinned one, or a Claude +# ship or scout launching on a declared config/claude-accounts entry named by +# , prints "declaredrootprovider", where provider is the +# Pi launch model's own (empty for Claude), after the model guard and the +# sign-in check pass. On refusal prints one error and returns 1. +# bin/fm-spawn.sh runs it before any endpoint exists, and bin/fm-control.sh +# before a relaunch stops the live agent. fm_worker_account_select() { - local harness=$1 config=$2 model=$3 executable=$4 raw=${5:-} mate=${6:-} - local selection declared root providers word provider='' selected_config setting + local harness=$1 config=$2 model=$3 executable=$4 raw=${5:-} mate=${6:-} account=${7:-} + local selection declared root providers word provider='' selected_config setting listed count + fm_worker_account_request_valid "$account" || return 1 + if [ -n "$account" ] && [ "$harness" != claude ]; then + echo "error: --account names one of config/claude-accounts and applies to Claude workers only, not $harness" >&2 + return 1 + fi + if [ -n "$account" ] && [ -n "$mate" ]; then + echo "error: --account applies to ships and scouts; secondmate $mate launches on its own config/secondmate-accounts/$mate/claude-account pin" >&2 + return 1 + fi + listed=$(fm_worker_account_list "$harness" "$config") || return 1 + if [ -z "$listed" ] && [ -n "$account" ]; then + echo "error: --account '$account' needs config/claude-accounts, which this home does not declare" >&2 + return 1 + fi + if [ -n "$listed" ] && { [ -e "$config/claude-account" ] || [ -L "$config/claude-account" ]; }; then + echo "error: config/claude-accounts and config/claude-account are both present; keep the account list or the single pin, not both" >&2 + return 1 + fi selected_config=$(fm_worker_account_config "$harness" "$config" "$mate") || return 1 setting="config/$(fm_worker_account_file "$harness")" [ "$selected_config" = "$config" ] || setting="$selected_config/$(fm_worker_account_file "$harness")" - selection=$(fm_worker_account_resolve "$harness" "$selected_config" "$setting") || return 1 - if [ -z "$selection" ]; then - [ "$selected_config" = "$config" ] && return 0 - echo "error: secondmate account pin disappeared during selection: $setting" >&2 + if [ -n "$listed" ] && [ -n "$mate" ] && [ "$selected_config" = "$config" ]; then + echo "error: config/claude-accounts chooses accounts for ships and scouts only; secondmate $mate needs its own pin in config/secondmate-accounts/$mate/claude-account" >&2 return 1 + elif [ -n "$listed" ] && [ -z "$mate" ]; then + setting=config/claude-accounts + if [ -z "$account" ]; then + count=$(printf '%s\n' "$listed" | wc -l | tr -d ' ') + echo "error: config/claude-accounts declares $count Claude accounts, so a Claude ship or scout launch must name one with --account; bin/fm-claude-account-quota.sh measures each, and Firstmate never picks a default" >&2 + return 1 + fi + declared= + while IFS= read -r word; do + [ "$word" != "$account" ] || { declared=$account; break; } + done <<< "$listed" + [ -n "$declared" ] || { + echo "error: account '$account' is not declared in config/claude-accounts; name a declared entry with --account" >&2 + return 1 + } + declared=$account + root=$account + [ "$declared" != ordinary ] || root= + if [ -n "$root" ] && { [ ! -d "$root" ] || [ ! -r "$root" ] || [ ! -x "$root" ]; }; then + # shellcheck disable=SC2088 # Literal text for the refusal. + echo "error: $setting must name readable, searchable existing directories (ordinary means ~/.claude with CLAUDE_CONFIG_DIR unset): $root" >&2 + return 1 + fi + providers= + else + selection=$(fm_worker_account_resolve "$harness" "$selected_config" "$setting") || return 1 + if [ -z "$selection" ]; then + [ "$selected_config" = "$config" ] && return 0 + echo "error: secondmate account pin disappeared during selection: $setting" >&2 + return 1 + fi + declared=${selection%%$'\t'*} + root=${selection#*$'\t'} + providers=${root#*$'\t'} + root=${root%%$'\t'*} fi - declared=${selection%%$'\t'*} - root=${selection#*$'\t'} - providers=${root#*$'\t'} - root=${root%%$'\t'*} if [ "$harness" = claude ]; then for word in $raw; do case "$word" in diff --git a/docs/agent-control.md b/docs/agent-control.md index bc9f28f7e0f..5c0fbe3a386 100644 --- a/docs/agent-control.md +++ b/docs/agent-control.md @@ -81,6 +81,7 @@ A relaunch does take one session reference when the endpoint's own runtime recor A recorded raw-command basename that differs from its resolved adapter cannot reproduce the command actually running, so relaunch refuses before the checkpoint unless the caller passes an explicit `--harness` to choose the replacement runtime deliberately. A harness change resets model and effort unless they are named too, because a model chosen for one adapter does not transfer to another. A Claude or Pi replacement must also pass the home's [worker account pin](configuration.md#worker-account-pin-configclaude-account-configpi-account), or a secondmate's own [per-secondmate account pin](configuration.md#per-secondmate-account-pins) when one is set, so a pin that no longer resolves or is signed out refuses before the old agent stops. + Under a declared [Claude account list](configuration.md#several-claude-accounts-configclaude-accounts), a Claude ship or scout keeps its recorded account, and `--account ` moves it to another declared one after the same check. An omp secondmate replacement likewise passes its [per-secondmate omp profile](configuration.md#per-secondmate-omp-profile) file check before the old agent stops. Ship and scout replacements also pass the [worker tool exclusion checks](configuration.md#worker-tool-exclusions-configcrew-exclude-tools) at this step. 2. **Safe checkpoint.** diff --git a/docs/configuration.md b/docs/configuration.md index f1ae02829eb..7859af75d29 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -9,7 +9,7 @@ Start with the directory layout, then use the setting reference for the behavior | --- | --- | | Firstmate's code, private files, or project location | [FM_HOME](#fm_home) and [operational home layout](#operational-home-layout-and-state) | | Task windows and worker tools | [Runtime backend](#runtime-backend-configbackend--fm_backend) and [harness support](#harness-support) | -| Worker permissions, accounts, or environment | [Codex approval review](#codex-automatic-approval-review), [Claude permission mode](#claude-permission-mode-configclaude-permission-mode), [Codex permission mode](#codex-permission-mode-configcodex-permission-mode), [persistent managed-policy failover](#persistent-managed-policy-failover), [worker account pin](#worker-account-pin-configclaude-account-configpi-account), [worker tool exclusions](#worker-tool-exclusions-configcrew-exclude-tools), [worker launch environment](#worker-launch-environment-configlaunch-env-allowlist), and its [Orca environment source](#orca-environment-source-configlaunch-env-tmux-session) | +| Worker permissions, accounts, or environment | [Codex approval review](#codex-automatic-approval-review), [Claude permission mode](#claude-permission-mode-configclaude-permission-mode), [Codex permission mode](#codex-permission-mode-configcodex-permission-mode), [persistent managed-policy failover](#persistent-managed-policy-failover), [worker account pin](#worker-account-pin-configclaude-account-configpi-account), [several Claude accounts](#several-claude-accounts-configclaude-accounts), [worker tool exclusions](#worker-tool-exclusions-configcrew-exclude-tools), [worker launch environment](#worker-launch-environment-configlaunch-env-allowlist), and its [Orca environment source](#orca-environment-source-configlaunch-env-tmux-session) | | Backlog, preferences, and memory | [Backlog backend](#backlog-backend-taskstoml--configbacklog-backend), [captain preferences](#captain-preferences-datacaptainmd--datacaptain-sharedmd), [external memory tiers](#external-memory-tiers-memory-layering-section), [record export](#record-export-configrecord-export-root), and [startup memory budget](#startup-memory-budget-configstartup-memory-budget) | | Supervision and presentation | [Pi supervision branch](#pi-supervision-branch), [supervision host](#supervision-host-configsupervision-host), [Codex native Stop park](#codex-native-stop-park-configcodex-stop-park), [warm-cache compaction](#warm-cache-compaction-configwarm-compact), and [Calm preference](#calm-preference-configcalm) | | Persistent secondmates | [Secondmate routes](#secondmate-routes-datasecondmatesmd) | @@ -1552,6 +1552,37 @@ A remote secondmate is launched on its host from its own home's configuration, s [`bin/fm-worker-account-lib.sh`](../bin/fm-worker-account-lib.sh) owns parsing, the sign-in check, and the full list of credentials a Claude launch unsets; [runtime backend verification](verification/runtime-backends.md#worker-account-pin-sign-in-check) records the check against the real runners. +### Several Claude accounts (config/claude-accounts) + +A home with more than one Claude subscription can let each ship and scout launch on whichever declared account has quota to spare, instead of pinning every Claude worker to one account. +Create `config/claude-accounts` with one account per line, each `ordinary` or the absolute path of an existing Claude config directory, written exactly as `config/claude-account` would hold it: + +```text +ordinary +/home/me/.claude-second +``` + +A final newline is optional; a blank line, a relative path, a repeated entry, or a control character refuses. +The list is opt-in: without it, every launch, including the single pin above, behaves exactly as before, and `--account` refuses. +A home keeps either the list or `config/claude-account`, never both; with both present, every Claude launch refuses. + +While the list is present, every Claude ship or scout spawn must name one declared entry with `--account `. +Firstmate chooses that entry at dispatch intake under the [`quota-array-dispatch`](../.agents/skills/quota-array-dispatch/SKILL.md) procedure, and [`bin/fm-claude-account-quota.sh`](../bin/fm-claude-account-quota.sh) measures each entry for it by running `quota-axi --provider claude --profile-only` under that entry's own config directory (`~/.claude` for `ordinary`). +Firstmate never picks an entry by default, by file order, or from the ambient account, and never discovers, adds, or copies a login. + +The named entry passes the same refusals as a pin before anything launches: its directory must exist, a raw Claude command must not override it, and `claude auth status` must say it is signed in, with the stripped environment and credential unsetting described above. +An undeclared, missing, or signed-out entry refuses rather than falling back to another entry or the ambient account. +The spawn line and the task record carry the entry as `account=`. + +A relaunch or recovery of that task keeps its recorded account, re-checking that it is still declared and signed in before the running worker stops. +To move a task to another declared account, for example when its own account is exhausted, relaunch it explicitly with `bin/fm-control.sh relaunch --account --note `; nothing moves a running task automatically. +A task with no recorded account, or one whose account is no longer declared, refuses a plain relaunch and needs that explicit `--account`. + +The list covers Claude ships and scouts only. +A local secondmate's own agent never draws from it: under a list it needs its own [per-secondmate account pin](#per-secondmate-account-pins), and `--account` refuses for every secondmate, local or remote. +Other runners ignore the list, and `--account` refuses for them. +Like the single pin, the list is not inherited into secondmate homes. + ### Per-secondmate account pins To choose an account for one local secondmate's own agent, create `config/secondmate-accounts//claude-account` or `config/secondmate-accounts//pi-account` in the primary home. diff --git a/docs/fm-test-portable-shards.md b/docs/fm-test-portable-shards.md index d3d29258111..9cefd369b0f 100644 --- a/docs/fm-test-portable-shards.md +++ b/docs/fm-test-portable-shards.md @@ -26,6 +26,7 @@ The native-Windows-only `tests/fm-pi-windows-shell-invocation.test.sh` retains i The 2026-10-07 polytoken adapter tests carry provisional local measurements instead - 21090 ms for `tests/fm-polytoken-harness.test.sh` and the 103 ms live-guard skip for `tests/fm-polytoken-signals-live-e2e.test.sh`, both measured on the adapter-verification macOS host - until the next CI refresh replaces them with Ubuntu measurements, because they postdate the 2026-09-30 baseline. The 2026-10-23 `tests/fm-approval-failover.test.sh` serial hint is a provisional local measurement of 5410 ms, the slowest of five local `bin/fm-test-run.sh` samples (4991-5410 ms), until the next CI refresh replaces it with an Ubuntu timing-artifact maximum. The 2026-10-23 Kimi folder-prompt live guard, `tests/fm-kimi-trust-prompt-live-e2e.test.sh`, carries a provisional 60 ms skip measured on the Linux host that recorded its captures, until the next CI refresh replaces it with an Ubuntu measurement. +The 2026-10-27 `tests/fm-claude-account-quota.test.sh` serial hint is a provisional local measurement of 2492 ms, the slowest of five local `bin/fm-test-run.sh` samples (1930-2492 ms) on a Linux host, until the next CI refresh replaces it with an Ubuntu timing-artifact maximum. The 2026-10-26 `tests/fm-test-tap-verify.test.sh` serial hint is a provisional local measurement of 1000 ms, above a 238 ms `bin/fm-test-run.sh` sample on this Linux host, until the next CI refresh replaces it with an Ubuntu timing-artifact maximum. The 2026-10-27 read-repetition suites carry provisional Linux x86_64 local runner maxima: 602 ms for `tests/fm-read-repetition.test.sh` (six successful samples, 528-602 ms) and 1110 ms for `tests/fm-read-repetition-live.test.sh` (five successful samples, 949-1110 ms). The live samples exercised installed Pi 1.4.0 RPC without capability skips; they are not CI timing evidence or timings for unavailable harnesses. diff --git a/tests/fm-claude-account-quota.test.sh b/tests/fm-claude-account-quota.test.sh new file mode 100644 index 00000000000..aed186448b0 --- /dev/null +++ b/tests/fm-claude-account-quota.test.sh @@ -0,0 +1,194 @@ +#!/usr/bin/env bash +# Behavior tests for bin/fm-claude-account-quota.sh: each account declared in +# config/claude-accounts is measured under its own CLAUDE_CONFIG_DIR and its +# quota facts and uncertainty are printed, never a choice. +# +# A fake quota-axi answers from /quota.json, the way the real +# --profile-only read answers from that root's own credential file, and logs +# the root and arguments of every read. +set -u + +# shellcheck source=tests/lib.sh +. "$(dirname "${BASH_SOURCE[0]}")/lib.sh" + +TMP_ROOT=$(fm_test_tmproot fm-claude-account-quota) +TOOL="$ROOT/bin/fm-claude-account-quota.sh" + +# new_case -> sets CASE HOME_DIR FAKEBIN +new_case() { + CASE="$TMP_ROOT/$1" + HOME_DIR="$CASE/home" + FAKEBIN="$CASE/fakebin" + mkdir -p "$HOME_DIR/config" "$FAKEBIN" "$CASE/user-home" + cat > "$FAKEBIN/quota-axi" <> '$CASE/reads' +[ -f "\$CLAUDE_CONFIG_DIR/quota.json" ] || exit 1 +cat "\$CLAUDE_CONFIG_DIR/quota.json" +[ ! -f "\$CLAUDE_CONFIG_DIR/exit-1" ] || exit 1 +SH + chmod +x "$FAKEBIN/quota-axi" +} + +# account [runway] [model-scope-spendPriority] [usableRunwaySeconds] +# A Claude root whose profile-only read reports these numbers. +account() { + local dir=$1 pct=$2 sp=$3 runway=${4:-through_reset} model_sp=${5:-} seconds=${6:-} + mkdir -p "$dir" + jq -n --argjson pct "$pct" --argjson sp "$sp" --arg runway "$runway" --arg model_sp "$model_sp" --arg seconds "$seconds" '{ + schemaVersion: 5, + providers: [{ + provider: "claude", + quotaSemantics: { + status: "known", + effectiveAvailability: ([ + {scope: "all_models", status: "known", effectivePercentRemaining: $pct, + runway: ({status: $runway} + (if $seconds == "" then {} else {usableRunwaySeconds: ($seconds | tonumber), projectionConfidence: "established"} end)), + selection: {spendPriority: $sp}} + ] + (if $model_sp == "" then [] else [ + {scope: "model:opus", status: "known", effectivePercentRemaining: 50, + runway: {status: "through_reset"}, selection: {spendPriority: ($model_sp | tonumber)}} + ] end)) + } + }] + }' > "$dir/quota.json" +} + +# rate_limited_account : a root whose read the vendor rate-limits, which +# quota-axi reports with exit 1 and a snapshot naming that state. +rate_limited_account() { + mkdir -p "$1" + jq -n '{ + schemaVersion: 5, + providers: [{ + provider: "claude", + state: {status: "rate_limited", error: "Claude quota endpoint rate limited"}, + quotaSemantics: {status: "unknown", effectiveAvailability: []} + }] + }' > "$1/quota.json" + : > "$1/exit-1" +} + +run_tool() { + env -i HOME="$CASE/user-home" PATH="$FAKEBIN:$PATH" FM_HOME="$HOME_DIR" \ + QUOTA_AXI_SNAPSHOT="$CASE/shared-fixture.json" "$TOOL" "$@" 2>&1 +} + +assert_no_choice() { + assert_not_contains "$1" "--account" "the tool must not print a chosen account" + assert_not_contains "$1" "status: " "the tool must not print a verdict status" + assert_not_contains "$1" "eligible" "the tool must not judge eligibility" +} + +test_two_accounts_print_their_own_rows() { + local out rc + new_case two + account "$CASE/a" 70 0.2 + account "$CASE/b" 60 0.5 + printf '%s\n%s\n' "$CASE/a" "$CASE/b" > "$HOME_DIR/config/claude-accounts" + out=$(run_tool); rc=$? + expect_code 0 "$rc" "measuring two declared accounts should succeed: $out" + assert_contains "$out" "row: $CASE/a root=$CASE/a scope=all_models status=known remaining=70% spendPriority=0.2 runway=through_reset" "account a's own row should be shown" + assert_contains "$out" "row: $CASE/b root=$CASE/b scope=all_models status=known remaining=60% spendPriority=0.5 runway=through_reset" "account b's own row should be shown" + assert_no_choice "$out" + assert_grep "$CASE/a unset --provider claude --profile-only --json" "$CASE/reads" "account a should be read in isolation under its own root" + assert_grep "$CASE/b unset --provider claude --profile-only --json" "$CASE/reads" "account b should be read in isolation under its own root" + pass "each declared account prints its own quota row, read under its own root" +} + +test_the_model_scope_is_printed() { + local out + new_case model + account "$CASE/a" 70 0.2 through_reset 0.9 + printf '%s\n' "$CASE/a" > "$HOME_DIR/config/claude-accounts" + out=$(run_tool --model opus) + assert_contains "$out" "row: $CASE/a root=$CASE/a scope=all_models status=known remaining=70% spendPriority=0.2" "the all_models scope applies to the model" + assert_contains "$out" "row: $CASE/a root=$CASE/a scope=model:opus status=known remaining=50% spendPriority=0.9" "the model scope should be printed" + out=$(run_tool) + assert_not_contains "$out" "scope=model:opus" "a model scope does not apply without --model" + assert_no_choice "$out" + pass "a model-specific scope is printed only for that model" +} + +test_exhausted_and_unreadable_accounts_print_facts() { + local out + new_case gates + account "$CASE/spent" 0 0.9 + account "$CASE/dry" 40 0.8 exhausted_now + mkdir -p "$CASE/unread" + printf '%s\n' "$CASE/spent" "$CASE/dry" "$CASE/unread" > "$HOME_DIR/config/claude-accounts" + out=$(run_tool) + assert_contains "$out" "row: $CASE/spent root=$CASE/spent scope=all_models status=known remaining=0% spendPriority=0.9 runway=through_reset" "a 0% account prints its facts" + assert_contains "$out" "row: $CASE/dry root=$CASE/dry scope=all_models status=known remaining=40% spendPriority=0.8 runway=exhausted_now" "an exhausted account prints its runway" + assert_contains "$out" "row: $CASE/unread root=$CASE/unread uncertainty: quota-axi could not read this account" "an unreadable account is disclosed uncertainty" + assert_no_choice "$out" + pass "exhausted, 0%, and unreadable accounts print facts and uncertainty without a verdict" +} + +test_projected_runway_prints_its_seconds() { + local out + new_case runway + account "$CASE/long" 80 0.4 projected_exhaustion "" 241920 + account "$CASE/short" 30 0.9 projected_exhaustion "" 2700 + account "$CASE/unknown" 50 0.5 projected_exhaustion + printf '%s\n' "$CASE/long" "$CASE/short" "$CASE/unknown" > "$HOME_DIR/config/claude-accounts" + out=$(run_tool) + assert_contains "$out" "row: $CASE/long root=$CASE/long scope=all_models status=known remaining=80% spendPriority=0.4 runway=projected_exhaustion usableRunwaySeconds=241920 confidence=established" \ + "a projected exhaustion should carry its runway seconds" + assert_contains "$out" "row: $CASE/short root=$CASE/short scope=all_models status=known remaining=30% spendPriority=0.9 runway=projected_exhaustion usableRunwaySeconds=2700 confidence=established" \ + "each account should carry its own runway seconds" + assert_contains "$out" "row: $CASE/unknown root=$CASE/unknown scope=all_models status=known remaining=50% spendPriority=0.5 runway=projected_exhaustion usableRunwaySeconds=-" \ + "a projection without seconds should show that it is missing" + assert_not_contains "$out" "runway=through_reset usableRunwaySeconds" "through_reset carries no runway seconds" + assert_no_choice "$out" + pass "a projected exhaustion prints each account's own runway seconds and confidence without a verdict" +} + +test_a_rate_limited_account_names_the_vendor_reason() { + local out + new_case rate-limited + rate_limited_account "$CASE/limited" + printf '%s\n' "$CASE/limited" > "$HOME_DIR/config/claude-accounts" + out=$(run_tool) + assert_contains "$out" "row: $CASE/limited root=$CASE/limited uncertainty: quota unknown (rate_limited: Claude quota endpoint rate limited)" \ + "a rate-limited read should keep quota-axi's own reason, not report an unreadable account" + assert_not_contains "$out" "could not read" "a rate-limited snapshot is not an unreadable root" + assert_no_choice "$out" + pass "a rate-limited account names the vendor's reason" +} + +test_ordinary_is_measured_from_the_default_root() { + local out + new_case ordinary + account "$CASE/user-home/.claude" 50 0.3 + printf 'ordinary\n' > "$HOME_DIR/config/claude-accounts" + out=$(run_tool) + assert_contains "$out" "row: ordinary root=$CASE/user-home/.claude scope=all_models status=known remaining=50% spendPriority=0.3" "the ordinary account should be measurable" + assert_no_choice "$out" + assert_grep "$CASE/user-home/.claude unset" "$CASE/reads" "ordinary should be read from ~/.claude" + pass "ordinary is measured from the default ~/.claude root" +} + +test_absent_or_malformed_lists_refuse() { + local out rc + new_case refuse + out=$(run_tool); rc=$? + expect_code 2 "$rc" "an absent list must refuse" + assert_contains "$out" "declares no config/claude-accounts" "the refusal should name the missing list" + printf 'relative\n' > "$HOME_DIR/config/claude-accounts" + out=$(run_tool); rc=$? + expect_code 2 "$rc" "a malformed list must refuse" + assert_contains "$out" "config/claude-accounts must hold one account per line" "the refusal should name the format" + assert_absent "$CASE/reads" "a refused list must not read any quota" + pass "an absent or malformed list refuses before any quota read" +} + +test_two_accounts_print_their_own_rows +test_the_model_scope_is_printed +test_exhausted_and_unreadable_accounts_print_facts +test_projected_runway_prints_its_seconds +test_a_rate_limited_account_names_the_vendor_reason +test_ordinary_is_measured_from_the_default_root +test_absent_or_malformed_lists_refuse + +echo "# all fm-claude-account-quota tests passed" diff --git a/tests/fm-control-relaunch.test.sh b/tests/fm-control-relaunch.test.sh index 878c415cb45..59df9b9ec5d 100755 --- a/tests/fm-control-relaunch.test.sh +++ b/tests/fm-control-relaunch.test.sh @@ -997,6 +997,91 @@ test_worker_account_pin_follows_the_relaunch() { pass "fm-control relaunch: the replacement follows the home's current worker account pin" } +# add_listed_task : a live Claude ship +# recorded on in a home declaring two signed-in accounts, +# first and second, plus a signed-out one. +add_listed_task() { + local dir=$1 id=$2 recorded=$3 + add_ship_task "$dir" "$id" claude + make_claude_auth_stub "$dir" + mkdir -p "$dir/home/config" "$dir/first" "$dir/second" "$dir/signed-out" + : > "$dir/first/.credentials.json" + : > "$dir/second/.credentials.json" + printf '%s\n' "$dir/first" "$dir/second" "$dir/signed-out" > "$dir/home/config/claude-accounts" + [ -z "$recorded" ] || echo "account=$recorded" >> "$dir/home/state/$id.meta" +} + +test_account_list_relaunch_reuses_the_recorded_account() { + local dir out rc id=rl-list + dir=$(new_case list-reuse "$id") + add_listed_task "$dir" "$id" "$dir/first" + out=$(run_control "$dir" "$id" relaunch --note "same account"); rc=$? + expect_code 0 "$rc" "a relaunch under a list should reuse the recorded account"$'\n'"$out" + [ "$(meta_field "$dir" "$id" account)" = "$dir/first" ] || fail "the relaunched record should keep the recorded account" + assert_contains "$(cat "$dir/fake/literal")" "CLAUDE_CONFIG_DIR='$dir/first'" \ + "the replacement should launch under the recorded account" + : > "$dir/fake/literal" + printf 'zsh' > "$dir/fake/command" + out=$(run_spawn "$dir" "$id" --relaunch); rc=$? + expect_code 0 "$rc" "a direct fm-spawn --relaunch under a list should reuse the recorded account"$'\n'"$out" + assert_contains "$out" "account=$dir/first" "the direct relaunch should report the recorded account" + pass "fm-control relaunch: a declared account list keeps the account the task records" +} + +test_account_list_relaunch_moves_only_on_explicit_account() { + local dir out rc id=rl-list-move + dir=$(new_case list-move "$id") + add_listed_task "$dir" "$id" "$dir/first" + out=$(run_control "$dir" "$id" relaunch --account "$dir/second" --note "first is exhausted"); rc=$? + expect_code 0 "$rc" "an explicit --account relaunch should move the task"$'\n'"$out" + [ "$(meta_field "$dir" "$id" account)" = "$dir/second" ] || fail "the relaunched record should name the new account" + assert_contains "$(cat "$dir/fake/literal")" "CLAUDE_CONFIG_DIR='$dir/second'" \ + "the replacement should launch under the explicitly chosen account" + : > "$dir/fake/literal" + out=$(run_control "$dir" "$id" relaunch --note "stay"); rc=$? + expect_code 0 "$rc" "a later plain relaunch should succeed"$'\n'"$out" + [ "$(meta_field "$dir" "$id" account)" = "$dir/second" ] || fail "a later relaunch should keep the moved account" + pass "fm-control relaunch: only an explicit --account moves a task to another declared account" +} + +test_account_list_relaunch_refusals_happen_before_stop() { + local dir out rc id=rl-list-refuse case_name recorded flag needle + for case_name in undeclared newline signed-out unrecorded removed wrong-harness; do + dir=$(new_case "list-refuse-$case_name" "$id") + recorded="$dir/first" + flag=() + case "$case_name" in + undeclared) + flag=(--account "$dir/elsewhere") + needle="account '$dir/elsewhere' is not declared in config/claude-accounts" ;; + newline) + flag=(--account "$dir/elsewhere"$'\n'"$dir/second") + needle="--account must name one config/claude-accounts entry exactly, with no control characters" ;; + signed-out) + flag=(--account "$dir/signed-out") + needle="config/claude-accounts pins Claude workers to $dir/signed-out, which is not signed in" ;; + unrecorded) + recorded= + needle="must name one with --account" ;; + removed) + recorded="$dir/retired" + needle="account '$dir/retired' is not declared in config/claude-accounts" ;; + wrong-harness) + flag=(--harness codex --account "$dir/second") + needle="applies to Claude workers only, not codex" ;; + esac + add_listed_task "$dir" "$id" "$recorded" + cp "$dir/home/state/$id.meta" "$dir/meta-before" + out=$(run_control "$dir" "$id" relaunch ${flag[@]+"${flag[@]}"} --note "refuse $case_name"); rc=$? + expect_code 1 "$rc" "the $case_name relaunch must refuse"$'\n'"$out" + assert_contains "$out" "$needle" "the $case_name refusal should say why" + [ "$(cat "$dir/fake/command")" = claude ] || fail "the $case_name refusal must happen before the running agent stops" + [ ! -s "$dir/fake/literal" ] || fail "the $case_name refusal must send no lifecycle input" + cmp -s "$dir/meta-before" "$dir/home/state/$id.meta" || fail "the $case_name refusal must leave the task record untouched" + done + pass "fm-control relaunch: undeclared, newline-split, signed-out, unrecorded, retired, and wrong-runner accounts refuse before the old agent stops" +} + test_secondmate_account_pin_follows_relaunch_and_refuses_before_stop() { local dir out rc id=rl-sm-acct harness file variable pin for harness in claude pi; do @@ -3036,6 +3121,9 @@ test_same_harness_relaunch_keeps_the_profile_axes test_native_ultra_relaunch_preserves_profile_and_rejects_before_stop test_signed_out_worker_account_pin_refuses_before_stop test_worker_account_pin_follows_the_relaunch +test_account_list_relaunch_reuses_the_recorded_account +test_account_list_relaunch_moves_only_on_explicit_account +test_account_list_relaunch_refusals_happen_before_stop test_secondmate_account_pin_follows_relaunch_and_refuses_before_stop test_pi_exclude_tools_follow_the_relaunch test_exclude_tools_refusals_happen_before_the_agent_stops diff --git a/tests/fm-worker-account.test.sh b/tests/fm-worker-account.test.sh index 9f7fe94f216..ae545d9f188 100755 --- a/tests/fm-worker-account.test.sh +++ b/tests/fm-worker-account.test.sh @@ -485,9 +485,155 @@ test_remote_secondmate_account_override_refuses_locally() { pass "a remote route refuses a primary-side account override instead of silently ignoring it" } +test_remote_secondmate_refuses_account() { + local out rc id=acct-remote-flag + new_case remote-account-flag claude + signed_in_claude_root "$CASE/first" + declare_accounts "$CASE/first" + printf -- '- %s - Remote fixture (host: account-test.invalid; root: /srv/firstmate; home: /srv/mate; scope: tests; projects: none; added 2026-10-17)\n' \ + "$id" > "$HOME_DIR/data/secondmates.md" + out=$(fm_test_run_spawn "$HOME_DIR" "$WT" "$FAKEBIN" "$id" --secondmate --account "$CASE/first"); rc=$? + expect_code 1 "$rc" "--account on a remote secondmate must refuse" + assert_refused_before_launch "$id" "$out" "--account applies to ships and scouts" + assert_absent "$CASE/claude-checks" "a refused remote launch must not inspect a local login" + pass "a remote secondmate refuses --account instead of launching on the remote home's account" +} + +# declare_accounts ...: the home's config/claude-accounts list. +declare_accounts() { + printf '%s\n' "$@" > "$HOME_DIR/config/claude-accounts" +} + +test_no_account_list_keeps_today_and_refuses_account() { + local out rc id=acct-list-off + new_case list-off claude + signed_in_claude_root "$CASE/work" + out=$(spawn_ship "$id"); rc=$? + expect_code 0 "$rc" "a Claude spawn in a home without a list should succeed: $out" + assert_not_contains "$out" "account=" "a home without a list must not report an account" + assert_no_grep "account=" "$HOME_DIR/state/$id.meta" "a home without a list must not record an account" + assert_absent "$CASE/claude-checks" "a home without a list must not run a sign-in check" + run_pane + assert_grep "CLAUDE_CONFIG_DIR=$CASE/ambient-claude" "$CASE/claude-worker" \ + "a home without a list must keep forwarding the invoking process's own Claude root" + assert_grep "ANTHROPIC_API_KEY=ambient-pane-key" "$CASE/claude-worker" \ + "a home without a list must leave the pane's environment credentials alone" + out=$(spawn_ship "$id-flag" --account "$CASE/work"); rc=$? + expect_code 1 "$rc" "--account without a list must refuse" + assert_refused_before_launch "$id-flag" "$out" "--account '$CASE/work' needs config/claude-accounts, which this home does not declare" + printf '%s\n' "$CASE/work" > "$HOME_DIR/config/claude-account" + : > "$CASE/claude-checks" + out=$(spawn_ship "$id-pin"); rc=$? + expect_code 0 "$rc" "the single pin must keep working without a list: $out" + assert_contains "$out" "account=$CASE/work" "the single pin must still report its account" + pass "without config/claude-accounts the launch, the single pin, and the record are unchanged, and --account refuses" +} + +test_account_list_launches_the_named_entry() { + local out rc id=acct-list + new_case list claude + signed_in_claude_root "$CASE/first" + signed_in_claude_root "$CASE/second" + declare_accounts "$CASE/first" "$CASE/second" + out=$(spawn_ship "$id" --account "$CASE/second"); rc=$? + expect_code 0 "$rc" "a spawn naming a declared, signed-in account should succeed: $out" + assert_contains "$out" "account=$CASE/second" "the spawn line should name the chosen account" + assert_grep "account=$CASE/second" "$HOME_DIR/state/$id.meta" "the task record should carry the chosen account" + [ "$(cat "$CASE/claude-checks")" = "$CASE/second" ] \ + || fail "the sign-in check should ask about the chosen account only: $(cat "$CASE/claude-checks")" + assert_contains "$(cat "$CASE/second/.claude.json" 2>/dev/null)" "$WT" \ + "workspace trust should be registered in the chosen account's store" + assert_absent "$CASE/first/.claude.json" "the other declared account must not be touched" + run_pane + assert_grep "CLAUDE_CONFIG_DIR=$CASE/second" "$CASE/claude-worker" "the worker should run under the chosen account" + assert_grep "ANTHROPIC_API_KEY=unset" "$CASE/claude-worker" "an ambient API key must not outrank the chosen account" + assert_grep "CLAUDE_CODE_OAUTH_TOKEN=unset" "$CASE/claude-worker" "an ambient OAuth token must not outrank the chosen account" + pass "a declared account named with --account is checked, launched, and recorded like a pin" +} + +test_account_list_refusals() { + local out rc id=acct-list-bad n=0 body + new_case list-refusals claude + signed_in_claude_root "$CASE/first" + signed_in_claude_root "$CASE/second" + mkdir -p "$CASE/signed-out" + declare_accounts "$CASE/first" "$CASE/second" "$CASE/signed-out" ordinary + out=$(spawn_ship "$id-none"); rc=$? + expect_code 1 "$rc" "a Claude spawn without --account must refuse under a list" + assert_refused_before_launch "$id-none" "$out" "config/claude-accounts declares 4 Claude accounts, so a Claude ship or scout launch must name one with --account" + out=$(spawn_ship "$id-other" --account "$CASE/elsewhere"); rc=$? + expect_code 1 "$rc" "an undeclared account must refuse" + assert_refused_before_launch "$id-other" "$out" "account '$CASE/elsewhere' is not declared in config/claude-accounts" + signed_in_claude_root "$CASE/elsewhere"$'\n'"$CASE/first" + out=$(spawn_ship "$id-newline" --account "$CASE/elsewhere"$'\n'"$CASE/first"); rc=$? + expect_code 1 "$rc" "an account holding a newline must refuse even when one of its lines is declared" + assert_refused_before_launch "$id-newline" "$out" "--account must name one config/claude-accounts entry exactly, with no control characters" + [ ! -e "$CASE/claude-checks" ] || assert_no_grep "$CASE/elsewhere" "$CASE/claude-checks" "a newline account must be refused before its sign-in check" + out=$(spawn_ship "$id-out" --account "$CASE/signed-out"); rc=$? + expect_code 1 "$rc" "a signed-out declared account must refuse even with an ambient login and key" + assert_refused_before_launch "$id-out" "$out" "config/claude-accounts pins Claude workers to $CASE/signed-out, which is not signed in" + out=$(spawn_ship "$id-ordinary" --account ordinary); rc=$? + expect_code 1 "$rc" "a signed-out ordinary entry must refuse" + assert_refused_before_launch "$id-ordinary" "$out" "pins Claude workers to the ordinary account, which is not signed in" + out=$(spawn_ship "$id-codex" --harness codex --account "$CASE/first"); rc=$? + expect_code 1 "$rc" "--account on another runner must refuse" + assert_refused_before_launch "$id-codex" "$out" "applies to Claude workers only, not codex" + out=$(spawn_ship "$id-raw" --account "$CASE/first" --harness "CLAUDE_CONFIG_DIR=$CASE/second claude --print raw"); rc=$? + expect_code 1 "$rc" "a raw command overriding the chosen account must refuse" + assert_refused_before_launch "$id-raw" "$out" "the raw launch command sets CLAUDE_CONFIG_DIR" + printf '%s\n' "$CASE/first" > "$HOME_DIR/config/claude-account" + out=$(spawn_ship "$id-both" --account "$CASE/first"); rc=$? + expect_code 1 "$rc" "a list beside a single pin must refuse" + assert_refused_before_launch "$id-both" "$out" "config/claude-accounts and config/claude-account are both present" + rm "$HOME_DIR/config/claude-account" + for body in "$CASE/first"$'\n\n'"$CASE/second" "relative/root" "$CASE/first"$'\r' '' "$CASE/first"$'\n'"$CASE/first" "$CASE/first"$'\n'"$CASE/missing"; do + n=$((n + 1)) + printf '%s' "$body" > "$HOME_DIR/config/claude-accounts" + out=$(spawn_ship "$id-$n" --account "$CASE/first"); rc=$? + if [ "$n" = 6 ]; then + expect_code 0 "$rc" "a missing entry that is not chosen must not block another: $out" + out=$(spawn_ship "$id-$n-missing" --account "$CASE/missing"); rc=$? + expect_code 1 "$rc" "a missing chosen entry must refuse" + assert_refused_before_launch "$id-$n-missing" "$out" "config/claude-accounts must name readable, searchable existing directories" + continue + fi + expect_code 1 "$rc" "malformed list #$n must refuse" + assert_refused_before_launch "$id-$n" "$out" "config/claude-accounts" + done + rm "$HOME_DIR/config/claude-accounts" + mkdir "$HOME_DIR/config/claude-accounts" + out=$(spawn_ship "$id-dir" --account "$CASE/first"); rc=$? + expect_code 1 "$rc" "a directory in place of the list must refuse" + assert_refused_before_launch "$id-dir" "$out" "config/claude-accounts must be a readable regular file" + assert_no_grep "$CASE/second" "$CASE/claude-checks" "an account no launch chose must never be sign-in checked" + assert_absent "$CASE/claude-worker" "no refused launch may start Claude" + pass "a list refuses a missing, undeclared, signed-out, wrong-runner, raw-override, doubled, or malformed choice" +} + +test_account_list_secondmate_needs_its_own_pin() { + local out rc id=acct-list-sm + new_case list-secondmate claude + signed_in_claude_root "$CASE/first" + signed_in_claude_root "$CASE/mate" + declare_accounts "$CASE/first" + out=$(spawn_account_secondmate "$id"); rc=$? + expect_code 1 "$rc" "a secondmate without its own pin must refuse under a list: $out" + assert_refused_before_launch "$id" "$out" "secondmate $id needs its own pin in config/secondmate-accounts/$id/claude-account" + out=$(spawn_account_secondmate "$id" --account "$CASE/first"); rc=$? + expect_code 1 "$rc" "--account on a secondmate must refuse" + assert_refused_before_launch "$id" "$out" "--account applies to ships and scouts" + mkdir -p "$HOME_DIR/config/secondmate-accounts/$id" + printf '%s\n' "$CASE/mate" > "$HOME_DIR/config/secondmate-accounts/$id/claude-account" + out=$(spawn_account_secondmate "$id"); rc=$? + expect_code 0 "$rc" "a secondmate with its own pin should launch under a list: $out" + assert_contains "$out" "account=$CASE/mate" "the secondmate should launch on its own pin" + pass "a list never chooses a secondmate's account: it needs its own pin and refuses --account" +} + test_secondmate_account_override test_secondmate_account_refusals test_remote_secondmate_account_override_refuses_locally +test_remote_secondmate_refuses_account test_absent_pin_keeps_the_launch_unchanged test_claude_pin_selects_the_root_and_sheds_ambient_credentials test_claude_pin_refuses_a_signed_out_root_despite_an_ambient_login @@ -501,5 +647,9 @@ test_raw_claude_command_receives_the_pin test_raw_claude_account_override_refuses_under_a_pin test_raw_claude_account_override_is_kept_without_a_pin test_local_secondmate_reads_the_launching_home_pin +test_no_account_list_keeps_today_and_refuses_account +test_account_list_launches_the_named_entry +test_account_list_refusals +test_account_list_secondmate_needs_its_own_pin echo "# all fm-worker-account tests passed" From 8aa66fff48a50977bc00dba2398d6713b16c8654 Mon Sep 17 00:00:00 2001 From: c6aw <225476801+c6aw@users.noreply.github.com> Date: Tue, 3 Nov 2026 09:30:11 -0600 Subject: [PATCH 04/34] feat(branch-prompt): append an optional home include to the supervision branch prompt (#8118) * feat(branch-prompt): append an optional home include to the supervision branch prompt The headless supervision engine runs in safe mode and loads none of the home's hooks, CLAUDE.md, skills or plugins, so a home had no way to give the branch a home-specific rule. fm-branch-prompt.sh now appends the optional local config/branch-prompt-include.md verbatim as its last section, the same way config/brief-include.md extends worker briefs: absent or blank leaves the prompt byte-identical, and an unusable path stops the generator before it emits anything. * no-mistakes(review): Pin byte-stability re-run to a temp home --------- Co-authored-by: c-c6aw <225476801+c-c6aw@users.noreply.github.com> --- .../skills/operational-home-layout/SKILL.md | 1 + bin/fm-branch-prompt.sh | 36 ++++++++++++-- docs/configuration.md | 11 +++++ docs/supervision-host.md | 1 + tests/fm-branch-supervision.test.sh | 47 ++++++++++++++++++- 5 files changed, 91 insertions(+), 5 deletions(-) diff --git a/.agents/skills/operational-home-layout/SKILL.md b/.agents/skills/operational-home-layout/SKILL.md index ead74f00d92..bd3533b3bbe 100644 --- a/.agents/skills/operational-home-layout/SKILL.md +++ b/.agents/skills/operational-home-layout/SKILL.md @@ -50,6 +50,7 @@ config/rex-tint optional "off" (default when absent), "subtle", or "subtle-ligh config/trace-context optional presence flag enabling default-off native W3C trace-context propagation to spawned agents; LOCAL, gitignored; inherited by secondmate homes; see docs/configuration.md "Trace context propagation" and docs/trace-context.md config/lavish-axi-host optional one-line per-machine Lavish server address; LOCAL, gitignored, inherited by secondmate homes, and exported into every worker launch; see docs/configuration.md "Lavish server address" for opening versus polling config/brief-include.md optional standing worker instructions appended verbatim as the last section of every ship and scout scaffold; LOCAL, gitignored, and not inherited; keep its text out of `## Firstmate spec`; see docs/configuration.md "Home brief include" +config/branch-prompt-include.md optional standing home rules appended verbatim as the last section of the supervision branch prompt; LOCAL, gitignored, and not inherited; see docs/configuration.md "Home branch prompt include" config/herdr-lifecycle-spawn-guard optional presence flag opting this home into the default-off spawn refusal of a ship or scout brief that names a Herdr lifecycle command without the Herdr isolation contract; LOCAL, gitignored, and not inherited; see docs/configuration.md "Herdr lifecycle spawn guard" config/fleet-ledger optional presence flag opting this home in to the default-off fleet activity ledger state/fleet-ledger.jsonl that outside tools can follow; LOCAL, gitignored, and not inherited; see docs/fleet-ledger.md config/firstmate-role optional LOCAL, gitignored firstmate-repository publication role; see docs/configuration.md "Firstmate role" for operator opt-in and secondmate inheritance diff --git a/bin/fm-branch-prompt.sh b/bin/fm-branch-prompt.sh index 32bacc634ec..c2242fb9e35 100755 --- a/bin/fm-branch-prompt.sh +++ b/bin/fm-branch-prompt.sh @@ -6,10 +6,11 @@ # PREFIX-STABILITY CONTRACT (this header is the one owner). The branch's # provider prompt cache only pays off while the request prefix stays # byte-identical, so this generator must be a pure function of this repo's -# tracked files: fixed rules text plus the verbatim tracked policy skills. -# NO timestamps, NO fleet snapshot, NO per-wake content, NO home-specific -# paths, NO environment reads. Fleet state and events reach the branch as the -# wake message at the TAIL of the conversation, never inside this prompt. The +# tracked files (plus the one home include described below): fixed rules text +# plus the verbatim tracked policy skills. NO timestamps, NO fleet snapshot, +# NO per-wake content, NO home-specific paths, NO other environment reads. +# Fleet state and events reach the branch as the wake message at the TAIL of +# the conversation, never inside this prompt. The # same rule extends to the branch session's tool set: each host offers the # same tools in the same order on every request. The text stays host-neutral, # so one prompt serves the Pi branch and the supervision host; each wake names @@ -22,12 +23,35 @@ # version". tests/fm-branch-supervision.test.sh holds this to byte-identical # output across runs, environments, and fleet states. # +# The one sanctioned home input is the optional local config/branch-prompt- +# include.md under the active home (FM_CONFIG_OVERRIDE, else $FM_HOME/config), +# mirroring config/brief-include.md in bin/fm-brief.sh: its text is appended +# verbatim as the last section, "# Home prompt additions", which defers to +# every other section. It is read whole once per prompt build and lands after +# the tracked text, so the prefix stays byte-stable for that home and changes +# only when the file does. An absent or blank file leaves the prompt byte- +# identical; a present path that is not a readable regular file stops the +# generator before anything is written to stdout. The branch's headless engine +# loads none of the home's own instructions, so this file is how a home gives +# the branch a home-specific rule. +# # Usage: fm-branch-prompt.sh (stdout is the complete system prompt) set -eu SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" FM_TRACKED_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +# Read before anything is emitted, so an unusable file never yields a partial prompt. +INCLUDE_FILE="${FM_CONFIG_OVERRIDE:-${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_TRACKED_ROOT}}/config}/branch-prompt-include.md" +INCLUDE_BODY= +if [ -e "$INCLUDE_FILE" ] || [ -L "$INCLUDE_FILE" ]; then + { [ -f "$INCLUDE_FILE" ] && INCLUDE_BODY=$(cat "$INCLUDE_FILE" 2>/dev/null); } || { + echo "error: $INCLUDE_FILE must be a readable regular file" >&2 + exit 1 + } + [ -n "$(printf '%s' "$INCLUDE_BODY" | tr -d '[:space:]')" ] || INCLUDE_BODY= +fi + cat <<'PROMPT' You are the SUPERVISION BRANCH of firstmate: the persistent second conversation beside the captain-facing MAIN conversation of this firstmate home. Your whole job is fleet supervision: absorb every fleet event, handle it with real tools, and report each outcome with a routine-or-captain verdict. @@ -171,3 +195,7 @@ cat <<'PROMPT' PROMPT cat "$FM_TRACKED_ROOT/.agents/skills/captain-hold-lifecycle/SKILL.md" +[ -z "$INCLUDE_BODY" ] || printf '\n%s\n%s\n%s\n' \ + '# Home prompt additions' \ + "These are this home's standing additions; every other section of this prompt takes precedence over anything here that conflicts." \ + "$INCLUDE_BODY" diff --git a/docs/configuration.md b/docs/configuration.md index 7859af75d29..ebd7f6a2be0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1653,6 +1653,17 @@ The text is static and never executed or expanded; secondmate charters never tak `bin/fm-brief.sh`'s header owns the placement rule and its safety argument. +## Home branch prompt include (config/branch-prompt-include.md) + +The optional local, gitignored `config/branch-prompt-include.md` adds standing home rules to the supervision branch's system prompt, the way `config/brief-include.md` extends worker briefs. +The branch's headless engine loads none of the home's own hooks, `CLAUDE.md`, skills, or plugins, so this file is how a home gives the branch a home-specific rule. +When the file exists, `bin/fm-branch-prompt.sh` appends its text verbatim as the prompt's last section, `# Home prompt additions`, which defers to every other section of the prompt. + +An absent or blank file leaves the prompt byte-identical, while a present path that is not a readable regular file stops the generator before it emits anything, so the branch does not start. +The text is static and never executed or expanded, and an edit takes effect when the branch next builds its prompt for a new conversation. + +`bin/fm-branch-prompt.sh`'s header owns the placement rule and how it keeps the prompt cache stable. + ## Herdr lifecycle spawn guard (config/herdr-lifecycle-spawn-guard) The optional local, gitignored `config/herdr-lifecycle-spawn-guard` presence flag opts this home into refusing, at spawn, a ship or scout brief that drives Herdr lifecycle without the Herdr isolation contract. diff --git a/docs/supervision-host.md b/docs/supervision-host.md index 4696f081c00..5697cd9250c 100644 --- a/docs/supervision-host.md +++ b/docs/supervision-host.md @@ -398,6 +398,7 @@ Today the only verified engine is Claude's print mode, measured on Claude Code 2 - `--safe-mode` loads none of the home's hooks, `CLAUDE.md`, skills, plugins, or MCP servers. So the engine can never fire the home's own Stop or SessionStart hooks. + A home's own rules reach the engine only through the optional `config/branch-prompt-include.md` ([configuration](configuration.md#home-branch-prompt-include-configbranch-prompt-includemd)). - `--bare` is unusable because it never reads claude.ai OAuth. - From inside the engine's shell the primary is not in the harness ancestry, so the engine can never act as the session-lock owner. diff --git a/tests/fm-branch-supervision.test.sh b/tests/fm-branch-supervision.test.sh index 947af7d7354..87e1ed80982 100644 --- a/tests/fm-branch-supervision.test.sh +++ b/tests/fm-branch-supervision.test.sh @@ -31,7 +31,7 @@ test_branch_prompt_is_byte_stable_and_above_cache_floor() { out_b=$(cd / && FM_HOME="$home_b" TZ=Australia/Eucla "$ROOT/bin/fm-branch-prompt.sh") \ || fail "branch prompt generator failed for home B" sleep 1 - out_c=$("$ROOT/bin/fm-branch-prompt.sh") || fail "branch prompt generator failed on re-run" + out_c=$(FM_HOME="$home_a" "$ROOT/bin/fm-branch-prompt.sh") || fail "branch prompt generator failed on re-run" [ "$out_a" = "$out_b" ] || fail "branch prompt differs across homes/cwd/timezone: prefix stability broken" [ "$out_a" = "$out_c" ] || fail "branch prompt differs across runs at different times: prefix stability broken" @@ -72,6 +72,50 @@ test_branch_prompt_is_byte_stable_and_above_cache_floor() { pass "branch prompt is byte-stable across homes, cwd, timezone, and time, above the cache floor" } +# A home adds its own rules through config/branch-prompt-include.md: absent or +# blank leaves the prompt byte-identical, present text lands verbatim as the +# last section, and an unusable path refuses with no prompt on stdout. +test_branch_prompt_home_include_is_appended_last() { + local home config base out rc last_heading + home="$TMP_ROOT/prompt-include-home" + config="$home/config" + mkdir -p "$config" + base=$(FM_HOME="$TMP_ROOT/prompt-include-none" "$ROOT/bin/fm-branch-prompt.sh") || fail "branch prompt failed without a home" + + out=$(FM_HOME="$home" "$ROOT/bin/fm-branch-prompt.sh") || fail "branch prompt failed without an include" + [ "$out" = "$base" ] || fail "an absent include changed the branch prompt" + printf ' \n\n' > "$config/branch-prompt-include.md" + out=$(FM_HOME="$home" "$ROOT/bin/fm-branch-prompt.sh") || fail "branch prompt failed with a blank include" + [ "$out" = "$base" ] || fail "a blank include changed the branch prompt" + + # shellcheck disable=SC2016 # The include is literal text and must never expand. + printf '%s\n' 'Relaunch workers with `house-tool $(id)`.' > "$config/branch-prompt-include.md" + out=$(FM_HOME="$home" "$ROOT/bin/fm-branch-prompt.sh") || fail "branch prompt failed with an include" + case "$out" in + "$base"*) ;; + *) fail "the include did not leave the tracked prompt as an unchanged prefix" ;; + esac + # shellcheck disable=SC2016 # Literal include text. + assert_contains "$out" 'Relaunch workers with `house-tool $(id)`.' "branch prompt did not carry the include verbatim" + assert_contains "$out" "every other section of this prompt takes precedence" "include section lost its precedence line" + last_heading=$(printf '%s\n' "$out" | grep '^# ' | tail -n 1) + [ "$last_heading" = '# Home prompt additions' ] || fail "include was not the last section (got: $last_heading)" + [ "$(FM_HOME="$home" "$ROOT/bin/fm-branch-prompt.sh")" = "$out" ] || fail "branch prompt with an include is not byte-stable across runs" + + out=$(FM_HOME="$home" FM_CONFIG_OVERRIDE="$TMP_ROOT/prompt-include-empty-config" "$ROOT/bin/fm-branch-prompt.sh") \ + || fail "branch prompt failed under FM_CONFIG_OVERRIDE" + [ "$out" = "$base" ] || fail "FM_CONFIG_OVERRIDE did not select the config directory" + + rm -f "$config/branch-prompt-include.md" + mkdir "$config/branch-prompt-include.md" + out=$(FM_HOME="$home" "$ROOT/bin/fm-branch-prompt.sh" 2>/dev/null); rc=$? + expect_code 1 "$rc" "an unusable include path must stop the branch prompt" + [ -z "$out" ] || fail "an unusable include still emitted a partial prompt" + out=$(FM_HOME="$home" "$ROOT/bin/fm-branch-prompt.sh" 2>&1 >/dev/null) + assert_contains "$out" "branch-prompt-include.md must be a readable regular file" "unusable include refusal did not name the file" + pass "fm-branch-prompt.sh: the home prompt include lands last, verbatim, and refuses an unusable path" +} + test_branch_prompt_routes_completed_scouts_through_guarded_cleanup() { local prompt skill prompt=$(bash "$ROOT/bin/fm-branch-prompt.sh") || fail "branch prompt generator failed" @@ -1612,6 +1656,7 @@ WRAPPER } test_branch_prompt_is_byte_stable_and_above_cache_floor +test_branch_prompt_home_include_is_appended_last test_branch_prompt_routes_completed_scouts_through_guarded_cleanup test_outcome_store_is_append_only_with_cursor_reads test_outcome_append_keeps_a_bounded_display_tail From 87f26ac7af8fabc279d4e28079512cede7f15603 Mon Sep 17 00:00:00 2001 From: jaig-in Date: Tue, 3 Nov 2026 10:30:30 -0500 Subject: [PATCH 05/34] fix(bin): bind live-lab tmux calls to explicit sockets so cleanup cannot kill the default server (#6422) * fix(bin): bind live-lab tmux calls to explicit sockets so cleanup cannot kill the default server tmux honours TMUX_TMPDIR only while that directory exists; once it is gone, tmux silently resolves the default socket under /tmp/tmux-. The live lab and its tests addressed their private server through TMUX_TMPDIR alone, so a cleanup aimed at a removed lab directory ran kill-server against the user's own default server and ended every session on it. Every tmux call in bin/fm-live-lab.sh and its tests now names the lab socket with tmux -S, and every kill-server runs only while that socket exists. The lab's stub spawns, the fm-gate-refuse lab-socket test, and the lab cleanup guidance in fm-brief.sh and fm-lab-home.sh follow the same rule. tests/lib.sh gains fm_tmux_isolation_gate: a suite that starts or kills tmux servers runs only when no live server answers in the default socket directory (a private /tmp, or a disposable CI runner), skips with the isolation it needs otherwise, and fails instead of skipping under CI. The live-lab suites open with it. tests/fm-live-lab-isolation.test.sh covers the gate both ways and proves that pane, say, check and down aimed at a missing lab directory leave a decoy server on the default socket alive. * no-mistakes(review): Run live-lab decoy only in private /tmp; drop gate bypasses * no-mistakes(review): Drop inherited temp dirs inside the isolation namespace * no-mistakes(document): Clarify live-lab down contract for socket-guarded server kill * test(live-lab): bound the isolation decoy cleanup and report a decoy it cannot stop * no-mistakes(review): Run bounded decoy cleanup tests on host; bound kill-server * no-mistakes(document): Reflow stop_decoy doc comment in isolation test * fix(tests): treat an exited unreaped decoy as gone in isolation cleanup * no-mistakes(review): Make pid_running fail closed when ps errors * no-mistakes(document): Document pid_running fail-closed ps behavior * no-mistakes(review): add isolation suite serial hint; lane saturated, guard still fails * no-mistakes(review): shorten isolation cleanup polls; hint 3482ms, guard passes * test(tests): bound the tmux isolation gate's server probe fm_tmux_isolation_gate asked each socket's server for its sessions with no deadline, so a stopped or stuck user tmux server held the gate, and with no per-script deadline in the runner, the whole run, before it could skip. Each probe now runs under fm_run_timed for FM_TMUX_ISOLATION_PROBE_SECONDS (default 5), and a server that does not answer in time counts as live: the gate skips and names the silent socket and the deadline. * test(tests): skip the live-lab decoy cases for a checkout under /tmp The isolation suite re-runs itself under unshare -Urm after mounting a fresh tmpfs on /tmp, so a checkout under /tmp lost the script to that mount: the namespace check passed and the re-run failed on a missing file instead of running its decoy cases. The suite now resolves its own physical path, skips the decoy cases with a reason before mounting when that path is under /tmp, and re-runs the physical path otherwise. A copy of the suite under /tmp pins the skip. * test(tests): run only the decoy preflight in the /tmp copy of the isolation suite The copy that pins the /tmp skip re-ran every host case, doubling the suite's runtime and its exposure to their timing bounds. It now goes straight to the decoy preflight it exists to exercise. * test(bin): refresh the live-lab isolation suite serial hint The probe-deadline and /tmp-checkout cases lengthen the suite from about 3.5 s to 4.3-6.5 s in a private /tmp; the provisional hint now carries the slowest of six new samples. --- bin/fm-brief.sh | 2 +- bin/fm-lab-home.sh | 5 +- bin/fm-live-lab.sh | 40 +++- bin/fm-test-run.sh | 1 + docs/fm-test-portable-shards.md | 1 + tests/fm-gate-refuse.test.sh | 10 +- tests/fm-live-lab-isolation.test.sh | 299 ++++++++++++++++++++++++++++ tests/fm-live-lab-up-mate.test.sh | 9 +- tests/fm-live-lab.test.sh | 22 +- tests/lib.sh | 42 ++++ 10 files changed, 412 insertions(+), 19 deletions(-) create mode 100755 tests/fm-live-lab-isolation.test.sh diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh index c170555d7eb..b753926423b 100755 --- a/bin/fm-brief.sh +++ b/bin/fm-brief.sh @@ -616,7 +616,7 @@ HERDR_SECTION=$(printf '%s\n' \ '' \ 'For tmux-based lab primaries, `bin/fm-lab-home.sh` owns the short private socket directory; do not place `TMUX_TMPDIR` under the lab home or worktree.' \ 'Use `LAB_HOME_HELPER='"$(shell_quote "$FM_ROOT/bin/fm-lab-home.sh")"'`, then `LAB_TMUX_DIR=$("$LAB_HOME_HELPER" tmux-dir "$FM_HOME")` and launch tmux with `TMUX_TMPDIR="$LAB_TMUX_DIR"`.' \ -'Your single EXIT cleanup trap must kill only the server addressed through that `TMUX_TMPDIR`, call `"$LAB_HOME_HELPER" teardown "$FM_HOME"`, and call the Herdr teardown below; do not install a second trap that replaces either cleanup.' \ +'Your single EXIT cleanup trap must kill only that server, by its explicit socket (`tmux -S "$LAB_TMUX_DIR/tmux-$(id -u)/" kill-server`) and only while that socket exists, never through `TMUX_TMPDIR` alone, which silently falls back to the default tmux server once the directory is gone; it must also call `"$LAB_HOME_HELPER" teardown "$FM_HOME"` and the Herdr teardown below; do not install a second trap that replaces either cleanup.' \ '' \ '1. Set `HERDR_LAB_HELPER='"$HERDR_LAB_HELPER"'` and generate the session name with `HERDR_LAB_SESSION=$("$HERDR_LAB_HELPER" name '"$ID"')`.' \ ' Install the combined EXIT cleanup before provisioning, then provision only with `"$HERDR_LAB_HELPER" provision "$HERDR_LAB_SESSION"`.' \ diff --git a/bin/fm-lab-home.sh b/bin/fm-lab-home.sh index 08edd772cf0..c74a5717b62 100755 --- a/bin/fm-lab-home.sh +++ b/bin/fm-lab-home.sh @@ -17,7 +17,10 @@ # FM_HOME=; bin/fm-gate-refuse-lib.sh owns permitted supervision overrides. # tmux-dir is the single owner of the short private socket directory: callers # use TMUX_TMPDIR= and call teardown from their cleanup trap after -# killing only the server addressed through that directory. +# killing only their own server by its explicit socket, +# tmux -S /tmux-/, and only while that socket exists: +# TMUX_TMPDIR alone silently falls back to /tmp/tmux- once the directory +# is gone, which reaches the user's default server. set -u SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" diff --git a/bin/fm-live-lab.sh b/bin/fm-live-lab.sh index 65462181a02..c096997b989 100755 --- a/bin/fm-live-lab.sh +++ b/bin/fm-live-lab.sh @@ -96,8 +96,13 @@ # worker --worker: its current crew state is paused on the gate. # treehouse ~/.treehouse gained no entry since up began. # +# Every tmux call names the lab's socket explicitly (tmux -S), never through +# TMUX_TMPDIR alone, so no lab command can reach another tmux server even after +# the private tmux directory is gone. +# # down refuses any path without the lab record up writes. It kills only the -# lab's recorded private tmux server and launch pane PIDs, and their descendants; +# lab's recorded launch pane PIDs and their descendants, and the lab's private +# tmux server, which it touches only while that server's socket exists; # runs bin/fm-lab-home.sh teardown; removes the task temp and launch dirs the # lab's spawns kept under /tmp, including a failed spawn's; removes every # project entry at or under from the recorded Claude store, following @@ -159,12 +164,34 @@ load_lab() { # : refuse anything up did not build, then load its record TREEHOUSE_DIR=$(rec_get "$ROOT" treehouse_dir) } -lab_tmux() { +# lab_socket: the explicit path of the lab's tmux socket, the one a lab process +# reaches through TMUX_TMPDIR=$TMUX_DIR. Every tmux call this script makes names +# it with -S, never TMUX_TMPDIR alone: tmux uses TMUX_TMPDIR only while that +# directory exists and otherwise silently falls back to /tmp/tmux-, where a +# lab command would reach the user's own default server. +lab_socket() { [ -n "${TMUX_DIR:-}" ] || return 1 - env -u TMUX TMUX_TMPDIR="$TMUX_DIR" tmux "$@" + printf '%s/tmux-%s/default\n' "$TMUX_DIR" "$(id -u)" +} + +lab_tmux() { + local socket + socket=$(lab_socket) || return 1 + env -u TMUX tmux -S "$socket" "$@" } -# The empty-environment base every lab process starts from. +# lab_kill_server: stop the lab's tmux server, and do nothing at all when its +# socket does not exist. +lab_kill_server() { + local socket + socket=$(lab_socket) || return 0 + [ -S "$socket" ] || return 0 + lab_tmux kill-server 2>/dev/null || true +} + +# The empty-environment base every lab process starts from. TMUX_TMPDIR here is +# how the lab's own firstmate backend finds the lab server; those processes run +# only while that server, and so its directory, exists. lab_env_base() { printf '%s\n' "HOME=$HOME" "USER=${USER:-$(id -un)}" "LOGNAME=${USER:-$(id -un)}" \ "PATH=$PATH" "SHELL=${SHELL:-/bin/zsh}" "TERM=xterm-256color" "LANG=${LANG:-en_US.UTF-8}" \ @@ -541,7 +568,8 @@ cmd_up() { TMUX_DIR=$("$LAB_HOME_HELPER" tmux-dir "$LAB") || die "cannot create the private tmux directory" echo "tmux_dir=$TMUX_DIR" >> "$ROOT/$RECORD_NAME" - lab_run tmux -f /dev/null new-session -d -s firstmate -n lab -x 220 -y 60 -c "$ROOT" || die "cannot start the lab tmux server" + mkdir -m 700 "$TMUX_DIR/tmux-$(id -u)" || die "cannot create the lab tmux socket directory" + lab_run tmux -S "$(lab_socket)" -f /dev/null new-session -d -s firstmate -n lab -x 220 -y 60 -c "$ROOT" || die "cannot start the lab tmux server" record_launch_pid "$(lab_tmux display-message -p '#{pid}')" if [ "$mate" = yes ]; then @@ -757,7 +785,7 @@ cmd_down() { case "$pgid" in ''|0|1|*[!0-9]*) continue ;; esac [ "$pgid" = "$own_group" ] || [ "$pgid" = "$caller_group" ] || groups+="$pgid " done - lab_tmux kill-server 2>/dev/null || true + lab_kill_server refresh_pairs survivors=$(live_pids "$pairs") if [ -n "$survivors" ]; then diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh index ad5779ad0f0..cddcbf9f93a 100755 --- a/bin/fm-test-run.sh +++ b/bin/fm-test-run.sh @@ -829,6 +829,7 @@ tests/fm-kimi-trust-prompt-live-e2e.test.sh 60 tests/fm-launch-prompt-signals-live-e2e.test.sh 50 tests/fm-lint-workflows.test.sh 872 tests/fm-live-gate.test.sh 7452 +tests/fm-live-lab-isolation.test.sh 6459 tests/fm-live-lab-up-mate.test.sh 17363 tests/fm-live-lab.test.sh 79639 tests/fm-mail-check.test.sh 7524 diff --git a/docs/fm-test-portable-shards.md b/docs/fm-test-portable-shards.md index 9cefd369b0f..e7560d1d824 100644 --- a/docs/fm-test-portable-shards.md +++ b/docs/fm-test-portable-shards.md @@ -31,6 +31,7 @@ The 2026-10-26 `tests/fm-test-tap-verify.test.sh` serial hint is a provisional l The 2026-10-27 read-repetition suites carry provisional Linux x86_64 local runner maxima: 602 ms for `tests/fm-read-repetition.test.sh` (six successful samples, 528-602 ms) and 1110 ms for `tests/fm-read-repetition-live.test.sh` (five successful samples, 949-1110 ms). The live samples exercised installed Pi 1.4.0 RPC without capability skips; they are not CI timing evidence or timings for unavailable harnesses. Both suites retain serial placement and full coverage; replace these provisional hints with Ubuntu timing-artifact maxima at the next CI refresh. +The 2026-10-29 `tests/fm-live-lab-isolation.test.sh` serial hint is a provisional local measurement of 6459 ms, the slowest of six `bin/fm-test-run.sh` samples (4308-6459 ms) taken inside a private `unshare -Urm` /tmp on this Linux host, until the next CI refresh replaces it with an Ubuntu timing-artifact maximum. The 2026-10-27 `tests/fm-codex-stop-park.test.sh` serial hint is a provisional local measurement of 35000 ms, above the slowest of the `bin/fm-test-run.sh` samples (20170-34700 ms) on a macOS arm64 host, until the next CI refresh replaces it with an Ubuntu timing-artifact maximum. The 2026-10-28 Antigravity primary tests carry provisional serial hints - 45000 ms for `tests/fm-agy-primary.test.sh` and the 75 ms live-guard skip for `tests/fm-agy-primary-live-e2e.test.sh` - until the next CI refresh replaces them with Ubuntu timing-artifact maxima. The wedge-cap suite carries the Ubuntu measurements from CI run [39597689178](https://github.com/kunchenguid/firstmate/actions/runs/39597689178) - 374225 ms for `tests/fm-watch-wedge-cap.test.sh` and the 74 ms live-guard skip for `tests/fm-watch-wedge-cap-live.test.sh` - in place of the provisional local measurements the suite first carried (1003000 ms and the 155 ms skip), which overstated the CI cost of both. diff --git a/tests/fm-gate-refuse.test.sh b/tests/fm-gate-refuse.test.sh index 85ddb6f2d3b..b5f9eeca212 100755 --- a/tests/fm-gate-refuse.test.sh +++ b/tests/fm-gate-refuse.test.sh @@ -243,7 +243,9 @@ test_lab_home_private_tmux_socket_survives_deep_paths() { [ "${socket_dir#/tmp/fml.}" != "$socket_dir" ] || fail "socket directory is not under the short /tmp/fml prefix" cleanup_deep_lab() { - env TMUX_TMPDIR="$socket_dir" "$real_tmux" -L fm-lab kill-server >/dev/null 2>&1 || true + # The explicit socket, only while it exists: TMUX_TMPDIR alone falls back + # to /tmp/tmux- once the private directory is gone. + [ ! -S "$socket_path" ] || "$real_tmux" -S "$socket_path" kill-server >/dev/null 2>&1 || true "$LABHOME" teardown "$lab" >/dev/null 2>&1 || true fm_test_cleanup } @@ -256,13 +258,13 @@ test_lab_home_private_tmux_socket_survives_deep_paths() { local attempts=0 while [ ! -f "$ready" ] && [ "$attempts" -lt 20 ]; do sleep 0.05; attempts=$((attempts + 1)); done [ -f "$ready" ] || fail "fake primary did not start" - env TMUX_TMPDIR="$socket_dir" "$real_tmux" -L fm-lab has-session -t primary \ - || fail "primary session is not reachable through the lab's TMUX_TMPDIR" + "$real_tmux" -S "$socket_path" has-session -t primary \ + || fail "primary session is not reachable through the lab socket" if "$LABHOME" teardown "$lab" >/dev/null 2>&1; then fail "lab teardown removed the directory while its server was running" fi [ -d "$socket_dir" ] || fail "refused active-server teardown removed the socket directory" - env TMUX_TMPDIR="$socket_dir" "$real_tmux" -L fm-lab kill-server \ + "$real_tmux" -S "$socket_path" kill-server \ || fail "could not stop the isolated lab tmux server" mkdir -p "$TMP/failing-tmux-bin" printf '#!/bin/sh\necho "tmux: probe failed" >&2\nexit 1\n' > "$TMP/failing-tmux-bin/tmux" diff --git a/tests/fm-live-lab-isolation.test.sh b/tests/fm-live-lab-isolation.test.sh new file mode 100755 index 00000000000..3c001d626be --- /dev/null +++ b/tests/fm-live-lab-isolation.test.sh @@ -0,0 +1,299 @@ +#!/usr/bin/env bash +# Behavior tests for the tmux isolation the live lab depends on: +# fm_tmux_isolation_gate (tests/lib.sh) and bin/fm-live-lab.sh's explicit lab +# socket. tmux resolves its socket under TMUX_TMPDIR only while that directory +# exists and otherwise silently falls back to /tmp/tmux-, so a lab command +# aimed at a removed lab directory would reach whatever server lives there. +# Here a decoy server stands on that default socket, and every lab command +# aimed at a missing lab directory must leave it alone. +# +# The decoy never runs on the host /tmp: the suite re-executes itself under +# `unshare -Urm` with a fresh tmpfs on /tmp, confirms there that /tmp is not the +# host one, and skips the decoy cases where no such namespace is available or +# the checkout itself lives under /tmp, where that mount would hide it. +set -u + +if [ -n "${FM_LAB_ISO_HOST_MARKER:-}" ]; then + if [ -e "$FM_LAB_ISO_HOST_MARKER" ] || [ -n "$(ls -A /tmp)" ]; then + echo "not ok - /tmp is not a fresh private mount; refusing to start the decoy" >&2 + exit 1 + fi +fi + +# shellcheck source=tests/fixtures.sh +. "$(dirname "${BASH_SOURCE[0]}")/fixtures.sh" +# shellcheck source=bin/fm-timeout-lib.sh +. "$ROOT/bin/fm-timeout-lib.sh" + +command -v tmux >/dev/null 2>&1 || { echo "skip: tmux not found"; exit 0; } +unset TMUX TMUX_TMPDIR + +TMP_ROOT=$(fm_test_tmproot fm-lab-iso) +LIVE_LAB="$ROOT/bin/fm-live-lab.sh" +GATE_SOCKET="$TMP_ROOT/base/tmux-$(id -u)/default" +DEFAULT_SOCKET="/tmp/tmux-$(id -u)/default" +STUCK_SOCKET="$TMP_ROOT/stuck/tmux-$(id -u)/default" +DECOY_PID='' +STUCK_PID='' + +# Poll steps (0.05s each) a process gets to exit after each escalation step. +DECOY_POLLS=100 + +# signal_decoy : one seam, so a case can stand in an unkillable process. +signal_decoy() { + kill -"$1" "$2" 2>/dev/null +} + +# pid_running : succeeds while the process exists and has not exited. +# An exited but unreaped process (a zombie, state Z) still answers kill -0 +# when the runner's PID 1 does not reap orphans, so it counts as gone. A ps +# that errors fails closed: the process counts as still running. +pid_running() { + local state + kill -0 "$1" 2>/dev/null || return 1 + state=$(ps -o stat= -p "$1" 2>/dev/null) || return 0 + case $state in + Z*) return 1 ;; + esac +} + +# wait_gone : succeeds once the process is gone, after at most polls. +wait_gone() { + local pid=$1 polls=$2 + while pid_running "$pid"; do + [ "$polls" -gt 0 ] || return 1 + polls=$((polls - 1)) + sleep 0.05 + done +} + +# stop_decoy [polls]: stop the decoy server recorded at start. +# kill-server on its own explicit socket first, then TERM, then KILL on the +# recorded pid, each step bounded (kill-server too, against a wedged server). +# A decoy that survives all three is reported and fails the call instead of +# stalling the suite on its pane's 600s sleep. +stop_decoy() { + local pid=$1 socket=$2 polls=${3:-$DECOY_POLLS} + [ ! -S "$socket" ] || fm_run_timed 5 tmux -S "$socket" kill-server 2>/dev/null + wait_gone "$pid" "$polls" && return 0 + signal_decoy TERM "$pid" + wait_gone "$pid" "$polls" && return 0 + signal_decoy KILL "$pid" + wait_gone "$pid" "$polls" && return 0 + echo "not ok - cleanup: decoy server $pid survived kill-server, TERM and KILL" >&2 + return 1 +} + +isolation_cleanup() { + # Only the servers this suite started, each by its own explicit socket, and + # only while it is still there; the decoy is gone before the suite returns. + local rc=0 + [ ! -S "$GATE_SOCKET" ] || tmux -S "$GATE_SOCKET" kill-server 2>/dev/null + if [ -n "$STUCK_PID" ]; then + kill -CONT "$STUCK_PID" 2>/dev/null + stop_decoy "$STUCK_PID" "$STUCK_SOCKET" || rc=1 + fi + if [ -n "$DECOY_PID" ]; then + stop_decoy "$DECOY_PID" "$DEFAULT_SOCKET" || rc=1 + fi + fm_test_cleanup + [ "$rc" -eq 0 ] || exit 1 +} +trap isolation_cleanup EXIT + +# gate_run [NAME=VALUE...]: the gate's output and exit, in a subshell, +# followed by RAN when the gate let the script continue. +gate_run() { + local base=$1 + shift + ( + for assignment in "$@"; do export "${assignment?}"; done + fm_tmux_isolation_gate "$base" + echo RAN + ) 2>&1 +} + +# ---- the gate --------------------------------------------------------------- + +# FM_LAB_ISO_TMP_COPY marks the copy of this suite under /tmp (below), which +# needs only the decoy preflight. +if [ -z "${FM_LAB_ISO_HOST_MARKER:-}" ] && [ -z "${FM_LAB_ISO_TMP_COPY:-}" ]; then + out=$(gate_run "$TMP_ROOT/base") + expect_code 0 "$?" "the gate passes with no socket directory: $out" + assert_equals RAN "$out" "the gate runs the suite where no tmux server can answer" + + mkdir -p "$TMP_ROOT/base" + mkdir -m 700 "$TMP_ROOT/base/tmux-$(id -u)" + tmux -S "$GATE_SOCKET" -f /dev/null new-session -d -s live 'exec sleep 600' || fail "cannot start the gate's own server" + out=$(gate_run "$TMP_ROOT/base") + expect_code 0 "$?" "the gate skips cleanly beside a live server: $out" + assert_contains "$(printf '%s\n' "$out" | head -n 1)" "skip: tmux isolation: a live tmux server answers on $GATE_SOCKET" "the skip is the first line and names the live socket" + assert_contains "$out" "unshare -Urm" "the skip names the isolation it needs" + assert_not_contains "$out" RAN "the gate stops the suite beside a live server" + + out=$(gate_run "$TMP_ROOT/base" CI=true) + expect_code 0 "$?" "under CI the gate skips the same way: $out" + assert_contains "$out" "skip: tmux isolation" "under CI the gate still says why it skips" + assert_not_contains "$out" RAN "under CI the gate stops the suite beside a live server" + + tmux -S "$GATE_SOCKET" kill-server 2>/dev/null + out=$(gate_run "$TMP_ROOT/base") + assert_equals RAN "$out" "the gate runs again once only a dead socket is left" + pass "fm_tmux_isolation_gate runs isolated and skips beside a live server" + + # A server that accepts the connection but never answers (stopped here) must + # not hold the gate: it gives up at its probe deadline and skips. + mkdir -p "$TMP_ROOT/stuck" + mkdir -m 700 "$TMP_ROOT/stuck/tmux-$(id -u)" + tmux -S "$STUCK_SOCKET" -f /dev/null new-session -d -s stuck 'exec sleep 600' || fail "cannot start the stuck server" + STUCK_PID=$(tmux -S "$STUCK_SOCKET" display-message -p '#{pid}') + [ -n "$STUCK_PID" ] || fail "the stuck server has no pid" + kill -STOP "$STUCK_PID" || fail "cannot stop the stuck server" + start=$(date +%s) + # shellcheck disable=SC2016 # $1 and $2 expand in the bounded shell. + out=$(FM_TMUX_ISOLATION_PROBE_SECONDS=1 fm_run_timed 30 bash -c '. "$1/tests/lib.sh"; fm_tmux_isolation_gate "$2"; echo RAN' _ "$ROOT" "$TMP_ROOT/stuck" 2>&1) + code=$? + kill -CONT "$STUCK_PID" 2>/dev/null + stop_decoy "$STUCK_PID" "$STUCK_SOCKET" || fail "cannot stop the stuck server" + STUCK_PID='' + expect_code 0 "$code" "the gate returns from a server that never answers: $out" + assert_contains "$out" "skip: tmux isolation: the tmux server on $STUCK_SOCKET did not answer within 1s" "the skip names the silent socket and the deadline" + assert_not_contains "$out" RAN "the gate stops the suite beside a server that never answers" + [ $(($(date +%s) - start)) -lt 10 ] || fail "the gate waited past its probe deadline" + pass "fm_tmux_isolation_gate skips at its deadline when a tmux server does not answer" + + # ---- the decoy cleanup is bounded ------------------------------------------ + + # No socket for kill-server to reach: TERM stops a plain process. + victim=$(bash -c 'sleep 600 /dev/null 2>&1 & echo $!') + start=$(date +%s) + stop_decoy "$victim" "$TMP_ROOT/no-such-socket" 4 || fail "cleanup could not stop a process that exits on TERM" + wait_gone "$victim" 0 || fail "cleanup returned success with the process still alive" + [ $(($(date +%s) - start)) -lt 5 ] || fail "cleanup of a TERM-able process was not prompt" + + # A process that ignores TERM is stopped by the KILL step. + victim=$(bash -c 'trap "" TERM; exec sleep 600 /dev/null 2>&1 & echo $!') + stop_decoy "$victim" "$TMP_ROOT/no-such-socket" 4 || fail "cleanup could not stop a process that ignores TERM" + wait_gone "$victim" 0 || fail "cleanup returned success with the TERM-ignoring process alive" + + # kill-server cannot stop it and neither signal lands: cleanup must return + # within its poll budget, name the survivor, and report failure. + victim=$(bash -c 'sleep 600 /dev/null 2>&1 & echo $!') + start=$(date +%s) + out=$(signal_decoy() { :; }; stop_decoy "$victim" "$TMP_ROOT/no-such-socket" 3 2>&1) + code=$? + kill -KILL "$victim" 2>/dev/null + expect_code 1 "$code" "cleanup reports a decoy it cannot stop: $out" + assert_contains "$out" "decoy server $victim survived" "the failure names the surviving decoy" + [ $(($(date +%s) - start)) -lt 5 ] || fail "cleanup of an unstoppable decoy waited past its bound" + # An exited decoy its parent never reaps stays a zombie that still answers + # kill -0: cleanup must count it as gone rather than report a failure. + bash -c 'sleep 0.2 /dev/null 2>&1 & echo $! $$; exec sleep 30 &3 2>/dev/null' 3>/dev/null >"$TMP_ROOT/zombie.pids" & + until [ -s "$TMP_ROOT/zombie.pids" ]; do sleep 0.05; done + read -r victim zombie_parent <"$TMP_ROOT/zombie.pids" + sleep 0.5 + kill -0 "$victim" 2>/dev/null || fail "the zombie fixture was reaped, so the case would be vacuous" + stop_decoy "$victim" "$TMP_ROOT/no-such-socket" 3 || fail "cleanup reported failure for an exited, unreaped decoy" + { kill -KILL "$zombie_parent"; wait "$zombie_parent"; } 2>/dev/null + + pass "decoy cleanup is bounded, escalates to TERM and KILL, and reports a decoy it cannot stop" +fi + +if [ -z "${FM_LAB_ISO_HOST_MARKER:-}" ]; then + # The decoy cases run only in a private mount namespace with a fresh /tmp. + if ! unshare -Urm sh -c 'mount -t tmpfs tmpfs /tmp' >/dev/null 2>&1; then + echo "skip: tmux isolation decoy: needs a private /tmp (unshare -Urm with a tmpfs mount on /tmp)" + exit 0 + fi + # bash reopens this script after the tmpfs is mounted on /tmp, so a checkout + # under /tmp would be hidden by the very mount that isolates the decoy. + suite=$(cd -P -- "$ROOT/tests" && pwd -P)/fm-live-lab-isolation.test.sh + case $suite in + "$(cd -P /tmp && pwd -P)"/*) + echo "skip: tmux isolation decoy: the checkout is under /tmp ($suite), which the private tmpfs on /tmp would hide" + exit 0 + ;; + esac + # A checkout under /tmp skips the decoy cases rather than failing on a script + # the tmpfs mount has hidden. The copy holds the suite and what it sources; + # its bin links back here. + if [ -z "${FM_LAB_ISO_TMP_COPY:-}" ]; then + copy=$(mktemp -d /tmp/fm-lab-iso-copy.XXXXXX) || fail "cannot make a checkout copy under /tmp" + FM_TEST_CLEANUP_DIRS+=("$copy") + mkdir -p "$copy/tests" + ln -s "$ROOT/bin" "$copy/bin" || fail "cannot link the copy's bin" + cp "$ROOT/tests/lib.sh" "$ROOT/tests/fixtures.sh" "$ROOT/tests/git-config-helpers.sh" \ + "$ROOT/tests/fm-live-lab-isolation.test.sh" "$copy/tests/" || fail "cannot copy the suite" + out=$(FM_LAB_ISO_TMP_COPY=1 fm_run_timed 120 bash "$copy/tests/fm-live-lab-isolation.test.sh" 2>&1) + expect_code 0 "$?" "a checkout under /tmp ends cleanly: $out" + assert_contains "$out" "skip: tmux isolation decoy: the checkout is under /tmp" "a checkout under /tmp says why it skips the decoy cases" + pass "a checkout under /tmp skips the decoy cases instead of losing its script to the mount" + fi + + host_marker=$(mktemp /tmp/fm-lab-iso-host.XXXXXX) || fail "cannot mark the host /tmp" + FM_TEST_CLEANUP_DIRS+=("$host_marker") + # shellcheck disable=SC2016 # $0 expands in the namespaced shell. + FM_LAB_ISO_HOST_MARKER=$host_marker unshare -Urm bash -c 'mount -t tmpfs tmpfs /tmp && exec env -u TMPDIR -u TMP -u TMUX_TMPDIR bash "$0"' "$suite" + exit $? +fi + +# ---- a lab aimed at a missing tmux directory -------------------------------- + +# /tmp is a fresh private tmpfs, so the decoy is a server of this suite's own +# that no one outside this namespace can reach. +env -u TMUX -u TMUX_TMPDIR tmux -f /dev/null new-session -d -s firstmate -n main \ + "printf 'DECOY-PANE\n'; exec sleep 600" || fail "cannot start the decoy default server" +DECOY_PID=$(tmux -S "$DEFAULT_SOCKET" display-message -p '#{pid}') +[ -n "$DECOY_PID" ] || fail "the decoy is not on the default socket" + +# shellcheck disable=SC2119 # No bases: the gate checks the real default ones. +out=$( (fm_tmux_isolation_gate; echo RAN) 2>&1) +assert_contains "$out" "skip: tmux isolation: a live tmux server answers on $DEFAULT_SOCKET" "the gate's default bases see a server on the default socket" +assert_not_contains "$out" RAN "the gate stops a suite beside the default server" + +HOME="$TMP_ROOT/home" +mkdir -p "$HOME/.pi/agent" "$HOME/.treehouse" +printf '{}\n' > "$HOME/.pi/agent/trust.json" +printf '{"projects":{}}\n' > "$HOME/.claude.json" +LAB_ROOT="$TMP_ROOT/lab" +MISSING_DIR=$(mktemp -d /tmp/fml.XXXXXX) || fail "cannot name a missing lab tmux directory" +rmdir "$MISSING_DIR" || fail "cannot remove the lab tmux directory" +mkdir -p "$LAB_ROOT/home/state" +: > "$LAB_ROOT/.treehouse-before" +{ + echo 'fm-live-lab v1' + echo "harness=claude" + echo "home=$LAB_ROOT/home" + echo "expect_host=no" + echo "host_off=no" + echo "mate=no" + echo "worker=no" + echo "nonce=deadbeef0000" + echo "mate_id=labdeadbeef0000-mate" + echo "worker_id=labdeadbeef0000-worker" + echo "pi_trust=$(shasum -a 256 "$HOME/.pi/agent/trust.json" | awk '{print $1}')" + echo "claude_config_dir=" + echo "claude_store=$HOME/.claude.json" + echo "pi_trust_store=$HOME/.pi/agent/trust.json" + echo "treehouse_dir=$HOME/.treehouse" + echo "tmux_dir=$MISSING_DIR" +} > "$LAB_ROOT/.fm-live-lab" + +# The divergence this suite exists for: the TMUX_TMPDIR-only form reaches the +# decoy once the lab directory is gone. +env -u TMUX TMUX_TMPDIR="$MISSING_DIR" tmux has-session -t firstmate 2>/dev/null \ + || fail "this tmux no longer falls back to the default socket; the decoy cases would prove nothing" + +out=$("$LIVE_LAB" pane "$LAB_ROOT" 2>&1) +assert_not_contains "$out" DECOY-PANE "pane never reads the default server's window" +"$LIVE_LAB" say "$LAB_ROOT" "LAB-TYPED-TEXT" >/dev/null 2>&1 +sleep 0.2 +assert_not_contains "$(tmux -S "$DEFAULT_SOCKET" capture-pane -p -t firstmate:=main)" LAB-TYPED-TEXT "say never types into the default server" +out=$("$LIVE_LAB" check "$LAB_ROOT" 2>&1) +assert_not_contains "$out" "ok primary" "check never reads the default server as the lab" +out=$("$LIVE_LAB" down "$LAB_ROOT" 2>&1) +expect_code 0 "$?" "down cleans a lab whose tmux directory is gone: $out" +assert_absent "$LAB_ROOT" "down removed the lab root" +kill -0 "$DECOY_PID" 2>/dev/null || fail "down killed the default tmux server" +tmux -S "$DEFAULT_SOCKET" has-session -t firstmate 2>/dev/null || fail "the default server lost its session" +pass "a lab aimed at a missing tmux directory never reaches the default tmux server" diff --git a/tests/fm-live-lab-up-mate.test.sh b/tests/fm-live-lab-up-mate.test.sh index 016b79b8cf5..040a667952e 100644 --- a/tests/fm-live-lab-up-mate.test.sh +++ b/tests/fm-live-lab-up-mate.test.sh @@ -5,6 +5,8 @@ set -u . "$(dirname "${BASH_SOURCE[0]}")/fixtures.sh" command -v tmux >/dev/null 2>&1 || { echo 'ok - skipped: tmux is not installed'; exit 0; } +# shellcheck disable=SC2119 # No bases: the gate checks the real default ones. +fm_tmux_isolation_gate TMP_ROOT=$(fm_test_tmproot fm-live-up-mate) export HOME="$TMP_ROOT/user" mkdir -p "$HOME/.pi/agent" "$HOME/.treehouse" "$TMP_ROOT/source/bin" "$TMP_ROOT/fakebin" @@ -25,8 +27,11 @@ fi SH cat > "$TMP_ROOT/source/bin/fm-spawn.sh" <<'SH' #!/usr/bin/env bash -tmux new-window -d -t firstmate: -n "fm-$1" -c "$FM_HOME/../mate" 'exec sleep 45' || exit 1 -pid=$(tmux display-message -p -t "firstmate:=fm-$1" '#{pane_pid}') +# The lab's explicit socket, never TMUX_TMPDIR alone, which falls back to the +# user's default server when its directory is missing. +lab_tmux() { tmux -S "${TMUX_TMPDIR:?}/tmux-$(id -u)/default" "$@"; } +lab_tmux new-window -d -t firstmate: -n "fm-$1" -c "$FM_HOME/../mate" 'exec sleep 45' || exit 1 +pid=$(lab_tmux display-message -p -t "firstmate:=fm-$1" '#{pane_pid}') printf '%s\n' "$pid" > "$FM_HOME/../mate/state/.lock" printf 'window=firstmate:fm-%s\n' "$1" > "$FM_HOME/state/$1.meta" SH diff --git a/tests/fm-live-lab.test.sh b/tests/fm-live-lab.test.sh index 7186d19e754..cfb22608b6a 100755 --- a/tests/fm-live-lab.test.sh +++ b/tests/fm-live-lab.test.sh @@ -17,6 +17,9 @@ TMP_ROOT=$(fm_test_tmproot fm-live-lab) LIVE_LAB="$ROOT/bin/fm-live-lab.sh" TRUST="$ROOT/bin/fm-claude-trust.sh" +# lab_socket_of : the explicit socket a lab's TMUX_TMPDIR names. +lab_socket_of() { printf '%s/tmux-%s/default\n' "$1" "$(id -u)"; } + live_lab_cleanup() { local dir pid marker for marker in "$TMP_ROOT/orphan-child" "$TMP_ROOT/late-child" "$TMP_ROOT/reused-child"; do @@ -26,7 +29,9 @@ live_lab_cleanup() { while read -r dir; do [ -n "$dir" ] || continue [ -d "$dir" ] || continue - env -u TMUX TMUX_TMPDIR="$dir" tmux kill-server 2>/dev/null + # Only the explicit lab socket, and only while it exists: a missing + # TMUX_TMPDIR would make tmux fall back to the user's default server. + [ ! -S "$(lab_socket_of "$dir")" ] || env -u TMUX tmux -S "$(lab_socket_of "$dir")" kill-server 2>/dev/null case "$dir" in /tmp/fml.*) rm -rf "$dir" ;; esac done < "$TMP_ROOT/tmux-dirs" rm -rf "/tmp/fm-labt$$-mate" "/tmp/fm-labt$$-worker" "/tmp/fm-labt$$-other" /tmp/fm-labt"$$"-*+* @@ -35,6 +40,8 @@ live_lab_cleanup() { trap live_lab_cleanup EXIT command -v tmux >/dev/null 2>&1 || { echo "ok - skipped: tmux is not installed"; exit 0; } +# shellcheck disable=SC2119 # No bases: the gate checks the real default ones. +fm_tmux_isolation_gate FAKE_HOME="$TMP_ROOT/fakehome" mkdir -p "$FAKE_HOME/.pi/agent" "$FAKE_HOME/.treehouse/existing-pool" @@ -65,6 +72,7 @@ make_lab() { git -C "$home" -c user.name=t -c user.email=t@example.invalid commit -qm lab tmux_dir=$("$ROOT/bin/fm-lab-home.sh" tmux-dir "$home") || fail "lab tmux dir" printf '%s\n' "$tmux_dir" >> "$TMP_ROOT/tmux-dirs" + mkdir -m 700 "$tmux_dir/tmux-$(id -u)" || fail "lab tmux socket dir" find "$HOME/.treehouse" -mindepth 1 -maxdepth 1 -exec basename {} \; | sort > "$root/.treehouse-before" { echo 'fm-live-lab v1' @@ -121,7 +129,8 @@ lab_tmux() { # local dir dir=$(sed -n 's/^tmux_dir=//p' "$1/.fm-live-lab") shift - env -u TMUX TMUX_TMPDIR="$dir" tmux "$@" + [ -n "$dir" ] || return 1 + env -u TMUX tmux -S "$(lab_socket_of "$dir")" "$@" } start_sleeper() { @@ -638,11 +647,14 @@ SH cat > "$WORKSRC/bin/fm-spawn.sh" <<'SH' #!/usr/bin/env bash id=$1 -tmux new-window -d -t firstmate: -n "fm-$id" -c "$FM_HOME" 'exec sleep 45 >/dev/null 2>&1' || exit 1 +# The lab's explicit socket, never TMUX_TMPDIR alone, which falls back to the +# user's default server when its directory is missing. +lab_tmux() { tmux -S "${TMUX_TMPDIR:?}/tmux-$(id -u)/default" "$@"; } +lab_tmux new-window -d -t firstmate: -n "fm-$id" -c "$FM_HOME" 'exec sleep 45 >/dev/null 2>&1' || exit 1 # A missing =name can silently resolve to the current window: verify the name. for (( n=0; n<30; n++ )); do - if tmux list-windows -t firstmate -F '#{window_name}' | grep -Fxq "fm-$id"; then - pid=$(tmux display-message -p -t "firstmate:=fm-$id" '#{pane_pid}') + if lab_tmux list-windows -t firstmate -F '#{window_name}' | grep -Fxq "fm-$id"; then + pid=$(lab_tmux display-message -p -t "firstmate:=fm-$id" '#{pane_pid}') [ -z "$pid" ] || break fi sleep 0.1 diff --git a/tests/lib.sh b/tests/lib.sh index ed4e04ed6af..fc7169234b8 100644 --- a/tests/lib.sh +++ b/tests/lib.sh @@ -560,6 +560,48 @@ fm_live_gate() { return 0 } +# fm_tmux_isolation_gate [...] is the gate a test opens with +# before it starts, kills, or cleans up a tmux server of its own. tmux resolves +# its socket under TMUX_TMPDIR only while that directory exists and otherwise +# silently falls back to /tmp, so one wrong tmux call reaches the user's own +# server. The test runs only when no live tmux server answers on any socket in +# /tmux- for each base (default: /tmp, plus TMUX_TMPDIR when set), +# which holds under a private /tmp such as +# unshare -Urm sh -c 'mount -t tmpfs tmpfs /tmp && exec bin/fm-test-run.sh ' +# and on a disposable CI runner. Each probe is bounded by +# FM_TMUX_ISOLATION_PROBE_SECONDS (default 5): a server that does not answer +# in time, stopped or stuck, counts as live. Otherwise it ends the script with +# skip: tmux isolation: ; +fm_tmux_isolation_gate() { + local base socket probe rc why='' seconds=${FM_TMUX_ISOLATION_PROBE_SECONDS:-5} + local -a bases=("$@") + case $seconds in '' | *[!0-9]* | 0) seconds=5 ;; esac + # shellcheck source=bin/fm-timeout-lib.sh + declare -F fm_run_timed >/dev/null || . "$(dirname "${BASH_SOURCE[0]}")/../bin/fm-timeout-lib.sh" + if [ "${#bases[@]}" -eq 0 ]; then + bases=(/tmp) + [ -z "${TMUX_TMPDIR:-}" ] || bases+=("$TMUX_TMPDIR") + fi + for base in "${bases[@]}"; do + for socket in "${base%/}/tmux-$(id -u)"/*; do + [ -S "$socket" ] || continue + probe=$(fm_run_timed "$seconds" env -u TMUX tmux -S "$socket" list-sessions 2>&1 >/dev/null) + rc=$? + if fm_timed_out "$rc"; then + why="the tmux server on $socket did not answer within ${seconds}s" + elif [ "$rc" -eq 0 ] || [ "${probe#*no server running}" = "$probe" ]; then + why="a live tmux server answers on $socket" + else + continue + fi + break 2 + done + done + [ -n "$why" ] || return 0 + printf 'skip: tmux isolation: %s; run under a private /tmp (unshare -Urm sh -c '"'"'mount -t tmpfs tmpfs /tmp && exec bin/fm-test-run.sh '"'"')\n' "$why" + exit 0 +} + # --- fakebin / PATH shims --------------------------------------------------- # # fm_fakebin creates /fakebin and echoes it; prepend it to PATH to From 89cdf4b7afae6f08b6c20cc419bda09bf301e817 Mon Sep 17 00:00:00 2001 From: Tim Kleinschmidt Date: Tue, 3 Nov 2026 20:29:37 +0100 Subject: [PATCH 06/34] fix(bin): return 124 on retriable bounded lock contention (#8119) * Fix retriable bounded lock deadline races Preserve retry-later status after an unpublished or exited lock holder at the deadline. Keep malformed lock records as hard failures and cover each classification with deterministic lock fixtures. Closes #8105 * no-mistakes(review): Return 124 when bounded lock is released --- bin/fm-wake-lib.sh | 17 +++++---- tests/fm-watcher-lock.test.sh | 66 +++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 7 deletions(-) diff --git a/bin/fm-wake-lib.sh b/bin/fm-wake-lib.sh index a31d2382461..f5908b1c846 100755 --- a/bin/fm-wake-lib.sh +++ b/bin/fm-wake-lib.sh @@ -1667,8 +1667,8 @@ _fm_lock_acquire_wait_handoff() { # # fm_lock_acquire_wait_bounded # # Bounded acquire variant. It preserves the ordinary wait/reclaim behavior -# until fm-timeout-lib.sh's hard deadline, returns 124 when a live holder still -# owns the lock, and leaves FM_LOCK_HELD_PID naming that holder. +# until fm-timeout-lib.sh's hard deadline, returns 124 for retriable contention, +# and leaves FM_LOCK_HELD_PID naming a live holder when one is known. # Use it where a caller must refuse rather than block: wake presentation, and # the guarded remote link clear, whose whole contract is to return a # reconciliation refusal instead of wedging an unattended close. @@ -1708,18 +1708,21 @@ fm_lock_acquire_wait_bounded() { fi if [ "$rc" -eq 124 ]; then owner_pid=$(cat "$lockdir/pid" 2>/dev/null || true) + # shellcheck disable=SC2034 # Output read by callers after bounded acquisition. + FM_LOCK_HELD_PID= case "$owner_pid" in - ''|*[!0-9]*|0) ;; + '') + fm_lock_parent_gone "$lockdir" && return 1 + if [ -e "$lockdir" ] || [ -L "$lockdir" ]; then [ -d "$lockdir" ] || return 1; fi + ;; + *[!0-9]*|0) return 1 ;; *) if [ "$owner_pid" -gt 0 ] 2>/dev/null && fm_pid_alive "$owner_pid"; then FM_LOCK_HELD_PID=$owner_pid - return 124 fi ;; esac - # shellcheck disable=SC2034 # Output read by callers after bounded acquisition. - FM_LOCK_HELD_PID= - return 1 + return 124 fi return "$rc" } diff --git a/tests/fm-watcher-lock.test.sh b/tests/fm-watcher-lock.test.sh index a7cf930ed6f..8dd1ee19843 100755 --- a/tests/fm-watcher-lock.test.sh +++ b/tests/fm-watcher-lock.test.sh @@ -1231,6 +1231,67 @@ test_lock_bounded_wait_earns_one_grace_window_for_unpublished_pid() { pass "bounded wait earns one grace window for an unpublished-pid lock, still bounds a live holder" } +assert_bounded_deadline_result() { + local mode=$1 expected=$2 dir out + dir=$(make_case "bounded-deadline-$mode") + out=$(FM_LOCK_STALE_AFTER=3600 FM_STATE_OVERRIDE="$dir/state" bash -c ' + . "$1" + lock=$2 + mode=$3 + mkdir "$lock" "$lock.steal" || exit 20 + printf "%s\n" "$4" > "$lock.steal/pid" + sleep 300 & + holder=$! + trap "kill $holder 2>/dev/null || true; wait $holder 2>/dev/null || true" EXIT + printf "%s\n" "$holder" > "$lock/pid" + _fm_wake_require_timeout || exit 21 + fm_run_timed() { + case "$mode" in + unpublished) rm "$lock/pid" ;; + exited) kill "$holder"; wait "$holder" 2>/dev/null || true ;; + absent) rm "$lock/pid"; rmdir "$lock" ;; + malformed) printf "invalid\n" > "$lock/pid" ;; + file) rm "$lock/pid"; rmdir "$lock"; printf "invalid\n" > "$lock" ;; + esac + return 124 + } + rc=0 + fm_lock_acquire_wait_bounded "$lock" 1 || rc=$? + case "$mode" in + live) [ "${FM_LOCK_HELD_PID:-}" = "$holder" ] || exit 22 ;; + *) [ -z "${FM_LOCK_HELD_PID:-}" ] || exit 23 ;; + esac + printf "%s\n" "$rc" + ' _ "$LIB" "$dir/state/.contend.lock" "$mode" "$$") || fail "$mode deadline fixture failed" + [ "$out" = "$expected" ] || fail "$mode deadline returned $out, expected $expected" +} + +test_bounded_deadline_unpublished_holder() { + assert_bounded_deadline_result unpublished 124 + pass "bounded deadline with an unpublished holder is retriable" +} + +test_bounded_deadline_exited_holder() { + assert_bounded_deadline_result exited 124 + pass "bounded deadline with an exited holder is retriable" +} + +test_bounded_deadline_released_lock() { + assert_bounded_deadline_result absent 124 + pass "bounded deadline with a released lock is retriable" +} + +test_bounded_deadline_live_holder() { + assert_bounded_deadline_result live 124 + pass "bounded deadline preserves the live holder advisory" +} + +test_bounded_deadline_malformed_lock() { + assert_bounded_deadline_result malformed 1 + assert_bounded_deadline_result file 1 + pass "bounded deadline rejects malformed pid data and non-directory locks" +} + test_lock_paused_mid_acquire_claim_fails_during_steal() { local dir state lockdir out pid dir=$(make_case lock-paused-claim-steal) @@ -2405,6 +2466,11 @@ test_lock_keeps_live_daemon_holder_with_stale_identity test_lock_empty_pid_uses_minimum_grace test_lock_late_claim_loses_after_recreate test_lock_bounded_wait_earns_one_grace_window_for_unpublished_pid +test_bounded_deadline_unpublished_holder +test_bounded_deadline_exited_holder +test_bounded_deadline_released_lock +test_bounded_deadline_live_holder +test_bounded_deadline_malformed_lock test_lock_paused_mid_acquire_claim_fails_during_steal test_watch_restart_rejects_reused_pid test_watch_restart_attaches_to_healthy_peer From ed1eb1d74079f42702ab706096079616bd214a3f Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Tue, 3 Nov 2026 19:30:06 +0000 Subject: [PATCH 07/34] fix(bin): ignore the no-mistakes mirror when teardown checks for landed work (#7820) * fix(teardown): refuse open-PR ships and ignore the no-mistakes mirror in the landed test Teardown deletes the record that merge recording depends on, so an ordinary ship whose recorded pr= is still open is refused (--force bypasses). The unpushed-commit checks also exclude the local no-mistakes mirror remote, which is not a forge, so work that only reached the mirror is no longer counted as landed. * no-mistakes(review): Exclude no-mistakes mirror from teardown unpushed checks * test: assert the mirror-only teardown refusal retains the task state --- bin/fm-teardown.sh | 9 +++++---- tests/fm-teardown.test.sh | 25 +++++++++++++++++++++++++ 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/bin/fm-teardown.sh b/bin/fm-teardown.sh index c0009358c30..09bfa5136fb 100755 --- a/bin/fm-teardown.sh +++ b/bin/fm-teardown.sh @@ -43,8 +43,9 @@ # that closes the call. # REFUSES if the worktree holds work that has not LANDED, because cleanup # hard-resets/removes the worktree and kills its processes. Work has landed when it is -# reachable from any remote-tracking branch (a fork counts as a remote, so -# upstream-contribution PRs pushed to a fork satisfy this in any mode), OR - for a +# reachable from any remote-tracking branch other than the local no-mistakes +# mirror (a fork counts as a remote, so upstream-contribution PRs pushed to a +# fork satisfy this in any mode; the mirror is not a forge), OR - for a # normal ship task whose commits are not so reachable - when its PR is merged and # GitHub reports a PR head that contains the current local work, or its content is # already present in the up-to-date default branch. This recognizes the common @@ -1689,7 +1690,7 @@ unpushed_patches_are_in_pr_head() { | sort -u ) || return 1 [ -n "$pr_patch_ids" ] || return 1 - unpushed=$(git -C "$WT" log --format=%H HEAD --not --remotes -- 2>/dev/null) || return 1 + unpushed=$(git -C "$WT" log --format=%H HEAD --not --exclude='no-mistakes/*' --remotes -- 2>/dev/null) || return 1 [ -n "$unpushed" ] || return 1 while IFS= read -r commit; do [ -n "$commit" ] || continue @@ -2127,7 +2128,7 @@ validate_worktree_teardown_safety() { fi dirty=$(printf '%s\n' "$dirty_raw" | grep -vE '^\?\? (\.claude/|\.fm-(grok|kimi)-turnend$)' || true) - if ! unpushed_raw=$(git -C "$WT" log --oneline HEAD --not --remotes -- 2>/dev/null); then + if ! unpushed_raw=$(git -C "$WT" log --oneline HEAD --not --exclude='no-mistakes/*' --remotes -- 2>/dev/null); then if worktree_safety_blocked_by_lock "commits not on a remote"; then return "$TEARDOWN_WORKTREE_SAFETY_LOCK_BLOCKED" fi diff --git a/tests/fm-teardown.test.sh b/tests/fm-teardown.test.sh index 42acd0e6d60..9de9723baa8 100755 --- a/tests/fm-teardown.test.sh +++ b/tests/fm-teardown.test.sh @@ -938,6 +938,30 @@ test_no_mistakes_truly_unpushed_refuses() { pass "no-mistakes worktree with genuinely unlanded work is refused (safety preserved)" } +test_no_mistakes_mirror_only_branch_refuses() { + local case_dir rc local_head + case_dir=$(make_case nm-mirror-only) + write_meta "$case_dir" no-mistakes ship + wt_commit_file "$case_dir" feature.txt hello "mirror-only work" + # A branch pushed only to the local pipeline mirror is not on a forge. + git init -q --bare "$case_dir/mirror.git" + git -C "$case_dir/project" remote add no-mistakes "$case_dir/mirror.git" + git -C "$case_dir/wt" push -q no-mistakes fm/task-x1 + git -C "$case_dir/project" fetch -q no-mistakes + git -C "$case_dir/wt" rev-parse --verify -q refs/remotes/no-mistakes/fm/task-x1 >/dev/null \ + || fail "nm-mirror-only: mirror remote-tracking ref was not created" + local_head=$(git -C "$case_dir/wt" rev-parse HEAD) + + set +e + run_teardown "$case_dir" > "$case_dir/stdout" 2> "$case_dir/stderr" + rc=$? + set -e + expect_code 1 "$rc" "nm-mirror-only: teardown should refuse mirror-only work" + grep -q REFUSED "$case_dir/stderr" || fail "nm-mirror-only: no REFUSED line in stderr" + assert_refusal_retained_task_state "$case_dir" nm-mirror-only "$local_head" + pass "branch pushed only to the no-mistakes mirror is refused as unlanded" +} + test_squash_merged_branch_deleted_allows() { local case_dir rc pr_head case_dir=$(make_case squash-merged) @@ -6176,6 +6200,7 @@ test_local_only_truly_unpushed_refuses test_local_only_merged_to_local_main_allows test_no_mistakes_origin_remote_allows test_no_mistakes_truly_unpushed_refuses +test_no_mistakes_mirror_only_branch_refuses test_local_only_force_overrides_unpushed test_secondmate_pr_registration_publishes_ready_line test_secondmate_pr_ready_line_waits_for_green_when_opted_in From 355ea8d4341d29ad62310ca1016cb24bbaa3e6ea Mon Sep 17 00:00:00 2001 From: Michal Zuber Date: Wed, 4 Nov 2026 00:17:10 +0100 Subject: [PATCH 08/34] fix: prevent Codex Stop hook JSON contamination (#7231) * fix: keep Codex Stop responses free of login-shell output * no-mistakes(document): Consolidate Codex Stop documentation under authoritative owners * no-mistakes(ci): Fixed both Pi before_agent_start handlers to narrow prompt-bearing events before accessing event.prompt, addressing the two TS2339 CI errors. Custom events now bypass user-prompt handling; ordinary prompt events and existing message_start paths remain unchanged. Local verification is blocked: tsc is not on PATH. No tools were installed and no other pipeline phases were executed * fix: keep Codex Stop responses free of login-shell output * no-mistakes(document): Consolidate Codex Stop documentation under authoritative owners * no-mistakes(document): Correct Codex verification prerequisites and guard coverage --- .../references/harness/codex.md | 8 +- .codex/hooks.json | 2 +- docs/turnend-guard.md | 5 +- docs/verification/runtime-backends.md | 24 +++ tests/fm-codex-hook-layer-live-e2e.test.sh | 204 +++++++++++++++++- tests/fm-turnend-guard.test.sh | 124 ++++++++++- 6 files changed, 345 insertions(+), 22 deletions(-) diff --git a/.agents/skills/harness-adapters/references/harness/codex.md b/.agents/skills/harness-adapters/references/harness/codex.md index 7dd042385a2..b162ad03c00 100644 --- a/.agents/skills/harness-adapters/references/harness/codex.md +++ b/.agents/skills/harness-adapters/references/harness/codex.md @@ -44,13 +44,9 @@ This is why `$no-mistakes` reaches a Codex worker instead of being consumed by t ## Primary integration -The primary integration was verified on 2026-07-08 with codex-cli 0.142.1. -The firstmate primary's `.codex/hooks.json` registers a Stop hook that pipes Codex's payload to `../../../bin/fm-turnend-guard.sh`, through `../../../bin/fm-codex-stop-park.sh --guard` when that script is present. -Codex Stop hooks preserve exit status 2 and stderr to block, and expose `stop_hook_active` for the same one-block loop safety used by the guard's default mode. +[`turnend-guard.md`](../../../../../docs/turnend-guard.md#harness-integrations) owns the primary Stop wrapper's scoping, response streams, and bounded continuation; [runtime backend verification](../../../../../docs/verification/runtime-backends.md#stop-response-parsing) owns the current parser evidence. -The Stop payload includes `cwd`, but the tracked hook does not use it to choose the guard executable. -Codex runs the Stop command with process PWD set to the hook-loaded project root, while no `CODEX_PROJECT_DIR`, `CODEX_WORKSPACE_ROOT`, or `CODEX_CWD` root variable is set. -The tracked hook anchors to `pwd -P`, verifies that root is Firstmate-shaped and hook-bearing, and then invokes the guard with the original payload. +Verified on 2026-07-08 with codex-cli 0.142.1: Codex runs the Stop command with process PWD set to the hook-loaded project root, while no `CODEX_PROJECT_DIR`, `CODEX_WORKSPACE_ROOT`, or `CODEX_CWD` root variable is set. Codex CLI 0.163.0 supports the native asynchronous Stop park registered by `bin/fm-codex-stop-park.sh` in a home that opts in with [`config/codex-stop-park`](../../../../../docs/configuration.md#codex-native-stop-park-configcodex-stop-park), verified in an isolated real CLI lab on 2026-10-19. The hook waits outside the model and delivers actionable wakes with `codex queue --thread`, including in embedded mode without a shared app-server daemon. diff --git a/.codex/hooks.json b/.codex/hooks.json index 9c68bb2c91c..534872eb170 100644 --- a/.codex/hooks.json +++ b/.codex/hooks.json @@ -33,7 +33,7 @@ "hooks": [ { "type": "command", - "command": "bash -lc 'payload=$(cat 2>/dev/null || true); [ -n \"$payload\" ] || exit 0; command -v jq >/dev/null 2>&1 || exit 0; root=$(pwd -P) || exit 0; [ -x \"$root/bin/fm-turnend-guard.sh\" ] || exit 0; [ -f \"$root/AGENTS.md\" ] || exit 0; [ -f \"$root/.codex/hooks.json\" ] || exit 0; jq -e \"any(.hooks.Stop[]?.hooks[]?.command?; type == \\\"string\\\" and contains(\\\"fm-turnend-guard.sh\\\"))\" \"$root/.codex/hooks.json\" >/dev/null 2>&1 || exit 0; if [ -x \"$root/bin/fm-codex-stop-park.sh\" ]; then printf \"%s\" \"$payload\" | \"$root/bin/fm-codex-stop-park.sh\" --guard; else printf \"%s\" \"$payload\" | \"$root/bin/fm-turnend-guard.sh\"; fi'", + "command": "bash -c 'fm_codex_stop() { payload=$(cat 2>/dev/null || true); [ -n \"$payload\" ] || return 0; command -v jq >/dev/null 2>&1 || return 0; root=$(pwd -P) || return 0; [ -x \"$root/bin/fm-turnend-guard.sh\" ] || return 0; [ -f \"$root/AGENTS.md\" ] || return 0; [ -f \"$root/.codex/hooks.json\" ] || return 0; jq -e \"any(.hooks.Stop[]?.hooks[]?.command?; type == \\\"string\\\" and contains(\\\"fm-turnend-guard.sh\\\"))\" \"$root/.codex/hooks.json\" >/dev/null 2>&1 || return 0; if [ -x \"$root/bin/fm-codex-stop-park.sh\" ]; then printf \"%s\" \"$payload\" | \"$root/bin/fm-codex-stop-park.sh\" --guard; else printf \"%s\" \"$payload\" | \"$root/bin/fm-turnend-guard.sh\"; fi; }; fm_codex_stop; code=$?; if [ \"$code\" -eq 0 ]; then printf \"{}\\n\"; fi; exit \"$code\"'", "timeout": 30 }, { diff --git a/docs/turnend-guard.md b/docs/turnend-guard.md index 3fac0db0e28..689faa219ca 100644 --- a/docs/turnend-guard.md +++ b/docs/turnend-guard.md @@ -272,7 +272,10 @@ The registrations in detail: It records idle when it allows the Stop and busy when its exit 2 blocks it into a continuation, because Claude runs Stop hooks in parallel and that continuation fires no `UserPromptSubmit`. A home whose guard predates `.fm-busy-stop` cannot close the turn, so that launch keeps the ordinary `Stop` idle hook instead. [Runtime backend verification](verification/runtime-backends.md#secondmate-busy-contract) owns the live evidence. -- Codex registers a `Stop` hook in `.codex/hooks.json`, anchors the executable to the hook process working directory, verifies a Firstmate-shaped hook-bearing root, and passes the original payload to the shared guard. +- Codex registers a synchronous `Stop` hook in `.codex/hooks.json`, anchors the executable to the hook process working directory, verifies a Firstmate-shaped hook-bearing root, and passes the original payload to the shared guard through `bin/fm-codex-stop-park.sh --guard` when that script is present. + Its inner wrapper uses non-login Bash with the inherited PATH to avoid login/logout output contaminating the hook response. + Allowed stops return one literal `{}` object; nonzero exits and stderr retain the shared guard's error or bounded-continuation behavior. + [Runtime backend verification](verification/runtime-backends.md#stop-response-parsing) owns the parser evidence and its portable and token-free live regression entry points. - OpenCode subscribes to the terminal `session.execution.succeeded`, `session.execution.failed`, and `session.execution.interrupted` events through `ctx.event.subscribe` in `.opencode/plugins/fm-primary-turnend-guard.js`, latched to the root worker session so child-session turns do not trip it, lets the watcher coordinator act first, and calls `ctx.session.prompt` once when the guard returns 2. The legacy OpenCode 1 `session.idle` + `client.session.promptAsync` path is retained in the plugin's `server` export. - Pi listens for `agent_settled` in `.pi/extensions/fm-primary-turnend-guard.ts`, runs once per logical agent run, and calls `pi.sendUserMessage(..., { deliverAs: "followUp" })` once when the guard returns 2. - omp answers its blocking `session_stop` hook in `.omp/extensions/fm-primary-turnend-guard.ts`, passing the payload's own `stop_hook_active` to the shared guard. diff --git a/docs/verification/runtime-backends.md b/docs/verification/runtime-backends.md index eadd015dcc2..87476bb4e7d 100644 --- a/docs/verification/runtime-backends.md +++ b/docs/verification/runtime-backends.md @@ -804,6 +804,30 @@ It captures the launch `bin/fm-spawn.sh` actually builds and confirms that the i It does not claim that a managed policy cannot re-enable hooks after launch. The portable half, `tests/fm-spawn-dispatch-profile.test.sh`, pins the requested hook-disablement flag for crewmates and its omission for secondmates, which run primary sessions on this repository's own project hooks. +### Stop response parsing + +Verified 2026-11-03 on Linux x86_64 with codex-cli 0.162.1. +The existing live hook-layer guard exercises the installed app-server's `hook/completed` notifications against a loopback Responses fixture that returns fixed text and no tool calls. +Each app-server has isolated config, hook trust, login files, and data; it neither uses a shared daemon nor contacts a model provider. +The fixture trusts only its synthetic Stop handler's exact key/hash. + +```sh +bash bin/fm-test-run.sh --jobs 1 tests/fm-turnend-guard.test.sh tests/fm-codex-hook-layer-live-e2e.test.sh +``` + +```text +ok - .codex Stop wrapper: clean success JSON, inherited PATH, unchanged errors and continuation without logout output +ok - codex codex-cli 0.162.1: Stop parser checked 12 isolated cases with clean wrapper JSON and bounded continuation +FM_TEST_SUMMARY total=2 failed=0 skipped_gate=0 duration_ms=97428 +``` + +The portable regression makes its login-shell logout emit terminal escape bytes and confirms that the fixture is effective before checking the tracked command's actual output. +It also checks primary, child-worktree, and non-Firstmate scope, empty input, missing jq, malformed registration, a non-executable guard, inherited PATH, and unchanged error status/stderr. +The optional native park's synchronous guard dispatch preserves its `--guard` argument, original payload, success JSON, and exit-2 stderr in an isolated executable fixture without registering a park. +The live parser accepts both empty output and `{}`, rejects mixed diagnostics/JSON, malformed syntax, multiple objects, and a wrong field type, and preserves an ordinary nonzero error. +The real copied supervision guard blocks once with its stderr reason, then allows the continuation's Stop; the fixture asserts both native hook verdicts and the two-request bound. +These checks refresh the Codex adapter evidence; [the integration owner](../turnend-guard.md#harness-integrations) describes its current behavior. + ## Codex automatic approval review Verified 2026-10-06 with codex-cli 0.160.1. diff --git a/tests/fm-codex-hook-layer-live-e2e.test.sh b/tests/fm-codex-hook-layer-live-e2e.test.sh index ec468e20165..fae10df0ecb 100755 --- a/tests/fm-codex-hook-layer-live-e2e.test.sh +++ b/tests/fm-codex-hook-layer-live-e2e.test.sh @@ -16,14 +16,17 @@ # and capability rather than falsely treating the effective setting as a # portable invariant. # -# It spends no model tokens (`codex features list` resolves configuration only), -# so it runs by default wherever codex is installed. +# The Stop-output cases use the installed app-server and a loopback Responses +# fixture with fixed text and no tool calls. They trust only the fixture hook +# and preserve the wrapper's inherited PATH without loading operator config. +# Neither layer spends model tokens, so the guard runs by default wherever +# its tools are installed. set -u # shellcheck source=tests/fixtures.sh . "$(dirname "${BASH_SOURCE[0]}")/fixtures.sh" -fm_live_gate default-on FM_CODEX_HOOK_LAYER_LIVE codex +fm_live_gate default-on FM_CODEX_HOOK_LAYER_LIVE codex python3 jq CODEX_VERSION=$(codex --version 2>&1) TMP_ROOT=$(fm_test_tmproot fm-codex-hook-layer-live) @@ -101,7 +104,202 @@ test_installed_codex_still_reports_the_hook_feature() { printf 'ok - codex %s still publishes the hook feature flag firstmate disables\n' "$CODEX_VERSION" } +test_installed_codex_accepts_the_stop_wrapper_and_rejects_invalid_output() { + python3 - "$ROOT" "$TMP_ROOT/stop-parser" "$CODEX_VERSION" <<'PY' +import http.server +import json +import os +from pathlib import Path +import queue +import shlex +import shutil +import subprocess +import sys +import threading +import time + +root, lab, version = Path(sys.argv[1]), Path(sys.argv[2]), sys.argv[3] +lab.mkdir() +wrapper = json.loads((root / '.codex/hooks.json').read_text())['hooks']['Stop'][0]['hooks'][0]['command'] +emitter = lab / 'emit.py' +emitter.write_text('''import json,sys +mode=sys.argv[1] +active=json.load(sys.stdin).get('stop_hook_active',False) +outputs={ + 'empty': ('','',0), 'json': ('{}\\n','',0), + 'mixed': ('diagnostic\\n{}\\n','',0), 'syntax': ('{','',0), + 'schema': ('{"continue":"yes"}','',0), 'two-objects': ('{}\\n{}','',0), + 'stderr': ('{}\\n','diagnostic\\n',0), 'error': ('','fixture error\\n',7)} +if mode=='continue': + out,err,code=('', 'fixture continuation\\n', 2) if not active else ('{}\\n','',0) +else: out,err,code=outputs[mode] +sys.stdout.write(out);sys.stderr.write(err);sys.exit(code) +''') +primary = lab / 'primary' +for name in ['bin', 'state', 'docs', '.codex']: + (primary / name).mkdir(parents=True, exist_ok=True) +(primary / 'AGENTS.md').write_text('Isolated Stop parser fixture.\n') +(primary / '.codex/hooks.json').write_text(json.dumps({'hooks': {'Stop': [{'hooks': [ + {'type': 'command', 'command': 'fm-turnend-guard.sh'}]}]}})) +for name in ['fm-turnend-guard.sh', 'fm-operational-input.sh', 'fm-supervision-instructions.sh', + 'fm-harness.sh', 'fm-primary-scope-lib.sh', 'fm-supervision-lib.sh', + 'fm-supervision-engine-lib.sh', 'fm-wake-lib.sh', 'fm-path-lib.sh', + 'fm-hook-host-lib.sh', 'fm-session-lock-lib.sh', 'fm-cursor-lib.sh', + 'fm-hermes-process-lib.sh', 'fm-timeout-lib.sh']: + shutil.copy2(root / 'bin' / name, primary / 'bin' / name) +shutil.copytree(root / 'docs/supervision-protocols', primary / 'docs/supervision-protocols') +subprocess.run(['git', 'init', '-q', str(primary)], check=True) + +class Responses(http.server.BaseHTTPRequestHandler): + requests = 0 + + def log_message(self, *args): + pass + + def do_POST(self): + self.rfile.read(int(self.headers.get('Content-Length', '0'))) + Responses.requests += 1 + message = {'id': 'msg_fixture', 'type': 'message', 'role': 'assistant', + 'status': 'completed', 'phase': 'final_answer', 'content': [ + {'type': 'output_text', 'text': 'fixture complete', 'annotations': []}]} + events = [ + {'type': 'response.created', 'response': {'id': 'resp_fixture', 'status': 'in_progress', 'output': []}}, + {'type': 'response.output_item.added', 'output_index': 0, + 'item': {**message, 'status': 'in_progress', 'content': []}}, + {'type': 'response.output_item.done', 'output_index': 0, 'item': message}, + {'type': 'response.completed', 'response': {'id': 'resp_fixture', 'status': 'completed', + 'output': [message], 'usage': {'input_tokens': 1, 'output_tokens': 1, 'total_tokens': 2}}}, + ] + data = ''.join('event: ' + event['type'] + '\ndata: ' + json.dumps(event) + '\n\n' + for event in events).encode() + self.send_response(200) + self.send_header('Content-Type', 'text/event-stream') + self.send_header('Content-Length', str(len(data))) + self.end_headers() + self.wfile.write(data) + +server = http.server.ThreadingHTTPServer(('127.0.0.1', 0), Responses) +server_thread = threading.Thread(target=server.serve_forever, daemon=True) +server_thread.start() + +def check(mode, expected): + case = lab / mode + case.mkdir() + fixture_home = case / 'login' + fixture_home.mkdir() + (fixture_home / '.bash_profile').write_text(':\n') + (fixture_home / '.bash_logout').write_text("printf '\\033[H\\033[2J\\033[3J'\n") + codex_data = case / 'codex' + codex_data.mkdir() + command = wrapper if mode.startswith('wrapper-') else shlex.join([sys.executable, str(emitter), mode]) + (codex_data / 'hooks.json').write_text(json.dumps({'hooks': {'Stop': [{'hooks': [ + {'type': 'command', 'command': command, 'timeout': 10}]}]}})) + (codex_data / 'config.toml').write_text(f'''model="fixture" +model_provider="fixture" +[model_providers.fixture] +name="Loopback Stop fixture" +base_url="http://127.0.0.1:{server.server_port}/v1" +wire_api="responses" +requires_openai_auth=false +[features] +hooks=true +shell_snapshot=false +[analytics] +enabled=false +''') + # Keep the inherited PATH, but no operator config, tokens, hook startup + # overrides, or fleet paths enter the child app-server or its hooks. + env = {key: os.environ[key] for key in ['PATH', 'LANG', 'LC_ALL', 'DISABLE_AUTOUPDATER'] if key in os.environ} + env.update({'HOME': str(fixture_home), 'CODEX_HOME': str(codex_data), + 'SHELL': '/bin/sh', 'TMPDIR': str(lab), 'OTEL_SDK_DISABLED': 'true'}) + cwd = primary if mode in ['wrapper-idle', 'wrapper-block'] else case + (primary / 'state/task.meta').unlink(missing_ok=True) + if mode == 'wrapper-block': + (primary / 'state/task.meta').touch() + notifications = [] + messages = queue.Queue() + deadline = time.monotonic() + 40 + before = Responses.requests + with (case / 'stderr').open('w') as stderr: + process = subprocess.Popen(['codex', 'app-server', '--stdio'], cwd=case, env=env, + stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=stderr, text=True) + def read_lines(): + for line in process.stdout: + messages.put(json.loads(line)) + messages.put(None) + reader = threading.Thread(target=read_lines, daemon=True) + reader.start() + def send(message): + process.stdin.write(json.dumps(message) + '\n') + process.stdin.flush() + def receive(): + message = messages.get(timeout=max(0.1, deadline - time.monotonic())) + assert message is not None, 'app-server exited before its hook verdict' + notifications.append(message) + return message + def rpc(number, method, params): + send({'id': number, 'method': method, 'params': params}) + while True: + message = receive() + if message.get('id') == number: + assert 'error' not in message, message + return message['result'] + try: + rpc(1, 'initialize', {'clientInfo': {'name': 'isolated-stop-test', 'version': '1'}, + 'capabilities': {'experimentalApi': True}}) + send({'method': 'initialized'}) + listed = rpc(2, 'hooks/list', {'cwds': [str(case)]}) + hooks = [hook for entry in listed['data'] for hook in entry['hooks'] + if hook['eventName'] == 'stop' and hook['sourcePath'] == str(codex_data / 'hooks.json')] + assert len(hooks) == 1, listed + hook = hooks[0] + thread = rpc(3, 'thread/start', {'cwd': str(cwd), 'model': 'fixture', 'modelProvider': 'fixture', + 'approvalPolicy': 'never', 'sandbox': 'read-only', 'ephemeral': True, + 'config': {'hooks.state': {hook['key']: {'trusted_hash': hook['currentHash']}}}}) + rpc(4, 'turn/start', {'threadId': thread['thread']['id'], + 'input': [{'type': 'text', 'text': 'fixture', 'text_elements': []}]}) + while receive().get('method') != 'turn/completed': + pass + runs = [message['params']['run'] for message in notifications + if message.get('method') == 'hook/completed' and message['params']['run']['eventName'] == 'stop'] + assert [run['status'] for run in runs] == expected, (mode, runs) + assert Responses.requests - before == len(expected), (mode, Responses.requests - before) + if mode in ['mixed', 'syntax', 'schema', 'two-objects']: + assert runs[0]['entries'] == [{'kind': 'error', 'text': 'hook returned invalid stop hook JSON output'}], runs + if mode == 'error': + assert runs[0]['entries'] == [{'kind': 'error', 'text': 'hook exited with code 7'}], runs + if mode == 'wrapper-block': + assert any('TURN WOULD END BLIND' in entry['text'] for entry in runs[0]['entries']), runs + finally: + process.terminate() + try: + process.wait(timeout=3) + except subprocess.TimeoutExpired: + process.kill() + process.wait() + reader.join(timeout=1) + +try: + for mode in ['empty', 'json', 'stderr', 'wrapper-noop', 'wrapper-idle']: + check(mode, ['completed']) + for mode in ['mixed', 'syntax', 'schema', 'two-objects', 'error']: + check(mode, ['failed']) + for mode in ['continue', 'wrapper-block']: + check(mode, ['blocked', 'completed']) + print(f'ok - codex {version}: Stop parser checked 12 isolated cases with clean wrapper JSON and bounded continuation') +except Exception as error: + raise SystemExit(f'not ok - codex {version}: isolated Stop parser failed: {error!r}') from error +finally: + server.shutdown() + server.server_close() + server_thread.join() +PY + local status=$? + [ "$status" -eq 0 ] || fail "codex $CODEX_VERSION: installed Stop parser regression failed" +} + test_installed_codex_still_reports_the_hook_feature test_installed_codex_accepts_requested_hook_disablement_for_the_captured_crewmate_launch +test_installed_codex_accepts_the_stop_wrapper_and_rejects_invalid_output echo "# all fm-codex-hook-layer-live-e2e tests passed" diff --git a/tests/fm-turnend-guard.test.sh b/tests/fm-turnend-guard.test.sh index 786e6610f01..9ddedac45b8 100755 --- a/tests/fm-turnend-guard.test.sh +++ b/tests/fm-turnend-guard.test.sh @@ -943,7 +943,7 @@ test_tracked_claude_entries_inert_under_grok() { } test_codex_hook_uses_process_pwd_when_payload_cwd_is_outside_root() { - local settings command dir expected_root outside payload out status + local settings command dir expected_root outside payload out status log settings="$ROOT/.codex/hooks.json" [ -f "$settings" ] || fail "tracked .codex/hooks.json is missing" command=$(jq -r '.hooks.Stop[0].hooks[0].command // empty' "$settings") @@ -953,22 +953,23 @@ test_codex_hook_uses_process_pwd_when_payload_cwd_is_outside_root() { expected_root=$(cd "$dir" && pwd -P) outside="$TMP_ROOT/codex-hook-outside" mkdir -p "$outside" + log="$TMP_ROOT/codex-hook-root.log" cat > "$dir/bin/fm-turnend-guard.sh" <<'EOF' #!/usr/bin/env bash -printf 'guard=%s\n' "$0" -cat +{ printf 'guard=%s\n' "$0"; cat; } > "${FM_CODEX_GUARD_LOG:?}" EOF chmod +x "$dir/bin/fm-turnend-guard.sh" payload=$(jq -cn --arg cwd "$outside" '{cwd:$cwd,stop_hook_active:false}') - out=$(printf '%s' "$payload" | (cd "$dir" && bash -c "$command") 2>&1); status=$? + out=$(printf '%s' "$payload" | (cd "$dir" && FM_CODEX_GUARD_LOG="$log" bash -c "$command") 2>&1); status=$? expect_code 0 "$status" "codex hook must execute successfully when payload cwd is outside the firstmate root" - assert_contains "$out" "guard=$expected_root/bin/fm-turnend-guard.sh" "codex hook must use the hook process root" - assert_contains "$out" "$payload" "codex hook must pass the original payload to the guard" + [ "$out" = '{}' ] || fail "codex hook must return a single success object: $out" + assert_contains "$(cat "$log")" "guard=$expected_root/bin/fm-turnend-guard.sh" "codex hook must use the hook process root" + assert_contains "$(cat "$log")" "$payload" "codex hook must pass the original payload to the guard" pass ".codex/hooks.json: Stop hook uses hook process root when payload cwd is outside" } test_codex_hook_ignores_nested_git_root_guard() { - local settings command dir nested subdir expected_root payload out status + local settings command dir nested subdir expected_root payload out status log settings="$ROOT/.codex/hooks.json" [ -f "$settings" ] || fail "tracked .codex/hooks.json is missing" command=$(jq -r '.hooks.Stop[0].hooks[0].command // empty' "$settings") @@ -976,6 +977,7 @@ test_codex_hook_ignores_nested_git_root_guard() { dir=$(make_primary_dir "$TMP_ROOT/codex-hook-outer") mark_codex_hook_root "$dir" expected_root=$(cd "$dir" && pwd -P) + log="$TMP_ROOT/codex-hook-outer.log" nested="$dir/projects/other" mkdir -p "$nested" git init -q "$nested" @@ -991,20 +993,119 @@ EOF chmod +x "$nested/bin/fm-turnend-guard.sh" cat > "$dir/bin/fm-turnend-guard.sh" <<'EOF' #!/usr/bin/env bash -printf 'guard=%s\n' "$0" -cat +{ printf 'guard=%s\n' "$0"; cat; } > "${FM_CODEX_GUARD_LOG:?}" EOF chmod +x "$dir/bin/fm-turnend-guard.sh" subdir="$nested/deep/path" mkdir -p "$subdir" payload=$(jq -cn --arg cwd "$subdir" '{cwd:$cwd,stop_hook_active:false}') - out=$(printf '%s' "$payload" | (cd "$dir" && bash -c "$command") 2>&1); status=$? + out=$(printf '%s' "$payload" | (cd "$dir" && FM_CODEX_GUARD_LOG="$log" bash -c "$command") 2>&1); status=$? expect_code 0 "$status" "codex hook must not execute a nested project guard" - assert_contains "$out" "guard=$expected_root/bin/fm-turnend-guard.sh" "codex hook must keep using the outer firstmate guard" + [ "$out" = '{}' ] || fail "codex hook must return a single success object: $out" + assert_contains "$(cat "$log")" "guard=$expected_root/bin/fm-turnend-guard.sh" "codex hook must keep using the outer firstmate guard" assert_not_contains "$out" "nested guard executed" "codex hook must not execute nested project code" pass ".codex/hooks.json: Stop hook ignores nested git root guard scripts" } +test_codex_hook_preserves_streams_without_login_logout_output() { + local dir command fixture_login other child stdout stderr expected payload status fakebin tool + dir=$(make_primary_dir "$TMP_ROOT/codex-output-primary") + mark_codex_hook_root "$dir" + command=$(jq -r '.hooks.Stop[0].hooks[0].command' "$ROOT/.codex/hooks.json") + fixture_login="$TMP_ROOT/codex-output-login" + other="$TMP_ROOT/codex-output-other" + mkdir -p "$fixture_login" "$other" + printf ':\n' > "$fixture_login/.bash_profile" + printf "printf '\\033[H\\033[2J\\033[3J'\n" > "$fixture_login/.bash_logout" + stdout="$TMP_ROOT/codex-output.stdout" + stderr="$TMP_ROOT/codex-output.stderr" + expected="$TMP_ROOT/codex-output.expected" + printf '{}\n' > "$expected" + payload='{"stop_hook_active":false}' + + # Assert the logout fixture is effective, so a green test cannot come from + # a host that happens to have a quiet login shell. + HOME="$fixture_login" BASH_ENV='' bash -lc 'exit 0' > "$stdout" 2> "$stderr" + [ -s "$stdout" ] || fail "the Codex noisy logout fixture did not emit anything" + + codex_output_case() { + local label=$1 cwd=$2 input=$3 want=$4 + shift 4 + printf '%s' "$input" | (cd "$cwd" && env HOME="$fixture_login" BASH_ENV='' ENV='' \ + FM_HOME="$dir" FM_ROOT_OVERRIDE='' FM_STATE_OVERRIDE="$dir/state" \ + FM_CONFIG_OVERRIDE="$dir/config" "$@" bash -c "$command") > "$stdout" 2> "$stderr" + status=$? + expect_code "$want" "$status" "Codex Stop wrapper $label must preserve its exit status" + if [ "$want" -eq 0 ]; then + cmp -s "$expected" "$stdout" || fail "Codex Stop wrapper $label emitted something other than one success object" + else + [ ! -s "$stdout" ] || fail "Codex Stop wrapper $label contaminated nonzero stdout" + fi + } + + codex_output_case idle "$dir" "$payload" 0 + [ ! -s "$stderr" ] || fail "idle Codex Stop wrapper emitted a diagnostic" + : > "$dir/state/task1.meta" + codex_output_case supervision-down "$dir" "$payload" 2 + assert_contains "$(cat "$stderr")" 'TURN WOULD END BLIND' "Codex Stop wrapper lost its continuation reason" + codex_output_case already-active "$dir" '{"stop_hook_active":true}' 0 + codex_output_case empty-input "$dir" '' 0 + codex_output_case non-firstmate "$other" "$payload" 0 + child=$(make_crewmate_worktree_dir "$TMP_ROOT/codex-output-parent" "$TMP_ROOT/codex-output-child") + mark_codex_hook_root "$child" + codex_output_case child-worktree "$child" "$payload" 0 + printf '{' > "$dir/.codex/hooks.json" + codex_output_case malformed-registration "$dir" "$payload" 0 + mark_codex_hook_root "$dir" + chmod -x "$dir/bin/fm-turnend-guard.sh" + codex_output_case nonexecutable-guard "$dir" "$payload" 0 + chmod +x "$dir/bin/fm-turnend-guard.sh" + + fakebin=$(fm_fakebin "$TMP_ROOT/codex-output-nojq") + for tool in bash cat; do + ln -s "$(command -v "$tool")" "$fakebin/$tool" + done + codex_output_case missing-jq "$dir" "$payload" 0 PATH="$fakebin" + + cat > "$dir/bin/fm-turnend-guard.sh" <<'EOF' +#!/usr/bin/env bash +cat >/dev/null +printf 'fixture guard failed\n' >&2 +exit 7 +EOF + codex_output_case runtime-error "$dir" "$payload" 7 + [ "$(cat "$stderr")" = 'fixture guard failed' ] || fail "Codex Stop wrapper changed runtime-error stderr" + + fakebin=$(fm_fakebin "$TMP_ROOT/codex-output-inherited-path") + printf '#!/usr/bin/env bash\nprintf "inherited PATH used\\n"\n' > "$fakebin/codex-path-probe" + chmod +x "$fakebin/codex-path-probe" + cat > "$dir/bin/fm-turnend-guard.sh" <<'EOF' +#!/usr/bin/env bash +cat >/dev/null +codex-path-probe >&2 +EOF + codex_output_case inherited-path "$dir" "$payload" 0 PATH="$fakebin:$PATH" + [ "$(cat "$stderr")" = 'inherited PATH used' ] || fail "Codex Stop wrapper lost its inherited PATH" + + # Current primaries route through the optional park's synchronous guard. + # Exercise that dispatch without registering or running a native park. + cat > "$dir/bin/fm-codex-stop-park.sh" <<'EOF' +#!/usr/bin/env bash +[ "$#" -eq 1 ] && [ "$1" = --guard ] || exit 99 +cat > "${FM_HOME:?}/park-payload" +printf 'fixture park guard\n' >&2 +exit "${FM_TEST_PARK_CODE:-0}" +EOF + chmod +x "$dir/bin/fm-codex-stop-park.sh" + codex_output_case park-guard-allow "$dir" "$payload" 0 + [ "$(cat "$dir/park-payload")" = "$payload" ] || fail "Codex Stop wrapper changed the park guard payload" + [ "$(cat "$stderr")" = 'fixture park guard' ] || fail "Codex Stop wrapper changed park guard stderr" + codex_output_case park-guard-block "$dir" "$payload" 2 FM_TEST_PARK_CODE=2 + [ "$(cat "$stderr")" = 'fixture park guard' ] || fail "Codex Stop wrapper lost park guard continuation stderr" + unset -f codex_output_case + pass ".codex Stop wrapper: clean success JSON, inherited PATH, unchanged errors and continuation without logout output" +} + test_opencode_plugin_anchors_guard_to_worktree() { local plugin parent worktree_dir wrong_dir out status plugin="$ROOT/.opencode/plugins/fm-primary-turnend-guard.js" @@ -2608,6 +2709,7 @@ test_grok_adapter_missing_jq_and_no_supervision_allow test_tracked_claude_entries_inert_under_grok test_codex_hook_uses_process_pwd_when_payload_cwd_is_outside_root test_codex_hook_ignores_nested_git_root_guard +test_codex_hook_preserves_streams_without_login_logout_output test_opencode_plugin_anchors_guard_to_worktree test_pi_extension_injects_once_per_logical_agent_run test_pi_extension_retries_after_followup_delivery_failure From c6b62326735593017ce8d25779eca7ece21085aa Mon Sep 17 00:00:00 2001 From: Lewis Mazzei Date: Tue, 3 Nov 2026 23:17:58 +0000 Subject: [PATCH 09/34] fix(calm): leave one blank row above the Claude Code working boat (#7253) * fix(calm): leave one blank row above the Claude Code working boat Refs #7160 * no-mistakes(review): Assert spinner Box padding by walking tree --- .claude/mods/firstmate-calm/hooks/register.ts | 2 ++ .claude/mods/firstmate-calm/tests/support.ts | 32 +++++++++++++++---- .../firstmate-calm/tests/working-ship.test.ts | 10 +++++- docs/calm.md | 2 +- 4 files changed, 38 insertions(+), 8 deletions(-) diff --git a/.claude/mods/firstmate-calm/hooks/register.ts b/.claude/mods/firstmate-calm/hooks/register.ts index 907ba188345..48e4c178b94 100644 --- a/.claude/mods/firstmate-calm/hooks/register.ts +++ b/.claude/mods/firstmate-calm/hooks/register.ts @@ -464,8 +464,10 @@ export const register: Register = (on) => { const packed = packCalmShipRasterCells(sprite.frame(columns), columns, palette); sites.set(e.requestId, { columns, rows: packed.rows }); const { Box, Raster } = $.ui.resolve(e); + // One blank row above the boat keeps its sail off the highlighted prompt, since Calm hides the rows between. return Box({ flexDirection: "column", + paddingTop: 1, children: Raster({ key: CALM_SHIP_RASTER_KEY, columns, rows: packed.rows, cells: packed.cells }), }); }); diff --git a/.claude/mods/firstmate-calm/tests/support.ts b/.claude/mods/firstmate-calm/tests/support.ts index 140d4db05ff..d7b09fa855e 100644 --- a/.claude/mods/firstmate-calm/tests/support.ts +++ b/.claude/mods/firstmate-calm/tests/support.ts @@ -272,20 +272,40 @@ export function isStock(tree: unknown): boolean { return JSON.stringify(tree).includes(STOCK_TEXT); } -/** The Raster element inside a Spinner drawing, or undefined when the drawing has none. */ -export function rasterOf(tree: unknown): { columns: number; rows: number; cells: string; key: string } | undefined { +function drawingNodes(tree: unknown): unknown[] { const seen: unknown[] = [tree]; + const nodes: unknown[] = []; while (seen.length > 0) { const node = seen.pop(); if (node === null || typeof node !== "object") continue; - const element = node as { type?: unknown; props?: Record; children?: unknown }; - if (element.type === "Raster" && element.props !== undefined) { - return element.props as { columns: number; rows: number; cells: string; key: string }; - } + nodes.push(node); + const element = node as { props?: Record; children?: unknown }; if (Array.isArray(element.children)) seen.push(...element.children); else if (element.children !== undefined) seen.push(element.children); if (element.props !== undefined && "children" in element.props) seen.push(element.props.children); } + return nodes; +} + +/** The Box wrapping a Spinner Raster, or undefined when the drawing has none. */ +export function boxOf(tree: unknown): { props?: Record } | undefined { + for (const node of drawingNodes(tree)) { + const element = node as { type?: unknown; props?: Record }; + if (element.type === "Box" && element.props !== undefined && rasterOf(element) !== undefined) { + return element; + } + } + return undefined; +} + +/** The Raster element inside a Spinner drawing, or undefined when the drawing has none. */ +export function rasterOf(tree: unknown): { columns: number; rows: number; cells: string; key: string } | undefined { + for (const node of drawingNodes(tree)) { + const element = node as { type?: unknown; props?: Record }; + if (element.type === "Raster" && element.props !== undefined) { + return element.props as { columns: number; rows: number; cells: string; key: string }; + } + } return undefined; } diff --git a/.claude/mods/firstmate-calm/tests/working-ship.test.ts b/.claude/mods/firstmate-calm/tests/working-ship.test.ts index a5210b1c660..1e5fe2a15e4 100644 --- a/.claude/mods/firstmate-calm/tests/working-ship.test.ts +++ b/.claude/mods/firstmate-calm/tests/working-ship.test.ts @@ -2,7 +2,7 @@ // working row while Calm is on, its cadence on the mocked clock, its size against the // viewport, and how it lets go of a site the surface no longer draws. import { describe, expect, test } from "claude-code/testing"; -import { calmCommand, decodeCells, isStock, rasterOf, spinner, themeChange, unmeasuredSpinner, world } from "./support.ts"; +import { boxOf, calmCommand, decodeCells, isStock, rasterOf, spinner, themeChange, unmeasuredSpinner, world } from "./support.ts"; const SAIL = "◿│◣"; const HULL = "╲▁▁▁╱"; @@ -43,6 +43,14 @@ describe("the working ship", () => { expect(backgrounds.flat().every((color) => color === DEFAULT)).toBe(true); }); + test("leaves one blank row above the boat so its sail stays off the highlighted prompt", async ($, on) => { + world(on, { preference: "on\n" }); + const drawing = await $.ui.render(spinner()); + const wrapper = boxOf(drawing); + expect(wrapper?.props?.paddingTop).toBe(1); + expect(rasterOf(wrapper)).toBeDefined(); + }); + test("animates the water every tick and moves the hull one column every fourth, through blits of the mounted size", async ($, on) => { const { clock, journal } = world(on, { preference: "on\n" }); await $.session.start({ cwd: "/work", surface: "terminal", isInteractive: true }); diff --git a/docs/calm.md b/docs/calm.md index c2130db72cc..6511c19e4f8 100644 --- a/docs/calm.md +++ b/docs/calm.md @@ -207,7 +207,7 @@ Toggling Calm redraws every hooked row already on screen, so rows drawn before t ### Working sailboat on Claude Code While Calm is on, the stock working row (`Sauteing... (12s · 300 tokens)`) becomes the same two-row sailboat Pi draws, from the same shared sprite geometry. -The sailboat fills the row inside the transcript margin. +The sailboat fills the row inside the transcript margin, under one blank row so its sail never touches the highlighted prompt above it. It repaints on the boat's 220ms cadence, with the hull moving every 880ms. It reflows on resize, and appears and disappears exactly where the stock row would. From b329c27529a686decfd52079f239aae196d86413 Mon Sep 17 00:00:00 2001 From: Trillium Smith Date: Wed, 4 Nov 2026 03:14:34 +0000 Subject: [PATCH 10/34] fix(bin): refuse to relaunch a worker into a primary home or checkout (#8127) * fix(spawn): refuse to relaunch a worker into a primary home or checkout A relaunch trusted the recorded worktree and started the worker there. After a machine restart the restored record could point at the primary home or a repository's primary checkout, so a worker was relaunched inside it. Relaunch now refuses with a named error when the recorded worktree is the home, the code root, or a repository's primary checkout (git dir equals git common dir). * no-mistakes(document): Document relaunch refusal of primary home or checkout worktrees * no-mistakes(ci): Fixed ci-2 (the Greptile P1 finding). ci-1, the Full suite failure, is the expected maintainer-label gate; the user chose to leave it alone, so nothing was changed for it. Invariant: the relaunch refusal must judge whether the recorded worktree is a primary checkout from the directory's own layout on disk. Inherited Git location variables must not be able to change the answer. In this change, the only place that probes Git for that decision is the git-dir and common-dir check in the `--relaunch` refusal in `bin/fm-spawn.sh`. The home and code-root comparison doesn't use git, so it can't be affected. Fix in `bin/fm-spawn.sh`: both probes now run in a single subshell. That subshell first unsets the same Git variables that `bin/fm-claude-trust.sh` clears (`GIT_DIR`, `GIT_WORK_TREE`, `GIT_COMMON_DIR`, `GIT_OBJECT_DIRECTORY`, `GIT_INDEX_FILE`, `GIT_ALTERNATE_OBJECT_DIRECTORIES`, `GIT_CEILING_DIRECTORIES`, `GIT_NAMESPACE`, `GIT_DISCOVERY_ACROSS_FILESYSTEM`, `GIT_CONFIG*`). It then runs one `git rev-parse --path-format=absolute --git-dir --git-common-dir` and splits the two output lines. The unset is scoped to the subshell, so the environment the rest of the script and the launched worker see is unchanged. When git fails, the result is empty and the code falls through exactly as before. Regression test in `tests/fm-control-relaunch.test.sh`: `test_relaunch_refuses_the_primary_checkout_under_inherited_git_overrides`. It records `worktree` as the project's primary checkout, then runs `fm-spawn --relaunch` with `GIT_DIR` set to the linked worktree's git directory and `GIT_WORK_TREE` set to the primary checkout. It asserts exit code 1, the "primary home or checkout" error, and that nothing was launched. The test is registered in the suite's run list. Verification: - `bash tests/fm-control-relaunch.test.sh` with the fix: rc=0, all tests pass, including the new one. - With the `fm-spawn.sh` change temporarily reverted: rc=1, and the new test fails with `missing: 'primary home or checkout'`. So it reproduces the reported bypass. - `shellcheck` on both files reports no warnings or errors --------- Co-authored-by: Trillium Smith <5898009+trillium@users.noreply.github.com> --- bin/fm-spawn.sh | 30 +++++++++++++++++++ docs/agent-control.md | 2 ++ tests/fm-control-relaunch.test.sh | 48 +++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+) diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh index 7f91ff72315..0e9397a2014 100755 --- a/bin/fm-spawn.sh +++ b/bin/fm-spawn.sh @@ -2559,6 +2559,36 @@ if [ "$RELAUNCH" -eq 1 ]; then echo "error: task $ID's recorded worktree '${RELAUNCH_WT:-none}' is missing; refusing to relaunch without the local copy its work lives in" >&2 exit 1 } + if [ "$KIND" != secondmate ]; then + # A worker must come back in its own disposable worktree, never in a + # primary home or a repository's primary checkout: refuse + # rather than fall back to wherever the restored pane happens to sit. + relaunch_wt_real=$(cd "$RELAUNCH_WT" 2>/dev/null && pwd -P) || relaunch_wt_real=$RELAUNCH_WT + relaunch_primary= + for relaunch_cand in "$FM_HOME" "$FM_ROOT"; do + relaunch_cand_real=$(cd "$relaunch_cand" 2>/dev/null && pwd -P) || continue + [ "$relaunch_wt_real" = "$relaunch_cand_real" ] && relaunch_primary=$relaunch_cand + done + if [ -z "$relaunch_primary" ]; then + # Probe the directory's own layout: an inherited GIT_DIR naming a linked + # worktree with GIT_WORK_TREE naming the primary checkout would otherwise + # make the two answers differ and pass the primary checkout. + relaunch_gdc=$( + unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_OBJECT_DIRECTORY GIT_INDEX_FILE \ + GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_CEILING_DIRECTORIES GIT_NAMESPACE \ + GIT_DISCOVERY_ACROSS_FILESYSTEM GIT_CONFIG GIT_CONFIG_GLOBAL \ + GIT_CONFIG_SYSTEM GIT_CONFIG_NOSYSTEM GIT_CONFIG_COUNT + git -C "$RELAUNCH_WT" rev-parse --path-format=absolute --git-dir --git-common-dir 2>/dev/null + ) || relaunch_gdc= + relaunch_gd=${relaunch_gdc%%$'\n'*} + relaunch_gc=${relaunch_gdc#*$'\n'} + [ -z "$relaunch_gd" ] || [ "$relaunch_gd" != "$relaunch_gc" ] || relaunch_primary="its repository's primary checkout" + fi + [ -z "$relaunch_primary" ] || { + echo "error: task $ID's recorded worktree '$RELAUNCH_WT' is the primary home or checkout ($relaunch_primary), not an isolated task worktree; refusing to relaunch a worker there" >&2 + exit 1 + } + fi if [ "$KIND" = secondmate ]; then FIRSTMATE_HOME=$(fm_meta_get "$RELAUNCH_META" home) [ -n "$FIRSTMATE_HOME" ] || FIRSTMATE_HOME=$RELAUNCH_WT diff --git a/docs/agent-control.md b/docs/agent-control.md index 5c0fbe3a386..1ee5d9fb48f 100644 --- a/docs/agent-control.md +++ b/docs/agent-control.md @@ -197,6 +197,8 @@ The worktree and the task's records are unaffected either way. - `exit`'s composer-empty check, above, is itself a fail-closed boundary that `relaunch` inherits by stopping the old agent through `exit`. - `fm-spawn --relaunch` independently refuses unless the endpoint is positively agent-free - either a `dead` endpoint that survives, or a Herdr or Rex endpoint proven gone by the absence proof above - so a replacement can never join a live agent. An `alive`, `ambiguous`, or `unreadable` verdict all refuse (a Rex `unreadable` after the absence proof cannot settle it), and so does any endpoint whose absence is not provable, which on tmux is every `missing`; absence is claimed only from positive evidence of it. + For a ship or scout it also refuses, by name, a recorded worktree that is the home, the code root, or a repository's primary checkout (its git dir equals its git common dir), so a worker only ever comes back in its own task worktree. + This check lives only in the launch owner, so on the `relaunch` verb it fires after the old agent has stopped and the transaction ends as a failed launch. It also requires the shell to be in the recorded worktree: every backend but Orca (which owns its own task worktree with no current-path probe) gets one explicit `cd` to the recorded path, then a pre-launch path read that refuses before any harness starts unless it confirms the endpoint is sitting in the recorded copy. ## Capability matrix diff --git a/tests/fm-control-relaunch.test.sh b/tests/fm-control-relaunch.test.sh index 59df9b9ec5d..7058776bf0c 100755 --- a/tests/fm-control-relaunch.test.sh +++ b/tests/fm-control-relaunch.test.sh @@ -1864,6 +1864,51 @@ test_missing_worktree_refuses_before_stopping_anything() { pass "fm-control relaunch: an unaccountable local copy refuses before the agent is touched" } +# A restart must never put a worker back in a primary home or a +# repository's primary checkout; the recorded worktree is the only launch cwd. +test_relaunch_refuses_a_recorded_worktree_that_is_the_primary_home() { + local dir out rc + dir=$(new_case homewt rl11) + add_ship_task "$dir" rl11 claude + sed -i.bak "s#^worktree=.*#worktree=$dir/home#" "$dir/home/state/rl11.meta" + printf 'zsh' > "$dir/fake/command" + out=$(run_spawn "$dir" rl11 --relaunch 2>&1); rc=$? + expect_code 1 "$rc" "a worktree that is the primary home should refuse" + assert_contains "$out" "primary home or checkout" "the refusal should name the primary home" + [ -z "$(cat "$dir/fake/literal")" ] || fail "a refused relaunch must launch nothing" + pass "fm-spawn --relaunch: a recorded worktree that is the primary home refuses" +} + +test_relaunch_refuses_a_recorded_worktree_that_is_the_project_primary_checkout() { + local dir out rc + dir=$(new_case projwt rl12) + add_ship_task "$dir" rl12 claude + sed -i.bak "s#^worktree=.*#worktree=$dir/proj#" "$dir/home/state/rl12.meta" + printf 'zsh' > "$dir/fake/command" + out=$(run_spawn "$dir" rl12 --relaunch 2>&1); rc=$? + expect_code 1 "$rc" "a worktree that is the project primary checkout should refuse" + assert_contains "$out" "primary home or checkout" "the refusal should name the primary checkout" + [ -z "$(cat "$dir/fake/literal")" ] || fail "a refused relaunch must launch nothing" + pass "fm-spawn --relaunch: a recorded worktree that is the project primary checkout refuses" +} + +# Inherited Git location overrides must not disguise the primary checkout: +# a linked worktree's GIT_DIR plus the primary checkout as GIT_WORK_TREE would +# make the git-dir and common-dir probes disagree. +test_relaunch_refuses_the_primary_checkout_under_inherited_git_overrides() { + local dir out rc linked_gd + dir=$(new_case projwtenv rl13) + add_ship_task "$dir" rl13 claude + linked_gd=$(git -C "$dir/wt" rev-parse --absolute-git-dir) + sed -i.bak "s#^worktree=.*#worktree=$dir/proj#" "$dir/home/state/rl13.meta" + printf 'zsh' > "$dir/fake/command" + out=$(GIT_DIR="$linked_gd" GIT_WORK_TREE="$dir/proj" run_spawn "$dir" rl13 --relaunch 2>&1); rc=$? + expect_code 1 "$rc" "the primary checkout should refuse even under inherited GIT_DIR/GIT_WORK_TREE" + assert_contains "$out" "primary home or checkout" "the refusal should name the primary checkout" + [ -z "$(cat "$dir/fake/literal")" ] || fail "a refused relaunch must launch nothing" + pass "fm-spawn --relaunch: inherited Git overrides do not hide the project primary checkout" +} + test_missing_instructions_refuse_before_stopping_anything() { local dir out rc dir=$(new_case nobrief rl11) @@ -3149,6 +3194,9 @@ test_prefixed_prior_harness_wiring_is_still_retired test_muse_session_binding_is_retired_on_a_harness_switch test_cursor_session_binding_is_retired_on_a_harness_switch test_missing_worktree_refuses_before_stopping_anything +test_relaunch_refuses_a_recorded_worktree_that_is_the_primary_home +test_relaunch_refuses_a_recorded_worktree_that_is_the_project_primary_checkout +test_relaunch_refuses_the_primary_checkout_under_inherited_git_overrides test_missing_instructions_refuse_before_stopping_anything test_checkpoint_refusal_leaves_the_record_byte_identical test_checkpoint_refuses_uninspectable_head_and_status From c2ee5e70d4c822113f7583a2c65ee2d71da282de Mon Sep 17 00:00:00 2001 From: Martin Kessler Date: Tue, 3 Nov 2026 23:25:49 -0800 Subject: [PATCH 11/34] fix(bin): read session-lock owner identity without the ps binary (#7609) * fix(session-lock): read process identity without the ps binary An EDR-style policy can deny the ps binary's exec itself - observed on a hardened macOS host where /bin/ps was refused even for 'ps -V', while kill, head, sysctl, pgrep and lsof all ran. The session lock proved identity by walking harness ancestry through ps, so the walk died at its first call: every session in that home became a permanent lock-refused read-only one, and a live lock owner looked reclaimable, so a fresh process could take over a lock whose owner was still running. All identity reads now go through one fm_proc_info reader. ps stays primary and is used verbatim wherever it executes, so a host where ps works is byte-identical to before. Only a ps that cannot execute at all - bash exit 126 for a refused exec, 127 for a missing binary, while a pid merely being gone exits ps 1 - routes one read to an OS provider: /proc on Linux, bin/fm-procinfo.py on macOS, which reads the ppid through a self-verified KERN_PROC_PID chain and the identity through the KERN_PROCARGS2 argv region. That last point is a correctness requirement, not a preference. macOS 'ps -o comm=' reports argv[0] and 'ps -o args=' reports the full argv, so the ps-free route keys both fields on the same argv region. A helper that reported the resolved exec path instead disagreed with ps for renamed, symlinked, or argv[0]-wrapped harnesses, and that disagreement turns a lock refusal into a wrong take-ownership decision. Every read fails closed and is verified against the requested pid: no route guessing, foreign chains still refused, dead pids still stop the walk. A record that is not exactly one line of three fields with a numeric ppid is refused rather than loosely sliced. Two defects found by diffing the change against the unchanged base on a live host are fixed here as well: 1. A pid ps can see but cannot name - a live process whose comm was emptied - was reported as stale, which means reclaimable. The base reports unknown for that case, and reporting it stale let a fresh process take over a lock whose owner was still running. The ps route now reports the pid as present, and the provider route accepts a record whose comm field is legitimately empty so both routes agree. 2. The provider record parser rejected a record with an empty field, but the field COUNT is what it must pin: a TAB is IFS whitespace, so a record with a MISSING field parsed exactly like a record whose field was empty. The parser now rebuilds the record from the parsed fields and compares it to the original, which proves the count without rejecting a legitimate empty field. Verified against the unchanged base: 120 identity reads and 200 lock inspections across live pids show zero divergence, and the empty-comm case reads unknown on both. * no-mistakes(review): Refuse reclaiming session locks with unreadable owner identity * no-mistakes(review): Reject partial process identity reads; reclaim non-pid locks * no-mistakes(review): Preserve platform process identity byte rendering across routes * no-mistakes(review): Normalize trailing empty argv elements across identity providers * no-mistakes(document): Document session-lock recovery requirements * no-mistakes(lint): Fix ShellCheck arithmetic array index style * fix(session-lock): decide the owner verdict from liveness first, not identity The review rounds that closed the "a live owner can be taken over" hole inverted the order of the two facts the verdict is built from: the provider read decided whether the recorded owner was alive, and liveness was only consulted afterwards. That order breaks two cases the base already handled. A pid this session cannot signal is not a live owner it may reclaim over, whatever a process table still says about it. A recorded owner that is gone therefore has to read as gone, or the stale lock can never be reclaimed and the session stays lock-refused read-only for good - the exact wedge this change exists to remove. The repository's own suites pin that: tests/fm-session-lock-ancestry.test.sh asserts that a recorded pid whose kill -0 fails is left for the ordinary reclaim, and tests/fm-session-lock-ancestry.test.sh's sibling case asserts that a recorded pid of 1 - which this session may not signal - is still reclaimable. The verdict now asks liveness first and identity second: kill -0 succeeds, the provider reads -> readable kill -0 succeeds, the provider fails -> unreadable: alive, identity not readable, so the lock must not be reclaimed kill -0 fails, the provider reads -> unknown: the process exists but this session may not signal it, so it is not a harness this session can prove - the base's "no live harness owner" kill -0 fails, the provider fails -> dead That keeps the protection the review rounds were after - a live owner whose identity cannot be read is never reclaimable - while restoring the base's reclaim behaviour for the cases the base handled. The new case "kill -0 succeeds, the provider fails" is the one that closes the reported takeover path, and it is unchanged. Verified on this host: tests/fm-session-lock-ancestry.test.sh exits 0 again (it exits 1 on the previous head, where the recorded-dead-pid case failed), tests/fm-session-lock-ps-denied.test.sh exits 0, and tests/fm-gotmp.test.sh exits 0. tests/fm-secondmate-harness.test.sh and tests/fm-session-start.test.sh still exit 1 with exactly the failures they have on the unchanged base: this host's restricted PATH lacks dirname, cat and awk. * no-mistakes(review): Preserve successful status for unreadable owner verdicts * fix(session-lock): keep the ppid a walk input, not an identity field The review round that made a partial identity read refuse the reclaim extended the rule from the arguments to the parent pid as well: a read that could not answer ps -o ppid= was treated as an unreadable identity, so the whole read failed. The parent pid is not an identity field. The identity the matcher reads is comm and args, and both of those are still fail-closed: a live harness whose arguments cannot be read is not reduced to a bare interpreter name, and its lock is still not reclaimable. The parent pid is a walk input, and a parent pid that cannot be read only ends the ancestry walk one hop early - the walk finds no harness and the session refuses the lock rather than taking one it cannot prove, which is the conservative direction. The base read the parent pid exactly this tolerant way, and the repository's own suites pin it: tests/fm-grok-harness.test.sh and tests/fm-kimi-harness.test.sh stub ps so that it answers comm= and args= and refuses every other question, and both expect the lock to be recognised as held by a live harness. Under the stricter rule both suites failed with "fm-lock did not recognize grok as a live holder" and "fm-lock did not acquire from Kimi ancestry". The provider route is unchanged and stays all-or-nothing: on Linux the parent pid comes from the same /proc read as the command name, and on macOS from the same KERN_PROC_PID chain, so a provider read is either complete or unreadable. The case that proves it - a /proc entry with no readable cmdline - still refuses the reclaim. The new test case is corrected rather than dropped: the failed-args case still has to refuse the reclaim, and the failed-ppid case now pins the tolerant contract - the verdict stays readable and the parent pid is empty. The same commit restores the shellcheck directives on the assignments inside fm_session_lock_inspect's verdict switch. The globals are read by bin/fm-lock.sh and bin/fm-inbox.sh, but the assignments inside the switch had lost their disable comments, so 'Lint 1' failed with SC2034 on FM_LOCK_INSPECT_STATE and FM_LOCK_INSPECT_LIVE_HARNESS. Verified on this host: tests/fm-session-lock-ps-denied.test.sh exits 0, tests/fm-session-lock-ancestry.test.sh exits 0, tests/fm-grok-harness.test.sh exits 0 (it exits 1 before this commit), tests/fm-kimi-harness.test.sh exits 0 (it exits 1 before this commit), tests/fm-gotmp.test.sh exits 0, and bin/fm-lint.sh exits 0. * no-mistakes(document): Clarify session-lock recovery ownership * no-mistakes(lint): Fix single-iteration ShellCheck loop * test(session-lock): drop the unused loop variable from the partial-identity case The failed-args case no longer runs through a loop, so the local that held the field name is never read, and the lint partition reports it as an unused variable (SC2034). The declaration loses it; nothing else about the case changes. * no-mistakes(review): Protect tagged lock owners; preserve Cygwin identity reads * no-mistakes(review): Fix zero-form locks; focused tests fail pty-host, ShellCheck warnings * fix(session-lock): read a classified live harness holder as held fm_session_lock_inspect lost its identity check on the readable verdict, so every live holder was classified unknown instead of held: grok and kimi holders failed the live-holder assertions, and a claude-named holder made fm-inbox report unknown for a lock that was held. Decide held from the single fm_harness_process_matches call on the readable branch. The Windows-tagged pre-block that made the same decision a second time is removed: fm_session_lock_pid_verdict already resolves the tagged pid through the Windows table and leaves the same FM_PROC_COMM/FM_PROC_ARGS, so re-reading it could only let the two answers diverge, and its winpid/win_rc were the unused bindings ShellCheck flagged as SC2034. * no-mistakes(document): Align session-lock docs with the shared reclaim verdict * fix(session-lock): emit the denied-ps diagnostic once per run `FM_OS_PROC_DIAG_SHOWN` was set by the diagnostic inside `triple=$(fm_os_proc_triple "$pid")`, so it died with that command-substitution subshell and every later ancestor read reprinted the same cause during one lock acquisition. `fm_proc_info` now spends the once-per-run guard in the shell that owns the walk. A cause line exists only on the provider's failure routes, so a failed read is exactly where that budget is used up; a readable read leaves it unspent for a later failure. The new case drives three failing reads in one shell and asserts one stderr line, then repeats with a readable first pid to prove a successful read does not spend the budget. * no-mistakes(document): Correct the denied-ps diagnostic scope to per shell * no-mistakes(review): Preserve UTF-8 process identity in Linux fallback * no-mistakes(document): Record the ps-free identity byte rule and helper inventory * test(session-lock): compare control-byte argv by shape, not by ps bytes The control-byte route-equivalence case compared the provider record and the ps record byte for byte. That pins one procps build's choice of byte for a control byte: 4.0.x writes a space where an argument's newline was and '?' for other controls, while other builds write '?' for the newline too, so the same two routes agree on one build and differ on the other even when both make the same identity decision. Fold each route's separator byte onto the placeholder the /proc route writes before comparing, keep the ppid and comm fields a raw comparison, and assert the fixture's words still straddle the control bytes on both routes so the case cannot pass by matching a loss. Pin the fold against both Linux renderings of this fixture's newline and assert those renderings really differ, so a return to raw bytes fails here instead of only on the other procps build. * no-mistakes(document): Align session-lock reclaim docs with the shared verdict * test(session-lock): keep the base PATH when no python3 shim is added The e2e blocked-ps case built the child PATH from fakebin alone on a host without python3, dropping the inherited base path with it. On Linux that left the /proc provider without the cat and tr it reads through, so the walk failed for a reason unrelated to the denied ps and the case failed spuriously on exactly the host it is meant to cover. Set the base path unconditionally and let the python3 branch only insert the shim ahead of it. * no-mistakes(document): Correct session-lock verdict comments and library ownership header * no-mistakes(document): Correct stale issue pointer in session-lock scope comment * no-mistakes(document): Correct malformed-lock reclaim wording and ps-denied nudge limit * fix(session-lock): parse /proc stat fields as stat_fields so rex.sh lints clean ShellCheck follows source directives: bin/backends/rex.sh sources bin/fm-agent-process-lib.sh, which sources bin/fm-session-lock-lib.sh, so the new array local named `fields` made rex.sh's string use of its own `fields` read as an array/string clash (SC2178/SC2128) and failed CI lane Lint 2 on 6e26ecb, while main's same lane passes. Rename the array to stat_fields, the name the repo's other /proc stat readers (bin/fm-remote-job-lib.sh, bin/fm-teardown.sh) already use. Verified with `shellcheck --norc --external-sources bin/backends/rex.sh` (was rc=1, now rc=0) and `bin/fm-lint.sh --partition 2of2` locally (rc=0, rex.sh reason=ok). * no-mistakes(document): Sync session-lock docs and stat-parser comment * test(run): hint fm-session-lock-ps-denied so the coverage guard stays under its unmeasured share The new session-lock denial script left 43 of 284 portable serial scripts without a measured duration hint on CI (main: 42), one past the guard's 15% bound. Record the 3012ms this run measured, in sorted order beside its ancestry sibling. --- bin/fm-claude-stop-autoarm.sh | 18 +- bin/fm-lock.sh | 6 +- bin/fm-procinfo.py | 185 +++++ bin/fm-session-lock-lib.sh | 463 +++++++++-- bin/fm-test-run.sh | 1 + bin/fm-turnend-guard-cursor.sh | 10 +- bin/fm-turnend-guard.sh | 9 +- docs/configuration.md | 2 +- docs/scripts.md | 3 +- docs/sessionstart-nudge.md | 1 + docs/turnend-guard.md | 4 +- docs/watcher-continuity.md | 8 +- tests/fm-session-lock-ancestry.test.sh | 79 ++ tests/fm-session-lock-ps-denied.test.sh | 979 ++++++++++++++++++++++++ 14 files changed, 1683 insertions(+), 85 deletions(-) create mode 100755 bin/fm-procinfo.py create mode 100644 tests/fm-session-lock-ps-denied.test.sh diff --git a/bin/fm-claude-stop-autoarm.sh b/bin/fm-claude-stop-autoarm.sh index 71745c717cb..d217c951913 100755 --- a/bin/fm-claude-stop-autoarm.sh +++ b/bin/fm-claude-stop-autoarm.sh @@ -15,10 +15,11 @@ # ancestor, or a live lock was recorded under this same trusted Claude # session id (which is what keeps a background session arming after its # transient helper chain is recycled). -# When an existing numeric owner fails the shared harness-liveness predicate, -# the hook delegates guarded recovery to bin/fm-lock.sh and then re-verifies -# ownership. A live owner, missing lock, malformed lock, or unresolved -# ancestry remains inert, so a competing session never arms or rewakes. +# When the shared fm_session_lock_pid_blocks_reclaim verdict refuses to +# reclaim the recorded owner, the hook stays inert; otherwise it delegates +# guarded recovery to bin/fm-lock.sh and then re-verifies ownership. +# A missing lock, a malformed record, or unresolved ancestry stays inert too, +# so a competing session never arms or rewakes. # - AFK: while state/.afk exists the away daemon owns the watcher and triage; # this hook exits 0 and NEVER rewakes the primary (checked again at # translation time so a mid-cycle AFK transition is honored). @@ -217,9 +218,10 @@ fm_primary_scope_matches "$FM_ROOT" "$STATE" || exit 0 # --- identity: only the lock-owning session's hooks may arm ------------------ # A prior session may have died after leaving its harness identity in .lock. -# Use the shared liveness predicate to recognize only that stale-owner case; it -# resolves a tagged identity too, so a dead Windows session is still recoverable -# rather than being read as a malformed lock nobody may ever clear. +# Use the shared fm_session_lock_pid_blocks_reclaim verdict to recognize only +# that stale-owner case; it resolves a tagged identity too, so a dead Windows +# session is still recoverable rather than being read as a malformed lock nobody +# may ever clear. # Defer the mutating claim until after the unchanged AFK and need gates, so an # idle or away home remains byte-for-byte inert. Missing or malformed locks are # uncertainty rather than stale-owner evidence and remain inert. @@ -227,7 +229,7 @@ RECOVER_SESSION_LOCK=0 if ! fm_session_lock_owned_by_self "$STATE"; then LOCK_PID=$(cat "$STATE/.lock" 2>/dev/null || true) fm_session_pid_valid "$LOCK_PID" || exit 0 - fm_harness_pid_alive "$LOCK_PID" && exit 0 + fm_session_lock_pid_blocks_reclaim "$LOCK_PID" && exit 0 RECOVER_SESSION_LOCK=1 fi diff --git a/bin/fm-lock.sh b/bin/fm-lock.sh index 897a368824a..f00754f8d72 100755 --- a/bin/fm-lock.sh +++ b/bin/fm-lock.sh @@ -254,7 +254,7 @@ if [ -f "$LOCK" ] && [ ! -L "$LOCK" ]; then confirm_own_lock "$old" old=$(cat "$LOCK" 2>/dev/null || true) fi - if [ -z "$REANCHOR" ] && fm_harness_pid_alive "$old"; then + if [ -z "$REANCHOR" ] && fm_session_lock_pid_blocks_reclaim "$old"; then refuse_live_owner "$old" fi fi @@ -282,10 +282,10 @@ if [ -e "$LOCK" ] || [ -L "$LOCK" ]; then } # A re-anchor decided above has held the claim lock since, so line 1 is the # pid it recorded and needs no second verdict. - if [ -z "$REANCHOR" ] && [ "$old" != "$me" ] && fm_harness_pid_alive "$old"; then + if [ -z "$REANCHOR" ] && [ "$old" != "$me" ] && fm_session_lock_pid_blocks_reclaim "$old"; then fm_session_lock_owned_by_self "$STATE" && confirm_own_lock "$old" old=$(cat "$LOCK" 2>/dev/null || true) - if [ -z "$REANCHOR" ] && [ "$old" != "$me" ] && fm_harness_pid_alive "$old"; then + if [ -z "$REANCHOR" ] && [ "$old" != "$me" ] && fm_session_lock_pid_blocks_reclaim "$old"; then refuse_live_owner "$old" fi fi diff --git a/bin/fm-procinfo.py b/bin/fm-procinfo.py new file mode 100755 index 00000000000..22d195a34df --- /dev/null +++ b/bin/fm-procinfo.py @@ -0,0 +1,185 @@ +#!/usr/bin/env python3 +"""fm-procinfo.py - ps-free process facts for bin/fm-session-lock-lib.sh. + +Prints one line: TABTAB for the pid given as argv[1], +using only sysctl(3) - the same kernel state `ps` reads, just without +executing /bin/ps. It exists because an EDR-style policy can deny the +ps binary's exec outright (even `ps -V`), and a session lock whose +identity walk needs ps can then never be acquired at all. + +Identity keeps ps's exact shape on macOS: comm is argv[0] and args is +the full argv joined with spaces, both taken from the kernel's per- +process argv region - the same region ps itself reports. That is a +correctness requirement, not a preference: the session lock compares a +process's identity across routes, and any process ps calls a verified +harness while this route calls it a non-harness turns a foreign +owner's fail-closed refusal into a lock takeover. A resolved exec path +(libproc proc_pidpath) is deliberately NOT reported - it is a +different fact that disagrees with ps for renamed, symlinked, or +argv[0]-wrapping harnesses, which is precisely the population the +denied-ps hosts are expected to run. + +Fail-closed by design: every read is verified against the requested pid +before anything is printed, and an argv that cannot be read to exactly +its declared length yields no identity rather than a partial one. No +pid, no verification, no output - exit 1. + +Usage: fm-procinfo.py +""" +import ctypes +import ctypes.util +import os +import struct +import sys + +CTL_KERN = 1 +KERN_PROC = 14 # CTL_KERN, KERN_PROC, KERN_PROC_PID: one kinfo_proc +KERN_PROC_PID = 1 +KERN_PROCARGS2 = 49 # CTL_KERN, KERN_PROCARGS2, pid: exec path + argv + env + +# kinfo_proc LP64 offsets: p_pid lives in kp_proc, the real parent pid in +# kp_eproc.e_ppid. These are assumptions, so _self_kinfo() proves them +# against this very process (os.getpid() / os.getppid()) before they are +# ever used on a requested pid, and a mismatch ends the run instead of +# reporting a guess. +P_PID_OFF = 40 +E_PPID_OFF = 560 + + +def _libc(): + return ctypes.CDLL(ctypes.util.find_library("c") or "libc.dylib", + use_errno=True) + + +_libc_cache = None + + +def libc(): + global _libc_cache + if _libc_cache is None: + _libc_cache = _libc() + return _libc_cache + + +def _sysctl(mib): + """Run a sysctl(3) mib, return the raw buffer, or None if it fails.""" + mib_arr = (ctypes.c_int * len(mib))(*mib) + size = ctypes.c_size_t(0) + ret = libc().sysctl(mib_arr, len(mib), None, ctypes.byref(size), None, 0) + if ret != 0 or size.value == 0: + return None + buf = ctypes.create_string_buffer(size.value) + ret = libc().sysctl(mib_arr, len(mib), buf, ctypes.byref(size), None, 0) + if ret != 0: + return None + return buf.raw[: size.value] + + +def _self_kinfo(): + """Return this process's own kinfo_proc, only if both offsets verify. + + The buffer read for os.getpid() must carry os.getpid() at P_PID_OFF and + os.getppid() at E_PPID_OFF. If either read disagrees, the layout + assumption is wrong on this system and every ppid_of() call that uses + these offsets returns None instead. + """ + buf = _sysctl((CTL_KERN, KERN_PROC, KERN_PROC_PID, os.getpid())) + if buf is None or len(buf) < E_PPID_OFF + 4: + return None + if struct.unpack_from(" 4096: + return None + strings = buf[4:].split(b"\0") + if not strings or not strings[0]: + return None + argv = [] + collecting = False + for raw in strings[1:]: + if not collecting: + if not raw: + continue # padding between the exec path and argv[0] + collecting = True + argv.append(raw) + if len(argv) == argc: + return argv + return None + + +def _ps_visible(raw): + result = [] + for byte in raw: + if byte >= 128: + result.append("M-") + byte -= 128 + if byte < 32 or byte == 127: + result.append("^" + chr(byte ^ 64)) + else: + result.append(chr(byte)) + return "".join(result) + + +def main(): + if len(sys.argv) != 2 or not sys.argv[1].isdigit(): + print("usage: fm-procinfo.py ", file=sys.stderr) + return 2 + pid = int(sys.argv[1]) + verified = _self_kinfo() + ppid = ppid_of(pid, verified) + if ppid is None: + return 1 + argv = _procargs(pid) + if not argv or not argv[0]: + # No argv means no identity. ps gets its comm/args from this + # same region, so a process unreadable here is unreadable + # there - substituting a resolved path from elsewhere would + # hand the two routes different facts about one process. + return 1 + comm = _ps_visible(argv[0]) + while argv and not argv[-1]: + argv.pop() + args = _ps_visible(b" ".join(argv)) + sys.stdout.write("%d\t%s\t%s\n" % (ppid, comm, args)) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/bin/fm-session-lock-lib.sh b/bin/fm-session-lock-lib.sh index cdf95c3d80e..391496faf21 100644 --- a/bin/fm-session-lock-lib.sh +++ b/bin/fm-session-lock-lib.sh @@ -11,6 +11,9 @@ # Claude session id below matches the id recorded beside a live lock. Neither # signal ever fails open: no id, no sidecar, an untrusted id, or a different # recorded id leaves the ancestry verdict exactly as it was. +# A second decision is owned here too: fm_session_lock_pid_blocks_reclaim +# answers whether a recorded owner may be reclaimed, so recovery callers +# delegate that question instead of re-deriving liveness from the fields. # This file is sourced by scripts and has no side effects on source. # Cursor process identity is NOT expressible as a command-name pattern and is @@ -272,6 +275,288 @@ fm_win_harness_ancestry_pids() { return 1 } +# --- one field reader, ps primary, ps-free route as fallback ----------------- +# Every identity read of a live process in THIS FILE (comm, args, ppid) +# goes through fm_proc_info below, so the denied-ps fallback has exactly +# one place to apply here. The verdict rules never change: the fallback +# changes only which route the same kernel facts arrive by, and both +# routes report the same fields - macOS identity comes from the argv +# region because that is what `ps -o comm=` and `ps -o args=` report +# there, and a route that read a different fact would let the two +# routes hand one process two different verdicts. +# +# This guarantee is per-file on purpose. The sibling walkers in +# bin/fm-harness.sh, bin/fm-backend.sh, bin/fm-sessionstart-nudge.sh, +# and bin/fm-branch-outcome.sh own their own ancestry reads and still +# require an executable ps; a denied-ps host stays degraded there +# until they route through a shared provider (follow-up). + +# One stderr line per shell that runs identity reads when the denied-ps +# route cannot answer. AGENTS.md session-start contract: a lock refusal +# owes its exact diagnostic - but a 16-hop walk over a dead provider +# must not print 48 lines, so the first cause wins and the rest stay +# silent in that shell. The provider is read through a command +# substitution, so a flag it sets dies with that subshell; fm_proc_info +# spends this guard in the shell that owns the walk, which is the only +# place it can persist. A walk that itself runs inside $(...) therefore +# keeps a private guard, so one run whose reads span several subshells +# can report the same cause once per such shell. +FM_OS_PROC_DIAG_SHOWN='' +fm_os_proc_diag_once() { # + if [ -z "$FM_OS_PROC_DIAG_SHOWN" ]; then + FM_OS_PROC_DIAG_SHOWN=1 + printf 'fm-session-lock: %s\n' "$1" >&2 + fi + return 0 +} + +# Parse one Linux "/proc//stat" line ($1, format " () +# ...") plus its already-NUL-flattened cmdline ($2) into +# "TABTAB". Pure seam: a saved stat line drives it +# identically on any host, which is why the parsing lives here. +fm_linux_stat_triple() { # + local line=$1 args=$2 rest comm ppid + # stat_fields, like the /proc//stat readers in + # bin/fm-remote-job-lib.sh and bin/fm-teardown.sh: ShellCheck follows + # sources, and bin/backends/rex.sh assigns a string to `fields`, so an + # array of that name here trips SC2178/SC2128 over there. + case $line in + *"("*") "*) ;; + *) return 1 ;; + esac + # comm may contain spaces and parentheses, so cut the rest off the + # LAST ") ", not the first. TAB/CR/LF are the record's delimiters, + # so flatten them out of the field the kernel lets name anything. + # Only C0 controls and DEL become '?': procps preserves valid UTF-8, + # and a live owner installed under a non-ASCII path (for example + # /home/José/.local/bin/agent) must keep the bytes ps reports, or its + # identity stops matching and the lock becomes reclaimable. + comm=${line#*(} + comm=${comm%*) *} + comm=$(printf '%s' "$comm" | LC_ALL=C tr '\012' ' ' | LC_ALL=C tr -c '\040-\176\200-\377' '?') + rest=${line##*") "} + local -a stat_fields + IFS=' ' read -r -a stat_fields <<< "$rest" + ppid=${stat_fields[1]:-} + case $ppid in + '' | *[!0-9]*) return 1 ;; + esac + printf '%s\t%s\t%s\n' "$ppid" "$comm" "$args" +} + +# OS provider for one pid: prints "TABTAB", or returns 1. +# Called only when the ps binary itself cannot execute. Tests override this +# whole function to drive a deterministic table. +fm_os_proc_triple() { # + local proc_root stat_line args element count rc=0 + local -a argv + case "$(uname -s 2>/dev/null)" in + Linux) + # The repo's other /proc readers (bin/fm-cursor-lib.sh, + # bin/fm-wake-lib.sh, bin/fm-teardown.sh) all take + # FM_PROC_ROOT_OVERRIDE so a fixture tree can drive them; this + # reader honors the same hook for the same reason. + proc_root=${FM_PROC_ROOT_OVERRIDE:-/proc} + [ -r "$proc_root/$1/stat" ] || return 1 + stat_line=$(cat "$proc_root/$1/stat" 2>/dev/null) || return 1 + [ -r "$proc_root/$1/cmdline" ] || return 1 + args=$( + argv=() + count=0 + while IFS= read -r -d '' element; do + argv[count]=$element + count=$((count + 1)) + done < "$proc_root/$1/cmdline" || exit 1 + while [ "$count" -gt 0 ] && [ -z "${argv[$((count - 1))]}" ]; do + unset 'argv[count - 1]' + count=$((count - 1)) + done + if [ "$count" -gt 0 ]; then + IFS=' ' + # Same byte rule as fm_linux_stat_triple: flatten only the + # record's control delimiters, keep the bytes ps preserves. + printf '%s' "${argv[*]}" | LC_ALL=C tr '\012' ' ' | LC_ALL=C tr -c '\040-\176\200-\377' '?' + fi + ) || return 1 + fm_linux_stat_triple "$stat_line" "$args" + ;; + Darwin) + # bin/fm-procinfo.py reads ppid through a self-verified + # KERN_PROC_PID chain and identity (comm/args) through the + # KERN_PROCARGS2 argv region - the same region ps reports, which + # is what keeps the two routes one fact per field. python3 is an + # optional toolchain member (Herdr ordering already depends on + # it); without it the denied-ps route degrades to today's + # fail-closed refusal rather than to a guess. + if ! command -v python3 >/dev/null 2>&1; then + fm_os_proc_diag_once 'ps cannot execute and no python3 is available for the ps-free identity provider; identity reads fail closed' + return 1 + fi + python3 "$(dirname -- "${BASH_SOURCE[0]}")/fm-procinfo.py" "$1" 2>/dev/null || rc=$? + if [ "$rc" -ne 0 ]; then + fm_os_proc_diag_once "ps cannot execute and the ps-free identity provider exited $rc; identity reads fail closed. Reproduce with: python3 $(dirname -- "${BASH_SOURCE[0]}")/fm-procinfo.py $1" + fi + return "$rc" + ;; + *) + return 1 + ;; + esac +} + +# Confirm once per process run that the ps BINARY cannot execute, the +# only environment this fallback exists for. A lone call's 126/127 can +# also come from a sandbox acting on that single call, and an actual +# binary block refuses every call including `ps -V`; only the second +# justifies routing identity off ps. The probe result is cached, so a +# refused walk of 16 pids costs one probe. (Busybox-era ps -V failures +# would read as "ps works" and keep the stop - the price of requiring +# positive proof of the denial.) +_fm_ps_exec_denied() { + local rc=0 + if [ -n "${_FM_PS_EXEC_DENIED+x}" ]; then + if [ "$_FM_PS_EXEC_DENIED" = 1 ]; then + return 0 + fi + return 1 + fi + ps -V >/dev/null 2>&1 || rc=$? + case $rc in + 126 | 127) _FM_PS_EXEC_DENIED=1 ;; + *) _FM_PS_EXEC_DENIED=0 ;; + esac + if [ "$_FM_PS_EXEC_DENIED" = 1 ]; then + return 0 + fi + return 1 +} + +# Read the identity fields of pid $1 into FM_PROC_COMM, FM_PROC_ARGS, and +# FM_PROC_PPID. +# +# ps stays primary everywhere it runs: while it executes, its output is +# used verbatim, so behavior is byte-identical to every session that ever +# worked. Only a ps that cannot execute at all - bash exits 126 for a +# refused exec, 127 for a missing binary - routes one read to the OS provider. +# Status 1 is platform-specific: Linux/macOS mean ps ran and named nothing; +# on Cygwin-family hosts it means ps refused the unsupported -o option and the +# fixed-column readers below are used instead. This exists because an +# EDR-style policy can deny the ps binary's exec itself (observed: +# /bin/ps refused even for `ps -V`, while kill, head, sysctl, pgrep, and +# lsof all ran) while every fact the identity walk needs remains readable +# through /proc or the kernel syscalls. +# +# Returning 1 means "no route can read this pid", which stops a walk +# exactly as a dead pid always has: nothing here ever fabricates a field. +fm_proc_info() { # + local pid=$1 rc=0 out comm args ppid + FM_PROC_COMM='' FM_PROC_ARGS='' FM_PROC_PPID='' + out=$(ps -o comm= -p "$pid" 2>/dev/null) || rc=$? + case $rc in + 0) ;; + 1) + # Linux/macOS: ps ran and named nothing. Cygwin-family: ps refused + # -o, so use its fixed-column readers only on that platform route. + fm_win_boundary_applies || return 1 + comm=$(fm_ps_comm "$pid") || return 1 + args=$(fm_ps_args "$pid") || return 1 + ppid=$(fm_ps_ppid "$pid") || return 1 + case "$ppid" in ''|*[!0-9]*) return 1 ;; esac + FM_PROC_COMM=$comm FM_PROC_ARGS=$args FM_PROC_PPID=$ppid + return 0 + ;; + 126 | 127) + # Confirmed, once per process: only a ps binary that cannot + # execute at all justifies the second provider. + _fm_ps_exec_denied || return 1 + local triple f1 f2 f3 rest tab + tab=$'\t' + # Spend the diagnostic guard for this shell here, not in the + # command-substitution subshell that prints it: a cause line lives + # only on the provider's failure routes, so a failed read is exactly + # where that budget is used up in the shell the walk runs in. + triple=$(fm_os_proc_triple "$pid") || { + FM_OS_PROC_DIAG_SHOWN=1 + return 1 + } + # The provider record is one line with exactly three TAB-separated + # fields: . The field count is proved by + # rebuilding the record from the parsed fields and comparing it to + # the original, because a TAB is IFS whitespace: a record with a + # MISSING field would otherwise parse exactly like a record whose + # field is legitimately empty, and a truncated record would be + # half-parsed into a plausible but wrong identity. + # + # A comm or args field that is legitimately empty is a real answer + # and is reported as one. A live process whose comm was emptied, and + # a kernel thread with no cmdline, are both PRESENT processes; the + # routes must agree about that, because a present pid that reads as + # gone is a reclaimable lock. + case $triple in + *$'\n'*) return 1 ;; + esac + # The TAB is a literal, so it is matched through a quoted expansion + # rather than an unquoted one: an unquoted $tab inside ${...} is a + # pattern, and a TAB is a glob character that would match any + # character. The record is split on literal TABs, and the rebuild + # below compares literal strings. + f1=${triple%%"$tab"*} + rest=${triple#*"$tab"} + f2=${rest%%"$tab"*} + f3=${rest#*"$tab"} + case $f3 in + *"$tab"*) return 1 ;; + esac + if [ "$triple" = "$f1$tab$f2$tab$f3" ]; then + : + else + return 1 + fi + case $f1 in + '' | *[!0-9]*) return 1 ;; + esac + FM_PROC_PPID=$f1 FM_PROC_COMM=$f2 FM_PROC_ARGS=$f3 + return 0 + ;; + *) + # 126/127 above are the statuses that prove "ps could not + # execute at all". Anything else, including signal-killed 137, + # means ps gave no answer, and callers read + # a non-zero exactly as "this pid cannot be verified". + return 1 + ;; + esac + # ps ran and named nothing. That is a real answer about a real + # process - a live process whose comm was emptied is still a live + # process - so it must NOT read as "the pid is gone". The callers + # below each need this distinction: the ancestry walk stops either + # way, but fm_session_lock_inspect separates "gone" (stale) from + # "present but not classifiable" (unknown), and collapsing the two + # here would report a live, unreadable pid as reclaimable and let a + # fresh process take over a lock whose owner is still running. + # + # The empty comm is still reported, not invented: FM_PROC_COMM stays + # empty and the matcher below rejects it, exactly as it rejects a + # comm it does not recognise. + comm=$out + args=$(ps -o args= -p "$pid" 2>/dev/null) || return 1 + # The ppid is a walk input, not an identity field. The identity the + # matcher reads is comm and args, and both of those are fail-closed + # above; a ppid that cannot be read only ends the ancestry walk one + # hop early, which is the conservative direction - the walk finds no + # harness and the session refuses the lock rather than taking one it + # cannot prove. + # + # The base read the ppid the same tolerant way, and the repository's + # grok and kimi harness suites pin that: their stubbed ps answers + # comm= and args= and refuses every other question, so a ppid read + # that failed had to leave the identity intact. + ppid=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ') + case "$ppid" in ''|*[!0-9]*) ppid='' ;; esac + FM_PROC_COMM=$comm FM_PROC_ARGS=$args FM_PROC_PPID=$ppid + return 0 +} + # Walk the current process ancestry (up to 16 hops) and print this session's # contiguous verified-harness ancestry, innermost pid first. # @@ -291,11 +576,10 @@ fm_win_harness_ancestry_pids() { # session cannot be read off the ancestry at all, so the whole contiguous run is # reported and the callers below decide what they need from it. fm_harness_ancestry_pids() { - local pid=$$ comm args extending=0 printed=0 + local pid=$$ extending=0 printed=0 for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16; do - comm=$(fm_ps_comm "$pid") || break - args=$(fm_ps_args "$pid") - if fm_harness_process_matches "$comm" "$args"; then + fm_proc_info "$pid" || break + if fm_harness_process_matches "$FM_PROC_COMM" "$FM_PROC_ARGS"; then printf '%s\n' "$pid" printed=1 [ "$FM_HARNESS_IS_CLAUDE" -eq 1 ] || break @@ -303,7 +587,7 @@ fm_harness_ancestry_pids() { elif [ "$extending" -eq 1 ]; then break fi - pid=$(fm_ps_ppid "$pid") + pid=$FM_PROC_PPID # Examine the top of the chain before stopping. Inside a PID namespace the # harness itself is pid 1, so stopping as soon as the next pid is 1 hides the # very process this walk exists to find. A host's real pid 1 (init, systemd, @@ -356,21 +640,63 @@ EOF return 1 } +# Classify session-lock pid $1, setting FM_SESSION_LOCK_PID_VERDICT to one of: +# readable - the identity was read into FM_PROC_COMM and FM_PROC_ARGS, plus +# FM_PROC_PPID for a numeric pid (a tagged pid has no local parent). +# dead - nothing can see the pid, or the Windows table proves it absent. +# unknown - the process exists but this session cannot signal it. +# unreadable - it may well be alive but its identity could not be read; also +# the value left for a local pid that never gets classified +# (empty, non-numeric, or the literal zero). +# Only "readable" answers an identity question; the other three carry no +# identity, and the two rules below own what each one means for ownership and +# for recovery: fm_harness_pid_alive and fm_session_lock_pid_blocks_reclaim. +fm_session_lock_pid_verdict() { + local pid=$1 winpid rc=0 comm + FM_SESSION_LOCK_PID_VERDICT=unreadable + if winpid=$(fm_win_untag_pid "$pid"); then + comm=$(fm_win_command "$winpid") || rc=$? + case $rc in + 0) FM_PROC_COMM=$comm FM_PROC_ARGS=$comm FM_PROC_PPID=; FM_SESSION_LOCK_PID_VERDICT=readable ;; + 1) FM_SESSION_LOCK_PID_VERDICT=dead ;; + esac + return 0 + fi + case "$pid" in ''|*[!0-9]*|0) return 0 ;; esac + # Liveness first, identity second. A pid this session cannot signal is + # not a live owner it may reclaim over; a pid it CAN signal is alive, + # and only then is its identity worth reading. Asking the identity + # first would let a stale process-table entry report a dead owner as + # live and keep a stale lock from ever being reclaimed - the same + # permanent read-only wedge this change exists to remove. + if kill -0 "$pid" 2>/dev/null; then + # Alive. Its identity may still be unreadable, and that is the case + # this verdict exists for: the owner is live, so its lock must not + # be reclaimed. + if fm_proc_info "$pid"; then + FM_SESSION_LOCK_PID_VERDICT=readable + fi + elif fm_proc_info "$pid"; then + # The process exists - this session simply may not signal it - so + # it is not a dead owner, but it is not a harness this session can + # prove either. The base contract treats that as "no live harness + # owner", and the lock stays reclaimable. + FM_SESSION_LOCK_PID_VERDICT=unknown + else + # Nothing can see the pid: it is gone. + FM_SESSION_LOCK_PID_VERDICT=dead + fi + return 0 +} + # True if $1 is a live process that looks like a verified harness. # A tagged Windows pid is answered from the Windows process table, because # kill -0 cannot see across that boundary and would report a live harness as # dead - which would hand a running session's home to a second one. fm_harness_pid_alive() { - local pid=$1 comm args winpid - if winpid=$(fm_win_untag_pid "$pid"); then - comm=$(fm_win_command "$winpid") || return 1 - fm_harness_process_matches "$comm" "$comm" - return - fi - kill -0 "$pid" 2>/dev/null || return 1 - comm=$(fm_ps_comm "$pid") || return 1 - args=$(fm_ps_args "$pid") - fm_harness_process_matches "$comm" "$args" + fm_session_lock_pid_verdict "$1" + [ "$FM_SESSION_LOCK_PID_VERDICT" = readable ] || return 1 + fm_harness_process_matches "$FM_PROC_COMM" "$FM_PROC_ARGS" } # Liveness and identity of a session-lock pid for readers outside this file: @@ -401,6 +727,36 @@ fm_session_pid_identity() { # fm_pid_identity "$1" } +# True when session-lock pid $1 must not be reclaimed: a readable harness owner +# that still matches holds the lock, and an unreadable-but-live owner is refused +# rather than guessed at. A dead record, a reused pid whose readable identity is +# not a verified harness, a malformed or all-zero record, and an owner this +# session can read but cannot signal are all reclaimable. +# +# The all-zero form is refused here rather than in the shared +# fm_session_pid_valid, because that predicate answers "is this value usable at +# all" for readers that must keep accepting any numeric record, and because zero +# is not a process identity: `kill -0 00` signals process group 0, so treating it +# as an owner wedges the home read-only instead of reclaiming it. This test is +# string-only on purpose - arithmetic or numeric normalization would let octal +# interpretation, integer overflow, or an arbitrarily long digit string change a +# verdict. +fm_session_lock_pid_blocks_reclaim() { + fm_session_pid_valid "$1" || return 1 + case "$1" in + "$FM_WIN_PID_PREFIX"*) ;; + *[1-9]*) ;; + *) return 1 ;; + esac + fm_session_lock_pid_verdict "$1" + case "$FM_SESSION_LOCK_PID_VERDICT" in + dead) return 1 ;; + unreadable) return 0 ;; + unknown) return 1 ;; + readable) fm_harness_process_matches "$FM_PROC_COMM" "$FM_PROC_ARGS" ;; + esac +} + # --- trusted same-session identity ------------------------------------------- # Claude Code hands every hook and tool shell CLAUDE_CODE_SESSION_ID (the # session's conversation id) and CLAUDE_PID (the pid of the process running the @@ -430,7 +786,7 @@ fm_session_pid_identity() { # # ancestry list an earlier walk already produced, so a caller that walked once # need not walk again. fm_session_lock_trusted_session_id() { # [] - local id=${CLAUDE_CODE_SESSION_ID:-} claude_pid=${CLAUDE_PID:-} pids=${1:-} pid comm args + local id=${CLAUDE_CODE_SESSION_ID:-} claude_pid=${CLAUDE_PID:-} pids=${1:-} pid [ -n "$id" ] || return 1 case "$id" in *$'\n'*|*$'\r'*) return 1 ;; esac case "$claude_pid" in ''|*[!0-9]*) return 1 ;; esac @@ -442,9 +798,8 @@ fm_session_lock_trusted_session_id() { # [] # from CLAUDE_PID and this same id, so it is matched in that form. case "$pid" in "$claude_pid") - comm=$(ps -o comm= -p "$pid" 2>/dev/null) || return 1 - args=$(ps -o args= -p "$pid" 2>/dev/null) - fm_harness_process_matches "$comm" "$args" || return 1 + fm_proc_info "$pid" || return 1 + fm_harness_process_matches "$FM_PROC_COMM" "$FM_PROC_ARGS" || return 1 ;; "$FM_WIN_PID_PREFIX$claude_pid") fm_harness_pid_alive "$pid" || return 1 @@ -525,9 +880,11 @@ fm_session_lock_owned_by_self() { fm_harness_pid_alive "$lock_pid" } -# True when state dir $1 records a live verified harness outside this process's -# contiguous harness ancestry that was not recorded by this same trusted Claude -# session. Sets FM_SESSION_LOCK_FOREIGN_OWNER_PID for a diagnostic caller. +# True when state dir $1 records a lock owner outside this process's contiguous +# harness ancestry that this session must not reclaim and did not record under +# its own trusted Claude session id - a live verified harness, or a live owner +# whose identity cannot be read. Sets FM_SESSION_LOCK_FOREIGN_OWNER_PID for a +# diagnostic caller. # Malformed, missing, dead, and ancestry-uncertain locks are not foreign-owner # evidence. # shellcheck disable=SC2034 # Output global, read by the sourcing guard caller. @@ -538,7 +895,7 @@ fm_session_lock_foreign_owner_live() { [ -f "$state/.lock" ] && [ ! -L "$state/.lock" ] || return 1 lock_pid=$(cat "$state/.lock" 2>/dev/null || true) fm_session_pid_valid "$lock_pid" || return 1 - fm_harness_pid_alive "$lock_pid" || return 1 + fm_session_lock_pid_blocks_reclaim "$lock_pid" || return 1 pids=$(fm_harness_ancestry_pids) || return 1 fm_harness_pid_listed "$lock_pid" "$pids" && return 1 fm_session_lock_same_session "$state" "$pids" && return 1 @@ -566,7 +923,7 @@ FM_LOCK_INSPECT_STATE=unknown FM_LOCK_INSPECT_PID= FM_LOCK_INSPECT_LIVE_HARNESS=unknown fm_session_lock_inspect() { # - local state=$1 lock pid winpid win_rc + local state=$1 lock pid # shellcheck disable=SC2034 # Output globals, read by lock status and inbox ready. FM_LOCK_INSPECT_STATE=unknown # shellcheck disable=SC2034 # Output globals, read by lock status and inbox ready. @@ -591,40 +948,28 @@ fm_session_lock_inspect() { # # shellcheck disable=SC2034 # Output global, read by lock status and inbox ready. FM_LOCK_INSPECT_PID=$pid fm_session_pid_valid "$pid" || return 0 - if winpid=$(fm_win_untag_pid "$pid"); then - # The same verdicts as a local pid below, read from the Windows table. - if fm_harness_pid_alive "$pid"; then - FM_LOCK_INSPECT_STATE=held - FM_LOCK_INSPECT_LIVE_HARNESS=true - return 0 - fi - win_rc=0 - fm_win_command "$winpid" >/dev/null || win_rc=$? - case "$win_rc" in - 0) FM_LOCK_INSPECT_LIVE_HARNESS=false ;; - 1) - FM_LOCK_INSPECT_STATE=stale - FM_LOCK_INSPECT_LIVE_HARNESS=false - ;; - esac - return 0 - fi - if kill -0 "$pid" 2>/dev/null; then - if fm_harness_pid_alive "$pid"; then - FM_LOCK_INSPECT_STATE=held - FM_LOCK_INSPECT_LIVE_HARNESS=true - else - FM_LOCK_INSPECT_STATE=unknown + # One verdict for every identity form. A tagged Windows pid is resolved by + # this same call through the Windows table, so the match below is the single + # place "live verified harness" is decided; deciding it a second time ahead + # of this one is what let a holder read as held there and unknown here. + fm_session_lock_pid_verdict "$pid" + case "$FM_SESSION_LOCK_PID_VERDICT" in + dead) + # shellcheck disable=SC2034 # Output globals, read by lock status and inbox ready. + FM_LOCK_INSPECT_STATE=stale + # shellcheck disable=SC2034 # Output globals, read by lock status and inbox ready. FM_LOCK_INSPECT_LIVE_HARNESS=false - fi - return 0 - fi - if ps -o comm= -p "$pid" >/dev/null 2>&1; then - FM_LOCK_INSPECT_STATE=unknown - return 0 - fi - # shellcheck disable=SC2034 # Output global, read by lock status and inbox ready. - FM_LOCK_INSPECT_STATE=stale - # shellcheck disable=SC2034 # Output global, read by lock status and inbox ready. - FM_LOCK_INSPECT_LIVE_HARNESS=false + ;; + readable) + if fm_harness_process_matches "$FM_PROC_COMM" "$FM_PROC_ARGS"; then + # shellcheck disable=SC2034 # Output globals, read by lock status and inbox ready. + FM_LOCK_INSPECT_STATE=held + # shellcheck disable=SC2034 # Output globals, read by lock status and inbox ready. + FM_LOCK_INSPECT_LIVE_HARNESS=true + else + # shellcheck disable=SC2034 # Output global, read by lock status and inbox ready. + FM_LOCK_INSPECT_LIVE_HARNESS=false + fi + ;; + esac } diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh index cddcbf9f93a..28dd780026d 100755 --- a/bin/fm-test-run.sh +++ b/bin/fm-test-run.sh @@ -899,6 +899,7 @@ tests/fm-send-resolve-key.test.sh 47317 tests/fm-send-secondmate-marker-herdr-e2e.test.sh 80 tests/fm-send-secondmate-marker.test.sh 7574 tests/fm-session-lock-ancestry.test.sh 18918 +tests/fm-session-lock-ps-denied.test.sh 3012 tests/fm-session-start.test.sh 363574 tests/fm-sessionstart-hook-live-e2e.test.sh 50 tests/fm-sessionstart-instruction-refresh-live-e2e.test.sh 49 diff --git a/bin/fm-turnend-guard-cursor.sh b/bin/fm-turnend-guard-cursor.sh index 1baf52f9add..613a8e36b1e 100755 --- a/bin/fm-turnend-guard-cursor.sh +++ b/bin/fm-turnend-guard-cursor.sh @@ -262,14 +262,14 @@ current_session_still_ours() { fm_session_lock_owned_by_self "$STATE" } -# Only the lock-owning session may arm or wake. A prior session that died -# leaving its harness identity behind, a local pid or a Windows-tagged one, is -# the one recoverable case, delegated to bin/fm-lock.sh so acquisition keeps its -# single owner. +# Only the lock-owning session may arm or wake. The shared +# fm_session_lock_pid_blocks_reclaim verdict decides whether a recorded owner may +# be reclaimed, and any reclaim is delegated to bin/fm-lock.sh so acquisition +# keeps its single owner. if ! fm_session_lock_owned_by_self "$STATE"; then LOCK_PID=$(cat "$STATE/.lock" 2>/dev/null || true) fm_session_pid_valid "$LOCK_PID" || exit 0 - fm_harness_pid_alive "$LOCK_PID" && exit 0 + fm_session_lock_pid_blocks_reclaim "$LOCK_PID" && exit 0 "$SCRIPT_DIR/fm-lock.sh" >/dev/null 2>&1 || exit 0 fm_session_lock_owned_by_self "$STATE" || exit 0 fi diff --git a/bin/fm-turnend-guard.sh b/bin/fm-turnend-guard.sh index dee66fde393..4a28d5f2357 100755 --- a/bin/fm-turnend-guard.sh +++ b/bin/fm-turnend-guard.sh @@ -66,7 +66,7 @@ # auto-arm (bin/fm-claude-stop-autoarm.sh), which fires on the same Stop event: # 1. a live identity-matched watcher with a fresh beacon - or, in away mode, a # live identity-matched daemon with a fresh beacon - allows immediately; -# 2. an unhealthy session with a verified live session-lock owner it does not +# 2. an unhealthy session with a live session-lock owner it does not # own under the shared ancestry-or-trusted-id verdict exits with a read-only # diagnostic instead of blocking a session that cannot repair supervision # without stealing ownership; @@ -315,9 +315,10 @@ block_stop() { exit 2 } -# Another verified live session owns the home lock under the shared -# ancestry-or-trusted-id verdict. This session is read-only and cannot arm or -# repair supervision without +# Another live session owns the home lock under the shared +# `fm_session_lock_pid_blocks_reclaim` verdict and is neither this session's +# harness ancestry nor its trusted id. +# This session is read-only and cannot arm or repair supervision without # stealing ownership, so blocking its Stop would create an impossible loop. # Report the ownership conflict as a diagnostic and let this turn end safely; # the owning session remains responsible for restoring the watcher. diff --git a/docs/configuration.md b/docs/configuration.md index ebd7f6a2be0..dcc8cde349e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -3292,7 +3292,7 @@ FM_STATE_OVERRIDE= # alternate state dir, mainly for tests FM_DATA_OVERRIDE= # alternate data dir, mainly for tests FM_PROJECTS_OVERRIDE= # alternate projects dir, mainly for tests FM_CONFIG_OVERRIDE= # alternate config dir, mainly for tests -FM_PROC_ROOT_OVERRIDE= # alternate /proc root for Linux process-identity reads in fm-wake-lib.sh and fm-teardown.sh, mainly for tests +FM_PROC_ROOT_OVERRIDE= # alternate /proc root for Linux process-identity readers, mainly for tests FM_BACKEND= # optional runtime backend override for new spawns; tmux/herdr/zellij/orca/cmux/paseo/rex/t3code/tern support ship/scout spawns, codex-app is not accepted FM_T3CODE_ORIGIN= # optional T3 Code server origin for bin/fm-t3-mcp.mjs login; the default is read from ~/.t3/userdata/server-runtime.json FM_TRACE_CONTEXT= # optional trace-context override; see "Trace context propagation" diff --git a/docs/scripts.md b/docs/scripts.md index 59def3cbe1d..384826c94bf 100644 --- a/docs/scripts.md +++ b/docs/scripts.md @@ -53,7 +53,8 @@ The shared no-mistakes gate lifecycle boundary is summarized in [architecture.md | `fm-capacity.sh` | Report of open lanes against the optional `config/lane-capacity` target and host headroom for queued-work dispatch; `--publish` writes this home's `state/lane-capacity.json` | | `fm-guard.sh` | Warn on primary-checkout tangles, main-session pending wakes, and unhealthy supervision | | `fm-primary-scope-lib.sh` | Shared marker-or-plain-checkout primary-home predicate for tracked hooks | -| `fm-session-lock-lib.sh` | Shared session-lock ownership from harness ancestry, a trusted Claude session id, or on Windows/Git Bash a published harness pid, for fm-lock.sh and the Claude Stop auto-arm, plus the read-only lock inspection behind `fm-lock.sh status` and `fm-inbox.sh ready` | +| `fm-session-lock-lib.sh` | Shared session-lock ownership from harness ancestry, a trusted Claude session id, or on Windows/Git Bash a published harness pid, for fm-lock.sh and the Claude Stop auto-arm, plus the reclaim verdict recovery callers apply, the ps-free identity fallback behind it, and the read-only lock inspection behind `fm-lock.sh status` and `fm-inbox.sh ready` | +| `fm-procinfo.py` | Read one pid's ppid, comm, and args through macOS kernel syscalls when the `ps` binary cannot execute | | `fm-claude-stop-autoarm.sh` | Claude Stop `asyncRewake` hook owning tokenless watcher continuity with single-flight exit-2 rewake (docs/watcher-continuity.md) | | `fm-turnend-guard.sh` | Shared primary turn-end guard predicate so no turn ends blind (docs/turnend-guard.md) | | `fm-turnend-guard-grok.sh` | Grok Stop-hook adapter for the primary turn-end guard | diff --git a/docs/sessionstart-nudge.md b/docs/sessionstart-nudge.md index 250c9b8daf8..b21eb2b60d0 100644 --- a/docs/sessionstart-nudge.md +++ b/docs/sessionstart-nudge.md @@ -211,6 +211,7 @@ It does this in its own separate, hard-coded loop, independent of two other owne - Pi's `lockOwnership()`. If the lock names a live pid in that ancestry, session start already ran in this harness session and the wrapper stays silent. +That loop reads each parent link through the `ps` binary, so a host that refuses `ps` cannot confirm a numeric lock's ancestry and the wrapper prints the nudge even for a session that already holds the lock. On Windows/Git Bash, a lock holding a tagged `win:` identity is outside this process table, so the wrapper instead asks the library's `fm_session_lock_owned_by_self`, whose Windows process-boundary bridge owns that identity. ### Exit codes diff --git a/docs/turnend-guard.md b/docs/turnend-guard.md index 689faa219ca..58f841d0db5 100644 --- a/docs/turnend-guard.md +++ b/docs/turnend-guard.md @@ -97,7 +97,7 @@ The guard cooperates with that arm rather than trusting a beacon left by the cyc ### Foreign session-lock owner -When an active home instead has a live session lock held by a verified harness that the current session does not own, the Claude guard emits a read-only ownership diagnostic and allows the turn to end safely. +When an active home instead has a session lock that the current session does not own and the shared `fm_session_lock_pid_blocks_reclaim` verdict refuses to reclaim, the Claude guard emits a read-only ownership diagnostic and allows the turn to end safely. Ownership is the shared `fm_session_lock_owned_by_self` verdict in `bin/fm-session-lock-lib.sh`. The current session owns the lock when either of these holds: @@ -429,7 +429,7 @@ The block budget is charged by two rules: That second rule still bounds an inert auto-arm when a hook never fires or fails before its generation claim and therefore leaves the ledger frozen at its last outcome. Charging only epoch changes let the count freeze with that ledger, so the remaining inert-hook cases could re-block without limit and make the attended fail-open unreachable. `budget_account_current_epoch` in `bin/fm-turnend-guard.sh` owns the rule. -A verified live foreign session-lock owner takes the earlier diagnostic safe exit instead and never reaches this budget path. +A live foreign session-lock owner takes the earlier diagnostic safe exit instead and never reaches this budget path. Whenever both coordination locks are needed, positive auto-arm recovery, the terminal check, and the auto-arm's attended-alarm commit acquire the auto-arm owner lock before the budget lock. #### Attended fail-open diff --git a/docs/watcher-continuity.md b/docs/watcher-continuity.md index 7fd4464b82d..a1ce484c1a1 100644 --- a/docs/watcher-continuity.md +++ b/docs/watcher-continuity.md @@ -94,8 +94,11 @@ While supervision is still needed and away mode remains inactive, an actionable The hook handles the session lock as follows: -- A session-lock owner, including a tagged `win:` holder on Windows/Git Bash, that fails the shared `fm_harness_pid_alive` predicate is reclaimed through `bin/fm-lock.sh` before auto-arm state changes. -- A live owner the session does not own, an absent lock, or an unusable lock keeps the competing hook inert. +- A well-formed session-lock owner is a numeric PID, or a tagged `win:` value on a Cygwin-family Git Bash host. + The shared `fm_session_lock_pid_blocks_reclaim` verdict in `bin/fm-session-lock-lib.sh` is the one decision every recovery caller applies to that identity: an all-zero, proven-dead, reused non-harness, or live-but-unsignalable record stays reclaimable, while a readable verified harness and a live owner whose identity cannot be read keep recovery inert. + That library also owns the process-info fallback used when the `ps` binary cannot execute. +- An absent lock keeps the competing hook inert: with no recorded owner there is nothing stale to recover. +- A malformed, empty, or otherwise unusable record is not an identity, so it never reaches that verdict: the competing hook stays inert, and a later `bin/fm-lock.sh` acquisition replaces the record. Whether the session owns that lock is the shared `fm_session_lock_owned_by_self` verdict in `bin/fm-session-lock-lib.sh`. That verdict accepts either of two cases: @@ -530,6 +533,7 @@ It checks that a newly appended keyed decision is classified without rereading e - Supersession of a dead session's orphaned claim by the replacement session's first Stop, including a resumed session that carries the dead one's conversation id, and a claim with no readable session lock. - A recycled background bridge keeping its live claim on the trusted session id pinned to the lock holder's recorded session-lock identity. - The Windows/Git Bash session-lock readers for the supervision-host key, claim read-back, and mid-turn health, plus untagged-value parity with the numeric helpers, in `tests/fm-session-lock-windows-consumers.test.sh`. +- The ps-free identity route and its fail-closed refusals when the `ps` binary cannot execute, in `tests/fm-session-lock-ps-denied.test.sh`. - Bounded failure retries. - Benign live-watcher cycle ends. - One-notice failure episodes. diff --git a/tests/fm-session-lock-ancestry.test.sh b/tests/fm-session-lock-ancestry.test.sh index 44a18352e72..bea82f5d8dc 100755 --- a/tests/fm-session-lock-ancestry.test.sh +++ b/tests/fm-session-lock-ancestry.test.sh @@ -626,6 +626,84 @@ test_windows_tagged_holder_is_a_live_foreign_owner() { pass "session-lock: a live tagged lock holder is a live foreign owner to a second Windows session" } +test_windows_tagged_lock_acquisition_uses_the_shared_owner_verdict() { + local dir fakebin home current_row live_table dead_table reused_table out status record + dir="$TMP_ROOT/win-lock-acquire" + fakebin=$(cygwin_fakebin "$dir") + home="$dir/home" + mkdir -p "$home/state" "$home/endpoints" "$home/bin" "$home/config" + git init -q "$home" + git -C "$home" commit -q --allow-empty -m fixture + : > "$home/AGENTS.md" + : > "$home/state/task.meta" + current_row=' 4201600 0 0 7300 ? 0 22:30:00 C:\Users\u\.local\bin\claude.exe' + live_table="$WIN_TABLE +$current_row" + dead_table=$current_row + reused_table=" 4201508 0 0 7204 ? 0 22:24:48 C:\\Windows\\explorer.exe +$current_row" + + attempt_lock() { # + local caller_pid=$1 caller_session=$2 table=$3 table_fails=$4 local_ppid=$5 + local -a assignments=() + assignments+=("PATH=$fakebin:$PATH" "FM_HOME=$home" "FM_TEST_WIN_TABLE=$table") + [ -z "$local_ppid" ] || assignments+=("FM_TEST_CYG_PPID=$local_ppid") + [ -z "$caller_pid" ] || assignments+=("CLAUDE_PID=$caller_pid" "CLAUDE_CODE_SESSION_ID=$caller_session") + [ "$table_fails" != 1 ] || assignments+=("FM_TEST_WIN_PS_FAIL=1") + env -u CLAUDE_PID -u CLAUDE_CODE_SESSION_ID -u FM_TEST_WIN_PS_FAIL -u FM_TEST_CYG_PPID \ + "${assignments[@]}" "$ROOT/bin/fm-lock.sh" + } + attempt_hook() { # + local script=$1 payload=$2 + printf '%s' "$payload" | env -u CLAUDE_PID -u CLAUDE_CODE_SESSION_ID \ + -u FM_TEST_WIN_PS_FAIL -u FM_TEST_CYG_PPID -u PI_CODING_AGENT -u CURSOR_AGENT -u CURSOR_INVOKED_AS \ + PATH="$fakebin:$PATH" FM_HOME="$home" FM_ROOT_OVERRIDE="$home" \ + FM_TEST_WIN_TABLE="$live_table" CLAUDE_PID=7300 CLAUDE_CODE_SESSION_ID=S2 \ + "$ROOT/bin/$script" + } + + printf 'win:7204\n' > "$home/state/.lock" + printf 'S1\n' > "$home/state/.lock-session" + if out=$(attempt_lock 7300 S2 "$live_table" 0 '' 2>&1); then status=0; else status=$?; fi + [ "$status" -eq 1 ] || fail "fm-lock.sh acquired a live tagged harness lock: $out" + case "$out" in *'another live firstmate session holds the lock'*) ;; *) fail "live tagged owner refusal was not reported: $out" ;; esac + [ "$(cat "$home/state/.lock")" = 'win:7204' ] || fail "a live tagged owner lock was replaced" + + if out=$(attempt_hook fm-claude-stop-autoarm.sh '' 2>&1); then status=0; else status=$?; fi + [ "$status" -eq 0 ] || fail "Stop recovery did not stand down for a live tagged owner: $out" + [ "$(cat "$home/state/.lock")" = 'win:7204' ] || fail "Stop recovery replaced a live tagged owner lock" + if out=$(attempt_hook fm-turnend-guard-cursor.sh '{"loop_count":0,"session_id":"S2"}' 2>&1); then status=0; else status=$?; fi + [ "$status" -eq 0 ] || fail "turn-end recovery did not stand down for a live tagged owner: $out" + [ "$(cat "$home/state/.lock")" = 'win:7204' ] || fail "turn-end recovery replaced a live tagged owner lock" + + printf 'win:7204\n' > "$home/state/.lock" + printf 'S1\n' > "$home/state/.lock-session" + if out=$(attempt_lock '' '' "$live_table" 1 700 2>&1); then status=0; else status=$?; fi + [ "$status" -eq 1 ] || fail "fm-lock.sh acquired through an unreadable Windows process table: $out" + [ "$(cat "$home/state/.lock")" = 'win:7204' ] || fail "an unreadable Windows table allowed the tagged owner lock to be replaced" + + printf 'win:7204\n' > "$home/state/.lock" + printf 'S1\n' > "$home/state/.lock-session" + if out=$(attempt_lock 7300 S2 "$dead_table" 0 '' 2>&1); then status=0; else status=$?; fi + [ "$status" -eq 0 ] || fail "fm-lock.sh refused a tagged owner absent from the Windows table: $out" + [ "$(cat "$home/state/.lock")" = 'win:7300' ] || fail "a dead tagged owner was not replaced by the current session" + + printf 'win:7204\n' > "$home/state/.lock" + printf 'S1\n' > "$home/state/.lock-session" + if out=$(attempt_lock 7300 S2 "$reused_table" 0 '' 2>&1); then status=0; else status=$?; fi + [ "$status" -eq 0 ] || fail "fm-lock.sh refused a reused tagged pid naming a non-harness: $out" + [ "$(cat "$home/state/.lock")" = 'win:7300' ] || fail "a reused non-harness pid was not reclaimed" + + for record in '' ' ' not-a-pid 0 00 000 0000 win: win:7abc; do + printf '%s\n' "$record" > "$home/state/.lock" + printf 'S1\n' > "$home/state/.lock-session" + if out=$(attempt_lock 7300 S2 "$dead_table" 0 '' 2>&1); then status=0; else status=$?; fi + [ "$status" -eq 0 ] || fail "fm-lock.sh refused non-owner record '$record': $out" + [ "$(cat "$home/state/.lock")" = 'win:7300' ] || fail "non-owner record '$record' was not replaced" + done + pass "session-lock: fm-lock.sh protects valid tagged owners and reclaims dead or malformed records" +} + test_windows_published_pid_needs_its_claude_session_id() { local dir fakebin got dir="$TMP_ROOT/win-session-id" @@ -1576,6 +1654,7 @@ test_windows_published_pid_is_confirmed_before_it_is_trusted test_windows_pid_is_never_resolved_as_a_cygwin_pid test_a_published_identity_is_accepted_by_the_gates_that_read_the_lock test_windows_tagged_holder_is_a_live_foreign_owner +test_windows_tagged_lock_acquisition_uses_the_shared_owner_verdict test_windows_published_pid_needs_its_claude_session_id test_windows_clear_rekeys_the_lock_under_the_same_pid test_tagged_lock_is_inert_off_windows diff --git a/tests/fm-session-lock-ps-denied.test.sh b/tests/fm-session-lock-ps-denied.test.sh new file mode 100644 index 00000000000..6e49799c1ee --- /dev/null +++ b/tests/fm-session-lock-ps-denied.test.sh @@ -0,0 +1,979 @@ +#!/usr/bin/env bash +# tests/fm-session-lock-ps-denied.test.sh - the ps-free identity route. +# +# An EDR-style policy can deny the ps BINARY's exec (verified on a hardened +# macOS host: /bin/ps refused even `ps -V`, while kill/head/sysctl/pgrep/lsof +# ran), and before bin/fm-session-lock-lib.sh could fall back to an OS +# provider, that turned every session into a permanent lock-refused +# read-only one, because identity proof walked ancestry through ps. +# +# The unit cases drive the library behind a deterministic fake ps that +# refuses to run (exit 126, bash's refused-exec status) plus a fake OS +# provider, covering the fallback decision table on any host. The e2e case +# blocks ps from a REAL process tree (fake ps on PATH) and resolves a real +# pid through the REAL platform provider, so a regression that only fakes +# would miss is caught here. +# shellcheck disable=SC2016 # single quotes are deliberate where they expand inside the fixture child +set -u + +# shellcheck source=tests/lib.sh +. "$(dirname "${BASH_SOURCE[0]}")/lib.sh" + +TMP_ROOT=$(fm_test_tmproot fm-session-lock-ps-denied) + +LIB="$ROOT/bin/fm-session-lock-lib.sh" + +# A denied ps: refuses to run at all, exactly like the blocked binary. +make_denied_ps() { # + local fakebin=$1 + cat > "$fakebin/ps" <<'SH' +#!/usr/bin/env bash +echo "$0: Operation not permitted" >&2 +exit 126 +SH + chmod +x "$fakebin/ps" +} + +# Run one library expression with a denied ps shadowing PATH and a table +# provider. The table reads FM_TEST_TRIPLE_N records (fake table rows +# "|||"); a pid absent from the table is unreadable, +# which is how a dead pid behaves. FM_TEST_KILL_RC decides kill as before. +# CLAUDE identity envs are scrubbed the same way the ancestry suite scrubs +# them, so a suite running inside a real Claude session cannot leak in. +lib_eval_denied() { # + env -u CLAUDE_CODE_SESSION_ID -u CLAUDE_PID \ + FM_PROVIDER_FILE="$2" PATH="$1:$PATH" bash -c " + . \"\$0\" + kill() { return \${FM_TEST_KILL_RC:-0}; } + _emit_row() { # + local ppid rest comm args + ppid=\${1#*|}; ppid=\${ppid%%|*} + rest=\${1#*|}; rest=\${rest#*|} + comm=\${rest%%|*} + args=\${rest#*|} + printf '%s\t%s\t%s\n' \"\$ppid\" \"\$comm\" \"\$args\" + } + fm_os_proc_triple() { + local row + while IFS= read -r row; do + case \"\$row\" in + \"\$1|\"*) _emit_row \"\$row\"; return 0 ;; + esac + done < \"\$FM_PROVIDER_FILE\" + while IFS= read -r row; do + case \"\$row\" in + \"default|\"*) _emit_row \"\$row\"; return 0 ;; + esac + done < \"\$FM_PROVIDER_FILE\" + return 1 + } + $3 + " "$LIB" +} + +make_table() { # a version-free claude session at 700, under launchd; any + # other pid (the child bash the walk starts from) reports bash -> 700. + # Args stay neutral: a real-looking bash -c command naming python3 and a + # lib path would be matched as "interpreter running a harness script", + # which is the matcher being honest, not a bug. + local file="$TMP_ROOT/table.$$" + cat > "$file" <<'ROWS' +700|1|claude|claude --resume +1|0|launchd|/sbin/launchd +default|700|bash|bash run.sh +ROWS + printf '%s\n' "$file" +} + +# --- the fallback decision table --------------------------------------------- + +test_denied_route_fields_parse_exactly() { + # Pin every field the 126-route parse produces. The original table rows + # named claude in both identity fields, so a parse that swapped comm + # and args, or shifted a field, still passed the walk tests. An + # asymmetric record plus per-field assertions is what fails such a + # regression here. + local dir fakebin table got + dir="$TMP_ROOT/fields" + fakebin=$(fm_fakebin "$dir"); make_denied_ps "$fakebin" + table="$dir/t" + cat > "$table" <<'ROWS' +700|1|claude|/opt/tools/x --resume +ROWS + got=$(lib_eval_denied "$fakebin" "$table" \ + 'fm_proc_info 700 && printf "%s|%s|%s\n" "$FM_PROC_PPID" "$FM_PROC_COMM" "$FM_PROC_ARGS"') \ + || fail "126-route fm_proc_info refused a well-formed record" + [ "$got" = "1|claude|/opt/tools/x --resume" ] \ + || fail "126-route parse produced '$got', expected '1|claude|/opt/tools/x --resume'" + # A record whose ppid field is empty is malformed even when the rest + # reads fine, and must be refused rather than carried as a blank id. + cat > "$table" <<'ROWS' +5||bash|bash x +ROWS + if lib_eval_denied "$fakebin" "$table" 'fm_proc_info 5' >/dev/null 2>&1; then + fail "126-route accepted a record with an empty ppid field" + fi + pass "126-route parse assigns each field and refuses a blank ppid" +} + +check_shape_rejected() { #