@bookedsolid/rea 0.40.0 → 0.42.0

package/MIGRATING.md

@@ -389,6 +389,145 @@ per finding and produces more consistent verdicts — fewer
 same-code-different-verdict round-trips. Trade-off is push-gate
 latency.
 
+## Node-binary hook scanner (added in 0.32.0)
+
+Pre-0.32.0 every `.claude/hooks/*.sh` carried the full gate body in
+bash. Adversarial review consistently caught bash-only edge cases that
+were structurally unfixable in shell — multi-line awk encodings,
+ANSI-C escapes, deep nested-shell decoding. 0.32.0 pivoted the entire
+hook surface to a Node-binary scanner: hooks became thin shims (~20-80
+LOC each) that delegate the actual gate work to `rea hook <name>` —
+which runs the canonical scanner inside `dist/cli/index.js`.
+
+**Consumer impact:**
+
+- Run `pnpm install` (or `npm install`) after upgrading to 0.32.0+ so
+  `dist/cli/index.js` is built and the shims have something to call.
+- `.claude/hooks/*.sh` files on disk are noticeably smaller after
+  `rea upgrade`; this is the canonical post-0.32.0 shape, not a
+  truncation. `rea doctor` will tell you if a shim is the wrong
+  vintage.
+- The audit trail is unchanged: hooks still emit `rea.bash_scan`-class
+  records to `.rea/audit.jsonl` with the same field shape.
+- Performance is materially better — single Node startup per scan
+  instead of an awk/sed pipeline per pattern.
+
+If `rea doctor` reports `policy-reader Tier 1 (rea CLI)` as `warn:
+dist not found`, you skipped the build step. Run `pnpm install`.
+
+## Graceful-degradation policy reader (added in 0.37.0)
+
+The shimmed hooks need to read `.rea/policy.yaml` from a bash context
+that may or may not have python3, jq, or rea's CLI on PATH. 0.37.0
+formalized a 4-tier reader ladder:
+
+1. **Tier 1** — `rea hook policy-get` (requires `dist/cli/index.js`)
+2. **Tier 2** — `python3 + stdlib yaml` (PyYAML) — handles flow-form
+3. **Tier 3** — POSIX `awk` block-form parser (the always-available floor)
+4. **Fail-closed** — every tier unreachable: shim refuses the action
+
+Tier 1 → 2 → 3 fallthrough is silent at hook-runtime; that's
+intentional (graceful degradation), but means an unreachable Tier 1 +
+unreachable Tier 2 can silently downgrade flow-form policy lookups to
+block-form-only. `rea doctor` (0.39.0+) surfaces all three tier
+reachabilities so you can spot the gap.
+
+**Consumer impact:**
+
+- If you use FLOW-form YAML for any policy block (e.g.
+  `blocked_paths: [.env, ".env.*"]`), make sure either the rea CLI
+  dist is present OR `python3 + PyYAML` is installed. With ONLY awk
+  reachable, flow-form lookups silently no-op on every shim
+  fallthrough path and your declared policy isn't enforced.
+- Install PyYAML on CI runners: `pip3 install pyyaml`. On consumer
+  developer machines, it's almost always already present (macOS ships
+  it; major Linux distros bundle it with python3).
+- For list-valued policy keys (`blocked_paths`, `protected_writes`),
+  the loader iterates the resulting JSON via jq OR python3. Have at
+  least one on PATH or `rea doctor` (0.42.0+) will report `fail` on
+  the `policy-reader Tier 3 (awk)` row with a list-walker-specific
+  remediation message.
+
+## Shim runtime extraction (added in 0.38.0)
+
+Cosmetic-only refactor: every `.claude/hooks/*.sh` shim now sources
+`hooks/_lib/shim-runtime.sh` for shared boilerplate (env loading,
+tier classification, audit-event emission). **No consumer action
+required** — the change is byte-equivalent at the gate surface. New
+shims you author can adopt the same runtime by sourcing the shared
+helper; documented in the shim authoring guide.
+
+## Doctor health surfaces for the policy reader (added in 0.39.0)
+
+`rea doctor` gained explicit reachability checks for the 4-tier
+ladder, the dist invokability probe, and a sandbox-containment check
+on the resolved `dist/cli/index.js` path. Output lines you'll see:
+
+- `policy-reader Tier 1 (rea CLI)` — pass/warn based on dist
+  presence + actual invocation
+- `policy-reader Tier 2 (python3 + PyYAML)` — pass/warn based on
+  python3 + import yaml succeeding
+- `policy-reader Tier 3 (awk)` — pass when awk present; warn or
+  fail conditional on whether other tiers cover the gap (0.40.0
+  refined the verdict logic; 0.42.0 hardened the list-walker
+  predicate)
+- `policy-reader effective floor` — summary verdict across all three
+- `policy-reader jq (JSON accelerator)` — info-level, calls out
+  Tier 1/2 perf when jq is absent
+
+**Consumer action:** run `rea doctor` after each upgrade. The lines
+above accurately reflect what your shims will do at runtime — a
+`warn` is not a hard failure but signals a posture worth knowing
+about (e.g. flow-form policy silently no-ops). A `fail` on any tier
+row IS a hard failure that the doctor exits non-zero on.
+
+## Upgrade preview + audit summary (added in 0.41.0)
+
+Two new consumer-facing commands rolled out:
+
+### `rea upgrade --check`
+
+Dry-run preview of what `rea upgrade` would write, file-by-file, with
+unified diffs. JSON output via `--json`. Always exits 0 — this is a
+preview, not a gate. Use it before any non-trivial rea upgrade to
+sanity-check the diff:
+
+```bash
+rea upgrade --check                       # human-readable table + diffs
+rea upgrade --check --json                # machine-readable for CI
+rea upgrade --check --no-diff             # counts + paths only
+```
+
+0.42.0 added the same settings-schema validation that `rea upgrade`
+itself runs — if the merged settings would fail schema parse (typo'd
+hook event, malformed hook command, …), the preview surfaces the
+`WOULD REFUSE` message rather than promising a write the real
+upgrade would refuse. The `settings_validation` field in the JSON
+output carries the structured outcome.
+
+### `rea audit summary`
+
+High-level rollup of the audit log: counts by `tool_name`, `tier`,
+`status`, `session`, the time window covered, and a sample-verified
+chain-integrity check. `--since <duration>` (e.g. `24h`, `7d`, `2w`)
+narrows to a recent window:
+
+```bash
+rea audit summary                         # all time
+rea audit summary --since 24h             # last 24 hours
+rea audit summary --since 7d --json       # last week, JSON
+```
+
+0.42.0 hardened the rotated-file walk: pre-0.42.0 `--since` pruned
+rotated audit segments by filename stamp, which is wall-clock at the
+rotation INSTANT — not the earliest record contained. A rotated file
+from N days ago can contain records from N+M days ago when the
+rotation cycle was long, so pruning by filename silently dropped
+in-window records. Post-0.42.0 the walker reads every rotated file
+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.
+
 ## Policy knobs worth setting
 
 For consumers with a long-running migration branch (>30 commits since

package/README.md

@@ -9,8 +9,13 @@
 [![DCO](https://img.shields.io/badge/DCO-required-green)](https://developercertificate.org/)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
 
-> Status: `0.11.0` — published to npm with SLSA v1 provenance. See
-> [CHANGELOG.md](./CHANGELOG.md) for the per-release history.
+> Status: `0.41.0` — published to npm with SLSA v1 provenance. See
+> [CHANGELOG.md](./CHANGELOG.md) for the per-release history. The
+> hook-port marathon (0.32→0.35) replaced every shell hook body with
+> a Node-binary shim; the bash files in `.claude/hooks/` are now
+> ~30-line stubs that fork `rea hook scan-bash` / `scan-write` for
+> the real work. See [Architecture](#architecture) for the runtime
+> picture.
 
 REA is a single npm package that gates and audits agentic tool calls made by
 Claude Code — shell commands, filesystem writes, and MCP tool invocations —
@@ -38,6 +43,7 @@ the [migration section](#migration-from-010x) below.
 - [Quickstart](#quickstart)
 - [What REA is](#what-rea-is)
 - [What REA is NOT](#what-rea-is-not)
+- [Architecture](#architecture)
 - [The pre-push Codex gate](#the-pre-push-codex-gate)
 - [MCP gateway](#mcp-gateway)
 - [Policy file](#policy-file)
@@ -141,31 +147,39 @@ does not prevent the kill-switch from firing.
 
 ### 3. A hook layer
 
-Eleven shell scripts ship in `hooks/` and are copied into `.claude/hooks/`
-by `rea init`. All eleven are wired into the default `.claude/settings.json`
-and fire on Claude Code's `PreToolUse` / `PostToolUse` events (secret
-scanning, dangerous-command interception, blocked-path enforcement,
-settings protection, attribution rejection, env-file protection,
-disclosure-policy routing, dependency audit, changeset security,
-PR-issue-link advisory, architecture advisory). Each hook uses
-`set -euo pipefail` (or `set -uo pipefail` for stdin-JSON consumers) and
-runs a HALT check near the top. See [Hooks shipped](#hooks-shipped) for
-the full inventory.
-
-**Bash-tier scanner (parser-backed since 0.23.0).** Two hooks —
-`protected-paths-bash-gate.sh` and `blocked-paths-bash-gate.sh` — are
-shims that forward stdin to `rea hook scan-bash`, a CLI subcommand
-that parses the Bash command via `mvdan-sh@0.10.1`, walks the AST,
-and emits a verdict JSON. Pre-0.23.0 these were 500-line bash regex
-pipelines; the rewrite closes 24 known-bypass classes
-(helix-021..023 + discord-ops Round 13 + codex round 1) by replacing
-re-tokenization heuristics with structural matches against the parsed
-argv tree. The other nine hooks remain regex-based bash. The shim
-re-verifies the verdict JSON shape on return so a tampered
-`REA_NODE_CLI` env var cannot bypass. See
+Fourteen hook scripts ship in `hooks/` and are copied into
+`.claude/hooks/` by `rea init`. All fourteen are wired into the default
+`.claude/settings.json` and fire on Claude Code's `PreToolUse` /
+`PostToolUse` events (secret scanning, dangerous-command interception,
+blocked-path enforcement, settings protection, attribution rejection,
+env-file protection, disclosure-policy routing, dependency audit,
+changeset security, PR-issue-link advisory, architecture advisory,
+local-review enforcement, protected-paths + blocked-paths bash-tier
+parity). Each hook performs a HALT check near the top. See
+[Hooks shipped](#hooks-shipped) for the full inventory.
+
+**Node-binary scanners (since 0.32.0).** The hook-port marathon
+(0.32.0 → 0.35.0) replaced every shell hook body with a Node-binary
+shim. The bash files in `.claude/hooks/` are now ~30-line stubs that
+fork `rea hook scan-bash` / `rea hook scan-write` (the AST-walker and
+write-tier scanner respectively) and re-verify the verdict JSON shape
+on return — a tampered `REA_NODE_CLI` env var cannot bypass. The
+parser-tier walker (`mvdan-sh@0.10.1`) handles Bash AST grammar
+exhaustively; the write-tier scanner handles `Write`/`Edit`/
+`MultiEdit`/`NotebookEdit` payloads against the same policy. See
 [`docs/architecture/bash-scanner.md`](docs/architecture/bash-scanner.md)
-for the AST-walker design and [`docs/migration/0.23.0.md`](docs/migration/0.23.0.md)
-for consumer migration notes.
+and [`docs/migration/0.23.0.md`](docs/migration/0.23.0.md) for the
+walker design and consumer migration notes.
+
+**Four-tier policy reader.** The shim infrastructure honors a
+four-tier ladder when loading policy (`hooks/_lib/policy-reader.sh`):
+Tier 1 is `rea hook policy-get` (the dist CLI), Tier 2 is
+`python3 + PyYAML`, Tier 3 is `awk` (block-form only), and an
+optional `jq` accelerator for JSON walks. `rea doctor` probes every
+tier and surfaces which one(s) are reachable in the operator's
+environment — pre-0.39.0 a stale dist + missing PyYAML would
+silently no-op flow-form policy when `awk` was the only working
+tier. See `Self-validation` below.
 
 The hook layer runs independently of the MCP gateway — bypassing one does
 not disable the other. That redundancy is intentional.
@@ -220,6 +234,71 @@ The non-goals are the product.
 
 ---
 
+## Architecture
+
+REA ships as a single npm package that delivers five runtime surfaces:
+
+1. **Node-binary CLI** (`dist/cli/index.js`) — the `rea` command, with
+   subcommands for install (`init`/`upgrade`), runtime
+   (`serve`/`check`/`status`/`doctor`), kill-switch (`freeze`/
+   `unfreeze`), audit (`rotate`/`verify`/`summary`/`specialists`),
+   review (`review`/`preflight`/`hook push-gate`), and hook
+   evaluation (`hook scan-bash`/`scan-write`/`policy-get`).
+2. **Shell hook shims** (`hooks/*.sh` → `.claude/hooks/*.sh`) — ~30
+   lines apiece. Each shim performs a HALT check, then forks the
+   corresponding `rea hook scan-*` Node CLI for the real verdict.
+   Pre-0.32.0 these were 500+ line bash regex pipelines; the rewrite
+   closed 24 known bypass classes and removed the bash hot-path
+   entirely. The shims still ship as bash so Claude Code's hook
+   matcher (which spawns sh) works without a Node prerequisite at
+   hook-fire time — the Node CLI is invoked from inside.
+3. **Husky hooks** (`.husky/commit-msg`, `.husky/pre-push`,
+   `.husky/prepare-commit-msg`) — written by `rea init`. Pre-push
+   runs `rea hook push-gate` (stateless Codex review). Commit-msg
+   blocks AI attribution and DCO violations. Prepare-commit-msg
+   optionally appends a `Co-Authored-By:` trailer when configured.
+   Extension surfaces in `.husky/{commit-msg,pre-push}.d/*` are
+   sourced after rea's body for layering commitlint, lint-staged,
+   etc.
+4. **MCP gateway** (`rea serve`) — a stdio MCP server started by
+   Claude Code via `.mcp.json`. Proxies downstream MCPs declared in
+   `.rea/registry.yaml` through a fixed middleware chain (audit,
+   kill-switch, tier, policy, blocked-paths, rate-limit, breaker,
+   injection, redact, size-cap). See [MCP gateway](#mcp-gateway).
+5. **Four-tier policy reader** (`hooks/_lib/policy-reader.sh`) — the
+   shared helper that bash shims use to read `.rea/policy.yaml`.
+   Tier 1 calls `rea hook policy-get` (full YAML semantics). Tier 2
+   falls back to `python3 + PyYAML` when the CLI is unreachable.
+   Tier 3 falls back to `awk` for the block-form subset. `jq` is an
+   optional JSON accelerator. Each tier downgrades silently to the
+   next; `rea doctor` probes the ladder explicitly so operators see
+   exactly which tier(s) work in their environment.
+
+### Self-validation
+
+`rea doctor` validates every install surface in one shot:
+
+- `.rea/policy.yaml` parses against the strict zod schema
+- `.rea/` directory layout (HALT, registry, fingerprints, audit log)
+- `.claude/settings.json` schema + every shipped hook registered
+- `.husky/commit-msg`, `.husky/pre-push`, `.husky/prepare-commit-msg`
+  exist + have the expected marker, with husky-9 stub indirection
+  followed transparently
+- `codex` binary on `PATH` when `policy.review.codex_required: true`
+- Per-tier policy reader probe (`rea hook policy-get` → `python3 +
+  PyYAML` → `awk` → optional `jq`) so silent flow-form no-ops are
+  caught at install time, not at first hook fire
+- Optional `--smoke` drives the real delegation-capture hook
+  end-to-end (writes a probe audit record + verifies chain integrity)
+- Optional `--drift` reports per-file SHA drift vs. the install
+  manifest without mutating
+- `--strict` promotes settings-schema warnings to hard fail (for CI)
+
+This repo dogfoods every check — see `.rea/` and `.claude/` in the
+checkout for the canonical `bst-internal` profile layout.
+
+---
+
 ## The pre-push Codex gate
 
 The 0.11.0 gate is stateless. Every `git push` runs Codex on the diff, and
@@ -864,12 +943,27 @@ Sync `.claude/`, `.husky/`, and managed fragments with this rea version.
 Prompts on drift; silently refreshes unmodified files.
 
 ```bash
-rea upgrade --dry-run   # show what would change; write nothing
-rea upgrade             # interactive
-rea upgrade -y          # non-interactive, keep drifted files
-rea upgrade --force     # non-interactive, overwrite drift
+rea upgrade --dry-run            # rehearse the interactive flow; write nothing
+rea upgrade --check              # structured preview + unified diffs (0.41.0)
+rea upgrade --check --json       # machine-readable preview document
+rea upgrade --check --no-diff    # paths + counts only (large repos)
+rea upgrade                      # interactive
+rea upgrade -y                   # non-interactive, keep drifted files
+rea upgrade --force              # non-interactive, overwrite drift
 ```
 
+`--check` and `--dry-run` are distinct:
+
+- `--dry-run` rehearses the full interactive flow with writes
+  suppressed (prompts still fire, output streams in classification
+  order). Useful locally to walk through the same prompts you'd see
+  during a real upgrade.
+- `--check` is the structured, non-interactive preview: emits a
+  summary table + unified diffs per modified file, exits 0
+  regardless of what would change. The shape mirrors
+  `terraform plan` / `npm install --dry-run` — wire it into CI to
+  surface the changes an upgrade PR would produce.
+
 ### `rea serve`
 
 Start the MCP gateway. Invoked by Claude Code via `.mcp.json`; not a
@@ -908,27 +1002,50 @@ rea status --json   # pipe to jq
 
 ### `rea doctor`
 
-Validate the install — policy parses, `.rea/` layout, hooks, Codex plugin
-presence, TOFU fingerprint store.
+Validate the install — policy parses, `.rea/` layout, hooks, Codex
+plugin presence, TOFU fingerprint store, husky stub indirection,
+and the four-tier policy reader ladder (`rea hook policy-get` → 
+`python3 + PyYAML` → `awk` → optional `jq`).
 
 ```bash
 rea doctor
 rea doctor --metrics   # also print 7-day Codex telemetry summary
 rea doctor --drift     # report drift vs. install manifest (read-only)
+rea doctor --smoke     # exercise delegation-capture hook end-to-end
+rea doctor --strict    # 0.30.0 — promote settings-schema warnings to fail
 ```
 
-In non-git directories the commit-msg and pre-push checks are skipped
-cleanly. Audit hash-chain integrity is verified by `rea audit verify`,
-not by `rea doctor`.
+In non-git directories the commit-msg and pre-push checks are
+skipped cleanly. Audit hash-chain integrity is verified by `rea
+audit verify`, not by `rea doctor`. Each policy-reader tier is
+probed independently so silent flow-form no-ops (e.g. stale dist +
+missing PyYAML, with awk handling block-form only) surface at
+install time instead of at first hook fire.
 
-### `rea audit rotate` / `rea audit verify`
+### `rea audit rotate` / `rea audit verify` / `rea audit summary` / `rea audit specialists`
 
 ```bash
 rea audit rotate                      # force rotation now
 rea audit verify                      # re-hash the chain; exit 1 on first tamper
 rea audit verify --since <file>       # walk forward from a rotated file
+
+rea audit summary                     # 0.41.0 — counts by tool/tier/session/status
+rea audit summary --since 24h         # filter to last 24h (units: s/m/h/d/w)
+rea audit summary --since 7d --json   # machine-readable rollup for jq
+
+rea audit specialists                 # delegation-telemetry roll-up
+rea audit specialists --session all   # show every session (default: $CLAUDE_SESSION_ID)
+rea audit specialists --since <file>  # extend the walk through rotated files
 ```
 
+`rea audit summary` is the high-level overview reader: total events,
+counts grouped by `tool_name` / tier / status / session, the time
+window covered, and a sample-verified chain-integrity check. Note
+that `--since` for `summary` is a duration (`24h`, `7d`) — distinct
+from `--since <rotated-file>` on `verify` / `specialists` which
+anchors on a rotated-audit basename. Use `rea audit verify` for the
+rigorous per-record re-hash; `summary` only samples.
+
 ### `rea tofu list` / `rea tofu accept`
 
 ```bash

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

@@ -0,0 +1,160 @@
+/**
+ * `rea audit summary` — high-level audit-log overview (0.41.0).
+ *
+ * The audit log is rich and `rea audit specialists` already exists for
+ * one narrow event-class. `rea audit summary` complements it with a
+ * broad rollup: total events, counts by `tool_name`, by tier, by
+ * session, by status, the time window covered, and a sample-verified
+ * chain-integrity check.
+ *
+ * # Filtering
+ *
+ * `--since <duration>` accepts a compact duration string
+ * (`s`/`m`/`h`/`d`/`w`) and filters records by `timestamp >= now -
+ * duration`. Examples: `24h`, `7d`, `90m`, `2w`. This is DIFFERENT
+ * from `rea audit verify --since <file>` / `rea audit specialists
+ * --since <file>` which take a rotated-file ANCHOR, not a duration —
+ * the two `--since` semantics serve different needs (anchor for chain
+ * walks, duration for summarization) and we accept the surface area
+ * cost. The duration form is what consumers reach for when asking
+ * "what happened in the last day?".
+ *
+ * # Chain integrity
+ *
+ * `rea audit verify` does the rigorous per-record re-hash. `summary`
+ * samples up to `CHAIN_SAMPLE_SIZE` records, evenly spaced through
+ * the filtered window, and reports `ok` / `tampered` / `unsampled`
+ * (window empty). Operators who suspect tampering should still run
+ * `rea audit verify` for an authoritative answer.
+ *
+ * # JSON output
+ *
+ *     {
+ *       "schema_version": 1,
+ *       "window_seconds": 86400,
+ *       "window_start": "2026-05-15T13:42:00Z",
+ *       "window_end":   "2026-05-16T13:42:00Z",
+ *       "files_scanned": ["/abs/path/.rea/audit.jsonl"],
+ *       "total_events": 1247,
+ *       "by_tool_name": { "Bash": 612, "Edit": 289, … },
+ *       "by_tier":      { "read": 683, "write": 416, "destructive": 148 },
+ *       "by_status":    { "allowed": 1242, "denied": 5, "error": 0 },
+ *       "by_session":   { "session-abc…": 312, "session-def…": 935 },
+ *       "session_count": 8,
+ *       "earliest_timestamp": "2026-05-15T13:43:01.103Z",
+ *       "latest_timestamp":   "2026-05-16T13:41:57.842Z",
+ *       "chain_integrity": "ok",
+ *       "chain_samples_verified": 12
+ *     }
+ *
+ * # Walk scope
+ *
+ * v1 walks the current `.rea/audit.jsonl` plus EVERY rotated file
+ * whose latest record falls within the window. Older rotated files
+ * are skipped — they cannot contain in-window records. When `--since`
+ * is omitted, no time filter is applied and the walk covers the
+ * current `audit.jsonl` only (operators wanting historical depth
+ * should pass `--since <DUR>`).
+ */
+import type { Command } from 'commander';
+export declare const AUDIT_SUMMARY_SCHEMA_VERSION = 1;
+/** Hard cap on chain-integrity samples. Keeps `rea audit summary`
+ *  fast even on large logs while still surfacing obvious tampering. */
+export declare const CHAIN_SAMPLE_SIZE = 12;
+/**
+ * Thrown by `computeAuditSummary` when `--since` cannot be parsed.
+ * The commander wrapper exits 1.
+ */
+export declare class AuditSummarySinceError extends Error {
+    constructor(message: string);
+}
+/** Three-state classification for chain integrity. */
+export type ChainIntegrity = 'ok' | 'tampered' | 'unsampled';
+export interface AuditSummaryResult {
+    schema_version: typeof AUDIT_SUMMARY_SCHEMA_VERSION;
+    /** Window length in seconds. `null` when no `--since` filter was set. */
+    window_seconds: number | null;
+    /** Inclusive window start. `null` when no filter; otherwise the
+     *  computed cutoff (now - duration). */
+    window_start: string | null;
+    /** Window end — always `now` when filter is set; `null` otherwise. */
+    window_end: string | null;
+    /** Absolute paths of audit files walked. */
+    files_scanned: string[];
+    /**
+     * 0.42.0 codex round 4 P2 + round 6 P2 (2026-05-16) — reserved for
+     * future use; ALWAYS EMPTY in 0.42.0. The original intent (round 4)
+     * was to soft-skip rotated segments that the operator could not
+     * read (e.g. EACCES/EPERM after a backup restore). Round 6 showed
+     * the soft-skip was unsound: without per-segment time-range
+     * metadata we cannot prove a skipped file is out-of-scope for the
+     * `--since` window, so a silent skip risks an undercount + a
+     * misleading `chain_integrity: ok`. The current implementation
+     * therefore throws on any non-ENOENT read error; this field is
+     * kept in the public schema so a future release that ships
+     * per-segment time-range metadata can populate it without breaking
+     * JSON consumers.
+     */
+    unreadable_segments: string[];
+    total_events: number;
+    by_tool_name: Record<string, number>;
+    by_tier: Record<string, number>;
+    by_status: Record<string, number>;
+    by_session: Record<string, number>;
+    session_count: number;
+    /** Earliest in-window `timestamp` seen. `null` when no records. */
+    earliest_timestamp: string | null;
+    /** Latest in-window `timestamp` seen. `null` when no records. */
+    latest_timestamp: string | null;
+    chain_integrity: ChainIntegrity;
+    /** Number of samples actually verified. Always `<= CHAIN_SAMPLE_SIZE`. */
+    chain_samples_verified: number;
+}
+export interface ComputeAuditSummaryOptions {
+    /** Override CWD. Tests set this; production uses `process.cwd()`. */
+    baseDir?: string;
+    /** Raw `--since` value (e.g. `24h`, `7d`). Parsed via parseDuration. */
+    since?: string;
+    /** Test seam — pin "now" for deterministic window calculations. */
+    now?: Date;
+}
+/**
+ * Parse a compact duration string into seconds. Accepts:
+ *
+ *   - `<N>s` — seconds
+ *   - `<N>m` — minutes
+ *   - `<N>h` — hours
+ *   - `<N>d` — days
+ *   - `<N>w` — weeks (7 days)
+ *
+ * `N` must be a positive integer with no whitespace. Returns the
+ * number of seconds; throws `AuditSummarySinceError` on parse failure.
+ *
+ * We deliberately do not accept bare numbers (would be ambiguous) or
+ * fractional units (no real use case; complicates rendering).
+ */
+export declare function parseDurationSeconds(raw: string): number;
+/**
+ * Compute the summary. Pure (read-only). Throws
+ * `AuditSummarySinceError` on bad `--since`; everything else is
+ * surfaced via the result.
+ */
+export declare function computeAuditSummary(options?: ComputeAuditSummaryOptions): Promise<AuditSummaryResult>;
+/**
+ * Render the result as a human-readable terminal block. Designed for
+ * the default `rea audit summary` invocation; `--json` callers bypass
+ * this entirely.
+ */
+export declare function renderAuditSummary(result: AuditSummaryResult): string;
+export interface RunAuditSummaryOptions {
+    since?: string;
+    json?: boolean;
+    /** Test seam — pin "now". */
+    now?: Date;
+}
+/** Commander entrypoint. */
+export declare function runAuditSummary(options: RunAuditSummaryOptions): Promise<void>;
+/**
+ * Register `rea audit summary` under the `audit` command group.
+ */
+export declare function registerAuditSummaryCommand(auditCommand: Command): void;