@cohortapp/agent-sdk 2.18.12 → 2.18.14

package/lib/org/inbound/directedness.mjs

@@ -480,7 +480,11 @@ function yes(surface, reason, extra = {}) {
  * @param {import("./facts.mjs").Facts} facts
  * @param {{enabled?: Record<string,boolean>, meAliases?: string[]}} [opts]
  *   `meAliases` — additional identity strings for this seat (slug, member id,
- *   agent email). Used ONLY to widen own-echo suppression; never to widen reach.
+ *   agent email). Widens own-echo suppression AND, as of TD-001, is also
+ *   load-bearing for reach: branch (5) matches a structured mentions[] row
+ *   against this same alias set, not against bare `me`, so a seat called with
+ *   its slug still resolves a mentions[] row keyed by CUID. A caller that
+ *   omits meAliases here loses that match, not just echo suppression.
  * @returns {{directed:boolean, surface:string|null, reason:string, why:string}}
  */
 export function resolveDirected(cand, me, facts = {}, opts = {}) {
@@ -535,7 +539,7 @@ export function resolveDirected(cand, me, facts = {}, opts = {}) {
 
   switch (cand.family) {
     case "messaging":
-      return resolveMessaging(cand, meId, facts, on);
+      return resolveMessaging(cand, meId, facts, on, meAliases);
     case "calling":
       return resolveCalling(cand, meId, facts, on);
     case "board":
@@ -603,7 +607,7 @@ function resolveCalendar(cand, me, facts, on) {
  *   6. thread root I have spoken in / been named in → `thread_reply`
  *   7. otherwise                            → ambient chatter, not directed
  */
-function resolveMessaging(cand, me, facts, on) {
+function resolveMessaging(cand, me, facts, on, meAliases) {
   const channelId = cand.ids.channelId;
   const visible = asSet(facts.visibleChannelIds);
   const members = asSet(facts.memberChannelIds);
@@ -656,8 +660,20 @@ function resolveMessaging(cand, me, facts, on) {
 
   // (5) An explicit @mention of my member id. The mention list is NOT in the
   //     chain payload; it comes from `messaging.history`, which hq ACLs to rooms
-  //     I may read.
-  if (msg && Array.isArray(msg.mentions) && me && msg.mentions.map(String).includes(me)) {
+  //     I may read. mentions[] holds member CUIDs, but the caller cannot always
+  //     know which namespace it handed us as `me` (slug vs cuid) — so match the
+  //     row against the SAME alias set the own-echo drop uses, not bare `me`.
+  //     Otherwise a seat called with its slug never matches a CUID mention row,
+  //     and the prose fallback below (now gated on an empty mentions[]) is the
+  //     only remaining catch — which the gate removes. Fall back to bare `me`
+  //     if no alias set was threaded through.
+  const mentionRow = msg && Array.isArray(msg.mentions) ? msg.mentions : null;
+  const mentionsMe =
+    mentionRow &&
+    (meAliases instanceof Set
+      ? mentionRow.some((m) => meAliases.has(String(m).trim()))
+      : me && mentionRow.map(String).includes(me));
+  if (mentionsMe) {
     return on("mention") ? yes("mention", "mention") : no("surface_disabled");
   }
 
@@ -670,8 +686,12 @@ function resolveMessaging(cand, me, facts, on) {
 
   // A mention by DISPLAY NAME, when the org has no structured mention row (an
   // agent addressed as "@Isla" in prose). Only ever consulted for a space I can
-  // already read, and only when the caller supplied its own names.
-  if (msg && matchesMyName(facts, msg.body ?? msg.text)) {
+  // already read, only when the caller supplied its own names, and — per
+  // matchesMyName's own contract — only as a LAST RESORT: a populated
+  // mentions[] row means hq already told us who this was for, and prose
+  // naming someone else in the same breath must not override that.
+  const hasStructuredMentions = msg && Array.isArray(msg.mentions) && msg.mentions.length > 0;
+  if (msg && !hasStructuredMentions && matchesMyName(facts, msg.body ?? msg.text)) {
     return on("mention") ? yes("mention", "named") : no("surface_disabled");
   }
 

package/lib/org/quota.mjs

@@ -22,6 +22,20 @@
  * Money stays a decimal string of integer micro-USD end to end; nothing here
  * turns it into a float except the display helpers budget-guard calls.
  *
+ * ## The one import from `lib/engine`, and why it is deliberate (W16)
+ *
+ * `readEnforcementState` / `readQuotaSourceState` below come from
+ * `lib/engine/wire/errors.mjs` — the only non-test import from `lib/org` into
+ * `lib/engine` in this repo. It is a considered choice, not an accident:
+ * `parseCohortSseFrame` here and `readCohortFrame` there are two parsers of the
+ * SAME `event: cohort` frame, and the §4.8 vocabularies they read
+ * (`off|shadow|on`, `ledger|unreadable|not_read|not_admitted`) are exactly the
+ * kind of pinned value set that drifts when it is written down twice — a
+ * gateway that adds a fourth mode would then reach one parser as a new word and
+ * the other as silence. The alternative was a duplicated set, i.e. the drift.
+ * If this layering is ever unwanted, move those two readers to a leaf module
+ * both layers may import; do NOT re-declare the value sets here.
+ *
  * @module lib/org/quota
  */
 
@@ -31,6 +45,11 @@ import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 
 import { writeJsonAtomic } from "../fs-atomic.mjs";
+// W16: the §4.8 vocabularies for `enforcement` and `quota_source` are parsed in
+// exactly one place, the engine's wire reader. Both helpers are pure and total.
+// Restating the value sets here is how the two frame parsers in this repo would
+// start disagreeing about what the gateway said.
+import { readEnforcementState, readQuotaSourceState } from "../engine/wire/errors.mjs";
 
 /** The cache may never be older than this (the pre-spawn gate reads it). */
 export const QUOTA_MAX_TTL_MS = 30_000;
@@ -192,6 +211,14 @@ export function parseCohortSseFrame(input) {
     requestId: str(obj.request_id) || str(obj.requestId),
     modelTier: str(obj.model_tier) || str(obj.modelTier),
     costMicros: micros(obj.cost_micros ?? obj.costMicros),
+    // W16 (hq a60b9595, design §4.8). `enforcement` qualifies `costMicros`:
+    // only under "on" did money move. `shadowCostMicros` is what enforcement
+    // WOULD have charged and is never a charge. `quotaSource` says why `quota`
+    // is empty when it is. Unrecognised or absent values read as null — an
+    // unknown `enforcement` is never promoted to "on".
+    enforcement: readEnforcementState(obj.enforcement),
+    shadowCostMicros: micros(obj.shadow_cost_micros ?? obj.shadowCostMicros),
+    quotaSource: readQuotaSourceState(obj.quota_source ?? obj.quotaSource),
     funding: str(obj.funding),
     windows,
     usage: obj.usage && typeof obj.usage === "object" ? { ...obj.usage } : null,

package/lib/session/config.mjs

@@ -127,6 +127,10 @@ export function sessionPaths(agentRoot) {
     upgradeNoticeFile: join(stateDir, "upgrade-notice.json"),
     lastExitFile: join(stateDir, "last-exit"),
     attentionFile: join(stateDir, "attention.json"),
+    // Consecutive identical launch failures, carried across supervisor
+    // lifetimes (lib/session/launch-failure.mjs). A counter held in memory is
+    // zero on every launch, which is why the bound never bound.
+    launchFailuresFile: join(stateDir, "launch-failures.json"),
     daemonHealthFile: join(agentRoot, "state", "dashboards", "daemon-health.yaml"),
     daemonPidFile: join(agentRoot, "state", "daemon.pid"),
     configFile: join(agentRoot, CONFIG_REL),

package/lib/session/identity.mjs

@@ -65,6 +65,7 @@ export function parseMainSession(text) {
   };
   if (typeof raw.lastLaunchAt === "string") rec.lastLaunchAt = raw.lastLaunchAt;
   if (typeof raw.rotatedFrom === "string") rec.rotatedFrom = raw.rotatedFrom;
+  if (typeof raw.rotatedReason === "string") rec.rotatedReason = raw.rotatedReason;
   return rec;
 }
 
@@ -178,38 +179,101 @@ export function recordLaunch(record, opts = {}) {
  *
  *   relaunch — the session ended (cleanly, or after living past the window):
  *              exit 75 and let launchd bring it back with the same id.
- *   rotate   — a resume died inside the failure window: mint a fresh id first.
+ *   rotate   — the resume target is unusable: mint a fresh id first.
  *   backoff  — the rotation budget for this hour is spent: sleep, then exit 75.
  *
  * An UNKNOWN exit code (the exit file was not written) inside the window is
  * treated as a failure: the cost of a wrong rotation is a fresh transcript,
  * the cost of a wrong relaunch is a seat stuck in a 30-second crash loop.
  *
- * @param {{record:object, mode:"session-id"|"resume", exitCode:number|null, startedAt:number, endedAt:number, now?:number|Function, failureWindowMs?:number, maxRotationsPerHour?:number}} a
- * @returns {{action:"relaunch"}|{action:"rotate"}|{action:"backoff", sleepMs:number}}
+ * ── PROVEN OUTRANKS INFERRED, AND IS NOT RATIONED ───────────────────────────
+ * `resumeTargetMissing` is the runtime's own verdict, read off the screen by
+ * `launch-failure#classifyLaunchFailure` ("No conversation found with session
+ * ID: …") or off the disk by `resume-target#resumeTargetState`. When it is
+ * true, rotating is not a guess that might help — it is the ONLY repair, and
+ * it provably works. So it bypasses {@link MAX_ROTATIONS_PER_HOUR}, which
+ * exists to bound blind rotation. Leaving it inside the budget is precisely
+ * how James Kirkland's seat spent days relaunching a dead id on a ten-minute
+ * backoff: the budget throttled the one action that would have fixed it.
+ *
+ * ── `beatSeen` NARROWS THE GUESS, IT DOES NOT WIDEN IT ──────────────────────
+ * The twenty-second window is a proxy for "it never really started". A launch
+ * that DID write a heartbeat and then died inside that window did start, so it
+ * no longer rotates: its transcript is good and the fault is elsewhere. The
+ * converse is deliberately NOT symmetric — "ran an hour, never beat, unknown
+ * exit" is not evidence enough to destroy a transcript on, because a broken
+ * heartbeat writer looks exactly like it.
+ *
+ * The one place a never-beaten launch rotates outside the window is when it
+ * has ALREADY failed identically to the escalation limit (`streakAtLimit`):
+ * every other repair has been tried, the seat is escalating anyway, and a
+ * fresh id is the last thing left that could work. It is suppressed when WE
+ * ended the session (`selfStopped`: the watchdog restarting a wedged session),
+ * since that is exactly the case where the transcript is still good.
+ *
+ * @param {object} a
+ * @param {object} a.record
+ * @param {"session-id"|"resume"} a.mode
+ * @param {number|null} a.exitCode
+ * @param {number} a.startedAt
+ * @param {number} a.endedAt
+ * @param {boolean} [a.resumeTargetMissing]  PROVEN: the conversation is not on this machine
+ * @param {boolean} [a.beatSeen]             did this launch write a heartbeat? (undefined = could not tell)
+ * @param {boolean} [a.streakAtLimit]        has this launch failed identically to the escalation limit?
+ * @param {boolean} [a.selfStopped]          did the supervisor itself end the session?
+ * @param {number|Function} [a.now]
+ * @param {number} [a.failureWindowMs]
+ * @param {number} [a.maxRotationsPerHour]
+ * @returns {{action:"relaunch"}|{action:"rotate", proven:boolean, why:string}|{action:"backoff", sleepMs:number}}
  */
 export function rotationDecision(a) {
   const windowMs = a.failureWindowMs ?? FAILURE_WINDOW_MS;
   const max = a.maxRotationsPerHour ?? MAX_ROTATIONS_PER_HOUR;
   const durationMs = Number(a.endedAt) - Number(a.startedAt);
   const failed = a.exitCode === null || a.exitCode === undefined || a.exitCode !== 0;
-  if (a.mode !== "resume" || !failed || !(durationMs < windowMs)) return { action: "relaunch" };
+  if (a.mode !== "resume") return { action: "relaunch" };
+  if (a.resumeTargetMissing === true) {
+    return { action: "rotate", proven: true, why: "the conversation this launch resumed does not exist on this machine" };
+  }
+  if (!failed || a.selfStopped === true) return { action: "relaunch" };
+  const insideWindow = durationMs < windowMs && a.beatSeen !== true;
+  const lastResort = a.beatSeen === false && a.streakAtLimit === true;
+  if (!insideWindow && !lastResort) return { action: "relaunch" };
   const t = nowMs(a.now);
   const recent = (a.record && a.record.rotations || []).filter((r) => t - Date.parse(r) < HOUR_MS);
   if (recent.length >= max) return { action: "backoff", sleepMs: BACKOFF_MS };
-  return { action: "rotate" };
+  return {
+    action: "rotate",
+    proven: false,
+    why: insideWindow
+      ? "the resume died inside the failure window"
+      : "every recent launch has failed identically and never beaten — a fresh id is the last untried repair",
+  };
 }
 
 /**
  * Pure: the record after a rotation — fresh id, zero resumes, this rotation
  * stamped, and the rotation history pruned to the last hour.
- * @param {object} record @param {{now?:number|Function, uuid?:Function}} [opts]
+ *
+ * THIS IS BOTH HALVES OF THE REPAIR, AND THAT IS THE POINT. A dead resume id
+ * needs the stale record INVALIDATED (so nothing ever resumes it again) and a
+ * FRESH id to fall back to (so the next launch has somewhere to go). Doing
+ * only the first leaves the supervisor with no id and `newMainSession` would
+ * be minted anyway; doing only the second leaves the dead id in the file for
+ * the next reader. One write does both: the dead id survives only as
+ * `rotatedFrom`, which is provenance, not a target — nothing resumes it.
+ *
+ * `reason` is recorded so the next reader of the file (a person, `maestro
+ * session status`) can tell a proven repair from a heuristic one.
+ *
+ * @param {object} record @param {{now?:number|Function, uuid?:Function, reason?:string}} [opts]
  */
 export function rotateMainSession(record, opts = {}) {
   const t = nowMs(opts.now);
   const fresh = newMainSession({ now: t, uuid: opts.uuid });
   const kept = (record.rotations || []).filter((r) => t - Date.parse(r) < HOUR_MS);
-  return { ...fresh, rotations: [...kept, iso(t)], rotatedFrom: record.sessionId };
+  const reason = typeof opts.reason === "string" && opts.reason.trim() ? opts.reason.trim().slice(0, 300) : "";
+  return { ...fresh, rotations: [...kept, iso(t)], rotatedFrom: record.sessionId, ...(reason ? { rotatedReason: reason } : {}) };
 }
 
 export default {

package/lib/session/launch-failure.mjs

@@ -0,0 +1,251 @@
+/**
+ * lib/session/launch-failure.mjs — WHY a main-session launch failed, and when
+ * the seat should stop trying quietly and say so. Pure; no clock, no fs.
+ *
+ * ── THE FAULT THIS MODULE EXISTS TO NOT HAVE ────────────────────────────────
+ * Measured on James Kirkland's seat, 2026-09-25. The supervisor relaunched
+ * every ten minutes for DAYS running
+ *
+ *     claude --resume e953a33e-97a0-4d13-9fd4-6a77cd7a68c9
+ *     No conversation found with session ID: e953a33e-…
+ *     exit 1, after ~2 s
+ *
+ * for a conversation that no longer existed on that machine. Every layer
+ * behaved "correctly": launchd relaunched a job that exited non-zero, the
+ * rotation budget throttled to one attempt per ten minutes, the log recorded
+ * each failure. The seat looked UP the whole time — a live launchd job, a
+ * supervisor process, a mux session flickering into existence — and never
+ * beat once. Nobody reads that log; nobody could ssh in to read it.
+ *
+ * Two things were missing and both are here:
+ *
+ *   1. THE FAILURE HAS A NAME AND THE NAME WAS ON THE SCREEN. "No conversation
+ *      found with session ID" is not a symptom to infer from timing — it is the
+ *      runtime telling us the resume target is gone. {@link classifyLaunchFailure}
+ *      reads it, so the repair (mint a fresh id) is taken on evidence rather
+ *      than on the 20-second heuristic in `identity#rotationDecision`, which
+ *      misses a failure that takes 21 seconds and cannot distinguish a dead
+ *      transcript from a missing binary.
+ *
+ *   2. N IDENTICAL FAILURES ARE NOT N CHANCES — they are one fault, repeated.
+ *      A launch that fails the same way three times in a row will fail the
+ *      fourth time too, and the only useful next step is to tell somebody who
+ *      is not on this machine. {@link launchFailureStreak} counts consecutive
+ *      failures WITH THE SAME SIGNATURE across supervisor lifetimes (each
+ *      launch is a fresh process, so an in-memory counter is always zero —
+ *      the same trap `first-run#carriedRestarts` exists for), and
+ *      {@link escalationDecision} says when it stops being a retry and becomes
+ *      an escalation.
+ *
+ * The signature deliberately does NOT include the session id: rotating to a
+ * fresh id and failing the same way again is the SAME fault (that is exactly
+ * what a missing binary does), and a signature that changed every rotation
+ * would reset the streak forever — which is how this failure stayed invisible.
+ *
+ * @module lib/session/launch-failure
+ */
+
+"use strict";
+
+/** Consecutive identical launch failures before the seat escalates. */
+export const IDENTICAL_FAILURE_LIMIT = 3;
+
+/**
+ * The runtime's own words for "the conversation you asked me to resume is not
+ * on this machine". Matched case-insensitively against the tail of the pane /
+ * the launcher's stderr. Kept as a list because the wording is the CLI's, not
+ * ours, and a second phrasing must be addable without touching the classifier.
+ */
+export const RESUME_MISSING_PATTERNS = Object.freeze([
+  /no conversation found with session id/i,
+  /no conversation found matching/i,
+  /session .{0,80}? not found/i,
+]);
+
+/** "the binary is not there" — a shell's 127, and the two spellings of ENOENT. */
+export const BINARY_MISSING_PATTERNS = Object.freeze([
+  /command not found/i,
+  /no such file or directory/i,
+  /\bENOENT\b/,
+]);
+
+const anyMatch = (patterns, text) => patterns.some((re) => re.test(text));
+
+/**
+ * Pure: name the failure of one launch.
+ *
+ * `output` is whatever text the launch left behind — a pane capture, the
+ * launcher's stderr, or "" when nothing was captured. It is EVIDENCE, and its
+ * absence is never treated as proof of anything: with no output the verdict
+ * falls back to what the exit code and the mode can carry on their own.
+ *
+ * @param {object} a
+ * @param {"session-id"|"resume"} a.mode      how this launch addressed the session
+ * @param {number|null} a.exitCode            the recorded exit (null = the exit file was never written)
+ * @param {string} [a.output]                 pane tail / stderr, may be ""
+ * @param {boolean} [a.beatSeen]              did this launch produce a heartbeat?
+ * @returns {{kind:"none"|"resume-target-missing"|"binary-missing"|"never-beaten"|"nonzero-exit", proven:boolean, detail:string}}
+ */
+export function classifyLaunchFailure(a = {}) {
+  const exitCode = a.exitCode === null || a.exitCode === undefined ? null : Number(a.exitCode);
+  const output = typeof a.output === "string" ? a.output : "";
+  const beatSeen = a.beatSeen === true;
+  const failed = exitCode === null || exitCode !== 0;
+
+  // A launch that beat and then exited 0 is a session that RAN. Nothing to name.
+  if (!failed && beatSeen) return { kind: "none", proven: true, detail: "the session ran and exited cleanly" };
+  if (!failed) return { kind: "none", proven: false, detail: "the session exited cleanly without beating" };
+
+  // PROVEN verdicts first: the runtime said what was wrong, in words.
+  if (a.mode === "resume" && anyMatch(RESUME_MISSING_PATTERNS, output)) {
+    return {
+      kind: "resume-target-missing",
+      proven: true,
+      detail: "the runtime reported that the conversation this launch tried to resume does not exist on this machine",
+    };
+  }
+  if (exitCode === 127 || anyMatch(BINARY_MISSING_PATTERNS, output)) {
+    return {
+      kind: "binary-missing",
+      proven: exitCode === 127 || anyMatch(BINARY_MISSING_PATTERNS, output),
+      detail: "the launcher could not find the binary it was told to run",
+    };
+  }
+
+  // INFERRED verdicts. `never-beaten` is the honest name for James's seat when
+  // the pane was not captured: the launch ended non-zero having never reported
+  // in, so whatever it was, it was never a working session.
+  if (!beatSeen) {
+    return { kind: "never-beaten", proven: false, detail: `the launch ended (exit ${exitCode === null ? "unknown" : exitCode}) without ever writing a heartbeat` };
+  }
+  return { kind: "nonzero-exit", proven: false, detail: `the session beat, then ended with exit ${exitCode === null ? "unknown" : exitCode}` };
+}
+
+/**
+ * Pure: the stable identity of a failure, for counting repeats.
+ *
+ * Mode and kind only. NOT the session id (see the module docblock) and not the
+ * exit code when the kind already names the fault — otherwise a flapping exit
+ * status would read as a different fault each time and never accumulate.
+ *
+ * @param {{mode:string, kind:string, exitCode?:number|null}} a
+ * @returns {string} e.g. `resume:resume-target-missing`
+ */
+export function launchFailureSignature(a = {}) {
+  const kind = String(a.kind || "unknown");
+  const mode = a.mode === "resume" ? "resume" : "session-id";
+  if (kind === "none") return "";
+  if (kind === "never-beaten" || kind === "nonzero-exit") {
+    const exit = a.exitCode === null || a.exitCode === undefined ? "unknown" : String(Number(a.exitCode));
+    return `${mode}:${kind}:${exit}`;
+  }
+  return `${mode}:${kind}`;
+}
+
+/**
+ * Pure: parse `state/session/launch-failures.json`. Anything unreadable is
+ * "no streak" — a corrupt counter must never be able to escalate on its own.
+ * @param {string|null|undefined} text
+ * @returns {{signature:string, streak:number, firstAt:string, lastAt:string, escalatedAt:string}|null}
+ */
+export function parseLaunchFailures(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  let raw;
+  try { raw = JSON.parse(text); } catch { return null; }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const signature = typeof raw.signature === "string" ? raw.signature : "";
+  const streak = Number.isInteger(raw.streak) && raw.streak > 0 ? raw.streak : 0;
+  if (!signature || !streak) return null;
+  return {
+    signature,
+    streak,
+    firstAt: typeof raw.firstAt === "string" ? raw.firstAt : "",
+    lastAt: typeof raw.lastAt === "string" ? raw.lastAt : "",
+    escalatedAt: typeof raw.escalatedAt === "string" ? raw.escalatedAt : "",
+  };
+}
+
+/**
+ * Pure: the streak after one more launch outcome.
+ *
+ * A DIFFERENT signature restarts the count at 1 rather than adding to it: two
+ * different faults in a row are two problems, and escalating on their sum
+ * would cry wolf. A successful launch (`signature` empty) clears the record
+ * entirely — evidence of work, the same reset rule `carriedRestarts` uses.
+ *
+ * @param {object|null} prior      {@link parseLaunchFailures} output
+ * @param {{signature:string, at:string}} outcome
+ * @returns {{signature:string, streak:number, firstAt:string, lastAt:string, escalatedAt:string}|null} null = clear the file
+ */
+export function launchFailureStreak(prior, outcome = {}) {
+  const signature = typeof outcome.signature === "string" ? outcome.signature : "";
+  const at = typeof outcome.at === "string" ? outcome.at : "";
+  if (!signature) return null; // the launch worked: nothing to carry
+  if (prior && prior.signature === signature) {
+    return { signature, streak: prior.streak + 1, firstAt: prior.firstAt || at, lastAt: at, escalatedAt: prior.escalatedAt || "" };
+  }
+  return { signature, streak: 1, firstAt: at, lastAt: at, escalatedAt: "" };
+}
+
+/**
+ * Pure: has this stopped being a retry?
+ *
+ * `escalate` is true on the launch that REACHES the limit and on every launch
+ * after it, because the escalation channel is a beat field that the next
+ * supervisor run clears (`attention.json` is unlinked at launch): a one-shot
+ * escalation would flicker off and the org would see a seat that healed. The
+ * `fresh` flag distinguishes the first crossing, which is the one worth a log
+ * line and a distinct wording.
+ *
+ * @param {{streak:number, limit?:number, escalatedAt?:string}} a
+ * @returns {{escalate:boolean, fresh:boolean, streak:number, limit:number, reason:string}}
+ */
+export function escalationDecision(a = {}) {
+  const limit = Number.isInteger(a.limit) && a.limit > 0 ? a.limit : IDENTICAL_FAILURE_LIMIT;
+  const streak = Number.isInteger(a.streak) && a.streak > 0 ? a.streak : 0;
+  if (streak < limit) {
+    return { escalate: false, fresh: false, streak, limit, reason: `launch failure ${streak}/${limit} — retrying` };
+  }
+  const fresh = !a.escalatedAt;
+  return {
+    escalate: true,
+    fresh,
+    streak,
+    limit,
+    reason: `${streak} consecutive launches have failed the same way (limit ${limit}) — this is a fault, not a retry`,
+  };
+}
+
+/**
+ * Pure: the one sentence an operator in a browser gets, via the beat's
+ * `machine.sessionNote.detail`.
+ *
+ * THE VERDICT LEADS, THE EXPLANATION TRAILS — because the channel TRUNCATES.
+ * `telemetry/collect#sanitizeNoteDetail` caps the detail at 200 characters and
+ * appends an ellipsis, so anything after the first sentence may never leave the
+ * machine. The first draft of this line ended "…this needs a person" and that
+ * clause — the only part that asks for an action — was the part that got cut.
+ * So: how many, that retries are not working, then the diagnosis.
+ *
+ * @param {{signature:string, streak:number, limit?:number, detail:string, sessionId?:string}} a
+ * @returns {string}
+ */
+export function escalationHint(a = {}) {
+  const sig = String(a.signature || "unknown");
+  const streak = Number(a.streak) || 0;
+  const detail = String(a.detail || "").trim();
+  const id = typeof a.sessionId === "string" && a.sessionId ? ` Session ${a.sessionId}.` : "";
+  return `${streak}× in a row, identically — retries are not fixing it and this needs a person. ${detail || sig}.${id}`;
+}
+
+export default {
+  IDENTICAL_FAILURE_LIMIT,
+  RESUME_MISSING_PATTERNS,
+  BINARY_MISSING_PATTERNS,
+  classifyLaunchFailure,
+  launchFailureSignature,
+  parseLaunchFailures,
+  launchFailureStreak,
+  escalationDecision,
+  escalationHint,
+};

package/lib/session/resume-target.mjs

@@ -0,0 +1,86 @@
+/**
+ * lib/session/resume-target.mjs — is the conversation we are about to `--resume`
+ * actually on this machine?
+ *
+ * ── WHY THIS IS A PREFLIGHT AND NOT A POST-MORTEM ───────────────────────────
+ * The supervisor already had a post-mortem: a resume that died non-zero inside
+ * twenty seconds rotates to a fresh id (`identity#rotationDecision`). It is a
+ * good heuristic and it is not enough — it cannot tell a dead transcript from a
+ * missing binary, it misses a failure that takes twenty-one seconds, and every
+ * one of its verdicts costs a full launch, a mux session and a launchd cycle to
+ * reach. On James Kirkland's seat that cycle ran every ten minutes for days
+ * against a session id that had not existed for just as long.
+ *
+ * The answer is on disk before we launch. Claude Code keeps each project's
+ * transcripts as `~/.claude/projects/<project-slug>/<session-id>.jsonl`, where
+ * the slug is the project directory with every non-alphanumeric character
+ * replaced by `-`. `--resume` is project-scoped, so the seat's own slug is the
+ * only place the id could be.
+ *
+ * ── FAIL-OPEN, DELIBERATELY ─────────────────────────────────────────────────
+ * A wrong "missing" throws away a live transcript; a wrong "unknown" costs one
+ * launch and lands in the post-mortem that was already there. So `missing` is
+ * returned ONLY from positive evidence: the project directory exists, it holds
+ * transcripts, and this id is not among them. An absent directory, an empty
+ * one, an unreadable one, an engine that does not use this layout at all — all
+ * `unknown`, and the launch proceeds exactly as before.
+ *
+ * One I/O shell (`readdirSync`/`existsSync`), both injected.
+ *
+ * @module lib/session/resume-target
+ */
+
+"use strict";
+
+import { readdirSync as fsReaddirSync } from "node:fs";
+import { join } from "node:path";
+
+/** Where Claude Code keeps per-project transcripts, relative to the home dir. */
+export const TRANSCRIPT_ROOT = join(".claude", "projects");
+
+/**
+ * Pure: Claude Code's directory name for a project path — every character that
+ * is not a letter or a digit becomes `-` (`/Users/x/hq` → `-Users-x-hq`).
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function projectSlug(projectDir) {
+  return String(projectDir || "").replace(/[^A-Za-z0-9]/g, "-");
+}
+
+/**
+ * Is `sessionId`'s transcript present for `projectDir`?
+ *
+ * @param {object} a
+ * @param {string} a.homeDir              the user's home directory
+ * @param {string} a.projectDir           the directory the session runs in (the agent root)
+ * @param {string} a.sessionId            the id this launch would resume
+ * @param {"claude"|"cohort"} [a.engine]  a non-claude engine does not use this layout → always "unknown"
+ * @param {{readdirSync?:Function}} [deps]
+ * @returns {{state:"present"|"missing"|"unknown", dir:string, reason:string}}
+ */
+export function resumeTargetState(a = {}, deps = {}) {
+  const readdirSync = deps.readdirSync || fsReaddirSync;
+  const homeDir = typeof a.homeDir === "string" ? a.homeDir : "";
+  const sessionId = String(a.sessionId || "").toLowerCase();
+  if (a.engine && a.engine !== "claude") return { state: "unknown", dir: "", reason: `engine ${a.engine} does not keep transcripts here` };
+  if (!homeDir || !sessionId) return { state: "unknown", dir: "", reason: "no home directory or session id to check" };
+  const dir = join(homeDir, TRANSCRIPT_ROOT, projectSlug(a.projectDir));
+  let entries;
+  try { entries = readdirSync(dir); } catch { return { state: "unknown", dir, reason: "the project's transcript directory is absent or unreadable" }; }
+  const names = (Array.isArray(entries) ? entries : []).map((e) => String(e && e.name ? e.name : e));
+  const transcripts = names.filter((n) => n.toLowerCase().endsWith(".jsonl"));
+  if (transcripts.some((n) => n.toLowerCase() === `${sessionId}.jsonl`)) {
+    return { state: "present", dir, reason: "the transcript is on disk" };
+  }
+  // An EMPTY directory proves nothing: it is equally what a seat looks like the
+  // moment before its first session writes, and rotating on it would be a guess.
+  if (transcripts.length === 0) return { state: "unknown", dir, reason: "the project's transcript directory holds no transcripts at all" };
+  return {
+    state: "missing",
+    dir,
+    reason: `${transcripts.length} transcript(s) on disk for this project and none of them is ${sessionId}`,
+  };
+}
+
+export default { TRANSCRIPT_ROOT, projectSlug, resumeTargetState };