@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/check_account_surface.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env tsx
+/**
+ * `check_account_surface` — a lexical, offline, read-only audit of a consumer
+ * repository's account-flow code (`road-to-account-surface-detector` Phase 2).
+ *
+ * It reports only what a local pattern proves. A class finding no pattern is
+ * listed as undecided, never as a passing surface: a regex that sees nothing
+ * has not seen a safe login. Until `claim:account-surface-finds-planted` is
+ * backed, every finding is printed as unmeasured.
+ *
+ * Remediation classes bind to `active-remediation`: `mechanical` is a fix that
+ * reuses a primitive the project already has and invents no policy, so it is a
+ * fix-now candidate; `policy` and `migration` are never applied — they are
+ * note-and-ask items carrying a "leave it as is" option.
+ *
+ * No writes, no subprocess, no network. Symlinks are not followed and files
+ * above {@link MAX_FILE_BYTES} are skipped and reported, so a hostile tree can
+ * neither escape the scanned root nor make the scan unbounded.
+ *
+ * Exit codes: 0 = the scan ran over at least one account-surface file
+ * (findings are advisory) · 1 = zero account-surface files matched — not a
+ * pass, since a scan that read nothing has not seen a safe login, so a
+ * repository with no login code reads 1 and its caller says why · 2 = usage.
+ */
+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, assertScanned } from './_lib/scan_scope.js';
+
+export type Evidence = 'violated' | 'suspected' | 'unknown' | 'not-applicable';
+export type Remediation = 'mechanical' | 'policy' | 'migration' | 'informational';
+
+export const MAX_FILE_BYTES = 256 * 1024;
+
+const PREDICATE = /login|register|signup|password|reset|verify|session|oauth|callback|mfa|otp|passkey/i;
+const CODE_EXT = new Set(['.php', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const SKIP_DIRS = new Set(['node_modules', 'vendor', '.git', 'dist', 'build', 'coverage']);
+
+interface ClassDef {
+    id: string;
+    threat_row: string;
+    evidence: Evidence;
+    remediation: Remediation;
+    /** Returns a short, secret-free description of the hit, or null. */
+    match: (line: string, file: string) => string | null;
+}
+
+const FAST_HASH = /\b(md5|sha1)\s*\(|createHash\(\s*['"](md5|sha1|sha256|sha512)['"]|\bhash\(\s*['"](md5|sha1|sha256|sha512)['"]/i;
+const CONSTANT_TIME = /hash_equals|timingSafeEqual|compare_digest|secure_compare|safeCompare/i;
+const SECRET_WORDS = new Set(['otp', 'token', 'secret', 'signature', 'sig', 'hmac', 'mac', 'nonce']);
+
+/** True when one word of the operand, split on case and punctuation, names a secret. */
+function namesSecret(operand: string): boolean {
+    return operand
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .some((w) => SECRET_WORDS.has(w));
+}
+const SECRET_PATH = /otp|mfa|totp|2fa|signature|webhook/i;
+const LITERAL = /^(null|undefined|true|false|NULL|\d+|'[^']*'|"[^"]*"|`[^`]*`)$/;
+const HOST_SOURCE = /getHost\(\)|getHttpHost\(\)|getSchemeAndHttpHost\(\)|\$_SERVER\[['"]HTTP_HOST['"]\]|req(uest)?\.headers\.host|req(uest)?\.get\(\s*['"]host['"]\s*\)|req\.hostname/;
+const TOKEN_KEY = String.raw`[^'"\x60]*(token|jwt|session|auth|bearer)[^'"\x60]*`;
+const WEB_STORAGE_SET = new RegExp(String.raw`(localStorage|sessionStorage)\.setItem\(\s*['"\x60]${TOKEN_KEY}['"\x60]`, 'i');
+const WEB_STORAGE_ASSIGN = new RegExp(
+    String.raw`(localStorage|sessionStorage)(\[\s*['"\x60]${TOKEN_KEY}['"\x60]\s*\]|\.\w*(token|jwt|session|auth|bearer)\w*)\s*=(?!=)`,
+    'i',
+);
+const DISCLOSURE = /['"`][^'"`]*(no account with|not registered|user not found|no such (user|account)|account (does not|doesn't) exist|unknown (email|user)|email (is )?not found)[^'"`]*['"`]/i;
+
+function equalityOperands(line: string): [string, string] | null {
+    const m = line.match(/(?<![=!<>])(===|!==|==|!=)(?![=])/);
+    if (!m || m.index === undefined) return null;
+    const left = line.slice(0, m.index).trimEnd().match(/([\w$>\-.'"()[\]]+)\s*$/)?.[1] ?? '';
+    const right = line.slice(m.index + m[0].length).match(/^\s*([\w$>\-.'"()[\]]+)/)?.[1] ?? '';
+    return [left.replace(/^\(+/, ''), right.replace(/\)+$/, '')];
+}
+
+export const CLASSES: readonly ClassDef[] = [
+    {
+        id: 'fast-hash',
+        threat_row: 'Fast or home-made password storage',
+        evidence: 'violated',
+        remediation: 'migration',
+        match: (line) => (FAST_HASH.test(line) && /password/i.test(line) ? 'general-purpose digest over a password' : null),
+    },
+    {
+        id: 'secret-compare',
+        threat_row: 'Unsafe secret comparison and home-made credential primitives',
+        evidence: 'violated',
+        remediation: 'mechanical',
+        match: (line, file) => {
+            if (CONSTANT_TIME.test(line)) return null;
+            const ops = equalityOperands(line);
+            if (!ops) return null;
+            const [a, b] = ops;
+            if (a === '' || b === '' || LITERAL.test(a) || LITERAL.test(b)) return null;
+            if (/\.length$|->length$|typeof/.test(a) || /\.length$|typeof/.test(b)) return null;
+            const secret = namesSecret(a) || namesSecret(b) || SECRET_PATH.test(file);
+            return secret ? 'secret compared with an ordinary equality operator' : null;
+        },
+    },
+    {
+        id: 'pepper-literal',
+        threat_row: 'Fast or home-made password storage',
+        evidence: 'violated',
+        remediation: 'migration',
+        match: (line) =>
+            /pepper\w*['"]?\s*(=>|=|:)\s*['"][^'"]+['"]/i.test(line) ? 'pepper assigned from a source literal (value withheld)' : null,
+    },
+    {
+        id: 'host-derived-reset',
+        threat_row: 'Password reset beyond the token',
+        evidence: 'violated',
+        remediation: 'mechanical',
+        match: (line, file) => (/reset|forgot|password/i.test(file) && HOST_SOURCE.test(line) ? 'link host taken from the request' : null),
+    },
+    {
+        id: 'email-linking',
+        threat_row: 'Federated sign-in account takeover',
+        evidence: 'violated',
+        remediation: 'policy',
+        match: (line) => (/allowDangerousEmailAccountLinking\s*:\s*true/.test(line) ? 'provider accounts linked on email alone' : null),
+    },
+    {
+        id: 'token-verify-off',
+        threat_row: 'Self-contained token validation bypass',
+        evidence: 'violated',
+        remediation: 'policy',
+        match: (line) =>
+            /algorithms?['"]?\s*(:|=>|=)\s*\[[^\]]*['"]none['"]/i.test(line) ||
+            /['"]?alg['"]?\s*(:|=>|=)\s*['"]none['"]/i.test(line) ||
+            /['"]?verify(_signature)?['"]?\s*(=>|:)\s*false\b/i.test(line)
+                ? 'token signature verification disabled or `none` accepted'
+                : null,
+    },
+    {
+        id: 'token-in-localstorage',
+        threat_row: 'Authentication token in script-readable browser storage',
+        evidence: 'violated',
+        remediation: 'migration',
+        match: (line) =>
+            WEB_STORAGE_SET.test(line) || WEB_STORAGE_ASSIGN.test(line) ? 'auth token written to script-readable storage' : null,
+    },
+    {
+        id: 'account-disclosure',
+        threat_row: 'Account enumeration through an observable difference',
+        evidence: 'suspected',
+        remediation: 'policy',
+        match: (line) => (DISCLOSURE.test(line) ? 'response text separates an unknown account from a wrong secret' : null),
+    },
+];
+
+export const REMEDIATION_BY_CLASS: Readonly<Record<string, Remediation>> = Object.fromEntries(
+    CLASSES.map((c) => [c.id, c.remediation]),
+);
+
+/** Sub-cases the lexical classes cannot decide; listed so absence never reads as a pass. */
+const UNDECIDED: readonly { class: string; reason: string }[] = [
+    { class: 'pepper-literal', reason: 'a credential-table column used as the pepper needs data flow, not a line pattern' },
+    { class: 'account-disclosure', reason: 'status codes, redirects, cookies and timing that differ per account are not string literals' },
+    { class: 'rate-limiting', reason: 'whether a limiter is wired to the login route needs a route relation the code graph does not emit' },
+    { class: 'session-lifecycle', reason: 'session rotation and server-side logout are behaviour, not a pattern on one line' },
+    { class: 'mfa-enforcement', reason: 'server-side second-factor enforcement cannot be read off a single file' },
+];
+
+export interface Finding {
+    class: string;
+    threat_row: string;
+    file: string;
+    line: number;
+    evidence: Evidence;
+    remediation: Remediation;
+    action: 'fix-now-candidate' | 'note-and-ask';
+    options: string[];
+    detail: string;
+}
+
+export interface Report {
+    measured: boolean;
+    root: string;
+    scanned_files: number;
+    findings: Finding[];
+    skipped: { file: string; reason: string }[];
+    undecided: { class: string; reason: string }[];
+}
+
+export function onAccountSurface(rel: string): boolean {
+    return CODE_EXT.has(path.extname(rel).toLowerCase()) && PREDICATE.test(rel);
+}
+
+function isComment(line: string): boolean {
+    return /^\s*(\/\/|#|\*|\/\*)/.test(line);
+}
+
+function optionsFor(remediation: Remediation): string[] {
+    if (remediation === 'mechanical') return ["apply the fix with the project's existing primitive", 'leave it as is'];
+    if (remediation === 'migration') return ['plan a migration with the owner', 'leave it as is'];
+    return ['decide the policy with the owner', 'leave it as is'];
+}
+
+export function scanAccountSurface(root: string): Report {
+    const findings: Finding[] = [];
+    const skipped: { file: string; reason: string }[] = [];
+    let scanned = 0;
+
+    const walk = (dir: string): void => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            const rel = path.relative(root, full).split(path.sep).join('/');
+            if (entry.isSymbolicLink()) {
+                skipped.push({ file: rel, reason: 'symlink not followed' });
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name)) walk(full);
+                continue;
+            }
+            if (!entry.isFile() || !onAccountSurface(rel)) continue;
+            if (fs.statSync(full).size > MAX_FILE_BYTES) {
+                skipped.push({ file: rel, reason: `larger than ${MAX_FILE_BYTES} bytes` });
+                continue;
+            }
+            scanned += 1;
+            const lines = fs.readFileSync(full, 'utf8').split('\n');
+            lines.forEach((line, i) => {
+                if (isComment(line)) return;
+                for (const cls of CLASSES) {
+                    const detail = cls.match(line, rel);
+                    if (detail === null) continue;
+                    findings.push({
+                        class: cls.id,
+                        threat_row: cls.threat_row,
+                        file: rel,
+                        line: i + 1,
+                        evidence: cls.evidence,
+                        remediation: cls.remediation,
+                        action: cls.remediation === 'mechanical' ? 'fix-now-candidate' : 'note-and-ask',
+                        options: optionsFor(cls.remediation),
+                        detail,
+                    });
+                }
+            });
+        }
+    };
+
+    walk(root);
+
+    return { measured: false, root, scanned_files: scanned, findings, skipped, undecided: [...UNDECIDED] };
+}
+
+function main(argv: string[]): number {
+    const json = argv.includes('--json');
+    const target = argv.find((a) => !a.startsWith('--'));
+    if (target === undefined) {
+        process.stderr.write('usage: check_account_surface <repo-root> [--json]\n');
+        return 2;
+    }
+    const root = path.resolve(target);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        process.stderr.write(`check_account_surface: ${root} is not a directory\n`);
+        return 2;
+    }
+    const report = scanAccountSurface(root);
+    if (json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+        process.stdout.write('check_account_surface — UNMEASURED: claim account-surface-finds-planted is unbacked\n');
+        for (const f of report.findings) {
+            process.stdout.write(`  [${f.evidence}] ${f.class} ${f.file}:${f.line} — ${f.detail} (${f.remediation}, ${f.action}; threat: ${f.threat_row})\n`);
+        }
+        for (const s of report.skipped) process.stdout.write(`  skipped ${s.file}: ${s.reason}\n`);
+        for (const u of report.undecided) process.stdout.write(`  undecided ${u.class}: ${u.reason}\n`);
+        process.stdout.write(`${report.scanned_files} account-surface file(s) scanned, ${report.findings.length} finding(s); absence of a finding is not a pass\n`);
+    }
+    // A warning here used to sit beside `return 0`: a gate whose predicate
+    // matched nothing reported "no findings" and passed, which is the shape
+    // `assertScanned` exists to refuse — an absence of findings over an empty
+    // corpus is not a reading. The deletion test applies: if the account
+    // surface moved or the predicate stopped matching, the reason "no findings"
+    // would still print and still be false, so no `allowEmpty` is written here.
+    try {
+        assertScanned({
+            gate: 'check_account_surface',
+            scanned: report.scanned_files,
+            units: 'account-surface file(s)',
+            roots: [path.relative(root, root) || '.'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    return 0;
+}
+
+/**
+ * True when this module is the process entry. Compared as resolved URLs, then
+ * as real paths: a raw `file://` string misses spaces, percent-encoding and
+ * symlinked paths (macOS `/var`), and a missed match exits 0 having run nothing.
+ */
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href ||
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_agent_artifact_location.ts

@@ -11,8 +11,10 @@
  * possible here, but it IS a reason to write the limit down: a gate whose reach
  * is not stated gets cited as broader than it is.
  *
- * The outward-facing half is `agent-config doctor --strict`, which already
- * knows the consumer shape and can now return a non-zero exit.
+ * The outward-facing half is the `artifact-location` row of `agent-config
+ * doctor` (`_lib/install_reach_checks.ts`). It runs the SAME detector, imported
+ * from `_lib/agent_artifact_location.ts`, reports a `warn` that never moves a
+ * file, and fails only under `doctor --strict --strict-level warn`.
  *
  * The constraint the detection rests on: every other mechanism that governs a
  * roadmap is keyed on the roadmap root, so a file placed outside it is governed
@@ -46,170 +48,25 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { is_roadmap_candidate as isRoadmapCandidate } from '../agent-src/scripts/update_roadmap_progress.js';
+import { ROADMAP_ROOT_REL, scan, type ScanResult } from './_lib/agent_artifact_location.js';
 import { reportScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
 
+// The detector moved to `_lib/agent_artifact_location.ts` so `doctor` can share
+// it; re-exported here so this gate's existing importers keep resolving.
+export {
+    ROADMAP_ROOT_REL,
+    isReviewInputRoadmapSnapshot,
+    roadmapShape,
+    scan,
+    type Finding,
+    type ScanResult,
+    type Shape,
+} from './_lib/agent_artifact_location.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
-/** The one legitimate home. Everything else is a finding. */
-export const ROADMAP_ROOT_REL = 'agents/roadmaps';
-
-/**
- * Directories the walk never enters.
- *
- * `dist/` and the per-tool projection trees are generated copies — a finding
- * there is a finding about `src/`, reported twice. `node_modules` and `.git`
- * are not this repository's prose.
- */
-const SKIP_DIRS: ReadonlySet<string> = new Set([
-    '.git',
-    'node_modules',
-    'dist',
-    '.augment',
-    '.claude',
-    '.cursor',
-    '.clinerules',
-    '.agents',
-    'coverage',
-    '.venv',
-]);
-
-/** Frontmatter keys that only a roadmap carries in this tree. */
-const FM_ROADMAP_RE = /^complexity:[ \t]*(lightweight|structural)[ \t]*$/m;
-/**
- * Anchored at the absolute start of the string — `^` with no `m` flag — on
- * purpose: this is a FRONTMATTER fence, which by the project's own convention
- * only means something at byte offset 0 of the file. A `---` fence that
- * begins three lines in is not frontmatter, it is a horizontal rule or a
- * quoted example, so loosening this to `m` would create false positives of
- * its own.
- *
- * The R2 review-input roadmap snapshots used to depend on that strictness as an
- * INCIDENTAL exemption: their two-line HTML-comment header, written for a
- * different gate, pushed this fence off offset 0. They are now exempt by path —
- * see `isReviewInputRoadmapSnapshot` — so neither the header nor this regex's
- * anchoring decides their fate any more.
- *
- * Tested in `check_agent_artifact_location.test.ts`
- * (describe: "review-input snapshot convention").
- */
-const FM_RE = /^---\n([\s\S]*?)\n---/;
-const PHASE_RE = /^##[ \t]+Phase[ \t]/m;
-const CHECKBOX_RE = /^[ \t]*- \[[ x~-]\][ \t]/m;
-
-export interface Shape {
-    /** Which signals fired. Empty means not roadmap-shaped. */
-    readonly signals: readonly string[];
-    readonly isRoadmap: boolean;
-}
-
-/**
- * Decide whether a file's CONTENT is a roadmap.
- *
- * All three signals are required. Each is individually common; together they are
- * this repository's roadmap format and nothing else's.
- */
-export function roadmapShape(text: string): Shape {
-    const signals: string[] = [];
-    const fm = FM_RE.exec(text);
-    if (fm !== null && FM_ROADMAP_RE.test(fm[1] as string)) {
-        signals.push('roadmap frontmatter (`complexity:` lightweight|structural)');
-    }
-    if (PHASE_RE.test(text)) {
-        signals.push('a `## Phase` heading');
-    }
-    if (CHECKBOX_RE.test(text)) {
-        signals.push('at least one checkbox step');
-    }
-    return { signals, isRoadmap: signals.length === 3 };
-}
-
-export interface Finding {
-    readonly rel: string;
-    readonly signals: readonly string[];
-}
-
-export interface ScanResult {
-    readonly findings: readonly Finding[];
-    /** Every `.md` file the walk visited — the scope, not the matches. */
-    readonly scanned: number;
-}
-
-function walkMarkdown(root: string): string[] {
-    const out: string[] = [];
-    const stack = [root];
-    while (stack.length > 0) {
-        const cur = stack.pop() as string;
-        let entries: fs.Dirent[];
-        try {
-            entries = fs.readdirSync(cur, { withFileTypes: true });
-        } catch {
-            continue;
-        }
-        for (const e of entries) {
-            if (e.isSymbolicLink()) continue;
-            const full = path.join(cur, e.name);
-            if (e.isDirectory()) {
-                if (!SKIP_DIRS.has(e.name)) stack.push(full);
-            } else if (e.name.toLowerCase().endsWith('.md')) {
-                out.push(full);
-            }
-        }
-    }
-    return out.sort();
-}
-
-/**
- * The one declared exemption: an R2 review-input roadmap snapshot.
- *
- * `dispatch_r2_reviewer.ts` writes a verbatim roadmap copy to exactly this
- * shape, and a file in it is non-authoritative evidence whoever wrote it —
- * nothing reads it back as a roadmap. Decided by path, not by a marker an
- * author could type anywhere (authority-routing roadmap 5.1, `## Decisions`):
- * measured 2026-10-07, every roadmap-shaped file outside the root was one of
- * these snapshots, so the path names the whole population and nothing else.
- * Takes the repository-relative POSIX path the walker produces; the walker
- * never follows a symlink, so a link cannot manufacture an exempt path.
- */
-const REVIEW_INPUT_SNAPSHOT_PATH_RE = /^agents\/evidence\/(?:[^/]+\/)*[^/.][^/]*\.review-input\/roadmap\.md$/;
-
-export function isReviewInputRoadmapSnapshot(rel: string): boolean {
-    return REVIEW_INPUT_SNAPSHOT_PATH_RE.test(rel) && !rel.split('/').some((s) => s === '..' || s === '.');
-}
-
-/** `true` when `child` is at or below `root`. */
-function isUnder(child: string, root: string): boolean {
-    const rel = path.relative(root, child);
-    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
-}
-
-export function scan(root: string): ScanResult {
-    const roadmapRoot = path.join(root, ...ROADMAP_ROOT_REL.split('/'));
-    const files = walkMarkdown(root);
-    const findings: Finding[] = [];
-    for (const f of files) {
-        if (isUnder(f, roadmapRoot)) continue;
-        if (isReviewInputRoadmapSnapshot(path.relative(root, f).split(path.sep).join('/'))) continue;
-        // Cheap name pre-filter first — the SHARED definition, imported, so the
-        // roadmap corpus and this guard cannot drift apart.
-        if (!isRoadmapCandidate(f)) continue;
-        let text: string;
-        try {
-            text = fs.readFileSync(f, 'utf-8');
-        } catch {
-            continue;
-        }
-        const shape = roadmapShape(text);
-        if (!shape.isRoadmap) continue;
-        findings.push({
-            rel: path.relative(root, f).split(path.sep).join('/'),
-            signals: shape.signals,
-        });
-    }
-    return { findings, scanned: files.length };
-}
 
 interface Args {
     quiet: boolean;

package/src/scripts/check_bundle_path_leakage.ts

@@ -103,11 +103,17 @@ const REPO = path.resolve(path.dirname(_HERE), '..', '..');
 // in case a future change tracks them too — `git ls-files` on an untracked
 // directory returns nothing, so listing an as-yet-untracked root here is
 // always safe.
+// The last entry is a pathspec, not a directory: the skill-script bundles sit
+// one per skill under `src/skills/`, and naming that directory would pull in
+// every corpus and prose file beside them. `src/` rather than the projection
+// because the two are byte-identical by the condensation invariant, and this
+// is the copy whose author can fix it.
 const BUNDLE_ROOTS: readonly string[] = [
     'dist/install',
     'dist/hooks',
     'dist/mcp',
     'dist/cli-delegate',
+    'src/skills/*/scripts/*.mjs',
 ];
 
 /**

package/src/scripts/check_ci_local_parity.ts

@@ -349,6 +349,14 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     }
     const r = analyse(REPO, mf);
 
+    // In `--format json` every other line goes to stderr: stdout carries the
+    // document and nothing else. Measured 2026-10-14 before this change —
+    // `JSON.parse` on stdout failed at position 28 039, because the narration
+    // below was appended to the document a caller was trying to read.
+    const say = (text: string): void => {
+        (wantJson ? process.stderr : process.stdout).write(text);
+    };
+
     if (wantJson) {
         process.stdout.write(`${JSON.stringify({ generated_by: 'check_ci_local_parity', ...r }, null, 2)}\n`);
     }
@@ -360,11 +368,11 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     let failed = false;
     if (r.undeclared_ci_only.length > 0) {
         failed = true;
-        process.stdout.write(
+        say(
             `❌  ${String(r.undeclared_ci_only.length)} gate(s) run in CI but are unreachable locally:\n`,
         );
-        for (const g of r.undeclared_ci_only) process.stdout.write(`  - ${g}\n`);
-        process.stdout.write(
+        for (const g of r.undeclared_ci_only) say(`  - ${g}\n`);
+        say(
             "\n    Either wire it into the `task ci` chain, or declare it under `ci_only:` in\n" +
                 '    src/config/ci-local-parity.yml with the reason it cannot run locally.\n' +
                 '    Undeclared, it means a contributor discovers this failure only after pushing.\n',
@@ -387,30 +395,30 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     });
     if (!parity.ok) {
         failed = true;
-        process.stdout.write(`❌  ${parity.message}\n`);
-        for (const g of r.undeclared_local_only) process.stdout.write(`  - ${g}\n`);
-        process.stdout.write(
+        say(`❌  ${parity.message}\n`);
+        for (const g of r.undeclared_local_only) say(`  - ${g}\n`);
+        say(
             '\n    Prefer adding it to a workflow — this is the direction that let real defects\n' +
                 '    merge (16 stale index rows reached main behind a local-only check-index).\n' +
                 '    If remote enforcement is genuinely not wanted, declare it under `local_only:`.\n' +
                 '    Raising the baseline is a defect, not a fix.\n',
         );
     } else {
-        process.stdout.write(`ℹ️   ${parity.message}\n`);
+        say(`ℹ️   ${parity.message}\n`);
     }
     if (r.stale_declarations.length > 0) {
         failed = true;
-        process.stdout.write(
+        say(
             `❌  ${String(r.stale_declarations.length)} stale declaration(s) — now on BOTH sides, so the exemption is dead:\n`,
         );
-        for (const g of r.stale_declarations) process.stdout.write(`  - ${g}\n`);
+        for (const g of r.stale_declarations) say(`  - ${g}\n`);
     }
 
     // Round 7 § 3.2 — printed on EVERY path, pass or fail, because the number is
     // the deliverable. A green parity verdict above says the local MIRROR matches
     // CI; it says nothing about the pass a contributor is told to run, and reading
     // the green line as if it did is the implication this block removes.
-    process.stdout.write(
+    say(
         `ℹ️   preflight: ${String(r.preflight_gates.length)} gate(s) of the ${String(r.local_gates.length)} local ones; ` +
             `${String(r.ci_not_in_preflight.length)} CI-enforced gate(s) run NEITHER in \`task preflight\` NOR\n` +
             '    anywhere else the pre-push hook reaches — i.e. the set that can only fail after\n' +
@@ -418,10 +426,10 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
             '    Report-only: the subset is deliberate (see the preflight docstring). A green\n' +
             '    preflight is therefore not a prediction that CI will be green.\n',
     );
-    for (const g of r.ci_not_in_preflight) process.stdout.write(`      · ${g}\n`);
+    for (const g of r.ci_not_in_preflight) say(`      · ${g}\n`);
 
     if (!failed) {
-        process.stdout.write(
+        say(
             `✅  CI ↔ local parity: ${String(r.ci_gates.length)} CI gate(s), ${String(r.local_gates.length)} local, ` +
                 `${String(mf.ci_only.length)} declared CI-only, ${String(mf.local_only.length)} declared local-only.\n`,
         );
@@ -441,5 +449,5 @@ function _isCliEntry(): boolean {
 }
 
 if (_isCliEntry()) {
-    process.exit(main());
+    process.exitCode = main();
 }