segreant 0.1.0 → 0.2.0

package/dist/cli/valueCmd.js

@@ -11,7 +11,7 @@ import { loadConfig, mutateConfig, dbPath, isDemo } from '../config.js';
 import { isGitRepo, projectName, resolveCommit } from '../git/correlate.js';
 import { computeArtifactPersistence } from '../git/quality.js';
 import { contributionEvidenceLines, summarizeContributionEvidence } from '../git/contribution.js';
-import { loadRealization } from '../value/realization.js';
+import { loadRealization, keptSummary, CLI_PERIOD_DAYS, CLI_GIT_BUDGET_MS } from '../value/realization.js';
 import { WORK_WEEK_MINUTES } from '../value/timeReclaimed.js';
 import { computeFrontier } from '../value/frontier.js';
 // The value report's one composition — shared with the dashboard's '/api/value'.
@@ -25,6 +25,87 @@ import { describeDriftReading, driftReading } from '../value/drift.js';
 import { C, color, usd, num, pct, gateGlyph, noteSource, printNotAGitRepo, printJson } from './ui.js';
 import {} from './flags.js';
 import { retentionNotice } from './retention.js';
+/**
+ * With no request recorded there is no AI spend for git history to be measured
+ * against. The value commands used to walk every commit of the last 90 days
+ * anyway (54-87 s on a real repository) and then print 0% realized, an RoI of
+ * 0 and $0.00 per commit: a zero where the honest answer is "nothing to
+ * measure yet". Returns true when it has answered for the caller.
+ */
+async function answeredNothingSpent(store, flags, repo) {
+    if (store.earliestRequestMs() !== null)
+        return false;
+    // A path that is not a repository is the user's real problem, and the
+    // command's own check reports it with a failing status; answering "nothing
+    // spent" first hid that behind exit 0 (PR #131 review).
+    if (!(await isGitRepo(repo)))
+        return false;
+    // No surviving request is not "nothing spent" once retention has pruned
+    // rows or a realization snapshot is stored: the stored report is the answer
+    // then, and the command must reach it (review 4, F2).
+    if (store.retentionFloor().requestsPrunedBeforeMs !== null || store.countRealizationUnits() > 0)
+        return false;
+    const next = ['segreant scan --setup', 'segreant demo --serve'];
+    if (flags.json) {
+        printJson({ status: 'no_spend_recorded', measured: false, next });
+    }
+    else {
+        const tty = process.stdout.isTTY ?? false;
+        console.log('');
+        console.log('  No AI spend is recorded yet, so there is nothing to measure against this repository.');
+        console.log(color(tty, C.gray, `  Import what your tools already logged:  ${next[0]}`));
+        console.log(color(tty, C.gray, `  Or see every figure on sample data:     ${next[1]}`));
+        console.log('');
+    }
+    store.close();
+    return true;
+}
+/**
+ * The budget decision in two sentences: whether the evidence shows the
+ * recommended cap doing better than the current one, and where the full record
+ * is. The record itself (renderBudgetCapDecision) stays one flag away.
+ */
+function plainCapVerdict(decision, canonical, soft) {
+    const label = (capUsd) => (capUsd === null || capUsd === undefined ? 'no cap' : usd(capUsd));
+    const recommendedCap = decision.actions.find((a) => a.action === 'apply_recommended')?.capUsd;
+    const currentCap = decision.actions.find((a) => a.action === 'keep_current')?.capUsd;
+    const recommended = label(recommendedCap);
+    const current = label(currentCap);
+    // Equal caps are one setting, not two options: there is nothing to compare,
+    // and blaming partly observed days for "no winner" would be a false reason
+    // (PR #142 review).
+    // The soft warning is part of the recommendation too: an equal daily cap
+    // with a different soft warning is a change, and is said as one (PR #145 review).
+    if (recommendedCap !== null && recommendedCap !== undefined && recommendedCap === currentCap) {
+        const first = soft.current === soft.recommended
+            ? `  Your current ${current} cap and ${usd(soft.recommended)} soft warning already match the recommendation; nothing to change.`
+            : `  Your current ${current} daily cap already matches the recommendation. Only the soft warning differs: recommended ${usd(soft.recommended)}, yours is ${soft.current === null ? 'off' : usd(soft.current)}.`;
+        return [first, '  Full decision record: segreant budget --recommend --detail'];
+    }
+    const certificate = canonical.certificateBundle.dominance;
+    const currentPhrase = current === 'no cap' ? 'having no cap' : `your current ${current}`;
+    const verdict = certificate.status === 'proven_dominant'
+        ? certificate.action === 'apply_recommended'
+            ? `  On this evidence the recommended ${recommended} cap does better than ${currentPhrase}.`
+            : `  On this evidence ${currentPhrase} does better than the recommended ${recommended} cap.`
+        : `  Is ${recommended} better than ${currentPhrase}? Not shown: which days' spend was kept is only partly observed, so neither is proven better.`;
+    return [verdict, '  Full decision record, with each assumption and what would settle it: segreant budget --recommend --detail'];
+}
+/** The last line of the budget advice when nothing is applied: why, in the reader's terms. */
+export function budgetClosingLine(applyPermitted, dominance, sameCap = null) {
+    if (sameCap?.softMatches)
+        return '  No change needed: your config already has this cap and soft warning.';
+    if (sameCap)
+        return `  Daily cap unchanged. To set only the soft warning: segreant budget --soft ${sameCap.softRecommended.toFixed(2)}`;
+    if (applyPermitted)
+        return '  Re-run with --apply to write these to your config.';
+    if (dominance?.status === 'proven_dominant' && dominance.action === 'apply_recommended') {
+        return '  No cap written: the evidence favours the new cap, but its inputs are not verified enough to change spend. --detail lists what is missing.';
+    }
+    if (dominance?.status === 'proven_dominant')
+        return '  No cap written: on this evidence your current setting does better.';
+    return '  No cap written: --apply needs evidence that the new cap does better, and this data does not show it. --detail lists what is missing.';
+}
 export async function cmdYield(flags) {
     const repo = flags.repo ?? process.cwd();
     const limit = flags.limit ? Number(flags.limit) : 30;
@@ -35,6 +116,8 @@ export async function cmdYield(flags) {
         return;
     }
     const store = new Store(dbPath());
+    if (await answeredNothingSpent(store, flags, repo))
+        return;
     const report = await computeArtifactPersistence(store, repo, { limit, windowDays, persist: true });
     if (flags.json) {
         printJson(report);
@@ -52,15 +135,25 @@ export async function cmdYield(flags) {
         console.log(color(tty, C.gray, '  Recent commits below are provisional (retention still settling).'));
     }
     else {
-        const yieldStr = m.aiYield === null ? 'n/a (no AI cost attributed)' : `${m.aiYield.toFixed(1)} retained lines / $`;
+        const withheld = m.aiYield === null && m.spendWindowTruncatedCommits > 0;
+        const yieldStr = m.aiYield !== null
+            ? `${m.aiYield.toFixed(1)} retained lines / $`
+            : withheld ? 'withheld (retention deleted the spend records)' : 'n/a (no AI cost attributed)';
         console.log(`  Retained lines / $  ${color(tty, C.green, yieldStr)}`);
         console.log(`  Effective spend     ${m.effectiveSpendRatio === null ? '—' : color(tty, m.effectiveSpendRatio > 0.5 ? C.green : C.yellow, pct(m.effectiveSpendRatio))}   ${color(tty, C.gray, 'of $ associated with retained artifacts')}`);
         console.log(`  Artifact retention   ${color(tty, m.survivalRatio > 0.7 ? C.green : C.yellow, pct(m.survivalRatio))}   ${color(tty, C.gray, `non-retained ${pct(m.churnRatio)}`)}`);
         console.log(`  Revert rate         ${color(tty, m.revertRate < 0.05 ? C.green : C.red, pct(m.revertRate))}`);
-        console.log(`  AI cost (matured)   ${usd(m.totalCostUsd)}   ${color(tty, C.gray, `${num(m.survivingLines)} retained lines`)}`);
+        const costScope = m.spendWindowTruncatedCommits > 0
+            ? `${num(m.survivingLines)} retained lines · excludes ${m.spendWindowTruncatedCommits} commit(s) with pruned spend`
+            : `${num(m.survivingLines)} retained lines`;
+        console.log(`  AI cost (matured)   ${usd(m.totalCostUsd)}   ${color(tty, C.gray, costScope)}`);
         if (m.costPerSurvivingLine !== null) {
             console.log(`  Cost / retained line ${usd(m.costPerSurvivingLine)}`);
         }
+        if (m.spendWindowTruncatedCommits > 0) {
+            console.log(color(tty, C.yellow, `  ● ${m.spendWindowTruncatedCommits} matured commit(s) lost spend records to retention inside their window.`));
+            console.log(color(tty, C.yellow, '    What remains understates what that work cost, so they are left out of AI cost and every per-dollar figure.'));
+        }
     }
     console.log('');
     console.log(color(tty, C.bold, '  Per commit'));
@@ -73,10 +166,12 @@ export async function cmdYield(flags) {
         const yld = c.aiYield === null ? '—' : c.aiYield.toFixed(0);
         const status = c.reverted
             ? color(tty, C.red, 'REVERTED')
-            : c.maturing
-                ? color(tty, C.yellow, 'maturing')
-                : color(tty, C.green, 'matured');
-        console.log(`  ${short}  ${age.padStart(4)}  ${usd(c.attributedCostUsd).padStart(9)}  ${String(c.linesAdded).padStart(6)}  ${surv.padStart(9)}  ${churn.padStart(5)}  ${yld.padStart(5)}   ${status}`);
+            : c.spendWindowTruncated !== false
+                ? color(tty, C.yellow, 'spend pruned')
+                : c.maturing
+                    ? color(tty, C.yellow, 'maturing')
+                    : color(tty, C.green, 'matured');
+        console.log(`  ${short}  ${age.padStart(4)}  ${(c.spendWindowTruncated !== false ? 'pruned' : usd(c.attributedCostUsd)).padStart(9)}  ${String(c.linesAdded).padStart(6)}  ${surv.padStart(9)}  ${churn.padStart(5)}  ${yld.padStart(5)}   ${status}`);
     }
     console.log('');
     console.log(color(tty, C.gray, '  Retained lines ÷ AI cost is an artifact-persistence lens, not code quality —'));
@@ -84,12 +179,75 @@ export async function cmdYield(flags) {
     console.log('');
     store.close();
 }
+/**
+ * The first answer a person wants, from git alone: of the AI work that became
+ * commits, how much is still in the code. Printed before the Standard, which
+ * needs more gates to call anything realized. Every figure is list cost.
+ */
+function printKeptAnswer(tty, report) {
+    const k = keptSummary(report);
+    const total = k.kept.units + k.notKept.units + k.contested.units + k.unknown.units + k.maturing.units;
+    if (total === 0)
+        return;
+    const days = report.windowDays;
+    const row = (label, b, what, tone) => {
+        if (b.units === 0)
+            return;
+        console.log(`    ${color(tty, C.bold, label.padEnd(10))} ${color(tty, tone, usd(b.costUsd).padStart(10))}  ${String(b.units).padStart(4)} commit${b.units === 1 ? ' ' : 's'}  ${color(tty, C.gray, what)}`);
+    };
+    console.log('');
+    console.log(color(tty, C.bold, '  Did the AI work stay in the code?') + color(tty, C.gray, '   from git history · list cost (estimate), not your bill'));
+    row('Kept', k.kept, `most of its lines are still in the code after ${days} days, and no tracked check failed`, C.green);
+    row('Not kept', k.notKept, 'most of its lines were rewritten or removed, or it was reverted', C.yellow);
+    row('Disputed', k.contested, 'the checks disagreed, and nothing failed outright; not settled either way', C.gray);
+    row('Unknown', k.unknown, 'not measured in this run (the git time budget ran out)', C.gray);
+    const due = k.maturing.nextVerdictMs === null ? '' : `; first verdict ${new Date(k.maturing.nextVerdictMs).toISOString().slice(0, 10)}`;
+    row('Maturing', k.maturing, `younger than ${days} days${due}`, C.gray);
+    const c = report.periodCoverage;
+    if (c !== undefined) {
+        const days90 = Math.round((c.periodEndMs - c.periodStartMs) / 86_400_000);
+        const off = c.beforeOldestUsd + c.noCommitFollowedUsd + c.notCommittedYetUsd;
+        const share = c.scopedCostUsd > 0 ? Math.round((c.onCommitsUsd / c.scopedCostUsd) * 100) : 0;
+        console.log(color(tty, C.gray, `    ${share}% of this repository's ${usd(c.scopedCostUsd)} over the last ${days90} days is on a commit above.`));
+        if (off > 0.005) {
+            const parts = [];
+            if (c.noCommitFollowedUsd > 0.005)
+                parts.push(`${usd(c.noCommitFollowedUsd)} no commit followed within 8 hours`);
+            if (c.beforeOldestUsd > 0.005)
+                parts.push(`${usd(c.beforeOldestUsd)} before the oldest commit measured`);
+            if (c.notCommittedYetUsd > 0.005)
+                parts.push(`${usd(c.notCommittedYetUsd)} not committed yet`);
+            console.log(color(tty, C.gray, `    Not on a commit: ${parts.join(' · ')}.`));
+        }
+    }
+    const s = report.spendScope;
+    if (s !== undefined) {
+        const moved = s.linkedFolders.filter((f) => f.reason === 'moved').length;
+        const worktrees = s.linkedFolders.filter((f) => f.reason === 'worktree' || f.reason === 'clone').length;
+        const extra = [
+            `${s.linkedSessions} agent session${s.linkedSessions === 1 ? '' : 's'}`,
+            ...(moved > 0 ? [`${moved} earlier location${moved === 1 ? '' : 's'} of this checkout`] : []),
+            ...(worktrees > 0 ? [`${worktrees} other checkout${worktrees === 1 ? '' : 's'} (worktrees, clones)`] : []),
+        ];
+        console.log(color(tty, C.gray, `    Includes ${extra.join(', ')}, linked by ${s.verifiedObservations} commits git confirmed they made.`));
+    }
+}
 export async function cmdRealize(flags) {
     const repo = flags.repo ?? process.cwd();
-    const limit = flags.limit ? Number(flags.limit) : 30;
+    const limit = flags.limit ? Number(flags.limit) : undefined;
     const windowDays = flags.window ? Number(flags.window) : 14;
     const store = new Store(dbPath());
-    const loaded = await loadRealization(store, repo, { limit, windowDays, persist: true });
+    if (await answeredNothingSpent(store, flags, repo))
+        return;
+    // Without --limit: every commit of the last 90 days, so the answer covers
+    // the same period the spend does.
+    const loaded = await loadRealization(store, repo, {
+        limit,
+        windowDays,
+        persist: true,
+        sinceDays: limit === undefined ? CLI_PERIOD_DAYS : undefined,
+        gitScanBudgetMs: CLI_GIT_BUDGET_MS,
+    });
     if (!loaded) {
         printNotAGitRepo(repo);
         process.exitCode = 1;
@@ -105,6 +263,7 @@ export async function cmdRealize(flags) {
     const tty = process.stdout.isTTY ?? false;
     const m = report.matured;
     const wiredGates = GATE_LADDER.filter((g) => m.instrumentation[g] > 0).length;
+    printKeptAnswer(tty, report);
     console.log('');
     console.log(color(tty, C.bold, '  The Realization Standard — did AI spend become real outcomes?'));
     console.log(color(tty, C.gray, `  ${m.units} matured units (older than ${windowDays}d) · ${wiredGates} of ${GATE_LADDER.length} gates instrumented`));
@@ -339,6 +498,8 @@ export async function cmdRoi(flags) {
     const windowDays = flags.window ? Number(flags.window) : 14;
     const cfg = loadConfig();
     const store = new Store(dbPath());
+    if (await answeredNothingSpent(store, flags, repo))
+        return;
     // The whole composition — realization, this project's resolved baseline, the
     // Lift source, the money inputs, RoI, the drift streams, sensitivity — is one
     // sequence in src/value/report.ts, shared with `/api/value`. The three inputs
@@ -353,6 +514,8 @@ export async function cmdRoi(flags) {
         repo,
         windowDays,
         persist: true,
+        sinceDays: CLI_PERIOD_DAYS,
+        gitScanBudgetMs: CLI_GIT_BUDGET_MS,
         laborRatePerHour: flags['labor-rate'] !== undefined ? Number(flags['labor-rate']) : undefined,
         tsfUpperBound: flags.tsf !== undefined ? Number(flags.tsf) : undefined,
         riskAversion: flags['risk'] !== undefined ? Number(flags['risk']) : 0,
@@ -644,7 +807,13 @@ export async function cmdBudgetAdvisor(flags) {
         console.log(color(tty, C.gray, `  · ${r}`));
     if (decision) {
         console.log('');
-        for (const line of renderBudgetCapDecision(decision, certificates, canonicalDecision))
+        // The full record (certificate, assurance level, every unmet input claim)
+        // is for an auditor; printed by default it buried the answer under internal
+        // claim ids and read as contradicting the recommendation above it.
+        const lines = flags.detail
+            ? renderBudgetCapDecision(decision, certificates, canonicalDecision)
+            : plainCapVerdict(decision, canonicalDecision, { current: cfg.budget.dailySoftUsd, recommended: softCap });
+        for (const line of lines)
             console.log(color(tty, C.gray, line));
     }
     // Raw allocation and frontier trim/grow hints are withheld from this surface
@@ -676,9 +845,11 @@ export async function cmdBudgetAdvisor(flags) {
     }
     else {
         console.log('');
-        console.log(color(tty, C.gray, decision && applyPermitted
-            ? '  Re-run with --apply to write these to your config.'
-            : '  No cap written. Applying a recommendation requires a certified DecisionCertificate with DAL-3 assurance; the decision block above says what is missing.'));
+        // Three different reasons, said differently: the evidence picks no winner,
+        // it picks the current cap, or it picks the new cap but its inputs are not
+        // verified enough to change spend (PR #142 review).
+        const dominance = canonicalDecision?.certificateBundle.dominance;
+        console.log(color(tty, C.gray, budgetClosingLine(decision !== null && applyPermitted, dominance ?? null, cfg.budget.dailyUsd === dailyCap ? { softRecommended: softCap, softMatches: cfg.budget.dailySoftUsd === softCap } : null)));
     }
     console.log('');
     store.close();
@@ -687,7 +858,11 @@ export async function cmdFrontier(flags) {
     const repo = flags.repo ?? process.cwd();
     const windowDays = flags.window ? Number(flags.window) : 14;
     const store = new Store(dbPath());
-    const loaded = await loadRealization(store, repo, { windowDays, persist: true });
+    if (await answeredNothingSpent(store, flags, repo))
+        return;
+    const loaded = await loadRealization(store, repo, {
+        windowDays, persist: true, sinceDays: CLI_PERIOD_DAYS, gitScanBudgetMs: CLI_GIT_BUDGET_MS,
+    });
     if (!loaded) {
         printNotAGitRepo(repo);
         process.exitCode = 1;

package/dist/cli.js

@@ -10,9 +10,11 @@
  *   segreant prune            prune old rows and compact the database
  */
 import './util/quiet.js';
-import { demoDbPath, envOverrideKey } from './config.js';
+import { join } from 'node:path';
+import { demoDbPath, envOverrideKey, segreantHome } from './config.js';
 import { packageVersion } from './version.js';
-import { parseFlags, UserInputError } from './cli/flags.js';
+import { configureSurvivalStore } from './git/survivalStore.js';
+import { parseFlags, trackFlags, suggestOption, UserInputError } from './cli/flags.js';
 // Command modules load on demand. Importing every command up front cost about
 // two seconds on every invocation, `--help` included; a command now pays only
 // for its own module graph. All specifiers are literal, so the import-closure
@@ -29,6 +31,9 @@ const causalCmd = () => import('./cli/causalCmd.js');
 const capitalCmd = () => import('./cli/capitalCmd.js');
 const opsCmd = () => import('./cli/opsCmd.js');
 const showCmd = () => import('./cli/showCmd.js');
+const planCmd = () => import('./cli/planCmd.js');
+const homeCmd = () => import('./cli/homeCmd.js');
+const quotaCmd = () => import('./cli/quotaCmd.js');
 const runCmd = () => import('./cli/runCmd.js');
 const launchCmd = () => import('./cli/launchCmd.js');
 const backupCmd = () => import('./cli/backupCmd.js');
@@ -51,13 +56,17 @@ function cmdHelpShort() {
   Usage: segreant <command> [options]
 
   Get started
-    guide                 Where you are and the single next step (bare "segreant")
+    (no command)          This month, your plans, what stayed in the code, and the next step
+    guide                 Where you are and the single next step
     scan                  Find the AI tools and git repos on this machine and preview
                           a setup plan; --setup imports and correlates them
     demo --serve          Every screen on clearly-labeled synthetic data, no API key
 
   Every day
     today | week | month  Spend for a window                        (--json)
+    plan                  Your plans, what you pay, and the work they did  (set <tool> <usd>)
+    quota                 The vendors' usage meters, pace to reset, and Segreant's count  (--json)
+    statusline            Claude Code status line: records its live usage meter (--setup shows how)
     start                 Start the proxy and the local dashboard
     launch -- <command>   Run a tool metered through the proxy while it runs
     budget                Set caps: --daily N --soft N --session N --runaway N
@@ -76,15 +85,18 @@ function cmdHelp() {
   Usage: segreant <command> [options]
 
   Commands
+    (no command)          Bare "segreant": this month, your plans, how much of the
+                          AI work stayed in the code, and the next step
     guide                 Where you are + the single next step, read from your
-                          actual state — also what bare "segreant" shows (--json)
+                          actual state — the full checklist (--json)
     start                 Start the proxy + local dashboard
     egress                Inspect/verify Segreant-process egress; plan exact cloud
                           rules without mutation, then persist only with:
                           egress apply --apply --mode controlled_cloud
                           (--id, --purpose, --data-class, --method, --origin,
-                          --path-prefix). Default local_locked permits literal
-                          loopback only; this is not a machine-wide firewall.
+                          --path-prefix). Built in: loopback, the public price
+                          list and the official OpenAI/Anthropic APIs. This is
+                          not a machine-wide firewall.
     causal                Retained randomized-study evidence: status, inspect,
                           replay verification, and review-only OPE from the
                           Store-owned action log. V1 is inspect-only; all causal
@@ -101,6 +113,10 @@ function cmdHelp() {
                           commitment, consumption, showback, opportunity and
                           policy-relative fairness; no chargeback or action.
     today | week | month  Show spend for a window      (--json)
+    plan                  Plans, prices you set, and the list-price work they did
+    quota                 Vendor usage meters and the pace to their reset
+    statusline            Claude Code status line: records its live usage meter
+                          on every refresh (--setup prints the line to add)
     economic              Inspect exact economic events, roles, bases, and legacy coverage
                           (--days N | --all, --target-currency UNIT, --as-of <ISO>,
                           --effective-at <ISO>, --json). Period controls use canonical
@@ -116,11 +132,18 @@ function cmdHelp() {
                           recipe). No tool lists the connectors.
     import <tool|all>     NATIVE metering, no routing: read the usage a tool
                           already logs locally — works on subscriptions the proxy
-                          can never see. Tools: claude-code, opencode, codex (or
-                          all). Idempotent. --watch keeps it live (poll every N
+                          can never see. Tools: claude-code, opencode, codex,
+                          antigravity (or all). Idempotent. --watch keeps it live (poll every N
                           sec: --every N). Files unchanged since their last full
                           import are skipped; --rescan reads them again.
                           (--root <dir>, --days N, --json)
+    alloc <action>        Cost-centre allocation: who has DECIDED owns the money.
+                          alloc centre <id> --name N [--owner O]; alloc rule <id>
+                          --method direct|fixed_split|proportional_to_direct
+                          --centre C --match-project P; alloc run --from <date>
+                          --to <date> previews a split, --apply records it (--json).
+                          alloc centres | rules | runs list them; alloc revoke <id>
+                          closes a rule; alloc export <run-id> --out <csv>.
     billing <action>     Import, inspect, or export LOCAL operator-supplied
                           provider billing evidence. V1 accepts a strict OpenAI
                           evidence JSON only; it never overwrites metered estimates
@@ -199,7 +222,7 @@ function cmdHelp() {
                           --include-imported on|off: whether imported subscription
                           spend counts toward cap ENFORCEMENT (default off — the
                           cap governs live proxy traffic, the spend it can block)
-    budget --recommend    Suggest a value-aware budget from usage + realized value
+    budget --recommend    Suggest a value-aware budget from usage + realized value (--detail: full decision record)
                           (--repo <path> for value-based, --apply to write, --json)
     budget --control      Evaluate one bounded autonomous daily-cap control step
                           from a versioned JSON policy (--policy <file>, --repo <path>,
@@ -226,6 +249,15 @@ function cmdHelp() {
                           when stale; --auto off to disable)
                           Evidence: pricing --coverage [--days N|--all] (--json;
                           read-only historical card/match cohorts)
+                          Declare: pricing set <model> --input <usd> --output <usd>
+                            [--cache-read <usd>] [--cache-write <usd>]
+                            [--cache-write-1h <usd>] (USD per 1M tokens)
+                          Or: pricing set <model> --like <known-model>
+                          Or: pricing set <model> --free (user-declared local price)
+                          Remove: pricing unset <model>
+                          Still need a price: pricing unknown [--json]
+                          Declarations leave recorded cost unchanged; segreant reprice
+                          previews changes, --apply writes them.
     reprice               Re-cost rows that were priced with a fallback estimate,
                           using the current rate card — only rows the card now
                           resolves EXACTLY are rewritten; remaining estimates are
@@ -268,13 +300,11 @@ function cmdHelp() {
     --version             Print the Segreant version
 
   Setup
-    1) If routing a cloud provider, review its exact rule first:
-       segreant egress plan --mode controlled_cloud --id openai-inference
-         --purpose provider_inference --data-class provider_request --method POST
-         --origin https://api.openai.com --path-prefix /v1/
-       Persist the reviewed plan only with the same command as:
-         segreant egress apply --apply ...
-       (Skip this for a local loopback-only model.)
+    1) OpenAI and Anthropic work with no setup. Another provider (OpenRouter, a
+       gateway) needs one rule; a refused request prints the exact command:
+         segreant egress apply --apply --mode controlled_cloud --id <as printed>
+           --purpose provider_inference --data-class provider_request --method POST
+           --origin https://<host> --path-prefix /
     2) segreant start
     3) $env:ANTHROPIC_BASE_URL="http://localhost:8090"   (PowerShell)
        $env:OPENAI_BASE_URL="http://localhost:8090/v1"
@@ -287,14 +317,30 @@ function cmdHelp() {
 }
 async function main() {
     const argv = process.argv.slice(2);
-    // Bare `segreant` opens the guide, not the reference: the tool's first job
-    // is to tell you where you are and the single next step. `help` is one word away.
-    const cmd = argv[0] ?? 'guide';
+    // Survival measurements are kept between runs in the home directory, so a
+    // later value run spends its git budget on what an earlier one did not reach.
+    // Only the CLI (and the dashboard it starts) turns this on.
+    configureSurvivalStore(join(segreantHome(), 'survival'));
+    // Bare `segreant` opens the home view, not the reference: what was spent this
+    // month, what stayed in the code, and the next step (or, on a new machine, the
+    // one command that reads the logs). `guide` keeps the full checklist.
+    // Flags with no command (`segreant --demo`) are flags for the home view; the
+    // help text says --demo works on any read command, and bare `segreant` is one.
+    // --help/-h and --version/-v stay commands of their own.
+    // Only long options qualify: parseFlags reads `--name` alone, so a single-dash
+    // token here would be swallowed as a positional and `segreant -bogus` would
+    // render the home view and exit 0 (PR #142 review).
+    const flagsOnly = argv[0] !== undefined && argv[0].startsWith('--')
+        && !['--help', '--version', '--'].includes(argv[0]);
+    const cmd = flagsOnly ? 'home' : argv[0] ?? 'home';
+    const rest = flagsOnly ? argv : argv.slice(1);
     // `exec` wraps another command: everything after the bare `--` belongs to the
     // wrapped command verbatim and must never be flag-parsed.
     const sep = argv.indexOf('--');
     const wraps = cmd === 'exec' || cmd === 'launch';
-    const flags = parseFlags(wraps && sep !== -1 ? argv.slice(1, sep) : argv.slice(1));
+    const parsed = parseFlags(wraps && sep !== -1 ? argv.slice(1, sep) : rest);
+    const tracked = trackFlags(parsed);
+    const flags = tracked.flags;
     const wrapped = wraps && sep !== -1 ? argv.slice(sep + 1) : [];
     // Demo mode: point every store-open at an isolated demo.db and flag surfaces
     // to render the DEMO label. One switch covers the CLI and the in-process
@@ -331,6 +377,17 @@ async function main() {
         case 'month':
             (await showCmd()).cmdShow('month', flags);
             break;
+        case 'plan':
+        case 'plans':
+            (await planCmd()).cmdPlan(flags);
+            break;
+        case 'quota':
+        case 'limits':
+            (await quotaCmd()).cmdQuota(flags);
+            break;
+        case 'statusline':
+            (await quotaCmd()).cmdStatusline(flags);
+            break;
         case 'economic':
         case 'economics':
             (await economicCmd()).cmdEconomic(flags);
@@ -377,12 +434,15 @@ async function main() {
         case 'export':
             (await showCmd()).cmdExport(flags);
             break;
+        case 'home':
+            (await homeCmd()).cmdHome(flags);
+            break;
         case 'guide':
         case 'next':
             await (await opsCmd()).cmdGuide(flags);
             break;
         case 'doctor':
-            await (await opsCmd()).cmdDoctor();
+            await (await opsCmd()).cmdDoctor(flags);
             break;
         case 'audit':
             await (await opsCmd()).cmdAudit(flags);
@@ -506,6 +566,27 @@ async function main() {
         default:
             console.error(`  Unknown command: ${cmd}\n  Run "segreant help" for usage.`);
             process.exitCode = 1;
+            return;
+    }
+    // Long-running commands keep reading options after this point, so only
+    // commands that have finished are checked.
+    // A command that already failed has said why; its exit code stays.
+    // --watch and --serve count only when the command itself read them: read
+    // here through the tracking proxy they would mark themselves used, and
+    // `segreant --watch` would render the home view and exit 0 (PR #142 review).
+    const consumed = (key) => parsed[key] === true && !tracked.unread().includes(key);
+    const longRunning = cmd === 'start' || wraps || consumed('watch') || consumed('serve');
+    const failed = typeof process.exitCode === 'number' && process.exitCode !== 0;
+    if (!longRunning && !failed) {
+        const unread = tracked.unread().filter((k) => k !== 'debug');
+        for (const k of unread) {
+            const near = suggestOption(k);
+            console.error(near === k
+                ? `  --${k} does nothing for "segreant ${cmd}"; nothing was done with it.`
+                : `  Unknown option --${k} for "segreant ${cmd}"; it did nothing.${near ? ` Did you mean --${near}?` : ''}`);
+        }
+        if (unread.length > 0)
+            process.exitCode = 2;
     }
 }
 // A reader closing early (e.g. `segreant scan | head`) makes further console.log