@bookedsolid/rea 0.7.0 → 0.9.0

package/dist/gateway/downstream.js

@@ -30,6 +30,26 @@
  * successful reconnect — in that case we mark the connection unhealthy and
  * let the circuit breaker take over.
  *
+ * ## Supervisor / child-death detection (0.9.0, BUG-002..003)
+ *
+ * The SDK `StdioClientTransport` exposes `onclose` + `onerror` callbacks that
+ * fire when the child process exits or the stdio pipe errors outside a
+ * caller-initiated `close()`. We wire both and treat an unexpected close as
+ * "child is dead" — the next `callTool` must force a fresh connect rather
+ * than calling into a stale `Client` that will reply `Not connected`.
+ *
+ * Before 0.9.0 the supervisor was reactive only: a dead child was not noticed
+ * until the NEXT tool call tried to use it, at which point the circuit could
+ * flap open → half-open → open with the child still dead because the
+ * half-open probe re-used the zombie client. 0.9.0 makes death detection
+ * eager: `onclose` nulls `this.client` so the very next call takes the
+ * `connect()` branch and actually respawns the child.
+ *
+ * "Not connected" error messages from the SDK (our in-flight fallback) are
+ * now also treated as fatal for the current client — we null it before the
+ * one-shot reconnect path so we spawn fresh rather than retrying with the
+ * same dead handle.
+ *
  * ## Why not request-level retries
  *
  * MCP tool calls are not idempotent by default. Retrying `send_message` after
@@ -94,10 +114,41 @@ export function buildChildEnv(config, hostEnv = process.env) {
     }
     return { env: out, missing: interp.missing, secretKeys: interp.secretKeys };
 }
+/**
+ * Substring marker for "the SDK thinks the client is still alive but the
+ * child transport is already gone" errors. Matches the exact message the
+ * MCP SDK throws from `Client` method calls after `onclose` has fired but
+ * before our own code has re-connected. Kept as a constant so tests can
+ * assert against it without string duplication.
+ */
+const NOT_CONNECTED_MARKER = 'Not connected';
 export class DownstreamConnection {
     config;
     logger;
     client = null;
+    /**
+     * Handle to the currently active transport, so our `onclose`/`onerror`
+     * hooks can tell "this is the transport we care about" vs "a stale callback
+     * firing after we already swapped to a new transport". Cleared in `close()`
+     * BEFORE we invoke `client.close()` so our own tear-down does not race the
+     * supervisor path.
+     */
+    activeTransport = null;
+    /**
+     * Set of transports currently being torn down by an in-flight `close()`.
+     * `onclose` / `onerror` callbacks that fire for a transport in this set
+     * must NOT be promoted to an "unexpected child death" — they are our own
+     * tear-down signal.
+     *
+     * Codex P2 (0.9.0 review): the earlier `closingIntentionally` boolean was
+     * connection-wide. Under concurrent calls, one call's `await this.close()`
+     * could overlap with another call's reconnect that had already installed
+     * a NEW transport. A genuine `onclose` from the new transport would hit
+     * the boolean guard and be silently ignored, reintroducing the stale-
+     * handle bug the patch targeted. Per-transport scoping eliminates the
+     * race: only the exact transport we asked to close is silenced.
+     */
+    closingTransports = new Set();
     /**
      * Whether a reconnect has already been attempted in the CURRENT failure
      * episode. Resets to `false` after a reconnect succeeds (so a later,
@@ -107,7 +158,30 @@ export class DownstreamConnection {
     reconnectAttempted = false;
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     lastReconnectAt = 0;
+    /**
+     * Epoch ms of the most recent unexpected child-death event. Stamped by
+     * `handleUnexpectedClose()`. 0 means "never died unexpectedly".
+     *
+     * Codex 0.9.0 pass-5 P2b: when `handleUnexpectedClose` nulls `this.client`,
+     * the very next `callTool` takes the top-level `client === null` branch,
+     * which normally bypasses the flap-window check entirely (that check lives
+     * in the catch branch below, conditioned on `lastReconnectAt`). A downstream
+     * that crashes immediately after every spawn would therefore be respawned
+     * unconditionally on every incoming call — exactly the loop the flap
+     * window is supposed to suppress. Consulting this timestamp in the
+     * `client === null` branch lets us refuse the respawn when the previous
+     * death is within the flap window, and the caller gets a clear error
+     * instead of watching the child die again.
+     */
+    unexpectedDeathAt = 0;
     health = 'healthy';
+    /**
+     * Optional supervisor-event listener. Set via
+     * {@link onSupervisorEvent}. A single subscriber is sufficient — the pool
+     * is the one consumer. Listener failures are swallowed; a broken consumer
+     * must never break the connection lifecycle.
+     */
+    supervisorListener = null;
     /**
      * The most recent error observed on this connection (connect or call
      * failure). Surfaced via `__rea__health` so callers can diagnose an empty
@@ -163,6 +237,127 @@ export class DownstreamConnection {
     get isConnected() {
         return this.client !== null;
     }
+    /**
+     * Register a supervisor-event listener. Intended for the pool to wire up
+     * SESSION_BLOCKER tracking + observability hooks without the connection
+     * class having to know about either. Only one listener is supported — a
+     * second call replaces the first. Pass `null` to detach.
+     */
+    onSupervisorEvent(listener) {
+        this.supervisorListener = listener;
+    }
+    /**
+     * Invoke the supervisor listener if registered. Swallows listener errors —
+     * a broken observer must never break the connection state machine.
+     */
+    emitSupervisorEvent(event) {
+        const listener = this.supervisorListener;
+        if (listener === null)
+            return;
+        try {
+            listener(event);
+        }
+        catch {
+            // Intentionally swallowed. See JSDoc.
+        }
+    }
+    /**
+     * Emit a `health_changed` event. Called from every site that mutates a
+     * health/last_error/tools_count-visible field WITHOUT firing one of the
+     * louder supervisor events (`child_died_unexpectedly` / `respawned`).
+     * Addresses Codex 0.9.0 pass-2 P2a — live-state was only scheduled from
+     * breaker transitions and respawns, so transient errors below the breaker
+     * threshold would leave `rea status` showing stale data.
+     */
+    emitHealthChanged() {
+        this.emitSupervisorEvent({ kind: 'health_changed', server: this.config.name });
+    }
+    /**
+     * Handle an unexpected transport close. Fires when the child process exits
+     * outside a caller-initiated `close()`, or when the stdio pipe errors in a
+     * way the SDK surfaces as a close event.
+     *
+     * Contract:
+     *   - Only runs for the currently-active transport (stale callbacks from
+     *     an already-swapped transport are ignored).
+     *   - Does NOT run when WE initiated the close (the transport is a member
+     *     of `closingTransports` for the duration of our own `close()` call).
+     *   - Nulls `this.client` so the next `callTool` takes the `connect()`
+     *     branch and actually respawns the child.
+     *   - Marks the connection unhealthy so the pool knows not to route
+     *     traffic to it while we wait for the next call.
+     *   - Emits a `child_died_unexpectedly` supervisor event so the pool's
+     *     SESSION_BLOCKER tracker can count this even though no callTool has
+     *     failed yet (the child may die mid-idle).
+     */
+    handleUnexpectedClose(transport, reason) {
+        // Stale callback: a previous transport's onclose firing after we've
+        // already swapped in a new one. Ignore — the new transport is live and
+        // we don't want to clobber it.
+        if (this.activeTransport !== transport)
+            return;
+        // Per-transport intentional-close filter. Codex P2 (0.9.0 review): a
+        // connection-wide boolean would let a late `onclose` from a newly
+        // reconnected transport be silenced while an earlier `close()` on the
+        // PREVIOUS transport was still in flight. Scoping by transport
+        // identity means only the exact transport we asked to close is
+        // silenced — a real death on any other transport fires normally.
+        if (this.closingTransports.has(transport))
+            return;
+        this.client = null;
+        this.activeTransport = null;
+        this.health = 'unhealthy';
+        this.#lastErrorMessage = `child process exited unexpectedly: ${reason}`;
+        // Codex 0.9.0 pass-5 P2b: stamp the death time so `callTool`'s
+        // `client === null` branch can consult the flap window and refuse a
+        // respawn if the child died within `RECONNECT_FLAP_WINDOW_MS`. Without
+        // this, the top-level respawn path bypasses the flap guard entirely.
+        this.unexpectedDeathAt = Date.now();
+        this.logger?.warn({
+            event: 'downstream.child_died',
+            server_name: this.config.name,
+            message: `downstream "${this.config.name}" child died unexpectedly — next call will respawn`,
+            reason,
+        });
+        this.emitSupervisorEvent({
+            kind: 'child_died_unexpectedly',
+            server: this.config.name,
+            reason,
+        });
+    }
+    /**
+     * Handle a transport-layer protocol error. onerror does NOT always imply
+     * close — the SDK emits it for protocol errors too. We record the error
+     * text but leave connection invalidation to the eventual onclose callback,
+     * which is guaranteed to follow a fatal transport error on stdio.
+     *
+     * Codex 0.9.0 pass-6 P2: filter stale/intentional-close callbacks the
+     * same way `handleUnexpectedClose` does. Without this, a delayed
+     * onerror from a PREVIOUSLY-ACTIVE transport (one we've already torn
+     * down or replaced) can clobber the HEALTHY replacement connection's
+     * last_error and emit a spurious health_changed, leaving `rea status`
+     * showing a stale error on a perfectly live child. The `onclose`
+     * hook already enforced this filter; the `onerror` hook did not.
+     */
+    handleTransportError(transport, err) {
+        if (this.activeTransport !== transport)
+            return;
+        if (this.closingTransports.has(transport))
+            return;
+        this.#lastErrorMessage = err.message;
+        this.logger?.warn({
+            event: 'downstream.transport_error',
+            server_name: this.config.name,
+            message: `downstream "${this.config.name}" transport error`,
+            error: err.message,
+        });
+        // Codex 0.9.0 pass-4 P2: surface the new last_error to the live-state
+        // publisher immediately. Before this emit, a protocol-level transport
+        // error that did NOT trigger a subsequent onclose would update
+        // last_error in memory but leave `rea status` showing the previous
+        // (stale) value until some unrelated circuit/respawn event flushed.
+        this.emitHealthChanged();
+    }
     /**
      * Last error observed, or null if the connection has never failed (or fully
      * recovered).
@@ -206,11 +401,13 @@ export class DownstreamConnection {
             this.health = 'unhealthy';
             const msg = `failed to resolve env for downstream "${this.config.name}": ${err instanceof Error ? err.message : err}`;
             this.#lastErrorMessage = msg;
+            this.emitHealthChanged();
             throw new Error(msg);
         }
         if (built.missing.length > 0) {
             this.health = 'unhealthy';
             this.#lastErrorMessage = `missing env: ${built.missing.join(', ')}`;
+            this.emitHealthChanged();
             // One line per missing var so grep/jq users can find the exact gap.
             // We intentionally do NOT log the env key name's VALUE (there is none —
             // it's unresolved) nor any other env values.
@@ -225,17 +422,38 @@ export class DownstreamConnection {
             args: this.config.args,
             env: built.env,
         });
+        // BUG-002/003: wire supervisor hooks BEFORE connect so we never miss a
+        // close event that fires during the initial handshake. The hooks only
+        // act on the transport we hand them — a stale callback from a previous
+        // transport is ignored in `handleUnexpectedClose`.
+        transport.onclose = () => {
+            this.handleUnexpectedClose(transport, 'transport closed');
+        };
+        transport.onerror = (err) => {
+            this.handleTransportError(transport, err);
+        };
         const client = new Client({ name: `rea-gateway-client:${this.config.name}`, version: '0.2.0' }, { capabilities: {} });
         try {
             await client.connect(transport);
             this.client = client;
+            this.activeTransport = transport;
             this.health = 'healthy';
             this.#lastErrorMessage = null;
+            this.emitHealthChanged();
         }
         catch (err) {
             this.health = 'unhealthy';
             const msg = `failed to connect to downstream "${this.config.name}" (${this.config.command}): ${err instanceof Error ? err.message : err}`;
             this.#lastErrorMessage = msg;
+            // The transport may have partially started and set up child pipes —
+            // tell the SDK to tear it down so we don't leak the zombie child.
+            try {
+                await transport.close();
+            }
+            catch {
+                // Best-effort.
+            }
+            this.emitHealthChanged();
             throw new Error(msg);
         }
     }
@@ -254,7 +472,38 @@ export class DownstreamConnection {
      */
     async callTool(toolName, args) {
         if (this.client === null) {
+            // Codex 0.9.0 pass-5 P2b: if the previous death was inside the flap
+            // window, refuse the respawn and surface the flap-window error instead.
+            // This keeps a crash-on-spawn child from being respawned on every
+            // incoming call — the same guarantee the `catch` branch provides for
+            // transport errors on a live client. The timestamp is stamped by
+            // `handleUnexpectedClose`; if the client was nulled by some other
+            // path (our own `close()`, initial cold start, etc.) `unexpectedDeathAt`
+            // is 0 and the check is a no-op.
+            const deathWithinFlapWindow = this.unexpectedDeathAt !== 0 &&
+                Date.now() - this.unexpectedDeathAt < RECONNECT_FLAP_WINDOW_MS;
+            if (deathWithinFlapWindow) {
+                this.health = 'unhealthy';
+                const msg = `downstream "${this.config.name}" unhealthy — child died within ` +
+                    `flap window, refusing to respawn`;
+                this.#lastErrorMessage = msg;
+                this.logger?.error({
+                    event: 'downstream.respawn_refused_flap',
+                    server_name: this.config.name,
+                    message: msg,
+                    last_death_ms_ago: Date.now() - this.unexpectedDeathAt,
+                });
+                this.emitHealthChanged();
+                throw new Error(msg);
+            }
             await this.connect();
+            // A successful spawn after a death ends the episode — clear the stamp
+            // so future unrelated deaths get their own flap window rather than
+            // inheriting this one.
+            this.unexpectedDeathAt = 0;
+            // Successful respawn counts as recovery for the supervisor — emit it
+            // so observability sinks can reset per-server session-blocker counts.
+            this.emitSupervisorEvent({ kind: 'respawned', server: this.config.name });
         }
         try {
             const result = await this.client.callTool({ name: toolName, arguments: args });
@@ -262,12 +511,40 @@ export class DownstreamConnection {
             // this, a connection that failed once and then recovered on the very
             // next call (same client, no reconnect) would forever report the old
             // error via `__rea__health`, misleading operators about live state.
+            //
+            // Codex 0.9.0 pass-2 P2a: only emit `health_changed` when we actually
+            // cleared something — the common success path runs through here every
+            // call, so noisy emission would burn debounced writes. A same-value
+            // write is a no-op for live-state purposes.
+            const hadError = this.#lastErrorMessage !== null;
             this.#lastErrorMessage = null;
+            if (hadError)
+                this.emitHealthChanged();
             return result;
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             const withinFlapWindow = this.lastReconnectAt !== 0 && Date.now() - this.lastReconnectAt < RECONNECT_FLAP_WINDOW_MS;
+            // BUG-003: "Not connected" means the SDK's idea of the client state
+            // has diverged from reality — usually because the child exited between
+            // calls and the `onclose` hook hasn't fired yet (or raced this call).
+            // Force a proper tear-down NOW so the next branch either reconnects
+            // against a clean slate (reconnect branch) or leaves a null client so
+            // the NEXT callTool's guard spawns fresh (terminal branch). Codex
+            // 0.9.0 pass-3 P2: an earlier implementation nulled `this.client` +
+            // `this.activeTransport` inline here, which made the subsequent
+            // `await this.close()` below a no-op (`c` was already null) — the
+            // stale child would leak until gateway shutdown. Calling `close()`
+            // eagerly ensures the transport is actually closed.
+            if (message.includes(NOT_CONNECTED_MARKER)) {
+                try {
+                    await this.close();
+                }
+                catch {
+                    // Best-effort — close() already swallows transport close errors,
+                    // but belt-and-braces for any unexpected throw.
+                }
+            }
             if (!this.reconnectAttempted && !withinFlapWindow) {
                 this.reconnectAttempted = true;
                 this.health = 'degraded';
@@ -278,8 +555,12 @@ export class DownstreamConnection {
                     reason: message,
                 });
                 try {
+                    // For non-NOT_CONNECTED paths we still need to tear down the old
+                    // client. When we DID take the NOT_CONNECTED branch above, `close()`
+                    // is idempotent: `c === null` short-circuits cleanly.
                     await this.close();
                     await this.connect();
+                    this.emitSupervisorEvent({ kind: 'respawned', server: this.config.name });
                     const result = await this.client.callTool({ name: toolName, arguments: args });
                     // Success: episode closed. Reset for the NEXT unrelated failure and
                     // stamp the reconnect time so flap-guard can refuse rapid repeats.
@@ -303,6 +584,7 @@ export class DownstreamConnection {
                         message: `downstream "${this.config.name}" unhealthy after one reconnect`,
                         error: errMsg,
                     });
+                    this.emitHealthChanged();
                     throw new Error(`downstream "${this.config.name}" unhealthy after one reconnect: ${errMsg}`);
                 }
             }
@@ -314,19 +596,39 @@ export class DownstreamConnection {
                 message: `downstream "${this.config.name}" call failed`,
                 error: message,
             });
+            this.emitHealthChanged();
             throw new Error(`downstream "${this.config.name}" call failed: ${message}`);
         }
     }
     async close() {
         const c = this.client;
+        // Capture the transport being closed BEFORE we null `activeTransport`,
+        // so a synchronously-firing `onclose` during `c.close()` can be matched
+        // against this specific transport instead of whichever transport is
+        // "current" at the moment the callback lands. Codex P2 (0.9.0 review):
+        // the earlier implementation used a connection-wide boolean, which
+        // under concurrent calls could silence a legitimate death event for a
+        // newer transport while we were still tearing down an older one.
+        const closingTransport = this.activeTransport;
+        if (closingTransport !== null) {
+            this.closingTransports.add(closingTransport);
+        }
         this.client = null;
-        if (c === null)
-            return;
+        this.activeTransport = null;
         try {
-            await c.close();
+            if (c === null)
+                return;
+            try {
+                await c.close();
+            }
+            catch {
+                // Best-effort close — child may already be gone.
+            }
         }
-        catch {
-            // Best-effort close — child may already be gone.
+        finally {
+            if (closingTransport !== null) {
+                this.closingTransports.delete(closingTransport);
+            }
         }
     }
 }

package/dist/gateway/live-state.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Live `serve.state.json` publisher (BUG-005, 0.9.0).
+ *
+ * Before 0.9.0 `.rea/serve.state.json` was written once at `rea serve` boot
+ * and never touched again. `rea status` therefore only surfaced
+ * `session_id`, `started_at`, and `metrics_port` — agents planning a
+ * multi-downstream workflow had no way to see "is helixir's circuit open
+ * right now?" without calling `__rea__health` through the MCP transport
+ * (which, ironically, wouldn't work if the gateway was the thing that had
+ * wedged).
+ *
+ * The publisher subscribes to two signals:
+ *
+ *   1. Circuit-breaker `onStateChange` — transitions to/from open/half-open
+ *      update the per-downstream block.
+ *   2. Supervisor events from the pool — `child_died_unexpectedly` and
+ *      `respawned` update per-downstream liveness.
+ *
+ * Each update debounces to at most one write per ~250 ms via a trailing
+ * timer so a storm of transitions (e.g. open → half-open → open → half-open
+ * during a flap) doesn't spam the filesystem.
+ *
+ * Writes reuse the atomic temp+rename pattern from `serve.ts`. The write
+ * carries the same ownership key (`session_id`) as the boot write so a
+ * racing second `rea serve` instance is still correctly distinguished at
+ * shutdown.
+ *
+ * ## Why not an IPC endpoint?
+ *
+ * We briefly considered piggy-backing a `/downstreams.json` route on the
+ * metrics HTTP server. Rejected on the grounds of:
+ *
+ *   - `rea status` works when `REA_METRICS_PORT` is unset (common in local
+ *     dev); a disk snapshot keeps it authoritative.
+ *   - The write rate is bounded (debounced) and the snapshot is tiny (few
+ *     hundred bytes).
+ *   - The on-disk file is the one surface a CRASHED gateway leaves behind
+ *     — IPC evaporates the moment the process dies, whereas a file survives
+ *     for post-mortem inspection.
+ */
+import type { CircuitBreaker, CircuitState } from './circuit-breaker.js';
+import type { DownstreamPool } from './downstream-pool.js';
+import type { FieldRedactor, Logger } from './log.js';
+import type { SessionBlockerTracker } from './session-blocker.js';
+export interface LiveStateOptions {
+    baseDir: string;
+    stateFilePath: string;
+    sessionId: string;
+    startedAt: string;
+    metricsPort: number | null;
+    pool: DownstreamPool;
+    breaker: CircuitBreaker;
+    sessionBlocker: SessionBlockerTracker;
+    logger?: Logger;
+    /**
+     * Debounce window for coalesced writes. Default 250 ms. Exposed so tests
+     * can force immediate flushes.
+     */
+    debounceMs?: number;
+    /**
+     * Redactor applied to `last_error` strings before they are written to
+     * `serve.state.json`. `rea serve` wires this to the same
+     * `buildRegexRedactor` instance the gateway logger uses (policy
+     * `redact.patterns` + built-in `SECRET_PATTERNS`) so a credential that
+     * leaked into a downstream error message does not end up on disk or on
+     * an operator's terminal via `rea status`.
+     *
+     * Omitting the redactor preserves pre-0.9.0 behavior (no last_error
+     * redaction at the publisher layer). Direct embedders of `createGateway`
+     * that pass their own logger redactor should also pass this.
+     */
+    lastErrorRedactor?: FieldRedactor;
+}
+/**
+ * Per-downstream block surfaced in `serve.state.json` and echoed by
+ * `rea status`. Narrow by design — anything an operator wants beyond this
+ * lives in `__rea__health` where the gateway's richer state machine is
+ * live.
+ */
+export interface LiveDownstreamState {
+    name: string;
+    connected: boolean;
+    healthy: boolean;
+    circuit_state: CircuitState;
+    /** ISO timestamp when the circuit is expected to move to half-open. Only present when `open`. */
+    retry_at: string | null;
+    last_error: string | null;
+    tools_count: number | null;
+    /** Cumulative circuit-open transitions counted toward SESSION_BLOCKER. */
+    open_transitions: number;
+    /** True once SESSION_BLOCKER has fired for this server in the current session. */
+    session_blocker_emitted: boolean;
+}
+export interface LiveServeState {
+    session_id: string;
+    started_at: string;
+    metrics_port: number | null;
+    /** Downstream block — added in 0.9.0. Empty array when no servers configured. */
+    downstreams: LiveDownstreamState[];
+    /** ISO timestamp of this snapshot. Separate from `started_at`. */
+    updated_at: string;
+    /**
+     * PID of the process that wrote this snapshot. Added in 0.9.0 pass-4 so
+     * a NEW `rea serve` can detect an ABANDONED state file (writer crashed,
+     * no one cleaned up) and take over ownership. Without this field,
+     * the pass-2 session_id-only ownership check was strictly safer but
+     * also strictly one-directional: once an older session wrote, no new
+     * session could ever claim the file, and `rea status` would stall on
+     * the dead session forever. Optional for backward compatibility with
+     * pre-0.9.0 snapshots that lack the field.
+     */
+    owner_pid?: number;
+}
+export declare class LiveStatePublisher {
+    private readonly opts;
+    private timer;
+    /**
+     * Separate timer for the yield-retry path. Kept distinct from `timer` so a
+     * scheduled debounce doesn't cancel the retry and vice-versa — they serve
+     * different purposes (coalesce vs. poll). Cleared by `stop()`.
+     */
+    private yieldRetryTimer;
+    private stopped;
+    constructor(opts: LiveStateOptions);
+    /**
+     * Schedule a write. Coalesces multiple calls within the debounce window
+     * into a single flush. Safe to call from circuit-breaker and supervisor
+     * event paths without worrying about write rate.
+     */
+    scheduleUpdate(): void;
+    /**
+     * Write the current snapshot synchronously, bypassing the debounce.
+     * Called on boot (to publish the initial downstream block) and on
+     * shutdown (to flush any pending updates before the state file is
+     * ownership-cleaned).
+     *
+     * ## Ownership handoff (Codex P1 + P2b)
+     *
+     * The ownership check + rename is performed under a sidecar lockfile
+     * (`serve.state.json.lock`) created with `O_EXCL` (`wx`). This converts
+     * what was two non-atomic steps into a serialized critical section.
+     *
+     * Flow:
+     *
+     *   1. Acquire the lock (`open(path, 'wx')`). If EEXIST, a concurrent
+     *      writer — either another publisher in THIS process (not possible
+     *      given the debounce, but cheap to defend against) or another
+     *      `rea serve` instance with overlapping lifetime — holds it. Skip
+     *      this flush silently; the debounce timer will try again, and on
+     *      shutdown the concurrent writer's own state will be authoritative.
+     *   2. Under the lock: re-read the on-disk `session_id`. If it belongs
+     *      to a DIFFERENT session, another instance has already claimed the
+     *      breadcrumb. Release the lock and yield (log-only).
+     *   3. Under the lock: atomically rename our temp file over the target.
+     *      Because the concurrent writer cannot execute step 3 until we
+     *      release the lock, and we only reach step 3 after confirming the
+     *      on-disk session matches ours, the "older clobbers newer"
+     *      race Codex flagged is closed.
+     *   4. Release the lock (unlink the sidecar) in a finally block.
+     *
+     * Stale locks from a crashed process with the same PID would deadlock
+     * the critical section forever — so the acquire step checks the lock
+     * file's contents (written as our PID + random nonce) and, if the
+     * owning PID is no longer running, steals it. The steal path is
+     * intentionally narrow (PID-check only, no timestamp TTL) because
+     * holding the lock longer than a single flushNow invocation is a bug.
+     */
+    flushNow(): void;
+    /** Path to the sidecar lockfile. Resolved once per call; trivial cost. */
+    private lockFilePath;
+    /**
+     * Try to acquire the sidecar lock. Returns the lock file descriptor on
+     * success, or `null` on contention. Throws only on unexpected I/O errors
+     * (permissions, disk full) — those propagate out of `flushNow`'s try
+     * block and land in the `write_failed` log path.
+     *
+     * Stale-lock recovery: if a lockfile exists but its recorded PID is not
+     * currently running, the file is unlinked and one retry is issued. This
+     * covers the case where a previous `rea serve` SIGKILL'd mid-flush and
+     * left a dangling lockfile.
+     */
+    private acquireLock;
+    /**
+     * Release the sidecar lock. Best-effort — if the unlink fails, the next
+     * flushNow will see a dangling lock and the stale-lock recovery path
+     * will clean it up. We MUST still close the fd so we don't leak it.
+     */
+    private releaseLock;
+    /**
+     * Returns true iff the lock file's recorded PID is not currently alive.
+     * Uses `process.kill(pid, 0)` which sends no signal but errors with
+     * ESRCH when the PID is gone. Any parse error or unexpected kill error
+     * is treated as "not stale" to err on the side of NOT stealing a live
+     * peer's lock.
+     */
+    private isStaleLock;
+    /**
+     * Returns true iff this publisher is allowed to write the on-disk state
+     * file on behalf of its session. The check runs under the sidecar lock
+     * (see `flushNow`) so the read + subsequent rename form one serialized
+     * critical section.
+     *
+     * Ownership resolves against three buckets:
+     *
+     *   1. **Safe-to-write**: the file is absent, corrupt, or has a missing/
+     *      malformed `session_id`. No competing session is on disk, so we
+     *      write without hesitation.
+     *   2. **We own it**: the stored `session_id` matches ours. Normal
+     *      steady-state — every flush lands here.
+     *   3. **Another session owns it**: the stored `session_id` differs
+     *      from ours. Before 0.9.0 pass-4 this was an unconditional yield,
+     *      which was strictly safer but broke the crash-recovery case —
+     *      a NEW `rea serve` launched after an unclean shutdown would
+     *      observe the crashed session's id and yield forever, leaving
+     *      `rea status` permanently stuck. Codex pass-4 P1 flagged this.
+     *
+     *      The 0.9.0 `owner_pid` field exists exactly to disambiguate this
+     *      bucket. If `owner_pid` is alive, an overlapping writer is still
+     *      running and we yield (silent). If `owner_pid` is gone (ESRCH)
+     *      or missing from the payload (pre-0.9.0 file or same-process
+     *      write), we treat the file as abandoned and take over.
+     *
+     * `process.kill(pid, 0)` returns ESRCH for a missing PID, EPERM for a
+     * live PID we cannot signal. We treat EPERM as "alive from someone's
+     * perspective" and yield — never steal a file the kernel is uncertain
+     * about.
+     */
+    private ownsStateFile;
+    /**
+     * Schedule a longer-interval retry of `flushNow`. Used by the yield path
+     * so a new gateway waiting on a live peer eventually reclaims the file
+     * when the peer exits. Idempotent — if a retry is already pending, this
+     * call is a no-op.
+     *
+     * Distinct from `scheduleUpdate()` because:
+     *   - The debounce timer coalesces rapid events; this timer polls at a
+     *     slow cadence for ownership changes.
+     *   - Scheduling yield retries on the debounce timer would mean one
+     *     supervisor event during the wait cancels the retry, and the
+     *     debounce timer ALSO can't be re-scheduled while `timer !== null`.
+     */
+    private scheduleYieldRetry;
+    /**
+     * Stop further scheduled writes. Called from the gateway shutdown path
+     * AFTER the final flush. Clears any pending timer; no more writes will
+     * occur after this returns.
+     */
+    stop(): void;
+    /** Exposed for tests. Builds the canonical payload from live sources. */
+    buildSnapshot(): LiveServeState;
+    private buildDownstreamBlock;
+}