@bookedsolid/rea 0.43.0 → 0.45.0

package/dist/cli/init.d.ts

@@ -59,6 +59,66 @@ export interface ResolvedConfig {
     reagentPolicyPath: string | null;
     reagentNotices: string[];
 }
+/**
+ * 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
@@ -67,6 +127,11 @@ export interface ResolvedConfig {
  * installer will ACTUALLY do given the target tree's shape), and
  * whether re-run preservation is active.
  *
+ * 0.44.0 charter item 1: hook count + listing is derived from the
+ * canonical hook resolvers via {@link canonicalInstalledHooks}, NOT
+ * hard-coded. Adding a hook to `EXPECTED_HOOKS` or
+ * `defaultDesiredHooks()` automatically reflects in this screen.
+ *
  * Rendered via clack's `note` primitive so it sits in a bordered block
  * adjacent to the final `confirm` gate. The string is also returned
  * verbatim so the test suite can assert content without mocking clack.
@@ -99,12 +164,97 @@ export interface TargetState {
  * and the summary was only slightly stale.
  */
 export declare function detectTargetState(targetDir: string): TargetState;
+/**
+ * 0.44.0 charter item 2: detect filesystems where Unix mode bits are
+ * unreliable (Windows-class FSes, WSL/native crossings, some network
+ * mounts). On these, `stat.mode` for a freshly-installed `.sh` either
+ * reads back without the `0o111` exec bit set, or is zeroed entirely.
+ *
+ * Pre-fix `postInstallVerify` hard-failed the install when zero `.sh`
+ * files had the exec bit — every Windows install thus produced a
+ * false-positive "0 executable .sh files" warning even on a perfectly
+ * healthy install. We now treat exec-bit checks as advisory on these
+ * filesystems and still verify the more meaningful invariant: the
+ * files exist and have non-empty bytes.
+ *
+ * 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. 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 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
  * "successfully" but are missing a critical artifact (write
  * permissions issue, partial copy, etc.).
  *
+ * 0.44.0 charter item 2: exec-bit check is skipped on mode-less
+ * filesystems (Windows / WSL-crossing / SMB mounts). When skipped, we
+ * still verify the files exist + are non-empty — that's the invariant
+ * a partial-copy or zero-byte write would actually violate. The skip
+ * is annotated in the returned advisory so the operator knows why a
+ * check they expected to run didn't.
+ *
  * Strictly read-only — no probes that touch python3 / jq / codex.
  * Pattern modelled on the synthetic round-trip checks established by
  * `checkDelegationRoundTrip` in 0.29.0/0.31.0: cheap, in-process,
@@ -112,7 +262,9 @@ export declare function detectTargetState(targetDir: string): TargetState;
  * that bites first-time consumers hardest. For deep diagnostics
  * point the operator at `rea doctor`.
  *
- * Returns the list of issues found (empty = healthy). The caller
+ * Returns the list of issues found (empty = healthy). Advisory
+ * (skipped-check) lines are prefixed with `advisory:` so the caller
+ * can distinguish them from real issues if desired. The caller
  * surfaces them via clack's `log.warn` and points the operator at
  * `rea doctor` for follow-up.
  */

package/dist/cli/init.js

@@ -8,6 +8,7 @@ import { HARD_DEFAULTS, loadProfile, mergeProfiles } from '../policy/profiles.js
 import { copyArtifacts } from './install/copy.js';
 import { ensureReaGitignore } from './install/gitignore.js';
 import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
+import { EXPECTED_HOOKS } from './doctor.js';
 import { installCommitMsgHook } from './install/commit-msg.js';
 import { installPrepareCommitMsgHook } from './install/prepare-commit-msg.js';
 import { installPrePushFallback } from './install/pre-push.js';
@@ -17,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',
@@ -813,6 +814,111 @@ function readExistingManifestInstalledAt(manifestPath) {
     }
     return undefined;
 }
+/**
+ * 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 function canonicalInstalledHooks() {
+    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;
+            // Commands have shape `"$CLAUDE_PROJECT_DIR"/.claude/hooks/<name>.sh`.
+            // Take the basename (everything after the last `/`). Robust against
+            // future path changes — only the filename matters here.
+            const slashIdx = cmd.lastIndexOf('/');
+            const basename = slashIdx >= 0 ? cmd.slice(slashIdx + 1) : cmd;
+            if (basename.endsWith('.sh'))
+                merged.add(basename);
+        }
+    }
+    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
  * BEFORE any files are written. Lists, in order: the policy file
@@ -821,6 +927,11 @@ function readExistingManifestInstalledAt(manifestPath) {
  * installer will ACTUALLY do given the target tree's shape), and
  * whether re-run preservation is active.
  *
+ * 0.44.0 charter item 1: hook count + listing is derived from the
+ * canonical hook resolvers via {@link canonicalInstalledHooks}, NOT
+ * hard-coded. Adding a hook to `EXPECTED_HOOKS` or
+ * `defaultDesiredHooks()` automatically reflects in this screen.
+ *
  * Rendered via clack's `note` primitive so it sits in a bordered block
  * adjacent to the final `confirm` gate. The string is also returned
  * verbatim so the test suite can assert content without mocking clack.
@@ -843,7 +954,16 @@ export function buildInstallSummary(targetDir, config, reRunMode, targetState) {
     lines.push(`  .rea/registry.yaml       — empty MCP-server registry`);
     lines.push(`  .rea/install-manifest.json — hash record for drift detection`);
     lines.push(`  .claude/agents/          — curated specialist agents`);
-    lines.push(`  .claude/hooks/           — hook scripts (executable)`);
+    // 0.44.0 charter item 1: hook count derived from the canonical
+    // resolvers (EXPECTED_HOOKS + defaultDesiredHooks). Pre-fix this
+    // line read `.claude/hooks/           — hook scripts (executable)`
+    // with no count, so adding a new hook silently changed the install
+    // surface without surfacing in the operator's confirm screen.
+    const hookNames = canonicalInstalledHooks();
+    lines.push(`  .claude/hooks/           — ${hookNames.length} hook scripts (executable):`);
+    for (const name of hookNames) {
+        lines.push(`      ${name}`);
+    }
     lines.push(`  .claude/commands/        — slash commands`);
     lines.push(`  .claude/settings.json    — hook registration entries`);
     // 0.43.0 codex round-1 P3: the installer writes to `.git/hooks/*`
@@ -908,12 +1028,171 @@ export function detectTargetState(targetDir) {
         huskyDirPresent: fs.existsSync(path.join(targetDir, '.husky')),
     };
 }
+/**
+ * 0.44.0 charter item 2: detect filesystems where Unix mode bits are
+ * unreliable (Windows-class FSes, WSL/native crossings, some network
+ * mounts). On these, `stat.mode` for a freshly-installed `.sh` either
+ * reads back without the `0o111` exec bit set, or is zeroed entirely.
+ *
+ * Pre-fix `postInstallVerify` hard-failed the install when zero `.sh`
+ * files had the exec bit — every Windows install thus produced a
+ * false-positive "0 executable .sh files" warning even on a perfectly
+ * healthy install. We now treat exec-bit checks as advisory on these
+ * filesystems and still verify the more meaningful invariant: the
+ * files exist and have non-empty bytes.
+ *
+ * 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. 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 all three shapes without spinning up an actual Windows VM.
+ */
+export function isModeLessFilesystem(hooksDir) {
+    if (process.platform === 'win32')
+        return true;
+    // Sample any single .sh file to probe whether the FS preserves
+    // exec bits at all. We don't need every file — just one signal.
+    try {
+        const entries = fs.readdirSync(hooksDir);
+        const firstSh = entries.find((e) => e.endsWith('.sh'));
+        if (firstSh === undefined) {
+            // No .sh files at all — let the caller's existence check fire.
+            // Treat as mode-aware (skip = false) so we don't hide the
+            // genuinely-missing-files case behind the WSL advisory.
+            return false;
+        }
+        const stat = fs.statSync(path.join(hooksDir, firstSh));
+        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 {
+        // Stat failed — let the caller's enumeration handle the error.
+        // Returning false here means "don't skip" so a genuine ENOENT
+        // surfaces through the normal exec-bit branch.
+        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
  * "successfully" but are missing a critical artifact (write
  * permissions issue, partial copy, etc.).
  *
+ * 0.44.0 charter item 2: exec-bit check is skipped on mode-less
+ * filesystems (Windows / WSL-crossing / SMB mounts). When skipped, we
+ * still verify the files exist + are non-empty — that's the invariant
+ * a partial-copy or zero-byte write would actually violate. The skip
+ * is annotated in the returned advisory so the operator knows why a
+ * check they expected to run didn't.
+ *
  * Strictly read-only — no probes that touch python3 / jq / codex.
  * Pattern modelled on the synthetic round-trip checks established by
  * `checkDelegationRoundTrip` in 0.29.0/0.31.0: cheap, in-process,
@@ -921,7 +1200,9 @@ export function detectTargetState(targetDir) {
  * that bites first-time consumers hardest. For deep diagnostics
  * point the operator at `rea doctor`.
  *
- * Returns the list of issues found (empty = healthy). The caller
+ * Returns the list of issues found (empty = healthy). Advisory
+ * (skipped-check) lines are prefixed with `advisory:` so the caller
+ * can distinguish them from real issues if desired. The caller
  * surfaces them via clack's `log.warn` and points the operator at
  * `rea doctor` for follow-up.
  */
@@ -945,17 +1226,21 @@ export function postInstallVerify(targetDir) {
                 'run `rea doctor` for details');
         }
     }
-    // 2. .claude/hooks directory present with executable scripts.
+    // 2. .claude/hooks directory present with non-empty scripts (and,
+    //    on mode-aware filesystems, executable).
     const hooksDir = path.join(targetDir, '.claude', 'hooks');
     if (!fs.existsSync(hooksDir)) {
         issues.push(`.claude/hooks/ directory missing after install (expected at ${hooksDir})`);
     }
     else {
+        const modeLess = isModeLessFilesystem(hooksDir);
         let executableCount = 0;
+        let shCount = 0;
         try {
             for (const entry of fs.readdirSync(hooksDir)) {
                 if (!entry.endsWith('.sh'))
                     continue;
+                shCount += 1;
                 const stat = fs.statSync(path.join(hooksDir, entry));
                 if ((stat.mode & 0o111) !== 0)
                     executableCount += 1;
@@ -964,7 +1249,58 @@ export function postInstallVerify(targetDir) {
         catch (e) {
             issues.push(`failed to enumerate .claude/hooks/: ${e instanceof Error ? e.message : String(e)}`);
         }
-        if (executableCount === 0) {
+        if (modeLess) {
+            // 0.44.0 charter item 2: emit a one-liner advisory so the
+            // operator understands why the exec-bit check didn't run. Still
+            // verify the files exist + have content — that's the partial-
+            // copy failure shape we genuinely want to catch on these FSes.
+            //
+            // 0.44.0 codex round-1 P2 fix: validate the FULL canonical hook
+            // set, not just `shCount > 0 && nonEmptyCount > 0`. Pre-fix a
+            // partial copy that left ONE non-empty .sh and dropped the rest
+            // would still report "install looks healthy" because the
+            // substitute invariant only required at least one survivor.
+            // Now we per-file check every entry in canonicalInstalledHooks()
+            // for existence + non-empty bytes — equivalent rigor to the
+            // mode-aware path's per-file exec-bit check.
+            issues.push('advisory: skipping exec-bit check on this filesystem ' +
+                '(Windows/WSL/SMB-class; mode bits not reliable). ' +
+                'Verifying per-file presence and non-empty content instead.');
+            const expected = canonicalInstalledHooks();
+            const missing = [];
+            const empty = [];
+            for (const name of expected) {
+                const hookPath = path.join(hooksDir, name);
+                if (!fs.existsSync(hookPath)) {
+                    missing.push(name);
+                    continue;
+                }
+                try {
+                    const stat = fs.statSync(hookPath);
+                    if (stat.size === 0)
+                        empty.push(name);
+                }
+                catch {
+                    // Treat unstattable as missing — the partial-copy failure
+                    // shape we are trying to detect.
+                    missing.push(name);
+                }
+            }
+            if (missing.length > 0) {
+                issues.push(`.claude/hooks/ is missing ${missing.length} expected hook file(s): ${missing.join(', ')}`);
+            }
+            if (empty.length > 0) {
+                issues.push(`.claude/hooks/ has ${empty.length} empty hook file(s): ${empty.join(', ')}`);
+            }
+            // Fallback for the no-canonical-list-known case (defensive — the
+            // helper always returns >=1 in practice, but if a future
+            // refactor empties the resolvers we still want to catch a
+            // completely-empty hooks dir).
+            if (expected.length === 0 && shCount === 0) {
+                issues.push('.claude/hooks/ contains zero .sh files — run `rea doctor`');
+            }
+        }
+        else if (executableCount === 0) {
             issues.push('.claude/hooks/ contains zero executable .sh files — run `rea doctor`');
         }
     }
@@ -1281,13 +1617,34 @@ export async function runInit(options) {
     // operator at `rea doctor` for the deep dive. Modelled on the
     // 0.29.0/0.31.0 synthetic round-trip pattern.
     const verifyIssues = postInstallVerify(targetDir);
-    if (verifyIssues.length > 0) {
+    // 0.44.0 charter item 2: split advisory (`advisory:`-prefixed) from
+    // real issues. Advisories explain skipped checks (Windows/WSL exec-
+    // bit skip) and don't merit the loud "verification flagged" header
+    // when no real issue is present.
+    const realIssues = verifyIssues.filter((i) => !i.startsWith('advisory:'));
+    const advisories = verifyIssues.filter((i) => i.startsWith('advisory:'));
+    if (realIssues.length > 0) {
         console.log('');
         warn('post-install verification flagged the following:');
-        for (const issue of verifyIssues)
+        for (const issue of realIssues)
             warn(`  • ${issue}`);
+        for (const adv of advisories)
+            warn(`  • ${adv}`);
         warn('Run `rea doctor` for a full diagnostic.');
     }
+    else if (advisories.length > 0) {
+        if (interactive) {
+            p.log.success('Post-install check: install looks healthy.');
+            for (const adv of advisories)
+                p.log.info(adv);
+        }
+        else {
+            console.log('');
+            console.log('Post-install check: install looks healthy.');
+            for (const adv of advisories)
+                console.log(`  ${adv}`);
+        }
+    }
     else if (interactive) {
         // Quiet success — confirm we checked, but don't shout about it.
         p.log.success('Post-install check: install looks healthy.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.43.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,
+};