@bookedsolid/rea 0.3.0 → 0.5.0

package/dist/cli/doctor.js

@@ -2,7 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { loadPolicy } from '../policy/loader.js';
 import { loadRegistry } from '../registry/loader.js';
+import { loadFingerprintStore } from '../registry/fingerprints-store.js';
+import { fingerprintServer } from '../registry/fingerprint.js';
 import { CodexProbe, } from '../gateway/observability/codex-probe.js';
+import { inspectPrePushState, } from './install/pre-push.js';
 import { summarizeTelemetry } from '../gateway/observability/codex-telemetry.js';
 import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFiles, } from './install/canonical.js';
 import { buildFragment } from './install/claude-md.js';
@@ -40,6 +43,69 @@ function checkPolicyParses(baseDir, policyPath) {
         };
     }
 }
+/**
+ * G7: report the TOFU fingerprint-store state. Pass = every enabled server
+ * in the registry has a matching stored fingerprint. Warn = at least one
+ * server would be first-seen or drifted at next `rea serve`. Info = no
+ * enabled servers (nothing to fingerprint). Fail only for unreadable store.
+ *
+ * Exported so tests can drive this without spinning up the full `runDoctor`.
+ */
+export async function checkFingerprintStore(baseDir) {
+    const label = 'fingerprint store';
+    let registry;
+    try {
+        registry = loadRegistry(baseDir);
+    }
+    catch {
+        return {
+            label,
+            status: 'info',
+            detail: 'registry missing — no fingerprints to compare',
+        };
+    }
+    const enabled = registry.servers.filter((s) => s.enabled);
+    if (enabled.length === 0) {
+        return { label, status: 'info', detail: 'no enabled servers to fingerprint' };
+    }
+    let store;
+    try {
+        store = await loadFingerprintStore(baseDir);
+    }
+    catch (e) {
+        return {
+            label,
+            status: 'fail',
+            detail: e instanceof Error ? e.message : String(e),
+        };
+    }
+    let firstSeen = 0;
+    let drifted = 0;
+    for (const s of enabled) {
+        const stored = store.servers[s.name];
+        if (stored === undefined)
+            firstSeen += 1;
+        else if (stored !== fingerprintServer(s))
+            drifted += 1;
+    }
+    if (firstSeen === 0 && drifted === 0) {
+        return {
+            label,
+            status: 'pass',
+            detail: `${enabled.length} server(s) trusted`,
+        };
+    }
+    const parts = [];
+    if (firstSeen > 0)
+        parts.push(`${firstSeen} first-seen`);
+    if (drifted > 0)
+        parts.push(`${drifted} drifted`);
+    return {
+        label,
+        status: 'warn',
+        detail: `${parts.join(', ')} — next \`rea serve\` will block drift (set REA_ACCEPT_DRIFT=<name> to accept)`,
+    };
+}
 function checkRegistryParses(baseDir, registryPath) {
     if (!fs.existsSync(registryPath)) {
         return {
@@ -198,6 +264,86 @@ function checkCommitMsgHook(baseDir) {
         };
     }
 }
+/**
+ * G6 — Verify at least one pre-push hook is installed and executable AND
+ * actually wires the protected-path review gate.
+ *
+ * Three install shapes are acceptable:
+ *   1. `.git/hooks/pre-push` — vanilla git (no hooksPath). Must carry the
+ *      rea fallback marker or delegate to `push-review-gate.sh`.
+ *   2. `${core.hooksPath}/pre-push` — husky 9 or custom hooksPath. Same
+ *      governance rule.
+ *   3. `.husky/pre-push` is present on disk but only counts if husky has
+ *      configured `core.hooksPath=.husky`. A `.husky/pre-push` with an
+ *      unconfigured hooksPath is dead weight; we do NOT treat it as
+ *      sufficient.
+ *
+ * Two possible outcomes:
+ *   - `pass`: active hook exists, is executable, and governance-carrying
+ *     (rea-managed marker or direct gate delegation).
+ *   - `fail`: no active hook, active file is non-executable, OR the active
+ *     hook does not reference `.claude/hooks/push-review-gate.sh`. The last
+ *     case is the "silent bypass" state — a lint-only husky hook or a
+ *     pre-existing repo hook that bypasses the Codex audit gate entirely.
+ *     Always a hard fail; `rea init` can install the fallback if the user
+ *     removes or updates the existing hook.
+ *
+ * "Executable" is defined by any user/group/other exec bit, matching
+ * `checkHooksInstalled`.
+ */
+function checkPrePushHook(state) {
+    if (state.ok) {
+        const active = state.candidates.find((c) => c.path === state.activePath);
+        const kind = active?.reaManaged === true
+            ? 'rea-managed'
+            : active?.delegatesToGate === true
+                ? 'external (delegates to push-review-gate.sh)'
+                : 'external';
+        const detail = active !== undefined ? `${kind} at ${active.path}` : undefined;
+        return detail !== undefined
+            ? { label: 'pre-push hook installed', status: 'pass', detail }
+            : { label: 'pre-push hook installed', status: 'pass' };
+    }
+    if (state.activeForeign) {
+        // Executable file exists at the active path but does not carry
+        // governance — the parser could not confirm the review gate is
+        // invoked unconditionally. Always a hard fail.
+        //
+        // R13 F3: previously, a substring match of the gate path in the hook
+        // downgraded this to WARN. That was unsafe — any comment, echo, or
+        // dead string mentioning the path would mask a silent-bypass hook.
+        // The classifier now fails closed: either the structural parser
+        // (`referencesReviewGate` in `pre-push.ts`) recognizes a real
+        // invocation, or doctor reports fail.
+        return {
+            label: 'pre-push hook installed',
+            status: 'fail',
+            detail: `active pre-push at ${state.activePath} is present and executable but does NOT ` +
+                `reference \`.claude/hooks/push-review-gate.sh\` — the protected-path ` +
+                `Codex audit gate is silently bypassed. Either add ` +
+                '`exec .claude/hooks/push-review-gate.sh "$@"` to the existing hook, or ' +
+                'remove it and re-run `rea init` to install the fallback.',
+        };
+    }
+    const present = state.candidates
+        .filter((c) => c.exists)
+        .map((c) => `${c.path}${c.executable ? '' : ' (not executable)'}`);
+    if (present.length > 0) {
+        return {
+            label: 'pre-push hook installed',
+            status: 'fail',
+            detail: `no active pre-push hook. Files on disk: ${present.join(', ')}. ` +
+                'Run `rea init` to install the fallback, or configure `core.hooksPath=.husky` ' +
+                'if you are using husky.',
+        };
+    }
+    return {
+        label: 'pre-push hook installed',
+        status: 'fail',
+        detail: 'no pre-push hook found in `.git/hooks/`, configured `core.hooksPath`, or `.husky/`. ' +
+            'Run `rea init` to install the fallback.',
+    };
+}
 function checkCodexAgent(baseDir) {
     const agentPath = path.join(baseDir, '.claude', 'agents', 'codex-adversarial.md');
     if (fs.existsSync(agentPath))
@@ -277,11 +423,16 @@ function codexRequiredFromPolicy(baseDir) {
  * `runDoctor`.
  *
  * `codexProbeState` is consulted ONLY when Codex is required by policy.
- * Callers that already have a fresh probe state (e.g. `runDoctor`) should
- * pass it; callers that don't (e.g. unit tests of the existing doctor
- * surface) can omit it and the probe-derived fields are skipped.
+ * `prePushState` is the pre-computed G6 pre-push inspection; when omitted
+ * the pre-push check is skipped entirely (older call sites that don't yet
+ * thread the state through keep working without behavioural change).
+ * Callers that already have fresh state (e.g. `runDoctor`) should pass
+ * both; callers that don't (e.g. unit tests of the existing doctor
+ * surface) can omit them and those checks are skipped.
+ *
+ * `activeForeign` always yields `fail` — a foreign hook bypassing the gate is a hard governance gap.
  */
-export function collectChecks(baseDir, codexProbeState) {
+export function collectChecks(baseDir, codexProbeState, prePushState) {
     const policyPath = reaPath(baseDir, POLICY_FILE);
     const registryPath = reaPath(baseDir, REGISTRY_FILE);
     const reaDirPath = path.join(baseDir, REA_DIR);
@@ -294,6 +445,9 @@ export function collectChecks(baseDir, codexProbeState) {
         checkSettingsJson(baseDir),
         checkCommitMsgHook(baseDir),
     ];
+    if (prePushState !== undefined) {
+        checks.push(checkPrePushHook(prePushState));
+    }
     if (codexRequiredFromPolicy(baseDir)) {
         checks.push(checkCodexAgent(baseDir), checkCodexCommand(baseDir));
         if (codexProbeState !== undefined) {
@@ -486,7 +640,20 @@ export async function runDoctor(opts = {}) {
             probeState = undefined;
         }
     }
-    const checks = collectChecks(baseDir, probeState);
+    // G6 — inspect pre-push state. Never throws; unreadable files downgrade
+    // individual candidates but never break the whole check.
+    let prePushState;
+    try {
+        prePushState = await inspectPrePushState(baseDir);
+    }
+    catch {
+        prePushState = undefined;
+    }
+    const checks = collectChecks(baseDir, probeState, prePushState);
+    // G7: async fingerprint-store check. Kept out of `collectChecks` so the
+    // existing sync contract stays intact for downstream consumers; appended
+    // here so runDoctor surfaces it inline.
+    checks.push(await checkFingerprintStore(baseDir));
     console.log('');
     log(`Doctor — ${baseDir}`);
     console.log('');

package/dist/cli/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { runAuditRotate, runAuditVerify } from './audit.js';
+import { parseCacheResult, runCacheCheck, runCacheClear, runCacheList, runCacheSet, } from './cache.js';
 import { runCheck } from './check.js';
 import { runDoctor } from './doctor.js';
 import { runFreeze, runUnfreeze } from './freeze.js';
 import { runInit } from './init.js';
 import { runServe } from './serve.js';
+import { runStatus } from './status.js';
 import { runUpgrade } from './upgrade.js';
 import { err, getPkgVersion } from './utils.js';
 async function main() {
@@ -53,7 +55,7 @@ async function main() {
     });
     program
         .command('serve')
-        .description('Start the MCP gateway (stub — prints status, verifies policy loads).')
+        .description('Start the MCP gateway — stdio server that proxies downstream MCPs declared in .rea/registry.yaml through the middleware chain.')
         .action(async () => {
         await runServe();
     });
@@ -77,6 +79,13 @@ async function main() {
         .action(() => {
         runCheck();
     });
+    program
+        .command('status')
+        .description('Running-process view — is `rea serve` live for this project? Session id, policy summary, audit stats. Use `rea check` for the on-disk view.')
+        .option('--json', 'emit JSON instead of the pretty table (composes with jq)')
+        .action((opts) => {
+        runStatus({ json: opts.json });
+    });
     const audit = program
         .command('audit')
         .description('Audit log operations — rotate and verify .rea/audit.jsonl (G1).');
@@ -93,6 +102,46 @@ async function main() {
         .action(async (opts) => {
         await runAuditVerify({ ...(opts.since !== undefined ? { since: opts.since } : {}) });
     });
+    const cache = program
+        .command('cache')
+        .description('Review-cache operations — check/set/clear/list .rea/review-cache.jsonl (BUG-009). Used by hooks/push-review-gate.sh to skip re-review on a previously-approved diff.');
+    cache
+        .command('check <sha>')
+        .description('Look up a cache entry. Emits JSON to stdout ONLY — hook contract. On hit: {hit,true,result,branch,base,recorded_at[,reason]}. On miss: {hit:false}. Never exits non-zero for normal miss.')
+        .requiredOption('--branch <branch>', 'feature branch being pushed')
+        .requiredOption('--base <base>', 'base branch the feature targets')
+        .action(async (sha, opts) => {
+        await runCacheCheck({ sha, branch: opts.branch, base: opts.base });
+    });
+    cache
+        .command('set <sha> <result>')
+        .description('Record a review outcome. <result> must be "pass" or "fail". Idempotent line-per-invocation; last write wins on (sha, branch, base).')
+        .requiredOption('--branch <branch>', 'feature branch being pushed')
+        .requiredOption('--base <base>', 'base branch the feature targets')
+        .option('--reason <text>', 'free-text context for this entry (recommended on fail)')
+        .action(async (sha, rawResult, opts) => {
+        const result = parseCacheResult(rawResult);
+        await runCacheSet({
+            sha,
+            result,
+            branch: opts.branch,
+            base: opts.base,
+            ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+        });
+    });
+    cache
+        .command('clear <sha>')
+        .description('Remove every cache entry matching <sha>. Dev convenience — prints the removed count.')
+        .action(async (sha) => {
+        await runCacheClear({ sha });
+    });
+    cache
+        .command('list')
+        .description('Print cache entries in file order. Filter with --branch.')
+        .option('--branch <branch>', 'only list entries for this branch')
+        .action(async (opts) => {
+        await runCacheList({ ...(opts.branch !== undefined ? { branch: opts.branch } : {}) });
+    });
     program
         .command('doctor')
         .description('Validate the install: policy parses, .rea/ layout, hooks, Codex plugin.')

package/dist/cli/init.js

@@ -5,8 +5,11 @@ import * as p from '@clack/prompts';
 import { AutonomyLevel } from '../policy/types.js';
 import { HARD_DEFAULTS, loadProfile, mergeProfiles } from '../policy/profiles.js';
 import { copyArtifacts } from './install/copy.js';
+import { ensureReaGitignore } from './install/gitignore.js';
 import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
 import { installCommitMsgHook } from './install/commit-msg.js';
+import { installPrePushFallback } from './install/pre-push.js';
+import { CodexProbe } from '../gateway/observability/codex-probe.js';
 import { buildFragment, writeClaudeMdFragment } from './install/claude-md.js';
 import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFiles, } from './install/canonical.js';
 import { writeManifestAtomic } from './install/manifest-io.js';
@@ -188,6 +191,48 @@ async function runWizard(options, targetDir, reagentPolicyPath, layeredBase) {
         reagentNotices: [],
     };
 }
+/**
+ * G6 — Codex install-assist probe.
+ *
+ * Runs a single {@link CodexProbe} attempt and prints a guidance block when
+ * the CLI is NOT responsive. Behavior:
+ *
+ *   - `cli_responsive === true`  → print a single-line "Codex CLI detected"
+ *     acknowledgement (informational, not verbose).
+ *   - `cli_responsive === false` → print a 4-line install guidance block
+ *     naming the Claude Code helper that installs Codex.
+ *
+ * Failure of the probe itself is never fatal — a hung CLI must not stall
+ * `rea init`. The probe class already caps each subcommand at 2s/5s. Any
+ * throw bubbling out here is caught and treated as "not responsive".
+ *
+ * We deliberately reference the user-visible helper path (`/codex:setup`)
+ * rather than shelling out to install Codex ourselves. `rea init` does not
+ * auto-install third-party tooling; the operator signs off.
+ */
+async function printCodexInstallAssist() {
+    let responsive = false;
+    let versionLine;
+    try {
+        const state = await new CodexProbe().probe();
+        responsive = state.cli_responsive;
+        versionLine = state.version;
+    }
+    catch {
+        // probe() is documented as never-throws, but belt-and-suspenders.
+        responsive = false;
+    }
+    console.log('');
+    if (responsive) {
+        const suffix = versionLine !== undefined ? ` (${versionLine})` : '';
+        console.log(`Codex CLI detected${suffix}.`);
+        return;
+    }
+    console.log('Codex CLI not detected on PATH.');
+    console.log('  Adversarial review via `/codex-review` requires the Codex plugin.');
+    console.log('  Install via the Claude Code Codex plugin helper: `/codex:setup`,');
+    console.log('  or set `review.codex_required: false` in .rea/policy.yaml to opt out.');
+}
 function writePolicyYaml(targetDir, config, layered) {
     const policyPath = path.join(targetDir, REA_DIR, POLICY_FILE);
     const installedBy = process.env.USER ?? os.userInfo().username ?? 'unknown';
@@ -213,6 +258,14 @@ function writePolicyYaml(targetDir, config, layered) {
     if (layered.injection_detection !== undefined) {
         lines.push(`injection_detection: ${layered.injection_detection}`);
     }
+    // G9: preserve `injection.suspicious_blocks_writes` when the layered profile
+    // pinned it (bst-internal/bst-internal-no-codex pin `true`). External profiles
+    // leave this unset so the policy loader's schema default (`false`) applies,
+    // which keeps 0.2.x consumers from being silently tightened on upgrade.
+    if (layered.injection?.suspicious_blocks_writes !== undefined) {
+        lines.push(`injection:`);
+        lines.push(`  suspicious_blocks_writes: ${layered.injection.suspicious_blocks_writes ? 'true' : 'false'}`);
+    }
     if (layered.context_protection !== undefined) {
         lines.push(`context_protection:`);
         const cp = layered.context_protection;
@@ -243,6 +296,21 @@ function writeRegistryYaml(targetDir) {
     const content = [
         `# .rea/registry.yaml — downstream MCP servers proxied through rea serve.`,
         `# Every entry below is subject to the same middleware chain as native tool calls.`,
+        `#`,
+        `# env: values support \${VAR} interpolation against rea-serve's own process.env.`,
+        `# If a referenced var is unset at startup, the affected server fails to start`,
+        `# (the rest of the gateway still comes up). Only the curly-brace form is`,
+        `# supported — no $VAR, no defaults, no command substitution.`,
+        `#`,
+        `# Example (uncomment and export the vars in your shell before running \`rea serve\`):`,
+        `#`,
+        `#   - name: discord-ops`,
+        `#     command: npx`,
+        `#     args: ['-y', 'discord-ops@latest']`,
+        `#     env:`,
+        `#       BOOKED_DISCORD_BOT_TOKEN: '\${BOOKED_DISCORD_BOT_TOKEN}'`,
+        `#       CLARITY_DISCORD_BOT_TOKEN: '\${CLARITY_DISCORD_BOT_TOKEN}'`,
+        `#     enabled: false  # flip to true after exporting the tokens`,
         `version: "1"`,
         `servers: []`,
         ``,
@@ -387,6 +455,7 @@ export async function runInit(options) {
     const mergeResult = mergeSettings(settings, desired);
     await writeSettingsAtomic(settingsPath, mergeResult.merged);
     const commitMsgResult = await installCommitMsgHook(targetDir);
+    const prePushResult = await installPrePushFallback(targetDir);
     const fragmentInput = {
         policyPath: `.${path.sep}rea${path.sep}policy.yaml`.replace(/\\/g, '/'),
         profile: config.profile,
@@ -396,6 +465,10 @@ export async function runInit(options) {
         blockAiAttribution: config.blockAiAttribution,
     };
     const mdResult = await writeClaudeMdFragment(targetDir, fragmentInput);
+    // BUG-010 — scaffold `.gitignore` entries for every runtime artifact
+    // `rea serve` / `rea cache` / `/freeze` can write under `.rea/`. Idempotent
+    // append (and `rea upgrade` backfills older installs that never got this).
+    const gitignoreResult = await ensureReaGitignore(targetDir);
     // G12 — record the install manifest. SHAs are of the files actually on disk
     // after the copy pass, so drift detection compares against real state (not
     // canonical, which may differ if the consumer's copy was aborted mid-run).
@@ -410,7 +483,26 @@ export async function runInit(options) {
         console.log(`  + ${path.relative(targetDir, commitMsgResult.gitHook)}`);
     if (commitMsgResult.huskyHook)
         console.log(`  + ${path.relative(targetDir, commitMsgResult.huskyHook)}`);
+    if (prePushResult.written !== undefined) {
+        const verb = prePushResult.decision.action === 'refresh' ? '~' : '+';
+        console.log(`  ${verb} ${path.relative(targetDir, prePushResult.written)} (pre-push fallback)`);
+    }
+    else if (prePushResult.decision.action === 'skip' &&
+        prePushResult.decision.reason === 'active-pre-push-present') {
+        console.log(`  = ${path.relative(targetDir, prePushResult.decision.hookPath)} (active pre-push already present — skipped fallback)`);
+    }
     console.log(`  ${mdResult.replaced ? '~' : '+'} ${path.relative(targetDir, mdResult.path)} (fragment ${mdResult.replaced ? 'replaced' : 'written'})`);
+    if (gitignoreResult.action === 'created') {
+        console.log(`  + ${path.relative(targetDir, gitignoreResult.path)} (managed block written)`);
+    }
+    else if (gitignoreResult.action === 'updated') {
+        console.log(`  ~ ${path.relative(targetDir, gitignoreResult.path)} (managed block ${gitignoreResult.addedEntries.length} entr${gitignoreResult.addedEntries.length === 1 ? 'y' : 'ies'} added)`);
+    }
+    else {
+        console.log(`  · ${path.relative(targetDir, gitignoreResult.path)} (managed block up to date)`);
+    }
+    for (const w of gitignoreResult.warnings)
+        warn(w);
     console.log(`  + ${path.relative(targetDir, manifestPath)}`);
     if (mergeResult.warnings.length > 0) {
         console.log('');
@@ -419,15 +511,25 @@ export async function runInit(options) {
     }
     for (const w of commitMsgResult.warnings)
         warn(w);
+    for (const w of prePushResult.warnings)
+        warn(w);
     for (const n of config.reagentNotices)
         warn(n);
-    // G11.4: when Codex review is disabled, print a durable notice. Mentions
-    // the exact edit path so the operator can flip back later without having
-    // to re-run init. (Coupling note: a future G6-style "Codex install
-    // assist" prompt belongs here too, and should short-circuit when
-    // codex_required is false — do not invoke install-assist in no-codex
-    // mode.)
-    if (!config.codexRequired) {
+    // G6 + G11.4: Codex install-assist.
+    //
+    // Split by codex_required:
+    //   - codex_required=true  → probe the CLI; if it is not responsive, print
+    //                            a clear "install Codex" guidance block so the
+    //                            operator knows why /codex-review will fail.
+    //   - codex_required=false → skip the probe entirely and print the
+    //                            existing "Codex review disabled" notice.
+    //                            Probing here is pointless (wasted 2s) and
+    //                            actively confusing — no-codex mode is a
+    //                            supported first-class configuration.
+    if (config.codexRequired) {
+        await printCodexInstallAssist();
+    }
+    else {
         console.log('');
         console.log('Codex review disabled. ClaudeSelfReviewer will be used.');
         console.log('  Set review.codex_required: true in .rea/policy.yaml to re-enable.');

package/dist/cli/install/gitignore.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ */
+export declare const GITIGNORE_BLOCK_START = "# === rea managed \u2014 do not edit between markers ===";
+export declare 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 declare const REA_GITIGNORE_ENTRIES: readonly string[];
+export interface EnsureGitignoreResult {
+    /** Absolute path to the `.gitignore` file that was (maybe) written. */
+    path: string;
+    /** `created` = no file before. `updated` = block added or amended. `unchanged` = no-op. */
+    action: 'created' | 'updated' | 'unchanged';
+    /** Entries the caller added this run (subset of `REA_GITIGNORE_ENTRIES`). */
+    addedEntries: string[];
+    /** Non-fatal operator-facing messages (e.g. symlink refused, duplicate blocks). */
+    warnings: string[];
+}
+/**
+ * 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 declare function ensureReaGitignore(targetDir: string, entries?: readonly string[]): Promise<EnsureGitignoreResult>;