@pugi/cli 0.1.0-beta.19 → 0.1.0-beta.20

package/dist/core/cost/rate-card.js

@@ -0,0 +1,129 @@
+/**
+ * Rate card for the `pugi cost` / `/cost` / `/usage` surface — L19 sprint.
+ *
+ * Distinct from `core/repl/model-pricing.ts` on purpose:
+ *
+ *   - `model-pricing.ts` powers the TUI cost meter (per-turn flash, status
+ *     row USD). Its ladder is keyed against the live Anvil model slugs and
+ *     intentionally inflates an honest worst-case figure via the Sonnet
+ *     fallback so an operator on a quiet model never gets billed by a
+ *     surprise. It rounds to USD per 1M tokens at runtime.
+ *
+ *   - `rate-card.ts` (this file) powers the persisted `/cost` table the
+ *     operator reads to plan budget. It distinguishes open-weight models
+ *     ($0 / $0 — infra cost only) from hosted closed models so the table
+ *     does not double-charge an operator running a self-hosted Qwen or
+ *     Kimi behind Pugi. The L19 spec calls these out by name.
+ *
+ * Both ladders intentionally agree on Anthropic Claude family pricing so
+ * the TUI flash and the persisted table cannot disagree on a Claude turn.
+ * If they diverge, the per-model-pricing ladder wins for live UI; the
+ * rate card here wins for the persisted `.pugi/cost.json` aggregate.
+ *
+ * Prices are USD per 1,000,000 tokens, sourced from the L19 spec
+ * (2026-05-27) which mirrors provider list-price pages as of that date.
+ */
+/**
+ * Exact-match price ladder keyed by model slug. Slugs match the L19 task
+ * spec verbatim so a copy-paste from the sprint doc resolves without
+ * normalisation.
+ */
+export const RATES_PER_MTOKEN = Object.freeze({
+    // Anthropic Claude family (hosted, billed).
+    'claude-opus-4-7': { input: 15, output: 75 },
+    'claude-opus-4-6': { input: 15, output: 75 },
+    'claude-sonnet-4-6': { input: 3, output: 15 },
+    'claude-sonnet-4-5': { input: 3, output: 15 },
+    'claude-haiku-4-5-20251001': { input: 1, output: 5 },
+    'claude-haiku-4-5': { input: 1, output: 5 },
+    // Open-weight models — infra cost only, never per-token billed. The
+    // note column surfaces the reason so a CFO reading the JSON envelope
+    // does not assume the row is broken.
+    'qwen3-coder-480b-instruct-fp8': { input: 0, output: 0, note: 'open-weight' },
+    'kimi-k2.6': { input: 0, output: 0, note: 'open-weight' },
+    'deepseek-v4-pro': { input: 0, output: 0, note: 'open-weight' },
+});
+/**
+ * Family-prefix fallback — used only when an exact slug miss. Mirrors the
+ * approach in `model-pricing.ts` so a future model rebind (e.g.
+ * `claude-opus-4-8`) prices reasonably without a code edit.
+ */
+const FAMILY_FALLBACKS = [
+    ['claude-opus-', { input: 15, output: 75 }],
+    ['claude-sonnet-', { input: 3, output: 15 }],
+    ['claude-haiku-', { input: 1, output: 5 }],
+    ['qwen', { input: 0, output: 0, note: 'open-weight' }],
+    ['kimi', { input: 0, output: 0, note: 'open-weight' }],
+    ['deepseek', { input: 0, output: 0, note: 'open-weight' }],
+];
+/**
+ * Final fallback for unknown slugs. Pinned to Sonnet-tier — same posture
+ * as `model-pricing.ts`'s default, so an unrecognised hosted model bills
+ * "honestly conservative" rather than $0 (which would silently hide cost
+ * from the operator).
+ */
+const DEFAULT_RATE = { input: 3, output: 15, note: 'unknown model — Sonnet-tier estimate' };
+/**
+ * Look up the rate for a model slug.
+ *
+ * Resolution order:
+ *   1. Exact match in `RATES_PER_MTOKEN`.
+ *   2. Family-prefix match (first hit wins).
+ *   3. Default Sonnet-tier estimate.
+ *
+ * Pure, never throws. Called on every cost-tracker write so the hot path
+ * stays branch-cheap.
+ */
+export function rateFor(model) {
+    if (!model || typeof model !== 'string')
+        return DEFAULT_RATE;
+    const exact = RATES_PER_MTOKEN[model];
+    if (exact)
+        return exact;
+    for (const [prefix, rate] of FAMILY_FALLBACKS) {
+        if (model.startsWith(prefix))
+            return rate;
+    }
+    return DEFAULT_RATE;
+}
+/**
+ * Compute the USD cost for a single (model, inputTokens, outputTokens)
+ * triple. Defensive against negative / NaN inputs — out-of-range values
+ * floor to zero so a buggy upstream cannot credit a negative cost.
+ */
+export function estimateUsd(model, inputTokens, outputTokens) {
+    const rate = rateFor(model);
+    const safeIn = Number.isFinite(inputTokens) && inputTokens > 0 ? inputTokens : 0;
+    const safeOut = Number.isFinite(outputTokens) && outputTokens > 0 ? outputTokens : 0;
+    const usd = (safeIn * rate.input + safeOut * rate.output) / 1_000_000;
+    return Number.isFinite(usd) && usd > 0 ? usd : 0;
+}
+/**
+ * Format a USD figure for the `/cost` table.
+ *
+ *   - `≥ $0.01` → two decimals (`$0.46`).
+ *   - `< $0.01` but `> 0` → three decimals (`$0.003`) so fractions of a
+ *     cent are honest instead of rounding to `$0.00`.
+ *   - Exactly `0` or NaN → `$0.00`.
+ *
+ * Mirrors `formatCostUsd` from `model-pricing.ts` intentionally — both
+ * surfaces should print the same number in the same shape.
+ */
+export function formatUsd(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return '$0.00';
+    if (value >= 0.01)
+        return `$${value.toFixed(2)}`;
+    return `$${value.toFixed(3)}`;
+}
+/**
+ * Format a token count for the `/cost` table. Uses comma-thousands so the
+ * table reads `14,300` instead of `14.3k` — distinct from the TUI status
+ * row which uses `k`/`m` shortening to save column width.
+ */
+export function formatTokensWithCommas(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return '0';
+    return Math.floor(value).toLocaleString('en-US');
+}
+//# sourceMappingURL=rate-card.js.map

package/dist/core/cost/tracker.js

@@ -0,0 +1,221 @@
+/**
+ * Persisted per-session cost tracker — L19 sprint (2026-05-27).
+ *
+ * Mission: every Anvil-mediated LLM call goes through `recordCall`, which
+ * aggregates per-model token + USD totals and atomically persists them
+ * to `.pugi/cost.json` so the operator can read `/cost` across REPL
+ * restarts and reconcile a 14-min session that crossed a process boundary.
+ *
+ * Why a fresh module instead of bolting onto `core/repl/session.ts`?
+ *
+ *   - `session.ts` accumulates in-memory state for the live TUI status
+ *     row, which is by-design ephemeral and cleared on REPL boot. The
+ *     operator's "what did I spend across the project?" question needs
+ *     a durable surface that survives a process restart.
+ *   - L19 also has to read `--all-sessions` (last 30 days). The natural
+ *     store for that is a per-workspace history of session aggregates,
+ *     which is easy with the JSON file pattern below and would be
+ *     awkward stitched into the REPL reducer.
+ *
+ * On-disk shape (single JSON file, atomic tmp+rename writes):
+ *
+ *   {
+ *     "version": 1,
+ *     "current": { sessionId, startedAt, models: { <slug>: ModelEntry } },
+ *     "history": [
+ *       { sessionId, startedAt, endedAt, models: { ... } }
+ *     ]
+ *   }
+ *
+ * History rotation: when `recordCall` is invoked with a sessionId
+ * different from `current.sessionId`, the existing `current` row is
+ * stamped with `endedAt = now()` and pushed onto `history`, then a new
+ * `current` row is initialised. History is capped at 90 entries (the L19
+ * `--all-sessions` window is 30 days; 90 gives a generous buffer for
+ * operators on >1 session/day cadence without unbounded growth).
+ *
+ * The tracker is workspace-scoped — every workspace has its own
+ * `.pugi/cost.json`. This matches the existing `.pugi/events.jsonl` /
+ * `.pugi/index.json` pattern and means a multi-repo operator's costs
+ * are billed against the repo they were incurred in.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { estimateUsd } from './rate-card.js';
+/** On-disk schema version. Bump if the file shape changes. */
+export const COST_FILE_SCHEMA_VERSION = 1;
+/** Maximum number of historical sessions persisted in `.pugi/cost.json`. */
+export const COST_HISTORY_CAP = 90;
+export function createCostTracker(opts) {
+    const filePath = resolve(opts.workspaceRoot, '.pugi/cost.json');
+    const now = opts.now ?? Date.now;
+    let state = readOrInit(filePath);
+    function ensureCurrent(sessionId) {
+        if (state.current && state.current.sessionId === sessionId) {
+            return state.current;
+        }
+        // Session rotation: stamp the previous current with endedAt and push
+        // onto history. Idempotent — calling rotate twice with the same
+        // session id is a no-op.
+        if (state.current) {
+            const ended = {
+                ...state.current,
+                endedAt: new Date(now()).toISOString(),
+            };
+            state.history = [ended, ...state.history].slice(0, COST_HISTORY_CAP);
+        }
+        state.current = {
+            sessionId,
+            startedAt: new Date(now()).toISOString(),
+            models: {},
+        };
+        return state.current;
+    }
+    function persist() {
+        try {
+            mkdirSync(dirname(filePath), { recursive: true });
+        }
+        catch {
+            // best-effort directory create; the write below surfaces the real
+            // error if the parent is genuinely unwritable
+        }
+        const tmp = `${filePath}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+        renameSync(tmp, filePath);
+    }
+    return {
+        recordCall(input) {
+            const sessionId = opts.sessionIdProvider();
+            if (!sessionId)
+                return;
+            const current = ensureCurrent(sessionId);
+            const slug = typeof input.model === 'string' && input.model.length > 0 ? input.model : 'unknown';
+            const safeIn = Number.isFinite(input.inputTokens) && input.inputTokens > 0 ? input.inputTokens : 0;
+            const safeOut = Number.isFinite(input.outputTokens) && input.outputTokens > 0 ? input.outputTokens : 0;
+            const existing = current.models[slug] ?? { input: 0, output: 0, callCount: 0 };
+            current.models[slug] = {
+                input: existing.input + safeIn,
+                output: existing.output + safeOut,
+                callCount: existing.callCount + 1,
+            };
+            persist();
+        },
+        current() {
+            return state.current;
+        },
+        history() {
+            return state.history;
+        },
+        aggregateWithin(withinDays) {
+            const cutoffMs = now() - withinDays * 24 * 60 * 60 * 1000;
+            const aggregate = {
+                sessionId: 'aggregate',
+                startedAt: new Date(cutoffMs).toISOString(),
+                endedAt: new Date(now()).toISOString(),
+                models: {},
+            };
+            const rows = [];
+            if (state.current)
+                rows.push(state.current);
+            for (const row of state.history) {
+                const stamp = Date.parse(row.startedAt);
+                if (Number.isFinite(stamp) && stamp >= cutoffMs)
+                    rows.push(row);
+            }
+            for (const row of rows) {
+                for (const [slug, entry] of Object.entries(row.models)) {
+                    const existing = aggregate.models[slug] ?? { input: 0, output: 0, callCount: 0 };
+                    aggregate.models[slug] = {
+                        input: existing.input + entry.input,
+                        output: existing.output + entry.output,
+                        callCount: existing.callCount + entry.callCount,
+                    };
+                }
+            }
+            return aggregate;
+        },
+        resetCurrent() {
+            const wiped = state.current;
+            state.current = null;
+            persist();
+            return wiped;
+        },
+        flush() {
+            persist();
+        },
+    };
+}
+/**
+ * Compute the per-session USD total from a `SessionAggregate`. Pure —
+ * uses the rate card to bind a price to every model entry. Open-weight
+ * models contribute $0 (their entries always have $0/$0 rate).
+ */
+export function totalUsd(aggregate) {
+    let total = 0;
+    for (const [slug, entry] of Object.entries(aggregate.models)) {
+        total += estimateUsd(slug, entry.input, entry.output);
+    }
+    return total;
+}
+/**
+ * Compute total input + output token sums across all models in an
+ * aggregate. Used by the CLI table footer.
+ */
+export function totalTokens(aggregate) {
+    let input = 0;
+    let output = 0;
+    for (const entry of Object.values(aggregate.models)) {
+        input += entry.input;
+        output += entry.output;
+    }
+    return { input, output };
+}
+/**
+ * Read the persisted file (or initialise an empty one). Tolerates a
+ * corrupted file by returning a fresh empty state — losing one
+ * session's history is preferable to throwing from the boot path of
+ * every `pugi cost` invocation.
+ */
+function readOrInit(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: COST_FILE_SCHEMA_VERSION, current: null, history: [] };
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { version: COST_FILE_SCHEMA_VERSION, current: null, history: [] };
+        }
+        const obj = parsed;
+        return {
+            version: typeof obj.version === 'number' ? obj.version : COST_FILE_SCHEMA_VERSION,
+            current: isAggregate(obj.current) ? obj.current : null,
+            history: Array.isArray(obj.history) ? obj.history.filter(isAggregate) : [],
+        };
+    }
+    catch {
+        return { version: COST_FILE_SCHEMA_VERSION, current: null, history: [] };
+    }
+}
+function isAggregate(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const obj = v;
+    if (typeof obj.sessionId !== 'string' || typeof obj.startedAt !== 'string')
+        return false;
+    if (!obj.models || typeof obj.models !== 'object')
+        return false;
+    return true;
+}
+/**
+ * Test helper — wipe the `.pugi/cost.json` file. Not exported through the
+ * public CostTracker surface because production code must never call
+ * this; an operator-facing reset goes through `resetCurrent()` which
+ * preserves history.
+ */
+export function _danger_wipeCostFile_forTests(workspaceRoot) {
+    const filePath = resolve(workspaceRoot, '.pugi/cost.json');
+    if (existsSync(filePath))
+        unlinkSync(filePath);
+}
+//# sourceMappingURL=tracker.js.map

package/dist/core/engine/tool-bridge.js

@@ -12,6 +12,7 @@ import { buildMcpToolDefs, defaultNonInteractiveMcpPrompt, dispatchMcpTool, MCP_
 import { buildDenialContext, DENIAL_REMINDER_THRESHOLD, } from '../denial-tracking/state.js';
 import { stripInternalFields } from './strip-internal-fields.js';
 import { applyAskAnswer, gate as permissionGate, getToolClass, PermissionDenied, } from '../permissions/index.js';
+import { RetryBudget, RetryBudgetExhausted, hashArgs } from '../retry-budget/index.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
  *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
@@ -492,6 +493,9 @@ function requireString(obj, key) {
 }
 export function buildExecutor(input) {
     const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry, permissionMode, permissionAlwaysCache, permissionAsk, } = input;
+    // Leak L31: per-cycle budget. Default to a fresh instance scoped to
+    // this executor's closure lifetime; tests pass their own.
+    const retryBudget = input.retryBudget ?? new RetryBudget();
     const mcpPrompt = input.mcpPrompt ?? defaultNonInteractiveMcpPrompt;
     const workspaceRoot = input.workspaceRoot ?? ctx.root;
     const planMode = kind === 'plan';
@@ -608,6 +612,20 @@ export function buildExecutor(input) {
         if (ctx.cancellation && ctx.cancellation.isAborted) {
             throw recordDenial(name, argsForTracking, `OPERATOR_ABORTED: ${name} refused — operator cancelled the dispatch.`);
         }
+        // Leak L31 — per-cycle tool retry budget. Same tool + same canonical
+        // args = same bucket. Once the cap is hit we throw a typed sentinel
+        // so the model is forced out of a repair loop. We gate AFTER
+        // permission (denied calls do not burn budget) and BEFORE PreToolUse
+        // hooks (hook-blocked retries DO count — the model still issued the
+        // same call). The `recordAttempt` fires unconditionally so warn-only
+        // mode (PUGI_RETRY_BUDGET_DISABLED=1) still tracks the pattern for
+        // diagnostics.
+        const argHash = hashArgs(argsRaw);
+        const budgetDecision = retryBudget.shouldAllow(name, argHash);
+        retryBudget.recordAttempt(name, argHash);
+        if (!budgetDecision.allowed) {
+            throw new RetryBudgetExhausted(name, budgetDecision.cap, argHash);
+        }
         // Fire PreToolUse hooks. The match grammar takes the tool name and
         // (when extractable) the target path. Each new tool dispatch starts a
         // fresh dedup batch so a hook fires once per dispatch, not once per

package/dist/core/repl/session.js

@@ -633,7 +633,7 @@ export class ReplSession {
                 return verdict;
             }
             case 'cost': {
-                this.dispatchCost();
+                await this.dispatchCost();
                 return verdict;
             }
             case 'quota': {
@@ -1166,13 +1166,21 @@ export class ReplSession {
             this.appendSystemLine(`/diff failed: ${this.errorMessage(error)}`);
         }
     }
-    dispatchCost() {
+    async dispatchCost() {
         // α7 cost-meter sprint — full breakdown matching the TUI status row
         // footer. The session totals line mirrors the footer format
         // (`↑ <in> ↓ <out> · $X.XX · <elapsed>`) so the operator scans the
         // same numbers in two places. Per-turn list shows the last 5 turns
         // oldest → newest; an empty list renders one system line so the
         // operator knows the surface is wired (`No completed turns yet.`).
+        //
+        // L19 (2026-05-27) — after the in-memory recap, also render the
+        // persisted per-model table from `.pugi/cost.json`. That surface
+        // survives a REPL restart and answers the "what did I spend on
+        // claude-opus vs qwen this week?" question the in-memory recap can
+        // not. Errors loading the file collapse to a single warning line so
+        // the in-memory recap (the older, well-tested surface) is never
+        // gated behind a fresh dependency.
         const { sessionTokensIn, sessionTokensOut, sessionCostUsd, sessionStartedAtEpochMs, recentTurns, agents, } = this.state;
         const active = agents.filter((a) => a.status === 'queued' || a.status === 'thinking').length;
         const elapsedMs = Math.max(0, this.now() - sessionStartedAtEpochMs);
@@ -1181,13 +1189,44 @@ export class ReplSession {
         this.appendSystemLine(`Active dispatches: ${active} of cap.`);
         if (recentTurns.length === 0) {
             this.appendSystemLine('No completed turns yet — brief the workforce to charge the meter.');
-            return;
         }
-        this.appendSystemLine(`Recent turns (last ${recentTurns.length}):`);
-        for (let i = 0; i < recentTurns.length; i += 1) {
-            const turn = recentTurns[i];
-            const idx = (i + 1).toString().padStart(2, ' ');
-            this.appendSystemLine(`  ${idx}. ↑ ${formatTokens(turn.tokensIn)} ↓ ${formatTokens(turn.tokensOut)} · ${formatCostUsd(turn.costUsd)}`);
+        else {
+            this.appendSystemLine(`Recent turns (last ${recentTurns.length}):`);
+            for (let i = 0; i < recentTurns.length; i += 1) {
+                const turn = recentTurns[i];
+                const idx = (i + 1).toString().padStart(2, ' ');
+                this.appendSystemLine(`  ${idx}. ↑ ${formatTokens(turn.tokensIn)} ↓ ${formatTokens(turn.tokensOut)} · ${formatCostUsd(turn.costUsd)}`);
+            }
+        }
+        // L19: append the persisted per-model table from .pugi/cost.json.
+        try {
+            const [{ createCostTracker }, { renderCostForSlash }] = await Promise.all([
+                import('../cost/tracker.js'),
+                import('../../runtime/commands/cost.js'),
+            ]);
+            const workspaceRoot = this.options.workspace?.workspaceCwd ?? process.cwd();
+            const sessionId = this.state.sessionId ?? 'no-session';
+            const tracker = createCostTracker({
+                workspaceRoot,
+                sessionIdProvider: () => sessionId,
+                now: () => this.now(),
+            });
+            const current = tracker.current();
+            if (current && Object.keys(current.models).length > 0) {
+                this.appendSystemLine('');
+                const { lines } = renderCostForSlash({
+                    tracker,
+                    allSessions: false,
+                    windowDays: 30,
+                    now: () => this.now(),
+                });
+                for (const line of lines)
+                    this.appendSystemLine(line);
+            }
+        }
+        catch {
+            // best-effort — the persisted view is additive; failure never
+            // breaks the in-memory recap above
         }
     }
     /**

package/dist/core/repl/slash-commands.js

@@ -223,11 +223,17 @@ export function parseSlashCommand(input) {
         case 'diff': {
             return { kind: 'diff' };
         }
-        case 'cost': {
+        case 'cost':
+        case 'usage': {
+            // L19 (2026-05-27): `/usage` is an alias of `/cost` per the cost-
+            // command spec. The previous mapping routed `/usage` to the
+            // network-backed `/quota` surface, but operators trained on Claude
+            // Code expect `/usage` to surface the per-model token breakdown
+            // (same shape as `/cost`). `/quota` remains the canonical name
+            // for the tier + monthly-cap fetch.
             return { kind: 'cost' };
         }
-        case 'quota':
-        case 'usage': {
+        case 'quota': {
             return { kind: 'quota' };
         }
         case 'status': {

package/dist/core/retry-budget/budget.js

@@ -0,0 +1,284 @@
+/**
+ * Leak L31 — Per-command tool retry budget (Claude Code parity).
+ *
+ * Claude Code limits the number of times the model may retry the SAME
+ * tool with the SAME arguments inside a single operator-input cycle.
+ * Once the cap is hit, the dispatcher hard-refuses and surfaces a
+ * sentinel string telling the model that this exact call has exhausted
+ * its retry budget. The model is expected (via system-prompt rule) to
+ * either change approach or ask the operator for guidance instead of
+ * looping forever on a transient failure.
+ *
+ * Why per-cycle, not per-session: a retry budget that persists across
+ * operator turns would surprise the operator. After the operator says
+ * "try again" the model rightly retries; the budget must reset when a
+ * fresh brief arrives. The simplest reset boundary is the executor
+ * lifetime — `buildExecutor` is called once per `runEngineLoop` and
+ * the loop drives exactly one operator-input cycle. Constructing the
+ * budget inside `buildExecutor` therefore gives us per-cycle scoping
+ * "for free" via closure lifetime; no external clear() call is needed
+ * from production callsites. The exported `clear()` exists so tests
+ * and a future hook surface (PreToolUse) can introspect the state.
+ *
+ * Hash design: same tool + same canonical args = same bucket. We
+ * canonicalise the args record by sorting object keys (stable across
+ * model output ordering) and then sha256 the JSON. The model emits
+ * `arguments` as a raw JSON string; we parse, canonicalise, hash. If
+ * parse fails we hash the raw string verbatim — that way an
+ * unparseable repeat still counts toward the cap (otherwise the model
+ * could loop on syntactic noise variants forever).
+ *
+ * Env overrides:
+ *   PUGI_RETRY_BUDGET_<TOOLNAME>=<N>   — override a single tool's cap.
+ *                                        Toolname matches DEFAULT_CAPS
+ *                                        keys verbatim, uppercased
+ *                                        (PUGI_RETRY_BUDGET_BASH=8).
+ *   PUGI_RETRY_BUDGET_DEFAULT=<N>      — override the fallback cap for
+ *                                        any tool not in DEFAULT_CAPS.
+ *   PUGI_RETRY_BUDGET_DISABLED=1       — warn-only mode. `shouldAllow`
+ *                                        still records but always
+ *                                        returns `allowed: true`. The
+ *                                        count is preserved so
+ *                                        diagnostics can still surface
+ *                                        the pattern.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Default per-tool retry caps. Tuned per leak research:
+ *
+ *   bash       — 5  (most volatile; transient flakes common)
+ *   edit       — 3  (deterministic; repeat = real bug)
+ *   write      — 3  (same)
+ *   read       — 10 (cheap; legitimate re-reads after edits)
+ *   search/grep/glob — 10 (cheap; exploration loop)
+ *   web_fetch  — 5  (transient network; not infinite)
+ *   default    — 5  (any tool not in the table)
+ *
+ * Operators override per-tool via `PUGI_RETRY_BUDGET_<NAME>` env vars.
+ * Caps are bounded `[1, 1000]` after override to defend against typo
+ * runaway (e.g. `PUGI_RETRY_BUDGET_BASH=5000000`).
+ */
+export const DEFAULT_CAPS = Object.freeze({
+    bash: 5,
+    edit: 3,
+    write: 3,
+    read: 10,
+    search: 10,
+    grep: 10,
+    glob: 10,
+    web_fetch: 5,
+    default: 5,
+});
+/**
+ * Lower / upper bound for any resolved cap. Defends against:
+ *   - PUGI_RETRY_BUDGET_BASH=0     -> first call instantly denied
+ *   - PUGI_RETRY_BUDGET_BASH=99999 -> effectively unbounded loop
+ */
+export const MIN_CAP = 1;
+export const MAX_CAP = 1000;
+/**
+ * Per-cycle retry budget. One instance per `buildExecutor` call.
+ *
+ * Not thread-safe: the executor is single-threaded by construction
+ * (Node event loop + sequential await in dispatcher). If a future
+ * executor parallelises tool dispatch it must serialise the budget
+ * mutation explicitly.
+ */
+export class RetryBudget {
+    counts = new Map();
+    capCache = new Map();
+    env;
+    programmaticCaps;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.programmaticCaps = options.caps ?? {};
+    }
+    /**
+     * Returns true when PUGI_RETRY_BUDGET_DISABLED=1. In disabled mode
+     * `shouldAllow` still records attempts but always allows the
+     * dispatch — useful for operators triaging a false-positive without
+     * a code change.
+     */
+    isDisabled() {
+        return this.env.PUGI_RETRY_BUDGET_DISABLED === '1';
+    }
+    /**
+     * Record one dispatch attempt. Idempotent on the bucket key (tool
+     * + argHash). Call this BEFORE the dispatch (or after `shouldAllow`
+     * but before `dispatch()` resolves) so a thrown dispatch counts.
+     */
+    recordAttempt(toolName, argHash) {
+        const key = `${toolName}::${argHash}`;
+        const next = (this.counts.get(key) ?? 0) + 1;
+        this.counts.set(key, next);
+        return next;
+    }
+    /**
+     * Returns the current count for (tool, argHash) WITHOUT mutating.
+     */
+    peek(toolName, argHash) {
+        return this.counts.get(`${toolName}::${argHash}`) ?? 0;
+    }
+    /**
+     * Resolve the effective cap for a tool.
+     *
+     * Precedence:
+     *   1. PUGI_RETRY_BUDGET_<TOOL_UPPER>=<N>  (env)
+     *   2. programmaticCaps[toolName]          (constructor)
+     *   3. DEFAULT_CAPS[toolName]              (this module)
+     *   4. PUGI_RETRY_BUDGET_DEFAULT=<N>       (env fallback)
+     *   5. DEFAULT_CAPS.default                (final fallback)
+     *
+     * Bounded by [MIN_CAP, MAX_CAP] post-resolution. Invalid (NaN, ≤0,
+     * non-integer) env values are ignored and the next layer wins.
+     */
+    capFor(toolName) {
+        const cached = this.capCache.get(toolName);
+        if (cached !== undefined)
+            return cached;
+        const envKey = `PUGI_RETRY_BUDGET_${toolName.toUpperCase()}`;
+        const envCap = parseCapEnv(this.env[envKey]);
+        const programmaticCap = this.programmaticCaps[toolName];
+        const defaultCap = DEFAULT_CAPS[toolName];
+        const fallbackEnvCap = parseCapEnv(this.env.PUGI_RETRY_BUDGET_DEFAULT);
+        // DEFAULT_CAPS.default is hard-coded above; cast keeps the type-
+        // narrower happy without leaking `| undefined` through the index
+        // access (tsc cannot prove the literal key exists).
+        const finalFallback = DEFAULT_CAPS.default;
+        let resolved;
+        if (envCap !== undefined) {
+            resolved = envCap;
+        }
+        else if (programmaticCap !== undefined) {
+            resolved = programmaticCap;
+        }
+        else if (defaultCap !== undefined) {
+            resolved = defaultCap;
+        }
+        else {
+            resolved = fallbackEnvCap ?? finalFallback;
+        }
+        const bounded = Math.min(MAX_CAP, Math.max(MIN_CAP, resolved));
+        this.capCache.set(toolName, bounded);
+        return bounded;
+    }
+    /**
+     * Should this dispatch be allowed? Caller passes the current count
+     * BEFORE recording — i.e. shouldAllow returns true when count < cap,
+     * then recordAttempt fires, bringing count up to cap. The next
+     * identical call sees count === cap and is refused.
+     *
+     * In disabled mode `allowed` is forced to true; `count` and `cap`
+     * still reflect reality so logs / diagnostics can spot the pattern.
+     */
+    shouldAllow(toolName, argHash) {
+        const cap = this.capFor(toolName);
+        const count = this.peek(toolName, argHash);
+        const disabled = this.isDisabled();
+        const allowed = disabled ? true : count < cap;
+        return { allowed, count, cap, argHash, disabled };
+    }
+    /** Reset all state. Used between operator-input cycles when the
+     *  budget instance is reused (most callers throw the instance away
+     *  per cycle, so clear() is mostly for tests and hook surfaces). */
+    clear() {
+        this.counts.clear();
+        this.capCache.clear();
+    }
+    /**
+     * Snapshot the current state for diagnostics. Returns a plain
+     * object so it round-trips through JSON.stringify cleanly.
+     */
+    snapshot() {
+        const out = [];
+        for (const [key, count] of this.counts) {
+            const sep = key.indexOf('::');
+            if (sep < 0)
+                continue;
+            out.push({ tool: key.slice(0, sep), argHash: key.slice(sep + 2), count });
+        }
+        return out;
+    }
+}
+/**
+ * Hash the model's tool-call arguments into a stable key. Same
+ * canonical args = same hash regardless of JSON whitespace / key
+ * order. Unparseable JSON is hashed verbatim so the budget still
+ * catches syntactically degenerate retry loops.
+ */
+export function hashArgs(argsRaw) {
+    const canonical = canonicalise(argsRaw);
+    return createHash('sha256').update(canonical).digest('hex');
+}
+/**
+ * Canonicalise a raw JSON arg string. Object keys are sorted
+ * recursively. Arrays preserve order (semantic). Primitives untouched.
+ * On parse failure, returns the original string prefixed with `raw:`
+ * so a malformed-args repeat still hashes to the same bucket.
+ */
+function canonicalise(argsRaw) {
+    try {
+        const parsed = JSON.parse(argsRaw);
+        return JSON.stringify(sortKeys(parsed));
+    }
+    catch {
+        return `raw:${argsRaw}`;
+    }
+}
+function sortKeys(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    const obj = value;
+    const sorted = {};
+    for (const k of Object.keys(obj).sort()) {
+        sorted[k] = sortKeys(obj[k]);
+    }
+    return sorted;
+}
+/**
+ * Parse and bound a `PUGI_RETRY_BUDGET_*` env var. Returns `undefined`
+ * for any non-positive-integer string so the resolver can fall
+ * through to the next precedence layer. Bounded by [MIN_CAP, MAX_CAP]
+ * is NOT applied here — `capFor` clamps after the final layer wins,
+ * matching the "operator typo defends against runaway" requirement
+ * without silently swallowing a meaningful low value (e.g.
+ * `PUGI_RETRY_BUDGET_BASH=1` should clamp to MIN_CAP=1, which it
+ * does naturally since 1 >= MIN_CAP).
+ */
+function parseCapEnv(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        return undefined;
+    return n;
+}
+/**
+ * Sentinel emitted to the model when the budget is exhausted. The
+ * format is stable so the engine adapter, spec layer, and operator
+ * dashboards can pattern-match on it.
+ */
+export function retryBudgetExhaustedSentinel(toolName, cap) {
+    return `RETRY_BUDGET_EXHAUSTED: ${toolName} exceeded ${cap} attempts with these args. Operator must intervene.`;
+}
+/**
+ * Typed error thrown by the tool-bridge when the cap is hit. Carries
+ * the sentinel string so the engine loop can pattern-match without
+ * re-parsing. `instanceof RetryBudgetExhausted` is the canonical
+ * downstream test.
+ */
+export class RetryBudgetExhausted extends Error {
+    toolName;
+    cap;
+    argHash;
+    constructor(toolName, cap, argHash) {
+        super(retryBudgetExhaustedSentinel(toolName, cap));
+        this.name = 'RetryBudgetExhausted';
+        this.toolName = toolName;
+        this.cap = cap;
+        this.argHash = argHash;
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/retry-budget/index.js

@@ -0,0 +1,5 @@
+/**
+ * Leak L31 — Tool retry budget. Public surface.
+ */
+export { DEFAULT_CAPS, MIN_CAP, MAX_CAP, RetryBudget, RetryBudgetExhausted, hashArgs, retryBudgetExhaustedSentinel, } from './budget.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/cli.js

@@ -32,6 +32,7 @@ import { runStatusCommand, defaultStatusHome, } from './commands/status.js';
 import { runUndoCommand } from './commands/undo.js';
 import { runCompactCommand } from './commands/compact.js';
 import { runBudgetCommand } from './commands/budget.js';
+import { runCostCommand } from './commands/cost.js';
 import { runSkillsCommand } from './commands/skills.js';
 import { installDefaultSkills } from '../core/skills/defaults.js';
 import { runAgentsCommand } from './commands/agents.js';
@@ -75,6 +76,7 @@ const handlers = {
     budget: dispatchBudget,
     code: runEngineTask('code'),
     config: dispatchConfig,
+    cost: dispatchCost,
     delegate: dispatchDelegate,
     deploy: dispatchDeploy,
     doctor,
@@ -108,6 +110,10 @@ const handlers = {
     sync,
     undo: dispatchUndo,
     compact: dispatchCompact,
+    // L19 (2026-05-27): `pugi usage` is an alias of `pugi cost` — same
+    // handler, same flags. Operators trained on Claude Code expect either
+    // verb to surface the per-model token + USD table.
+    usage: dispatchCost,
     version,
     web: dispatchWeb,
     whoami,
@@ -419,6 +425,19 @@ async function dispatchPermissions(args, flags, _session) {
         writeOutput: (text) => writeOutput(flags, { text }, text),
     });
 }
+/**
+ * L19 sprint (2026-05-27): `pugi cost` / `pugi usage` top-level surface.
+ *
+ * Aliased through the handlers table so `pugi usage` reuses the same
+ * implementation. The persisted store lives at `<cwd>/.pugi/cost.json`
+ * and is shared with the REPL `/cost` / `/usage` slash handlers.
+ */
+async function dispatchCost(args, flags, _session) {
+    await runCostCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 async function dispatchSkills(args, flags, _session) {
     await runSkillsCommand(args, {
         workspaceRoot: process.cwd(),
@@ -1025,6 +1044,26 @@ const COMMAND_HELP_BODIES = {
         '  pugi config get privacy',
         '  pugi config set privacy=<mode>',
     ],
+    cost: [
+        'pugi cost — token + USD breakdown for the current Pugi session.',
+        '',
+        'Reads .pugi/cost.json (persisted via the in-REPL CostTracker) and',
+        'prints a per-model table plus dollar estimate. Alias: pugi usage.',
+        '',
+        'Flags:',
+        '  --all-sessions          30-day rolling aggregate across all sessions.',
+        '  --window=<days>         Override the aggregate window (max 365).',
+        '  --reset --yes           Clear the current-session counter. History',
+        '                          is preserved. Requires --yes to confirm.',
+        '  --json                  Emit a structured JSON envelope only.',
+        '',
+        'Examples:',
+        '  pugi cost                       Current session totals.',
+        '  pugi cost --all-sessions        Past 30 days aggregated.',
+        '  pugi cost --all-sessions --window=7',
+        '  pugi cost --reset --yes         Wipe the session counter.',
+        '  pugi usage                      Alias for pugi cost.',
+    ],
     config: [
         'pugi config — read / write CLI + tenant configuration.',
         '',

package/dist/runtime/commands/cost.js

@@ -0,0 +1,199 @@
+/**
+ * `pugi cost` / `pugi usage` command handler — L19 sprint (2026-05-27).
+ *
+ * Shared backend for three operator surfaces:
+ *
+ *   - `pugi cost`                  current session (default)
+ *   - `pugi cost --all-sessions`   30-day rolling aggregate
+ *   - `pugi cost --reset --yes`    wipe current session counter (operator-only)
+ *   - `pugi usage`                 alias of `pugi cost`
+ *   - `/cost` REPL slash           same handler, in-REPL output
+ *   - `/usage` REPL slash          same handler, alias of /cost
+ *
+ * Why a separate command from the existing `pugi budget`:
+ *
+ *   - `pugi budget` walks `.pugi/events.jsonl` and bills against the
+ *     event-log heuristic (per-command / per-persona attribution). It
+ *     is the right surface for "what did this brief / this persona
+ *     spend?". It does not break down by model and it does not persist
+ *     a cross-session aggregate.
+ *
+ *   - `pugi cost` (this command) reads the persisted `.pugi/cost.json`
+ *     written by the `CostTracker`. It is the right surface for "what
+ *     did this model spend?" and "what did I spend across the last 30
+ *     days?". Token + USD figures are sourced from the rate card, which
+ *     distinguishes hosted Claude (per-token billed) from open-weight
+ *     Qwen / Kimi / DeepSeek (infra cost only).
+ *
+ * Both commands intentionally coexist — they answer adjacent but distinct
+ * operator questions. The L19 spec calls out `/cost` and `/usage` by
+ * name; the budget surface is unaffected.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createCostTracker, totalTokens, totalUsd, } from '../../core/cost/tracker.js';
+import { buildCostView, renderCostTableText } from '../../tui/cost-table.js';
+/**
+ * Parsed flag bundle. Exported for the test surface; production callers
+ * never touch it directly — `runCostCommand` owns parsing.
+ */
+export function parseCostFlags(args) {
+    const flags = {
+        allSessions: false,
+        reset: false,
+        yes: false,
+        json: false,
+        windowDays: 30,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--all-sessions')
+            flags.allSessions = true;
+        else if (arg === '--reset')
+            flags.reset = true;
+        else if (arg === '--yes' || arg === '-y')
+            flags.yes = true;
+        else if (arg === '--json')
+            flags.json = true;
+        else if (arg.startsWith('--window=')) {
+            const raw = Number.parseInt(arg.slice('--window='.length), 10);
+            if (Number.isFinite(raw) && raw > 0 && raw <= 365)
+                flags.windowDays = raw;
+        }
+    }
+    return flags;
+}
+export async function runCostCommand(args, ctx) {
+    const flags = parseCostFlags(args);
+    const sessionId = ctx.sessionId ?? deriveSessionIdFromEvents(ctx.workspaceRoot) ?? 'no-session';
+    const tracker = createCostTracker({
+        workspaceRoot: ctx.workspaceRoot,
+        sessionIdProvider: () => sessionId,
+        now: ctx.now,
+    });
+    // --reset: clear the current session counter. Operator-only — refuses
+    // without `--yes` so a typo / shell completion never wipes the meter.
+    if (flags.reset) {
+        if (!flags.yes) {
+            ctx.writeOutput({ command: 'cost', status: 'reset_pending_confirmation' }, 'pugi cost --reset clears the current session counter. Re-run with --yes to confirm.');
+            return;
+        }
+        const wiped = tracker.resetCurrent();
+        const payload = {
+            command: 'cost',
+            status: 'reset_ok',
+            wiped: wiped ?? null,
+        };
+        ctx.writeOutput(payload, wiped
+            ? `Cleared session ${wiped.sessionId} (${Object.keys(wiped.models).length} model(s) wiped).`
+            : 'No current session counter to clear.');
+        return;
+    }
+    const aggregate = flags.allSessions ? tracker.aggregateWithin(flags.windowDays) : (tracker.current() ?? emptyAggregate(sessionId, ctx.now ?? Date.now));
+    const tier = ctx.resolveTier ? await safeResolveTier(ctx.resolveTier) : null;
+    const heading = flags.allSessions
+        ? `Pugi cost / usage — aggregate (last ${flags.windowDays} days)`
+        : buildSessionHeading(aggregate, ctx.now ?? Date.now);
+    const view = buildCostView({ aggregate, heading, tier: tier ?? undefined });
+    const text = renderCostTableText(view);
+    ctx.writeOutput({
+        command: flags.allSessions ? 'cost.aggregate' : 'cost.session',
+        status: 'ok',
+        window: flags.allSessions ? `${flags.windowDays}d` : 'current',
+        tokens: {
+            input: view.totalInputTokens,
+            output: view.totalOutputTokens,
+        },
+        dollars: view.totalUsd,
+        perModel: view.rows.map((row) => ({
+            model: row.model,
+            input: row.inputTokens,
+            output: row.outputTokens,
+            usd: row.usd,
+            note: row.note ?? null,
+        })),
+        tier: tier ?? null,
+    }, text);
+}
+/**
+ * Render-only helper for the REPL slash. The slash dispatcher inside
+ * `session.ts` owns the side-effect of pushing system lines; this
+ * function builds the view and the text rendition so the slash handler
+ * can fan the lines into the existing `appendSystemLine` queue.
+ *
+ * Exposed here (not in the Ink module) so the slash path never imports
+ * Ink/React — keeps the REPL bundle slim and the slash handler async-free.
+ */
+export function renderCostForSlash(input) {
+    const aggregate = input.allSessions
+        ? input.tracker.aggregateWithin(input.windowDays)
+        : (input.tracker.current() ?? emptyAggregate('no-session', input.now));
+    const heading = input.allSessions
+        ? `Pugi cost / usage — aggregate (last ${input.windowDays} days)`
+        : buildSessionHeading(aggregate, input.now);
+    const view = buildCostView({ aggregate, heading, tier: input.tier ?? undefined });
+    return { view, lines: renderCostTableText(view).split('\n') };
+}
+/**
+ * Derive a session id from `.pugi/events.jsonl` when the caller does not
+ * pass one. Walks the file once and picks the most recent `session.start`
+ * event's id. Falls back to `null` when the file is missing / corrupted
+ * — the caller substitutes a `'no-session'` placeholder so the table
+ * still renders an empty state instead of crashing.
+ */
+function deriveSessionIdFromEvents(workspaceRoot) {
+    const path = resolve(workspaceRoot, '.pugi/events.jsonl');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+        // Walk from newest to oldest — `session.start` is rare, no reason to
+        // scan the whole file when the answer is at the tail.
+        for (let i = lines.length - 1; i >= 0; i -= 1) {
+            try {
+                const parsed = JSON.parse(lines[i]);
+                if (parsed.type === 'session' && parsed.name === 'start' && typeof parsed.sessionId === 'string') {
+                    return parsed.sessionId;
+                }
+            }
+            catch {
+                // partial-write lines are ignored
+            }
+        }
+    }
+    catch {
+        // best-effort; absent events.jsonl is a normal first-boot state
+    }
+    return null;
+}
+function buildSessionHeading(aggregate, now) {
+    if (!aggregate || aggregate.sessionId === 'no-session' || aggregate.sessionId === 'aggregate') {
+        return 'Pugi cost / usage — no active session';
+    }
+    const start = Date.parse(aggregate.startedAt);
+    if (!Number.isFinite(start)) {
+        return `Pugi cost / usage — session ${aggregate.sessionId}`;
+    }
+    const elapsedMin = Math.max(0, Math.floor((now() - start) / 60_000));
+    return `Pugi cost / usage — session ${aggregate.sessionId} (${elapsedMin} min)`;
+}
+function emptyAggregate(sessionId, now) {
+    return {
+        sessionId,
+        startedAt: new Date(now()).toISOString(),
+        models: {},
+    };
+}
+async function safeResolveTier(resolver) {
+    try {
+        return await resolver();
+    }
+    catch {
+        return null;
+    }
+}
+// Re-export aggregate helpers so the cli.ts wire-up can read totals
+// without reaching into the tracker module directly.
+export { totalUsd, totalTokens };
+//# sourceMappingURL=cost.js.map

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.19');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.20');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/tui/cost-table.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { estimateUsd, formatTokensWithCommas, formatUsd, rateFor } from '../core/cost/rate-card.js';
+/**
+ * Column widths chosen to match the L19 spec output. The model column is
+ * the widest because slug strings like `qwen3-coder-480b-instruct-fp8`
+ * run 31 chars. We pad/truncate inside the renderer so a TUI on a 80-col
+ * terminal does not wrap mid-table.
+ */
+const COL_MODEL = 34;
+const COL_IN = 8;
+const COL_OUT = 9;
+const COL_USD = 10;
+/**
+ * Render one cost report. Stateless — re-rendering with the same view
+ * produces the same output by construction. Tests assert against
+ * `lastFrame()` from `ink-testing-library`.
+ */
+export function CostTable({ view }) {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: view.heading }), _jsx(Text, { children: "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550" }), _jsx(Text, { children: " " }), _jsxs(Text, { children: [pad('MODEL', COL_MODEL), padLeft('IN_TOK', COL_IN), padLeft('OUT_TOK', COL_OUT), padLeft('$ EST', COL_USD)] }), view.rows.length === 0 ? (_jsx(Text, { dimColor: true, children: "No calls recorded yet \u2014 brief a persona to charge the meter." })) : (view.rows.map((row) => (_jsxs(Text, { children: [pad(row.model, COL_MODEL), padLeft(formatTokensWithCommas(row.inputTokens), COL_IN), padLeft(formatTokensWithCommas(row.outputTokens), COL_OUT), padLeft(formatUsd(row.usd), COL_USD), row.note ? ` (${row.note})` : ''] }, row.model)))), _jsx(Text, { children: " " }), _jsxs(Text, { children: ["Total tokens: ", formatTokensWithCommas(view.totalInputTokens + view.totalOutputTokens), ' (in: ', formatTokensWithCommas(view.totalInputTokens), ', out: ', formatTokensWithCommas(view.totalOutputTokens), ')'] }), _jsxs(Text, { children: ["Total dollar estimate: ", formatUsd(view.totalUsd)] }), view.tier ? _jsxs(Text, { children: ["Tier: ", view.tier.tier, view.tier.quotaLine ? ` (${view.tier.quotaLine})` : ''] }) : null] }));
+}
+/**
+ * Build a `CostView` from a `SessionAggregate`. The function lives here
+ * (next to the renderer) so a future caller — the REPL slash, the CLI
+ * command, a JSON-only path — uses the same view-model shape and the
+ * same row-sort rule.
+ */
+export function buildCostView(input) {
+    const rows = [];
+    for (const [model, entry] of Object.entries(input.aggregate.models)) {
+        const usd = estimateUsd(model, entry.input, entry.output);
+        const rate = rateFor(model);
+        rows.push({
+            model,
+            inputTokens: entry.input,
+            outputTokens: entry.output,
+            usd,
+            note: rate.note,
+        });
+    }
+    // Sort by USD descending first (most-expensive-first, matches the L19
+    // sample output where the Claude row leads). Ties break by total
+    // tokens so two free open-weight rows order deterministically.
+    rows.sort((a, b) => {
+        if (b.usd !== a.usd)
+            return b.usd - a.usd;
+        return (b.inputTokens + b.outputTokens) - (a.inputTokens + a.outputTokens);
+    });
+    let totalIn = 0;
+    let totalOut = 0;
+    let totalUsd = 0;
+    for (const row of rows) {
+        totalIn += row.inputTokens;
+        totalOut += row.outputTokens;
+        totalUsd += row.usd;
+    }
+    return {
+        heading: input.heading,
+        rows,
+        totalInputTokens: totalIn,
+        totalOutputTokens: totalOut,
+        totalUsd,
+        tier: input.tier,
+    };
+}
+/**
+ * Plain-string renderer for non-TTY / `--json` callers. Produces the
+ * same table the Ink component would render — no ANSI / no color so it
+ * pipes cleanly into `less` or a JSON tool.
+ */
+export function renderCostTableText(view) {
+    const lines = [];
+    lines.push(view.heading);
+    lines.push('════════════════════════════════════════════════');
+    lines.push('');
+    lines.push(pad('MODEL', COL_MODEL) +
+        padLeft('IN_TOK', COL_IN) +
+        padLeft('OUT_TOK', COL_OUT) +
+        padLeft('$ EST', COL_USD));
+    if (view.rows.length === 0) {
+        lines.push('No calls recorded yet — brief a persona to charge the meter.');
+    }
+    else {
+        for (const row of view.rows) {
+            const noteSuffix = row.note ? ` (${row.note})` : '';
+            lines.push(pad(row.model, COL_MODEL) +
+                padLeft(formatTokensWithCommas(row.inputTokens), COL_IN) +
+                padLeft(formatTokensWithCommas(row.outputTokens), COL_OUT) +
+                padLeft(formatUsd(row.usd), COL_USD) +
+                noteSuffix);
+        }
+    }
+    lines.push('');
+    lines.push(`Total tokens: ${formatTokensWithCommas(view.totalInputTokens + view.totalOutputTokens)} (in: ${formatTokensWithCommas(view.totalInputTokens)}, out: ${formatTokensWithCommas(view.totalOutputTokens)})`);
+    lines.push(`Total dollar estimate: ${formatUsd(view.totalUsd)}`);
+    if (view.tier) {
+        lines.push(`Tier: ${view.tier.tier}${view.tier.quotaLine ? ` (${view.tier.quotaLine})` : ''}`);
+    }
+    return lines.join('\n');
+}
+function pad(value, width) {
+    if (value.length >= width)
+        return value.slice(0, Math.max(0, width - 1)) + ' ';
+    return value + ' '.repeat(width - value.length);
+}
+function padLeft(value, width) {
+    if (value.length >= width)
+        return value.slice(0, width);
+    return ' '.repeat(width - value.length) + value;
+}
+//# sourceMappingURL=cost-table.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.19",
+  "version": "0.1.0-beta.20",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -54,7 +54,7 @@
     "undici": "^8.3.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.19"
+    "@pugi/sdk": "0.1.0-beta.20"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",