@event4u/agent-config 9.22.0 → 9.24.0

package/src/scripts/_lib/ratchet_base_ref.ts

@@ -0,0 +1,373 @@
+/**
+ * Shrink-only, enforced against the base ref instead of against a count.
+ *
+ * WHY THIS EXISTS. Every ratchet in this tree is shrink-only *by convention*
+ * plus a count comparison — and a count comparison permits
+ * swap-one-out-add-one-in. Removing a real entry and adding a fresh suppression
+ * in the same change keeps the number flat, passes the gate, and moves the
+ * estate backwards. The count cannot see it, because the count is the same.
+ *
+ * The fix is to compare the entry *sets*, and to read the "before" side from
+ * the base ref rather than from a checked-in number that the same commit can
+ * edit. `git show <baseRef>:<path>` is the only reading of the baseline that
+ * the change under review cannot rewrite.
+ *
+ * **Renames are read from git.** Moving a file must not read as growth: an
+ * entry keyed on a path that git reports as a rename of a path present at base
+ * is the same entry, relocated. Without this, the first legitimate refactor
+ * that moves an allowlisted file blocks itself, the gate gets a reputation for
+ * false reds, and someone turns it off — the gate-fatigue failure this
+ * repository has already recorded.
+ *
+ * **A deliberate reset is reported, never silent.** A real tooling change can
+ * legitimately re-baseline. That path exists ({@link RATCHET_RESET_KEY}) and
+ * costs a visible one-line diff carrying a reason; what it does not do is let
+ * the reset pass unannounced.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+
+/**
+ * Opt-in key that marks a baseline as deliberately re-based.
+ *
+ * Present with a non-empty string reason ⇒ growth is reported rather than
+ * thrown. The key lives in the baseline JSON itself so it shows up in the diff
+ * of the very commit that performs the reset.
+ */
+export const RATCHET_RESET_KEY = '__ratchet_reset__';
+
+/**
+ * Find a usable "before" ref, in descending order of trustworthiness.
+ *
+ * This ladder exists because the obvious answer — `origin/main` — is the one
+ * that is NOT available where it matters most. `actions/checkout` performs a
+ * shallow PR-merge fetch, so a PR build has no `origin/main` remote-tracking
+ * ref, and this repository has already recorded that `git fetch origin <base>`
+ * can race with the configured auth extraheader on some runners. The merge
+ * commit's first parent IS the base on exactly those builds, and it needs no
+ * network at all.
+ *
+ * Returns `null` when nothing resolves; callers decide, and the honest default
+ * is to fail rather than to compare against an assumed-empty base.
+ */
+export function resolveBaseRef(
+    repoRoot: string,
+    env: NodeJS.ProcessEnv = process.env,
+    git: (args: readonly string[], cwd: string) => { ok: boolean; stdout: string; stderr: string } = runGit,
+): string | null {
+    const resolves = (ref: string): boolean =>
+        git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], repoRoot).ok;
+
+    const explicit = env['RATCHET_BASE_REF'];
+    if (explicit !== undefined && explicit !== '' && resolves(explicit)) {
+        return explicit;
+    }
+    const ghBase = env['GITHUB_BASE_REF'];
+    if (ghBase !== undefined && ghBase !== '') {
+        for (const candidate of [`origin/${ghBase}`, ghBase]) {
+            if (resolves(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    // A PR-merge checkout: HEAD is the synthetic merge, HEAD^1 is the base tip.
+    //
+    // Gated on GITHUB_ACTIONS because "HEAD has two parents" is NOT specific to
+    // a PR-merge checkout: a feature branch that merged main back in has a merge
+    // commit at its tip too, and taking HEAD^1 there compares the branch against
+    // its own previous commit — a base so recent that every real change looks
+    // like growth. Observed on the first run of this resolver.
+    if (env['GITHUB_ACTIONS'] === 'true') {
+        const parents = git(['rev-list', '--parents', '-n', '1', 'HEAD'], repoRoot);
+        if (parents.ok && parents.stdout.trim().split(/\s+/).length >= 3 && resolves('HEAD^1')) {
+            return 'HEAD^1';
+        }
+    }
+    for (const candidate of ['origin/main', 'main']) {
+        if (resolves(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+
+/** Raised when the working copy carries entries the base ref does not. */
+export class RatchetGrowthError extends Error {
+    readonly baselinePath: string;
+    readonly added: readonly string[];
+
+    constructor(baselinePath: string, baseRef: string, added: readonly string[]) {
+        const shown = added.slice(0, 20);
+        const more = added.length - shown.length;
+        super(
+            `${baselinePath}: ${String(added.length)} entry(ies) present in the working copy and ` +
+                `absent at ${baseRef} — this baseline is shrink-only, and a flat count is not ` +
+                'evidence of that (removing one entry while adding another keeps the number ' +
+                `identical). Added: ${shown.join(', ')}${more > 0 ? ` … and ${String(more)} more` : ''}. ` +
+                `If this is a deliberate re-baseline, add "${RATCHET_RESET_KEY}": "<reason>" to the ` +
+                'file in the same commit so the reset is reviewable instead of silent.',
+        );
+        this.name = 'RatchetGrowthError';
+        this.baselinePath = baselinePath;
+        this.added = added;
+    }
+}
+
+/** Raised when the base ref cannot be read, so no honest comparison exists. */
+export class BaseRefUnavailableError extends Error {
+    constructor(baseRef: string, detail: string) {
+        super(
+            `cannot read the baseline at ${baseRef}: ${detail}. A ratchet that cannot see its ` +
+                '"before" has not verified anything — fetch the base ref (CI needs more than a ' +
+                'depth-1 clone) rather than treating the missing side as empty.',
+        );
+        this.name = 'BaseRefUnavailableError';
+    }
+}
+
+export type RatchetVerdict = 'ok' | 'growth' | 'reset' | 'new_baseline';
+
+export interface RatchetComparison {
+    verdict: RatchetVerdict;
+    /** Entries in the working copy that are absent at the base ref. */
+    added: string[];
+    /** Entries at the base ref that are absent in the working copy — the wanted direction. */
+    removed: string[];
+    /** Entries counted as unchanged because git reports the path as a rename. */
+    renamed: Array<{ from: string; to: string }>;
+    baseCount: number;
+    headCount: number;
+    /** Present only when the baseline carries {@link RATCHET_RESET_KEY}. */
+    resetReason?: string;
+}
+
+export interface RatchetBaseRefOptions {
+    /** Repo-relative path to the baseline file. */
+    baselinePath: string;
+    /** Ref to read the "before" side from, e.g. `origin/main`. */
+    baseRef: string;
+    /** Absolute repo root. */
+    repoRoot: string;
+    /**
+     * Extract the comparable entry keys from a parsed baseline.
+     *
+     * Defaults to {@link defaultEntriesOf}, which covers the two shapes this
+     * repo actually uses: a JSON array of strings, and a JSON object keyed by
+     * entry. A baseline with a nested shape passes its own extractor.
+     */
+    entriesOf?: (parsed: unknown) => string[];
+    /**
+     * Accept a baseline that does not exist at `baseRef` as genuinely new.
+     *
+     * Off by default: absent-at-base and mistyped-path look identical, and the
+     * silent-pass consequence of guessing wrong is the failure this module is
+     * built against. Turn it on for exactly the one change that introduces the
+     * baseline, then remove it.
+     */
+    allowNewBaseline?: boolean;
+    /** Injection seam for tests; defaults to a real `git` invocation. */
+    git?: (args: readonly string[], cwd: string) => { ok: boolean; stdout: string; stderr: string };
+}
+
+/** Run git, capturing output without throwing on a non-zero exit. */
+function runGit(args: readonly string[], cwd: string): { ok: boolean; stdout: string; stderr: string } {
+    const res = spawnSync('git', [...args], { cwd, encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 });
+    if (res.error) {
+        return { ok: false, stdout: '', stderr: res.error.message };
+    }
+    return { ok: res.status === 0, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
+}
+
+/**
+ * Entry keys for the two baseline shapes in this repository.
+ *
+ * - array of strings → the strings themselves;
+ * - array of objects → each object's `path`, `id`, `key`, `entry`, or `file`
+ *   field, whichever it carries first, falling back to its stable JSON form;
+ * - object → its own keys.
+ *
+ * {@link RATCHET_RESET_KEY} is never an entry.
+ */
+export function defaultEntriesOf(parsed: unknown): string[] {
+    if (Array.isArray(parsed)) {
+        return parsed.map((item) => {
+            if (typeof item === 'string') {
+                return item;
+            }
+            if (item !== null && typeof item === 'object') {
+                const rec = item as Record<string, unknown>;
+                for (const field of ['path', 'id', 'key', 'entry', 'file']) {
+                    const v = rec[field];
+                    if (typeof v === 'string' && v !== '') {
+                        return v;
+                    }
+                }
+            }
+            return JSON.stringify(item);
+        });
+    }
+    if (parsed !== null && typeof parsed === 'object') {
+        return Object.keys(parsed as Record<string, unknown>).filter((k) => k !== RATCHET_RESET_KEY);
+    }
+    return [];
+}
+
+function resetReasonOf(parsed: unknown): string | undefined {
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        const v = (parsed as Record<string, unknown>)[RATCHET_RESET_KEY];
+        if (typeof v === 'string' && v.trim() !== '') {
+            return v.trim();
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Map every renamed path at HEAD back to its name at `baseRef`.
+ *
+ * `-M` is what makes a moved allowlist entry read as the same entry rather
+ * than as one deletion plus one addition.
+ */
+function renameMap(
+    baseRef: string,
+    repoRoot: string,
+    git: NonNullable<RatchetBaseRefOptions['git']>,
+): Map<string, string> {
+    const out = new Map<string, string>();
+    const res = git(['diff', '--name-status', '-M', `${baseRef}...HEAD`], repoRoot);
+    if (!res.ok) {
+        return out;
+    }
+    for (const line of res.stdout.split('\n')) {
+        const parts = line.split('\t');
+        const status = parts[0];
+        if (status === undefined || !status.startsWith('R')) {
+            continue;
+        }
+        const from = parts[1];
+        const to = parts[2];
+        if (from !== undefined && to !== undefined) {
+            out.set(to, from);
+        }
+    }
+    return out;
+}
+
+/**
+ * Compare a baseline's entry set against the same file at `baseRef`.
+ *
+ * @throws {BaseRefUnavailableError} when the base ref cannot be read.
+ */
+export function compareToBaseRef(opts: RatchetBaseRefOptions): RatchetComparison {
+    const git = opts.git ?? runGit;
+    const entriesOf = opts.entriesOf ?? defaultEntriesOf;
+    const absolute = path.join(opts.repoRoot, opts.baselinePath);
+
+    let headRaw: string;
+    try {
+        headRaw = fs.readFileSync(absolute, 'utf-8');
+    } catch (e) {
+        throw new BaseRefUnavailableError(opts.baseRef, `working-copy baseline unreadable: ${String(e)}`);
+    }
+
+    const refCheck = git(['rev-parse', '--verify', '--quiet', `${opts.baseRef}^{commit}`], opts.repoRoot);
+    if (!refCheck.ok) {
+        throw new BaseRefUnavailableError(opts.baseRef, 'ref does not resolve in this clone');
+    }
+
+    // A baseline absent at base is EITHER a genuinely new ratchet OR a typo in
+    // `baselinePath`. Those two are indistinguishable from here, and treating
+    // the missing side as an empty set would make a mistyped path pass forever
+    // while comparing against nothing — the dead-scan-root shape, one level up.
+    // So it is fail-closed, and introducing a new baseline is an explicit
+    // opt-in the reviewer sees at the call site.
+    const show = git(['show', `${opts.baseRef}:${opts.baselinePath}`], opts.repoRoot);
+    if (!show.ok && opts.allowNewBaseline !== true) {
+        throw new BaseRefUnavailableError(
+            opts.baseRef,
+            `no such file at that ref (${opts.baselinePath}). If the baseline is genuinely new in ` +
+                'this change, pass allowNewBaseline; if it is not, the path is wrong and this gate ' +
+                'would otherwise compare against an empty set forever',
+        );
+    }
+    const baseEntries = show.ok ? entriesOf(JSON.parse(show.stdout)) : [];
+
+    const headParsed: unknown = JSON.parse(headRaw);
+    const headEntries = entriesOf(headParsed);
+
+    const renames = renameMap(opts.baseRef, opts.repoRoot, git);
+    const baseSet = new Set(baseEntries);
+    const headSet = new Set(headEntries);
+
+    const added: string[] = [];
+    const renamed: Array<{ from: string; to: string }> = [];
+    for (const entry of headEntries) {
+        if (baseSet.has(entry)) {
+            continue;
+        }
+        const previous = renames.get(entry);
+        if (previous !== undefined && baseSet.has(previous)) {
+            renamed.push({ from: previous, to: entry });
+            continue;
+        }
+        added.push(entry);
+    }
+    const removed = baseEntries.filter((e) => !headSet.has(e) && !renamed.some((r) => r.from === e));
+
+    const resetReason = resetReasonOf(headParsed);
+    let verdict: RatchetVerdict;
+    if (!show.ok) {
+        verdict = 'new_baseline';
+    } else if (added.length === 0) {
+        verdict = 'ok';
+    } else {
+        verdict = resetReason !== undefined ? 'reset' : 'growth';
+    }
+
+    const comparison: RatchetComparison = {
+        verdict,
+        added,
+        removed,
+        renamed,
+        baseCount: baseEntries.length,
+        headCount: headEntries.length,
+    };
+    if (resetReason !== undefined) {
+        comparison.resetReason = resetReason;
+    }
+    return comparison;
+}
+
+/**
+ * Assert a baseline gained no entries relative to `baseRef`.
+ *
+ * @throws {RatchetGrowthError} on growth without a declared reset.
+ * @throws {BaseRefUnavailableError} when the base ref cannot be read.
+ */
+export function assertNoNewEntries(opts: RatchetBaseRefOptions): RatchetComparison {
+    const comparison = compareToBaseRef(opts);
+    if (comparison.verdict === 'growth') {
+        throw new RatchetGrowthError(opts.baselinePath, opts.baseRef, comparison.added);
+    }
+    return comparison;
+}
+
+/**
+ * One-line human summary of a comparison, for a gate's green path.
+ *
+ * A reset is stated out loud, because a re-baseline that reads like a normal
+ * pass is the same silence this module removes.
+ */
+export function describeComparison(baselinePath: string, c: RatchetComparison): string {
+    const base = `${baselinePath}: ${String(c.headCount)} entry(ies), ${String(c.baseCount)} at base`;
+    const moved = c.renamed.length > 0 ? `, ${String(c.renamed.length)} renamed` : '';
+    if (c.verdict === 'new_baseline') {
+        return `${base}${moved} — NEW BASELINE (absent at base; nothing to ratchet against yet)`;
+    }
+    if (c.verdict === 'reset') {
+        return `${base}${moved} — RE-BASELINED (+${String(c.added.length)}): ${c.resetReason ?? ''}`;
+    }
+    return `${base}${moved}, ${String(c.removed.length)} removed since base`;
+}

package/src/scripts/check_gate_completeness.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env tsx
+/**
+ * Ledger adoption across the CI-registered gate estate.
+ *
+ * `_lib/gate_ledger.ts` makes a gate's per-target accounting explicit, so that
+ * "found nothing" and "looked at almost nothing" stop being the same green
+ * line. A library nobody adopts changes nothing, and a 220-gate sweep in one
+ * change is exactly the unreviewable diff that gets rubber-stamped — so
+ * adoption is a **ratchet**, not a deadline: today's un-adopted count is
+ * recorded, and it may only go down.
+ *
+ * A gate satisfies this check by either
+ *
+ *   1. importing `./_lib/gate_ledger.js`, or
+ *   2. carrying a `// ledger-exempt: <reason>` marker naming why per-target
+ *      accounting does not apply to it.
+ *
+ * The marker is deliberately cheap to write and expensive to write *badly*: an
+ * empty or near-empty reason is a hard failure rather than an exemption,
+ * because a marker that explains nothing is a suppression wearing a
+ * justification's clothes — the gate-fatigue failure this repository has
+ * already recorded.
+ *
+ * **Gaming risk** (per the authoring discipline this roadmap introduces): the
+ * cheapest degenerate pass is to sprinkle `// ledger-exempt:` markers with
+ * plausible-sounding boilerplate, which drops the count without improving a
+ * single gate. Mitigations, both partial and stated as such: the minimum
+ * reason length below rejects the laziest form, and the marker text lands in
+ * the diff where a reviewer sees it. What this gate CANNOT do is judge whether
+ * a reason is true; that stays a human read.
+ *
+ * **Lifecycle.** This gate lands ADVISORY over its existing population: the 217
+ * un-adopted gates are recorded as a baseline, not as 217 reds. It is already
+ * ENFORCED against growth from day one — a new gate must adopt or exempt.
+ * Promote to error over the whole population when the
+ * `check_gate_completeness` entry in `src/config/gate-violation-baselines.json`
+ * reaches 0.
+ *
+ * CLI contract: exit 0 = at or under the ratchet, 1 = regressed, marker
+ * malformed, or scope dead. `--quiet` suppresses the per-gate listing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { checkRatchet } from './_lib/gate_baseline.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { renderCoverage } from './_lib/measured_render.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { load_tasks, local_closure } from './check_ci_local_parity.js';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const QUIET = process.argv.slice(2).includes('--quiet');
+
+/** Task roots whose transitive closure defines "registered in the CI task list". */
+const TASK_ROOTS = ['ci', 'consistency'] as const;
+
+/** The marker that opts a gate out of per-target accounting. */
+export const EXEMPT_MARKER = '// ledger-exempt:';
+
+/**
+ * Shortest reason accepted after the marker.
+ *
+ * Not a quality bar — no length can be one. It rejects the specific degenerate
+ * form this check invites: `// ledger-exempt: n/a`.
+ */
+export const MIN_REASON_CHARS = 20;
+
+export interface GateCompletenessRow {
+    id: string;
+    status: 'ledgered' | 'exempt' | 'unledgered' | 'malformed_exemption';
+    reason?: string;
+}
+
+const LEDGER_IMPORT_RE = /^import\s.*from\s+'\.\/_lib\/gate_ledger\.js';/m;
+/**
+ * The marker must OPEN its own line.
+ *
+ * An unanchored match reads the marker out of prose — this gate's own
+ * docblock, which names the marker to explain it, exempted this gate from
+ * itself on the first run. A checker that its own documentation can silence is
+ * the false-green shape it exists to remove, so the anchor is load-bearing and
+ * is pinned by a fixture.
+ */
+const EXEMPT_RE = /^[ \t]*\/\/[ \t]*ledger-exempt:(.*)$/m;
+
+/** Classify one gate source. */
+export function classifyGateSource(id: string, source: string): GateCompletenessRow {
+    if (LEDGER_IMPORT_RE.test(source)) {
+        return { id, status: 'ledgered' };
+    }
+    const m = EXEMPT_RE.exec(source);
+    if (m === null) {
+        return { id, status: 'unledgered' };
+    }
+    const reason = (m[1] ?? '').trim();
+    if (reason.length < MIN_REASON_CHARS) {
+        return { id, status: 'malformed_exemption', reason };
+    }
+    return { id, status: 'exempt', reason };
+}
+
+/** Every gate id reachable from the CI task roots, script present or not. */
+export function registeredGateIds(repoRoot = REPO_ROOT): string[] {
+    return [...local_closure(TASK_ROOTS, load_tasks(repoRoot))].sort();
+}
+
+/**
+ * Classify every registered gate, accounting for the ones with no script.
+ *
+ * This gate dogfoods the ledger it enforces. The `.ts`-exists filter used to
+ * live in {@link registeredGateIds} as a silent `filter`, which meant a task
+ * pointing at a deleted script simply vanished from the denominator — the same
+ * invisible-skip shape the ledger exists to name. Now it is an out-of-scope
+ * outcome with a reason, and it prints.
+ */
+export function auditGateCompleteness(repoRoot = REPO_ROOT): {
+    rows: GateCompletenessRow[];
+    ledger: GateLedger;
+} {
+    const ledger = new GateLedger('check_gate_completeness');
+    const ids = registeredGateIds(repoRoot);
+    ledger.plan(ids);
+    const rows: GateCompletenessRow[] = [];
+    for (const id of ids) {
+        const file = path.join(repoRoot, 'src', 'scripts', `${id}.ts`);
+        if (!fs.existsSync(file)) {
+            ledger.outOfScope(id, 'manifest_absent');
+            continue;
+        }
+        const row = classifyGateSource(id, fs.readFileSync(file, 'utf-8'));
+        rows.push(row);
+        if (row.status === 'malformed_exemption') {
+            ledger.fail(id, 'exemption marker carries no usable reason');
+        } else {
+            ledger.complete(id);
+        }
+    }
+    return { rows, ledger };
+}
+
+export function main(): number {
+    const { rows, ledger } = auditGateCompleteness();
+
+    try {
+        assertScanned({
+            gate: 'check_gate_completeness',
+            scanned: rows.length,
+            units: 'registered gate(s)',
+            roots: ['Taskfile.yml → src/scripts'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const malformed = rows.filter((r) => r.status === 'malformed_exemption');
+    const unledgered = rows.filter((r) => r.status === 'unledgered');
+    const exempt = rows.filter((r) => r.status === 'exempt');
+    const ledgered = rows.filter((r) => r.status === 'ledgered');
+
+    // The denominator on the green path — auditable without waiting for a red —
+    // and the GAP LIST beside it. A coverage number published alone lets the
+    // reader assume the remainder is small and boring; naming it costs one line.
+    process.stdout.write(
+        `gate completeness: ${String(ledgered.length)} ledgered · ${String(exempt.length)} exempt · ` +
+            `${String(unledgered.length)} un-adopted · ${String(rows.length)} registered\n`,
+    );
+    process.stdout.write(
+        `${renderCoverage({
+            label: '  ledger coverage',
+            covered: ledgered.length + exempt.length,
+            total: rows.length,
+            gaps: unledgered.map((r) => r.id),
+            maxGaps: 6,
+        })}\n`,
+    );
+    ledger.report();
+    process.stdout.write(`scanned: ${String(rows.length)}\n`);
+
+    if (malformed.length > 0) {
+        process.stderr.write(
+            `\n❌  ${String(malformed.length)} exemption marker(s) carry no usable reason ` +
+                `(minimum ${String(MIN_REASON_CHARS)} characters). An exemption that explains ` +
+                'nothing is a suppression:\n',
+        );
+        for (const row of malformed) {
+            process.stderr.write(`    - ${row.id}: "${row.reason ?? ''}"\n`);
+        }
+        return 1;
+    }
+
+    const verdict = checkRatchet({
+        gate: 'check_gate_completeness',
+        actual: unledgered.length,
+        repoRoot: REPO_ROOT,
+    });
+
+    if (!QUIET && unledgered.length > 0 && verdict.status !== 'within') {
+        process.stdout.write('\nun-adopted gates:\n');
+        for (const row of unledgered) {
+            process.stdout.write(`    - ${row.id}\n`);
+        }
+    }
+
+    if (verdict.ok) {
+        if (!QUIET) {
+            process.stdout.write(`\n⚠️   ${verdict.message}\n`);
+        }
+        return 0;
+    }
+    process.stderr.write(`\n❌  ${verdict.message}\n`);
+    return 1;
+}
+
+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 (installed projection, or macOS /var → /private/var
+    // temp dirs) makes the raw URLs differ: compare realpaths so the entry guard
+    // still fires instead of silently no-opping.
+    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.exitCode = main();
+}
+
+export { QUIET, TASK_ROOTS };