@bookedsolid/rea 0.46.0 → 0.48.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
@@ -573,3 +662,91 @@ verdict that triggered it is.
   document the ambivalence.
 - **My pre-commit hook breaks on push** → not rea (rea ships no
   pre-commit). Fix in your repo.
+
+## Shim session-cache (added in 0.48.0)
+
+Every Node-binary shim (`.claude/hooks/*.sh`) does three steps that
+do not change across same-session same-CLI fires:
+
+1. Resolve the rea CLI through the fixed 2-tier sandboxed order
+   (`node_modules/@bookedsolid/rea/dist/cli/index.js`, then
+   `./dist/cli/index.js`).
+2. Sandbox-check the resolved CLI (realpath inside project + ancestor
+   `package.json` with `name: @bookedsolid/rea` + optional
+   `dist/cli/index.js` shape enforcement).
+3. Version-probe via `rea hook <NAME> --help` to confirm the
+   subcommand exists in the resolved CLI.
+
+The 0.48.0 per-session cache (`hooks/_lib/shim-cache.sh`) records
+the answers under a key composed of `(session_token, project_realpath,
+cli_realpath, cli_mtime, cli_size_bytes, euid, enforce_cli_shape,
+shim_name, pkg_mtime, pkg_size_bytes, dist_dir_mtime, node_realpath,
+node_mtime)`. Subsequent
+fires that match the same key skip both the sandbox check (step 5
+in `shim_run`) and the version probe (step 8). Cache hit latency is
+roughly the cache-read cost (~5-10ms) instead of the full hot path
+(~80-150ms on macOS).
+
+### Disable switches
+
+- `REA_SHIM_CACHE=0` in env disables both reads and writes for the
+  current process. `pnpm perf:hooks` sets this automatically so
+  baseline measurements reflect the uncached path.
+- `policy.shim_cache.enabled: false` disables the cache via
+  `.rea/policy.yaml`:
+  ```yaml
+  shim_cache:
+    enabled: false
+  ```
+  Default is `enabled: true`. The block is optional — a vanilla
+  install with no `shim_cache:` block gets the cache on.
+
+### Where the cache lives
+
+`$TMPDIR/rea-shim-cache.<euid>/<key>.json` — per-user `0700`
+directory, per-entry `0600` file. Entries are atomically written
+via `mv` from `.tmp.$$` (no half-written reads). On reboot the
+tmpfs is wiped — there is no cross-session persistence by design.
+
+### Invalidation
+
+Cache entries are invalidated automatically when any of the key
+fields change. The most common triggers:
+
+- `pnpm install` / `npm install` updates the CLI mtime + size →
+  cache key differs → next fire takes the full path and writes a
+  fresh entry.
+- Hard 3600s (1h) TTL ceiling enforced inside `shim_run` even when
+  mtime + size match — bounds staleness on long-lived sessions.
+- Schema version bump (future `v2`) → every `v1` entry becomes a
+  cache-miss (no migration).
+- Cross-user read attempts refused via owner check.
+
+### Forcing a cache rebuild
+
+Use the env var or wipe the directory:
+
+```bash
+# One invocation, uncached
+REA_SHIM_CACHE=0 git commit -m "..."
+
+# Wipe the entire cache for the current user
+rm -rf "$TMPDIR/rea-shim-cache.$(id -u)"
+```
+
+There is intentionally no `rea cache clear` CLI in 0.48.0 — the
+env-var and rm patterns handle the realistic cases without adding
+surface area.
+
+### Why this matters
+
+Before 0.48.0 every shim fire paid the full sandbox + probe cost on
+every Bash/Edit/Write/MultiEdit/NotebookEdit tool call. With 8+
+hooks firing per Bash event, the cumulative latency was felt by the
+operator on every single command. The cache brings warm-session
+hot-path latency down to roughly the cache-read overhead, which is
+the dominant cost ceiling that motivated 0.45.0's profiling work.
+
+See `docs/shim-session-cache-design.md` for the security contract
+and `docs/hook-perf-baseline.md` §"Per-session shim cache and the
+baseline" for the perf methodology note.

package/THREAT_MODEL.md

@@ -1277,3 +1277,143 @@ The bash gate explicitly does NOT defend against:
   to an attacker binary on PATH, the gate is defeated. Production
   deployments pin PATH via the harness; `rea doctor` verifies PATH
   integrity at install time but does not enforce it at runtime.
+
+---
+
+## 9. Per-session shim cache (0.48.0+)
+
+The `hooks/_lib/shim-cache.sh` helper sits between the relevance
+pre-gate and the sandbox check inside `hooks/_lib/shim-runtime.sh`.
+On a cache HIT it short-circuits steps 5 (sandbox check) and 8
+(version probe) — those answers were validated when the entry was
+written, the cache key invalidates if any field changes, and the
+entry has a 3600-second TTL. On a cache MISS, corrupt file, or any
+error condition, the runtime falls through to the existing uncached
+hot path. The cache is an **optimization, not a security boundary**.
+
+### 9.1 Cache key construction
+
+The cache key is `sha256(NUL-joined-tuple)[0:32]` of:
+
+  1. `schema_version` (`"v1"`)
+  2. `session_token` (claude-ancestor PID+start-time hash, or
+     tty/login-shell/boot-id fallback, or "cache disabled" if
+     neither is derivable)
+  3. `project_root_realpath` (post-symlink-resolution)
+  4. `cli_realpath` (post-symlink-resolution)
+  5. `cli_mtime` (nanosecond precision uniformly across macOS and
+     Linux — see §9.4 for the portability rationale; closes the
+     same-second-same-size rebuild class flagged by codex round-2)
+  6. `cli_size_bytes` (defeats `touch -r` mtime-preserving swap)
+  7. `euid` (refuses cross-user reuse)
+  8. `SHIM_ENFORCE_CLI_SHAPE` (whether the `dist/cli/index.js`
+     shape was required for this fire)
+  9. `SHIM_NAME` (0.48.0 codex round-1 P1 — hook-scoped key prevents
+     a cache-warm shim letting a sibling skip its own probe)
+ 10. `pkg_mtime` + `pkg_size` of the ancestor `package.json` the
+     sandbox check found (codex round-3 P2 — same-session edit /
+     rename of that file invalidates the entry)
+ 11. `dist_mtime` of `dist/cli/` directory (codex round-3 P1 — a
+     same-session rebuild that adds/removes ANY file in that
+     directory invalidates the entry, the dominant signal for the
+     rea-dev workflow where `tsc` rewrites many siblings of
+     `index.js`)
+ 12. `node_realpath` + `node_mtime` (codex round-4 P1 — a
+     same-session `nvm use` / `volta pin` / PATH-prepended wrapper
+     that swaps the node interpreter invalidates the entry; warm
+     hits otherwise would skip both node-availability AND the
+     version probe and forward through a different interpreter
+     whose JS engine version may not match what the probe
+     validated)
+
+### 9.2 Storage discipline
+
+  - Per-user directory at `$TMPDIR/rea-shim-cache.<euid>/`, created
+    mode `0700` via `umask 077`. Reads refuse if mode is wider or
+    owner != euid.
+  - Per-entry file at `<dir>/<key>.json`, written mode `0600` via
+    atomic `mv` from `.tmp.$$`. Reads refuse if mode is wider or
+    owner != euid.
+  - JSON entry shape includes `schema_version`, `cli_realpath`,
+    `cli_mtime`, `cli_size_bytes`, `pkg_mtime`, `pkg_size_bytes`,
+    `dist_mtime`, `node_realpath`, `node_mtime`, `sandbox_ok`,
+    `shape_ok`, `cached_at_unix`, `ttl_seconds`. Any unknown / missing
+    required
+    field → ignore entry. Schema version bump → all v(n-1) entries
+    become unreadable cache-misses (no migration).
+
+### 9.3 Attack enumeration
+
+| # | Attack | Defense |
+|---|--------|---------|
+| 1 | Symlink swap of cached CLI between cache-write and cache-read | `cli_realpath` recomputed at every read and compared to entry; any drift → miss |
+| 2 | Two concurrent projects sharing `$TMPDIR` | `project_root_realpath` in key + per-user `0700` dir; cross-project read produces different key |
+| 3 | Cache file race on parallel hook fires | One file per key; identical inputs produce identical content; atomic `mv` from `.tmp.$$` ensures no partial reads |
+| 4 | Cross-user TOCTOU (other local user plants entry) | `0700` dir + `0600` file + owner check refuse foreign-owned reads |
+| 5 | mtime-preserving binary swap (attacker `touch -r`s after replacing CLI) | `cli_size_bytes` in key; size change forces miss even with preserved mtime |
+| 6 | Cached `sandbox_ok=true` after consumer moves project | `project_root_realpath` in key; CLAUDE_PROJECT_DIR drift → different key |
+| 7 | Schema rollback (older shim reads newer entry) | `schema_version` in key; cross-version reads miss cleanly |
+| 8 | Stale cache during a 0.x → 0.y upgrade mid-session | `cli_version` field + `cli_mtime` (ns precision) + `cli_size_bytes` — three independent invalidators |
+| 8b | Rebuild within the same wall-clock second + same byte length | `cli_mtime` recorded at nanosecond precision (codex round-2 P2) — APFS / ext4 / xfs all store ns mtime; a same-second rebuild moves the ns suffix so the key differs |
+| 9 | Long-lived session accumulating staleness past acceptable bound | Hard 3600s TTL enforced inside `shim-runtime.sh` even if mtime+size match |
+| 10 | Session-token spoofing on stripped containers (no `/proc`, no `ps -o lstart=`) | Final fallback is **cache disabled** (return 1), NOT "use PPID alone" — the contract is never silently weakened |
+| 11 | Same-session rebuild of CLI's hook surface that does not touch `dist/cli/index.js` itself (codex round-3 P1) | `dist_mtime` of the parent dir in the key — any add/remove in `dist/cli/` shifts the dir mtime and invalidates every entry under that CLI |
+| 12 | Same-session edit of the ancestor `package.json` that the sandbox check trusted (codex round-3 P2) | `pkg_mtime` + `pkg_size_bytes` in the key — any change forces a fresh sandbox + probe pass |
+| 13 | Same-session `node` interpreter swap (nvm use / volta pin / PATH-prepended wrapper) (codex round-4 P1 + round-7 P2) | `node_realpath` is derived from `process.execPath` (node's own path to itself), NOT from resolving the PATH-visible `node`. Stable version-manager shims like `~/.volta/bin/node` resolve to themselves; only `execPath` reveals which concrete Node binary the shim launched (e.g. `~/.volta/tools/image/node/22.x.x/bin/node`). Swapping versions changes execPath → different key |
+| 14 | Same-session rebuild that rewrites any module in `dist/**/*.js` without changing dist/cli/ — including transitively imported files like `dist/hooks/**`, `dist/policy/**`, `dist/audit/**` (codex round-5 P1 + round-9 P1) | `dist_mtime` is a sha256 of every `*.js` file's `ns-mtime / size / name` across the WHOLE dist tree (not just dist/cli/), built via `find -exec stat +` for ~15ms total cost. Any in-place rewrite of any imported module invalidates the entry. Falls back to single-dir mtime if `find`/`stat`/`shasum`/`sha256sum` are all unavailable. Hasher detection: `shasum -a 256` on macOS, `sha256sum` on GNU coreutils Linux (codex round-6 P2) |
+| 15 | Cache silently disabled on non-interactive subprocess launches (CI, vitest spawn, editor wrappers) where no claude/claude-code ancestor exists AND stdin is piped (codex round-6 P1) | Intermediate fallback: `(PPID basename + PPID start_time + boot_id)`. NOT "PPID alone" — start-time defeats PID reuse across reboots, boot-id confines to the current boot. Scopes the cache to "this specific parent process invocation, on this boot". A different parent / a reboot → different token |
+| 16 | Cache silently disabled on sandboxed macOS / locked-down CI where `/proc` is absent AND `ps`/`sysctl` are denied (codex round-8 P1) | Final fallback before disabled: `(euid + REA_ROOT)`. Coarser session scope than the process-anchored paths above, but cache poisoning still prevented by the per-user 0700 dir + 0600 file (foreign-owned reads refused) and cross-install reuse still prevented by REA_ROOT in the token PLUS every other key field (project, CLI mtime, dist hash, node execPath). The trade-off honors the spirit of design memo concern #2 (NEVER PPID alone) while letting the cache function in environments where the design's primary anchors are unavailable. Truly hostile environments (no euid AND no REA_ROOT) still fall through to "cache disabled" |
+
+### 9.4 Portability — mtime precision
+
+macOS supports fractional-second mtime via `stat -f %Fm`; GNU
+coreutils supports the same via `stat -c %.Y`. Both produce the
+same `1779052861.082677123` string shape — string-equal across
+platforms for the same physical mtime. **Both are used** at
+nanosecond precision (codex round-2 P2 closure). The design memo
+concern #1 was conditional ("if you can't get ns on one platform,
+downgrade both") — since both CAN, we use ns and close the
+same-second-same-size rebuild collision class.
+
+`cli_size_bytes` remains in the key as defense-in-depth for
+filesystems that truncate nanosecond mtime to seconds (some
+FAT/NTFS mounts). On those filesystems the same-second-same-size
+rebuild would still hit the cache for up to 3600s — the TTL is the
+backstop, plus `pnpm install` typically changes the file size.
+The realistic exposure is "consumer runs `npm run build` twice
+within the same wall-clock second on a FAT volume" which is a
+corner case for a dev tool.
+
+### 9.5 Disable switches
+
+  - `REA_SHIM_CACHE=0` in env disables both reads and writes. Used
+    by `pnpm perf:hooks` so steady-state measurements reflect the
+    uncached hot path (a warmed cache would silently mask
+    regressions in the underlying resolve / sandbox / probe layers).
+  - `policy.shim_cache.enabled: false` disables the cache via the
+    policy file. The bash-tier helper consults this via a narrow
+    inline YAML grep (the cache runs BEFORE the canonical 4-tier
+    policy reader is available). The zod schema in
+    `src/policy/loader.ts` validates the field at CLI load time so
+    typos / wrong types are caught at the load boundary.
+
+### 9.6 Out of scope
+
+The cache explicitly does NOT defend against:
+
+  - **A poisoned cache entry that happens to collide with a
+    legitimate key.** The 32-hex-char (128-bit) key space and the
+    fail-safe validate-on-read pass (mtime/size/realpath rechecked
+    against disk, JSON shape verified, TTL enforced) make this
+    economically infeasible without already having euid + tmpdir
+    write access — which is a higher privilege than the gate
+    protects against to begin with.
+  - **An attacker with the same euid who has already compromised
+    the shim runtime.** At that point the cache layer is moot —
+    every code path is attacker-controlled.
+  - **A long-running session where the operator wants to force a
+    cache rebuild without the TTL expiring.** Set `REA_SHIM_CACHE=0`
+    in the env, or `rm -rf $TMPDIR/rea-shim-cache.$(id -u)/`. There
+    is intentionally no `rea cache clear` CLI surface in 0.48.0 —
+    the disable switch + on-reboot tmpfs wipe handle the realistic
+    cases.

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