@bookedsolid/rea 0.10.1 → 0.10.3

package/dist/hooks/review-gate/audit.js

@@ -0,0 +1,181 @@
+/**
+ * Audit-record emission + consumption for the review gate.
+ *
+ * ## Responsibilities
+ *
+ * 1. Emit `push.review.skipped` and `codex.review.skipped` records via the
+ *    existing `appendAuditRecord()` helper. These are NEVER forgeable-
+ *    verdict records (the push-review gate never consults them as Codex
+ *    receipts), so they intentionally go through the `"other"`-stamped
+ *    public path rather than the `"rea-cli"` dedicated writer.
+ *
+ * 2. Scan `.rea/audit.jsonl` for a qualifying `codex.review` receipt
+ *    certifying a given `head_sha`. This is the TS equivalent of the
+ *    bash core's `jq -R 'fromjson? | select(...)'` predicate
+ *    (push-review-core.sh §959-966).
+ *
+ * ## Defect carry-forwards
+ *
+ * - **Defect P** (forgery rejection). The scan filter requires
+ *   `emission_source ∈ {"rea-cli", "codex-cli"}`. The public
+ *   `appendAuditRecord()` helper stamps `"other"`; only the dedicated
+ *   `appendCodexReviewAuditRecord()` helper and the Codex CLI write
+ *   `"rea-cli"` / `"codex-cli"`. Records with `emission_source: "other"`
+ *   or missing the field entirely are rejected here.
+ *
+ * - **Defect U** (streaming-parse tolerance). Every line in `.rea/
+ *   audit.jsonl` is parsed independently in a try/catch. A single
+ *   corrupt line mid-file does NOT abort the scan — later lines still
+ *   get a chance. Before 0.10.2 the bash `jq -e` scan would bail on the
+ *   first unparseable line and miss every subsequent legitimate record.
+ *
+ * - **Verdict whitelist**. Only `verdict ∈ {"pass", "concerns"}` records
+ *   satisfy the protected-path gate. `blocking` and `error` verdicts are
+ *   receipts that a review HAPPENED but with a negative outcome, which
+ *   does NOT unblock the push. Mirrors push-review-core.sh §964.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { appendAuditRecord, InvocationStatus, Tier, } from '../../audit/append.js';
+import { collectOsIdentity } from './metadata.js';
+/** Tool-names the gate emits. Kept as constants so string-literal drift is caught at compile time. */
+export const PUSH_REVIEW_SKIPPED_TOOL = 'push.review.skipped';
+export const CODEX_REVIEW_SKIPPED_TOOL = 'codex.review.skipped';
+export const PUSH_REVIEW_CACHE_HIT_TOOL = 'push.review.cache.hit';
+export const PUSH_REVIEW_CACHE_ERROR_TOOL = 'push.review.cache.error';
+/** Server-names for the emit paths — carry forward from bash §473/§639. */
+export const ESCAPE_HATCH_SERVER = 'rea.escape_hatch';
+export const PUSH_REVIEW_SERVER = 'rea.push_review';
+/**
+ * Emit the `push.review.skipped` audit record. Wraps the public
+ * `appendAuditRecord()` helper — emission_source lands as `"other"`.
+ *
+ * The skipped record is intentionally NOT a `codex.review` receipt: the
+ * push-review cache-gate scan rejects any record whose `tool_name` is not
+ * `codex.review` AND any record whose `emission_source` is not
+ * `rea-cli` / `codex-cli`. So this record is on the hash chain as
+ * forensic evidence but cannot be confused with a real Codex review.
+ */
+export async function emitPushReviewSkipped(input) {
+    const osIdentity = input.os_identity ?? collectOsIdentity();
+    const metadata = {
+        head_sha: input.head_sha,
+        branch: input.branch,
+        reason: input.reason,
+        actor: input.actor,
+        verdict: 'skipped',
+        os_identity: osIdentity,
+    };
+    const record = {
+        tool_name: PUSH_REVIEW_SKIPPED_TOOL,
+        server_name: ESCAPE_HATCH_SERVER,
+        status: InvocationStatus.Allowed,
+        tier: Tier.Read,
+        metadata,
+    };
+    return appendAuditRecord(input.baseDir, record);
+}
+export async function emitCodexReviewSkipped(input) {
+    const metadata = {
+        head_sha: input.head_sha,
+        target: input.target,
+        reason: input.reason,
+        actor: input.actor,
+        verdict: 'skipped',
+        files_changed: null,
+        metadata_source: input.metadata_source,
+    };
+    const record = {
+        tool_name: CODEX_REVIEW_SKIPPED_TOOL,
+        server_name: ESCAPE_HATCH_SERVER,
+        status: InvocationStatus.Allowed,
+        tier: Tier.Read,
+        metadata,
+    };
+    return appendAuditRecord(input.baseDir, record);
+}
+/** Verdicts that satisfy the protected-path Codex-receipt gate. */
+const ACCEPTABLE_VERDICTS = new Set(['pass', 'concerns']);
+/** Emission sources that satisfy the protected-path Codex-receipt gate. */
+const ACCEPTABLE_SOURCES = new Set(['rea-cli', 'codex-cli']);
+/**
+ * Predicate: does this parsed JSON object qualify as a valid
+ * `codex.review` receipt for the given `head_sha`?
+ *
+ * Exported for unit tests; callers should usually use
+ * `hasValidCodexReview()` below.
+ */
+export function isQualifyingCodexReview(record, head_sha) {
+    if (record === null || typeof record !== 'object')
+        return false;
+    const r = record;
+    if (r.tool_name !== 'codex.review')
+        return false;
+    if (typeof r.emission_source !== 'string' || !ACCEPTABLE_SOURCES.has(r.emission_source)) {
+        return false;
+    }
+    const md = r.metadata;
+    if (md === null || md === undefined || typeof md !== 'object')
+        return false;
+    if (md.head_sha !== head_sha)
+        return false;
+    if (typeof md.verdict !== 'string' || !ACCEPTABLE_VERDICTS.has(md.verdict)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Scan `.rea/audit.jsonl` for a qualifying `codex.review` record matching
+ * the given `head_sha`. Returns true as soon as one is found.
+ *
+ * ## Defect U tolerance
+ *
+ * Each line is parsed independently via `JSON.parse` inside try/catch. A
+ * malformed line logs nothing and the scan continues. The bash fix in
+ * 0.10.2 was `jq -R 'fromjson?'`; we mirror the per-line behavior in
+ * native JS.
+ *
+ * ## Path safety
+ *
+ * The audit file is always `<baseDir>/.rea/audit.jsonl` — baseDir flows
+ * in from the caller and is the same resolved path used everywhere else.
+ * No caller-supplied path segments.
+ *
+ * ## Missing file
+ *
+ * ENOENT resolves to `false` (no receipt exists yet). Any other error
+ * propagates — the caller's policy is to fail-closed, and a permission
+ * error on the audit file is a distinct operational concern the caller
+ * should surface rather than silently mask as "no receipt".
+ */
+export async function hasValidCodexReview(baseDir, head_sha) {
+    const auditFile = path.join(baseDir, '.rea', 'audit.jsonl');
+    let raw;
+    try {
+        raw = await fs.readFile(auditFile, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    if (raw.length === 0)
+        return false;
+    // Walk lines. Each line is independently parsed; a corrupt line is
+    // silently skipped. A matching record short-circuits the scan.
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            // Defect U tolerance — move on.
+            continue;
+        }
+        if (isQualifyingCodexReview(parsed, head_sha))
+            return true;
+    }
+    return false;
+}

package/dist/hooks/review-gate/banner.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Operator-facing banner composition.
+ *
+ * The bash core builds its banners via `printf` inside a `{ ... } >&2`
+ * block, counting diff lines with `grep -cE ...` and file changes with
+ * `grep -c '^+++ '`. Defect K (rea#62) surfaced because `grep -c`
+ * emits `0` to stdout AND exits non-zero on no-match, and the bash author
+ * wrote `$(grep -c ... || echo 0)` — which emitted `0\n0` when the pipe
+ * produced no matches. The fix in the bash core was `|| true` + default
+ * via `${LINE_COUNT:-0}`.
+ *
+ * The TS port closes this entire class of bug: counting happens over an
+ * actual string in Node, not via a pipe-on-a-side-effect. The only way
+ * LINE_COUNT / FILE_COUNT can ever be wrong now is a test-missed edge in
+ * `countChangedLines` or `countChangedFiles` — unit tests in `banner.test.ts`
+ * cover the zero case, the empty-diff case, the unicode-filename case, and
+ * the `+++ b/-file` edge explicitly.
+ *
+ * ## Format parity
+ *
+ * `renderPushReviewRequiredBanner` reproduces the byte-exact output of the
+ * bash core's "PUSH REVIEW GATE: Review required..." block, including the
+ * cache-disabled fallback branch. A fixture test in `banner.test.ts` asserts
+ * the output against a snapshot captured from the 0.10.1 bash core.
+ */
+export interface DiffStats {
+    /** Number of `^\+[^+]|^-[^-]` lines in the unified diff. */
+    line_count: number;
+    /** Number of `^\+\+\+ ` lines (one per changed file). */
+    file_count: number;
+}
+/**
+ * Count lines that begin with `+` followed by a non-`+` character, OR `-`
+ * followed by a non-`-` character. Bash-core parity (push-review-core.sh
+ * §1082): `grep -cE '^\+[^+]|^-[^-]'`. This rejects every line whose
+ * SECOND character is the same as the first — not just `+++`/`---`
+ * headers, but also pathological `++foo` and `--bar` strings (which bash
+ * did not count). Codex pass-1 on phase 1 flagged the earlier too-lax
+ * char-1-only TS implementation that would have silently changed the
+ * Scope: banner line count vs. bash and broken phase-4 byte compatibility.
+ *
+ * Empty input → 0. Bare `+` or `-` (single char line) → 0, same as bash
+ * (the regex requires a second character).
+ */
+export declare function countChangedLines(diff: string): number;
+/**
+ * Count `^\+\+\+ ` header lines (one per file in the diff). Parity with
+ * the bash core's `grep -c '^\+\+\+ '`.
+ */
+export declare function countChangedFiles(diff: string): number;
+/**
+ * Compute `{line_count, file_count}` over a diff string. Exposed separately
+ * so callers can use just the stats without generating the full banner.
+ */
+export declare function computeDiffStats(diff: string): DiffStats;
+export interface PushReviewRequiredBannerInput {
+    /** The ref being pushed (e.g. `refs/heads/feature/foo` or `HEAD`). */
+    source_ref: string;
+    /** The source commit SHA (12 chars + rest; full sha expected). */
+    source_sha: string;
+    /** Target branch / base label (defect N completion surfaces here). */
+    target_branch: string;
+    /** Resolved merge-base SHA. */
+    merge_base: string;
+    /** Diff stats — pre-computed by `computeDiffStats`. */
+    stats: DiffStats;
+    /**
+     * The sha256-of-diff cache key. When empty, the banner emits the
+     * cache-disabled fallback branch (`Cache is DISABLED on this host`).
+     */
+    push_sha: string;
+    /** Source branch name for the `rea cache set` hint. */
+    source_branch: string;
+}
+/**
+ * Compose the "PUSH REVIEW GATE: Review required before pushing" banner.
+ * Output goes to stderr via the caller; this function is pure. Returns the
+ * exact text the bash core would have printed (including trailing blank
+ * line and spacing), so the fixture snapshot can be compared byte-exactly.
+ */
+export declare function renderPushReviewRequiredBanner(input: PushReviewRequiredBannerInput): string;
+export interface ProtectedPathsBlockedBannerInput {
+    source_ref: string;
+    source_sha: string;
+}
+/**
+ * Compose the "PUSH BLOCKED: protected paths changed — /codex-review
+ * required" banner. Pure; exit-2 translation happens in the CLI shim.
+ */
+export declare function renderProtectedPathsBlockedBanner(input: ProtectedPathsBlockedBannerInput): string;
+/**
+ * Strip C0 control characters (0x00-0x1F, 0x7F) and C1 (0x80-0x9F) from a
+ * string. Used when a banner embeds text from a subprocess's stderr (e.g.
+ * the cache-check failure case). Mirrors the `LC_ALL=C tr -d` invocation
+ * in the bash core's cache-error path. Codex LOW 5 on the 0.9.4 pass.
+ */
+export declare function stripControlChars(input: string): string;

package/dist/hooks/review-gate/banner.js

@@ -0,0 +1,172 @@
+/**
+ * Operator-facing banner composition.
+ *
+ * The bash core builds its banners via `printf` inside a `{ ... } >&2`
+ * block, counting diff lines with `grep -cE ...` and file changes with
+ * `grep -c '^+++ '`. Defect K (rea#62) surfaced because `grep -c`
+ * emits `0` to stdout AND exits non-zero on no-match, and the bash author
+ * wrote `$(grep -c ... || echo 0)` — which emitted `0\n0` when the pipe
+ * produced no matches. The fix in the bash core was `|| true` + default
+ * via `${LINE_COUNT:-0}`.
+ *
+ * The TS port closes this entire class of bug: counting happens over an
+ * actual string in Node, not via a pipe-on-a-side-effect. The only way
+ * LINE_COUNT / FILE_COUNT can ever be wrong now is a test-missed edge in
+ * `countChangedLines` or `countChangedFiles` — unit tests in `banner.test.ts`
+ * cover the zero case, the empty-diff case, the unicode-filename case, and
+ * the `+++ b/-file` edge explicitly.
+ *
+ * ## Format parity
+ *
+ * `renderPushReviewRequiredBanner` reproduces the byte-exact output of the
+ * bash core's "PUSH REVIEW GATE: Review required..." block, including the
+ * cache-disabled fallback branch. A fixture test in `banner.test.ts` asserts
+ * the output against a snapshot captured from the 0.10.1 bash core.
+ */
+/**
+ * Count lines that begin with `+` followed by a non-`+` character, OR `-`
+ * followed by a non-`-` character. Bash-core parity (push-review-core.sh
+ * §1082): `grep -cE '^\+[^+]|^-[^-]'`. This rejects every line whose
+ * SECOND character is the same as the first — not just `+++`/`---`
+ * headers, but also pathological `++foo` and `--bar` strings (which bash
+ * did not count). Codex pass-1 on phase 1 flagged the earlier too-lax
+ * char-1-only TS implementation that would have silently changed the
+ * Scope: banner line count vs. bash and broken phase-4 byte compatibility.
+ *
+ * Empty input → 0. Bare `+` or `-` (single char line) → 0, same as bash
+ * (the regex requires a second character).
+ */
+export function countChangedLines(diff) {
+    if (diff.length === 0)
+        return 0;
+    let n = 0;
+    const lines = diff.split('\n');
+    for (const line of lines) {
+        if (line.length < 2)
+            continue;
+        const c0 = line.charCodeAt(0);
+        const c1 = line.charCodeAt(1);
+        // `+` = 43: match only when char-2 is NOT `+`.
+        if (c0 === 43 && c1 !== 43) {
+            n++;
+            continue;
+        }
+        // `-` = 45: match only when char-2 is NOT `-`.
+        if (c0 === 45 && c1 !== 45) {
+            n++;
+            continue;
+        }
+        // Any other leading char, including `++...` and `--...`, is skipped.
+    }
+    return n;
+}
+/**
+ * Count `^\+\+\+ ` header lines (one per file in the diff). Parity with
+ * the bash core's `grep -c '^\+\+\+ '`.
+ */
+export function countChangedFiles(diff) {
+    if (diff.length === 0)
+        return 0;
+    let n = 0;
+    const lines = diff.split('\n');
+    for (const line of lines) {
+        if (line.startsWith('+++ '))
+            n++;
+    }
+    return n;
+}
+/**
+ * Compute `{line_count, file_count}` over a diff string. Exposed separately
+ * so callers can use just the stats without generating the full banner.
+ */
+export function computeDiffStats(diff) {
+    return {
+        line_count: countChangedLines(diff),
+        file_count: countChangedFiles(diff),
+    };
+}
+/**
+ * Compose the "PUSH REVIEW GATE: Review required before pushing" banner.
+ * Output goes to stderr via the caller; this function is pure. Returns the
+ * exact text the bash core would have printed (including trailing blank
+ * line and spacing), so the fixture snapshot can be compared byte-exactly.
+ */
+export function renderPushReviewRequiredBanner(input) {
+    const lines = [];
+    lines.push('PUSH REVIEW GATE: Review required before pushing');
+    lines.push('');
+    lines.push(`  Source ref: ${input.source_ref} (${input.source_sha.slice(0, 12)})`);
+    lines.push(`  Target: ${input.target_branch}`);
+    lines.push(`  Scope: ${input.stats.file_count} files changed, ${input.stats.line_count} lines`);
+    lines.push('');
+    lines.push('  Action required:');
+    lines.push(`  1. Spawn a code-reviewer agent to review: git diff ${input.merge_base}..${input.source_sha}`);
+    lines.push('  2. Spawn a security-engineer agent for security review');
+    if (input.push_sha.length > 0) {
+        lines.push('  3. After both pass, cache the result:');
+        lines.push(`     rea cache set ${input.push_sha} pass --branch ${input.source_branch} --base ${input.target_branch}`);
+    }
+    else {
+        lines.push('  3. Cache is DISABLED on this host (no sha256 hasher found).');
+        lines.push('     After both reviews pass, bypass the push-review gate with:');
+        lines.push('       REA_SKIP_PUSH_REVIEW="<reason>" git push ...');
+        lines.push('     The bypass is audited as push.review.skipped — this is the');
+        lines.push('     documented escape hatch when cache is unavailable.');
+        lines.push('     To restore the cache path, install one of: sha256sum,');
+        lines.push('     shasum (Perl Digest::SHA), or openssl.');
+    }
+    lines.push('');
+    // bash `printf '%s\n'` with no trailing args adds a final newline; the
+    // block renders terminal-ready. `lines.join('\n') + '\n'` reproduces
+    // exactly that shape.
+    return lines.join('\n') + '\n';
+}
+/**
+ * Compose the "PUSH BLOCKED: protected paths changed — /codex-review
+ * required" banner. Pure; exit-2 translation happens in the CLI shim.
+ */
+export function renderProtectedPathsBlockedBanner(input) {
+    const lines = [];
+    lines.push(`PUSH BLOCKED: protected paths changed — /codex-review required for ${input.source_sha}`);
+    lines.push('');
+    lines.push(`  Source ref: ${input.source_ref}`);
+    lines.push('  Diff touches one of:');
+    lines.push('    - src/gateway/middleware/');
+    lines.push('    - hooks/');
+    lines.push('    - .claude/hooks/');
+    lines.push('    - src/policy/');
+    lines.push('    - .github/workflows/');
+    lines.push('    - .rea/');
+    lines.push('    - .husky/');
+    lines.push('');
+    lines.push(`  Run /codex-review against ${input.source_sha}, then retry the push.`);
+    lines.push('  The codex-adversarial agent emits the required audit entry.');
+    lines.push('  Only `pass` or `concerns` verdicts satisfy this gate.');
+    lines.push('');
+    return lines.join('\n') + '\n';
+}
+/**
+ * Strip C0 control characters (0x00-0x1F, 0x7F) and C1 (0x80-0x9F) from a
+ * string. Used when a banner embeds text from a subprocess's stderr (e.g.
+ * the cache-check failure case). Mirrors the `LC_ALL=C tr -d` invocation
+ * in the bash core's cache-error path. Codex LOW 5 on the 0.9.4 pass.
+ */
+export function stripControlChars(input) {
+    let out = '';
+    for (let i = 0; i < input.length; i++) {
+        const c = input.charCodeAt(i);
+        // Allow tab (9), LF (10), CR (13) — but not any other C0/C1 byte.
+        if (c === 9 || c === 10 || c === 13) {
+            out += input[i];
+            continue;
+        }
+        if (c <= 0x1f)
+            continue;
+        if (c === 0x7f)
+            continue;
+        if (c >= 0x80 && c <= 0x9f)
+            continue;
+        out += input[i];
+    }
+    return out;
+}

package/dist/hooks/review-gate/base-resolve.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Base-ref resolution for the push-review gate.
+ *
+ * ## What "base resolution" means
+ *
+ * Given a pushed refspec (a `local_sha` + `remote_ref` pair, plus the
+ * remote name), determine:
+ *
+ *   1. the commit SHA the local changes should be diffed against
+ *      (the "merge base"), and
+ *   2. the human-facing label for the `Target:` banner line
+ *      (defect N semantic: the SEMANTIC base, not the refspec destination).
+ *
+ * The four code paths the bash core walked (push-review-core.sh §720-889):
+ *
+ *   A. Tracked-branch push (`remote_sha != ZERO`). Use
+ *      `git merge-base <remote_sha> <local_sha>`. Label = refspec target.
+ *   B. New-branch push with `branch.<source>.base` config (defect N). The
+ *      operator opted into a specific base. Prefer `refs/remotes/<remote>/
+ *      <configured>` if it exists, else fall back to `refs/heads/<configured>`
+ *      with a WARN on stderr. Label = configured base name.
+ *   C. New-branch push without config, with `refs/remotes/<remote>/HEAD`
+ *      resolvable. Use that symbolic-ref as the anchor. Label = refspec
+ *      target (preserves the cache-key contract for bare pushes).
+ *   D. Bootstrap: no config, no symbolic-ref, probe `main` then `master`.
+ *      If both fail, anchor on the empty-tree SHA so the full push content
+ *      is reviewable. Label = refspec target.
+ *
+ * ## Phase 2a scope (this file)
+ *
+ * `resolveBaseForRefspec()` composes the four paths via the `GitRunner`
+ * port from `diff.ts`. This module is pure in the same sense `diff.ts`
+ * is — every git hit goes through the injected runner, so unit tests
+ * enumerate the four paths without touching a real repo.
+ *
+ * Defect-N fail-loud (design §7) is Phase 4's final cutover and is NOT
+ * turned on here. `NoBaseResolvableError` is reserved in `errors.ts` but
+ * the empty-tree bootstrap remains the current production fallback.
+ * Phase 2b composes the final policy into `runPushReviewGate()`.
+ */
+import { type GitRunner } from './diff.js';
+import type { RefspecRecord } from './args.js';
+/**
+ * Resolved base outcome for a single refspec. Never thrown — callers
+ * translate blocked conditions (remote object missing, no merge-base)
+ * into `BlockedError` subclasses up the stack.
+ */
+export interface ResolvedBase {
+    /**
+     * The commit / tree SHA to diff against. Always set when
+     * `status === 'ok'`; otherwise null.
+     */
+    merge_base: string | null;
+    /**
+     * The human-facing `Target:` label (defect N). The bash core defaults
+     * this to the refspec target and promotes it to the configured base's
+     * short name only when `branch.<source>.base` resolved. We mirror that.
+     */
+    target_label: string;
+    /** Discriminator for the caller. */
+    status: 'ok' | 'remote_object_missing' | 'no_merge_base' | 'no_base_resolvable';
+    /**
+     * For the "tracked branch but the remote commit isn't locally present"
+     * path, return the remote SHA so the caller's banner can echo it. Empty
+     * otherwise.
+     */
+    remote_sha?: string;
+    /**
+     * True when the configured-base branch was resolved via the LOCAL ref
+     * (`refs/heads/<configured>`) instead of the remote-tracking ref. The
+     * bash core prints a WARN in this case (push-review-core.sh §819-820).
+     * Phase 2a carries the signal; Phase 2b's composition emits the banner.
+     */
+    local_ref_fallback_warning?: string;
+    /**
+     * The resolution path taken. Audit + debugging aid; never part of the
+     * cache key. Phase 2b's audit records include this for forensic trace.
+     */
+    path: 'tracked' | 'new_branch_config' | 'new_branch_origin_head' | 'bootstrap_empty_tree';
+}
+/**
+ * Deps for base resolution. Same `GitRunner` port `diff.ts` uses; plus the
+ * remote name (from the adapter's argv, defaults to `origin`). `cwd` is
+ * the resolved repo root.
+ */
+export interface ResolveBaseDeps {
+    runner: GitRunner;
+    cwd: string;
+    /** Remote name (`origin` by convention, but respect what git passed to the hook). */
+    remote: string;
+}
+/**
+ * Strip `refs/heads/` / `refs/for/` prefixes from a ref and return the
+ * trailing branch name. Used for the target-label normalization path
+ * where both ref families should collapse to a bare branch name for
+ * display. Exported for tests.
+ */
+export declare function stripRefsPrefix(ref: string): string;
+/**
+ * Strip ONLY the `refs/heads/` prefix — leaves `refs/for/`, `refs/tags/`,
+ * and every other ref-namespace untouched. Mirrors the bash core's
+ * `${local_ref#refs/heads/}` on the source-branch lookup path (push-review-
+ * core.sh §797), so Gerrit-style pushes (`refs/for/main`) keep their
+ * namespace and do NOT accidentally match a `branch.main.base` config
+ * entry intended for a regular branch push.
+ *
+ * Codex pass-1 on Phase 2a flagged the earlier implementation that used
+ * `stripRefsPrefix` here — it would have promoted the Target: label for
+ * a Gerrit push against the reviewer's intent. Exported for tests.
+ */
+export declare function stripRefsHeadsOnly(ref: string): string;
+/**
+ * Resolve the base anchor for a single push refspec. See the file-top
+ * docstring for the four code paths.
+ *
+ * Deletion refspecs (local_sha === ZERO_SHA) return `{merge_base: null,
+ * status: 'ok'}` with `path: 'tracked'` — the caller is expected to have
+ * already trapped deletions via `hasDeletion()` before calling here. We
+ * don't throw in that case because the caller owns the deletion policy,
+ * not this resolver.
+ */
+export declare function resolveBaseForRefspec(record: RefspecRecord, deps: ResolveBaseDeps): ResolvedBase;
+/**
+ * Compute the initial `Target:` label for a refspec: the short name of
+ * the remote ref, falling back to `main` when it's empty (defensive;
+ * `args.ts` should never emit an empty remote_ref for a non-deletion).
+ *
+ * Exported for unit tests. Mirrors push-review-core.sh §725-727.
+ */
+export declare function computeInitialTargetLabel(record: RefspecRecord): string;
+/**
+ * Inner helper: resolve the new-branch anchor via the B→C→D walk. Stays
+ * module-private so callers only see `resolveBaseForRefspec` as the
+ * public surface. Returns a discriminated union so the caller can branch
+ * on path + extract the warning / label cleanly.
+ */
+type NewBranchOutcome = {
+    kind: 'config_hit';
+    ref: string;
+    label: string;
+    /** Non-null when we fell back to `refs/heads/<base>` (§819-820 WARN). */
+    warning: string | null;
+} | {
+    kind: 'origin_head';
+    ref: string;
+} | {
+    kind: 'bootstrap';
+};
+/**
+ * Path B: consult `branch.<source>.base`. Returns `config_hit` iff a base
+ * was configured AND resolvable to a ref that exists. Falls through
+ * otherwise. Exported so tests can exercise the config-path independently.
+ */
+export declare function resolveNewBranchBase(sourceBranch: string, deps: ResolveBaseDeps): NewBranchOutcome;
+export {};