@bookedsolid/rea 0.30.0 → 0.31.0

package/dist/cli/doctor.d.ts

@@ -109,56 +109,127 @@ export declare function checksFromProbeState(state: CodexProbeState): CheckResul
  * `.claude/settings.json` under PreToolUse with matcher `Agent|Skill`
  * AND that the hook file exists at the expected dogfood path.
  *
- * Status posture for 0.29.0:
- *
- * The 0.29.0 release introduces a new desired-hook entry in
- * `defaultDesiredHooks()` that `rea init` and `rea upgrade` will merge
- * into consumer `.claude/settings.json` files. Existing consumer
- * installs (and this repo's own dogfood, which is locked from
- * agent-driven edits by `settings-protection.sh`) won't have the
- * matcher registered until the operator runs `rea upgrade`.
- *
- * To keep the upgrade-lag period from breaking `rea doctor`, the
- * check is `warn` (not `fail`) for 0.29.0. The detail message names
- * the exact command to fix and points at the canonical
- * `delegation-capture.sh` install. After 0.29.0+1 consumer-install
- * cycles have propagated, this should be promoted to `fail` so a
- * skipped upgrade is loud rather than silent. Codex round 2 P2
- * (2026-05-12).
+ * Status posture:
+ *
+ * 0.29.0 shipped this check as `warn` (advisory) — the
+ * `defaultDesiredHooks()` entry was new, and existing consumer
+ * installs (plus this repo's own dogfood, locked from agent-driven
+ * edits by `settings-protection.sh`) wouldn't have the matcher
+ * registered until the operator ran `rea upgrade`. The comments
+ * promised promotion to `fail` "in 0.30.0".
+ *
+ * **0.31.0 makes good on that promise.** The 0.29.0 → 0.30.x consumer
+ * cycles have propagated; the `Agent|Skill` matcher has been in
+ * `defaultDesiredHooks()` for multiple minors. A consumer install
+ * that still lacks the registration is a real governance gap (the
+ * delegation telemetry — and now the 0.31.0 nudge — silently does
+ * nothing), so the check is `fail`. The detail message still names
+ * the exact `rea upgrade` fix.
  *
  * Hook-file presence is verified separately by `checkHooksInstalled`
- * via `EXPECTED_HOOKS` — that path stays at the hard-`fail` posture
- * because file presence is part of the install manifest and doesn't
- * suffer the same template-propagation lag.
+ * via `EXPECTED_HOOKS` — that path was always hard-`fail`.
  */
 export declare function checkDelegationHookRegistered(baseDir: string): CheckResult;
+/**
+ * 0.31.0 — verify the delegation-advisory hook is registered in
+ * `.claude/settings.json` under PostToolUse with matcher
+ * `Bash|Edit|Write|MultiEdit|NotebookEdit`, that a
+ * `delegation-advisory.sh` command is present in that group, AND that
+ * the `.claude/hooks/delegation-advisory.sh` file actually exists.
+ *
+ * Status posture: `warn` (advisory) for 0.31.0. This is a brand-new
+ * `defaultDesiredHooks()` entry — the exact same upgrade-lag situation
+ * `checkDelegationHookRegistered` faced in 0.29.0. Existing consumer
+ * installs (and this repo's own dogfood, locked from agent-driven
+ * edits by `settings-protection.sh`) won't have the PostToolUse group
+ * until the operator runs `rea upgrade`. Holding at `warn` for one
+ * release cycle keeps `rea doctor` green during propagation; a future
+ * minor promotes it to `fail` once consumer installs have caught up —
+ * the same ratchet `checkDelegationHookRegistered` just completed.
+ *
+ * The hook is ALSO advisory at runtime (it never blocks a tool call,
+ * and `policy.delegation_advisory` defaults to disabled), so a missing
+ * registration is a lower-stakes gap than a missing security gate —
+ * `warn` is proportionate even setting the upgrade-lag aside.
+ *
+ * # Why this check verifies file presence AND executability (round-2/3 P2)
+ *
+ * `delegation-advisory.sh` is deliberately NOT in `EXPECTED_HOOKS` for
+ * 0.31.0 (staged rollout — see the `EXPECTED_HOOKS` comment). That
+ * leaves THIS function as the only 0.31.0 doctor signal covering the
+ * new hook, so it must check the file too:
+ *
+ *   - File MISSING — a settings.json that references
+ *     `delegation-advisory.sh` while the actual script is absent (a
+ *     partial `rea upgrade`, manual drift) would otherwise report
+ *     `pass`, and every matching PostToolUse dispatch would shell out
+ *     to a nonexistent path.
+ *   - File present but NOT EXECUTABLE — a script copied without its
+ *     mode bits (a manual `cp`, an archive extracted without `+x`
+ *     preservation) cannot be launched by Claude Code from
+ *     `settings.json` at all. `checkHooksInstalled` performs this exact
+ *     `0o111` check for every `EXPECTED_HOOKS` entry; because
+ *     `delegation-advisory.sh` is held out of that list, the parity
+ *     check has to live here.
+ *
+ * Both failures are held at the same `warn` tier as the registration
+ * failures: consistent posture for 0.31.0, and they promote to `fail`
+ * alongside them — at which point `delegation-advisory.sh` also joins
+ * `EXPECTED_HOOKS` and gets the hard-`fail` `checkHooksInstalled`
+ * coverage (presence + executability) the other hooks have.
+ */
+export declare function checkDelegationAdvisoryHookRegistered(baseDir: string): CheckResult;
 /**
  * 0.29.0 — synthetic round-trip of the delegation-signal audit path.
- * Drives a synthetic Claude Code PreToolUse hook payload through the
- * REAL `rea hook delegation-signal` CLI by spawning a child process
- * (same path the shell hook hits) and asserts:
+ * 0.31.0 — drives the REAL `.claude/hooks/delegation-capture.sh` shell
+ * hook, not just the `rea hook delegation-signal` CLI underneath it.
  *
- *   - The CLI exited 0.
- *   - A new `rea.delegation_signal` record landed on disk.
+ * Feeds a synthetic Claude Code PreToolUse hook payload to the shell
+ * hook (the exact entry point Claude Code's `Agent|Skill` matcher
+ * invokes in production) and asserts:
+ *
+ *   - The shell hook exited 0.
+ *   - A new `rea.delegation_signal` record landed on disk — the smoke
+ *     check POLLS for it, because `delegation-capture.sh` backgrounds
+ *     + disowns the CLI (`& disown`) so the shell hook returns before
+ *     the audit append completes.
  *   - The record's metadata contains the probe tag (so we don't
  *     mistakenly attribute an existing record to our run).
+ *   - The recorded `invocation_description_sha256` matches the
+ *     expected hash of the probe description.
  *   - Chain integrity holds (recomputed hash == stored hash).
  *
- * Codex round 1 P2 (2026-05-12): the previous implementation called
- * `appendAuditRecord()` directly — short-circuiting stdin parsing,
- * SHA-256 hashing, redact-secrets timing, and the `process.exit`
- * ordering that round 1's P1 exposed. That made the smoke check
- * report success even when the real production path was broken.
- *
- * This rewrite exercises the same surface the `Agent|Skill`
- * PreToolUse hook does in production, so future regressions in
- * stdin parsing, hashing, redaction, or process-lifecycle behavior
- * fail the smoke check loudly.
- *
- * Gated behind `--smoke` so a casual `rea doctor` doesn't write
- * probe records on every invocation. Operators run
- * `rea doctor --smoke` after install / upgrade to confirm the
- * pipeline is wired end-to-end.
+ * # Why drive the shell hook, not the CLI directly
+ *
+ * 0.29.0's version spawned `rea hook delegation-signal` directly. That
+ * exercised the CLI's stdin parsing / hashing / redaction / process-
+ * lifecycle — but NOT the shell shim's own logic: the 2-tier sandboxed
+ * CLI resolution, the realpath sandbox check, the `& disown`
+ * backgrounding. A regression in the shim (a botched resolution order,
+ * a sandbox check that rejects the legitimate dogfood CLI, a
+ * backgrounding bug that drops the signal) would pass 0.29.0's smoke
+ * check while breaking production. 0.31.0 closes that gap: the smoke
+ * check now invokes `bash .claude/hooks/delegation-capture.sh` and
+ * the CLI is reached only through the shim.
+ *
+ * # Prerequisites and graceful degradation
+ *
+ * The check needs THREE things and degrades to `warn` (not `fail`)
+ * when any is absent — a missing prerequisite is an environment gap,
+ * not a wiring regression:
+ *
+ *   - `bash` on PATH.
+ *   - `.claude/hooks/delegation-capture.sh` present (the consumer
+ *     install path; absent before `rea init` / `rea upgrade`).
+ *   - A sandboxed rea CLI the shim can resolve — either
+ *     `<baseDir>/node_modules/@bookedsolid/rea/dist/cli/index.js` OR
+ *     `<baseDir>/dist/cli/index.js` (the rea-repo dogfood). Without
+ *     one the shim silently drops the signal by design, so the smoke
+ *     check would time out waiting for a record that will never land.
+ *
+ * Gated behind `--smoke` so a casual `rea doctor` doesn't write probe
+ * records on every invocation. Operators run `rea doctor --smoke`
+ * after install / upgrade to confirm the pipeline is wired end-to-end.
  */
 export declare function checkDelegationRoundTrip(baseDir: string): Promise<CheckResult>;
 /**