@bookedsolid/rea 0.46.0 → 0.47.0

package/MIGRATING.md

@@ -528,6 +528,95 @@ under `--since` and lets the per-record timestamp filter drop the
 out-of-window entries. Correctness over micro-optimization;
 `rea audit summary` performance is unchanged in practice.
 
+## Audit observability completion (added in 0.47.0)
+
+0.46.0 shipped `rea audit by-tool` and `rea audit timeline`. 0.47.0
+rounds out the observability surface with two timeline ergonomics fixes
+and a new refusal-debugging reader:
+
+### `rea audit timeline` — helpful MAX_BUCKETS errors + auto-clamp
+
+Pre-0.47.0, `rea audit timeline --bucket=15m --since=21d` (= 2016
+buckets, just past the 2000-bucket ceiling) rejected with a generic
+"use a larger --bucket or narrower --since" message. The 0.47.0 error
+now carries concrete remediation:
+
+```text
+rea audit timeline: --bucket=15m × --since=21d = 2016 buckets exceeds
+MAX_BUCKETS=2000. Try --bucket=1h (504 buckets) or --since=20d 20h
+(1999 buckets).
+```
+
+For the related "I omitted `--since` and the audit log spans a year"
+case, the timeline now AUTO-CLAMPS to the widest window that fits at
+the requested cadence rather than throwing. The clamp is surfaced
+inline in human output:
+
+```text
+rea audit timeline (clamped to ~1999h of newest activity, hourly)
+────────────────────────────────────────
+note: --since not specified; auto-clamped to newest 2000 buckets
+      (~1999h span at --bucket=1h). Pass --since=DUR to anchor at
+      now, or rerun with a WIDER --bucket (current 1h) to fit the
+      full log.
+…
+```
+
+JSON consumers see the clamp as a new `clamped_since` field — `null`
+in the common case, a duration string (e.g. `"1999h"`) when the
+clamp fired. The field is informational, not reproducible: `--since`
+always anchors at `now`, so a clamp anchored at an older record
+cannot be round-tripped through `--since=<clamped_since>`. Use the
+field to detect that clamping occurred and to size the rendered
+window in dashboards. For a fully reproducible view, pass `--since`
+or `--bucket` explicitly. Schema version is unchanged (still v1) —
+the field is purely additive. `window.start/end/seconds` is also
+nulled out on sparse-log clamps where the kept buckets don't form a
+contiguous time lattice, so `total_events / window.seconds` never
+derives a misleading rate.
+
+### `rea audit top-blocks` — debugging "why was that refused?"
+
+A new subcommand surfaces the most recent refusal events (any record
+whose `status` is `denied` or `error`) from the audit log:
+
+```bash
+rea audit top-blocks                          # last 20 refusals, all time
+rea audit top-blocks --since=24h              # last 24h
+rea audit top-blocks --since=7d --limit=50    # last week, top 50
+rea audit top-blocks --json                   # dashboard shape
+```
+
+Each row carries the short hash (first 8 chars), full timestamp, tool
+name, and the refusal reason (sourced from the record's `error` field;
+truncated to ~80 chars in human output, full text in JSON). Sorted
+newest-first so the most recent refusals are at the top.
+
+Use this when an agent reports "the hook blocked my push" or "the
+write was refused" and you need the exact reason without grepping
+`.rea/audit.jsonl` by hand.
+
+JSON shape (stable, v1):
+
+```json
+{
+  "schema_version": 1,
+  "since": "24h",
+  "limit": 20,
+  "window": { "seconds": 86400, "start": "...", "end": "..." },
+  "total_matched": 4,
+  "events": [
+    { "hash": "...", "timestamp": "...", "tool": "Bash",
+      "status": "denied", "reason": "...", "session_id": "..." }
+  ],
+  "files_scanned": ["/abs/path/.rea/audit.jsonl"]
+}
+```
+
+`total_matched` is the pre-limit count, so dashboards can show
+"20 of 47 refusals in window". Walk scope mirrors the sibling audit
+readers — current `.rea/audit.jsonl` PLUS every rotated segment.
+
 ## Policy knobs worth setting
 
 For consumers with a long-running migration branch (>30 commits since

package/dist/cli/audit-timeline.d.ts

@@ -112,6 +112,16 @@ export interface AuditTimelineResult {
     /** Index of the bucket with the highest count. `-1` when no events. */
     peak_index: number;
     files_scanned: string[];
+    /**
+     * 0.47.0 charter item 2: when `--since` was NOT specified and the
+     * audit log spans more than `MAX_BUCKETS` buckets at the requested
+     * cadence, the timeline auto-clamps the window to the widest duration
+     * that fits. This field carries the duration string that was actually
+     * applied (e.g. `"7d"`) — `null` when no clamping fired (the common
+     * case). Dashboard consumers use this to flag "the window you saw is
+     * not the whole log" in their UI.
+     */
+    clamped_since: string | null;
 }
 export interface ComputeAuditTimelineOptions {
     /** Override CWD. Tests set this; production uses `process.cwd()`. */
@@ -134,6 +144,16 @@ export interface ComputeAuditTimelineOptions {
  * value but `MAX_BUCKETS` will bound the rendered output.
  */
 export declare function resolveBucketSeconds(raw: string): number;
+/**
+ * Format a duration in seconds as the coarsest single-unit compact
+ * string that round-trips through `parseDurationSeconds`. Mirrors the
+ * shape `--since` accepts (`s`/`m`/`h`/`d`/`w`).
+ *
+ * 0.47.0 charter item 1: powers the helpful-error suggestion + the
+ * auto-clamp `clamped_since` field. The largest-unit pass keeps the
+ * suggestion readable — `"21d"` not `"1814400s"`.
+ */
+export declare function formatDurationCompact(seconds: number): string;
 /**
  * Compute the bucketed timeline. Pure (read-only). Throws
  * `AuditTimelineOptionError` on bad `--since` / `--bucket`; throws on

package/dist/cli/audit-timeline.js

@@ -165,6 +165,107 @@ function alignToBucket(epochMs, bucketSeconds) {
     const bucketMs = bucketSeconds * 1000;
     return Math.floor(epochMs / bucketMs) * bucketMs;
 }
+/**
+ * Format a duration in seconds as the coarsest single-unit compact
+ * string that round-trips through `parseDurationSeconds`. Mirrors the
+ * shape `--since` accepts (`s`/`m`/`h`/`d`/`w`).
+ *
+ * 0.47.0 charter item 1: powers the helpful-error suggestion + the
+ * auto-clamp `clamped_since` field. The largest-unit pass keeps the
+ * suggestion readable — `"21d"` not `"1814400s"`.
+ */
+export function formatDurationCompact(seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return '0s';
+    const units = [
+        ['w', 60 * 60 * 24 * 7],
+        ['d', 60 * 60 * 24],
+        ['h', 60 * 60],
+        ['m', 60],
+        ['s', 1],
+    ];
+    for (const [unit, factor] of units) {
+        if (seconds % factor === 0) {
+            return `${String(seconds / factor)}${unit}`;
+        }
+    }
+    return `${String(seconds)}s`;
+}
+/**
+ * 0.47.0 charter item 1: build a helpful error message for the
+ * MAX_BUCKETS guard. Computes a concrete "use --bucket=X" and
+ * "use --since=Y" suggestion based on the actual inputs, so the
+ * operator sees the next step inline instead of having to do the
+ * division themselves.
+ *
+ * Strategy:
+ *   - "Try a wider bucket" — smallest unit from {1h, 4h, 1d, 1w} that
+ *     brings projected ≤ MAX_BUCKETS. Falls back to a concrete second
+ *     count if no unit fits (extreme `--since`).
+ *   - "Try a narrower since" — largest multiple of the requested bucket
+ *     that fits under MAX_BUCKETS, rendered compactly.
+ *
+ * The error text always includes the substrings `bucket=`, `since=`,
+ * and `Try` so test assertions can pin the shape.
+ */
+function bucketOverflowMessage(windowSeconds, bucketSeconds, rawBucket, rawSince, sinceImplicit) {
+    const projected = Math.ceil(windowSeconds / bucketSeconds);
+    // Candidate wider buckets, in ascending size — pick the first that fits.
+    const allCandidates = [
+        ['1h', 60 * 60],
+        ['4h', 4 * 60 * 60],
+        ['1d', 60 * 60 * 24],
+        ['1w', 60 * 60 * 24 * 7],
+    ];
+    const widerCandidates = allCandidates.filter((entry) => entry[1] > bucketSeconds);
+    let bucketSuggestion = null;
+    let bucketSuggestionCount = null;
+    for (const [label, secs] of widerCandidates) {
+        // Account for alignment slack: a window of N seconds at bucket
+        // size S emits up to `ceil(N/S) + 1` buckets after alignment
+        // (lower-edge + upper-edge alignment can each contribute one
+        // extra bucket vs the naive division). Codex round-4 P2 (0.47.0):
+        // suggesting a bucket where `ceil(N/S) === MAX_BUCKETS` would
+        // still re-throw at the post-alignment guard. Use the +1
+        // worst-case so the operator's retry actually succeeds.
+        const cnt = Math.ceil(windowSeconds / secs) + 1;
+        if (cnt <= MAX_BUCKETS) {
+            bucketSuggestion = label;
+            bucketSuggestionCount = cnt;
+            break;
+        }
+    }
+    // Largest --since that fits at the requested bucket size, rendered
+    // compactly. Subtract one bucket so the suggested value survives the
+    // post-alignment guard regardless of where `now` falls on the
+    // bucket lattice — codex round-1 P2 (0.47.0): a window of exactly
+    // `MAX_BUCKETS * bucketSeconds` aligns to MAX_BUCKETS+1 buckets in
+    // the common case (`now` not already on a boundary), so the
+    // operator pasting our suggestion would hit the same error they
+    // just got. `(MAX_BUCKETS - 1) * bucketSeconds` leaves alignment
+    // slack on either edge.
+    const fittingSinceSeconds = (MAX_BUCKETS - 1) * bucketSeconds;
+    const sinceSuggestion = formatDurationCompact(fittingSinceSeconds);
+    const sinceSuggestionCount = Math.floor(fittingSinceSeconds / bucketSeconds);
+    const parts = [];
+    const reason = sinceImplicit
+        ? `--since not specified; defaulting to full audit log (${rawSince}) at --bucket=${rawBucket} = ${String(projected)} buckets exceeds MAX_BUCKETS=${String(MAX_BUCKETS)}.`
+        : `--bucket=${rawBucket} × --since=${rawSince} = ${String(projected)} buckets exceeds MAX_BUCKETS=${String(MAX_BUCKETS)}.`;
+    parts.push(reason);
+    const suggestions = [];
+    if (bucketSuggestion !== null && bucketSuggestionCount !== null) {
+        suggestions.push(`--bucket=${bucketSuggestion} (${String(bucketSuggestionCount)} buckets)`);
+    }
+    suggestions.push(`--since=${sinceSuggestion} (${String(sinceSuggestionCount)} buckets)`);
+    parts.push(`Try ${suggestions.join(' or ')}.`);
+    return parts.join(' ');
+}
+// 0.47.0 round-3 (codex P1+P2): the pre-scan `measureLogBounds`
+// helper was removed. The all-time auto-clamp now runs as a
+// post-scan recovery against observed bucket keys (the only data
+// that can't be fooled by caller-supplied timestamps or empty
+// current-file edge cases). See the "post-scan auto-clamp" branch
+// inside `computeAuditTimeline`.
 /**
  * Compute the bucketed timeline. Pure (read-only). Throws
  * `AuditTimelineOptionError` on bad `--since` / `--bucket`; throws on
@@ -181,6 +282,7 @@ export async function computeAuditTimeline(options = {}) {
     let windowSeconds = null;
     let windowStart = null;
     let windowEnd = null;
+    let clampedSince = null;
     if (options.since !== undefined && options.since.length > 0) {
         try {
             windowSeconds = parseDurationSeconds(options.since);
@@ -194,16 +296,28 @@ export async function computeAuditTimeline(options = {}) {
         windowEnd = now;
         windowStart = new Date(now.getTime() - windowSeconds * 1000);
         // Guard against runaway bucket counts under a wide --since with a
-        // tiny --bucket. A simple ceiling is cheaper than rendering 100k
-        // empty rows and gives the operator a clear remediation path.
+        // tiny --bucket. 0.47.0 charter item 1: deliver a concrete-suggestion
+        // error rather than the prior "use a larger --bucket or narrower
+        // --since" generic line — the operator should see the next step
+        // inline.
         const projected = Math.ceil(windowSeconds / bucketSeconds);
         if (projected > MAX_BUCKETS) {
-            throw new AuditTimelineOptionError(`--bucket=${bucketRaw} with --since=${options.since} would emit ` +
-                `${String(projected)} buckets (max ${String(MAX_BUCKETS)}). ` +
-                `Use a larger --bucket or narrower --since.`);
+            throw new AuditTimelineOptionError(bucketOverflowMessage(windowSeconds, bucketSeconds, bucketRaw, options.since, false));
         }
     }
     const files = await resolveTimelineFileWalk(baseDir);
+    // 0.47.0 charter item 2: auto-clamp on long-history repos is
+    // implemented as a POST-SCAN recovery, not a pre-scan guess. Codex
+    // round-3 P1: a pre-scan clamp based on `latestMs - earliestMs`
+    // span is wrong for the no-`--since` path, which normally emits
+    // ONLY event-bearing buckets. A sparse long-lived repo (two
+    // records a year apart at `--bucket=1h`) has a 365d span but a
+    // 2-bucket result — pre-clamping would incorrectly drop one of
+    // those events. We must let the scan see what bucket count the
+    // actual records produce, then clamp only if that exceeds
+    // MAX_BUCKETS. The clamp anchor uses the busiest in-data range
+    // (max observed timestamp + alignment buffer), so we never have
+    // to guess from disk metadata. See the post-scan branch below.
     // Bucket key is the aligned epoch-ms boundary; value is the count.
     const buckets = new Map();
     let totalEvents = 0;
@@ -275,8 +389,19 @@ export async function computeAuditTimeline(options = {}) {
         // the renderer.
         const emit = Math.floor((endKey - startKey) / stepMs) + 1;
         if (emit > MAX_BUCKETS) {
-            throw new AuditTimelineOptionError(`--bucket / --since would emit ${String(emit)} buckets after alignment ` +
-                `(max ${String(MAX_BUCKETS)}). Use a larger --bucket or narrower --since.`);
+            // Post-alignment overflow is a near-miss vs the pre-scan
+            // projection check (alignment can add at most one bucket on
+            // either edge). Codex round-6 P3 (0.47.0): the helpful-error
+            // builder previously recomputed the projected count from
+            // `windowSeconds` and could end up saying "= 2000 buckets
+            // exceeds MAX_BUCKETS=2000" when the actual post-alignment
+            // count was 2001. Inflate `windowSeconds` by enough to make
+            // the projection match the actual aligned emit count — that
+            // way the operator sees a consistent number, and the
+            // remediation suggestions inherit the same +1 bias.
+            const effectiveSince = clampedSince ?? (options.since ?? formatDurationCompact(windowSeconds ?? 0));
+            const reportedSeconds = Math.max(windowSeconds ?? 0, (emit - 1) * bucketSeconds + 1);
+            throw new AuditTimelineOptionError(bucketOverflowMessage(reportedSeconds, bucketSeconds, bucketRaw, effectiveSince, options.since === undefined || options.since.length === 0));
         }
         for (let k = startKey; k <= endKey; k += stepMs) {
             result.push({
@@ -288,20 +413,107 @@ export async function computeAuditTimeline(options = {}) {
     }
     else if (buckets.size > 0) {
         const keys = Array.from(buckets.keys()).sort((a, b) => a - b);
+        const stepMs = bucketSeconds * 1000;
         if (keys.length > MAX_BUCKETS) {
-            // Without --since the operator hasn't asked for a fixed shape,
-            // but a runaway result still needs a guard. Refuse rather than
-            // truncate silently.
-            throw new AuditTimelineOptionError(`Without --since, the audit log spans ${String(keys.length)} ${bucketRaw} buckets ` +
-                `(max ${String(MAX_BUCKETS)}). Pass --since to scope, or use a larger --bucket.`);
+            // 0.47.0 charter item 2 (post-scan auto-clamp): the actual
+            // observed bucket count exceeds MAX_BUCKETS. The no-`--since`
+            // path emits only event-bearing buckets (not a zero-filled
+            // lattice), so clamping by a contiguous time window would
+            // discard most of the newest activity on SPARSE logs (codex
+            // round-5 P1: e.g. one record/day across 2001 days at
+            // --bucket=1h, a time-window clamp keeps ~83 buckets — the
+            // newest-2000-keys clamp keeps all 2000 newest event-bearing
+            // buckets). The right shape: slice the keys array to the newest
+            // MAX_BUCKETS entries directly.
+            //
+            // Codex round-3 P1: clamp on OBSERVED data, not guessed span.
+            // Codex round-3 P2: observed-max timestamp sidesteps both the
+            // empty-current-file case and the out-of-order-timestamp case.
+            // Codex round-4 P2: full MAX_BUCKETS budget (the +1 alignment
+            // slack doesn't apply when cherry-picking from observed keys).
+            const fittingBuckets = MAX_BUCKETS;
+            const kept = keys.slice(keys.length - fittingBuckets);
+            const startKey = kept[0];
+            const anchorKey = kept[kept.length - 1];
+            // Determine whether the kept buckets form a CONTIGUOUS lattice
+            // (every bucket between startKey and anchorKey is present) or a
+            // SPARSE one (gaps inside). The no-`--since` path emits only
+            // event-bearing buckets, so a sparse clamp is the common case.
+            // Codex round-6 P2 (0.47.0): if we filled `window.start/end/
+            // seconds` with the bucket span of a sparse clamp, the JSON
+            // would lie to dashboard consumers — `total_events / window.
+            // seconds` would derive a wildly-wrong rate, and the operator
+            // could NOT reproduce the view by re-running with
+            // `--since=<clamped_since>` (it would either error or include
+            // far more buckets). Treat the two shapes distinctly:
+            //   - contiguous: report the time-window shape (operator can
+            //     paste `--since=<clamped_since>` to reproduce).
+            //   - sparse: leave `window` null (no reproducible duration
+            //     exists), but still report `clamped_since` so callers
+            //     know the kept-bucket count was budgeted.
+            const expectedContiguousCount = Math.floor((anchorKey - startKey) / stepMs) + 1;
+            const isContiguous = expectedContiguousCount === kept.length;
+            // 0.47.0 charter item 2: `clamped_since` is ALWAYS a duration
+            // string (per the charter `clamped_since: "<DUR>"` contract).
+            // It carries the approximate time span the rendered window
+            // covers — informative, not necessarily paste-back-safe.
+            //
+            // Codex round-8 P2 (0.47.0): on stale logs (latest record
+            // hours/days ago) `--since=<DUR>` would NOT reproduce the
+            // returned data because `--since` always anchors on `now`,
+            // not on the audit's latest record. The reproducibility
+            // promise we entertained briefly across rounds 7-8 is
+            // inherently unsound — `--since` semantics fix one side of
+            // the window (now), so any clamp anchored at an older
+            // timestamp can't round-trip through it. The `note:` line in
+            // human output now describes the field as APPROXIMATE
+            // rather than pasteable.
+            //
+            // Codex round-8 P2 (0.47.0): the sparse-clamp branch
+            // previously emitted `"newest 2000 buckets"` for clarity, but
+            // that broke the documented `<DUR>` shape — dashboards trying
+            // to parse it as a duration would fail only on sparse logs.
+            // Both branches now emit a duration string; the human note
+            // adds the "sparse" qualifier so operators understand what
+            // they're looking at.
+            const spanSeconds = Math.max(bucketSeconds, Math.ceil((anchorKey - startKey) / 1000) + bucketSeconds);
+            clampedSince = formatDurationCompact(spanSeconds);
+            // For contiguous clamps, also fill window.* so consumers can
+            // compute rates against a real duration. For sparse clamps,
+            // window.* stays null — `total_events / window.seconds` would
+            // be meaningless when the kept buckets don't form a contiguous
+            // lattice.
+            if (isContiguous) {
+                windowSeconds = spanSeconds;
+                windowEnd = new Date(anchorKey + stepMs);
+                windowStart = new Date(startKey);
+            }
+            // Track the contiguous-vs-sparse shape so the renderer can
+            // surface the right note.
+            void expectedContiguousCount; // used above via isContiguous
+            // Emit each kept bucket. total_events under the post-scan clamp
+            // path counts only what the rendered buckets contain — older
+            // sliced-out buckets contribute nothing to the report.
+            let inWindow = 0;
+            for (const k of kept) {
+                const cnt = buckets.get(k) ?? 0;
+                result.push({
+                    start: new Date(k).toISOString(),
+                    end: new Date(k + stepMs).toISOString(),
+                    count: cnt,
+                });
+                inWindow += cnt;
+            }
+            totalEvents = inWindow;
         }
-        const stepMs = bucketSeconds * 1000;
-        for (const k of keys) {
-            result.push({
-                start: new Date(k).toISOString(),
-                end: new Date(k + stepMs).toISOString(),
-                count: buckets.get(k) ?? 0,
-            });
+        else {
+            for (const k of keys) {
+                result.push({
+                    start: new Date(k).toISOString(),
+                    end: new Date(k + stepMs).toISOString(),
+                    count: buckets.get(k) ?? 0,
+                });
+            }
         }
     }
     // Peak index. -1 when no events at all (every bucket is 0 or the
@@ -329,6 +541,7 @@ export async function computeAuditTimeline(options = {}) {
         total_events: totalEvents,
         peak_index: peakIndex,
         files_scanned: filesScanned,
+        clamped_since: clampedSince,
     };
 }
 /**
@@ -381,10 +594,39 @@ function formatWindowLabel(seconds) {
  */
 export function renderAuditTimeline(result) {
     const lines = [];
-    const windowLabel = formatWindowLabel(result.window.seconds);
+    // Codex round-9 P2 (0.47.0): when auto-clamp fires, the regular
+    // `last <DUR>` header (derived from `window.seconds`) is wrong —
+    // contiguous stale logs would print "last 1d" even though the
+    // newest event was days ago, and sparse clamps would fall back
+    // to "all time". Use a clamp-aware header that describes the
+    // returned shape instead.
     const cadenceLabel = bucketLabel(result.bucket.seconds, result.bucket.raw);
+    let windowLabel;
+    if (result.clamped_since !== null) {
+        windowLabel = `clamped to ~${result.clamped_since} of newest activity`;
+    }
+    else {
+        windowLabel = formatWindowLabel(result.window.seconds);
+    }
     lines.push(`rea audit timeline (${windowLabel}, ${cadenceLabel})`);
     lines.push('─'.repeat(40));
+    // 0.47.0 charter item 2: surface the auto-clamp inline. Operators
+    // scanning the rendered output should immediately see that the
+    // window they got isn't the full audit log. Codex round-8 P2
+    // (0.47.0): `clamped_since` is informational, not reproducible —
+    // `--since=DUR` anchors at `now`, so a clamp anchored at an older
+    // record can't round-trip. Codex round-9 P3 (0.47.0): only a
+    // WIDER `--bucket` actually changes the result — pinning the same
+    // bucket would just re-trigger the clamp. The remediation
+    // suggestion names "wider" explicitly to avoid sending operators
+    // down a no-op retry path.
+    if (result.clamped_since !== null) {
+        lines.push(`note: --since not specified; auto-clamped to newest ${String(MAX_BUCKETS)} buckets ` +
+            `(~${result.clamped_since} span at --bucket=${result.bucket.raw}). ` +
+            `Pass --since=DUR to anchor at now, or rerun with a WIDER --bucket ` +
+            `(current ${result.bucket.raw}) to fit the full log.`);
+        lines.push('');
+    }
     // Codex round-1 P2 (0.46.0): the zero-events case has two distinct
     // shapes and the renderer must NOT collapse them.
     //

package/dist/cli/audit-top-blocks.d.ts

@@ -0,0 +1,154 @@
+/**
+ * `rea audit top-blocks [--since=DUR] [--limit=N] [--json]` — 0.47.0
+ * charter item 3.
+ *
+ * Surface the most recent refusal events from the audit log. Designed
+ * for the question "why was that refused?" — operators see the latest
+ * blocks at a glance with enough context (timestamp, tool, reason) to
+ * grep the offending Bash/Edit/Write call site or fix the policy that
+ * tripped the gate.
+ *
+ * A "refusal" in the rea audit schema is any record whose
+ * `InvocationStatus` is NOT `Allowed` — that's `Denied` (policy
+ * refused) OR `Error` (middleware exception or downstream failure).
+ * Both are interesting to operators debugging "why didn't this run".
+ *
+ * # Walk scope
+ *
+ * Mirrors `audit summary` / `audit by-tool` / `audit timeline`: the
+ * current `.rea/audit.jsonl` PLUS every rotated `audit-…jsonl` segment
+ * is walked regardless of `--since` (the per-record timestamp filter
+ * inside the main loop decides what counts). Rotated filename stamps
+ * mark the rotation INSTANT, not the earliest record contained
+ * (0.41.0 round-3 P2 / 0.42.0 charter item 3) — pruning by filename
+ * would silently drop in-window records from conservatively-rotated
+ * logs. Walking every segment is the only sound shape.
+ *
+ * # Output (default)
+ *
+ *     rea audit top-blocks (last 24h, limit 20)
+ *     ─────────────────────────────────────────
+ *     a1b2c3d4  2026-05-17T12:34:56.789Z  Bash    rm -rf bypass attempted (...)
+ *     deadbeef  2026-05-17T11:20:01.123Z  Write   blocked-path .env write
+ *     …
+ *     total: 4 refusal events in window
+ *     files scanned: 2
+ *
+ * # JSON output
+ *
+ *     {
+ *       "schema_version": 1,
+ *       "since": "24h",
+ *       "limit": 20,
+ *       "window": { "seconds": 86400, "start": "...", "end": "..." },
+ *       "total_matched": 4,
+ *       "events": [
+ *         { "hash": "a1b2c3d4...", "timestamp": "...", "tool": "Bash",
+ *           "status": "denied", "reason": "rm -rf bypass attempted (...)" },
+ *         …
+ *       ],
+ *       "files_scanned": ["/abs/path/.rea/audit.jsonl"]
+ *     }
+ *
+ * `total_matched` is the pre-limit count so dashboards can show "20 of
+ * 47 refusals in window". `events` is sorted newest-first and capped at
+ * `limit`.
+ */
+import type { Command } from 'commander';
+export declare const AUDIT_TOP_BLOCKS_SCHEMA_VERSION = 1;
+/** Default `--limit` value. 20 fits a debugging session's eyeballable window. */
+export declare const DEFAULT_LIMIT = 20;
+/**
+ * Hard ceiling on `--limit`. Refusal events are typically a small slice
+ * of total traffic, but a 1000 cap keeps the renderer / JSON output
+ * bounded under a runaway misconfiguration that's denying everything.
+ */
+export declare const MAX_LIMIT = 1000;
+/**
+ * Thrown when `--limit` is outside [1, MAX_LIMIT] or `--since` fails to
+ * parse. The commander wrapper catches and exits 1. Distinct from
+ * `AuditByToolOptionError` / `AuditTimelineOptionError` so the
+ * caller-facing message names the right flag.
+ */
+export declare class AuditTopBlocksOptionError extends Error {
+    constructor(message: string);
+}
+export interface AuditTopBlocksEvent {
+    /** Full sha256 hash from the audit record — stable cross-tool ID. */
+    hash: string;
+    /** Raw ISO-8601 timestamp from the record. */
+    timestamp: string;
+    /** Tool name as recorded; `(unknown)` for missing/empty. */
+    tool: string;
+    /** Raw `status` value (`denied` / `error`). */
+    status: string;
+    /**
+     * Best-effort human-readable reason. Sourced from the record's
+     * `error` field when present, else a synthesized "<status>: <tool>"
+     * fallback so the row carries SOMETHING informative even when the
+     * middleware didn't attach an error message.
+     */
+    reason: string;
+    /** Session ID from the record; useful for cross-referencing. */
+    session_id: string;
+}
+export interface AuditTopBlocksResult {
+    schema_version: typeof AUDIT_TOP_BLOCKS_SCHEMA_VERSION;
+    /** Raw `--since` value as passed by the caller (`null` when omitted). */
+    since: string | null;
+    /** Resolved `--limit` actually used. */
+    limit: number;
+    window: {
+        seconds: number | null;
+        start: string | null;
+        end: string | null;
+    };
+    /** Pre-limit count of refusal records in window. */
+    total_matched: number;
+    /** Sorted newest-first; capped at `limit`. */
+    events: AuditTopBlocksEvent[];
+    /** Absolute paths of audit files actually read. */
+    files_scanned: string[];
+}
+export interface ComputeAuditTopBlocksOptions {
+    /** Override CWD. Tests set this; production uses `process.cwd()`. */
+    baseDir?: string;
+    /** Raw `--since` value (e.g. `24h`, `7d`). Parsed via parseDuration. */
+    since?: string;
+    /** Raw `--limit` value. Default `DEFAULT_LIMIT`. */
+    limit?: number;
+    /** Test seam — pin "now" for deterministic window calculations. */
+    now?: Date;
+}
+/**
+ * Compute the top-blocks list. Pure (read-only). Throws
+ * `AuditTopBlocksOptionError` on bad `--since` / `--limit`.
+ */
+export declare function computeAuditTopBlocks(options?: ComputeAuditTopBlocksOptions): Promise<AuditTopBlocksResult>;
+/**
+ * Render the result as a human-readable terminal block. JSON callers
+ * bypass this; the rendering is intentionally minimal — a fixed-column
+ * table that scans cleanly in a typical terminal.
+ */
+export declare function renderAuditTopBlocks(result: AuditTopBlocksResult): string;
+export interface RunAuditTopBlocksOptions {
+    since?: string;
+    limit?: number;
+    json?: boolean;
+    /** Test seam — pin "now". */
+    now?: Date;
+}
+/** Commander entrypoint. */
+export declare function runAuditTopBlocks(options: RunAuditTopBlocksOptions): Promise<void>;
+/**
+ * Strict integer parser for the commander `--limit <n>` option.
+ *
+ * Mirrors the `parseTopOption` discipline in `audit-by-tool.ts`:
+ * reject anything that isn't a bare integer so `Number.parseInt`
+ * can't silently truncate (`1.5` → `1`, `10abc` → `10`).
+ */
+export declare function parseLimitOption(raw: string): number;
+/**
+ * Register `rea audit top-blocks` under the `audit` command group.
+ */
+export declare function registerAuditTopBlocksCommand(auditCommand: Command): void;

package/dist/cli/audit-top-blocks.js

@@ -0,0 +1,419 @@
+/**
+ * `rea audit top-blocks [--since=DUR] [--limit=N] [--json]` — 0.47.0
+ * charter item 3.
+ *
+ * Surface the most recent refusal events from the audit log. Designed
+ * for the question "why was that refused?" — operators see the latest
+ * blocks at a glance with enough context (timestamp, tool, reason) to
+ * grep the offending Bash/Edit/Write call site or fix the policy that
+ * tripped the gate.
+ *
+ * A "refusal" in the rea audit schema is any record whose
+ * `InvocationStatus` is NOT `Allowed` — that's `Denied` (policy
+ * refused) OR `Error` (middleware exception or downstream failure).
+ * Both are interesting to operators debugging "why didn't this run".
+ *
+ * # Walk scope
+ *
+ * Mirrors `audit summary` / `audit by-tool` / `audit timeline`: the
+ * current `.rea/audit.jsonl` PLUS every rotated `audit-…jsonl` segment
+ * is walked regardless of `--since` (the per-record timestamp filter
+ * inside the main loop decides what counts). Rotated filename stamps
+ * mark the rotation INSTANT, not the earliest record contained
+ * (0.41.0 round-3 P2 / 0.42.0 charter item 3) — pruning by filename
+ * would silently drop in-window records from conservatively-rotated
+ * logs. Walking every segment is the only sound shape.
+ *
+ * # Output (default)
+ *
+ *     rea audit top-blocks (last 24h, limit 20)
+ *     ─────────────────────────────────────────
+ *     a1b2c3d4  2026-05-17T12:34:56.789Z  Bash    rm -rf bypass attempted (...)
+ *     deadbeef  2026-05-17T11:20:01.123Z  Write   blocked-path .env write
+ *     …
+ *     total: 4 refusal events in window
+ *     files scanned: 2
+ *
+ * # JSON output
+ *
+ *     {
+ *       "schema_version": 1,
+ *       "since": "24h",
+ *       "limit": 20,
+ *       "window": { "seconds": 86400, "start": "...", "end": "..." },
+ *       "total_matched": 4,
+ *       "events": [
+ *         { "hash": "a1b2c3d4...", "timestamp": "...", "tool": "Bash",
+ *           "status": "denied", "reason": "rm -rf bypass attempted (...)" },
+ *         …
+ *       ],
+ *       "files_scanned": ["/abs/path/.rea/audit.jsonl"]
+ *     }
+ *
+ * `total_matched` is the pre-limit count so dashboards can show "20 of
+ * 47 refusals in window". `events` is sorted newest-first and capped at
+ * `limit`.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { listRotatedAuditFiles } from './audit-specialists.js';
+import { AuditSummarySinceError, parseDurationSeconds, } from './audit-summary.js';
+import { AUDIT_FILE, REA_DIR, err } from './utils.js';
+export const AUDIT_TOP_BLOCKS_SCHEMA_VERSION = 1;
+/** Default `--limit` value. 20 fits a debugging session's eyeballable window. */
+export const DEFAULT_LIMIT = 20;
+/**
+ * Hard ceiling on `--limit`. Refusal events are typically a small slice
+ * of total traffic, but a 1000 cap keeps the renderer / JSON output
+ * bounded under a runaway misconfiguration that's denying everything.
+ */
+export const MAX_LIMIT = 1000;
+/** Max characters of refusal reason to display per row before truncation. */
+const REASON_TRUNCATE = 80;
+/** Short-hash prefix length for the displayed event ID. */
+const SHORT_HASH_LEN = 8;
+/**
+ * Thrown when `--limit` is outside [1, MAX_LIMIT] or `--since` fails to
+ * parse. The commander wrapper catches and exits 1. Distinct from
+ * `AuditByToolOptionError` / `AuditTimelineOptionError` so the
+ * caller-facing message names the right flag.
+ */
+export class AuditTopBlocksOptionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuditTopBlocksOptionError';
+    }
+}
+/**
+ * Resolve the audit files to walk. Identical strategy to the sibling
+ * audit commands — inlined to keep the public surface of
+ * `audit-summary.ts` narrow.
+ */
+async function resolveTopBlocksFileWalk(baseDir) {
+    const reaDir = path.join(baseDir, REA_DIR);
+    const currentAudit = path.join(reaDir, AUDIT_FILE);
+    const files = [];
+    const rotated = await listRotatedAuditFiles(reaDir);
+    for (const name of rotated)
+        files.push(path.join(reaDir, name));
+    try {
+        const stat = await fs.stat(currentAudit);
+        if (stat.isFile())
+            files.push(currentAudit);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    return files;
+}
+function parseTimestamp(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/**
+ * Decide whether an audit record represents a refusal. The rea
+ * InvocationStatus enum has three values (`allowed`, `denied`,
+ * `error`); refusals are the non-`allowed` set. We accept any other
+ * string here too so a future status enum extension (or an unusual
+ * consumer-emitted status) surfaces in the report rather than silently
+ * dropping — the operator can decide whether the new bucket is signal
+ * or noise.
+ */
+function isRefusal(status) {
+    if (typeof status !== 'string')
+        return false;
+    return status !== 'allowed';
+}
+/**
+ * Compute the top-blocks list. Pure (read-only). Throws
+ * `AuditTopBlocksOptionError` on bad `--since` / `--limit`.
+ */
+export async function computeAuditTopBlocks(options = {}) {
+    const baseDir = options.baseDir ?? process.cwd();
+    const now = options.now ?? new Date();
+    // Resolve --limit first so a bad value fails fast before any I/O.
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+        throw new AuditTopBlocksOptionError(`--limit: must be an integer between 1 and ${String(MAX_LIMIT)}; got ${JSON.stringify(limit)}.`);
+    }
+    let windowSeconds = null;
+    let windowStart = null;
+    let windowEnd = null;
+    if (options.since !== undefined && options.since.length > 0) {
+        try {
+            windowSeconds = parseDurationSeconds(options.since);
+        }
+        catch (e) {
+            if (e instanceof AuditSummarySinceError) {
+                throw new AuditTopBlocksOptionError(e.message);
+            }
+            throw e;
+        }
+        windowEnd = now;
+        windowStart = new Date(now.getTime() - windowSeconds * 1000);
+    }
+    const files = await resolveTopBlocksFileWalk(baseDir);
+    const filesScanned = [];
+    // Codex round-10 P2 (0.47.0): in a policy-storm scenario (many
+    // refusals, verbose `error` strings) the prior shape accumulated
+    // every match into a flat array, sorted it, then sliced to
+    // `--limit`. Memory + runtime scaled with the total refusal count
+    // — exactly the case `top-blocks` was designed to debug. The
+    // bounded-buffer shape keeps memory O(limit): we maintain a
+    // sorted "top K newest" list of size <= limit and discard the
+    // oldest entry whenever a newer one displaces it. `totalMatched`
+    // counts every in-window refusal so the JSON shape still
+    // communicates "N of M shown".
+    const topBuf = [];
+    let totalMatched = 0;
+    // Insert into the bounded buffer, keeping it sorted newest-first
+    // by parsed instant (with hash tiebreaker for determinism). Drop
+    // the oldest when capacity exceeded.
+    const insertIntoTop = (event, parsedTime) => {
+        // Find insertion point — small linear scan; for limit=20 (the
+        // default) this is cheaper than a heap and keeps the code
+        // simple. For limit=1000 (the max) we're still O(limit) per
+        // insert in the worst case, well under the prior O(N log N)
+        // sort across N matches.
+        let idx = topBuf.length;
+        for (let i = 0; i < topBuf.length; i += 1) {
+            const cur = topBuf[i];
+            if (parsedTime > cur.parsedTime ||
+                (parsedTime === cur.parsedTime && event.hash.localeCompare(cur.event.hash) < 0)) {
+                idx = i;
+                break;
+            }
+        }
+        if (idx < limit) {
+            topBuf.splice(idx, 0, { event, parsedTime });
+            if (topBuf.length > limit)
+                topBuf.length = limit;
+        }
+    };
+    for (const filePath of files) {
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, 'utf8');
+        }
+        catch (e) {
+            const errno = e.code;
+            if (errno === 'ENOENT')
+                continue;
+            // Mirror the sibling audit commands' stance: any non-ENOENT read
+            // error is fatal. A silent skip on a rotated segment that may
+            // contain in-window refusals would let `top-blocks` exit 0 with
+            // the operator's question unanswered.
+            throw new Error(`rea audit top-blocks: cannot read ${filePath} (${errno ?? 'unknown errno'}). ` +
+                `An unreadable audit segment may contain in-window records, so the ` +
+                `refusal report would be silently incomplete. Fix permissions ` +
+                `(e.g. \`chmod u+r ${filePath}\`), or move the file out of \`.rea/\` ` +
+                `if you no longer need it.`);
+        }
+        filesScanned.push(filePath);
+        for (const line of raw.split('\n')) {
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                // Malformed line — `rea audit verify` is the right tool. Skip
+                // so a single corrupt line doesn't tank the report.
+                continue;
+            }
+            if (!isRefusal(parsed.status))
+                continue;
+            const ts = parseTimestamp(parsed.timestamp);
+            if (windowStart !== null && (ts === null || ts < windowStart))
+                continue;
+            if (windowEnd !== null && (ts === null || ts > windowEnd))
+                continue;
+            totalMatched += 1;
+            const tool = typeof parsed.tool_name === 'string' && parsed.tool_name.length > 0
+                ? parsed.tool_name
+                : '(unknown)';
+            const errorText = typeof parsed.error === 'string' && parsed.error.length > 0
+                ? parsed.error
+                : `${typeof parsed.status === 'string' ? parsed.status : 'refused'}: ${tool}`;
+            const event = {
+                hash: typeof parsed.hash === 'string' ? parsed.hash : '',
+                timestamp: typeof parsed.timestamp === 'string' ? parsed.timestamp : '',
+                tool,
+                status: typeof parsed.status === 'string' ? parsed.status : '(unknown)',
+                reason: errorText,
+                session_id: typeof parsed.session_id === 'string' ? parsed.session_id : '',
+            };
+            // Codex round-2 P2 (0.47.0): parse the timestamp before
+            // comparing — `appendAuditRecord` accepts any ISO-8601 shape,
+            // so `2026-05-17T23:00:00+02:00` (= 21:00:00Z, OLDER) would
+            // lex-sort ahead of `2026-05-17T22:30:00Z` (NEWER) under a
+            // string compare.
+            const parsedTime = Date.parse(event.timestamp);
+            insertIntoTop(event, Number.isFinite(parsedTime) ? parsedTime : 0);
+        }
+    }
+    const capped = topBuf.map((entry) => entry.event);
+    return {
+        schema_version: AUDIT_TOP_BLOCKS_SCHEMA_VERSION,
+        since: options.since !== undefined && options.since.length > 0 ? options.since : null,
+        limit,
+        window: {
+            seconds: windowSeconds,
+            start: windowStart !== null ? windowStart.toISOString() : null,
+            end: windowEnd !== null ? windowEnd.toISOString() : null,
+        },
+        total_matched: totalMatched,
+        events: capped,
+        files_scanned: filesScanned,
+    };
+}
+/**
+ * Truncate a reason string to `REASON_TRUNCATE` chars for the human
+ * renderer. JSON consumers get the full string — they can render at
+ * any width.
+ *
+ * Codex round-10 P3 (0.47.0): refusal reasons often contain embedded
+ * newlines (shell stderr, Node stack traces). Writing them straight
+ * into a fixed-width row spills a single event across multiple
+ * terminal lines and breaks the hash/timestamp/tool columns. Collapse
+ * `\r`, `\n`, and tabs to single spaces FIRST, then truncate to the
+ * column width. The JSON path preserves the raw `reason` field so
+ * consumers see the full multiline message.
+ */
+function truncateReason(reason) {
+    const collapsed = reason.replace(/[\r\n\t]+/g, ' ').replace(/  +/g, ' ').trim();
+    if (collapsed.length <= REASON_TRUNCATE)
+        return collapsed;
+    return collapsed.slice(0, REASON_TRUNCATE - 1) + '…';
+}
+/**
+ * Short-hash prefix for the displayed event ID. Falls back to the
+ * full string when it's shorter than the prefix length (degenerate
+ * inputs only — real hashes are always 64 hex chars).
+ */
+function shortHash(hash) {
+    if (hash.length <= SHORT_HASH_LEN)
+        return hash || '(no-hash)';
+    return hash.slice(0, SHORT_HASH_LEN);
+}
+/**
+ * Compact human duration label. Mirrors the sibling audit commands.
+ */
+function formatDurationShort(seconds) {
+    const units = [
+        ['w', 60 * 60 * 24 * 7],
+        ['d', 60 * 60 * 24],
+        ['h', 60 * 60],
+        ['m', 60],
+        ['s', 1],
+    ];
+    for (const [unit, factor] of units) {
+        if (seconds % factor === 0) {
+            return `last ${String(seconds / factor)}${unit}`;
+        }
+    }
+    return `last ${String(seconds)}s`;
+}
+/**
+ * Render the result as a human-readable terminal block. JSON callers
+ * bypass this; the rendering is intentionally minimal — a fixed-column
+ * table that scans cleanly in a typical terminal.
+ */
+export function renderAuditTopBlocks(result) {
+    const lines = [];
+    const windowLabel = result.window.seconds !== null ? formatDurationShort(result.window.seconds) : 'all time';
+    lines.push(`rea audit top-blocks (${windowLabel}, limit ${String(result.limit)})`);
+    lines.push('─'.repeat(40));
+    if (result.total_matched === 0) {
+        lines.push(result.window.seconds !== null
+            ? 'No refusal events in the requested window.'
+            : 'No refusal events in the audit log.');
+        if (result.files_scanned.length === 0) {
+            lines.push('(no audit files found — has `rea serve` ever run?)');
+        }
+        lines.push('');
+        return lines.join('\n');
+    }
+    // Stable column widths for the table:
+    //   short hash (8) + 2  | timestamp (24) + 2 | tool (max in view) + 2 | reason
+    const maxToolLen = result.events.reduce((m, ev) => Math.max(m, ev.tool.length), 4);
+    for (const ev of result.events) {
+        const h = shortHash(ev.hash).padEnd(SHORT_HASH_LEN);
+        const ts = ev.timestamp.padEnd(24); // ISO-8601 with ms is 24 chars
+        const tool = ev.tool.padEnd(maxToolLen);
+        const reason = truncateReason(ev.reason);
+        lines.push(`${h}  ${ts}  ${tool}  ${reason}`);
+    }
+    lines.push('');
+    if (result.total_matched > result.events.length) {
+        lines.push(`total: ${String(result.events.length)} of ${String(result.total_matched)} refusal events shown (--limit=${String(result.limit)})`);
+    }
+    else {
+        lines.push(`total: ${String(result.total_matched)} refusal event${result.total_matched === 1 ? '' : 's'} in window`);
+    }
+    lines.push(`files scanned: ${String(result.files_scanned.length)}`);
+    lines.push('');
+    return lines.join('\n');
+}
+/** Commander entrypoint. */
+export async function runAuditTopBlocks(options) {
+    let result;
+    try {
+        result = await computeAuditTopBlocks({
+            ...(options.since !== undefined ? { since: options.since } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+    }
+    catch (e) {
+        if (e instanceof AuditTopBlocksOptionError) {
+            err(`rea audit top-blocks: ${e.message}`);
+            process.exit(1);
+        }
+        throw e;
+    }
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write(renderAuditTopBlocks(result));
+}
+/**
+ * Strict integer parser for the commander `--limit <n>` option.
+ *
+ * Mirrors the `parseTopOption` discipline in `audit-by-tool.ts`:
+ * reject anything that isn't a bare integer so `Number.parseInt`
+ * can't silently truncate (`1.5` → `1`, `10abc` → `10`).
+ */
+export function parseLimitOption(raw) {
+    if (!/^-?\d+$/.test(raw.trim())) {
+        throw new AuditTopBlocksOptionError(`--limit: expected integer; got ${JSON.stringify(raw)}.`);
+    }
+    const n = Number.parseInt(raw.trim(), 10);
+    if (!Number.isFinite(n)) {
+        throw new AuditTopBlocksOptionError(`--limit: expected integer; got ${JSON.stringify(raw)}.`);
+    }
+    return n;
+}
+/**
+ * Register `rea audit top-blocks` under the `audit` command group.
+ */
+export function registerAuditTopBlocksCommand(auditCommand) {
+    auditCommand
+        .command('top-blocks')
+        .description('Recent refusal events from the audit log — `--limit=N` (default 20, max 1000), `--since=DUR` window filter, `--json` for dashboards. Read-only.')
+        .option('--limit <n>', `cap the rendered / serialized list to the most recent N refusals (default ${String(DEFAULT_LIMIT)}, max ${String(MAX_LIMIT)})`, parseLimitOption)
+        .option('--since <duration>', 'filter to records within the last <duration>. Compact form: <N><unit> where unit is s|m|h|d|w (e.g. 24h, 7d).')
+        .option('--json', 'emit a JSON document instead of the human-readable table')
+        .action(async (opts) => {
+        await runAuditTopBlocks({
+            ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+            ...(opts.since !== undefined ? { since: opts.since } : {}),
+            ...(opts.json === true ? { json: true } : {}),
+        });
+    });
+}

package/dist/cli/index.js

@@ -17,6 +17,7 @@ import { runUpgradeCheck } from './upgrade-check.js';
 import { registerAuditSummaryCommand } from './audit-summary.js';
 import { registerAuditByToolCommand } from './audit-by-tool.js';
 import { registerAuditTimelineCommand } from './audit-timeline.js';
+import { registerAuditTopBlocksCommand } from './audit-top-blocks.js';
 import { registerVerifyClaimCommand } from './verify-claim.js';
 import { err, getPkgVersion } from './utils.js';
 async function main() {
@@ -154,6 +155,10 @@ async function main() {
     // [--since=DUR] [--json]`. Time-bucketed event counts with inline
     // histogram. Useful for spotting activity spikes + cadence patterns.
     registerAuditTimelineCommand(audit);
+    // 0.47.0 charter item 3 — `rea audit top-blocks [--limit=N]
+    // [--since=DUR] [--json]`. Most-recent refusal events (denied/error).
+    // The "why was that refused?" debugging lens.
+    registerAuditTopBlocksCommand(audit);
     // Register `rea hook push-gate` — the stateless pre-push Codex gate
     // called by `.husky/pre-push` and `.git/hooks/pre-push`.
     registerHookCommand(program);

package/dist/config/tier-map.js

@@ -301,6 +301,38 @@ export function reaCommandTier(command) {
                 // Write-tier default. Codex round 3 P2 (2026-05-12).
                 if (sub2 === 'specialists')
                     return Tier.Read;
+                // 0.47.0 codex round-11 P2: the audit-reader trio
+                // (`summary`, `by-tool`, `timeline`, `top-blocks`) all share
+                // the read-only contract — they walk audit.jsonl + rotated
+                // segments and emit aggregations to stdout. The pre-0.47.0
+                // tier-map only downgraded `verify` + `specialists`, leaving
+                // 0.41.0+ readers misclassified as Write under TRUSTED
+                // invocations — which made them unavailable in L0 sessions
+                // run from `/usr/local/bin/rea` or
+                // `/proj/node_modules/.bin/rea` despite being purely
+                // observational. Close the gap for all four readers here.
+                //
+                // 0.47.0 codex round-12 P2 (DELIBERATE NON-FIX): the weak-
+                // trust branch below intentionally returns null for Read-tier
+                // subcommands, including these audit readers. That keeps a
+                // bare `rea audit summary` (PATH-lookup or relative path) at
+                // generic Bash Write, where an attacker who shadowed `rea` on
+                // PATH cannot trick the gateway into downgrading their
+                // payload via a fake subcommand. Consumers needing Read
+                // semantics under L0 use the trusted invocation shapes
+                // (`/usr/local/bin/rea …`, `npx rea …`,
+                // `./node_modules/.bin/rea …`) — same contract as `verify`
+                // and `specialists` since 0.10.x / 0.29.0. The UX gap is
+                // documented in `docs/cli/trust-model.md` (see also the
+                // weak-trust branch comment below).
+                if (sub2 === 'summary')
+                    return Tier.Read;
+                if (sub2 === 'by-tool')
+                    return Tier.Read;
+                if (sub2 === 'timeline')
+                    return Tier.Read;
+                if (sub2 === 'top-blocks')
+                    return Tier.Read;
                 if (sub2 === 'rotate')
                     return Tier.Write;
                 return Tier.Write;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "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)",