Harden app-server recovery edge cases

Avoid exec fallback once app-server turn/start may have accepted a prompt.

Preserve timeout status for interrupted timeout completions and merge durable session-state writes.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: xuio

dist/index.js

@@ -24103,7 +24103,7 @@ var CodexAppServerSession = class _CodexAppServerSession {
     }
     if (method === "turn/completed") {
       const turn = params?.turn;
-      const status = resultStatusFromTurn(turn?.status);
+      const status = active.timeoutReason && turn?.status === "interrupted" ? "timeout" : resultStatusFromTurn(turn?.status);
       if (hasTurnErrorStatus(turn?.status) && turn?.error) {
         active.summary.errors.push(JSON.stringify(turn.error));
       }
@@ -24241,13 +24241,18 @@ var SessionStateStore = class {
       return [];
     }
   }
-  save(sessions) {
+  save(sessions, options = {}) {
     mkdirSync3(path7.dirname(this.file), { recursive: true });
     const temp = `${this.file}.${process.pid}.tmp`;
+    const replaceIds = new Set(options.replaceIds ?? sessions.map((session) => session.id));
+    const merged = [
+      ...this.load().filter((session) => !replaceIds.has(session.id)),
+      ...sessions
+    ];
     const payload = {
       version: 1,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      sessions
+      sessions: merged
     };
     writeFileSync2(temp, `${JSON.stringify(payload, null, 2)}
 `, "utf8");
@@ -24356,6 +24361,7 @@ function readPositiveInt2(value, fallback, max) {
 var CodexSessionManager = class {
   sessions = /* @__PURE__ */ new Map();
   stateStore;
+  persistedSessionIds = /* @__PURE__ */ new Set();
   completedTtlSeconds = readPositiveInt2(
     process.env.CODEX_SUBAGENTS_SESSION_COMPLETED_TTL_SECONDS,
     3600,
@@ -24460,6 +24466,7 @@ var CodexSessionManager = class {
       stateFile: this.stateStore?.file
     };
     this.sessions.set(session.id, session);
+    if (this.stateStore) this.persistedSessionIds.add(session.id);
     const turn = this.enqueueTurn(session, {
       prompt: options.prompt,
       overrides: {
@@ -24950,15 +24957,13 @@ var CodexSessionManager = class {
         { sessionTurnId: session.activeTurn?.id }
       );
     } catch (error2) {
-      if (session.turns === 0 && shouldFallbackToExec(error2)) {
+      if (session.turns === 0 && !session.appServer && shouldFallbackToExec(error2)) {
         session.appServerFallbackReason = error2 instanceof Error ? error2.message : String(error2);
         logger.warn("session.app_server_fallback_to_exec", {
           sessionId: session.id,
           appServerFallbackReason: session.appServerFallbackReason,
           error: errorForLog(error2)
         });
-        await session.appServer?.close().catch(() => {
-        });
         session.appServer = void 0;
         session.protocol = "exec";
         return this.runExecTurn(session, {
@@ -25080,6 +25085,7 @@ var CodexSessionManager = class {
       const record2 = this.recordFromState(persisted);
       if (!record2) continue;
       this.sessions.set(record2.id, record2);
+      this.persistedSessionIds.add(record2.id);
     }
     logger.info("session.state.loaded", { stateFile: store.file, sessions: this.sessions.size });
   }
@@ -25139,7 +25145,7 @@ var CodexSessionManager = class {
       error: session.error
     }));
     try {
-      store.save(states);
+      store.save(states, { replaceIds: this.persistedSessionIds });
     } catch (error2) {
       logger.error("session.state.save_failed", { stateFile: store.file, error: errorForLog(error2) });
     }

src/app-server.ts

@@ -853,7 +853,9 @@ export class CodexAppServerSession {
 
     if (method === "turn/completed") {
       const turn = params?.turn as JsonObject | undefined;
-      const status = resultStatusFromTurn(turn?.status);
+      const status = active.timeoutReason && turn?.status === "interrupted"
+        ? "timeout"
+        : resultStatusFromTurn(turn?.status);
       if (hasTurnErrorStatus(turn?.status) && turn?.error) {
         active.summary.errors.push(JSON.stringify(turn.error));
       }

src/session-state.ts

@@ -47,13 +47,18 @@ export class SessionStateStore {
     }
   }
 
-  save(sessions: DurableSessionState[]): void {
+  save(sessions: DurableSessionState[], options: { replaceIds?: Iterable<string> } = {}): void {
     mkdirSync(path.dirname(this.file), { recursive: true });
     const temp = `${this.file}.${process.pid}.tmp`;
+    const replaceIds = new Set(options.replaceIds ?? sessions.map((session) => session.id));
+    const merged = [
+      ...this.load().filter((session) => !replaceIds.has(session.id)),
+      ...sessions,
+    ];
     const payload: SessionStateFile = {
       version: 1,
       updatedAt: new Date().toISOString(),
-      sessions,
+      sessions: merged,
     };
     writeFileSync(temp, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
     renameSync(temp, this.file);

src/sessions.ts

@@ -180,6 +180,7 @@ function readPositiveInt(value: string | undefined, fallback: number, max: numbe
 export class CodexSessionManager {
   private readonly sessions = new Map<string, CodexSessionRecord>();
   private readonly stateStore: SessionStateStore | undefined;
+  private readonly persistedSessionIds = new Set<string>();
   private readonly completedTtlSeconds = readPositiveInt(
     process.env.CODEX_SUBAGENTS_SESSION_COMPLETED_TTL_SECONDS,
     3600,
@@ -304,6 +305,7 @@ export class CodexSessionManager {
       stateFile: this.stateStore?.file,
     };
     this.sessions.set(session.id, session);
+    if (this.stateStore) this.persistedSessionIds.add(session.id);
     const turn = this.enqueueTurn(session, {
       prompt: options.prompt,
       overrides: {
@@ -872,14 +874,13 @@ export class CodexSessionManager {
         { sessionTurnId: session.activeTurn?.id },
       );
     } catch (error) {
-      if (session.turns === 0 && shouldFallbackToExec(error)) {
+      if (session.turns === 0 && !session.appServer && shouldFallbackToExec(error)) {
         session.appServerFallbackReason = error instanceof Error ? error.message : String(error);
         logger.warn("session.app_server_fallback_to_exec", {
           sessionId: session.id,
           appServerFallbackReason: session.appServerFallbackReason,
           error: errorForLog(error),
         });
-        await session.appServer?.close().catch(() => {});
         session.appServer = undefined;
         session.protocol = "exec";
         return this.runExecTurn(session, {
@@ -1036,6 +1037,7 @@ export class CodexSessionManager {
       const record = this.recordFromState(persisted);
       if (!record) continue;
       this.sessions.set(record.id, record);
+      this.persistedSessionIds.add(record.id);
     }
     logger.info("session.state.loaded", { stateFile: store.file, sessions: this.sessions.size });
   }
@@ -1099,7 +1101,7 @@ export class CodexSessionManager {
         error: session.error,
       }));
     try {
-      store.save(states);
+      store.save(states, { replaceIds: this.persistedSessionIds });
     } catch (error) {
       logger.error("session.state.save_failed", { stateFile: store.file, error: errorForLog(error) });
     }

test/app-server-hardening.test.ts

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { AgentRunQueue, BackpressureError, CodexJobManager } from "../src/jobs.js";
+import { SessionStateStore, type DurableSessionState } from "../src/session-state.js";
 import { CodexSessionManager } from "../src/sessions.js";
 
 const fakeCodex = path.resolve("test/fixtures/fake-codex.mjs");
@@ -132,6 +133,24 @@ describe("app-server hardening", () => {
     manager.cancel(session.id);
   });
 
+  it("preserves timeout status when a timed-out turn completes as interrupted", async () => {
+    const manager = new CodexSessionManager();
+    const projectDir = await tempDir("codex-subagents-app-timeout-interrupted-project-");
+
+    const { result, session } = await manager.start({
+      prompt: "timeout interrupted probe DELAY_MS=500",
+      projectDir,
+      codexBin: fakeCodex,
+      timeoutMs: 30,
+      terminateGraceMs: 100,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe("timeout");
+    expect(result.timeoutReason).toBe("timeout");
+    manager.cancel(session.id);
+  });
+
   it("terminates the app-server child process when a session is cancelled", async () => {
     const manager = new CodexSessionManager();
     const projectDir = await tempDir("codex-subagents-app-cancel-project-");
@@ -229,6 +248,53 @@ describe("app-server hardening", () => {
     manager.cancel(session.id);
   });
 
+  it("does not fall back to exec after turn/start may have been accepted", async () => {
+    const manager = new CodexSessionManager();
+    const projectDir = await tempDir("codex-subagents-app-turn-timeout-project-");
+    const recordDir = await tempDir("codex-subagents-app-turn-timeout-record-");
+
+    const { session, turn } = manager.startAsync({
+      prompt: "TURN_START_NO_RESPONSE",
+      projectDir,
+      codexBin: fakeCodex,
+      spawnTimeoutMs: 50,
+      env: {
+        FAKE_CODEX_RECORD_DIR: recordDir,
+      },
+    });
+
+    const waited = await manager.wait(session.id, 2_000, turn.id);
+    expect(waited.completed).toBe(true);
+    expect(waited.turn?.status).toBe("failed");
+    expect(waited.session?.protocol).toBe("app-server");
+
+    const calls = await recordedCalls(recordDir);
+    expect(calls.some((call) => call.protocol === "app-server" && call.method === "turn/start")).toBe(true);
+    expect(calls.some((call) => call.protocol === "exec")).toBe(false);
+    manager.cancel(session.id);
+  });
+
+  it("merges durable session state instead of overwriting unknown sessions", async () => {
+    const stateDir = await tempDir("codex-subagents-state-merge-");
+    const store = new SessionStateStore(path.join(stateDir, "sessions.json"));
+    const now = new Date().toISOString();
+    const state = (id: string): DurableSessionState => ({
+      id,
+      status: "active",
+      createdAt: now,
+      updatedAt: now,
+      codexThreadId: `thread-${id}`,
+      protocol: "app-server",
+      turns: 1,
+      baseOptions: { projectDir: stateDir },
+    });
+
+    store.save([state("external")], { replaceIds: ["external"] });
+    store.save([state("local")], { replaceIds: ["local"] });
+
+    expect(store.load().map((session) => session.id).sort()).toEqual(["external", "local"]);
+  });
+
   it("marks live steering unsupported when turn/steer fails", async () => {
     const manager = new CodexSessionManager();
     const projectDir = await tempDir("codex-subagents-app-steer-fail-project-");

test/fixtures/fake-codex.mjs

@@ -272,6 +272,9 @@ if (args[0] === "app-server") {
         return;
       }
       recordCall({ protocol: "app-server", method, prompt: activePrompt, threadId, turnId: activeTurn });
+      if (hasMode("TURN_START_NO_RESPONSE")) {
+        return;
+      }
       send({
         id,
         result: {