segreant 0.1.0 → 0.2.0

package/dist/export/statementCsv.js

@@ -0,0 +1,104 @@
+/**
+ * The monthly statement as a spreadsheet.
+ *
+ * Built from the same payload the Statement page renders, so the file and the
+ * screen cannot disagree. The four claims stay four sections: each row names
+ * its claim, its basis and its own dates, and there is no total row, because
+ * metered usage, provider-billed cost, allocated cost and realized value are
+ * different questions and adding them answers none of them.
+ */
+import { toCsv } from './csv.js';
+export const STATEMENT_CSV_COLUMNS = [
+    'claim', 'item', 'amountUsd', 'amountMicros', 'requests', 'basis',
+    'periodStartUtc', 'periodEndUtc', 'coversMonth', 'recordedAtUtc', 'runId', 'note',
+];
+const iso = (ms) => new Date(ms).toISOString();
+const microsUsd = (micros) => {
+    const sign = micros < 0 ? '-' : '';
+    const abs = Math.abs(micros);
+    return `${sign}${Math.trunc(abs / 1_000_000)}.${String(abs % 1_000_000).padStart(6, '0')}`;
+};
+function billedSource(kind) {
+    if (kind === 'operator_supplied_export')
+        return 'provider figure from an export the operator supplied';
+    if (kind === 'provider_api_pull')
+        return 'provider figure read from the provider';
+    return 'provider figure, source not recorded';
+}
+function billedNote(r) {
+    const notes = [];
+    if (r.snapshotStability === 'changed_across_observations')
+        notes.push('conflicted: the provider reported different figures for the same days');
+    else if (r.snapshotStability === null)
+        notes.push('snapshot stability not recorded');
+    if (r.offPathBound === 'none_local_estimate_exceeds_provider')
+        notes.push('local estimate exceeds the provider total, so the remainder bounds nothing');
+    else if (r.offPathBound === 'unknown_local_total_truncated_by_retention')
+        notes.push('retention deleted local rows, so the remainder bounds nothing');
+    else if (r.offPathBound === null)
+        notes.push('remainder bound not recorded');
+    if (!r.coversWholeMonth)
+        notes.push('figures are for this run\'s own period, not prorated to the month');
+    if (r.localQuantization && r.localQuantization.daysRounded > 0) {
+        notes.push(`local side summed exactly per day; ${r.localQuantization.daysRounded} day total(s) rounded half to even to the microdollar`);
+    }
+    return notes.join('; ');
+}
+/** One calendar month, four claims, never summed. */
+export function statementToCsv(s) {
+    const month = [iso(s.period.startMs), iso(s.period.endMs)];
+    const rows = [];
+    rows.push(['statement', s.period.label, '', '', '', s.demo ? 'sample data, not measured' : 'local ledger',
+        ...month, '', s.generatedAt, '',
+        'Four separate claims. Do not add the sections together. The month runs from local midnight; times are shown in UTC.' + (s.period.complete ? '' : ' Month in progress: figures so far.')]);
+    const m = s.metered;
+    const exact = m.basis.exactShare === null ? '' : `; ${Math.round(m.basis.exactShare * 100)}% at each model's own list rate`;
+    const basis = `local estimate: ${m.basis.headlineLabel.toLowerCase()}${exact}`;
+    const retention = m.retention.truncated ? `retention deleted ${m.retention.rowsRemoved} row(s) in this period; covers what survived` : '';
+    rows.push(['metered', 'total', m.costUsd.toFixed(6), '', m.requests, basis, ...month, 'yes', '', '', retention]);
+    for (const p of m.byProject)
+        rows.push(['metered', `project: ${p.label}`, p.costUsd.toFixed(6), '', p.requests, 'local estimate', ...month, 'yes', '', '', '']);
+    for (const x of m.byModel)
+        rows.push(['metered', `model: ${x.provider ? `${x.provider}/` : ''}${x.label}`, x.costUsd.toFixed(6), '', x.requests, 'local estimate', ...month, 'yes', '', '', '']);
+    const b = s.billed;
+    if (b.runs.length === 0) {
+        rows.push(['billed', 'not established', '', '', '', '', ...month, 'no', '', '',
+            b.scanComplete ? 'no comparison with a provider bill covers this month' : 'none among the most recent comparisons; an older one may exist']);
+    }
+    for (const r of b.runs) {
+        const own = [iso(r.periodStartMs), iso(r.periodEndMs), r.coversWholeMonth ? 'yes' : 'no', iso(r.computedAtMs), r.reconciliationRunId];
+        const project = r.providerProjectRef ? ` (${r.providerProjectRef})` : '';
+        const note = billedNote(r);
+        rows.push(['billed', `provider reported${project}`, microsUsd(r.providerReportedMicros), r.providerReportedMicros, '', billedSource(r.providerSourceKind), ...own, note]);
+        rows.push(['billed', `measured locally for comparison${project}`, microsUsd(r.localCapturedMicros), r.localCapturedMicros, '', 'local estimate, same scope and days', ...own, note]);
+        rows.push(['billed', `not explained${project}`, microsUsd(r.unexplainedVarianceMicros), r.unexplainedVarianceMicros, '', 'provider reported minus measured', ...own, note]);
+    }
+    const a = s.allocated;
+    const names = new Map(a.costCentres.map((c) => [c.costCentreId, c.name]));
+    if (a.runs.length === 0) {
+        rows.push(['allocated', 'not established', '', '', '', '', ...month, 'no', '', '',
+            a.scanComplete ? 'no recorded split covers this month' : 'none among the most recent splits; an older one may exist']);
+    }
+    for (const r of a.runs) {
+        const own = [iso(r.periodStartMs), iso(r.periodEndMs), r.coversWholeMonth ? 'yes' : 'no', iso(r.computedAtMs), r.allocationRunId];
+        const note = r.coversWholeMonth ? '' : 'figures are for this run\'s own period, not prorated to the month';
+        for (const c of r.byCostCentre) {
+            rows.push(['allocated', `cost centre: ${names.get(c.costCentreId) ?? c.costCentreId}`, microsUsd(c.allocatedMicros), c.allocatedMicros, c.requestCount, 'showback split of the local estimate', ...own, note]);
+        }
+        if (r.unallocatedMicros !== 0)
+            rows.push(['allocated', 'not allocated', microsUsd(r.unallocatedMicros), r.unallocatedMicros, '', 'showback split of the local estimate', ...own, note]);
+    }
+    const kept = (item, c) => {
+        // No amount: the realized section never carries a dollar a reader could sum
+        // as value. The count is in the requests column; the spend behind it is named
+        // in the note as spend.
+        rows.push(['realized', item, '', '', c.units, 'pieces of work judged in the month (count in the requests column); not value', ...month, 'yes', s.realized.measuredAt ?? '', '', `list cost behind this work: $${c.costUsd.toFixed(2)} (spend, not value). ${s.realized.reason}`]);
+    };
+    kept('kept', s.realized.kept);
+    kept('not kept', s.realized.notKept);
+    kept('results disagree', s.realized.contested);
+    kept('no signal', s.realized.unknown);
+    kept('too early to tell', s.realized.tooEarly);
+    rows.push(['close', s.close.status, '', '', '', 'economic period close', ...month, '', '', s.close.activeFinalizationId ?? '', '']);
+    return toCsv([...STATEMENT_CSV_COLUMNS], rows);
+}

package/dist/git/correlate.js

@@ -65,6 +65,17 @@ export async function repoToplevel(dir) {
         return null;
     }
 }
+/** Commits reachable from HEAD made in the last `days` days (0 when unreadable). */
+export async function commitCountSince(repoPath, days) {
+    try {
+        const out = await git(repoPath, ['rev-list', '--count', `--since=${days}.days`, 'HEAD']);
+        const n = Number(out.trim());
+        return Number.isSafeInteger(n) && n > 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 export async function projectName(repoPath) {
     try {
         const top = (await git(repoPath, ['rev-parse', '--show-toplevel'])).trim();
@@ -146,29 +157,95 @@ export async function attributeCommits(store, repoPath, opts = {}) {
     const limit = opts.limit ?? 20;
     const maxLookbackMs = (opts.maxLookbackHours ?? 8) * 60 * 60 * 1000;
     const project = await projectName(repoPath);
-    const commits = await readCommits(repoPath, limit + 1);
+    // Newest first BY TIME, not in log order. `git log` follows the graph, and
+    // after a rebase, cherry-pick or merge the author times along it are not
+    // monotonic; windows built from log neighbours then overlapped and booked the
+    // same request to two commits. On one real repository 40 windows overlapped
+    // and the Kept answer counted $99 of spend twice. Sorted, the windows tile
+    // time and every request lands in at most one of them.
+    const commits = (await readCommits(repoPath, limit + 1))
+        .map((c, i) => ({ c, i }))
+        .sort((a, b) => b.c.tsEpochMs - a.c.tsEpochMs || a.i - b.i)
+        .map((x) => x.c);
     const results = [];
-    for (let i = 0; i < Math.min(limit, commits.length); i++) {
+    const n = Math.min(limit, commits.length);
+    const windowOf = (i) => {
         const commit = commits[i];
         const prev = commits[i + 1];
         const naturalStart = prev ? prev.tsEpochMs : commit.tsEpochMs - maxLookbackMs;
-        const windowStartMs = Math.max(naturalStart, commit.tsEpochMs - maxLookbackMs);
-        const windowEndMs = commit.tsEpochMs;
+        return [Math.max(naturalStart, commit.tsEpochMs - maxLookbackMs), commit.tsEpochMs];
+    };
+    // With an evidence scope, read the scoped rows ONCE for the whole span and
+    // slice each window out of them. Three queries per commit took 10.5 s for
+    // 1,018 commits on a real repository; the slices give the same rows, in the
+    // same [start, end) bounds and order, because the read is ordered by time.
+    let scoped = null;
+    let scopedTs = [];
+    if (opts.scope && n > 0) {
+        let lo = Infinity;
+        let hi = -Infinity;
+        for (let i = 0; i < n; i++) {
+            const [a, b] = windowOf(i);
+            if (a < lo)
+                lo = a;
+            if (b > hi)
+                hi = b;
+        }
+        scoped = store.requestsInRange(lo, hi).filter((r) => opts.scope.matches(r));
+        scopedTs = scoped.map((r) => r.tsEpochMs);
+    }
+    const firstAtOrAfter = (t) => {
+        let a = 0;
+        let b = scopedTs.length;
+        while (a < b) {
+            const m = (a + b) >> 1;
+            if (scopedTs[m] < t)
+                a = m + 1;
+            else
+                b = m;
+        }
+        return a;
+    };
+    // The retention floor is one fact for the whole pass; read it once.
+    const floor = store.windowCoverage(Number.POSITIVE_INFINITY);
+    for (let i = 0; i < n; i++) {
+        const commit = commits[i];
+        const [windowStartMs, windowEndMs] = windowOf(i);
         // Scope the window's spend to this repo's project when the caller asks — so a
         // commit absorbs only its own project's native/imported spend, not every
         // project's concurrent traffic. Undefined scope = the project-blind window sum
         // (proxy default), preserving the original behavior.
-        const spend = store.summary(windowStartMs, windowEndMs, opts.scopeProject);
-        const economicRows = store.economicRequestRowsInRange(windowStartMs, windowEndMs, {
-            project: opts.scopeProject,
-        });
+        let spend;
+        let economicRows;
+        if (opts.scope) {
+            // The repository's label PLUS the folders and sessions its commits prove
+            // belong to it (a moved checkout, a worktree, a session started elsewhere).
+            const rows = windowEndMs > windowStartMs
+                ? scoped.slice(firstAtOrAfter(windowStartMs), firstAtOrAfter(windowEndMs))
+                : [];
+            spend = {
+                costUsd: rows.reduce((s, r) => s + r.costUsd, 0),
+                requests: rows.length,
+                outputTokens: rows.reduce((s, r) => s + r.outputTokens, 0),
+            };
+            economicRows = store.economicRowsOf(rows);
+        }
+        else {
+            spend = store.summary(windowStartMs, windowEndMs, opts.scopeProject);
+            economicRows = store.economicRequestRowsInRange(windowStartMs, windowEndMs, {
+                project: opts.scopeProject,
+            });
+        }
         const economic = economicAttributionFromRows(economicRows);
         const totalLines = commit.linesAdded + commit.linesDeleted;
         const attributedCostUsd = economicAttributionNumber(economic, spend.costUsd);
         // Did retention delete rows from inside this window? Strictly before the
         // boundary, because `prune` removes rows older than it; a null boundary is
         // "no prune on record" and licenses nothing either way (D-170, D-176).
-        const coverage = store.windowCoverage(windowStartMs);
+        const coverage = {
+            truncated: floor.prunedBeforeMs !== null && windowStartMs < floor.prunedBeforeMs,
+            prunedBeforeMs: floor.prunedBeforeMs,
+        };
         const costPerHundredLines = totalLines > 0 && !coverage.truncated
             ? (attributedCostUsd / totalLines) * 100
             : null;

package/dist/git/quality.js

@@ -16,6 +16,7 @@ import { promisify } from 'node:util';
 import { attributeCommits } from './correlate.js';
 import { measurementModel } from '../measurement/model.js';
 import { scope } from '../epistemic/scope.js';
+import { storedCommitFiles, rememberCommitFiles, reusableBlame, rememberBlame, flushSurvivalStore } from './survivalStore.js';
 const run = promisify(execFile);
 /** The construct measured by Git line retention. */
 export const ARTIFACT_PERSISTENCE_CONSTRUCT = 'artifact_persistence';
@@ -84,6 +85,19 @@ async function git(repoPath, args) {
     const { stdout } = await run('git', ['-C', repoPath, ...args], { maxBuffer: 64 * 1024 * 1024 });
     return stdout;
 }
+/**
+ * How many survival reads actually started git, since the process began or the
+ * last reset. For tests and diagnostics: a cache that answers shows up here as
+ * work not done.
+ */
+const gitRuns = { blame: 0, numstat: 0 };
+export function survivalGitRuns() {
+    return { ...gitRuns };
+}
+export function resetSurvivalGitRuns() {
+    gitRuns.blame = 0;
+    gitRuns.numstat = 0;
+}
 /** A commit's numstat never changes, so it is read once per process. */
 const commitFilesCache = new Map();
 /** Files a commit touched, with lines added per file (numstat). */
@@ -93,7 +107,11 @@ function commitFiles(repoPath, hash) {
     if (pending === undefined) {
         if (commitFilesCache.size >= BLAME_CACHE_MAX)
             commitFilesCache.clear();
-        pending = readCommitFiles(repoPath, hash);
+        // A commit's file list is fixed by its hash, so one read in any earlier run stands.
+        const stored = storedCommitFiles(repoPath, hash);
+        pending = stored !== undefined
+            ? Promise.resolve(stored)
+            : (gitRuns.numstat += 1, readCommitFiles(repoPath, hash).then((files) => { rememberCommitFiles(repoPath, hash, files); return files; }));
         // A failed read is not cached: the next caller retries rather than inheriting it.
         pending.catch(() => commitFilesCache.delete(key));
         commitFilesCache.set(key, pending);
@@ -101,15 +119,35 @@ function commitFiles(repoPath, hash) {
     return pending;
 }
 async function readCommitFiles(repoPath, hash) {
-    // --format= suppresses the commit header; --numstat gives "added<TAB>deleted<TAB>path".
-    const out = await git(repoPath, ['show', '--numstat', '--format=', hash]);
+    // --format= suppresses the commit header; -z keeps paths exact (see parseNumstatZ).
+    return parseNumstatZ(await git(repoPath, ['show', '--numstat', '-z', '--format=', hash]));
+}
+/**
+ * Parse `git show --numstat -z`. Each file is `added<TAB>deleted<TAB>path<NUL>`,
+ * except a rename or copy, which is `added<TAB>deleted<TAB><NUL>old<NUL>new<NUL>`.
+ *
+ * The paths returned are blamed at HEAD, so a rename has to yield its NEW path.
+ * Without -z, git prints a renamed file as `src/{old.ts => new.ts}`, which is not
+ * a path: blame refused it ("no such path in HEAD"), the file read as deleted,
+ * and every line the commit added there counted as not retained. -z also keeps
+ * a path containing spaces, tabs, quotes or " => " exactly as it is.
+ */
+export function parseNumstatZ(out) {
+    const fields = out.split('\0');
     const files = [];
-    for (const line of out.split('\n')) {
-        const m = line.match(/^(\d+|-)\t(\d+|-)\t(.+)$/);
+    for (let i = 0; i < fields.length; i++) {
+        const m = /^\n?(\d+|-)\t(\d+|-)\t([\s\S]*)$/.exec(fields[i]);
         if (!m)
             continue;
-        const added = m[1] === '-' ? 0 : Number(m[1]);
-        files.push({ path: m[3], added });
+        let path = m[3];
+        if (path === '') {
+            // A rename or copy: the old path, then the new one, as their own fields.
+            path = fields[i + 2] ?? '';
+            i += 2;
+        }
+        if (path === '')
+            continue;
+        files.push({ path, added: m[1] === '-' ? 0 : Number(m[1]) });
     }
     return files;
 }
@@ -141,7 +179,11 @@ export function clearBlameCache() {
  * caller's own deadline check, so a prefetch can never turn an unmeasured
  * commit into a measured one.
  */
-export async function prefetchSurvival(repoPath, hashes, deadlineMs, concurrency = 8) {
+export async function prefetchSurvival(repoPath, hashes, deadlineMs, concurrency = 8, 
+/** The same history bound the measuring pass will use, so the caches meet. */
+sinceSec, 
+/** The pass's HEAD (survivalHead); read here when not given. */
+passHead) {
     const expired = () => deadlineMs !== undefined && Date.now() >= deadlineMs;
     const pool = async (items, work) => {
         let next = 0;
@@ -156,7 +198,7 @@ export async function prefetchSurvival(repoPath, hashes, deadlineMs, concurrency
         });
         await Promise.all(lanes);
     };
-    const head = await headCommit(repoPath);
+    const head = passHead === undefined ? await survivalHead(repoPath) : passHead;
     if (head === null)
         return;
     const paths = new Set();
@@ -165,9 +207,17 @@ export async function prefetchSurvival(repoPath, hashes, deadlineMs, concurrency
             if (f.added > 0)
                 paths.add(f.path);
     });
-    await pool([...paths], (path) => blameAt(repoPath, head, path));
+    await pool([...paths], (path) => blameAt(repoPath, head, path, sinceSec));
+    flushSurvivalStore();
 }
-async function headCommit(repoPath) {
+/**
+ * The commit HEAD names now, or null for an unborn branch. A measuring pass
+ * reads it once and hands it to `prefetchSurvival` and `survivingLines`: asking
+ * per commit started one `git rev-parse` each, which was 3.6 s of a 3.9 s pass
+ * over 80 commits once the blames were cached. A caller that passes no HEAD
+ * still gets a fresh read per call, so a commit made a moment ago is seen.
+ */
+export async function survivalHead(repoPath) {
     try {
         const out = (await git(repoPath, ['rev-parse', 'HEAD'])).trim();
         return /^[0-9a-f]{40,64}$/.test(out) ? out : null;
@@ -192,13 +242,32 @@ export function blameCountsFromPorcelain(out) {
     }
     return counts;
 }
-function blameAt(repoPath, head, path) {
-    const key = `${repoPath}\0${head}\0${path}`;
+/**
+ * `sinceSec` bounds blame's walk back through history. Every commit newer than
+ * it keeps its exact line count; lines from older history are credited to a
+ * boundary commit instead of being traced to their origin, which is where
+ * almost all of blame's time goes on a long-lived file. Callers pass a bound
+ * older than every commit they measure, so their counts are unchanged.
+ */
+function blameAt(repoPath, head, path, sinceSec) {
+    const key = `${repoPath}\0${head}\0${path}\0${sinceSec ?? ''}`;
     let pending = blameCache.get(key);
     if (pending === undefined) {
         if (blameCache.size >= BLAME_CACHE_MAX)
             blameCache.clear();
-        pending = git(repoPath, ['blame', '--porcelain', head, '--', path]).then(blameCountsFromPorcelain, () => null);
+        const bound = sinceSec === undefined ? [] : [`--since=${sinceSec}`];
+        pending = (async () => {
+            // An earlier run's blame of this file, when it is provably the same
+            // observation (survivalStore.ts says when that is).
+            const reused = await reusableBlame(repoPath, head, path, sinceSec);
+            if (reused !== undefined)
+                return reused;
+            gitRuns.blame += 1;
+            const counts = await git(repoPath, ['blame', '--porcelain', ...bound, head, '--', path]).then(blameCountsFromPorcelain, () => null);
+            if (counts !== null)
+                rememberBlame(repoPath, head, path, sinceSec, counts);
+            return counts;
+        })();
         blameCache.set(key, pending);
     }
     return pending;
@@ -208,8 +277,8 @@ function blameAt(repoPath, head, path) {
  * `hash` by git blame. This is the retained-line count for `hash`'s introduced
  * artifact lines; it is not a quality score.
  */
-async function survivingLinesInFile(repoPath, head, hash, path) {
-    const counts = await blameAt(repoPath, head, path);
+async function survivingLinesInFile(repoPath, head, hash, path, sinceSec) {
+    const counts = await blameAt(repoPath, head, path, sinceSec);
     if (counts === null)
         return 0; // file deleted/renamed at HEAD → none of its lines survived as-is
     const exact = counts.get(hash);
@@ -231,23 +300,29 @@ async function survivingLinesInFile(repoPath, head, hash, path) {
  * between files: a single `git blame` already running is allowed to finish,
  * because killing it would cost the work without producing an answer.
  */
-export async function survivingLines(repoPath, hash, deadlineMs) {
-    const [files, head] = await Promise.all([commitFiles(repoPath, hash), headCommit(repoPath)]);
+export async function survivingLines(repoPath, hash, deadlineMs, 
+/** Optional history bound for blame; must be older than `hash` (see blameAt). */
+sinceSec, 
+/** The pass's HEAD (survivalHead); read here when not given. */
+passHead) {
+    const [files, head] = await Promise.all([commitFiles(repoPath, hash), passHead === undefined ? survivalHead(repoPath) : passHead]);
     let added = 0;
     let surviving = 0;
     let measured = true;
+    let filesWithAdditions = 0;
     for (const f of files) {
         added += f.added;
         if (f.added === 0)
             continue;
+        filesWithAdditions += 1;
         if (head === null || (deadlineMs !== undefined && Date.now() >= deadlineMs)) {
             // No HEAD to blame against (an unborn branch) is unmeasured, never zero.
             measured = false;
             continue;
         }
-        surviving += await survivingLinesInFile(repoPath, head, hash, f.path);
+        surviving += await survivingLinesInFile(repoPath, head, hash, f.path, sinceSec);
     }
-    return { added, surviving, measured };
+    return { added, surviving, measured, filesWithAdditions };
 }
 /**
  * Scan recent history for reverts, and report the boundary of what was read.
@@ -304,8 +379,9 @@ export async function computeArtifactPersistence(store, repoPath, opts = {}) {
     const attributions = await attributeCommits(store, repoPath, { limit, persist: opts.persist });
     const reverted = await revertedHashes(repoPath, limit);
     const commits = [];
+    const passHead = await survivalHead(repoPath);
     for (const a of attributions) {
-        const survival = await survivingLines(repoPath, a.hash);
+        const survival = await survivingLines(repoPath, a.hash, undefined, undefined, passHead);
         const { added, surviving } = survival;
         const retainedArtifact = artifactPersistence({
             introducedLines: added,
@@ -316,6 +392,9 @@ export async function computeArtifactPersistence(store, repoPath, opts = {}) {
         const ageDays = (now - a.tsEpochMs) / (24 * 60 * 60 * 1000);
         const maturing = now - a.tsEpochMs < windowMs;
         const cost = a.attributedCostUsd;
+        // A window retention emptied reports the surviving spend, which is not the
+        // cost of the work, so no per-dollar figure is derived from it.
+        const spendKnown = a.spendWindowTruncated === false;
         const isReverted = reverted.has(a.hash.slice(0, 7));
         commits.push({
             ...a,
@@ -327,8 +406,8 @@ export async function computeArtifactPersistence(store, repoPath, opts = {}) {
             reverted: isReverted,
             ageDays,
             maturing,
-            aiYield: cost > 0 ? surviving / cost : null,
-            costPerSurvivingLine: surviving > 0 ? cost / surviving : null,
+            aiYield: spendKnown && cost > 0 ? surviving / cost : null,
+            costPerSurvivingLine: spendKnown && surviving > 0 ? cost / surviving : null,
         });
     }
     // Retention/churn/revert are artifact observations over all matured commits.
@@ -345,7 +424,10 @@ export async function computeArtifactPersistence(store, repoPath, opts = {}) {
     const revertCount = mature.filter((c) => c.reverted).length;
     // Legacy AI Yield/effective-spend projections only count commits with AI cost,
     // so pure-human commits do not pad the retained-lines-per-dollar numerator.
-    const aiCommits = mature.filter((c) => c.attributedCostUsd > 0);
+    // Commits whose spend window retention pruned are withheld from every
+    // cost-based figure: their surviving cost would understate the denominator.
+    const spendTruncated = mature.filter((c) => c.spendWindowTruncated !== false);
+    const aiCommits = mature.filter((c) => c.spendWindowTruncated === false && c.attributedCostUsd > 0);
     const aiCost = aiCommits.reduce((s, c) => s + c.attributedCostUsd, 0);
     const aiSurviving = aiCommits.reduce((s, c) => s + c.survivingLines, 0);
     const costOnDurable = aiCommits
@@ -371,6 +453,7 @@ export async function computeArtifactPersistence(store, repoPath, opts = {}) {
             aiYield: aiCost > 0 ? aiSurviving / aiCost : null,
             costPerSurvivingLine: aiSurviving > 0 ? aiCost / aiSurviving : null,
             effectiveSpendRatio: aiCost > 0 ? costOnDurable / aiCost : null,
+            spendWindowTruncatedCommits: spendTruncated.length,
         },
     };
 }