@cohortapp/agent-sdk 2.18.13 → 2.18.15

package/scripts/local-triggers/autoupdate.sh

@@ -481,18 +481,133 @@ write_notice(){ # $1 = from, $2 = to, [$3 = reason → healthy:false] — tell t
 }
 write_upgrade_notice(){ write_notice "$1" "$2"; }
 LAST_JSON="$AGENT_DIR/state/autoupdate/last.json"
-write_last(){ # $1 from, $2 to, $3 ok, $4 healthy, $5 reason — state/autoupdate/last.json (→ beat machine.upgrade)
-  local dir="$AGENT_DIR/state/autoupdate" tmp
+# How many CONSECUTIVE failed attempts to reach @latest make a seat STUCK, and
+# at what point it stops being a warning. See the `failStreak` block below.
+STUCK_STREAK="${MAESTRO_AUTOUPDATE_STUCK_STREAK:-3}"
+# ── failStreak — "this seat cannot get to @latest" is a FACT, not a discovery ─
+# The fleet learned on 2026-09-25 that three seats had sat on 2.17.0 for days.
+# Nothing was broken in the sense anything reports: the launchd job fired every
+# hour, npm answered, the install ran, the health gate failed, the rollback
+# worked, last.json recorded it honestly, and the beat carried it. Each hour was
+# a correct, self-contained failure — and a correct failure repeated forty times
+# is a different fact from a correct failure once. Only the REPETITION says the
+# seat will never arrive on its own, and no single record can hold it, so the
+# count lives in last.json and rides the beat the rest of that record already
+# rides. There is no second channel here and there must not be one: the seats
+# this is about are, by construction, the ones running the oldest code.
+#
+# WHAT COUNTS AS AN ATTEMPT — the whole honesty of the number:
+#   · An ATTEMPT is a record whose `to` differs from its `from`: the upgrade
+#     path actually installed (or tried to install) a different version. Those
+#     are the only records that move the streak.
+#   · A FAILED attempt (`ok:false`) increments it and stamps `stuckSince` with
+#     the first failure of the run of failures, so a reader gets a DURATION and
+#     not merely a tally — "4 attempts since Monday" and "4 attempts in the last
+#     hour" are different seats.
+#   · A SUCCEEDED attempt (`ok:true`) clears all three fields. Arrival is the
+#     only thing that resets it; a fleet-wide publish does not, because a seat
+#     that fails 2.18.12, 2.18.13 and 2.18.14 in turn has failed three times to
+#     do the one thing asked of it, and restarting the count on every release
+#     would guarantee the number never reaches any threshold.
+#   · Everything else PRESERVES the fields untouched. A `to == from` record is
+#     a report on the installed version, not an attempt to leave it, so it must
+#     not move a count of ATTEMPTS in either direction. (Every such call site
+#     today sits on the up-to-date branch and therefore takes the arrival path
+#     below instead — this rule governs the writer, for the next caller that
+#     does not.) And a run that SKIPS writes no record at all, which is the
+#     same preservation by a shorter route. THIS IS THE POINT OF (d): a seat that has not been ASKED —
+#     nothing newer published, or held for the day after its last failure — is
+#     not a stuck seat, and must never accumulate a streak for sitting still.
+#     Only a real, completed, failed attempt does.
+#   · WHICH RUNS ACTUALLY SKIP — the exact list, because a wrong one was
+#     written here first. The paths that reach `exit 0` with NO write_last are:
+#     the failed-target hold, the overlap lock, the kill-switch, and a failed
+#     `npm view`. "SIMPLY BEING UP TO DATE" IS NOT AMONG THEM and never was —
+#     the up-to-date branch is the daemon health gate, and it calls write_last
+#     on every one of its outcomes (healthy, unhealthy-current,
+#     ahead-of-registry, recovered, and the stale-daemon kickstart). The
+#     original text claimed otherwise; nothing checked it, and the streak
+#     arithmetic on that branch is not what the sentence implied.
+#   · ARRIVAL IS BEING AT @latest, NOT MERELY INSTALLING IT. Every write on the
+#     up-to-date branch passes `at_latest=true`, which clears all three fields
+#     — because that branch is only entered when `CUR >= LATEST`, i.e. there is
+#     nothing left for this seat to reach. That covers the case the increment
+#     rule alone gets wrong: if a bad release is YANKED and @latest rolls back
+#     to the version a seat already runs, the seat stops attempting anything,
+#     so nothing would ever reset it and `upgrade_stuck` would fire forever
+#     (critical past 6) on a seat that is in fact perfectly current. It also
+#     makes the stale-daemon kickstart record honest rather than accidental:
+#     that hop really is an arrival.
+# The write is done in node rather than printf because the record now depends on
+# the record before it; a shell that reads a file it is about to overwrite gets
+# that wrong at exactly the moments it matters.
+write_last(){ # $1 from, $2 to, $3 ok, $4 healthy, $5 reason, [$6 at_latest] — state/autoupdate/last.json (→ beat machine.upgrade)
+  local dir="$AGENT_DIR/state/autoupdate" tmp streak at_latest="${6:-false}"
   mkdir -p "$dir" 2>/dev/null || return 0
   tmp="$(mktemp "$dir/.last.XXXXXX" 2>/dev/null)" || return 0
-  printf '{\n  "from": "%s",\n  "to": "%s",\n  "at": "%s",\n  "ok": %s,\n  "healthy": %s,\n  "reason": "%s"\n}\n' \
-    "$1" "$2" "$(date -u +%FT%TZ)" "$3" "$4" "$(json_str "$5")" > "$tmp" && mv -f "$tmp" "$LAST_JSON"
+  streak="$(node -e '
+    const fs = require("fs");
+    const [file, tmp, from, to, okS, healthyS, reason, stuckStreakS, atLatestS] = process.argv.slice(1);
+    const ok = okS === "true";
+    const at = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    let prev = null;
+    try { prev = JSON.parse(fs.readFileSync(file, "utf8")); } catch {}
+    if (!prev || typeof prev !== "object") prev = {};
+    const prevStreak = Number.isInteger(prev.failStreak) && prev.failStreak > 0 ? prev.failStreak : 0;
+    const attempt = from !== to;               // an upgrade was actually tried
+    const atLatest = atLatestS === "true";     // this seat is AT or past @latest — nothing left to reach
+    let failStreak, stuckSince, streakTarget;
+    if (atLatest || (attempt && ok)) {         // arrival, by install OR because @latest came back to us (a yank)
+      failStreak = 0; stuckSince = ""; streakTarget = "";
+    } else if (!attempt) {                     // a report on the installed version — carry the count, do not touch it
+      failStreak = prevStreak;
+      stuckSince = typeof prev.stuckSince === "string" ? prev.stuckSince : "";
+      streakTarget = typeof prev.streakTarget === "string" ? prev.streakTarget : "";
+    } else {
+      failStreak = prevStreak + 1;
+      stuckSince = typeof prev.stuckSince === "string" && prev.stuckSince ? prev.stuckSince : at;
+      streakTarget = to;
+    }
+    const rec = { from, to, at, ok, healthy: healthyS === "true", reason };
+    if (failStreak > 0) {
+      rec.failStreak = failStreak;
+      if (stuckSince) rec.stuckSince = stuckSince;
+      if (streakTarget) rec.streakTarget = streakTarget;
+    }
+    fs.writeFileSync(tmp, JSON.stringify(rec, null, 2) + "\n");
+    // stdout is the shell'"'"'s only view of what was decided: "<streak> <target> <since>"
+    process.stdout.write(failStreak >= Number(stuckStreakS) && attempt && !ok ? `STUCK ${failStreak} ${streakTarget} ${stuckSince}` : "");
+  ' "$LAST_JSON" "$tmp" "$1" "$2" "$3" "$4" "$5" "$STUCK_STREAK" "$at_latest" 2>/dev/null)" || streak=""
+  if [ -s "$tmp" ]; then
+    mv -f "$tmp" "$LAST_JSON"
+  else
+    # The node writer produced nothing. Before this branch existed the tmp was
+    # simply removed and last.json was LEFT AT ITS PREVIOUS VALUE — so a write
+    # failure did not lose a record, it published a STALE one, and the 24 h
+    # failed-target hold (which reads `to` and `reason` out of this file) then
+    # made its decision from a previous run's outcome while believing it was
+    # this run's. A missing record is fail-open by design here; a wrong one is
+    # not. So write the event itself with printf, which needs no interpreter,
+    # and say loudly that the count did not survive: the streak is the one
+    # field that cannot be reconstructed without reading the old file, and a
+    # silently reset counter is the failure this whole block exists to prevent.
+    log "WARN: write_last could not run node — recording the bare outcome without the failStreak. The count restarts from this run; see state/autoupdate/last.json."
+    printf '{\n  "from": "%s",\n  "to": "%s",\n  "at": "%s",\n  "ok": %s,\n  "healthy": %s,\n  "reason": "%s"\n}\n' \
+      "$1" "$2" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$3" "$4" "$(printf '%s' "$5" | sed 's/[\\"]/\\&/g')" > "$LAST_JSON" 2>/dev/null || true
+  fi
   rm -f "$tmp" 2>/dev/null
+  if [ -n "$streak" ]; then
+    set -- $streak
+    log "STUCK: $2 consecutive failed attempts to reach $3 (since $4). This seat will not arrive on its own — the org now carries machine.upgrade.failStreak=$2 and an \`upgrade_stuck\` alert on every beat. maestro doctor; then rm state/autoupdate/last.json to retry immediately."
+  fi
   return 0
 }
 last_reason(){ # the reason field of last.json, or nothing
   node -e 'try { process.stdout.write(String(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).reason || "")); } catch {}' "$LAST_JSON" 2>/dev/null
 }
+last_streak(){ # the failStreak of last.json as a positive integer, or nothing
+  node -e 'try { const n = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).failStreak; if (Number.isInteger(n) && n > 0) process.stdout.write(String(n)); } catch {}' "$LAST_JSON" 2>/dev/null
+}
 # The version the RUNNING daemon started on. scripts/daemon/health.mjs resolves
 # sdk_version once at load and writes it to state/dashboards/daemon-health.yaml
 # with its pid, precisely so a reader can tell the installed package from the
@@ -595,13 +710,13 @@ if [ "$CUR" = "$LATEST" ] || [ "$(printf '%s\n%s\n' "$CUR" "$LATEST" | sort -V |
       # the notice tells the session to restart itself onto the new code.
       log "OK: daemon now on $CUR (was $STALE_FROM) — the manual upgrade is complete"
       write_upgrade_notice "$STALE_FROM" "$CUR"
-      write_last "$STALE_FROM" "$CUR" true true ""
+      write_last "$STALE_FROM" "$CUR" true true "" true
     elif [ -n "$STALE_FROM" ]; then
       # Same version, newer files: the daemon is reconciled; the session is
       # not told to restart (a touched or restored file must not cost it its
       # context — the version did not change).
       log "OK: daemon restarted onto the installed $CUR code; no session notice (same version)"
-      write_last "$CUR" "$CUR" true true ""
+      write_last "$CUR" "$CUR" true true "" true
     elif [ -n "$AHEAD" ]; then
       # The DAEMON is well; the FLEET is not. Recorded as ok/healthy — because
       # it is — with the finding in `reason`, so the org learns that this seat
@@ -609,14 +724,32 @@ if [ "$CUR" = "$LATEST" ] || [ "$(printf '%s\n%s\n' "$CUR" "$LATEST" | sort -V |
       # per episode: unlike an unhealthy daemon this does not clear itself, and
       # a fact that ages out of one log file is how six days went by.
       log "OK: healthy on $CUR, but AHEAD of the registry ($LATEST) — recorded for the org as ahead-of-registry"
-      write_last "$CUR" "$CUR" true true "ahead-of-registry: npm latest is $LATEST"
+      write_last "$CUR" "$CUR" true true "ahead-of-registry: npm latest is $LATEST" true
     else
-      case "$PREV_REASON" in unhealthy-current*)
+      case "$PREV_REASON" in
+      unhealthy-current*)
         log "recovered: last.json no longer reports unhealthy-current"
-        write_last "$CUR" "$CUR" true true "" ;;
+        write_last "$CUR" "$CUR" true true "" true ;;
       ahead-of-registry*)
         log "recovered: $CUR is on the registry now (latest $LATEST) — last.json no longer reports ahead-of-registry"
-        write_last "$CUR" "$CUR" true true "" ;;
+        write_last "$CUR" "$CUR" true true "" true ;;
+      *)
+        # A healthy seat that is simply up to date writes NOTHING — there is
+        # nothing to report and an empty last.json is the honest state.
+        #
+        # The one exception is a standing failStreak, and it is the reason this
+        # branch exists at all. A streak only ever reset on ARRIVAL, i.e. on a
+        # successful hop. If a bad release is YANKED and @latest rolls back to
+        # the version this seat already runs, the seat stops attempting
+        # anything: every hour it takes this quiet path, writes nothing, and the
+        # count stands for ever — `upgrade_stuck` firing critical on a seat that
+        # is, in fact, exactly where the registry wants it. Being AT @latest is
+        # an arrival however you got there, so record one and say so.
+        STREAK="$(last_streak)"
+        if [ -n "$STREAK" ]; then
+          log "streak cleared: $CUR is @latest and this seat is healthy on it, but last.json still carried failStreak=$STREAK — @latest has come back to this version (a yank or a withdrawn release). Recording the arrival so the upgrade_stuck alert stops."
+          write_last "$CUR" "$CUR" true true "" true
+        fi ;;
       esac
     fi
   else
@@ -625,7 +758,7 @@ if [ "$CUR" = "$LATEST" ] || [ "$(printf '%s\n%s\n' "$CUR" "$LATEST" | sort -V |
     # and failed_hold_reason both match on it), so the ahead-of-registry fact
     # is appended, never prepended — an unpublished build that is also sick is
     # the worst case and must say both things.
-    write_last "$CUR" "$CUR" false false "unhealthy-current: $HEALTH_REASON${AHEAD:+ (and ahead-of-registry: npm latest is $LATEST)}"
+    write_last "$CUR" "$CUR" false false "unhealthy-current: $HEALTH_REASON${AHEAD:+ (and ahead-of-registry: npm latest is $LATEST)}" true
     case "$PREV_REASON" in
       unhealthy-current*) log "session already notified this episode (last.json was unhealthy-current); notice not rewritten" ;;
       *) write_notice "$CUR" "$CUR" "unhealthy-current: $HEALTH_REASON" ;;

package/scripts/resume-operations.sh

@@ -3,12 +3,34 @@
 # Usage: ./scripts/resume-operations.sh
 #
 # Reverses emergency-stop.sh:
-#   1. Verifies health check passes.
+#   1. Verifies health check passes — EXCLUDING the stop flag itself.
 #   2. Removes the .emergency-stop flag.
 #   3. Reloads every installed `ai.maestro.<agent>-*` (and legacy
 #      `ai.adaptic.<agent>-*`) launchd job.
 #
 # Agent first-name slug resolved from config/agent.json (SOT).
+#
+# THE DEADLOCK THIS SCRIPT USED TO HAVE. healthcheck.sh counts an active
+# .emergency-stop flag as an ERROR; this script ran it bare and exited on any
+# non-zero. So the one tool whose entire purpose is lifting the stop could
+# never lift it — Eli Rosenberg's seat sat halted from 2026-09-24T08:16Z until
+# the flag was removed by hand. Two independent faults produced that:
+#
+#   (a) The stop flag was its own veto. Fixed by passing
+#       `--ignore-emergency-stop`, which demotes that ONE check to a note.
+#       It is a PUBLIC CLI flag — nothing refuses it to another caller, and
+#       nothing here pretends to (healthcheck.sh's header says so plainly).
+#       What makes it safe is scope, not exclusivity: it demotes exactly one
+#       check, every other check still gates the resume, and step 1b below
+#       VERIFIES that the healthcheck on this disk actually honoured it
+#       rather than assuming the two files are the same vintage.
+#   (b) DEGRADED was treated as failure. healthcheck exits 1 for warnings and
+#       2 for errors; `if ! healthcheck` refused on both, so seven warnings
+#       about optional repos and an uninstalled Slack.app were enough to keep
+#       a seat halted. Warnings are "operational with limitations" by
+#       healthcheck's own contract — they are reported loudly and resumed.
+#       Only CRITICAL (exit 2) still refuses, and the refusal names which
+#       condition blocked it.
 
 set -e
 
@@ -46,19 +68,92 @@ if [ ! -f "$AGENT_DIR/.emergency-stop" ]; then
             launchctl load "$plist" 2>/dev/null && loaded=$((loaded + 1))
         fi
     done
-    [ "$loaded" -gt 0 ] && echo "Loaded $loaded missing launchd job(s)"
+    # `if`, not `[ "$loaded" -gt 0 ] && echo ...` — but NOT for the reason
+    # first written here, which was wrong and would have seeded a wrong rule.
+    # `set -e` does not abort on the false short-circuit: bash exempts a
+    # failing command that is not the last in an && list. MEASURED:
+    #   bash -c 'set -e; n=0; [ "$n" -gt 0 ] && echo hi; exit 0'  → exit 0
+    # and the pre-fix script (which had `exit 0` on the next line) also
+    # exited 0 on a seat with nothing to load. The real hazard is narrower
+    # and has nothing to do with `set -e`: a false && list leaves status 1,
+    # so a script whose LAST command is one exits 1. `exit 0` follows today;
+    # the `if` keeps this line harmless if it ever stops following.
+    if [ "$loaded" -gt 0 ]; then echo "Loaded $loaded missing launchd job(s)"; fi
     exit 0
 fi
 
 echo "[$TIMESTAMP] RESUMING OPERATIONS (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
 
-# 1. Run health check first.
-echo "Running health check..."
-if ! "$SCRIPT_DIR/healthcheck.sh"; then
-    echo "ERROR: Health check failed. Fix issues before resuming."
+# 1. Run health check first — with the stop flag exempted, since lifting it is
+#    this script's entire job. Every OTHER check still gates the resume.
+echo "Running health check (emergency-stop flag exempted)..."
+set +e
+HEALTH_OUTPUT=$("$SCRIPT_DIR/healthcheck.sh" --ignore-emergency-stop 2>&1)
+HEALTH_STATUS=$?
+set -e
+echo "$HEALTH_OUTPUT"
+
+# 1b. Prove the exemption was HONOURED before trusting the verdict.
+#
+#     Fault (a)'s fix is version-coupled: it only works if the healthcheck.sh
+#     next to this script understands --ignore-emergency-stop. A seat that
+#     pins framework files (.maestroignore) can carry the new resume script
+#     beside a pre-fix healthcheck, which has no argument parsing at all — it
+#     swallows the flag, still counts the stop as an error, and prints no
+#     `Blocking:` line. MEASURED on that exact pairing: the deadlock is back,
+#     and the refusal reads "(healthcheck named no condition; see output
+#     above)" — worse than the original, because it names nothing to fix.
+#     The seats most likely to be halted are the ones most likely to be
+#     pinned, so this has to be detected and named rather than inferred.
+#
+#     We are past the `[ -f .emergency-stop ]` guard, so a healthcheck that
+#     honoured the flag MUST have printed the NOTE line. Its absence means
+#     the exemption did not take: stale, missing, or not executable.
+if ! printf '%s\n' "$HEALTH_OUTPUT" | grep -q '^\[NOTE\] Emergency stop flag' ||
+    printf '%s\n' "$HEALTH_OUTPUT" | grep -q '^Blocking:.*emergency-stop-flag'; then
+    echo ""
+    echo "REFUSING TO RESUME — scripts/healthcheck.sh is stale."
+    echo "  --ignore-emergency-stop was ignored (healthcheck exit $HEALTH_STATUS): it did"
+    echo "  not report '[NOTE] Emergency stop flag ... not counted', so its verdict still"
+    echo "  counts the very flag this script exists to lift. Resuming on that verdict"
+    echo "  would be resuming on a health check nobody read."
+    echo "  Fix: run 'maestro upgrade' on this seat, then confirm .maestroignore is not"
+    echo "  pinning scripts/healthcheck.sh, and that the file exists and is executable."
+    echo "  The .emergency-stop flag has been LEFT IN PLACE."
+    echo "[$TIMESTAMP] Resume REFUSED — healthcheck.sh stale (exemption ignored, status $HEALTH_STATUS)" >> "$LOG_FILE"
     exit 1
 fi
 
+if [ "$HEALTH_STATUS" -ge 2 ]; then
+    # Name the blocking condition. The operator should never have to re-run
+    # the health check with a filter to learn which of "1 errors" stopped them.
+    BLOCKING=$(printf '%s\n' "$HEALTH_OUTPUT" | sed -n 's/^Blocking://p' | tr -s ' ' | sed 's/^ //')
+    [ -n "$BLOCKING" ] || BLOCKING="(healthcheck named no condition; see output above)"
+    echo ""
+    echo "REFUSING TO RESUME — health check is CRITICAL."
+    echo "  Blocking condition(s): $BLOCKING"
+    # Re-list the failing lines under the refusal, RE-PREFIXED. The whole
+    # health output is echoed above, so the previous `grep '^\[FAIL\]'` here
+    # emitted bytes indistinguishable from it — deleting the line left the
+    # test that claimed to pin it green. The `  FAIL: ` prefix is produced
+    # only here, which is what makes that assertion load-bearing.
+    printf '%s\n' "$HEALTH_OUTPUT" | sed -n 's/^\[FAIL\] /  FAIL: /p'
+    echo "  The .emergency-stop flag has been LEFT IN PLACE."
+    echo "  Fix the condition(s) above, then re-run: $0"
+    {
+        echo "[$TIMESTAMP] Resume REFUSED — blocking: $BLOCKING"
+    } >> "$LOG_FILE"
+    exit 1
+fi
+
+if [ "$HEALTH_STATUS" -eq 1 ]; then
+    DEGRADED=$(printf '%s\n' "$HEALTH_OUTPUT" | sed -n 's/^Warnings://p' | tr -s ' ' | sed 's/^ //')
+    echo ""
+    echo "NOTE: health check is DEGRADED — resuming anyway (warnings are not faults)."
+    echo "  Warning condition(s): $DEGRADED"
+    echo "[$TIMESTAMP] Resume proceeding DEGRADED — warnings: $DEGRADED" >> "$LOG_FILE"
+fi
+
 # 2. Remove stop flag.
 rm "$AGENT_DIR/.emergency-stop"
 echo "[$TIMESTAMP] Stop flag removed" >> "$LOG_FILE"

package/scripts/session/supervisor.mjs

@@ -42,7 +42,7 @@
  * @module scripts/session/supervisor
  */
 
-import { existsSync as fsExistsSync, readFileSync as fsReadFileSync, mkdirSync as fsMkdirSync, unlinkSync as fsUnlinkSync, writeFileSync as fsWriteFileSync, chmodSync as fsChmodSync } from "node:fs";
+import { existsSync as fsExistsSync, readFileSync as fsReadFileSync, mkdirSync as fsMkdirSync, unlinkSync as fsUnlinkSync, writeFileSync as fsWriteFileSync, chmodSync as fsChmodSync, readdirSync as fsReaddirSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
@@ -66,6 +66,11 @@ import {
   launchMode, recordLaunch, rotationDecision, rotateMainSession, BACKOFF_MS,
 } from "../../lib/session/identity.mjs";
 import { detectMux, chooseMux, buildMuxCommands, parseScreenList, parseExitFile, renderEnvFile } from "../../lib/session/launch-args.mjs";
+import { resumeTargetState } from "../../lib/session/resume-target.mjs";
+import {
+  classifyLaunchFailure, launchFailureSignature, parseLaunchFailures,
+  launchFailureStreak, escalationDecision, escalationHint, IDENTICAL_FAILURE_LIMIT,
+} from "../../lib/session/launch-failure.mjs";
 
 /** Write a private (0600) file that must not already exist. The engine env file carries the seat token. */
 export function writePrivateFile(path, text) {
@@ -83,6 +88,17 @@ export const LOCK_NAME = "session";
 export const DEFAULT_POLL_MS = 2_000;
 /** The signals the supervisor owns (launchd sends SIGTERM to stop a job). */
 export const OWNED_SIGNALS = Object.freeze(["SIGTERM", "SIGINT"]);
+/**
+ * How long after start the pane is captured ONCE, to keep whatever the runtime
+ * printed before it died. A resume against a missing conversation is over in
+ * about two seconds, taking its mux session (and its pane) with it — so the
+ * capture has to happen while it is still there. Best-effort by design: when
+ * it comes back empty, `resumeTargetState`'s preflight is what carries the
+ * verdict, and the post-mortem heuristics below carry the rest.
+ */
+export const EARLY_PANE_MS = 1_500;
+/** Consecutive identical launch failures before the seat escalates to the org. */
+export const LAUNCH_FAILURE_LIMIT = IDENTICAL_FAILURE_LIMIT;
 
 /** Real signal wiring: `fn(signal)` on each owned signal. */
 function installSignalHandlers(fn) {
@@ -198,6 +214,15 @@ export async function runSupervisor(deps = {}) {
     seatSpawn: deps.seatSpawn || ((root) => resolveSeatSpawn(root)),
     writePrivateFile: deps.writePrivateFile || writePrivateFile,
     envFileId: deps.envFileId || randomUUID,
+    readdirSync: deps.readdirSync || fsReaddirSync,
+    launchFailureLimit: deps.launchFailureLimit ?? LAUNCH_FAILURE_LIMIT,
+    earlyPaneMs: deps.earlyPaneMs ?? EARLY_PANE_MS,
+    // The one-shot pane probe has its OWN timer seam, separate from the
+    // watchdog's `after`. They are different clocks doing different jobs — one
+    // fires once at a second and a half, the other recurs at the grace period —
+    // and collapsing them would make every watchdog test reason about a timer
+    // that has nothing to do with the watchdog.
+    afterPaneProbe: deps.afterPaneProbe || deps.after || defaultAfter,
   };
   const fsDeps = { readFileSync: d.readFileSync, writeJsonAtomic: d.writeJsonAtomic };
   const agentRoot = d.agentRoot;
@@ -271,7 +296,7 @@ export async function runSupervisor(deps = {}) {
   // 4. Identity + argv.
   let record = loadMainSession(agentRoot, fsDeps);
   if (!record || cfg.resume === false) record = newMainSession({ now: d.now, uuid: d.uuid });
-  const mode = launchMode(record, cfg);
+  let mode = launchMode(record, cfg);
   let permissionArgs = d.permissionArgs;
   if (!permissionArgs) {
     permissionArgs = sessionPermissionArgs({ source: MAIN_SESSION_SOURCE, allowedTools: cfg.allowedTools });
@@ -288,6 +313,38 @@ export async function runSupervisor(deps = {}) {
   let seat = { engine: "claude", fields: {} };
   try { seat = (await d.seatSpawn(agentRoot)) || seat; } catch { seat = { engine: "claude", fields: {} }; }
   const engineCohort = seat.engine === "cohort";
+
+  // ── (a) A DEAD RESUME TARGET IS CAUGHT BEFORE THE LAUNCH, NOT AFTER IT ────
+  //
+  // James Kirkland's seat, measured 2026-09-25: `claude --resume <id>` for a
+  // conversation that no longer existed on that machine, exit 1 after 2 s,
+  // relaunched every ten minutes for DAYS. state/session/main-session.json held
+  // the dead id and nothing ever invalidated it.
+  //
+  // THE CHOICE, MADE EXPLICIT: invalidate the record AND fall back to a fresh
+  // id — both, in one write, here, before anything is spawned. Invalidating
+  // alone would leave the supervisor with no id (and `newMainSession` would
+  // mint one anyway, unrecorded); falling back alone would leave the dead id on
+  // disk for the next reader to resume again. `rotateMainSession` does both:
+  // the dead id survives as `rotatedFrom` — provenance, never a target.
+  //
+  // It runs on POSITIVE EVIDENCE ONLY (`resume-target.mjs` fails open): a
+  // wrong "missing" throws away a live transcript, a wrong "unknown" costs one
+  // launch and lands in the post-mortem that was already there.
+  if (mode === "resume") {
+    const target = resumeTargetState(
+      { homeDir: d.homeDir, projectDir: agentRoot, sessionId: record.sessionId, engine: seat.engine },
+      { readdirSync: d.readdirSync },
+    );
+    if (target.state === "missing") {
+      const dead = record.sessionId;
+      record = rotateMainSession(record, { now: d.now, uuid: d.uuid, reason: `resume target ${dead} is not on this machine` });
+      mode = launchMode(record, cfg);
+      const res = saveMainSession(agentRoot, record, fsDeps);
+      d.log(`resume target ${dead} is gone (${target.reason}) — invalidated it and starting a fresh session ${record.sessionId}${res.ok ? "" : ` (not saved: ${res.error})`}`);
+    }
+  }
+
   const spec = buildSpawn({ lane: "main-session", bin: d.claudeBin || undefined, first, sessionId: record.sessionId, resumeMode: mode, permissions: permissionArgs, env: d.env, ...seat.fields });
   if (!spec.ok && engineCohort) {
     // An engine-cohort seat never falls back to claude (it would spend the seat's
@@ -348,8 +405,34 @@ export async function runSupervisor(deps = {}) {
   const restartsSoFar = carriedRestarts({ attention: priorAttention, heartbeat: priorHeartbeat });
   if (restartsSoFar > 0) d.log(`this launch carries ${restartsSoFar} silent restart(s) from the previous run`);
 
+  // ── (b) THE CARRIED LAUNCH-FAILURE STREAK ────────────────────────────────
+  //
+  // Read BEFORE the unlink below, for the same reason `carriedRestarts` is: a
+  // count held in memory is zero on every launch, because every launch is a
+  // fresh process. This one lives in its own file rather than on the attention
+  // record, because it has to survive the unlink that clears that record.
+  let priorFailures = null;
+  try { priorFailures = parseLaunchFailures(d.readFileSync(paths.launchFailuresFile, "utf8")); } catch { priorFailures = null; }
+
   try { d.unlinkSync(paths.lastExitFile); } catch { /* none from a previous run */ }
   try { d.unlinkSync(paths.attentionFile); } catch { /* none outstanding */ }
+
+  // A seat already past the limit re-states the escalation on EVERY launch.
+  // The note rides `machine.sessionNote` on the presence beat, and the unlink
+  // above just cleared it: without this the org would see the alert blink out
+  // each time the seat tried again, which reads as a seat that healed.
+  if (priorFailures) {
+    const carried = escalationDecision({ streak: priorFailures.streak, limit: d.launchFailureLimit, escalatedAt: priorFailures.escalatedAt });
+    if (carried.escalate) {
+      writeLaunchAttention({
+        d, paths, mux, muxName, now: d.now(),
+        streak: carried.streak, limit: carried.limit, signature: priorFailures.signature,
+        detail: `${priorFailures.signature} since ${priorFailures.firstAt || "an earlier launch"}`,
+        sessionId: record.sessionId, phase: "retrying",
+      });
+      d.log(`launch-failure escalation still standing: ${carried.reason}`);
+    }
+  }
   // 4c. An upgrade notice asking for a restart onto the version THIS launch
   //     runs is honoured by this launch: retire it, so `maestro session
   //     status` stops flagging a hop the session has completed (and a notice
@@ -380,6 +463,9 @@ export async function runSupervisor(deps = {}) {
   //    almost certainly waiting on a dialog or a prompt nobody can see.
   const startedAt = Number(d.now());
   let launchFailed = false;
+  /** Whatever the mux client itself printed — `screen -D -m` reports a missing
+   *  command here, and it is the one piece of evidence no pane capture can race. */
+  let startStdout = "";
   stopCmd = cmds.stop;
   // ── THE WATCHDOG ────────────────────────────────────────────────────────
   //
@@ -400,6 +486,10 @@ export async function runSupervisor(deps = {}) {
   let clears = 0;
   let restarts = restartsSoFar;
   let watchdogStopped = false;
+  /** The last non-empty pane the watchdog saw — evidence for the post-mortem. */
+  let lastPane = "";
+  /** Did the WATCHDOG end this session? A death we caused is never rotated on. */
+  let watchdogRestarted = false;
   let cancelPass = () => {};
   const paneFile = join(agentRoot, "state", "session", "pane-capture.txt");
 
@@ -412,6 +502,17 @@ export async function runSupervisor(deps = {}) {
     } catch { return ""; }
   };
 
+  // The pane is captured ONCE, early, and kept. A resume whose conversation is
+  // gone prints "No conversation found with session ID: <id>" and exits inside
+  // a couple of seconds, taking the mux session and its pane with it — so the
+  // only moment this evidence exists is while the doomed session is still up.
+  // Best-effort: an empty capture is not an absence of fault, it is an absence
+  // of evidence, and `classifyLaunchFailure` is written to say so.
+  let earlyPane = "";
+  d.afterPaneProbe(d.earlyPaneMs, () => {
+    capturePane().then((text) => { if (!earlyPane) earlyPane = paneTail(text); }).catch(() => {});
+  });
+
   const sendKeys = async (keys) => {
     for (const k of keys) {
       const cmd = sendKeyCommand(mux, muxName, k);
@@ -433,6 +534,7 @@ export async function runSupervisor(deps = {}) {
     if (!silence.silent) { schedulePass(); return; }
 
     const pane = paneTail(await capturePane());
+    if (pane) lastPane = pane;
     const seen = classifyPane(pane);
     const act = watchdogAction({ silent: true, kind: seen.kind, keys: seen.keys, clears, restarts });
 
@@ -459,6 +561,7 @@ export async function runSupervisor(deps = {}) {
       await sendKeys(seen.keys);
     } else if (act.act === "restart") {
       restarts = nextRestarts;
+      watchdogRestarted = true;
       d.log(`session ${muxName}: restarting (${restarts}) — the session is not answering and the screen cannot be cleared safely`);
       try { await d.execFile(cmds.stop.file, cmds.stop.args, { cwd: agentRoot, env: d.env }); } catch { /* the relaunch loop handles a dead mux */ }
       watchdogStopped = true; // the supervisor's own loop relaunches; do not fight it
@@ -485,6 +588,7 @@ export async function runSupervisor(deps = {}) {
     // env file; the mux client itself gets the supervisor's env, as for claude.
     if (envFile) d.writePrivateFile(envFile, renderEnvFile(spec.env));
     const r = await d.execFile(cmds.start.file, cmds.start.args, { cwd: agentRoot, env: d.env });
+    startStdout = `${String((r && r.stdout) || "")}${String((r && r.stderr) || "")}`.trim();
     if (r && r.code !== 0) { launchFailed = true; d.log(`${mux.kind} start exited ${r.code}${r.stderr ? `: ${String(r.stderr).trim()}` : ""}`); }
     else if (!cmds.blocking) await waitForProbe(cmds.waitProbe, d);
   } catch (err) {
@@ -506,11 +610,69 @@ export async function runSupervisor(deps = {}) {
     d.log(`session ${muxName} stopped on ${stopping} — id kept, exit ${EXIT_RELAUNCH}`);
     return EXIT_RELAUNCH;
   }
-  const decision = rotationDecision({ record: launched, mode, exitCode, startedAt, endedAt, now: d.now });
+
+  // Did THIS launch ever report in? The single most useful fact about a run,
+  // and the one the ten-minute relaunch loop never asked: James's seat looked
+  // up for days and had not beaten once.
+  let endHeartbeat = null;
+  try { endHeartbeat = parseHeartbeat(d.readFileSync(paths.heartbeatFile, "utf8")); } catch { endHeartbeat = null; }
+  const endBeatMs = endHeartbeat && typeof endHeartbeat.ts === "string" ? Date.parse(endHeartbeat.ts) : NaN;
+  const beatSeen = Number.isFinite(endBeatMs) && endBeatMs >= startedAt;
+
+  // What the runtime itself said, if we caught it. `earlyPane` is the capture
+  // taken while a fast-failing session was still up; `lastPane` is the
+  // watchdog's. `startStdout` is whatever the mux client printed to us.
+  const evidence = [startStdout, earlyPane, lastPane].filter(Boolean).join("\n");
+  const failure = classifyLaunchFailure({ mode, exitCode, output: evidence, beatSeen });
+  if (failure.kind !== "none") d.log(`launch verdict: ${failure.kind}${failure.proven ? " (proven)" : ""} — ${failure.detail}`);
+
+  // ── (b) N IDENTICAL FAILURES ARE A FAULT, NOT N RETRIES ──────────────────
+  //
+  // The ten-minute backoff was the right instinct and the wrong outcome: every
+  // attempt failed identically and the seat stayed quiet about it for days,
+  // because the only record was a log on a machine nobody can reach. So the
+  // streak is counted across supervisor lifetimes and, at the limit, written
+  // where it LEAVES the machine — `state/session/attention.json` rides the
+  // presence beat as `machine.sessionNote`, which is the org's view of this
+  // seat. A watchdog restart is not counted here: that path has its own
+  // bounded budget (`carriedRestarts`) and counting it twice would escalate a
+  // fault the seat is already handling.
+  let escalation = { escalate: false, fresh: false, streak: 0, limit: d.launchFailureLimit, reason: "" };
+  if (!watchdogRestarted) {
+    const signature = launchFailureSignature({ mode, kind: failure.kind, exitCode });
+    const next = launchFailureStreak(priorFailures, { signature, at: new Date(Number(d.now())).toISOString() });
+    if (!next) {
+      // The launch worked. Evidence of work clears the record — the same reset
+      // rule `carriedRestarts` uses, and for the same reason.
+      try { d.unlinkSync(paths.launchFailuresFile); } catch { /* nothing carried */ }
+    } else {
+      escalation = escalationDecision({ streak: next.streak, limit: d.launchFailureLimit, escalatedAt: next.escalatedAt });
+      if (escalation.escalate && !next.escalatedAt) next.escalatedAt = new Date(Number(d.now())).toISOString();
+      try { d.writeJsonAtomic(paths.launchFailuresFile, next); } catch { /* the log line still says it */ }
+      d.log(`launch failure ${next.streak}× in a row (${signature}) — ${escalation.reason}`);
+      if (escalation.escalate) {
+        writeLaunchAttention({
+          d, paths, mux, muxName, now: d.now(),
+          streak: next.streak, limit: escalation.limit, signature,
+          detail: failure.detail, sessionId: launched.sessionId, phase: "failed",
+        });
+        if (escalation.fresh) d.log(`escalating to the org: ${escalationHint({ signature, streak: next.streak, limit: escalation.limit, detail: failure.detail, sessionId: launched.sessionId })}`);
+      }
+    }
+  }
+
+  const decision = rotationDecision({
+    record: launched, mode, exitCode, startedAt, endedAt, now: d.now,
+    resumeTargetMissing: failure.kind === "resume-target-missing",
+    beatSeen,
+    streakAtLimit: escalation.escalate,
+    selfStopped: watchdogRestarted,
+  });
   if (decision.action === "rotate") {
-    const rotated = rotateMainSession(launched, { now: d.now, uuid: d.uuid });
+    const why = decision.why || "the resume failed";
+    const rotated = rotateMainSession(launched, { now: d.now, uuid: d.uuid, reason: why });
     const res = saveMainSession(agentRoot, rotated, fsDeps);
-    d.log(`resume of ${launched.sessionId} failed inside the failure window — rotated to ${rotated.sessionId}${res.ok ? "" : ` (not saved: ${res.error})`}`);
+    d.log(`resume of ${launched.sessionId}: ${why}${decision.proven ? " (proven, so not rationed by the rotation budget)" : ""} — invalidated it and rotated to ${rotated.sessionId}${res.ok ? "" : ` (not saved: ${res.error})`}`);
   } else if (decision.action === "backoff") {
     d.log(`rotation budget spent for this hour — sleeping ${decision.sleepMs / 60000} min before relaunch`);
     await d.sleep(decision.sleepMs);
@@ -518,6 +680,37 @@ export async function runSupervisor(deps = {}) {
   return EXIT_RELAUNCH;
 }
 
+/**
+ * Write the escalation where it LEAVES THE MACHINE.
+ *
+ * `state/session/attention.json` is read by `lib/telemetry/collect#sessionNote`
+ * and rides the presence beat to hq as `machine.sessionNote` — the only channel
+ * out of a seat that accepts no ssh. The record is shaped exactly like the
+ * watchdog's (`first-run#attentionRecord` fields) so the existing reader needs
+ * no special case; `restarts: 0` is honest and, per `carriedRestarts`, cannot
+ * steal budget from the watchdog.
+ *
+ * @param {object} a
+ */
+export function writeLaunchAttention(a) {
+  const { d, paths, mux, muxName } = a;
+  const attach = mux && mux.kind === "tmux" ? `tmux attach -t =${muxName}` : `screen -r ${muxName}`;
+  const record = {
+    reason: "launch-failing",
+    since: new Date(Number(a.now)).toISOString(),
+    runMs: 0,
+    restarts: 0,
+    action: a.phase === "retrying" ? "wait" : "give-up",
+    attach,
+    signature: a.signature,
+    streak: a.streak,
+    limit: a.limit,
+    hint: escalationHint({ signature: a.signature, streak: a.streak, limit: a.limit, detail: a.detail, sessionId: a.sessionId }),
+  };
+  try { d.writeJsonAtomic(paths.attentionFile, record); } catch { /* the log line still says it */ }
+  return record;
+}
+
 const isMain = (() => {
   try { return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href; } catch { return false; }
 })();