feat: sync upstream main and harden session-lock identity

[ruby-dlee]

Intent

Sync the FirstMate fork with current official upstream main, retain only PID-reuse/Codex-app-server session-lock hardening and its documentation, keep the macOS gotmp fixture correction, remove browser isolation and duplicate review policy, and leave FirstMate stopped but ready to start.

What Changed

• Merged official upstream through 9ecd7c4, pulling in the upstream feature/fix train (bounded bearings snapshots, primary-shell cd guard, backend-independent wedge alerts, herdr/cmux backend hardening, watcher paused external-wait supervision, and the accompanying docs and tests).
• Hardened the per-home session lock: state/.lock now records the harness PID plus holder process start time on two lines, acquire/status treat it as held only when that PID is live with a matching start time and is not a Codex app-server (so PID reuse and app-server processes no longer count as live holders), with legacy one-line lock liveness handling, a new bin/fm-lock-lib.sh, dedicated tests/fm-lock.test.sh coverage, and the format documented in AGENTS.md.
• Reverted the browser-isolation experiment and the duplicate PR-ready review-policy note; kept the macOS gotmp teardown fixture correction (composer/lock-lib helper symlinks), skipped Pi TypeScript extension tests on older node with the gate documented in CONTRIBUTING, and documented six missing bin scripts in docs/scripts.md.

Risk Assessment

✅ Low: The final tree is byte-identical to already-reviewed upstream except 13 intended files; the fork-specific session-lock hardening is well-bounded, backward compatible with legacy one-line locks, consistently handled by every lock reader, and covered by a dedicated new test suite, with the two reverts fully landed.

Testing

Baseline full behavior suite passed; re-ran the lock and gotmp suites, statically verified upstream ancestry plus retention/removal of each intended piece, and manually drove bin/fm-lock.sh with real processes to demonstrate PID-reuse takeover, live-holder refusal, and Codex app-server rejection working end-to-end — all green with transcripts saved as evidence; the "stopped but ready to start" aspect concerns the author's live gitignored fleet state and is out of scope for repo testing.

Evidence: Session-lock hardening manual demo transcript (real ps, real processes)

Scenario 1 (PID reuse): lock records LIVE claude-named pid 8006 + stale start time 'Sun Dec 31 23:59:59 2023' -> status: "lock: stale (pid 8006 dead or not a harness)"; acquire -> "lock acquired: harness pid 3190" (this session's real harness) with real start time written. Scenario 2 (genuine holder): same pid with CORRECT start time -> status: "held by live harness pid 8006"; acquire refused: "error: another live firstmate session holds the lock (pid 8006)" exit 1. Scenario 3 (app-server): live '/tmp/fm1/codex app-server' with matching start time -> status: stale (not a session holder); same binary without app-server args -> "held by live harness pid 8290". Scenario 4 (legacy one-line lock): held while pid alive, stale after kill.

===== Scenario 1: PID reuse — lock records a LIVE claude-named PID but a stale start time =====
live process occupying the recorded PID:
   8006 Sun Jul 12 04:02:30 2026     /tmp/fm1/claude
lock file contents (pid line + recorded start-time line):
  | 8006
  | Sun Dec 31 23:59:59 2023
-> fm-lock.sh status:
  lock: stale (pid 8006 dead or not a harness)
-> fm-lock.sh acquire (this session takes over the stale lock):
  lock acquired: harness pid 3190
lock file after takeover (this session's real harness pid + real start time):
  | 3190
  | Sun Jul 12 03:56:37 2026

===== Scenario 2: genuinely live holder — same claude-named PID, CORRECT start time =====
lock file contents:
  | 8006
  | Sun Jul 12 04:02:30 2026
-> fm-lock.sh status:
  lock: held by live harness pid 8006
-> fm-lock.sh acquire (must refuse: another live session holds it):
  error: another live firstmate session holds the lock (pid 8006); operate read-only until resolved
  (exit status of acquire: 1)

===== Scenario 3: Codex app-server occupying the lock PID is NOT a session holder =====
live codex-named app-server process:
   8255 /tmp/fm1/codex /tmp/fm1/codex app-server
-> fm-lock.sh status (pid live, start time matches, name is codex — but it is an app-server):
  lock: stale (pid 8255 dead or not a harness)

===== Scenario 3b: contrast — the SAME codex binary without app-server args IS a holder =====
live plain codex-named process:
   8290 /tmp/fm1/codex /tmp/fm1/codex
-> fm-lock.sh status:
  lock: held by live harness pid 8290

===== Scenario 4: legacy ONE-line lock falls back to harness liveness =====
legacy lock file (single pid line, no start time):
  | 8006
-> fm-lock.sh status (live claude-named pid => held):
  lock: held by live harness pid 8006
-> after killing that pid, fm-lock.sh status:
  lock: stale (pid 8006 dead or not a harness)

demo complete
/var/folders/y_/bfdbj_vx20l9b9tw7crgkzwm0000gn/T/no-mistakes-evidence/01KXAM8RQDM5Z0T038ZWZW7JB1/lock-demo.sh: line 12:  8255 Terminated: 15          "$BINDIR/codex" app-server
/var/folders/y_/bfdbj_vx20l9b9tw7crgkzwm0000gn/T/no-mistakes-evidence/01KXAM8RQDM5Z0T038ZWZW7JB1/lock-demo.sh: line 12:  8290 Terminated: 15          "$BINDIR/codex"

Evidence: Intent verification transcript (upstream ancestry, retained/removed content)

== HEAD of worktree ==
19427c4 merge: sync official upstream through 9ecd7c4

== 1. Upstream sync: target is a merge whose 2nd parent is official upstream tip 9ecd7c4 ==
tree f9e2cc5dcd60b565cb37e5a903634a3cced045b3
parent 2d8143fdd609fb25d9cf87f5630f693881dc86be
parent 9ecd7c43ad7d866a54c3332e97e4b2744e589a2e
9ecd7c4 (feat: make bearings concise and accurate (#485)) IS an ancestor of HEAD

== 2. Session-lock hardening retained ==
-- bin/fm-lock.sh: PID + start-time identity and app-server rejection --
21:process_start_time() {
36:command_is_app_server() {
44:lock_start_time() {
50:  start=$(process_start_time "$pid") || return 1
65:    if ! command_is_app_server "$command" && printf '%s' "$(basename "$comm")" | grep -qE "$HARNESS_RE"; then
71:        if ! command_is_app_server "$command" && printf '%s' "$args" | grep -qE "$HARNESS_RE"; then
87:  recorded_start=$(lock_start_time "$lock")
89:    current_start=$(process_start_time "$pid") || return 1
-- AGENTS.md documents the two-line lock --
106:  .lock              per-home session lock written by fm-lock.sh: harness PID on line 1, holder process start time on line 2; direct readers parse only the first-line PID, while acquire/status treat it as held only when that PID is live with a matching start time (skipped for a legacy one-line lock, which is held while its PID is a live harness) and is not a Codex app-server
-- CONTRIBUTING.md lists the lock test suite --

== 3. macOS gotmp fixture correction retained (composer + lock lib in teardown fixture) ==
55:  ln -s "$ROOT/bin/fm-composer-lib.sh" "$fake/bin/fm-composer-lib.sh"
56:  # fm-lock-lib.sh: teardown sources it for the shared lock-staleness proof.
57:  ln -s "$ROOT/bin/fm-lock-lib.sh" "$fake/bin/fm-lock-lib.sh"
152:  ln -s "$ROOT/bin/fm-composer-lib.sh" "$fake/bin/fm-composer-lib.sh"
153:  ln -s "$ROOT/bin/fm-lock-lib.sh" "$fake/bin/fm-lock-lib.sh"

== 4. Browser isolation removed ==
ls: docs/browser-axi-isolation.md: No such file or directory
ls: tests/fm-browser-axi-isolation.test.sh: No such file or directory
grep for isolation code in bin/, docs/, .agents/:
(no matches)

== 5. Duplicate review policy removed from AGENTS.md ==
(no matches — the three reverted lines are gone)

== 6. Worktree clean at target commit ==
(porcelain exit: 0)

== Note on the empty CONTRIBUTING.md grep in section 2 ==
Commit 88ab966 originally added a "tests/fm-lock.test.sh" line to CONTRIBUTING.md's
enumerated test list. Upstream commit 78f9cce (merged here) replaced that whole
enumerated list with a generic "Discover tests by listing tests/*.test.sh" instruction,
so the line's absence is deliberate upstream restructuring, not lost documentation.
The lock-hardening documentation is retained at AGENTS.md:106 (two-line lock format,
start-time identity, app-server rejection, legacy one-line fallback) and in the
bin/fm-lock.sh and tests/fm-lock.test.sh header comments.

Evidence: fm-lock.test.sh transcript (5 hardening tests ok)

ok - fm-lock treats a live harness-named PID with mismatched start time as stale
ok - fm-lock blocks a genuinely live same-identity holder
ok - fm-lock still allows a genuine same-session re-acquire
ok - fm-lock rejects Codex app-server as a live session holder
ok - fm-lock falls back to harness liveness for a legacy one-line lock

Evidence: fm-gotmp.test.sh transcript (macOS gotmp fixture ok)

ok - fm-spawn creates gotmp dir and records tasktmp in meta
ok - fm-teardown removes the dir pointed to by tasktmp= in meta
ok - fm-teardown skips gracefully when tasktmp= is absent (backward compat)
ok - fm-teardown skips gracefully when tasktmp= points to a nonexistent dir

Evidence: Reproducible manual lock demo script

#!/usr/bin/env bash
# Manual end-to-end demo of the hardened per-home session lock (bin/fm-lock.sh),
# using the REAL macOS ps and real processes (no fixtures, no fake ps).
# Harness-named stand-ins are tiny compiled idle binaries at short paths so the
# real `ps -o comm=` reports their name exactly as it would for a real harness.
set -u
ROOT=$1
DEMO=$(mktemp -d)
BINDIR=/tmp/fm1
mkdir -p "$DEMO/home/state" "$BINDIR"
PIDS=()
cleanup() { for p in "${PIDS[@]:-}"; do kill "$p" 2>/dev/null; done; rm -rf "$DEMO" "$BINDIR"; }
trap cleanup EXIT

LOCKSH="$ROOT/bin/fm-lock.sh"
HOME_DEMO="$DEMO/home"
LOCK="$HOME_DEMO/state/.lock"

cat > "$BINDIR/idle.c" <<'EOF'
#include <unistd.h>
int main(int argc, char **argv) { (void)argc; (void)argv; sleep(300); return 0; }
EOF
cc -o "$BINDIR/claude" "$BINDIR/idle.c"
cc -o "$BINDIR/codex" "$BINDIR/idle.c"

section() { printf '\n===== %s =====\n' "$*"; }

section "Scenario 1: PID reuse — lock records a LIVE claude-named PID but a stale start time"
"$BINDIR/claude" & FAKE_CLAUDE=$!; PIDS+=("$FAKE_CLAUDE")
sleep 0.3
echo "live process occupying the recorded PID:"
ps -o pid=,lstart=,comm= -p "$FAKE_CLAUDE" | sed 's/^/  /'
printf '%s\n%s\n' "$FAKE_CLAUDE" 'Sun Dec 31 23:59:59 2023' > "$LOCK"
echo "lock file contents (pid line + recorded start-time line):"
sed 's/^/  | /' "$LOCK"
echo "-> fm-lock.sh status:"
FM_HOME="$HOME_DEMO" bash "$LOCKSH" status | sed 's/^/  /'
echo "-> fm-lock.sh acquire (this session takes over the stale lock):"
FM_HOME="$HOME_DEMO" bash "$LOCKSH" | sed 's/^/  /'
echo "lock file after takeover (this session's real harness pid + real start time):"
sed 's/^/  | /' "$LOCK"

section "Scenario 2: genuinely live holder — same claude-named PID, CORRECT start time"
REAL_START=$(LC_ALL=C ps -o lstart= -p "$FAKE_CLAUDE" | sed 's/^ *//;s/ *$//')
printf '%s\n%s\n' "$FAKE_CLAUDE" "$REAL_START" > "$LOCK"
echo "lock file contents:"
sed 's/^/  | /' "$LOCK"
echo "-> fm-lock.sh status:"
FM_HOME="$HOME_DEMO" bash "$LOCKSH" status | sed 's/^/  /'
echo "-> fm-lock.sh acquire (must refuse: another live session holds it):"
acquire_out=$(FM_HOME="$HOME_DEMO" bash "$LOCKSH" 2>&1); acquire_rc=$?
printf '%s\n' "$acquire_out" | sed 's/^/  /'
echo "  (exit status of acquire: $acquire_rc)"

section "Scenario 3: Codex app-server occupying the lock PID is NOT a session holder"
"$BINDIR/codex" app-server & APPSRV=$!; PIDS+=("$APPSRV")
sleep 0.3
echo "live codex-named app-server process:"
ps -o pid=,comm=,args= -p "$APPSRV" | sed 's/^/  /'
APPSRV_START=$(LC_ALL=C ps -o lstart= -p "$APPSRV" | sed 's/^ *//;s/ *$//')
printf '%s\n%s\n' "$APPSRV" "$APPSRV_START" > "$LOCK"
echo "-> fm-lock.sh status (pid live, start time matches, name is codex — but it is an app-server):"
FM_HOME="$HOME_DEMO" bash "$LOCKSH" status | sed 's/^/  /'

section "Scenario 3b: contrast — the SAME codex binary without app-server args IS a holder"
"$BINDIR/codex" & PLAIN=$!; PIDS+=("$PLAIN")
sleep 0.3
PLAIN_START=$(LC_ALL=C ps -o lstart= -p "$PLAIN" | sed 's/^ *//;s/ *$//')
printf '%s\n%s\n' "$PLAIN" "$PLAIN_START" > "$LOCK"
echo "live plain codex-named process:"
ps -o pid=,comm=,args= -p "$PLAIN" | sed 's/^/  /'
echo "-> fm-lock.sh status:"
FM_HOME="$HOME_DEMO" bash "$LOCKSH" status | sed 's/^/  /'

section "Scenario 4: legacy ONE-line lock falls back to harness liveness"
printf '%s\n' "$FAKE_CLAUDE" > "$LOCK"
echo "legacy lock file (single pid line, no start time):"
sed 's/^/  | /' "$LOCK"
echo "-> fm-lock.sh status (live claude-named pid => held):"
FM_HOME="$HOME_DEMO" bash "$LOCKSH" status | sed 's/^/  /'
kill "$FAKE_CLAUDE" 2>/dev/null; wait "$FAKE_CLAUDE" 2>/dev/null
sleep 0.2
echo "-> after killing that pid, fm-lock.sh status:"
FM_HOME="$HOME_DEMO" bash "$LOCKSH" status | sed 's/^/  /'

echo
echo "demo complete"

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

⚠️ **Rebase** - 1 warning

• ⚠️ .agents/skills/harness-adapters/SKILL.md - branch carries 5 commit(s) that exist on your local main branch but were never pushed to origin/main; rebasing would bundle this unrelated work (28 file(s)) into the PR:
• 7d08b4c fix: harden browser isolation lifecycle
• 732d4d4 feat: isolate browser sessions per spawn
• 50f0841 no-mistakes(document): document two-line session lock format in AGENTS.md state listing
• 88ab966 Harden session lock identity
• 7a863f7 clarify PR ready review checks

Push main to origin, or rebase your branch onto origin/main, before gating.

⚠️ **Review** - 2 infos

• ℹ️ bin/fm-lock.sh:36 - command_is_app_server matches the 'app-server' token anywhere in the full comm+args string, so a live harness whose command line legitimately contains a standalone 'app-server' argument would be misclassified as a stale holder, letting a second session acquire the lock concurrently. The token-boundary regex makes this contrived in practice, and it mirrors the existing HARNESS_RE substring approach; anchoring on argv[1] of a codex process would be tighter if it ever bites.
• ℹ️ bin/fm-lock.sh:112 - A write_lock failure (e.g. the harness PID vanishing between the ancestry walk and ps -o lstart=) exits 1 from acquire, and fm-session-start's read-only banner headline then reads 'ANOTHER LIVE FIRSTMATE SESSION HOLDS THE FLEET LOCK', misattributing the cause. The actual 'cannot record harness process identity' line is printed inside the banner, so the true error is visible; differentiating exit codes would make the headline accurate on this unlikely path.

✅ **Test** - passed

✅ No issues found.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• Baseline (pre-run): for t in tests/*.test.sh; do bash "$t"; done — full behavior suite passed
• bash tests/fm-lock.test.sh — session-lock PID/start-time identity, stale PID reuse, same-holder re-acquire, app-server rejection, legacy one-line lock liveness (all ok)
• bash tests/fm-gotmp.test.sh — macOS gotmp spawn/teardown fixture including the corrected composer/lock-lib helper symlinks (all ok)
• Manual end-to-end lock demo (lock-demo.sh) using real ps and compiled harness-named binaries: stale start-time takeover by this session's real harness, live-holder acquire refusal (exit 1), Codex app-server rejection vs plain-codex acceptance, legacy one-line lock fallback
• git cat-file -p 19427c4 + git merge-base --is-ancestor 9ecd7c4 19427c4 — merge parents and upstream ancestry
• Static greps at target: browser-isolation files/code absent (docs/browser-axi-isolation.md, tests/fm-browser-axi-isolation.test.sh, bin/docs/.agents refs), duplicate review-policy lines absent from AGENTS.md, two-line lock documented at AGENTS.md:106, gotmp fixture lines present
• Traced the removed CONTRIBUTING.md fm-lock.test.sh line to upstream 78f9cce's test-list restructuring (deliberate, not lost docs)

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.