segreant 0.1.0 → 0.2.0

package/dist/cli/opsCmd.js

@@ -3,6 +3,7 @@
  * Extracted verbatim from cli.ts in the per-command-module split;
  * gatherGuideFacts is exported for the CLI/dashboard guidance contract tests.
  */
+import { capBasisSpend } from '../budget/guard.js';
 import { Store } from '../store/db.js';
 import { loadConfig, mutateConfig, dbPath, configPath, isDemo } from '../config.js';
 import { attributeCommits, isGitRepo } from '../git/correlate.js';
@@ -11,6 +12,7 @@ import { buildGuide } from '../guide.js';
 import { computeAlertCoverage, computeAlerts } from '../alerts/detect.js';
 import { notifyWebhook } from '../alerts/notify.js';
 import { pricingStatus } from '../cost/pricing.js';
+import { summarizeBasis } from '../cost/basis.js';
 import { baselineManifestStatus } from '../value/liftBaseline.js';
 import { probeProxyState } from '../egress/proxyHealth.js';
 import { C, color, usd, num, printNotAGitRepo, printJson } from './ui.js';
@@ -108,7 +110,30 @@ export async function cmdAlerts(flags) {
         process.exitCode = 1;
     store.close();
 }
-export async function cmdDoctor() {
+/**
+ * How the last 30 days were priced, in one line. A price you set is not a list
+ * price and was never checked against one, so it is named on its own rather
+ * than folded into "each model's own list rate" (PR #146 review).
+ */
+export function doctorPricingLine(basis) {
+    if (basis.cohorts.length === 0)
+        return 'no priced requests in 30d';
+    const weak = basis.cohorts.filter((c) => (c.id === 'fallback' || c.id === 'tool_reported' || c.id === 'unrecorded') && c.costUsd >= 0.005);
+    const declared = basis.cohorts.find((c) => c.id === 'user_declared');
+    const parts = [];
+    if (weak.length > 0) {
+        parts.push(`${usd(weak.reduce((s, c) => s + c.costUsd, 0))} of 30d spend priced without the model's own rate (${weak.map((c) => c.label).join(', ')}) — see "segreant month"`);
+    }
+    if (declared)
+        parts.push(`${usd(declared.costUsd)} at prices you set (not checked against a price list)`);
+    const free = basis.cohorts.find((c) => c.id === 'user_free');
+    if (free && !basis.cohorts.some((c) => c.id === 'list_exact' || c.id === 'list_family')) {
+        // Only free models: no rate card priced any of it (PR #146 review).
+        parts.push(`${num(free.requests)} requests on models you marked free (no charge)`);
+    }
+    return parts.length > 0 ? parts.join('; ') : "30d spend priced at each model's own list rate (an estimate, not a bill)";
+}
+export async function cmdDoctor(flags = { _: [] }) {
     const tty = process.stdout.isTTY ?? false;
     const cfg = loadConfig();
     const store = new Store(dbPath());
@@ -121,6 +146,25 @@ export async function cmdDoctor() {
     const criticals = alerts.filter((a) => a.severity === 'critical').length;
     const proxyStatus = await probeProxyState(cfg);
     const proxyUp = proxyStatus.kind === 'up';
+    const basis = summarizeBasis(store.pricingEvidenceByModel(now - 30 * day, now + 1000));
+    if (flags.json) {
+        // The same checks as the text below, as data. `doctor --json` used to print
+        // the text (H013).
+        const price = pricingStatus(cfg.pricing.maxAgeDays);
+        const base = baselineManifestStatus();
+        const coverage = computeAlertCoverage(store, cfg);
+        printJson({
+            config: { path: configPath() },
+            database: { path: dbPath(), last30Days: { requests: sum30.requests, costUsd: sum30.costUsd } },
+            proxy: { port: cfg.port, state: proxyStatus.kind },
+            budget: { dailyUsd: cfg.budget.dailyUsd },
+            pricing: { basis, rateCard: price },
+            baseline: base,
+            alerts: { active: alerts.length, critical: criticals, coverage },
+        });
+        store.close();
+        return;
+    }
     const mark = (good) => (good ? color(tty, C.green, '✓') : color(tty, C.yellow, '!'));
     console.log('');
     console.log(color(tty, C.bold, '  Segreant — doctor'));
@@ -134,7 +178,7 @@ export async function cmdDoctor() {
             : color(tty, C.yellow, `not reachable on :${cfg.port} — start with "segreant start"`);
     console.log(`  ${mark(proxyUp)} Proxy       ${proxyMessage}`);
     console.log(`  ${mark(cfg.budget.dailyUsd !== null)} Daily cap   ${cfg.budget.dailyUsd !== null ? usd(cfg.budget.dailyUsd) : color(tty, C.yellow, 'none — metering only (set with "segreant budget --daily N")')}`);
-    console.log(`  ${mark(estShare <= 0.2)} Pricing     ${estShare > 0 ? `${Math.round(estShare * 100)}% of 30d spend used estimated rates` : 'all spend priced from the rate card'}`);
+    console.log(`  ${mark(estShare <= 0.2)} Pricing     ${doctorPricingLine(basis)}`);
     const price = pricingStatus(cfg.pricing.maxAgeDays);
     const priceAge = price.ageDays === null ? '' : ` · ${price.ageDays}d old`;
     const priceEvidence = price.source === 'cache'
@@ -201,6 +245,7 @@ export async function gatherGuideFacts() {
     const all = store.summary(0, now + 1000);
     const sum30 = store.summary(now - 30 * day, now + 1000);
     const outcomeSignals = store.countSignals();
+    const capBasis = capBasisSpend(store, cfg.budget, now - 30 * day, now + 1000);
     const realizationUnits = store.countRealizationUnits();
     // Read before the store closes: without it `requestsAllTime` is a count of
     // survivors presented as a count of everything (D-170).
@@ -216,6 +261,8 @@ export async function gatherGuideFacts() {
         requestsAllTime: all.requests,
         requestsRetention,
         spend30dUsd: sum30.costUsd,
+        capBasisSpend30dUsd: capBasis.usd,
+        capBasis: capBasis.basis,
         dailyCapUsd: cfg.budget.dailyUsd,
         outcomeSignals,
         realizationUnits,

package/dist/cli/planCmd.js

@@ -0,0 +1,181 @@
+/**
+ * `segreant plan`: which plan each tool runs on, what the person pays for it,
+ * and how much list-price work the plan did. Two bases, always named: the plan
+ * price is what the person entered; the work is list cost from the rate card.
+ */
+import { computeCost, withoutDeclaredPrices } from '../cost/pricing.js';
+import { Store } from '../store/db.js';
+import { dbPath, loadConfig, mutateConfig, PLAN_SOURCES } from '../config.js';
+import { detectPlans, planName, suggestedPrice, PUBLIC_PLAN_PRICES_CHECKED, } from '../plans/detect.js';
+import { C, color, usd, printJson, num } from './ui.js';
+import { rangeFor, UserInputError } from './flags.js';
+const TOOL_LABEL = { 'claude-code': 'Claude Code', codex: 'Codex' };
+/** List cost of a tool's imported (subscription) use in a window. */
+export function importedListCost(store, source, startMs, endMs) {
+    return importedListWork(store, source, startMs, endMs).listCostUsd;
+}
+/**
+ * The list-price work a tool's imported use did, and how many requests on a
+ * price you set were left out because the card has no exact price for their
+ * model. "List-price work" means list prices: a declared row is priced from
+ * the card here, so a declaration never inflates, shrinks or hides the plan
+ * line, and a private model the card only estimates (family or fallback) is
+ * withheld rather than shown as a published price (PR #146 review). Other
+ * rows keep the price they were recorded at.
+ */
+export function importedListWork(store, source, startMs, endMs) {
+    let listCostUsd = 0;
+    let withheldRequests = 0;
+    for (const r of store.requestsInRange(startMs, endMs)) {
+        if (r.source !== source || r.via !== 'import')
+            continue;
+        if (r.pricing?.costBasis !== 'user_declared_price') {
+            listCostUsd += r.costUsd;
+            continue;
+        }
+        const card = withoutDeclaredPrices(() => computeCost(r.provider, r.model, {
+            inputTokens: r.inputTokens, outputTokens: r.outputTokens,
+            cacheWriteTokens: r.cacheWriteTokens, cacheReadTokens: r.cacheReadTokens,
+            ...(r.cacheWriteTtl === undefined ? {} : { cacheWriteTtl: r.cacheWriteTtl }),
+        }));
+        if (card.estimated) {
+            withheldRequests++;
+            continue;
+        }
+        listCostUsd += card.costUsd;
+    }
+    return { listCostUsd, withheldRequests };
+}
+export function planComparisons(store, startMs, endMs) {
+    const cfg = loadConfig();
+    return detectPlans().map((detected) => ({
+        source: detected.source,
+        detected,
+        price: cfg.plans[detected.source] ?? null,
+        ...importedListWork(store, detected.source, startMs, endMs),
+    }));
+}
+function withheldNote(r) {
+    return r.withheldRequests > 0
+        ? ` · ${num(r.withheldRequests)} request${r.withheldRequests === 1 ? '' : 's'} on models with no published price left out`
+        : '';
+}
+/**
+ * The month's plan lines, printed under the list cost by `month` and `scan`.
+ * A price the person set: "Your $20 Claude Pro plan did $1,830 of list-price
+ * work". A plan with no price: the plan, and the command that sets it.
+ */
+export function printPlanLines(tty, rows) {
+    for (const r of rows) {
+        if (r.listCostUsd < 0.005)
+            continue;
+        const name = planName(r.detected) ?? `${TOOL_LABEL[r.source]} (plan not detected)`;
+        if (r.price !== null) {
+            const times = r.price.monthlyUsd > 0 ? `, ${(r.listCostUsd / r.price.monthlyUsd).toFixed(1)}× its price` : '';
+            console.log(`  ${color(tty, C.bold, `Your ${usd(r.price.monthlyUsd)}/month ${name} plan`)} did ${color(tty, C.green, usd(r.listCostUsd))} of list-price work in the last 30 days${color(tty, C.gray, `${times}`)}`);
+            console.log(color(tty, C.gray, `              plan price: what you set${r.price.plan !== null && r.price.plan !== r.detected.plan ? ` (for ${r.price.plan}; the tool now reports ${r.detected.plan ?? 'no plan'})` : ''} · work: priced from the rate card${withheldNote(r)}`));
+        }
+        else if (r.detected.plan !== null) {
+            const hint = suggestedPrice(r.detected);
+            console.log(color(tty, C.gray, `  ${name} plan: ${usd(r.listCostUsd)} of list-price work${withheldNote(r)}. Compare it with what you pay: segreant plan set ${r.source} <dollars per month>${hint !== null ? ` (public price ${usd(hint)})` : ''}`));
+        }
+    }
+}
+/**
+ * Ask once, at the end of `scan --setup`, what the person pays for each plan a
+ * tool reports and no price is set for. Interactive terminals only: a script,
+ * a pipe or --json never waits. Enter skips; an answer is saved through the
+ * same validated path as `segreant plan set`. Returns how many were saved.
+ */
+export async function askPlanPrices(tty, io = {
+    input: process.stdin, output: process.stdout, interactive: process.stdin.isTTY === true,
+}) {
+    if (!io.interactive)
+        return 0;
+    const cfg = loadConfig();
+    const pending = detectPlans().filter((p) => p.plan !== null && cfg.plans[p.source] === undefined);
+    if (pending.length === 0)
+        return 0;
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: io.input, output: io.output, terminal: false });
+    let saved = 0;
+    try {
+        io.output.write(color(tty, C.bold, '  What do you pay for your plans?') + color(tty, C.gray, '   so Segreant can set the plan price beside the list-price work (Enter skips)') + '\n');
+        for (const p of pending) {
+            const hint = suggestedPrice(p);
+            const answer = (await rl.question(`    ${planName(p)}, dollars per month${hint !== null ? ` (public price ${hint})` : ''}: `)).trim().replace(/^\$/, '');
+            if (answer === '')
+                continue;
+            const monthlyUsd = Number(answer);
+            if (!Number.isFinite(monthlyUsd) || monthlyUsd < 0 || monthlyUsd > 100_000) {
+                io.output.write(color(tty, C.yellow, `      Not a dollar amount; skipped. Set it later: segreant plan set ${p.source} <dollars>`) + '\n');
+                continue;
+            }
+            mutateConfig((c) => ({ ...c, plans: { ...c.plans, [p.source]: { monthlyUsd, plan: p.plan, setAt: new Date().toISOString() } } }));
+            saved += 1;
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return saved;
+}
+export function cmdPlan(flags) {
+    const [action, tool, amount] = flags._.map(String);
+    if (action === 'set' || action === 'clear') {
+        if (tool === undefined || !PLAN_SOURCES.includes(tool)) {
+            throw new UserInputError(`Name the tool: segreant plan ${action} ${PLAN_SOURCES.join('|')}${action === 'set' ? ' <dollars per month>' : ''}`);
+        }
+        const source = tool;
+        const detected = detectPlans().find((p) => p.source === source);
+        if (action === 'set') {
+            if (amount === undefined)
+                throw new UserInputError(`Give the monthly price: segreant plan set ${source} 20`);
+            const monthlyUsd = Number(amount.replace(/^\$/, ''));
+            if (!Number.isFinite(monthlyUsd) || monthlyUsd < 0 || monthlyUsd > 100_000) {
+                throw new UserInputError('The price must be a dollar amount per month, for example 20.');
+            }
+            mutateConfig((cfg) => ({
+                ...cfg,
+                plans: { ...cfg.plans, [source]: { monthlyUsd, plan: detected.plan, setAt: new Date().toISOString() } },
+            }));
+            console.log(`  Saved: ${planName(detected) ?? TOOL_LABEL[source]} costs you ${usd(monthlyUsd)} a month.`);
+        }
+        else {
+            mutateConfig((cfg) => {
+                const plans = { ...cfg.plans };
+                delete plans[source];
+                return { ...cfg, plans };
+            });
+            console.log(`  Cleared the plan price for ${TOOL_LABEL[source]}.`);
+        }
+        return;
+    }
+    if (action !== undefined)
+        throw new UserInputError('Usage: segreant plan [set <tool> <dollars> | clear <tool>]');
+    const store = new Store(dbPath());
+    const { startMs, endMs } = rangeFor('month');
+    const rows = planComparisons(store, startMs, endMs);
+    store.close();
+    if (flags.json) {
+        printJson({ windowDays: 30, plans: rows, publicPricesChecked: PUBLIC_PLAN_PRICES_CHECKED });
+        return;
+    }
+    const tty = process.stdout.isTTY ?? false;
+    console.log('');
+    console.log(color(tty, C.bold, '  Plans') + color(tty, C.gray, '   read from each tool\'s own files · the price is only what you set'));
+    for (const r of rows) {
+        const name = planName(r.detected);
+        const price = r.price === null ? color(tty, C.gray, 'price not set') : `${usd(r.price.monthlyUsd)}/month (you set this ${r.price.setAt.slice(0, 10)})`;
+        console.log(`    ${TOOL_LABEL[r.source].padEnd(12)} ${(name ?? 'not detected').padEnd(18)} ${price}`);
+        console.log(color(tty, C.gray, `                 ${r.detected.evidence}${r.detected.billing ? ` · billed via ${r.detected.billing.replace(/_/g, ' ')}` : ''}`));
+    }
+    console.log('');
+    printPlanLines(tty, rows);
+    const unset = rows.filter((r) => r.price === null && r.detected.plan !== null);
+    if (unset.length > 0) {
+        console.log('');
+        console.log(color(tty, C.gray, `  Public prices (checked ${PUBLIC_PLAN_PRICES_CHECKED}) are only a hint: App Store billing, tax and annual plans change what you pay.`));
+    }
+    console.log('');
+}

package/dist/cli/pricingDeclareCmd.js

@@ -0,0 +1,178 @@
+/** User-declared model prices; historical request amounts remain unchanged. */
+import { existsSync } from 'node:fs';
+import { dbPath, isDemo } from '../config.js';
+import { modelNameError, PriceOverridesError, removePriceOverride, } from '../cost/overrides.js';
+import { declarePrice as declare, unknownModels } from '../cost/declarations.js';
+import { Store } from '../store/db.js';
+import { printJson, usd } from './ui.js';
+const NEXT_STEP = 'segreant reprice previews re-pricing recorded requests; nothing changes without --apply.';
+const SET_WAYS = 'Set a price: segreant pricing set <model> --input <usd> --output <usd> (USD per 1M tokens), --like <known-model>, or --free.';
+const PRICE_OPTIONS = ['input', 'output', 'cache-read', 'cache-write', 'cache-write-1h', 'like', 'free'];
+function priceInput(flags) {
+    // Read every form before choosing one, including cache-only mixtures.
+    const input = flags.input;
+    const output = flags.output;
+    const cacheRead = flags['cache-read'];
+    const cacheWrite = flags['cache-write'];
+    const cacheWrite1h = flags['cache-write-1h'];
+    const like = flags.like;
+    const free = flags.free;
+    const rate = [input, output, cacheRead, cacheWrite, cacheWrite1h].some((v) => v !== undefined);
+    if (Number(rate) + Number(like !== undefined) + Number(free !== undefined) !== 1) {
+        throw new PriceOverridesError('Choose exactly one price form: --input with --output, --like, or --free; do not mix them.');
+    }
+    if (free !== undefined) {
+        if (free !== true)
+            throw new PriceOverridesError('--free is a switch; give it no value.');
+        return { kind: 'free' };
+    }
+    if (like !== undefined) {
+        if (typeof like !== 'string')
+            throw new PriceOverridesError('--like needs an exact model name from the rate card.');
+        return { kind: 'like', like };
+    }
+    if (typeof input !== 'string' || typeof output !== 'string') {
+        throw new PriceOverridesError('A rate needs both --input <usd> and --output <usd> (USD per 1M tokens).');
+    }
+    if (cacheRead !== undefined && typeof cacheRead !== 'string')
+        throw new PriceOverridesError('--cache-read needs a decimal USD price per 1M tokens.');
+    if (cacheWrite !== undefined && typeof cacheWrite !== 'string')
+        throw new PriceOverridesError('--cache-write needs a decimal USD price per 1M tokens.');
+    if (cacheWrite1h !== undefined && typeof cacheWrite1h !== 'string')
+        throw new PriceOverridesError('--cache-write-1h needs a decimal USD price per 1M tokens.');
+    return {
+        kind: 'rate', input, output,
+        ...(cacheRead === undefined ? {} : { cacheRead }),
+        ...(cacheWrite === undefined ? {} : { cacheWrite }),
+        ...(cacheWrite1h === undefined ? {} : { cacheWrite1h }),
+    };
+}
+function storedLine(model, price) {
+    if (price.kind === 'free')
+        return `Stored user-declared price for ${model}: free ($0 per request).`;
+    if (price.kind === 'like')
+        return `Stored user-declared price for ${model}: like ${price.like} (exact rate-card model).`;
+    const cache = [
+        ...(price.cacheRead === undefined ? [] : [`cache-read $${price.cacheRead}`]),
+        ...(price.cacheWrite === undefined ? [] : [`cache-write $${price.cacheWrite}`]),
+        ...(price.cacheWrite1h === undefined ? [] : [`cache-write-1h $${price.cacheWrite1h}`]),
+    ];
+    // A cache price left out is not yours: it is the usual multiple of your
+    // input price. Say so where the price is stored (independent review,
+    // 2026-10-18), naming only the parts that were left out.
+    // --cache-write also prices 1-hour writes unless --cache-write-1h is given
+    // (declaredRate), so 2× is derived only when neither was (PR #150 review).
+    const derived = [
+        ...(price.cacheWrite === undefined ? ['5-minute cache writes at 1.25×'] : []),
+        ...(price.cacheWrite1h === undefined && price.cacheWrite === undefined ? ['1-hour cache writes at 2×'] : []),
+        ...(price.cacheRead === undefined ? ['cache reads at 0.1×'] : []),
+    ];
+    const note = derived.length
+        ? ` Not set, so priced at the usual multiple of your input price: ${derived.join(', ')} (set --cache-write, --cache-write-1h or --cache-read to give your own).`
+        : '';
+    return `Stored user-declared price for ${model}: input $${price.input}, output $${price.output}${cache.length ? `, ${cache.join(', ')}` : ''} (USD per 1M tokens).${note}`;
+}
+/** No ledger is created just to inspect historical usage. */
+function readLedger(empty, read) {
+    const path = dbPath();
+    if (!existsSync(path))
+        return empty;
+    // An existing ledger opens as every command opens it; a missing one is not created.
+    const store = new Store(path);
+    try {
+        return read(store);
+    }
+    finally {
+        store.close();
+    }
+}
+/** `flags._` includes the action. Input refusals are one line and exit 2. */
+export function cmdPricingDeclare(action, flags) {
+    try {
+        const allowed = new Set(['_', 'debug', 'help', 'demo', ...(action === 'set' ? PRICE_OPTIONS : action === 'unknown' ? ['json'] : [])]);
+        const unsupported = Object.keys(flags).find((k) => !allowed.has(k));
+        if (unsupported)
+            throw new PriceOverridesError(`--${unsupported} does nothing for segreant pricing ${action}.`);
+        if (action === 'unknown') {
+            if (flags._.length !== 1)
+                throw new PriceOverridesError('Usage: segreant pricing unknown [--json]');
+            const models = readLedger([], unknownModels);
+            if (flags.json) {
+                printJson({ models, costBasis: 'recorded cost (estimated)', nextStep: SET_WAYS, demo: isDemo() });
+            }
+            else {
+                if (isDemo())
+                    console.log('  DEMO DATA — synthetic requests.');
+                if (models.length === 0)
+                    console.log('  No unresolved models with recorded guessed prices.');
+                for (const r of models) {
+                    console.log(`  ${r.provider}  ${r.model}  ${r.requests} recorded requests  recorded cost (estimated): ${usd(r.costUsd)}  current match: ${r.rateMatchKind}`);
+                }
+                console.log(`  ${SET_WAYS}`);
+            }
+            return;
+        }
+        const model = flags._[1];
+        if (flags._.length !== 2 || model === undefined)
+            throw new PriceOverridesError(`Usage: segreant pricing ${action} <model>${action === 'set' ? ' --input <usd> --output <usd> | --like <known-model> | --free' : ''}`);
+        const error = modelNameError(model);
+        if (error)
+            throw new PriceOverridesError(error);
+        if (isDemo())
+            throw new PriceOverridesError('Demo mode only shows sample data; run without --demo to change a declared price.');
+        if (action === 'unset') {
+            console.log(removePriceOverride(model) ? `  Removed declared price for ${model}.` : `  No declared price for ${model}.`);
+            console.log(`  ${NEXT_STEP}`);
+            return;
+        }
+        const input = priceInput(flags);
+        const recorded = readLedger({ requests: 0, costUsd: 0 }, (store) => {
+            return store.byModel(Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER)
+                .filter((r) => r.label === model)
+                .reduce((total, r) => ({ requests: total.requests + r.requests, costUsd: total.costUsd + r.costUsd }), { requests: 0, costUsd: 0 });
+        });
+        const price = declare(model, input);
+        console.log(`  ${storedLine(model, price)}`);
+        console.log(`  ${recorded.requests} recorded requests use ${model}; recorded cost (estimated): ${usd(recorded.costUsd)}.`);
+        console.log(`  ${NEXT_STEP}`);
+    }
+    catch (error) {
+        if (!(error instanceof PriceOverridesError))
+            throw error;
+        console.error('  ' + error.message.replace(/[\r\n]+/g, ' '));
+        process.exitCode = 2;
+    }
+}
+/** Ask once per model name, with at most one retry; callers own terminal IO. */
+export async function promptForUnknownModels(models, io) {
+    const made = [];
+    for (const model of new Set(models.map((m) => m.model))) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const answer = (await io.ask(`price for ${model}? [Enter] skip  l <model> like another  p <in> <out> price per 1M  f free`)).trim();
+            if (answer === '' || answer === 's')
+                break;
+            const words = answer.split(/\s+/);
+            let input;
+            if (words[0] === 'f' && words.length === 1)
+                input = { kind: 'free' };
+            if (words[0] === 'l' && words.length === 2)
+                input = { kind: 'like', like: words[1] };
+            if (words[0] === 'p' && words.length === 3)
+                input = { kind: 'rate', input: words[1], output: words[2] };
+            try {
+                if (!input)
+                    throw new PriceOverridesError('Use Enter or s to skip, l <model>, p <in> <out>, or f.');
+                const price = declare(model, input);
+                made.push({ model, ...price });
+                io.print(`  ${storedLine(model, price)}`);
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof PriceOverridesError))
+                    throw error;
+                io.print(`  ${error.message.replace(/[\r\n]+/g, ' ')} ${attempt === 0 ? 'Try once more (Enter skips).' : 'Skipped.'}`);
+            }
+        }
+    }
+    return made;
+}

package/dist/cli/quotaCmd.js

@@ -0,0 +1,190 @@
+/**
+ * `segreant quota`: each vendor's own usage meter, read from its tool's logs,
+ * the pace to the next reset, and whether the meter moves in step with what
+ * Segreant counted. It reads what the last import or status-line reading
+ * stored; `segreant import all` refreshes it.
+ */
+import { Store } from '../store/db.js';
+import { dbPath } from '../config.js';
+import { quotaView, median } from '../quota/view.js';
+import { statuslineLine } from '../quota/statusline.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { detectPlans, planName } from '../plans/detect.js';
+import { C, color, usd, printJson } from './ui.js';
+const DAY = 86_400_000;
+function when(ms, nowMs) {
+    const d = new Date(ms);
+    const sameDay = new Date(nowMs).toDateString() === d.toDateString();
+    const time = d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+    return sameDay ? `today ${time}` : `${d.toLocaleDateString([], { weekday: 'short' })} ${time}`;
+}
+function inFor(ms, nowMs) {
+    const mins = Math.max(0, Math.round((ms - nowMs) / 60_000));
+    if (mins < 60)
+        return `${mins}m`;
+    const h = Math.floor(mins / 60);
+    return h < 48 ? `${h}h ${mins % 60}m` : `${Math.round(h / 24)}d`;
+}
+function windowLabel(w) {
+    if (w.windowMinutes === 300)
+        return '5-hour';
+    if (w.windowMinutes === 10_080)
+        return 'weekly';
+    return w.windowMinutes === null ? 'window' : `${Math.round(w.windowMinutes / 60)}-hour`;
+}
+const STATUSLINE_ABOUT = `  Claude Code then hands Segreant its live usage meter (5-hour and weekly percentages)
+  each time the status line refreshes. Segreant records a reading when it changes and
+  prints one short line. Nothing leaves your machine; segreant quota shows the history.`;
+/**
+ * The setup text for THIS install. It used to name the bare
+ * segreant-statusline command, which exists only after a global install;
+ * after a local install or npx, Claude Code ran a command that was not there
+ * (H012). It now names the installed file by its absolute path, run with node,
+ * so nothing has to be on PATH. Under npx the package lives in a cache that
+ * can be cleared, so it asks for a lasting install first.
+ *
+ * `launcher` is bin/segreant.mjs as started: process.argv[1] in the runtime
+ * child, which the launcher spawns with its own real path, never the snapshot.
+ */
+export function statuslineSetupText(launcher) {
+    const bin = launcher ? join(dirname(launcher), 'segreant-statusline.mjs').replace(/\\/g, '/') : null;
+    if (bin === null || /[\\/]_npx[\\/]/.test(launcher)) {
+        return `  Segreant is running from npx's temporary cache, which can be cleared at any time.
+  Install it so the status line has a file that stays put:
+
+    npm install -g segreant
+
+  then run  segreant statusline --setup  again for the exact line to add.`;
+    }
+    const command = `node "${bin}"`;
+    return `  Add this to ~/.claude/settings.json (or merge it into an existing statusLine):
+
+    "statusLine": ${JSON.stringify({ type: 'command', command })}
+
+  It runs the installed file directly, so nothing has to be on PATH.
+${STATUSLINE_ABOUT}`;
+}
+/**
+ * `segreant statusline`: the same lean path as the `segreant-statusline` bin
+ * (src/quota/statusline.ts), reachable through the full CLI for convenience.
+ * The bin is what the setup snippet names, because it starts far faster.
+ */
+export function cmdStatusline(flags) {
+    if (flags.setup) {
+        console.log(statuslineSetupText(process.argv[1]));
+        return;
+    }
+    let raw = '';
+    try {
+        raw = readFileSync(0, 'utf8').slice(0, 1_000_000);
+    }
+    catch {
+        raw = '';
+    }
+    process.stdout.write(statuslineLine(dbPath(), raw, Date.now()) + '\n');
+}
+export function cmdQuota(flags) {
+    const store = new Store(dbPath());
+    const now = Date.now();
+    const events = store.quotaEvents(now - 35 * DAY);
+    const view = quotaView(events, (source, a, b) => store.sourceCostBetween(source, a, b), now);
+    store.close();
+    if (flags.json) {
+        printJson({ generatedAtMs: now, ...view });
+        return;
+    }
+    const tty = process.stdout.isTTY ?? false;
+    const plans = new Map(detectPlans().map((p) => [p.source, planName(p)]));
+    console.log('');
+    console.log(color(tty, C.bold, '  Quota') + color(tty, C.gray, "   the vendors' own meters, read from their tools' logs · refresh with segreant import all"));
+    console.log('');
+    console.log(color(tty, C.bold, `  Codex${plans.get('codex') ? ` (${plans.get('codex')})` : ''}`));
+    if (view.codex === null) {
+        console.log(color(tty, C.gray, '    No rate-limit readings in the Codex logs yet.'));
+    }
+    else {
+        for (const w of view.codex.windows) {
+            const label = windowLabel(w).padEnd(7);
+            if (w.reset) {
+                console.log(`    ${label} ${color(tty, C.gray, `reset at ${when(w.resetsAtMs, now)}; no use logged since, so no current reading`)}`);
+                continue;
+            }
+            const resets = w.resetsAtMs === null ? '' : ` · resets ${when(w.resetsAtMs, now)} (in ${inFor(w.resetsAtMs, now)})`;
+            const tone = w.usedPercent >= 90 ? C.red : w.usedPercent >= 70 ? C.yellow : C.green;
+            console.log(`    ${label} ${color(tty, tone, `${Math.round(w.usedPercent)}% used`)}${resets}${color(tty, C.gray, ` · read ${when(w.asOfMs, now)}`)}`);
+            if (w.limitAtMs !== null && w.limitAtMs <= now) {
+                console.log(color(tty, C.yellow, `            at the pace of that reading the limit was due ${when(w.limitAtMs, now)}; nothing has been logged since, so whether it was reached is not known yet`));
+            }
+            else if (w.limitAtMs !== null) {
+                console.log(color(tty, C.yellow, `            at this pace you reach the limit ${when(w.limitAtMs, now)} (estimate: the pace since the window opened)`));
+            }
+            else if (w.projectedAtResetPercent !== null) {
+                console.log(color(tty, C.gray, `            at this pace: about ${Math.round(w.projectedAtResetPercent)}% by the reset (estimate)`));
+            }
+        }
+        const m = view.codex.weekly;
+        if (m.currentUsdPerPercent !== null) {
+            const earlier = median(m.earlierUsdPerPercent);
+            const line = `    Segreant counted ${usd(m.currentUsdPerPercent)} of list-price work per 1% of the weekly meter this week`
+                + (earlier === null ? '' : `; ${usd(earlier)} per 1% in earlier weeks (median of ${m.earlierUsdPerPercent.length})`);
+            console.log(color(tty, C.gray, line));
+            if (m.agrees === false) {
+                console.log(color(tty, C.yellow, '    The meter and the count disagree beyond 1.5x this week. Both figures are above; the vendor may weight models or caching differently from list price.'));
+            }
+            else if (m.agrees === true) {
+                console.log(color(tty, C.gray, '    The meter moves in step with what Segreant counted.'));
+            }
+        }
+    }
+    console.log('');
+    console.log(color(tty, C.bold, `  Claude Code${plans.get('claude-code') ? ` (${plans.get('claude-code')})` : ''}`));
+    const c = view.claude;
+    if (c === null) {
+        console.log(color(tty, C.gray, '    No Claude Code use or limit messages in the last 35 days.'));
+    }
+    else {
+        if (view.claudeWindows.length > 0) {
+            for (const w of view.claudeWindows) {
+                const label = (w.kind === 'claude_spend_window' ? 'spend' : windowLabel(w)).padEnd(7);
+                if (w.reset) {
+                    console.log(`    ${label} ${color(tty, C.gray, `reset at ${when(w.resetsAtMs, now)}; no reading since`)}`);
+                    continue;
+                }
+                const resets = w.resetsAtMs === null ? '' : ` · resets ${when(w.resetsAtMs, now)} (in ${inFor(w.resetsAtMs, now)})`;
+                const tone = w.usedPercent >= 90 ? C.red : w.usedPercent >= 70 ? C.yellow : C.green;
+                console.log(`    ${label} ${color(tty, tone, `${Math.round(w.usedPercent)}% used`)}${resets}${color(tty, C.gray, ` · read ${when(w.asOfMs, now)} from the status line`)}`);
+                if (w.limitAtMs !== null && w.limitAtMs > now) {
+                    console.log(color(tty, C.yellow, `            at this pace you reach the limit ${when(w.limitAtMs, now)} (estimate: the pace since the window opened)`));
+                }
+            }
+        }
+        else {
+            console.log(color(tty, C.gray, '    Claude Code logs no percentage; it logs a message when a limit is reached. For the live percentage, set segreant as'));
+            console.log(color(tty, C.gray, '    your Claude Code status line (segreant statusline --setup shows how), or see claude.ai/settings/usage.'));
+        }
+        const parts = [
+            `the session limit ${c.sessionHits} time${c.sessionHits === 1 ? '' : 's'}`,
+            `the weekly limit ${c.weeklyHits} time${c.weeklyHits === 1 ? '' : 's'}`,
+            ...(c.spendHits > 0 ? [`the monthly spend limit ${c.spendHits} time${c.spendHits === 1 ? '' : 's'}`] : []),
+        ];
+        console.log(`    Last 35 days: you reached ${parts.join(', ')}.`);
+        if (c.lastHit !== null) {
+            const reset = c.lastHit.resetsAtMs === null ? '' : `, reset ${when(c.lastHit.resetsAtMs, now)}`;
+            console.log(color(tty, C.gray, `    Last: ${when(c.lastHit.tsEpochMs, now)}${reset} ("${c.lastHit.detail ?? ''}")`));
+        }
+        const before = c.usdBeforeSessionHit.filter((x) => x > 0);
+        const med = median(before);
+        if (med !== null) {
+            const lo = Math.min(...before);
+            const hi = Math.max(...before);
+            console.log(`    Before a session-limit message, the 5 hours held ${usd(lo)}–${usd(hi)} of list-price work (median ${usd(med)}).`);
+            const share = Math.round((c.lastFiveHoursUsd / med) * 100);
+            console.log(color(tty, C.gray, `    The last 5 hours: ${usd(c.lastFiveHoursUsd)}, about ${share}% of that median (estimate: the window's real start is not logged).`));
+        }
+        else {
+            console.log(color(tty, C.gray, `    The last 5 hours: ${usd(c.lastFiveHoursUsd)} of list-price work.`));
+        }
+    }
+    console.log('');
+}