@bookedsolid/rea 0.4.0 → 0.6.0

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 #!/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';
@@ -101,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,6 +5,7 @@ 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';
@@ -464,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).
@@ -487,6 +492,17 @@ export async function runInit(options) {
         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('');

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>;

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/upgrade.js

@@ -45,6 +45,7 @@ import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFile
 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 { 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';
@@ -475,6 +476,25 @@ export async function runUpgrade(options = {}) {
             source: 'claude-md',
         });
     }
+    // BUG-010 — ensure `.gitignore` carries every runtime artifact entry. This
+    // backfills older installs that predate the scaffolding in `rea init`. A
+    // consumer who upgraded from 0.3.x/0.4.0 was previously seeing
+    // `.rea/fingerprints.json` show up as an untracked file; this closes the
+    // loop without touching operator-authored gitignore lines.
+    if (!dryRun) {
+        const gi = await ensureReaGitignore(resolvedRoot);
+        if (gi.action === 'created') {
+            console.log(`  + ${path.relative(resolvedRoot, gi.path)} (managed block written)`);
+        }
+        else if (gi.action === 'updated') {
+            console.log(`  ~ ${path.relative(resolvedRoot, gi.path)} (managed block ${gi.addedEntries.length} entr${gi.addedEntries.length === 1 ? 'y' : 'ies'} added)`);
+        }
+        else {
+            console.log(`  · ${path.relative(resolvedRoot, gi.path)} (managed block up to date)`);
+        }
+        for (const w of gi.warnings)
+            warn(w);
+    }
     if (dryRun) {
         console.log('');
         log('dry run — no changes written.');

package/dist/gateway/downstream-pool.d.ts

@@ -14,8 +14,36 @@ export interface PrefixedTool extends DownstreamToolInfo {
     /** Full prefixed name, as exposed to the upstream client. */
     name: string;
 }
+/**
+ * Per-downstream state surfaced by the `__rea__health` meta-tool. Kept
+ * separate from the richer internal state so we only expose what a caller
+ * can actually reason about.
+ */
+export interface DownstreamHealth {
+    name: string;
+    /** Registered in the registry (always true for entries present in the pool). */
+    enabled: boolean;
+    /** Underlying MCP client currently connected. */
+    connected: boolean;
+    /** Gateway considers this downstream healthy enough to route calls to. */
+    healthy: boolean;
+    /** Last error observed, or null if the connection is clean or never errored. */
+    last_error: string | null;
+    /**
+     * Number of tools advertised by the downstream on the most recent
+     * successful `tools/list`, or null when never listed / listing failed.
+     */
+    tools_count: number | null;
+}
 export declare class DownstreamPool {
     private readonly connections;
+    /**
+     * Cached tool counts from the most recent successful `listAllTools` cycle,
+     * keyed by server name. Surfaced via `healthSnapshot()` so the meta-tool
+     * can report per-server counts even when the current listing pass fails
+     * or is skipped. Stale but truthful > absent.
+     */
+    private readonly lastToolsCount;
     constructor(registry: Registry, logger?: Logger);
     get size(): number;
     connectAll(): Promise<void>;
@@ -25,6 +53,12 @@ export declare class DownstreamPool {
      * will see a smaller catalog rather than a crash.
      */
     listAllTools(): Promise<PrefixedTool[]>;
+    /**
+     * Snapshot per-server connection state for the `__rea__health` meta-tool.
+     * Pure / non-blocking — no MCP I/O — so it can be called while HALT is
+     * active or while other tool calls are in-flight.
+     */
+    healthSnapshot(): DownstreamHealth[];
     /**
      * Split a prefixed tool name and dispatch. Returns the raw result from the
      * downstream (the gateway response handler shapes it for the upstream reply).