instar 1.3.211 → 1.3.213

package/dist/core/SessionRecoveryChannel.d.ts

@@ -0,0 +1,103 @@
+/**
+ * SessionRecoveryChannel — the cross-process request/ack channel for codex
+ * session-wedge SELF-recovery.
+ *
+ * The constraint that shapes this (grounded 2026-06-03):
+ *   - The DETECTOR (`StuckInputSentinel`) runs in the SERVER process.
+ *   - The RESTART AUTHORITY (`ServerSupervisor` + `TelegramLifeline.replayQueue`)
+ *     runs in the LIFELINE process.
+ * So the sentinel cannot restart anything directly — it must cross the process
+ * boundary. This channel is that boundary, modelled on the existing
+ * version-skew signal-file pattern (`state/lifeline-restart-requested.json`)
+ * but dedicated to per-session recovery and SAFE for two processes to share:
+ *
+ *   - `state/session-recovery-requested.json` — SOLE writer is the SERVER
+ *     (sentinel requests recovery). The lifeline only READS it.
+ *   - `state/session-recovery-acked.json` — SOLE writer is the LIFELINE
+ *     (it acks progress/outcome). The server only READS it.
+ *
+ * Single-writer-per-file means there is never a cross-process write race; both
+ * writes are atomic (temp+rename via SafeFsExecutor). Requests/acks are keyed by
+ * sessionId and carry an `attemptId` so a stale ack from a prior escalation
+ * episode can't be mistaken for the current one.
+ *
+ * Signal vs Authority: the request is a SIGNAL the server emits; the lifeline
+ * holds the AUTHORITY to act (or decline). This module is pure I/O — it performs
+ * NO restart and makes NO decision. Spec: docs/specs/CODEX-SESSION-WEDGE-SELF-RECOVERY.md
+ */
+/** Escalation tier the sentinel is asking the lifeline to perform.
+ *  - `redeliver`: re-deliver the pending/queued message to the wedged session
+ *    (the targeted primitive — this is what cleared the live wedge).
+ *  - `server-restart-replay`: graceful server restart + queue replay (the heavy
+ *    fallback; highest blast radius, hard-gated by the caller). */
+export type RecoveryTier = 'redeliver' | 'server-restart-replay';
+/** Lifecycle of a recovery attempt as reported back by the lifeline. */
+export type RecoveryOutcome = 'in-progress' | 'recovered' | 'failed';
+export interface RecoveryRequest {
+    /** tmux session name of the wedged session. */
+    sessionId: string;
+    tier: RecoveryTier;
+    /** Human-readable reason (e.g. "input present ≥N ticks, no turn progress"). */
+    reason: string;
+    /** ISO timestamp the stall was observed. */
+    observedAt: string;
+    /** Unique per escalation episode — distinguishes a fresh request from a stale
+     *  one for the same session. */
+    attemptId: string;
+    /** Who emitted it (e.g. 'StuckInputSentinel'). */
+    requestedBy: string;
+}
+export interface RecoveryAck {
+    sessionId: string;
+    /** Echoes the request's attemptId so the server can match ack→request. */
+    attemptId: string;
+    tier: RecoveryTier;
+    outcome: RecoveryOutcome;
+    /** Optional detail (e.g. "Replay complete: 1 delivered"). */
+    detail?: string;
+    /** ISO timestamp of this ack. */
+    updatedAt: string;
+}
+/**
+ * Cross-process recovery request/ack channel. Construct on BOTH sides with the
+ * same stateDir; the server uses the request* / readAck methods, the lifeline
+ * uses the readPendingRequests / ack* methods. The class enforces the
+ * single-writer-per-file invariant by never writing the file the other side owns.
+ */
+export declare class SessionRecoveryChannel {
+    private readonly requestPath;
+    private readonly ackPath;
+    private readonly cooldownPath;
+    constructor(stateDir: string);
+    /** Emit/refresh a recovery request for a session. Idempotent per
+     *  (sessionId, attemptId): re-requesting the SAME attempt is a no-op write of
+     *  identical content; a NEW attemptId replaces the prior request for that
+     *  session. Returns true if the file changed. */
+    requestRecovery(req: RecoveryRequest): boolean;
+    /** Read the lifeline's ack for a session (null if none). The server matches
+     *  `attemptId` to confirm the ack is for the CURRENT attempt. */
+    readAck(sessionId: string): RecoveryAck | null;
+    /** Clear a session's request after recovery is verified (or abandoned). */
+    clearRequest(sessionId: string): boolean;
+    /** All pending recovery requests (server-emitted). Empty array if none. */
+    readPendingRequests(): RecoveryRequest[];
+    /** Record/refresh the lifeline's ack for a session. Sole writer of the ack
+     *  file; overwrites the prior ack for that session (the latest outcome wins). */
+    ackRecovery(ack: RecoveryAck): void;
+    /** Drop a session's ack once the server has consumed it (keeps the file small). */
+    clearAck(sessionId: string): boolean;
+    /** Record that the lifeline performed a tier-C restart for a session. DURABLE:
+     *  survives the server restart that wipes the sentinel's in-memory bound, so it
+     *  is the only thing standing between a restart-can't-fix wedge and an infinite
+     *  restart loop. `atEpochMs` is supplied by the caller (Date.now()). */
+    recordRestart(sessionId: string, atEpochMs: number): void;
+    /** Epoch-ms of the last tier-C restart for a session, or null if none recorded. */
+    lastRestartAt(sessionId: string): number | null;
+    /** True if a tier-C restart for this session happened within `cooldownMs` of
+     *  `nowMs` — the lifeline MUST NOT restart again while this is true (loop guard). */
+    isInCooldown(sessionId: string, nowMs: number, cooldownMs: number): boolean;
+    private ensureDir;
+    private writeRequests;
+    private writeAcks;
+}
+//# sourceMappingURL=SessionRecoveryChannel.d.ts.map

package/dist/core/SessionRecoveryChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRecoveryChannel.d.ts","sourceRoot":"","sources":["../../src/core/SessionRecoveryChannel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH;;;;mEAImE;AACnE,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,uBAAuB,CAAC;AAEjE,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB;oCACgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC;IACzB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB;AAoCD;;;;;GAKG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,QAAQ,EAAE,MAAM;IAU5B;;;qDAGiD;IACjD,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO;IAW9C;qEACiE;IACjE,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAK9C,2EAA2E;IAC3E,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAUxC,2EAA2E;IAC3E,mBAAmB,IAAI,eAAe,EAAE;IAMxC;qFACiF;IACjF,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAMnC,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAUpC;;;4EAGwE;IACxE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAOzD,mFAAmF;IACnF,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAM/C;yFACqF;IACrF,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAO3E,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,SAAS;CAIlB"}

package/dist/core/SessionRecoveryChannel.js

@@ -0,0 +1,158 @@
+/**
+ * SessionRecoveryChannel — the cross-process request/ack channel for codex
+ * session-wedge SELF-recovery.
+ *
+ * The constraint that shapes this (grounded 2026-06-03):
+ *   - The DETECTOR (`StuckInputSentinel`) runs in the SERVER process.
+ *   - The RESTART AUTHORITY (`ServerSupervisor` + `TelegramLifeline.replayQueue`)
+ *     runs in the LIFELINE process.
+ * So the sentinel cannot restart anything directly — it must cross the process
+ * boundary. This channel is that boundary, modelled on the existing
+ * version-skew signal-file pattern (`state/lifeline-restart-requested.json`)
+ * but dedicated to per-session recovery and SAFE for two processes to share:
+ *
+ *   - `state/session-recovery-requested.json` — SOLE writer is the SERVER
+ *     (sentinel requests recovery). The lifeline only READS it.
+ *   - `state/session-recovery-acked.json` — SOLE writer is the LIFELINE
+ *     (it acks progress/outcome). The server only READS it.
+ *
+ * Single-writer-per-file means there is never a cross-process write race; both
+ * writes are atomic (temp+rename via SafeFsExecutor). Requests/acks are keyed by
+ * sessionId and carry an `attemptId` so a stale ack from a prior escalation
+ * episode can't be mistaken for the current one.
+ *
+ * Signal vs Authority: the request is a SIGNAL the server emits; the lifeline
+ * holds the AUTHORITY to act (or decline). This module is pure I/O — it performs
+ * NO restart and makes NO decision. Spec: docs/specs/CODEX-SESSION-WEDGE-SELF-RECOVERY.md
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { SafeFsExecutor } from './SafeFsExecutor.js';
+const REQUEST_RELPATH = path.join('state', 'session-recovery-requested.json');
+const ACK_RELPATH = path.join('state', 'session-recovery-acked.json');
+const COOLDOWN_RELPATH = path.join('state', 'session-recovery-cooldown.json');
+function readJsonOrNull(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return null;
+        const raw = fs.readFileSync(filePath, 'utf8');
+        if (!raw.trim())
+            return null;
+        return JSON.parse(raw);
+    }
+    catch {
+        // Corrupt/torn file → treat as empty rather than throw. A subsequent write
+        // overwrites it cleanly.
+        return null;
+    }
+}
+/**
+ * Cross-process recovery request/ack channel. Construct on BOTH sides with the
+ * same stateDir; the server uses the request* / readAck methods, the lifeline
+ * uses the readPendingRequests / ack* methods. The class enforces the
+ * single-writer-per-file invariant by never writing the file the other side owns.
+ */
+export class SessionRecoveryChannel {
+    requestPath;
+    ackPath;
+    cooldownPath;
+    constructor(stateDir) {
+        // stateDir is the agent's .instar dir; the signal files live under
+        // <stateDir>/state/ alongside the version-skew signal.
+        this.requestPath = path.join(stateDir, REQUEST_RELPATH);
+        this.ackPath = path.join(stateDir, ACK_RELPATH);
+        this.cooldownPath = path.join(stateDir, COOLDOWN_RELPATH);
+    }
+    // ---- SERVER (sentinel) side — sole writer of the request file ----
+    /** Emit/refresh a recovery request for a session. Idempotent per
+     *  (sessionId, attemptId): re-requesting the SAME attempt is a no-op write of
+     *  identical content; a NEW attemptId replaces the prior request for that
+     *  session. Returns true if the file changed. */
+    requestRecovery(req) {
+        const file = readJsonOrNull(this.requestPath) ?? { version: 1, requests: {} };
+        const existing = file.requests[req.sessionId];
+        if (existing && existing.attemptId === req.attemptId && existing.tier === req.tier) {
+            return false; // identical in-flight request — nothing to do
+        }
+        file.requests[req.sessionId] = req;
+        this.writeRequests(file);
+        return true;
+    }
+    /** Read the lifeline's ack for a session (null if none). The server matches
+     *  `attemptId` to confirm the ack is for the CURRENT attempt. */
+    readAck(sessionId) {
+        const file = readJsonOrNull(this.ackPath);
+        return file?.acks?.[sessionId] ?? null;
+    }
+    /** Clear a session's request after recovery is verified (or abandoned). */
+    clearRequest(sessionId) {
+        const file = readJsonOrNull(this.requestPath);
+        if (!file || !file.requests[sessionId])
+            return false;
+        delete file.requests[sessionId];
+        this.writeRequests(file);
+        return true;
+    }
+    // ---- LIFELINE side — sole writer of the ack file ----
+    /** All pending recovery requests (server-emitted). Empty array if none. */
+    readPendingRequests() {
+        const file = readJsonOrNull(this.requestPath);
+        if (!file?.requests)
+            return [];
+        return Object.values(file.requests);
+    }
+    /** Record/refresh the lifeline's ack for a session. Sole writer of the ack
+     *  file; overwrites the prior ack for that session (the latest outcome wins). */
+    ackRecovery(ack) {
+        const file = readJsonOrNull(this.ackPath) ?? { version: 1, acks: {} };
+        file.acks[ack.sessionId] = ack;
+        this.writeAcks(file);
+    }
+    /** Drop a session's ack once the server has consumed it (keeps the file small). */
+    clearAck(sessionId) {
+        const file = readJsonOrNull(this.ackPath);
+        if (!file || !file.acks[sessionId])
+            return false;
+        delete file.acks[sessionId];
+        this.writeAcks(file);
+        return true;
+    }
+    // ---- LIFELINE side — durable restart cooldown (sole writer of the cooldown file) ----
+    /** Record that the lifeline performed a tier-C restart for a session. DURABLE:
+     *  survives the server restart that wipes the sentinel's in-memory bound, so it
+     *  is the only thing standing between a restart-can't-fix wedge and an infinite
+     *  restart loop. `atEpochMs` is supplied by the caller (Date.now()). */
+    recordRestart(sessionId, atEpochMs) {
+        const file = readJsonOrNull(this.cooldownPath) ?? { version: 1, restarts: {} };
+        file.restarts[sessionId] = atEpochMs;
+        this.ensureDir(this.cooldownPath);
+        SafeFsExecutor.atomicWriteJsonSync(this.cooldownPath, file, { operation: 'SessionRecoveryChannel.recordRestart' });
+    }
+    /** Epoch-ms of the last tier-C restart for a session, or null if none recorded. */
+    lastRestartAt(sessionId) {
+        const file = readJsonOrNull(this.cooldownPath);
+        const v = file?.restarts?.[sessionId];
+        return typeof v === 'number' ? v : null;
+    }
+    /** True if a tier-C restart for this session happened within `cooldownMs` of
+     *  `nowMs` — the lifeline MUST NOT restart again while this is true (loop guard). */
+    isInCooldown(sessionId, nowMs, cooldownMs) {
+        const last = this.lastRestartAt(sessionId);
+        return last !== null && nowMs - last < cooldownMs;
+    }
+    // ---- internals ----
+    ensureDir(filePath) {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+    }
+    writeRequests(file) {
+        this.ensureDir(this.requestPath);
+        SafeFsExecutor.atomicWriteJsonSync(this.requestPath, file, { operation: 'SessionRecoveryChannel.writeRequests' });
+    }
+    writeAcks(file) {
+        this.ensureDir(this.ackPath);
+        SafeFsExecutor.atomicWriteJsonSync(this.ackPath, file, { operation: 'SessionRecoveryChannel.writeAcks' });
+    }
+}
+//# sourceMappingURL=SessionRecoveryChannel.js.map

package/dist/core/SessionRecoveryChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRecoveryChannel.js","sourceRoot":"","sources":["../../src/core/SessionRecoveryChannel.ts"],"names":[],"mappings":"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"}

package/dist/core/SessionRecoveryConsumer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * SessionRecoveryConsumer — the LIFELINE-side executor for codex session-wedge
+ * self-recovery (tier C). It is the AUTHORITY half of the Signal-vs-Authority
+ * split: the server-process sentinel emits requests via SessionRecoveryChannel;
+ * this consumer (run from TelegramLifeline, where ServerSupervisor lives) reads
+ * them and actually performs the server restart + queue replay.
+ *
+ * The logic is deliberately separated from TelegramLifeline and takes its
+ * effects as injected callbacks (`restart`, `replay`) + an injectable clock, so
+ * it is unit-testable without standing up a lifeline. TelegramLifeline wires the
+ * real `supervisor.performGracefulRestart` and `replayQueue` and calls `tick()`
+ * on an interval.
+ *
+ * Safety properties (this is the highest-blast-radius path — it restarts the
+ * whole agent server):
+ *  - DRY-RUN first: `dryRun:true` logs what it WOULD do and acks recovered
+ *    without restarting. Ships in this mode.
+ *  - DURABLE cooldown: before any restart it checks `channel.isInCooldown`. A
+ *    tier-C restart wipes the sentinel's in-memory bound, so this durable guard
+ *    is the only thing preventing a restart-can't-fix wedge from looping.
+ *  - Records the restart BEFORE acting, so a crash mid-restart still counts
+ *    against the cooldown.
+ *  - Dedups on (sessionId, attemptId) so a lingering request (the sentinel was
+ *    restarted before it could clear it) is not re-executed.
+ *  - Never writes the request file (the server owns it) — ack + cooldown only.
+ *
+ * Spec: docs/specs/CODEX-SESSION-WEDGE-SELF-RECOVERY.md
+ */
+import type { SessionRecoveryChannel } from './SessionRecoveryChannel.js';
+export interface SessionRecoveryConsumerOptions {
+    channel: SessionRecoveryChannel;
+    /** Perform the server restart (TelegramLifeline → supervisor.performGracefulRestart). */
+    restart: (reason: string) => Promise<boolean>;
+    /** Replay the queued messages after the server is back (TelegramLifeline.replayQueue). */
+    replay: () => void;
+    /** When true, log only — never actually restart. Ships true. */
+    dryRun: boolean;
+    /** Minimum gap between tier-C restarts for the same session (loop guard). */
+    cooldownMs: number;
+    /** Injectable clock (epoch ms). Defaults to Date.now. */
+    now?: () => number;
+    /** Injectable logger. Defaults to console.log. */
+    log?: (msg: string) => void;
+}
+export declare class SessionRecoveryConsumer {
+    private readonly channel;
+    private readonly restart;
+    private readonly replay;
+    private readonly dryRun;
+    private readonly cooldownMs;
+    private readonly now;
+    private readonly log;
+    constructor(opts: SessionRecoveryConsumerOptions);
+    /** One pass: handle every pending tier-C recovery request. Best-effort — a
+     *  read/exec failure on one request never throws out of tick(). */
+    tick(): Promise<void>;
+    private handle;
+    private ack;
+}
+//# sourceMappingURL=SessionRecoveryConsumer.d.ts.map

package/dist/core/SessionRecoveryConsumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRecoveryConsumer.d.ts","sourceRoot":"","sources":["../../src/core/SessionRecoveryConsumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAmB,MAAM,6BAA6B,CAAC;AAE3F,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,sBAAsB,CAAC;IAChC,yFAAyF;IACzF,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,0FAA0F;IAC1F,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAC;IAChB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,kDAAkD;IAClD,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;gBAEhC,IAAI,EAAE,8BAA8B;IAUhD;uEACmE;IAC7D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAiBb,MAAM;IAqCpB,OAAO,CAAC,GAAG;CAUZ"}

package/dist/core/SessionRecoveryConsumer.js

@@ -0,0 +1,110 @@
+/**
+ * SessionRecoveryConsumer — the LIFELINE-side executor for codex session-wedge
+ * self-recovery (tier C). It is the AUTHORITY half of the Signal-vs-Authority
+ * split: the server-process sentinel emits requests via SessionRecoveryChannel;
+ * this consumer (run from TelegramLifeline, where ServerSupervisor lives) reads
+ * them and actually performs the server restart + queue replay.
+ *
+ * The logic is deliberately separated from TelegramLifeline and takes its
+ * effects as injected callbacks (`restart`, `replay`) + an injectable clock, so
+ * it is unit-testable without standing up a lifeline. TelegramLifeline wires the
+ * real `supervisor.performGracefulRestart` and `replayQueue` and calls `tick()`
+ * on an interval.
+ *
+ * Safety properties (this is the highest-blast-radius path — it restarts the
+ * whole agent server):
+ *  - DRY-RUN first: `dryRun:true` logs what it WOULD do and acks recovered
+ *    without restarting. Ships in this mode.
+ *  - DURABLE cooldown: before any restart it checks `channel.isInCooldown`. A
+ *    tier-C restart wipes the sentinel's in-memory bound, so this durable guard
+ *    is the only thing preventing a restart-can't-fix wedge from looping.
+ *  - Records the restart BEFORE acting, so a crash mid-restart still counts
+ *    against the cooldown.
+ *  - Dedups on (sessionId, attemptId) so a lingering request (the sentinel was
+ *    restarted before it could clear it) is not re-executed.
+ *  - Never writes the request file (the server owns it) — ack + cooldown only.
+ *
+ * Spec: docs/specs/CODEX-SESSION-WEDGE-SELF-RECOVERY.md
+ */
+export class SessionRecoveryConsumer {
+    channel;
+    restart;
+    replay;
+    dryRun;
+    cooldownMs;
+    now;
+    log;
+    constructor(opts) {
+        this.channel = opts.channel;
+        this.restart = opts.restart;
+        this.replay = opts.replay;
+        this.dryRun = opts.dryRun;
+        this.cooldownMs = opts.cooldownMs;
+        this.now = opts.now ?? (() => Date.now());
+        this.log = opts.log ?? ((m) => console.log(m));
+    }
+    /** One pass: handle every pending tier-C recovery request. Best-effort — a
+     *  read/exec failure on one request never throws out of tick(). */
+    async tick() {
+        let pending;
+        try {
+            pending = this.channel.readPendingRequests();
+        }
+        catch {
+            return;
+        }
+        for (const req of pending) {
+            if (req.tier !== 'server-restart-replay')
+                continue; // lifeline only owns tier C
+            try {
+                await this.handle(req);
+            }
+            catch (err) {
+                this.ack(req, 'failed', `executor error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    async handle(req) {
+        const now = this.now();
+        // Dedup: this exact attempt already reached a terminal ack → done.
+        const prior = this.channel.readAck(req.sessionId);
+        if (prior && prior.attemptId === req.attemptId && prior.outcome !== 'in-progress') {
+            return;
+        }
+        // Durable cooldown — the cross-restart loop guard.
+        if (this.channel.isInCooldown(req.sessionId, now, this.cooldownMs)) {
+            this.ack(req, 'failed', 'restart cooldown active (loop guard)');
+            this.log(`[SessionRecovery] cooldown active for ${req.sessionId} — refusing restart`);
+            return;
+        }
+        // Mark in-progress and record the restart BEFORE acting (so a crash mid-restart
+        // still counts against the cooldown).
+        this.ack(req, 'in-progress', this.dryRun ? 'dry-run' : 'restarting server + replay');
+        this.channel.recordRestart(req.sessionId, now);
+        if (this.dryRun) {
+            this.log(`[SessionRecovery] [DRY-RUN] would restart server + replay for wedged session ${req.sessionId} (${req.reason})`);
+            this.ack(req, 'recovered', 'dry-run: no restart performed');
+            return;
+        }
+        this.log(`[SessionRecovery] restarting server + replay for wedged session ${req.sessionId} (${req.reason})`);
+        const ok = await this.restart(`codex-wedge-recovery: ${req.sessionId}`);
+        if (ok) {
+            this.replay();
+            this.ack(req, 'recovered', 'server restarted + queue replayed');
+        }
+        else {
+            this.ack(req, 'failed', 'graceful restart returned false');
+        }
+    }
+    ack(req, outcome, detail) {
+        this.channel.ackRecovery({
+            sessionId: req.sessionId,
+            attemptId: req.attemptId,
+            tier: req.tier,
+            outcome,
+            detail,
+            updatedAt: new Date(this.now()).toISOString(),
+        });
+    }
+}
+//# sourceMappingURL=SessionRecoveryConsumer.js.map

package/dist/core/SessionRecoveryConsumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRecoveryConsumer.js","sourceRoot":"","sources":["../../src/core/SessionRecoveryConsumer.ts"],"names":[],"mappings":"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"}

package/dist/core/StuckInputSentinel.d.ts

@@ -49,6 +49,7 @@
  * silently disappear after a server crash."
  */
 import type { SessionManager } from './SessionManager.js';
+import { SessionRecoveryChannel, type RecoveryTier } from './SessionRecoveryChannel.js';
 export interface StuckInputSentinelOptions {
     /** Poll interval. Default 10s. */
     tickMs?: number;
@@ -63,6 +64,18 @@ export interface StuckInputSentinelOptions {
     stateDir: string;
     /** Disable persistence to disk (used by unit tests). */
     noPersist?: boolean;
+    /** Cross-process recovery channel. When provided AND escalationEnabled, the
+     *  sentinel escalates PAST the keypress ladder (tier C: it requests a server
+     *  restart + replay from the lifeline, which owns ServerSupervisor). When
+     *  absent the sentinel keeps its legacy behavior (exhaust → stop). */
+    recoveryChannel?: SessionRecoveryChannel;
+    /** Master gate for the deeper-tier escalation. Default false (dark): the
+     *  sentinel marks the record exhausted after the keypress ladder, exactly as
+     *  before. Set true (via config) to enable tier-C recovery requests. */
+    escalationEnabled?: boolean;
+    /** How many ticks to wait for the lifeline to ack a tier-C request before
+     *  giving up (bounded — no restart loop). Default 6. */
+    escalationTimeoutTicks?: number;
 }
 /** In-memory record of what the sentinel has seen for a given session. */
 interface SessionStuckRecord {
@@ -77,6 +90,16 @@ interface SessionStuckRecord {
     /** Whether this record is exhausted (max attempts reached, won't fire
      *  again until the prompt text changes). */
     exhausted: boolean;
+    /** Deeper-tier escalation phase (after the keypress ladder exhausts).
+     *   - 'none': not escalating (keypress ladder still running or escalation off).
+     *   - 'requested': a tier-C recovery request is in flight to the lifeline;
+     *     subsequent ticks read the ack.
+     *   - 'recovered'/'gave-up': terminal. */
+    recoveryPhase: 'none' | 'requested' | 'recovered' | 'gave-up';
+    /** attemptId of the in-flight recovery request (matches the channel ack). */
+    recoveryAttemptId?: string;
+    /** tickCounter value when the request was emitted (for the bounded wait). */
+    recoveryRequestedTick?: number;
 }
 /** Event row written to stuck-input-events.jsonl on each fire. */
 export interface StuckInputEvent {
@@ -84,8 +107,10 @@ export interface StuckInputEvent {
     session: string;
     promptText: string;
     attempt: number;
-    action: 'Enter' | 'C-m' | 'Enter-sleep-Enter';
-    outcome: 'fired' | 'fire-error';
+    action: 'Enter' | 'C-m' | 'Enter-sleep-Enter' | 'escalate-request' | 'escalate-recovered' | 'escalate-failed' | 'escalate-timeout';
+    outcome: 'fired' | 'fire-error' | 'escalated' | 'recovered' | 'gave-up';
+    /** Recovery tier for escalation events (absent for keypress events). */
+    tier?: RecoveryTier;
     error?: string;
 }
 export declare class StuckInputSentinel {
@@ -96,11 +121,16 @@ export declare class StuckInputSentinel {
     private readonly stateDir;
     private readonly noPersist;
     private readonly eventsLogPath;
+    private readonly recoveryChannel;
+    private readonly escalationEnabled;
+    private readonly escalationTimeoutTicks;
     /** Per-session sticky state. Keyed by tmuxSession. */
     private readonly records;
     private intervalHandle;
     private tickInProgress;
     private degradationReportedOnce;
+    /** Monotonic tick counter — drives the bounded escalation wait. */
+    private tickCounter;
     constructor(sessionManager: SessionManager, opts: StuckInputSentinelOptions);
     start(): void;
     stop(): void;
@@ -149,6 +179,33 @@ export declare class StuckInputSentinel {
     /** Map attempt index → human-readable action name (matches
      *  SessionManager.fireStuckInputRecovery's escalation). */
     static actionForAttempt(attempt: number): StuckInputEvent['action'];
+    /**
+     * Clear a session's in-flight tier-C recovery request when the session has
+     * recovered out-of-band — it's now actively working (the wedge drained) or it
+     * is gone. The sentinel is the sole writer of the request file, so it (not the
+     * lifeline) does this cleanup. No-op unless a request is actually in flight.
+     * This closes the "request lingers after a successful drain" path that the
+     * stuck-detection branches would otherwise skip (they early-return before
+     * handleEscalation ever reads the ack).
+     */
+    private finalizePendingRecovery;
+    /**
+     * Deeper-tier escalation, invoked once the keypress ladder (tier A) is
+     * exhausted but the prompt is still stuck. This is the codex session-wedge
+     * SELF-recovery path: the sentinel (server process) cannot restart the server
+     * itself — ServerSupervisor lives in the lifeline process — so it REQUESTS a
+     * tier-C recovery (server restart + queue replay) through SessionRecoveryChannel
+     * and the lifeline executes + acks. The sentinel here only signals, polls the
+     * ack, verifies, and bounds the wait (no restart loop). Spec:
+     * docs/specs/CODEX-SESSION-WEDGE-SELF-RECOVERY.md.
+     *
+     * Dark by default: with escalation disabled or no channel, this reproduces the
+     * legacy behavior exactly (mark the record exhausted and stop).
+     *
+     * NOTE: a gentler server-side tier B (re-inject the full pending message before
+     * requesting a restart) is a planned refinement; this first cut goes A→C.
+     */
+    private handleEscalation;
     /** Append one event row to the JSONL log. Best-effort. */
     private recordEvent;
     /** Test helper: read the in-memory record for a session. */

package/dist/core/StuckInputSentinel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StuckInputSentinel.d.ts","sourceRoot":"","sources":["../../src/core/StuckInputSentinel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,WAAW,yBAAyB;IACxC,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;0CAEsC;IACtC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;wEACoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,0EAA0E;AAC1E,UAAU,kBAAkB;IAC1B,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB;gDAC4C;IAC5C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,mBAAmB,CAAC;IAC9C,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAeD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IAEtE,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,uBAAuB,CAAS;gBAE5B,cAAc,EAAE,cAAc,EAAE,IAAI,EAAE,yBAAyB;IAU3E,KAAK,IAAI,IAAI;IAiBb,IAAI,IAAI,IAAI;IAOZ;;;;;;OAMG;IACH,IAAI,IAAI,IAAI;IA0BZ,+DAA+D;IAC/D,OAAO,CAAC,eAAe;IA4GvB;;;6EAGyE;IACzE,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAoB9C;;;;;;;;;;;;;;;;;;;;;iCAqB6B;IAC7B,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK5C;;oDAEgD;IAChD,OAAO,CAAC,YAAY;IAUpB;+DAC2D;IAC3D,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC;IAMnE,0DAA0D;IAC1D,OAAO,CAAC,WAAW;IAUnB,4DAA4D;IAC5D,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrE,8CAA8C;IAC9C,YAAY,IAAI,IAAI;CAIrB"}
+{"version":3,"file":"StuckInputSentinel.d.ts","sourceRoot":"","sources":["../../src/core/StuckInputSentinel.ts"],"names":[],"mappings":"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"}