@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/scripts/daemon/assurance.mjs

@@ -60,7 +60,9 @@ import { resultTextFromStdout } from "./session-outcomes.mjs";
 // The ack generator funnels through `claude --print` like every other daemon
 // model call (CEO directive 2026-04-27: no direct Anthropic API from the
 // daemon), pinned to the cheapest model with a tight, env-tunable timeout.
-import { resolveClaudeBin, augmentedPath, daemonClaudeArgs } from "../../lib/claude-bin.mjs";
+import { resolveClaudeBin } from "../../lib/claude-bin.mjs";
+import { buildSpawn } from "../../lib/runtime/adapter.mjs";
+import { resolveSeatSpawn } from "../../lib/runtime/seat-engine.mjs";
 import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
 // Second self-echo guard: even if an echo somehow reaches the ack decision,
 // this agent never acknowledges its own message back at itself.
@@ -76,6 +78,7 @@ import * as counters from "../../lib/diagnostics/counters.mjs";
 // the only composer of interim copy left in the system, and carries the two
 // copy rules (GENERIC_OPENER, FORWARD_PROMISE) every interim must satisfy.
 import { replyTier } from "../../lib/assurance/tier.mjs";
+import { isRollCallItem } from "../../lib/org/inbound/broadcast.mjs";
 import {
   claimRoomInterim,
   claimRoomNotice,
@@ -602,6 +605,14 @@ export function shouldAcknowledge(o = {}) {
     logDispatchGateRefusal(item, "peer-ack-shaped");
     return { ack: false, reason: "peer-ack-shaped", emitterClass: true, tier };
   }
+  // ── A ROLL-CALL NEVER GETS AN INTERIM ─────────────────────────────────────
+  // A human asked the whole room for a line each. Thirteen "checking now"
+  // lines followed by thirteen answers is twice the traffic and half the
+  // signal; the answer IS the acknowledgement. `ack:false` here makes
+  // `interimForbidden` durable on the debt, so no later sweep in any process
+  // posts one either. The caller still opens the debt — silence about timing
+  // is not silence about outcome.
+  if (isRollCallItem(item)) return { ack: false, reason: "roll-call", tier };
   // ── THE TIER ──────────────────────────────────────────────────────────────
   // The answer tier is silence by construction: the reply arrives in this turn,
   // so an interim in front of it is the content-free traffic this whole change
@@ -650,21 +661,46 @@ const CLAUDE_BIN = resolveClaudeBin();
  * same spawn-not-exec injection hygiene) rather than importing it, because the
  * classifier's 30s budget is a different promise from this path's ~5s one.
  */
+/**
+ * The ack lane's spawn from the runtime adapter (lane "ack"): --print
+ * <permissions> <MCP by source> --model <m> --append-system-prompt <sys>, prompt
+ * on stdin; stock env posture (stale API keys stripped, PATH that can find the
+ * binary's runtime under launchd).
+ *
+ * W4-E1 (CF-44): `seat` is the seat's engine resolved once for this spawn. A
+ * claude seat adds no fields (unchanged); an engine-cohort seat runs `cli.mjs run`.
+ * @param {{systemPrompt:string, userPrompt:string, env?:object, bin?:string, seat?:{fields:object}}} o
+ */
+export function ackSpawn({ systemPrompt, userPrompt, env = process.env, bin = CLAUDE_BIN, seat = { fields: {} } }) {
+  return buildSpawn({
+    lane: "ack",
+    bin,
+    model: ACK_MODEL,
+    systemPrompt,
+    prompt: userPrompt,
+    permissions: sessionPermissionArgs({ source: "ack" }),
+    mcp: { source: "ack" },
+    env,
+    ...seat.fields,
+  });
+}
+
 function runAckModel(systemPrompt, userPrompt, o = {}) {
+  // W4-E1: the seat's engine, once per spawn (a claude seat reads config/agent.json only).
+  return resolveSeatSpawn(AGENT_REPO_DIR).then((seat) => runAckModelWith(seat, systemPrompt, userPrompt, o));
+}
+
+function runAckModelWith(seat, systemPrompt, userPrompt, o = {}) {
   const timeoutMs = Number.isFinite(o.timeoutMs) ? o.timeoutMs : ACK_GEN_TIMEOUT_MS;
   return new Promise((resolvePromise, rejectPromise) => {
-    const args = [
-      "--print",
-      ...sessionPermissionArgs({ source: "ack" }),
-      ...daemonClaudeArgs(undefined, { source: "ack" }),
-      "--model", ACK_MODEL,
-      "--append-system-prompt", systemPrompt,
-    ];
-    const proc = spawn(CLAUDE_BIN, args, {
+    const spawnSpec = ackSpawn({ systemPrompt, userPrompt, seat });
+    if (!spawnSpec.ok) {
+      rejectPromise(new Error(`claude CLI unavailable: ${spawnSpec.error.message}`));
+      return;
+    }
+    const proc = spawn(spawnSpec.bin, spawnSpec.argv, {
       stdio: ["pipe", "pipe", "pipe"],
-      // Keychain OAuth (Max subscription); strip stale API keys; PATH that can
-      // actually find the binary's runtime under launchd.
-      env: { ...process.env, PATH: augmentedPath(), ANTHROPIC_API_KEY: "", ANTHROPIC_AUTH_TOKEN: "" },
+      env: spawnSpec.env,
     });
     let stdout = "";
     let settled = false;

package/scripts/daemon/cadence-consumer.mjs

@@ -94,7 +94,7 @@ import {
 import { readFrontDoorState, shouldHandOffTick } from "../../lib/session/frontdoor.mjs";
 import { writeHandoff, listHandoffs, expireHandoffs, pruneHandoffs, handoffPaths } from "../../lib/session/handoffs.mjs";
 import { writeFileAtomic } from "../../lib/fs-atomic.mjs";
-import { resolveClaudeBin as sharedResolveClaude, augmentedPath, daemonClaudeArgs } from "../../lib/claude-bin.mjs";
+import { resolveClaudeBin as sharedResolveClaude } from "../../lib/claude-bin.mjs";
 import { getCadenceDef } from "./cadence-handlers.mjs";
 import { obligationAllowedUnderPosture } from "../../lib/plan/compile.mjs";
 import { isHumanLaneCadence } from "../../lib/cadences.mjs";
@@ -112,7 +112,10 @@ import {
   loadRoutingConfig,
   resolveChain,
 } from "../../lib/model-router.mjs";
-import { buildChildEnv } from "../../lib/model-router/spawn.mjs";
+import { buildSpawn, admitSpawn, isCohortRouted, readSeatEngine } from "../../lib/runtime/adapter.mjs";
+import { seatEngineFields, engineRunShape, seatTokenSync } from "../../lib/runtime/seat-engine.mjs";
+import { seatCohortClients } from "../../lib/org/llm-token.mjs";
+import { COHORT_LLM_BILLED_BY } from "../../lib/org/cost-sync.mjs";
 import { budgetLadder, batchLaneFor, spawnKnobsFor } from "../../lib/model-router/economics.mjs";
 import * as budgetGuardForBand from "../../lib/budget-guard.mjs";
 // WS4 — the consumer is one of the spawn sources, so it honours the SAME
@@ -214,24 +217,38 @@ export function parseUsageFromStdout(stdoutPath) {
   }
   if (!obj || typeof obj !== "object") return { ok: false, reason: "no-json-object" };
 
+  // A Cohort Engine result names the gateway requests that served it.
+  const cohort = obj.cohort && typeof obj.cohort === "object" ? obj.cohort : null;
+  const cohortMeta = cohort
+    ? { servedByCohort: true, requestIds: Array.isArray(cohort.requestIds) ? cohort.requestIds.filter((x) => typeof x === "string" && x) : [] }
+    : {};
+
   const usage = obj.usage && typeof obj.usage === "object" ? obj.usage : null;
-  if (!usage) return { ok: false, reason: "no-usage-field" };
+  if (!usage) return { ok: false, reason: "no-usage-field", ...cohortMeta };
 
   const inputTokens = Number(usage.input_tokens);
   const outputTokens = Number(usage.output_tokens);
   if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens)) {
-    return { ok: false, reason: "non-numeric-tokens" };
+    return { ok: false, reason: "non-numeric-tokens", ...cohortMeta };
   }
 
-  const out = { ok: true, inputTokens, outputTokens };
+  const out = { ok: true, inputTokens, outputTokens, ...cohortMeta };
   const cacheRead = Number(usage.cache_read_input_tokens);
   if (Number.isFinite(cacheRead)) out.cacheReadTokens = cacheRead;
   // Cache CREATION tokens bill at 1.25x input; dropping them was a large slice
   // of the gap between the local estimate and the CLI's authoritative cost.
   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;
+  // A NUMBER, not anything Number() will coerce. The Cohort Engine writes
+  // `total_cost_usd: null` when not every request reported gateway cost
+  // (lib/engine/output/json.mjs), and `Number(null)` is 0 — finite, >= 0 —
+  // which recorded such a cadence as $0.00 authoritative: the free-looking
+  // row the parse-failure branch below exists never to write. This consumer
+  // spawns the engine on an engine=cohort seat (engineRunShape above), so the
+  // null is reachable here exactly as in dispatcher.mjs#parseUsageFromText
+  // and responder.mjs#responderCostArgs. (engine-envelope-parity.test.mjs)
+  const totalCost = obj.total_cost_usd;
+  if (typeof totalCost === "number" && Number.isFinite(totalCost) && totalCost >= 0) out.totalCostUsd = totalCost;
   // The CLI may report the resolved model (e.g. "claude-sonnet-4-6"); map it to
   // the tracker's coarse class so pricing lookup stays correct.
   if (typeof obj.model === "string" && obj.model) {
@@ -363,7 +380,7 @@ export function renderCadencePromptBody(agentRoot, body) {
  * so non-zero exits remain diagnosable after the fact. The last ~4 KB of
  * stderr is also captured in-memory and surfaced on the failure event.
  */
-function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
+function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log, target: gatedTarget, engine: gatedEngine, cohortToken: gatedToken, cohortBaseUrl: gatedBaseUrl }) {
   return new Promise((resolveOut) => {
     const fullPrompt = join(agentRoot, promptPath);
     if (!existsSync(fullPrompt)) {
@@ -392,64 +409,81 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
     // Route the cadence sub-session's model through the v2 router (opt-in). When
     // a backend is chosen we pass its --model flag + spawn knobs; otherwise the
     // argv stays exactly as before (no --model → stock CLI default model).
-    const target = routeCadenceSpawn(agentRoot, cadence);
-    const routedArgs = [];
+    // The consumer's cohort gate already resolved (and admitted) the target;
+    // re-resolving here could pick a different one. undefined = no gate ran.
+    const target = gatedTarget !== undefined ? gatedTarget : routeCadenceSpawn(agentRoot, cadence);
     if (target) {
-      if (target.maxTurns != null && Number.isFinite(Number(target.maxTurns))) {
-        routedArgs.push("--max-turns", String(target.maxTurns));
-      }
-      if (target.effort) routedArgs.push("--effort", String(target.effort));
-      if (target.agentsJson) {
-        routedArgs.push("--agents", typeof target.agentsJson === "string" ? target.agentsJson : JSON.stringify(target.agentsJson));
-      }
-      if (target.modelFlag) routedArgs.push("--model", String(target.modelFlag));
       log({ level: "info", stage: "cadence_routed", cadence, decision_id: target.decisionId, backend: target.backend, model: target.model, transport: target.transport, lane: target.lane, explain: target.explain });
     }
 
-    // --output-format json makes stdout a single JSON object carrying the real
-    // token usage (and total_cost_usd) for this run. The cadence sub-session's
-    // stdout is redirected to stdoutPath (below) and nothing parses it for
-    // CONTENT — only this function reads it back, to record a TRUTHFUL cost row
-    // (recovery C1). Without this the ledger logged input/output tokens 0 → the
-    // fleet's only spend control summed $0 forever.
-    // The cadence PROMPT (body) stays the LAST positional arg; routed model +
-    // knob flags slot before it (after the daemon args), mirroring the dispatcher.
-    const args = ["--print", "--output-format", "json", ...permissionArgs, ...daemonClaudeArgs(), ...routedArgs, body];
-    // PATH augmented via lib/claude-bin.mjs so subsession can find jq/node.
-    let env = {
-      ...process.env,
-      AGENT_ROOT: agentRoot,
-      AGENT_DIR: agentRoot,
-      PATH: augmentedPath(),
-    };
-    // v2 third-party retarget: build the child env through the execution layer's
-    // §7.3 allowlist scrub so no foreign credential leaks into the third-party
-    // session (buildChildEnv injects ANTHROPIC_API_KEY="" for a retarget). We
-    // preserve the cadence-specific env (AGENT_ROOT/AGENT_DIR/PATH) on top.
-    const retargeting = !!(target && target.envForSpawn && target.envForSpawn.ANTHROPIC_BASE_URL);
-    if (retargeting) {
-      env = {
-        ...buildChildEnv(env, target.envForSpawn),
-        AGENT_ROOT: agentRoot,
-        AGENT_DIR: agentRoot,
-        PATH: augmentedPath(),
-      };
-    } else {
-      // Auth handling. Claude Code authenticates via macOS Keychain
-      // (OAuth from the user's Pro/Max subscription) when no API key is
-      // set, OR via the ANTHROPIC_API_KEY env var when one is present.
-      // If the env key is present BUT looks like a placeholder / empty
-      // string, we strip it so claude can fall back to Keychain OAuth.
-      // Set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 in .env to always strip
-      // the API key (force subscription auth) — useful when the agent
-      // owns a Claude Code Pro/Max subscription and shouldn't burn API
-      // credits for routine ticks.
-      const preferSubscription = process.env.MAESTRO_PREFER_SUBSCRIPTION_AUTH === "1";
-      const apiKey = env.ANTHROPIC_API_KEY || "";
-      if (preferSubscription || !apiKey.trim() || /^(your-api-key|placeholder|xxx+|sk-ant-xxx)/i.test(apiKey)) {
-        delete env.ANTHROPIC_API_KEY;
+    // argv + env come from the runtime adapter (lib/runtime/adapter.mjs, lane
+    // "cadence"). What it builds, unchanged from the inline version:
+    //   argv  --print --output-format json <permissions> <daemon MCP args>
+    //         <router knobs> [--model <flag>] <body>
+    //         --output-format json makes stdout one JSON object carrying the real
+    //         token usage, read back below only to record a TRUTHFUL cost row
+    //         (recovery C1). The body stays the LAST positional arg; no router →
+    //         no knobs and no --model (the CLI default model).
+    //   env   {...process.env, AGENT_ROOT, AGENT_DIR, PATH (augmented)}. Stock:
+    //         ANTHROPIC_API_KEY is deleted when MAESTRO_PREFER_SUBSCRIPTION_AUTH=1
+    //         or the key is empty/a placeholder, so claude rides the seat's
+    //         subscription credential. A v2 retarget goes through the one runtime
+    //         env builder (foreign credentials AND the OAuth token scrubbed,
+    //         ANTHROPIC_API_KEY="", CLAUDE_CODE_ATTRIBUTION_HEADER=0) with the
+    //         cadence vars re-applied on top.
+    // W4-E1 (CF-44): the engine the gate resolved for this tick (else read now,
+    // once). An engine-cohort seat runs `cli.mjs run` with the admitted seat
+    // token and no retarget; a claude seat's input is exactly as before.
+    const engine = gatedEngine === "cohort" || gatedEngine === "claude" ? gatedEngine : readSeatEngine(agentRoot);
+    const engineShape = engine === "cohort" ? engineRunShape({ target, laneModel: null }) : null;
+    let engineToken = null;
+    let engineBaseUrl = null;
+    if (engineShape) {
+      engineToken = gatedToken || null;
+      engineBaseUrl = gatedBaseUrl || null;
+      if (!engineToken || !engineBaseUrl) {
+        try {
+          const seatToken = seatCohortClients({ agentRoot }).token;
+          if (!engineToken) engineToken = seatTokenSync(seatToken);
+          if (!engineBaseUrl) engineBaseUrl = seatToken.baseUrl || null;
+        } catch { /* no seat key: the adapter refuses the spawn as a value */ }
       }
     }
+    const spawnInput = {
+      lane: "cadence",
+      bin,
+      prompt: body,
+      permissions: permissionArgs,
+      mcp: {},
+      knobs: engineShape ? engineShape.knobs : target,
+      model: engineShape ? engineShape.model : target && target.modelFlag ? target.modelFlag : null,
+      agentRoot,
+      env: process.env,
+      retarget: engineShape ? engineShape.retarget : (target && target.envForSpawn) || {},
+      ...seatEngineFields({ engine, agentRoot, token: engineToken, baseUrl: engineBaseUrl }),
+    };
+    let spawnSpec = buildSpawn(spawnInput);
+    let refusedRetarget = null;
+    if (!spawnSpec.ok && /^retarget_/.test(spawnSpec.error.code)) {
+      // Refused retarget (no third-party token): run the tick exactly as an
+      // unrouted spawn instead of handing that backend the seat's credential.
+      log({ level: "warn", stage: "cadence_retarget_refused", cadence, decision_id: target && target.decisionId, code: spawnSpec.error.code, error: spawnSpec.error.message });
+      refusedRetarget = spawnSpec.error;
+      spawnSpec = buildSpawn({ ...spawnInput, knobs: null, model: null, retarget: {} });
+    }
+    // CF-11: after a refusal the run is the unrouted stock session — the cost
+    // row must not carry the refused backend's model.
+    const costTarget = refusedRetarget ? null : target;
+    // The breaker and billing flags follow the engine as well as routing (W4-E1).
+    const servedByCohort = engine === "cohort" || (!refusedRetarget && isCohortRouted({ target }));
+    if (!spawnSpec.ok) {
+      resolveOut({ ok: false, exit_code: -5, cohort_routed: servedByCohort, error: `runtime unavailable: ${spawnSpec.error.message}` });
+      return;
+    }
+    const args = spawnSpec.argv;
+    // The adapter's binary: the claude binary resolved above, or node for the engine.
+    const spawnBin = spawnSpec.bin;
+    const env = spawnSpec.env;
     const started = Date.now();
 
     // Per-run log file. Pattern is short enough to be tail-friendly.
@@ -462,7 +496,7 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
     const stdoutFd = openSync(stdoutPath, "a");
     const stderrFd = openSync(stderrPath, "a");
 
-    log({ level: "info", stage: "subsession_spawn", cadence, bin, stdout: stdoutPath, stderr: stderrPath });
+    log({ level: "info", stage: "subsession_spawn", cadence, bin: spawnBin, ...(engine === "cohort" ? { engine } : {}), stdout: stdoutPath, stderr: stderrPath });
 
     let child;
     try {
@@ -470,7 +504,7 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
       //   0 ignore  (claude --print reads prompt from argv, not stdin)
       //   1 → file  (capture stdout for later inspection)
       //   2 → file  (capture stderr — critical for diagnosing exit-1)
-      child = spawn(bin, args, { cwd: agentRoot, env, stdio: ["ignore", stdoutFd, stderrFd] });
+      child = spawn(spawnBin, args, { cwd: agentRoot, env, stdio: ["ignore", stdoutFd, stderrFd] });
     } catch (err) {
       try { closeSync(stdoutFd); closeSync(stderrFd); } catch { /* */ }
       resolveOut({ ok: false, exit_code: -4, error: `spawn failed: ${err.message}` });
@@ -501,6 +535,10 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
           stderrTail = so.slice(-4096);
         }
       } catch { /* file may not exist if spawn ENOENT before fd-redirect */ }
+      // stdout's own tail, for the structured cohort-refusal check: an engine
+      // run's JSON result lands on stdout even when stderr is not empty.
+      let stdoutTail = "";
+      try { stdoutTail = readFileSync(stdoutPath, "utf-8").slice(-65_536); } catch { /* */ }
 
       // Record a TRUTHFUL cost-ledger row (recovery C1). We parse the run's
       // `--output-format json` object from stdoutPath to read the REAL token
@@ -518,13 +556,16 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
             "--source", "cadence-consumer",
             // Prefer the CLI-reported resolved model class; else the routed
             // model flag (v2); else the historical sonnet default.
-            "--model", usage.model || (target && target.model) || "sonnet",
+            "--model", usage.model || (costTarget && costTarget.model) || "sonnet",
             "--duration-ms", String(durationMs),
             "--exit", String(exit_code),
           ];
           // Carry the v2 RouteDecision id onto the ledger row (SPEC §4.7) so a
           // cadence spend row joins its routing decision. Absent on stock-CLI.
           if (target && target.decisionId) trackerArgs.push("--decision-id", String(target.decisionId));
+          // Metered by cohort-llm at the gateway: mark it so org cost-sync skips it.
+          if (servedByCohort || usage.servedByCohort) trackerArgs.push("--billed-by", COHORT_LLM_BILLED_BY);
+          if (Array.isArray(usage.requestIds) && usage.requestIds.length) trackerArgs.push("--request-ids", usage.requestIds.join(","));
           if (usage.ok) {
             trackerArgs.push("--input-tokens", String(usage.inputTokens));
             trackerArgs.push("--output-tokens", String(usage.outputTokens));
@@ -555,9 +596,11 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
       resolveOut({
         ok: exit_code === 0,
         exit_code,
+        cohort_routed: servedByCohort,
         signal: signal || null,
         duration_ms: durationMs,
         stderr_tail: stderrTail || null,
+        stdout_tail: stdoutTail || null,
         stdout_path: stdoutPath,
         stderr_path: stderrPath,
       });
@@ -604,6 +647,62 @@ export function startConsumer(opts = {}) {
   const rateGuard = opts.rateGuard || rateGuardModule;
   const budgetGuard = opts.budgetGuard || budgetGuardModule;
   const handoffDeadlineMs = opts.handoffDeadlineMs;
+  // cohort-llm pre-spawn gate (design C6 / §8.3). `opts.cohort` = {quota, token}
+  // (null disables it); `opts.routeCadence` replaces routeCadenceSpawn.
+  const routeCadence = typeof opts.routeCadence === "function" ? opts.routeCadence : routeCadenceSpawn;
+  let cohortClientsMemo = opts.cohort;
+  function cohortClients() {
+    if (cohortClientsMemo === undefined) {
+      try { cohortClientsMemo = seatCohortClients({ agentRoot }); } catch { cohortClientsMemo = null; }
+    }
+    return cohortClientsMemo;
+  }
+
+  /**
+   * May this cadence's sub-session start on cohort-llm? Not cohort-routed →
+   * yes. Cohort-routed → a cohort hold or the quota endpoint decides. Human-lane
+   * cadences are NOT exempt: a refused seat would 429 them too.
+   *
+   * The resolved target rides out on the result (`target`) and is handed to
+   * the spawn, so the session that starts is the one that was gated — never a
+   * second routing decision that could differ (a band change in between).
+   *
+   * Failure: if ROUTING throws, the tick runs unrouted (`target: null` — the
+   * stock session, which no cohort quota governs), loudly. If ADMISSION throws
+   * for a cohort-routed target, the tick is deferred for a short retry — it is
+   * never spawned into a gateway that may 429/402 it.
+   */
+  const COHORT_GATE_ERROR_RETRY_MS = 30_000;
+  // The seat's engine (config/agent.json runtime.engine). A seat on engine
+  // cohort is cohort-metered whatever routing picks, so it is always gated.
+  const seatEngine = typeof opts.seatEngine === "function" ? opts.seatEngine : () => readSeatEngine(agentRoot);
+  async function cohortGate(cadence) {
+    // W4-E1: the engine is resolved once per tick and rides the result to the spawn.
+    const engine = seatEngine();
+    let target;
+    try {
+      target = routeCadence(agentRoot, cadence);
+    } catch (err) {
+      log({ level: "error", stage: "cohort_gate_route_failed_unrouted", cadence, engine, error: err && err.message });
+      // Unrouted on the claude engine is the stock session no cohort quota
+      // governs; on engine cohort the session is still cohort-metered.
+      if (engine !== "cohort") return { ok: true, cohort: false, target: null, engine };
+      target = null;
+    }
+    if (!isCohortRouted({ engine, target })) return { ok: true, cohort: false, target: target || null, engine };
+    try {
+      const c = cohortClients();
+      const adm = await admitSpawn({ engine, target }, { quota: c && c.quota, token: c && c.token, rateGuard, rateGuardDeps: { agentRoot }, now: nowMs });
+      return { ...adm, target, engine };
+    } catch (err) {
+      log({ level: "error", stage: "cohort_gate_failed_closed", cadence, error: err && err.message });
+      const until = nowMs() + COHORT_GATE_ERROR_RETRY_MS;
+      return {
+        ok: false, cohort: true, target, engine,
+        deferral: { kind: "retry", until, code: "cohort_gate_error", message: `cohort-llm admission failed: ${err && err.message}`, refusal: null },
+      };
+    }
+  }
   const frontDoorStateImpl = typeof opts.frontDoorState === "function"
     ? opts.frontDoorState
     : () => readFrontDoorState(agentRoot, { now: nowMs() });
@@ -985,6 +1084,29 @@ export function startConsumer(opts = {}) {
       if (!gov.admit) return deferTick(event, gov.reason);
     }
 
+    // cohort-llm quota gate: a tick whose sub-session cohort-llm would refuse is
+    // requeued, not spawned — and never failTick'd (a spent window is an
+    // upstream gate, not a broken cadence). The refusal is recorded as a cohort
+    // hold, so the requeued tick is gated again without another quota read.
+    let gatedTarget;
+    let gatedEngine;
+    let gatedToken = null;
+    let gatedBaseUrl = null;
+    {
+      const cg = await cohortGate(event.cadence);
+      gatedTarget = cg.target;
+      gatedEngine = cg.engine;
+      gatedToken = cg.token || null;
+      if (gatedEngine === "cohort") { try { gatedBaseUrl = cohortClients()?.token?.baseUrl || null; } catch { gatedBaseUrl = null; } }
+      if (!cg.ok) {
+        const d = cg.deferral || {};
+        return deferTick(event, `cohort:${d.code || d.kind || "refused"}`, {
+          cohort_kind: d.kind || null,
+          until: Number.isFinite(d.until) ? new Date(d.until).toISOString() : null,
+        });
+      }
+    }
+
     const def = getCadenceDef(event.cadence);
     let promptPath = def?.prompt;
     if (!promptPath) {
@@ -1069,6 +1191,12 @@ export function startConsumer(opts = {}) {
         promptPath,
         timeoutMs: maxSpawnMs,
         log,
+        // The target the cohort gate admitted (null = run unrouted). Never re-resolved.
+        target: gatedTarget,
+        // W4-E1: the engine the gate resolved, and the seat token it admitted with.
+        engine: gatedEngine,
+        cohortToken: gatedToken,
+        cohortBaseUrl: gatedBaseUrl,
       });
     } finally {
       activeSubSessions -= 1;
@@ -1087,8 +1215,9 @@ export function startConsumer(opts = {}) {
         stderr_path: result.stderr_path || null,
       });
       recordSubsessionSuccess(event.cadence);
-      // WS4: a clean sub-session closes the shared 429 breaker.
-      try { rateGuard.recordSuccess(RATE_PROVIDER, { agentRoot }); } catch { /* */ }
+      // WS4: a clean sub-session closes the shared 429 breaker (the cohort hold
+      // for a cohort-served run — never the Anthropic breaker on its behalf).
+      try { rateGuard.recordSuccess(result.cohort_routed || seatEngine() === "cohort" ? rateGuardModule.COHORT_BACKEND : RATE_PROVIDER, { agentRoot }); } catch { /* */ }
       stats.escalated += 1;
       stats.last_decision = "escalated";
       return { ok: true, decision: "escalated", exit_code: result.exit_code };
@@ -1099,10 +1228,31 @@ export function startConsumer(opts = {}) {
     // instead of failTick — a 429 is an upstream gate, not a per-event failure,
     // so it must not burn this cadence's retry budget toward the DLQ.
     const cadenceOut = result.stderr_tail || result.error || result.stdout_tail || "";
-    const cadenceUl = rateGuard.classifyUsageLimit?.(cadenceOut, { agentRoot }) ?? { isLimit: false, resetAt: null };
+    // A seat on engine cohort is cohort-served whatever routing picked (the gate's own test).
+    const engineCohort = seatEngine() === "cohort";
+    const cohortServed = Boolean(result.cohort_routed) || engineCohort;
+    const breakerProvider = cohortServed ? rateGuardModule.COHORT_BACKEND : RATE_PROVIDER;
+    // A cohort-llm refusal first: keyed by the "cohort" backend, held until its
+    // resetsAt, never an Anthropic breaker, never a failed attempt. Both streams:
+    // an engine's JSON result is on stdout even when stderr carries text.
+    const refusalText = [result.stderr_tail, result.error, result.stdout_tail].filter(Boolean).join("\n");
+    const cohortRefusal = cohortServed ? (rateGuard.classifyCohortRefusal?.(refusalText) ?? null) : null;
+    if (cohortRefusal) {
+      try {
+        const rec = rateGuard.recordCohortRefusal(cohortRefusal, { agentRoot });
+        log({ level: "warn", stage: "subsession_cohort_refused", id: event.id, cadence: event.cadence, code: cohortRefusal.code, disposition: rec.disposition && rec.disposition.kind, open_until: rec.openUntil });
+      } catch { /* */ }
+      try { const c = cohortClients(); if (c && c.quota && typeof c.quota.invalidate === "function") c.quota.invalidate(); } catch { /* */ }
+      return deferTick(event, `cohort-refused:${cohortRefusal.code}`);
+    }
+    // An engine-cohort lane has no Claude subscription: its English limit text is
+    // never a subscription usage limit (logged; the run fails or backs off below).
+    const cadenceUlText = rateGuard.classifyUsageLimit?.(cadenceOut, { agentRoot }) ?? { isLimit: false, resetAt: null };
+    const cadenceUl = engineCohort ? { isLimit: false, resetAt: null } : cadenceUlText;
+    if (engineCohort && cadenceUlText.isLimit) log({ level: "warn", stage: "subsession_usage_limit_text_ignored", id: event.id, cadence: event.cadence, engine: "cohort" });
     if (cadenceUl.isLimit) {
       try {
-        const rec = rateGuard.recordUsageLimit(RATE_PROVIDER, cadenceUl.resetAt, { agentRoot });
+        const rec = rateGuard.recordUsageLimit(breakerProvider, cadenceUl.resetAt, { agentRoot });
         log({ level: "warn", stage: "subsession_usage_limited", id: event.id, cadence: event.cadence, open_until: rec.openUntil, reset_at: rec.resetAt });
       } catch { /* */ }
       // Same handling as a 429: a window-usage limit is a shared, provider-side
@@ -1113,7 +1263,7 @@ export function startConsumer(opts = {}) {
     }
     if (rateGuard.classifyStderr(cadenceOut)) {
       try {
-        const rec = rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot });
+        const rec = rateGuard.recordRateLimit(breakerProvider, { agentRoot });
         log({ level: "warn", stage: "subsession_rate_limited", id: event.id, cadence: event.cadence, open_until: rec.openUntil });
       } catch { /* */ }
       // L2: a 429 is a SHARED, provider-side rate-limit signal — the shared

package/scripts/daemon/cadence-handlers.mjs

@@ -500,7 +500,65 @@ async function handleNightlyBackup({ event, agentRoot, log }, opts = {}) {
  * (`flagged`) logs a warning. The result (drift %) goes in the inline result.
  * The lib fn is injectable via `opts.reconcileImpl` for tests.
  */
+/**
+ * Regenerate state/dashboards/cost-summary.yaml from the local cost ledger.
+ *
+ * WHY THIS IS SPAWNED AND NOT IMPORTED: scripts/cost/track-claude-usage.mjs has
+ * no import.meta.main guard — it dispatches on process.argv at module scope, so
+ * importing it from the daemon would run the CLI's usage branch and
+ * process.exit(2) the daemon itself. A child process is the only safe call.
+ *
+ * Fail-soft by construction: this is a dashboard refresh, not the reconcile, so
+ * it must never turn a good reconcile into ok:false. Errors are RETURNED as a
+ * named reason, never thrown and never swallowed into silence.
+ *
+ * Injectable via `opts.summariseImpl` for tests (no child process).
+ */
+async function runCostSummarise({ agentRoot, days = 7 }, opts = {}) {
+  try {
+    const runner =
+      opts.summariseImpl ||
+      (async () => {
+        const { execFile } = await import("node:child_process");
+        const script = join(agentRoot, "scripts", "cost", "track-claude-usage.mjs");
+        const fallback = join(__dirname, "..", "cost", "track-claude-usage.mjs");
+        const target = existsSync(script) ? script : fallback;
+        if (!existsSync(target)) return { code: 127, stderr: "tracker-not-found" };
+        return new Promise((resolvePromise) => {
+          execFile(
+            process.execPath,
+            [target, "summarise", "--days", String(days)],
+            { timeout: 2 * 60 * 1000, maxBuffer: 8 * 1024 * 1024, env: { ...process.env, AGENT_ROOT: agentRoot } },
+            (err, stdout, stderr) => {
+              resolvePromise({
+                code: err ? (typeof err.code === "number" ? err.code : 1) : 0,
+                stdout: String(stdout || ""),
+                stderr: String(stderr || ""),
+              });
+            }
+          );
+        });
+      });
+    const res = await runner({ agentRoot, days });
+    if (!res || res.code !== 0) {
+      return { ok: false, reason: (res && String(res.stderr || "").trim().slice(0, 200)) || `exit ${res && res.code}` };
+    }
+    return { ok: true, reason: null };
+  } catch (err) {
+    return { ok: false, reason: err && err.message ? err.message : String(err) };
+  }
+}
+
 async function handleNightlyCostReconcile({ event, agentRoot, log }, opts = {}) {
+  // Refresh the cost dashboard FIRST. cost-summary.yaml is written by nothing
+  // else in production — `summarise` had no caller at all, so the file sat at a
+  // zeroed scaffold while real ledger rows accumulated beside it. Running it
+  // ahead of the reconcile means a reconcile failure cannot also cost the
+  // refresh, and its own failure is reported, never thrown.
+  const summarised = await runCostSummarise({ agentRoot }, opts);
+  if (!summarised.ok && typeof log === "function") {
+    log("warn", `[nightly-cost-reconcile] cost-summary regeneration failed: ${summarised.reason}`);
+  }
   try {
     const reconcile =
       opts.reconcileImpl ||
@@ -514,6 +572,8 @@ async function handleNightlyCostReconcile({ event, agentRoot, log }, opts = {})
       ok: true,
       decision: "inline",
       cadence: event.cadence,
+      costSummaryRegenerated: summarised.ok,
+      costSummaryError: summarised.reason,
       day: res?.day ?? null,
       driftPct: res?.driftPct ?? null,
       flagged: !!(res && res.flagged),
@@ -521,7 +581,7 @@ async function handleNightlyCostReconcile({ event, agentRoot, log }, opts = {})
       providerUSD: res?.providerUSD ?? null,
     };
   } catch (err) {
-    return { ok: false, decision: "inline", cadence: event.cadence, error: err && err.message ? err.message : String(err) };
+    return { ok: false, decision: "inline", cadence: event.cadence, costSummaryRegenerated: summarised.ok, costSummaryError: summarised.reason, error: err && err.message ? err.message : String(err) };
   }
 }
 
@@ -588,7 +648,8 @@ async function handleOrgCostSync({ event, agentRoot }, opts = {}) {
 
 /**
  * monitoring-alerts (inline): gather the diagnostics counters, today's cost
- * ledger, peer presence, daemon health + backup freshness, evaluate the
+ * ledger, peer presence, daemon health + yesterday's cadence output artefacts,
+ * evaluate the
  * behavioral alert rules, and emit any firing alerts to the configured webhook
  * (config/alerts.yaml `alerts.webhook`) — else log them. Deterministic, no LLM.
  * Fail-open + fully injectable for tests. This is what makes lib/diagnostics/
@@ -609,8 +670,16 @@ async function handleMonitoringAlerts({ event, agentRoot, log }, opts = {}) {
     const health = opts.health !== undefined ? opts.health : recoverStaleClaims && readDaemonHealth(agentRoot);
     const cfg = opts.cfg !== undefined ? opts.cfg : loadAgentCfg(agentRoot);
     const now = opts.now || Date.now();
+    // Read yesterday's cadence OUTPUT artefacts off disk. This is the only input
+    // here that is not derived from the cadence bus, and it is deliberately so:
+    // the bus logged a timed-out evening wrap as stage="processed" on 29 Aug 2026,
+    // so no rule keyed on the bus's own decision can see that class of miss.
+    const outputs = opts.outputs !== undefined
+      ? opts.outputs
+      : (await import("../../lib/diagnostics/cadence-output-freshness.mjs"))
+          .cadenceOutputFreshness({ agentRoot, now });
 
-    const alerts = A.evaluateAlerts({ snapshot, ledger, presence, health, thresholds: opts.thresholds, now }) || [];
+    const alerts = A.evaluateAlerts({ snapshot, ledger, presence, health, outputs, thresholds: opts.thresholds, now }) || [];
 
     const sinkUrl = cfg && cfg.alerts && cfg.alerts.webhook;
     const sink = opts.sink || (async (alert) => {
@@ -622,7 +691,7 @@ async function handleMonitoringAlerts({ event, agentRoot, log }, opts = {}) {
       }
     });
     const res = alerts.length ? await A.emitAlerts(alerts, { sink }) : { attempted: 0, delivered: 0, failed: 0 };
-    return { ok: true, decision: "inline", cadence: event.cadence, alerts: alerts.length, delivered: res.delivered ?? 0, severities: alerts.map((a) => a.severity) };
+    return { ok: true, decision: "inline", cadence: event.cadence, alerts: alerts.length, delivered: res.delivered ?? 0, severities: alerts.map((a) => a.severity), outputsChecked: outputs?.checked ?? 0, outputsMissing: outputs?.missing?.length ?? 0 };
   } catch (err) {
     return { ok: false, decision: "inline", cadence: event.cadence, error: err && err.message ? err.message : String(err) };
   }