@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/scripts/daemon/deliver.mjs

@@ -0,0 +1,314 @@
+/**
+ * deliver.mjs — put a specific string in front of a specific human. No model.
+ *
+ * This module exists because the acknowledgement was an LLM call.
+ *
+ * The old holding-message path spawned a full `claude --print` child, under a
+ * 60s hard cap, on a machine sitting at 95-99% memory, purely to write "let me
+ * look into it". It lost that race roughly two times in three (20 of 32
+ * observed attempts died on `claude CLI timed out after 60000ms`), and when it
+ * lost, the failure was caught, logged, and the human was told NOTHING while a
+ * 15-45 minute session ran behind a typing indicator.
+ *
+ * Everything on this path is therefore synchronous string work plus one HTTP
+ * call. There is no generation step that can time out, no model to be starved
+ * of memory, and no budget that can refuse it. It is the floor beneath every
+ * "never silent" guarantee in assurance.mjs: whatever else fails, THIS can run.
+ *
+ * The three per-service senders were previously private to responder.mjs, so
+ * nothing but a generated reply could reach a human. They are now here, and
+ * responder.mjs imports them — one delivery path, used by generated replies,
+ * acknowledgements, progress updates and failure notices alike.
+ *
+ * @module scripts/daemon/deliver
+ */
+
+"use strict";
+
+import { execFileSync } from "child_process";
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { screenOutbound } from "../../lib/comms/send-gate.mjs";
+import { getHookBus } from "../../lib/hooks/bus.mjs";
+import { recordOutbound } from "../../lib/comms/receipts.mjs";
+
+const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
+
+function today() {
+  return new Date().toISOString().split("T")[0];
+}
+
+function getSlackToken() {
+  return process.env.SLACK_USER_TOKEN || process.env.SLACK_BOT_TOKEN;
+}
+
+// ---------------------------------------------------------------------------
+// Channel resolution
+// ---------------------------------------------------------------------------
+
+/** Resolve a Slack channel id from a daemon inbox item. */
+export function resolveSlackChannel(item) {
+  if (!item) return null;
+  // Direct channel ID (starts with D for DM, C for channel)
+  if (item.channel && /^[DC][A-Z0-9]{8,}$/.test(item.channel)) return item.channel;
+  if (item.channel_id) return item.channel_id;
+
+  // Extract from raw_ref format: "slack:D099N1JGKRQ:1775331885.690669"
+  if (item.raw_ref) {
+    const match = item.raw_ref.match(/slack:([DC][A-Z0-9]+):/);
+    if (match) return match[1];
+    const bare = item.raw_ref.match(/^([DC][A-Z0-9]{8,})$/);
+    if (bare) return bare[1];
+  }
+  return null;
+}
+
+/**
+ * The channel a reply to this item belongs in, whatever the service — the key
+ * both the receipt ledger and the obligation ledger are keyed on.
+ *
+ * Routing is by ROOM, not by person: the room the inbound arrived in is the
+ * room the answer belongs in.
+ */
+export function replyTargetOf(item) {
+  if (!item) return null;
+  if (item.service === "slack") return resolveSlackChannel(item);
+  if (item.service === "gmail") return item.sender_email || item.sender || null;
+  return item.channel_id || item.channel || null;
+}
+
+/**
+ * The services this module can actually put a string in front of a human on.
+ *
+ * The daemon polls more than this: telegram, whatsapp, orgmail, voice, calendar
+ * and a second Gmail account all produce inbox items. `deliver` returns
+ * "unsupported service X" for those — a fact that used to be discovered only at
+ * send time, once per sweep tick, forever.
+ *
+ * Naming the set explicitly lets the caller ask BEFORE it promises anything,
+ * which is the difference between "I can't reach you here, so an operator has
+ * been told" and an apology retried 1,440 times a day into a void.
+ */
+export const DELIVERABLE_SERVICES = Object.freeze(["slack", "gmail", "cohort"]);
+
+/**
+ * Can `deliver` reach the human behind this item at all? Requires both a
+ * transport for the service AND a resolvable room to write into.
+ */
+export function canDeliverTo(item) {
+  if (!item || !item.service) return false;
+  if (!DELIVERABLE_SERVICES.includes(item.service)) return false;
+  return Boolean(replyTargetOf(item));
+}
+
+// ---------------------------------------------------------------------------
+// Slack
+// ---------------------------------------------------------------------------
+
+async function sendSlackMessage(channel, text, threadTs = null, o = {}) {
+  // Unified send-gate (P0-3): the daemon path passes the same chokepoint as the
+  // shell senders + BaseAdapter — banned-phrase, AI disclosure, and
+  // information-barrier screening at one place. Block on deny.
+  try {
+    const gate = await screenOutbound({ channel: "slack", recipient: channel, text, agentRoot: AGENT_REPO_DIR });
+    if (gate && gate.allow === false) {
+      throw new Error(`send-gate blocked Slack reply: ${gate.reason}`);
+    }
+  } catch (err) {
+    if (/send-gate blocked/.test(err.message)) throw err; // a real block propagates
+    // gate infra error (module/policy unreadable): fail-open for internal Slack
+    // channels (matches send-gate's internal posture) — never silently drop.
+    console.warn(`[deliver] send-gate check errored (allowing internal Slack): ${err.message}`);
+    try {
+      Promise.resolve(getHookBus().emit("onGuardFail", { guard: "send_gate", channel: "slack", recipient: channel, reason: err.message, failed_open: true }))
+        .catch(() => { /* bus emit is isolated; never propagate */ });
+    } catch { /* never let telemetry break the send path */ }
+  }
+
+  // Always use user token — bot tokens can't access DM channels
+  const token = getSlackToken();
+  if (!token) throw new Error("No Slack token available (set SLACK_USER_TOKEN in .env)");
+
+  const body = { channel, text, ...(threadTs ? { thread_ts: threadTs } : {}) };
+  const fetchImpl = o.fetchImpl || fetch;
+  const res = await fetchImpl("https://slack.com/api/chat.postMessage", {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!data.ok) throw new Error(`Slack API error: ${data.error}`);
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// Gmail
+// ---------------------------------------------------------------------------
+
+async function sendGmailResponse(item, text) {
+  const to = item.sender_email || item.sender;
+  const subject = `Re: ${item.subject || "(no subject)"}`;
+  const sendScript = join(AGENT_REPO_DIR, "scripts", "send-email-threaded.py");
+
+  try {
+    const args = [sendScript, to, subject, text];
+    if (item.subject) args.push("--reply-to-subject", item.subject);
+    execFileSync("python3", args, { cwd: AGENT_REPO_DIR, timeout: 30000, encoding: "utf-8", env: { ...process.env } });
+    return { sent: true, via: "smtp", to };
+  } catch (err) {
+    console.error(`[deliver] Gmail send failed for ${to}: ${err.message}`);
+    // Fall back to draft file so the response is not lost
+    const draftPath = join(AGENT_REPO_DIR, "outputs", "drafts",
+      `${today()}-quick-reply-${String(item.sender || "unknown").replace(/[^a-z0-9]/gi, "-")}.md`);
+    mkdirSync(join(AGENT_REPO_DIR, "outputs", "drafts"), { recursive: true });
+    const content = `# Quick Reply Draft (SEND FAILED)\n\nTo: ${to}\nSubject: ${subject}\nGenerated: ${new Date().toISOString()}\nError: ${err.message}\n\n---\n\n${text}\n`;
+    writeFileSync(draftPath, content);
+    return { sent: false, via: "draft_fallback", draft_path: draftPath, error: err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Cohort (the org's own messaging app)
+// ---------------------------------------------------------------------------
+
+/**
+ * Send onto Cohort. Goes through lib/org/messaging.sendMessage rather than the
+ * raw RPC so the outbound send-gate, the afterSend hook and cost attribution
+ * all still run.
+ *
+ * `idempotencySuffix` distinguishes the several distinct things we may say
+ * about ONE item — the acknowledgement, the FIRST progress update, the SECOND
+ * one, the answer, a failure notice. Without it they share a client message id
+ * and hq's server-side dedup swallows every message after the first, which
+ * would turn "never silent" into "acknowledged once and then silent forever".
+ *
+ * It must be distinct per MESSAGE, not per kind: two progress updates that both
+ * key on "progress" are one message as far as hq is concerned. Callers that can
+ * emit a kind more than once pass an ordinal (`progress-1`, `progress-2`). A
+ * genuine transport RETRY deliberately reuses the same suffix — that is the
+ * dedup doing its job.
+ */
+async function sendCohortReply(item, text, o = {}) {
+  try {
+    const channel = item.channel_id || item.channel || "";
+    if (!channel) return { sent: false, via: null, error: "no channel_id on item" };
+    const { sendMessage } = await import("../../lib/org/messaging.mjs");
+    const { loadOrgConfig } = await import("../../lib/org/client.mjs");
+    const agentRoot = process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+    const base = item.message_id || item.id || item.raw_ref || Date.now();
+    const suffix = o.idempotencySuffix ? `-${o.idempotencySuffix}` : "";
+    const frame = await sendMessage(
+      {
+        channel,
+        body: text,
+        idempotencyId: `reply-${base}${suffix}`,
+        ...(item.thread_id ? { threadId: item.thread_id } : {}),
+        ...(Array.isArray(o.mentions) && o.mentions.length ? { mentions: o.mentions } : {}),
+      },
+      { cfg: loadOrgConfig(agentRoot), agentRoot },
+    );
+    if (frame && frame.ok) return { sent: true, via: "cohort", channel };
+    return { sent: false, via: null, channel, error: (frame && frame.error && frame.error.message) || "send failed" };
+  } catch (err) {
+    return { sent: false, via: null, error: err && err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The one public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Deliver `text` to the human behind `item`. No generation, no model, no
+ * budget — only transport.
+ *
+ * A successful delivery writes a RECEIPT (lib/comms/receipts). That receipt is
+ * how the daemon later answers "did this session actually say anything to the
+ * requester", which is the question it previously could not ask and therefore
+ * always answered "yes".
+ *
+ * @param {object} item      daemon inbox item
+ * @param {string} text      exactly what the human will read
+ * @param {object} [o]
+ * @param {string} [o.kind]  receipt kind: "ack" | "progress" | "failure" | "reply"
+ * @param {string[]} [o.mentions] org member ids to @-tag (cohort only)
+ * @param {function} [o.fetchImpl] test seam
+ * @returns {Promise<{sent:boolean, via:string|null, channel?:string, error?:string}>}
+ *          NEVER throws — a transport failure is returned, so the caller can
+ *          escalate rather than lose the message to an exception.
+ */
+export async function deliver(item, text, o = {}) {
+  const kind = o.kind || "reply";
+  if (!item || !text || !String(text).trim()) {
+    return { sent: false, via: null, error: "nothing to deliver" };
+  }
+  // `permanent` says retrying changes nothing. A caller that cannot tell the
+  // difference between "hq blipped" and "there is no transport for telegram"
+  // retries both at the same cadence, which is how an impossible send becomes an
+  // infinite loop.
+  let result = { sent: false, via: null, permanent: true, error: `unsupported service ${item && item.service}` };
+  try {
+    if (item.service === "slack") {
+      const channel = resolveSlackChannel(item);
+      if (!channel) {
+        result = { sent: false, via: null, permanent: true, error: "could not resolve slack channel" };
+      } else {
+        await sendSlackMessage(channel, text, item.thread_id || null, o);
+        result = { sent: true, via: "slack_api", channel };
+      }
+    } else if (item.service === "gmail") {
+      const r = await sendGmailResponse(item, text);
+      result = { sent: r.sent, via: r.via, channel: r.to, ...(r.draft_path ? { draft_path: r.draft_path } : {}), ...(r.error ? { error: r.error } : {}) };
+    } else if (item.service === "cohort") {
+      const r = await sendCohortReply(item, text, { ...o, idempotencySuffix: o.idempotencySuffix || (kind === "reply" ? "" : kind) });
+      result = r;
+    }
+  } catch (err) {
+    result = { sent: false, via: null, error: err && err.message ? err.message : String(err) };
+  }
+
+  if (result.sent) {
+    recordOutbound({
+      service: item.service,
+      channel: result.channel || replyTargetOf(item),
+      kind,
+      via: result.via,
+      chars: String(text).length,
+      agentRoot: AGENT_REPO_DIR,
+    });
+  }
+  return result;
+}
+
+/**
+ * Deliver with bounded retry. Transport failures are usually transient (a 429,
+ * a dropped socket, hq restarting); a courtesy message that gives up on the
+ * first refusal is how silence happens.
+ *
+ * Deliberately short and bounded: this runs in front of a waiting human, so the
+ * total budget here is ~3s, not a minute. If it still fails, the caller gets
+ * `{sent:false}` and the obligation ledger keeps the debt.
+ *
+ * @param {number} [o.attempts=3]
+ * @param {number} [o.baseDelayMs=250]
+ * @param {(ms:number)=>Promise<void>} [o.sleep] test seam
+ */
+export async function deliverWithRetry(item, text, o = {}) {
+  const attempts = Number.isFinite(o.attempts) ? o.attempts : 3;
+  const base = Number.isFinite(o.baseDelayMs) ? o.baseDelayMs : 250;
+  const sleep = o.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let last = { sent: false, via: null, error: "not attempted" };
+  for (let i = 0; i < attempts; i++) {
+    last = await deliver(item, text, o);
+    if (last.sent) return { ...last, attempts: i + 1 };
+    // A policy block is a decision, not a fault — retrying re-runs the same
+    // deterministic screen and gets the same answer. Stop and surface it.
+    if (last.permanent || (last.error && /send-gate blocked|blocked by send-gate|FORBIDDEN/i.test(last.error))) {
+      return { ...last, attempts: i + 1, permanent: true };
+    }
+    if (i < attempts - 1) await sleep(base * Math.pow(2, i));
+  }
+  return { ...last, attempts };
+}
+
+export default { deliver, deliverWithRetry, resolveSlackChannel, replyTargetOf, canDeliverTo, DELIVERABLE_SERVICES };

package/scripts/daemon/dispatcher-governance.test.mjs

@@ -504,6 +504,16 @@ test("0.3: a finished inbox session writes a nonzero cost-ledger row from its re
       new URL("../cost/track-claude-usage.mjs", import.meta.url),
       join(dir, "scripts/cost/track-claude-usage.mjs")
     );
+    // The tracker imports the shared billing contract (lib/cost/ledger-row.mjs)
+    // relative to itself, so a synthetic agent root needs it too — otherwise the
+    // detached `record` spawn dies on import and writes nothing. (In the wild
+    // that failure is silent, which is why doctor's tripwire now goes RED when
+    // the daemon logs sessions that never reach the ledger.)
+    await fsp.mkdir(join(dir, "lib/cost"), { recursive: true });
+    await fsp.copyFile(
+      new URL("../../lib/cost/ledger-row.mjs", import.meta.url),
+      join(dir, "lib/cost/ledger-row.mjs")
+    );
 
     const proc = controllableProc();
     const restore = mod.setSpawnForTests(() => proc);

package/scripts/daemon/dispatcher.mjs

@@ -64,7 +64,16 @@ function admitFor(source, priority) {
   try {
     let mode = null;
     try {
-      if (budgetGuard.dailyStatus({ agentRoot: AGENT_REPO_DIR }).essentialOnly) mode = "essential-only";
+      // The full ladder, not just the top rung: `mode` is
+      // normal|degraded|suspended|refused, banded against the seat's hq-funded
+      // envelope. Reading `.essentialOnly` here (as this did) collapsed four
+      // rungs into one and threw away both the degrade rung and the spawn-level
+      // refuse.
+      const st = budgetGuard.dailyStatus({ agentRoot: AGENT_REPO_DIR });
+      if (st.mode && st.mode !== "normal") {
+        mode = st.mode;
+        console.warn(`[dispatcher] budget ${st.mode}: ${st.pct}% of $${st.capUSD}/day (${st.capSource}) — gating ${source} work`);
+      }
     } catch { /* budget read best-effort */ }
     return governor.admit({ source, priority, mode }, governor.defaultDeps({ agentRoot: AGENT_REPO_DIR }));
   } catch {
@@ -242,6 +251,12 @@ export function parseUsageFromText(text) {
   const out = { ok: true, inputTokens, outputTokens };
   const cacheRead = Number(usage.cache_read_input_tokens);
   if (Number.isFinite(cacheRead)) out.cacheReadTokens = cacheRead;
+  // Cache CREATION tokens bill at 1.25x input and were previously dropped on
+  // the floor — on a cache-heavy workload that is a large slice of the real
+  // cost, and its absence is most of the gap between the local estimate and
+  // the CLI's total_cost_usd.
+  const cacheWrite = Number(usage.cache_creation_input_tokens);
+  if (Number.isFinite(cacheWrite)) out.cacheWriteTokens = cacheWrite;
   const totalCost = Number(obj.total_cost_usd);
   if (Number.isFinite(totalCost) && totalCost >= 0) out.totalCostUsd = totalCost;
   if (typeof obj.model === "string" && obj.model) {
@@ -253,9 +268,17 @@ export function parseUsageFromText(text) {
 /**
  * Append a TRUTHFUL cost-ledger row for a finished dispatcher session via
  * scripts/cost/track-claude-usage.mjs (source "dispatcher"). Real token counts
- * are parsed from the run's --output-format json stdout; on a parse failure we
- * pass NO token flags (tracker records 0) rather than fabricate zeros, and the
- * caller logs the gap. Best-effort + detached; never blocks the close path.
+ * are parsed from the run's --output-format json stdout.
+ *
+ * On a parse failure we pass `--tokens-unknown <reason>`, which records
+ * measurement:"unknown" with NULL tokens. Previously we passed no token flags
+ * at all and the tracker defaulted them to 0 — a row that read as a free
+ * session. "Omit the flags rather than fabricate zeros" was the intent, but the
+ * tracker fabricated them anyway, so a systematic parse regression would drive
+ * the day's measured spend toward $0 and the budget governor would go quiet
+ * exactly when it should have been shouting. Fail-open is fine; silent is not.
+ *
+ * Best-effort + detached; never blocks the close path.
  */
 function recordDispatcherCost({ stdout, model, durationMs, exitCode, decisionId }) {
   const usage = parseUsageFromText(stdout);
@@ -278,7 +301,20 @@ function recordDispatcherCost({ stdout, model, durationMs, exitCode, decisionId
       trackerArgs.push("--input-tokens", String(usage.inputTokens));
       trackerArgs.push("--output-tokens", String(usage.outputTokens));
       if (usage.cacheReadTokens != null) trackerArgs.push("--cache-read-tokens", String(usage.cacheReadTokens));
+      if (usage.cacheWriteTokens != null) trackerArgs.push("--cache-creation-tokens", String(usage.cacheWriteTokens));
       if (usage.totalCostUsd != null) trackerArgs.push("--total-cost-usd", String(usage.totalCostUsd));
+    } else {
+      // Explicit "we ran a session and could not measure it" marker. NEVER a 0.
+      trackerArgs.push("--tokens-unknown", String(usage.reason || "usage-parse-failed"));
+      try {
+        logSession({
+          event: "cost_usage_parse_failed",
+          reason: usage.reason || "unknown",
+          model: model || null,
+          duration_ms: durationMs,
+          exit_code: exitCode,
+        });
+      } catch { /* logging must not break the close path */ }
     }
     spawn(process.execPath, trackerArgs, {
       stdio: "ignore",
@@ -732,7 +768,17 @@ export function canDispatchBacklog(item) {
  *   which leave the durable on-disk item untouched for the next sweep anyway.
  */
 export function dispatch(prompt, item, classResult, source = "inbox", opts = {}) {
-  const entry = { prompt, item, classResult, source, onClose: typeof opts.onClose === "function" ? opts.onClose : null };
+  // `obligationKey` names the debt this session was spawned to discharge. It is
+  // carried into the child's environment so the CLI send lanes (the ONLY way a
+  // session is allowed to reply) can stamp their delivery receipts with it.
+  // Without it a receipt says only "somebody spoke into that room", and a room
+  // is shared: two asks in one DM produce two debts, the first reply discharges
+  // both, and the unanswered one is closed as answered with nobody told.
+  const entry = {
+    prompt, item, classResult, source,
+    obligationKey: opts.obligationKey || null,
+    onClose: typeof opts.onClose === "function" ? opts.onClose : null,
+  };
   const priority = classResult.priority;
   const isPriorityInbox = source === "inbox" && (priority === "critical" || priority === "high");
 
@@ -892,7 +938,12 @@ export function _hasReDrainArmed() {
 function currentBudgetBand() {
   try {
     const st = budgetGuard.dailyStatus({ agentRoot: AGENT_REPO_DIR });
-    return budgetLadder(st.spentUSD, st.capUSD).band;
+    // Pass the GOVERNOR'S band rather than letting budgetLadder re-derive one
+    // from (spent, cap). dailyStatus has already reconciled the day reading, the
+    // month reading, the cap latch and blindness; re-deriving here collapsed to
+    // band 0 whenever the monthly envelope was spent out (cap === 0), so the
+    // router stopped degrading exactly when the seat was furthest over.
+    return budgetLadder(st.spentUSD, st.capUSD, { band: st.band }).band;
   } catch {
     return 0;
   }
@@ -1088,6 +1139,13 @@ function spawnSession(entry) {
         ANTHROPIC_AUTH_TOKEN: "",
         ...(target.envForSpawn || {}),
       };
+  // ATTRIBUTION for delivery receipts. Set after the merges above so a router
+  // target's envForSpawn can never drop it — a retargeted session replies
+  // through exactly the same CLI lanes and owes exactly the same receipt.
+  // These are plain identifiers, never credentials, so the §7.3 allowlist scrub
+  // in buildChildEnv has nothing to object to.
+  spawnEnv.MAESTRO_SESSION_ID = sessionId;
+  if (entry.obligationKey) spawnEnv.MAESTRO_OBLIGATION_KEY = String(entry.obligationKey);
 
   const proc = _spawn(CLAUDE_BIN, args, {
     cwd: AGENT_REPO_DIR,

package/scripts/daemon/responder-cost.test.mjs

@@ -0,0 +1,68 @@
+/**
+ * responder-cost.test.mjs — every responder spawn is billed, including the ones
+ * that FAIL.
+ *
+ * The defect this guards: `recordResponderCost` was reached only at the bottom
+ * of the `close` handler, after `if (settled) return;` and after
+ * `if (code !== 0) { reject; return; }`. So the two most expensive outcomes the
+ * daemon has — a 60s CLI timeout and a non-zero exit — wrote NO ledger row at
+ * all, not even `--tokens-unknown`. On the live seat that was 15 timeouts on
+ * 2026-08-11 and 10 on 2026-08-12: a full minute of paid model work each,
+ * invisible to the governor and to doctor.
+ *
+ * Run: `node --test scripts/daemon/responder-cost.test.mjs`
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { unmeasuredReasonFor } from "./responder.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SRC = readFileSync(join(HERE, "responder.mjs"), "utf-8");
+
+test("a TIMED-OUT session is billed as unmeasured, naming the timeout", () => {
+  const r = unmeasuredReasonFor({ parsed: null, timedOut: true, exitCode: null, parseError: null, timeoutMs: 60_000 });
+  assert.equal(r, "cli-timeout-60000ms");
+});
+
+test("a NON-ZERO exit is billed as unmeasured, naming the code", () => {
+  const r = unmeasuredReasonFor({ parsed: null, timedOut: false, exitCode: 1, parseError: null, timeoutMs: 60_000 });
+  assert.equal(r, "cli-exit-1");
+});
+
+test("an unparseable envelope on a clean exit is billed as unmeasured", () => {
+  const r = unmeasuredReasonFor({ parsed: null, timedOut: false, exitCode: 0, parseError: new Error("bad json"), timeoutMs: 60_000 });
+  assert.equal(r, "json-parse-failed");
+});
+
+test("a parsed envelope is measured — no reason at all", () => {
+  const r = unmeasuredReasonFor({ parsed: { usage: {} }, timedOut: true, exitCode: 1, parseError: new Error("x"), timeoutMs: 60_000 });
+  assert.equal(r, null, "a real envelope wins over every failure signal");
+});
+
+test("the timeout path never masks itself as a plain non-zero exit", () => {
+  // SIGTERM'd processes close with a code, and the operator needs to know WHICH
+  // failure burned the minute — the fixes are different.
+  const r = unmeasuredReasonFor({ parsed: null, timedOut: true, exitCode: 143, parseError: null, timeoutMs: 60_000 });
+  assert.equal(r, "cli-timeout-60000ms");
+});
+
+test("STRUCTURAL: the cost record happens BEFORE the close handler's early returns", () => {
+  // This is an ordering bug in code that cannot be unit-tested without a spawn
+  // harness, so the ordering itself is the assertion. If someone moves the
+  // recording back below `if (settled) return;`, every timeout goes unbilled
+  // again — silently, because the reply still works.
+  const close = SRC.slice(SRC.indexOf('proc.on("close"'));
+  const record = close.indexOf("recordResponderCost({");
+  const settledGuard = close.indexOf("if (settled) return;");
+  const exitGuard = close.indexOf("if (code !== 0) {");
+
+  assert.ok(record > 0 && settledGuard > 0 && exitGuard > 0, "all three markers present");
+  assert.ok(record < settledGuard, "cost is recorded before the settled early-return (the TIMEOUT path)");
+  assert.ok(record < exitGuard, "cost is recorded before the non-zero-exit early-return");
+  assert.match(close.slice(0, record), /costRecorded/, "and exactly once per spawn");
+});