@bookedsolid/rea 0.10.3 → 0.12.0

package/dist/cli/install/settings-merge.d.ts

@@ -41,6 +41,23 @@ export interface MergeResult {
  * hooks and returns the merged settings plus a list of warnings. Does NOT
  * touch disk.
  */
+/**
+ * Remove hook entries whose `command` contains any of the listed
+ * substrings. Returns a deep-cloned settings object plus the count of
+ * entries removed. Empty hook arrays and empty groups are pruned too so
+ * the resulting file doesn't accumulate empty sentinel objects after
+ * repeated upgrade runs.
+ *
+ * Used by `rea upgrade` to purge references to hooks we delete in a
+ * release (0.11.0 removed `push-review-gate.sh` and `commit-review-gate.sh`).
+ * Without this, `mergeSettings()` is additive-only and consumer
+ * `.claude/settings.json` would keep executing stale commands that
+ * point at files we just deleted from `.claude/hooks/`.
+ */
+export declare function pruneHookCommands(existing: Record<string, unknown>, staleSubstrings: readonly string[]): {
+    merged: Record<string, unknown>;
+    removedCount: number;
+};
 export declare function mergeSettings(existing: Record<string, unknown>, desired: DesiredHookGroup[]): MergeResult;
 /**
  * Atomic write via tmp-file + rename.

package/dist/cli/install/settings-merge.js

@@ -39,6 +39,54 @@ function keyFor(matcher, command) {
  * hooks and returns the merged settings plus a list of warnings. Does NOT
  * touch disk.
  */
+/**
+ * Remove hook entries whose `command` contains any of the listed
+ * substrings. Returns a deep-cloned settings object plus the count of
+ * entries removed. Empty hook arrays and empty groups are pruned too so
+ * the resulting file doesn't accumulate empty sentinel objects after
+ * repeated upgrade runs.
+ *
+ * Used by `rea upgrade` to purge references to hooks we delete in a
+ * release (0.11.0 removed `push-review-gate.sh` and `commit-review-gate.sh`).
+ * Without this, `mergeSettings()` is additive-only and consumer
+ * `.claude/settings.json` would keep executing stale commands that
+ * point at files we just deleted from `.claude/hooks/`.
+ */
+export function pruneHookCommands(existing, staleSubstrings) {
+    const merged = deepClone(existing);
+    const hooks = ensureHooksShape(merged);
+    let removedCount = 0;
+    for (const event of Object.keys(hooks)) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            const entries = group.hooks ?? [];
+            if (!Array.isArray(entries))
+                continue;
+            const kept = [];
+            for (const entry of entries) {
+                const cmd = typeof entry.command === 'string' ? entry.command : '';
+                if (staleSubstrings.some((s) => cmd.includes(s))) {
+                    removedCount += 1;
+                    continue;
+                }
+                kept.push(entry);
+            }
+            group.hooks = kept;
+        }
+        // Drop groups whose hooks list is now empty.
+        hooks[event] = groups.filter((g) => Array.isArray(g.hooks) && g.hooks.length > 0);
+    }
+    // Drop events whose group list is now empty.
+    for (const event of Object.keys(hooks)) {
+        const groups = hooks[event];
+        if (Array.isArray(groups) && groups.length === 0) {
+            delete hooks[event];
+        }
+    }
+    return { merged, removedCount };
+}
 export function mergeSettings(existing, desired) {
     const merged = deepClone(existing);
     const hooks = ensureHooksShape(merged);
@@ -215,7 +263,6 @@ export function defaultDesiredHooks() {
                 { type: 'command', command: `${base}/security-disclosure-gate.sh`, timeout: 5000, statusMessage: 'Checking disclosure policy...' },
                 { type: 'command', command: `${base}/pr-issue-link-gate.sh`, timeout: 5000, statusMessage: 'Checking PR for issue reference...' },
                 { type: 'command', command: `${base}/attribution-advisory.sh`, timeout: 5000, statusMessage: 'Checking for AI attribution...' },
-                { type: 'command', command: `${base}/push-review-gate.sh`, timeout: 30000, statusMessage: 'Running push review gate...' },
             ],
         },
         {

package/dist/cli/upgrade.js

@@ -44,11 +44,103 @@ import { loadPolicy } from '../policy/loader.js';
 import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFiles, } from './install/canonical.js';
 import { buildFragment, extractFragment, } from './install/claude-md.js';
 import { atomicReplaceFile, safeDeleteFile, safeInstallFile, safeReadFile, } from './install/fs-safe.js';
-import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
+import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, pruneHookCommands, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
 import { ensureReaGitignore } from './install/gitignore.js';
 import { manifestExists, readManifest, writeManifestAtomic, } from './install/manifest-io.js';
 import { sha256OfBuffer, sha256OfFile } from './install/sha.js';
 import { err, getPkgVersion, log, warn } from './utils.js';
+// ---------------------------------------------------------------------------
+// 0.11.0 policy migration
+// ---------------------------------------------------------------------------
+/**
+ * Strip 0.10.x review.* fields that 0.11.0 rejects at schema load, and
+ * backfill `concerns_blocks: true` if the `review:` block exists without
+ * it. Writes a timestamped backup to `.rea/policy.yaml.bak-<ts>` before
+ * mutating.
+ *
+ * Surgical text rewrite, not YAML round-trip. YAML round-tripping loses
+ * comments and reformats quoting; operators care about their comments.
+ * Line-by-line deletion of the two removed keys keeps every other line
+ * byte-identical. This is safe because the keys we strip are simple
+ * scalars (`cache_max_age_seconds: 3600`, `allow_skip_in_ci: false`) that
+ * cannot span multiple lines in any reasonable policy file.
+ */
+async function migrateReviewPolicyFor0110(resolvedRoot, opts) {
+    const policyPath = path.join(resolvedRoot, '.rea', 'policy.yaml');
+    let raw;
+    try {
+        raw = await fsPromises.readFile(policyPath, 'utf8');
+    }
+    catch {
+        return; // no policy to migrate
+    }
+    const lines = raw.split(/\r?\n/);
+    const REVIEW_RE = /^review:\s*(?:#.*)?$/;
+    const REMOVED_KEY_RE = /^(\s+)(cache_max_age_seconds|allow_skip_in_ci):\s*\S.*$/;
+    const INDENT_RE = /^(\s+)\S/;
+    let reviewStart = -1;
+    let reviewIndent = '';
+    const linesToDrop = new Set();
+    let hasConcernsBlocks = false;
+    let reviewChildIndent = '';
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        if (reviewStart < 0 && REVIEW_RE.test(line.trimEnd())) {
+            reviewStart = i;
+            const indentMatch = INDENT_RE.exec(line);
+            reviewIndent = indentMatch?.[1] ?? '';
+            continue;
+        }
+        if (reviewStart < 0)
+            continue;
+        // Inside the review: block as long as indent is deeper than reviewIndent.
+        if (line.trim() === '')
+            continue;
+        const indentMatch = INDENT_RE.exec(line);
+        const lineIndent = indentMatch?.[1] ?? '';
+        if (lineIndent.length <= reviewIndent.length) {
+            // Left the block.
+            break;
+        }
+        if (reviewChildIndent.length === 0)
+            reviewChildIndent = lineIndent;
+        if (/^\s+concerns_blocks:/.test(line))
+            hasConcernsBlocks = true;
+        if (REMOVED_KEY_RE.test(line)) {
+            linesToDrop.add(i);
+        }
+    }
+    const addConcernsBlocks = reviewStart >= 0 && !hasConcernsBlocks;
+    if (linesToDrop.size === 0 && !addConcernsBlocks)
+        return;
+    const newLines = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        if (linesToDrop.has(i))
+            continue;
+        newLines.push(lines[i] ?? '');
+        // Append `concerns_blocks: true` right after the `review:` header line
+        // when the block exists but lacks the key.
+        if (i === reviewStart && addConcernsBlocks) {
+            const indent = reviewChildIndent.length > 0 ? reviewChildIndent : reviewIndent + '  ';
+            newLines.push(`${indent}concerns_blocks: true`);
+        }
+    }
+    const updated = newLines.join('\n');
+    const droppedSummary = [];
+    if (linesToDrop.size > 0)
+        droppedSummary.push(`dropped ${linesToDrop.size} removed-field line(s)`);
+    if (addConcernsBlocks)
+        droppedSummary.push('added concerns_blocks: true');
+    if (opts.dryRun) {
+        log(`[dry-run] would migrate .rea/policy.yaml: ${droppedSummary.join(', ')}`);
+        return;
+    }
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${policyPath}.bak-${ts}`;
+    await fsPromises.copyFile(policyPath, backupPath);
+    await atomicReplaceFile(policyPath, updated);
+    warn(`migrated .rea/policy.yaml for 0.11.0 (${droppedSummary.join(', ')}); backup at ${path.basename(backupPath)}`);
+}
 /**
  * Hard cap for `showDiff` reads. Canonical files are all tiny (<64KB) but a
  * consumer could have replaced a hook with a 500MB log; refuse to slurp the
@@ -282,19 +374,50 @@ async function upgradeClaudeMdFragment(resolvedRoot, opts) {
     await atomicReplaceFile(claudeMdPath, next);
     return { sha: newSha, action: 'written' };
 }
+/**
+ * Hook commands deleted in 0.11.0. `upgradeSettings` prunes any entries
+ * whose `command` string contains one of these tokens so consumer
+ * `.claude/settings.json` files don't keep invoking missing scripts
+ * (which would fail every matched tool call until the operator edited
+ * settings by hand).
+ *
+ * 0.11.0 removals:
+ *   - push-review-gate.sh        (replaced by husky stub → rea hook push-gate)
+ *   - commit-review-gate.sh      (intentionally unregistered; source-of-truth deleted)
+ *   - push-review-gate-git.sh    (native-git adapter; deleted)
+ *
+ * Add future removals here rather than baking the list into
+ * `pruneHookCommands` itself — the removal list is release history,
+ * not a static setting.
+ */
+const STALE_HOOK_COMMAND_TOKENS = [
+    'push-review-gate.sh',
+    'commit-review-gate.sh',
+    'push-review-gate-git.sh',
+];
 async function upgradeSettings(baseDir, opts) {
     const desired = defaultDesiredHooks();
     const sha = canonicalSettingsSubsetHash(desired);
     const { settings, settingsPath } = readSettings(baseDir);
-    const mergeResult = mergeSettings(settings, desired);
+    // PRUNE FIRST (remove 0.11.0-deleted hook references), THEN MERGE
+    // (add any new hooks). Order matters: merging first would re-add the
+    // stale entry only to have the prune re-delete it on the next line —
+    // pointless work. Pruning first means the merge sees a clean baseline.
+    const pruned = pruneHookCommands(settings, STALE_HOOK_COMMAND_TOKENS);
+    const mergeResult = mergeSettings(pruned.merged, desired);
     if (opts.dryRun !== true) {
         await writeSettingsAtomic(settingsPath, mergeResult.merged);
     }
+    const warnings = [...mergeResult.warnings];
+    if (pruned.removedCount > 0) {
+        warnings.push(`pruned ${pruned.removedCount} stale 0.10.x hook entr${pruned.removedCount === 1 ? 'y' : 'ies'} from .claude/settings.json (removed in 0.11.0)`);
+    }
     return {
         sha,
         addedCount: mergeResult.addedCount,
         skippedCount: mergeResult.skippedCount,
-        warnings: mergeResult.warnings,
+        removedCount: pruned.removedCount,
+        warnings,
     };
 }
 /** Re-hash a file we just wrote. Source and on-disk bytes should match, but
@@ -321,6 +444,11 @@ export async function runUpgrade(options = {}) {
     if (options.force === true && !dryRun) {
         warn('--force: overwriting locally-modified files and deleting removed-upstream entries without prompt.');
     }
+    // 0.11.0 migration — strip removed review.* fields and backfill the new
+    // concerns_blocks default. Runs before canonical file reconciliation so a
+    // policy that fails strict schema load (which happens on upgrade from
+    // 0.10.x the moment we re-read `.rea/policy.yaml`) is cleaned up first.
+    await migrateReviewPolicyFor0110(resolvedRoot, { dryRun });
     const canonicalFiles = await enumerateCanonicalFiles();
     if (canonicalFiles.length === 0) {
         err('no canonical files found in package — is the build complete?');

package/dist/config/tier-map.js

@@ -110,28 +110,20 @@ export function isToolBlocked(toolName, serverName, gatewayConfig) {
  * Classify a `rea <subcommand>` Bash invocation by its own semantics rather
  * than the generic Bash default.
  *
- * Defect E (rea#78): REA's own governance CLI must not be denied by REA's own
- * middleware. The gate's error messages literally say "Run `rea cache set
- * <sha> pass --branch <x> --base <y>`" — then the agent is denied at autonomy
- * L1 because `Bash` is classified Write and the downstream middleware can't
- * see that the Write is just appending a line to `.rea/review-cache.jsonl`.
+ * REA's own governance CLI must not be denied by REA's own middleware. This
+ * helper returns the tier appropriate to the rea subcommand when the command
+ * parses as `rea <sub>` or `npx rea <sub>`. Returns `null` if the command is
+ * not a rea invocation — callers then fall back to the generic Bash tier.
  *
- * This helper returns the tier appropriate to the rea subcommand when the
- * command parses as `rea <sub>` or `npx rea <sub>`. Returns `null` if the
- * command is not a rea invocation — callers then fall back to the generic
- * Bash tier.
- *
- * Tier mapping:
- *   - Read:        `cache check|list|get`, `audit verify`,
- *                  `audit record codex-review`, `check`, `doctor`, `status`
- *   - Write:       `cache set|clear`, `audit rotate`, `init`,
- *                  `serve`, `upgrade`, `unfreeze`
+ * Tier mapping (0.11.0):
+ *   - Read:        `audit verify`, `check`, `doctor`, `status`,
+ *                  `hook push-gate` (exec-only — no state mutation)
+ *   - Write:       `audit rotate`, `init`, `serve`, `upgrade`, `unfreeze`
  *   - Destructive: `freeze` (writes `.rea/HALT`, suspends the session)
  *
- * `audit record codex-review` is Read-tier because it is REA's own append-only
- * audit surface — the whole point of the command is to let an L1 agent satisfy
- * the push-review gate without a human in the loop. Write-tier here would
- * reintroduce exactly the deadlock Defect D/E close.
+ * `rea cache` and `rea audit record codex-review` were removed in 0.11.0 —
+ * the stateless push-gate needs neither. Any lingering reference to those
+ * subcommands falls through to `Tier.Write` (safe default).
  *
  * SECURITY: returns `null` for any command containing shell metacharacters
  * that would let an attacker piggyback arbitrary commands onto an allowed
@@ -275,18 +267,19 @@ export function reaCommandTier(command) {
             case 'doctor':
             case 'status':
                 return Tier.Read;
-            case 'cache': {
-                if (sub2 === 'check' || sub2 === 'list' || sub2 === 'get')
+            case 'hook': {
+                // `rea hook push-gate` is execution-only — it runs codex exec review
+                // and writes `.rea/last-review.json` + an audit record, but the
+                // user-visible effect is an exit code. Classify Read so the pre-push
+                // hook is not blocked at L1 (symmetric to the 0.10.x reasoning for
+                // `audit record codex-review`).
+                if (sub2 === 'push-gate')
                     return Tier.Read;
-                if (sub2 === 'set' || sub2 === 'clear')
-                    return Tier.Write;
                 return Tier.Write;
             }
             case 'audit': {
                 if (sub2 === 'verify')
                     return Tier.Read;
-                if (sub2 === 'record')
-                    return Tier.Read;
                 if (sub2 === 'rotate')
                     return Tier.Write;
                 return Tier.Write;

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

@@ -0,0 +1,104 @@
+/**
+ * Base-branch resolution for the push-gate.
+ *
+ * Codex `exec review --base <ref>` needs a git ref to diff against. The
+ * caller may provide one via `rea hook push-gate --base <ref>`; if they
+ * don't, we resolve it in priority order:
+ *
+ *   1. Current branch's upstream (`@{upstream}`) — the branch the operator
+ *      configured as their tracking ref. Most accurate since it matches
+ *      what `git push` is about to compare against.
+ *   2. `origin/HEAD` symbolic ref (e.g. `refs/remotes/origin/main`). Set
+ *      automatically by `git clone` and `git remote set-head`.
+ *   3. Explicit probes: `origin/main` → `origin/master` via rev-parse.
+ *   4. Local `main` / `master` — last resort when the clone has no remote
+ *      tracking refs yet (freshly initialized sibling project, mirror
+ *      clone).
+ *
+ * On total failure we surface the sentinel `empty-tree` SHA
+ * (`4b825dc642cb6eb9a060e54bf8d69288fbee4904`) so the diff covers every
+ * file in HEAD. First pushes to a fresh remote still get reviewed — the
+ * 0.10.x fail-open at this resolution step was defect J.
+ *
+ * All git commands are invoked via the injected `GitExecutor` — tests
+ * replace it with a fake to avoid shelling out.
+ */
+import type { GitExecutor } from './codex-runner.js';
+export interface BaseResolution {
+    /**
+     * Resolved ref (branch, remote-tracking ref, or 40-char SHA). Always
+     * usable as the `--base` argument to `codex exec review`.
+     */
+    ref: string;
+    /** Where the ref came from — surfaces in audit records and stderr. */
+    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
+ * installation carries this object implicitly. Using it as a fallback lets
+ * a review on a clone with no tracking refs still exercise the entire HEAD
+ * tree diff.
+ */
+export declare const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+export interface ResolveBaseOptions {
+    /**
+     * Explicit ref from `--base <ref>` or equivalent. When set, the resolver
+     * returns it unchanged with `source: 'explicit'` — the caller is
+     * responsible for its correctness. We do NOT validate that it exists;
+     * 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 —
+ * every failure mode degrades to the next step, and the worst case (no
+ * tracking refs, no local main/master) is `empty-tree`.
+ */
+export declare function resolveBaseRef(git: GitExecutor, options?: ResolveBaseOptions): BaseResolution;

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

@@ -0,0 +1,198 @@
+/**
+ * Base-branch resolution for the push-gate.
+ *
+ * Codex `exec review --base <ref>` needs a git ref to diff against. The
+ * caller may provide one via `rea hook push-gate --base <ref>`; if they
+ * don't, we resolve it in priority order:
+ *
+ *   1. Current branch's upstream (`@{upstream}`) — the branch the operator
+ *      configured as their tracking ref. Most accurate since it matches
+ *      what `git push` is about to compare against.
+ *   2. `origin/HEAD` symbolic ref (e.g. `refs/remotes/origin/main`). Set
+ *      automatically by `git clone` and `git remote set-head`.
+ *   3. Explicit probes: `origin/main` → `origin/master` via rev-parse.
+ *   4. Local `main` / `master` — last resort when the clone has no remote
+ *      tracking refs yet (freshly initialized sibling project, mirror
+ *      clone).
+ *
+ * On total failure we surface the sentinel `empty-tree` SHA
+ * (`4b825dc642cb6eb9a060e54bf8d69288fbee4904`) so the diff covers every
+ * file in HEAD. First pushes to a fresh remote still get reviewed — the
+ * 0.10.x fail-open at this resolution step was defect J.
+ *
+ * All git commands are invoked via the injected `GitExecutor` — tests
+ * replace it with a fake to avoid shelling out.
+ */
+/**
+ * Well-known empty-tree SHA: `git hash-object -t tree /dev/null`. Every git
+ * installation carries this object implicitly. Using it as a fallback lets
+ * a review on a clone with no tracking refs still exercise the entire HEAD
+ * tree diff.
+ */
+export const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * Resolve the base ref using the configured priority order. Never throws —
+ * every failure mode degrades to the next step, and the worst case (no
+ * tracking refs, no local main/master) is `empty-tree`.
+ */
+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
+    //    new feature branch; fall through.
+    const upstream = git
+        .tryRevParse(['--abbrev-ref', '--symbolic-full-name', '@{upstream}'])
+        .trim();
+    if (upstream.length > 0) {
+        return { ref: upstream, source: 'upstream' };
+    }
+    // 2. origin/HEAD symbolic ref. Set by `git clone` to point at the remote's
+    //    default branch. `git symbolic-ref` returns the full ref path; we
+    //    hand that to Codex directly (it's `refs/remotes/origin/<name>`).
+    const originHead = git.trySymbolicRef('refs/remotes/origin/HEAD').trim();
+    if (originHead.length > 0) {
+        return { ref: originHead, source: 'origin-head' };
+    }
+    // 3. Explicit probes for the two most common default-branch names.
+    if (git.tryRevParse(['--verify', '--quiet', 'refs/remotes/origin/main']).length > 0) {
+        return { ref: 'refs/remotes/origin/main', source: 'origin-main' };
+    }
+    if (git.tryRevParse(['--verify', '--quiet', 'refs/remotes/origin/master']).length > 0) {
+        return { ref: 'refs/remotes/origin/master', source: 'origin-master' };
+    }
+    // 4. Local branches. `main` and `master` without `refs/remotes/` prefix
+    //    resolve via `refs/heads/`. Order matches priority 3.
+    if (git.tryRevParse(['--verify', '--quiet', 'refs/heads/main']).length > 0) {
+        return { ref: 'refs/heads/main', source: 'local-main' };
+    }
+    if (git.tryRevParse(['--verify', '--quiet', 'refs/heads/master']).length > 0) {
+        return { ref: 'refs/heads/master', source: 'local-master' };
+    }
+    // 5. Last resort: diff against the empty-tree SHA. Covers every file in
+    //    HEAD; expensive for large repos but correct.
+    return { ref: EMPTY_TREE_SHA, source: 'empty-tree' };
+}