@cohortapp/agent-sdk 2.18.13 → 2.18.15

package/lib/engine/output/json.mjs

@@ -100,6 +100,28 @@ export function buildResult({ outcome, sessionId, durationMs, wire, session = nu
       modelTier: outcome.modelTier,
       requestIds: outcome.requestIds,
       costMicros: outcome.costMicros,
+      // W16 (hq a60b9595): what the gateway says ABOUT `costMicros` above.
+      // `enforcement` is the billing mode that produced it — only "on" means
+      // money moved, `null` means the endpoint did not say — so a consumer
+      // summing `costMicros` (or `total_cost_usd`) as spend must read this in
+      // the same breath. `shadowCostMicros` is what enforcement WOULD have
+      // charged, kept under its own name because folding a counterfactual into
+      // a charge is the misread the gateway split the fields to prevent; it is
+      // null in production today. `quotaSource` says why `quota` is empty when
+      // it is: the ledger answered and there is no allowance, the read failed,
+      // or nothing was read — three answers one `{}` used to collapse.
+      //
+      // SCOPE: these three have the SAME scope as `costMicros` above, on purpose.
+      // On a run with subagents cli.mjs replaces `costMicros` with the
+      // parent+children sum and replaces these three with the fold over the same
+      // set (agents/usage.mjs), so a parent served under "on" whose child was
+      // served under "shadow" reports "mixed" — never "on" beside a total that
+      // includes the child's shadow figure. Per-child modes are on
+      // `cohort.agents[]`. (`gatewayUsage` below does NOT follow that rule; its
+      // own comment says so.)
+      enforcement: outcome.enforcement ?? null,
+      shadowCostMicros: outcome.shadowCostMicros ?? null,
+      quotaSource: outcome.quotaSource ?? null,
       quota: outcome.quota,
       usage: outcome.usage,
       // CF-158: the gateway's own view of the same turns, off the terminal
@@ -151,6 +173,10 @@ export function buildSetupErrorResult({ sessionId, code, message, durationMs, wi
       modelTier: null,
       requestIds: [],
       costMicros: null,
+      // No request was made, so the endpoint stated nothing (W16).
+      enforcement: null,
+      shadowCostMicros: null,
+      quotaSource: null,
       quota: null,
       usage: emptyUsage("estimated"),
       // No request was made, so the gateway reported nothing (CF-158).

package/lib/engine/wire/errors.mjs

@@ -379,6 +379,14 @@ export function readCohortHeaders(headers) {
     // Headers never carry usage — only the terminal frame does (CF-158). The key
     // is present so the merged shape is uniform whether a frame arrived or not.
     usage: null,
+    // §4.6 defines no header for any of these three either: only the terminal
+    // frame — and the identical object on a non-streamed response — carries
+    // them. Present and null so a caller reads one shape whether a frame
+    // arrived or not, and so "the endpoint did not say" is never silently the
+    // same value as a mode it did say.
+    enforcement: null,
+    shadowCostMicros: null,
+    quotaSource: null,
     quota: {
       windows,
       creditsRemainingMicros: micros(credits, true),
@@ -400,6 +408,132 @@ function micros(v, signed) {
   return (signed ? /^-?\d+$/ : /^\d+$/).test(s) ? s : null;
 }
 
+/**
+ * The billing modes the gateway names in the frame's `enforcement` field
+ * (design §4.8, shipped hq a60b9595). `on` is the only one under which a
+ * reported `cost_micros` is money that moved.
+ *
+ * A value outside this set reads as UNKNOWN (`null`), never as `"on"`: the
+ * field exists to say whether a figure is money, and promoting a word this
+ * client has never seen to `"on"` would put a counterfactual charge into a
+ * seat's spend — the very misread this contract was extended to prevent.
+ */
+export const ENFORCEMENT_MODES = new Set(["off", "shadow", "on"]);
+
+/**
+ * `enforcement` as one of the three modes, or null for absent, non-string or
+ * unrecognised. PURE, never throws.
+ * @param {unknown} v @returns {'off'|'shadow'|'on'|null}
+ */
+export function readEnforcement(v) {
+  return typeof v === "string" && ENFORCEMENT_MODES.has(v) ? /** @type {any} */ (v) : null;
+}
+
+/**
+ * The four answers `quota_source` splits a previously-ambiguous empty `quota`
+ * object into (design §4.8):
+ *
+ *   ledger        the ledger answered — this seat genuinely has no included
+ *                 allowance (a money-only band reports no windows by design)
+ *   unreadable    the quota read FAILED. An empty quota here is not headroom.
+ *   not_read      admission is off, so nothing was read.
+ *   not_admitted  a defensive fourth answer no served request produces today:
+ *                 read it as "unknown", not as a state to branch on.
+ *
+ * An unrecognised value is also unknown, and is reported as such rather than
+ * being rounded to the nearest known one.
+ */
+export const QUOTA_SOURCES = new Set(["ledger", "unreadable", "not_read", "not_admitted"]);
+
+/** @param {unknown} v @returns {'ledger'|'unreadable'|'not_read'|'not_admitted'|null} */
+export function readQuotaSource(v) {
+  return typeof v === "string" && QUOTA_SOURCES.has(v) ? /** @type {any} */ (v) : null;
+}
+
+/**
+ * `enforcement` as a CLOSED four-word vocabulary: one of the three modes, the
+ * client's own `"unknown"` when the endpoint stated something else, or null when
+ * it stated nothing. PURE, never throws.
+ *
+ * The fourth word exists so the seam does not erase the difference between "the
+ * endpoint said nothing" and "the endpoint said a word this client has never
+ * seen" — a gateway that ships a fourth mode would otherwise reach a seat as
+ * silence, and nobody would learn it had spoken. `"unknown"` can never be
+ * confused with `"on"`, which is the one guarantee that matters for money.
+ * @param {unknown} v @returns {'off'|'shadow'|'on'|'unknown'|null}
+ */
+export function readEnforcementState(v) {
+  return v == null || v === "" ? null : readEnforcement(v) ?? "unknown";
+}
+
+/**
+ * `quota_source` as the same closed vocabulary: one of the four §4.8 answers,
+ * `"unknown"` for anything else stated, null for silence. PURE.
+ * @param {unknown} v @returns {'ledger'|'unreadable'|'not_read'|'not_admitted'|'unknown'|null}
+ */
+export function readQuotaSourceState(v) {
+  return v == null || v === "" ? null : readQuotaSource(v) ?? "unknown";
+}
+
+/**
+ * Fold one request's stated `enforcement` into what a whole run has observed.
+ * PURE. Silence never changes what was already stated; a stated word this
+ * client does not know folds to `"unknown"` (distinct from "never stated");
+ * two different modes in one run fold to `"mixed"`.
+ * @param {'off'|'shadow'|'on'|'unknown'|'mixed'|null|undefined} prev
+ * @param {unknown} next
+ * @returns {'off'|'shadow'|'on'|'unknown'|'mixed'|null}
+ */
+export function foldEnforcement(prev, next) {
+  return fold(prev, next, readEnforcement);
+}
+
+/**
+ * Fold one request's stated `quota_source` into what a whole run has observed.
+ * Same rules as {@link foldEnforcement}.
+ * @param {'ledger'|'unreadable'|'not_read'|'not_admitted'|'unknown'|'mixed'|null|undefined} prev
+ * @param {unknown} next
+ * @returns {'ledger'|'unreadable'|'not_read'|'not_admitted'|'unknown'|'mixed'|null}
+ */
+export function foldQuotaSource(prev, next) {
+  return fold(prev, next, readQuotaSource);
+}
+
+/**
+ * Combine two ALREADY-FOLDED statements — each already one of the closed
+ * vocabulary's words, `"mixed"`, or null for "nothing stated". PURE.
+ *
+ * This is the fold one level up: a parent run folds its own requests with
+ * {@link foldEnforcement} (which reads RAW wire values), and then folds that
+ * result with each subagent's. Passing a folded `"mixed"` back through
+ * `foldEnforcement` would flatten it to `"unknown"`, because `"mixed"` is this
+ * client's word and not one the gateway ever sends.
+ *
+ * Silence never unsays a statement; two different statements are `"mixed"`.
+ * @template {string} T
+ * @param {T|'mixed'|null|undefined} a @param {T|'mixed'|null|undefined} b
+ * @returns {T|'mixed'|null}
+ */
+export function combineStated(a, b) {
+  const x = a ?? null;
+  const y = b ?? null;
+  if (y === null) return /** @type {any} */ (x);
+  if (x === null) return /** @type {any} */ (y);
+  return /** @type {any} */ (x === y ? x : "mixed");
+}
+
+/**
+ * @param {any} prev @param {unknown} next @param {(v:unknown)=>string|null} read
+ * @returns {any}
+ */
+function fold(prev, next, read) {
+  const before = prev ?? null;
+  if (next == null || next === "") return before;
+  const m = read(next) ?? "unknown";
+  if (before === null) return m;
+  return before === m ? before : "mixed";
+}
+
 /** SSE event name of the gateway's terminal cost/quota frame. */
 export const COHORT_FRAME_EVENT = "cohort";
 
@@ -435,6 +569,31 @@ export const COHORT_FRAME_EVENT = "cohort";
  * nothing fails when it is absent. See docs/engine/eval.md §3; the fix for the
  * contract itself belongs to hq, which this repo does not edit.
  *
+ * ## W16 — `enforcement`, `shadow_cost_micros`, `quota_source` (hq a60b9595)
+ *
+ * The frame gained three fields, all normative in §4.8, all optional here:
+ *
+ *   `enforcement`         "off" | "shadow" | "on" — the billing mode that
+ *                         produced the two cost figures. Only under `on` is
+ *                         `cost_micros` money that moved. A word outside the
+ *                         three reaches the merged result as `"unknown"`, never
+ *                         as `"on"` and never as silence.
+ *   `shadow_cost_micros`  what enforcement WOULD have charged. It is a separate
+ *                         field on purpose and is carried under the separate key
+ *                         `shadowCostMicros`; it is never folded into
+ *                         `costMicros` and never counted as spend. Non-null only
+ *                         where the retail card is partial — null in production
+ *                         today, which has no published price book.
+ *   `quota_source`        "ledger" | "unreadable" | "not_read" | "not_admitted"
+ *                         — why `quota` is empty when it is. `{}` used to
+ *                         collapse "no allowance" and "the read failed", which
+ *                         call for opposite behaviour.
+ *
+ * Each is read through its own total parser ({@link readEnforcement},
+ * {@link readQuotaSource}, and `micros` for the figure): absent, wrong-typed
+ * and unrecognised all yield null, nothing throws, and an unrecognised
+ * `enforcement` is NEVER promoted to `"on"`.
+ *
  * @param {string} data
  * @returns {Partial<ReturnType<typeof readCohortHeaders>> & { quota?: any }}
  */
@@ -469,6 +628,18 @@ export function readCohortFrame(data) {
   // CF-158: undocumented upstream, so absence is normal and never an error.
   const usage = readFrameUsage(o.usage);
   if (usage) patch.usage = usage;
+  // W16 (hq a60b9595): enforcement, shadow_cost_micros and quota_source. Each
+  // is read defensively and only SET when it is usable, so an omitted or
+  // unrecognised value leaves the merged value at null rather than overwriting
+  // a mode an earlier frame stated. `shadow_cost_micros` lands under a name
+  // that cannot be confused with `costMicros`, because the gateway's whole
+  // reason for splitting the fields is that one is money and the other is not.
+  const mode = readEnforcementState(o.enforcement);
+  if (mode) patch.enforcement = mode;
+  const shadow = micros(o.shadow_cost_micros, false);
+  if (shadow !== null) patch.shadowCostMicros = shadow;
+  const qs = readQuotaSourceState(o.quota_source);
+  if (qs) patch.quotaSource = qs;
   return patch;
 }
 
@@ -486,6 +657,14 @@ export function mergeCohort(base, patch) {
     modelTier: patch.modelTier ?? base.modelTier,
     costMicros: patch.costMicros ?? base.costMicros,
     usage: patch.usage ?? base.usage ?? null,
+    // W16. `enforcement` qualifies `costMicros`: only under "on" is that figure
+    // money that moved. `shadowCostMicros` is what enforcement WOULD have
+    // charged and is never spend. `quotaSource` says why `quota` is empty when
+    // it is. null means the endpoint did not say — read as unknown, and NOT as
+    // a licence to assume "on"; the budget meter decides what to do with that.
+    enforcement: patch.enforcement ?? base.enforcement ?? null,
+    shadowCostMicros: patch.shadowCostMicros ?? base.shadowCostMicros ?? null,
+    quotaSource: patch.quotaSource ?? base.quotaSource ?? null,
     quota: {
       windows: { ...base.quota.windows, ...(pq.windows || {}) },
       creditsRemainingMicros: pq.creditsRemainingMicros ?? base.quota.creditsRemainingMicros,

package/lib/engine/wire/search.mjs

@@ -6,9 +6,19 @@
  *   POST <base>/cohort/v1/search
  *     Authorization: Bearer <seat token>
  *     body  {"query":"…","maxResults":8,"allowedDomains":["…"],"blockedDomains":["…"]}
- *     200   {"results":[{"title":"…","url":"…","snippet":"…"}],"costMicros":"1200"}
+ *     200   {"results":[{"title":"…","url":"…","snippet":"…"}],"costMicros":"1200",
+ *            "shadowCostMicros":"…|null","enforcement":"off|shadow|on"}
  *           (costMicros: decimal integer string of micro-USD, or a safe integer;
  *            `x-cohort-request-id` and `x-cohort-cost-micros` headers as on every route)
+ *
+ * **`costMicros` is money only under `enforcement: "on"` (W16, design §4.8).**
+ * The search body spells the three billing fields in camelCase because it is a
+ * plain JSON response rather than the `cohort` object, but they carry exactly
+ * the frame's meanings: under `shadow` a priced search settles for real and
+ * moves no money, and `shadowCostMicros` is what enforcement WOULD have charged.
+ * All three ride the returned `cohort` object, so the budget meter applies the
+ * same rule to a search as to a model call — a search's cost would otherwise be
+ * the one figure still counted as spend under shadow billing.
  *     404   the gateway has no search → the tool reports search as unavailable
  *     4xx/5xx refusals use the §4.6/§4.8 error bodies
  *
@@ -19,7 +29,7 @@
  * @module lib/engine/wire/search
  */
 
-import { classifyHttpError, classifyTransportError, tokenFailureError, header } from "./errors.mjs";
+import { classifyHttpError, classifyTransportError, tokenFailureError, header, readEnforcementState } from "./errors.mjs";
 
 export const SEARCH_ROUTE = "/cohort/v1/search";
 export const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
@@ -41,7 +51,8 @@ function micros(v) {
 /**
  * Validate the 200 body (pure).
  * @param {unknown} body
- * @returns {{ok:true, results:Array<{title:string, url:string, snippet:string}>, costMicros:string|null}|{ok:false, message:string}}
+ * @returns {{ok:true, results:Array<{title:string, url:string, snippet:string}>, costMicros:string|null,
+ *   shadowCostMicros:string|null, enforcement:'off'|'shadow'|'on'|'unknown'|null}|{ok:false, message:string}}
  */
 export function parseSearchBody(body) {
   if (!body || typeof body !== "object" || !Array.isArray(/** @type any */ (body).results)) return { ok: false, message: "the search response has no results array" };
@@ -49,7 +60,15 @@ export function parseSearchBody(body) {
   const results = b.results
     .filter((r) => r && typeof r === "object" && typeof r.url === "string" && r.url !== "")
     .map((r) => ({ title: typeof r.title === "string" ? r.title : r.url, url: r.url, snippet: typeof r.snippet === "string" ? r.snippet : "" }));
-  return { ok: true, results, costMicros: micros(b.costMicros) };
+  return {
+    ok: true,
+    results,
+    costMicros: micros(b.costMicros),
+    // W16. Read defensively and kept apart from the charge, exactly as on the
+    // frame: an unrecognised enforcement is "unknown", never "on".
+    shadowCostMicros: micros(b.shadowCostMicros),
+    enforcement: readEnforcementState(b.enforcement),
+  };
 }
 
 /**
@@ -65,8 +84,8 @@ export function parseSearchBody(body) {
  * @param {AbortSignal} [p.signal]
  * @param {number} [p.timeoutMs]
  * @param {() => number} [p.now]
- * @returns {Promise<{ok:true, results:Array<{title:string,url:string,snippet:string}>, cohort:{requestId:string|null, costMicros:string|null}}
- *   | {ok:false, error:{kind:string, code:string, status:number|null, message:string}, cohort:{requestId:string|null, costMicros:string|null}|null, accepted:boolean}>}
+ * @returns {Promise<{ok:true, results:Array<{title:string,url:string,snippet:string}>, cohort:{requestId:string|null, costMicros:string|null, shadowCostMicros:string|null, enforcement:string|null}}
+ *   | {ok:false, error:{kind:string, code:string, status:number|null, message:string}, cohort:{requestId:string|null, costMicros:string|null, shadowCostMicros:string|null, enforcement:string|null}|null, accepted:boolean}>}
  */
 export async function searchWeb(p) {
   const fetchImpl = p.fetchImpl ?? globalThis.fetch;
@@ -106,7 +125,15 @@ export async function searchWeb(p) {
         const err = classifyTransportError(e, controller.signal);
         return { ok: false, error: { kind: err.kind, code: err.code, status: null, message: err.message }, cohort: null, accepted: false };
       }
-      const cohort = { requestId: header(res.headers, "x-cohort-request-id"), costMicros: micros(header(res.headers, "x-cohort-cost-micros")) };
+      // §4.6 defines no header for the billing fields; only the body carries
+      // them. Null here so the shape is uniform on a refusal, which has no body
+      // to read them from.
+      const cohort = {
+        requestId: header(res.headers, "x-cohort-request-id"),
+        costMicros: micros(header(res.headers, "x-cohort-cost-micros")),
+        shadowCostMicros: null,
+        enforcement: null,
+      };
       if (res.status === 401 && typeof p.token === "function" && !refresh) {
         await res.body?.cancel().catch(() => {});
         refresh = true;
@@ -130,7 +157,16 @@ export async function searchWeb(p) {
       }
       const parsed = parseSearchBody(json);
       if (!parsed.ok) return { ok: false, error: { kind: "protocol", code: "search_protocol_error", status: res.status, message: parsed.message }, cohort, accepted: true };
-      return { ok: true, results: parsed.results.slice(0, body.maxResults), cohort: { requestId: cohort.requestId, costMicros: parsed.costMicros ?? cohort.costMicros } };
+      return {
+        ok: true,
+        results: parsed.results.slice(0, body.maxResults),
+        cohort: {
+          requestId: cohort.requestId,
+          costMicros: parsed.costMicros ?? cohort.costMicros,
+          shadowCostMicros: parsed.shadowCostMicros,
+          enforcement: parsed.enforcement,
+        },
+      };
     }
     return { ok: false, error: { kind: "auth", code: "http_401", status: 401, message: "the gateway refused the refreshed token" }, cohort: null, accepted: false };
   } finally {

package/lib/identity/persona.mjs

@@ -42,6 +42,10 @@
 
 import { readFileSync } from "fs";
 import { join } from "path";
+// A seat's config/agent.json is seat-local prose too — `maestro upgrade` never
+// touches it — and its free-text fields render straight into the persona block
+// at the TOP of every prompt both planes build. See scrubAgentConfig.
+import { scrubSeatText } from "./disclosure-scrub.mjs";
 
 /**
  * Human-readable gloss for each archetype altitude band (archetypes/altitudes/).
@@ -349,13 +353,33 @@ export function configuredStr(v) {
   return t;
 }
 
-/** Strip scaffold sentinels out of a parsed config/agent.json. @param {object} a @returns {object} */
+/**
+ * The free-text fields of config/agent.json — the ones that render as PROSE
+ * rather than as a name or a title, and so can carry a standing instruction.
+ *
+ * `persona`, `background` and `bio` reach `### Background` and the persona
+ * prose at the very top of every prompt, ahead of the framework's own rules.
+ * That is the path that made this list necessary: the CLAUDE.md scrape and the
+ * sender profiles were filtered first, a poisoned seat was rendered end to end,
+ * and the opener came out of `config/agent.json#persona` — a file nobody had
+ * thought of as prompt text because it looks like configuration.
+ */
+const AGENT_PROSE_FIELDS = ["companyDescription", "persona", "background", "bio"];
+
+/**
+ * Strip scaffold sentinels out of a parsed config/agent.json — and scrub the
+ * free-text fields, which are seat-local prose in an instruction position.
+ * @param {object} a @returns {object}
+ */
 export function scrubAgentConfig(a) {
   const src = a && typeof a === "object" ? a : {};
   const out = { ...src };
   for (const k of ["firstName", "lastName", "fullName", "title", "company", "companyDescription", "persona", "background", "bio"]) {
     if (k in out) out[k] = configuredStr(out[k]);
   }
+  for (const k of AGENT_PROSE_FIELDS) {
+    if (typeof out[k] === "string" && out[k]) out[k] = scrubSeatText(out[k]).trim();
+  }
   // A surname with no first name and no full name is not an identity — better
   // to render no name at all than "You are AGENT." (the scaffold ships
   // firstName "UNCONFIGURED" / lastName "AGENT").
@@ -375,6 +399,11 @@ export function scrubCompanyConfig(c) {
   for (const k of ["name", "legalName", "description", "tagline", "industry", "stage"]) {
     if (k in out) out[k] = configuredStr(out[k]);
   }
+  // `description` and `tagline` render as prose in the persona block, the same
+  // as the agent's own free-text fields.
+  for (const k of ["description", "tagline"]) {
+    if (typeof out[k] === "string" && out[k]) out[k] = scrubSeatText(out[k]).trim();
+  }
   return out;
 }
 
@@ -408,4 +437,4 @@ export function renderSeatPersona(root, opts = {}) {
   }
 }
 
-export const _test = { ALTITUDE_STANDING, personaProse, reportingLine, voiceRules, list, SELF_PRESENTATION_RULES };
+export const _test = { ALTITUDE_STANDING, personaProse, reportingLine, voiceRules, list, SELF_PRESENTATION_RULES, AGENT_PROSE_FIELDS };

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 {