segreant 0.1.0 → 0.2.0

package/dist/value/realization.js

@@ -15,9 +15,12 @@
  */
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { attributeCommits, isGitRepo, projectName } from '../git/correlate.js';
+import { attributeCommits, commitCountSince, isGitRepo, projectName } from '../git/correlate.js';
 import { isDemo } from '../config.js';
-import { survivingLines, revertScan, prefetchSurvival } from '../git/quality.js';
+import { survivingLines, revertScan, prefetchSurvival, survivalHead } from '../git/quality.js';
+import { repoIdentity, repoSpendScope } from '../git/repoScope.js';
+import { mapLimit } from '../util/pool.js';
+import { modelSpendFromRows } from '../store/scopeEvidence.js';
 import { revertCompletenessWitness } from '../git/completeness.js';
 import { acceptanceForCommit } from './proposals.js';
 import { GATE_LADDER, terminalRealizationBounds, serialRealization, aggregatePolarity, polarityFromVerdict, verdictFromPolarity, evaluateCodingOutcome, } from './gates.js';
@@ -93,6 +96,77 @@ function signalPolarity(signals, kind) {
     return aggregatePolarity(observations);
 }
 export const CLEAN_COMPLETENESS_EVENT_TYPES = CODING_CLEAN_COMPLETENESS_EVENT_TYPES;
+/** `Store.modelPricingBasis`, over rows already in scope (same rule: null cards are not revisions). */
+function pricingLineageFromRows(rows, model, provider) {
+    const bases = new Set();
+    const cards = new Set();
+    for (const r of rows) {
+        if (r.model !== model || r.provider !== provider)
+            continue;
+        if (r.costBasis != null)
+            bases.add(r.costBasis);
+        if (r.rateCardSha256)
+            cards.add(r.rateCardSha256);
+    }
+    return { costBases: [...bases].sort(), rateCardShas: [...cards].sort() };
+}
+export function keptBucketOf(u) {
+    if (u.maturing)
+        return 'maturing';
+    const survived = u.funnel.results.find((r) => r.gate === 'survived')?.verdict;
+    // A fail projected from contradictory evidence is not a refutation: the
+    // waste rollup already files it under 'conflicted', and calling it "not
+    // kept" here settled what the evidence left open.
+    const definiteFail = u.funnel.results.some((r) => r.verdict === 'fail' && r.polarity !== 'conflicted');
+    const contested = (u.funnel.conflicts?.length ?? 0) > 0;
+    return u.reverted || definiteFail ? 'notKept' : contested ? 'contested' : survived === 'pass' ? 'kept' : 'unknown';
+}
+export function keptSummary(report) {
+    const out = {
+        kept: { units: 0, costUsd: 0 },
+        notKept: { units: 0, costUsd: 0 },
+        contested: { units: 0, costUsd: 0 },
+        unknown: { units: 0, costUsd: 0 },
+        maturing: { units: 0, costUsd: 0, nextVerdictMs: null },
+    };
+    const DAY_MS = 24 * 60 * 60 * 1000;
+    for (const u of report.units) {
+        const cost = Number.isFinite(u.attributedCostUsd) ? u.attributedCostUsd : 0;
+        if (u.maturing) {
+            out.maturing.units += 1;
+            out.maturing.costUsd += cost;
+            // The unit's own window when it recorded one, as the Statement places it.
+            const due = u.tsEpochMs + (u.checkWindowDays ?? report.windowDays) * DAY_MS;
+            out.maturing.nextVerdictMs = out.maturing.nextVerdictMs === null ? due : Math.min(out.maturing.nextVerdictMs, due);
+            continue;
+        }
+        const bucket = out[keptBucketOf(u)];
+        bucket.units += 1;
+        bucket.costUsd += cost;
+    }
+    return out;
+}
+/** The most commits one period scan measures (the newest first). */
+export const MAX_PERIOD_COMMITS = 1500;
+/** The value period the terminal commands cover by default. */
+export const CLI_PERIOD_DAYS = 90;
+/**
+ * The git budget for a terminal command. The 20 s default exists so a
+ * dashboard route answers instead of hanging (it once took 416 s); a command
+ * someone runs and watches, with a progress line, can spend longer to measure
+ * a real period, and what the budget does not reach is still reported unknown.
+ */
+export const CLI_GIT_BUDGET_MS = 180_000;
+/**
+ * The time `scan` and `discover` give the value pass across ALL repositories
+ * together. Per-repository budgets alone stacked: a machine with dozens of
+ * repositories (agent worktrees count) spent 14 minutes and more. Largest spend
+ * goes first; a repository the stage does not reach is reported as not
+ * measured, with the command that measures it.
+ */
+export const SCAN_VALUE_BUDGET_MS = 120_000;
+/** Time kept back from the stage deadline for scoring and writing each repository after its git work. */
+export const STAGE_FINISH_RESERVE_MS = 15_000;
 /**
  * Build a gate result from its four-valued polarity, deriving the legacy
  * verdict rather than accepting one. The projection lives in exactly one place
@@ -132,7 +206,10 @@ function cleanCompleteness(project, commitHash, commitTsEpochMs, observedAtMs, w
     };
 }
 export async function computeRealization(store, repoPath, opts = {}) {
-    const limit = opts.limit ?? 30;
+    const limit = opts.limit
+        ?? (opts.sinceDays !== undefined
+            ? Math.max(1, Math.min(MAX_PERIOD_COMMITS, await commitCountSince(repoPath, opts.sinceDays)))
+            : 30);
     const windowDays = opts.windowDays ?? 14;
     // ONE budget across every commit's git work, not one per commit.
     //
@@ -171,11 +248,16 @@ export async function computeRealization(store, repoPath, opts = {}) {
     // x-segreant-project); otherwise fall back to the project-blind window sum so a
     // classic 'default'-tagged proxy store is unchanged. This is the bridge that
     // makes native, no-proxy imported spend produce correct per-project RoI.
-    const projectScoped = store.hasProjectSpend(project);
+    // Extended by evidence: folders and sessions that verifiably made commits in
+    // this repository (git/repoScope.ts). Without any such evidence the scope is
+    // the label alone, exactly as before.
+    const spendScope = opts.spendScope ?? await repoSpendScope(store, repoPath);
+    const projectScoped = store.hasProjectSpend(project) || spendScope.extended;
     const attributions = await attributeCommits(store, repoPath, {
         limit,
         persist: opts.persist,
-        scopeProject: projectScoped ? project : undefined,
+        scopeProject: projectScoped && !spendScope.extended ? project : undefined,
+        scope: projectScoped && spendScope.extended ? spendScope : undefined,
     });
     const scan = await revertScan(repoPath, limit);
     const reverted = scan.reverted;
@@ -197,11 +279,56 @@ export async function computeRealization(store, repoPath, opts = {}) {
     // the whole allowance before measuring anything — turning a scheduling
     // accident into forty unknown gates.
     gitDeadlineMs = Number.isFinite(gitBudgetMs) ? Date.now() + gitBudgetMs : undefined;
+    if (opts.gitDeadlineAtMs !== undefined) {
+        gitDeadlineMs = gitDeadlineMs === undefined ? opts.gitDeadlineAtMs : Math.min(gitDeadlineMs, opts.gitDeadlineAtMs);
+    }
     // Warm the git caches for every unit in parallel; the loop below still
     // measures (and decides measured/unmeasured) one unit at a time.
-    await prefetchSurvival(repoPath, attributions.map((a) => a.hash), gitDeadlineMs);
+    // Blame need not trace history older than the oldest commit measured here: a
+    // day before it keeps every measured commit's line count exact (blameAt).
+    const blameSinceSec = attributions.length > 0
+        ? Math.floor(Math.min(...attributions.map((a) => a.tsEpochMs)) / 1000) - 24 * 60 * 60
+        : undefined;
+    // A budget that runs out leaves the rest unmeasured, so spend it where the
+    // dollars are: matured commits (the only ones survival can judge) by
+    // attributed cost, largest first, then the maturing ones. The report keeps
+    // the attribution order.
+    const position = new Map(attributions.map((a, i) => [a.hash, i]));
+    // With an evidence scope, every unit's model attribution reads the SAME
+    // scoped rows its dollars came from. Read them once for the span of all
+    // windows and slice per unit: two queries per commit, one of them mapping
+    // every row of the window (scoped or not) through the economic ledger, took
+    // most of a repository's measurement time on a real ledger.
+    let scopedAll = [];
+    let scopedAllTs = [];
+    if (spendScope.extended && attributions.length > 0) {
+        const lo = Math.min(...attributions.map((a) => a.windowStartMs));
+        const hi = Math.max(...attributions.map((a) => a.windowEndMs));
+        scopedAll = store.requestsInRange(lo, hi).filter((r) => spendScope.matches(r));
+        scopedAllTs = scopedAll.map((r) => r.tsEpochMs);
+    }
+    const atOrAfter = (t) => {
+        let lo = 0;
+        let hi = scopedAllTs.length;
+        while (lo < hi) {
+            const m = (lo + hi) >> 1;
+            if (scopedAllTs[m] < t)
+                lo = m + 1;
+            else
+                hi = m;
+        }
+        return lo;
+    };
+    const measureOrder = [...attributions].sort((a, b) => {
+        const am = now - a.tsEpochMs < windowMs ? 1 : 0;
+        const bm = now - b.tsEpochMs < windowMs ? 1 : 0;
+        return am - bm || b.attributedCostUsd - a.attributedCostUsd;
+    });
+    // One HEAD for the whole pass: every unit below is measured against it.
+    const passHead = await survivalHead(repoPath);
+    await prefetchSurvival(repoPath, measureOrder.map((a) => a.hash), gitDeadlineMs, 8, blameSinceSec, passHead);
     const units = [];
-    for (const a of attributions) {
+    for (const a of measureOrder) {
         const ageDays = (now - a.tsEpochMs) / (24 * 60 * 60 * 1000);
         const maturing = now - a.tsEpochMs < windowMs;
         // Checked ONCE per unit and reused, so a unit is measured or unmeasured as a
@@ -211,17 +338,23 @@ export async function computeRealization(store, repoPath, opts = {}) {
         // were gathered.
         const scanned = !gitBudgetSpent();
         const survival = scanned
-            ? await survivingLines(repoPath, a.hash, gitDeadlineMs)
-            : { added: 0, surviving: 0, measured: false };
+            ? await survivingLines(repoPath, a.hash, gitDeadlineMs, blameSinceSec, passHead)
+            : { added: 0, surviving: 0, measured: false, filesWithAdditions: 0 };
         const { added, surviving } = survival;
         const survivalRatio = added > 0 ? Math.min(1, surviving / added) : 0;
         if (!survival.measured)
             unmeasuredSurvival += 1;
         const isReverted = reverted.has(a.hash) || reverted.has(a.hash.slice(0, 7));
-        // proxy gates: proposals captured in this commit's attribution window
-        const addedByFile = scanned ? await addedLinesByFile(repoPath, a.hash) : new Map();
-        const committedPaths = [...addedByFile.keys()];
+        // proxy gates: proposals captured in this commit's attribution window.
+        // The full diff is read only when there is a proposal to compare it with:
+        // every use below is gated on one. Reading it for every commit cost one
+        // serial `git show` per unit (1,126 of them, about 56 s on Windows, for a
+        // ledger with no captured proposals at all).
         const winProposals = store.proposalsInWindow(project, a.windowStartMs, a.windowEndMs);
+        const addedByFile = scanned && winProposals.length > 0
+            ? await addedLinesByFile(repoPath, a.hash)
+            : new Map();
+        const committedPaths = [...addedByFile.keys()];
         const proposalCaptureCoverage = !scanned || winProposals.length === 0
             // Without this unit's committed paths there is nothing to match a proposal
             // against, so capture coverage is unknown for the same reason an empty
@@ -315,7 +448,7 @@ export async function computeRealization(store, repoPath, opts = {}) {
             // this. Only the line and file counts come from the skipped calls, so the
             // reason falls back to what the attribution already knew.
             committed: gate('committed', 'supported', scanned
-                ? `${added} lines in ${committedPaths.length || a.filesChanged} files`
+                ? `${added} lines in ${survival.filesWithAdditions || a.filesChanged} files`
                 : `${a.filesChanged} files; line counts unmeasured (scan budget exhausted)`),
             tested: gate('tested', signalPolarity(signals, 'tested'), 'CI/test signal'),
             merged: gate('merged', signalPolarity(signals, 'merged'), 'merge signal'),
@@ -347,10 +480,20 @@ export async function computeRealization(store, repoPath, opts = {}) {
         // from another project's concurrent traffic. A partial exact window has no
         // winner; a wholly legacy window retains a display-only compatibility label
         // with null cost/share so the frontier cannot treat it as priceable evidence.
-        const modelSpend = store.byModel(a.windowStartMs, a.windowEndMs, projectScoped ? project : undefined);
-        const economicModelRows = store.economicRequestRowsInRange(a.windowStartMs, a.windowEndMs, {
-            project: projectScoped ? project : undefined,
-        });
+        // With an evidence-extended scope the model read takes the SAME rows the
+        // dollars came from (label, linked sessions, linked folders).
+        const scopedRows = spendScope.extended
+            ? (a.windowEndMs > a.windowStartMs ? scopedAll.slice(atOrAfter(a.windowStartMs), atOrAfter(a.windowEndMs)) : [])
+            : null;
+        const unitSpendScope = scopedRows === null ? undefined : spendScope.evidenceFor(scopedRows);
+        const modelSpend = scopedRows !== null
+            ? modelSpendFromRows(scopedRows)
+            : store.byModel(a.windowStartMs, a.windowEndMs, projectScoped ? project : undefined);
+        const economicModelRows = scopedRows !== null
+            ? store.economicRowsOf(scopedRows)
+            : store.economicRequestRowsInRange(a.windowStartMs, a.windowEndMs, {
+                project: projectScoped ? project : undefined,
+            });
         const modelAuthority = canonicalModelAttribution(economicModelRows);
         const dominantProvider = modelAuthority.coverage === 'exact'
             ? modelAuthority.dominant?.provider ?? null
@@ -378,7 +521,9 @@ export async function computeRealization(store, repoPath, opts = {}) {
         let dominantModelCostBasis = null;
         let dominantModelRateCard = null;
         if (dominantProvider !== null && dominantModel !== null) {
-            const lineage = store.modelPricingBasis(a.windowStartMs, a.windowEndMs, dominantModel, projectScoped ? project : undefined, dominantProvider);
+            const lineage = scopedRows !== null
+                ? pricingLineageFromRows(scopedRows, dominantModel, dominantProvider)
+                : store.modelPricingBasis(a.windowStartMs, a.windowEndMs, dominantModel, projectScoped ? project : undefined, dominantProvider);
             dominantModelCostBasis =
                 lineage.costBases.length === 1 ? lineage.costBases[0] : lineage.costBases.length > 1 ? 'mixed' : null;
             dominantModelRateCard =
@@ -388,6 +533,7 @@ export async function computeRealization(store, repoPath, opts = {}) {
             ...a,
             ageDays,
             maturing,
+            checkWindowDays: windowDays,
             survivalRatio,
             reverted: isReverted,
             hadProposal,
@@ -405,10 +551,12 @@ export async function computeRealization(store, repoPath, opts = {}) {
             cleanCompleteness: completeness,
             proposalCaptureCoverage,
             ...(contributionEvidence === undefined ? {} : { contributionEvidence }),
+            ...(unitSpendScope === undefined ? {} : { spendScope: unitSpendScope }),
         });
     }
     // Persist the snapshot so this realized-value picture can be served later
     // without the repo (e.g. to a manager's dashboard). Keyed by commit hash.
+    units.sort((x, y) => (position.get(x.hash) ?? 0) - (position.get(y.hash) ?? 0));
     if (opts.persist) {
         store.saveRealizationUnits(units.map((u) => ({
             commitHash: u.hash,
@@ -425,7 +573,7 @@ export async function computeRealization(store, repoPath, opts = {}) {
             costScope: projectScoped ? 'project' : 'window',
         })));
     }
-    return rollupRealization(units, {
+    const report = rollupRealization(units, {
         generatedAt: now,
         windowDays,
         acceptanceThreshold,
@@ -433,6 +581,39 @@ export async function computeRealization(store, repoPath, opts = {}) {
         projectScoped,
         survivalUnmeasuredUnits: unmeasuredSurvival,
     });
+    if (spendScope.extended) {
+        report.spendScope = {
+            linkedSessions: spendScope.linkedSessions.size,
+            linkedFolders: [...spendScope.linkedFolders],
+            verifiedObservations: spendScope.verifiedObservations,
+        };
+    }
+    if (opts.sinceDays !== undefined && projectScoped) {
+        report.periodCoverage = periodCoverage(store.requestsInRange(now - opts.sinceDays * 24 * 60 * 60 * 1000, now + 1).filter((r) => spendScope.matches(r)), units, now - opts.sinceDays * 24 * 60 * 60 * 1000, now);
+    }
+    return report;
+}
+/** Split the period's in-scope spend by whether, and why not, a commit window covers it. */
+export function periodCoverage(rows, units, periodStartMs, periodEndMs) {
+    const windows = units.map((u) => [u.windowStartMs, u.windowEndMs]).sort((a, b) => a[0] - b[0]);
+    const oldest = windows.length > 0 ? windows[0][0] : Infinity;
+    const newest = windows.length > 0 ? Math.max(...windows.map((w) => w[1])) : -Infinity;
+    const out = {
+        periodStartMs, periodEndMs, scopedCostUsd: 0, onCommitsUsd: 0,
+        beforeOldestUsd: 0, noCommitFollowedUsd: 0, notCommittedYetUsd: 0,
+    };
+    for (const r of rows) {
+        out.scopedCostUsd += r.costUsd;
+        if (r.tsEpochMs < oldest)
+            out.beforeOldestUsd += r.costUsd;
+        else if (r.tsEpochMs >= newest)
+            out.notCommittedYetUsd += r.costUsd;
+        else if (windows.some(([a, b]) => r.tsEpochMs >= a && r.tsEpochMs < b))
+            out.onCommitsUsd += r.costUsd;
+        else
+            out.noCommitFollowedUsd += r.costUsd;
+    }
+    return out;
 }
 /**
  * Reconstruct a realization report from persisted snapshots — no git, no repo.
@@ -517,11 +698,23 @@ export function realizationFromStore(store, opts = {}) {
  * the subject, not whatever repository the process happens to be sitting in.
  */
 export async function loadRealization(store, repo, opts = {}) {
+    if (opts.preferStored && store.countRealizationUnits() > 0) {
+        return { source: 'store', report: realizationFromStore(store, { windowDays: opts.windowDays }) };
+    }
+    // With no request recorded there is no spend for git work to attribute, and
+    // the dashboard's value read spent 17-22 s per load proving that on an empty
+    // ledger. The Realized claim and the budget drawer's recommendation waited
+    // on it. (Other reads do not queue behind it: settings answered in 6-16 ms
+    // while a 25 s value read ran.)
+    if (opts.preferStored && store.earliestRequestMs() === null)
+        return null;
     if (!isDemo() && repo && (await isGitRepo(repo))) {
         return {
             source: 'git',
             report: await computeRealization(store, repo, {
-                limit: opts.limit ?? 40,
+                limit: opts.limit ?? (opts.sinceDays !== undefined ? undefined : 40),
+                sinceDays: opts.sinceDays,
+                gitScanBudgetMs: opts.gitScanBudgetMs,
                 windowDays: opts.windowDays ?? 14,
                 persist: opts.persist ?? false,
             }),
@@ -657,6 +850,51 @@ export function projectTaskStrata(store, opts = {}) {
     }
     return out.sort((a, b) => b.costUsd - a.costUsd);
 }
+/**
+ * Clones, worktrees and copies of one repository (same root commit) are one
+ * repository: measured once, on the checkout whose HEAD is newest (the one the
+ * others' work was merged into), with the others' spend in its scope through
+ * git/repoScope.ts. Measuring each separately counted the same spend once per
+ * checkout.
+ */
+async function oneCheckoutPerRepository(repos) {
+    const groups = new Map();
+    const out = [];
+    for (const r of repos) {
+        const id = await repoIdentity(r.repoPath);
+        if (id === null) {
+            out.push(r);
+            continue;
+        }
+        const head = await headCommitTimeMs(r.repoPath);
+        const list = groups.get(id) ?? [];
+        list.push({ ...r, headMs: head });
+        groups.set(id, list);
+    }
+    for (const list of groups.values()) {
+        list.sort((a, b) => b.headMs - a.headMs || b.costUsd - a.costUsd);
+        const [best, ...rest] = list;
+        const { headMs: _h, ...keep } = best;
+        out.push({
+            ...keep,
+            sources: [...new Set(list.flatMap((r) => r.sources))].sort(),
+            costUsd: list.reduce((s, r) => s + r.costUsd, 0),
+            requests: list.reduce((s, r) => s + r.requests, 0),
+            ...(rest.length > 0 ? { otherCheckouts: rest.map((r) => r.repoPath) } : {}),
+        });
+    }
+    return out.sort((a, b) => b.costUsd - a.costUsd);
+}
+async function headCommitTimeMs(repoPath) {
+    try {
+        const { stdout } = await run('git', ['-C', repoPath, 'log', '-1', '--format=%ct', 'HEAD']);
+        const n = Number(stdout.trim());
+        return Number.isFinite(n) ? n * 1000 : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 /**
  * Discover the git repos behind the ledger's projects — the interconnectedness that
  * makes native per-project RoI possible with NO --repo and NO wiring. For each
@@ -666,13 +904,13 @@ export function projectTaskStrata(store, opts = {}) {
  * a cwd that isn't a repo (or has been deleted), is simply skipped — never guessed.
  */
 export async function discoverProjectRepos(store) {
-    const out = [];
-    for (const p of store.projectPaths()) {
-        if (await isGitRepo(p.cwd)) {
-            out.push({ project: p.project, repoPath: p.cwd, sources: p.sources, costUsd: p.costUsd, requests: p.requests });
-        }
-    }
-    return out;
+    // One git process per folder, several at once: one after another this took
+    // 5.7 s on a real ledger before any repository was measured.
+    const paths = store.projectPaths();
+    const isRepo = await mapLimit(paths, 8, (p) => isGitRepo(p.cwd));
+    return paths
+        .filter((_, i) => isRepo[i])
+        .map((p) => ({ project: p.project, repoPath: p.cwd, sources: p.sources, costUsd: p.costUsd, requests: p.requests }));
 }
 /**
  * Auto-correlate every discovered project repo: run the REAL realization scorer on
@@ -684,7 +922,31 @@ export async function discoverProjectRepos(store) {
  * e.g. in demo mode, where seeded rows carry no cwd.
  */
 export async function realizeDiscoveredProjects(store, opts = {}) {
-    const repos = await discoverProjectRepos(store);
+    // The deadline starts HERE, before discovery and scoping. It used to start
+    // after them, so about 19 s of setup on a real ledger ran outside the budget
+    // and the stage that promised 120 s took 162 s (H010).
+    const stageDeadline = opts.stageBudgetMs === undefined ? undefined : Date.now() + opts.stageBudgetMs;
+    const found = await oneCheckoutPerRepository(await discoverProjectRepos(store));
+    // With a period and a shared deadline, rank by what each repository really
+    // spent in the period (label plus commit evidence: a moved checkout's label
+    // alone can hold a sliver of it), and skip one with no priced spend at all.
+    // Every scope is built once, several at once, from one read of the commit
+    // observations, and handed to the measurement below instead of rebuilt there.
+    const periodCost = new Map();
+    const scopes = new Map();
+    if (opts.stageBudgetMs !== undefined && opts.sinceDays !== undefined) {
+        const now = Date.now();
+        const rows = store.requestsInRange(now - opts.sinceDays * 24 * 60 * 60 * 1000, now + 1);
+        const observations = store.observedCommits();
+        const built = await mapLimit(found, 6, (r) => repoSpendScope(store, r.repoPath, { observations }));
+        found.forEach((r, i) => {
+            const scope = built[i];
+            scopes.set(r.repoPath, scope);
+            periodCost.set(r.repoPath, rows.reduce((s, row) => (scope.matches(row) ? s + row.costUsd : s), 0));
+        });
+    }
+    const rank = (r) => periodCost.get(r.repoPath) ?? r.costUsd;
+    const repos = opts.stageBudgetMs === undefined ? found : [...found].sort((a, b) => rank(b) - rank(a));
     const results = new Array(repos.length);
     // Repositories are independent and almost all of their time is spent waiting
     // on git, so a few run at once. Safe on one DatabaseSync handle because every
@@ -696,13 +958,38 @@ export async function realizeDiscoveredProjects(store, opts = {}) {
         while (next < repos.length) {
             const i = next++;
             const r = repos[i];
+            const left = stageDeadline === undefined ? undefined : stageDeadline - Date.now();
+            const spent = periodCost.get(r.repoPath);
+            if (spent !== undefined && spent <= 0) {
+                results[i] = { ...r, units: 0, realizedUnits: 0, measured: false, skipped: 'no-spend', periodCostUsd: 0 };
+                done += 1;
+                opts.onProgress?.(done, repos.length, r.project);
+                continue;
+            }
+            if (left !== undefined && left <= 0) {
+                results[i] = { ...r, units: 0, realizedUnits: 0, measured: false, skipped: 'deadline', ...(spent === undefined ? {} : { periodCostUsd: spent }) };
+                done += 1;
+                opts.onProgress?.(done, repos.length, r.project);
+                continue;
+            }
             const rep = await computeRealization(store, r.repoPath, {
-                limit: opts.limit ?? 40,
+                limit: opts.limit ?? (opts.sinceDays !== undefined ? undefined : 40),
+                sinceDays: opts.sinceDays,
+                gitScanBudgetMs: left === undefined ? opts.gitScanBudgetMs : Math.min(left, opts.gitScanBudgetMs ?? left),
                 windowDays: opts.windowDays,
                 persist: true,
+                ...(scopes.has(r.repoPath) ? { spendScope: scopes.get(r.repoPath) } : {}),
+                // Stop git a little before the stage deadline: the scoring and the
+                // snapshot write after it still have to fit inside the promise.
+                ...(stageDeadline === undefined ? {} : { gitDeadlineAtMs: stageDeadline - STAGE_FINISH_RESERVE_MS }),
             });
             const realizedUnits = rep.units.filter((u) => !u.maturing && u.funnel.realized).length;
-            results[i] = { ...r, units: rep.units.length, realizedUnits };
+            const periodCostUsd = rep.periodCoverage?.scopedCostUsd ?? spent;
+            results[i] = {
+                ...r, units: rep.units.length, realizedUnits, measured: true, kept: keptSummary(rep),
+                ...(periodCostUsd === undefined ? {} : { periodCostUsd }),
+                ...(rep.periodCoverage === undefined ? {} : { coverage: rep.periodCoverage }),
+            };
             done += 1;
             opts.onProgress?.(done, repos.length, r.project);
         }
@@ -752,11 +1039,14 @@ export function rollupRealization(units, opts) {
         wasteMap.set(stage, b);
     }
     const instrumentation = Object.fromEntries(GATE_LADDER.map((g) => [g, 0]));
+    const gatePasses = Object.fromEntries(GATE_LADDER.map((g) => [g, 0]));
     const gateConflicts = Object.fromEntries(GATE_LADDER.map((g) => [g, 0]));
     for (const u of mature) {
         for (const r of u.funnel.results) {
             if (r.verdict !== 'unknown')
                 instrumentation[r.gate] += 1;
+            if (r.verdict === 'pass' && r.polarity !== 'conflicted')
+                gatePasses[r.gate] += 1;
             if (r.polarity === 'conflicted')
                 gateConflicts[r.gate] += 1;
         }
@@ -796,6 +1086,7 @@ export function rollupRealization(units, opts) {
             realizedSpendShare: totalCostUsd > 0 ? spendOnRealizedUnitsUsd / totalCostUsd : null,
             wasteByStage: [...wasteMap.values()].sort((a, b) => b.costUsd - a.costUsd),
             instrumentation,
+            gatePasses,
             gateConflicts,
             realizationBounds: terminalRealizationBounds(mature.map((u) => u.funnel)),
             serial: serialRealization(mature.map((u) => u.funnel)),

package/dist/value/report.js

@@ -42,6 +42,7 @@
  *   5. RoI, drift, time reclaimed, frontier — all read (1)–(4), never the store
  *                     directly, so no surface can re-derive an input its own way.
  */
+import { capBasisSpend } from '../budget/guard.js';
 import { isDemo, DEFAULT_CONFIG } from '../config.js';
 import { demoLiftOptions } from '../demo/seed.js';
 import { projectName } from '../git/correlate.js';
@@ -76,9 +77,12 @@ const DEFAULT_SPEND_WINDOW_DAYS = 30;
 export async function valueSpine(store, config, opts) {
     const windowDays = opts.windowDays ?? 14;
     const loaded = await loadRealization(store, opts.repo, {
-        limit: opts.limit ?? 40,
+        limit: opts.limit ?? (opts.sinceDays !== undefined ? undefined : 40),
         windowDays,
         persist: opts.persist ?? false,
+        sinceDays: opts.sinceDays,
+        gitScanBudgetMs: opts.gitScanBudgetMs,
+        preferStored: opts.preferStored,
     });
     if (!loaded)
         return null;
@@ -267,14 +271,30 @@ export function budgetAdvice(store, config, opts = {}) {
     const series = store.economicSeries(startMs, endMs, DAY_MS, liveOnly);
     const realizedSpendShare = opts.realizedSpendShare ?? null;
     const coverage = exactRows.length === 0 ? 'legacy_unknown' : exact.complete ? 'exact' : 'partial';
+    const rec = recommendBudget({
+        dailySpends: series.map((s) => s.costUsd),
+        realizedSpendShare,
+        frontier: opts.frontier ?? [],
+        currentDailyCapUsd: config.budget.dailyUsd,
+        decisionInputs: budgetCapDecisionInputs(coverage, realizedSpendShare),
+    });
+    // A user whose spend so far was all imported from agent logs has history,
+    // just none the cap governs. "Not enough spend history" would contradict
+    // every other page, so name the basis and the two ways forward instead.
+    if (liveOnly && rec.status === 'cold_start') {
+        // "No requests went through the proxy" is a claim about requests, so it
+        // is decided by counting them, on the guard's own projection (review 4, F3).
+        const live = capBasisSpend(store, config.budget, startMs, endMs);
+        const liveUsd = series.reduce((a, s) => a + s.costUsd, 0);
+        const importedUsd = store.economicSeries(startMs, endMs, DAY_MS, false).reduce((a, s) => a + s.costUsd, 0) - liveUsd;
+        if (live.requests === 0 && importedUsd >= 0.005) {
+            rec.rationale = [
+                `No requests went through Segreant's proxy in the last ${days} days. The $${importedUsd.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })} at list price in that time was imported from agent logs: it is observed, but a cap only governs proxied requests, so it does not count toward one. Route a tool through the proxy for a few active days, or count imported spend toward the cap with: segreant budget --include-imported on`,
+            ];
+        }
+    }
     return {
-        ...recommendBudget({
-            dailySpends: series.map((s) => s.costUsd),
-            realizedSpendShare,
-            frontier: opts.frontier ?? [],
-            currentDailyCapUsd: config.budget.dailyUsd,
-            decisionInputs: budgetCapDecisionInputs(coverage, realizedSpendShare),
-        }),
+        ...rec,
         spendBasis: liveOnly ? 'live_proxy' : 'all_observed',
         windowDays: days,
         economic: {

package/dist/value/selfReported.js

@@ -131,12 +131,14 @@ function events(store, startMs, endMs) {
         return event;
     });
 }
-function matched(rows, link) {
-    if (link.type === 'request')
-        return rows.filter((row) => row.requestId === link.requestId);
-    if (link.type === 'session')
-        return rows.filter((row) => row.sessionId === link.sessionId);
-    return rows.filter((row) => row.tsEpochMs >= link.fromMs && row.tsEpochMs < link.toMs && row.source === link.tool);
+/**
+ * The requests before `endMs` that a link names, read per link rather than by
+ * filtering the whole ledger: the report ran on every /api/value load and held
+ * every request ever recorded, outcomes or not (540 MiB of heap on a
+ * 300,000-request ledger).
+ */
+function matched(store, link, endMs) {
+    return store.requestsForSpendLink(link, endMs);
 }
 /** Preview is read-only; apply appends one signal to the existing ledger. */
 export function recordReportedOutcome(store, raw, apply = false, enabled = true, nowMs = Date.now()) {
@@ -146,7 +148,7 @@ export function recordReportedOutcome(store, raw, apply = false, enabled = true,
     const prior = events(store, 0, Number.MAX_SAFE_INTEGER).filter((item) => item.outcomeId === event.outcomeId);
     if (prior.some((item) => !sameIdentity(item, event)))
         throw new Error('outcomeId already has a different kind or spend link');
-    const rows = matched(store.requestsInRange(0, Number.MAX_SAFE_INTEGER), event.link);
+    const rows = matched(store, event.link, Number.MAX_SAFE_INTEGER);
     const preview = {
         apply,
         basis: SELF_REPORTED_BASIS,
@@ -180,8 +182,7 @@ export function selfReportedValueReport(store, startMs, endMs, enabled = true) {
     // A linked session or request may have started before the report window, so
     // spend is matched over all history up to the window end, exactly as the
     // record preview matches it. The window selects outcomes, not their cost.
-    const requestRows = store.requestsInRange(0, endMs);
-    const claims = selected.map((group) => matched(requestRows, group[0].link));
+    const claims = selected.map((group) => matched(store, group[0].link, endMs));
     const claimedBy = new Map();
     for (const rows of claims)
         for (const row of rows)

package/docs/ARCHITECTURE.md

@@ -263,9 +263,12 @@ selected eligible address is pinned into the one socket request; the OS resolver
 is not asked to choose a different address afterward.
 Only a genuinely absent receipt path may establish a genesis predecessor, and a
 present invalid path is never silently reset. Loaded JSON egress configuration
-also accepts only the two declared modes and exact rule field types; ambiguous
-mode/enabled values return to local-locked behavior rather than authorizing a
-cloud rule. Loaded rules use the same exact semantic validator as CLI-authored
+also accepts only the two declared modes and exact rule field types. A present
+but malformed egress section (ambiguous mode or enabled values, an invalid rule,
+unexpected fields) loads as `invalid`, which refuses every non-loopback target,
+the built-in provider and price-list routes included, until it is repaired; only
+an absent section means local-locked. Falling back to local-locked would now let
+built-in provider traffic through a typo. Loaded rules use the same exact semantic validator as CLI-authored
 rules: canonical HTTPS origin, non-empty safe path prefix, valid identifiers,
 and no unexpected fields. A bounded stale-lock refusal is
 operator-repairable only after confirming no Segreant writer is active; the lock
@@ -444,5 +447,6 @@ genuinely open:
 
 - Sees only traffic routed through it (D1).
 - Cost accuracy depends on the pricing table; unknown models are flagged `estimated` and use a conservative fallback rather than failing.
-- Budget blocking is pre-flight on cumulative state; a single in-flight request can still complete above a cap (you can't un-send a request mid-stream).
+- Budget blocking is pre-flight on recorded spend. Every request already admitted when the cap is crossed still completes, so the overshoot is bounded by how many requests are in flight times their cost: a stream cannot be un-sent. Measured 2026-10-17 against a local stub provider: with 50 concurrent requests at $0.00072 each, 42 completed past a $1.66 cap ($0.031 over) and the other 752 were refused with 429. One agent working serially overshoots by at most one request.
+- A cap saved from the CLI, the dashboard or an editor governs the running proxy within a second: the proxy re-reads the budget when `config.json` changes. While the file is invalid, every request is refused (503) without being sent; deleting the file keeps the cap in force.
 - "Cost reduction %" is a function of baseline waste, not a guarantee the tool makes. Segreant provides visibility and controls; the savings are the user's to realize.