@cohortapp/agent-sdk 2.18.13 → 2.18.14

package/scripts/daemon/cadence-consumer.mjs

@@ -96,6 +96,13 @@ import { writeHandoff, listHandoffs, expireHandoffs, pruneHandoffs, handoffPaths
 import { writeFileAtomic } from "../../lib/fs-atomic.mjs";
 import { resolveClaudeBin as sharedResolveClaude } from "../../lib/claude-bin.mjs";
 import { getCadenceDef } from "./cadence-handlers.mjs";
+// PERMANENT vs TRANSIENT (lane/permanent-errors). A retry loop that never
+// inspects its error class is how two seats burned down: a cadence whose prompt
+// file does not exist retried at poll speed forever (measured 16 requeues per
+// 30 s on Eli Rosenberg's seat, 2026-09-24). The taxonomy is pure and lives on
+// its own so the policy can be argued with without a daemon.
+import { classifyCadenceFailure, isPermanent, PERMANENT_MAX_ATTEMPTS } from "../../lib/cadence-failure-class.mjs";
+import { bump as bumpCounter } from "../../lib/diagnostics/counters.mjs";
 import { obligationAllowedUnderPosture } from "../../lib/plan/compile.mjs";
 import { isHumanLaneCadence } from "../../lib/cadences.mjs";
 import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
@@ -636,6 +643,12 @@ export function startConsumer(opts = {}) {
   const budgetEscalateMs = opts.budgetEscalateMs ?? DEFAULT_BUDGET_ESCALATE_MS;
   const maxSpawnMs = opts.maxSpawnMs ?? DEFAULT_SPAWN_TIMEOUT_MS;
   const spawnSession = opts.spawnSession || realSpawnSession;
+  // Cadence registry lookup. Injectable because the config-driven half
+  // (`config/.cadence-registry.json`) is read once and memoised at module
+  // scope, which a hermetic test cannot re-point — and the permanent-error
+  // path is reached precisely through a CONFIGURED cadence whose prompt is
+  // absent, so it has to be reachable in a test.
+  const cadenceDef = typeof opts.getCadenceDef === "function" ? opts.getCadenceDef : getCadenceDef;
   const userLogger = opts.logger;
   // Test / tuning hooks for the reliability layer.
   const backoffSchedule = opts.backoffSchedule || BACKOFF_SCHEDULE_MS;
@@ -725,13 +738,64 @@ export function startConsumer(opts = {}) {
    * `renderCadencePromptBody`, so the handed-off prompt is byte-identical to
    * what a sub-session would have been given, parallelism directive included —
    * and land it under state/session/handoffs/prompts/<tickId>.md.
+   *
+   * WHY IT TAGS ITS OWN FAILURES. This function does two unrelated things: it
+   * READS the cadence's prompt (whose failure says the spawn cannot work
+   * either — the spawn opens the same path) and it WRITES a rendered copy into
+   * the handoff dir (whose failure says nothing about the spawn at all). The
+   * caller has to tell them apart, and the first attempt at that inferred it
+   * from the message — `msg.includes(promptPath)`.
+   *
+   * That inference is WRONG, measured 2026-09-25: `readFileSync` on a
+   * DIRECTORY throws exactly `EISDIR: illegal operation on a directory, read`,
+   * with no path in the text. A directory at the configured prompt path
+   * therefore passed the `existsSync` pre-check, threw here, was read as "not
+   * about the prompt", classified transient, and fell through to a spawn — the
+   * commonest unreadable case, and precisely the one the PROMPT_UNREADABLE code
+   * exists for. Node puts the path in the message for ENOENT and EACCES and
+   * not for EISDIR; no caller should have to know which.
+   *
+   * So the phase is not inferred, it is STAMPED, at the only two places that
+   * know it: `err.cadencePhase` is `"prompt"` on the read and `"handoff"` on
+   * everything after it. `err.cadenceErrno` carries `err.code` alongside, since
+   * the errno is the contract and the message is not.
    */
   function renderHandoffPrompt(tickId, promptPath) {
     const fullPrompt = join(agentRoot, promptPath);
-    const body = renderCadencePromptBody(agentRoot, readFileSync(fullPrompt, "utf-8"));
-    const out = join(handoffPaths(agentRoot).prompts, `${tickId}.md`);
-    writeFileAtomic(out, body);
-    return out;
+    let source;
+    try {
+      source = readFileSync(fullPrompt, "utf-8");
+    } catch (err) {
+      throw stampPhase(err, "prompt");
+    }
+    // Everything past the read is about OUR output, not the cadence's input:
+    // a render bug or an unwritable handoff dir leaves the spawn perfectly able
+    // to run, so neither may be read as a permanent prompt fault.
+    try {
+      const body = renderCadencePromptBody(agentRoot, source);
+      const out = join(handoffPaths(agentRoot).prompts, `${tickId}.md`);
+      writeFileAtomic(out, body);
+      return out;
+    } catch (err) {
+      throw stampPhase(err, "handoff");
+    }
+  }
+
+  /**
+   * Stamp an error with the phase it came from, so a catch does not have to
+   * guess. Non-destructive: an already-stamped error keeps its innermost phase
+   * (the read is nested inside nothing, but this keeps re-throws honest), and a
+   * non-object throw is wrapped rather than dropped.
+   */
+  function stampPhase(err, phase) {
+    if (!err || typeof err !== "object") {
+      const wrapped = new Error(String(err ?? "unknown error"));
+      wrapped.cadencePhase = phase;
+      return wrapped;
+    }
+    if (!err.cadencePhase) err.cadencePhase = phase;
+    if (!err.cadenceErrno && typeof err.code === "string") err.cadenceErrno = err.code;
+    return err;
   }
 
   /**
@@ -759,7 +823,7 @@ export function startConsumer(opts = {}) {
       // predicate both places — the daemon and the plan cannot disagree about
       // what is suspended.
       if (posture && cadence) {
-        const def = getCadenceDef(cadence) || {};
+        const def = cadenceDef(cadence) || {};
         const verdict = obligationAllowedUnderPosture(
           {
             kind: "SCHEDULE",
@@ -824,6 +888,13 @@ export function startConsumer(opts = {}) {
     handed_off: 0,
     handoff_timeouts: 0,
     deferred: 0,
+    // A failure the classifier called PERMANENT — the cause cannot change by
+    // waiting, so the tick was dead-lettered instead of retried. Rides the
+    // heartbeat (writeHealth) so `maestro cadence status` and the beat carry it
+    // without a new channel; `last_permanent_failure` names the cadence and the
+    // code so the reader does not have to go back to the log to find out which.
+    permanent_failures: 0,
+    last_permanent_failure: null,
     last_event_id: null,
     last_decision: null,
   };
@@ -887,6 +958,99 @@ export function startConsumer(opts = {}) {
     return { ok: false, decision: "deferred", reason };
   }
 
+  /**
+   * A failure the classifier calls PERMANENT: stop retrying, record it
+   * durably, and make it visible to a person.
+   *
+   * THE FAULT THIS CLOSES (Eli Rosenberg's seat, 2026-09-24). A cadence whose
+   * configured prompt file was not on disk requeued forever — measured at 16
+   * per 30 seconds — because nothing in the retry path ever asked whether the
+   * cause could change by waiting. It cannot: a file that does not exist will
+   * not exist 30 seconds later.
+   *
+   * Three things happen, and all three matter:
+   *
+   *  1. STOP. `failTick` with `min(this consumer's budget,
+   *     PERMANENT_MAX_ATTEMPTS)` — the permanent cap lowers a budget, never
+   *     raises one. Two attempts, then dlq/: not because the cause can never be
+   *     repaired (someone can drop the prompt onto the seat), but because it
+   *     cannot be repaired BY WAITING.
+   *
+   *     STATED HONESTLY (corrected 2026-09-25). `failTick`'s first outcome for
+   *     attempt 1 is a REQUEUE, so what this buys is "one extra attempt, then
+   *     stop" — not "the cadence's own schedule is the retry window", which is
+   *     what an earlier draft of this comment claimed. The schedule only
+   *     becomes the window once the last attempt reaches dlq/. Spacing the one
+   *     extra attempt is a separate act, and it is done here:
+   *     `holdCadenceForBackoff` moves the per-cadence gate forward so the retry
+   *     cannot land in the same drain that produced the first failure. The
+   *     measured before/after is 16 requeues per 30 s, unbounded → 2 attempts
+   *     one backoff interval apart, then a durable stop.
+   *
+   *     The budget is the smaller half of this; the bigger half is (2) and (3),
+   *     and that a permanent fault no longer falls through to a second code
+   *     path that opens the same missing file.
+   *  2. RECORD. The dlq/ file is the durable record and now carries
+   *     `permanent:<code>` in `last_error`, so the reason survives a restart
+   *     and a log rotation. A durable counter (`cadence.permanent_failure`)
+   *     goes to logs/diagnostics/counters/<day>.jsonl alongside it.
+   *  3. BE VISIBLE. The counter is what the seat's EXISTING alert lane reads
+   *     (lib/diagnostics/alerts.mjs `cadence_permanently_failing`, delivered by
+   *     the alerts cadence through config/alerts.yaml's webhook, or logged
+   *     when there is none) — no new channel. And `stats.permanent_failures`
+   *     rides the heartbeat, so the seat's health file and everything
+   *     downstream of it say so without anyone tailing a log.
+   *
+   * Never throws: the counter bump is best-effort by contract and failTick is
+   * already guarded.
+   *
+   * @param {object} event     the claimed tick
+   * @param {object} verdict   a CadenceFailureVerdict (class "permanent")
+   * @param {string} detail    the raw error text, for the dlq record + log
+   * @param {string} stage     log stage naming WHERE it was caught
+   */
+  function failPermanently(event, verdict, detail, stage) {
+    // The permanent cap LOWERS a budget, never raises one: if this consumer is
+    // already stricter than the cap, its own number wins.
+    const budget = Math.min(maxAttempts, verdict.maxAttempts ?? PERMANENT_MAX_ATTEMPTS);
+    const reason = `permanent:${verdict.code} — ${verdict.reason}${detail ? `: ${detail}` : ""}`;
+    log({
+      level: "error",
+      stage,
+      permanent: true,
+      code: verdict.code,
+      id: event.id,
+      cadence: event.cadence,
+      error: detail || verdict.reason,
+      max_attempts: budget,
+      note: "cause cannot change by waiting — one more attempt after the cadence backoff, then dead-lettered",
+    });
+    try {
+      bumpCounter("cadence.permanent_failure", { cadence: event.cadence, code: verdict.code }, { agentRoot });
+    } catch { /* a counter must never crash the path it observes */ }
+    stats.permanent_failures += 1;
+    stats.last_permanent_failure = {
+      cadence: event.cadence,
+      code: verdict.code,
+      at: new Date().toISOString(),
+    };
+    stats.last_decision = "permanent-failure";
+    // Space the one remaining attempt. Without this the requeue below is
+    // re-claimed by the very next drain pass — "bounded" but still at poll
+    // speed, which is the behaviour this lane exists to remove.
+    const heldUntil = holdCadenceForBackoff(event.cadence);
+    const outcome = failTick(agentRoot, event.id, reason, { maxAttempts: budget });
+    if (outcome?.destination === "dlq") stats.dlq += 1;
+    else {
+      stats.retries += 1;
+      log({ level: "warn", stage: "permanent_retry_held", id: event.id, cadence: event.cadence, code: verdict.code, retry_at: new Date(heldUntil).toISOString() });
+    }
+    // The heartbeat is the visible surface; write it now rather than waiting up
+    // to `heartbeatMs` for a reader to learn a cadence just died.
+    heartbeat();
+    return { ok: false, decision: outcome?.destination === "dlq" ? "dlq-permanent" : "failed-permanent", code: verdict.code };
+  }
+
   // Ledger hygiene runs from the sweep at most this often.
   const HANDOFF_PRUNE_EVERY_MS = 60 * 60_000;
   let lastHandoffPruneAt = 0;
@@ -989,20 +1153,47 @@ export function startConsumer(opts = {}) {
     s.failures += 1;
     // Exponential back-off honouring the (test-overridable) schedule.
     const idx = Math.min(s.failures, backoffSchedule.length - 1);
-    s.nextAllowedAt = Date.now() + backoffSchedule[idx];
+    s.nextAllowedAt = nowMs() + backoffSchedule[idx];
     if (s.failures >= circuitThreshold) {
-      s.openUntil = Date.now() + circuitDurationMs;
+      s.openUntil = nowMs() + circuitDurationMs;
       log({ level: "error", stage: "circuit_opened", cadence, failures: s.failures, open_until: new Date(s.openUntil).toISOString() });
       writeCircuitFile();
     }
   }
 
+  /**
+   * Hold a cadence off the spawn path for one backoff interval WITHOUT
+   * advancing it toward an open circuit.
+   *
+   * WHY IT IS SEPARATE FROM `recordSubsessionFailure`. A permanent failure is
+   * not a flaky sub-session: counting it toward `circuitThreshold` would trip a
+   * breaker whose whole job is to ride out a bad patch, for a cause that has no
+   * patch to ride out. What it DOES need is spacing — `PERMANENT_MAX_ATTEMPTS`
+   * is a count, not a delay, and `failPermanently`'s first outcome is a requeue,
+   * so without this the "one extra attempt" lands in the very same drain that
+   * produced the first. `escalate` consults `isCadenceAllowed` before it reaches
+   * the prompt at all, so moving `nextAllowedAt` forward is all it takes for the
+   * extra attempt to cost a real interval rather than a millisecond.
+   *
+   * Idempotent-ish and monotonic: never moves the hold EARLIER, so a circuit or
+   * a longer transient backoff already in force keeps its own deadline.
+   */
+  function holdCadenceForBackoff(cadence) {
+    const s = getCadenceState(cadence);
+    // The first rung is deliberately 0 ("retry immediately once"); a permanent
+    // fault has already proved it needs a gap, so take the first NON-zero rung.
+    const step = backoffSchedule.find((ms) => ms > 0) ?? 0;
+    const until = nowMs() + step;
+    if (until > s.nextAllowedAt) s.nextAllowedAt = until;
+    return s.nextAllowedAt;
+  }
+
   function writeCircuitFile() {
     // Persist the open-circuit snapshot so doctor + the operator can see
     // which cadences are currently held back without scraping logs.
     const open = {};
     for (const [cad, s] of cadenceState.entries()) {
-      if (s.openUntil > Date.now()) {
+      if (s.openUntil > nowMs()) {
         open[cad] = { failures: s.failures, open_until: new Date(s.openUntil).toISOString() };
       }
     }
@@ -1020,7 +1211,7 @@ export function startConsumer(opts = {}) {
 
   function isCadenceAllowed(cadence) {
     const s = getCadenceState(cadence);
-    const now = Date.now();
+    const now = nowMs();
     if (s.openUntil > now) return { allowed: false, reason: "circuit-open", retry_at: s.openUntil };
     if (s.nextAllowedAt > now) return { allowed: false, reason: "backoff", retry_at: s.nextAllowedAt };
     // Circuit closes automatically when openUntil passes.
@@ -1107,7 +1298,7 @@ export function startConsumer(opts = {}) {
       }
     }
 
-    const def = getCadenceDef(event.cadence);
+    const def = cadenceDef(event.cadence);
     let promptPath = def?.prompt;
     if (!promptPath) {
       // Unknown cadence — try the conventional location.
@@ -1121,6 +1312,15 @@ export function startConsumer(opts = {}) {
         stats.dlq += 1;
         return { ok: false, decision: "dlq-no-prompt" };
       }
+    } else if (!existsSync(join(agentRoot, promptPath))) {
+      // THE ELI FAULT, caught before it can loop. The `!promptPath` branch above
+      // has checked the conventional path since it was written; a prompt named
+      // by CONFIG was never checked at all — it was handed straight to the
+      // handoff renderer and then, when that threw, to the spawn, which opens
+      // the same path. Both fail, neither is terminal, and the tick comes back
+      // on the bus 30 seconds later. Check it once, here, and classify.
+      const verdict = classifyCadenceFailure({ phase: "prompt", error: `prompt not found: ${promptPath}` });
+      return failPermanently(event, verdict, `configured prompt missing: ${promptPath}`, "escalate_prompt_missing");
     }
 
     // Per-cadence in-flight guard (F9): never the same cadence twice at once —
@@ -1139,31 +1339,69 @@ export function startConsumer(opts = {}) {
       const fd = frontDoorState();
       const verdict = shouldHandOffTick({ ...fd, mode: def?.mode, metadata: event.metadata });
       if (verdict.handOff) {
+        // The PROMPT read is its own step, with its own catch. It used to sit
+        // inside the handoff try/catch, so a prompt that could not be read was
+        // indistinguishable from a handoff file that could not be written — and
+        // the shared catch fell through to the spawn, which opens the same
+        // prompt path. That is the busy loop: `handoff_failed_spawning_instead`
+        // 16 times per 30 seconds on Eli Rosenberg's seat, 2026-09-24.
+        // Split apart, each failure gets the answer it deserves: a permanent
+        // prompt fault stops here; an unwritable handoff still falls through,
+        // because the spawn genuinely might work.
+        let rendered = null;
         try {
-          const rendered = renderHandoffPrompt(event.id, promptPath);
-          const h = writeHandoff(agentRoot, {
-            tickId: event.id,
-            cadence: event.cadence,
-            mode: def?.mode || "escalate",
-            promptPath: rendered,
-            metadata: { ...(event.metadata || {}), sourcePrompt: promptPath },
-          }, { now: nowMs(), deadlineMs: handoffDeadlineMs });
-          if (!h.ok) throw new Error(h.error || "handoff write failed");
-          completeTick(agentRoot, event.id, {
-            decision: "handed-to-session",
-            cadence: event.cadence,
-            prompt: promptPath,
-            handoff: h.path,
-            deadline_at: h.handoff && h.handoff.deadlineAt,
-          });
-          stats.handed_off += 1;
-          stats.last_decision = "handed-to-session";
-          log({ level: "info", stage: "handed_to_session", id: event.id, cadence: event.cadence, prompt: rendered, deadline_at: h.handoff && h.handoff.deadlineAt });
-          return { ok: true, decision: "handed-to-session" };
+          rendered = renderHandoffPrompt(event.id, promptPath);
         } catch (err) {
-          // A handoff we could not write is not a reason to lose the tick —
-          // fall through to the legacy spawn, loudly.
-          log({ level: "warn", stage: "handoff_failed_spawning_instead", id: event.id, cadence: event.cadence, error: err && err.message });
+          // renderHandoffPrompt stamps which half failed (see its doc): the
+          // READ of the cadence prompt, or everything after it. Only the read
+          // says anything about whether a spawn would work — the spawn opens
+          // the same path — so only `cadencePhase === "prompt"` may reach a
+          // permanent verdict. An unwritable handoff dir falls through to the
+          // spawn like any other handoff fault.
+          //
+          // This used to be inferred from `msg.includes(promptPath)`, which is
+          // false for EISDIR (Node omits the path), so the commonest unreadable
+          // case — a DIRECTORY at the prompt path — fell through and spawned.
+          // Never classify a path fault by whether the message quotes the path.
+          const msg = (err && err.message) || "";
+          const promptVerdict = classifyCadenceFailure({
+            phase: err?.cadencePhase === "prompt" ? "prompt" : "spawn",
+            error: msg,
+            errno: err?.cadenceErrno,
+          });
+          if (isPermanent(promptVerdict)) {
+            return failPermanently(event, promptVerdict, msg, "handoff_prompt_failed_permanently");
+          }
+          log({ level: "warn", stage: "handoff_render_failed_spawning_instead", id: event.id, cadence: event.cadence, phase: err?.cadencePhase || null, error: msg });
+        }
+        if (rendered) {
+          try {
+            const h = writeHandoff(agentRoot, {
+              tickId: event.id,
+              cadence: event.cadence,
+              mode: def?.mode || "escalate",
+              promptPath: rendered,
+              metadata: { ...(event.metadata || {}), sourcePrompt: promptPath },
+            }, { now: nowMs(), deadlineMs: handoffDeadlineMs });
+            if (!h.ok) throw new Error(h.error || "handoff write failed");
+            completeTick(agentRoot, event.id, {
+              decision: "handed-to-session",
+              cadence: event.cadence,
+              prompt: promptPath,
+              handoff: h.path,
+              deadline_at: h.handoff && h.handoff.deadlineAt,
+            });
+            stats.handed_off += 1;
+            stats.last_decision = "handed-to-session";
+            log({ level: "info", stage: "handed_to_session", id: event.id, cadence: event.cadence, prompt: rendered, deadline_at: h.handoff && h.handoff.deadlineAt });
+            return { ok: true, decision: "handed-to-session" };
+          } catch (err) {
+            // A handoff FILE we could not write is not a reason to lose the tick,
+            // and it says nothing about whether the spawn would work — fall
+            // through to the legacy spawn, loudly, exactly as before. The prompt
+            // half of this, which DOES say so, is handled above.
+            log({ level: "warn", stage: "handoff_failed_spawning_instead", id: event.id, cadence: event.cadence, error: err && err.message });
+          }
         }
       }
     }
@@ -1292,6 +1530,15 @@ export function startConsumer(opts = {}) {
     stats.spawn_failures += 1;
     recordSubsessionFailure(event.cadence);
     const reason = result.error || (stderrTail ? `exit ${result.exit_code}: ${stderrTail}` : `exit ${result.exit_code}`);
+    // Can this possibly succeed if we try again? `realSpawnSession` answers
+    // -2 (prompt not on disk) / -3 (prompt unreadable) for causes that do not
+    // move; those get the classifier's bounded budget and a durable,
+    // visible record. Everything else — a timeout, a non-zero exit, a crash —
+    // is transient and unchanged.
+    const spawnVerdict = classifyCadenceFailure({ phase: "spawn", exitCode: result.exit_code, error: reason });
+    if (isPermanent(spawnVerdict)) {
+      return failPermanently(event, spawnVerdict, reason, "subsession_failed_permanently");
+    }
     const outcome = failTick(agentRoot, event.id, reason, { maxAttempts });
     if (outcome?.destination === "dlq") stats.dlq += 1;
     else stats.retries += 1;
@@ -1304,7 +1551,7 @@ export function startConsumer(opts = {}) {
     stats.received += 1;
     stats.last_event_id = event.id;
 
-    const def = getCadenceDef(event.cadence);
+    const def = cadenceDef(event.cadence);
     if (def?.mode === "inline" && typeof def.handler === "function") {
       try {
         const out = await def.handler({ event, agentRoot, log });

package/scripts/emergency-stop.sh

@@ -1,13 +1,42 @@
 #!/bin/bash
 # Emergency Stop — Immediately halts all Maestro agent operations.
-# Usage: ./scripts/emergency-stop.sh
+# Usage: ./scripts/emergency-stop.sh [--dry-run] [--help]
 #
 # This script is the kill switch for all autonomous operations:
 #   1. Drops .emergency-stop flag (every workflow / cadence consumer / enqueue
 #      script honours this on the next tick).
 #   2. Unloads every installed `ai.maestro.<agent>-*` (and legacy
 #      `ai.adaptic.<agent>-*`) launchd job.
-#   3. Kills running Claude Code subagent processes.
+#   3. Kills running Claude Code subagent processes (EXCEPT this process and
+#      its ancestors — see step 3).
+#
+# --dry-run
+#   Report the kill set instead of signalling it. The flag and the launchd
+#   unload still happen; only the signals are withheld — and BOTH the closing
+#   banner and the log line say "DRY RUN — NO PROCESSES SIGNALLED", so a dry
+#   run can never be mistaken for a halt. It exists so the self-sparing in
+#   step 3 is testable without a suite that kills the operator's own session
+#   to prove that it does not.
+#
+#   WHY A FLAG AND NOT AN ENV VAR. This used to be read from the ambient
+#   environment as MAESTRO_EMERGENCY_STOP_DRY_RUN, while step 4 printed
+#   "EMERGENCY STOP COMPLETE — All operations halted" unconditionally. A stray
+#   `export`, a line in .env, or an EnvironmentVariables entry in a plist
+#   would therefore turn the kill switch into a no-op — every claude process
+#   surviving — while the banner and the log both asserted the halt had
+#   succeeded. That is the same fault class this file was being repaired for:
+#   something that looks like it is handling the case and is not. On a
+#   break-glass control the escape hatch must be typed at the call site, once,
+#   deliberately. The env var is NOT consulted; setting it does nothing.
+#
+# SCOPE OF THE KILL (step 3), stated rather than hidden: every process of THIS
+# user whose command line matches `claude`, minus this process and its
+# ancestors. That is machine-wide, not agent-scoped — an unrelated Claude
+# session of yours in another directory WILL be terminated (21 processes
+# matched on the host where this was measured). Nothing here can narrow it
+# honestly, because a Claude Code session's argv does not carry the agent dir;
+# so the set is printed before it is signalled, and --dry-run shows it without
+# signalling anything.
 #
 # Plist resolution: the agent's first-name slug is read from config/agent.json
 # (SOT) so unload targets the correct labels; falls back to the directory
@@ -21,6 +50,25 @@ LOG_FILE="$AGENT_DIR/logs/emergency-stop.log"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
 
+# Argument parsing runs BEFORE anything is halted: a typo must refuse loudly,
+# not drop the flag and then exit.
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --dry-run) DRY_RUN=1 ;;
+        -h | --help)
+            sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+            exit 0
+            ;;
+        *)
+            echo "emergency-stop: unknown argument: $1" >&2
+            echo "Usage: emergency-stop.sh [--dry-run]" >&2
+            exit 2
+            ;;
+    esac
+    shift
+done
+
 # Resolve agent first-name slug from SOT (config/agent.json) so the unload
 # loop targets the right launchd labels. Falls back to the basename of the
 # agent directory (stripping -ai suffix).
@@ -39,7 +87,11 @@ LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
 # (deployed agents whose plists predate the rename). The loops guard with [ -f ].
 PLIST_GLOB="$LAUNCH_AGENTS_DIR/ai.maestro.${AGENT_FIRST}-*.plist $LAUNCH_AGENTS_DIR/ai.adaptic.${AGENT_FIRST}-*.plist"
 
-echo "[$TIMESTAMP] EMERGENCY STOP INITIATED (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
+if [ "$DRY_RUN" -eq 1 ]; then
+    echo "[$TIMESTAMP] EMERGENCY STOP DRY RUN INITIATED (agent=$AGENT_FIRST) — no process will be signalled" | tee -a "$LOG_FILE"
+else
+    echo "[$TIMESTAMP] EMERGENCY STOP INITIATED (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
+fi
 
 # 1. Drop the stop flag FIRST so any in-flight work sees it on next tick.
 echo "$TIMESTAMP" > "$AGENT_DIR/.emergency-stop"
@@ -57,23 +109,72 @@ for plist in $PLIST_GLOB; do
 done
 echo "[$TIMESTAMP] Unloaded $unloaded launchd job(s)" >> "$LOG_FILE"
 
-# 3. Kill running Claude Code subagent processes. Filter to processes that
-#    have AGENT_ROOT or this agent's directory in their cwd to avoid
-#    killing unrelated claude sessions the operator may have running.
+# 3. Kill running Claude Code subagent processes.
+#
+#    THE MIRROR-IMAGE FAULT THIS FIXES: `pgrep -f claude` matches the process
+#    that is RUNNING THIS SCRIPT whenever an agent session invokes it — which
+#    is the normal way it gets invoked. The stop then killed its own caller
+#    mid-flight, so step 4 never ran and the halt was never logged complete:
+#    a script that destroys the condition it needs in order to finish, the
+#    same shape as resume-operations.sh refusing to lift its own stop flag.
+#    The comment here also claimed a cwd filter that did not exist.
+#
+#    So: build the kill set, then subtract this process and every ancestor of
+#    it. Everything else matching `claude` is still terminated — the stop is
+#    still a kill switch, it just no longer includes the hand on the switch.
+#    See SCOPE OF THE KILL in the header: "everything else" really does mean
+#    every matching process of this user on this machine, so it is printed.
 echo "Stopping Claude Code agent processes..."
-# pgrep -lf is more selective than pkill -f
-pids=$(pgrep -f "claude" 2>/dev/null | tr '\n' ' ' || true)
-if [ -n "$pids" ]; then
+
+# PIDs to spare: this shell and its whole ancestor chain (the launching
+# session, its shell, launchd). Walk up via ppid until PID 1.
+SPARE=" $$ "
+_p=$$
+while [ -n "$_p" ] && [ "$_p" -gt 1 ]; do
+    _p=$(ps -o ppid= -p "$_p" 2>/dev/null | tr -d ' ')
+    [ -n "$_p" ] || break
+    SPARE="$SPARE$_p "
+done
+
+# claude_targets — matching PIDs (this user only) minus the spare set.
+claude_targets() {
+    local out=""
+    local pid
+    for pid in $(pgrep -u "$(id -u)" -f "claude" 2>/dev/null || true); do
+        case "$SPARE" in
+            *" $pid "*) continue ;;
+        esac
+        out="$out$pid "
+    done
+    printf '%s' "$out"
+}
+
+pids=$(claude_targets)
+if [ "$DRY_RUN" -eq 1 ]; then
+    echo "[DRY-RUN] sparing:$SPARE"
+    echo "[DRY-RUN] would terminate: ${pids:-<none>}"
+    echo "[$TIMESTAMP] DRY RUN — would terminate: ${pids:-<none>}" >> "$LOG_FILE"
+elif [ -n "$pids" ]; then
+    # Name the set before signalling it — this is machine-wide for this user.
+    echo "Terminating (every matching process of this user, not just this agent): $pids"
     # Send SIGTERM first, give 3s, then SIGKILL stragglers.
     kill -TERM $pids 2>/dev/null || true
     sleep 3
-    still=$(pgrep -f "claude" 2>/dev/null | tr '\n' ' ' || true)
-    [ -n "$still" ] && kill -KILL $still 2>/dev/null || true
+    still=$(claude_targets)
+    if [ -n "$still" ]; then kill -KILL $still 2>/dev/null || true; fi
     echo "[$TIMESTAMP] Claude processes terminated ($pids)" >> "$LOG_FILE"
+else
+    echo "[$TIMESTAMP] No Claude processes to terminate (self/ancestors spared)" >> "$LOG_FILE"
 fi
 
-# 4. Log completion.
-echo "[$TIMESTAMP] EMERGENCY STOP COMPLETE — All operations halted" | tee -a "$LOG_FILE"
+# 4. Log completion. A dry run says so in BOTH places — the banner an operator
+#    reads and the log an incident review reads — because the previous version
+#    printed the halt banner either way.
+if [ "$DRY_RUN" -eq 1 ]; then
+    echo "[$TIMESTAMP] EMERGENCY STOP DRY RUN — NO PROCESSES SIGNALLED (flag set, launchd unloaded)" | tee -a "$LOG_FILE"
+else
+    echo "[$TIMESTAMP] EMERGENCY STOP COMPLETE — All operations halted" | tee -a "$LOG_FILE"
+fi
 echo ""
 echo "To resume operations:"
 echo "  ./scripts/resume-operations.sh"

package/scripts/fleet/rollout.mjs

@@ -262,13 +262,20 @@ export function gateLine(r) {
 }
 
 /**
- * A note about paths the GATES themselves dirtied. `npm test` appends to a
- * tracked runtime ledger (.claude-flow/policy/state.json), so a second run in a
- * row would refuse on a file the first run wrote. The clean-tree gate is NOT
+ * A note about paths the GATES themselves dirtied: a second run in a row would
+ * otherwise refuse on a file the FIRST run wrote. The clean-tree gate is NOT
  * weakened for this — publishing a tree you cannot describe stays a refusal —
  * the run just says which paths are the gates' own leavings so the operator
  * reverts them instead of hunting them. Pure.
  *
+ * ~~"`npm test` appends to a tracked runtime ledger
+ * (.claude-flow/policy/state.json)"~~ — struck 2026-09-25: that file is the
+ * reason this function exists, and it is no longer tracked (it is a per-machine
+ * receipt chain, so it never should have been; `.gitignore` says why). This
+ * function stays because the SHAPE recurs — the next gate that writes into the
+ * tree will do the same thing — and because naming the paths beats hunting
+ * them. When it returns null for a whole rollout, that is the expected reading.
+ *
  * @param {string[]} before dirty paths before the gates ran
  * @param {string[]} after  dirty paths after
  * @returns {string|null}