@bookedsolid/rea 0.44.0 → 0.45.0

package/dist/cli/init.d.ts

@@ -60,28 +60,65 @@ export interface ResolvedConfig {
     reagentNotices: string[];
 }
 /**
- * 0.44.0 charter item 1: derive the canonical hook filename set the
- * installer will lay down. Union of:
- *
- *   - `EXPECTED_HOOKS` (the doctor's required-on-disk list — source of
- *     truth for "what `.claude/hooks/` must contain after install").
- *   - The `command` paths of every entry in `defaultDesiredHooks()`
- *     (the source of truth for "what `.claude/settings.json` registers
- *     with Claude Code"). Each command path ends in
- *     `.claude/hooks/<name>.sh`; we extract `<name>.sh` so the result
- *     joins cleanly with `EXPECTED_HOOKS`.
- *
- * Pre-0.44.0 `buildInstallSummary` hard-coded a hook count / list. If
- * a new hook was added to `EXPECTED_HOOKS` (e.g. `delegation-advisory`
- * was promoted in 0.36.0) or registered in `defaultDesiredHooks()`
- * without anyone touching the summary, the operator's confirm screen
- * silently lied about what was about to be installed. This helper
- * means the summary now tracks the real installer surface — adding
- * a hook to either canonical source automatically updates the screen.
+ * 0.45.0 charter item 2 — derive the canonical hook filename set
+ * PRIMARILY from the packaged `hooks/` filesystem tree (the literal
+ * shipped artifact), with the two source-code registries
+ * (`EXPECTED_HOOKS` and `defaultDesiredHooks()`) layered on top as
+ * defensive fallbacks.
+ *
+ * # Why filesystem-first
+ *
+ * 0.44.0 introduced this helper as the UNION of two source-code
+ * lists. Round-2 noticed a drift hazard: if either source-code list
+ * gets out of sync with the actual `hooks/` filesystem reality
+ * (e.g. a hook is added to `hooks/` but not to `EXPECTED_HOOKS`),
+ * the install-summary lies about what's about to land on disk.
+ * The filesystem is the source of truth — what the installer
+ * actually copies into `.claude/hooks/` is the contents of
+ * `hooks/`. Pinning the canonical set to the FS catches drift at
+ * runtime; the cross-check test in `init.test.ts` catches it at
+ * build time.
+ *
+ * # Strategy
+ *
+ *   1. Try to read `PKG_ROOT/hooks/*.sh` (filtered to exclude `_lib/`).
+ *      This is the authoritative list — it's literally what the
+ *      installer will copy into `.claude/hooks/`.
+ *   2. Union with `EXPECTED_HOOKS` (doctor's required list) — covers
+ *      the future case where the FS read fails (e.g. an unusual
+ *      install layout) but the source-code registry is intact.
+ *   3. Union with `defaultDesiredHooks()` basenames — covers the
+ *      symmetric case where a hook is registered in settings.json
+ *      but somehow absent from `EXPECTED_HOOKS`.
+ *
+ * Steps 2 and 3 are belt-and-suspenders. The cross-check test
+ * asserts all three sources agree; a drift between the FS and either
+ * source-code list fails the test loudly. In production the FS read
+ * (step 1) is the only one that contributes anything that wouldn't
+ * already be covered by steps 2+3 IF the test stays green.
  *
  * Sorted + deduped so the screen is stable across orderings.
+ *
+ * Exported for testability — the cross-check test imports it
+ * directly to compare against `canonicalHooksFromFilesystem()` and
+ * the two source-code registries.
  */
 export declare function canonicalInstalledHooks(): string[];
+/**
+ * 0.45.0 charter item 2 — read the canonical hook filename set
+ * directly from the packaged `hooks/` filesystem tree. Returns
+ * basenames (e.g. `dangerous-bash-interceptor.sh`) sorted ascending.
+ * Excludes anything under `_lib/` (shared helpers, not installed
+ * shims).
+ *
+ * Returns `[]` if the directory can't be read — caller is expected
+ * to union with `EXPECTED_HOOKS` / `defaultDesiredHooks()` so a
+ * missing FS doesn't produce a zero-length canonical list.
+ *
+ * Exported so the cross-check test can compare it against the two
+ * source-code registries and fail loudly on drift.
+ */
+export declare function canonicalHooksFromFilesystem(): string[];
 /**
  * 0.43.0 UX polish: build the human-readable install summary shown
  * BEFORE any files are written. Lists, in order: the policy file
@@ -140,26 +177,71 @@ export declare function detectTargetState(targetDir: string): TargetState;
  * filesystems and still verify the more meaningful invariant: the
  * files exist and have non-empty bytes.
  *
- * Detection strategy — two layers, either sufficient:
+ * Detection strategy — three layers, ordered cheapest-first.
  *
  *   1. Platform — `process.platform === 'win32'` always skips the
  *      exec-bit check (native Windows has no POSIX mode bit; node's
  *      `stat.mode` is a translation that may or may not preserve the
  *      0o111 bit depending on the source).
- *   2. Sample — even on Linux/macOS, when crossing into a Windows-
- *      backed filesystem (WSL bind-mount onto `/mnt/c/`, an SMB
- *      share, etc.), `stat.mode` returns a value whose `0o777`
- *      portion is zero. We detect this by sampling the FIRST `.sh`
- *      file in the hooks directory and checking whether ANY of the
- *      `0o777` bits are set; if none are, treat as mode-less.
+ *   2. Unambiguous shapes via sample — sample the FIRST `.sh` file:
+ *
+ *      - All 0o777 bits clear (`0o000`) — historical mode-less shape.
+ *        On a genuine Unix install no shipped hook is ever 0o000,
+ *        and a chmod-stripped install (the only innocuous source of
+ *        0o000) would already be unusable so a false skip there is
+ *        harmless (the substitute presence + non-empty check still
+ *        fires).
+ *      - All 0o777 bits set (`0o777`) — "no info, everything exec";
+ *        some SMB / NTFS-via-FUSE mounts surface this so file IO
+ *        works regardless of source mode.
+ *
+ *   3. Active mode-bit probe (0.45.0 codex round-1 P1 fix) — for
+ *      ambiguous shapes like `0o644` / `0o666` where the sample
+ *      COULD be "mode-less mount surfacing as 0o644" OR "chmod-
+ *      stripped genuine Unix install", do an active probe:
+ *
+ *        a. Write a temporary file with mode `0o755`.
+ *        b. Stat it back; if the kernel returned a value missing
+ *           the exec bits we just set, the FS truly ignores mode
+ *           bits — mode-less.
+ *        c. If the kernel returned `0o755` (preserved the mode),
+ *           the FS DOES respect mode bits — the sampled hook's
+ *           lack of exec bits is a real install failure, NOT a
+ *           mode-less mount. Return false so the caller emits the
+ *           genuine "zero executable .sh files" error.
+ *        d. If the probe itself fails (EROFS, EPERM, ENOSPC,
+ *           anything), fall through to false — let the caller
+ *           surface the real installation failure rather than
+ *           hide it behind an advisory.
+ *
+ *      Pre-fix the `0o644` branch suppressed the exec-bit check
+ *      unconditionally, masking genuinely broken Unix installs.
  *
  * Returns true when the exec-bit check should be SKIPPED.
  *
  * Exported for testability — callers can stub the filesystem and
- * exercise both shapes (mode-aware vs mode-less) without spinning
- * up an actual Windows VM.
+ * exercise all three shapes without spinning up an actual Windows VM.
  */
 export declare function isModeLessFilesystem(hooksDir: string): boolean;
+/**
+ * 0.45.0 codex round-1 P1 fix: active probe to disambiguate a
+ * mode-less filesystem from a chmod-stripped genuine Unix install.
+ *
+ * Writes a temporary file with mode `0o755` and stats it back. If
+ * the kernel returns a value that LACKS the exec bits we just set,
+ * the filesystem is ignoring mode bits — it's truly mode-less.
+ * Otherwise (kernel preserves the mode, OR the probe fails for any
+ * reason), return false so the caller surfaces the real install
+ * failure instead of hiding it behind an advisory.
+ *
+ * Probe file is written into `hooksDir` to match the exact mount
+ * the caller is checking — sampling a different directory could
+ * cross a mount boundary and lie about the target FS. The file is
+ * always unlinked, even on probe failure.
+ *
+ * Exported for testability.
+ */
+export declare function filesystemIgnoresModeBits(hooksDir: string): boolean;
 /**
  * 0.43.0 UX polish: post-install sanity check. Runs synchronously
  * after the file-write phase to catch installs that completed

package/dist/cli/init.js

@@ -18,7 +18,7 @@ import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFile
 import { writeManifestAtomic } from './install/manifest-io.js';
 import { sha256OfBuffer, sha256OfFile } from './install/sha.js';
 import { defaultReagentPath, ReagentDroppedFieldsError, translateReagentPolicy, } from './install/reagent.js';
-import { POLICY_FILE, REA_DIR, REGISTRY_FILE, err, getPkgVersion, log, warn } from './utils.js';
+import { PKG_ROOT, POLICY_FILE, REA_DIR, REGISTRY_FILE, err, getPkgVersion, log, warn, } from './utils.js';
 const PROFILE_NAMES = [
     'minimal',
     'client-engagement',
@@ -815,29 +815,53 @@ function readExistingManifestInstalledAt(manifestPath) {
     return undefined;
 }
 /**
- * 0.44.0 charter item 1: derive the canonical hook filename set the
- * installer will lay down. Union of:
+ * 0.45.0 charter item 2 — derive the canonical hook filename set
+ * PRIMARILY from the packaged `hooks/` filesystem tree (the literal
+ * shipped artifact), with the two source-code registries
+ * (`EXPECTED_HOOKS` and `defaultDesiredHooks()`) layered on top as
+ * defensive fallbacks.
  *
- *   - `EXPECTED_HOOKS` (the doctor's required-on-disk list — source of
- *     truth for "what `.claude/hooks/` must contain after install").
- *   - The `command` paths of every entry in `defaultDesiredHooks()`
- *     (the source of truth for "what `.claude/settings.json` registers
- *     with Claude Code"). Each command path ends in
- *     `.claude/hooks/<name>.sh`; we extract `<name>.sh` so the result
- *     joins cleanly with `EXPECTED_HOOKS`.
+ * # Why filesystem-first
  *
- * Pre-0.44.0 `buildInstallSummary` hard-coded a hook count / list. If
- * a new hook was added to `EXPECTED_HOOKS` (e.g. `delegation-advisory`
- * was promoted in 0.36.0) or registered in `defaultDesiredHooks()`
- * without anyone touching the summary, the operator's confirm screen
- * silently lied about what was about to be installed. This helper
- * means the summary now tracks the real installer surface — adding
- * a hook to either canonical source automatically updates the screen.
+ * 0.44.0 introduced this helper as the UNION of two source-code
+ * lists. Round-2 noticed a drift hazard: if either source-code list
+ * gets out of sync with the actual `hooks/` filesystem reality
+ * (e.g. a hook is added to `hooks/` but not to `EXPECTED_HOOKS`),
+ * the install-summary lies about what's about to land on disk.
+ * The filesystem is the source of truth — what the installer
+ * actually copies into `.claude/hooks/` is the contents of
+ * `hooks/`. Pinning the canonical set to the FS catches drift at
+ * runtime; the cross-check test in `init.test.ts` catches it at
+ * build time.
+ *
+ * # Strategy
+ *
+ *   1. Try to read `PKG_ROOT/hooks/*.sh` (filtered to exclude `_lib/`).
+ *      This is the authoritative list — it's literally what the
+ *      installer will copy into `.claude/hooks/`.
+ *   2. Union with `EXPECTED_HOOKS` (doctor's required list) — covers
+ *      the future case where the FS read fails (e.g. an unusual
+ *      install layout) but the source-code registry is intact.
+ *   3. Union with `defaultDesiredHooks()` basenames — covers the
+ *      symmetric case where a hook is registered in settings.json
+ *      but somehow absent from `EXPECTED_HOOKS`.
+ *
+ * Steps 2 and 3 are belt-and-suspenders. The cross-check test
+ * asserts all three sources agree; a drift between the FS and either
+ * source-code list fails the test loudly. In production the FS read
+ * (step 1) is the only one that contributes anything that wouldn't
+ * already be covered by steps 2+3 IF the test stays green.
  *
  * Sorted + deduped so the screen is stable across orderings.
+ *
+ * Exported for testability — the cross-check test imports it
+ * directly to compare against `canonicalHooksFromFilesystem()` and
+ * the two source-code registries.
  */
 export function canonicalInstalledHooks() {
-    const fromExpected = new Set(EXPECTED_HOOKS);
+    const merged = new Set(canonicalHooksFromFilesystem());
+    for (const name of EXPECTED_HOOKS)
+        merged.add(name);
     for (const group of defaultDesiredHooks()) {
         for (const h of group.hooks) {
             const cmd = h.command;
@@ -847,10 +871,53 @@ export function canonicalInstalledHooks() {
             const slashIdx = cmd.lastIndexOf('/');
             const basename = slashIdx >= 0 ? cmd.slice(slashIdx + 1) : cmd;
             if (basename.endsWith('.sh'))
-                fromExpected.add(basename);
+                merged.add(basename);
         }
     }
-    return Array.from(fromExpected).sort();
+    return Array.from(merged).sort();
+}
+/**
+ * 0.45.0 charter item 2 — read the canonical hook filename set
+ * directly from the packaged `hooks/` filesystem tree. Returns
+ * basenames (e.g. `dangerous-bash-interceptor.sh`) sorted ascending.
+ * Excludes anything under `_lib/` (shared helpers, not installed
+ * shims).
+ *
+ * Returns `[]` if the directory can't be read — caller is expected
+ * to union with `EXPECTED_HOOKS` / `defaultDesiredHooks()` so a
+ * missing FS doesn't produce a zero-length canonical list.
+ *
+ * Exported so the cross-check test can compare it against the two
+ * source-code registries and fail loudly on drift.
+ */
+export function canonicalHooksFromFilesystem() {
+    const dir = path.join(PKG_ROOT, 'hooks');
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith('.sh'))
+            .filter((name) => {
+            try {
+                // Exclude subdirectories like `_lib/`; only top-level `.sh`
+                // files are shipped shims. `readdirSync` returns names from
+                // the directory itself, but a future `_lib/foo.sh` reachable
+                // via the root listing should still be excluded — hence the
+                // explicit isFile() check.
+                return fs.statSync(path.join(dir, name)).isFile();
+            }
+            catch {
+                return false;
+            }
+        })
+            .sort();
+    }
+    catch {
+        // PKG_ROOT/hooks/ unreadable — fall through to the caller's
+        // source-code union. This is a defensive branch; in practice the
+        // packaged tarball always ships hooks/, and source builds always
+        // have a hooks/ checked into the repo.
+        return [];
+    }
 }
 /**
  * 0.43.0 UX polish: build the human-readable install summary shown
@@ -974,24 +1041,50 @@ export function detectTargetState(targetDir) {
  * filesystems and still verify the more meaningful invariant: the
  * files exist and have non-empty bytes.
  *
- * Detection strategy — two layers, either sufficient:
+ * Detection strategy — three layers, ordered cheapest-first.
  *
  *   1. Platform — `process.platform === 'win32'` always skips the
  *      exec-bit check (native Windows has no POSIX mode bit; node's
  *      `stat.mode` is a translation that may or may not preserve the
  *      0o111 bit depending on the source).
- *   2. Sample — even on Linux/macOS, when crossing into a Windows-
- *      backed filesystem (WSL bind-mount onto `/mnt/c/`, an SMB
- *      share, etc.), `stat.mode` returns a value whose `0o777`
- *      portion is zero. We detect this by sampling the FIRST `.sh`
- *      file in the hooks directory and checking whether ANY of the
- *      `0o777` bits are set; if none are, treat as mode-less.
+ *   2. Unambiguous shapes via sample — sample the FIRST `.sh` file:
+ *
+ *      - All 0o777 bits clear (`0o000`) — historical mode-less shape.
+ *        On a genuine Unix install no shipped hook is ever 0o000,
+ *        and a chmod-stripped install (the only innocuous source of
+ *        0o000) would already be unusable so a false skip there is
+ *        harmless (the substitute presence + non-empty check still
+ *        fires).
+ *      - All 0o777 bits set (`0o777`) — "no info, everything exec";
+ *        some SMB / NTFS-via-FUSE mounts surface this so file IO
+ *        works regardless of source mode.
+ *
+ *   3. Active mode-bit probe (0.45.0 codex round-1 P1 fix) — for
+ *      ambiguous shapes like `0o644` / `0o666` where the sample
+ *      COULD be "mode-less mount surfacing as 0o644" OR "chmod-
+ *      stripped genuine Unix install", do an active probe:
+ *
+ *        a. Write a temporary file with mode `0o755`.
+ *        b. Stat it back; if the kernel returned a value missing
+ *           the exec bits we just set, the FS truly ignores mode
+ *           bits — mode-less.
+ *        c. If the kernel returned `0o755` (preserved the mode),
+ *           the FS DOES respect mode bits — the sampled hook's
+ *           lack of exec bits is a real install failure, NOT a
+ *           mode-less mount. Return false so the caller emits the
+ *           genuine "zero executable .sh files" error.
+ *        d. If the probe itself fails (EROFS, EPERM, ENOSPC,
+ *           anything), fall through to false — let the caller
+ *           surface the real installation failure rather than
+ *           hide it behind an advisory.
+ *
+ *      Pre-fix the `0o644` branch suppressed the exec-bit check
+ *      unconditionally, masking genuinely broken Unix installs.
  *
  * Returns true when the exec-bit check should be SKIPPED.
  *
  * Exported for testability — callers can stub the filesystem and
- * exercise both shapes (mode-aware vs mode-less) without spinning
- * up an actual Windows VM.
+ * exercise all three shapes without spinning up an actual Windows VM.
  */
 export function isModeLessFilesystem(hooksDir) {
     if (process.platform === 'win32')
@@ -1008,12 +1101,21 @@ export function isModeLessFilesystem(hooksDir) {
             return false;
         }
         const stat = fs.statSync(path.join(hooksDir, firstSh));
-        // If ALL 0o777 bits are clear, the FS is not preserving Unix
-        // mode bits. Genuine Unix installs always have at least the
-        // owner-read bit (0o400) set, so an entirely-zero perms triple
-        // means we're on a mode-less mount.
-        if ((stat.mode & 0o777) === 0)
+        const perm = stat.mode & 0o777;
+        // (a) All 0o777 bits clear — historical mode-less detection.
+        if (perm === 0)
+            return true;
+        // (b) All 0o777 bits set — some SMB / FUSE mounts surface this.
+        if (perm === 0o777)
             return true;
+        // (c) 0.45.0 codex round-1 P1 fix: when 0o111 bits are clear
+        //     (e.g. 0o644 / 0o666), we MUST disambiguate "mode-less
+        //     mount that surfaces as 0o644" from "chmod-stripped Unix
+        //     install" via an active write-then-stat probe. The pre-fix
+        //     unconditional skip masked genuinely-broken Unix installs.
+        if ((perm & 0o111) === 0) {
+            return filesystemIgnoresModeBits(hooksDir);
+        }
         return false;
     }
     catch {
@@ -1023,6 +1125,61 @@ export function isModeLessFilesystem(hooksDir) {
         return false;
     }
 }
+/**
+ * 0.45.0 codex round-1 P1 fix: active probe to disambiguate a
+ * mode-less filesystem from a chmod-stripped genuine Unix install.
+ *
+ * Writes a temporary file with mode `0o755` and stats it back. If
+ * the kernel returns a value that LACKS the exec bits we just set,
+ * the filesystem is ignoring mode bits — it's truly mode-less.
+ * Otherwise (kernel preserves the mode, OR the probe fails for any
+ * reason), return false so the caller surfaces the real install
+ * failure instead of hiding it behind an advisory.
+ *
+ * Probe file is written into `hooksDir` to match the exact mount
+ * the caller is checking — sampling a different directory could
+ * cross a mount boundary and lie about the target FS. The file is
+ * always unlinked, even on probe failure.
+ *
+ * Exported for testability.
+ */
+export function filesystemIgnoresModeBits(hooksDir) {
+    const probePath = path.join(hooksDir, `.rea-modeless-probe-${process.pid}-${Date.now()}`);
+    try {
+        // 0.45.0 codex round-2 P2: write WITHOUT the mode option, then
+        // explicitly chmod to 0o755. `writeFileSync({ mode })` is filtered
+        // through the process umask, so a caller running under e.g.
+        // `umask 0111` would have their probe land as 0o644 even on a
+        // real Unix FS — falsely flagging mode-less and re-introducing
+        // the bug the round-1 fix was trying to close. Explicit chmod
+        // bypasses umask and always lands exactly the bits we asked for
+        // (when the FS honors them, which is the property we're probing).
+        fs.writeFileSync(probePath, '');
+        fs.chmodSync(probePath, 0o755);
+        const stat = fs.statSync(probePath);
+        const perm = stat.mode & 0o777;
+        // If the kernel preserved any of our exec bits, the FS honors
+        // mode bits — NOT mode-less.
+        if ((perm & 0o111) !== 0)
+            return false;
+        // Kernel stripped every exec bit we wrote — mode-less.
+        return true;
+    }
+    catch {
+        // Probe write/stat failed (read-only mount, EPERM, ENOSPC).
+        // Conservative: return false so the caller emits the real error
+        // rather than swallow it behind an advisory.
+        return false;
+    }
+    finally {
+        try {
+            fs.unlinkSync(probePath);
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+}
 /**
  * 0.43.0 UX polish: post-install sanity check. Runs synchronously
  * after the file-write phase to catch installs that completed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.44.0",
+  "version": "0.45.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)",
@@ -98,6 +98,7 @@
     "lint": "pnpm run lint:regex && pnpm run lint:awk-quotes && eslint .",
     "lint:regex": "node scripts/lint-safe-regex.mjs",
     "lint:awk-quotes": "node scripts/lint-awk-shim-quotes.mjs",
+    "perf:hooks": "pnpm run build && node scripts/profile-hooks.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "pnpm run build && pnpm run test:dogfood && pnpm run test:bash-syntax && node scripts/run-vitest.mjs",
@@ -105,6 +106,7 @@
     "test:coverage": "vitest run --coverage",
     "test:dogfood": "node tools/check-dogfood-drift.mjs",
     "test:bash-syntax": "bash -c 'for f in hooks/*.sh hooks/_lib/*.sh; do bash -n \"$f\" || exit 1; done && echo \"[bash-syntax] OK — all hooks parse cleanly\"'",
+    "test:perf": "pnpm run build && REA_INCLUDE_PERF=1 vitest run __tests__/scripts/profile-hooks.test.ts",
     "type-check": "tsc --noEmit",
     "changeset": "changeset",
     "changeset:version": "changeset version",

package/scripts/profile-hooks.mjs

@@ -0,0 +1,478 @@
+#!/usr/bin/env node
+// 0.45.0 charter item 1 — Hook hot-path profiling harness.
+//
+// # What this measures
+//
+// Every Bash / Edit / Write / MultiEdit / NotebookEdit tool call in
+// Claude Code fires one or more `.claude/hooks/*.sh` shims. 14 shims
+// are registered by default. Cumulative latency matters: 14 × 50ms is
+// 700ms added to every tool call, which the operator FEELS. This
+// harness measures per-shim wall-clock latency under a synthetic
+// payload and writes a baseline so regressions are visible.
+//
+// # Methodology
+//
+// For each shim:
+//   1. Build a representative stdin JSON payload (Claude Code shape)
+//      tuned to be "irrelevant" — i.e. the shim runs through its
+//      full HALT → stdin-capture → resolve → sandbox → policy
+//      short-circuit / version-probe path but does NOT trigger a
+//      block. This is the steady-state hot path.
+//   2. Warm up: 2 invocations (discarded). The first invocation has
+//      cold filesystem caches + Node startup costs that don't
+//      reflect steady-state.
+//   3. Measure: 10 invocations. Capture wall-clock + child cputime.
+//   4. Compute median / p95 / max from the 10 samples.
+//
+// The shim is invoked via `bash <hook-path>` with stdin piped in, the
+// same way Claude Code invokes them. Environment is preserved so the
+// real-world resolution path runs (node_modules / dist / PATH).
+//
+// # Output
+//
+// Writes `docs/hook-perf-baseline.json` sorted by p95 descending.
+// Shape:
+//
+//   {
+//     "version": "0.45.0",
+//     "measured_at": "2026-05-17T...",
+//     "platform": "darwin",
+//     "node_version": "v22.x.x",
+//     "iterations": 10,
+//     "warmup": 2,
+//     "hooks": [
+//       {
+//         "name": "local-review-gate.sh",
+//         "median_ms": 123.4,
+//         "p95_ms": 145.6,
+//         "max_ms": 158.9,
+//         "samples_ms": [...],
+//         "exit_codes": [0,0,0,0,0,0,0,0,0,0]
+//       },
+//       ...
+//     ]
+//   }
+//
+// # Threshold
+//
+// The harness DOES NOT enforce thresholds itself — it's a measurement
+// tool. The regression test at `__tests__/scripts/profile-hooks.test.ts`
+// asserts a permissive ceiling so absolute regressions get caught.
+// Tighten the ceiling over time as the baseline stabilizes.
+//
+// # Wiring
+//
+// `pnpm perf:hooks` runs this script. Not part of the default
+// `pnpm test` chain — it's heavy (160+ subprocess spawns) and timing
+// is sensitive to system load. CI calls it explicitly when the perf
+// guard is active.
+
+import { spawnSync } from 'node:child_process';
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  statSync,
+  existsSync,
+  mkdirSync,
+} from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { performance } from 'node:perf_hooks';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+const HOOKS_DIR = path.join(REPO_ROOT, 'hooks');
+const DOCS_DIR = path.join(REPO_ROOT, 'docs');
+const BASELINE_PATH = path.join(DOCS_DIR, 'hook-perf-baseline.json');
+
+// Permissive default per-shim p95 ceilings. The regression test in
+// `__tests__/scripts/profile-hooks.test.ts` enforces these. Start
+// loose to avoid CI flakes from cold caches / shared runners; tighten
+// in future releases as the baseline stabilizes.
+//
+// `local-review-gate.sh` is a documented outlier — it does its own
+// early sandbox check (round-5 P1) + subtree policy reads + a git
+// stash-create on the forward path. ~1800ms is its current healthy
+// p95 on the rea repo; the ceiling sits 2x above for CI headroom.
+// See `docs/hook-perf-baseline.md` for the breakdown.
+const DEFAULT_P95_CEILING_MS = 2000;
+const PER_SHIM_P95_CEILING_MS = {
+  'local-review-gate.sh': 4500,
+};
+
+/**
+ * Resolve the p95 ceiling for a given shim. Falls back to the default
+ * when no per-shim entry exists.
+ */
+export function ceilingForShim(name) {
+  return PER_SHIM_P95_CEILING_MS[name] ?? DEFAULT_P95_CEILING_MS;
+}
+
+const DEFAULT_ITERATIONS = 10;
+const DEFAULT_WARMUP = 2;
+
+/**
+ * Per-hook stdin payload generator. Each shim sees a Claude Code
+ * PreToolUse/PostToolUse event JSON; the shape varies slightly per
+ * hook (Bash vs Edit vs Write). We use intentionally innocuous
+ * payloads so the shim runs through its full hot path without
+ * blocking — that's the realistic latency we want to measure.
+ *
+ * Returns the JSON string to pipe into the shim's stdin.
+ */
+export function payloadForHook(name) {
+  // PreToolUse Bash event (Bash-tier hooks): a simple `ls` payload —
+  // not destructive, not policy-relevant, not a git push. The shim
+  // should run to completion without refusal.
+  const bashEvent = JSON.stringify({
+    tool_name: 'Bash',
+    tool_input: { command: 'ls -la', description: 'list current directory' },
+    hook_event_name: 'PreToolUse',
+  });
+
+  // PreToolUse Write event (Write-tier hooks): writing a benign .ts
+  // file with no secrets, no protected-path target.
+  const writeEvent = JSON.stringify({
+    tool_name: 'Write',
+    tool_input: { file_path: '/tmp/rea-profile-scratch.ts', content: 'export const x = 1;\n' },
+    hook_event_name: 'PreToolUse',
+  });
+
+  // PostToolUse Edit event (architecture-review-gate fires PostToolUse).
+  const postEditEvent = JSON.stringify({
+    tool_name: 'Edit',
+    tool_input: { file_path: '/tmp/scratch.ts', old_string: 'a', new_string: 'b' },
+    tool_response: { success: true },
+    hook_event_name: 'PostToolUse',
+  });
+
+  // PreToolUse Agent event (delegation-capture matches Agent|Skill).
+  const agentEvent = JSON.stringify({
+    tool_name: 'Agent',
+    tool_input: { subagent_type: 'general-purpose', prompt: 'noop' },
+    hook_event_name: 'PreToolUse',
+  });
+
+  switch (name) {
+    case 'architecture-review-gate.sh':
+      return postEditEvent;
+    case 'attribution-advisory.sh':
+      // Triggers on Bash `git commit` / `gh pr create`. We use a
+      // non-attribution payload so it runs through and exits clean.
+      return JSON.stringify({
+        tool_name: 'Bash',
+        tool_input: { command: 'git status', description: 'check status' },
+        hook_event_name: 'PreToolUse',
+      });
+    case 'blocked-paths-bash-gate.sh':
+      return bashEvent;
+    case 'blocked-paths-enforcer.sh':
+      return writeEvent;
+    case 'changeset-security-gate.sh':
+      return writeEvent;
+    case 'dangerous-bash-interceptor.sh':
+      return bashEvent;
+    case 'delegation-advisory.sh':
+      // Fires PostToolUse on Bash|Edit|Write|MultiEdit|NotebookEdit.
+      return JSON.stringify({
+        tool_name: 'Write',
+        tool_input: { file_path: '/tmp/scratch.ts', content: 'x' },
+        tool_response: { success: true },
+        hook_event_name: 'PostToolUse',
+      });
+    case 'delegation-capture.sh':
+      return agentEvent;
+    case 'dependency-audit-gate.sh':
+      // Fires on Bash. Payload is benign — not an install command.
+      return bashEvent;
+    case 'env-file-protection.sh':
+      return bashEvent;
+    case 'local-review-gate.sh':
+      // Fires on Bash. Use a non-push command so the gate runs through
+      // its policy-read path without triggering the actual
+      // local-review refusal.
+      return bashEvent;
+    case 'pr-issue-link-gate.sh':
+      // Fires on `gh pr create`. Benign Bash payload.
+      return bashEvent;
+    case 'protected-paths-bash-gate.sh':
+      return bashEvent;
+    case 'secret-scanner.sh':
+      return writeEvent;
+    case 'security-disclosure-gate.sh':
+      return bashEvent;
+    case 'settings-protection.sh':
+      return writeEvent;
+    default:
+      return bashEvent;
+  }
+}
+
+/**
+ * List the shims to profile — every `.sh` directly under `hooks/`,
+ * excluding `_lib/`.
+ */
+export function listShims(hooksDir = HOOKS_DIR) {
+  return readdirSync(hooksDir)
+    .filter((f) => f.endsWith('.sh'))
+    .filter((f) => {
+      try {
+        return statSync(path.join(hooksDir, f)).isFile();
+      } catch {
+        return false;
+      }
+    })
+    .sort();
+}
+
+/**
+ * Run a single shim invocation and return wall-clock ms + exit code.
+ */
+function runOnce(hookPath, payload) {
+  const start = performance.now();
+  const res = spawnSync('bash', [hookPath], {
+    input: payload,
+    encoding: 'utf8',
+    timeout: 30000,
+    env: { ...process.env, CLAUDE_PROJECT_DIR: REPO_ROOT },
+  });
+  const elapsed = performance.now() - start;
+  // spawnSync returns res.status null on timeout/signal — surface
+  // that as -1 so the caller can flag it.
+  const status = res.status === null ? -1 : res.status;
+  return { ms: elapsed, status };
+}
+
+/**
+ * Compute percentile from a sorted ascending array of numbers.
+ */
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+  return sorted[idx];
+}
+
+/**
+ * Profile a single hook. Returns the measurement record.
+ *
+ * 0.45.0 codex round-1 P2 #2: every shim is expected to exit 0 under
+ * its synthetic non-blocking payload — that's the steady-state hot
+ * path we want to measure. A non-zero exit (refusal, malformed
+ * payload, timeout, CLI-missing) means the shim ran an ERROR path
+ * instead of the hot path, and the resulting latency number does NOT
+ * represent steady-state. The record carries an `error` field
+ * surfacing any non-zero exit, and `runProfile` propagates it to the
+ * report so callers can fail loudly rather than silently shipping a
+ * "healthy" baseline that timed nothing but error paths.
+ */
+export function profileHook(name, opts = {}) {
+  const iterations = opts.iterations ?? DEFAULT_ITERATIONS;
+  const warmup = opts.warmup ?? DEFAULT_WARMUP;
+  const hooksDir = opts.hooksDir ?? HOOKS_DIR;
+  const hookPath = path.join(hooksDir, name);
+  const payload = payloadForHook(name);
+
+  for (let i = 0; i < warmup; i += 1) {
+    runOnce(hookPath, payload);
+  }
+
+  const samples = [];
+  const exitCodes = [];
+  for (let i = 0; i < iterations; i += 1) {
+    const r = runOnce(hookPath, payload);
+    samples.push(r.ms);
+    exitCodes.push(r.status);
+  }
+
+  const sorted = [...samples].sort((a, b) => a - b);
+  const median = percentile(sorted, 50);
+  const p95 = percentile(sorted, 95);
+  const max = sorted[sorted.length - 1];
+
+  // 0.45.0 codex round-1 P2 #2: surface non-zero exits. -1 marks a
+  // timeout (runOnce normalizes spawnSync's null status). Any
+  // non-zero value means the shim ran a refusal / error path, not
+  // the steady-state hot path the measurement assumes.
+  const nonZero = exitCodes.filter((c) => c !== 0);
+  const error =
+    nonZero.length > 0
+      ? `${nonZero.length}/${exitCodes.length} samples exited non-zero ` +
+        `(codes: ${exitCodes.join(',')}). Synthetic payload likely hit an ` +
+        `error path; latency is NOT representative of the hot path. ` +
+        `Tune the payload in payloadForHook() so this shim exits 0.`
+      : null;
+
+  return {
+    name,
+    median_ms: round(median),
+    p95_ms: round(p95),
+    max_ms: round(max),
+    samples_ms: samples.map(round),
+    exit_codes: exitCodes,
+    error,
+  };
+}
+
+function round(n) {
+  return Math.round(n * 100) / 100;
+}
+
+/**
+ * Run the full profile and return the report object.
+ */
+export function runProfile(opts = {}) {
+  const hooksDir = opts.hooksDir ?? HOOKS_DIR;
+  const iterations = opts.iterations ?? DEFAULT_ITERATIONS;
+  const warmup = opts.warmup ?? DEFAULT_WARMUP;
+  const shims = (opts.shims ?? listShims(hooksDir)).filter((n) => {
+    // Skip non-file entries defensively.
+    try {
+      return statSync(path.join(hooksDir, n)).isFile();
+    } catch {
+      return false;
+    }
+  });
+
+  const records = [];
+  for (const name of shims) {
+    records.push(profileHook(name, { iterations, warmup, hooksDir }));
+  }
+
+  // Sort by p95 desc — slowest at the top makes the operator's eye
+  // land on the leaders immediately.
+  records.sort((a, b) => b.p95_ms - a.p95_ms);
+
+  // Decorate each record with the resolved ceiling so the baseline JSON
+  // documents the per-shim threshold inline (avoids drift between the
+  // doc and the regression test).
+  const decorated = records.map((r) => ({
+    ...r,
+    p95_ceiling_ms: ceilingForShim(r.name),
+    over_budget: r.p95_ms > ceilingForShim(r.name),
+  }));
+
+  return {
+    version: getPkgVersion(),
+    measured_at: new Date().toISOString(),
+    platform: process.platform,
+    node_version: process.version,
+    iterations,
+    warmup,
+    default_p95_ceiling_ms: DEFAULT_P95_CEILING_MS,
+    per_shim_p95_ceiling_ms: PER_SHIM_P95_CEILING_MS,
+    hooks: decorated,
+  };
+}
+
+function getPkgVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * CLI entry. Writes the report to disk.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  const iterArg = args.find((a) => a.startsWith('--iterations='));
+  const warmArg = args.find((a) => a.startsWith('--warmup='));
+  const iterations = iterArg ? parseInt(iterArg.split('=')[1], 10) : DEFAULT_ITERATIONS;
+  const warmup = warmArg ? parseInt(warmArg.split('=')[1], 10) : DEFAULT_WARMUP;
+
+  process.stderr.write(
+    `[profile-hooks] profiling ${listShims().length} shims ` +
+      `(${iterations} iterations + ${warmup} warmup each) — this takes ~30-60s\n`,
+  );
+
+  const report = runProfile({ iterations, warmup });
+
+  if (!existsSync(DOCS_DIR)) {
+    mkdirSync(DOCS_DIR, { recursive: true });
+  }
+
+  const json = JSON.stringify(report, null, 2) + '\n';
+
+  // Human-readable summary on stderr (top 5 by p95).
+  process.stderr.write('\n[profile-hooks] p95 leaders:\n');
+  for (const r of report.hooks.slice(0, 5)) {
+    process.stderr.write(
+      `  ${r.name.padEnd(32)}  ` +
+        `p95=${String(r.p95_ms).padStart(7)}ms  ` +
+        `median=${String(r.median_ms).padStart(7)}ms  ` +
+        `max=${String(r.max_ms).padStart(7)}ms\n`,
+    );
+  }
+
+  // 0.45.0 codex round-1 P2 #2: fail loudly if any shim ran a
+  // non-zero-exit error path — the latency number is meaningless in
+  // that case and the baseline would silently ship lies.
+  //
+  // 0.45.0 codex round-2 P2 #3: this AND the over-budget check below
+  // run BEFORE the baseline write — a failed measurement run must
+  // NOT clobber the checked-in last-known-good baseline. The dry-run
+  // branch still emits JSON for inspection regardless.
+  const errored = report.hooks.filter((h) => h.error !== null);
+  if (errored.length > 0) {
+    process.stderr.write(
+      `\n[profile-hooks] ${errored.length} shim(s) ran a non-zero error path:\n`,
+    );
+    for (const h of errored) {
+      process.stderr.write(`  ${h.name}: ${h.error}\n`);
+    }
+    process.stderr.write(
+      `[profile-hooks] NOT writing ${BASELINE_PATH} — last-known-good baseline preserved.\n`,
+    );
+    if (dryRun) process.stdout.write(json);
+    process.exit(2);
+  }
+
+  const overBudget = report.hooks.filter((h) => h.p95_ms > ceilingForShim(h.name));
+  if (overBudget.length > 0) {
+    process.stderr.write(
+      `\n[profile-hooks] ${overBudget.length} shim(s) exceeded the p95 ceiling:\n`,
+    );
+    for (const h of overBudget) {
+      process.stderr.write(
+        `  ${h.name}  p95=${h.p95_ms}ms (ceiling=${ceilingForShim(h.name)}ms)\n`,
+      );
+    }
+    process.stderr.write(
+      `[profile-hooks] NOT writing ${BASELINE_PATH} — last-known-good baseline preserved.\n`,
+    );
+    if (dryRun) process.stdout.write(json);
+    process.exit(1);
+  }
+
+  // All checks passed — safe to persist the baseline.
+  if (dryRun) {
+    process.stdout.write(json);
+  } else {
+    writeFileSync(BASELINE_PATH, json);
+    process.stderr.write(`[profile-hooks] wrote ${BASELINE_PATH}\n`);
+  }
+}
+
+// Run main only when invoked directly (not when imported by tests).
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === __filename;
+if (invokedDirectly) {
+  main().catch((e) => {
+    process.stderr.write(`[profile-hooks] FAILED: ${e.message}\n`);
+    process.exit(1);
+  });
+}
+
+export {
+  BASELINE_PATH,
+  DEFAULT_P95_CEILING_MS,
+  PER_SHIM_P95_CEILING_MS,
+  DEFAULT_ITERATIONS,
+  DEFAULT_WARMUP,
+};