@tokenfactory/acc-runner 0.29.4 → 0.33.0

package/dist/prepr-gate.d.ts

@@ -1,4 +1,4 @@
-export type PreprGateName = "typecheck" | "lint" | "build" | "test" | "migration-lint";
+export type PreprGateName = "nul-check" | "scope" | "typecheck" | "lint" | "build" | "test" | "migration-lint";
 /**
  * Run order. typecheck → lint → build → test mirrors the CLAUDE.md quality-gate
  * order (cheapest / most-likely-to-fail first) so a broken worktree fails on
@@ -25,6 +25,28 @@ export interface PreprGateResult {
     absent: PreprGateName[];
     /** Set iff `ok === false`: the first gate that failed + its output tail. */
     failure?: PreprGateFailure;
+    /**
+     * SHADOW MODE: set when the migration linter reported findings but the
+     * `migration_lint_blocking` knob is OFF — the PR was NOT blocked, but the
+     * output is surfaced so the caller can log it (advisory). `ok` stays `true`.
+     * Never set in blocking mode (there a finding lands in `failure` instead).
+     */
+    migrationLintShadow?: {
+        exitCode: number | null;
+        /** Tail of the linter's findings output — log-safe. */
+        outputTail: string;
+    };
+    /**
+     * V96 (R5) SHADOW MODE: set when staged files fell outside the task's
+     * `allowed` globs but the scope-enforce knob was OFF — the PR was NOT blocked
+     * (advisory only). `ok` stays `true`. In enforce mode the violation lands in
+     * `failure` (gate `scope`) instead and this is unset.
+     */
+    scopeShadow?: {
+        /** Repo-relative staged paths that matched none of the allowed globs. */
+        offending: string[];
+        outputTail: string;
+    };
 }
 export interface PreprGateDeps {
     /**
@@ -65,9 +87,117 @@ export interface PreprGateDeps {
         exitCode: number | null;
         output: string;
     }>;
+    /**
+     * SHADOW-WEEK knob. When the migration linter reports a lint ERROR (exit ≠ 0):
+     *   • `true`  → block the PR (fail the gate) — the linter's output lands in
+     *               the runner log via `failure.outputTail`.
+     *   • `false` → advisory: log the findings (`migrationLintShadow`) but open
+     *               the PR anyway.
+     * This mirrors the org `acc.org_settings.migration_lint_blocking` knob, which
+     * defaults to `false` (shadow). The task-runner resolves that org setting and
+     * passes it here; when unset (dep + `ACC_MIGRATION_LINT_BLOCKING` env both
+     * absent) this defaults to `false` (shadow) — defaults ship OFF; blocking is
+     * an explicit opt-in via the org knob or the env.
+     */
+    migrationLintBlocking?: boolean;
+    /**
+     * V96 (R5): the task's `allowed` file globs. When non-empty, the scope check
+     * flags every staged file that matches NONE of these globs. Empty/undefined
+     * disables the scope check entirely (a task with no declared scope is not
+     * scope-checked). Never enforced-by-default — see `scopeEnforce`.
+     */
+    allowedGlobs?: string[];
+    /**
+     * V96 (R5) knob (DEFAULT OFF). When true a scope violation FAILS the gate
+     * (HALT — no PR opened). When false/unset the violation is advisory
+     * (`scopeShadow`, PR still opens). Precedence mirrors migrationLintBlocking:
+     * explicit dep, else `ACC_PREPR_SCOPE_ENFORCE` env, else `false`.
+     */
+    scopeEnforce?: boolean;
+    /**
+     * V96 (R4/R5): the staged files (repo-relative) this branch added/changed vs
+     * `baseRef`. Default: `git diff --name-only --diff-filter=ACMR <base>...HEAD`.
+     * Drives BOTH the NUL/binary check and the scope check. Omitted + no `baseRef`
+     * → both checks are skipped (unit suite never shells out to git).
+     */
+    listStagedFiles?: (workdir: string, baseRef?: string) => Promise<string[]>;
+    /**
+     * V96 (R4): read a staged file's raw bytes (for the NUL/binary scan). Default:
+     * `fs.readFile(join(workdir, file))`. Injectable so the unit suite can feed a
+     * NUL fixture without a real file.
+     */
+    readFileBytes?: (workdir: string, file: string) => Promise<Buffer>;
+}
+/**
+ * Text-source extensions the NUL/binary check scans. An allowlist (never a
+ * binary denylist) so genuine binary assets — images, fonts, the design export —
+ * are never false-positives. Kept in sync with scripts/ci/check-no-binary-source.mjs
+ * (the CI backstop for the SAME defect class); the runner package cannot import
+ * that .mjs, so the list is duplicated per the standing cross-package convention.
+ */
+export declare const TEXT_EXTENSIONS: Set<string>;
+/** True when `p` has a text-source extension the NUL check scans. */
+export declare function isTextSourcePath(p: string): boolean;
+export interface NulHit {
+    path: string;
+    /** Byte offset of the first NUL. */
+    offset: number;
+    /** 1-based line of the NUL byte. */
+    line: number;
+    /** 1-based byte column within the line. */
+    col: number;
 }
-/** Escape-hatch flag. Matches the truthy convention in anthropic-auth.ts. */
+/** Offset of the first NUL byte in `buf`, or -1 if there is none. */
+export declare function firstNulOffset(buf: Buffer): number;
+/** 1-based {line, col} of byte `offset` within `buf` (col counts bytes). */
+export declare function lineColOf(buf: Buffer, offset: number): {
+    line: number;
+    col: number;
+};
+/**
+ * Build the log-safe failure message for a NUL hit. Names the file, the byte
+ * offset, and the 1-based line:col — the exact pointer the reviewer needed for
+ * PR #1059 (a single NUL byte burned two review cycles).
+ */
+export declare function formatNulFailure(hit: NulHit): string;
+/**
+ * Convert one `allowed`-list glob into a RegExp anchored to a full repo-relative
+ * path. Semantics:
+ *   - `**` matches any run of chars INCLUDING `/`;
+ *   - `*` matches any run of chars EXCLUDING `/` (within one path segment);
+ *   - `?` matches a single non-`/` char;
+ *   - a pattern ending in `/` (or a bare directory with no wildcard) matches
+ *     everything beneath that directory prefix;
+ *   - every other char is matched literally.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+/**
+ * True when `file` (repo-relative) matches ANY of `globs`, OR when a wildcard-free
+ * glob names a directory that `file` sits beneath (`api/_lib` matches
+ * `api/_lib/x.ts`). Fail-open on an empty glob list — a task that declares no
+ * scope is treated as "everything allowed" (the caller gates on non-empty).
+ */
+export declare function matchesAllowedGlobs(file: string, globs: string[]): boolean;
+/** Repo-relative staged paths that match NONE of the allowed globs. */
+export declare function scopeViolations(files: string[], globs: string[]): string[];
+/**
+ * Resolve whether a scope violation BLOCKS the PR. Precedence:
+ *   1. explicit `deps.scopeEnforce`, else
+ *   2. the `ACC_PREPR_SCOPE_ENFORCE` env (`1/true/yes/on` → enforce), else
+ *   3. `false` — advisory/shadow (defaults ship OFF; enforcement is opt-in).
+ */
+export declare function scopeEnforceResolved(explicit: boolean | undefined, env: NodeJS.ProcessEnv): boolean;
+/** Escape-hatch flag. Matches the truthy convention in provider-auth.ts. */
 export declare function preprSkipRequested(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve whether a migration-lint ERROR blocks the PR. Precedence:
+ *   1. explicit `deps.migrationLintBlocking` (the resolved org knob), else
+ *   2. the `ACC_MIGRATION_LINT_BLOCKING` env (`1/true/yes/on` → blocking), else
+ *   3. `false` — shadow (defaults ship OFF; blocking is an explicit opt-in).
+ * Matches the org `migration_lint_blocking` default of `false` (shadow), so
+ * un-wired callers get the same effective default as wired ones.
+ */
+export declare function migrationLintBlockingResolved(explicit: boolean | undefined, env: NodeJS.ProcessEnv): boolean;
 /**
  * Run the repo's own quality gates in `workdir` before a PR is opened.
  * `ok === false` means the caller MUST NOT open a PR — fail the task with

package/dist/prepr-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepr-gate.d.ts","sourceRoot":"","sources":["../src/prepr-gate.ts"],"names":[],"mappings":"AA+BA,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,MAAM,GACN,OAAO,GACP,MAAM,GACN,gBAAgB,CAAC;AAErB;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,aAAa,EAA2C,CAAC;AAEnF,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,GAAG,EAAE,aAAa,EAAE,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnE;;;;OAIG;IACH,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,aAAa,KAChB,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjF;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,KACZ,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3D;AAQD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAGlE;AAkFD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CA8D1B"}
+{"version":3,"file":"prepr-gate.d.ts","sourceRoot":"","sources":["../src/prepr-gate.ts"],"names":[],"mappings":"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"}

package/dist/prepr-gate.js

@@ -32,14 +32,167 @@ import { buildEnv } from "./bin-resolve.js";
  */
 export const PREPR_GATES = ["typecheck", "lint", "build", "test"];
 // ─────────────────────────────────────────────────────────────────────────────
+// V96 (R4/R5): scope + binary/NUL pure helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Text-source extensions the NUL/binary check scans. An allowlist (never a
+ * binary denylist) so genuine binary assets — images, fonts, the design export —
+ * are never false-positives. Kept in sync with scripts/ci/check-no-binary-source.mjs
+ * (the CI backstop for the SAME defect class); the runner package cannot import
+ * that .mjs, so the list is duplicated per the standing cross-package convention.
+ */
+export const TEXT_EXTENSIONS = new Set([
+    ".ts", ".tsx", ".mts", ".cts",
+    ".js", ".jsx", ".mjs", ".cjs",
+    ".json", ".jsonc",
+    ".sql",
+    ".md", ".mdx", ".txt",
+    ".css", ".scss", ".html",
+    ".yml", ".yaml", ".toml",
+    ".sh", ".env",
+]);
+/** True when `p` has a text-source extension the NUL check scans. */
+export function isTextSourcePath(p) {
+    return TEXT_EXTENSIONS.has(path.extname(p).toLowerCase());
+}
+/** Offset of the first NUL byte in `buf`, or -1 if there is none. */
+export function firstNulOffset(buf) {
+    return buf.indexOf(0);
+}
+/** 1-based {line, col} of byte `offset` within `buf` (col counts bytes). */
+export function lineColOf(buf, offset) {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < offset && i < buf.length; i++) {
+        if (buf[i] === 0x0a) {
+            line++;
+            lineStart = i + 1;
+        }
+    }
+    return { line, col: offset - lineStart + 1 };
+}
+/**
+ * Build the log-safe failure message for a NUL hit. Names the file, the byte
+ * offset, and the 1-based line:col — the exact pointer the reviewer needed for
+ * PR #1059 (a single NUL byte burned two review cycles).
+ */
+export function formatNulFailure(hit) {
+    return [
+        `raw NUL byte in staged text source: ${hit.path}:${hit.line}:${hit.col} (byte offset ${hit.offset})`,
+        "git treats a file with a NUL byte as BINARY, so the diff renders as an opaque",
+        "blob and the reviewer cannot review it (this blocked V82 / PR #1059). tsc +",
+        "eslint accept a NUL inside a string, so typecheck/lint/build will NOT catch it.",
+        "Fix: replace the raw NUL byte with the \\u0000 escape sequence (or a non-control",
+        "delimiter). UTF-16-encoded files trip this too — re-save as UTF-8.",
+    ].join("\n");
+}
+/**
+ * Convert one `allowed`-list glob into a RegExp anchored to a full repo-relative
+ * path. Semantics:
+ *   - `**` matches any run of chars INCLUDING `/`;
+ *   - `*` matches any run of chars EXCLUDING `/` (within one path segment);
+ *   - `?` matches a single non-`/` char;
+ *   - a pattern ending in `/` (or a bare directory with no wildcard) matches
+ *     everything beneath that directory prefix;
+ *   - every other char is matched literally.
+ */
+export function globToRegExp(glob) {
+    const g = glob.trim();
+    // Directory-prefix form: `foo/bar/` → everything under it.
+    if (g.endsWith("/")) {
+        return new RegExp("^" + escapeRegexLiteral(g) + ".*$");
+    }
+    let re = "";
+    for (let i = 0; i < g.length; i++) {
+        const c = g[i];
+        if (c === "*") {
+            if (g[i + 1] === "*") {
+                re += ".*";
+                i++;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            re += "[^/]";
+        }
+        else {
+            re += escapeRegexLiteral(c);
+        }
+    }
+    return new RegExp("^" + re + "$");
+}
+function escapeRegexLiteral(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * True when `file` (repo-relative) matches ANY of `globs`, OR when a wildcard-free
+ * glob names a directory that `file` sits beneath (`api/_lib` matches
+ * `api/_lib/x.ts`). Fail-open on an empty glob list — a task that declares no
+ * scope is treated as "everything allowed" (the caller gates on non-empty).
+ */
+export function matchesAllowedGlobs(file, globs) {
+    const f = file.trim();
+    if (globs.length === 0)
+        return true;
+    for (const raw of globs) {
+        const g = raw.trim();
+        if (!g)
+            continue;
+        if (globToRegExp(g).test(f))
+            return true;
+        // Wildcard-free directory prefix: `api/_lib` allows `api/_lib/**`.
+        if (!/[*?]/.test(g) && f.startsWith(g.endsWith("/") ? g : `${g}/`))
+            return true;
+    }
+    return false;
+}
+/** Repo-relative staged paths that match NONE of the allowed globs. */
+export function scopeViolations(files, globs) {
+    if (globs.length === 0)
+        return [];
+    return files.filter((f) => f && !matchesAllowedGlobs(f, globs));
+}
+/**
+ * Resolve whether a scope violation BLOCKS the PR. Precedence:
+ *   1. explicit `deps.scopeEnforce`, else
+ *   2. the `ACC_PREPR_SCOPE_ENFORCE` env (`1/true/yes/on` → enforce), else
+ *   3. `false` — advisory/shadow (defaults ship OFF; enforcement is opt-in).
+ */
+export function scopeEnforceResolved(explicit, env) {
+    if (typeof explicit === "boolean")
+        return explicit;
+    const v = env.ACC_PREPR_SCOPE_ENFORCE?.trim().toLowerCase();
+    if (v === undefined || v === "")
+        return false;
+    return !(v === "0" || v === "false" || v === "no" || v === "off");
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // Pure helpers
 // ─────────────────────────────────────────────────────────────────────────────
 const OUTPUT_TAIL = 4000;
-/** Escape-hatch flag. Matches the truthy convention in anthropic-auth.ts. */
+/** Escape-hatch flag. Matches the truthy convention in provider-auth.ts. */
 export function preprSkipRequested(env) {
     const v = env.ACC_RUNNER_SKIP_PREPR?.trim().toLowerCase();
     return v === "1" || v === "true" || v === "yes" || v === "on";
 }
+/**
+ * Resolve whether a migration-lint ERROR blocks the PR. Precedence:
+ *   1. explicit `deps.migrationLintBlocking` (the resolved org knob), else
+ *   2. the `ACC_MIGRATION_LINT_BLOCKING` env (`1/true/yes/on` → blocking), else
+ *   3. `false` — shadow (defaults ship OFF; blocking is an explicit opt-in).
+ * Matches the org `migration_lint_blocking` default of `false` (shadow), so
+ * un-wired callers get the same effective default as wired ones.
+ */
+export function migrationLintBlockingResolved(explicit, env) {
+    if (typeof explicit === "boolean")
+        return explicit;
+    const v = env.ACC_MIGRATION_LINT_BLOCKING?.trim().toLowerCase();
+    if (v === undefined || v === "")
+        return false;
+    return !(v === "0" || v === "false" || v === "no" || v === "off");
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Default I/O implementations
 // ─────────────────────────────────────────────────────────────────────────────
@@ -91,6 +244,23 @@ async function defaultListChangedMigrations(workdir, baseRef) {
         .map((s) => s.trim())
         .filter((s) => s.endsWith(".sql"));
 }
+async function defaultListStagedFiles(workdir, baseRef) {
+    if (!baseRef)
+        return [];
+    // `<base>...HEAD` (merge-base range) so only files THIS branch added/changed
+    // are checked — never files the base already carried. reject:false + exitCode
+    // guard: a missing base ref yields no files rather than throwing.
+    const result = await execa("git", ["diff", "--name-only", "--diff-filter=ACMR", `${baseRef}...HEAD`], { cwd: workdir, env: buildEnv(), reject: false });
+    if (result.exitCode !== 0)
+        return [];
+    return (result.stdout ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+async function defaultReadFileBytes(workdir, file) {
+    return fs.readFile(path.join(workdir, file));
+}
 async function defaultRunMigrationLint(workdir, files) {
     const script = path.join(workdir, "scripts", "ci", "migration-lint.mjs");
     const result = await execa("node", [script, ...files], {
@@ -120,9 +290,74 @@ export async function runPreprGate(workdir, deps = {}) {
     }
     const readScripts = deps.readScripts ?? defaultReadScripts;
     const runGate = deps.runGate ?? defaultRunGate;
-    const scripts = await readScripts(workdir);
     const ran = [];
     const absent = [];
+    let scopeShadow;
+    // V96 (R4/R5): staged-file checks run FIRST — they are cheap and catch the
+    // exact classes typecheck/lint/build cannot (a NUL byte tsc accepts inside a
+    // string; an out-of-scope edit). Gated on baseRef / injected dep so the unit
+    // suite (which provides neither) never shells out to git.
+    if (deps.listStagedFiles || deps.baseRef) {
+        const listStagedFiles = deps.listStagedFiles ?? defaultListStagedFiles;
+        const readFileBytes = deps.readFileBytes ?? defaultReadFileBytes;
+        const staged = await listStagedFiles(workdir, deps.baseRef);
+        // (a) BINARY/NUL check — always-on structural guard (not a knob). Any staged
+        // text-extension file that git will treat as binary (a raw NUL byte, or
+        // UTF-16 which is riddled with NULs) FAILS the gate with file + byte offset.
+        ran.push("nul-check");
+        for (const file of staged) {
+            if (!isTextSourcePath(file))
+                continue;
+            let buf;
+            try {
+                buf = await readFileBytes(workdir, file);
+            }
+            catch {
+                continue; // unreadable (e.g. deleted after diff) — not our failure to raise
+            }
+            const offset = firstNulOffset(buf);
+            if (offset >= 0) {
+                const { line, col } = lineColOf(buf, offset);
+                const hit = { path: file, offset, line, col };
+                return {
+                    ok: false,
+                    skipped: false,
+                    ran,
+                    absent,
+                    failure: {
+                        gate: "nul-check",
+                        exitCode: 1,
+                        outputTail: formatNulFailure(hit),
+                    },
+                };
+            }
+        }
+        // (b) SCOPE check — staged files vs the task's `allowed` globs. Only when the
+        // task declares a scope (non-empty globs). Enforcement is a DEFAULT-OFF knob:
+        // ON → HALT (fail gate); OFF → advisory (scopeShadow, PR still opens).
+        const globs = (deps.allowedGlobs ?? []).filter((g) => g && g.trim().length > 0);
+        if (globs.length > 0) {
+            const offending = scopeViolations(staged, globs);
+            if (offending.length > 0) {
+                ran.push("scope");
+                const detail = `staged file(s) outside the task's allowed scope:\n` +
+                    offending.map((f) => `  - ${f}`).join("\n") +
+                    `\nallowed globs:\n` +
+                    globs.map((g) => `  - ${g}`).join("\n");
+                if (scopeEnforceResolved(deps.scopeEnforce, env)) {
+                    return {
+                        ok: false,
+                        skipped: false,
+                        ran,
+                        absent,
+                        failure: { gate: "scope", exitCode: 1, outputTail: detail.slice(-OUTPUT_TAIL) },
+                    };
+                }
+                scopeShadow = { offending, outputTail: detail.slice(-OUTPUT_TAIL) };
+            }
+        }
+    }
+    const scripts = await readScripts(workdir);
     for (const gate of PREPR_GATES) {
         if (!scripts[gate]) {
             absent.push(gate);
@@ -154,20 +389,36 @@ export async function runPreprGate(workdir, deps = {}) {
             ran.push("migration-lint");
             const { exitCode, output } = await runMigrationLint(workdir, migrations);
             if (exitCode !== 0) {
+                const blocking = migrationLintBlockingResolved(deps.migrationLintBlocking, env);
+                if (blocking) {
+                    // Blocking mode: a lint ERROR fails the gate — no PR is opened and the
+                    // linter output lands in the runner log via failure.outputTail.
+                    return {
+                        ok: false,
+                        skipped: false,
+                        ran,
+                        absent,
+                        failure: {
+                            gate: "migration-lint",
+                            exitCode,
+                            outputTail: output.slice(-OUTPUT_TAIL),
+                        },
+                    };
+                }
+                // Shadow mode: advisory only — surface the findings for logging but do
+                // NOT block the PR. (The linter itself exits 0 on warning-only findings,
+                // so reaching here means a genuine lint ERROR that shadow week tolerates.)
                 return {
-                    ok: false,
+                    ok: true,
                     skipped: false,
                     ran,
                     absent,
-                    failure: {
-                        gate: "migration-lint",
-                        exitCode,
-                        outputTail: output.slice(-OUTPUT_TAIL),
-                    },
+                    migrationLintShadow: { exitCode, outputTail: output.slice(-OUTPUT_TAIL) },
+                    scopeShadow,
                 };
             }
         }
     }
-    return { ok: true, skipped: false, ran, absent };
+    return { ok: true, skipped: false, ran, absent, scopeShadow };
 }
 //# sourceMappingURL=prepr-gate.js.map

package/dist/prepr-gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"prepr-gate.js","sourceRoot":"","sources":["../src/prepr-gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prepr-gate.js","sourceRoot":"","sources":["../src/prepr-gate.ts"],"names":[],"mappings":"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"}

package/dist/provider-auth.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Centralised resolution of how the spawned
+ * `claude` CLI authenticates with Anthropic.
+ *
+ * Claude Code authenticates *strictly* via the `ANTHROPIC_API_KEY`
+ * environment variable (or an apiKeyHelper) — it has no `--api-key` flag;
+ * passing one fails with `error: unknown option '--api-key'`. So "passing
+ * the API key to claude" means making sure the variable is present in the
+ * spawned subprocess's environment.
+ *
+ * When ANTHROPIC_API_KEY is set the CLI bills against the API account, which
+ * has no per-session usage cap. When it is absent the CLI falls back to the
+ * operator's interactive OAuth session, which is subject to the 429 session
+ * caps this change exists to avoid.
+ *
+ * M4 (ENGINE-CODEX): this module was renamed anthropic-auth.ts →
+ * provider-auth.ts and extended to cover the OpenAI Codex CLI as well, which
+ * has TWO auth channels (see §0.1.5 of the multi-model plan): an `api-key`
+ * mode driven by `OPENAI_API_KEY` (keychain/env) and a `subscription` mode
+ * driven by a stored ChatGPT login session. The Anthropic helpers are
+ * unchanged (byte-identical) so existing call sites keep their behaviour.
+ */
+export type AnthropicAuthMode = "api-key" | "interactive-session";
+/** Trimmed ANTHROPIC_API_KEY from `env`, or "" when unset/blank. */
+export declare function anthropicApiKey(env?: NodeJS.ProcessEnv): string;
+/**
+ * Opt-in claude-config isolation. Even with ANTHROPIC_API_KEY
+ * set, the Claude CLI prefers a stored claude.ai OAuth login when one exists —
+ * the observed cause of 429 session caps on a key-configured runner. Pointing
+ * the spawned claude at an isolated CLAUDE_CONFIG_DIR (no stored login) leaves
+ * the env key as the only credential, forcing API-key auth. Opt-in via
+ * ACC_RUNNER_ISOLATE_CLAUDE_CONFIG because the behaviour needs live-runner
+ * validation before becoming default.
+ */
+export declare function claudeConfigIsolationEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Runner-owned claude config dir used when isolation is enabled. */
+export declare function isolatedClaudeConfigDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * `"api-key"` when ANTHROPIC_API_KEY is set (non-blank), else
+ * `"interactive-session"`.
+ */
+export declare function resolveAuthMode(env?: NodeJS.ProcessEnv): AnthropicAuthMode;
+/**
+ * Returns `base` with ANTHROPIC_API_KEY explicitly forwarded (trimmed) when
+ * set, so every claude spawn site authenticates identically regardless of how
+ * `base` was assembled. A passthrough of `base` when the key is absent — the
+ * CLI then uses the operator's interactive OAuth session.
+ */
+export declare function withAnthropicAuth(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** One-line, human-readable description of an auth mode for banners/checks. */
+export declare function describeAuthMode(mode: AnthropicAuthMode): string;
+/**
+ * Precedence hint for the banner / doctor. Returns null when
+ * there's nothing to add (interactive-session mode is already self-explanatory
+ * via describeAuthMode). In api-key mode it tells the operator either that
+ * isolation is forcing the key, or — if not isolated — how to stop a claude.ai
+ * login from shadowing the key and causing 429s.
+ */
+export declare function authPrecedenceHint(env?: NodeJS.ProcessEnv): string | null;
+/** How the codex CLI authenticates for a given spawn. */
+export type CodexAuthMode = "api-key" | "subscription";
+/**
+ * Preference resolved from `auth_preference` (plan §0.1.5). `subscription_first`
+ * starts on the subscription session and spills to the api-key on a cap-hit;
+ * `api_key_first` starts on the key. Defaults to `subscription_first` — the
+ * program's cost-saving default — so an unset preference behaves as the plan
+ * specifies.
+ */
+export type CodexAuthPreference = "subscription_first" | "api_key_first";
+/**
+ * The per-provider keychain account under the frozen `acc-runner` service.
+ * FROZEN-CONTRACT EXTENSION (Track-A note): this ADDS a namespaced account
+ * (`provider:openai`) alongside the existing `default` session entry — the
+ * session schema in keychain.ts is untouched, so a Track-A review only needs
+ * to bless the new account name, not a shape change. The value is the raw
+ * OPENAI_API_KEY string (never a JSON blob), so it round-trips through keytar
+ * without colliding with the StoredSession JSON at `default`.
+ */
+export declare const OPENAI_KEYCHAIN_ACCOUNT: "provider:openai";
+/** Trimmed OPENAI_API_KEY from `env`, or "" when unset/blank. */
+export declare function openaiApiKey(env?: NodeJS.ProcessEnv): string;
+/**
+ * Read the OPENAI_API_KEY from the OS keychain (per-provider account). Returns
+ * "" when absent, keytar is unavailable (headless Linux without libsecret), or
+ * the entry is empty. Async because keychain access is — the sync spawn path
+ * (`withOpenAiAuth`) only ever reads the env-present key, exactly like the
+ * Anthropic path; the keychain is consulted by startup/doctor which can await.
+ */
+export declare function openaiApiKeyFromKeychain(): Promise<string>;
+/**
+ * Resolve the `auth_preference` string into a typed preference. Accepts the
+ * env-string forms and the DB spelling; anything unknown/blank falls back to
+ * the `subscription_first` default.
+ */
+export declare function resolveCodexAuthPreference(raw: string | null | undefined): CodexAuthPreference;
+/**
+ * The auth mode a codex spawn should START in, given the preference and whether
+ * an api key is present. `subscription_first` uses subscription; `api_key_first`
+ * uses the key when one is available (else subscription). This is the FIRST
+ * attempt only — the spill to api-key on a `subscription_exhausted` cap-hit is
+ * driven by the (future, M5) task-runner orchestration, which re-invokes with
+ * mode "api-key" explicitly.
+ */
+export declare function initialCodexAuthMode(preference: CodexAuthPreference, hasApiKey: boolean): CodexAuthMode;
+/** One-line, human-readable description of a codex auth mode for banners/checks. */
+export declare function describeCodexAuthMode(mode: CodexAuthMode): string;
+/**
+ * Augment `base` for a codex spawn in the given auth mode:
+ *   - "api-key":      OPENAI_API_KEY is forwarded (trimmed) so codex bills the
+ *                     key. A passthrough when the key is absent — codex then
+ *                     errors on missing auth, surfaced as `auth_expired`.
+ *   - "subscription": OPENAI_API_KEY is REMOVED from the environment so codex
+ *                     cannot silently bill the key and instead uses the stored
+ *                     ChatGPT login (the mirror of the claude config-isolation
+ *                     concern: a stray key must not shadow the subscription we
+ *                     deliberately chose to try first).
+ * Never mutates `base`; returns a shallow copy.
+ */
+export declare function withOpenAiAuth(mode: CodexAuthMode, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+//# sourceMappingURL=provider-auth.d.ts.map

package/dist/provider-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-auth.d.ts","sourceRoot":"","sources":["../src/provider-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,qBAAqB,CAAC;AAElE,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAGT;AAED,qEAAqE;AACrE,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,iBAAiB,CAEvF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,UAAU,CAc1F;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAIhE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,IAAI,CASf;AAiBD,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAG,iBAA0B,CAAC;AAElE,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEzE;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,CAAC,CAYhE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,mBAAmB,CAMrB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,mBAAmB,EAC/B,SAAS,EAAE,OAAO,GACjB,aAAa,CAGf;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAIjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,IAAI,GAAE,MAAM,CAAC,UAAwB,GACpC,MAAM,CAAC,UAAU,CAUnB"}