@bookedsolid/rea 0.11.0 → 0.12.0

package/dist/cli/doctor.d.ts

@@ -46,6 +46,18 @@ export declare function checkFingerprintStore(baseDir: string): Promise<CheckRes
  * NOT a trust boundary. Do not key security decisions on the return value.
  */
 export declare function isGitRepo(baseDir: string): boolean;
+/**
+ * Hard-fail when `policy.review.codex_required: true` but the `codex`
+ * binary is not on PATH. Pre-0.12.0 this prereq surfaced only at first
+ * push, by which point the consumer had cloned, run `pnpm install`,
+ * authored a commit, and tried to push — only then to learn that they
+ * needed a separate install. Fix C of 0.12.0 surfaces it during install.
+ *
+ * Returns `pass` when codex resolves; `fail` when missing. Operators who
+ * want to disable the gate can flip `policy.review.codex_required: false`
+ * (the doctor then short-circuits past every Codex check).
+ */
+export declare function checkCodexBinaryOnPath(): CheckResult;
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last

package/dist/cli/doctor.js

@@ -423,6 +423,95 @@ function checkCodexCommand(baseDir) {
         detail: `missing: ${cmdPath}`,
     };
 }
+/**
+ * Resolve the absolute path of `codex` on PATH (cross-platform). Returns
+ * `null` when codex is not installed. We walk `process.env.PATH`
+ * directly rather than shelling out — earlier iterations spawned
+ * `sh -c "command -v codex"` which gave false negatives in sanitized
+ * POSIX environments where `/bin` is omitted from PATH (CI runners,
+ * hardened dev shells) but the `codex` binary lives at a project-bin
+ * path that IS on PATH. Codex [P2] 2026-04-29.
+ *
+ * On Windows we iterate `PATHEXT` (default `.COM;.EXE;.BAT;.CMD`) so
+ * `codex.cmd` (the typical npm shim) is discovered. POSIX checks the
+ * bare name and accepts any file with an execute bit set.
+ */
+function resolveCodexBinary() {
+    const isWindows = process.platform === 'win32';
+    const pathEnv = process.env.PATH ?? process.env.Path ?? '';
+    if (pathEnv.length === 0)
+        return null;
+    const sep = isWindows ? ';' : ':';
+    const entries = pathEnv.split(sep).filter((p) => p.length > 0);
+    if (isWindows) {
+        const pathExt = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';');
+        for (const dir of entries) {
+            for (const ext of pathExt) {
+                const candidate = path.join(dir, `codex${ext}`);
+                try {
+                    const st = fs.statSync(candidate);
+                    if (st.isFile())
+                        return candidate;
+                }
+                catch {
+                    // not present in this PATH entry — keep walking
+                }
+            }
+            // also check the bare name in case PATHEXT is unusual
+            const bare = path.join(dir, 'codex');
+            try {
+                const st = fs.statSync(bare);
+                if (st.isFile())
+                    return bare;
+            }
+            catch {
+                // not present — keep walking
+            }
+        }
+        return null;
+    }
+    // POSIX: check executable bit on the file mode.
+    for (const dir of entries) {
+        const candidate = path.join(dir, 'codex');
+        try {
+            const st = fs.statSync(candidate);
+            if (st.isFile() && (st.mode & 0o111) !== 0)
+                return candidate;
+        }
+        catch {
+            // not present in this PATH entry — keep walking
+        }
+    }
+    return null;
+}
+/**
+ * Hard-fail when `policy.review.codex_required: true` but the `codex`
+ * binary is not on PATH. Pre-0.12.0 this prereq surfaced only at first
+ * push, by which point the consumer had cloned, run `pnpm install`,
+ * authored a commit, and tried to push — only then to learn that they
+ * needed a separate install. Fix C of 0.12.0 surfaces it during install.
+ *
+ * Returns `pass` when codex resolves; `fail` when missing. Operators who
+ * want to disable the gate can flip `policy.review.codex_required: false`
+ * (the doctor then short-circuits past every Codex check).
+ */
+export function checkCodexBinaryOnPath() {
+    const resolved = resolveCodexBinary();
+    if (resolved !== null) {
+        return {
+            label: 'codex CLI on PATH',
+            status: 'pass',
+            detail: resolved,
+        };
+    }
+    return {
+        label: 'codex CLI on PATH',
+        status: 'fail',
+        detail: 'codex not found on PATH. policy.review.codex_required: true requires the codex binary. ' +
+            'Install: https://github.com/openai/codex (e.g. `npm i -g @openai/codex`). ' +
+            'To disable the push-gate instead, set policy.review.codex_required: false in .rea/policy.yaml.',
+    };
+}
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last
@@ -521,7 +610,7 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
         });
     }
     if (codexRequiredFromPolicy(baseDir)) {
-        checks.push(checkCodexAgent(baseDir), checkCodexCommand(baseDir));
+        checks.push(checkCodexAgent(baseDir), checkCodexCommand(baseDir), checkCodexBinaryOnPath());
         if (codexProbeState !== undefined) {
             checks.push(...checksFromProbeState(codexProbeState));
         }

package/dist/cli/hook.d.ts

@@ -31,6 +31,13 @@
 import type { Command } from 'commander';
 export interface HookPushGateOptions {
     base?: string;
+    /**
+     * Diff against `HEAD~N` instead of running the upstream ladder. Mirrors
+     * `policy.review.last_n_commits`; the CLI flag wins when both are set.
+     * `--base` always wins over both. Validated as a positive integer; the
+     * CLI rejects non-numeric input before reaching `runPushGate`.
+     */
+    lastNCommits?: number;
 }
 /**
  * Public runner, exposed so integration tests and the commander binding can

package/dist/cli/hook.js

@@ -55,6 +55,7 @@ export async function runHookPushGate(options) {
             stderr,
             refspecs,
             ...(options.base !== undefined && options.base.length > 0 ? { explicitBase: options.base } : {}),
+            ...(options.lastNCommits !== undefined ? { lastNCommits: options.lastNCommits } : {}),
         });
         process.exit(result.exitCode);
     }
@@ -121,7 +122,17 @@ export function registerHookCommand(program) {
         .argument('[gitArgs...]', 'positional args forwarded by git (remote name, URL); ignored')
         .description('Run `codex exec review` against the current diff and block on blocking findings. Exits 0/1/2: pass/HALT/blocked. No cache — every push runs Codex afresh.')
         .option('--base <ref>', 'explicit base ref to diff against (e.g. origin/main). Defaults to @{upstream} → origin/HEAD → main/master → empty-tree.')
+        .option('--last-n-commits <n>', 'narrow review to the last N commits (diff against HEAD~N). Useful for large feature branches. Loses to --base when both are set; mirrors policy.review.last_n_commits.', (raw) => {
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`--last-n-commits must be a positive integer, got ${JSON.stringify(raw)}`);
+        }
+        return n;
+    })
         .action(async (_gitArgs, opts) => {
-        await runHookPushGate({ ...(opts.base !== undefined ? { base: opts.base } : {}) });
+        await runHookPushGate({
+            ...(opts.base !== undefined ? { base: opts.base } : {}),
+            ...(opts.lastNCommits !== undefined ? { lastNCommits: opts.lastNCommits } : {}),
+        });
     });
 }

package/dist/cli/install/pre-push.d.ts

@@ -53,19 +53,26 @@
  * classification. Bump the version suffix whenever the body semantics
  * change so upgrades can migrate old installs cleanly.
  *
+ * v3 — 0.12.0 BODY_TEMPLATE rewrite: positional-args dispatch via `case`
+ *      arms with `set --`, removing the `exec $REA_BIN` word-splitting bug
+ *      that broke pushes from repo paths containing spaces.
  * v2 — 0.11.0 stateless push-gate body (no bash core, no audit grep).
  * v1 — 0.10.x and prior, delegated to `.claude/hooks/push-review-gate.sh`.
  */
-export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v2";
+export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v3";
+/** Legacy v2 marker (0.11.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_FALLBACK_MARKER_V2 = "# rea:pre-push-fallback v2";
 /** Legacy v1 marker — used by upgrade migration to detect old installs. */
 export declare const LEGACY_FALLBACK_MARKER_V1 = "# rea:pre-push-fallback v1";
 /**
  * Marker present in the shipped `.husky/pre-push` governance gate. The
  * second line of the shipped husky hook is this marker — rea upgrade
  * detects it to refresh in-place. Bump the suffix whenever the body
- * changes; pre-0.11 markers live in `LEGACY_HUSKY_GATE_MARKER_V1`.
+ * changes; pre-0.12 markers live in `LEGACY_HUSKY_GATE_MARKER_V{1,2}`.
  */
-export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v2";
+export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v3";
+/** Legacy v2 husky marker (0.11.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_HUSKY_GATE_MARKER_V2 = "# rea:husky-pre-push-gate v2";
 /** Legacy v1 husky marker for migration. */
 export declare const LEGACY_HUSKY_GATE_MARKER_V1 = "# rea:husky-pre-push-gate v1";
 /**
@@ -73,7 +80,9 @@ export declare const LEGACY_HUSKY_GATE_MARKER_V1 = "# rea:husky-pre-push-gate v1
  * empty body (stubbed out by a consumer) is NOT classified as rea-managed.
  * A real rea hook always carries both markers.
  */
-export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v2";
+export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v3";
+/** Legacy v2 body marker (0.11.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_HUSKY_GATE_BODY_MARKER_V2 = "# rea:gate-body-v2";
 /** Legacy body marker — used by upgrade migration detection. */
 export declare const LEGACY_HUSKY_GATE_BODY_MARKER_V1 = "# rea:gate-body-v1";
 /** Fallback hook body — `.git/hooks/pre-push` in vanilla-git installs. */
@@ -87,10 +96,11 @@ export declare function huskyHookContent(): string;
  */
 export declare function isReaManagedFallback(content: string): boolean;
 /**
- * True when `content` is the legacy v1 fallback (`.git/hooks/pre-push`
- * that delegated to `.claude/hooks/push-review-gate.sh`). Used by `rea
- * upgrade` to migrate — we overwrite these unconditionally because we
- * control the entire body shape.
+ * True when `content` is a legacy fallback hook authored by an earlier rea
+ * release: v2 (0.11.x — broken `exec $REA_BIN` body) or v1 (0.10.x —
+ * delegated to `.claude/hooks/push-review-gate.sh`). Used by `rea upgrade`
+ * to migrate — we overwrite these unconditionally because we control the
+ * entire body shape.
  */
 export declare function isLegacyReaManagedFallback(content: string): boolean;
 /**
@@ -106,8 +116,9 @@ export declare function isLegacyReaManagedFallback(content: string): boolean;
  */
 export declare function isReaManagedHuskyGate(content: string): boolean;
 /**
- * True when `content` is the legacy v1 Husky gate (`.husky/pre-push` from
- * 0.10.x and earlier). Used to trigger the upgrade migration.
+ * True when `content` is a legacy Husky gate from an earlier rea release:
+ * v2 (0.11.x — broken `exec $REA_BIN` body) or v1 (0.10.x — bash core
+ * delegating). Used to trigger the upgrade migration.
  */
 export declare function isLegacyReaManagedHuskyGate(content: string): boolean;
 /**

package/dist/cli/install/pre-push.js

@@ -65,19 +65,26 @@ const execFileAsync = promisify(execFile);
  * classification. Bump the version suffix whenever the body semantics
  * change so upgrades can migrate old installs cleanly.
  *
+ * v3 — 0.12.0 BODY_TEMPLATE rewrite: positional-args dispatch via `case`
+ *      arms with `set --`, removing the `exec $REA_BIN` word-splitting bug
+ *      that broke pushes from repo paths containing spaces.
  * v2 — 0.11.0 stateless push-gate body (no bash core, no audit grep).
  * v1 — 0.10.x and prior, delegated to `.claude/hooks/push-review-gate.sh`.
  */
-export const FALLBACK_MARKER = '# rea:pre-push-fallback v2';
+export const FALLBACK_MARKER = '# rea:pre-push-fallback v3';
+/** Legacy v2 marker (0.11.x bodies). Refresh-on-upgrade. */
+export const LEGACY_FALLBACK_MARKER_V2 = '# rea:pre-push-fallback v2';
 /** Legacy v1 marker — used by upgrade migration to detect old installs. */
 export const LEGACY_FALLBACK_MARKER_V1 = '# rea:pre-push-fallback v1';
 /**
  * Marker present in the shipped `.husky/pre-push` governance gate. The
  * second line of the shipped husky hook is this marker — rea upgrade
  * detects it to refresh in-place. Bump the suffix whenever the body
- * changes; pre-0.11 markers live in `LEGACY_HUSKY_GATE_MARKER_V1`.
+ * changes; pre-0.12 markers live in `LEGACY_HUSKY_GATE_MARKER_V{1,2}`.
  */
-export const HUSKY_GATE_MARKER = '# rea:husky-pre-push-gate v2';
+export const HUSKY_GATE_MARKER = '# rea:husky-pre-push-gate v3';
+/** Legacy v2 husky marker (0.11.x bodies). Refresh-on-upgrade. */
+export const LEGACY_HUSKY_GATE_MARKER_V2 = '# rea:husky-pre-push-gate v2';
 /** Legacy v1 husky marker for migration. */
 export const LEGACY_HUSKY_GATE_MARKER_V1 = '# rea:husky-pre-push-gate v1';
 /**
@@ -85,7 +92,9 @@ export const LEGACY_HUSKY_GATE_MARKER_V1 = '# rea:husky-pre-push-gate v1';
  * empty body (stubbed out by a consumer) is NOT classified as rea-managed.
  * A real rea hook always carries both markers.
  */
-export const HUSKY_GATE_BODY_MARKER = '# rea:gate-body-v2';
+export const HUSKY_GATE_BODY_MARKER = '# rea:gate-body-v3';
+/** Legacy v2 body marker (0.11.x bodies). Refresh-on-upgrade. */
+export const LEGACY_HUSKY_GATE_BODY_MARKER_V2 = '# rea:gate-body-v2';
 /** Legacy body marker — used by upgrade migration detection. */
 export const LEGACY_HUSKY_GATE_BODY_MARKER_V1 = '# rea:gate-body-v1';
 // ---------------------------------------------------------------------------
@@ -107,7 +116,8 @@ const BODY_TEMPLATE = `set -eu
 # invocation, verdict inference, audit write — lives in
 # \`src/hooks/push-gate/\` and is invoked via \`rea hook push-gate\`.
 # This stub only short-circuits on the kill-switch and resolves the rea
-# binary (in priority: project node_modules/.bin/rea → PATH → npx).
+# binary (in priority: project node_modules/.bin/rea → dogfood dist →
+# PATH → npx).
 #
 # The 0.10.x hooks assumed rea was on PATH. Consumers who bootstrap via
 # \`npx @bookedsolid/rea init\` have no persistent global rea install, so
@@ -123,35 +133,39 @@ if [ -f "\${REA_ROOT}/.rea/HALT" ]; then
   exit 1
 fi
 
-# The pre-push stdin carries one line per refspec (local_ref local_sha
-# remote_ref remote_sha). Forward stdin verbatim via process substitution
-# — the \`rea hook push-gate\` CLI reads it via process.stdin to pick up
-# the actual push base. Empty stdin (direct invocation, CI, etc.) is
-# handled by the CLI falling back to upstream → origin/HEAD resolution.
+# Dispatch the rea CLI as a positional-args list rather than a string
+# (the 0.11.x \`exec \$REA_BIN ...\` pattern broke when REA_ROOT contained
+# whitespace because the unquoted \$REA_BIN expansion underwent word
+# splitting; \`/Users/jane/My Projects/repo\` produced four argv tokens
+# instead of two). The \`set --\` form below preserves spaces verbatim.
+#
+# The pre-push stdin carries one line per refspec; \`exec\` inherits stdin
+# unchanged. \$@ on entry carries git's <remote-name> <remote-url>; we
+# preserve those by appending "\$@" inside each \`set --\` arm.
 
-REA_BIN=""
 if [ -x "\${REA_ROOT}/node_modules/.bin/rea" ]; then
-  REA_BIN="\${REA_ROOT}/node_modules/.bin/rea"
-elif [ -f "\${REA_ROOT}/dist/cli/index.js" ]; then
+  set -- "\${REA_ROOT}/node_modules/.bin/rea" hook push-gate "\$@"
+elif [ -f "\${REA_ROOT}/dist/cli/index.js" ] && [ -f "\${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "\${REA_ROOT}/package.json" 2>/dev/null; then
   # rea's own repo (dogfood) — the package is not installed under
   # node_modules here because we ARE the package. The built CLI
   # entry point lives at dist/cli/index.js; node runs it directly.
-  REA_BIN="node \${REA_ROOT}/dist/cli/index.js"
+  # Gate this branch on \`package.json\` declaring \`@bookedsolid/rea\` so a
+  # consumer repo that happens to ship its own \`dist/cli/index.js\` does
+  # not get this hook executing the consumer's unrelated build.
+  set -- node "\${REA_ROOT}/dist/cli/index.js" hook push-gate "\$@"
 elif command -v rea >/dev/null 2>&1; then
-  REA_BIN="rea"
+  set -- rea hook push-gate "\$@"
 elif command -v npx >/dev/null 2>&1; then
   # Last resort: npx will resolve the package from npm or the cache.
   # Pass \`--no-install\` so a rare cache-cold machine surfaces a clear
   # error instead of silently downloading at push time.
-  REA_BIN="npx --no-install @bookedsolid/rea"
+  set -- npx --no-install @bookedsolid/rea hook push-gate "\$@"
 else
   printf 'rea: cannot locate the rea CLI. Install locally (\`pnpm add -D @bookedsolid/rea\`) or globally (\`npm i -g @bookedsolid/rea\`).\\n' >&2
   exit 2
 fi
 
-# \$@ carries the pre-push arguments (git passes <remote-name> <remote-url>).
-# Stdin is inherited by \`exec\` → the CLI sees it unchanged.
-exec \$REA_BIN hook push-gate "\$@"
+exec "\$@"
 `;
 /** Fallback hook body — `.git/hooks/pre-push` in vanilla-git installs. */
 export function fallbackHookContent() {
@@ -202,10 +216,11 @@ export function isReaManagedFallback(content) {
     return secondLine === FALLBACK_MARKER;
 }
 /**
- * True when `content` is the legacy v1 fallback (`.git/hooks/pre-push`
- * that delegated to `.claude/hooks/push-review-gate.sh`). Used by `rea
- * upgrade` to migrate — we overwrite these unconditionally because we
- * control the entire body shape.
+ * True when `content` is a legacy fallback hook authored by an earlier rea
+ * release: v2 (0.11.x — broken `exec $REA_BIN` body) or v1 (0.10.x —
+ * delegated to `.claude/hooks/push-review-gate.sh`). Used by `rea upgrade`
+ * to migrate — we overwrite these unconditionally because we control the
+ * entire body shape.
  */
 export function isLegacyReaManagedFallback(content) {
     if (!content.startsWith('#!/bin/sh\n'))
@@ -214,7 +229,8 @@ export function isLegacyReaManagedFallback(content) {
     if (secondLineEnd < 0)
         return false;
     const secondLine = content.slice(10, secondLineEnd);
-    return secondLine === LEGACY_FALLBACK_MARKER_V1;
+    return (secondLine === LEGACY_FALLBACK_MARKER_V2 ||
+        secondLine === LEGACY_FALLBACK_MARKER_V1);
 }
 /**
  * True when `content` carries the rea Husky gate markers in the canonical
@@ -231,11 +247,13 @@ export function isReaManagedHuskyGate(content) {
     return hasHeaderMarkers(content, HUSKY_GATE_MARKER, HUSKY_GATE_BODY_MARKER);
 }
 /**
- * True when `content` is the legacy v1 Husky gate (`.husky/pre-push` from
- * 0.10.x and earlier). Used to trigger the upgrade migration.
+ * True when `content` is a legacy Husky gate from an earlier rea release:
+ * v2 (0.11.x — broken `exec $REA_BIN` body) or v1 (0.10.x — bash core
+ * delegating). Used to trigger the upgrade migration.
  */
 export function isLegacyReaManagedHuskyGate(content) {
-    return hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V1, LEGACY_HUSKY_GATE_BODY_MARKER_V1);
+    return (hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V2, LEGACY_HUSKY_GATE_BODY_MARKER_V2) ||
+        hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V1, LEGACY_HUSKY_GATE_BODY_MARKER_V1));
 }
 function hasHeaderMarkers(content, header, body) {
     if (!content.startsWith('#!/bin/sh\n'))
@@ -523,6 +541,8 @@ async function cleanupStaleTempFiles(dst) {
             return;
         if (!body.includes(FALLBACK_MARKER) &&
             !body.includes(HUSKY_GATE_MARKER) &&
+            !body.includes(LEGACY_FALLBACK_MARKER_V2) &&
+            !body.includes(LEGACY_HUSKY_GATE_MARKER_V2) &&
             !body.includes(LEGACY_FALLBACK_MARKER_V1) &&
             !body.includes(LEGACY_HUSKY_GATE_MARKER_V1)) {
             return;

package/dist/hooks/push-gate/base.d.ts

@@ -31,7 +31,27 @@ export interface BaseResolution {
      */
     ref: string;
     /** Where the ref came from — surfaces in audit records and stderr. */
-    source: 'explicit' | 'upstream' | 'origin-head' | 'origin-main' | 'origin-master' | 'local-main' | 'local-master' | 'empty-tree';
+    source: 'explicit' | 'last-n-commits' | 'upstream' | 'origin-head' | 'origin-main' | 'origin-master' | 'local-main' | 'local-master' | 'empty-tree';
+    /**
+     * Set when `last-n-commits` was requested but `<headRef>~N` did not
+     * resolve at the requested depth (shallower-than-N clone, or N larger
+     * than the branch history). The resolver clamps to the deepest
+     * reachable commit (`<headRef>~K` for the largest `K <= N` that does
+     * resolve) and surfaces both numbers so the caller can emit a stderr
+     * warning ("requested N=50; clamped to K=12 (oldest reachable)").
+     * Present on both `last-n-commits` results (when clamped) and
+     * `empty-tree` results (when even `~1` was unreachable — orphan or
+     * single-commit branch).
+     */
+    lastNCommitsRequested?: number;
+    /**
+     * The N value actually used. When source is `last-n-commits`, this is
+     * the depth that resolved (equals `lastNCommitsRequested` on full
+     * resolution; smaller when clamped to a shallow clone). Surfaces in
+     * audit metadata so operators can grep their audit log for narrowed
+     * reviews.
+     */
+    lastNCommits?: number;
 }
 /**
  * Well-known empty-tree SHA: `git hash-object -t tree /dev/null`. Every git
@@ -48,6 +68,33 @@ export interface ResolveBaseOptions {
      * that's Codex's job (it'll error clearly if the ref is bad).
      */
     explicit?: string;
+    /**
+     * Resolve the base to `HEAD~N` instead of running the upstream ladder.
+     * `--last-n-commits N` flag and `policy.review.last_n_commits` map
+     * here. Ignored when `explicit` is set (explicit ref wins). When
+     * `<headRef>~N` does not resolve (shallower-than-N clone, or branch
+     * history shorter than N), the resolver CLAMPS to the deepest
+     * reachable commit (`<headRef>~K` for the largest `K <= N` that does
+     * resolve) — i.e. it diffs against the oldest commit on the branch.
+     * It does NOT fall back to the empty-tree sentinel; that would
+     * silently expand "the last N commits" to "the entire repository
+     * snapshot" on a normal repo with a short feature branch, flooding
+     * Codex with unchanged base-branch files. The resolver only emits
+     * `source: 'empty-tree'` when even `<headRef>~1` cannot be resolved
+     * (orphan branch, single-commit history); in that case
+     * `lastNCommitsRequested: N` is set so the caller can warn.
+     */
+    lastNCommits?: number;
+    /**
+     * The head ref the gate is reviewing. Defaults to literal "HEAD" — i.e.
+     * the local checkout's tip. When the gate is invoked via pre-push and
+     * the pushed ref is not the current branch (e.g.
+     * `git push origin some-other-branch`), the caller passes the pushed
+     * `<sha>` here so `last-n-commits` resolves `<sha>~N` rather than
+     * `HEAD~N`. Without this thread-through the review walks back N commits
+     * from the local checkout, which can be a different branch entirely.
+     */
+    headRef?: string;
 }
 /**
  * Resolve the base ref using the configured priority order. Never throws —

package/dist/hooks/push-gate/base.js

@@ -39,6 +39,127 @@ export function resolveBaseRef(git, options = {}) {
     if (options.explicit !== undefined && options.explicit.length > 0) {
         return { ref: options.explicit, source: 'explicit' };
     }
+    // 0. Last-N-commits override. Caller (CLI flag or policy key) requested
+    //    diffing against `HEAD~N` directly. Resolves to a 40-char SHA via
+    //    `git rev-parse HEAD~N`; on failure (shallower-than-N clone, or N
+    //    larger than the branch's history depth) we fall back to the
+    //    empty-tree sentinel and surface `lastNCommitsRequested` so the
+    //    caller can emit a stderr warning. We deliberately resolve to a
+    //    SHA rather than passing `HEAD~N` through to Codex — Codex shells
+    //    out to `git diff` itself, but a SHA is unambiguous regardless of
+    //    intermediate ref churn.
+    if (options.lastNCommits !== undefined && options.lastNCommits > 0) {
+        // Walk back N commits from the actual head being reviewed (defaults to
+        // local HEAD when the caller didn't thread a pushed ref through). Using
+        // a literal "HEAD" here would be wrong for `git push origin
+        // some-other-branch` invocations, where the local checkout's HEAD is a
+        // different branch entirely and the resulting diff would compare the
+        // wrong commits.
+        const headRef = options.headRef !== undefined && options.headRef.length > 0
+            ? options.headRef
+            : 'HEAD';
+        const requested = options.lastNCommits;
+        const tryDepth = (k) => git.tryRevParse(['--verify', '--quiet', `${headRef}~${k}^{commit}`]).trim();
+        // Fast path: requested depth resolves directly.
+        const direct = tryDepth(requested);
+        if (direct.length > 0) {
+            return {
+                ref: direct,
+                source: 'last-n-commits',
+                lastNCommits: requested,
+            };
+        }
+        // Clamp: `<headRef>~N` did not resolve. Two distinct causes need
+        // different handling — and the difference matters because the wrong
+        // choice silently inflates the review:
+        //
+        //   (i) Branch is genuinely shorter than N (full clone). The
+        //       deepest resolvable ancestor `<headRef>~K` IS the root
+        //       commit (parent-less). Diffing against `<headRef>~K` would
+        //       EXCLUDE the root commit's changes (`git diff base..head`
+        //       excludes `base`), so we diff against EMPTY_TREE_SHA to
+        //       include them. Report lastNCommits = K + 1 (every commit on
+        //       the branch was reviewed).
+        //
+        //   (ii) Repo is a shallow clone — `<headRef>~K` resolves but
+        //        `<headRef>~K`'s parent simply isn't fetched locally. The
+        //        commit isn't actually the root; older history exists on
+        //        the remote. Diffing against EMPTY_TREE_SHA would balloon
+        //        the review to "every tracked file in the checkout"
+        //        (including all unchanged base-branch files), defeating
+        //        the entire point of last-n-commits. So in the shallow
+        //        case we diff against `<headRef>~K` itself, accepting that
+        //        the K-th commit's changes are excluded — the operator
+        //        chose a shallow clone and the deepest reachable commit is
+        //        the best base we have. Report lastNCommits = K (the K
+        //        ancestors we DID reach).
+        //
+        // `git rev-parse --is-shallow-repository` distinguishes the two
+        // cases (returns "true" / "false"). On unknown / errored output we
+        // assume FULL (the safer default for case (i): we'd rather review
+        // the root commit and risk a slightly larger diff than silently
+        // drop changes).
+        //
+        // Both Codex [P1] findings 2026-04-29 (initial empty-tree-on-clamp
+        // dropping root commit, then shallow-clone empty-tree expanding to
+        // full repo) drove this two-branch design.
+        const oneSha = tryDepth(1);
+        if (oneSha.length === 0) {
+            // Even `<headRef>~1` does not resolve — single-commit history
+            // (full clone with one commit) OR a shallow clone fetched at
+            // depth=1. In both cases the only locally-resolvable commit is
+            // headRef itself; there's no useful intermediate base. Fall back
+            // to empty-tree (matches case (i) of single commit review) and
+            // report lastNCommits = 1.
+            return {
+                ref: EMPTY_TREE_SHA,
+                source: 'empty-tree',
+                lastNCommits: 1,
+                lastNCommitsRequested: requested,
+            };
+        }
+        // Binary search for the deepest K < N where `<headRef>~K` resolves.
+        // Invariant: tryDepth(lo) resolves; tryDepth(hi+1) does not. We
+        // narrow until lo > hi; bestDepth carries the highest K seen.
+        let lo = 1;
+        let hi = requested - 1;
+        let bestDepth = 1;
+        while (lo <= hi) {
+            const mid = lo + Math.floor((hi - lo) / 2);
+            const sha = tryDepth(mid);
+            if (sha.length > 0) {
+                bestDepth = mid;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        const shallowFlag = git.tryRevParse(['--is-shallow-repository']).trim();
+        if (shallowFlag === 'true') {
+            // Case (ii): shallow clone. Diff against the deepest reachable
+            // ancestor SHA — its parent exists on the remote but isn't
+            // locally available, so empty-tree would over-review. Accept that
+            // the K-th commit's content is excluded; that's the cost of the
+            // shallow clone the operator chose.
+            const bestSha = tryDepth(bestDepth);
+            return {
+                ref: bestSha,
+                source: 'last-n-commits',
+                lastNCommits: bestDepth,
+                lastNCommitsRequested: requested,
+            };
+        }
+        // Case (i): full clone, branch genuinely shorter than N. The
+        // deepest resolvable ancestor IS the root. Diff against empty-tree
+        // to include the root commit's changes; reviewed count = K + 1.
+        return {
+            ref: EMPTY_TREE_SHA,
+            source: 'last-n-commits',
+            lastNCommits: bestDepth + 1,
+            lastNCommitsRequested: requested,
+        };
+    }
     // 1. Upstream of current branch. `@{upstream}` resolves to the configured
     //    tracking ref (typically `refs/remotes/origin/<branch>`). Returns
     //    empty on branches without an upstream — which is normal for a brand

package/dist/hooks/push-gate/index.d.ts

@@ -63,6 +63,14 @@ export interface PushGateDeps {
     stderr: (line: string) => void;
     /** Override via `--base <ref>`. Absent → auto-resolve. */
     explicitBase?: string;
+    /**
+     * Override from the `--last-n-commits N` CLI flag. When set, the gate
+     * diffs against `HEAD~N` instead of running the upstream ladder. Wins
+     * over `policy.review.last_n_commits` but loses to `explicitBase`. When
+     * both `explicitBase` and this are set, `explicitBase` is used and a
+     * stderr warning is emitted noting the conflict.
+     */
+    lastNCommits?: number;
     /**
      * Pre-push refspecs from git's stdin. Empty when invoked outside a
      * pre-push context (manual `rea hook push-gate` from the CLI). When