@bookedsolid/rea 0.28.0 → 0.28.1

package/dist/cli/review.d.ts

@@ -31,6 +31,8 @@
  * the push-gate's review.
  */
 import type { Command } from 'commander';
+import { type LocalReviewVerdict } from '../audit/local-review-event.js';
+import { type Finding } from '../hooks/push-gate/findings.js';
 export interface RunReviewOptions {
     /** Optional explicit base ref. Defaults to upstream-ladder resolution. */
     base?: string;
@@ -42,13 +44,65 @@ export interface RunReviewOptions {
     strictFailOn?: 'concerns' | 'blocking';
     /** Emit a single JSON line on stdout instead of pretty output. */
     json?: boolean;
+    /**
+     * 0.28.1 defect-V: when true, after the human-readable summary line
+     * (or alongside the JSON payload), emit the finding bodies grouped by
+     * severity. Default off — preserves backward-compatible single-line
+     * stdout for existing CI consumers.
+     */
+    withFindings?: boolean;
+}
+/**
+ * Exported so tests can construct fake outcomes for the seam in
+ * `runReview`. Production callers don't reference this directly.
+ */
+export interface ReviewOutcome {
+    verdict: LocalReviewVerdict;
+    findingCount: number;
+    baseRef: string;
+    headSha: string;
+    /**
+     * 0.26.0 helix-026 finding-1: tree SHA of HEAD at review time. The
+     * deterministic content fingerprint `rea preflight` matches coverage
+     * on. Empty string when not resolvable (no HEAD, no git repo) — the
+     * audit writer omits `content_token` from metadata in that case.
+     */
+    contentToken: string;
+    durationSeconds: number;
+    model: string;
+    reasoningEffort: string;
+    /**
+     * 0.28.1 defect-V: structured findings produced by the review. Pre-fix
+     * the CLI threw these away after counting; agents could not remediate
+     * blocking verdicts because the bodies were unreadable through any
+     * documented surface.
+     */
+    findings: Finding[];
+    /**
+     * 0.28.1 defect-V: full agent-prose review text. Persisted to
+     * `.rea/last-review.json` (post-redaction) so consumers have a
+     * machine-readable transcript for parser-miss debugging.
+     */
+    reviewText: string;
+    /** Count of raw JSONL events from codex — recorded in last-review.json. */
+    eventCount: number;
+}
+/**
+ * 0.28.1 defect-V — narrow test seam. Production callers never set this;
+ * tests inject a fake to drive `runReview` deterministically without
+ * spawning codex. The seam matches `executeCodexReview`'s signature so
+ * the production path and the test path go through the same downstream
+ * wiring (audit append, last-review.json, exit code, output).
+ */
+export interface RunReviewDeps {
+    executeCodexReview?: (baseDir: string, options: RunReviewOptions) => Promise<ReviewOutcome>;
 }
 /**
  * Public runner — exposed so tests can drive the function in-process and
  * the commander binding can stay thin. Throws via `process.exit` (CLI
  * convention across `src/cli/`).
  */
-export declare function runReview(options: RunReviewOptions): Promise<void>;
+export declare function runReview(options: RunReviewOptions, deps?: RunReviewDeps): Promise<void>;
 /**
  * Attach `rea review` to a commander Program.
  */

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",