@bookedsolid/rea 0.3.0 → 0.5.0

package/.husky/pre-push

@@ -1,4 +1,6 @@
 #!/bin/sh
+# rea:husky-pre-push-gate v1
+# rea:gate-body-v1
 # .husky/pre-push — rea governance gate for terminal-initiated pushes.
 #
 # Mirrors the logic of `.claude/hooks/push-review-gate.sh` but consumes the
@@ -20,8 +22,10 @@
 # which ran the loop in a subshell — `exit 1` inside the loop aborted the
 # subshell only, and the script then ran `exit 0` and allowed the push. We
 # now feed the loop with a here-doc so it runs in the main shell, and we
-# track `block_push` in the enclosing scope. Final `exit 1` is reached only
-# if no refspec is blocked; a single blocking refspec propagates correctly.
+# abort immediately (`exit 1`) on the first blocking refspec. The accumulator
+# pattern (`block_push=1; continue`) was dropped so the text-level detector
+# in `src/cli/install/pre-push.ts` can verify the miss-path is truly blocking
+# without modeling loop-carried flags and post-loop exit blocks.
 
 set -eu
 
@@ -63,13 +67,11 @@ if [ -f "$READ_FIELD_JS" ]; then
   fi
 fi
 
-block_push=0
-
-# Here-doc feeds the loop without creating a subshell, so `block_push=1`
-# assignments below persist in the enclosing scope and the final `exit`
-# reflects them. A pipeline would run the loop in a subshell and `exit 1`
-# inside it would only abort that subshell — NOT the push — which was a
-# real governance defect in the pre-review version of this file.
+# Here-doc feeds the loop without creating a subshell, so an `exit 1`
+# inside the loop terminates the hook and blocks the push. A pipeline
+# would run the loop in a subshell and `exit 1` inside it would only
+# abort that subshell — NOT the push — which was a real governance
+# defect in the pre-review version of this file.
 while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
   [ -z "${local_sha:-}" ] && continue
   # Branch deletion: local_sha is 40 zeros. Skip protected-path check.
@@ -103,26 +105,21 @@ while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
     if [ ! -f "$AUDIT_LOG" ]; then
       printf 'PUSH BLOCKED: protected paths changed but no audit log found at %s\n' "$AUDIT_LOG" >&2
       printf '  Run /codex-review on HEAD %s before pushing.\n' "$local_sha" >&2
-      block_push=1
-      continue
+      exit 1
     fi
     # Require both (a) a `codex.review` tool_name and (b) the exact head_sha
     # on the same JSONL line. The `codex.review` pattern ends with a closing
-    # quote, so `codex.review.skipped` never satisfies the gate.
+    # quote, so `codex.review.skipped` never satisfies the gate. The first
+    # refspec that fails this check aborts the hook — no accumulator needed.
     if ! grep -E '"tool_name":"codex\.review"' "$AUDIT_LOG" 2>/dev/null | \
          grep -qF "\"head_sha\":\"$local_sha\""; then
       printf 'PUSH BLOCKED: protected paths changed — /codex-review required for HEAD %s\n' "$local_sha" >&2
       printf '  Run /codex-review, or set REA_SKIP_CODEX_REVIEW=<reason> to bypass.\n' >&2
-      block_push=1
-      continue
+      exit 1
     fi
   fi
 done <<HOOK_INPUT_EOF
 $INPUT
 HOOK_INPUT_EOF
 
-if [ "$block_push" -ne 0 ]; then
-  exit 1
-fi
-
 exit 0

package/README.md

@@ -66,7 +66,10 @@ to build a separate package that composes with REA.
   `policy.yaml` is the maximum surface area — one outbound POST, opt-in.
 - **Not a daemon supervisor.** `rea serve` is started by Claude Code via
   `.mcp.json`. Claude Code owns the lifecycle. There is no `rea start`,
-  no `rea stop`, no pid file, no systemd unit.
+  no `rea stop`, no systemd unit. A short-lived `.rea/serve.pid`
+  breadcrumb is written at startup so `rea status` can detect a live
+  gateway — it is removed on graceful shutdown and never used for
+  locking or lifecycle management.
 - **Not a hosted service.** There is no REA Cloud, no SaaS tier, no
   multi-token workstreams, no workload isolation platform.
 - **Not a 70-agent roster.** 10 curated agents ship in the package. Four
@@ -132,6 +135,43 @@ install, `.mcp.json` gateway wiring, Codex plugin availability, and the
 integrity of the audit hash chain. It returns a pass/fail summary with
 specific remediation hints.
 
+### 4. Watch the running gateway
+
+```bash
+rea status              # human-readable summary
+rea status --json       # JSON — pipe to jq
+```
+
+`rea status` is the live-process view. It reads the pidfile written by
+`rea serve`, verifies the pid is alive, and surfaces the session id,
+policy summary (profile, autonomy, HALT state), and audit stats (lines,
+last timestamp, whether the tail record's hash looks well-formed). Use
+`rea check` when you want the pure on-disk view without probing for a
+live process.
+
+### 5. Optional Prometheus `/metrics` endpoint
+
+`rea serve` can expose a loopback-only Prometheus endpoint when the
+`REA_METRICS_PORT` environment variable is set:
+
+```bash
+REA_METRICS_PORT=9464 rea serve
+# in another shell
+curl http://127.0.0.1:9464/metrics
+```
+
+Metrics exposed: per-downstream call and error counters, in-flight
+gauge, audit-lines-appended counter, circuit-breaker state gauge, and a
+seconds-since-last-HALT-check gauge. The listener binds to `127.0.0.1`
+only, serves only `GET /metrics` (everything else is a fixed-body 404),
+and never binds by default — "no silent listeners" is a design rule.
+There is no TLS; scrape through SSH/a reverse proxy if you need
+cross-host access.
+
+Set `REA_LOG_LEVEL=debug` for verbose gateway logs; the default is
+`info`. Records are JSON lines on a non-TTY stderr and pretty-printed
+on an interactive terminal.
+
 ## Architecture
 
 ### Middleware chain

package/dist/cache/review-cache.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Review cache (BUG-009). The push-review-gate hook (`hooks/push-review-gate.sh`)
+ * has shipped since 0.3.x calling `rea cache check <sha>` to skip re-review on
+ * a previously-approved diff, and `rea cache set <sha> pass ...` as the
+ * operator's advertised way to complete the gate. Neither subcommand existed
+ * in the CLI through 0.4.0. Once BUG-008's pre-push stdin adapter lands and
+ * the gate actually fires, a protected-path push has no completion path
+ * without this cache — hence "paired ship blocker."
+ *
+ * ## File layout
+ *
+ * `.rea/review-cache.jsonl` — one JSON object per line, terminated with `\n`.
+ * Each entry:
+ *
+ *   {
+ *     "sha": "<diff-sha256>",
+ *     "branch": "<feature-branch>",
+ *     "base": "<target-branch>",
+ *     "result": "pass" | "fail",
+ *     "recorded_at": "<ISO-8601>",
+ *     "reason"?: "<free text>"   // optional, populated on fail or on skip
+ *   }
+ *
+ * The `sha` is whatever the caller supplies — the hook happens to use a
+ * SHA-256 of the full diff, but the cache does not interpret or validate the
+ * value. Hash-chained is intentionally NOT required: this is a keyed cache,
+ * not an append-only integrity log. The audit log at `.rea/audit.jsonl`
+ * remains the integrity story.
+ *
+ * ## Concurrency
+ *
+ * Every write takes the same `proper-lockfile` lock on the `.rea/` parent
+ * directory that the audit helpers use (`withAuditLock`). This means a
+ * concurrent audit append and cache write serialize against each other — a
+ * negligible cost given cache writes happen once per push gate completion.
+ *
+ * ## Idempotency
+ *
+ * `appendEntry` writes a new line unconditionally. `lookup` returns the most
+ * recent entry matching `(sha, branch, base)`. This "last write wins" keeps
+ * the write path O(1) and the read path O(n) over the file; n is bounded by
+ * typical review frequency (dozens per week, not millions). If a future
+ * operator needs a compact file, `rea cache clear <sha>` drops matching
+ * entries and a separate `rea cache compact` (not in 0.5.0) could rewrite.
+ *
+ * ## TTL
+ *
+ * `lookup` honors `review.cache_max_age_seconds` (default 3600). Entries
+ * older than the window are treated as a miss. Expired entries are not
+ * garbage-collected on read — `rea cache clear` or `rea cache compact`
+ * is the operator tool for shrinking.
+ */
+/** Default TTL when policy does not supply one. */
+export declare const DEFAULT_CACHE_MAX_AGE_SECONDS = 3600;
+export type CacheResult = 'pass' | 'fail';
+export interface CacheEntry {
+    sha: string;
+    branch: string;
+    base: string;
+    result: CacheResult;
+    recorded_at: string;
+    reason?: string;
+}
+export interface CacheLookupInput {
+    sha: string;
+    branch: string;
+    base: string;
+    /** Epoch ms used as the "now" reference for TTL comparison. Defaults to `Date.now()`. */
+    nowMs?: number;
+    /** TTL in seconds; defaults to {@link DEFAULT_CACHE_MAX_AGE_SECONDS}. */
+    maxAgeSeconds?: number;
+}
+export interface CacheLookupResult {
+    hit: boolean;
+    entry?: CacheEntry;
+    /** Reason for a miss. One of `'no-entry' | 'expired' | 'empty-file'`. Always set when `hit === false`. */
+    missReason?: 'no-entry' | 'expired' | 'empty-file';
+}
+export interface CacheAppendInput {
+    sha: string;
+    branch: string;
+    base: string;
+    result: CacheResult;
+    reason?: string;
+    /** ISO-8601 timestamp. Defaults to `new Date().toISOString()`. */
+    timestamp?: string;
+}
+export declare function resolveCacheFile(baseDir: string): string;
+/**
+ * Append an entry to the cache. Writes are serialized through the shared
+ * `.rea/` directory lock so audit writes and cache writes do not interleave.
+ */
+export declare function appendEntry(baseDir: string, input: CacheAppendInput): Promise<CacheEntry>;
+/**
+ * Find the most-recent entry matching `(sha, branch, base)` within the TTL
+ * window. Idempotent and side-effect free.
+ */
+export declare function lookup(baseDir: string, input: CacheLookupInput): Promise<CacheLookupResult>;
+/**
+ * Remove every entry matching `sha`. Returns the count removed. A `0` return
+ * is a valid outcome (sha not present). Writes back via the same lock as
+ * `appendEntry`, so concurrent sets do not lose entries.
+ *
+ * Writes use temp-file + `fs.rename` (atomic within a single directory on
+ * POSIX) so unlocked readers (`lookup`, `list`) can never observe a torn or
+ * empty intermediate state. Codex F4 on the 0.5.0 PR1 review.
+ */
+export declare function clear(baseDir: string, sha: string): Promise<number>;
+/**
+ * Return every entry, optionally filtered by branch. Entries are returned in
+ * file order (oldest first). Callers that want "newest first" should reverse.
+ */
+export declare function list(baseDir: string, options?: {
+    branch?: string;
+}): Promise<CacheEntry[]>;

package/dist/cache/review-cache.js

@@ -0,0 +1,200 @@
+/**
+ * Review cache (BUG-009). The push-review-gate hook (`hooks/push-review-gate.sh`)
+ * has shipped since 0.3.x calling `rea cache check <sha>` to skip re-review on
+ * a previously-approved diff, and `rea cache set <sha> pass ...` as the
+ * operator's advertised way to complete the gate. Neither subcommand existed
+ * in the CLI through 0.4.0. Once BUG-008's pre-push stdin adapter lands and
+ * the gate actually fires, a protected-path push has no completion path
+ * without this cache — hence "paired ship blocker."
+ *
+ * ## File layout
+ *
+ * `.rea/review-cache.jsonl` — one JSON object per line, terminated with `\n`.
+ * Each entry:
+ *
+ *   {
+ *     "sha": "<diff-sha256>",
+ *     "branch": "<feature-branch>",
+ *     "base": "<target-branch>",
+ *     "result": "pass" | "fail",
+ *     "recorded_at": "<ISO-8601>",
+ *     "reason"?: "<free text>"   // optional, populated on fail or on skip
+ *   }
+ *
+ * The `sha` is whatever the caller supplies — the hook happens to use a
+ * SHA-256 of the full diff, but the cache does not interpret or validate the
+ * value. Hash-chained is intentionally NOT required: this is a keyed cache,
+ * not an append-only integrity log. The audit log at `.rea/audit.jsonl`
+ * remains the integrity story.
+ *
+ * ## Concurrency
+ *
+ * Every write takes the same `proper-lockfile` lock on the `.rea/` parent
+ * directory that the audit helpers use (`withAuditLock`). This means a
+ * concurrent audit append and cache write serialize against each other — a
+ * negligible cost given cache writes happen once per push gate completion.
+ *
+ * ## Idempotency
+ *
+ * `appendEntry` writes a new line unconditionally. `lookup` returns the most
+ * recent entry matching `(sha, branch, base)`. This "last write wins" keeps
+ * the write path O(1) and the read path O(n) over the file; n is bounded by
+ * typical review frequency (dozens per week, not millions). If a future
+ * operator needs a compact file, `rea cache clear <sha>` drops matching
+ * entries and a separate `rea cache compact` (not in 0.5.0) could rewrite.
+ *
+ * ## TTL
+ *
+ * `lookup` honors `review.cache_max_age_seconds` (default 3600). Entries
+ * older than the window are treated as a miss. Expired entries are not
+ * garbage-collected on read — `rea cache clear` or `rea cache compact`
+ * is the operator tool for shrinking.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { withAuditLock } from '../audit/fs.js';
+/** Default TTL when policy does not supply one. */
+export const DEFAULT_CACHE_MAX_AGE_SECONDS = 3600;
+/**
+ * Tolerated clock skew for future-dated entries. A `recorded_at` more than
+ * this far in the future relative to `nowMs` is treated as tampered or
+ * severely-drifted and forces a miss (re-review). 60s covers NTP jitter on
+ * well-synced hosts; anything beyond that is noise we do not trust.
+ */
+const FUTURE_SKEW_ALLOWANCE_MS = 60_000;
+const CACHE_FILENAME = 'review-cache.jsonl';
+const REA_DIRNAME = '.rea';
+export function resolveCacheFile(baseDir) {
+    return path.join(baseDir, REA_DIRNAME, CACHE_FILENAME);
+}
+/**
+ * Load every entry from the cache file. Returns `[]` when the file does not
+ * exist or is empty. Malformed lines are skipped — we never throw on a
+ * corrupt line, because the cache is advisory and a bad write (e.g. a
+ * half-written line from a crashed host) must not block a subsequent push.
+ */
+async function loadEntries(cacheFile) {
+    let raw;
+    try {
+        raw = await fs.readFile(cacheFile, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    if (raw.length === 0)
+        return [];
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.sha === 'string' &&
+                typeof parsed.branch === 'string' &&
+                typeof parsed.base === 'string' &&
+                (parsed.result === 'pass' || parsed.result === 'fail') &&
+                typeof parsed.recorded_at === 'string') {
+                entries.push(parsed);
+            }
+        }
+        catch {
+            // Skip malformed line.
+        }
+    }
+    return entries;
+}
+/**
+ * Append an entry to the cache. Writes are serialized through the shared
+ * `.rea/` directory lock so audit writes and cache writes do not interleave.
+ */
+export async function appendEntry(baseDir, input) {
+    const cacheFile = resolveCacheFile(baseDir);
+    await fs.mkdir(path.dirname(cacheFile), { recursive: true });
+    const entry = {
+        sha: input.sha,
+        branch: input.branch,
+        base: input.base,
+        result: input.result,
+        recorded_at: input.timestamp ?? new Date().toISOString(),
+        ...(input.reason !== undefined && input.reason.length > 0
+            ? { reason: input.reason }
+            : {}),
+    };
+    await withAuditLock(cacheFile, async () => {
+        const line = JSON.stringify(entry) + '\n';
+        await fs.appendFile(cacheFile, line);
+    });
+    return entry;
+}
+/**
+ * Find the most-recent entry matching `(sha, branch, base)` within the TTL
+ * window. Idempotent and side-effect free.
+ */
+export async function lookup(baseDir, input) {
+    const cacheFile = resolveCacheFile(baseDir);
+    const entries = await loadEntries(cacheFile);
+    if (entries.length === 0)
+        return { hit: false, missReason: 'empty-file' };
+    // Walk from the tail so the first match is the newest.
+    let matched;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (e.sha === input.sha && e.branch === input.branch && e.base === input.base) {
+            matched = e;
+            break;
+        }
+    }
+    if (matched === undefined)
+        return { hit: false, missReason: 'no-entry' };
+    const nowMs = input.nowMs ?? Date.now();
+    const maxAgeSeconds = input.maxAgeSeconds ?? DEFAULT_CACHE_MAX_AGE_SECONDS;
+    const recordedMs = Date.parse(matched.recorded_at);
+    if (Number.isNaN(recordedMs)) {
+        // Corrupt timestamp — treat as an expired miss so the caller re-reviews.
+        return { hit: false, missReason: 'expired', entry: matched };
+    }
+    if (recordedMs > nowMs + FUTURE_SKEW_ALLOWANCE_MS) {
+        return { hit: false, missReason: 'expired', entry: matched };
+    }
+    if ((nowMs - recordedMs) / 1000 > maxAgeSeconds) {
+        return { hit: false, missReason: 'expired', entry: matched };
+    }
+    return { hit: true, entry: matched };
+}
+/**
+ * Remove every entry matching `sha`. Returns the count removed. A `0` return
+ * is a valid outcome (sha not present). Writes back via the same lock as
+ * `appendEntry`, so concurrent sets do not lose entries.
+ *
+ * Writes use temp-file + `fs.rename` (atomic within a single directory on
+ * POSIX) so unlocked readers (`lookup`, `list`) can never observe a torn or
+ * empty intermediate state. Codex F4 on the 0.5.0 PR1 review.
+ */
+export async function clear(baseDir, sha) {
+    const cacheFile = resolveCacheFile(baseDir);
+    return withAuditLock(cacheFile, async () => {
+        const entries = await loadEntries(cacheFile);
+        const kept = entries.filter((e) => e.sha !== sha);
+        const removed = entries.length - kept.length;
+        if (removed === 0)
+            return 0;
+        const out = kept.length === 0 ? '' : kept.map((e) => JSON.stringify(e)).join('\n') + '\n';
+        const tmpFile = `${cacheFile}.tmp.${process.pid}.${Date.now()}`;
+        await fs.writeFile(tmpFile, out);
+        await fs.rename(tmpFile, cacheFile);
+        return removed;
+    });
+}
+/**
+ * Return every entry, optionally filtered by branch. Entries are returned in
+ * file order (oldest first). Callers that want "newest first" should reverse.
+ */
+export async function list(baseDir, options = {}) {
+    const cacheFile = resolveCacheFile(baseDir);
+    const entries = await loadEntries(cacheFile);
+    if (options.branch === undefined)
+        return entries;
+    return entries.filter((e) => e.branch === options.branch);
+}

package/dist/cli/cache.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `rea cache` — push-review cache operator subcommands (BUG-009).
+ *
+ * Four verbs:
+ *   - `check <sha> --branch <b> --base <b>` — JSON to stdout ONLY; never
+ *     diagnostics. `hooks/push-review-gate.sh` reads this via
+ *     `printf '%s' "$CACHE_RESULT" | jq -e '.hit == true'`, so any stray
+ *     text on stdout would poison the hook's JSON parse.
+ *   - `set <sha> pass|fail --branch <b> --base <b> [--reason <s>]` — record
+ *     a review outcome.
+ *   - `clear <sha>` — drop every entry for a sha (dev convenience).
+ *   - `list [--branch <b>]` — pretty-print entries.
+ *
+ * The TTL used by `check` reads `review.cache_max_age_seconds` from
+ * `.rea/policy.yaml` when present, falling back to
+ * {@link DEFAULT_CACHE_MAX_AGE_SECONDS} (1 hour) when the policy file or
+ * field is absent. An unreadable/malformed policy file is NOT fatal for
+ * `check` — it degrades to the default so a broken policy never deadlocks
+ * the push gate; other commands that don't consume the TTL ignore the policy
+ * entirely.
+ */
+import { type CacheResult } from '../cache/review-cache.js';
+export interface CacheCheckOptions {
+    sha: string;
+    branch: string;
+    base: string;
+}
+export interface CacheSetOptions {
+    sha: string;
+    result: CacheResult;
+    branch: string;
+    base: string;
+    reason?: string;
+}
+export interface CacheClearOptions {
+    sha: string;
+}
+export interface CacheListOptions {
+    branch?: string;
+}
+/**
+ * Print the cache-check JSON to stdout. Hook contract: stdout is ONLY JSON.
+ * On a miss we still exit 0 with `{"hit":false}` — the hook interprets
+ * non-zero as "rea broken, force re-review" via its `|| echo '{"hit":false}'`
+ * fallback.
+ */
+export declare function runCacheCheck(options: CacheCheckOptions): Promise<void>;
+export declare function runCacheSet(options: CacheSetOptions): Promise<void>;
+export declare function runCacheClear(options: CacheClearOptions): Promise<void>;
+export declare function runCacheList(options: CacheListOptions): Promise<void>;
+/** Parse-and-validate helper for `set` — surfaces a clean error on bad input. */
+export declare function parseCacheResult(raw: string): CacheResult;

package/dist/cli/cache.js

@@ -0,0 +1,112 @@
+/**
+ * `rea cache` — push-review cache operator subcommands (BUG-009).
+ *
+ * Four verbs:
+ *   - `check <sha> --branch <b> --base <b>` — JSON to stdout ONLY; never
+ *     diagnostics. `hooks/push-review-gate.sh` reads this via
+ *     `printf '%s' "$CACHE_RESULT" | jq -e '.hit == true'`, so any stray
+ *     text on stdout would poison the hook's JSON parse.
+ *   - `set <sha> pass|fail --branch <b> --base <b> [--reason <s>]` — record
+ *     a review outcome.
+ *   - `clear <sha>` — drop every entry for a sha (dev convenience).
+ *   - `list [--branch <b>]` — pretty-print entries.
+ *
+ * The TTL used by `check` reads `review.cache_max_age_seconds` from
+ * `.rea/policy.yaml` when present, falling back to
+ * {@link DEFAULT_CACHE_MAX_AGE_SECONDS} (1 hour) when the policy file or
+ * field is absent. An unreadable/malformed policy file is NOT fatal for
+ * `check` — it degrades to the default so a broken policy never deadlocks
+ * the push gate; other commands that don't consume the TTL ignore the policy
+ * entirely.
+ */
+import { loadPolicy } from '../policy/loader.js';
+import { DEFAULT_CACHE_MAX_AGE_SECONDS, appendEntry, clear as clearEntries, list as listEntries, lookup, } from '../cache/review-cache.js';
+import { err, log } from './utils.js';
+function resolveMaxAgeSeconds(baseDir) {
+    try {
+        const policy = loadPolicy(baseDir);
+        const configured = policy.review?.cache_max_age_seconds;
+        if (typeof configured === 'number' && configured > 0)
+            return configured;
+        return DEFAULT_CACHE_MAX_AGE_SECONDS;
+    }
+    catch {
+        // Missing or malformed policy must not block the push gate — degrade to
+        // the default. `rea doctor` is the canonical surface for flagging a
+        // broken policy file; the cache is not the place to re-diagnose it.
+        return DEFAULT_CACHE_MAX_AGE_SECONDS;
+    }
+}
+/**
+ * Print the cache-check JSON to stdout. Hook contract: stdout is ONLY JSON.
+ * On a miss we still exit 0 with `{"hit":false}` — the hook interprets
+ * non-zero as "rea broken, force re-review" via its `|| echo '{"hit":false}'`
+ * fallback.
+ */
+export async function runCacheCheck(options) {
+    const baseDir = process.cwd();
+    const maxAgeSeconds = resolveMaxAgeSeconds(baseDir);
+    const result = await lookup(baseDir, {
+        sha: options.sha,
+        branch: options.branch,
+        base: options.base,
+        maxAgeSeconds,
+    });
+    if (result.hit && result.entry !== undefined) {
+        const payload = {
+            hit: true,
+            result: result.entry.result,
+            branch: result.entry.branch,
+            base: result.entry.base,
+            recorded_at: result.entry.recorded_at,
+            ...(result.entry.reason !== undefined ? { reason: result.entry.reason } : {}),
+        };
+        process.stdout.write(JSON.stringify(payload) + '\n');
+        return;
+    }
+    process.stdout.write(JSON.stringify({ hit: false }) + '\n');
+}
+export async function runCacheSet(options) {
+    const baseDir = process.cwd();
+    const entry = await appendEntry(baseDir, {
+        sha: options.sha,
+        branch: options.branch,
+        base: options.base,
+        result: options.result,
+        ...(options.reason !== undefined && options.reason.length > 0
+            ? { reason: options.reason }
+            : {}),
+    });
+    log(`Recorded ${entry.result} for ${entry.sha.slice(0, 12)} (${entry.branch} → ${entry.base}).`);
+}
+export async function runCacheClear(options) {
+    const baseDir = process.cwd();
+    const removed = await clearEntries(baseDir, options.sha);
+    if (removed === 0) {
+        log(`No entries found for ${options.sha.slice(0, 12)}.`);
+        return;
+    }
+    log(`Cleared ${removed} entr${removed === 1 ? 'y' : 'ies'} for ${options.sha.slice(0, 12)}.`);
+}
+export async function runCacheList(options) {
+    const baseDir = process.cwd();
+    const entries = await listEntries(baseDir, {
+        ...(options.branch !== undefined ? { branch: options.branch } : {}),
+    });
+    if (entries.length === 0) {
+        log('No review-cache entries.');
+        return;
+    }
+    for (const e of entries) {
+        const shortSha = e.sha.slice(0, 12);
+        const reason = e.reason !== undefined ? `  — ${e.reason}` : '';
+        console.log(`${e.recorded_at}  ${e.result.padEnd(4)}  ${shortSha}  ${e.branch} → ${e.base}${reason}`);
+    }
+}
+/** Parse-and-validate helper for `set` — surfaces a clean error on bad input. */
+export function parseCacheResult(raw) {
+    if (raw === 'pass' || raw === 'fail')
+        return raw;
+    err(`result must be 'pass' or 'fail'; got ${JSON.stringify(raw)}`);
+    process.exit(1);
+}

package/dist/cli/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type CodexProbeState } from '../gateway/observability/codex-probe.js';
+import { type PrePushDoctorState } from './install/pre-push.js';
 export interface CheckResult {
     label: string;
     /**
@@ -9,6 +10,15 @@ export interface CheckResult {
     status: 'pass' | 'fail' | 'warn' | 'info';
     detail?: string;
 }
+/**
+ * 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 declare function checkFingerprintStore(baseDir: string): Promise<CheckResult>;
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last
@@ -22,11 +32,16 @@ export declare function checksFromProbeState(state: CodexProbeState): CheckResul
  * `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 declare function collectChecks(baseDir: string, codexProbeState?: CodexProbeState): CheckResult[];
+export declare function collectChecks(baseDir: string, codexProbeState?: CodexProbeState, prePushState?: PrePushDoctorState): CheckResult[];
 export interface RunDoctorOptions {
     /** When true, print a 7-day telemetry summary after the checks (G11.5). */
     metrics?: boolean;