@bookedsolid/rea 0.8.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/package.json

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