@cohortapp/agent-sdk 2.18.12 → 2.18.14

package/lib/engine/agents/usage.mjs

@@ -17,6 +17,7 @@
  */
 
 import { addUsage, emptyUsage, toResultUsage } from "../wire/usage.mjs";
+import { combineStated } from "../wire/errors.mjs";
 
 /**
  * @typedef {Object} UsageRecord
@@ -24,6 +25,10 @@ import { addUsage, emptyUsage, toResultUsage } from "../wire/usage.mjs";
  * @property {import('../wire/usage.mjs').NormalisedUsage} usage
  * @property {string|null} costMicros   null = unknown (may have been billed with no figure)
  * @property {string[]} requestIds
+ * @property {'off'|'shadow'|'on'|'unknown'|'mixed'|null} [enforcement]
+ *   W16. What the gateway said ABOUT `costMicros` — only "on" means money moved.
+ * @property {string|null} [shadowCostMicros]  what enforcement WOULD have charged; never spend
+ * @property {'ledger'|'unreadable'|'not_read'|'not_admitted'|'unknown'|'mixed'|null} [quotaSource]
  */
 
 /**
@@ -40,6 +45,13 @@ export function recordFromOutcome(outcome, fallbackTier) {
     usage: outcome.usage ?? emptyUsage("estimated"),
     costMicros: outcome.costMicros != null ? outcome.costMicros : exact ? "0" : null,
     requestIds: [...(outcome.requestIds ?? [])],
+    // W16. The qualifiers travel WITH the figure they qualify. A child's cost is
+    // summed into the parent's `costMicros`, so a child's `enforcement` must
+    // reach the same sum — otherwise the parent reports "on" beside a total that
+    // includes a child's shadow figure, which is the misread one layer up.
+    enforcement: outcome.enforcement ?? null,
+    shadowCostMicros: outcome.shadowCostMicros ?? null,
+    quotaSource: outcome.quotaSource ?? null,
   };
 }
 
@@ -53,8 +65,34 @@ function sumMicros(parts) {
   return total.toString();
 }
 
+/**
+ * Sum the `shadow_cost_micros` figures that were reported, or null when none
+ * was. Unlike `costMicros` a missing counterfactual does not null the sum: it is
+ * not a charge, so a partial one is still worth reporting.
+ * @param {Array<string|null|undefined>} parts
+ */
+function sumShadowMicros(parts) {
+  let total = 0n;
+  let seen = false;
+  for (const p of parts) {
+    if (p == null) continue;
+    try {
+      total += BigInt(p);
+      seen = true;
+    } catch {
+      /* an unparseable counterfactual is simply not recorded */
+    }
+  }
+  return seen ? total.toString() : null;
+}
+
 /**
  * Combine the parent's record with its children's.
+ *
+ * W16: `enforcement` and `quotaSource` fold across parent AND children exactly
+ * as `costMicros` sums across them, so the qualifier and the figure it qualifies
+ * always describe the same scope. A parent served under `on` whose subagent was
+ * served under `shadow` reports `"mixed"`, never `"on"`.
  * @param {UsageRecord} parent @param {UsageRecord[]} children
  */
 export function aggregateUsage(parent, children) {
@@ -91,5 +129,12 @@ export function aggregateUsage(parent, children) {
     requestIds: all.flatMap((r) => r.requestIds),
     modelUsage,
     cohortModelUsage: { byTier, total: { usage, costMicros } },
+    // The run-wide qualifiers for the run-wide `costMicros` above.
+    // `combineStated`, not `foldEnforcement`: each record's value is ALREADY
+    // folded, so it may be this client's own "mixed" — a word the gateway never
+    // sends and the raw reader would flatten to "unknown".
+    enforcement: all.reduce((m, r) => combineStated(m, r.enforcement), /** @type {any} */ (null)),
+    quotaSource: all.reduce((q, r) => combineStated(q, r.quotaSource), /** @type {any} */ (null)),
+    shadowCostMicros: sumShadowMicros(all.map((r) => r.shadowCostMicros)),
   };
 }

package/lib/engine/budget.mjs

@@ -53,12 +53,112 @@
  * guess wearing a measurement's clothes — the exact failure CF-157 is about.
  * `spent` therefore stays at the gateway's own figures, and only those.
  *
+ * ## W16 — a figure the gateway reports is not the same as money that moved
+ *
+ * The gateway now states which billing mode produced each figure
+ * (`enforcement`, design §4.8, hq a60b9595). Under `shadow` a PRICED request
+ * settles for real and reports a real `cost_micros` while **no money moves**:
+ * a shadow request the ledger would have refused is admitted on an unfunded
+ * hold, served, and its settle posts an empty transaction. This meter used to
+ * add that figure to `spent` and enforce a cap against it — counting spend that
+ * never happened, against a cap that cannot fire. That is CF-157's own misread,
+ * surviving on the client after the server side was fixed.
+ *
+ * So a figure only becomes `spent` when the endpoint says `enforcement: "on"`.
+ * A figure reported under `shadow` or `off` is kept — as `unenforcedCostMicros`
+ * and `unenforcedRequests`, under names that cannot be read as spend — and adds
+ * a fourth cost-visibility state:
+ *
+ *   unenforced  figures arrived, and the endpoint states none of them is money.
+ *               THE CAP CANNOT BIND — for a different reason than `blind`: not
+ *               "we were not told the price" but "the price is not charged".
+ *
+ * `bindable()` is false for `unenforced` exactly as for `blind`, and `notice()`
+ * says which. Neither is reported as "$0 spent" alone: "nothing was spent" and
+ * "spending is not being enforced" are different statements.
+ *
+ * **When the endpoint states no mode at all, a figure IS counted as spend** —
+ * the pre-W16 behaviour. The choice is deliberate and it is the one asymmetry
+ * worth stating: over-counting produces a LOUD failure (the run stops and says
+ * the cap was reached, which an operator sees immediately), while under-counting
+ * produces the SILENT one (a cap that never fires, which is CF-157 itself).
+ * A never-seen `enforcement` word is therefore read as unknown, never as "on"
+ * — `snapshot().enforcement` reports `"unknown"` for it and `null` for silence
+ * — but unknown and silent both leave the cap armed. Only a stated `shadow` or
+ * `off` withholds a figure from spend.
+ *
+ * **…with one exception: silence AFTER the endpoint has named a mode inherits
+ * it.** A run talks to one `--base-url`, and a gateway's billing mode does not
+ * change without a deploy, so once this run has heard `shadow` from that
+ * endpoint, `shadow` is far better evidence about a later frameless request from
+ * it than the absence of a field is. Without this, a billed request whose frame
+ * never arrived — a stream that died after the headers, and every `searchWeb`
+ * refusal path, which has only headers to read — put a shadow figure straight
+ * into `spent`. The inheritance costs nothing against the cases the asymmetry
+ * above protects: a non-Cohort endpoint, a dropped-frame proxy and a gateway
+ * older than a60b9595 never name a mode at all, so they never inherit one.
+ * `snapshot().enforcement` still reports only what was STATED; the inherited
+ * decisions are counted separately as `inheritedModeRequests`.
+ *
+ * ## W16 — an empty quota is three different answers
+ *
+ * `quota_source` splits what an empty `quota` object used to collapse: the
+ * ledger answered and the seat has no included allowance (`ledger`), the read
+ * threw (`unreadable`), or nothing was read (`not_read`; `not_admitted` is
+ * "unknown"). A governor cannot tell "you have no allowance" from "we could not
+ * look", and those call for opposite behaviour. The meter records what was
+ * stated and `quotaNotice()` says it once per run, so an operator reading
+ * stderr learns which it was.
+ *
  * Pure apart from its own counters; no I/O.
  *
  * @module lib/engine/budget
  */
 
 import { addUsage, emptyUsage, readFrameUsage, totalTokens } from "./wire/usage.mjs";
+import { foldEnforcement, foldQuotaSource, readEnforcement } from "./wire/errors.mjs";
+
+/**
+ * The one-line answer to "what did an EMPTY quota mean?", or null when there is
+ * nothing to say. PURE and total.
+ *
+ * It lives outside {@link createBudgetMeter} because the meter only exists when
+ * `--max-budget-usd` was passed, and the operator who most needs this line — no
+ * cap, nothing pacing — is precisely the one who did not pass it. The meter's
+ * {@link createBudgetMeter} `quotaNotice` is the same text with a once-per-run
+ * latch; `cli.mjs` calls this directly so an unbudgeted run says it too.
+ *
+ * Silent when the quota actually answered (windows, credits or funding — there
+ * is then nothing ambiguous to explain) and silent when the endpoint stated no
+ * source at all (nothing new to say). Otherwise it names which of the three
+ * answers `{}` was, because "you have no allowance" and "we could not look" call
+ * for opposite behaviour from anything pacing against it.
+ *
+ * @param {'ledger'|'unreadable'|'not_read'|'not_admitted'|'unknown'|'mixed'|null|undefined} quotaSource
+ * @param {boolean} quotaAnswered
+ * @returns {string|null}
+ */
+export function quotaSourceNotice(quotaSource, quotaAnswered) {
+  if (quotaAnswered || quotaSource == null) return null;
+  const head = `cohort quota: this run saw no quota windows, and the endpoint states quota_source "${quotaSource}" — `;
+  if (quotaSource === "ledger") {
+    return (
+      head +
+      `the ledger ANSWERED: this seat has no included allowance (a money-only band reports no windows by design). ` +
+      `Nothing is wrong, and there is no window to pace against.`
+    );
+  }
+  if (quotaSource === "unreadable") {
+    return (
+      head +
+      `the quota read FAILED. The empty quota is a failed read, NOT "no allowance": do not read it as headroom.`
+    );
+  }
+  return (
+    head +
+    `no quota was read for this seat, so the empty quota states nothing about its allowance either way — read it as unknown.`
+  );
+}
 
 /**
  * `--max-budget-usd` as integer micro-USD, or an error. PURE.
@@ -83,20 +183,56 @@ export function microsToUsdNumber(micros) {
  * @param {{maxMicros:bigint}} o
  */
 export function createBudgetMeter({ maxMicros }) {
+  /** Money that MOVED, by the gateway's own figures under `enforcement: "on"`. */
   let spent = 0n;
+  /** Retail figures the endpoint reported while stating it enforces nothing. NEVER spend. */
+  let unenforcedCost = 0n;
+  /** `shadow_cost_micros`: what enforcement WOULD have charged. NEVER spend. */
+  let shadowCost = 0n;
+  let shadowCostSeen = false;
   let unknownCost = false;
   let requests = 0;
-  /** Billed requests that carried a cost figure. */
+  /** Billed requests whose figure counted toward the cap. */
   let priced = 0;
-  /** Billed requests that carried NO cost figure — the shadow-mode signature. */
+  /** Billed requests that carried NO cost figure — the shadow-with-no-price-book signature. */
   let unpriced = 0;
+  /** Billed requests that carried a figure the endpoint says is not money. */
+  let unenforced = 0;
+  /** The billing mode(s) the endpoint stated: a mode, 'unknown', 'mixed', or null for silence. */
+  let mode = /** @type {ReturnType<typeof foldEnforcement>} */ (null);
+  /**
+   * The last mode the endpoint actually NAMED (one of the three §4.8 words), or
+   * null before it named any. A later request that names none inherits this —
+   * see the module header. An unrecognised word does not replace it: it is not
+   * evidence about enforcement either way, and discarding a mode the endpoint
+   * did state would only make the seat count more shadow figures as spend.
+   */
+  let lastStatedMode = /** @type {'off'|'shadow'|'on'|null} */ (null);
+  /** Requests whose billing mode was inherited from an earlier statement, not stated on the request itself. */
+  let inheritedMode = 0;
+  /** The quota source(s) stated, folded the same way. */
+  let quotaSource = /** @type {ReturnType<typeof foldQuotaSource>} */ (null);
+  /** True once any request's quota object actually said something. */
+  let quotaAnswered = false;
   /** Exact token counts off the terminal frame (CF-158). Never priced. */
   let tokens = emptyUsage("provider");
   let tokenRequests = 0;
   let noticed = false;
+  let quotaNoticed = false;
 
-  /** @returns {'exact'|'partial'|'blind'} */
-  const visibility = () => (unpriced === 0 ? "exact" : priced === 0 ? "blind" : "partial");
+  /** @returns {'exact'|'partial'|'blind'|'unenforced'} */
+  const visibility = () => {
+    // A figure that counted is the only thing that can make a cap bind.
+    if (priced > 0) return unpriced === 0 && unenforced === 0 ? "exact" : "partial";
+    // Figures arrived, and the endpoint says none of them is money.
+    if (unenforced > 0) return "unenforced";
+    // Nothing recorded yet reads as `exact`: nothing has contradicted the cap.
+    return unpriced === 0 ? "exact" : "blind";
+  };
+  const bindable = () => {
+    const v = visibility();
+    return v !== "blind" && v !== "unenforced";
+  };
 
   return {
     maxMicros,
@@ -111,11 +247,46 @@ export function createBudgetMeter({ maxMicros }) {
         tokens = addUsage(tokens, u);
         tokenRequests++;
       }
+      // W16. Re-read through the wire's own total parsers rather than trusting
+      // the field: `record` is also handed results built by call sites that
+      // never went through `mergeCohort` (WebSearch, the fixtures), and an
+      // unrecognised word must land as unknown there too.
+      mode = foldEnforcement(mode, res.cohort?.enforcement);
+      quotaSource = foldQuotaSource(quotaSource, res.cohort?.quotaSource);
+      if (hasQuotaAnswer(res.cohort?.quota)) quotaAnswered = true;
+      const shadow = res.cohort?.shadowCostMicros;
+      if (shadow != null) {
+        try {
+          shadowCost += BigInt(shadow);
+          shadowCostSeen = true;
+        } catch {
+          /* an unparseable counterfactual is simply not recorded */
+        }
+      }
+      // Which mode governs THIS figure. A named mode governs itself; silence
+      // inherits the last mode this endpoint named, because within one run
+      // against one base URL the mode does not change without a deploy, and a
+      // frameless billed request (a stream that died after the headers, a
+      // search refusal) would otherwise put a shadow figure into spend. Silence
+      // before any statement, and an unrecognised word, leave the cap armed —
+      // see the module header for why that asymmetry is the safe one here.
+      const stated = readEnforcement(res.cohort?.enforcement);
+      if (stated) lastStatedMode = stated;
+      else if (res.cohort?.enforcement == null && lastStatedMode !== null) inheritedMode++;
+      const enforcing = stated ?? (res.cohort?.enforcement == null ? lastStatedMode : null);
+      const isMoney = enforcing !== "shadow" && enforcing !== "off";
       const c = res.cohort?.costMicros;
       if (c != null) {
         try {
-          spent += BigInt(c);
-          priced++;
+          const micros = BigInt(c);
+          if (isMoney) {
+            spent += micros;
+            priced++;
+          } else {
+            // Kept, and kept out of spend: no money moved for this figure.
+            unenforcedCost += micros;
+            unenforced++;
+          }
           return;
         } catch {
           /* an unparseable figure is an unknown one */
@@ -127,15 +298,20 @@ export function createBudgetMeter({ maxMicros }) {
         unpriced++;
       }
     },
-    // A blind meter never reaches the cap: spent stays 0 because no cost was
-    // ever reported. That is reported by bindable()/notice(), never papered
-    // over by treating an unreported cost as zero spend.
+    // A blind or unenforced meter never reaches the cap: spent stays 0 because
+    // no money figure was ever counted. That is reported by
+    // bindable()/notice(), never papered over by treating an unreported — or
+    // unenforced — cost as zero spend.
     exhausted: () => spent >= maxMicros,
     spentMicros: () => spent,
-    /** 'exact' | 'partial' | 'blind' — see the module header. */
+    /** 'exact' | 'partial' | 'blind' | 'unenforced' — see the module header. */
     costVisibility: visibility,
-    /** False when the gateway priced nothing, i.e. the cap cannot fire at all. */
-    bindable: () => visibility() !== "blind",
+    /** False when no figure could count toward the cap, i.e. it cannot fire at all. */
+    bindable,
+    /** The billing mode the endpoint stated, or 'unknown'/'mixed'/null. */
+    enforcement: () => mode,
+    /** The quota source the endpoint stated, or 'unknown'/'mixed'/null. */
+    quotaSource: () => quotaSource,
     /**
      * A one-time, run-level warning when the cap cannot bind, else null.
      * Self-clearing, so a caller may ask after every turn and the operator
@@ -143,35 +319,94 @@ export function createBudgetMeter({ maxMicros }) {
      * @returns {string|null}
      */
     notice() {
-      if (noticed || visibility() !== "blind") return null;
+      // A cap that cannot bind must say so — and so must a cap that binds on
+      // only PART of the run's figures. The second case is bindable, so it used
+      // to fall through this gate and say nothing at all: an operator saw a cap
+      // that looked armed against money that had not moved. That silence is the
+      // failure mode this lane exists to end, so `unenforced > 0` speaks too.
+      if (noticed || (bindable() && unenforced === 0)) return null;
       noticed = true;
       const observed =
         tokenRequests > 0
           ? `${totalTokens(tokens)} tokens over ${tokenRequests} request(s)`
           : "no token counts either";
-      return (
-        // State the observation; do NOT diagnose the cause. An absent
-        // cost_micros is all this meter can see, and --base-url is free-form:
-        // a non-Cohort Anthropic-compatible endpoint, a proxy that drops the
-        // header, or a gateway bug land here identically. Naming shadow
-        // billing as THE reason would be inferring a cause from an absence,
-        // which is the habit this lane exists to break.
-        `--max-budget-usd ($${microsToUsdNumber(maxMicros)}) is NOT being enforced: ` +
-        `the endpoint priced none of ${unpriced} billed request(s) (no cost_micros; shadow billing is the usual cause), ` +
-        `so the run reports $0 spent and the cap can never trigger. Measured instead: ${observed} ` +
+      const cap = `--max-budget-usd ($${microsToUsdNumber(maxMicros)}) is NOT being enforced: `;
+      const tail =
+        `Measured instead: ${observed} ` +
         `— tokens are exact, but this SDK has no per-tier price table and does not convert them to dollars. ` +
-        `See docs/engine/eval.md §3 (CF-157).`
+        `See docs/engine/eval.md §3 (CF-157).`;
+      if (priced > 0) {
+        // A MIXED run: some figures the endpoint says it charged for, some it
+        // says it did not. The cap IS armed — on the enforced subset only — so
+        // this does not claim it is unenforced; it names the split, because
+        // `spentMicros` here is not the whole of what the gateway reported.
+        return (
+          `--max-budget-usd ($${microsToUsdNumber(maxMicros)}) is being enforced on PART of this run only: ` +
+          `${priced} billed request(s) carried figures counted as spend, and ${unenforced} carried figures the ` +
+          `endpoint states are not money (enforcement "${mode}"; ${unenforcedCost.toString()} micro-USD reported, ` +
+          `deliberately kept out of spend), so the cap binds on a lower bound. ${tail}`
+        );
+      }
+      if (visibility() === "unenforced") {
+        // W16: the endpoint DID price these requests and says it charges
+        // nothing for them. Naming the mode here is not a diagnosis — it is
+        // quoting the field the gateway sent for exactly this purpose.
+        return (
+          cap +
+          `the endpoint priced ${unenforced} billed request(s) but states enforcement is "${mode}", so no money moved ` +
+          `for those figures (${unenforcedCost.toString()} micro-USD reported, deliberately kept out of spend) ` +
+          `and the cap can never trigger. ${tail}`
+        );
+      }
+      return (
+        // State the observation; do NOT diagnose the cause beyond what the
+        // endpoint itself stated. An absent cost_micros is all this meter can
+        // see, and --base-url is free-form: a non-Cohort Anthropic-compatible
+        // endpoint, a proxy that drops the header, or a gateway bug land here
+        // identically. Naming shadow billing as THE reason when the endpoint
+        // did not say so would be inferring a cause from an absence, which is
+        // the habit this lane exists to break.
+        cap +
+        `the endpoint priced none of ${unpriced} billed request(s) (no cost_micros; ` +
+        `${mode === null || mode === "unknown" ? "shadow billing is the usual cause" : `the endpoint states enforcement is "${mode}"`}), ` +
+        `so the run reports $0 spent and the cap can never trigger. ${tail}`
       );
     },
+    /**
+     * A one-time, run-level line naming what an EMPTY quota meant, else null.
+     * Self-clearing like {@link notice}.
+     *
+     * Silent when the gateway's quota actually answered (windows, credits or
+     * funding), and silent when no source was stated at all — there is then
+     * nothing new to say. Otherwise it distinguishes the three answers an empty
+     * `quota` used to collapse, because "you have no allowance" and "we could
+     * not look" call for opposite behaviour from anything pacing against it.
+     *
+     * The text is {@link quotaSourceNotice}, which is also what `cli.mjs` calls
+     * on an UNBUDGETED run — a meter-only line would never reach the operator
+     * who passed no cap, which is the common case. Two callers, one sentence, so
+     * they cannot drift; `cli.mjs` emits exactly one of them per run.
+     * @returns {string|null}
+     */
+    quotaNotice() {
+      if (quotaNoticed) return null;
+      const line = quotaSourceNotice(quotaSource, quotaAnswered);
+      if (line === null) return null;
+      quotaNoticed = true;
+      return line;
+    },
     /**
      * The `cohort.budget` block of a result.
      *
      * **`spentUsd` / `spentMicros` / `exhausted` are only meaningful when
      * `bindable` is true.** On a blind run they read `0` / `"0"` / `false`
-     * because the endpoint priced nothing — not because nothing was spent.
-     * Any consumer that shows or acts on the spend must read `bindable` (or
-     * `costVisibility`) in the same breath; `observedTokens` is the figure
-     * that is actually measured on such a run.
+     * because the endpoint priced nothing; on an `unenforced` one because the
+     * endpoint priced the requests and charges nothing for them. Neither means
+     * nothing was spent. Any consumer that shows or acts on the spend must read
+     * `bindable` (or `costVisibility`) in the same breath; `observedTokens` is
+     * the figure that is actually measured on such a run, and
+     * `unenforcedCostMicros` / `shadowCostMicros` are the money-shaped figures
+     * that were reported and are deliberately NOT spend.
      */
     snapshot: () => ({
       maxUsd: microsToUsdNumber(maxMicros),
@@ -182,13 +417,42 @@ export function createBudgetMeter({ maxMicros }) {
       unknownCost,
       requests,
       costVisibility: visibility(),
-      bindable: visibility() !== "blind",
+      bindable: bindable(),
       pricedRequests: priced,
       unpricedRequests: unpriced,
+      // Requests whose billing mode was not stated on the request itself and was
+      // inherited from an earlier statement by the same endpoint in this run.
+      inheritedModeRequests: inheritedMode,
+      // W16. The mode the endpoint stated for this run: a mode, "mixed" when it
+      // changed mid-run, "unknown" when it stated a word this client does not
+      // know, null when it stated none. A null does NOT mean "on" — it means
+      // the figures above were counted on the endpoint's silence.
+      enforcement: mode,
+      // Figures reported under a mode that moves no money. Named so they cannot
+      // be mistaken for spend, and left in micros for the same reason.
+      unenforcedRequests: unenforced,
+      unenforcedCostMicros: unenforcedCost.toString(),
+      // `shadow_cost_micros`: what enforcement WOULD have charged. null when the
+      // endpoint reported none, which is every request in production today.
+      shadowCostMicros: shadowCostSeen ? shadowCost.toString() : null,
+      // Why `quota` was empty, when it was. null = the endpoint did not say.
+      quotaSource,
+      quotaAnswered,
       // Exact token counts, or null when no frame reported any. Never dollars.
       observedTokens: tokenRequests > 0 ? { ...tokens, total: totalTokens(tokens) } : null,
     }),
   };
 }
 
+/**
+ * Did the gateway's quota object actually say something? PURE. Used only to
+ * decide whether `quota_source` has anything to explain — an answered quota
+ * needs no explanation.
+ * @param {any} q
+ */
+function hasQuotaAnswer(q) {
+  if (!q || typeof q !== "object") return false;
+  return Object.keys(q.windows || {}).length > 0 || q.creditsRemainingMicros != null || q.funding != null;
+}
+
 /** @typedef {ReturnType<typeof createBudgetMeter>} BudgetMeter */

package/lib/engine/cli.mjs

@@ -124,7 +124,7 @@ import { createPromptCacheKeyState, promptCacheKeyMode } from "./wire/prompt-cac
 // W4-A1: background-shell completion notices (CF-50); `cohort session` plugs in through `deps.host`.
 import { createNotificationQueue, shellExitNotice } from "./session-runtime/notifications.mjs";
 // W4-E1: --max-budget-usd.
-import { parseBudgetUsd, createBudgetMeter } from "./budget.mjs";
+import { parseBudgetUsd, createBudgetMeter, quotaSourceNotice } from "./budget.mjs";
 // W4-E2: slash commands and skills invoked from a prompt (rows 14, 34).
 import { discoverCommands, expandSlashCommand, resolveSlashCommand } from "./commands/index.mjs";
 import { resolveAgentModel } from "./agents/definitions.mjs";
@@ -171,7 +171,9 @@ Flags:
   --bare                       No user/project settings, hooks, instructions, skills, subagents or
                                project MCP; managed policy, --settings and --mcp-config still apply
   --max-budget-usd <usd>       Stop before the next model call once the run (subagents included) has
-                               spent this much, by the gateway's cost figures (error_max_budget_usd)
+                               spent this much, by the gateway's cost figures (error_max_budget_usd).
+                               Only counts figures the gateway says it CHARGED: under shadow billing
+                               the cap cannot bind, and stderr says so once per run
 
 Environment:
   COHORT_LLM_TOKEN             Gateway credential (this or COHORT_LLM_TOKEN_HELPER)
@@ -690,6 +692,10 @@ async function runCliBody(argv, deps, inputs) {
     const gatewayHeaders = { "x-cohort-surface": "engine", "x-cohort-session-id": session.id };
     // W4-E1 (row 24): one spend meter for the run, its subagents and its workflow children.
     const budget = o.maxBudgetMicros !== undefined ? createBudgetMeter({ maxMicros: o.maxBudgetMicros }) : null;
+    // W16: the quota discriminant is said once per RUN, not once per budgeted
+    // run — it rides the result, not the meter, so an operator who passed no cap
+    // still learns whether an empty quota was "no allowance" or a failed read.
+    let quotaNoticed = false;
     // CF-156: a stalled stream ends on its own silence budget and says why on
     // stderr. A stall or a mid-stream fault always reports — that is the
     // evidence W13 did not have — while a merely slow stream reports only
@@ -1071,9 +1077,36 @@ async function runCliBody(argv, deps, inputs) {
       history = outcome.messages;
 
       const children = agentRuntime.drainRecords();
-      const total = aggregateUsage({ tier: outcome.modelTier || model, usage: outcome.usage, costMicros: outcome.costMicros, requestIds: outcome.requestIds }, children);
+      // W16: the three billing qualifiers go in beside the parent's own cost, and
+      // come back folded across parent + children — so they describe the same
+      // scope as the `costMicros` they qualify. Without this the result said
+      // `enforcement: "on"` (the parent's) next to a total that included a
+      // child's shadow figure.
+      const total = aggregateUsage(
+        {
+          tier: outcome.modelTier || model,
+          usage: outcome.usage,
+          costMicros: outcome.costMicros,
+          requestIds: outcome.requestIds,
+          enforcement: outcome.enforcement,
+          shadowCostMicros: outcome.shadowCostMicros,
+          quotaSource: outcome.quotaSource,
+        },
+        children,
+      );
       const result = buildResult({
-        outcome: children.length > 0 ? { ...outcome, usage: total.usage, costMicros: total.costMicros, requestIds: total.requestIds } : outcome,
+        outcome:
+          children.length > 0
+            ? {
+                ...outcome,
+                usage: total.usage,
+                costMicros: total.costMicros,
+                requestIds: total.requestIds,
+                enforcement: total.enforcement,
+                shadowCostMicros: total.shadowCostMicros,
+                quotaSource: total.quotaSource,
+              }
+            : outcome,
         sessionId: session.id,
         durationMs: now() - turnStarted,
         wire,
@@ -1087,7 +1120,10 @@ async function runCliBody(argv, deps, inputs) {
       result.cohort.mcpServers = mcpServerStatuses();
       result.cohort.modelUsage = total.cohortModelUsage;
       result.cohort.todos = todoState.todos;
-      result.cohort.agents = children.map((c) => ({ agentId: c.agentId, agentType: c.agentType, tier: c.tier, costMicros: c.costMicros, background: c.background, numTurns: c.numTurns, stop: c.stop }));
+      // W16: `enforcement` rides each child's own `costMicros` for the same
+      // reason it rides the run's — a figure without its billing mode reads as
+      // money, and a child may have been served under a different mode.
+      result.cohort.agents = children.map((c) => ({ agentId: c.agentId, agentType: c.agentType, tier: c.tier, costMicros: c.costMicros, enforcement: c.enforcement ?? null, background: c.background, numTurns: c.numTurns, stop: c.stop }));
       // Context stats for the session so far; `compactions` are this turn's.
       const stats = manager.stats();
       result.cohort.context = { ...stats, compactions: stats.compactions.slice(compactionsBefore) };
@@ -1099,6 +1135,19 @@ async function runCliBody(argv, deps, inputs) {
         const budgetNotice = budget.notice();
         if (budgetNotice) warn(budgetNotice);
       }
+      // W16: and say ONCE which of the three answers an empty quota was — "no
+      // allowance" and "we could not look" call for opposite behaviour from
+      // anything pacing against it, and `{}` used to collapse both. Outside the
+      // `if (budget)` deliberately: the meter exists only under
+      // --max-budget-usd, and the seat with no cap needs this line just as much.
+      // `cohort.quota` is null unless a quota actually answered.
+      if (!quotaNoticed) {
+        const quotaNotice = quotaSourceNotice(result.cohort.quotaSource, result.cohort.quota != null);
+        if (quotaNotice) {
+          quotaNoticed = true;
+          warn(quotaNotice);
+        }
+      }
       if (slash.invoked) result.cohort.slashCommand = slash.invoked;
       appendResult(session, result, now);
       last = result;

package/lib/engine/loop.mjs

@@ -53,6 +53,7 @@ import { toolUses, messageText, stableStringify, userText } from "./messages.mjs
 import { validateInput, repairToolJson } from "./tools/schema.mjs";
 import { toolDefinitions } from "./tools/index.mjs";
 import { emptyUsage, addUsage, readFrameUsage } from "./wire/usage.mjs";
+import { foldEnforcement, foldQuotaSource } from "./wire/errors.mjs";
 
 /**
  * @typedef {{kind:'completed'} | {kind:'max_turns', maxTurns:number} | {kind:'wall_clock', wallClockMs:number}
@@ -247,6 +248,15 @@ async function runTurns(p, r) {
   const requestIds = [];
   let costTotal = 0n;
   let costComplete = true;
+  // W16 (hq a60b9595): what the terminal frame says ABOUT those cost figures.
+  // `enforcement` qualifies `costMicros` — only under "on" is it money that
+  // moved — `shadowCostTotal` is the counterfactual charge and is never spend,
+  // and `quotaSource` says why `quota` is empty when it is. All three stay null
+  // when the endpoint says nothing, so silence never reads as an answer.
+  let enforcement = null;
+  let quotaSource = null;
+  let shadowCostTotal = 0n;
+  let shadowCostSeen = false;
   let quota = null;
   let modelTier = null;
   let model = null;
@@ -300,6 +310,14 @@ async function runTurns(p, r) {
       // turn and costComplete true was never billed (agents/usage.mjs).
       costComplete,
       quota,
+      // W16. `costMicros` above is what the gateway REPORTED; `enforcement` is
+      // whether that figure is money that moved. A consumer that sums the one
+      // without reading the other repeats the defect this lane fixed in the
+      // budget meter. `shadowCostMicros` is the counterfactual charge (null in
+      // production today) and `quotaSource` is why `quota` is empty when it is.
+      enforcement,
+      quotaSource,
+      shadowCostMicros: shadowCostSeen ? shadowCostTotal.toString() : null,
       modelTier,
       model,
       apiMs,
@@ -331,6 +349,18 @@ async function runTurns(p, r) {
       // rather than adding zeros.
       const gu = readFrameUsage(res.cohort.usage);
       if (gu) gatewayUsage = addUsage(gatewayUsage ?? emptyUsage("provider"), gu);
+      // W16. Folded rather than last-write-wins so a run whose gateway changed
+      // mode mid-flight reports "mixed" instead of whichever frame came last.
+      enforcement = foldEnforcement(enforcement, res.cohort.enforcement);
+      quotaSource = foldQuotaSource(quotaSource, res.cohort.quotaSource);
+      if (res.cohort.shadowCostMicros != null) {
+        try {
+          shadowCostTotal += BigInt(res.cohort.shadowCostMicros);
+          shadowCostSeen = true;
+        } catch {
+          /* an unparseable counterfactual is simply not recorded */
+        }
+      }
     }
     if (!res.ok) {
       // A request that may have been billed has no cost figure, so the sum of