@bookedsolid/rea 0.27.0 → 0.28.1

package/dist/cli/review.js

@@ -39,9 +39,34 @@ import { loadPolicyAsync } from '../policy/loader.js';
 import { CodexNotInstalledError, CodexProtocolError, CodexSubprocessError, CodexTimeoutError, IRON_GATE_DEFAULT_MODEL, IRON_GATE_DEFAULT_REASONING, createRealGitExecutor, runCodexReview, } from '../hooks/push-gate/codex-runner.js';
 import { resolvePushGatePolicy } from '../hooks/push-gate/policy.js';
 import { resolveBaseRef } from '../hooks/push-gate/base.js';
-import { summarizeReview } from '../hooks/push-gate/findings.js';
+import { summarizeReview, } from '../hooks/push-gate/findings.js';
+import { writeLastReview } from '../hooks/push-gate/report.js';
 import { computeTreeToken, EMPTY_TREE_SHA } from '../audit/content-token.js';
+import { compileDefaultSecretPatterns, redactSecrets, } from '../gateway/middleware/redact.js';
 import { err, log } from './utils.js';
+/** Relative path to the last-review snapshot, surfaced in JSON output. */
+const LAST_REVIEW_RELATIVE = '.rea/last-review.json';
+/**
+ * 0.28.1 defect-V round-1 P2-1: shared redactor for the
+ * `writeLastReview` failure path. The canonical writer redacts findings
+ * before serialization; if it threw we still need to redact the
+ * in-memory findings before they reach `--with-findings` stdout or
+ * `--json --with-findings`. Without this, a writer failure (read-only
+ * .rea/, ENOSPC, race) would let unredacted Codex prose — which can
+ * quote secrets from the diff — escape via the new surfaces, defeating
+ * the redaction guarantee the writer provides.
+ */
+function redactFindingsInMemory(findings) {
+    const patterns = compileDefaultSecretPatterns({ source: 'default' });
+    const redactStr = (s) => redactSecrets(s, patterns).output;
+    return findings.map((f) => ({
+        severity: f.severity,
+        title: redactStr(f.title),
+        body: redactStr(f.body),
+        ...(f.file !== undefined ? { file: f.file } : {}),
+        ...(f.line !== undefined ? { line: f.line } : {}),
+    }));
+}
 const PROVIDER_CODEX = 'codex';
 /**
  * Probe `codex --version` synchronously. Same shape as the push-gate's
@@ -84,7 +109,7 @@ async function resolveLocalReviewMode(baseDir) {
  * the commander binding can stay thin. Throws via `process.exit` (CLI
  * convention across `src/cli/`).
  */
-export async function runReview(options) {
+export async function runReview(options, deps = {}) {
     const baseDir = process.cwd();
     const strictFailOn = options.strictFailOn ?? 'blocking';
     const { mode, policy } = await resolveLocalReviewMode(baseDir);
@@ -131,7 +156,8 @@ export async function runReview(options) {
     // Codex available — run the review.
     let outcome;
     try {
-        outcome = await executeCodexReview(baseDir, options);
+        const exec = deps.executeCodexReview ?? executeCodexReview;
+        outcome = await exec(baseDir, options);
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
@@ -168,6 +194,49 @@ export async function runReview(options) {
     if (probe.version !== undefined)
         metadata.provider_version = probe.version;
     await safeAudit(baseDir, LOCAL_REVIEW_TOOL_NAME, outcome.verdict === 'blocking' ? InvocationStatus.Denied : InvocationStatus.Allowed, metadata, policy);
+    // 0.28.1 defect-V: persist `.rea/last-review.json` on EVERY successful
+    // codex run (pass / concerns / blocking) BEFORE the exit so agents can
+    // read structured findings to remediate. Pre-fix only the push-gate
+    // wrote this file; `rea review` discarded the bodies after counting,
+    // so consumers saw stale snapshots from days-old push-gate runs (Ava
+    // reported a 2026-05-08 file surviving across new 2026-05-09 runs).
+    //
+    // Reuses the push-gate's writer — the canonical atomic-write path with
+    // redaction. We do NOT inline a second implementation: any divergence
+    // between the two writers would silently desynchronize the schema for
+    // `rea preflight` and any tooling that reads last-review.json.
+    //
+    // Skipped/error paths (codex unavailable, codex error) do NOT call this
+    // — there are no findings to serialize.
+    let lastReviewWritten;
+    try {
+        // `LocalReviewVerdict` permits `'error'` for the audit-record schema
+        // (transport / subprocess failures) but the codex success path can
+        // only produce pass | concerns | blocking — we caught throw above.
+        // Narrow here so the report writer's stricter `Verdict` type accepts
+        // it without losing the audit shape elsewhere in this file.
+        const verdict = outcome.verdict;
+        lastReviewWritten = writeLastReview({
+            baseDir,
+            summary: {
+                verdict,
+                findings: outcome.findings,
+                reviewText: outcome.reviewText,
+            },
+            baseRef: outcome.baseRef,
+            headSha: outcome.headSha,
+            eventCount: outcome.eventCount,
+            durationSeconds: outcome.durationSeconds,
+        });
+    }
+    catch (e) {
+        // last-review.json is a remediation surface, not a gate. A write
+        // failure (read-only fs, ENOSPC, race with another run) must not
+        // change the verdict-driven exit code. Surface the error to stderr
+        // so operators can correlate, then continue.
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`rea: last-review.json write failed: ${msg}\n`);
+    }
     // Decide exit code based on strictFailOn.
     let exitCode;
     if (outcome.verdict === 'blocking') {
@@ -179,8 +248,17 @@ export async function runReview(options) {
     else {
         exitCode = 0;
     }
+    // 0.28.1 defect-V: redacted findings come from the writer when it
+    // succeeded (so `--with-findings` shows the same bodies that landed on
+    // disk). When the write FAILED we re-redact the in-memory findings
+    // inline (round-1 P2-1) — without this fallback, secrets that codex
+    // copied from the diff into a finding body would escape via stdout/
+    // JSON in the exact failure mode where the on-disk surface is gone.
+    const findingsForOutput = lastReviewWritten !== undefined
+        ? lastReviewWritten.findings
+        : redactFindingsInMemory(outcome.findings);
     if (options.json === true) {
-        process.stdout.write(JSON.stringify({
+        const payload = {
             status: outcome.verdict,
             finding_count: outcome.findingCount,
             head_sha: outcome.headSha,
@@ -190,14 +268,89 @@ export async function runReview(options) {
             reasoning_effort: outcome.reasoningEffort,
             duration_seconds: outcome.durationSeconds,
             exit_code: exitCode,
-        }) + '\n');
+            // 0.28.1 defect-V round-1 P2-2: only advertise `last_review_path`
+            // when the writer actually produced a current snapshot. If the
+            // write threw, the file on disk is either missing or a stale
+            // snapshot from an older run — pointing JSON consumers at it
+            // would let agents remediate against the wrong findings while
+            // the current run still exits successfully. Emit `null` and an
+            // explicit `last_review_error` so consumers can branch
+            // deterministically.
+            last_review_path: lastReviewWritten !== undefined ? LAST_REVIEW_RELATIVE : null,
+        };
+        if (lastReviewWritten === undefined) {
+            payload.last_review_error = 'write_failed';
+        }
+        if (options.withFindings === true) {
+            // Mirror last-review.json's Finding shape so JSON consumers see one
+            // schema. Findings are pre-redacted (writer-redacted on success,
+            // re-redacted inline on writer failure — see findingsForOutput).
+            payload.findings = findingsForOutput;
+        }
+        process.stdout.write(JSON.stringify(payload) + '\n');
     }
     else {
         log(`local review: ${outcome.verdict} (${outcome.findingCount} finding(s)) — head=${outcome.headSha.slice(0, 12)} base=${outcome.baseRef}`);
         log(`audit entry written: tool_name=${LOCAL_REVIEW_TOOL_NAME}`);
+        if (options.withFindings === true) {
+            printFindingsBySeverity(findingsForOutput, lastReviewWritten !== undefined);
+        }
     }
     process.exit(exitCode);
 }
+/**
+ * 0.28.1 defect-V — group findings by severity (P1 → P2 → P3) and print
+ * to stdout via `log()`. Each finding renders as
+ *
+ *   - [P1] <title> — <file>:<line>
+ *
+ * mirroring the codex-banner shape produced by the push-gate, so muscle
+ * memory transfers between the two surfaces. The full body is intentionally
+ * NOT printed here — the body can be very long, and the canonical place to
+ * read full bodies is `.rea/last-review.json`. We print enough to identify
+ * each finding and drive the agent to the file.
+ *
+ * Round-2 P2 fix: only point at last-review.json when the writer
+ * actually produced a current snapshot. Mirrors the JSON-path guard on
+ * `last_review_path`. If the write failed, the on-disk file is missing
+ * or stale; pointing a human there would let them remediate against the
+ * wrong findings. Falls back to a self-contained banner that names the
+ * failure mode.
+ */
+function printFindingsBySeverity(findings, lastReviewWritten) {
+    if (findings.length === 0)
+        return;
+    const order = ['P1', 'P2', 'P3'];
+    log('');
+    if (lastReviewWritten) {
+        log(`findings (see ${LAST_REVIEW_RELATIVE} for full bodies):`);
+    }
+    else {
+        log('findings (last-review.json write FAILED — bodies shown inline below; stale file may exist on disk and should be ignored):');
+    }
+    for (const sev of order) {
+        const group = findings.filter((f) => f.severity === sev);
+        if (group.length === 0)
+            continue;
+        for (const f of group) {
+            const loc = f.file !== undefined ? ` — ${f.file}${f.line !== undefined ? `:${f.line}` : ''}` : '';
+            log(`  - [${sev}] ${f.title}${loc}`);
+            // Round-3 P2 fix: when the writer failed, the on-disk surface is
+            // gone — agents and humans have no other place to read the body.
+            // Render the body inline (already redacted upstream) so the
+            // banner's "bodies shown inline below" promise is truthful and
+            // remediation can still happen. On the success path, bodies stay
+            // in last-review.json so the stdout surface stays scannable.
+            if (!lastReviewWritten && f.body.length > 0) {
+                for (const bodyLine of f.body.split(/\r?\n/)) {
+                    if (bodyLine.length === 0)
+                        continue;
+                    log(`      ${bodyLine}`);
+                }
+            }
+        }
+    }
+}
 /**
  * Execute the codex review subprocess and translate the output to a
  * verdict. Reuses the push-gate's resolved policy so `codex_model` /
@@ -260,6 +413,13 @@ async function executeCodexReview(baseDir, options) {
         durationSeconds: codexResult.durationSeconds,
         model: resolved.codex_model ?? IRON_GATE_DEFAULT_MODEL,
         reasoningEffort: resolved.codex_reasoning_effort ?? IRON_GATE_DEFAULT_REASONING,
+        // 0.28.1 defect-V: thread the structured findings + reviewText + event
+        // count through to the caller so `runReview` can persist last-review.json
+        // and (optionally) print bodies. Pre-fix these were dropped on the floor
+        // after `summary.findings.length` was computed.
+        findings: summary.findings,
+        reviewText: codexResult.reviewText,
+        eventCount: codexResult.eventCount,
     };
 }
 function classifyCodexError(e) {
@@ -313,11 +473,13 @@ export function registerReviewCommand(program) {
         return raw;
     })
         .option('--json', 'emit a single-line JSON result instead of human-readable output')
+        .option('--with-findings', 'after the summary, print findings grouped by severity (P1/P2/P3); when combined with --json, the JSON payload gains a `findings` array')
         .action(async (opts) => {
         await runReview({
             ...(opts.base !== undefined ? { base: opts.base } : {}),
             ...(opts.strictFailOn !== undefined ? { strictFailOn: opts.strictFailOn } : {}),
             ...(opts.json === true ? { json: true } : {}),
+            ...(opts.withFindings === true ? { withFindings: true } : {}),
         });
     });
 }

package/dist/cli/status.d.ts

@@ -75,6 +75,12 @@ export interface LiveDownstreamSnapshot {
     circuit_state: 'closed' | 'open' | 'half-open';
     retry_at: string | null;
     last_error: string | null;
+    /**
+     * 0.28.0 helix-025 F1 — `'never' | 'ok' | 'errored'` tri-state.
+     * `null` for snapshots written by pre-0.28.0 gateways that did not
+     * include the field (back-compat).
+     */
+    connection_state: 'never' | 'ok' | 'errored' | null;
     tools_count: number | null;
     open_transitions: number;
     session_blocker_emitted: boolean;

package/dist/cli/status.js

@@ -129,6 +129,12 @@ function parseDownstreamEntry(raw) {
     const circuit = r.circuit_state === 'open' || r.circuit_state === 'half-open' || r.circuit_state === 'closed'
         ? r.circuit_state
         : 'closed';
+    // 0.28.0 helix-025 F1: tri-state. `null` when the snapshot was written
+    // by a pre-0.28.0 gateway (back-compat) — the pretty-printer renders
+    // that as "—" rather than fabricating a value.
+    const connectionState = r.connection_state === 'never' || r.connection_state === 'ok' || r.connection_state === 'errored'
+        ? r.connection_state
+        : null;
     return {
         name: r.name,
         connected: typeof r.connected === 'boolean' ? r.connected : false,
@@ -136,6 +142,7 @@ function parseDownstreamEntry(raw) {
         circuit_state: circuit,
         retry_at: typeof r.retry_at === 'string' ? r.retry_at : null,
         last_error: typeof r.last_error === 'string' ? r.last_error : null,
+        connection_state: connectionState,
         tools_count: typeof r.tools_count === 'number' && Number.isInteger(r.tools_count) ? r.tools_count : null,
         open_transitions: typeof r.open_transitions === 'number' && Number.isInteger(r.open_transitions)
             ? r.open_transitions

package/dist/cli/verify-claim.d.ts

@@ -0,0 +1,149 @@
+/**
+ * `rea verify-claim <claim-id>` — replay a recorded security-claim PoC
+ * battery against the currently-installed (or in-tree dogfood) rea CLI.
+ *
+ * The centerpiece of 0.28.0 (4th structural pivot — claims as
+ * machine-verifiable artifacts rather than prose-only release notes).
+ *
+ * Each claim lives at `data/claims/<id>.json` and lists 1..N PoCs.
+ * Every PoC has a `type` that names the executor:
+ *
+ *   - `scan-bash` (primary): pipes `input` into
+ *     `dist/cli/index.js hook scan-bash --mode <protected|blocked>` and
+ *     compares the resulting verdict to `expected_verdict`.
+ *   - `shellcheck` (helix-031 case): runs shellcheck on `target` and
+ *     asserts the run is clean (no SC<code> warnings).
+ *
+ * Resolution order for the rea CLI under test:
+ *
+ *   - `--installed` → resolves to `<cwd>/node_modules/@bookedsolid/rea/dist/cli/index.js`.
+ *     This is the canonical "verify against MY pinned rea" mode for
+ *     consumers — tells them whether the version they actually have
+ *     installed still rejects the PoCs the claim targets.
+ *   - default → uses the same `dist/cli/index.js` that ships with the
+ *     CLI itself (i.e. the rea repo's own dogfood). Resolved relative
+ *     to the running script.
+ *
+ * Exit codes:
+ *
+ *   - 0 — every PoC matched the recorded `expected_verdict`.
+ *   - 1 — at least one PoC mismatched (regression — investigate).
+ *   - 2 — claim id is unknown / no JSON file at `data/claims/<id>.json`.
+ */
+import { type SpawnSyncReturns } from 'node:child_process';
+import type { Command } from 'commander';
+export interface ScanBashPoC {
+    id: string;
+    type: 'scan-bash';
+    input: string;
+    mode: 'protected' | 'blocked';
+    expected_verdict: 'allow' | 'block';
+}
+export interface ShellcheckPoC {
+    id: string;
+    type: 'shellcheck';
+    target: string;
+    expected_verdict: 'clean';
+}
+export type ClaimPoC = ScanBashPoC | ShellcheckPoC;
+export interface Claim {
+    id: string;
+    title: string;
+    introduced_in: string;
+    closed_in: string;
+    summary?: string;
+    pocs: ClaimPoC[];
+}
+export interface VerifyClaimOptions {
+    /** Resolve the CLI to `<cwd>/node_modules/@bookedsolid/rea/dist/cli/index.js`. */
+    installed?: boolean;
+    /** Emit a single JSON document on stdout. */
+    json?: boolean;
+    /**
+     * Override the claim-file root. Production resolves this internally
+     * (ships at `data/claims/` next to the package). Tests pass an
+     * absolute path so they can stage fixtures.
+     */
+    claimsDir?: string;
+    /**
+     * Override the rea CLI under test. Wins over `installed`. Used by
+     * tests to point at a stub binary. Production callers leave this
+     * unset.
+     */
+    cliOverride?: string;
+    /**
+     * Override the working directory the `--installed` resolver uses.
+     * Defaults to `process.cwd()`; tests pass a tmp dir.
+     */
+    cwd?: string;
+}
+export interface PoCResult {
+    poc_id: string;
+    type: ClaimPoC['type'];
+    expected: string;
+    actual: string;
+    match: boolean;
+    /** Empty on match; populated on mismatch with a one-line diagnostic. */
+    detail: string;
+}
+export interface VerifyClaimResult {
+    claim_id: string;
+    cli: string;
+    total: number;
+    matched: number;
+    mismatched: number;
+    results: PoCResult[];
+    exit_code: 0 | 1 | 2;
+}
+/**
+ * Resolve the directory holding the bundled claim JSON files. Walks up
+ * from the running script (or from this file at dev time) looking for
+ * a `data/claims/` sibling. Returns null when the directory cannot be
+ * located — the caller falls back to whatever `claimsDir` override was
+ * passed.
+ */
+export declare function resolveDefaultClaimsDir(): string | null;
+/**
+ * Load and validate a claim file. Throws on malformed JSON or shape
+ * mismatch — `runVerifyClaim` translates the throw into exit-code 2 +
+ * a stderr message.
+ */
+export declare function loadClaim(claimsDir: string, claimId: string): Claim;
+/**
+ * Resolve the rea CLI to invoke for `scan-bash` PoCs.
+ *
+ * Precedence: cliOverride > --installed > sibling dogfood dist/cli/index.js.
+ *
+ * Returns a pair `[command, args]` so the caller can do
+ * `spawnSync(cmd, [...args, 'hook', 'scan-bash', ...])`. The shape
+ * keeps node-vs-direct-binary differences localized to this resolver.
+ */
+export declare function resolveCli(opts: VerifyClaimOptions): {
+    cmd: string;
+    args: string[];
+    path: string;
+};
+interface SpawnImpl {
+    (cmd: string, args: string[], options: {
+        input?: string;
+        encoding: 'utf8';
+        timeout: number;
+    }): SpawnSyncReturns<string>;
+}
+/**
+ * Run a single PoC against the resolved CLI. Pure function — no global
+ * state, all dependencies threaded through `cliCmd` / `cliArgs` / `spawn`.
+ * Tests substitute `spawn` with a fake.
+ */
+export declare function runPoC(poc: ClaimPoC, cliCmd: string, cliArgs: string[], spawn?: SpawnImpl, cwd?: string): PoCResult;
+/**
+ * Run all PoCs in a claim. Pure — exposed so tests can drive without
+ * spawning processes if they substitute `spawn`.
+ */
+export declare function runVerifyClaimSync(claim: Claim, cliCmd: string, cliArgs: string[], cliPath: string, spawn?: SpawnImpl, cwd?: string): VerifyClaimResult;
+export declare function runVerifyClaim(claimId: string, opts: VerifyClaimOptions): Promise<void>;
+/**
+ * Attach `rea verify-claim <claim-id>` to the commander program.
+ */
+export declare function registerVerifyClaimCommand(program: Command): void;
+export {};