@bookedsolid/rea 0.11.0 → 0.13.0

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/codex-runner.d.ts

@@ -51,6 +51,14 @@ export interface GitExecutor {
     headSha(): string;
     /** `git diff --name-only <base> <head>`. Returns path list (possibly empty). */
     diffNames(base: string, head: string): string[];
+    /**
+     * `git rev-list --count <base>..<head>`. Returns the integer commit count
+     * or `null` when the range cannot be resolved (unreachable base, shallow
+     * clone, etc.) — null lets the caller treat divergence-counting as
+     * best-effort without breaking the gate. Used by the auto-narrow probe
+     * (J / 0.13.0).
+     */
+    revListCount(base: string, head: string): number | null;
 }
 /**
  * Real git implementation using `spawnSync`. Each call is independent (no

package/dist/hooks/push-gate/codex-runner.js

@@ -95,6 +95,19 @@ export function createRealGitExecutor(cwd) {
                 return [];
             return r.stdout.split(/\r?\n/).filter((l) => l.length > 0);
         },
+        revListCount(base, head) {
+            // `git rev-list --count base..head` — number of commits reachable
+            // from head but not base. Returns null on any failure so the caller
+            // can treat divergence-counting as best-effort (auto-narrow probe).
+            const r = run(['rev-list', '--count', `${base}..${head}`]);
+            if (r.code !== 0)
+                return null;
+            const trimmed = r.stdout.trim();
+            if (trimmed.length === 0)
+                return null;
+            const n = Number(trimmed);
+            return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+        },
     };
 }
 /**

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

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

@@ -24,7 +24,7 @@
 import path from 'node:path';
 import { appendAuditRecord } from '../../audit/append.js';
 import { Tier, InvocationStatus } from '../../policy/types.js';
-import { resolvePushGatePolicy, } from './policy.js';
+import { resolvePushGatePolicy, PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK, } from './policy.js';
 import { readHalt } from './halt.js';
 import { resolveBaseRef } from './base.js';
 import { createRealGitExecutor, runCodexReview, CodexNotInstalledError, CodexProtocolError, CodexSubprocessError, CodexTimeoutError, } from './codex-runner.js';
@@ -124,38 +124,109 @@ export async function runPushGate(deps) {
             summary: 'review.codex_required is false — push-gate skipped',
         };
     }
-    // 3. REA_SKIP_PUSH_GATE — value-carrying waiver. HALT-wins ordering means
-    //    this is checked AFTER halt (step 1) and AFTER codex_required=false
+    // 3. Value-carrying skip waivers. HALT-wins ordering means these are
+    //    checked AFTER halt (step 1) and AFTER codex_required=false
     //    short-circuit (step 2). Both of those should hold anyway; this is
-    //    for the case where codex is required but the operator wants to
+    //    for the case where codex IS required but the operator wants to
     //    skip for a narrow, documented reason.
-    const skipReason = (env.REA_SKIP_PUSH_GATE ?? '').trim();
-    if (skipReason.length > 0) {
-        stderr(`rea: REA_SKIP_PUSH_GATE=${skipReason} — push-gate skipped (audited).\n`);
+    //
+    //    Two equivalent env vars are honored — gate behavior is identical;
+    //    only the audit metadata's `skip_var` differs so operators can grep
+    //    their audit log to see which variant agents used:
+    //
+    //      - REA_SKIP_PUSH_GATE     — the original 0.11.0 var
+    //      - REA_SKIP_CODEX_REVIEW  — added in 0.12.0 to match the variant
+    //                                 documented elsewhere in the codebase
+    //                                 (gateway/reviewers, codex-probe). Prior
+    //                                 to 0.12.0 this string only worked at
+    //                                 the gateway tier; agents who set it on
+    //                                 a `git push` got no skip and codex still
+    //                                 ran. The mismatch surfaced during the
+    //                                 helixir migration session 2026-04-26.
+    //
+    //    Precedence on simultaneous set: REA_SKIP_PUSH_GATE wins (it was the
+    //    canonical name) and REA_SKIP_CODEX_REVIEW is logged but not used.
+    //    Either var alone with non-empty reason short-circuits.
+    const skipPush = (env.REA_SKIP_PUSH_GATE ?? '').trim();
+    const skipCodex = (env.REA_SKIP_CODEX_REVIEW ?? '').trim();
+    if (skipPush.length > 0 || skipCodex.length > 0) {
+        const skipVar = skipPush.length > 0 ? 'REA_SKIP_PUSH_GATE' : 'REA_SKIP_CODEX_REVIEW';
+        const skipReason = skipVar === 'REA_SKIP_PUSH_GATE' ? skipPush : skipCodex;
+        stderr(`rea: ${skipVar}=${skipReason} — push-gate skipped (audited).\n`);
         await safeAppend(appendAuditFn, deps.baseDir, EVT_SKIPPED, {
             reason: skipReason,
+            skip_var: skipVar,
         });
         return {
             status: 'skipped',
             exitCode: 0,
-            summary: `REA_SKIP_PUSH_GATE waiver: ${skipReason}`,
+            summary: `${skipVar} waiver: ${skipReason}`,
         };
     }
     // 4. Resolve (base_ref, head_sha) for the actual review.
     //
-    //    When pre-push stdin yielded at least one refspec (`git push` path),
-    //    diff against the first NON-DELETION refspec's (remote_sha..local_sha).
-    //    This matches what git itself is about to push — critical when the
-    //    operator uses `git push origin HEAD:release/1.0` and the branch's
-    //    tracking ref is a different branch entirely (the 0.10.x gate
-    //    silently reviewed against the wrong base in that case).
+    //    Precedence (highest first):
+    //      a) `--base <ref>` CLI flag (deps.explicitBase) — explicit ref the
+    //         operator named; we trust it.
+    //      b) `--last-n-commits N` CLI flag (deps.lastNCommits) — diff
+    //         against HEAD~N. Wins over the policy key.
+    //      c) `policy.review.last_n_commits` — same effect as (b), but
+    //         configured in `.rea/policy.yaml`. Persistent narrow-window.
+    //      d) Active refspec from pre-push stdin — what git is about to
+    //         push. Critical for `git push origin HEAD:release/1.0`.
+    //      e) Upstream → origin/HEAD → main/master ladder.
     //
-    //    When stdin was empty (manual invocation, test), fall back to the
-    //    upstream → origin/HEAD → main/master ladder.
+    //    When (a) collides with (b) or (c), (a) wins and we warn — explicit
+    //    ref beats relative count.
+    const policyLastN = policy.last_n_commits;
+    const explicitBaseSet = deps.explicitBase !== undefined && deps.explicitBase.length > 0;
+    const lastNFromFlag = deps.lastNCommits;
+    const effectiveLastN = lastNFromFlag !== undefined ? lastNFromFlag : policyLastN;
+    if (explicitBaseSet && effectiveLastN !== undefined) {
+        const source = lastNFromFlag !== undefined ? '--last-n-commits' : 'policy.review.last_n_commits';
+        stderr(`rea: --base ${deps.explicitBase} overrides ${source}=${effectiveLastN}; using explicit ref.\n`);
+    }
     const activeRefspec = (deps.refspecs ?? []).find((r) => r.localSha !== NULL_SHA && r.localSha.length > 0);
     let base;
     let headSha;
-    if (activeRefspec !== undefined && (deps.explicitBase === undefined || deps.explicitBase.length === 0)) {
+    // Tracks whether the base was resolved from the active refspec's
+    // remoteSha — i.e. "the tip of this branch as the remote currently sees
+    // it". Only that case represents commits Codex has already reviewed in
+    // a prior push; auto-narrow is only safe there (J / 0.13.0). Initial
+    // pushes against `origin/main`-shaped bases must NOT auto-narrow,
+    // because earlier commits on the branch may never have been reviewed.
+    let baseFromPushedRemoteTip = false;
+    if (explicitBaseSet) {
+        // (a) explicit base wins absolutely.
+        base = resolveBaseRef(git, { explicit: deps.explicitBase });
+        headSha = activeRefspec !== undefined ? activeRefspec.localSha : git.headSha();
+    }
+    else if (effectiveLastN !== undefined && effectiveLastN > 0) {
+        // (b) / (c) last-n-commits. Resolves to a SHA via `git rev-parse
+        // <headRef>~N`. Compute headSha FIRST so the resolver walks back N
+        // commits from the pushed ref rather than the local HEAD — critical
+        // for `git push origin some-other-branch` where the active refspec's
+        // localSha is a different branch entirely from the checkout's HEAD.
+        headSha = activeRefspec !== undefined ? activeRefspec.localSha : git.headSha();
+        base = resolveBaseRef(git, {
+            lastNCommits: effectiveLastN,
+            headRef: headSha,
+        });
+        if (base.lastNCommitsRequested !== undefined &&
+            base.lastNCommits !== undefined &&
+            base.lastNCommits < base.lastNCommitsRequested) {
+            // Clamp warning: the resolver couldn't go back N commits, so it
+            // clamped to the entire branch history (diff vs empty-tree, K+1
+            // commits reviewed) — `base.lastNCommits` carries the actual K+1.
+            // This warning fires both when source is 'last-n-commits' (clamped
+            // mid-branch, root commit included via empty-tree) and when source
+            // is 'empty-tree' (single-commit branch). The user-facing message
+            // is identical: we wanted N, got K, here's what we reviewed.
+            stderr(`rea: ${headSha.slice(0, 12)}~${base.lastNCommitsRequested} not reachable; reviewing all ${base.lastNCommits} commits on this branch instead.\n`);
+        }
+    }
+    else if (activeRefspec !== undefined) {
+        // (d) refspec-aware base — use what git is about to push.
         headSha = activeRefspec.localSha;
         if (activeRefspec.remoteSha === NULL_SHA || activeRefspec.remoteSha.length === 0) {
             // New remote ref — no existing commits to diff against. Fall back to
@@ -165,14 +236,14 @@ export async function runPushGate(deps) {
         }
         else {
             base = { ref: activeRefspec.remoteSha, source: 'explicit' };
+            // ONLY this path produces a base that represents the previously-
+            // reviewed remote tip of THIS branch. Auto-narrow is safe here.
+            baseFromPushedRemoteTip = true;
         }
     }
     else {
-        base = resolveBaseRef(git, {
-            ...(deps.explicitBase !== undefined && deps.explicitBase.length > 0
-                ? { explicit: deps.explicitBase }
-                : {}),
-        });
+        // (e) upstream ladder.
+        base = resolveBaseRef(git);
         headSha = git.headSha();
     }
     if (headSha.length === 0) {
@@ -180,6 +251,67 @@ export async function runPushGate(deps) {
         await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, { kind: 'head-sha-missing' });
         return { status: 'error', exitCode: 2, summary: 'head-sha-missing' };
     }
+    // 4b. Auto-narrow probe (J / 0.13.0). When the resolved base is far
+    //     behind HEAD AND the operator has not already pinned an explicit
+    //     window, scope the review down to the recent commits and warn.
+    //
+    //     CRITICAL safety rule: auto-narrow ONLY fires when the base was
+    //     resolved from the active refspec's remoteSha — i.e. "the tip of
+    //     this branch as the remote currently sees it". Only that case
+    //     represents commits Codex already reviewed in a prior push, so
+    //     skipping older commits on the branch is safe.
+    //
+    //     For initial pushes (or any base resolved via the upstream /
+    //     origin-head / origin-main ladder), the diff target is a trunk-
+    //     like ref where commits earlier in the branch may never have been
+    //     reviewed. Auto-narrowing past them would silently bypass the
+    //     advertised pre-push review for a hook/policy/security change
+    //     made early in the branch (codex-review 0.13.0 [P1]).
+    //
+    //     Suppression rules (any one prevents auto-narrow from firing):
+    //
+    //       - `--base` flag set (operator picked an explicit ref)
+    //       - `--last-n-commits` flag set (operator picked an explicit
+    //         window)
+    //       - `policy.review.last_n_commits` set (persistent narrow window)
+    //       - `policy.review.auto_narrow_threshold: 0` (disabled)
+    //       - resolver already produced a `last-n-commits` source (we got
+    //         here via the policyLastN branch above)
+    //       - resolver fell back to `empty-tree` (single-commit branch /
+    //         orphan; no usable upstream — narrowing would be silly)
+    //       - base was NOT derived from the active refspec's remoteSha
+    //         (initial push, no upstream, fallback to origin/main, etc.)
+    //
+    //     The probe uses `git rev-list --count base..HEAD` rather than
+    //     `diffNames().length` — line-counting commits is far cheaper than
+    //     listing every changed path on a 50+ commit branch. A null result
+    //     (range unresolvable) suppresses auto-narrow entirely; we'd
+    //     rather err on the side of reviewing more than tripping a
+    //     half-baked auto-narrow on a degenerate ref.
+    let autoNarrowed = false;
+    let originalCommitCount = null;
+    const autoNarrowEligible = !explicitBaseSet &&
+        lastNFromFlag === undefined &&
+        policyLastN === undefined &&
+        policy.auto_narrow_threshold > 0 &&
+        base.source !== 'last-n-commits' &&
+        base.source !== 'empty-tree' &&
+        baseFromPushedRemoteTip;
+    if (autoNarrowEligible) {
+        originalCommitCount = git.revListCount(base.ref, headSha);
+        if (originalCommitCount !== null &&
+            originalCommitCount > policy.auto_narrow_threshold) {
+            const fallbackWindow = PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK;
+            const narrowed = resolveBaseRef(git, {
+                lastNCommits: fallbackWindow,
+                headRef: headSha,
+            });
+            stderr(`rea: auto-narrow — ${originalCommitCount} commits behind ${base.ref} (threshold ${policy.auto_narrow_threshold}); reviewing the last ${fallbackWindow} commits instead.\n` +
+                `  Override: pass \`--last-n-commits N\` or \`--base <ref>\`, set \`review.last_n_commits\` in .rea/policy.yaml, or disable with \`review.auto_narrow_threshold: 0\`.\n`);
+            base = narrowed;
+            autoNarrowed = true;
+        }
+    }
     // 5. Empty-diff short-circuit. An initial push against the empty-tree
     //    sentinel ALWAYS has a non-empty diff (HEAD vs empty tree); this
     //    short-circuit only fires when the feature branch really is a
@@ -190,6 +322,10 @@ export async function runPushGate(deps) {
             base_ref: base.ref,
             base_source: base.source,
             head_sha: headSha,
+            last_n_commits: base.lastNCommits,
+            last_n_commits_requested: base.lastNCommitsRequested,
+            auto_narrowed: autoNarrowed ? true : undefined,
+            original_commit_count: originalCommitCount !== null ? originalCommitCount : undefined,
         });
         return {
             status: 'empty-diff',
@@ -238,6 +374,10 @@ export async function runPushGate(deps) {
             duration_seconds: codexResult.durationSeconds,
             event_count: codexResult.eventCount,
             concerns_override: summary.verdict === 'concerns' && isConcernsOverrideSet(env) ? true : undefined,
+            last_n_commits: base.lastNCommits,
+            last_n_commits_requested: base.lastNCommitsRequested,
+            auto_narrowed: autoNarrowed ? true : undefined,
+            original_commit_count: originalCommitCount !== null ? originalCommitCount : undefined,
         });
         if (blocked) {
             return {

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

@@ -9,9 +9,16 @@
  * skip". This module is pure policy.
  *
  * Defaults (when a field is absent or `review:` is missing entirely):
- *   - `codex_required`   → `true`  (safe-by-default: run Codex)
- *   - `concerns_blocks`  → `true`  (safe-by-default: concerns halt the push)
- *   - `timeout_ms`       → 600_000 (10 minutes)
+ *   - `codex_required`   → `true`    (safe-by-default: run Codex)
+ *   - `concerns_blocks`  → `true`    (safe-by-default: concerns halt the push)
+ *   - `timeout_ms`       → 1_800_000 (30 minutes — raised in 0.12.0 from the
+ *                                     previous 10-minute default after the
+ *                                     helixir migration session 2026-04-26
+ *                                     showed realistic feature-branch
+ *                                     reviews routinely exceeded 10 minutes
+ *                                     on large diffs. Operators who pin
+ *                                     `timeout_ms:` in policy.yaml are
+ *                                     unaffected by this change.)
  *
  * A missing `.rea/policy.yaml` is treated as "defaults apply" — the
  * operator may not have run `rea init` yet, and the gate's behavior
@@ -22,12 +29,40 @@ export interface ResolvedReviewPolicy {
     codex_required: boolean;
     concerns_blocks: boolean;
     timeout_ms: number;
+    /**
+     * When set, the gate resolves the diff base to `HEAD~N` (see Fix D in
+     * 0.12.0). The CLI flag `--last-n-commits N` overrides this; the
+     * policy key surfaces here as a runtime knob with the same effect.
+     * `undefined` when unset (default-untouched behavior).
+     */
+    last_n_commits: number | undefined;
+    /**
+     * Auto-narrow threshold (J / 0.13.0). When the resolved diff base is more
+     * than N commits behind HEAD AND no explicit narrowing was pinned, the
+     * gate scopes to `PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK` (10) and
+     * emits a stderr warning. Defaults to 30 when unset; 0 disables.
+     */
+    auto_narrow_threshold: number;
     /** `true` when `.rea/policy.yaml` was absent; defaults apply. */
     policyMissing: boolean;
 }
-export declare const PUSH_GATE_DEFAULT_TIMEOUT_MS = 600000;
+export declare const PUSH_GATE_DEFAULT_TIMEOUT_MS = 1800000;
 export declare const PUSH_GATE_DEFAULT_CODEX_REQUIRED = true;
 export declare const PUSH_GATE_DEFAULT_CONCERNS_BLOCKS = true;
+/**
+ * Default auto-narrow threshold (J / 0.13.0). When the divergence between
+ * the resolved base and HEAD exceeds this count and the operator has not
+ * pinned an explicit window, the gate auto-narrows to
+ * `PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK` commits.
+ */
+export declare const PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD = 30;
+/**
+ * Window the gate auto-narrows to when the threshold trips and the operator
+ * has not pinned `policy.review.last_n_commits`. Conservative — small
+ * enough that Codex review stays fast, large enough to capture meaningful
+ * recent work.
+ */
+export declare const PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK = 10;
 /**
  * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
  * policy file surfaces as a typed error via the underlying zod validator,

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

@@ -9,9 +9,16 @@
  * skip". This module is pure policy.
  *
  * Defaults (when a field is absent or `review:` is missing entirely):
- *   - `codex_required`   → `true`  (safe-by-default: run Codex)
- *   - `concerns_blocks`  → `true`  (safe-by-default: concerns halt the push)
- *   - `timeout_ms`       → 600_000 (10 minutes)
+ *   - `codex_required`   → `true`    (safe-by-default: run Codex)
+ *   - `concerns_blocks`  → `true`    (safe-by-default: concerns halt the push)
+ *   - `timeout_ms`       → 1_800_000 (30 minutes — raised in 0.12.0 from the
+ *                                     previous 10-minute default after the
+ *                                     helixir migration session 2026-04-26
+ *                                     showed realistic feature-branch
+ *                                     reviews routinely exceeded 10 minutes
+ *                                     on large diffs. Operators who pin
+ *                                     `timeout_ms:` in policy.yaml are
+ *                                     unaffected by this change.)
  *
  * A missing `.rea/policy.yaml` is treated as "defaults apply" — the
  * operator may not have run `rea init` yet, and the gate's behavior
@@ -21,9 +28,23 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadPolicyAsync } from '../../policy/loader.js';
-export const PUSH_GATE_DEFAULT_TIMEOUT_MS = 600_000;
+export const PUSH_GATE_DEFAULT_TIMEOUT_MS = 1_800_000;
 export const PUSH_GATE_DEFAULT_CODEX_REQUIRED = true;
 export const PUSH_GATE_DEFAULT_CONCERNS_BLOCKS = true;
+/**
+ * Default auto-narrow threshold (J / 0.13.0). When the divergence between
+ * the resolved base and HEAD exceeds this count and the operator has not
+ * pinned an explicit window, the gate auto-narrows to
+ * `PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK` commits.
+ */
+export const PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD = 30;
+/**
+ * Window the gate auto-narrows to when the threshold trips and the operator
+ * has not pinned `policy.review.last_n_commits`. Conservative — small
+ * enough that Codex review stays fast, large enough to capture meaningful
+ * recent work.
+ */
+export const PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK = 10;
 /**
  * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
  * policy file surfaces as a typed error via the underlying zod validator,
@@ -41,6 +62,8 @@ export async function resolvePushGatePolicy(baseDir) {
             codex_required: PUSH_GATE_DEFAULT_CODEX_REQUIRED,
             concerns_blocks: PUSH_GATE_DEFAULT_CONCERNS_BLOCKS,
             timeout_ms: PUSH_GATE_DEFAULT_TIMEOUT_MS,
+            last_n_commits: undefined,
+            auto_narrow_threshold: PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD,
             policyMissing: true,
         };
     }
@@ -50,6 +73,8 @@ export async function resolvePushGatePolicy(baseDir) {
         codex_required: review.codex_required ?? PUSH_GATE_DEFAULT_CODEX_REQUIRED,
         concerns_blocks: review.concerns_blocks ?? PUSH_GATE_DEFAULT_CONCERNS_BLOCKS,
         timeout_ms: review.timeout_ms ?? PUSH_GATE_DEFAULT_TIMEOUT_MS,
+        last_n_commits: review.last_n_commits,
+        auto_narrow_threshold: review.auto_narrow_threshold ?? PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD,
         policyMissing: false,
     };
 }