@bookedsolid/rea 0.38.1 → 0.40.0

package/dist/cli/delegation-advisory.d.ts

@@ -89,7 +89,47 @@ export interface HookDelegationAdvisoryOptions {
      * Production omits.
      */
     stdinOverride?: string;
+    /**
+     * Test seam — override the sleep used by
+     * `sessionHasRealDelegation`'s poll-and-backoff loop. Production
+     * omits and uses real `setTimeout`-backed sleeps; tests pass a
+     * controllable fake so the race-coverage tests don't wall-clock on
+     * the real 500ms budget.
+     *
+     * 0.40.0 charter item 1.
+     */
+    sleepOverride?: (ms: number) => Promise<void>;
 }
+/**
+ * Backoff schedule (in milliseconds) for `sessionHasRealDelegation`'s
+ * poll-and-backoff loop.
+ *
+ * 0.40.0 charter item 1 — closes the `& disown` race between
+ * `delegation-capture.sh` (which fire-and-forgets `rea hook
+ * delegation-signal --detach &` for sub-50ms PreToolUse latency) and the
+ * `delegation-advisory.sh` PostToolUse path (which reads the audit log
+ * to decide whether the session has delegated). A `git commit` landing
+ * within the narrow window between an Agent dispatch and the audit
+ * append-on-disk would read the stale chain, see no delegation, fire
+ * the nudge spuriously, AND write the `.fired` sentinel — silencing
+ * every future advisory in the session even though delegation DID
+ * happen.
+ *
+ * The schedule is delays BETWEEN re-reads (NOT cumulative): 50ms,
+ * 150ms, 300ms. Total worst-case 500ms — acceptable hot-path budget
+ * for a PostToolUse hook running on `Bash|Edit|Write|MultiEdit|
+ * NotebookEdit`. The first read is immediate (no upfront delay), so a
+ * session that DID delegate before threshold-crossing pays zero extra
+ * latency. Only the rare "we crossed threshold while a recent
+ * delegation signal hasn't yet hit disk" case pays the full budget,
+ * and only ONCE per session (the `.fired` sentinel suppresses future
+ * scans).
+ *
+ * Exported for the race-coverage test in
+ * `delegation-advisory.test.ts` so it can assert on the schedule
+ * without duplicating the constant.
+ */
+export declare const DELEGATION_POLL_BACKOFF_MS: readonly number[];
 /**
  * Derive a filesystem-safe, **collision-free** per-session state-key
  * basename from an untrusted session id.

package/dist/cli/delegation-advisory.js

@@ -70,6 +70,36 @@ import { loadDelegationRecords, listRotatedAuditFiles, } from './audit-specialis
 import { discoverRoster, countsAsRealDelegation, DEFAULT_EXEMPT_SUBAGENTS, } from './roster.js';
 import { REA_DIR } from './utils.js';
 const DEFAULT_THRESHOLD = 25;
+/**
+ * Backoff schedule (in milliseconds) for `sessionHasRealDelegation`'s
+ * poll-and-backoff loop.
+ *
+ * 0.40.0 charter item 1 — closes the `& disown` race between
+ * `delegation-capture.sh` (which fire-and-forgets `rea hook
+ * delegation-signal --detach &` for sub-50ms PreToolUse latency) and the
+ * `delegation-advisory.sh` PostToolUse path (which reads the audit log
+ * to decide whether the session has delegated). A `git commit` landing
+ * within the narrow window between an Agent dispatch and the audit
+ * append-on-disk would read the stale chain, see no delegation, fire
+ * the nudge spuriously, AND write the `.fired` sentinel — silencing
+ * every future advisory in the session even though delegation DID
+ * happen.
+ *
+ * The schedule is delays BETWEEN re-reads (NOT cumulative): 50ms,
+ * 150ms, 300ms. Total worst-case 500ms — acceptable hot-path budget
+ * for a PostToolUse hook running on `Bash|Edit|Write|MultiEdit|
+ * NotebookEdit`. The first read is immediate (no upfront delay), so a
+ * session that DID delegate before threshold-crossing pays zero extra
+ * latency. Only the rare "we crossed threshold while a recent
+ * delegation signal hasn't yet hit disk" case pays the full budget,
+ * and only ONCE per session (the `.fired` sentinel suppresses future
+ * scans).
+ *
+ * Exported for the race-coverage test in
+ * `delegation-advisory.test.ts` so it can assert on the schedule
+ * without duplicating the constant.
+ */
+export const DELEGATION_POLL_BACKOFF_MS = [50, 150, 300];
 /**
  * Maximum length of the human-readable prefix in a state key. The full
  * key is `<prefix>-<16-hex-hash>`, so a 64-char cap keeps basenames well
@@ -250,7 +280,22 @@ export function advisoryMessage(count, threshold) {
  * `since` anchor is `undefined` and behavior is the pre-0.31.0
  * single-file walk.
  */
-async function sessionHasRealDelegation(reaRoot, sessionId, exemptSubagents) {
+/**
+ * Real-clock sleep used by the production poll-and-backoff loop.
+ * Factored out so tests can swap it for a fake controllable scheduler
+ * via `HookDelegationAdvisoryOptions.sleepOverride`.
+ */
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Single audit-chain scan: returns `'delegated'` when a real
+ * delegation signal is found, `'not-delegated'` when scanning succeeds
+ * but no real signal is in the chain, and `'unreadable'` when audit
+ * loading throws (the chain is missing / unreadable). Split out from
+ * the polling loop so each retry runs identical scan logic.
+ */
+async function scanForRealDelegationOnce(reaRoot, sessionId, exemptSubagents) {
     let records;
     try {
         // Resolve the rotated-file set the same way `rea audit specialists`
@@ -263,13 +308,10 @@ async function sessionHasRealDelegation(reaRoot, sessionId, exemptSubagents) {
         records = loaded.records;
     }
     catch {
-        // Audit log unreadable — we cannot prove the session delegated, so
-        // we DON'T fire (fail toward silence, not toward a false-positive
-        // nudge). Returning `true` here suppresses the advisory.
-        return true;
+        return 'unreadable';
     }
     if (records.length === 0)
-        return false;
+        return 'not-delegated';
     const roster = discoverRoster(reaRoot);
     for (const rec of records) {
         if (countsAsRealDelegation({
@@ -278,9 +320,45 @@ async function sessionHasRealDelegation(reaRoot, sessionId, exemptSubagents) {
             roster,
             exempt: exemptSubagents,
         })) {
-            return true;
+            return 'delegated';
         }
     }
+    return 'not-delegated';
+}
+async function sessionHasRealDelegation(reaRoot, sessionId, exemptSubagents, sleep = realSleep) {
+    // 0.40.0 charter item 1 — poll-and-backoff before declaring
+    // "no delegation in this session".
+    //
+    // The producer (`delegation-capture.sh`) calls `rea hook
+    // delegation-signal --detach &` to fire-and-forget the audit append.
+    // For sub-50ms PreToolUse latency this is the right call, but it
+    // opens a narrow race: a write-class call (Bash/Edit/Write/…)
+    // landing in the same tick as an Agent/Skill dispatch can run this
+    // predicate BEFORE the audit append commits to disk. Pre-fix, the
+    // function then returned `false`, the caller fired the advisory,
+    // wrote the `.fired` sentinel, and silenced every future nudge in
+    // the session — even though delegation DID happen.
+    //
+    // Each retry runs a full audit scan. The first scan is immediate
+    // (no upfront delay); subsequent scans wait per
+    // `DELEGATION_POLL_BACKOFF_MS`. Worst-case total: 50+150+300 = 500ms
+    // for the four-scan path. We exit early as soon as a delegation is
+    // observed OR the chain becomes unreadable (preserving the pre-fix
+    // "audit log unreadable → suppress the advisory" posture so a
+    // missing chain never produces a false-positive nudge).
+    let outcome = await scanForRealDelegationOnce(reaRoot, sessionId, exemptSubagents);
+    if (outcome === 'delegated')
+        return true;
+    if (outcome === 'unreadable')
+        return true;
+    for (const waitMs of DELEGATION_POLL_BACKOFF_MS) {
+        await sleep(waitMs);
+        outcome = await scanForRealDelegationOnce(reaRoot, sessionId, exemptSubagents);
+        if (outcome === 'delegated')
+            return true;
+        if (outcome === 'unreadable')
+            return true;
+    }
     return false;
 }
 /**
@@ -379,7 +457,7 @@ export async function computeDelegationAdvisory(options) {
     // verbatim (or `'unknown'` for untagged sessions), so the `stateKey`
     // filesystem form would never match (see the comment at the
     // `auditSessionId` / `stateKey` split above).
-    const delegated = await sessionHasRealDelegation(reaRoot, auditSessionId, policy.exemptSubagents);
+    const delegated = await sessionHasRealDelegation(reaRoot, auditSessionId, policy.exemptSubagents, options.sleepOverride);
     if (delegated) {
         // Session DID delegate to a real specialist — no nudge warranted.
         // We deliberately do NOT write the `.fired` sentinel here: if the

package/dist/cli/doctor.d.ts

@@ -97,6 +97,159 @@ export declare function checkPrepareCommitMsgHook(baseDir: string): CheckResult;
  * (the doctor then short-circuits past every Codex check).
  */
 export declare function checkCodexBinaryOnPath(): CheckResult;
+/**
+ * Probe interface accepted by the policy-reader tier checks. Each
+ * field is optional; when omitted the check uses the real-environment
+ * default (PATH walk, spawnSync). Tests inject stubs to get
+ * deterministic, fast verdicts without touching the real filesystem or
+ * spawning subprocesses.
+ *
+ * - `cliDistExists` — does the rea CLI binary exist on disk at one of
+ *   the two shim-resolved paths? Cheap (single `existsSync`). Used to
+ *   give a clear "missing vs. broken" error message when Tier 1 is
+ *   unreachable.
+ * - `cliInvokable` — does the resolved CLI actually respond to
+ *   `rea hook policy-get version --json`? The expensive probe (one
+ *   subprocess spawn). Mirrors EXACTLY what `_pr_load_full_json`
+ *   does in `hooks/_lib/policy-reader.sh` so a stale or broken dist
+ *   reports `warn` here — same outcome the real shim ladder would
+ *   produce. Codex round-1 P2 (2026-05-16).
+ * - `python3OnPath` / `python3PyYamlReachable` — Tier 2 reachability.
+ *   `python3PyYamlReachable` returns `true` when both python3 AND the
+ *   `yaml` stdlib (PyYAML) can be imported (the Tier 2 loader needs
+ *   both).
+ * - `awkOnPath` / `jqOnPath` — Tier 3 + JSON-accelerator reachability.
+ */
+export interface PolicyReaderProbes {
+    cliDistExists?: (baseDir: string) => boolean;
+    cliInvokable?: (baseDir: string) => boolean;
+    python3OnPath?: () => string | null;
+    /**
+     * 0.40.0 charter item 3 — accepts the consumer's `baseDir` so the
+     * probe can thread it as `cwd` to the spawned `python3 -c` process.
+     * Pre-fix, the spawn happened in doctor's own cwd, which meant the
+     * sys.path scrub (which removes "", ".", CWD, realpath(CWD) to
+     * mirror policy-reader.sh's defense against a malicious repo-local
+     * `./yaml.py`) operated on the wrong directory when `rea doctor`
+     * was invoked from outside the consumer tree (e.g. `cd /tmp && rea
+     * doctor --base-dir /Users/.../consumer-repo`).
+     *
+     * Probes that don't care about cwd (test stubs, fakes) can simply
+     * ignore the argument; the default production probe uses it.
+     */
+    python3PyYamlReachable?: (baseDir: string) => boolean;
+    awkOnPath?: () => string | null;
+    jqOnPath?: () => string | null;
+}
+/**
+ * Tier 1 — `rea hook policy-get`. Reachable when the rea CLI is
+ * present at one of the two shim-resolved paths (consumer install OR
+ * dogfood `dist/`) AND actually responds to `rea hook policy-get
+ * version --json`. The shim ladder uses that exact invocation as its
+ * Tier 1 probe (see `_pr_load_full_json` in `hooks/_lib/policy-reader.sh`);
+ * mirroring it here means a stale or broken dist (file present but
+ * import-throws / postinstall failed) reports `warn` — matching the
+ * real fall-through to Tier 2/3 the shim would do at runtime.
+ *
+ * Three states:
+ *   - dist present + CLI responds → `pass` (canonical loader fully wired).
+ *   - dist present + CLI broken → `warn` (stale build, missing native
+ *     module, broken postinstall — needs `pnpm build` / `rea upgrade`).
+ *   - dist absent → `warn` (not installed; Tier 2/3 still cover).
+ *
+ * Codex round-1 P2 (2026-05-16) replaced the file-existence-only
+ * probe with this CLI-invocation probe — pre-fix, a consumer with
+ * `dist/cli/index.js` present but throwing on load would see `pass`
+ * here while every real shim would silently fall through.
+ */
+export declare function checkPolicyReaderTier1(baseDir: string, probes?: PolicyReaderProbes): CheckResult;
+/**
+ * Tier 2 — python3 + stdlib `yaml` (PyYAML). Handles BOTH block-form
+ * and flow-form YAML; the practical floor when Tier 1 is unreachable.
+ *
+ * Three states:
+ *   - python3 present + PyYAML importable → `pass`.
+ *   - python3 present, PyYAML missing → `warn` (the loader will fall
+ *     through to Tier 3, which only handles block-form).
+ *   - python3 absent → `warn` (same Tier 3 fall-through).
+ *
+ * Never `fail` — Tier 3 is still a valid floor for block-form policy.
+ * The warning highlights the silent no-op risk for flow-form lookups
+ * when CLI is also unreachable.
+ */
+export declare function checkPolicyReaderTier2(baseDir: string, probes?: PolicyReaderProbes): CheckResult;
+/**
+ * Tier 3 — awk block-form parser. Last-resort no-dep fallback.
+ * Practically always present (POSIX requirement).
+ *
+ * 0.40.0 charter item 2 — conditional verdict, refined by codex
+ * round 1 P2:
+ *   - awk present                                            → `pass`
+ *   - awk absent AND Tier 2 reachable                        → `warn`
+ *     (Tier 2 implies python3, which is a list-walker)
+ *   - awk absent AND Tier 1 reachable AND a list walker
+ *     (jq OR python3) is on PATH                             → `warn`
+ *   - awk absent AND Tier 1 reachable BUT no list walker     → `fail`
+ *     (codex round 1 P2 — list-valued policy reads silently
+ *     fail-closed even though scalar reads work, so the
+ *     downgrade-to-warn is misleading; doctor would exit 0 on a
+ *     broken install)
+ *   - awk absent AND no other tier reachable                 → `fail`
+ *
+ * Pre-fix the absent-awk branch always returned `fail` — but when
+ * Tier 1 (rea CLI) AND/OR Tier 2 (python3+PyYAML) are reachable AND
+ * the list walker exists, the operator's effective floor is fine even
+ * without awk; Tier 3 is the LAST fallback, not a hard requirement.
+ * The summary check (`checkPolicyReaderTierSummary`) already
+ * aggregates correctly; this per-tier verdict now reflects the same
+ * severity logic so an operator who reads ONLY the Tier 3 row isn't
+ * misled into thinking the install is broken on a perfectly-
+ * functional box that has python3 + jq + the rea CLI all wired but
+ * happens to lack awk.
+ *
+ * Takes `baseDir` so it can evaluate Tier 1's two-stage check (dist
+ * present + CLI invokable) and Tier 2's reachability. Probes are
+ * threaded through identically.
+ */
+export declare function checkPolicyReaderTier3(baseDir: string, probes?: PolicyReaderProbes): CheckResult;
+/**
+ * jq — optional accelerator used by Tier 1/2's JSON subtree parsing.
+ * Per the 0.37.0 round-1 P2 fix the helper falls back to a python3
+ * walker when jq is absent (still correct, just an extra spawn per
+ * leaf). `warn` when missing so operators know they're paying the
+ * latency cost.
+ *
+ * `info` when present — no action needed, just confirming the
+ * accelerator is wired.
+ */
+export declare function checkPolicyReaderJq(probes?: PolicyReaderProbes): CheckResult;
+/**
+ * Summary roll-up: which tiers are reachable, what's the effective
+ * floor when the CLI is unreachable, and is flow-form policy at risk
+ * of silent no-op.
+ *
+ * Four verdicts:
+ *   - `pass` — Tier 1 OR Tier 2 reachable AND a JSON list walker
+ *     (jq or python3) is available. Flow-form scalars AND flow-form
+ *     arrays both parse correctly via whichever tier is hit first.
+ *   - `warn` (flow-form-lists-degraded) — Tier 1 reachable but neither
+ *     jq nor python3 on PATH. Flow-form SCALARS parse correctly via
+ *     the CLI's JSON output, but `policy_reader_get_list` cannot
+ *     iterate the resulting JSON array — it falls through to Tier 3
+ *     awk, which silently misses flow-form arrays like
+ *     `blocked_paths: [.env, ...]`. Codex round-1 P2 (2026-05-16).
+ *   - `warn` (Tier-3-only) — Only Tier 3 (awk) reachable. Block-form
+ *     policy works; flow-form scalars AND arrays both silently no-op
+ *     on every shim fallback.
+ *   - `fail` — No tiers reachable. Shims fail closed on every policy
+ *     lookup. (Practically requires losing awk too — see Tier 3.)
+ *
+ * Tier 2 implies python3 is on PATH (it's the interpreter that runs
+ * the loader), so when Tier 2 is reachable the list-iteration python3
+ * fallback is also reachable — only the Tier-1-without-list-walker
+ * shape can produce the degraded warning.
+ */
+export declare function checkPolicyReaderTierSummary(baseDir: string, probes?: PolicyReaderProbes): CheckResult;
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last

package/dist/cli/doctor.js

@@ -1,4 +1,4 @@
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsPromises from 'node:fs/promises';
@@ -950,6 +950,649 @@ export function checkCodexBinaryOnPath() {
             'To disable the push-gate instead, set policy.review.codex_required: false in .rea/policy.yaml.',
     };
 }
+/**
+ * 0.39.0 — `rea doctor` visibility into the 4-tier shim policy reader.
+ *
+ * `hooks/_lib/policy-reader.sh` (introduced 0.37.0) is the unified
+ * shim-side policy reader. Each shim sources it and reads policy
+ * values via a graceful-degradation ladder:
+ *
+ *   Tier 1: `rea hook policy-get --json` — canonical TS loader.
+ *   Tier 2: `python3` + stdlib `yaml` (PyYAML).
+ *   Tier 3: `awk` block-form parser (last resort, block-form ONLY).
+ *   Tier 4: fail-closed sentinel.
+ *
+ * The Tier 1/2 path handles BOTH block-form and flow-form YAML
+ * (`local_review: { mode: off }`). Tier 3 only handles block-form, so
+ * a consumer with flow-form policy AND no reachable CLI AND no python3
+ * silently no-ops on every shim fallback path — exactly the split-brain
+ * 0.37.0 set out to fix. The risk persists if the consumer's box lacks
+ * the upper tiers; operators currently have no way to see which tier
+ * their shims would actually use.
+ *
+ * These doctor checks surface the tier inventory so the gap is visible
+ * before it produces a silent regression. Each check is independent and
+ * uses optional probe-function injection so unit tests can simulate any
+ * combination of tier availability without manipulating PATH.
+ *
+ * Pure environment probes — no policy read, no shim spawn. Doctor calls
+ * each one in turn and the summary check aggregates the verdicts.
+ */
+/**
+ * Cheap PATH walker — returns the absolute path of `bin` when found
+ * with an executable bit set, or `null` otherwise. Mirrors
+ * `resolveCodexBinary`'s POSIX path but generalized for any binary.
+ *
+ * Windows path: walks PATHEXT and the bare name like `resolveCodexBinary`
+ * does for `codex`. Most consumer machines that run the shim ladder are
+ * POSIX (the shim is bash); Windows support is best-effort.
+ */
+function resolveBinaryOnPath(bin) {
+    const isWindows = process.platform === 'win32';
+    const pathEnv = process.env.PATH ?? process.env.Path ?? '';
+    if (pathEnv.length === 0)
+        return null;
+    const sep = isWindows ? ';' : ':';
+    const entries = pathEnv.split(sep).filter((p) => p.length > 0);
+    if (isWindows) {
+        const pathExt = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';');
+        for (const dir of entries) {
+            for (const ext of pathExt) {
+                const candidate = path.join(dir, `${bin}${ext}`);
+                try {
+                    const st = fs.statSync(candidate);
+                    if (st.isFile())
+                        return candidate;
+                }
+                catch {
+                    // not present — keep walking
+                }
+            }
+            const bare = path.join(dir, bin);
+            try {
+                const st = fs.statSync(bare);
+                if (st.isFile())
+                    return bare;
+            }
+            catch {
+                // not present — keep walking
+            }
+        }
+        return null;
+    }
+    for (const dir of entries) {
+        const candidate = path.join(dir, bin);
+        try {
+            const st = fs.statSync(candidate);
+            if (st.isFile() && (st.mode & 0o111) !== 0)
+                return candidate;
+        }
+        catch {
+            // not present — keep walking
+        }
+    }
+    return null;
+}
+/** Resolve the shim's preferred CLI dist path, or null when no layout matches. */
+function resolveCliDistPath(baseDir) {
+    // The shim's Tier 1 path requires the rea CLI binary to be
+    // resolvable from the consumer's tree. Two layouts cover every
+    // real-world install:
+    //   1. <baseDir>/node_modules/@bookedsolid/rea/dist/cli/index.js
+    //      (consumer install — `pnpm i @bookedsolid/rea`)
+    //   2. <baseDir>/dist/cli/index.js
+    //      (rea-repo dogfood after `pnpm build`)
+    // Either presence is enough for the shim's sandboxed CLI resolution
+    // (see hooks/_lib/shim-runtime.sh).
+    const consumerCli = path.join(baseDir, 'node_modules', '@bookedsolid', 'rea', 'dist', 'cli', 'index.js');
+    if (fs.existsSync(consumerCli))
+        return consumerCli;
+    const dogfoodCli = path.join(baseDir, 'dist', 'cli', 'index.js');
+    if (fs.existsSync(dogfoodCli))
+        return dogfoodCli;
+    return null;
+}
+function defaultCliDistExists(baseDir) {
+    return resolveCliDistPath(baseDir) !== null;
+}
+/**
+ * Sandbox check — mirrors `shim_sandbox_check` in
+ * `hooks/_lib/shim-runtime.sh` (introduced 0.38.0).
+ *
+ * Codex round-2 P1 (2026-05-16): the pre-fix `defaultCliInvokable`
+ * spawned the resolved CLI WITHOUT this validation. An attacker who
+ * could plant a `dist/cli/index.js` outside `realpath(baseDir)` (via
+ * a symlink) — OR plant one inside the tree but WITHOUT an ancestor
+ * `package.json` whose `name === "@bookedsolid/rea"` — would have
+ * their forged code executed every time doctor probed Tier 1
+ * reachability. The real shim chain refuses these layouts; the
+ * doctor probe MUST refuse them identically so it cannot be tricked
+ * into reporting `pass` on a layout the production shims would
+ * never trust.
+ *
+ * Returns `true` when:
+ *   1. `realpath(cli)` resolves AND lives INSIDE `realpath(baseDir)`
+ *      (no symlink-out of the project)
+ *   2. an ancestor `package.json` (walking up from
+ *      `dirname(dirname(dirname(real)))` — i.e. the package root for
+ *      a `dist/cli/index.js` shape) has `name === "@bookedsolid/rea"`
+ *      (max 20 hops)
+ *
+ * Returns `false` on any failure (realpath miss, escapes-project,
+ * missing/wrong package.json). Doctor's Tier 1 check then treats a
+ * sandbox-failed CLI identically to a CLI-missing layout — both
+ * report `warn` ("Tier 1 unreachable") rather than `pass`.
+ *
+ * This mirrors the bash logic EXACTLY:
+ *   - `fs.realpathSync` on both paths (no symlink slippage)
+ *   - path-prefix containment via `realProj + sep` (so a sibling
+ *     directory whose name STARTS with realProj cannot match)
+ *   - ancestor walk capped at 20 hops with a filesystem-root break
+ *     (`cur === path.dirname(cur)`)
+ *   - JSON parse failures in any candidate `package.json` are
+ *     swallowed and the walk continues (mirrors the bash `try/catch`)
+ *
+ * Kept in sync with the bash helper: any future change to the
+ * sandbox-check shape (e.g. CLI-shape enforcement) MUST be applied
+ * in both places.
+ */
+function sandboxCheckCli(cli, baseDir) {
+    let real;
+    let realProj;
+    try {
+        real = fs.realpathSync(cli);
+    }
+    catch {
+        return false;
+    }
+    try {
+        realProj = fs.realpathSync(baseDir);
+    }
+    catch {
+        return false;
+    }
+    const sep = path.sep;
+    const projWithSep = realProj.endsWith(sep) ? realProj : realProj + sep;
+    if (!(real === realProj || real.startsWith(projWithSep))) {
+        return false;
+    }
+    // Walk ancestor directories from the package root (3 levels up
+    // from a `<root>/dist/cli/index.js` shape) looking for a
+    // package.json whose `name === "@bookedsolid/rea"`. Max 20 hops
+    // with a filesystem-root break so we never loop forever on
+    // exotic mount layouts.
+    let cur = path.dirname(path.dirname(path.dirname(real)));
+    for (let i = 0; i < 20 && cur && cur !== path.dirname(cur); i += 1) {
+        const pj = path.join(cur, 'package.json');
+        if (fs.existsSync(pj)) {
+            try {
+                const data = JSON.parse(fs.readFileSync(pj, 'utf8'));
+                if (data && data.name === '@bookedsolid/rea') {
+                    return true;
+                }
+            }
+            catch {
+                // keep walking — malformed package.json on the path is not fatal
+            }
+        }
+        cur = path.dirname(cur);
+    }
+    return false;
+}
+/**
+ * Codex round-1 P2 (2026-05-16): the file-presence probe alone allows
+ * a stale or broken dist (e.g. an upgrade-lagged consumer who never
+ * re-ran `pnpm build`) to falsely report `pass` while the real shim
+ * ladder in `hooks/_lib/policy-reader.sh` would skip Tier 1 because
+ * `rea hook policy-get version --json` exits non-zero. We mirror that
+ * exact probe verbatim — same key (`version`), same `--json` flag,
+ * same accept-criterion (exit 0 + non-empty stdout).
+ *
+ * Codex round-2 P1 (2026-05-16): BEFORE invoking the resolved CLI,
+ * apply the same realpath + ancestor-package.json sandbox check the
+ * shims apply in `hooks/_lib/shim-runtime.sh::shim_sandbox_check`.
+ * Pre-fix, an attacker who could plant a `dist/cli/index.js` via a
+ * symlink-out (or without a `@bookedsolid/rea` package.json ancestor)
+ * would have their forged code executed every probe call — yet the
+ * real shim ladder would refuse the same layout. This probe MUST
+ * refuse identically so it cannot mis-report `pass` on an
+ * unsandboxed CLI.
+ *
+ * Returns `true` when the CLI responds correctly; `false` when the
+ * dist is missing OR present-but-broken OR present-but-unsandboxed.
+ * Doctor's Tier 1 check then surfaces the difference: missing →
+ * install guidance; broken/unsandboxed → rebuild guidance. (The
+ * unsandboxed branch deliberately collapses into the "broken" bucket
+ * because either way Tier 1 is unreachable for the shim chain.)
+ *
+ * 8s timeout: the CLI's `hook policy-get` path is local-only (zod
+ * load + YAML parse + JSON walk); on any reasonable machine it
+ * resolves in under a second. The timeout is a defense against a CLI
+ * that hangs on import (a broken postinstall, a missing native module)
+ * rather than a normal-operation budget.
+ */
+function defaultCliInvokable(baseDir) {
+    const cli = resolveCliDistPath(baseDir);
+    if (cli === null)
+        return false;
+    // Codex round-2 P1: sandbox check BEFORE spawn. Pre-fix the probe
+    // spawned arbitrary code that happened to live at the expected
+    // shim-resolved path; if a symlink-out OR a missing rea
+    // package.json ancestor existed, we executed an attacker payload.
+    if (!sandboxCheckCli(cli, baseDir))
+        return false;
+    try {
+        const res = spawnSync('node', [cli, 'hook', 'policy-get', 'version', '--json'], {
+            cwd: baseDir,
+            timeout: 8_000,
+            // Tier 1 reads policy.yaml at REA_ROOT — propagate so the probe
+            // honors the same scope the real shim chain would (a missing
+            // `CLAUDE_PROJECT_DIR` falls back to cwd, which doctor has
+            // already set).
+            env: { ...process.env, CLAUDE_PROJECT_DIR: baseDir },
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (res.status !== 0)
+            return false;
+        const out = (res.stdout ?? '').trim();
+        return out.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultPython3PyYamlReachable(baseDir) {
+    // The Tier 2 loader runs `python3 -c "import yaml"`. We mirror that
+    // probe verbatim so a `yaml`-installable-but-broken interpreter is
+    // not falsely reported as "reachable". Apply the SAME env scrub
+    // (PYTHONPATH / PYTHONHOME / PYTHONSTARTUP unset, PYTHONSAFEPATH=1)
+    // that policy-reader.sh applies, so a repo-local `yaml.py` cannot
+    // shadow the stdlib copy here either — otherwise this probe would
+    // report `true` against a malicious repo where the actual loader
+    // would (correctly) refuse to import.
+    //
+    // Codex round-3 P1 (2026-05-16): `PYTHONSAFEPATH=1` is the env-var
+    // form of `python3 -P` and is only honored on Python 3.11+. On
+    // Python 3.4-3.10 (still installed by default on macOS Big Sur /
+    // Monterey / Ventura, RHEL 8, Ubuntu 20.04, …) it is SILENTLY
+    // IGNORED — meaning the interpreter will still prepend `""`/`"."`/
+    // CWD to `sys.path[0]` and import a repo-local `./yaml.py` instead
+    // of the stdlib copy. The production loader in
+    // hooks/_lib/policy-reader.sh closes this gap with a defensive
+    // sys.path scrub at the top of every `python3 -c` body (see the
+    // "Codex round 2 P1" comment block in policy-reader.sh:256-267).
+    // We MUST mirror that scrub here — without it, a malicious repo
+    // could plant `./yaml.py`, get this probe to report `true`, while
+    // the real Tier 2 loader (which DOES scrub) refuses to import and
+    // falls through to Tier 3. The doctor verdict would then point
+    // operators at the wrong tier when diagnosing a stuck shim.
+    try {
+        const probeEnv = { ...process.env, PYTHONSAFEPATH: '1' };
+        delete probeEnv['PYTHONPATH'];
+        delete probeEnv['PYTHONHOME'];
+        delete probeEnv['PYTHONSTARTUP'];
+        // Same scrub shape as policy-reader.sh's Tier 2 body — strip
+        // empty/CWD entries from sys.path BEFORE the `import yaml` so
+        // the probe and the production loader produce the same answer
+        // on Python 3.4-3.10.
+        const probeBody = [
+            'import sys',
+            'import os',
+            '_cwd = os.getcwd()',
+            '_cwd_real = os.path.realpath(_cwd)',
+            'sys.path[:] = [p for p in sys.path if p not in ("", ".", _cwd, _cwd_real)]',
+            'import yaml',
+        ].join('\n');
+        // 0.40.0 charter item 3 — thread `baseDir` as cwd so the sys.path
+        // scrub above strips THIS consumer's repo root (the directory the
+        // production shim chain runs from), not doctor's own cwd. Pre-fix,
+        // `rea doctor --base-dir <consumer>` invoked from `/tmp/foo` would
+        // scrub against `/tmp/foo`, leaving any `<consumer>/yaml.py`
+        // shadowing potential undetected — exactly the multi-repo workflow
+        // every other doctor probe (cliInvokable, …) already handles by
+        // setting cwd to baseDir.
+        const res = spawnSync('python3', ['-c', probeBody], {
+            cwd: baseDir,
+            env: probeEnv,
+            timeout: 5_000,
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+        return res.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+const DEFAULT_PROBES = {
+    cliDistExists: defaultCliDistExists,
+    cliInvokable: defaultCliInvokable,
+    python3OnPath: () => resolveBinaryOnPath('python3'),
+    python3PyYamlReachable: defaultPython3PyYamlReachable,
+    awkOnPath: () => resolveBinaryOnPath('awk'),
+    jqOnPath: () => resolveBinaryOnPath('jq'),
+};
+function resolveProbes(probes) {
+    if (probes === undefined)
+        return DEFAULT_PROBES;
+    return { ...DEFAULT_PROBES, ...probes };
+}
+/**
+ * Tier 1 — `rea hook policy-get`. Reachable when the rea CLI is
+ * present at one of the two shim-resolved paths (consumer install OR
+ * dogfood `dist/`) AND actually responds to `rea hook policy-get
+ * version --json`. The shim ladder uses that exact invocation as its
+ * Tier 1 probe (see `_pr_load_full_json` in `hooks/_lib/policy-reader.sh`);
+ * mirroring it here means a stale or broken dist (file present but
+ * import-throws / postinstall failed) reports `warn` — matching the
+ * real fall-through to Tier 2/3 the shim would do at runtime.
+ *
+ * Three states:
+ *   - dist present + CLI responds → `pass` (canonical loader fully wired).
+ *   - dist present + CLI broken → `warn` (stale build, missing native
+ *     module, broken postinstall — needs `pnpm build` / `rea upgrade`).
+ *   - dist absent → `warn` (not installed; Tier 2/3 still cover).
+ *
+ * Codex round-1 P2 (2026-05-16) replaced the file-existence-only
+ * probe with this CLI-invocation probe — pre-fix, a consumer with
+ * `dist/cli/index.js` present but throwing on load would see `pass`
+ * here while every real shim would silently fall through.
+ */
+export function checkPolicyReaderTier1(baseDir, probes) {
+    const label = 'policy-reader Tier 1 (rea CLI)';
+    const p = resolveProbes(probes);
+    const distPresent = p.cliDistExists(baseDir);
+    if (!distPresent) {
+        return {
+            label,
+            status: 'warn',
+            detail: 'rea CLI dist not found at node_modules/@bookedsolid/rea/dist/cli/index.js or <baseDir>/dist/cli/index.js — ' +
+                'shims fall through to Tier 2/3 (works, but loses validated schema + full subtree shapes). ' +
+                'Consumer: run `pnpm i @bookedsolid/rea`. Dogfood: run `pnpm build`.',
+        };
+    }
+    if (!p.cliInvokable(baseDir)) {
+        return {
+            label,
+            status: 'warn',
+            detail: 'rea CLI dist exists but `rea hook policy-get version --json` failed — the dist is ' +
+                'stale or broken (incomplete build, missing native module, broken postinstall). The ' +
+                'shim ladder will skip Tier 1 and fall through to Tier 2/3 just as this probe did. ' +
+                'Run `pnpm build` (dogfood) or `rea upgrade` (consumer) to rebuild.',
+        };
+    }
+    return {
+        label,
+        status: 'pass',
+        detail: 'rea CLI dist responds to `hook policy-get version --json` — canonical loader fully wired',
+    };
+}
+/**
+ * Tier 2 — python3 + stdlib `yaml` (PyYAML). Handles BOTH block-form
+ * and flow-form YAML; the practical floor when Tier 1 is unreachable.
+ *
+ * Three states:
+ *   - python3 present + PyYAML importable → `pass`.
+ *   - python3 present, PyYAML missing → `warn` (the loader will fall
+ *     through to Tier 3, which only handles block-form).
+ *   - python3 absent → `warn` (same Tier 3 fall-through).
+ *
+ * Never `fail` — Tier 3 is still a valid floor for block-form policy.
+ * The warning highlights the silent no-op risk for flow-form lookups
+ * when CLI is also unreachable.
+ */
+export function checkPolicyReaderTier2(baseDir, probes) {
+    const label = 'policy-reader Tier 2 (python3 + PyYAML)';
+    const p = resolveProbes(probes);
+    const py = p.python3OnPath();
+    if (py === null) {
+        return {
+            label,
+            status: 'warn',
+            detail: 'python3 not on PATH — Tier 2 unavailable. Shims fall through to Tier 3 (awk, ' +
+                'block-form only). Flow-form policy (e.g. `local_review: { mode: off }`) silently ' +
+                'no-ops when the rea CLI is also unreachable. Install python3 to close this gap.',
+        };
+    }
+    if (!p.python3PyYamlReachable(baseDir)) {
+        return {
+            label,
+            status: 'warn',
+            detail: `python3 found at ${py} but \`import yaml\` failed — PyYAML missing. ` +
+                'Shims fall through to Tier 3 (awk, block-form only). Flow-form policy silently ' +
+                'no-ops when the rea CLI is also unreachable. Install: `pip3 install pyyaml`.',
+        };
+    }
+    return {
+        label,
+        status: 'pass',
+        detail: `python3 + PyYAML reachable at ${py} — flow-form policy parses correctly`,
+    };
+}
+/**
+ * Tier 3 — awk block-form parser. Last-resort no-dep fallback.
+ * Practically always present (POSIX requirement).
+ *
+ * 0.40.0 charter item 2 — conditional verdict, refined by codex
+ * round 1 P2:
+ *   - awk present                                            → `pass`
+ *   - awk absent AND Tier 2 reachable                        → `warn`
+ *     (Tier 2 implies python3, which is a list-walker)
+ *   - awk absent AND Tier 1 reachable AND a list walker
+ *     (jq OR python3) is on PATH                             → `warn`
+ *   - awk absent AND Tier 1 reachable BUT no list walker     → `fail`
+ *     (codex round 1 P2 — list-valued policy reads silently
+ *     fail-closed even though scalar reads work, so the
+ *     downgrade-to-warn is misleading; doctor would exit 0 on a
+ *     broken install)
+ *   - awk absent AND no other tier reachable                 → `fail`
+ *
+ * Pre-fix the absent-awk branch always returned `fail` — but when
+ * Tier 1 (rea CLI) AND/OR Tier 2 (python3+PyYAML) are reachable AND
+ * the list walker exists, the operator's effective floor is fine even
+ * without awk; Tier 3 is the LAST fallback, not a hard requirement.
+ * The summary check (`checkPolicyReaderTierSummary`) already
+ * aggregates correctly; this per-tier verdict now reflects the same
+ * severity logic so an operator who reads ONLY the Tier 3 row isn't
+ * misled into thinking the install is broken on a perfectly-
+ * functional box that has python3 + jq + the rea CLI all wired but
+ * happens to lack awk.
+ *
+ * Takes `baseDir` so it can evaluate Tier 1's two-stage check (dist
+ * present + CLI invokable) and Tier 2's reachability. Probes are
+ * threaded through identically.
+ */
+export function checkPolicyReaderTier3(baseDir, probes) {
+    const label = 'policy-reader Tier 3 (awk)';
+    const p = resolveProbes(probes);
+    const awk = p.awkOnPath();
+    if (awk !== null) {
+        return {
+            label,
+            status: 'pass',
+            detail: `awk at ${awk} — block-form fallback available`,
+        };
+    }
+    // 0.40.0 — awk is absent. Decide whether this is `warn` (other tiers
+    // cover) or `fail` (catastrophic — no working policy lookup tier).
+    // Mirror Tier 1's two-stage check (dist + invokable) and Tier 2's
+    // python3 + PyYAML pair so the verdict here matches what the shim
+    // ladder would actually do at runtime.
+    const tier1 = p.cliDistExists(baseDir) && p.cliInvokable(baseDir);
+    const tier2 = p.python3OnPath() !== null && p.python3PyYamlReachable(baseDir);
+    // Codex round 1 P2 (2026-05-16): the downgrade-to-warn branch needs
+    // a list walker too. `policy_reader_get_list` (the helper that reads
+    // list-valued keys like `blocked_paths`) iterates the parsed JSON
+    // array via jq OR python3, falling back to Tier 3 awk for inline
+    // arrays. With awk gone AND no jq AND no python3, list-valued
+    // policy reads silently fail-closed even when Tier 1 is reachable —
+    // `blocked-paths-bash-gate.sh` etc. would see an EMPTY blocked-paths
+    // set and stop enforcing entries the operator declared. Pre-fix
+    // this concrete shape (cliInvokable + no python3 + no jq + no awk)
+    // returned `warn` and the doctor exited 0 on a broken install.
+    // Post-fix the downgrade requires a list walker; otherwise we stay
+    // on `fail`. Tier 2 implies python3 on PATH (the interpreter that
+    // ran PyYAML), so Tier 2 always brings list-walker support — no
+    // additional check needed for the Tier-2 branch.
+    const py = p.python3OnPath();
+    const listWalker = p.jqOnPath() !== null || py !== null;
+    if (tier2 || (tier1 && listWalker)) {
+        const reachable = [];
+        if (tier1)
+            reachable.push('Tier 1 (rea CLI)');
+        if (tier2)
+            reachable.push('Tier 2 (python3+PyYAML)');
+        return {
+            label,
+            status: 'warn',
+            detail: `awk not on PATH — Tier 3 (block-form fallback) unreachable. ${reachable.join(' and ')} ` +
+                'still cover the shim ladder, so policy lookups continue to work; this is a ' +
+                'soft degradation, not a hard failure. Install awk (`mawk`, `gawk`, or `nawk`) ' +
+                'to restore the last-resort fallback.',
+        };
+    }
+    // Codex round 1 P2: separate "no list walker" diagnosis from the
+    // catastrophic "no tier at all" case. Tier 1 reachable but no jq
+    // AND no python3 AND no awk means list-valued policy reads
+    // fail-closed silently — distinct from the truly-empty
+    // no-CLI-no-python-no-awk shape, and worth a precise remediation.
+    if (tier1) {
+        return {
+            label,
+            status: 'fail',
+            detail: 'awk not on PATH AND neither jq nor python3 is on PATH — Tier 1 (rea CLI) parses ' +
+                'flow-form scalars, but `policy_reader_get_list` cannot iterate list-valued keys ' +
+                '(e.g. `blocked_paths: [.env, ...]`) without jq, python3, OR awk to walk the ' +
+                'resulting JSON arrays. Affected hooks (`blocked-paths-bash-gate.sh`, ' +
+                '`blocked-paths-enforcer.sh`, …) see an EMPTY list and silently stop enforcing. ' +
+                'Install awk OR jq OR python3 to restore list-iteration.',
+        };
+    }
+    return {
+        label,
+        status: 'fail',
+        detail: 'awk not on PATH — no fallback tier reachable. If the rea CLI and python3+PyYAML are ' +
+            'ALSO unreachable, every shim policy lookup fails closed. This is unusual; awk is a ' +
+            'POSIX requirement. Install awk (`mawk`, `gawk`, or `nawk`).',
+    };
+}
+/**
+ * jq — optional accelerator used by Tier 1/2's JSON subtree parsing.
+ * Per the 0.37.0 round-1 P2 fix the helper falls back to a python3
+ * walker when jq is absent (still correct, just an extra spawn per
+ * leaf). `warn` when missing so operators know they're paying the
+ * latency cost.
+ *
+ * `info` when present — no action needed, just confirming the
+ * accelerator is wired.
+ */
+export function checkPolicyReaderJq(probes) {
+    const label = 'policy-reader jq (JSON accelerator)';
+    const p = resolveProbes(probes);
+    const jq = p.jqOnPath();
+    if (jq !== null) {
+        return {
+            label,
+            status: 'pass',
+            detail: `jq at ${jq} — used by Tier 1/2 JSON subtree walking`,
+        };
+    }
+    return {
+        label,
+        status: 'warn',
+        detail: 'jq not on PATH — Tier 1/2 fall back to a python3 JSON walker per leaf (correct, ' +
+            'just slower). Install jq to reduce per-leaf spawn overhead.',
+    };
+}
+/**
+ * Summary roll-up: which tiers are reachable, what's the effective
+ * floor when the CLI is unreachable, and is flow-form policy at risk
+ * of silent no-op.
+ *
+ * Four verdicts:
+ *   - `pass` — Tier 1 OR Tier 2 reachable AND a JSON list walker
+ *     (jq or python3) is available. Flow-form scalars AND flow-form
+ *     arrays both parse correctly via whichever tier is hit first.
+ *   - `warn` (flow-form-lists-degraded) — Tier 1 reachable but neither
+ *     jq nor python3 on PATH. Flow-form SCALARS parse correctly via
+ *     the CLI's JSON output, but `policy_reader_get_list` cannot
+ *     iterate the resulting JSON array — it falls through to Tier 3
+ *     awk, which silently misses flow-form arrays like
+ *     `blocked_paths: [.env, ...]`. Codex round-1 P2 (2026-05-16).
+ *   - `warn` (Tier-3-only) — Only Tier 3 (awk) reachable. Block-form
+ *     policy works; flow-form scalars AND arrays both silently no-op
+ *     on every shim fallback.
+ *   - `fail` — No tiers reachable. Shims fail closed on every policy
+ *     lookup. (Practically requires losing awk too — see Tier 3.)
+ *
+ * Tier 2 implies python3 is on PATH (it's the interpreter that runs
+ * the loader), so when Tier 2 is reachable the list-iteration python3
+ * fallback is also reachable — only the Tier-1-without-list-walker
+ * shape can produce the degraded warning.
+ */
+export function checkPolicyReaderTierSummary(baseDir, probes) {
+    const label = 'policy-reader effective floor';
+    const p = resolveProbes(probes);
+    // Mirror Tier 1's two-stage check — dist present + CLI invokable.
+    // A stale/broken dist that fails the invokable probe is treated as
+    // "Tier 1 not reachable" so the summary matches what the shim
+    // ladder would actually do at runtime.
+    const tier1 = p.cliDistExists(baseDir) && p.cliInvokable(baseDir);
+    const py = p.python3OnPath();
+    const tier2 = py !== null && p.python3PyYamlReachable(baseDir);
+    const tier3 = p.awkOnPath() !== null;
+    const jq = p.jqOnPath();
+    // List iteration after Tier 1/2 needs jq OR python3 to walk the
+    // JSON. Tier 2 implies python3 on PATH (the interpreter that ran
+    // the loader); so the only "lists broken" shape is Tier 1 reachable
+    // but neither jq nor python3 on PATH.
+    const listWalker = jq !== null || py !== null;
+    const reachable = [];
+    if (tier1)
+        reachable.push('Tier 1 (CLI)');
+    if (tier2)
+        reachable.push('Tier 2 (python3+PyYAML)');
+    if (tier3)
+        reachable.push('Tier 3 (awk)');
+    if (tier1 || tier2) {
+        if (!listWalker) {
+            // Tier 1 + no python3/jq. flow-form scalars work; flow-form
+            // arrays silently no-op via Tier 3 fallthrough. (Tier 2 path
+            // is unreachable here because Tier 2 requires python3.)
+            return {
+                label,
+                status: 'warn',
+                detail: `${reachable.join(', ')} reachable — flow-form scalars parse via Tier 1 CLI, ` +
+                    'BUT neither jq nor python3 is on PATH so `policy_reader_get_list` cannot iterate ' +
+                    'the resulting JSON arrays. Flow-form list policy (e.g. `blocked_paths: [.env, ...]`) ' +
+                    'silently falls through to Tier 3 awk and misses inline arrays. Install jq ' +
+                    '(`brew install jq` / `apt-get install jq`) or python3 to close the gap.',
+            };
+        }
+        return {
+            label,
+            status: 'pass',
+            detail: `${reachable.join(', ')} reachable — flow-form policy parses correctly`,
+        };
+    }
+    if (tier3) {
+        return {
+            label,
+            status: 'warn',
+            detail: 'only Tier 3 (awk, block-form ONLY) reachable — flow-form policy ' +
+                '(e.g. `local_review: { mode: off }`, `blocked_paths: [.env, ...]`) silently ' +
+                'no-ops on every shim fallback path. Restore Tier 1 (rea CLI dist) or Tier 2 ' +
+                '(python3 + PyYAML) to close the gap.',
+        };
+    }
+    return {
+        label,
+        status: 'fail',
+        detail: 'no policy-reader tier reachable — every shim policy lookup fails closed. ' +
+            'Install at least one of: rea CLI dist (Tier 1), python3 + PyYAML (Tier 2), ' +
+            'awk (Tier 3).',
+    };
+}
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last
@@ -1457,9 +2100,15 @@ export function collectChecks(baseDir, codexProbeState, prePushState, options =
     const policyPath = reaPath(baseDir, POLICY_FILE);
     const registryPath = reaPath(baseDir, REGISTRY_FILE);
     const reaDirPath = path.join(baseDir, REA_DIR);
+    // Run checkPolicyParses up-front so we can both push its result and
+    // use the verdict to gate the 0.39.0 policy-reader tier checks below.
+    // A malformed policy file should NOT trigger the tier-reachability
+    // probes — those reports would misattribute a parse failure to a
+    // runtime/install problem (codex round-3 P2, 2026-05-16).
+    const policyParsesResult = checkPolicyParses(baseDir, policyPath);
     const checks = [
         checkFileExists('.rea/ directory exists', reaDirPath, true),
-        checkPolicyParses(baseDir, policyPath),
+        policyParsesResult,
         checkRegistryParses(baseDir, registryPath),
         checkAgentsPresent(baseDir),
         checkHooksInstalled(baseDir),
@@ -1482,6 +2131,30 @@ export function collectChecks(baseDir, codexProbeState, prePushState, options =
         // went through in 0.29.0 → 0.30.0, after 4 release cycles of
         // propagation).
         checkDelegationAdvisoryHookRegistered(baseDir),
+        // 0.39.0 — policy-reader tier visibility. Surfaces which tiers of
+        // the 4-tier `hooks/_lib/policy-reader.sh` ladder are reachable in
+        // this environment so operators can SEE whether flow-form policy
+        // would silently no-op when the CLI is unreachable.
+        //
+        // Codex round-3 P2 (2026-05-16): gated on `policyParsesResult`
+        // being a `pass` — NOT just `existsSync(policyPath)`. A
+        // malformed policy file (present but unparseable) should report
+        // exactly ONE failure — the parse-error from `checkPolicyParses`
+        // above — and not also light up the tier probes with misleading
+        // "Tier 1 dist exists but failed" or summary "ladder degraded"
+        // diagnostics that misattribute a config bug to an
+        // install/runtime problem. The parse-failure row already tells
+        // the operator the right thing to fix; adding more downstream
+        // noise would obscure it.
+        ...(policyParsesResult.status === 'pass'
+            ? [
+                checkPolicyReaderTier1(baseDir),
+                checkPolicyReaderTier2(baseDir),
+                checkPolicyReaderTier3(baseDir),
+                checkPolicyReaderJq(),
+                checkPolicyReaderTierSummary(baseDir),
+            ]
+            : []),
     ];
     // Non-git escape hatch: when `.git/` is absent, both git-hook checks are
     // meaningless (commit-msg + pre-push can't be invoked without git). Emit

package/package.json

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