@cohortapp/agent-sdk 2.18.13 → 2.18.14

package/bin/maestro.mjs

@@ -38,6 +38,7 @@ import { selectProvider } from "../lib/secrets/providers.mjs";
 import { syncSecrets, rotateSecret, makeBroker, auditLogPath } from "../lib/secrets/broker.mjs";
 import { applyBrandEnvCompat } from "../lib/env-compat.mjs";
 import { buildIgnoredDriftReport, formatIgnoredLine, IGNORED_DRIFT_REL } from "../lib/upgrade/ignored-drift.mjs";
+import { summarisePinnedDrift, formatPinnedDriftWarning } from "../lib/upgrade/pinned-drift.mjs";
 
 // Fleet back-compat FIRST: bridge NEOLITH_* ⇄ COHORT_* env names before any
 // env-first resolution below — installed hosts still export the legacy names.
@@ -1613,7 +1614,6 @@ Per-file behaviour:
       { sdkVersion: readFrameworkVersion(), at: new Date().toISOString() },
     );
     for (const f of ignoredDrift.files) console.log(formatIgnoredLine(f));
-    if (ignoredDrift.counts.drifts) warn(`${ignoredDrift.counts.drifts} protected file(s) drift from upstream — every upstream fix to those paths stops here until you port it (diff each against node_modules/@cohortapp/agent-sdk/<path>)`);
     if (!flags.dryRun) {
       try {
         const out = join(cwd, IGNORED_DRIFT_REL);
@@ -1622,6 +1622,43 @@ Per-file behaviour:
       } catch (e) { warn(`could not write ${IGNORED_DRIFT_REL}: ${e && e.message ? e.message : e}`); }
     }
   }
+  // ── THE PIN THAT STRANDS A FIX ──────────────────────────────────────────
+  // The per-file lines above say what every protected file looks like. They do
+  // not say which of them MATTERS, and on 2026-09-25 that distinction was the
+  // difference between a healthy fork and a seat dying at import time on a
+  // pinned `deliver.mjs`. `summarisePinnedDrift` asks the one question the
+  // report does not — is upstream carrying lines this pin refuses — and the
+  // warning names the file, the distance, the runnable remedy, and (because
+  // the obvious wrong response is to empty `.maestroignore`) which pins must
+  // stay. See lib/upgrade/pinned-drift.mjs for why `onlyUpstream > 0` rather
+  // than "drifts" is the predicate.
+  {
+    // `|| { files: [] }` and not `null`: here the upgrade has just RUN, so an
+    // empty ignored list is a measured answer ("your patterns matched nothing")
+    // and not the unreadable-report case. `null` would be read as unknown,
+    // which is the right answer for the beat's disk read and the wrong one
+    // here — the caller is the thing that took the measurement.
+    const pinSummary = summarisePinnedDrift(ignoredDrift || { files: [] }, {
+      pinCount: ignorePatterns ? ignorePatterns.length : 0,
+    });
+    const lines = formatPinnedDriftWarning(pinSummary);
+    if (lines.length) {
+      console.log();
+      // Tone follows the FACT, not the topic. A seat whose pins strand nothing
+      // gets a plain line — and it gets one rather than silence, because an
+      // all-clear that is printed every run is what makes the loud version
+      // believable the day it appears. Only a stranded fix, or a report that
+      // could not be read, earns the warning chevron.
+      const loud =
+        pinSummary.unknown === true || pinSummary.stranded > 0;
+      // The headline carries the chevron; the rest is the instruction under
+      // it, and an instruction printed in warning-yellow reads as five more
+      // problems rather than one problem and its fix.
+      if (loud) warn(lines[0]);
+      else console.log(`  · ${lines[0]}`);
+      for (const l of lines.slice(1)) console.log(`  ${l}`);
+    }
+  }
   if (counts.mergeKept) console.log(`  ~ ${counts.mergeKept} merge-mode kept (agents/ custom files preserved)`);
   if (counts.preserved) warn(`${counts.preserved} preserved (local edits — kept your version)`);
   if (counts.forced)    warn(`${counts.forced} force-overwritten (backups in .maestro/backup/)`);

package/docs/runbooks/fleet-rollout.md

@@ -153,13 +153,20 @@ the version moved, the beat is fresh, `maestro session status` is not
 fresh beat from a restarted DAEMON and still answer nothing — which is why the
 beat alone is never the proof.
 
-## One wrinkle: the gates dirty the tree
-
-`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 relaxed for it — the run names those paths and tells you
-to `git checkout --` them. The gate order also means a first run is unaffected:
-cleanliness is read before the gates run.
+## One wrinkle: the gates can dirty the tree
+
+If a gate writes into the working tree, a second run in a row refuses on a file
+the *first* run wrote. The clean-tree gate is not relaxed for it — the run names
+those paths and tells you to `git checkout --` them. The gate order also means a
+first run is unaffected: cleanliness is read before the gates run.
+
+~~"`npm test` appends to a tracked runtime ledger
+(`.claude-flow/policy/state.json`)"~~ — struck 2026-09-25. That was the one
+known instance, and it is fixed at the source rather than described: the file is
+a per-machine receipt chain (one signed receipt per MCP tool call, ~160 lines
+added per full `npm test`), it is now in `.gitignore`, and it is no longer
+tracked. Nothing in a normal run should trip this section today; the machinery
+stays because the next gate that writes into the tree will need it.
 
 ## Reading a round
 

package/docs/runbooks/recovery-and-failover.md

@@ -193,6 +193,24 @@ scripts/resume-operations.sh    # health check → rm .emergency-stop → reload
 `maestro doctor` FAILS while `.emergency-stop` is present, pointing at
 `resume-operations.sh`.
 
+The health check it runs is passed `--ignore-emergency-stop`: the stop flag is
+not a reason to refuse to lift the stop flag. (It was until 2026-09-25 —
+`healthcheck.sh` counts the flag as an error and the resume refused on any
+non-zero exit, so a seat sat halted until the flag was removed by hand.) Every
+other check still gates the resume, and two things follow from healthcheck's
+own exit contract:
+
+- **CRITICAL (exit 2) refuses**, leaves the flag in place, and NAMES the
+  blocking condition — e.g. `Blocking condition(s): config:priorities.yaml`.
+  You should never have to re-run the health check with a filter to find out
+  what stopped you.
+- **DEGRADED (exit 1 — warnings only) resumes**, printing the warnings.
+  "Operational with limitations" is what healthcheck means by degraded;
+  a missing optional repo is not grounds to keep a seat halted.
+
+Run `scripts/healthcheck.sh` on its own and the flag is still reported as an
+error, which is what an operator inspecting a halted seat needs to see.
+
 ---
 
 ## 7. Manual cadence-bus recovery (rarely needed)

package/lib/cadence-failure-class.mjs

@@ -0,0 +1,245 @@
+/**
+ * lib/cadence-failure-class.mjs — is this cadence failure worth retrying?
+ *
+ * THE FAULT THIS EXISTS FOR (measured, Eli Rosenberg's seat, 2026-09-24).
+ * His config scheduled the cadence `commitment-sweep` with
+ * `prompt: schedules/triggers/commitment-sweep.md`. That file was not on the
+ * seat. The consumer never checked: it rendered the handoff, `readFileSync`
+ * threw `ENOENT: no such file or directory`, the catch logged
+ * `handoff_failed_spawning_instead` and fell through to the spawn — which
+ * opens THE SAME PATH — and the tick went back on the bus. Measured at
+ * 16 requeues per 30 seconds, indefinitely. It is also the failure the seat's
+ * own emergency stop had been set to contain once before
+ * (`reason=meeting-action-capture requeue busy-loop containment`), so this
+ * shape has burned a seat down at least twice.
+ *
+ * The defect is not the missing file. It is that **every failure was treated
+ * as transient**. A file that does not exist will not exist on the next
+ * attempt 30 seconds later; retrying is not resilience, it is a busy loop with
+ * a log line. The bus already had a retry budget and a circuit breaker; what it
+ * did not have was the question *"can this possibly succeed if I try again?"*
+ *
+ * THE RULE, and its honest boundary. A permanent failure is one whose CAUSE
+ * cannot change as a result of waiting. That is not the same as "can never
+ * succeed": a human (or an `agent-sync`) could drop the missing prompt onto the
+ * seat between two attempts. So the policy here is NOT zero retries — it is a
+ * SMALL BOUNDED number of attempts (`PERMANENT_MAX_ATTEMPTS`) after which the
+ * tick is dead-lettered.
+ *
+ * ~~"and the long window is the cadence's OWN SCHEDULE: the next scheduled tick
+ * is a fresh event with a fresh budget, so a daily cadence re-tries twice a day
+ * ... What the classification removes is only the tight loop"~~ — struck
+ * 2026-09-25, on review of the lane that introduced it. The second half is
+ * true; the first half described a retry WINDOW this module does not enforce
+ * and cannot. `PERMANENT_MAX_ATTEMPTS` is a COUNT, not a delay. The next
+ * scheduled tick really is a fresh event with a fresh budget, but that only
+ * becomes "the window" AFTER the last attempt reaches dlq/ — and nothing here
+ * spaces the attempts before then. A caller that simply requeues gets its
+ * second attempt on the very next poll.
+ *
+ * What the classification actually buys, stated exactly: a fault whose cause
+ * cannot move goes from UNBOUNDED retries at drain speed (16 per 30 s, measured)
+ * to ONE extra attempt, then a stop with a durable record. Spacing that one
+ * extra attempt is the CALLER's job, because only the caller owns a clock —
+ * `cadence-consumer.mjs` `failPermanently` arms the per-cadence backoff gate for
+ * exactly that reason, so the retry cannot land in the same drain. Read the
+ * budget here as "how many", and look at the caller for "how far apart".
+ *
+ * THE IDIOM ALREADY EXISTED ONE LANE OVER. `scripts/daemon/assurance.mjs`
+ * `classifyFailure` asks exactly this question for the INBOX lane, and says why
+ * in the same words: "retrying a permanent fault burns another 45 minutes of
+ * the human's patience for the same outcome". The cadence lane never asked it.
+ * Two deliberate differences from that one: this classifier keys on the PHASE
+ * (we know whether we were touching the cadence's own prompt file, so an errno
+ * is unambiguous rather than a guess at a message), and it returns the attempt
+ * budget with the verdict so the caller does not re-derive the policy.
+ *
+ * ELSEWHERE IN THE DAEMON — the same shape, swept 2026-09-25. Four other retry
+ * loops were read for "does it ever inspect the error class?". None do. Three
+ * are BOUNDED, which is what keeps them out of this module for now; the fourth
+ * is not, and is deliberate:
+ *
+ *   - `dispatcher.mjs` backlog retries (MAX_BACKLOG_RETRIES = 6, plus a
+ *     post-failure cooldown). Bounded, but a permanent fault spends all six
+ *     sessions and six cooldowns to learn what the first one knew.
+ *   - `dispatcher.mjs` resume reconcile (RESUME_MAX_ATTEMPTS = 3 + a freshness
+ *     window + retire-on-no-id/no-prompt). Bounded. A dead `--resume` id burns
+ *     all three: "No conversation found with session ID" is as permanent as an
+ *     ENOENT and is never read as such.
+ *   - `lib/session/identity.mjs` `rotationDecision`. This one uses TIMING as a
+ *     proxy for the class question — a resume that dies inside 20 s rotates to
+ *     a fresh id, which is why James Kirkland's 2-second `--resume` failure is
+ *     handled at HEAD. But a failure that takes LONGER than the window returns
+ *     `{action:"relaunch"}`, and the relaunch re-uses the same dead id. A
+ *     timing proxy answers the wrong question; the message says "permanent"
+ *     outright.
+ *   - `cadence-consumer.mjs` `sweepHandoffTimeouts` → `handoff_requeue_failed`:
+ *     genuinely unbounded ("handoff kept open; retried next sweep"), and
+ *     deliberately so — the alternative is losing the tick. It is at least
+ *     loud (error level, every sweep). Nothing escalates it.
+ *
+ * PURE. Strings and numbers in, a verdict out. No fs, no clock, no env, no
+ * network — so the policy can be tested on its own (and reasoned about) without
+ * standing up a consumer. Never throws: a garbage input classifies as transient,
+ * because the safe default when we cannot tell is today's behaviour.
+ *
+ * @module lib/cadence-failure-class
+ */
+
+/** A failure whose cause cannot change by waiting. Bounded retries, then DLQ. */
+export const PERMANENT = "permanent";
+/** A failure that could plausibly succeed on the next attempt. Today's budget. */
+export const TRANSIENT = "transient";
+
+/**
+ * A CAP on how many attempts a PERMANENT failure gets before the tick is
+ * dead-lettered. A caller applies `min(its own budget, this)` — it lowers a
+ * budget, it never raises one.
+ *
+ * Why 2 and not 1: the cause can be repaired between attempts (someone writes
+ * the prompt file), and one extra attempt is cheap — a single spawn, not a
+ * loop. Why a cap at all, when the cadence consumer's own transient budget
+ * already happens to be 2: `failTick`'s default is 5 and other call sites use
+ * it, so the number has to be stated here rather than inherited from whichever
+ * lane happens to be calling.
+ *
+ * This is a COUNT and nothing else. It does not delay anything; two attempts
+ * with no spacing are two attempts in the same drain. The caller is what makes
+ * the extra attempt cost a backoff interval rather than a millisecond. The
+ * budget is the SMALLEST part of this fix; the larger parts are that a
+ * permanent failure stops where it is instead of falling through to a second
+ * code path that opens the same missing file, and that it is recorded and
+ * alerted rather than logged and forgotten.
+ */
+export const PERMANENT_MAX_ATTEMPTS = 2;
+
+/**
+ * The permanent codes, as a frozen set, so a caller can branch on the code
+ * without re-deriving the taxonomy.
+ * @type {Readonly<Record<string,string>>}
+ */
+export const PERMANENT_CODES = Object.freeze({
+  /** The cadence's prompt file is not on disk at the configured path. */
+  PROMPT_MISSING: "prompt_missing",
+  /** The prompt path exists but cannot be read as a file (perms / it's a dir). */
+  PROMPT_UNREADABLE: "prompt_unreadable",
+  /** The cadence has no handler and no prompt anywhere to fall back to. */
+  NO_PROMPT_CONFIGURED: "no_prompt_configured",
+});
+
+/** errno tokens that mean "this path is not a readable file, and waiting won't help". */
+const PERMANENT_PATH_ERRNOS = /\b(ENOENT|EACCES|EPERM|EISDIR|ENOTDIR|ELOOP|ENAMETOOLONG)\b/;
+/** errno tokens on a path that CAN clear on their own (busy fs, full disk, IO blip). */
+const TRANSIENT_PATH_ERRNOS = /\b(EBUSY|EAGAIN|EMFILE|ENFILE|ENOSPC|EIO|ETIMEDOUT)\b/;
+
+/**
+ * `realSpawnSession` exit codes that are not process exits at all but the
+ * consumer's own pre-flight verdicts. Kept here rather than re-matched from
+ * prose, because the message text is a log string and the number is a contract.
+ */
+export const SPAWN_EXIT_PROMPT_MISSING = -2;
+export const SPAWN_EXIT_PROMPT_READ_FAILED = -3;
+
+/**
+ * @typedef {object} CadenceFailureVerdict
+ * @property {"permanent"|"transient"} class  the verdict
+ * @property {string|null} code   a stable machine code for a permanent failure
+ *                                (`PERMANENT_CODES.*`), else null
+ * @property {number|null} maxAttempts  attempt budget the caller should apply;
+ *                                null means "the caller's own default"
+ * @property {string} reason      one short human line saying why
+ */
+
+/**
+ * Classify a cadence failure.
+ *
+ * @param {object} [failure]
+ * @param {string} [failure.error]     the error message / stderr tail
+ * @param {string} [failure.errno]     the Node error `code` (`err.code`), when
+ *        the caller has the Error object. THE MESSAGE IS NOT A CONTRACT AND THE
+ *        ERRNO IS — measured 2026-09-25: `readFileSync` on a DIRECTORY produces
+ *        exactly `EISDIR: illegal operation on a directory, read`, with no path
+ *        anywhere in it, so anything that recognises a path fault by finding the
+ *        path in the text misses the commonest unreadable case outright. When
+ *        `errno` is given it is authoritative and the text is not consulted for
+ *        the class; the text stays the fallback for callers that only have a
+ *        stderr tail (a sub-session's output is text, never an Error).
+ * @param {"prompt"|"spawn"} [failure.phase]
+ *        WHERE the failure happened. `"prompt"` means we were resolving or
+ *        reading the cadence's own prompt file — so a path errno is
+ *        unambiguously ABOUT that file, and we do not have to guess from the
+ *        message text. `"spawn"` (the default) means a sub-session ran.
+ * @returns {CadenceFailureVerdict}
+ */
+export function classifyCadenceFailure(failure = {}) {
+  try {
+    const text = typeof failure.error === "string" ? failure.error : String(failure.error ?? "");
+    const exitCode = Number.isFinite(failure.exitCode) ? failure.exitCode : null;
+    const phase = failure.phase === "prompt" ? "prompt" : "spawn";
+    // An explicit errno beats the message every time; falling back to the text
+    // is for callers holding a stderr tail rather than an Error.
+    const errno = typeof failure.errno === "string" && failure.errno ? failure.errno : null;
+    const hasErrno = (re) => (errno ? re.test(errno) : re.test(text));
+
+    // 1. The consumer's own pre-flight verdicts, by contract number.
+    if (exitCode === SPAWN_EXIT_PROMPT_MISSING) {
+      return permanent(PERMANENT_CODES.PROMPT_MISSING, "the cadence prompt file is not on disk");
+    }
+    if (exitCode === SPAWN_EXIT_PROMPT_READ_FAILED) {
+      // A read that failed for a reason that CAN clear (disk full, too many
+      // open files) is transient even though the exit code is the same.
+      if (hasErrno(TRANSIENT_PATH_ERRNOS)) {
+        return transient("prompt read failed for a cause that can clear on its own");
+      }
+      return permanent(PERMANENT_CODES.PROMPT_UNREADABLE, "the cadence prompt path is not a readable file");
+    }
+
+    // 2. The prompt phase: any path errno here is about the prompt file.
+    if (phase === "prompt") {
+      if (hasErrno(TRANSIENT_PATH_ERRNOS)) {
+        return transient("prompt I/O failed for a cause that can clear on its own");
+      }
+      if (hasErrno(/\bENOENT\b/) || /prompt not found/i.test(text)) {
+        return permanent(PERMANENT_CODES.PROMPT_MISSING, "the cadence prompt file is not on disk");
+      }
+      if (hasErrno(PERMANENT_PATH_ERRNOS)) {
+        return permanent(PERMANENT_CODES.PROMPT_UNREADABLE, "the cadence prompt path is not a readable file");
+      }
+      // A prompt-phase failure we do not recognise (a render bug, say) keeps
+      // the ordinary budget: we do not dead-letter on a guess.
+      return transient("prompt step failed for an unrecognised reason");
+    }
+
+    // 3. Spawn phase. `prompt not found:` is realSpawnSession's own wording and
+    //    is definitive wherever it surfaces; a bare errno in a sub-session's
+    //    stderr is NOT — it is far more likely to be about some file the session
+    //    itself touched than about the cadence. So we do not read it.
+    if (/prompt not found/i.test(text)) {
+      return permanent(PERMANENT_CODES.PROMPT_MISSING, "the cadence prompt file is not on disk");
+    }
+    if (/no handler and no prompt/i.test(text)) {
+      return permanent(PERMANENT_CODES.NO_PROMPT_CONFIGURED, "the cadence has neither a handler nor a prompt");
+    }
+    return transient("no rule recognises this failure as permanent");
+  } catch {
+    // A classifier that can throw is a classifier that can wedge the lane it
+    // advises. Unknown → transient → today's behaviour.
+    return transient("classifier error; defaulting to the retryable path");
+  }
+}
+
+/** Is a verdict (or a bare class string) permanent? */
+export function isPermanent(v) {
+  if (!v) return false;
+  return (typeof v === "string" ? v : v.class) === PERMANENT;
+}
+
+function permanent(code, reason) {
+  return { class: PERMANENT, code, maxAttempts: PERMANENT_MAX_ATTEMPTS, reason };
+}
+
+function transient(reason) {
+  return { class: TRANSIENT, code: null, maxAttempts: null, reason };
+}
+
+export default { classifyCadenceFailure, isPermanent, PERMANENT, TRANSIENT, PERMANENT_CODES, PERMANENT_MAX_ATTEMPTS };

package/lib/claude-bin.mjs

@@ -46,6 +46,31 @@ export function isSafeExecutable(p) {
   }
 }
 
+/**
+ * The fixed paths `resolveClaudeBin` searches, in order, AFTER $CLAUDE_BIN.
+ * `~/` is the seat's home directory.
+ *
+ * THIS IS THE ONE COPY. `lib/cli/doctor-checks.mjs` reports on exactly these
+ * paths and imports this list rather than restating it: a hand-copied twin is
+ * how the doctor comes to say a path resolves that the resolver never looks at
+ * (and vice versa), and nothing fails when it does.
+ */
+export const CLAUDE_BIN_CANDIDATES = Object.freeze([
+  "~/.local/bin/claude",
+  "/opt/homebrew/bin/claude",
+  "/usr/local/bin/claude",
+  "/usr/bin/claude",
+]);
+
+/**
+ * `CLAUDE_BIN_CANDIDATES` with `~/` expanded against `home`.
+ * @param {string} [home] defaults to this process's home directory
+ * @returns {string[]}
+ */
+export function claudeBinCandidatePaths(home = homedir()) {
+  return CLAUDE_BIN_CANDIDATES.map((c) => (c.startsWith("~/") ? join(home, c.slice(2)) : c));
+}
+
 /**
  * Return the absolute path to the Claude CLI. Searches, in order:
  *   1. $CLAUDE_BIN env var (if set + executable on disk)
@@ -70,13 +95,7 @@ export function resolveClaudeBin() {
       `non-writable executable. Falling back to default search paths.`
     );
   }
-  const candidates = [
-    join(homedir(), ".local/bin/claude"),
-    "/opt/homebrew/bin/claude",
-    "/usr/local/bin/claude",
-    "/usr/bin/claude",
-  ];
-  for (const c of candidates) {
+  for (const c of claudeBinCandidatePaths()) {
     if (existsSync(c)) { _resolved = c; return c; }
   }
   // Last resort: bare name (lets the OS PATH + spawn error stay informative).

package/lib/cli/doctor-checks.mjs

@@ -35,6 +35,7 @@ import { probeClaude as defaultProbeClaude } from "../setup/claude-probe.mjs";
 import { readSeatEngine } from "../runtime/adapter.mjs";
 import { sessionLiveness, SESSION_STALE_MS } from "../telemetry/collect.mjs";
 import { CONSOLE_KEY_REMEDY, SEAT_AUTH_VARS, REQUIRE_CONSOLE_KEY_VAR, seatAuthVerdict } from "./seat-auth.mjs";
+import { CLAUDE_BIN_CANDIDATES, isSafeExecutable } from "../claude-bin.mjs";
 
 export const SDK_PACKAGE = "@cohortapp/agent-sdk";
 /** The SDK checkout this module ships in — the source of the shipped hook copies. */
@@ -151,6 +152,132 @@ export function hookNodeResolvable({ onPath = "", isExecutable = () => false, ho
   };
 }
 
+/**
+ * Where `lib/claude-bin.mjs#resolveClaudeBin` looks, in order. `~/` is the
+ * seat's home. IMPORTED, never restated: this row's whole job is to describe
+ * what the resolver does, so the list it reports on has to be the resolver's
+ * own. A hand-copied twin drifted silently the moment a path was added to one
+ * of them.
+ */
+export { CLAUDE_BIN_CANDIDATES };
+/** Where the Claude Code installer keeps its versioned installs. */
+export const CLAUDE_VERSIONS_DIR = "~/.local/share/claude/versions";
+
+/**
+ * Can anything on this seat actually RUN `claude`?
+ *
+ * ── THE SEAT THIS EXISTS FOR ────────────────────────────────────────────────
+ * James Kirkland's machine, measured 2026-09-25: no `~/.local/bin/claude` at
+ * all, while `~/.local/share/claude/versions/` held 2.1.273 and 2.1.278. Every
+ * launch exited 127 — for days. `resolveClaudeBin` falls back to the bare name
+ * `"claude"` when none of its fixed paths exist, deliberately, so the spawn's
+ * own error stays informative; but nobody was reading the spawn's error, and
+ * nothing anywhere said the plainest possible thing: the binary is not there.
+ *
+ * So this says it plainly, and — because the repair genuinely is one line —
+ * it prints the line. A `versions/` directory with installs in it and no
+ * symlink pointing at one is an interrupted install, not a missing product.
+ *
+ * ── THE ROW MUST ASK WHAT THE RESOLVER ASKS ────────────────────────────────
+ * Two probes, because `resolveClaudeBin` uses two different gates and an `ok`
+ * that answers the wrong one is the exact blind spot this row exists to close:
+ *
+ *   $CLAUDE_BIN      — accepted only if `isSafeExecutable`: a regular file,
+ *                      not group/world-writable, owned by this uid or root
+ *                      (M2). A 0o777 binary is executable AND ignored, so
+ *                      asking X_OK alone reports `ok` for an override that
+ *                      never gets used and a seat that exits 127 every spawn.
+ *   the fixed paths  — accepted on mere `existsSync`. A present-but-chmod-644
+ *                      `~/.local/bin/claude` is therefore what the resolver
+ *                      returns, and the spawn fails with EACCES — which is a
+ *                      different fault, and a different repair, from "no
+ *                      binary is installed".
+ *
+ * Pure over its inputs; the caller supplies the probes.
+ *
+ * @param {object} o
+ * @param {string} [o.onPath]                 `which claude` output ("" when it does not resolve)
+ * @param {(p:string)=>boolean} [o.isExecutable] can it be executed (X_OK)
+ * @param {(p:string)=>boolean} [o.isSafe]    would claude-bin.mjs TRUST it as $CLAUDE_BIN (defaults to its own `isSafeExecutable`)
+ * @param {(p:string)=>boolean} [o.exists]    is it on disk at all (defaults to `isExecutable`, i.e. the pre-existing behaviour)
+ * @param {string} [o.home]                   the seat's home directory
+ * @param {string[]} [o.versions]             entries of ~/.local/share/claude/versions (newest need not be sorted)
+ * @param {string} [o.envOverride]            $CLAUDE_BIN, when set
+ * @returns {{level:"ok"|"warn"|"fail", msg:string}}
+ */
+export function claudeBinResolvable({ onPath = "", isExecutable = () => false, isSafe = isSafeExecutable, exists = null, home = "", versions = [], envOverride = "" } = {}) {
+  const abs = (c) => (c.startsWith("~/") ? `${home}/${c.slice(2)}` : c);
+  const onDisk = typeof exists === "function" ? exists : isExecutable;
+  const override = String(envOverride || "").trim();
+  if (override) {
+    const trusted = isSafe(override);
+    if (trusted && isExecutable(override)) return { level: "ok", msg: `Claude CLI: $CLAUDE_BIN resolves (${override})` };
+    if (trusted) {
+      return {
+        level: "warn",
+        msg: `Claude CLI: $CLAUDE_BIN is set to ${override}, which lib/claude-bin.mjs accepts but the OS will not execute — every session launch and every daemon spawn fails on it; chmod +x ${override} or unset CLAUDE_BIN`,
+      };
+    }
+    return {
+      level: "warn",
+      msg: `Claude CLI: $CLAUDE_BIN is set to ${override}, which lib/claude-bin.mjs IGNORES — it accepts an override only when it is a regular file, not group- or world-writable, and owned by you or root (M2); it falls through to the fixed paths instead. Unset it, or fix the file (chmod go-w ${override}) and point it at a real binary`,
+    };
+  }
+  let present = "";
+  for (const c of CLAUDE_BIN_CANDIDATES) {
+    if (c.startsWith("~/") && !home) continue;
+    const p = abs(c);
+    if (isExecutable(p)) return { level: "ok", msg: `Claude CLI: resolves at ${p}` };
+    if (!present && onDisk(p)) present = p;
+  }
+  // The resolver searches with existsSync, so a file that is THERE and not
+  // executable is the one it returns — and the spawn, not the search, is what
+  // fails. Saying "install Claude Code" here would send an operator to fix a
+  // thing that is not broken.
+  if (present) {
+    return {
+      level: "fail",
+      msg: `Claude CLI: ${present} exists but is not executable — lib/claude-bin.mjs resolves it on presence alone, so every session launch and every daemon spawn fails on it. Fix: chmod +x ${present}`,
+    };
+  }
+  const found = String(onPath || "").trim();
+  if (found) {
+    return {
+      level: "warn",
+      msg: `Claude CLI: \`claude\` is on your PATH (${found}) but at none of the fixed paths lib/claude-bin.mjs searches (${CLAUDE_BIN_CANDIDATES.join(", ")}) — launchd jobs get a bare environment and will not find it; symlink it: ln -sfn ${found} ${home ? `${home}/.local/bin/claude` : "~/.local/bin/claude"}`,
+    };
+  }
+  // An interrupted install: the product is here, the entry point is not.
+  const installs = (Array.isArray(versions) ? versions : []).map((v) => String(v && v.name ? v.name : v)).filter(Boolean);
+  if (installs.length > 0) {
+    const newest = [...installs].sort(compareVersionNames).pop();
+    const target = `${home || "~"}/.local/share/claude/versions/${newest}`;
+    const link = `${home || "~"}/.local/bin/claude`;
+    return {
+      level: "fail",
+      msg: `Claude CLI: no \`claude\` binary resolves, but ${installs.length} install(s) sit in ${CLAUDE_VERSIONS_DIR} (${installs.join(", ")}) — every session and every daemon spawn exits 127 until the symlink is back. Fix: mkdir -p ${home || "~"}/.local/bin && ln -sfn ${target} ${link}`,
+    };
+  }
+  return {
+    level: "fail",
+    msg: `Claude CLI: no \`claude\` binary resolves — not on PATH and at none of ${CLAUDE_BIN_CANDIDATES.join(", ")}, and ${CLAUDE_VERSIONS_DIR} holds no installs. Every session launch and every daemon spawn exits 127. Install Claude Code (curl -fsSL https://claude.ai/install.sh | bash), then re-run \`maestro doctor\``,
+  };
+}
+
+/** Sort helper: version-ish directory names, numerically where they look numeric. */
+function compareVersionNames(a, b) {
+  const seg = (v) => String(v).split(/[.\-]/).map((x) => (/^\d+$/.test(x) ? Number(x) : x));
+  const A = seg(a); const B = seg(b);
+  for (let i = 0; i < Math.max(A.length, B.length); i += 1) {
+    const x = A[i]; const y = B[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (typeof x === "number" && typeof y === "number") { if (x !== y) return x - y; continue; }
+    if (String(x) !== String(y)) return String(x) < String(y) ? -1 : 1;
+  }
+  return 0;
+}
+
 /**
  * Do the seat's copies of the pre-send hook and the send gate match the
  * versions this SDK ships? `maestro upgrade` keeps a locally modified copy (and
@@ -549,6 +676,27 @@ export async function runDoctorChecks(o = {}) {
     }
   }
 
+  // ── The Claude CLI itself (§3.1) ──────────────────────────────────────────
+  //
+  // Before "is the session job installed" comes "is there anything for it to
+  // run". A seat with a loaded job, a live supervisor and no binary exits 127
+  // on every launch and looks, from every other row here, entirely fine.
+  {
+    const home = o.home !== undefined ? o.home : homedir();
+    const isExecutable = o.isExecutable || ((p) => { try { accessSync(p, fsConstants.X_OK); return true; } catch { return false; } });
+    // The two gates `resolveClaudeBin` actually uses, wired to the real thing:
+    // `isSafeExecutable` for the $CLAUDE_BIN override (it is the resolver's own
+    // function, imported, not a restatement), `existsSync` for the fixed paths.
+    const isSafe = o.isSafe || isSafeExecutable;
+    const exists = o.existsSync || existsSync;
+    const listVersions = o.listClaudeVersions || (() => { try { return readdirSync(join(home, ".local", "share", "claude", "versions")); } catch { return []; } });
+    const binRow = claudeBinResolvable({
+      onPath: tryExec("which", ["claude"], { timeout: 2000 }).trim(),
+      isExecutable, isSafe, exists, home, versions: listVersions(), envOverride: env.CLAUDE_BIN || "",
+    });
+    rows.push(binRow);
+  }
+
   // ── Main session job (§3.1) ───────────────────────────────────────────────
   const listPlists = o.listPlists || (() => { try { return readdirSync(join(homedir(), "Library", "LaunchAgents")); } catch { return []; } });
   const loaded = parseLaunchctlList(tryExec("launchctl", ["list"], { timeout: 4000 }));
@@ -569,4 +717,4 @@ function pick(obj, keys) {
   return out;
 }
 
-export default { parseDotEnv, mask, authMode, looksLikeOrgId, orgIdShape, effectiveSource, sdkGlobalInstall, tailscaleSsh, sessionInstalled, hookNodeResolvable, hookCopyDrift, runDoctorChecks };
+export default { parseDotEnv, mask, authMode, looksLikeOrgId, orgIdShape, effectiveSource, sdkGlobalInstall, tailscaleSsh, sessionInstalled, hookNodeResolvable, hookCopyDrift, claudeBinResolvable, runDoctorChecks };

package/lib/diagnostics/alerts.mjs

@@ -91,6 +91,20 @@ export const DEFAULT_THRESHOLDS = Object.freeze({
     warnSec: 120, // 2 min (heartbeat refreshes ~15s)
     critSec: 300, // 5 min
   }),
+  cadencePermanentFailure: Object.freeze({
+    // A cadence failed for a cause that cannot change by waiting — its prompt
+    // file is not on disk, or the path is not readable. Unlike every other rule
+    // here, this one fires at ONE. The pattern-not-single-failure principle is
+    // about failures that are individually meaningless; a permanent failure is
+    // not one of those. It means a scheduled obligation has stopped running and
+    // will not start again until a person puts the file back — and the
+    // alternative to alerting is what actually happened on Eli Rosenberg's seat
+    // (2026-09-24): 16 requeues per 30 seconds for a day and a half, contained
+    // eventually by an emergency stop rather than noticed.
+    counters: Object.freeze(["cadence.permanent_failure"]),
+    warnCount: 1,
+    critCount: 3,
+  }),
   cadenceOutputMissing: Object.freeze({
     // A scheduled workflow finished without leaving its output artefacts behind.
     // This is the ONLY rule here not derived from the cadence bus, and that is
@@ -275,6 +289,7 @@ export function evaluateAlerts(args = {}) {
     push(alerts, costPerSessionRule(ledger, t.costPerSessionP99));
     push(alerts, absentAgentRule(presence, t.absentAgent));
     push(alerts, daemonDownRule(presence, t.daemonDown));
+    push(alerts, cadencePermanentFailureRule(snapshot, t.cadencePermanentFailure));
     push(alerts, cadenceOutputMissingRule(outputs, t.cadenceOutputMissing));
 
     // Deterministic order: critical first, then by id, so identical inputs always
@@ -380,6 +395,24 @@ function daemonDownRule(presence, cfg = {}) {
   };
 }
 
+/**
+ * A cadence failed permanently: the cause cannot change by waiting, so the tick
+ * was dead-lettered rather than retried (see lib/cadence-failure-class.mjs and
+ * the consumer's `failPermanently`). Fires at one, by design — see the
+ * threshold comment. The counter is durable (counters JSONL), so this stays
+ * true across a daemon restart within the day.
+ */
+function cadencePermanentFailureRule(snapshot, cfg = {}) {
+  const count = sumCounters(snapshot, cfg.counters);
+  const sev = severityFor(count, num(cfg.warnCount, Infinity), num(cfg.critCount, Infinity));
+  if (!sev) return null;
+  return {
+    id: "cadence_permanently_failing",
+    severity: sev,
+    detail: `${count} cadence tick(s) failed permanently today (warn ${num(cfg.warnCount)}, crit ${num(cfg.critCount)}) — a scheduled obligation is not running and retrying will not fix it. Read state/cadence-bus/dlq/ for the cadence and the code (prompt_missing = put the prompt file back).`,
+  };
+}
+
 /**
  * A scheduled workflow completed without producing its output artefacts.
  *