segreant 0.1.0 → 0.2.0

package/dist/cli/runCmd.js

@@ -11,12 +11,58 @@ import { createDashboardServer } from '../dashboard/server.js';
 import { loadConfig, mutateConfig, dbPath, demoDbPath, isDemo, unlinkDemoDb, segreantHome } from '../config.js';
 import { packageVersion } from '../version.js';
 import { seedDemo } from '../demo/seed.js';
-import { startOfLocalDay } from '../budget/guard.js';
+import { capBasisSpend, startOfLocalDay } from '../budget/guard.js';
+import { previewReprice, applyReprice } from '../cost/reprice.js';
 import { pricingCoverage } from '../cost/coverage.js';
-import { refreshPricing, pricingStatus, computeCost, DEFAULT_MANIFEST_URL } from '../cost/pricing.js';
+import { refreshPricing, pricingStatus, DEFAULT_MANIFEST_URL } from '../cost/pricing.js';
 import { refreshBaselineManifest, baselineManifestStatus } from '../value/liftBaseline.js';
+import { createFirstSightWatcher } from '../cost/firstSight.js';
 import { C, color, usd, num, printJson } from './ui.js';
 import {} from './flags.js';
+import { capConfigured } from './launchCmd.js';
+/**
+ * Fill an empty sample ledger before the dashboard serves it. `start --demo`
+ * used to serve whatever demo.db held, so on a fresh install every page said
+ * "sample data" over $0 and "no recorded requests". demo.db only ever holds
+ * synthetic rows, so seeding it never touches real metering; a ledger that
+ * already has sample rows is left exactly as it is.
+ */
+export function ensureDemoSeeded(store) {
+    if (store.earliestRequestMs() !== null)
+        return null;
+    return seedDemo(store);
+}
+/**
+ * Listen, or say why not. A busy port used to surface as Node's unhandled
+ * 'error' event and a stack trace; the usual cause is a Segreant that is
+ * already running, and the fix is one flag.
+ */
+export function listenOrExplain(server, port, what, flag) {
+    return new Promise((resolve) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            if (error.code === 'EADDRINUSE') {
+                console.error(`  Port ${port} (${what}) is already in use, so Segreant did not start.`);
+                console.error(`  Another Segreant may be running: open http://localhost:${port} to check.`);
+                console.error(`  Otherwise pick a free port: segreant start ${flag} ${port + 10}`);
+            }
+            else if (error.code === 'EACCES') {
+                console.error(`  Port ${port} (${what}) needs permission this account does not have. Pick another: segreant start ${flag} ${port + 10}`);
+            }
+            else {
+                console.error(`  The ${what} could not listen on 127.0.0.1:${port}: ${error.message}`);
+            }
+            resolve(false);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve(true);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, '127.0.0.1');
+    });
+}
 export async function cmdStart(flags) {
     const cfg = loadConfig();
     if (flags.port)
@@ -25,6 +71,11 @@ export async function cmdStart(flags) {
         cfg.dashboardPort = Number(flags['dashboard-port']);
     const store = new Store(dbPath());
     const tty = process.stdout.isTTY ?? false;
+    if (isDemo()) {
+        const seeded = ensureDemoSeeded(store);
+        if (seeded)
+            console.log(color(tty, C.gray, `  Sample data generated: ${num(seeded.requests)} requests over ${seeded.days} days (same as segreant demo).`));
+    }
     // The proposal store may contain literal suggested code. Honor its short
     // retention boundary whenever the local service starts; this does not touch
     // the longer-lived cost ledger, and an operator can still clear proposals
@@ -44,29 +95,94 @@ export async function cmdStart(flags) {
             ? color(tty, C.gray, `  ↻ pricing refreshed — ${res.modelCount} models (${cfg.pricing.manifestUrl ?? DEFAULT_MANIFEST_URL})`)
             : color(tty, C.yellow, `  ↻ pricing auto-refresh skipped: ${res.error ?? 'unreachable'} — keeping current table`));
     }
-    const proxy = createProxyServer({
+    // With --demo the open store is demo.db. A proxy started here recorded
+    // real provider traffic into the sample store while the banner said "Real
+    // metering is untouched", so demo mode serves the dashboard only. A tool
+    // started with `segreant launch` then finds no proxy, warns that it is
+    // unmetered and goes direct, as it does whenever Segreant is not running.
+    const demo = isDemo();
+    // A model priced by a guess sends one lookup to the public price list (never
+    // in the request's path). Rows are not rewritten: the user is told, and
+    // `segreant reprice` previews the correction.
+    const firstSight = createFirstSightWatcher({
+        // Read from the file at each sighting: `segreant pricing --auto off` in
+        // another terminal must stop the next lookup without a restart (PR #146
+        // review). A config that no longer reads is treated as off.
+        enabled: () => {
+            try {
+                // Only against the built-in public list, which is what the banner and
+                // the privacy statement disclose: an operator who points
+                // pricing.manifestUrl at their own card refreshes it themselves
+                // (PR #146 review).
+                const pricing = loadConfig().pricing;
+                return pricing.lookupUnknownModels && pricingSourceLabel(pricing.manifestUrl) === 'the public price list';
+            }
+            catch {
+                return false;
+            }
+        },
+        // The source the live config selects, not the one at start: enabled() has
+        // just confirmed it is the built-in list, and a source changed since then
+        // is never fetched behind the operator's back (PR #146 review).
+        refresh: async () => {
+            let url;
+            try {
+                url = loadConfig().pricing.manifestUrl;
+            }
+            catch {
+                return { ok: false, error: 'the configuration could not be read' };
+            }
+            if (pricingSourceLabel(url) !== 'the public price list')
+                return { ok: false, error: 'the price source is no longer the public price list' };
+            return refreshPricing(DEFAULT_MANIFEST_URL);
+        },
+        onLearned: (models) => {
+            const names = models.map((m) => m.model).join(', ');
+            // refresh() above fetches only the built-in list, so that is the source
+            // that learned them, whatever the config said at start (PR #146 review).
+            console.log(color(tty, C.green, `  ↻ the public price list now prices ${names}: new requests use that price.`));
+            console.log(color(tty, C.gray, '    Requests already recorded keep their estimate until you run: segreant reprice (preview), then segreant reprice --apply'));
+        },
+        onFailed: (error) => {
+            console.log(color(tty, C.yellow, `  ↻ price lookup skipped: ${error}. Estimated prices stand; segreant pricing set <model> gives one yourself.`));
+        },
+    });
+    const proxy = demo ? null : createProxyServer({
         store,
         config: cfg,
         onLog: (row) => {
+            if (row.pricing)
+                firstSight.note(row.provider, row.model, row.pricing.rateMatchKind);
             if (row.statusCode === 429) {
                 console.log(color(tty, C.red, `  ⛔ blocked  ${row.provider}/${row.model}  (budget)`));
                 return;
             }
-            const today = store.spendBetween(startOfLocalDay(), Date.now() + 1000);
             const time = new Date(row.tsEpochMs).toLocaleTimeString('en-US', { hour12: false });
-            const est = row.estimated ? color(tty, C.yellow, ' ~est') : '';
+            // A price you set is not a guess, and not a list price either (PR #146 sweep).
+            const est = row.estimated ? color(tty, C.yellow, ' ~est')
+                : row.pricing?.costBasis === 'user_declared_price' ? color(tty, C.gray, ' your price') : '';
             console.log(`  ${color(tty, C.gray, time)}  ${row.provider}/${row.model}  ` +
                 `in ${num(row.inputTokens)} out ${num(row.outputTokens)}  ` +
-                `${color(tty, C.green, usd(row.costUsd))}${est}  ${color(tty, C.gray, `today ${usd(today)}`)}`);
+                `${color(tty, C.green, usd(row.costUsd))}${est}  ${color(tty, C.gray, liveTodayLine(store, cfg.budget))}`);
         },
     });
     const dashboard = createDashboardServer({ store, config: cfg, version: packageVersion() });
-    await new Promise((resolve) => proxy.listen(cfg.port, '127.0.0.1', resolve));
-    await new Promise((resolve) => dashboard.listen(cfg.dashboardPort, '127.0.0.1', resolve));
-    printBanner(cfg, tty);
+    const listening = (!proxy || await listenOrExplain(proxy, cfg.port, 'proxy', '--port'))
+        && await listenOrExplain(dashboard, cfg.dashboardPort, 'dashboard', '--dashboard-port');
+    if (!listening) {
+        proxy?.close();
+        dashboard.close();
+        store.close();
+        process.exitCode = 1;
+        return;
+    }
+    if (demo)
+        printDemoBanner(cfg, tty);
+    else
+        printBanner(cfg, tty);
     const shutdown = () => {
         console.log('\n  Shutting down…');
-        proxy.close();
+        proxy?.close();
         dashboard.close();
         store.close();
         process.exit(0);
@@ -74,6 +190,20 @@ export async function cmdStart(flags) {
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }
+function printDemoBanner(cfg, tty) {
+    const line = (s) => console.log('  ' + s);
+    console.log('');
+    line(color(tty, C.bold, 'Segreant  ·  sample-data dashboard'));
+    console.log('');
+    line(`Dashboard  ${color(tty, C.cyan, `http://localhost:${cfg.dashboardPort}`)}`);
+    console.log('');
+    line(color(tty, C.yellow, '● DEMO DATA — synthetic, isolated in demo.db. No proxy runs in demo mode,'));
+    line(color(tty, C.yellow, '  so nothing you send to a provider is recorded here. Real metering is untouched.'));
+    line(color(tty, C.gray, '  To meter your own tools, run "segreant start" without --demo.'));
+    console.log('');
+    line(color(tty, C.gray, 'Press Ctrl+C to stop.'));
+    console.log('');
+}
 function printBanner(cfg, tty) {
     const line = (s) => console.log('  ' + s);
     console.log('');
@@ -90,7 +220,9 @@ function printBanner(cfg, tty) {
     }
     line(color(tty, C.bold, 'Start your tools through Segreant:'));
     line(color(tty, C.gray, '  segreant launch -- claude        (or codex, aider, opencode, …)'));
-    line(color(tty, C.gray, '  Metered while this proxy runs; starts unmetered with a warning when it does not.'));
+    line(color(tty, C.gray, capConfigured(cfg)
+        ? '  Metered while this proxy runs. With a cap set, launch refuses while it is stopped (--allow-unmetered overrides).'
+        : '  Metered while this proxy runs; starts unmetered with a warning when it does not.'));
     line(color(tty, C.bold, 'Or point a tool here yourself (PowerShell):'));
     line(color(tty, C.gray, `  $env:ANTHROPIC_BASE_URL="http://localhost:${cfg.port}"`));
     line(color(tty, C.gray, `  $env:OPENAI_BASE_URL="http://localhost:${cfg.port}/v1"`));
@@ -101,11 +233,46 @@ function printBanner(cfg, tty) {
     else {
         line(color(tty, C.gray, 'No budget cap set. Add one: segreant budget --daily 25 --soft 18'));
     }
+    // The one request Segreant makes on its own: said where the user starts it.
+    if (cfg.pricing.lookupUnknownModels && pricingSourceLabel(cfg.pricing.manifestUrl) === 'the public price list') {
+        line(color(tty, C.gray, 'Prices     a model missing from the rate card is looked up in the public price list'));
+        line(color(tty, C.gray, '           (a plain download; sends nothing about you). Off: segreant pricing --auto off'));
+    }
+    else if (cfg.pricing.lookupUnknownModels) {
+        line(color(tty, C.gray, `Prices     ${pricingSourceLabel(cfg.pricing.manifestUrl)} is not looked up automatically;`));
+        line(color(tty, C.gray, '           refresh it with: segreant pricing --refresh'));
+    }
     console.log('');
     line(color(tty, C.gray, 'Press Ctrl+C to stop. A tool pointed at this address by hand cannot connect while'));
     line(color(tty, C.gray, 'Segreant is stopped; unset the two variables, or use segreant launch, to go direct.'));
     console.log('');
 }
+/**
+ * The source a price refresh reads, in words. The built-in list is spelled two
+ * ways, no URL configured or its own URL; both are the public price list (PR #146 review).
+ */
+/**
+ * The running total on each live log line. With a daily cap it is the spend the
+ * cap counts, beside the cap: the all-sources total read "today $51.29" next to
+ * a $25 cap while requests went through, because imported spend does not count
+ * toward the cap by default (launch pass, 2026-10-18). Any other spend today is
+ * named separately, never added in.
+ */
+export function liveTodayLine(store, budget, nowMs = Date.now()) {
+    const start = startOfLocalDay(nowMs);
+    const all = store.spendBetween(start, nowMs + 1000);
+    if (budget.dailyUsd === null)
+        return `today ${usd(all)}`;
+    const counted = capBasisSpend(store, budget, start, nowMs + 1000);
+    const other = all - counted.usd;
+    return `today ${usd(counted.usd)} of the ${usd(budget.dailyUsd)} cap`
+        + (other >= 0.005 ? ` (+${usd(other)} imported, not counted)` : '');
+}
+export function pricingSourceLabel(manifestUrl) {
+    return manifestUrl === null || manifestUrl === undefined || manifestUrl === DEFAULT_MANIFEST_URL
+        ? 'the public price list'
+        : `your price source (${manifestUrl})`;
+}
 export async function cmdDemo(flags) {
     const tty = process.stdout.isTTY ?? false;
     if (flags.clear) {
@@ -141,6 +308,10 @@ export async function cmdDemo(flags) {
     }
 }
 export async function cmdPricing(flags) {
+    const action = flags._[0];
+    if (action === 'set' || action === 'unset' || action === 'unknown') {
+        return (await import('./pricingDeclareCmd.js')).cmdPricingDeclare(action, flags);
+    }
     const cfg = loadConfig();
     const on = process.stdout.isTTY ?? false;
     // Ledger evidence is deliberately a separate read-only surface from the
@@ -200,15 +371,18 @@ export async function cmdPricing(flags) {
     // file — nothing about the user). `--auto off` turns it back off.
     if (flags['auto'] !== undefined) {
         const enable = flags['auto'] !== 'off' && flags['auto'] !== 'false';
-        const updated = mutateConfig((latest) => ({ ...latest, pricing: { ...latest.pricing, autoRefresh: enable } }));
+        // One switch for both: the age-based refresh and the first-sight lookup.
+        const updated = mutateConfig((latest) => ({ ...latest, pricing: { ...latest.pricing, autoRefresh: enable, lookupUnknownModels: enable } }));
         console.log('');
         if (enable) {
-            console.log(`  ${color(on, C.green, '✓')} Auto-refresh ON — "segreant start" updates the rate card when it is older than ${cfg.pricing.maxAgeDays}d.`);
+            console.log(`  ${color(on, C.green, '✓')} Auto-refresh ON — "segreant start" updates the rate card when it is older than ${cfg.pricing.maxAgeDays}d,`);
+            console.log('    and a running Segreant looks up a model the card does not know the first time it sees it.');
             console.log(`  ${color(on, C.dim, `Source: ${updated.pricing.manifestUrl ?? DEFAULT_MANIFEST_URL}`)}`);
             console.log(`  ${color(on, C.dim, 'The fetch is a GET of a public pricing file — it sends nothing about you. Turn off: segreant pricing --auto off')}`);
         }
         else {
-            console.log(`  ${color(on, C.green, '✓')} Auto-refresh OFF — the rate card only changes when you run "segreant pricing --refresh".`);
+            console.log(`  ${color(on, C.green, '✓')} Auto-refresh OFF — the rate card only changes when you run "segreant pricing --refresh",`);
+            console.log('    and a model the card does not know stays at an estimate until you refresh or run segreant pricing set.');
         }
         console.log('');
         return;
@@ -343,46 +517,19 @@ export function cmdReprice(flags) {
     const store = new Store(dbPath());
     const tty = process.stdout.isTTY ?? false;
     try {
-        const rows = store.estimatedRequestRows();
-        const updates = [];
-        const byModel = new Map();
-        let stillEstimated = 0;
-        for (const r of rows) {
-            const c = computeCost(r.provider, r.model, {
-                inputTokens: r.inputTokens,
-                outputTokens: r.outputTokens,
-                cacheWriteTokens: r.cacheWriteTokens,
-                cacheReadTokens: r.cacheReadTokens,
-            });
-            if (c.estimated) {
-                stillEstimated++;
-                continue; // still a guess — keep the original guess rather than churn numbers
-            }
-            updates.push({ requestId: r.requestId, costUsd: c.costUsd, pricing: c.pricing, ...(c.exact === undefined ? {} : { economicAmount: c.exact.total }) });
-            // Tuple key, not a delimiter join (D-217/D-241): a model name may carry '/'.
-            const key = JSON.stringify([r.provider, r.model]);
-            const agg = byModel.get(key) ?? { n: 0, before: 0, after: 0 };
-            agg.n++;
-            agg.before += r.costUsd;
-            agg.after += c.costUsd;
-            byModel.set(key, agg);
-        }
-        const before = [...byModel.values()].reduce((a, v) => a + v.before, 0);
-        const after = [...byModel.values()].reduce((a, v) => a + v.after, 0);
+        const report = flags.apply ? applyReprice(store) : previewReprice(store);
+        const { updates, stillEstimated, totalBeforeUsd: before, totalAfterUsd: after } = report;
+        const rows = { length: report.estimatedRows };
+        const byModel = new Map(report.byModel.map((v) => [JSON.stringify([v.provider, v.model]), { n: v.rows, before: v.beforeUsd, after: v.afterUsd }]));
         if (flags.json) {
             // Write BEFORE serializing, so the payload can report what the reprice did
             // to the stored realized-value snapshots rather than describing the request
             // rows alone and leaving the snapshots' state to be discovered elsewhere.
-            const sync = flags.apply && updates.length ? store.applyRepricedCosts(updates) : null;
+            const sync = report.realizationSync;
             printJson({
                 applied: !!flags.apply, estimatedRows: rows.length, repriceable: updates.length,
-                stillEstimated, totalBeforeUsd: before, totalAfterUsd: after,
-                priceEvidence: updates.length ? {
-                    localRateCardOnly: true,
-                    cardSha256: updates[0].pricing.rateCardSha256,
-                    sourceKind: updates[0].pricing.rateCardSourceKind,
-                    note: 'Local list-price estimate only; never provider invoice, discount, tax, credit, or reconciliation.',
-                } : null,
+                stillEstimated, cacheDurationUnknown: report.cacheDurationUnknown, alreadyRepriced: report.alreadyRepriced, totalBeforeUsd: before, totalAfterUsd: after,
+                priceEvidence: report.priceEvidence,
                 byModel: [...byModel.entries()].map(([key, v]) => {
                     const [provider, model] = JSON.parse(key);
                     return { provider, model, rows: v.n, beforeUsd: v.before, afterUsd: v.after };
@@ -399,20 +546,25 @@ export function cmdReprice(flags) {
             return;
         }
         console.log(`  Estimated rows       ${num(rows.length)}`);
-        console.log(`  Now exactly priced   ${num(updates.length)}  ${color(tty, C.gray, '(current card has an exact rate for these models)')}`);
+        console.log(`  Now exactly priced   ${num(updates.length)}  ${color(tty, C.gray, '(the current card, or a price you set, gives these models an exact rate)')}`);
         if (stillEstimated)
             console.log(`  Still estimates      ${num(stillEstimated)}  ${color(tty, C.gray, 'left untouched — a new guess is not more honest than the old one')}`);
+        if (report.alreadyRepriced)
+            console.log(`  Already re-priced    ${num(report.alreadyRepriced)}  ${color(tty, C.gray, 'another reprice wrote these first; left as it wrote them and not counted here')}`);
+        if (report.cacheDurationUnknown)
+            console.log(`  Cache duration       ${num(report.cacheDurationUnknown)}  ${color(tty, C.gray, 'rows recorded before Segreant kept the cache-write duration; their writes are priced at the 5-minute rate')}`);
         if (updates.length) {
             console.log('');
             for (const [model, v] of [...byModel.entries()].sort((a, b) => b[1].after - a[1].after).slice(0, 10)) {
                 const delta = v.after - v.before;
                 const dc = delta > 0 ? C.red : C.green;
-                console.log(`  ${model.padEnd(40)} ${num(v.n).padStart(6)} rows  ${usd(v.before).padStart(10)} → ${usd(v.after).padStart(10)}  ${color(tty, dc, (delta >= 0 ? '+' : '') + usd(delta))}`);
+                const [provider, name] = JSON.parse(model);
+                console.log(`  ${`${provider}/${name}`.padEnd(40)} ${num(v.n).padStart(6)} rows  ${usd(v.before).padStart(10)} → ${usd(v.after).padStart(10)}  ${color(tty, dc, (delta >= 0 ? '+' : '') + usd(delta))}`);
             }
             console.log('');
             console.log(`  Total                ${usd(before)} → ${usd(after)}  ${color(tty, after - before >= 0 ? C.red : C.green, (after - before >= 0 ? '+' : '') + usd(after - before))}`);
             if (flags.apply) {
-                const sync = store.applyRepricedCosts(updates);
+                const sync = report.realizationSync;
                 console.log(color(tty, C.green, `  ✓ Applied — ${num(updates.length)} rows re-costed, estimated flag cleared.`));
                 if (sync.resynced) {
                     const delta = sync.costUsdAfter - sync.costUsdBefore;

package/dist/cli/showCmd.js

@@ -12,10 +12,13 @@ import { economicRequestsToCsv, economicRequestsToJson } from '../export/economi
 import { computeAlerts, computeAlertCoverage } from '../alerts/detect.js';
 import { describeSourceDepth } from '../value/sourceDepth.js';
 import { isDeclaredAttribution } from '../value/characterization.js';
-import { C, color, usd, num, pct, printJson } from './ui.js';
+import { C, color, usd, num, pct, printJson, cliJsonResponse } from './ui.js';
 import { stringifyJson } from '../util/json.js';
 import { rangeFor, UserInputError, usdFlag } from './flags.js';
 import { retentionNotice } from './retention.js';
+import { planComparisons, printPlanLines } from './planCmd.js';
+import { summarizeBasis } from '../cost/basis.js';
+import { basisLines } from './basisLines.js';
 import { instant } from '../epistemic/time.js';
 export function cmdShow(window, flags) {
     const cfg = loadConfig();
@@ -44,7 +47,7 @@ export function cmdShow(window, flags) {
     }
     if (flags.json) {
         printJson({
-            window, label, demo: isDemo(), retention, summary, byModel, byProject, byUser, bySource,
+            window, label, demo: isDemo(), retention, summary, basis: summarizeBasis(store.pricingEvidenceByModel(startMs, endMs)), byModel, byProject, byUser, bySource,
             ...(alerts === null || coverage === null ? {} : { alerts, alertCoverage: coverage }),
         });
         store.close();
@@ -60,19 +63,30 @@ export function cmdShow(window, flags) {
     const truncation = retentionNotice(retention);
     if (truncation !== null)
         console.log(color(tty, C.yellow, `  ● ${truncation}`));
-    // Every figure here is priced from the rate card, so it is LIST COST, never
-    // "spend": imported subscription usage is what the work would bill at API
-    // list price, not what was paid, and even proxied API traffic is metered at
-    // list price until a bill reconciles it. Say which part is which.
+    // The total is never "spend". Its word follows the weakest part of it: list
+    // cost only when every dollar was priced at a model's own card rate. A model
+    // missing from the card, an amount a tool reported, or an unpriced provider
+    // each gets its own line, so no part is presented as another (H003/H007).
+    const basis = summarizeBasis(store.pricingEvidenceByModel(startMs, endMs));
     const liveCostUsd = store.spendBetween(startMs, endMs, true);
     const importedCostUsd = Math.max(0, summary.costUsd - liveCostUsd);
-    console.log(`  List cost   ${color(tty, C.green, usd(summary.costUsd))}   ${color(tty, C.gray, `(${num(summary.requests)} requests · priced from the rate card · an estimate)`)}`);
+    const single = basis.cohorts.length === 0 || (basis.cohorts.length === 1 && basis.cohorts[0].id === 'list_exact');
+    console.log(`  ${basis.headlineLabel.padEnd(10)}  ${color(tty, C.green, usd(summary.costUsd))}   ${color(tty, C.gray, single
+        ? basis.cohorts.length === 0 ? `(${num(summary.requests)} requests)` : `(${num(summary.requests)} requests · priced at each model's API list rate · not your bill)`
+        : `(${num(summary.requests)} requests · priced in parts:)`)}`);
+    if (!single) {
+        for (const line of basisLines(basis))
+            console.log(color(tty, C.gray, line));
+    }
     if (importedCostUsd >= 0.005) {
-        console.log(color(tty, C.gray, `              ${usd(importedCostUsd)} read from tool logs: what this use would bill at API list price, not your invoice`));
+        console.log(color(tty, C.gray, `              ${usd(importedCostUsd)} read from tool logs: use on your plans and keys, priced as above, not your invoice`));
     }
     if (liveCostUsd >= 0.005) {
         console.log(color(tty, C.gray, `              ${usd(liveCostUsd)} metered through the proxy: list price; your provider's bill may differ`));
     }
+    // A plan price is monthly, so only the 30-day window sets the two side by side.
+    if (window === 'month' && !isDemo())
+        printPlanLines(tty, planComparisons(store, startMs, endMs));
     console.log(`  Input       ${num(summary.inputTokens)} tokens`);
     console.log(`  Output      ${num(summary.outputTokens)} tokens`);
     if (alerts !== null && coverage !== null) {
@@ -261,12 +275,20 @@ export function cmdExport(flags) {
     }
     const asJson = flags.json === true || flags.format === 'json';
     const out = economic
-        ? (asJson ? economicRequestsToJson(economicRows) : economicRequestsToCsv(economicRows))
-        : (asJson ? `${stringifyJson(rows)}\n` : requestsToCsv(rows));
+        ? (asJson ? `${stringifyJson(cliJsonResponse(JSON.parse(economicRequestsToJson(economicRows))))}\n` : economicRequestsToCsv(economicRows))
+        : (asJson ? `${stringifyJson(cliJsonResponse(rows))}\n` : requestsToCsv(rows));
+    // The economic export leaves out requests refused before they were sent
+    // (they cost nothing), so its count is its own rows, and the gap is named
+    // rather than left for the reader to discover (PR #145 review).
+    const exportedCount = economicRows ? economicRows.length : rows.length;
+    const notSent = economicRows ? rows.length - economicRows.length : 0;
+    if (notSent > 0) {
+        console.error(color(process.stdout.isTTY ?? false, C.gray, `  ${num(notSent)} request${notSent === 1 ? '' : 's'} refused before sending left out: no cost, no economic record.`));
+    }
     if (typeof flags.out === 'string') {
         writeFileSync(flags.out, out);
         const tty = process.stdout.isTTY ?? false;
-        console.error(color(tty, C.green, `  Exported ${num(rows.length)} requests (${economic ? 'economic-' : ''}${asJson ? 'json' : 'csv'}) → ${flags.out}`));
+        console.error(color(tty, C.green, `  Exported ${num(exportedCount)} requests (${economic ? 'economic-' : ''}${asJson ? 'json' : 'csv'}) → ${flags.out}`));
     }
     else {
         process.stdout.write(out);
@@ -313,6 +335,10 @@ export function cmdBudget(flags) {
         }
         return updated;
     });
+    if (flags.json) {
+        printJson({ updated: changing, budget: next.budget });
+        return;
+    }
     console.log('');
     console.log(changing ? '  Budget updated:' : '  Current caps (change one with, for example, segreant budget --daily 20):');
     console.log(`    Daily hard cap:   ${next.budget.dailyUsd === null ? 'off' : usd(next.budget.dailyUsd)}`);

package/dist/cli/teamCmd.js

@@ -109,7 +109,7 @@ export async function cmdReceipt(flags) {
     if (flags.pubkey) {
         const keys = loadOrCreateKeyPair(join(segreantHome(), 'receipt-key.json'));
         if (flags.json) {
-            process.stdout.write(JSON.stringify({ keyId: keys.keyId, publicKey: keys.publicPem }, null, 2) + '\n');
+            printJson({ keyId: keys.keyId, publicKey: keys.publicPem });
             return;
         }
         console.log('');
@@ -255,7 +255,7 @@ export async function cmdReceipt(flags) {
         store.saveReceipt({ unit: r.body.unit, project, tsEpochMs: Date.now(), realized: r.body.realized, receiptJson: JSON.stringify(r) });
     }
     if (flags.json) {
-        process.stdout.write(JSON.stringify(receipts, null, 2) + '\n');
+        printJson(receipts);
         store.close();
         return;
     }
@@ -323,7 +323,7 @@ export async function cmdJudge(flags) {
     if (!picked) {
         store.close();
         if (flags.json) {
-            process.stdout.write(JSON.stringify({ error: 'no-sessions-in-window', project, windowDays, sessions: 0 }, null, 2) + '\n');
+            printJson({ error: 'no-sessions-in-window', project, windowDays, sessions: 0 });
             return;
         }
         console.log('');
@@ -540,7 +540,7 @@ export async function cmdTeamPush(flags) {
     if (flags.pubkey) {
         const keys = loadOrCreateKeyPair(keyPath);
         if (flags.json) {
-            process.stdout.write(JSON.stringify({ keyId: keys.keyId, publicKey: keys.publicPem }, null, 2) + '\n');
+            printJson({ keyId: keys.keyId, publicKey: keys.publicPem });
             return;
         }
         console.log('');
@@ -571,7 +571,7 @@ export async function cmdTeamPush(flags) {
                 console.log(JSON.stringify({ ok: false, error: transportError }, null, 2));
             }
             else {
-                console.error(`  ${color(tty, C.red, '✗')} ${transportError}`);
+                console.error(`  ${color(tty, C.red, '✗')} ${transportError}`);
             }
             process.exitCode = 1;
             return;

package/dist/cli/ui.js

@@ -23,13 +23,17 @@ export function color(on, code, s) {
     return on ? `${code}${s}${C.reset}` : s;
 }
 export function usd(n) {
-    if (n === 0)
+    // Sign outside the symbol, and the same precision either side of zero: a
+    // credit of 5 dollars used to fall through every branch to "$-5.000000".
+    const sign = n < 0 ? '-' : '';
+    const a = Math.abs(n);
+    if (a === 0)
         return '$0.00';
-    if (n >= 1)
-        return `$${n.toFixed(2)}`;
-    if (n >= 0.01)
-        return `$${n.toFixed(4)}`;
-    return `$${n.toFixed(6)}`;
+    if (a >= 1)
+        return `${sign}$${a.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+    if (a >= 0.01)
+        return `${sign}$${a.toFixed(4)}`;
+    return `${sign}$${a.toFixed(6)}`;
 }
 export function num(n) {
     return n.toLocaleString('en-US');
@@ -37,9 +41,21 @@ export function num(n) {
 export function pct(n) {
     return `${(n * 100).toFixed(0)}%`;
 }
-/** Emit a Segreant-owned JSON response with stable six-decimal USD fields. */
+/** CLI response version, separate from database and exported artifact schemas. */
+export const CLI_JSON_SCHEMA_VERSION = 1;
+export function cliJsonResponse(value) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        // A document that already names its own schema version keeps it: that
+        // number describes the document, and the CLI must not relabel it.
+        if (Object.hasOwn(value, 'schemaVersion'))
+            return value;
+        return { ...value, schemaVersion: CLI_JSON_SCHEMA_VERSION };
+    }
+    return { schemaVersion: CLI_JSON_SCHEMA_VERSION, data: value };
+}
+/** Emit one versioned response with stable six-decimal USD fields. */
 export function printJson(value, space = 2) {
-    process.stdout.write(stringifyJson(value, space) + '\n');
+    process.stdout.write(stringifyJson(cliJsonResponse(value), space) + '\n');
 }
 /** Actionable not-a-git-repo message: tell the user what to do, not just what's wrong. */
 export function printNotAGitRepo(repo) {