@event4u/agent-config 12.0.0 → 13.0.0

package/src/scripts/bench_ab_v2_stats.ts

@@ -46,6 +46,15 @@ const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const REPORTS_DIR = path.join(REPO_ROOT, 'internal', 'bench', 'reports', 'ab-v2');
 const PRICING_PATH = path.join(REPO_ROOT, 'internal', 'bench', 'pricing.yaml');
 
+import { addPair, newPairedSample, searchClaimSection, searchClaimVerdict } from './_lib/bench_ab_search_adherence.js';
+import {
+    evaluateSizeClaim,
+    renderSizeClaimSection,
+    type PairedContinuous,
+    type PairedRate,
+    type SizeClaimVerdict,
+} from './_lib/bench_ab_size_claim.js';
+
 type Dict = Record<string, unknown>;
 
 const COMPARISONS: Array<[string, string, string]> = [
@@ -63,6 +72,10 @@ const COMPARISONS: Array<[string, string, string]> = [
     ['rules-kernel-dc', 'vanilla', 'kernel+downstream rules lift'],
     ['rules-balanced', 'vanilla', 'balanced-profile rules lift'],
     ['package', 'rules-kernel-dc', 'full package residual over kernel+downstream'],
+    // Phase-3 T1: the size claim is `package-ladder` vs `package`, and it is a
+    // metric PAIR — see `size_claim_verdict`. Arm-guarded like every row above,
+    // so a run without the ladder arm renders exactly as before.
+    ['package-ladder', 'package', 'ladder size claim (T1/T2 pair)'],
 ];
 
 // ── CPython math.erf / math.comb ports ────────────────────────────────────
@@ -312,6 +325,23 @@ export function compare(records: Dict[], arm_t: string, arm_b: string): Dict {
     let dropped_baseline_only = 0;
     let dropped_both = 0;
     const dropped_buckets: Record<string, number> = {};
+    // Delta #11 — the metric PAIR (T1 size, T2 complexity) and the T4 safety
+    // disqualifier. Each is collected pair-wise and independently: a pair that
+    // carries added lines but no complexity contributes to T1's sample and not
+    // to T2's, which is what keeps an absent endpoint reported as absent rather
+    // than as a value.
+    const size_t: number[] = [];
+    const size_b: number[] = [];
+    const size_diffs: number[] = [];
+    const cx_t: number[] = [];
+    const cx_b: number[] = [];
+    const cx_diffs: number[] = [];
+    let saf_n = 0;
+    let saf_t = 0;
+    let saf_bl = 0;
+    let saf_disc_t = 0;
+    let saf_disc_b = 0;
+    const sea = newPairedSample(); // T5 — continuous in [0,1], collects like complexity.
     for (const { rt, rb } of _pairs(records, arm_t, arm_b)) {
         pairs_seen += 1;
         const t_err = _pyTruthy(rt['errored']);
@@ -353,6 +383,36 @@ export function compare(records: Dict[], arm_t: string, arm_b: string): Dict {
             dis_t_sum += dt;
             dis_b_sum += db;
             disn += 1;
+
+            const mt = _dictOr(rt['metrics']);
+            const mb = _dictOr(rb['metrics']);
+
+            const at = _numOrNull(mt['added_lines']);
+            const ab = _numOrNull(mb['added_lines']);
+            if (at !== null && ab !== null) {
+                size_t.push(at);
+                size_b.push(ab);
+                size_diffs.push(at - ab);
+            }
+
+            const ct = _numOrNull(mt['median_cognitive_complexity']);
+            const cb = _numOrNull(mb['median_cognitive_complexity']);
+            if (ct !== null && cb !== null) {
+                cx_t.push(ct);
+                cx_b.push(cb);
+                cx_diffs.push(ct - cb);
+            }
+
+            const st = _boolOrNull(mt['safety_tier_pass']);
+            const sb2 = _boolOrNull(mb['safety_tier_pass']);
+            if (st !== null && sb2 !== null) {
+                saf_n += 1;
+                saf_t += st ? 1 : 0;
+                saf_bl += sb2 ? 1 : 0;
+                if (st && !sb2) saf_disc_t += 1;
+                else if (sb2 && !st) saf_disc_b += 1;
+            }
+            addPair(sea, mt['search_adherence'], mb['search_adherence']);
         }
     }
     void both1;
@@ -393,9 +453,80 @@ export function compare(records: Dict[], arm_t: string, arm_b: string): Dict {
             drop_asymmetry: dropped_treatment_only - dropped_baseline_only,
             dropped_by_status_bucket: dropped_buckets,
         },
+        size: _paired_median_block(size_t, size_b, size_diffs),
+        complexity: _paired_median_block(cx_t, cx_b, cx_diffs),
+        safety: _paired_rate_block(saf_n, saf_t, saf_bl, saf_disc_t, saf_disc_b),
+        search: _paired_median_block(sea.t, sea.b, sea.diffs),
+    };
+}
+
+/**
+ * A paired continuous endpoint (added lines, cognitive complexity).
+ *
+ * `measured: false` when no analysed pair carried the metric on BOTH sides. It
+ * is not a zero and not a neutral value: `size_claim_verdict` reads it as
+ * "unmeasured" and refuses to report a win, which is the whole point of shipping
+ * the endpoint rather than defaulting it.
+ */
+function _paired_median_block(t: number[], b: number[], diffs: number[]): Dict {
+    if (diffs.length === 0) {
+        return { measured: false, n_pairs: 0 };
+    }
+    const mt = _median(t);
+    const mb = _median(b);
+    const wil = wilcoxon(diffs);
+    // Percent change of the medians. A zero baseline has no percent change —
+    // report null rather than Infinity, which would render as a win.
+    const pct = mb === 0 ? null : PF(_pyRound(((mt - mb) / Math.abs(mb)) * 100, 4));
+    return {
+        measured: true,
+        n_pairs: diffs.length,
+        median_treatment: PF(_pyRound(mt, 4)),
+        median_baseline: PF(_pyRound(mb, 4)),
+        median_delta: PF(_pyRound(mt - mb, 4)),
+        median_delta_pct: pct,
+        wilcoxon_p: PF(wil.p),
+        rank_biserial: PF(wil.rank_biserial),
+        n_nonzero: wil.n,
+    };
+}
+
+/** A paired binary endpoint (the safety tier). Same `measured` contract. */
+function _paired_rate_block(n: number, t: number, b: number, disc_t: number, disc_b: number): Dict {
+    if (n === 0) {
+        return { measured: false, n_pairs: 0 };
+    }
+    const p1 = t / n;
+    const p2 = b / n;
+    return {
+        measured: true,
+        n_pairs: n,
+        rate_treatment: PF(_pyRound(p1, 4)),
+        rate_baseline: PF(_pyRound(p2, 4)),
+        discordant_b_only_treatment: disc_t,
+        discordant_c_only_baseline: disc_b,
+        mcnemar_p: PF(_pyRound(mcnemar_exact(disc_t, disc_b), 4)),
     };
 }
 
+/** Median over an already-collected sample; mean of the two middles when even. */
+function _median(values: readonly number[]): number {
+    const s = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(s.length / 2);
+    if (s.length % 2 === 1) return s[mid] as number;
+    return ((s[mid - 1] as number) + (s[mid] as number)) / 2;
+}
+
+function _numOrNull(v: unknown): number | null {
+    if (typeof v === 'number' && Number.isFinite(v)) return v;
+    return null;
+}
+
+function _boolOrNull(v: unknown): boolean | null {
+    if (typeof v === 'boolean') return v;
+    return null;
+}
+
 /**
  * Recursion's NOVEL discipline lift over rules-only (ADR-106).
  *
@@ -574,12 +705,64 @@ export function analyse(payload: Dict): Dict {
         seeds: payload['seeds'] ?? null,
         n_tasks: records.length,
         comparisons: comps,
+        // One verdict per rendered comparison. Present even when every endpoint
+        // is absent — an `INCONCLUSIVE` row naming the missing endpoint is the
+        // reportable fact; omitting the block would read as "no size question
+        // was asked", which is a different claim.
+        size_claims: comps.map((c) => size_claim_verdict(c)),
+        search_claims: comps.map((c) => searchClaimVerdict(c)), // separate on purpose — see the T5 lib
         status_buckets: bucket_rates(records, arms),
         mean_tokens: mean_tokens_by_arm(records, arms),
         cost: cost_by_arm(records, arms, payload['model'] ? String(payload['model']) : null, PRICING_PATH),
     };
 }
 
+// ── the size claim is a PAIR, and safety is a disqualifier ─────────────────
+//
+// The verdict itself lives in `_lib/bench_ab_size_claim.ts`: it is decision
+// logic over already-computed blocks, not statistics, and keeping it there makes
+// it a pure function with no dependency on this pipeline. What stays here is the
+// adapter — the `Dict`-shaped report objects this module speaks are coerced into
+// the typed input that module takes.
+
+/** Coerce one `compare()` block into the typed paired-continuous input. */
+function _toContinuous(block: Dict): PairedContinuous {
+    return {
+        measured: block['measured'] === true,
+        n_pairs: _pyFloat(block['n_pairs']),
+        median_delta_pct: block['median_delta_pct'] == null ? null : _pyFloat(block['median_delta_pct']),
+        median_delta: _pyFloat(block['median_delta']),
+        wilcoxon_p: _pyFloat(block['wilcoxon_p']),
+    };
+}
+
+function _toRate(block: Dict): PairedRate {
+    return {
+        measured: block['measured'] === true,
+        n_pairs: _pyFloat(block['n_pairs']),
+        rate_treatment: _pyFloat(block['rate_treatment']),
+        rate_baseline: _pyFloat(block['rate_baseline']),
+        mcnemar_p: _pyFloat(block['mcnemar_p']),
+    };
+}
+
+/** The Phase-3 size claim for one comparison. Contract: `evaluateSizeClaim`. */
+export function size_claim_verdict(comparison: Dict): Dict {
+    return evaluateSizeClaim({
+        arm_treatment: comparison['arm_treatment'] == null ? null : String(comparison['arm_treatment']),
+        arm_baseline: comparison['arm_baseline'] == null ? null : String(comparison['arm_baseline']),
+        size: _toContinuous(_dictOr(comparison['size'])),
+        complexity: _toContinuous(_dictOr(comparison['complexity'])),
+        safety: _toRate(_dictOr(comparison['safety'])),
+    }) as unknown as Dict;
+}
+
+function _size_claim_section(a: Dict): string[] {
+    const claims = Array.isArray(a['size_claims']) ? (a['size_claims'] as unknown as SizeClaimVerdict[]) : [];
+    return renderSizeClaimSection(claims);
+}
+
+
 export function gate_verdict(analysis: Dict): Dict {
     // L4 gate: PASS if ANY axis shows significant paired lift for package vs
     // vanilla (McNemar p<0.05 OR Wilcoxon p<0.05 OR a status-bucket reduction).
@@ -604,6 +787,13 @@ export function gate_verdict(analysis: Dict): Dict {
         capability_significant: cap_sig,
         discipline_significant: dis_sig,
         status_bucket_better: bucket_better,
+        // Goodhart guard, structural: this gate reads capability, discipline and
+        // status buckets ONLY. Size never enters it, so no arm can be ranked
+        // above another here by producing a smaller diff. The size question has
+        // exactly one home — `size_claim_verdict` — and that function refuses a
+        // win whenever the safety tier regressed or is unmeasured.
+        size_considered: false,
+        size_claim_owner: 'size_claim_verdict',
         note:
             'PASS = significant paired discipline/capability lift; ' +
             'FALSIFIED only if also trivial across seeds (inspect n_pairs).',
@@ -660,6 +850,7 @@ export function to_markdown(analysis: Dict, payload: Dict): string {
     L.push(`- discipline lift significant: \`${_pyStr(g['discipline_significant'])}\``);
     L.push(`- status-bucket better (package vs vanilla): \`${_pyStr(g['status_bucket_better'])}\``);
     L.push('');
+    L.push(..._size_claim_section(a), '', ...searchClaimSection(a));
     if (g['verdict'] === 'PASS') {
         L.push(
             '> **Measurable discipline lift (significant).** On the scope-creep / ' +

package/src/scripts/build_archive_index.ts

@@ -0,0 +1,383 @@
+#!/usr/bin/env tsx
+/**
+ * Build a machine-readable index over the roadmap archive.
+ *
+ * "Has this already been tried, closed, or refuted?" is answered today by
+ * walking `agents/roadmaps/archive/` — 500 top-level files. This emits
+ * `INDEX.md` (human) and `index.json` (machine) beside them so the question
+ * costs one read instead of a walk.
+ *
+ * ## What is and is not extracted
+ *
+ * Every field is derived by a deterministic rule from the file's own bytes.
+ * There are NO model-written summaries: a verdict the frontmatter does not
+ * carry is emitted as `null` in JSON and `not extractable` in the table, so a
+ * reader can tell a missing verdict from an invented one. That is the
+ * roadmap's non-goal, enforced here rather than promised.
+ *
+ * `disposition` is the one derived field, and it is derived from the checkbox
+ * tally alone — including acceptance-criteria boxes, which are checkboxes in
+ * the same file and are not distinguished. It records how the file LOOKS at
+ * archival, never why it was archived:
+ *
+ * | tally | disposition |
+ * |---|---|
+ * | no checkbox anywhere | `not-extractable` |
+ * | any `[ ]` | `archived-with-open-steps` |
+ * | any `[-]`, none open | `closed-with-cancellations` |
+ * | any `[~]`, none open/cancelled | `completed-with-deferrals` |
+ * | otherwise | `completed` |
+ *
+ * ## Drift
+ *
+ * `--check` regenerates in memory and compares byte-for-byte against the two
+ * committed artefacts, following the shape `compile_router --check` already
+ * uses. A generated artefact nobody re-derives goes stale in one merge.
+ *
+ * The output carries no timestamp on purpose — a clock in a generated file
+ * makes every `--check` run a false red. The generation time lives in git
+ * history, the same convention `agents/roadmaps-progress.md` states.
+ *
+ * Reuses `validate_frontmatter`'s reader; this file adds no second parser.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+import { parse_frontmatter } from './validate_frontmatter.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const ARCHIVE_REL = 'agents/roadmaps/archive';
+const INDEX_MD = 'INDEX.md';
+const INDEX_JSON = 'index.json';
+
+/** The generated artefacts themselves are never indexed. */
+const SELF: ReadonlySet<string> = new Set([INDEX_MD, INDEX_JSON]);
+
+/** `- [ ]` / `* [x]` / `- [~]` / `- [-]`, the four glyphs the roadmaps use. */
+const CHECKBOX_RE = /^[ \t]*[-*][ \t]+\[([ xX~-])\][ \t]/;
+
+/** `## Phase 3 — …` or `### Phase 0: …`. Two heading levels are in use. */
+const PHASE_RE = /^#{2,3}[ \t]+Phase\b/;
+
+/** The first level-1 heading, used as the title when frontmatter has none. */
+const H1_RE = /^#[ \t]+(.+?)[ \t]*$/;
+
+export type Disposition =
+    | 'completed'
+    | 'completed-with-deferrals'
+    | 'closed-with-cancellations'
+    | 'archived-with-open-steps'
+    | 'not-extractable';
+
+export interface StepTally {
+    open: number;
+    done: number;
+    deferred: number;
+    cancelled: number;
+}
+
+export interface ArchiveEntry {
+    slug: string;
+    title: string | null;
+    disposition: Disposition;
+    phases: number;
+    steps: StepTally;
+    /** Frontmatter `verdict:`, verbatim. `null` = the file carries none. */
+    verdict: string | null;
+    /** Frontmatter `status:`, verbatim. Authoring status, not a closure. */
+    status: string | null;
+}
+
+/** Frontmatter value → string, or `null` for absent / non-scalar. */
+function _scalar(value: unknown): string | null {
+    if (typeof value === 'string') {
+        const t = value.trim();
+        return t === '' ? null : t;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return null;
+}
+
+/**
+ * Frontmatter, or `{}` when the file has none or carries a malformed block.
+ *
+ * A 500-file corpus assembled over months contains frontmatter the strict
+ * subset parser rejects; that is a property of the archive, not an error in
+ * this pass. Such a file still gets an entry — with its frontmatter-derived
+ * fields absent, which is exactly what "not extractable" means.
+ */
+function _frontmatter(text: string): Record<string, unknown> {
+    try {
+        const [data] = parse_frontmatter(text);
+        return data ?? {};
+    } catch {
+        return {};
+    }
+}
+
+/** Body lines, i.e. everything after a frontmatter block if one is present. */
+function _bodyLines(text: string): string[] {
+    const lines = text.split('\n');
+    if (lines[0]?.trimEnd() !== '---') {
+        return lines;
+    }
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i]?.trimEnd() === '---') {
+            return lines.slice(i + 1);
+        }
+    }
+    return lines;
+}
+
+export function tally(bodyLines: readonly string[]): StepTally {
+    const t: StepTally = { open: 0, done: 0, deferred: 0, cancelled: 0 };
+    for (const line of bodyLines) {
+        const m = CHECKBOX_RE.exec(line);
+        if (m === null) {
+            continue;
+        }
+        switch (m[1]) {
+            case ' ':
+                t.open += 1;
+                break;
+            case '~':
+                t.deferred += 1;
+                break;
+            case '-':
+                t.cancelled += 1;
+                break;
+            default:
+                t.done += 1;
+        }
+    }
+    return t;
+}
+
+export function disposition(t: StepTally): Disposition {
+    if (t.open + t.done + t.deferred + t.cancelled === 0) {
+        return 'not-extractable';
+    }
+    if (t.open > 0) {
+        return 'archived-with-open-steps';
+    }
+    if (t.cancelled > 0) {
+        return 'closed-with-cancellations';
+    }
+    if (t.deferred > 0) {
+        return 'completed-with-deferrals';
+    }
+    return 'completed';
+}
+
+export function buildEntry(slug: string, text: string): ArchiveEntry {
+    const fm = _frontmatter(text);
+    const body = _bodyLines(text);
+
+    let title = _scalar(fm['title']);
+    if (title === null) {
+        for (const line of body) {
+            const m = H1_RE.exec(line);
+            if (m !== null) {
+                title = (m[1] ?? '').trim() || null;
+                break;
+            }
+        }
+    }
+
+    const steps = tally(body);
+    return {
+        slug,
+        title,
+        disposition: disposition(steps),
+        phases: body.filter((l) => PHASE_RE.test(l)).length,
+        steps,
+        verdict: _scalar(fm['verdict']),
+        status: _scalar(fm['status']),
+    };
+}
+
+/** Top-level `*.md` under the archive, sorted, excluding the generated pair. */
+export function archiveFiles(dir: string): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => !e.isDirectory() && e.name.endsWith('.md') && !SELF.has(e.name))
+        .map((e) => e.name)
+        .sort();
+}
+
+export function buildIndex(dir: string): ArchiveEntry[] {
+    return archiveFiles(dir).map((name) =>
+        buildEntry(name.replace(/\.md$/, ''), fs.readFileSync(path.join(dir, name), 'utf8')),
+    );
+}
+
+/** Table-cell text: pipes escaped, newlines flattened, never empty. */
+function _cell(value: string | null): string {
+    if (value === null) {
+        return '_not extractable_';
+    }
+    return value.replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim();
+}
+
+export function renderJson(entries: readonly ArchiveEntry[]): string {
+    return (
+        JSON.stringify(
+            {
+                generated_by: 'src/scripts/build_archive_index.ts',
+                source: ARCHIVE_REL,
+                count: entries.length,
+                entries,
+            },
+            null,
+            2,
+        ) + '\n'
+    );
+}
+
+export function renderMarkdown(entries: readonly ArchiveEntry[]): string {
+    const byDisposition = new Map<Disposition, number>();
+    for (const e of entries) {
+        byDisposition.set(e.disposition, (byDisposition.get(e.disposition) ?? 0) + 1);
+    }
+    const summary = [...byDisposition.entries()]
+        .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+        .map(([d, n]) => `${d} ${String(n)}`)
+        .join(' · ');
+
+    const out: string[] = [
+        '# Archive index',
+        '',
+        '> Auto-generated — do not edit. Regenerate with `task build-archive-index`;',
+        '> `task check-archive-index` fails on drift. Generation time lives in git',
+        '> history, not in this file (a clock here would make every drift check a',
+        '> false red).',
+        '',
+        `**${String(entries.length)} archived roadmaps** · ${summary}`,
+        '',
+        'Every column is extracted deterministically from the file itself. No',
+        'summary here is model-written: a verdict the frontmatter does not carry',
+        'reads _not extractable_ rather than being inferred. `Disposition` is',
+        'derived from the checkbox tally alone (acceptance-criteria boxes',
+        'included) and records how the file looks, never why it was archived —',
+        'so for anything the index marks _not extractable_, open the file.',
+        '',
+        '**Limits worth knowing before you rely on this.** Only a handful of',
+        'archived roadmaps carry a frontmatter `verdict:`, so the index answers',
+        '_tried?_ and _closed?_ and sends you to the file for _why_. The measured',
+        'saving is 82 % fewer files opened on a pre-registered question set — and',
+        'below roughly five candidate files it is a wash, so a single narrow',
+        'question is cheaper answered directly. Reading, method and full',
+        'distribution: [`archive-index-saving`](../../evidence/analysis/archive-index-saving.md).',
+        '',
+        '| Roadmap | Title | Disposition | Phases | Steps (done/total) | Verdict |',
+        '|---|---|---|---:|---|---|',
+    ];
+
+    for (const e of entries) {
+        const total = e.steps.open + e.steps.done + e.steps.deferred + e.steps.cancelled;
+        const steps = total === 0 ? '—' : `${String(e.steps.done)}/${String(total)}`;
+        out.push(
+            `| [\`${e.slug}\`](${e.slug}.md) | ${_cell(e.title)} | ${e.disposition} | ` +
+                `${String(e.phases)} | ${steps} | ${_cell(e.verdict)} |`,
+        );
+    }
+    out.push('');
+    return out.join('\n');
+}
+
+function _read(p: string): string | null {
+    try {
+        return fs.readFileSync(p, 'utf8');
+    } catch {
+        return null;
+    }
+}
+
+export function main(argv: readonly string[]): number {
+    const quiet = argv.includes('--quiet');
+    const dir = path.join(ROOT, ARCHIVE_REL);
+
+    const entries = buildIndex(dir);
+    try {
+        reportScanned({
+            gate: 'build_archive_index',
+            scanned: entries.length,
+            units: 'archived roadmap(s)',
+            roots: [ARCHIVE_REL],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+
+    const mdPath = path.join(dir, INDEX_MD);
+    const jsonPath = path.join(dir, INDEX_JSON);
+    const md = renderMarkdown(entries);
+    const json = renderJson(entries);
+
+    if (argv.includes('--check')) {
+        const stale = [
+            _read(mdPath) === md ? null : `${ARCHIVE_REL}/${INDEX_MD}`,
+            _read(jsonPath) === json ? null : `${ARCHIVE_REL}/${INDEX_JSON}`,
+        ].filter((v): v is string => v !== null);
+        if (stale.length > 0) {
+            process.stderr.write(
+                `❌  archive index out of date (${stale.join(', ')}) — run \`task build-archive-index\`\n`,
+            );
+            return 1;
+        }
+        if (!quiet) {
+            process.stdout.write('✅  archive index is up to date\n');
+        }
+        return 0;
+    }
+
+    fs.writeFileSync(mdPath, md, 'utf8');
+    fs.writeFileSync(jsonPath, json, 'utf8');
+    if (!quiet) {
+        process.stdout.write(
+            `✅  archive index — ${String(entries.length)} roadmap(s) → ` +
+                `${ARCHIVE_REL}/{${INDEX_MD},${INDEX_JSON}}\n`,
+        );
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (an installed projection, or macOS /var →
+    // /private/var temp dirs) makes the raw URLs differ: import.meta.url is
+    // the resolved real path while argv[1] keeps the symlink path.
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main(process.argv.slice(2)));
+}