@cspeach/cli 1.1.3 → 1.1.4

package/dist/agent/loop.js

@@ -20,6 +20,7 @@ import { turnStatusEmitter } from '../ui/turn-status-emitter.js';
 import { buildRetryCapPausePayload, buildSkippedSiblingResults } from './retry-cap.js';
 import { appendCostLine, buildEntry as buildCostEntry } from '../cost/cost-log.js';
 import { computeSessionCost } from '../cost/session-cost.js';
+import { refreshCreditsAfterTurn, creditsForCostLog } from '../cost/credits-wire.js';
 import { globalStore } from '../ui/sap-state-store.js';
 import { lastAssistantIsAwaitingAnswer } from '../session/awaiting-answer.js';
 import { enrichUserMessage } from '../router/intent-extractor.js';
@@ -823,6 +824,11 @@ export async function runTurn(params) {
         // never crash a turn. Runs for both happy and interrupted paths so
         // the user's spend is recorded even when a turn dies mid-stream.
         {
+            // Credits (2026-09-16): sample the customer's balance BEFORE building
+            // the cost line so the JSONL records what the LEDGER charged alongside
+            // our COGS, and so the status footer the REPL prints next reads a fresh
+            // figure. No-op + no request outside credits mode; capped at 2.5 s.
+            await refreshCreditsAfterTurn();
             const turnTokens = {
                 input: (session.usage?.input_tokens ?? 0) - turnStartTokens.input,
                 output: (session.usage?.output_tokens ?? 0) - turnStartTokens.output,
@@ -838,6 +844,9 @@ export async function runTurn(params) {
                 model: params.modelOverride ?? session.model,
                 tokens: turnTokens,
                 duration_ms: turnDurationMs,
+                // Additive: present only in credits mode (undefined in USD mode, so
+                // the emitted line is byte-identical to a pre-credits one).
+                credits: creditsForCostLog(),
             });
             void appendCostLine(session.id, entry);
         }

package/dist/commands/config-set.js

@@ -15,6 +15,7 @@ const MUTABLE_KEYS = new Set([
     'classifier.safe_mode',
     'local_build',
     'local_files', // deprecated alias for local_build (2026-06-13) — still accepted
+    'show_cogs',
     'write_mode',
     'plan_mode',
     'plan_audit',
@@ -502,6 +503,20 @@ export async function runConfigSet(args) {
             console.log(chalk.dim('  → takes effect on the next `cspeach` launch.'));
             break;
         }
+        case 'show_cogs': {
+            // Operator escape hatch — render OUR Anthropic COGS in USD even on a
+            // managed, metered account (where the customer-facing unit is credits).
+            // Off/absent is the product default; see cost/display-mode.ts.
+            const b = coerceBool(value);
+            if (b === null) {
+                err(`${key} must be on/off (also accepts true/false, 1/0).`);
+            }
+            cfg.show_cogs = b;
+            console.log(chalk.dim(b
+                ? '  → cost figures will show USD (our Anthropic cost), not credits.'
+                : '  → cost figures will show credits on a managed, metered account.'));
+            break;
+        }
         case 'write_mode':
             if (!isValidWriteMode(value)) {
                 err(`Invalid value for write_mode. Must be one of: auto, approval-gated, advisory-only`);
@@ -632,6 +647,7 @@ export function validateValue(key, value) {
             return value === 'true' || value === 'false';
         case 'local_build':
         case 'local_files': // deprecated alias — same on/off coercion
+        case 'show_cogs':
             return coerceBool(value) !== null;
         case 'write_mode':
             return isValidWriteMode(value);

package/dist/commands/cost.js

@@ -11,7 +11,24 @@
 import chalk from 'chalk';
 import { readCostLog, summarise } from '../cost/cost-log.js';
 import { formatCost } from '../cost/pricing.js';
-export async function runCostCommand(sessionId) {
+import { creditsActive, formatCredits, globalCredits, CREDITS_PENDING, } from '../cost/credits.js';
+/**
+ * Sum the credits the proxy charged across the logged turns. Entries written
+ * before credits existed (or on turns whose balance fetch failed) carry no
+ * number — they are skipped, not counted as zero, and the caller says so.
+ */
+function summariseCredits(entries) {
+    let total = 0;
+    let unknown = 0;
+    for (const e of entries) {
+        if (typeof e.credits_charged === 'number')
+            total += e.credits_charged;
+        else
+            unknown++;
+    }
+    return { total, unknown };
+}
+export async function runCostCommand(sessionId, credits = globalCredits.snapshot()) {
     const entries = await readCostLog(sessionId);
     if (entries.length === 0) {
         console.log('');
@@ -20,9 +37,27 @@ export async function runCostCommand(sessionId) {
         return;
     }
     const s = summarise(entries);
+    // Credits mode: the customer is billed in credits at a multiplier we do not
+    // disclose, so NOTHING derived from cost/pricing.ts may be printed here —
+    // not the total, not the per-model split, not the per-turn figures. Tokens
+    // stay: they are a usage fact, not a COGS leak.
+    const inCredits = creditsActive();
+    const perTurn = summariseCredits(entries);
     // Header
     console.log('');
-    console.log(chalk.bold(`Session cost so far: ${formatCost(s.totalCost)}`) + chalk.dim(`   (${s.turns} turn${s.turns === 1 ? '' : 's'})`));
+    if (inCredits) {
+        const unit = credits?.unitLabel ?? 'credits';
+        // Prefer the live session tracker (balance deltas observed this run);
+        // fall back to the logged per-turn charges when it has nothing yet.
+        const total = credits && credits.sessionTotal > 0 ? credits.sessionTotal : perTurn.total;
+        console.log(chalk.bold(`Session usage so far: ${formatCredits(total, unit)}`) + chalk.dim(`   (${s.turns} turn${s.turns === 1 ? '' : 's'})`));
+        if (credits?.balance != null) {
+            console.log(chalk.dim(`Remaining balance: ${formatCredits(credits.balance, unit)}`));
+        }
+    }
+    else {
+        console.log(chalk.bold(`Session cost so far: ${formatCost(s.totalCost)}`) + chalk.dim(`   (${s.turns} turn${s.turns === 1 ? '' : 's'})`));
+    }
     // Token breakdown
     console.log('');
     console.log(chalk.dim('Tokens:'));
@@ -35,7 +70,10 @@ export async function runCostCommand(sessionId) {
         console.log('');
         console.log(chalk.dim('By model:'));
         for (const m of s.byModel) {
-            console.log(`  ${m.model.padEnd(24)} ${m.turns} turn${m.turns === 1 ? '' : 's'}   ${formatCost(m.cost)}`);
+            // Credits mode: turn counts only. A per-model dollar split is a direct
+            // read on our per-model COGS.
+            const tail = inCredits ? '' : `   ${formatCost(m.cost)}`;
+            console.log(`  ${m.model.padEnd(24)} ${m.turns} turn${m.turns === 1 ? '' : 's'}${tail}`);
         }
     }
     else if (s.byModel[0]) {
@@ -48,7 +86,21 @@ export async function runCostCommand(sessionId) {
     console.log(chalk.dim(`Recent turns (last ${recent.length}):`));
     for (const e of recent) {
         const tok = (e.tokens.input + e.tokens.output).toLocaleString();
-        console.log(`  turn ${String(e.turn).padStart(3)}   ${tok.padStart(10)} tok   ${formatCost(e.cost)}`);
+        // Credits mode: the per-turn figure is what the LEDGER charged (a balance
+        // delta recorded at turn end), never our computed USD. A turn whose
+        // balance sample failed shows the pending marker rather than a number we
+        // would have to invent.
+        const tail = inCredits
+            ? (typeof e.credits_charged === 'number'
+                ? formatCredits(e.credits_charged, credits?.unitLabel ?? 'credits')
+                : CREDITS_PENDING)
+            : formatCost(e.cost);
+        console.log(`  turn ${String(e.turn).padStart(3)}   ${tok.padStart(10)} tok   ${tail}`);
+    }
+    if (inCredits && perTurn.unknown > 0) {
+        console.log('');
+        console.log(chalk.dim(`${perTurn.unknown} turn${perTurn.unknown === 1 ? '' : 's'} had no balance reading — `
+            + `their usage is included in a later turn's figure.`));
     }
     console.log('');
     console.log(chalk.dim(`Detailed JSONL: ~/.cspeach/sessions/${sessionId}-cost.jsonl`));

package/dist/commands/export-audit.js

@@ -15,6 +15,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { buildAuditReport } from '../session/audit-export.js';
+import { globalCredits } from '../cost/credits.js';
 import { readCostLog } from '../cost/cost-log.js';
 /** Parse the text after `/export` into a subcommand + optional filename. */
 export function parseExportArgs(rest) {
@@ -30,7 +31,9 @@ export async function runExportAuditCommand(opts) {
     const { session, transport, emit } = opts;
     const cwd = opts.cwd ?? process.cwd();
     const costEntries = opts.costEntries ?? (await readCostLog(session.id));
-    const report = buildAuditReport({ session, costEntries, transport });
+    // The exported .md is a file the customer opens and forwards, so it carries
+    // their credits (not our COGS) whenever credits mode is active.
+    const report = buildAuditReport({ session, costEntries, transport, credits: globalCredits.snapshot() });
     const name = opts.filename && opts.filename.trim().length > 0
         ? opts.filename.trim()
         : defaultAuditFilename(session);

package/dist/commands/plan-chain.js

@@ -30,6 +30,7 @@ import { applyAuditResult, applyPhaseResolution, buildResumeCommand, offerNextPh
 import { appendCostLine, buildEntry } from '../cost/cost-log.js';
 import { startThinkingHeartbeat, AUDIT_HEARTBEAT_THRESHOLDS } from '../renderer/thinking-heartbeat.js';
 import { computeCost, formatCost } from '../cost/pricing.js';
+import { creditsActive } from '../cost/credits.js';
 /** Two consecutive failed verdicts on the same phase force status 'blocked'. */
 export const MAX_CONSECUTIVE_AUDIT_FAILURES = 2;
 /** Infra error strings are model/HTTP noise — clamp when rendering (Task 5 review). */
@@ -659,7 +660,13 @@ function renderAuditCost(args, cost) {
     try {
         const tok = cost.tokens.input + cost.tokens.output;
         const usd = computeCost(cost.model, cost.tokens);
-        args.log(chalk.dim(`[audit] ${tok.toLocaleString()} tok · ${formatCost(usd)} (${cost.model})`));
+        // Credits mode: the audit turn's USD is our COGS. There is no per-audit
+        // credit figure to substitute (the ledger charges the turn, not this
+        // sub-step), so the dim line drops the cost fragment and keeps tokens —
+        // never a dollar on a managed customer's screen.
+        args.log(chalk.dim(creditsActive()
+            ? `[audit] ${tok.toLocaleString()} tok (${cost.model})`
+            : `[audit] ${tok.toLocaleString()} tok · ${formatCost(usd)} (${cost.model})`));
         void appendCostLine(args.sessionId, {
             ...buildEntry({ turn: 0, model: cost.model, tokens: cost.tokens, duration_ms: cost.durationMs }),
             label: 'audit',

package/dist/config/loader.js

@@ -155,6 +155,11 @@ export async function loadConfig() {
             // standalone: whitelist-coerced profile table. An unrecognised platform
             // drops the whole table (undefined → key deleted below).
             standalone: sanitiseStandaloneProfile(parsed.standalone),
+            // show_cogs: plain boolean, DEFAULT off (absent). Preserve only a genuine
+            // boolean; a typo/wrong-type collapses to undefined, which reads as OFF —
+            // fail-safe in the customer's favour: a config typo can never leak our
+            // USD COGS onto a managed customer's screen.
+            show_cogs: typeof parsed.show_cogs === 'boolean' ? parsed.show_cogs : undefined,
             write_mode: isValidWriteMode(parsed.write_mode) ? parsed.write_mode : DEFAULT_CONFIG.write_mode,
             // plan_mode: whitelist coercion — anything but the two valid literals
             // (typos, wrong types) collapses to undefined, which callers treat as
@@ -232,6 +237,11 @@ export async function loadConfig() {
             delete merged.no_sap;
         if (merged.standalone === undefined)
             delete merged.standalone;
+        // Same for `show_cogs`: absent-or-invalid must not serialise as
+        // `show_cogs = undefined` — drop the key so `config show` stays clean and
+        // callers see a genuine "absent" shape (treated as OFF → credits).
+        if (merged.show_cogs === undefined)
+            delete merged.show_cogs;
         // Same for `plan_mode`: absent-or-invalid must not serialise as
         // `plan_mode = undefined` — drop the key so `config show` stays clean and
         // callers see a genuine "absent" shape (treated as 'step').

package/dist/cost/cost-log.js

@@ -27,7 +27,7 @@ export function costLogPath(sessionId) {
  * `appendCostLine` or accumulate in memory for the `/cost` command.
  */
 export function buildEntry(opts) {
-    return {
+    const entry = {
         ts: new Date().toISOString(),
         turn: opts.turn,
         model: opts.model,
@@ -35,6 +35,11 @@ export function buildEntry(opts) {
         cost: computeCost(opts.model, opts.tokens),
         duration_ms: opts.duration_ms,
     };
+    if (opts.credits) {
+        entry.credits_charged = opts.credits.charged;
+        entry.balance_credits = opts.credits.balance;
+    }
+    return entry;
 }
 /**
  * Append a single line to the session's cost log. Best-effort:

package/dist/cost/credits-wire.js

@@ -0,0 +1,101 @@
+/**
+ * The one place the credits meter is driven (2026-09-16).
+ *
+ * Two touch points, both best-effort and both no-ops outside credits mode:
+ *
+ *   initCredits()              — REPL / one-shot startup. ONE balance call,
+ *                                capped at BALANCE_TIMEOUT_MS. Resolves the
+ *                                display mode and seeds the tracker + store.
+ *   refreshCreditsAfterTurn()  — post-turn. One more capped call; the proxy
+ *                                commits a turn's charge BEFORE the SSE stream
+ *                                closes, so this sample already includes the
+ *                                turn that just ended.
+ *
+ * The post-turn refresh is awaited inside the agent loop's post-turn block
+ * rather than fired and forgotten, because two consumers need the fresh
+ * number synchronously: the JSONL cost line written moments later, and the
+ * post-turn status footer the REPL prints once runTurn returns. Awaiting a
+ * 2.5 s-capped call at the end of a multi-second turn is cheap; showing the
+ * previous turn's figure would be wrong.
+ *
+ * The cfg + bearer getter are captured at init so every later call site stays
+ * a one-liner and no module has to re-derive the display mode for itself.
+ */
+import { fetchBalance, globalCredits, setCostDisplayMode, creditsActive, } from './credits.js';
+import { costDisplayMode } from './display-mode.js';
+import { globalStore } from '../ui/sap-state-store.js';
+let wiredCfg = null;
+let wiredBearer = null;
+/** Mirror the tracker's state onto the Ink store so the chrome re-renders. */
+function publish() {
+    const s = globalCredits.snapshot();
+    globalStore.update({
+        creditsMode: creditsActive(),
+        creditsSessionTotal: s.sessionTotal,
+        creditsBalance: s.balance,
+        creditsUnitLabel: s.unitLabel,
+        creditsPending: s.pending,
+    });
+}
+/**
+ * Startup: resolve the display mode and seed the opening balance.
+ * Never throws; on any failure the process stays in USD mode, which is the
+ * pre-credits behaviour.
+ */
+export async function initCredits(cfg, getBearer) {
+    try {
+        // Non-managed modes can't be metered by us — skip the round-trip entirely.
+        if (cfg.llm?.mode !== 'managed') {
+            setCostDisplayMode('usd');
+            return;
+        }
+        const info = await fetchBalance(cfg, getBearer);
+        const mode = costDisplayMode(cfg, info);
+        setCostDisplayMode(mode);
+        if (mode !== 'credits')
+            return;
+        wiredCfg = cfg;
+        wiredBearer = getBearer;
+        globalCredits.start(info);
+        publish();
+    }
+    catch {
+        // Startup must never be blocked by the meter.
+        setCostDisplayMode('usd');
+    }
+}
+/**
+ * Post-turn: sample the balance again and fold the delta into the session
+ * total. Returns null (and makes no request) outside credits mode.
+ */
+export async function refreshCreditsAfterTurn() {
+    if (!creditsActive() || !wiredCfg || !wiredBearer)
+        return null;
+    try {
+        const info = await fetchBalance(wiredCfg, wiredBearer);
+        const r = globalCredits.afterTurn(info);
+        publish();
+        return r;
+    }
+    catch {
+        // Treat an unexpected throw exactly like a failed fetch: unknown, not zero.
+        const r = globalCredits.afterTurn(null);
+        publish();
+        return r;
+    }
+}
+/**
+ * The credits payload for a cost-log line, or undefined in USD mode so the
+ * emitted JSONL keeps its pre-credits shape byte for byte.
+ */
+export function creditsForCostLog() {
+    if (!creditsActive())
+        return undefined;
+    const s = globalCredits.snapshot();
+    return { charged: s.chargedThisTurn, balance: s.balance };
+}
+/** Test seam — drop the captured cfg/bearer between cases. */
+export function resetCreditsWire() {
+    wiredCfg = null;
+    wiredBearer = null;
+}

package/dist/cost/credits.js

@@ -0,0 +1,199 @@
+/**
+ * Customer-facing spend — credits, not dollars (2026-09-16).
+ *
+ * Every figure in `cost/pricing.ts` is OUR Anthropic COGS. A managed
+ * customer is billed in CREDITS at a multiplier we do not disclose, so
+ * showing them a `$` number is both wrong (it is not what they pay) and a
+ * business leak (it reveals our margin). This module is the customer-facing
+ * half of the split:
+ *
+ *   cost/pricing.ts   → USD, our cost, telemetry + BYOK/local/ai-hub display
+ *   cost/credits.ts   → credits, what the customer is actually charged
+ *
+ * The proxy is the only source of truth for credits. It commits a turn's
+ * charge BEFORE the SSE stream closes, so a balance fetched after the turn
+ * ends already reflects that turn — which is why the per-turn charge here is
+ * a BALANCE DELTA, not a locally computed number. We never price a turn in
+ * credits ourselves; we only observe what the ledger did.
+ *
+ * Everything in here is best-effort. A balance fetch that fails, times out,
+ * or returns garbage must never crash or block a turn — it degrades to
+ * "unknown", which the UI renders as `credits: updating…` (never a dollar
+ * fallback; see display-mode.ts).
+ */
+/** Hard cap on the balance round-trip — never block a turn on it. */
+export const BALANCE_TIMEOUT_MS = 2_500;
+const DEFAULT_UNIT_LABEL = 'credits';
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+/**
+ * Fetch the customer's credit balance from the proxy.
+ *
+ * Uses the same bearer key the CLI already sends on every other proxy call.
+ * NEVER throws and NEVER hangs past BALANCE_TIMEOUT_MS — returns null on any
+ * failure (transport error, non-2xx, timeout, unparseable body, no key).
+ */
+export async function fetchBalance(cfg, getBearer) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), BALANCE_TIMEOUT_MS);
+    try {
+        const key = await getBearer();
+        if (!key)
+            return null;
+        const url = `${cfg.proxy_url.replace(/\/$/, '')}/v1/me/balance`;
+        const r = await fetch(url, {
+            headers: { Authorization: `Bearer ${key}` },
+            signal: controller.signal,
+        });
+        if (!r.ok)
+            return null;
+        const body = await r.json();
+        if (typeof body !== 'object' || body === null)
+            return null;
+        const b = body;
+        const info = {
+            metered: b.metered === true,
+            unit_label: typeof b.unit_label === 'string' && b.unit_label ? b.unit_label : DEFAULT_UNIT_LABEL,
+            balance_credits: num(b.balance_credits),
+            subscription_credits: num(b.subscription_credits),
+            purchased_credits: num(b.purchased_credits),
+        };
+        if (b.unprovisioned === true)
+            info.unprovisioned = true;
+        return info;
+    }
+    catch {
+        // Timeout, offline, DNS, malformed JSON — all the same to the caller.
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * In-memory, session-scoped credit meter.
+ *
+ * Honest-arithmetic contract:
+ * - A turn's charge is `previousBalance − currentBalance`, clamped at ≥ 0
+ *   (a mid-session top-up must never subtract from the session total).
+ * - When a fetch fails we do NOT invent a charge and we do NOT move the
+ *   baseline. The turn is reported as `null` (unknown) and the spend it
+ *   incurred is folded into the next SUCCESSFUL fetch's delta — so the
+ *   session total stays correct even across missed samples.
+ * - With no baseline at all (session opened offline) the first successful
+ *   fetch only establishes the baseline; it cannot be a delta.
+ */
+export class CreditsTracker {
+    baseline = null;
+    state = {
+        chargedThisTurn: null,
+        sessionTotal: 0,
+        balance: null,
+        unitLabel: DEFAULT_UNIT_LABEL,
+        pending: false,
+    };
+    /** Seed the session's opening balance. */
+    start(balance) {
+        if (balance)
+            this.state.unitLabel = balance.unit_label;
+        const opening = balance ? balance.balance_credits : null;
+        this.baseline = opening;
+        this.state = {
+            ...this.state,
+            chargedThisTurn: null,
+            sessionTotal: 0,
+            balance: opening,
+            pending: false,
+        };
+    }
+    /** Record a post-turn balance sample and return this turn's charge. */
+    afterTurn(balance) {
+        if (balance)
+            this.state.unitLabel = balance.unit_label;
+        const current = balance ? balance.balance_credits : null;
+        if (current === null) {
+            // Unknown — keep the baseline so the next good sample covers both turns.
+            this.state = { ...this.state, chargedThisTurn: null, pending: true };
+            return { chargedThisTurn: null, sessionTotal: this.state.sessionTotal, balance: this.state.balance };
+        }
+        if (this.baseline === null) {
+            // First balance we have ever seen — establish the baseline only.
+            this.baseline = current;
+            this.state = { ...this.state, chargedThisTurn: null, balance: current, pending: false };
+            return { chargedThisTurn: null, sessionTotal: this.state.sessionTotal, balance: current };
+        }
+        const charged = Math.max(0, this.baseline - current);
+        this.baseline = current;
+        const sessionTotal = this.state.sessionTotal + charged;
+        this.state = { ...this.state, chargedThisTurn: charged, sessionTotal, balance: current, pending: false };
+        return { chargedThisTurn: charged, sessionTotal, balance: current };
+    }
+    snapshot() {
+        return { ...this.state };
+    }
+}
+/**
+ * Format a credit count for display: thousands-separated, unit-labelled.
+ * Credits are whole units to the customer, so fractions round.
+ */
+export function formatCredits(n, unitLabel = DEFAULT_UNIT_LABEL) {
+    return `${Math.round(n).toLocaleString('en-US')} ${unitLabel}`;
+}
+/**
+ * Shown instead of a number when the post-turn balance fetch failed.
+ * Deliberately NOT a dollar fallback: a managed customer must never see our
+ * COGS, and "updating" is the truth — the charge is committed server-side and
+ * will surface on the next successful sample.
+ */
+export const CREDITS_PENDING = 'credits: updating…';
+/**
+ * The customer-facing spend line, e.g.
+ *   `▲ 52 credits this turn · 519 this session · balance 9,481`
+ * Degrades gracefully: an unknown turn charge renders CREDITS_PENDING, and a
+ * missing balance simply drops that segment.
+ */
+export function formatCreditsLine(s) {
+    if (s.chargedThisTurn === null)
+        return CREDITS_PENDING;
+    const parts = [
+        `▲ ${formatCredits(s.chargedThisTurn, s.unitLabel)} this turn`,
+        `${Math.round(s.sessionTotal).toLocaleString('en-US')} this session`,
+    ];
+    if (s.balance !== null) {
+        parts.push(`balance ${Math.round(s.balance).toLocaleString('en-US')}`);
+    }
+    return parts.join(' · ');
+}
+/**
+ * Session-scoped singletons.
+ *
+ * The cost-render sites are scattered across chalk printers, Ink components,
+ * slash commands and the markdown audit exporter — threading config + balance
+ * through every one of them would be a far larger diff than the behaviour
+ * warrants, and would leave each site free to re-derive the mode differently
+ * (exactly how a leak happens). Instead the mode is decided ONCE at startup
+ * (see costDisplayMode) and published here; every render site asks.
+ *
+ * Tests inject explicitly via each site's optional parameter, so the singleton
+ * is a default, never a hard dependency.
+ */
+export const globalCredits = new CreditsTracker();
+let activeMode = 'usd';
+/** Publish the resolved display mode for the whole process. */
+export function setCostDisplayMode(mode) {
+    activeMode = mode;
+}
+/** The resolved display mode. Defaults to 'usd' until startup resolves it —
+ *  fail-safe for BYOK/local/one-shot paths that never call the setter. */
+export function activeCostDisplayMode() {
+    return activeMode;
+}
+/** Convenience predicate for render sites. */
+export function creditsActive() {
+    return activeMode === 'credits';
+}
+/** Test seam — reset the process-wide mode between cases. */
+export function resetCostDisplayMode() {
+    activeMode = 'usd';
+}

package/dist/cost/display-mode.js

@@ -0,0 +1,29 @@
+/**
+ * The one rule that decides whether a cost figure renders as credits or as
+ * dollars (2026-09-16).
+ *
+ * `'credits'` — a MANAGED customer on a METERED account. They pay us in
+ *   credits; the USD number we compute locally is our Anthropic COGS and
+ *   must never reach their screen.
+ *
+ * `'usd'` — everything else:
+ *   - byok / ai-hub / local: the customer holds the provider relationship,
+ *     so the dollar figure IS their bill. Showing it is the whole point.
+ *   - managed but unmetered (or the balance fetch failed): we have no
+ *     credit truth to show. Fall back to the existing dollar rendering so
+ *     the meter is never blank.
+ *   - `show_cogs = on`: our own operator escape hatch for reading real COGS
+ *     on a managed account (margin analysis, pricing work). Never a default.
+ *
+ * Callers must treat this as the single source of truth — no site may
+ * re-derive the mode from `cfg.llm.mode` alone.
+ */
+export function costDisplayMode(cfg, balanceInfo) {
+    if (cfg.llm?.mode !== 'managed')
+        return 'usd';
+    if (balanceInfo?.metered !== true)
+        return 'usd';
+    if (cfg.show_cogs === true)
+        return 'usd';
+    return 'credits';
+}

package/dist/doctor/checks/credits.js

@@ -0,0 +1,48 @@
+/**
+ * `cspeach doctor` — credits line (2026-09-16).
+ *
+ * Purely informational: whether this account is billed in credits and, if so,
+ * what is left. It NEVER fails the run — a customer with no balance reading
+ * still has a perfectly working CLI, and an unreachable balance endpoint is a
+ * proxy problem the proxy check already reports.
+ *
+ * Deliberately dollar-free: doctor output is the first thing a customer pastes
+ * into a support thread.
+ */
+import { fetchBalance, formatCredits } from '../../cost/credits.js';
+import { getStore } from '../../auth/api-key.js';
+function defaultProbe(cfg) {
+    return () => fetchBalance(cfg, async () => {
+        const store = await getStore();
+        return (await store.get()) ?? '';
+    });
+}
+export async function checkCredits(cfg, probe = defaultProbe(cfg)) {
+    // BYOK / ai-hub / local never touch our ledger — no reason to call the proxy.
+    if (cfg.llm?.mode !== 'managed') {
+        return { name: 'credits', ok: true, message: 'not metered (BYOK)' };
+    }
+    const info = await probe().catch(() => null);
+    if (!info) {
+        return {
+            name: 'credits', ok: true, skipped: true, message: 'unavailable',
+            hint: 'Could not read your balance — check the proxy check above, then retry.',
+        };
+    }
+    if (!info.metered) {
+        return { name: 'credits', ok: true, message: 'not metered (BYOK)' };
+    }
+    if (info.balance_credits === null) {
+        return {
+            name: 'credits', ok: true, skipped: true, message: 'unavailable',
+            hint: info.unprovisioned
+                ? 'Your account is metered but has no credit ledger yet — visit cspeach.dev/portal.'
+                : 'The server reported no balance figure.',
+        };
+    }
+    return {
+        name: 'credits',
+        ok: true,
+        message: `balance ${formatCredits(info.balance_credits, info.unit_label)}`,
+    };
+}

package/dist/doctor/run.js

@@ -10,6 +10,7 @@ import { checkSkill } from './checks/skill.js';
 import { checkKeychainFallback } from './checks/keychain-fallback.js';
 import { checkWriteMode } from './checks/write-mode.js';
 import { checkLlmMode } from './checks/llm-mode.js';
+import { checkCredits } from './checks/credits.js';
 import { checkForgeRules } from './checks/forge-rules.js';
 import { checkSystemRoles } from './checks/system-roles.js';
 import { checkStandards } from './checks/standards.js';
@@ -20,6 +21,7 @@ export async function runDoctor() {
     checks.push(await checkProxy());
     checks.push(await checkAuth());
     checks.push(await checkLlmMode(cfg));
+    checks.push(await checkCredits(cfg));
     checks.push(await checkWriteMode(cfg));
     checks.push(await checkSystemRoles(cfg));
     checks.push(await checkKeychain());

package/dist/one-shot.js

@@ -19,6 +19,7 @@ import { createClassicOutputEmitter } from './renderer/notices.js';
 import { todoEmitter } from './ui/todo-emitter.js';
 import { applyLocalBuildConfig } from './tools/local-build.js';
 import { getEffectiveWriteMode } from './repl/mode-cycle.js';
+import { initCredits } from './cost/credits-wire.js';
 // Side-effect imports for tool registration.
 import './tools/sap-read.js';
 import './tools/sap-write.js';
@@ -97,6 +98,12 @@ export async function runOneShot(prompt, opts) {
         console.error('No API key configured. Run `cspeach` (interactive) first to set one.');
         return 1;
     }
+    // Credits (2026-09-16) — resolve the display mode before the turn runs, so
+    // the per-turn cost JSONL records the ledger charge and nothing downstream
+    // can print a dollar to a managed customer. One-shot prints no cost figure
+    // of its own today, but the agent loop's cost-log path is shared with the
+    // REPL and must not diverge. Capped + fail-safe; BYOK/local skip the call.
+    await initCredits(cfg, async () => (await store.get()) ?? '');
     const aliases = Object.keys(cfg.sap);
     let alias;
     let adt;

package/dist/renderer/status-footer.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { formatCost } from '../cost/pricing.js';
+import { creditsActive, formatCreditsLine, CREDITS_PENDING } from '../cost/credits.js';
 const RULE_WIDTH = 72;
 const RULE = chalk.dim('─'.repeat(RULE_WIDTH));
 /**
@@ -40,15 +41,24 @@ export const LARGE_SESSION_THRESHOLD = 100_000;
  * direct stdout (which would corrupt the live Ink frame).
  */
 export function formatStatusFooter(params) {
-    const { sessionId, sapAlias, skill, turnCount, tokens, cachedTokens, elapsedMs, costThisTurn, costSession, sessionInputTokens, variant } = params;
+    const { sessionId, sapAlias, skill, turnCount, tokens, cachedTokens, elapsedMs, costThisTurn, costSession, sessionInputTokens, variant, credits } = params;
     const shortSession = sessionId.slice(0, 8);
     const skillDisplay = skill.startsWith('/') ? skill : `/${skill}`;
     const turns = `${turnCount} turn${turnCount === 1 ? '' : 's'}`;
     const tokStr = tokens.toLocaleString() + ' tok this turn';
     const cachedStr = cachedTokens > 0 ? `${cachedTokens.toLocaleString()} cached` : '';
     const elapsed = elapsedMs > 0 ? `${(elapsedMs / 1000).toFixed(1)}s` : '';
-    const costTurnStr = costThisTurn != null ? formatCost(costThisTurn) : '';
-    const costSessStr = costSession != null ? `session: ${formatCost(costSession)}` : '';
+    // Credits mode: the whole spend story collapses into ONE customer-facing
+    // segment (turn · session · balance) in place of the two dollar segments.
+    // Both variants read `costTurnStr`, so putting the combined line there
+    // covers the slim Ink receipt and the full classic receipt alike.
+    const inCredits = creditsActive();
+    const costTurnStr = inCredits
+        ? (credits ? formatCreditsLine(credits) : CREDITS_PENDING)
+        : (costThisTurn != null ? formatCost(costThisTurn) : '');
+    const costSessStr = inCredits
+        ? ''
+        : (costSession != null ? `session: ${formatCost(costSession)}` : '');
     // Ink turn-receipt (see the variant doc on StatusFooterParams):
     // turn-only facts — everything session-scoped lives in <StatusLine />.
     const parts = variant === 'turn'

package/dist/repl/post-turn-status.js

@@ -20,6 +20,7 @@
 import { computeCost } from '../cost/pricing.js';
 import { computeSessionCost } from '../cost/session-cost.js';
 import { globalStore } from '../ui/sap-state-store.js';
+import { globalCredits } from '../cost/credits.js';
 import { printStatusFooter, formatStatusFooter } from '../renderer/status-footer.js';
 import { shouldUseInk } from '../renderer/tty.js';
 export function snapshotTurnStart(session) {
@@ -71,6 +72,10 @@ export function pushPostTurnStatus(params) {
         costThisTurn: turnCost,
         costSession: sessionCost,
         sessionInputTokens: session.usage.input_tokens,
+        // Credits (2026-09-16): the agent loop already sampled the post-turn
+        // balance, so this snapshot is fresh. formatStatusFooter ignores it
+        // entirely in USD mode — the dollar receipt stays byte-identical.
+        credits: globalCredits.snapshot(),
     };
     if (shouldUseInk() && chunkEmitter) {
         // Push through chunkEmitter so the line lands in Body's <Static>

package/dist/repl/session-spend-line.js

@@ -0,0 +1,20 @@
+/**
+ * The `spend:` row of the /exit session summary (2026-09-16).
+ *
+ * Extracted from repl.tsx's printGoodbye so the credits/USD switch has one
+ * testable home. USD output is byte-identical to the line printed before
+ * credits existed: `  spend:     $1.37`.
+ */
+import { formatCost } from '../cost/pricing.js';
+import { creditsActive, formatCredits, CREDITS_PENDING } from '../cost/credits.js';
+export function formatSessionSpendLine(sessionCostUsd, credits) {
+    if (!creditsActive())
+        return `  spend:     ${formatCost(sessionCostUsd)}`;
+    if (!credits)
+        return `  spend:     ${CREDITS_PENDING}`;
+    const value = formatCredits(credits.sessionTotal, credits.unitLabel);
+    const balance = credits.balance !== null
+        ? ` · balance ${Math.round(credits.balance).toLocaleString('en-US')}`
+        : '';
+    return `  spend:     ${value}${balance}`;
+}

package/dist/repl.js

@@ -22,7 +22,10 @@ import { makeSessionId, saveSession } from './session/store.js';
 import { newSession } from './session/schema.js';
 import { resolveModelRole } from './models/resolve.js';
 import { loadServerModelConfig } from './models/server-config.js';
-import { computeCost, formatCost } from './cost/pricing.js';
+import { computeCost } from './cost/pricing.js';
+import { formatSessionSpendLine } from './repl/session-spend-line.js';
+import { globalCredits } from './cost/credits.js';
+import { initCredits } from './cost/credits-wire.js';
 import { createProviderForMode } from './agent/providers/factory.js';
 import { assertModeLicensed, CspeachLicenseError } from './agent/providers/license-gate.js';
 import { runTurn } from './agent/loop.js';
@@ -242,7 +245,7 @@ function printGoodbye(session) {
     console.log(chalk.dim(`  turns:     ${userTurns}`));
     console.log(chalk.dim(`  last skill: ${session.skill ?? '(none)'}`));
     console.log(chalk.dim(`  tokens:    ${totalTokens.toLocaleString()}  (input+output+cache)`));
-    console.log(chalk.dim(`  spend:     ${formatCost(sessionCost)}`));
+    console.log(chalk.dim(formatSessionSpendLine(sessionCost, globalCredits.snapshot())));
     console.log('');
     console.log(chalk.cyan(`Resume with: cspeach --resume ${session.id}`));
     console.log(chalk.dim(`Full log: ~/.cspeach/streams/${session.id}.md`));
@@ -404,6 +407,13 @@ export async function runRepl(opts) {
     // fetch lands simply uses the built-ins (fail-safe). Precedence when it does
     // land: env > local config > server > built-in.
     void loadServerModelConfig(cfg);
+    // Credits (2026-09-16) — resolve ONCE, before any cost figure can render.
+    // A managed customer is billed in credits at a multiplier we do not
+    // disclose, so the dollar figures (our Anthropic COGS) must never reach
+    // their screen. Awaited, but hard-capped at 2.5s inside fetchBalance and
+    // fail-safe: any failure leaves the process in USD mode, i.e. exactly the
+    // pre-credits behaviour. BYOK/ai-hub/local skip the round-trip entirely.
+    await initCredits(cfg, async () => apiKey ?? '');
     // Task C.10 — surface the current write_mode prominently. advisory-only gets
     // a bold yellow banner (no-writes is a surprising-enough state that the user
     // should not miss it). Other modes get a quiet one-liner so the state is

package/dist/session/audit-export.js

@@ -31,6 +31,7 @@
 // never an invented approval.
 import { summarise } from '../cost/cost-log.js';
 import { CLI_VERSION } from '../lib/version.js';
+import { creditsActive, formatCredits } from '../cost/credits.js';
 /**
  * Object-mutating tools — one row per completed call in the Writes table.
  * Kept as a literal name set (not the tool registry) so this pure builder
@@ -319,7 +320,7 @@ function transportsSeen(toolCalls, sessionTransport) {
 }
 // ── Main builder ──────────────────────────────────────────────────────────
 export function buildAuditReport(input) {
-    const { session, costEntries, transport } = input;
+    const { session, costEntries, transport, credits } = input;
     const calls = session.toolCalls;
     const completed = calls.filter((c) => c.completed === true);
     const approvals = parseApprovals(calls);
@@ -437,15 +438,33 @@ export function buildAuditReport(input) {
     const cost = summarise(costEntries);
     const auditEntries = costEntries.filter((e) => e.label);
     const auditCost = Math.round(auditEntries.reduce((s, e) => s + e.cost, 0) * 10000) / 10000;
-    L(`- **Total:** $${cost.totalCost.toFixed(4)} over ${cost.turns} turn${cost.turns === 1 ? '' : 's'}`);
+    const inCredits = creditsActive();
+    if (inCredits) {
+        const unit = credits?.unitLabel ?? 'credits';
+        const logged = costEntries.reduce((s, e) => s + (typeof e.credits_charged === 'number' ? e.credits_charged : 0), 0);
+        const total = credits && credits.sessionTotal > 0 ? credits.sessionTotal : logged;
+        L(`- **Total:** ${formatCredits(total, unit)} over ${cost.turns} turn${cost.turns === 1 ? '' : 's'}`);
+    }
+    else {
+        L(`- **Total:** $${cost.totalCost.toFixed(4)} over ${cost.turns} turn${cost.turns === 1 ? '' : 's'}`);
+    }
     L(`- **Tokens:** ${cost.totalTokens.input.toLocaleString('en-US')} in · ${cost.totalTokens.output.toLocaleString('en-US')} out · ${cost.totalTokens.cacheRead.toLocaleString('en-US')} cache-read · ${cost.totalTokens.cacheCreate.toLocaleString('en-US')} cache-write`);
+    if (inCredits && credits?.balance != null) {
+        L(`- **Remaining:** balance ${Math.round(credits.balance).toLocaleString('en-US')}`);
+    }
     if (auditEntries.length > 0) {
-        L(`- **Includes** ${auditEntries.length} labelled audit turn${auditEntries.length === 1 ? '' : 's'}: $${auditCost.toFixed(4)}`);
+        // Credits mode: the labelled-audit turn COUNT is still useful provenance;
+        // its USD cost is not ours to publish to a customer.
+        L(inCredits
+            ? `- **Includes** ${auditEntries.length} labelled audit turn${auditEntries.length === 1 ? '' : 's'}`
+            : `- **Includes** ${auditEntries.length} labelled audit turn${auditEntries.length === 1 ? '' : 's'}: $${auditCost.toFixed(4)}`);
     }
     if (cost.byModel.length > 1) {
         L('- **By model:**');
         for (const m of cost.byModel) {
-            L(`  - ${m.model}: ${m.turns} turn${m.turns === 1 ? '' : 's'} · $${m.cost.toFixed(4)}`);
+            L(inCredits
+                ? `  - ${m.model}: ${m.turns} turn${m.turns === 1 ? '' : 's'}`
+                : `  - ${m.model}: ${m.turns} turn${m.turns === 1 ? '' : 's'} · $${m.cost.toFixed(4)}`);
         }
     }
     else if (cost.byModel[0]) {

package/dist/ui/header.js

@@ -1,6 +1,7 @@
 import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { useSapState } from './sap-state-store.js';
+import { formatSpendSegment } from './status-line.js';
 import { CLI_VERSION } from '../lib/version.js';
 const PEACH = '#FFCBA4';
 /**
@@ -34,6 +35,7 @@ export function Header({ writeMode } = {}) {
     const tokDisplay = s.tokenUsageToday >= 1000
         ? `${(s.tokenUsageToday / 1000).toFixed(1)}k tok`
         : `${s.tokenUsageToday} tok`;
-    const spendDisplay = `$${s.dollarSpendToday.toFixed(2)}`;
+    // Shared with <StatusLine /> so the credits/dollar switch has one home.
+    const spendDisplay = formatSpendSegment(s);
     return (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsxs(Text, { bold: true, color: PEACH, children: ["\uD83C\uDF51 CSPeach ", CLI_VERSION] }), _jsx(Text, { color: "gray", children: " \u2502 " }), _jsx(Text, { color: "cyan", children: s.system || 'no system' }), _jsx(Text, { color: "gray", children: " \u2502 " }), _jsx(Text, { color: "white", children: s.user || '—' }), _jsx(Text, { color: "gray", children: " \u2502 tr " }), _jsx(Text, { color: "yellow", children: s.transport ?? 'none' }), _jsx(Text, { color: "gray", children: " \u2502 " }), _jsx(Text, { color: "green", children: tokDisplay }), _jsx(Text, { color: "gray", children: " \u2502 " }), _jsx(Text, { color: "green", children: spendDisplay }), modeLabel && (_jsxs(_Fragment, { children: [_jsx(Text, { color: "gray", children: " \u2502 " }), _jsx(Text, { color: modeColor, bold: isAdvisory, children: modeLabel })] }))] }));
 }

package/dist/ui/sap-state-store.js

@@ -15,6 +15,10 @@ const DEFAULT_STATE = {
     system: '', user: '', transport: null, locksHeld: [],
     tokenUsageToday: 0, dollarSpendToday: 0, dollarCap: 100, recentTurns: [],
     writeMode: null, lastWriteTransport: null,
+    // Credits default OFF: BYOK/local/ai-hub and any pre-resolution frame keep
+    // the dollar rendering. Only an explicit managed+metered resolution flips it.
+    creditsMode: false, creditsSessionTotal: 0, creditsBalance: null,
+    creditsUnitLabel: 'credits', creditsPending: false,
 };
 /**
  * Rate limiter: calls `fn` at most once every `minIntervalMs`. Trailing-only:

package/dist/ui/status-line.js

@@ -1,6 +1,21 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from 'ink';
 import { useSapState } from './sap-state-store.js';
+import { formatCredits, CREDITS_PENDING } from '../cost/credits.js';
+/**
+ * The spend segment shared by <StatusLine /> and <Header />.
+ *
+ * Single home for the credits/dollar switch so the two chrome widgets can
+ * never drift apart — a drift here is exactly how our COGS would leak onto a
+ * managed customer's screen from one of them.
+ */
+export function formatSpendSegment(s) {
+    if (!s.creditsMode)
+        return `$${s.dollarSpendToday.toFixed(2)}`;
+    if (s.creditsPending && s.creditsSessionTotal === 0)
+        return CREDITS_PENDING;
+    return formatCredits(s.creditsSessionTotal, s.creditsUnitLabel);
+}
 /**
  * Persistent SAP statusline (UX Wave 1, Task 4) — Header reborn,
  * bottom-anchored. Single borderless line rendered between <TurnStatus />
@@ -25,7 +40,11 @@ const MODE_COLORS = {
 };
 export function StatusLine() {
     const s = useSapState();
-    const spendDisplay = `$${s.dollarSpendToday.toFixed(2)}`;
+    // Credits mode (2026-09-16): a managed customer sees what THEY are charged.
+    // The segment keeps its meaning — "what this session has cost me" — so it
+    // carries the session credit total, not the balance (the balance has its
+    // own home in the post-turn receipt and `cspeach doctor`).
+    const spendDisplay = formatSpendSegment(s);
     // Wave1 live-fix (Bug 1) — one TRUNCATING <Text> instead of a <Box> of
     // sibling Texts. The statusline lives in the dynamic Ink frame, where a
     // row that soft-wraps in the terminal breaks log-update's logical-line

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cspeach/cli",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "CSPeach — AI-assisted ABAP development CLI. Direct SAP access, 34 skills, safety gates.",
   "keywords": [
     "abap",