@bookedsolid/rea 0.3.0 → 0.5.0

package/dist/cli/install/gitignore.js

@@ -0,0 +1,356 @@
+/**
+ * BUG-010 — `.gitignore` scaffolding for rea-managed runtime artifacts.
+ *
+ * Background. `rea serve` (G7 catalog fingerprint) writes
+ * `.rea/fingerprints.json` at startup. `rea init` in 0.4.0 and earlier never
+ * scaffolded ANY `.gitignore` entries for the consumer repo, so an operator
+ * who ran `rea init` then started the gateway would see a "new file" in
+ * `git status` that nobody told them about. Helix reported this as BUG-010.
+ *
+ * The fix is broader than fingerprints.json — every runtime artifact rea
+ * writes (under `.rea/` AND its sibling `proper-lockfile` directory at
+ * `.rea.lock`) must be in the consumer's `.gitignore`:
+ *
+ *   - `.rea/audit.jsonl`              — G1 hash-chained audit log (append-only)
+ *   - `.rea/audit-*.jsonl`            — G1 rotated audit archives
+ *   - `.rea/HALT`                     — /freeze marker (ephemeral)
+ *   - `.rea/metrics.jsonl`            — G5 metrics stream
+ *   - `.rea/serve.pid`                — G5 `rea serve` pidfile
+ *   - `.rea/serve.state.json`         — G5 `rea serve` state snapshot
+ *   - `.rea/fingerprints.json`        — G7 downstream catalog fingerprints (BUG-010)
+ *   - `.rea/review-cache.jsonl`       — BUG-009 review cache (rea cache set/check)
+ *   - `.rea/*.tmp`                    — serve temp-file-then-rename pattern
+ *   - `.rea/*.tmp.*`                  — review-cache pid-salted temp pattern
+ *   - `.rea/install-manifest.json.bak` / `.tmp` — fs-safe atomic-replace sidecars
+ *   - `.gitignore.rea-tmp-*`          — this module's own temp files on crash
+ *                                       (root-level — writeAtomic stages next
+ *                                       to .gitignore, not under .rea/)
+ *   - `.rea.lock`                     — proper-lockfile sibling dir (NOT under .rea/)
+ *     (Codex F1 on the BUG-010 review caught all three of these last groups.)
+ *
+ * Idempotency contract.
+ *
+ *   - `rea init` on a fresh repo with no `.gitignore` → create one with the
+ *     managed block only.
+ *   - `rea init` on a repo with a `.gitignore` that has NO rea block → append
+ *     a managed block separated by a blank line.
+ *   - `rea upgrade` on an older install whose `.gitignore` lacks the block →
+ *     same as init; backfill the block so `fingerprints.json` stops showing
+ *     up as an untracked file.
+ *   - `rea upgrade` where the managed block exists but is missing some new
+ *     entries (e.g. `fingerprints.json`, `review-cache.jsonl` added in 0.5.0)
+ *     → insert the missing lines inside the existing block, preserving any
+ *     operator-authored lines within the block.
+ *   - All entries already present, in any order → no-op.
+ *
+ *   Operator DELETIONS of canonical entries are NOT preserved — re-running
+ *   ensureReaGitignore will re-insert any canonical entry missing from the
+ *   block body. To opt out of ignoring a specific artifact, operators must
+ *   configure rea itself, not edit the managed block. This is intentional —
+ *   the managed block is rea's territory.
+ *
+ * Security/containment.
+ *
+ *   - Refuse to follow a `.gitignore` symlink (`lstat` gate before any read).
+ *     The subsequent read uses `O_NOFOLLOW | O_RDONLY` so a TOCTOU swap after
+ *     the lstat cannot trick us into reading through a symlink to secrets
+ *     (e.g. `~/.ssh/id_rsa`) and splicing them into the written `.gitignore`.
+ *   - Temp file name uses `crypto.randomBytes(16)` — not PID + Date.now, which
+ *     are predictable and leak process info. (Codex F2.)
+ *   - Cleanup best-effort on write failure so a stale temp file from a
+ *     prior crash does not accrete.
+ *
+ * CRLF compatibility (Codex F3).
+ *
+ *   Windows consumers with `core.autocrlf=true` get CRLF line endings on
+ *   `.gitignore`. Without explicit handling, `"# === rea managed ==="` !==
+ *   `"# === rea managed ===\r"` and every upgrade would append a duplicate
+ *   block. We detect the input EOL on read, split on `\r?\n`, trim trailing
+ *   whitespace from each line before marker-anchored matching, and re-emit
+ *   with the detected EOL on write.
+ *
+ * Duplicate blocks (Codex F4).
+ *
+ *   If the file already contains two managed blocks (from a prior bug,
+ *   manual copy-paste, or two different rea versions), refuse to modify and
+ *   surface a warning. Merging is more ambitious than this module needs to
+ *   be — the operator resolves manually, then a subsequent run proceeds.
+ */
+import crypto from 'node:crypto';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+const GITIGNORE = '.gitignore';
+export const GITIGNORE_BLOCK_START = '# === rea managed — do not edit between markers ===';
+export const GITIGNORE_BLOCK_END = '# === end rea managed ===';
+/**
+ * Ordered list of entries every rea install must gitignore. Order is stable
+ * so the scaffolded block is deterministic across runs, which in turn makes
+ * drift detection tractable: a diff in the managed block means a consumer
+ * (or another installer) edited it, not that rea reshuffled.
+ *
+ * The grouping below is by origin, not alphabetical:
+ *   1. audit + HALT + metrics   (G1, G4, G5)
+ *   2. serve state              (G5)
+ *   3. fingerprints             (G7 / BUG-010)
+ *   4. review cache             (BUG-009)
+ *   5. temp/sidecar patterns    (Codex F1)
+ *   6. sibling lockfile         (Codex F1 — OUTSIDE .rea/)
+ */
+export const REA_GITIGNORE_ENTRIES = [
+    '.rea/audit.jsonl',
+    '.rea/audit-*.jsonl',
+    '.rea/HALT',
+    '.rea/metrics.jsonl',
+    '.rea/serve.pid',
+    '.rea/serve.state.json',
+    '.rea/fingerprints.json',
+    '.rea/review-cache.jsonl',
+    '.rea/*.tmp',
+    '.rea/*.tmp.*',
+    '.rea/install-manifest.json.bak',
+    '.rea/install-manifest.json.tmp',
+    // This module's own crash-time temp files. `writeAtomic` stages the temp
+    // next to `.gitignore` (i.e. at the repo root), NOT under `.rea/` — so
+    // the glob must live at the repo root too. Codex F2 on the re-review
+    // caught the earlier `.rea/.gitignore.rea-tmp-*` mismatch.
+    '.gitignore.rea-tmp-*',
+    // proper-lockfile (audit chain, cache) locks `.rea/` via a SIBLING dir at
+    // `.rea.lock` — NOT inside `.rea/`. If this looks wrong to a future
+    // maintainer: it is correct, see src/audit/fs.ts.
+    '.rea.lock',
+];
+function buildManagedBlock(entries, eol) {
+    return [GITIGNORE_BLOCK_START, ...entries, GITIGNORE_BLOCK_END].join(eol);
+}
+/**
+ * Trim trailing whitespace ONLY (not leading) and strip a leading UTF-8 BOM.
+ * Leading whitespace would defeat the substring-spoof-rejection guarantee
+ * the tests exercise (`## === rea managed ===` must NOT match).
+ */
+function normalizeLineForMatch(line, isFirst) {
+    const noBom = isFirst ? line.replace(/^\uFEFF/, '') : line;
+    return noBom.replace(/\s+$/, '');
+}
+/**
+ * Find the managed block by ANCHORED marker lines — substring matches are
+ * rejected. A consumer comment containing the sentinel string must not
+ * reclassify an arbitrary block as rea-managed.
+ *
+ * Returns `null` if the start or end marker is not present, or if the start
+ * appears after the end (mangled block — caller falls back to append).
+ *
+ * Returns `'duplicate'` if more than one start marker or more than one end
+ * marker is found — caller refuses to modify in that case.
+ */
+function findManagedBlock(lines) {
+    const startIndices = [];
+    const endIndices = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const norm = normalizeLineForMatch(lines[i], i === 0);
+        if (norm === GITIGNORE_BLOCK_START)
+            startIndices.push(i);
+        else if (norm === GITIGNORE_BLOCK_END)
+            endIndices.push(i);
+    }
+    if (startIndices.length === 0 || endIndices.length === 0)
+        return null;
+    if (startIndices.length > 1 || endIndices.length > 1)
+        return 'duplicate';
+    const [startIdx] = startIndices;
+    const [endIdx] = endIndices;
+    if (endIdx <= startIdx)
+        return null;
+    return { startIdx, endIdx };
+}
+/**
+ * Ensure every required entry is present in the managed block. Preserves any
+ * operator-authored lines between the markers (e.g. a consumer adds
+ * `.rea/my-local-cache` to the block directly — we leave it alone). Missing
+ * required entries are appended in the canonical order, after the existing
+ * body lines.
+ *
+ * NOTE: operator deletions of canonical entries are NOT preserved — see the
+ * module docstring.
+ */
+function reconcileBlock(bodyLines, required) {
+    const present = new Set(bodyLines.map((l) => l.replace(/\s+$/, '')).filter((l) => l.length > 0));
+    const added = [];
+    const appended = [];
+    for (const entry of required) {
+        if (!present.has(entry)) {
+            appended.push(entry);
+            added.push(entry);
+        }
+    }
+    return { lines: [...bodyLines, ...appended], added };
+}
+/**
+ * Open `.gitignore` via `O_NOFOLLOW | O_RDONLY` so a symlink that appeared
+ * after our `lstat` (TOCTOU window) cannot be followed. Darwin/Linux map
+ * `O_NOFOLLOW` to `ELOOP`; we translate that to the same symlink-refusal
+ * message the lstat path would produce.
+ *
+ * Returns `null` when the file does not exist.
+ */
+async function readGitignoreIfFile(absPath) {
+    let lst;
+    try {
+        lst = await fsPromises.lstat(absPath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    if (lst.isSymbolicLink()) {
+        throw new Error(`${absPath} is a symlink — refusing to edit .gitignore through a link. ` +
+            `Replace the link with a regular file and rerun.`);
+    }
+    if (!lst.isFile()) {
+        throw new Error(`${absPath} is not a regular file (type=${String(lst.mode & 0o170000)}) — refusing to edit.`);
+    }
+    // O_NOFOLLOW closes the TOCTOU window between lstat and open on POSIX.
+    // On Windows O_NOFOLLOW is not defined — refuse to edit an existing
+    // `.gitignore` there rather than silently accept the TOCTOU hole.
+    // (Codex F1 on the bc2b77b re-review.) Consumers who still have a
+    // regular file get the lstat-only protection below; operators who end
+    // up with a symlinked .gitignore get a refusal rather than a splice.
+    const O_NOFOLLOW = fsPromises.constants?.O_NOFOLLOW;
+    const O_RDONLY = fsPromises.constants?.O_RDONLY;
+    if (O_NOFOLLOW === undefined || O_RDONLY === undefined) {
+        throw new Error(`${absPath} exists and this platform lacks O_NOFOLLOW — refusing to edit ` +
+            `an existing .gitignore without symlink-race protection. Delete the ` +
+            `file first if rea should scaffold a fresh one.`);
+    }
+    const fd = await fsPromises
+        .open(absPath, O_RDONLY | O_NOFOLLOW)
+        .catch((err) => {
+        if (err.code === 'ELOOP') {
+            throw new Error(`${absPath} became a symlink between lstat and open — refusing to read.`);
+        }
+        throw err;
+    });
+    try {
+        return await fd.readFile('utf8');
+    }
+    finally {
+        await fd.close();
+    }
+}
+/**
+ * Write `.gitignore` with a temp-file + rename, same pattern as the cache
+ * atomic-clear (F4). Avoids torn reads for any tool (IDE, `rea doctor`)
+ * racing this write.
+ *
+ * Temp-name uses `crypto.randomBytes(16)` (not PID/timestamp) — Codex F2
+ * flagged the old name as predictable, which gave a local attacker a way
+ * to pre-create the path and block the write (or place a FIFO on it).
+ */
+async function writeAtomic(absPath, content) {
+    const dir = path.dirname(absPath);
+    const rand = crypto.randomBytes(16).toString('hex');
+    const tmp = path.join(dir, `.gitignore.rea-tmp-${rand}`);
+    try {
+        await fsPromises.writeFile(tmp, content, { encoding: 'utf8', mode: 0o644 });
+        await fsPromises.rename(tmp, absPath);
+    }
+    catch (err) {
+        await fsPromises.unlink(tmp).catch(() => {
+            // Best-effort cleanup. If rename failed the tmp exists; if writeFile
+            // failed before anything landed, unlink fails with ENOENT — either way
+            // we don't want the original error masked.
+        });
+        throw err;
+    }
+}
+/**
+ * Main entry point. Idempotent: calling twice in a row produces `unchanged`
+ * on the second call.
+ *
+ * The `entries` parameter defaults to `REA_GITIGNORE_ENTRIES` — both `rea
+ * init` and `rea upgrade` pass the default. Tests override to verify
+ * reconciliation.
+ */
+export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTRIES) {
+    const absPath = path.resolve(targetDir, GITIGNORE);
+    const warnings = [];
+    let existing;
+    try {
+        existing = await readGitignoreIfFile(absPath);
+    }
+    catch (err) {
+        warnings.push(err.message);
+        return { path: absPath, action: 'unchanged', addedEntries: [], warnings };
+    }
+    // Detect EOL so a CRLF repo stays CRLF and doesn't get torn. Codex F3.
+    const eol = existing !== null && existing.includes('\r\n') ? '\r\n' : '\n';
+    if (existing === null) {
+        const content = buildManagedBlock(entries, '\n') + '\n';
+        await writeAtomic(absPath, content);
+        return {
+            path: absPath,
+            action: 'created',
+            addedEntries: [...entries],
+            warnings,
+        };
+    }
+    const lines = existing.split(/\r?\n/);
+    const hadTrailingNewline = existing.endsWith('\n');
+    const block = findManagedBlock(lines);
+    if (block === 'duplicate') {
+        warnings.push(`${absPath} contains multiple '# === rea managed' blocks — refusing to modify. ` +
+            `Consolidate the managed blocks manually and rerun.`);
+        return { path: absPath, action: 'unchanged', addedEntries: [], warnings };
+    }
+    if (block === null) {
+        // No managed block. Append one after a blank-line separator (unless the
+        // file is empty or already ends with a blank line).
+        const trimmedTailIdx = (() => {
+            let i = lines.length - 1;
+            while (i >= 0 && lines[i] === '')
+                i -= 1;
+            return i;
+        })();
+        const bodyLines = lines.slice(0, trimmedTailIdx + 1);
+        const separator = bodyLines.length === 0 ? [] : [''];
+        const newLines = [
+            ...bodyLines,
+            ...separator,
+            buildManagedBlock(entries, eol),
+        ];
+        const content = newLines.join(eol) + eol;
+        await writeAtomic(absPath, content);
+        return {
+            path: absPath,
+            action: 'updated',
+            addedEntries: [...entries],
+            warnings,
+        };
+    }
+    // Managed block exists — reconcile body lines.
+    const bodyLines = lines.slice(block.startIdx + 1, block.endIdx);
+    const { lines: reconciledBody, added } = reconcileBlock(bodyLines, entries);
+    if (added.length === 0) {
+        return {
+            path: absPath,
+            action: 'unchanged',
+            addedEntries: [],
+            warnings,
+        };
+    }
+    const newLines = [
+        ...lines.slice(0, block.startIdx + 1),
+        ...reconciledBody,
+        ...lines.slice(block.endIdx),
+    ];
+    let content = newLines.join(eol);
+    if (hadTrailingNewline && !content.endsWith(eol))
+        content += eol;
+    await writeAtomic(absPath, content);
+    return {
+        path: absPath,
+        action: 'updated',
+        addedEntries: added,
+        warnings,
+    };
+}

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

@@ -0,0 +1,335 @@
+/**
+ * G6 — Pre-push hook fallback installer.
+ *
+ * Ships alongside `commit-msg.ts` as a second-line defender for the
+ * protected-path Codex audit gate. The primary path is `.husky/pre-push`,
+ * which rea copies into the consumer's `.husky/` via the canonical copy
+ * module. That file only runs when the consumer has husky active
+ * (`core.hooksPath` points at `.husky/`). Consumers who have never run
+ * `husky install`, or who have disabled husky entirely, would otherwise get
+ * ZERO pre-push enforcement — and the protected-path gate is exactly the
+ * thing we cannot let silently lapse.
+ *
+ * The fallback writes a small shell script that `exec`s the same
+ * `push-review-gate.sh` logic the Claude Code hook already runs. The gate
+ * itself is shared — we do NOT duplicate its 700 lines.
+ *
+ * ## Install policy (decision tree, documented)
+ *
+ * Given a consumer repo, we must decide where (if anywhere) to install a
+ * fallback `pre-push`:
+ *
+ *   1. `core.hooksPath` unset (vanilla git):
+ *      → Install `.git/hooks/pre-push`. This is the only path git will fire.
+ *        `.husky/pre-push` sits on disk as a source-of-truth copy but is not
+ *        consulted by git directly.
+ *
+ *   2. `core.hooksPath` set to a directory containing an EXECUTABLE,
+ *      governance-carrying `pre-push`:
+ *      → Do NOT install. A hook is "governance-carrying" when it either
+ *        carries our `FALLBACK_MARKER` (rea-managed) or execs / invokes
+ *        `.claude/hooks/push-review-gate.sh` (consumer-wired delegation).
+ *        This is the happy path for any project running husky 9+ that has
+ *        wired the gate.
+ *
+ *   3. `core.hooksPath` set to a directory with a pre-push that is NOT
+ *      governance-carrying (wrong bits, unrelated script, lint-only husky
+ *      hook, directory, etc.):
+ *      → Classify as foreign. Leave it alone, warn the user, and let
+ *        `rea doctor` downgrade the check to `warn` so the gap is visible.
+ *
+ *   4. `core.hooksPath` set to a directory WITHOUT a pre-push:
+ *      → Install into the configured hooksPath (as `pre-push`). This is the
+ *        "hooksPath is set but nothing lives there yet" case. The active
+ *        hook directory has changed; we install where git will actually look.
+ *
+ * Idempotency: every install writes a stable managed header
+ * (`# rea:pre-push-fallback v1`). Re-running `rea init` detects the header
+ * by ANCHORED match (exact second line after the shebang) and refreshes in
+ * place; it NEVER overwrites a hook without our marker — if the consumer
+ * has their own pre-push already, we warn and skip. Substring matches are
+ * deliberately rejected: a consumer comment, a grep log, or copy-pasted
+ * snippet containing the sentinel must not reclassify a foreign file as
+ * rea-managed.
+ *
+ * ## Why not just rely on `.husky/pre-push`?
+ *
+ * Three concrete failure modes we saw during 0.2.x dogfooding:
+ *   - Consumer hasn't run `husky install` (fresh clone, pnpm hasn't run
+ *     postinstall yet, etc.). `.husky/pre-push` exists but git's hooksPath
+ *     still points at `.git/hooks/`. No enforcement.
+ *   - Consumer deliberately uses `core.hooksPath=./custom-hooks` with a
+ *     different tool. `.husky/pre-push` is dead weight.
+ *   - CI or release automation disables husky via `HUSKY=0`. Again, no
+ *     enforcement at push time.
+ *
+ * The protected-path Codex audit requirement is too important to let any
+ * of those slip through silently. See THREAT_MODEL.md §Governance for the
+ * full rationale.
+ */
+/**
+ * Marker baked into every rea-installed fallback pre-push hook. Used for
+ * idempotency: on re-run we refresh files carrying the marker and refuse
+ * to touch anything that doesn't.
+ *
+ * Bump the version suffix whenever the embedded script semantics change so
+ * upgrades can migrate old installs. Comparison is NOT a substring match —
+ * see `isReaManagedFallback` for the anchored form required to classify
+ * a file as rea-managed.
+ */
+export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v1";
+/**
+ * Marker present in the shipped `.husky/pre-push` governance gate. Detection
+ * requires the marker to appear on the SECOND LINE of the file (immediately
+ * after the shebang) to prevent a consumer comment or copy-pasted snippet
+ * that mentions the string from causing a foreign hook to be misclassified
+ * as rea-managed and then silently overwritten. See `isReaManagedHuskyGate`
+ * for the anchored check.
+ */
+export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v1";
+/**
+ * Second versioned marker embedded in the body of the shipped `.husky/pre-push`.
+ * Required alongside `HUSKY_GATE_MARKER` so that a hook containing only the
+ * header marker + `exit 0` (or any stub body) is not classified as rea-managed.
+ * A genuine rea Husky gate always carries both. The marker is versioned so it
+ * can be bumped if the gate implementation changes significantly.
+ */
+export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v1";
+/**
+ * True when `content` starts with the exact rea fallback prelude. The
+ * marker must appear as the second line, immediately after the shebang,
+ * with no leading whitespace, no alternate shebang (`#!/usr/bin/env sh`),
+ * and no interposed blank lines. Anything else is foreign.
+ *
+ * Rejecting a substring match is what stops a consumer comment like
+ * `# Hint: the old rea:pre-push-fallback v1 marker moved into .husky/` from
+ * accidentally classifying a user's own hook as rea-managed and then
+ * getting overwritten on the next `rea init`.
+ */
+export declare function isReaManagedFallback(content: string): boolean;
+/**
+ * True when `content` has the shipped Husky gate marker on the SECOND LINE
+ * (immediately after the shebang). This is the canonical structure of the
+ * rea-authored `.husky/pre-push` — the shebang occupies line 1 and the marker
+ * occupies line 2 with no intervening blank lines.
+ *
+ * Requiring line-2 placement prevents a consumer comment, copy-pasted snippet,
+ * or any other text that merely *mentions* the marker string from reclassifying
+ * a consumer-owned hook as rea-managed and triggering an overwrite on the next
+ * `rea init`. A marker buried anywhere else in the file is not the canonical
+ * structure and must not be trusted.
+ *
+ * This classification is checked BEFORE `isReaManagedFallback` in
+ * `classifyExistingHook` so that the shipped `.husky/pre-push` is recognized
+ * as a governance-carrying hook rather than `foreign/no-marker`.
+ */
+export declare function isReaManagedHuskyGate(content: string): boolean;
+/**
+ * Pre-0.4 rea-authored `.husky/pre-push` shape — same governance behavior
+ * as the current gate but lacks the line-2/3 versioned markers
+ * (`# rea:husky-pre-push-gate v1` / `# rea:gate-body-v1`) introduced in
+ * 0.4.
+ *
+ * Codex R21 F1: without this detector, any consumer upgrading from a rea
+ * release that shipped the pre-marker hook fell into `foreign/no-marker`.
+ * `classifyPrePushInstall` mapped that to `skip/foreign-pre-push` and
+ * `rea init` refused to touch the file. `rea doctor` reported
+ * `activeForeign=true`. Users had no self-heal path short of manually
+ * deleting the hook — which is a bad migration story for a governance
+ * primitive that they are supposed to trust.
+ *
+ * Shape-level detection:
+ *   1. Line 2 is the canonical pre-0.4 filename header
+ *      `# .husky/pre-push — rea governance gate for terminal-initiated pushes.`
+ *      This header shipped verbatim across the 0.2.x/0.3.x rea releases.
+ *   2. Real governance still present — `hasHaltEnforcement(content)` AND
+ *      `hasAuditCheck(content)` both pass. A stub that only matches the
+ *      header comment (no enforcement) fails the shape check and stays
+ *      classified as foreign.
+ *
+ * Classification consequence: `classifyExistingHook` returns
+ * `rea-managed-husky` for legacy matches. `classifyPrePushInstall` maps
+ * that to `skip/active-pre-push-present` — `rea init` does not touch the
+ * hook (correctness: the file IS still functional governance), but
+ * `inspectPrePushState` reports `ok=true, activeForeign=false` so doctor
+ * stops flagging it. The canonical-manifest-driven upgrade path
+ * (`rea upgrade`) detects the hash mismatch against the packaged
+ * `.husky/pre-push` and surfaces the legacy shape as drift, letting the
+ * operator opt into the refresh explicitly.
+ */
+export declare function isLegacyReaManagedHuskyGate(content: string): boolean;
+/**
+ * True when `content` contains a REAL shell invocation of
+ * `push-review-gate.sh`. Used as a softer signal that a consumer-owned
+ * pre-push still wires the shared gate (e.g. a husky 9 file that runs
+ * lint AND execs the gate). Combined with "exists AND executable", a
+ * gate-referencing foreign hook is a legitimate integration point —
+ * doctor reports `pass`, install skips.
+ *
+ * Accepts (positive-match allowlist):
+ *   - Bare invocation: `.claude/hooks/push-review-gate.sh "$@"`
+ *   - POSIX exec keyword: `exec`, `.`, `sh`, `bash`, `zsh` followed by the
+ *     gate path. The bash-only `source` keyword is NOT accepted — the POSIX
+ *     equivalent `.` (dot) is.
+ *   - Quoted/expanded path prefix: `exec "$REA_ROOT"/.claude/hooks/push-review-gate.sh "$@"`
+ *     — double- or single-quoted variable expansions before the literal path
+ *     are treated as part of the path, not as a mention context.
+ *   - Trailing `;` after `exec <gate>`: `exec gate.sh "$@";` — exec replaces
+ *     the shell, so the `;` and anything after it never runs; gate exit IS
+ *     the hook's exit status.
+ *   - Variable indirection: `GATE=<path-containing-gate>` on one line plus
+ *     `exec "$GATE"` / `. "$GATE"` / etc. on a later line.
+ *
+ * Rejects:
+ *   - Comment lines starting with `#`
+ *   - Shell tests: `[ -x .claude/hooks/push-review-gate.sh ]`
+ *   - File tests: `test -f .claude/hooks/push-review-gate.sh`
+ *   - Chmod / cp / mv / cat / printf / echo mentioning the path
+ *   - String literals inside quoted arguments to non-invocation commands
+ *   - Invocations inside `if`/`for`/`while`/`case` blocks (conditional —
+ *     not guaranteed to run)
+ *   - Invocations after an unconditional top-level `exit`
+ *   - Non-`exec` invocations followed by `||`, `&&`, `;`, or trailing `&`
+ *     (status-swallowing operators)
+ *
+ * This is a pragmatic heuristic, not a full shell parser. R12 F2 broadened
+ * the allowlist to match the forms Codex flagged as valid but previously
+ * rejected; narrower patterns silently hard-failed `rea doctor` on
+ * correctly-governed consumer repos.
+ */
+export declare function referencesReviewGate(content: string): boolean;
+/**
+ * Resolve a configured `core.hooksPath` (possibly relative) to an absolute
+ * path relative to `targetDir`, or `null` if the key is unset.
+ */
+export declare function resolveHooksDir(targetDir: string): Promise<{
+    dir: string | null;
+    configured: boolean;
+}>;
+export type InstallDecision = 
+/** Active pre-push already present and governance-carrying. */
+{
+    action: 'skip';
+    reason: 'active-pre-push-present';
+    hookPath: string;
+}
+/** Consumer owns a non-rea pre-push; refusing to stomp it. */
+ | {
+    action: 'skip';
+    reason: 'foreign-pre-push';
+    hookPath: string;
+}
+/** Write a fresh hook. */
+ | {
+    action: 'install';
+    hookPath: string;
+}
+/** Refresh an existing rea-managed hook (marker match). */
+ | {
+    action: 'refresh';
+    hookPath: string;
+};
+/**
+ * Classify what we should do at `targetDir` based on current state. Pure —
+ * reads the filesystem and git config but performs no writes. Split out so
+ * tests can drive every branch without going through the write path.
+ *
+ * NOTE: The result is a snapshot. `installPrePushFallback` re-resolves and
+ * re-classifies immediately before writing to defend against a husky
+ * install or concurrent `rea init` running between classify and write.
+ */
+export declare function classifyPrePushInstall(targetDir: string): Promise<InstallDecision>;
+export interface PrePushInstallResult {
+    decision: InstallDecision;
+    /** Absolute path of the file written, if any. */
+    written?: string;
+    /** User-facing warnings accumulated during install. */
+    warnings: string[];
+}
+export interface WriteExecutableResult {
+    /**
+     * R25 F2 — set to true when the install path had to use a non-atomic
+     * fallback (copyFile after link() refused). Callers surface this as a
+     * warning to the operator so they know publication was best-effort on
+     * this filesystem rather than atomic.
+     */
+    degradedFromAtomic: boolean;
+}
+/**
+ * Options controlling `installPrePushFallback`. Exposed primarily for
+ * tests — production callers get sensible defaults.
+ */
+export interface InstallPrePushOptions {
+    /**
+     * Serialize concurrent installs via an advisory lockfile under `.git/`.
+     * Defaults to `true`. Tests that simulate concurrent races must keep
+     * this on; the only reason to turn it off is unit-testing a specific
+     * write branch in isolation.
+     */
+    useLock?: boolean;
+    /**
+     * Called exactly once inside the advisory lock, after classification
+     * and before re-resolution + write. Test-only seam that lets a race
+     * partner drop a file in between those two steps so we can assert on
+     * the re-check behavior. Invoked with the classified target path.
+     * Production callers never set this.
+     */
+    onBeforeReresolve?: (hookPath: string) => Promise<void> | void;
+    /**
+     * Called inside the lock, after the safety re-check passes but
+     * immediately before `writeExecutable`. Test-only seam: creates a
+     * file at the hook path to exercise the EEXIST-from-link path that
+     * guards the remaining TOCTOU window. Production callers never set this.
+     */
+    onBeforeWrite?: (hookPath: string) => Promise<void> | void;
+}
+/**
+ * Install (or refresh, or skip) the fallback pre-push hook at `targetDir`.
+ * Idempotent: safe to call on every `rea init`, including re-runs over an
+ * existing install. Never overwrites a foreign hook.
+ *
+ * Requires `targetDir/.git` to exist. Non-git directories are skipped with
+ * a warning — same shape as `installCommitMsgHook`.
+ */
+export declare function installPrePushFallback(targetDir: string, options?: InstallPrePushOptions): Promise<PrePushInstallResult>;
+/**
+ * Doctor check: at least one pre-push hook (Husky OR git fallback OR the
+ * configured hooksPath location) must exist AND be executable AND carry
+ * governance (rea marker or gate delegation). Returns a small record the
+ * doctor module can turn into a CheckResult.
+ *
+ * "Executable" is defined as having any of the user/group/other exec bits
+ * set, matching the existing `checkHooksInstalled` convention. A file that
+ * is executable but does not wire the Codex review gate is intentionally
+ * classified as non-governing: `ok=false` + `activeForeign=true`, which
+ * doctor turns into a `warn`, not a `pass`.
+ */
+export interface PrePushDoctorState {
+    /** Every candidate path we consulted, with its live status on disk. */
+    candidates: Array<{
+        path: string;
+        exists: boolean;
+        executable: boolean;
+        /** `true` when the file content carries our anchored rea prelude. */
+        reaManaged: boolean;
+        /** `true` when the body references the shared review gate. */
+        delegatesToGate: boolean;
+    }>;
+    /**
+     * The candidate path git would actually fire right now, given current
+     * `core.hooksPath`. May or may not exist.
+     */
+    activePath: string;
+    /**
+     * True when the active candidate exists, is executable, AND carries
+     * governance (rea marker OR references the review gate).
+     */
+    ok: boolean;
+    /**
+     * True when the active candidate exists + is executable but does NOT
+     * carry governance. This is the "silent bypass" case doctor surfaces as
+     * a warn. Distinct from `ok=false + absent` (which is a hard fail).
+     */
+    activeForeign: boolean;
+}
+export declare function inspectPrePushState(targetDir: string): Promise<PrePushDoctorState>;