@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/config_cost_report.ts

@@ -0,0 +1,302 @@
+#!/usr/bin/env tsx
+/**
+ * `config-cost report` — what does this configuration cost per session
+ * (`road-to-delivered-cost-truth` Phase 1).
+ *
+ * Class A per ADR-124: in-process, per-invocation, no socket, no daemon, no
+ * network, no writes outside a stdout/JSON report. The same class
+ * `cache_realization_report` already occupies, and for the same reason.
+ *
+ * Four figures, and the discipline is the point of each:
+ *
+ *   delivered payload         from the per-asset ledger, exact BPE where it resolves
+ *   billable_input split      fresh input · cache read · cache creation
+ *   cache-read share          `null` when nothing was billed, never 0 %
+ *   payload_amplification     delivered / profile-declared, or `unknown_profile`
+ *
+ * NO CURRENCY, ANYWHERE. The suite does not know the consumer's contract, so a
+ * monetary figure would be extrapolated from a rate it invented — actionable and
+ * wrong, which is worse than absent. `check_no_currency_in_cost_surfaces` gates
+ * it rather than leaving it to intent.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/config_cost_report [--format text|json]
+ *     [--root <path>] [--profile <name>] [--transcript-root <path>]
+ *     [--max-age-days <n>] [--summary-line]
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { buildLedger } from './_lib/asset_delivery_ledger.js';
+import {
+    amplification,
+    billableSplit,
+    rereadCost,
+    summaryLine,
+    type AmplificationResult,
+    type BillableSplit,
+    type ProfileDeclaration,
+    type RereadCost,
+    type RereadLeg,
+} from './_lib/config_cost.js';
+import { prefixStableDirRoots } from './_lib/prefix_stable_surfaces.js';
+import { DEFAULT_PROJECTS_ROOT, aggregateByBucket, scanTranscripts } from './_lib/cc_transcript.js';
+import { computeRereads } from './_lib/transcript_reads.js';
+import { gpt_tokens } from './_lib/token_count.js';
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const REPO_ROOT = path.resolve(HERE, '..', '..');
+
+export interface Options {
+    format: 'text' | 'json';
+    transcript: string | null;
+    root: string;
+    profile: string | null;
+    transcriptRoot: string;
+    maxAgeDays: number;
+    summaryOnly: boolean;
+}
+
+export function parseArgs(argv: string[]): Options {
+    const o: Options = {
+        format: 'text',
+        transcript: null,
+        root: REPO_ROOT,
+        profile: null,
+        transcriptRoot: DEFAULT_PROJECTS_ROOT,
+        maxAgeDays: 14,
+        summaryOnly: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined) continue;
+        if (a === '--format') o.format = (argv[++i] as Options['format']) ?? o.format;
+        else if (a.startsWith('--format=')) o.format = a.slice('--format='.length) as Options['format'];
+        else if (a === '--root') o.root = path.resolve(argv[++i] ?? o.root);
+        else if (a.startsWith('--root=')) o.root = path.resolve(a.slice('--root='.length));
+        else if (a === '--profile') o.profile = argv[++i] ?? null;
+        else if (a.startsWith('--profile=')) o.profile = a.slice('--profile='.length);
+        else if (a === '--transcript-root') o.transcriptRoot = argv[++i] ?? o.transcriptRoot;
+        else if (a.startsWith('--transcript-root=')) o.transcriptRoot = a.slice('--transcript-root='.length);
+        else if (a === '--max-age-days') o.maxAgeDays = Number(argv[++i]) || o.maxAgeDays;
+        else if (a.startsWith('--max-age-days=')) o.maxAgeDays = Number(a.slice('--max-age-days='.length)) || o.maxAgeDays;
+        else if (a === '--transcript') o.transcript = argv[++i] ?? null;
+        else if (a.startsWith('--transcript=')) o.transcript = a.slice('--transcript='.length);
+        else if (a === '--summary-line') o.summaryOnly = true;
+    }
+    if (o.format !== 'text' && o.format !== 'json') o.format = 'text';
+    return o;
+}
+
+/** Read a profile's declared standing payload. Absent file or key → `null`, never a default. */
+export function readProfileDeclaration(root: string, profile: string): ProfileDeclaration | null {
+    const file = path.join(root, 'src', 'config', 'profiles', `${profile}.ini`);
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return null;
+    }
+    const num = (key: string): number | null => {
+        const m = new RegExp(`^${key}\\s*=\\s*([0-9.]+)\\s*$`, 'm').exec(text);
+        if (m === null) return null;
+        const v = Number(m[1]);
+        return Number.isFinite(v) ? v : null;
+    };
+    const rules = num('declared_rules_tokens');
+    const skills = num('declared_skill_catalogue_tokens');
+    const headroom = num('declared_payload_sanity_headroom');
+    if (rules === null || skills === null || headroom === null) return null;
+    return { profile, declared: { rules_tokens: rules, skill_catalogue_tokens: skills }, sanity_headroom: headroom };
+}
+
+/** The active profile, read from the settings cascade. `full` is the shipped default. */
+export function activeProfile(root: string, override: string | null): string {
+    if (override !== null) return override;
+    for (const rel of ['.agent-settings.yml', path.join('agents', 'settings', '.agent-settings.yml')]) {
+        try {
+            const m = /^\s*profile:\s*['"]?([A-Za-z0-9_-]+)/m.exec(fs.readFileSync(path.join(root, rel), 'utf-8'));
+            if (m !== null) return m[1] as string;
+        } catch {
+            /* absent layer — try the next */
+        }
+    }
+    return 'full';
+}
+
+/**
+ * Turn the re-reads `hot_context_hook` already counts into a token figure
+ * (step 1.3).
+ *
+ * The hook notices a repeated read and renders it as an advisory line; nothing
+ * ever priced it, so a re-read was visible and free-looking. The cost is
+ * `duplicate_reads x the file's MEASURED size` — derived, never a constant,
+ * because a constant would rank a re-read of a one-line config beside a re-read
+ * of a 3,000-token rule.
+ *
+ * A file that no longer exists is skipped rather than priced at zero: it was
+ * genuinely read, and a zero would understate the cost while looking measured.
+ */
+export function collectRereadLegs(transcriptPath: string | null, root: string): RereadLeg[] {
+    if (transcriptPath === null) return [];
+    let result;
+    try {
+        result = computeRereads([transcriptPath]);
+    } catch {
+        return [];
+    }
+    const legs: RereadLeg[] = [];
+    for (const f of result.files) {
+        if (f.duplicate_reads <= 0) continue;
+        const rel = path.relative(root, f.file_path);
+        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        let text: string;
+        try {
+            text = fs.readFileSync(f.file_path, 'utf-8');
+        } catch {
+            continue;
+        }
+        legs.push({
+            file: rel,
+            total_reads: f.total_reads,
+            duplicate_reads: f.duplicate_reads,
+            file_tokens: gpt_tokens(text).tokens,
+        });
+    }
+    legs.sort((a, b) => b.duplicate_reads * b.file_tokens - a.duplicate_reads * a.file_tokens);
+    return legs;
+}
+
+export interface CostReport {
+    schema: 'config-cost-report/v1';
+    profile: string;
+    delivered: { total_tokens: number; rules_tokens: number; skill_catalogue_tokens: number; exact_throughout: boolean };
+    /** `null` with a stated reason when the transcript ledger carries nothing. */
+    billable: BillableSplit | null;
+    billable_reason: string | null;
+    amplification: AmplificationResult;
+    reread: RereadCost;
+    summary_line: string;
+}
+
+export function buildReport(o: Options, legsOverride?: readonly RereadLeg[]): CostReport {
+    const legs = legsOverride ?? collectRereadLegs(o.transcript, o.root);
+    const [rulesRel, skillsRel] = prefixStableDirRoots();
+    const ledger = buildLedger(
+        path.join(o.root, rulesRel ?? 'dist/agent-src/rules'),
+        path.join(o.root, skillsRel ?? 'dist/agent-src/skills'),
+        o.root,
+    );
+    const measured = {
+        rules_tokens: ledger.by_kind.rule.tokens,
+        skill_catalogue_tokens: ledger.by_kind['skill-catalogue-line'].tokens,
+    };
+
+    let billable: BillableSplit | null = null;
+    let billableReason: string | null = null;
+    try {
+        const scan = scanTranscripts({ root: o.transcriptRoot, maxAgeDays: o.maxAgeDays });
+        const buckets = aggregateByBucket(scan.records);
+        const fresh = buckets.main.input_tokens + buckets.subagent.input_tokens;
+        const read = buckets.main.cache_read_input_tokens + buckets.subagent.cache_read_input_tokens;
+        const creation = buckets.main.cache_creation_input_tokens + buckets.subagent.cache_creation_input_tokens;
+        if (fresh + read + creation === 0) {
+            billableReason = `no billable input recorded under ${o.transcriptRoot} in the last ${String(o.maxAgeDays)} day(s)`;
+        } else {
+            billable = billableSplit(fresh, read, creation);
+        }
+    } catch (err) {
+        billableReason = `the transcript ledger at ${o.transcriptRoot} could not be read: ${(err as Error).message}`;
+    }
+
+    const profile = activeProfile(o.root, o.profile);
+    return {
+        schema: 'config-cost-report/v1',
+        profile,
+        delivered: {
+            total_tokens: ledger.total_tokens,
+            rules_tokens: measured.rules_tokens,
+            skill_catalogue_tokens: measured.skill_catalogue_tokens,
+            exact_throughout: ledger.exact_throughout,
+        },
+        billable,
+        billable_reason: billableReason,
+        amplification: amplification(ledger.total_tokens, measured, readProfileDeclaration(o.root, profile)),
+        reread: rereadCost(legs),
+        summary_line: summaryLine(ledger.total_tokens, billable),
+    };
+}
+
+export function renderText(r: CostReport): string {
+    const out: string[] = [];
+    const n = (v: number): string => String(v);
+    out.push('Config-cost report — what this configuration costs per session');
+    out.push(`  profile: ${r.profile}`);
+    out.push(
+        `  delivered standing payload: ${n(r.delivered.total_tokens)} tok ` +
+            `(rules ${n(r.delivered.rules_tokens)} · skill catalogue ${n(r.delivered.skill_catalogue_tokens)})` +
+            `${r.delivered.exact_throughout ? '' : ' — MIXED measurement, some rows fell back to the chars/4 proxy'}`,
+    );
+    out.push('');
+    out.push('billable_input = fresh input + cache read + cache creation');
+    if (r.billable === null) {
+        out.push(`  unavailable — ${r.billable_reason ?? 'no reason recorded'}`);
+        out.push('  (a stated reason, never zeros standing in for absence)');
+    } else {
+        const b = r.billable;
+        out.push(`  fresh input:    ${n(b.fresh_input_tokens)} tok`);
+        out.push(`  cache read:     ${n(b.cache_read_tokens)} tok`);
+        out.push(`  cache creation: ${n(b.cache_creation_tokens)} tok`);
+        out.push(`  billable total: ${n(b.billable_input_tokens)} tok`);
+        out.push(
+            `  cache-read share: ${b.cache_read_share === null ? 'unavailable (nothing was billed)' : `${(b.cache_read_share * 100).toFixed(1)}%`}`,
+        );
+    }
+    out.push('');
+    out.push('payload amplification (delivered ÷ profile-declared)');
+    out.push(`  verdict: ${r.amplification.verdict}`);
+    out.push(`  ratio:   ${r.amplification.ratio === null ? 'not computed' : r.amplification.ratio.toFixed(2)}`);
+    out.push(`  ${r.amplification.reason}`);
+    out.push('');
+    out.push('  This measures AMPLIFICATION, not net value. It never observes what the payload');
+    out.push('  returned, so it informs the question of whether the configuration earns its cost');
+    out.push('  and is not allowed to answer it.');
+    if (r.reread.legs.length > 0) {
+        out.push('');
+        out.push('re-read cost (content paid for twice)');
+        out.push(`  wasted: ${n(r.reread.wasted_tokens)} tok across ${n(r.reread.legs.length)} file(s)`);
+        if (r.reread.worst_file !== null) out.push(`  worst:  ${r.reread.worst_file}`);
+    }
+    out.push('');
+    out.push(r.summary_line);
+    return out.join('\n') + '\n';
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const o = parseArgs(argv);
+    let report: CostReport;
+    try {
+        report = buildReport(o);
+    } catch (err) {
+        process.stderr.write(`❌  config_cost_report: ${(err as Error).message}\n`);
+        return 2;
+    }
+    if (report.delivered.total_tokens === 0) {
+        process.stderr.write(
+            '❌  config_cost_report: no standing asset measured. The rule and skill trees are\n' +
+                '    generated (`task sync && task generate-tools`); a checkout that has not run them\n' +
+                '    has no payload to price. Stated, not reported as a cost of zero.\n',
+        );
+        return 2;
+    }
+    if (o.summaryOnly) {
+        process.stdout.write(report.summary_line + '\n');
+        return 0;
+    }
+    process.stdout.write(o.format === 'json' ? JSON.stringify(report, null, 2) + '\n' : renderText(report));
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+    process.exit(main());
+}

package/src/scripts/consumer_matrix.ts

@@ -344,7 +344,80 @@ interface MissingModule {
  * deliberately ignores bare package specifiers (`from 'commander'`) so the
  * walk never leaves the package's own `dist/` tree.
  */
-export function parseRelativeSpecifiers(source: string): string[] {
+/**
+ * Strip comments before scanning for import specifiers.
+ *
+ * A doc comment can contain a perfectly well-formed `export { X } from './X'`
+ * as an EXAMPLE, and the scanner had no way to tell one from a real import —
+ * `src/cli/commands/uiAudit.ts` carries exactly that line, and the built output
+ * keeps it, so the gate reported `commands/uiAudit.js → missing ./X` for a
+ * module nobody imports. That is a false red on a completeness gate, which is
+ * the worst kind: it says the shipped tarball is broken when it is not.
+ *
+ * ## Why the string state resets at every newline
+ *
+ * The first version carried quote state across the whole file, and it did not
+ * survive contact with that very comment: prose says `module's body`, and an
+ * apostrophe inside a comment is only inert while the lexer KNOWS it is inside
+ * one. One desync — a regex literal, an unpaired apostrophe reached in the
+ * wrong mode — and every subsequent `/*` reads as string content, so the doc
+ * comment is scanned as code and the false red survives the fix. Measured: the
+ * fix shipped, CI stayed red on the identical message.
+ *
+ * So block-comment state is tracked ACROSS lines (a block comment is the thing
+ * being removed) while quote state is tracked WITHIN one line and discarded at
+ * the newline. A desync then costs the remainder of one line instead of the
+ * remainder of the file. A multi-line template literal containing a relative
+ * specifier would be read as code — a false red, the same direction the gate
+ * already errs, and no such literal exists in the compiled output this walks.
+ */
+export function stripComments(source: string): string {
+    const out: string[] = [];
+    let inBlock = false;
+    for (const rawLine of source.split('\n')) {
+        let line = '';
+        let i = 0;
+        let quote: string | null = null;
+        while (i < rawLine.length) {
+            const c = rawLine[i] as string;
+            const next = rawLine[i + 1];
+            if (inBlock) {
+                if (c === '*' && next === '/') {
+                    inBlock = false;
+                    i += 2;
+                    continue;
+                }
+                i += 1;
+                continue;
+            }
+            if (quote !== null) {
+                line += c;
+                if (c === '\\' && next !== undefined) {
+                    line += next;
+                    i += 2;
+                    continue;
+                }
+                if (c === quote) quote = null;
+                i += 1;
+                continue;
+            }
+            if (c === '/' && next === '/') break;
+            if (c === '/' && next === '*') {
+                inBlock = true;
+                i += 2;
+                continue;
+            }
+            if (c === "'" || c === '"' || c === '`') quote = c;
+            line += c;
+            i += 1;
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
+
+export function parseRelativeSpecifiers(rawSource: string): string[] {
+    const source = stripComments(rawSource);
     const out = new Set<string>();
     const patterns = [
         /\bfrom\s*["']([^"']+)["']/g,

package/src/scripts/corpus_manifest.ts

@@ -0,0 +1,235 @@
+#!/usr/bin/env tsx
+/**
+ * `corpus_manifest` — pin the metered-proposer experiment's subject, and check
+ * that a fresh checkout reproduces it.
+ *
+ * Two verbs and no third. `capture` writes the pin from the tree as it stands;
+ * `verify` re-captures and reports every difference against a pin on disk.
+ * There is deliberately no `update` verb: a pin that can be refreshed in place
+ * is a pin that silently follows the tree, which is the property it exists not
+ * to have.
+ *
+ * `verify` exits 3 when the SUBJECT differs and 0 when only the explanatory
+ * fields do. That split is the whole point of the exit code — a different
+ * runtime version is a fact worth printing and is not a reason to refuse a
+ * comparison, while a different subject means the two runs measured different
+ * things and no amount of green elsewhere repairs it.
+ *
+ * Nothing here spends: it reads files and shells out to `git` for the commit.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { partitionActive } from '../install/partitionEligibility.js';
+import {
+    type CorpusManifest,
+    captureManifest,
+    diffManifests,
+    parseManifest,
+    serialiseManifest,
+    subjectsEquivalent,
+} from './_lib/corpus_manifest.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_USAGE = 2;
+/** The subject differs. Distinct from a plain error so a runner can branch. */
+export const EXIT_SUBJECT_DIFFERS = 3;
+
+/**
+ * The enumeration rule this manifest pins under, as an ID rather than prose.
+ *
+ * It is part of the digest, so changing the rule changes the subject even when
+ * every file hash is unchanged. That is correct: a corpus of the same five
+ * files selected by a different rule is a different experiment, and a digest
+ * that could not see the difference would let the selection semantics be
+ * amended without the pin noticing.
+ */
+export const ENUMERATION_RULE_ID = 'claude-rules-md-bytesorted-first-N/v1';
+
+const USAGE = `usage: corpus_manifest capture --out FILE [--limit N]
+       corpus_manifest verify --manifest FILE
+
+  capture   write the subject pin from the tree as it stands
+  verify    re-capture and report every difference against FILE
+
+  --limit N  corpus size, on CAPTURE only; defaults to max_candidates from the
+             pre-registered budget, which is the ceiling the run guard aborts
+             on. verify re-captures at the size its own manifest pinned, so it
+             REFUSES --limit rather than accepting a flag it cannot honour
+
+Exit: 0 ok  ·  1 error  ·  2 usage  ·  3 the SUBJECT differs
+`;
+
+/**
+ * The corpus size, read from the pre-registered budget rather than defaulted.
+ *
+ * Hardcoding five here would put a second copy of a pre-registered number in a
+ * file nobody would think to check when the budget changed, and the two would
+ * disagree in the direction that matters: a manifest pinning more subjects than
+ * the run guard admits describes an experiment that cannot be run.
+ */
+export function defaultLimit(repoRoot: string = REPO_ROOT): number {
+    const raw = JSON.parse(
+        fs.readFileSync(path.join(repoRoot, 'src', 'config', 'harness-evolution-budget.json'), 'utf-8'),
+    ) as { budget?: { max_candidates?: unknown } };
+    const n = raw.budget?.max_candidates;
+    if (typeof n !== 'number' || !Number.isInteger(n) || n <= 0) {
+        throw new Error('max_candidates missing or not a positive integer in the pre-registered budget');
+    }
+    return n;
+}
+
+interface Parsed {
+    verb?: string;
+    out?: string;
+    manifest?: string;
+    limit?: number;
+}
+
+export function parseArgs(argv: readonly string[]): Parsed | string {
+    const p: Parsed = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        if (!a.startsWith('--') && p.verb === undefined) {
+            p.verb = a;
+            continue;
+        }
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith('--')) return `${a} requires a value`;
+        i += 1;
+        if (a === '--out') p.out = v;
+        else if (a === '--manifest') p.manifest = v;
+        else if (a === '--limit') {
+            const n = Number(v);
+            if (!Number.isInteger(n) || n <= 0) return '--limit must be a positive integer';
+            p.limit = n;
+        } else return `unknown option '${a}'`;
+    }
+    if (p.verb === 'verify' && p.limit !== undefined) {
+        return (
+            'verify does not take --limit: it re-captures at the size its own manifest pinned, ' +
+            'because a re-capture at another corpus size is a comparison against another subject. ' +
+            'Accepting the flag and then using the pinned size reported green on a run that had ' +
+            'not honoured it'
+        );
+    }
+    return p;
+}
+
+/**
+ * One real capture over the real tree.
+ *
+ * This is the one caller for which the process globals `partitionActive` reads
+ * — the host layer under the running user's home, and the install lockfile —
+ * ARE this run's own host, so it is the one caller that passes the predicate.
+ * Everywhere else the field stays `null` rather than recording some other
+ * machine's state under this tree's name.
+ */
+function capture(limit: number): CorpusManifest {
+    return captureManifest({
+        repoRoot: REPO_ROOT,
+        userHome: process.env['HOME'] ?? os.homedir(),
+        limit,
+        enumerationRule: ENUMERATION_RULE_ID,
+        partitionActive,
+    });
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+        process.stdout.write(USAGE);
+        return args.length === 0 ? EXIT_USAGE : EXIT_OK;
+    }
+    const parsed = parseArgs(args);
+    if (typeof parsed === 'string') {
+        process.stderr.write(`corpus_manifest: error: ${parsed}\n${USAGE}`);
+        return EXIT_USAGE;
+    }
+
+    if (parsed.verb === 'capture') {
+        if (parsed.out === undefined) {
+            process.stderr.write(`corpus_manifest: error: capture requires --out FILE\n${USAGE}`);
+            return EXIT_USAGE;
+        }
+        let m: CorpusManifest;
+        try {
+            m = capture(parsed.limit ?? defaultLimit());
+        } catch (e) {
+            process.stderr.write(`corpus_manifest: capture refused — ${(e as Error).message}\n`);
+            return EXIT_ERROR;
+        }
+        fs.mkdirSync(path.dirname(path.resolve(parsed.out)), { recursive: true });
+        fs.writeFileSync(parsed.out, serialiseManifest(m), 'utf-8');
+        process.stdout.write(
+            `corpus_manifest: wrote ${parsed.out} · subject_digest=${m.subject_digest.slice(0, 16)} · ` +
+                `${String(m.included.length)} subject(s) · ${String(m.produced.length)} produced · ` +
+                `${String(m.user_scope.filter((t) => t.byte_identical).length)} byte-identical ` +
+                `twin(s), ${String(m.user_scope.filter((t) => t.causes_skip).length)} of them ` +
+                `causing a skip under ${String(m.generator_config['projection.scope_dedup'])}\n`,
+        );
+        if (m.tree_dirty) {
+            process.stdout.write(
+                'corpus_manifest: WARNING the working tree is dirty, so the recorded commit does not ' +
+                    'describe the bytes that were hashed\n',
+            );
+        }
+        return EXIT_OK;
+    }
+
+    if (parsed.verb === 'verify') {
+        if (parsed.manifest === undefined) {
+            process.stderr.write(`corpus_manifest: error: verify requires --manifest FILE\n${USAGE}`);
+            return EXIT_USAGE;
+        }
+        let expected: CorpusManifest;
+        let actual: CorpusManifest;
+        try {
+            expected = parseManifest(JSON.parse(fs.readFileSync(parsed.manifest, 'utf-8')));
+            actual = capture(expected.included.length);
+        } catch (e) {
+            process.stderr.write(`corpus_manifest: verify refused — ${(e as Error).message}\n`);
+            return EXIT_ERROR;
+        }
+        const diffs = diffManifests(expected, actual);
+        for (const d of diffs) {
+            process.stdout.write(`corpus_manifest: DIFF ${d.field}: expected ${d.expected}, got ${d.actual}\n`);
+        }
+        if (subjectsEquivalent(expected, actual)) {
+            process.stdout.write(
+                `corpus_manifest: SUBJECT EQUIVALENT · ${String(actual.included.length)} subject(s) · ` +
+                `digest=${actual.subject_digest.slice(0, 16)}` +
+                    (diffs.length > 0 ? ` · ${String(diffs.length)} explanatory difference(s) above\n` : '\n'),
+            );
+            return EXIT_OK;
+        }
+        process.stdout.write(
+            'corpus_manifest: SUBJECT DIFFERS — a comparison captured against this manifest is not ' +
+                'comparable to one captured here\n',
+        );
+        return EXIT_SUBJECT_DIFFERS;
+    }
+
+    process.stderr.write(`corpus_manifest: error: unknown verb ${JSON.stringify(parsed.verb)}\n${USAGE}`);
+    return EXIT_USAGE;
+}
+
+function _isCliEntry(): boolean {
+    try {
+        if (process.argv[1] === undefined) return false;
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/cost/budget.mjs

@@ -2,9 +2,16 @@
 // cost-budget — set / get / check the project's cost budget against
 // accumulated session spend in agents/cost-tracking/sessions.jsonl.
 //
-// Forked from ruvnet/ruflo plugins/ruflo-cost-tracker/scripts/budget.mjs.
-// Local-JSONL swap replaces the upstream `mcp__claude-flow__memory_store`
-// dependency. Budget config lives next to the sessions store as budget.json.
+// Derived work. The upstream, its MIT terms and the reproduced copyright and
+// permission notice are in CREDITS.md; the transformation record is in
+// docs/THIRD-PARTY-NOTICES.md, generated from provenance/borrows.jsonl. The
+// first two ship with the package, which is what discharges the obligation for
+// a consumer who receives this file from npm. The source is not named here
+// because a source name in a tracked source file is what
+// `source-confidentiality` forbids, and MIT discharges through a distributed
+// notice rather than an in-file one.
+// Local-JSONL swap replaces the upstream MCP memory-store dependency. Budget
+// config lives next to the sessions store as budget.json.
 //
 // Usage: node scripts/cost/budget.mjs {set <usd>|get|check}
 // Env: BUDGET_STORE, BUDGET_CONFIG, BUDGET_PERIOD={today|week|month|all}, BUDGET_QUIET=1

package/src/scripts/cost/track.mjs

@@ -2,9 +2,16 @@
 // cost-track — auto-capture token usage from a Claude Code session jsonl
 // and append a structured record to agents/cost-tracking/sessions.jsonl.
 //
-// Forked from ruvnet/ruflo plugins/ruflo-cost-tracker/scripts/track.mjs.
-// Local-JSONL swap replaces the upstream `mcp__claude-flow__memory_store`
-// dependency. Pricing constants are kept in sync with REFERENCE.md.
+// Derived work. The upstream, its MIT terms and the reproduced copyright and
+// permission notice are in CREDITS.md; the transformation record is in
+// docs/THIRD-PARTY-NOTICES.md, generated from provenance/borrows.jsonl. The
+// first two ship with the package, which is what discharges the obligation for
+// a consumer who receives this file from npm. The source is not named here
+// because a source name in a tracked source file is what
+// `source-confidentiality` forbids, and MIT discharges through a distributed
+// notice rather than an in-file one.
+// Local-JSONL swap replaces the upstream MCP memory-store dependency. Pricing
+// constants are kept in sync with REFERENCE.md.
 //
 // Dedup + main/subagent split, and the logic driving them, are mirrored
 // (not imported) from `src/scripts/_lib/cc_transcript.ts`: this file ships