@bookedsolid/rea 0.7.0 → 0.9.0

package/dist/gateway/server.js

@@ -53,6 +53,8 @@ import { executeChain } from './middleware/chain.js';
 import { RateLimiter } from './rate-limiter.js';
 import { CircuitBreaker } from './circuit-breaker.js';
 import { currentSessionId } from './session.js';
+import { SessionBlockerTracker } from './session-blocker.js';
+import { LiveStatePublisher } from './live-state.js';
 import { InvocationStatus, Tier } from '../policy/types.js';
 import { log } from '../cli/utils.js';
 import { createLogger } from './log.js';
@@ -127,6 +129,36 @@ export function createGateway(opts) {
     const pool = new DownstreamPool(registry, logger);
     const gatewayVersion = getPkgVersion();
     const startedAtMs = Date.now();
+    // 0.9.0 — SESSION_BLOCKER tracker. One per gateway process. The audit
+    // sink wraps `appendAuditRecord` so a fired record lands in the hash
+    // chain for forensic inspection.
+    const sessionBlocker = new SessionBlockerTracker(currentSessionId(), {}, logger, async (event) => {
+        try {
+            await appendAuditRecord(baseDir, {
+                tool_name: 'session_blocker',
+                server_name: event.server_name,
+                status: InvocationStatus.Error,
+                tier: Tier.Read,
+                autonomy_level: String(policy.autonomy_level),
+                session_id: event.session_id,
+                duration_ms: 0,
+                metadata: {
+                    event: event.event,
+                    open_transitions: event.open_transitions,
+                    threshold: event.threshold,
+                    emitted_at: event.emitted_at,
+                },
+            });
+        }
+        catch (err) {
+            logger.error({
+                event: 'session_blocker.audit_failed',
+                server_name: event.server_name,
+                message: 'failed to append SESSION_BLOCKER audit record — log remains the sole record',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
     // BUG-011 (0.6.2) — process-lifetime counter of failed audit appends from
     // the `__rea__health` short-circuit. Exposed on the health snapshot as
     // `summary.audit_fail_count` so operators can detect the silent-audit-gap
@@ -135,6 +167,9 @@ export function createGateway(opts) {
     const server = new Server({ name: 'rea', version: gatewayVersion }, { capabilities: { tools: {} } });
     // Build the circuit breaker with observability hooks wired in — state
     // transitions log a structured record AND update the Prometheus gauge.
+    // 0.9.0: also feed SESSION_BLOCKER tracker and live-state publisher so
+    // `rea status` and the audit chain surface per-session outages.
+    let livePublisher = null;
     const breaker = new CircuitBreaker({
         onStateChange: (event) => {
             const level = event.to === 'open' ? 'warn' : 'info';
@@ -155,9 +190,56 @@ export function createGateway(opts) {
                     metrics?.setCircuitState(event.server, CIRCUIT_GAUGE.open);
                     break;
             }
+            sessionBlocker.recordCircuitTransition({
+                server: event.server,
+                from: event.from,
+                to: event.to,
+            });
+            livePublisher?.scheduleUpdate();
         },
     });
     const staticChain = buildMiddlewareChain(opts, { breaker });
+    // Pool supervisor events → live-state publisher. Covers three kinds:
+    //   - `child_died_unexpectedly` — child exited outside a caller-initiated
+    //     close(). Session-blocker counts this indirectly through the breaker
+    //     transition it eventually triggers.
+    //   - `respawned` — successful reconnect. Forwarded to session-blocker as
+    //     an intentional no-op (see `recordRespawn` JSDoc): respawn is NOT
+    //     equivalent to circuit recovery, so we do NOT clear blocker state
+    //     on reconnect. The method exists to make the wiring site obvious
+    //     on the call graph and to give us one place to change if the
+    //     semantics ever shift — but today it deliberately records nothing.
+    //   - `health_changed` — a non-transition mutation of a field surfaced in
+    //     `rea status` (health, last_error, tools_count). Codex 0.9.0 pass-2
+    //     P2a: without this, the first failure below the breaker threshold
+    //     or a successful `listTools` count change never reached the
+    //     publisher, leaving `rea status` showing stale downstream data.
+    // `scheduleUpdate()` is debounced (250 ms default) so storm bursts
+    // coalesce to one write.
+    pool.onSupervisorEvent((event) => {
+        if (event.kind === 'respawned')
+            sessionBlocker.recordRespawn(event.server);
+        livePublisher?.scheduleUpdate();
+    });
+    if (opts.liveStateFilePath !== undefined) {
+        // Build options defensively — exactOptionalPropertyTypes refuses
+        // `lastErrorRedactor: undefined` against `lastErrorRedactor?: FieldRedactor`.
+        const publisherOpts = {
+            baseDir,
+            stateFilePath: opts.liveStateFilePath,
+            sessionId: opts.liveStateSessionId ?? currentSessionId(),
+            startedAt: opts.liveStateStartedAt ?? new Date(startedAtMs).toISOString(),
+            metricsPort: opts.liveStateMetricsPort ?? null,
+            pool,
+            breaker,
+            sessionBlocker,
+            logger,
+            ...(opts.liveStateLastErrorRedactor !== undefined
+                ? { lastErrorRedactor: opts.liveStateLastErrorRedactor }
+                : {}),
+        };
+        livePublisher = new LiveStatePublisher(publisherOpts);
+    }
     // Read `.rea/HALT` without ever throwing. Returns `{halt, reason}` where
     // `reason` is the (trimmed) file contents or null when the file is absent
     // / unreadable. The meta-tool never surfaces I/O errors — health is the one
@@ -462,12 +544,21 @@ export function createGateway(opts) {
         }
         const activeTransport = transport ?? new StdioServerTransport();
         await server.connect(activeTransport);
+        // Publish the initial live-state snapshot so `rea status` sees the
+        // `downstreams` block from the first moment the gateway is up, not
+        // only after the first circuit transition.
+        livePublisher?.flushNow();
     }
     async function stop() {
         if (stopping)
             return;
         stopping = true;
         logger.info({ event: 'gateway.shutdown', message: 'gateway stop requested' });
+        // Final flush BEFORE we drop the publisher so any last-moment transition
+        // (e.g. a circuit closing as pool.close() quiesces it) is reflected on
+        // disk for the very last `rea status` after shutdown.
+        livePublisher?.flushNow();
+        livePublisher?.stop();
         try {
             await server.close();
         }
@@ -476,5 +567,14 @@ export function createGateway(opts) {
         }
         await pool.close();
     }
-    return { server, start, stop, pool, logger, metrics };
+    return {
+        server,
+        start,
+        stop,
+        pool,
+        logger,
+        metrics,
+        livePublisher,
+        sessionBlocker,
+    };
 }

package/dist/gateway/session-blocker.d.ts

@@ -0,0 +1,132 @@
+/**
+ * SESSION_BLOCKER tracker (BUG-004, 0.9.0).
+ *
+ * When a downstream MCP server fails repeatedly in a single session the
+ * operator needs one LOUD signal — not a log stream full of identical
+ * circuit-open records. This module owns the per-(session_id, server_name)
+ * counter and emits exactly one `SESSION_BLOCKER` event once a threshold is
+ * crossed; the event is replayed neither on continued failure nor on a
+ * circuit-breaker flap. Recovery (downstream returns to healthy) resets the
+ * counter and re-arms the emission.
+ *
+ * ## Why this lives separately from CircuitBreaker
+ *
+ * The circuit breaker tracks CONSECUTIVE CALL-LEVEL failures per server —
+ * it is wire-hot and opens/closes many times across a long session. The
+ * session blocker tracks OPEN-LEVEL failures per session: every
+ * circuit-open transition counts as ONE. A downstream that flaps
+ * open→closed→open three times in ten minutes is already a blocker from an
+ * operator perspective — it should be surfaced once, not muted by the
+ * breaker's own internal recoveries.
+ *
+ * ## Emission semantics
+ *
+ *   - Increment on every circuit transition to `open`.
+ *   - When the counter for (session, server) crosses `threshold`, fire
+ *     ONE `SESSION_BLOCKER` record (structured log + audit append). The
+ *     counter keeps incrementing — subsequent opens do NOT re-fire.
+ *   - On circuit recovery (transition to `closed`) the counter resets and
+ *     the "already emitted" flag clears; the next threshold crossing will
+ *     fire a fresh record.
+ *   - On session change (new session_id) every counter is dropped — a new
+ *     `rea serve` instance starts fresh.
+ *
+ * ## Why audit
+ *
+ * The hash-chained audit log is the single place an operator can look for a
+ * forensic record of persistent downstream outages. A `SESSION_BLOCKER`
+ * record in the audit trail pinpoints the session + downstream that went
+ * dark, independent of whichever log sink the operator had configured.
+ *
+ * Audit appends are best-effort; a failure to write never breaks the
+ * gateway. The log-side emission happens first and unconditionally.
+ */
+import type { Logger } from './log.js';
+/**
+ * Event shape observed by the tracker. Only `from` → `to` and `server` are
+ * needed; the tracker does not care about retryAt/reason.
+ */
+export interface CircuitTransitionEvent {
+    server: string;
+    from: 'closed' | 'open' | 'half-open';
+    to: 'closed' | 'open' | 'half-open';
+}
+/**
+ * Structured record emitted when a session-level block threshold is
+ * crossed. Exposed so tests and audit-append helpers can construct the
+ * canonical shape without re-declaring the fields.
+ */
+export interface SessionBlockerEvent {
+    event: 'SESSION_BLOCKER';
+    session_id: string;
+    server_name: string;
+    open_transitions: number;
+    threshold: number;
+    /** ISO timestamp at emission. */
+    emitted_at: string;
+    message: string;
+}
+/**
+ * Callback the tracker invokes when a SESSION_BLOCKER fires. The gateway
+ * wires this to `appendAuditRecord` so forensic capture survives logger
+ * downtime. Errors raised by the sink are swallowed — a broken audit
+ * pipeline must never break state tracking.
+ */
+export type SessionBlockerAuditSink = (event: SessionBlockerEvent) => Promise<void> | void;
+export interface SessionBlockerOptions {
+    /**
+     * Number of open-transitions required to fire the event. Default: 3 —
+     * matches Jake's "after N consecutive same-downstream failures in one
+     * session" from the bug report. Low enough to catch real outages quickly,
+     * high enough that a single noisy reconnect doesn't spuriously fire.
+     */
+    threshold?: number;
+}
+/**
+ * Per-(session_id, server_name) SESSION_BLOCKER tracker.
+ *
+ * Stateful and single-instance per gateway process. The circuit breaker's
+ * `onStateChange` listener plus the pool's respawn events feed it; the
+ * tracker decides whether to emit.
+ */
+export declare class SessionBlockerTracker {
+    private readonly threshold;
+    private readonly logger;
+    private readonly auditSink;
+    private sessionId;
+    private readonly entries;
+    constructor(sessionId: string, options?: SessionBlockerOptions, logger?: Logger, auditSink?: SessionBlockerAuditSink);
+    /**
+     * Replace the tracked session id and clear all counters. Called from the
+     * serve entry when a fresh session boots. In practice `session_id` is
+     * assigned once per process — this is here for test determinism and
+     * future multi-session transports.
+     */
+    resetForSession(sessionId: string): void;
+    /**
+     * Feed a circuit-breaker transition. Fires a SESSION_BLOCKER record when
+     * the threshold is crossed for the first time. Subsequent opens increment
+     * the counter but do NOT re-fire until recovery resets.
+     */
+    recordCircuitTransition(event: CircuitTransitionEvent): void;
+    /**
+     * Feed a respawn event from the supervisor. A successful respawn is NOT
+     * the same as circuit recovery — the circuit closes only after a
+     * successful probe tool call, not just after reconnect. We intentionally
+     * do nothing here so the respawn path does not mask a live outage.
+     * Exposed as a method so the wiring site is obvious at the call graph.
+     */
+    recordRespawn(_server: string): void;
+    /**
+     * Snapshot for observability / status — the `rea status` JSON output
+     * surfaces per-server transition counts so operators can see "this one
+     * has failed twice but hasn't crossed threshold yet".
+     */
+    snapshot(): Array<{
+        server: string;
+        open_transitions: number;
+        emitted: boolean;
+    }>;
+    private getOrCreate;
+    private fire;
+}

package/dist/gateway/session-blocker.js

@@ -0,0 +1,163 @@
+/**
+ * SESSION_BLOCKER tracker (BUG-004, 0.9.0).
+ *
+ * When a downstream MCP server fails repeatedly in a single session the
+ * operator needs one LOUD signal — not a log stream full of identical
+ * circuit-open records. This module owns the per-(session_id, server_name)
+ * counter and emits exactly one `SESSION_BLOCKER` event once a threshold is
+ * crossed; the event is replayed neither on continued failure nor on a
+ * circuit-breaker flap. Recovery (downstream returns to healthy) resets the
+ * counter and re-arms the emission.
+ *
+ * ## Why this lives separately from CircuitBreaker
+ *
+ * The circuit breaker tracks CONSECUTIVE CALL-LEVEL failures per server —
+ * it is wire-hot and opens/closes many times across a long session. The
+ * session blocker tracks OPEN-LEVEL failures per session: every
+ * circuit-open transition counts as ONE. A downstream that flaps
+ * open→closed→open three times in ten minutes is already a blocker from an
+ * operator perspective — it should be surfaced once, not muted by the
+ * breaker's own internal recoveries.
+ *
+ * ## Emission semantics
+ *
+ *   - Increment on every circuit transition to `open`.
+ *   - When the counter for (session, server) crosses `threshold`, fire
+ *     ONE `SESSION_BLOCKER` record (structured log + audit append). The
+ *     counter keeps incrementing — subsequent opens do NOT re-fire.
+ *   - On circuit recovery (transition to `closed`) the counter resets and
+ *     the "already emitted" flag clears; the next threshold crossing will
+ *     fire a fresh record.
+ *   - On session change (new session_id) every counter is dropped — a new
+ *     `rea serve` instance starts fresh.
+ *
+ * ## Why audit
+ *
+ * The hash-chained audit log is the single place an operator can look for a
+ * forensic record of persistent downstream outages. A `SESSION_BLOCKER`
+ * record in the audit trail pinpoints the session + downstream that went
+ * dark, independent of whichever log sink the operator had configured.
+ *
+ * Audit appends are best-effort; a failure to write never breaks the
+ * gateway. The log-side emission happens first and unconditionally.
+ */
+/**
+ * Per-(session_id, server_name) SESSION_BLOCKER tracker.
+ *
+ * Stateful and single-instance per gateway process. The circuit breaker's
+ * `onStateChange` listener plus the pool's respawn events feed it; the
+ * tracker decides whether to emit.
+ */
+export class SessionBlockerTracker {
+    threshold;
+    logger;
+    auditSink;
+    sessionId;
+    entries = new Map();
+    constructor(sessionId, options = {}, logger, auditSink) {
+        this.threshold = Math.max(1, options.threshold ?? 3);
+        this.logger = logger;
+        this.auditSink = auditSink;
+        this.sessionId = sessionId;
+    }
+    /**
+     * Replace the tracked session id and clear all counters. Called from the
+     * serve entry when a fresh session boots. In practice `session_id` is
+     * assigned once per process — this is here for test determinism and
+     * future multi-session transports.
+     */
+    resetForSession(sessionId) {
+        this.sessionId = sessionId;
+        this.entries.clear();
+    }
+    /**
+     * Feed a circuit-breaker transition. Fires a SESSION_BLOCKER record when
+     * the threshold is crossed for the first time. Subsequent opens increment
+     * the counter but do NOT re-fire until recovery resets.
+     */
+    recordCircuitTransition(event) {
+        const entry = this.getOrCreate(event.server);
+        if (event.to === 'closed') {
+            // Recovery resets state — a future threshold crossing will fire a
+            // fresh record rather than being muted by the prior one.
+            entry.openTransitions = 0;
+            entry.alreadyEmitted = false;
+            return;
+        }
+        if (event.to !== 'open')
+            return;
+        entry.openTransitions += 1;
+        if (!entry.alreadyEmitted && entry.openTransitions >= this.threshold) {
+            entry.alreadyEmitted = true;
+            this.fire(event.server, entry.openTransitions);
+        }
+    }
+    /**
+     * Feed a respawn event from the supervisor. A successful respawn is NOT
+     * the same as circuit recovery — the circuit closes only after a
+     * successful probe tool call, not just after reconnect. We intentionally
+     * do nothing here so the respawn path does not mask a live outage.
+     * Exposed as a method so the wiring site is obvious at the call graph.
+     */
+    recordRespawn(_server) {
+        // Intentional no-op. See JSDoc.
+    }
+    /**
+     * Snapshot for observability / status — the `rea status` JSON output
+     * surfaces per-server transition counts so operators can see "this one
+     * has failed twice but hasn't crossed threshold yet".
+     */
+    snapshot() {
+        const out = [];
+        for (const [server, state] of this.entries) {
+            out.push({
+                server,
+                open_transitions: state.openTransitions,
+                emitted: state.alreadyEmitted,
+            });
+        }
+        return out;
+    }
+    getOrCreate(server) {
+        let entry = this.entries.get(server);
+        if (entry === undefined) {
+            entry = { openTransitions: 0, alreadyEmitted: false };
+            this.entries.set(server, entry);
+        }
+        return entry;
+    }
+    fire(server, count) {
+        const event = {
+            event: 'SESSION_BLOCKER',
+            session_id: this.sessionId,
+            server_name: server,
+            open_transitions: count,
+            threshold: this.threshold,
+            emitted_at: new Date().toISOString(),
+            message: `downstream "${server}" has opened the circuit ${count} time(s) in this session ` +
+                `(threshold ${this.threshold}). This is a SESSION_BLOCKER — the gateway will keep ` +
+                `routing around it, but operator attention is required to restore capacity.`,
+        };
+        // LOUD structured log at error level. This is the primary surface for
+        // live operators tailing stderr; the audit record below is the forensic
+        // companion.
+        this.logger?.error({
+            event: 'session_blocker',
+            server_name: server,
+            message: event.message,
+            session_id: this.sessionId,
+            open_transitions: count,
+            threshold: this.threshold,
+        });
+        if (this.auditSink === undefined)
+            return;
+        // Fire-and-forget: a slow audit sink must not block the circuit-state
+        // transition path. The sink itself is contracted to swallow errors.
+        void Promise.resolve()
+            .then(() => this.auditSink(event))
+            .catch(() => {
+            // All errors are already swallowed in the sink; this is a defensive
+            // catch for an unlikely sync throw on the thenable boundary.
+        });
+    }
+}

package/hooks/_lib/push-review-core.sh

@@ -213,6 +213,14 @@ pr_core_run() {
   # typically unset. Default to `origin` for BUG-008 sniff consistency.
   local argv_remote="${1:-origin}"
 
+  # 0.8.0 (#85): when REA_SKIP_CODEX_REVIEW is set, this flag flips to 1
+  # in section 5c. The protected-path Codex-audit check (section 7) then
+  # treats the requirement as satisfied — but every other gate (HALT,
+  # cross-repo guard, ref-resolution, push-review cache, blocked-paths)
+  # still runs. Full-gate bypass moved to REA_SKIP_PUSH_REVIEW a release
+  # cycle ago; this narrows REA_SKIP_CODEX_REVIEW to what its name implies.
+  local CODEX_WAIVER_ACTIVE=0
+
   # ── 1a. Cross-repo guard (must come FIRST — before any rea-scoped check) ──
   # BUG-012 (0.6.2) — anchor the install to the SCRIPT'S OWN LOCATION on disk.
   # The hook knows where it lives: installed at `<root>/.claude/hooks/<name>.sh`,
@@ -653,16 +661,23 @@ pr_core_run() {
 
     {
       printf '\n'
-      printf '==  CODEX REVIEW SKIPPED via REA_SKIP_CODEX_REVIEW\n'
+      printf '==  CODEX REVIEW WAIVER active (REA_SKIP_CODEX_REVIEW)\n'
       printf '    Reason:   %s\n' "$SKIP_REASON"
       printf '    Actor:    %s\n' "$SKIP_ACTOR"
       printf '    Head SHA: %s\n' "${SKIP_HEAD:-<unknown>}"
       printf '    Audited:  .rea/audit.jsonl (tool_name=codex.review.skipped)\n'
       printf '\n'
-      printf '    This is a gate weakening. Every invocation is permanently audited.\n'
+      printf '    Scope:    waives the protected-path Codex-audit requirement only.\n'
+      printf '    Still active: HALT, cross-repo guard, ref-resolution,\n'
+      printf '                  push-review cache. For a full-gate bypass\n'
+      # shellcheck disable=SC2016  # backticks are literal markdown in user-facing message
+      printf '                  use `REA_SKIP_PUSH_REVIEW=<reason>`.\n'
+      printf '\n'
+      printf '    This is a gate weakening. The waiver receipt is written BEFORE\n'
+      printf '    this banner — seeing this banner means the audit is durable.\n'
       printf '\n'
     } >&2
-    exit 0
+    CODEX_WAIVER_ACTIVE=1
   fi
 
   # ── 6. Determine source/target commits for each refspec ───────────────────
@@ -853,7 +868,13 @@ pr_core_run() {
         '; then
         local _audit="${REA_ROOT}/.rea/audit.jsonl"
         local _codex_ok=0
-        if [[ -f "$_audit" ]]; then
+        # 0.8.0 (#85): Codex-only waiver satisfies this check without a real
+        # audit entry. Every other gate still ran — HALT, cross-repo guard,
+        # ref-resolution, push-review cache — and the waiver itself is
+        # already recorded in .rea/audit.jsonl as tool_name=codex.review.skipped.
+        if [[ "$CODEX_WAIVER_ACTIVE" == "1" ]]; then
+          _codex_ok=1
+        elif [[ -f "$_audit" ]]; then
           if jq -e --arg sha "$local_sha" '
               select(
                 .tool_name == "codex.review"
@@ -977,15 +998,38 @@ pr_core_run() {
     REA_CLI_ARGS=(node "${REA_ROOT}/dist/cli/index.js")
   fi
 
+  # Cache-branch derivation (Codex 0.8.0 pass-2 finding #2, pass-3 finding #1):
+  # Use the PUSHED source ref (from pre-push stdin / bootstrap walk), not the
+  # checkout branch. `git push origin hotfix:main` from a `feature` checkout
+  # must look up a cache entry keyed on `hotfix`, not `feature`. Strip the
+  # `refs/heads/` prefix.
+  #
+  # Fall back to the checkout branch when SOURCE_REF is:
+  #   • unset (defence-in-depth, not reached on any observed path), or
+  #   • the literal string "HEAD" — emitted by pr_resolve_argv_refspecs for a
+  #     bare `git push` with no explicit refspec. Keying a cache lookup on
+  #     "HEAD" would force a miss on every bare push; the checkout branch
+  #     name is the right lookup key for that workflow.
+  local SOURCE_BRANCH="${SOURCE_REF#refs/heads/}"
+  if [[ -z "$SOURCE_BRANCH" || "$SOURCE_BRANCH" == "HEAD" ]]; then
+    SOURCE_BRANCH="$CURRENT_BRANCH"
+  fi
+
   if [[ -n "$PUSH_SHA" ]] && [[ ${#REA_CLI_ARGS[@]} -gt 0 ]]; then
     local CACHE_RESULT
-    CACHE_RESULT=$("${REA_CLI_ARGS[@]}" cache check "$PUSH_SHA" --branch "$CURRENT_BRANCH" --base "$TARGET_BRANCH" 2>/dev/null || echo '{"hit":false}')
-    if printf '%s' "$CACHE_RESULT" | jq -e '.hit == true' >/dev/null 2>&1; then
+    CACHE_RESULT=$("${REA_CLI_ARGS[@]}" cache check "$PUSH_SHA" --branch "$SOURCE_BRANCH" --base "$TARGET_BRANCH" 2>/dev/null || echo '{"hit":false}')
+    # Require BOTH hit == true AND result == "pass". A cached `fail` verdict
+    # (Codex 0.8.0 pass-2 finding #1) must NOT satisfy the gate — cache.ts
+    # serializes `result` verbatim, so a negative verdict would otherwise
+    # slip through. Under the #85 narrowed semantic the cache is the ONLY
+    # way a waiver-using operator reaches exit 0, so a permissive predicate
+    # here would be a real security regression.
+    if printf '%s' "$CACHE_RESULT" | jq -e '.hit == true and .result == "pass"' >/dev/null 2>&1; then
       local DISCORD_LIB="${REA_ROOT}/hooks/_lib/discord.sh"
       if [ -f "$DISCORD_LIB" ]; then
         # shellcheck source=/dev/null
         source "$DISCORD_LIB"
-        discord_notify "dev" "Push passed quality gates on \`${CURRENT_BRANCH}\` -- $(cd "$REA_ROOT" && git log -1 --oneline 2>/dev/null)" "green"
+        discord_notify "dev" "Push passed quality gates on \`${SOURCE_BRANCH}\` -- $(cd "$REA_ROOT" && git log -1 --oneline 2>/dev/null)" "green"
       fi
       exit 0
     fi
@@ -1006,7 +1050,7 @@ pr_core_run() {
     printf '  1. Spawn a code-reviewer agent to review: git diff %s..%s\n' "$MERGE_BASE" "$SOURCE_SHA"
     printf '  2. Spawn a security-engineer agent for security review\n'
     printf '  3. After both pass, cache the result:\n'
-    printf '     rea cache set %s pass --branch %s --base %s\n' "$PUSH_SHA" "$CURRENT_BRANCH" "$TARGET_BRANCH"
+    printf '     rea cache set %s pass --branch %s --base %s\n' "$PUSH_SHA" "$SOURCE_BRANCH" "$TARGET_BRANCH"
     printf '\n'
   } >&2
   exit 2

package/hooks/push-review-gate-git.sh

@@ -45,13 +45,15 @@
 # generic Claude Code adapter.
 #
 # ── Escape hatches ────────────────────────────────────────────────────────────
-#   REA_SKIP_CODEX_REVIEW=<reason>  — bypass the Codex adversarial-review
-#                                     requirement for this push. Audit record
+#   REA_SKIP_CODEX_REVIEW=<reason>  — Codex-only waiver. Since 0.8.0 (#85)
+#                                     this ONLY satisfies the protected-path
+#                                     Codex-audit requirement. HALT, cross-
+#                                     repo guard, ref-resolution, and the
+#                                     push-review cache still run. See the
+#                                     authoritative docstring in
+#                                     `push-review-gate.sh` for the full
+#                                     scope description. Audit record
 #                                     `tool_name: "codex.review.skipped"`.
-#                                     Currently a whole-gate bypass (see
-#                                     task #85); the distinct audit tool_name
-#                                     keeps it from satisfying the Codex-
-#                                     review jq predicate.
 #   REA_SKIP_PUSH_REVIEW=<reason>   — bypass the WHOLE gate for this push.
 #                                     Audit record
 #                                     `tool_name: "push.review.skipped"`.

package/hooks/push-review-gate.sh

@@ -22,24 +22,39 @@
 # so in practice a consumer can wire THIS file into `.husky/pre-push` and it
 # just works. The `-git` adapter exists for clarity of install intent.
 #
-# ── Escape hatch: REA_SKIP_CODEX_REVIEW ──────────────────────────────────────
-# Env var `REA_SKIP_CODEX_REVIEW=<reason>` bypasses the Codex adversarial-
-# review requirement. Set to any non-empty value; the value IS the reason
-# recorded in the audit record (no default reason is supplied — if the
-# operator sets `REA_SKIP_CODEX_REVIEW=1` the reason is literally "1").
+# ── Codex-only waiver: REA_SKIP_CODEX_REVIEW ─────────────────────────────────
+# Env var `REA_SKIP_CODEX_REVIEW=<reason>` waives the Codex adversarial-
+# review requirement (section 7 protected-path check). Set to any non-empty
+# value; the value IS the reason recorded in the audit record (no default
+# reason is supplied — if the operator sets `REA_SKIP_CODEX_REVIEW=1` the
+# reason is literally "1").
 #
-# ORDERING (0.7.0): the hatch fires AFTER the HALT check but BEFORE ref-
-# resolution and protected-path detection. Prior to 0.7.0 the check ran
-# inside the protected-path branch and only fired when the diff touched a
-# protected path — which meant an operator who wanted to skip Codex review
-# got blocked by a transient ref-resolution failure (missing remote object,
-# unresolvable source ref, etc.) before the skip ever fired. The new
-# ordering mirrors REA_SKIP_PUSH_REVIEW: if the operator has committed to
-# the bypass (accepting the audit record), ref-resolution failures should
-# not strand the skip. Tradeoff: the skip now fires on every push when set,
-# not just protected-path pushes. The audit receipt makes the operator
-# accountable either way, and REA_SKIP_CODEX_REVIEW keeps its distinct
-# tool_name so it never satisfies the `codex.review` jq predicate.
+# SCOPE (0.8.0, #85): Codex-only. The waiver only satisfies the
+# protected-path Codex-audit requirement. Every other gate this hook
+# runs still runs:
+#   • HALT (.rea/HALT) — still blocks.
+#   • Cross-repo guard — still blocks.
+#   • Ref-resolution failures — still block.
+#   • Push-review cache — a miss still falls through to section 9's general
+#     review-required block.
+# (Blocked-paths enforcement is a separate hook on Edit/Write tiers, not
+# this push hook — it was never gated by REA_SKIP_CODEX_REVIEW.)
+#
+# For a full-gate bypass, use `REA_SKIP_PUSH_REVIEW=<reason>` (section 5a).
+# The 0.7.0 semantic (whole-gate bypass via the Codex hatch) was misleading
+# — operators reached for REA_SKIP_CODEX_REVIEW to silence a transient
+# Codex unavailability and accidentally bypassed every other check too.
+# 0.8.0 narrows it to what the name implies.
+#
+# ORDERING: the waiver fires AFTER the HALT check but BEFORE ref-resolution.
+# Prior to 0.7.0 the check ran inside the protected-path branch and only
+# fired when the diff touched a protected path — which meant an operator
+# who wanted to skip Codex review got blocked by a transient ref-resolution
+# failure (missing remote object, unresolvable source ref, etc.) before the
+# skip ever fired. The current ordering preserves the skip audit record
+# even when downstream gates (ref-resolution, cache) block: the operator's
+# commitment to waive is durable, even if the push itself is blocked on
+# another gate.
 #
 # Every invocation appends a `tool_name: "codex.review.skipped"` record to
 # `.rea/audit.jsonl` via the public audit helper. This record is intentionally

package/package.json

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