@bookedsolid/rea 0.39.0 → 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

@@ -124,7 +124,20 @@ export interface PolicyReaderProbes {
     cliDistExists?: (baseDir: string) => boolean;
     cliInvokable?: (baseDir: string) => boolean;
     python3OnPath?: () => string | null;
-    python3PyYamlReachable?: () => boolean;
+    /**
+     * 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;
 }
@@ -164,15 +177,41 @@ export declare function checkPolicyReaderTier1(baseDir: string, probes?: PolicyR
  * The warning highlights the silent no-op risk for flow-form lookups
  * when CLI is also unreachable.
  */
-export declare function checkPolicyReaderTier2(probes?: PolicyReaderProbes): CheckResult;
+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); hard-fail only when
- * truly absent (in which case the consumer has ZERO working fallback
- * tiers and any CLI-absent shim invocation will silently fail-closed
- * on every policy lookup).
+ * 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(probes?: PolicyReaderProbes): CheckResult;
+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

package/dist/cli/doctor.js

@@ -1202,7 +1202,7 @@ function defaultCliInvokable(baseDir) {
         return false;
     }
 }
-function defaultPython3PyYamlReachable() {
+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
@@ -1244,7 +1244,16 @@ function defaultPython3PyYamlReachable() {
             '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'],
@@ -1332,7 +1341,7 @@ export function checkPolicyReaderTier1(baseDir, probes) {
  * The warning highlights the silent no-op risk for flow-form lookups
  * when CLI is also unreachable.
  */
-export function checkPolicyReaderTier2(probes) {
+export function checkPolicyReaderTier2(baseDir, probes) {
     const label = 'policy-reader Tier 2 (python3 + PyYAML)';
     const p = resolveProbes(probes);
     const py = p.python3OnPath();
@@ -1345,7 +1354,7 @@ export function checkPolicyReaderTier2(probes) {
                 'no-ops when the rea CLI is also unreachable. Install python3 to close this gap.',
         };
     }
-    if (!p.python3PyYamlReachable()) {
+    if (!p.python3PyYamlReachable(baseDir)) {
         return {
             label,
             status: 'warn',
@@ -1362,12 +1371,38 @@ export function checkPolicyReaderTier2(probes) {
 }
 /**
  * Tier 3 — awk block-form parser. Last-resort no-dep fallback.
- * Practically always present (POSIX requirement); hard-fail only when
- * truly absent (in which case the consumer has ZERO working fallback
- * tiers and any CLI-absent shim invocation will silently fail-closed
- * on every policy lookup).
+ * 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(probes) {
+export function checkPolicyReaderTier3(baseDir, probes) {
     const label = 'policy-reader Tier 3 (awk)';
     const p = resolveProbes(probes);
     const awk = p.awkOnPath();
@@ -1378,6 +1413,61 @@ export function checkPolicyReaderTier3(probes) {
             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',
@@ -1449,7 +1539,7 @@ export function checkPolicyReaderTierSummary(baseDir, probes) {
     // ladder would actually do at runtime.
     const tier1 = p.cliDistExists(baseDir) && p.cliInvokable(baseDir);
     const py = p.python3OnPath();
-    const tier2 = py !== null && p.python3PyYamlReachable();
+    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
@@ -2059,8 +2149,8 @@ export function collectChecks(baseDir, codexProbeState, prePushState, options =
         ...(policyParsesResult.status === 'pass'
             ? [
                 checkPolicyReaderTier1(baseDir),
-                checkPolicyReaderTier2(),
-                checkPolicyReaderTier3(),
+                checkPolicyReaderTier2(baseDir),
+                checkPolicyReaderTier3(baseDir),
                 checkPolicyReaderJq(),
                 checkPolicyReaderTierSummary(baseDir),
             ]

package/package.json

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