@leo000001/codex-mcp 2.1.3 → 2.1.5

package/dist/index.js

@@ -392,7 +392,7 @@ var DEFAULT_TERMINAL_CLEANUP_MS = 5 * 60 * 1e3;
 var CLEANUP_INTERVAL_MS = 6e4;
 
 // src/app-server/client.ts
-var CLIENT_VERSION = true ? "2.1.3" : "0.0.0-dev";
+var CLIENT_VERSION = true ? "2.1.5" : "0.0.0-dev";
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var STARTUP_REQUEST_TIMEOUT = 9e4;
 var MAX_WRITE_QUEUE_BYTES = 5 * 1024 * 1024;
@@ -417,6 +417,9 @@ var AppServerClient = class extends EventEmitter {
   get supportsTurnOverrides() {
     return true;
   }
+  get childPid() {
+    return this.process?.pid ?? void 0;
+  }
   /**
    * Spawn codex app-server and perform initialization handshake.
    */
@@ -814,7 +817,7 @@ function resolveAndValidateCwd(inputCwd, baseCwd) {
 function redactPaths(message) {
   const uncPath = /(^|[\s'"(])\\\\[^\s\\/:]+\\[^\s:]+(?:\\[^\s:]+)*/g;
   const windowsPath = /\b[A-Za-z]:\\[^\s:]+/g;
-  const posixPath = /(^|[\s'"(])\/[^\s:'")]+/g;
+  const posixPath = /(^|[\s'"(])\/[^\s:'")]*\/[^\s:'")]+/g;
   return message.replace(uncPath, (_m, prefix) => `${prefix}<path>`).replace(windowsPath, "<path>").replace(posixPath, (_m, prefix) => `${prefix}<path>`);
 }
 
@@ -877,19 +880,97 @@ function stripShellNoise(delta) {
   if (cleaned.length === 0) return "";
   return cleaned.join("\n");
 }
+var MAX_WAITERS_PER_SESSION = 4;
+var MAX_WAIT_MS = 12e4;
 var SessionManager = class {
   sessions = /* @__PURE__ */ new Map();
   clients = /* @__PURE__ */ new Map();
   cancellationInFlight = /* @__PURE__ */ new Map();
   cleanupTimer = null;
   createClient;
+  /** Optional disk persistence adapter. */
+  persistence;
+  /** Track last persisted status to avoid redundant writes. */
+  lastPersistedStatus = /* @__PURE__ */ new Map();
+  /** Sessions for which a TTL warning event has already been emitted this cycle. */
+  ttlWarningEmitted = /* @__PURE__ */ new Set();
+  /** Long-poll notifiers: set of resolve callbacks waiting for any change in a session. */
+  sessionNotifiers = /* @__PURE__ */ new Map();
   constructor(options = {}) {
     this.createClient = options.createClient ?? (() => new AppServerClient());
+    this.persistence = options.persistence ?? null;
     if (!options.disableCleanup) {
       this.cleanupTimer = setInterval(() => this.cleanupSessions(), CLEANUP_INTERVAL_MS);
       if (this.cleanupTimer.unref) this.cleanupTimer.unref();
     }
   }
+  /**
+   * Ingest recovered sessions from disk into the in-memory session store.
+   * Marks previously-running sessions as error, preserves completed results.
+   */
+  ingestRecovered(recovered) {
+    for (const rec of recovered) {
+      if (this.sessions.has(rec.sessionId)) continue;
+      const VALID_STATUSES = /* @__PURE__ */ new Set([
+        "running",
+        "idle",
+        "waiting_approval",
+        "error",
+        "cancelled"
+      ]);
+      const wasActive = rec.meta.status === "running" || rec.meta.status === "waiting_approval";
+      const resolvedStatus = wasActive ? "error" : VALID_STATUSES.has(rec.meta.status) ? rec.meta.status : "error";
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const session = {
+        sessionId: rec.meta.sessionId,
+        threadId: rec.meta.threadId,
+        status: resolvedStatus,
+        lastEventCursor: 0,
+        createdAt: rec.meta.createdAt,
+        lastActiveAt: now,
+        cancelledAt: rec.meta.cancelledAt,
+        cancelledReason: wasActive ? "Server restarted while session was active" : rec.meta.cancelledReason,
+        cwd: rec.meta.cwd ?? ".",
+        model: rec.meta.model,
+        approvalPolicy: rec.meta.approvalPolicy,
+        sandbox: rec.meta.sandbox,
+        eventBuffer: createEventBuffer(),
+        pendingRequests: /* @__PURE__ */ new Map(),
+        lastResult: rec.result
+      };
+      this.sessions.set(rec.sessionId, session);
+      if (rec.lastSeq >= 0) {
+        this.persistence?.setEventLogNextSeq(rec.sessionId, rec.lastSeq + 1);
+      }
+      if (wasActive) {
+        this.persistSessionIfChanged(session);
+      }
+    }
+  }
+  /**
+   * Best-effort persist session metadata to disk when status changes.
+   * Deduplicates writes if status hasn't changed since last persist.
+   */
+  persistSessionIfChanged(session) {
+    if (!this.persistence) return;
+    const lastStatus = this.lastPersistedStatus.get(session.sessionId);
+    if (lastStatus === session.status) return;
+    try {
+      this.persistence.writeSessionMeta(session);
+      this.lastPersistedStatus.set(session.sessionId, session.status);
+    } catch {
+    }
+  }
+  /**
+   * Best-effort persist result to disk.
+   */
+  persistResult(session) {
+    if (!this.persistence || !session.lastResult) return;
+    try {
+      this.persistence.writeResult(session.sessionId, session.lastResult);
+    } catch {
+    }
+  }
   // ── Session Creation ─────────────────────────────────────────────
   async createSession(prompt, cwd, spawnOpts, effort, advanced) {
     const sessionId = `sess_${randomUUID().slice(0, 12)}`;
@@ -915,9 +996,19 @@ var SessionManager = class {
     };
     this.sessions.set(sessionId, session);
     this.clients.set(sessionId, client);
+    try {
+      this.persistence?.writeSessionMeta(session);
+    } catch {
+    }
     try {
       this.registerHandlers(sessionId, client, approvalTimeoutMs);
       await client.start(spawnOpts);
+      if (client.childPid !== void 0) {
+        try {
+          this.persistence?.writePidInfo(sessionId, client.childPid, spawnOpts.model);
+        } catch {
+        }
+      }
       const threadStartResult = await client.threadStart({
         cwd,
         model: spawnOpts.model,
@@ -985,6 +1076,7 @@ var SessionManager = class {
     clearTerminalEvents(session.eventBuffer);
     session.status = "running";
     session.lastActiveAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.persistSessionIfChanged(session);
     const input = [{ type: "text", text: prompt }];
     const resolvedCwd = overrides?.cwd ? resolveAndValidateCwd(overrides.cwd, session.cwd) : void 0;
     const turnParams = {
@@ -1070,6 +1162,18 @@ var SessionManager = class {
     const session = this.getSessionOrThrow(sessionId);
     return includeSensitive ? toSensitiveInfo(session) : toPublicInfo(session);
   }
+  getLastResult(sessionId) {
+    return this.getSessionOrThrow(sessionId).lastResult;
+  }
+  getPendingActionTypes(sessionId) {
+    const session = this.getSessionOrThrow(sessionId);
+    const actionTypes = /* @__PURE__ */ new Set();
+    for (const req of session.pendingRequests.values()) {
+      if (req.resolved) continue;
+      actionTypes.add(req.kind === "user_input" ? "user_input" : "approval");
+    }
+    return Array.from(actionTypes);
+  }
   async cancelSession(sessionId, reason) {
     const existing = this.cancellationInFlight.get(sessionId);
     if (existing) {
@@ -1093,6 +1197,7 @@ var SessionManager = class {
     session.cancelledAt = now;
     session.lastActiveAt = now;
     session.cancelledReason = reason ?? "Cancelled by user";
+    this.persistSessionIfChanged(session);
     for (const [reqId, req] of session.pendingRequests) {
       if (req.timeoutHandle) clearTimeout(req.timeoutHandle);
       if (!req.resolved && req.respond) {
@@ -1129,6 +1234,7 @@ var SessionManager = class {
       { status: "cancelled", reason: session.cancelledReason, turnId: cancelledTurnId },
       true
     );
+    this.notifyWaiters(sessionId);
     if (client) {
       await client.destroy();
       this.clients.delete(sessionId);
@@ -1244,6 +1350,57 @@ var SessionManager = class {
       );
     }
   }
+  // ── Long-poll support ────────────────────────────────────────────
+  /**
+   * Wait until a new event is pushed, a new pending request arrives, a status
+   * change occurs, or `timeoutMs` elapses (whichever comes first).
+   *
+   * Rejects with an error when more than MAX_WAITERS_PER_SESSION concurrent
+   * waiters are already queued for the same session.
+   */
+  waitForChange(sessionId, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        resolve();
+        return;
+      }
+      let notifiers = this.sessionNotifiers.get(sessionId);
+      if (!notifiers) {
+        notifiers = /* @__PURE__ */ new Set();
+        this.sessionNotifiers.set(sessionId, notifiers);
+      }
+      if (notifiers.size >= MAX_WAITERS_PER_SESSION) {
+        reject(
+          new Error(
+            `[codex-mcp] Too many concurrent long-poll waiters for session '${sessionId}' (max ${MAX_WAITERS_PER_SESSION})`
+          )
+        );
+        return;
+      }
+      const clampedMs = Math.min(Math.max(0, timeoutMs), MAX_WAIT_MS);
+      const done = () => {
+        notifiers.delete(notifyFn);
+        if (notifiers.size === 0) this.sessionNotifiers.delete(sessionId);
+        clearTimeout(timer);
+        if (signal) signal.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      const notifyFn = done;
+      const timer = setTimeout(done, clampedMs);
+      if (timer.unref) timer.unref();
+      const onAbort = () => done();
+      if (signal) signal.addEventListener("abort", onAbort, { once: true });
+      notifiers.add(notifyFn);
+    });
+  }
+  /** Resolve all waiters for a session immediately (called on any state change). */
+  notifyWaiters(sessionId) {
+    const notifiers = this.sessionNotifiers.get(sessionId);
+    if (!notifiers || notifiers.size === 0) return;
+    for (const fn of Array.from(notifiers)) {
+      fn();
+    }
+  }
   // ── Event Polling ────────────────────────────────────────────────
   pollEvents(sessionId, cursor, maxEvents = DEFAULT_MAX_EVENTS, options = {}) {
     const session = this.getSessionOrThrow(sessionId);
@@ -1464,9 +1621,19 @@ var SessionManager = class {
         `Error [${"INTERNAL" /* INTERNAL */}]: Failed to build approval response for request '${requestId}'`
       );
     }
-    sendPendingRequestResponseOrThrow(req, response, sessionId, requestId);
     req.resolved = true;
     req.decision = decision;
+    try {
+      sendPendingRequestResponseOrThrow(req, response, sessionId, requestId);
+    } catch (error) {
+      req.resolved = false;
+      req.decision = void 0;
+      session.pendingRequests.set(requestId, req);
+      if (session.status !== "cancelled") {
+        session.status = "waiting_approval";
+      }
+      throw error;
+    }
     if (req.timeoutHandle) clearTimeout(req.timeoutHandle);
     pushEvent(
       session.eventBuffer,
@@ -1484,6 +1651,7 @@ var SessionManager = class {
     if (session.pendingRequests.size === 0 && session.status === "waiting_approval") {
       session.status = "running";
     }
+    this.notifyWaiters(sessionId);
   }
   // ── User Input Response ──────────────────────────────────────────
   resolveUserInput(sessionId, requestId, answers) {
@@ -1494,13 +1662,22 @@ var SessionManager = class {
         `Error [${"REQUEST_NOT_FOUND" /* REQUEST_NOT_FOUND */}]: User input request '${requestId}' not found`
       );
     }
-    sendPendingRequestResponseOrThrow(
-      req,
-      { answers },
-      sessionId,
-      requestId
-    );
     req.resolved = true;
+    try {
+      sendPendingRequestResponseOrThrow(
+        req,
+        { answers },
+        sessionId,
+        requestId
+      );
+    } catch (error) {
+      req.resolved = false;
+      session.pendingRequests.set(requestId, req);
+      if (session.status !== "cancelled") {
+        session.status = "waiting_approval";
+      }
+      throw error;
+    }
     if (req.timeoutHandle) clearTimeout(req.timeoutHandle);
     pushEvent(
       session.eventBuffer,
@@ -1517,6 +1694,7 @@ var SessionManager = class {
     if (session.pendingRequests.size === 0 && session.status === "waiting_approval") {
       session.status = "running";
     }
+    this.notifyWaiters(sessionId);
   }
   // ── Cleanup ──────────────────────────────────────────────────────
   destroy() {
@@ -1625,6 +1803,8 @@ var SessionManager = class {
             },
             true
           );
+          this.persistSessionIfChanged(session);
+          this.persistResult(session);
           break;
         }
         case Methods.ERROR: {
@@ -1651,6 +1831,7 @@ var SessionManager = class {
               );
             } else {
               pushEvent(session.eventBuffer, "error", data, true);
+              this.persistSessionIfChanged(session);
             }
           }
           break;
@@ -1699,6 +1880,7 @@ var SessionManager = class {
         default:
           break;
       }
+      this.notifyWaiters(sessionId);
     });
     client.onServerRequest((id, method, params) => {
       if (session.status === "cancelled" || session.status === "error") {
@@ -1769,6 +1951,7 @@ var SessionManager = class {
               if (session.pendingRequests.size === 0 && session.status === "waiting_approval") {
                 session.status = "running";
               }
+              this.notifyWaiters(sessionId);
             }
           }, approvalTimeoutMs);
           session.pendingRequests.set(requestId, pending);
@@ -1836,6 +2019,7 @@ var SessionManager = class {
               if (session.pendingRequests.size === 0 && session.status === "waiting_approval") {
                 session.status = "running";
               }
+              this.notifyWaiters(sessionId);
             }
           }, approvalTimeoutMs);
           session.pendingRequests.set(requestId, pending);
@@ -1890,6 +2074,7 @@ var SessionManager = class {
               if (session.pendingRequests.size === 0 && session.status === "waiting_approval") {
                 session.status = "running";
               }
+              this.notifyWaiters(sessionId);
             }
           }, approvalTimeoutMs);
           session.pendingRequests.set(requestId, pending);
@@ -1928,6 +2113,7 @@ var SessionManager = class {
           client.respondErrorToServer(id, -32601, `Unhandled server request: ${method}`);
           break;
       }
+      this.notifyWaiters(sessionId);
     });
     client.on("exit", (code) => {
       clearSessionPendingRequests(session);
@@ -1943,6 +2129,9 @@ var SessionManager = class {
           },
           true
         );
+        this.persistSessionIfChanged(session);
+        this.persistResult(session);
+        this.notifyWaiters(sessionId);
       }
     });
     client.on("error", (err) => {
@@ -1959,25 +2148,34 @@ var SessionManager = class {
           },
           true
         );
+        this.persistSessionIfChanged(session);
+        this.persistResult(session);
+        this.notifyWaiters(sessionId);
       }
     });
   }
   cleanupSessions() {
     const now = Date.now();
+    const TTL_WARNING_THRESHOLD_MS = 6e4;
     for (const [id, session] of this.sessions) {
       const lastActive = new Date(session.lastActiveAt).getTime();
       if (Number.isNaN(lastActive)) {
+        this.ttlWarningEmitted.delete(id);
         this.requestCancellation(id, "Invalid timestamp");
         continue;
       }
       const age = now - lastActive;
       if (session.status === "idle" && age > DEFAULT_IDLE_CLEANUP_MS) {
+        this.ttlWarningEmitted.delete(id);
         this.requestCancellation(id, "Idle timeout");
       } else if (session.status === "waiting_approval" && age > DEFAULT_RUNNING_CLEANUP_MS) {
+        this.ttlWarningEmitted.delete(id);
         this.requestCancellation(id, "Approval timeout");
       } else if (session.status === "running" && age > DEFAULT_RUNNING_CLEANUP_MS) {
+        this.ttlWarningEmitted.delete(id);
         this.requestCancellation(id, "Running timeout");
       } else if ((session.status === "cancelled" || session.status === "error") && age > DEFAULT_TERMINAL_CLEANUP_MS) {
+        this.ttlWarningEmitted.delete(id);
         this.clients.get(id)?.destroy().catch((err) => {
           console.error(
             `[codex-mcp] Failed to destroy app-server client during cleanup: session=${id} error=${err instanceof Error ? err.message : String(err)}`
@@ -1985,6 +2183,27 @@ var SessionManager = class {
         });
         this.clients.delete(id);
         this.sessions.delete(id);
+        this.lastPersistedStatus.delete(id);
+        this.ttlWarningEmitted.delete(id);
+      } else {
+        let ttlMs;
+        if (session.status === "idle") {
+          ttlMs = DEFAULT_IDLE_CLEANUP_MS;
+        } else if (session.status === "running" || session.status === "waiting_approval") {
+          ttlMs = DEFAULT_RUNNING_CLEANUP_MS;
+        }
+        if (ttlMs !== void 0 && !this.ttlWarningEmitted.has(id)) {
+          const timeUntilExpiry = ttlMs - age;
+          if (timeUntilExpiry <= TTL_WARNING_THRESHOLD_MS && timeUntilExpiry > 0) {
+            this.ttlWarningEmitted.add(id);
+            pushEvent(session.eventBuffer, "progress", {
+              method: "codex-mcp/ttl_warning",
+              type: "ttl_warning",
+              ttlRemainingMs: timeUntilExpiry,
+              sessionId: id
+            });
+          }
+        }
       }
     }
   }
@@ -2018,6 +2237,14 @@ function clearSessionPendingRequests(session) {
   session.pendingRequests.clear();
   for (const [, req] of entries) {
     if (req.timeoutHandle) clearTimeout(req.timeoutHandle);
+    if (!req.resolved && req.respond) {
+      try {
+        if (req.kind === "command") req.respond({ decision: "cancel" });
+        else if (req.kind === "fileChange") req.respond({ decision: "cancel" });
+        else if (req.kind === "user_input") req.respond({ answers: {} });
+      } catch {
+      }
+    }
     req.resolved = true;
   }
 }
@@ -2299,15 +2526,27 @@ function tryCoalesceProgressDelta(buf, type, data, pinned) {
   return true;
 }
 function evictEvents(buf) {
-  while (buf.events.length > buf.maxSize) {
-    const idx = buf.events.findIndex((e) => !e.pinned);
-    if (idx === -1) break;
-    buf.events.splice(idx, 1);
-  }
-  while (buf.events.length > buf.maxSize) {
-    const idx = buf.events.findIndex((e) => e.type === "approval_result");
-    if (idx === -1) break;
-    buf.events.splice(idx, 1);
+  if (buf.events.length > buf.maxSize) {
+    const overflow2 = buf.events.length - buf.maxSize;
+    const unpinnedIdx = [];
+    const approvalResultIdx2 = [];
+    for (let i = 0; i < buf.events.length; i++) {
+      const event = buf.events[i];
+      if (!event.pinned) unpinnedIdx.push(i);
+      else if (event.type === "approval_result") approvalResultIdx2.push(i);
+    }
+    const drop2 = /* @__PURE__ */ new Set();
+    for (const idx of unpinnedIdx) {
+      if (drop2.size >= overflow2) break;
+      drop2.add(idx);
+    }
+    for (const idx of approvalResultIdx2) {
+      if (drop2.size >= overflow2) break;
+      drop2.add(idx);
+    }
+    if (drop2.size > 0) {
+      buf.events = buf.events.filter((_, idx) => !drop2.has(idx));
+    }
   }
   if (buf.events.length <= buf.hardMaxSize) return;
   const overflow = buf.events.length - buf.hardMaxSize;
@@ -2454,17 +2693,117 @@ function extractSpawnOptions(params) {
   };
 }
 
+// src/utils/execution.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["idle", "error", "cancelled"]);
+function interactionStateForStatus(status) {
+  if (status === "waiting_approval") return "waiting_input";
+  if (TERMINAL_STATUSES.has(status)) return "finished";
+  return "working";
+}
+function recommendedNextActionForStatus(status, actionTypes = []) {
+  if (status === "waiting_approval") {
+    if (actionTypes.includes("user_input")) return "respond_user_input";
+    if (actionTypes.includes("approval")) return "respond_permission";
+  }
+  if (TERMINAL_STATUSES.has(status)) return "none";
+  return "poll";
+}
+function buildExecutionInfo(waitForResultMs, status, fallbackReason) {
+  const requested = waitForResultMs && waitForResultMs > 0 ? "foreground" : "background";
+  const effective = requested === "foreground" && TERMINAL_STATUSES.has(status) ? "foreground" : "background";
+  return {
+    requested,
+    effective,
+    waitForResultMs: waitForResultMs && waitForResultMs > 0 ? waitForResultMs : void 0,
+    fallbackReason: effective === "background" ? fallbackReason : void 0
+  };
+}
+async function waitForCodexSessionForegroundResult(sessionManager, sessionId, waitForResultMs, signal) {
+  const deadline = Date.now() + Math.min(waitForResultMs, 3e5);
+  while (Date.now() < deadline) {
+    let status2;
+    try {
+      status2 = sessionManager.getSession(sessionId).status;
+    } catch {
+      status2 = "error";
+    }
+    if (TERMINAL_STATUSES.has(status2)) {
+      const finalResult = sessionManager.getLastResult(sessionId);
+      return {
+        status: status2,
+        result: finalResult,
+        completedAt: finalResult?.completedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+    if (status2 === "waiting_approval") {
+      return {
+        status: status2,
+        pendingActionTypes: sessionManager.getPendingActionTypes(sessionId),
+        fallbackReason: "interactive_poll_required"
+      };
+    }
+    const remainingMs = Math.min(deadline - Date.now(), 5e3);
+    if (remainingMs <= 0) break;
+    try {
+      await sessionManager.waitForChange(sessionId, remainingMs, signal);
+    } catch {
+      break;
+    }
+  }
+  let status = "running";
+  try {
+    status = sessionManager.getSession(sessionId).status;
+  } catch {
+    status = "error";
+  }
+  return { status, fallbackReason: "wait_for_result_timeout" };
+}
+
 // src/tools/codex.ts
-async function executeCodex(args, sessionManager, serverCwd) {
+async function executeCodex(args, sessionManager, serverCwd, requestSignal) {
   const cwd = resolveAndValidateCwd(args.cwd, serverCwd);
   const spawnOpts = extractSpawnOptions(args);
   const effort = args.effort ?? DEFAULT_EFFORT_LEVEL;
-  return sessionManager.createSession(args.prompt, cwd, spawnOpts, effort, args.advanced);
+  const startResult = await sessionManager.createSession(
+    args.prompt,
+    cwd,
+    spawnOpts,
+    effort,
+    args.advanced
+  );
+  const waitMs = args.advanced?.waitForResult;
+  const baseResult = {
+    ...startResult,
+    execution: buildExecutionInfo(waitMs, "running"),
+    interactionState: interactionStateForStatus("running"),
+    recommendedNextAction: recommendedNextActionForStatus("running")
+  };
+  if (!waitMs || waitMs <= 0) return baseResult;
+  const foreground = await waitForCodexSessionForegroundResult(
+    sessionManager,
+    startResult.sessionId,
+    waitMs,
+    requestSignal
+  );
+  return {
+    sessionId: startResult.sessionId,
+    threadId: startResult.threadId,
+    result: foreground.result,
+    status: foreground.status,
+    completedAt: foreground.completedAt,
+    pollInterval: foreground.status === "waiting_approval" ? WAITING_APPROVAL_POLL_INTERVAL : foreground.status === "running" ? startResult.pollInterval : void 0,
+    execution: buildExecutionInfo(waitMs, foreground.status, foreground.fallbackReason),
+    interactionState: interactionStateForStatus(foreground.status),
+    recommendedNextAction: recommendedNextActionForStatus(
+      foreground.status,
+      foreground.pendingActionTypes ?? []
+    )
+  };
 }
 
 // src/tools/codex-reply.ts
-async function executeCodexReply(args, sessionManager) {
-  return sessionManager.replyToSession(args.sessionId, args.prompt, {
+async function executeCodexReply(args, sessionManager, requestSignal) {
+  const startResult = await sessionManager.replyToSession(args.sessionId, args.prompt, {
     model: args.model,
     approvalPolicy: args.approvalPolicy,
     effort: args.effort,
@@ -2474,6 +2813,36 @@ async function executeCodexReply(args, sessionManager) {
     cwd: args.cwd,
     outputSchema: args.outputSchema
   });
+  const waitMs = args.waitForResult;
+  const baseResult = {
+    ...startResult,
+    execution: buildExecutionInfo(waitMs, "running"),
+    interactionState: interactionStateForStatus("running"),
+    recommendedNextAction: recommendedNextActionForStatus("running")
+  };
+  if (!waitMs || waitMs <= 0) {
+    return baseResult;
+  }
+  const foreground = await waitForCodexSessionForegroundResult(
+    sessionManager,
+    startResult.sessionId,
+    waitMs,
+    requestSignal
+  );
+  return {
+    sessionId: startResult.sessionId,
+    threadId: startResult.threadId,
+    status: foreground.status,
+    pollInterval: foreground.status === "waiting_approval" ? WAITING_APPROVAL_POLL_INTERVAL : foreground.status === "running" ? startResult.pollInterval : void 0,
+    result: foreground.result,
+    completedAt: foreground.completedAt,
+    execution: buildExecutionInfo(waitMs, foreground.status, foreground.fallbackReason),
+    interactionState: interactionStateForStatus(foreground.status),
+    recommendedNextAction: recommendedNextActionForStatus(
+      foreground.status,
+      foreground.pendingActionTypes ?? []
+    )
+  };
 }
 
 // src/tools/codex-session.ts
@@ -2536,7 +2905,7 @@ async function executeCodexSession(args, sessionManager) {
 }
 
 // src/tools/codex-check.ts
-function executeCodexCheck(args, sessionManager) {
+function executeCodexCheck(args, sessionManager, requestSignal) {
   const responseMode = args.responseMode ?? "minimal";
   const pollOptions = args.pollOptions;
   switch (args.action) {
@@ -2548,10 +2917,34 @@ function executeCodexCheck(args, sessionManager) {
         };
       }
       const maxEvents = typeof args.maxEvents === "number" ? Math.max(POLL_MIN_MAX_EVENTS, Math.floor(args.maxEvents)) : POLL_DEFAULT_MAX_EVENTS;
-      return sessionManager.pollEvents(args.sessionId, args.cursor, maxEvents, {
-        responseMode,
-        pollOptions
-      });
+      const waitMs = pollOptions?.waitMs;
+      if (typeof waitMs === "number" && waitMs > 0) {
+        const firstCheck = sessionManager.pollEvents(args.sessionId, args.cursor, maxEvents, {
+          responseMode,
+          pollOptions
+        });
+        const hasData = firstCheck.events.length > 0 || firstCheck.actions !== void 0 && firstCheck.actions.length > 0 || firstCheck.result !== void 0;
+        if (!hasData) {
+          const clampedWait = Math.min(waitMs, 12e4);
+          return sessionManager.waitForChange(args.sessionId, clampedWait, requestSignal).catch(() => void 0).then(
+            () => enrichCheckResult(
+              sessionManager,
+              sessionManager.pollEvents(args.sessionId, args.cursor, maxEvents, {
+                responseMode,
+                pollOptions
+              })
+            )
+          );
+        }
+        return enrichCheckResult(sessionManager, firstCheck);
+      }
+      return enrichCheckResult(
+        sessionManager,
+        sessionManager.pollEvents(args.sessionId, args.cursor, maxEvents, {
+          responseMode,
+          pollOptions
+        })
+      );
     }
     case "respond_permission": {
       if (!args.requestId || !args.decision) {
@@ -2621,10 +3014,13 @@ function executeCodexCheck(args, sessionManager) {
         return { error: message, isError: true };
       }
       const maxEvents = typeof args.maxEvents === "number" ? Math.max(0, Math.floor(args.maxEvents)) : RESPOND_DEFAULT_MAX_EVENTS;
-      return sessionManager.pollEventsMonotonic(args.sessionId, args.cursor, maxEvents, {
-        responseMode,
-        pollOptions
-      });
+      return enrichCheckResult(
+        sessionManager,
+        sessionManager.pollEventsMonotonic(args.sessionId, args.cursor, maxEvents, {
+          responseMode,
+          pollOptions
+        })
+      );
     }
     case "respond_user_input": {
       if (!args.requestId || !args.answers) {
@@ -2646,10 +3042,13 @@ function executeCodexCheck(args, sessionManager) {
         return { error: message, isError: true };
       }
       const maxEvents = typeof args.maxEvents === "number" ? Math.max(0, Math.floor(args.maxEvents)) : RESPOND_DEFAULT_MAX_EVENTS;
-      return sessionManager.pollEventsMonotonic(args.sessionId, args.cursor, maxEvents, {
-        responseMode,
-        pollOptions
-      });
+      return enrichCheckResult(
+        sessionManager,
+        sessionManager.pollEventsMonotonic(args.sessionId, args.cursor, maxEvents, {
+          responseMode,
+          pollOptions
+        })
+      );
     }
     default:
       return {
@@ -2658,9 +3057,218 @@ function executeCodexCheck(args, sessionManager) {
       };
   }
 }
+function enrichCheckResult(sessionManager, result) {
+  const actionTypes = result.status === "waiting_approval" ? sessionManager.getPendingActionTypes(result.sessionId) : [];
+  return {
+    ...result,
+    interactionState: interactionStateForStatus(result.status),
+    recommendedNextAction: recommendedNextActionForStatus(result.status, actionTypes)
+  };
+}
 
-// src/resources/register-resources.ts
+// src/tools/codex-setup.ts
 import { spawnSync } from "child_process";
+import { existsSync as existsSync5 } from "fs";
+import { homedir } from "os";
+import path5 from "path";
+
+// src/app-server/detect.ts
+import { spawn as spawn2 } from "child_process";
+var DETECTION_TIMEOUT_MS = 5e3;
+async function detectClientMode(codexCommand, codexIsPath = false, env = process.env) {
+  const override = env.CODEX_MCP_MODE;
+  if (override === "app-server" || override === "exec") {
+    return override;
+  }
+  try {
+    const supported = await probeAppServer(codexCommand, codexIsPath, env);
+    return supported ? "app-server" : "exec";
+  } catch {
+    return "exec";
+  }
+}
+function probeAppServer(codexCommand, codexIsPath, env) {
+  return new Promise((resolve) => {
+    const invocation = resolveCodexInvocation(["app-server", "--help"], {
+      env,
+      codexCommand,
+      codexIsPath
+    });
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    let stdout = "";
+    let stderr = "";
+    const proc = spawn2(invocation.cmd, invocation.args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+      windowsHide: true
+    });
+    proc.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    proc.on("error", () => {
+      settle(false);
+    });
+    proc.on("exit", (code) => {
+      if (code === 0) {
+        settle(true);
+      } else {
+        const combined = (stdout + stderr).toLowerCase();
+        const isUnknown = combined.includes("unknown") || combined.includes("unrecognized") || combined.includes("not found") || combined.includes("no such subcommand");
+        settle(!isUnknown && combined.includes("app-server"));
+      }
+    });
+    const timer = setTimeout(() => {
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+      }
+      const forceKill = setTimeout(() => {
+        try {
+          if (!proc.killed && proc.exitCode === null) {
+            proc.kill("SIGKILL");
+          }
+        } catch {
+        }
+      }, 2e3);
+      if (forceKill.unref) forceKill.unref();
+      settle(false);
+    }, DETECTION_TIMEOUT_MS);
+    if (timer.unref) timer.unref();
+  });
+}
+
+// src/tools/codex-setup.ts
+function classifyAuthResult(status, combined) {
+  if (status === 0) return "authenticated";
+  if (/(not (logged|authenticated)|login required|run\s+codex\s+login)/i.test(combined)) {
+    return "unauthenticated";
+  }
+  return "unknown";
+}
+function resolveCodexStateDir() {
+  const configured = process.env.CODEX_MCP_STATE_DIR?.trim();
+  return configured && configured !== "" ? configured : path5.join(homedir(), ".codex-mcp", "state");
+}
+function probeCodexAuth(info) {
+  const invocation = resolveCodexInvocation(["login", "status"], {
+    codexCommand: info.command,
+    codexIsPath: info.isPath
+  });
+  const run = spawnSync(invocation.cmd, invocation.args, {
+    encoding: "utf8",
+    timeout: 5e3,
+    windowsHide: true
+  });
+  const combined = `${run.stdout ?? ""}
+${run.stderr ?? ""}`.trim();
+  if (run.error) {
+    return {
+      ok: false,
+      state: "unknown",
+      detail: `Failed to probe auth status: ${run.error.message}`
+    };
+  }
+  const state = classifyAuthResult(run.status, combined);
+  return {
+    ok: state !== "unauthenticated",
+    state,
+    detail: combined || (state === "authenticated" ? "Authenticated." : "Auth status unknown.")
+  };
+}
+async function executeCodexSetup(input, serverCwd) {
+  const cwd = input?.cwd && input.cwd.trim() !== "" ? input.cwd : serverCwd;
+  const warnings = [];
+  const nextSteps = [];
+  let executable;
+  let auth;
+  let clientMode;
+  try {
+    const info = resolveDefaultCodexExecutable();
+    const available = info.source !== "default";
+    executable = {
+      ok: available,
+      source: info.source,
+      command: info.command,
+      isPath: info.isPath,
+      detail: info.source === "default" ? "No codex executable was auto-detected; the server would fall back to `codex` and let process spawn fail later." : `Codex resolves via ${info.source}.`
+    };
+    if (available) {
+      auth = probeCodexAuth(info);
+      clientMode = await detectClientMode(info.command, info.isPath);
+    } else {
+      auth = {
+        ok: false,
+        state: "unknown",
+        detail: "Auth status not checked because no codex executable was detected."
+      };
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    executable = {
+      ok: false,
+      source: "error",
+      detail: message
+    };
+    auth = {
+      ok: false,
+      state: "unknown",
+      detail: "Auth status not checked because executable resolution failed."
+    };
+  }
+  const projectContext = {
+    hasUserConfig: existsSync5(path5.join(homedir(), ".codex", "config.toml")),
+    hasProjectConfig: existsSync5(path5.join(cwd, ".codex", "config.toml"))
+  };
+  if (!executable.ok) {
+    warnings.push(executable.detail);
+    nextSteps.push(
+      "Install Codex or fix CODEX_MCP_COMMAND / CODEX_MCP_PATH so the executable can be resolved."
+    );
+  }
+  if (auth.state === "unauthenticated") {
+    warnings.push(auth.detail);
+    nextSteps.push("Run `codex login` and rerun `codex_setup`.");
+  } else if (auth.state === "unknown") {
+    warnings.push(auth.detail);
+    nextSteps.push(
+      "Verify Codex authentication explicitly (for example with `codex login status`) before relying on this environment."
+    );
+  }
+  if (!projectContext.hasUserConfig && !projectContext.hasProjectConfig) {
+    warnings.push("No Codex config.toml was found in ~/.codex or this project.");
+  }
+  if (clientMode === "exec") {
+    warnings.push(
+      "Codex app-server support was not detected; codex-mcp would run in exec fallback mode with fewer capabilities."
+    );
+  }
+  return {
+    ready: executable.ok && auth.ok,
+    cwd,
+    executable,
+    auth,
+    runtime: {
+      sameMachineRequired: true,
+      clientMode,
+      stateDir: resolveCodexStateDir()
+    },
+    projectContext,
+    warnings,
+    nextSteps
+  };
+}
+
+// src/resources/register-resources.ts
+import { spawnSync as spawnSync2 } from "child_process";
 
 // src/utils/stdio-guard.ts
 var STDIO_MODES = ["auto", "strict", "off"];
@@ -2759,7 +3367,8 @@ var RESOURCE_URIS = {
   config: `${RESOURCE_SCHEME}:///config`,
   gotchas: `${RESOURCE_SCHEME}:///gotchas`,
   quickstart: `${RESOURCE_SCHEME}:///quickstart`,
-  errors: `${RESOURCE_SCHEME}:///errors`
+  errors: `${RESOURCE_SCHEME}:///errors`,
+  delegationGuide: `${RESOURCE_SCHEME}:///delegation-guide`
 };
 var RESOURCE_CATALOG = [
   {
@@ -2803,6 +3412,13 @@ var RESOURCE_CATALOG = [
     title: "Errors",
     description: "Error code reference and recovery hints",
     mimeType: "text/markdown"
+  },
+  {
+    key: "delegationGuide",
+    name: "delegation_guide",
+    title: "Delegation Guide",
+    description: "Best practices for delegating tasks to Codex",
+    mimeType: "text/markdown"
   }
 ];
 var ERROR_CODE_HINTS = {
@@ -2833,7 +3449,8 @@ function asTextResource(uri, text, mimeType) {
 }
 function detectCodexCliVersion(timeoutMs = 1500) {
   try {
-    const run = spawnSync("codex", ["--version"], {
+    const executable = getDefaultCodexExecutable();
+    const run = spawnSync2(executable.command, ["--version"], {
       encoding: "utf8",
       timeout: timeoutMs,
       windowsHide: true
@@ -2975,6 +3592,8 @@ function buildQuickstartText() {
   return [
     "## Minimal flow",
     "",
+    "0. Optional but recommended: run `codex_setup` first to verify the local Codex CLI, login state, and backend mode.",
+    "",
     "1. Start session (`codex`)",
     "",
     "```json",
@@ -3073,6 +3692,64 @@ function buildErrorsText() {
   lines.push("");
   return lines.join("\n");
 }
+function buildDelegationGuideText() {
+  return [
+    "# Codex Delegation Guide",
+    "",
+    "## When to delegate",
+    "- Bug investigation or fix that benefits from a second opinion",
+    "- Code review (use read-only sandbox)",
+    "- Refactoring or migration tasks with clear scope",
+    "- Tasks where the calling agent is stuck or wants parallel work",
+    "",
+    "## Permission combinations by task type",
+    "",
+    "| Task | approvalPolicy | sandbox | Notes |",
+    "|------|---------------|---------|-------|",
+    "| Code review / analysis | `never` | `read-only` | Safe: sandbox blocks writes, no approval needed |",
+    "| Quick bug fix | `on-failure` | `workspace-write` | Auto-approves unless error; good with `waitForResult` |",
+    "| Feature implementation | `on-failure` | `workspace-write` | Async mode recommended for longer tasks |",
+    "| Sensitive refactor | `on-request` | `workspace-write` | Codex asks before each action; requires active polling |",
+    "| Full autonomy | `never` | `workspace-write` | No guardrails \u2014 only for well-scoped, trusted tasks |",
+    "| Network access needed | `on-failure` | `danger-full-access` | Rare; avoid unless genuinely required |",
+    "",
+    "**Key rule:** `read-only` sandbox already prevents writes, so `approvalPolicy: 'never'` is safe with it. Avoid `untrusted` + `read-only` \u2014 every read command triggers approval for no safety gain.",
+    "",
+    "## Quick mode: `waitForResult`",
+    "For short tasks (< 2 min), set `advanced.waitForResult` to get the final result in a single tool call:",
+    "```json",
+    '{ "prompt": "Fix the null check in auth.ts", "approvalPolicy": "on-failure", "sandbox": "workspace-write", "effort": "medium", "advanced": { "waitForResult": 120000 } }',
+    "```",
+    "If the task finishes within the timeout, the result is returned directly. Otherwise the response falls back to polling metadata (including `sessionId` and `threadId`).",
+    "",
+    "**Constraint:** `waitForResult` blocks your tool call. If the task hits `waiting_approval`, you cannot respond \u2014 the timeout will always expire. Only use with `approvalPolicy: 'on-failure'` or `'never'`.",
+    "",
+    "## Async mode: poll loop",
+    'For long tasks, omit `waitForResult`. Use `codex_check(action="poll", pollOptions={ waitMs: 30000 })` with long-polling to avoid empty polls.',
+    "",
+    "## Effort selection",
+    "- `low` (default): quick questions, lookups, simple edits",
+    "- `medium`: multi-file changes, moderate reasoning",
+    "- `high`/`xhigh`: complex architecture decisions, large refactors",
+    "",
+    "## Troubleshooting",
+    "",
+    "**Tool call hangs:** Likely `waitForResult` + approval conflict; cancel and retry with `on-failure`/`never`. See `codex-mcp:///gotchas`.",
+    "",
+    "**Empty polls:** Use `pollOptions.waitMs` for long-polling; stop when status is terminal. See `codex-mcp:///gotchas`.",
+    "",
+    "**Session not found after restart:** Previously-running sessions surface as `status: 'error'` with restart reason. See `codex-mcp:///gotchas`.",
+    "",
+    "**Approval timeout:** Default is 60s; infrequent polling causes silent auto-decline. See `codex-mcp:///gotchas`.",
+    "",
+    "## Security notes",
+    "- `sandbox: 'read-only'` is the strongest isolation \u2014 blocks all writes regardless of approval policy",
+    "- `approvalPolicy: 'never'` + `sandbox: 'workspace-write'` gives the agent full write access with no human oversight \u2014 use only for well-defined, low-risk tasks",
+    "- `danger-full-access` allows network and system access \u2014 treat as root-equivalent",
+    "- Persisted session data (events, results) may contain code snippets and file paths \u2014 stored in `~/.codex-mcp/state/`",
+    ""
+  ].join("\n");
+}
 function buildCompatReport(deps, codexCliVersion) {
   const runtimeWarnings = [];
   if (!codexCliVersion) {
@@ -3107,7 +3784,7 @@ function buildCompatReport(deps, codexCliVersion) {
         }
       },
       toolCounts: {
-        core: 4
+        core: 5
       },
       runtimeWarnings,
       detectedMismatches: [],
@@ -3237,10 +3914,22 @@ function registerResources(server, deps) {
     },
     () => asTextResource(errorsUri, buildErrorsText(), "text/markdown")
   );
-}
+  const delegationGuideMeta = byKey.get("delegationGuide");
+  const delegationGuideUri = new URL(RESOURCE_URIS.delegationGuide);
+  server.registerResource(
+    delegationGuideMeta.name,
+    delegationGuideUri.toString(),
+    {
+      title: delegationGuideMeta.title,
+      description: delegationGuideMeta.description,
+      mimeType: delegationGuideMeta.mimeType
+    },
+    () => asTextResource(delegationGuideUri, buildDelegationGuideText(), "text/markdown")
+  );
+}
 
 // src/server.ts
-var SERVER_VERSION = true ? "2.1.3" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.1.5" : "0.0.0-dev";
 function formatErrorMessage(err) {
   const message = err instanceof Error ? err.message : String(err);
   const m = /^Error \[([A-Z_]+)\]:\s*(.*)$/.exec(message);
@@ -3286,20 +3975,63 @@ function createServer(serverCwd, options) {
     error: z.string().optional(),
     isError: z.boolean().optional()
   };
+  const executionInfoSchema = z.object({
+    requested: z.enum(["background", "foreground"]),
+    effective: z.enum(["background", "foreground"]),
+    waitForResultMs: z.number().int().positive().optional(),
+    fallbackReason: z.enum(["wait_for_result_timeout", "interactive_poll_required"]).optional()
+  });
+  const interactionStateSchema = z.enum(["working", "waiting_input", "finished"]);
+  const nextActionSchema = z.enum(["poll", "respond_permission", "respond_user_input", "none"]);
+  const setupResultShape = {
+    ready: z.boolean(),
+    cwd: z.string(),
+    executable: z.object({
+      ok: z.boolean(),
+      source: z.string(),
+      command: z.string().optional(),
+      isPath: z.boolean().optional(),
+      detail: z.string()
+    }),
+    auth: z.object({
+      ok: z.boolean(),
+      state: z.enum(["authenticated", "unauthenticated", "unknown"]),
+      detail: z.string()
+    }),
+    runtime: z.object({
+      sameMachineRequired: z.boolean(),
+      clientMode: z.enum(["app-server", "exec"]).optional(),
+      stateDir: z.string()
+    }),
+    projectContext: z.object({
+      hasUserConfig: z.boolean(),
+      hasProjectConfig: z.boolean()
+    }),
+    warnings: z.array(z.string()),
+    nextSteps: z.array(z.string())
+  };
   const sessionStartOutputShape = {
     sessionId: z.string().optional(),
     threadId: z.string().optional(),
-    status: z.enum(["running", "idle"]).optional(),
+    status: z.enum(["running", "waiting_approval", "idle", "error", "cancelled"]).optional(),
     pollInterval: z.number().int().optional().describe(
       "Recommended minimum delay before next poll (ms): running >=120000, waiting_approval ~=1000."
     ),
+    result: z.unknown().optional().describe("Final result when waitForResult is set and session completed."),
+    completedAt: z.string().optional().describe("ISO timestamp when the session completed (only when waitForResult succeeded)."),
+    execution: executionInfoSchema.optional(),
+    interactionState: interactionStateSchema.optional(),
+    recommendedNextAction: nextActionSchema.optional(),
     ...errorOutputShape
   };
   const codexCheckPollOptionsSchema = z.object({
     includeEvents: z.boolean().optional().describe("Default: true. Include events[] in response."),
     includeActions: z.boolean().optional().describe("Default: true. Include actions[] in response."),
     includeResult: z.boolean().optional().describe("Default: true. Include result in response."),
-    maxBytes: z.number().int().positive().optional().describe("Default: unlimited. Best-effort response payload cap in bytes.")
+    maxBytes: z.number().int().positive().optional().describe("Default: unlimited. Best-effort response payload cap in bytes."),
+    waitMs: z.number().int().nonnegative().optional().describe(
+      "Long-poll: block up to this many ms for new events (max 120000). Omit or 0 for immediate return."
+    )
   }).optional().describe("Optional poll shaping controls.");
   const codexCheckInputSchema = z.object({
     action: z.enum(CHECK_ACTIONS),
@@ -3329,10 +4061,10 @@ function createServer(serverCwd, options) {
       })
     ).optional().describe("question-id -> answers map (id from actions[] user_input request).")
   }).superRefine((value, ctx) => {
-    const addIssue = (path5, message) => {
+    const addIssue = (path6, message) => {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        path: [path5],
+        path: [path6],
         message
       });
     };
@@ -3459,7 +4191,10 @@ function createServer(serverCwd, options) {
           ephemeral: z.boolean().optional().describe("Do not persist thread (default: false)."),
           outputSchema: z.record(z.string(), z.unknown()).optional().describe("Structured output schema."),
           images: z.array(z.string()).optional().describe("Local image paths."),
-          approvalTimeoutMs: z.number().int().positive().default(DEFAULT_APPROVAL_TIMEOUT_MS).optional().describe(`Auto-decline timeout in ms (default: ${DEFAULT_APPROVAL_TIMEOUT_MS})`)
+          approvalTimeoutMs: z.number().int().positive().default(DEFAULT_APPROVAL_TIMEOUT_MS).optional().describe(`Auto-decline timeout in ms (default: ${DEFAULT_APPROVAL_TIMEOUT_MS})`),
+          waitForResult: z.number().int().positive().max(3e5).optional().describe(
+            "Block up to this many ms for session completion (max 300000). Falls back to sessionId for polling if not done in time. Only use with approvalPolicy on-failure/never."
+          )
         }).optional().describe("Advanced settings.")
       },
       outputSchema: sessionStartOutputShape,
@@ -3471,9 +4206,9 @@ function createServer(serverCwd, options) {
         openWorldHint: true
       }
     },
-    async (args) => {
+    async (args, extra) => {
       try {
-        const result = await executeCodex(args, sessionManager, serverCwd);
+        const result = await executeCodex(args, sessionManager, serverCwd, extra.signal);
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
           structuredContent: toStructuredContent(result),
@@ -3504,7 +4239,10 @@ function createServer(serverCwd, options) {
         personality: z.enum(PERSONALITIES).optional().describe("Override personality."),
         sandbox: z.enum(SANDBOX_MODES).optional().describe("Override sandbox."),
         cwd: z.string().optional().describe("Override cwd."),
-        outputSchema: z.record(z.string(), z.unknown()).optional().describe("Structured output schema override (top-level in codex_reply).")
+        outputSchema: z.record(z.string(), z.unknown()).optional().describe("Structured output schema override (top-level in codex_reply)."),
+        waitForResult: z.number().int().positive().max(3e5).optional().describe(
+          "Wait up to this many ms for the reply turn to complete and return the result directly. Max 300000 (5 min). If the turn does not finish in time or enters interactive approval/user-input flow, returns session metadata for polling."
+        )
       },
       outputSchema: sessionStartOutputShape,
       annotations: {
@@ -3515,9 +4253,9 @@ function createServer(serverCwd, options) {
         openWorldHint: true
       }
     },
-    async (args) => {
+    async (args, extra) => {
       try {
-        const result = await executeCodexReply(args, sessionManager);
+        const result = await executeCodexReply(args, sessionManager, extra.signal);
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
           structuredContent: toStructuredContent(result),
@@ -3533,6 +4271,32 @@ function createServer(serverCwd, options) {
       }
     }
   );
+  server.registerTool(
+    "codex_setup",
+    {
+      title: "Codex Setup",
+      description: "Run local readiness checks for codex-mcp: executable resolution, login status, detected backend mode, and project config. Use this before starting a session when setup is uncertain.",
+      inputSchema: {
+        cwd: z.string().optional().describe("Optional cwd to inspect for project-local Codex config. Default: server cwd.")
+      },
+      outputSchema: setupResultShape,
+      annotations: {
+        title: "Codex Setup",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (args) => {
+      const result = await executeCodexSetup(args, serverCwd);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: toStructuredContent(result),
+        isError: false
+      };
+    }
+  );
   server.registerTool(
     "codex_session",
     {
@@ -3604,23 +4368,11 @@ function createServer(serverCwd, options) {
     "codex_check",
     {
       title: "Poll & Respond",
-      description: `Poll session for events or respond to approval/input requests.
-
-POLLING FREQUENCY: Do NOT poll every turn. Codex tasks take minutes, not seconds.
-- Treat pollInterval as a minimum hint, not a fixed schedule.
-- "running": sleep at least 2 minutes between polls; increase for complex tasks. Do NOT high-frequency poll \u2014 it wastes tokens and provides no benefit.
-- "waiting_approval": poll about every 1000ms and respond quickly to actions[].
-- When status is "idle"/"error"/"cancelled": stop polling, the session is done.
-- Adapt interval based on task complexity and whether the previous poll returned new events.
+      description: `Poll session for events or respond to approval/input requests. Use pollInterval as a minimum hint; stop polling on terminal status (idle/error/cancelled). See codex-mcp:///gotchas for poll frequency guidance.
 
 poll: events since cursor. Default maxEvents=${POLL_DEFAULT_MAX_EVENTS}.
-
 respond_permission: approval decision. Default maxEvents=${RESPOND_DEFAULT_MAX_EVENTS} (compact ACK).
-
-respond_user_input: user-input answers. Default maxEvents=${RESPOND_DEFAULT_MAX_EVENTS} (compact ACK).
-
-events[].type is coarse-grained; details are in events[].data.method.
-cursor omitted => use session last cursor. cursorResetTo => reset and continue.`,
+respond_user_input: user-input answers. Default maxEvents=${RESPOND_DEFAULT_MAX_EVENTS} (compact ACK).`,
       inputSchema: codexCheckInputSchema,
       outputSchema: {
         sessionId: z.string().optional(),
@@ -3628,6 +4380,8 @@ cursor omitted => use session last cursor. cursorResetTo => reset and continue.`
         pollInterval: z.number().int().optional().describe(
           "Recommended minimum delay before next poll (ms): running >=120000, waiting_approval ~=1000."
         ),
+        interactionState: interactionStateSchema.optional(),
+        recommendedNextAction: nextActionSchema.optional(),
         events: z.array(
           z.object({
             id: z.number().int(),
@@ -3682,9 +4436,9 @@ cursor omitted => use session last cursor. cursorResetTo => reset and continue.`
         openWorldHint: false
       }
     },
-    async (args) => {
+    async (args, extra) => {
       try {
-        const result = executeCodexCheck(args, sessionManager);
+        const result = await executeCodexCheck(args, sessionManager, extra.signal);
         const isError = typeof result.isError === "boolean" ? result.isError : false;
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -3706,77 +4460,12 @@ cursor omitted => use session last cursor. cursorResetTo => reset and continue.`
     sessionManager.destroy();
     await originalClose();
   };
-  return server;
-}
-
-// src/app-server/detect.ts
-import { spawn as spawn2 } from "child_process";
-var DETECTION_TIMEOUT_MS = 5e3;
-async function detectClientMode(codexCommand, codexIsPath = false, env = process.env) {
-  const override = env.CODEX_MCP_MODE;
-  if (override === "app-server" || override === "exec") {
-    return override;
-  }
-  try {
-    const supported = await probeAppServer(codexCommand, codexIsPath, env);
-    return supported ? "app-server" : "exec";
-  } catch {
-    return "exec";
-  }
-}
-function probeAppServer(codexCommand, codexIsPath, env) {
-  return new Promise((resolve) => {
-    const invocation = resolveCodexInvocation(["app-server", "--help"], {
-      env,
-      codexCommand,
-      codexIsPath
-    });
-    let settled = false;
-    const settle = (result) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(result);
-    };
-    let stdout = "";
-    let stderr = "";
-    const proc = spawn2(invocation.cmd, invocation.args, {
-      stdio: ["ignore", "pipe", "pipe"],
-      env,
-      windowsHide: true
-    });
-    proc.stdout?.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    proc.stderr?.on("data", (chunk) => {
-      stderr += chunk.toString();
-    });
-    proc.on("error", () => {
-      settle(false);
-    });
-    proc.on("exit", (code) => {
-      if (code === 0) {
-        settle(true);
-      } else {
-        const combined = (stdout + stderr).toLowerCase();
-        const isUnknown = combined.includes("unknown") || combined.includes("unrecognized") || combined.includes("not found") || combined.includes("no such subcommand");
-        settle(!isUnknown && combined.includes("app-server"));
-      }
-    });
-    const timer = setTimeout(() => {
-      try {
-        proc.kill("SIGTERM");
-      } catch {
-      }
-      settle(false);
-    }, DETECTION_TIMEOUT_MS);
-    if (timer.unref) timer.unref();
-  });
+  return { server, sessionManager };
 }
 
 // src/app-server/exec-client.ts
 import { spawn as spawn3 } from "child_process";
-import { writeFileSync, mkdtempSync } from "fs";
+import { writeFileSync, mkdtempSync, rmSync } from "fs";
 import { EventEmitter as EventEmitter2 } from "events";
 import { randomUUID as randomUUID2 } from "crypto";
 import { tmpdir } from "os";
@@ -3873,6 +4562,7 @@ var ExecClient = class extends EventEmitter2 {
   threadStartParams = null;
   lastAgentMessageText = "";
   turnCompleted = false;
+  schemaTmpDirs = [];
   // Handlers
   notificationHandler = null;
   serverRequestHandler = null;
@@ -3885,6 +4575,9 @@ var ExecClient = class extends EventEmitter2 {
   get supportsTurnOverrides() {
     return this.turnCount <= 1 || this.realThreadId == null;
   }
+  get childPid() {
+    return this.process?.pid ?? void 0;
+  }
   async start(opts) {
     if (this._destroyed) throw new Error("Client destroyed");
     this.spawnOpts = opts;
@@ -3959,6 +4652,7 @@ var ExecClient = class extends EventEmitter2 {
     });
     proc.on("exit", (code, signal) => {
       if (this.turnId && !this._destroyed && !this.turnCompleted) {
+        this.turnCompleted = true;
         if (code !== 0 && code !== null) {
           this.emitNotification(Methods.ERROR, {
             threadId: this.threadId,
@@ -3967,6 +4661,17 @@ var ExecClient = class extends EventEmitter2 {
             willRetry: false
           });
         }
+        const turnId2 = this.turnId ?? "";
+        this.emitNotification(Methods.TURN_COMPLETED, {
+          threadId: this.threadId,
+          turn: {
+            id: turnId2,
+            status: code === 0 ? "completed" : "failed",
+            output: this.lastAgentMessageText || void 0,
+            ...code !== 0 && code !== null ? { error: { message: `exec process exited with code ${code}` } } : signal ? { error: { message: `exec process killed by signal ${signal}` } } : {}
+          }
+        });
+        this.turnId = null;
       }
       if (!this._destroyed) {
         this.emit("exit", code, signal);
@@ -4030,6 +4735,13 @@ var ExecClient = class extends EventEmitter2 {
     }
     this.process = null;
     this.removeAllListeners();
+    for (const dir of this.schemaTmpDirs) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+      }
+    }
+    this.schemaTmpDirs = [];
   }
   // ── Private helpers ─────────────────────────────────────────────
   /**
@@ -4057,6 +4769,7 @@ var ExecClient = class extends EventEmitter2 {
     if (params.outputSchema && Object.keys(params.outputSchema).length > 0) {
       try {
         const tmpDir = mkdtempSync(join(tmpdir(), "codex-mcp-schema-"));
+        this.schemaTmpDirs.push(tmpDir);
         const schemaPath = join(tmpDir, "output-schema.json");
         writeFileSync(schemaPath, JSON.stringify(params.outputSchema));
         args.push("--output-schema", schemaPath);
@@ -4143,7 +4856,7 @@ var ExecClient = class extends EventEmitter2 {
     const type = event.type;
     switch (type) {
       case "thread.started": {
-        const cliThreadId = event.thread_id;
+        const cliThreadId = event.thread_id ?? event.threadId;
         if (cliThreadId) {
           this.threadId = cliThreadId;
           this.realThreadId = cliThreadId;
@@ -4298,7 +5011,625 @@ var ExecClient = class extends EventEmitter2 {
   }
 };
 
+// src/session/persistence.ts
+import { join as join5 } from "path";
+import { mkdirSync as mkdirSync4, existsSync as existsSync7 } from "fs";
+import { homedir as homedir2 } from "os";
+
+// src/persistence/atomic-writer.ts
+import { writeFileSync as writeFileSync2, renameSync, mkdirSync, unlinkSync } from "fs";
+import { dirname, join as join2 } from "path";
+import { randomBytes } from "crypto";
+function atomicWriteJson(filePath, data) {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmpPath = join2(dir, `.tmp-${randomBytes(6).toString("hex")}`);
+  try {
+    writeFileSync2(tmpPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
+}
+
+// src/persistence/lockfile.ts
+import {
+  openSync,
+  closeSync,
+  readFileSync as readFileSync2,
+  writeFileSync as writeFileSync3,
+  unlinkSync as unlinkSync2,
+  mkdirSync as mkdirSync2,
+  constants as constants2
+} from "fs";
+import { dirname as dirname2 } from "path";
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function acquireLock(lockPath) {
+  mkdirSync2(dirname2(lockPath), { recursive: true });
+  try {
+    const raw = readFileSync2(lockPath, "utf-8");
+    const existing = JSON.parse(raw);
+    if (isPidAlive(existing.pid) && existing.pid !== process.pid) {
+      throw new Error(
+        `STATE_DIR is locked by another process (pid=${existing.pid}, started=${existing.startedAt}). If this is stale, delete ${lockPath}`
+      );
+    }
+    unlinkSync2(lockPath);
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      if (err.message?.includes("STATE_DIR is locked")) throw err;
+      console.error(
+        `[lockfile] Existing lock at ${lockPath} is unreadable \u2014 will attempt O_EXCL create`
+      );
+    }
+  }
+  const content = {
+    pid: process.pid,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  let fd;
+  try {
+    fd = openSync(lockPath, constants2.O_WRONLY | constants2.O_CREAT | constants2.O_EXCL);
+    writeFileSync3(fd, JSON.stringify(content) + "\n", "utf-8");
+    closeSync(fd);
+    fd = void 0;
+  } catch (err) {
+    if (fd !== void 0) {
+      try {
+        closeSync(fd);
+      } catch {
+      }
+    }
+    if (err.code === "EEXIST") {
+      throw new Error(
+        `Failed to acquire STATE_DIR lock at ${lockPath} \u2014 race with another process`
+      );
+    }
+    try {
+      unlinkSync2(lockPath);
+    } catch {
+    }
+    throw err;
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    try {
+      unlinkSync2(lockPath);
+    } catch {
+    }
+  };
+}
+
+// src/persistence/event-log.ts
+import { appendFileSync, mkdirSync as mkdirSync3 } from "fs";
+import { dirname as dirname3 } from "path";
+var EventLog = class {
+  filePath;
+  batchIntervalMs;
+  buffer = [];
+  flushTimer = null;
+  nextSeq = 0;
+  destroyed = false;
+  constructor(opts) {
+    this.filePath = opts.filePath;
+    this.batchIntervalMs = opts.batchIntervalMs ?? 100;
+    mkdirSync3(dirname3(this.filePath), { recursive: true });
+  }
+  /**
+   * Append an event to the log.
+   * @param event - Arbitrary JSON-serializable event data
+   * @param criticality - "critical" forces immediate flush; "normal" batches
+   */
+  append(event, criticality = "normal") {
+    if (this.destroyed) return -1;
+    const seq = this.nextSeq++;
+    const line = JSON.stringify({ seq, ...event }) + "\n";
+    this.buffer.push({ line });
+    if (criticality === "critical") {
+      this.flushSync();
+    } else if (!this.flushTimer) {
+      this.flushTimer = setTimeout(() => {
+        this.flushTimer = null;
+        this.flushSync();
+      }, this.batchIntervalMs);
+      if (this.flushTimer.unref) this.flushTimer.unref();
+    }
+    return seq;
+  }
+  /** Set the next sequence number (used during recovery to continue from last known seq). */
+  setNextSeq(seq) {
+    this.nextSeq = seq;
+  }
+  /** Synchronously flush all buffered writes to disk. */
+  flushSync() {
+    if (this.buffer.length === 0) return;
+    const chunk = this.buffer.map((w) => w.line).join("");
+    this.buffer = [];
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    try {
+      appendFileSync(this.filePath, chunk, "utf-8");
+    } catch (err) {
+      console.error(`[event-log] Failed to flush to ${this.filePath}:`, err);
+    }
+  }
+  /** Destroy the log, flushing any remaining events. */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.flushSync();
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+};
+
+// src/persistence/recovery-scanner.ts
+import { readdirSync, readFileSync as readFileSync3, existsSync as existsSync6, statSync as statSync4 } from "fs";
+import { join as join3 } from "path";
+var SCHEMA_VERSION = 1;
+function parseEventsJsonl(filePath) {
+  if (!existsSync6(filePath)) return [];
+  const raw = readFileSync3(filePath, "utf-8");
+  const lines = raw.split("\n");
+  const events = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed.seq === "number") {
+        events.push(parsed);
+      }
+    } catch {
+      break;
+    }
+  }
+  return events.sort((a, b) => a.seq - b.seq);
+}
+function readJsonSafe(filePath) {
+  if (!existsSync6(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync3(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function scanRecoverableSessions(sessionsDir, maxEvents = 500) {
+  if (!existsSync6(sessionsDir)) return [];
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(sessionsDir);
+  } catch {
+    return [];
+  }
+  for (const entry of entries) {
+    const sessionDir = join3(sessionsDir, entry);
+    try {
+      if (!statSync4(sessionDir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const meta = readJsonSafe(join3(sessionDir, "meta.json"));
+    if (!meta || !meta.sessionId) continue;
+    if (meta.schemaVersion !== void 0 && meta.schemaVersion > SCHEMA_VERSION) {
+      console.error(
+        `[recovery] Skipping session ${meta.sessionId}: schema version ${meta.schemaVersion} > ${SCHEMA_VERSION}`
+      );
+      continue;
+    }
+    let events = parseEventsJsonl(join3(sessionDir, "events.jsonl"));
+    if (events.length > maxEvents) {
+      events = events.slice(-maxEvents);
+    }
+    const lastSeq = events.length > 0 ? events[events.length - 1].seq : -1;
+    const result = readJsonSafe(join3(sessionDir, "result.json"));
+    const pidInfo = readJsonSafe(join3(sessionDir, "pid.json"));
+    results.push({
+      sessionId: meta.sessionId,
+      meta,
+      events,
+      lastSeq,
+      result,
+      pidInfo,
+      sessionDir
+    });
+  }
+  return results;
+}
+
+// src/persistence/retention.ts
+import { readdirSync as readdirSync2, rmSync as rmSync2, statSync as statSync5, readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
+var DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var DEFAULT_MAX_COUNT = 200;
+var DEFAULT_MAX_DISK_BYTES = 500 * 1024 * 1024;
+function getDirSize(dirPath) {
+  let total = 0;
+  try {
+    for (const entry of readdirSync2(dirPath)) {
+      try {
+        const st = statSync5(join4(dirPath, entry));
+        total += st.isFile() ? st.size : 0;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return total;
+}
+function pruneSessionDirs(sessionsDir, policy) {
+  const maxAgeMs = policy?.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+  const maxCount = policy?.maxCount ?? DEFAULT_MAX_COUNT;
+  const maxDiskBytes = policy?.maxDiskBytes ?? DEFAULT_MAX_DISK_BYTES;
+  let entries;
+  try {
+    entries = readdirSync2(sessionsDir);
+  } catch {
+    return 0;
+  }
+  const now = Date.now();
+  const dirs = [];
+  for (const entry of entries) {
+    const dirPath = join4(sessionsDir, entry);
+    try {
+      if (!statSync5(dirPath).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    let lastActiveAt = 0;
+    try {
+      const meta = JSON.parse(readFileSync4(join4(dirPath, "meta.json"), "utf-8"));
+      lastActiveAt = new Date(meta.lastActiveAt || meta.createdAt || 0).getTime();
+    } catch {
+      try {
+        lastActiveAt = statSync5(dirPath).mtimeMs;
+      } catch {
+        lastActiveAt = 0;
+      }
+    }
+    dirs.push({
+      path: dirPath,
+      sessionId: entry,
+      lastActiveAt,
+      diskBytes: getDirSize(dirPath)
+    });
+  }
+  dirs.sort((a, b) => a.lastActiveAt - b.lastActiveAt);
+  const toRemove = /* @__PURE__ */ new Set();
+  for (const dir of dirs) {
+    if (now - dir.lastActiveAt > maxAgeMs) {
+      toRemove.add(dir.path);
+    }
+  }
+  const remaining = dirs.filter((d) => !toRemove.has(d.path));
+  if (remaining.length > maxCount) {
+    const excess = remaining.length - maxCount;
+    for (let i = 0; i < excess; i++) {
+      toRemove.add(remaining[i].path);
+    }
+  }
+  const afterCountPrune = dirs.filter((d) => !toRemove.has(d.path));
+  let totalSize = afterCountPrune.reduce((sum, d) => sum + d.diskBytes, 0);
+  for (const dir of afterCountPrune) {
+    if (totalSize <= maxDiskBytes) break;
+    toRemove.add(dir.path);
+    totalSize -= dir.diskBytes;
+  }
+  let pruned = 0;
+  for (const dirPath of toRemove) {
+    try {
+      rmSync2(dirPath, { recursive: true, force: true });
+      pruned++;
+    } catch (err) {
+      console.error(`[retention] Failed to remove ${dirPath}:`, err);
+    }
+  }
+  return pruned;
+}
+
+// src/session/persistence.ts
+var CRITICAL_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "approval_request",
+  "approval_result",
+  "result",
+  "error"
+]);
+function eventCriticality(type) {
+  return CRITICAL_EVENT_TYPES.has(type) ? "critical" : "normal";
+}
+var SessionPersistence = class {
+  stateDir;
+  sessionsDir;
+  releaseLock = null;
+  eventLogs = /* @__PURE__ */ new Map();
+  constructor(stateDir) {
+    this.stateDir = stateDir ?? process.env.CODEX_MCP_STATE_DIR ?? join5(homedir2(), ".codex-mcp", "state");
+    this.sessionsDir = join5(this.stateDir, "sessions");
+    mkdirSync4(this.sessionsDir, { recursive: true });
+  }
+  /** Acquire the STATE_DIR lock. Call once at startup. */
+  acquireLock() {
+    this.releaseLock = acquireLock(join5(this.stateDir, ".lock"));
+  }
+  /** Release the lock. Call on shutdown. */
+  releaseLockIfHeld() {
+    if (this.releaseLock) {
+      this.releaseLock();
+      this.releaseLock = null;
+    }
+  }
+  // ── Write operations ────────────────────────────────────────────
+  /** Persist session metadata (called on create and status changes). */
+  writeSessionMeta(session) {
+    const meta = {
+      schemaVersion: SCHEMA_VERSION,
+      sessionId: session.sessionId,
+      status: session.status,
+      createdAt: session.createdAt,
+      lastActiveAt: session.lastActiveAt,
+      cancelledAt: session.cancelledAt,
+      cancelledReason: session.cancelledReason,
+      threadId: session.threadId,
+      model: session.model,
+      cwd: session.cwd,
+      approvalPolicy: session.approvalPolicy,
+      sandbox: session.sandbox,
+      profile: session.profile
+    };
+    const dir = join5(this.sessionsDir, session.sessionId);
+    atomicWriteJson(join5(dir, "meta.json"), meta);
+  }
+  /** Persist PID info for orphan detection. */
+  writePidInfo(sessionId, pid, command) {
+    const info = {
+      pid,
+      spawnedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      command
+    };
+    const dir = join5(this.sessionsDir, sessionId);
+    mkdirSync4(dir, { recursive: true });
+    atomicWriteJson(join5(dir, "pid.json"), info);
+  }
+  /** Append an event to the session's event log. */
+  appendEvent(sessionId, type, data) {
+    let log = this.eventLogs.get(sessionId);
+    if (!log) {
+      const dir = join5(this.sessionsDir, sessionId);
+      mkdirSync4(dir, { recursive: true });
+      log = new EventLog({ filePath: join5(dir, "events.jsonl") });
+      this.eventLogs.set(sessionId, log);
+    }
+    log.append({ type, data, timestamp: (/* @__PURE__ */ new Date()).toISOString() }, eventCriticality(type));
+  }
+  /** Set the next sequence number for a recovered session's event log. */
+  setEventLogNextSeq(sessionId, seq) {
+    let log = this.eventLogs.get(sessionId);
+    if (!log) {
+      const dir = join5(this.sessionsDir, sessionId);
+      mkdirSync4(dir, { recursive: true });
+      log = new EventLog({ filePath: join5(dir, "events.jsonl") });
+      this.eventLogs.set(sessionId, log);
+    }
+    log.setNextSeq(seq);
+  }
+  /** Persist the final result. */
+  writeResult(sessionId, result) {
+    const dir = join5(this.sessionsDir, sessionId);
+    mkdirSync4(dir, { recursive: true });
+    atomicWriteJson(join5(dir, "result.json"), result);
+  }
+  // ── Read / Recovery ─────────────────────────────────────────────
+  /** Scan and recover sessions from disk. */
+  recoverSessions(maxEvents) {
+    return scanRecoverableSessions(this.sessionsDir, maxEvents);
+  }
+  /** Apply retention policy. Returns number of sessions pruned. */
+  prune(policy) {
+    return pruneSessionDirs(this.sessionsDir, policy);
+  }
+  // ── Lifecycle ───────────────────────────────────────────────────
+  /** Flush all event logs synchronously (call on shutdown). */
+  flushAll() {
+    for (const log of this.eventLogs.values()) {
+      log.flushSync();
+    }
+  }
+  /** Destroy a single session's event log. */
+  destroySessionLog(sessionId) {
+    const log = this.eventLogs.get(sessionId);
+    if (log) {
+      log.destroy();
+      this.eventLogs.delete(sessionId);
+    }
+  }
+  /** Clean up: flush all logs, release lock. */
+  destroy() {
+    for (const log of this.eventLogs.values()) {
+      log.destroy();
+    }
+    this.eventLogs.clear();
+    this.releaseLockIfHeld();
+  }
+  /** Check if a session directory exists on disk. */
+  hasSessionOnDisk(sessionId) {
+    return existsSync7(join5(this.sessionsDir, sessionId, "meta.json"));
+  }
+};
+
+// src/session/orphan-reaper.ts
+import { execSync, spawn as spawn4 } from "child_process";
+import { readFileSync as readFileSync5 } from "fs";
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getWindowsCreationTimeMs(pid) {
+  try {
+    const raw = execSync(`wmic process where "ProcessId=${pid}" get CreationDate /value`, {
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5e3
+    }).toString();
+    const match = raw.match(/CreationDate=(\d{14})/);
+    if (!match || !match[1]) return null;
+    const s = match[1];
+    const iso = `${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6, 8)}T${s.slice(8, 10)}:${s.slice(10, 12)}:${s.slice(12, 14)}.000Z`;
+    const ms = new Date(iso).getTime();
+    return isNaN(ms) ? null : ms;
+  } catch {
+    return null;
+  }
+}
+function getProcStatStartTick(pid) {
+  try {
+    const stat = readFileSync5(`/proc/${pid}/stat`, "utf-8");
+    const afterComm = stat.slice(stat.lastIndexOf(")") + 1).trim();
+    const fields = afterComm.split(" ");
+    const starttime = fields[19];
+    return starttime ?? null;
+  } catch {
+    return null;
+  }
+}
+function getPsLstart(pid) {
+  try {
+    const output = execSync(`ps -p ${pid} -o lstart=`, {
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5e3
+    }).toString().trim();
+    if (!output) return null;
+    const ms = new Date(output).getTime();
+    return isNaN(ms) ? null : ms;
+  } catch {
+    return null;
+  }
+}
+function isOrphan(pid, spawnedAt) {
+  const storedMs = new Date(spawnedAt).getTime();
+  if (isNaN(storedMs)) return false;
+  if (process.platform === "win32") {
+    const procMs = getWindowsCreationTimeMs(pid);
+    if (procMs === null) return false;
+    return Math.abs(procMs - storedMs) < 5e3;
+  }
+  const lstartMs = getPsLstart(pid);
+  if (lstartMs !== null) {
+    return Math.abs(lstartMs - storedMs) < 5e3;
+  }
+  const tick = getProcStatStartTick(pid);
+  if (tick !== null) {
+    const ageMs = Date.now() - storedMs;
+    return ageMs > 0 && ageMs < 24 * 60 * 60 * 1e3;
+  }
+  return false;
+}
+function sendGraceful(pid) {
+  try {
+    if (process.platform === "win32") {
+      spawn4("taskkill", ["/PID", String(pid)], {
+        stdio: "ignore",
+        windowsHide: true
+      });
+    } else {
+      process.kill(pid, "SIGTERM");
+    }
+  } catch {
+  }
+}
+function sendForce(pid) {
+  try {
+    if (process.platform === "win32") {
+      spawn4("taskkill", ["/PID", String(pid), "/F"], {
+        stdio: "ignore",
+        windowsHide: true
+      });
+    } else {
+      process.kill(pid, "SIGKILL");
+    }
+  } catch {
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (t.unref) t.unref();
+  });
+}
+async function reapOrphanProcesses(recovered) {
+  const summary = { reaped: 0, alreadyDead: 0, skipped: 0 };
+  const candidates = recovered.filter((s) => s.pidInfo !== null);
+  if (candidates.length === 0) return summary;
+  const reapPromises = candidates.map(async (session) => {
+    const { pid, spawnedAt } = session.pidInfo;
+    if (!isAlive(pid)) {
+      summary.alreadyDead++;
+      return;
+    }
+    if (!isOrphan(pid, spawnedAt)) {
+      console.error(
+        `[orphan-reaper] PID ${pid} (session ${session.sessionId}) is alive but does not match stored spawn time \u2014 likely a reused PID. Skipping.`
+      );
+      summary.skipped++;
+      return;
+    }
+    if (!isAlive(pid) || !isOrphan(pid, spawnedAt)) {
+      summary.skipped++;
+      return;
+    }
+    console.error(
+      `[orphan-reaper] Sending graceful terminate to orphan PID ${pid} (session ${session.sessionId}).`
+    );
+    sendGraceful(pid);
+    const deadline = Date.now() + 5e3;
+    while (isAlive(pid) && Date.now() < deadline) {
+      await sleep(250);
+    }
+    if (isAlive(pid)) {
+      console.error(
+        `[orphan-reaper] PID ${pid} did not exit after graceful terminate \u2014 force killing.`
+      );
+      sendForce(pid);
+      await sleep(500);
+    }
+    summary.reaped++;
+  });
+  await Promise.all(reapPromises);
+  return summary;
+}
+
+// src/utils/stdin-shutdown.ts
+function decideStdinShutdown(params) {
+  if (!params.stdinUnavailable) return "clear";
+  if (params.isConnected) return "reschedule";
+  if (!params.hasActiveSessions) return "shutdown_now";
+  if (params.elapsedMs >= params.maxWaitMs) return "shutdown_timeout";
+  return "reschedule";
+}
+
 // src/index.ts
+var STDIN_SHUTDOWN_CHECK_MS = 750;
+var STDIN_SHUTDOWN_MAX_WAIT_MS = process.platform === "win32" ? 15e3 : 1e4;
 async function main() {
   const preflight = runStdioPreflight();
   for (const note of preflight.notes) {
@@ -4323,27 +5654,177 @@ async function main() {
   const clientMode = await detectClientMode(executable.command, executable.isPath);
   console.error(`[codex-mcp] client mode: ${clientMode} (binary: ${executable.command})`);
   const createClient = () => clientMode === "exec" ? new ExecClient() : new AppServerClient();
+  const persistence = new SessionPersistence();
+  try {
+    persistence.acquireLock();
+    console.error("[codex-mcp] STATE_DIR lock acquired");
+  } catch (err) {
+    console.error("[codex-mcp] WARNING: Failed to acquire STATE_DIR lock:", err);
+  }
+  const recovered = persistence.recoverSessions();
+  if (recovered.length > 0) {
+    console.error(`[codex-mcp] Recovered ${recovered.length} session(s) from disk`);
+  }
+  const pruned = persistence.prune();
+  if (pruned > 0) {
+    console.error(`[codex-mcp] Pruned ${pruned} old session(s)`);
+  }
+  const reaped = await reapOrphanProcesses(recovered);
+  if (reaped.reaped > 0) console.error(`[codex-mcp] Reaped ${reaped.reaped} orphan process(es)`);
   const serverCwd = process.cwd();
-  const server = createServer(serverCwd, {
+  const ctx = createServer(serverCwd, {
     createClient,
-    clientMode
+    clientMode,
+    persistence
   });
+  const server = ctx.server;
+  const sessionManager = ctx.sessionManager;
+  if (recovered.length > 0) {
+    sessionManager.ingestRecovered(recovered);
+  }
   const transport = new StdioServerTransport();
   let closing = false;
-  const shutdown = async () => {
+  let lastExitCode = 0;
+  let stdinClosedAt;
+  let stdinClosedReason;
+  let stdinShutdownTimer;
+  const onStdinEnd = () => handleStdinTerminated("end");
+  const onStdinClose = () => handleStdinTerminated("close");
+  const clearStdinShutdownTimer = () => {
+    if (stdinShutdownTimer) {
+      clearTimeout(stdinShutdownTimer);
+      stdinShutdownTimer = void 0;
+    }
+  };
+  function hasActiveSessions() {
+    return sessionManager.listSessions().some((s) => s.status === "running" || s.status === "waiting_approval");
+  }
+  const shutdown = async (reason = "unknown") => {
     if (closing) return;
     closing = true;
+    clearStdinShutdownTimer();
+    if (typeof process.stdin.off === "function") {
+      process.stdin.off("error", handleStdinError);
+      process.stdin.off("end", onStdinEnd);
+      process.stdin.off("close", onStdinClose);
+    }
+    const forceExitMs = process.platform === "win32" ? 1e4 : 5e3;
+    const forceExitTimer = setTimeout(() => process.exit(lastExitCode), forceExitMs);
+    if (forceExitTimer.unref) forceExitTimer.unref();
+    const activeSessions = sessionManager.listSessions();
+    const runningCount = activeSessions.filter(
+      (s) => s.status === "running" || s.status === "waiting_approval"
+    ).length;
+    console.error(
+      `[codex-mcp] shutdown triggered (reason=${reason}, activeSessions=${runningCount}, total=${activeSessions.length})`
+    );
+    try {
+      if (server.isConnected()) {
+        await server.sendLoggingMessage({
+          level: "info",
+          data: {
+            event: "server_stopping",
+            reason,
+            activeSessions: runningCount,
+            totalSessions: activeSessions.length
+          }
+        });
+      }
+    } catch {
+    }
+    try {
+      persistence.flushAll();
+      persistence.releaseLockIfHeld();
+    } catch {
+    }
     try {
       await server.close();
     } catch {
     }
-    process.exitCode = 0;
-    const exitTimer = setTimeout(() => process.exit(0), 100);
-    exitTimer.unref();
+    persistence.destroy();
+    process.exitCode = lastExitCode;
+    try {
+      await new Promise((resolve) => process.stderr.write("", () => resolve()));
+    } catch {
+    } finally {
+      clearTimeout(forceExitTimer);
+    }
+  };
+  function handleStdinError(error) {
+    console.error("[codex-mcp] stdin error:", error);
+    lastExitCode = 1;
+    void shutdown("stdin_error");
+  }
+  const evaluateStdinTermination = () => {
+    if (closing || stdinClosedAt === void 0) return;
+    const stdinUnavailable = process.stdin.destroyed || process.stdin.readableEnded || !process.stdin.readable;
+    const elapsedMs = Date.now() - stdinClosedAt;
+    const active = hasActiveSessions();
+    const connected = server.isConnected();
+    const decision = decideStdinShutdown({
+      stdinUnavailable,
+      elapsedMs,
+      maxWaitMs: STDIN_SHUTDOWN_MAX_WAIT_MS,
+      hasActiveSessions: active,
+      isConnected: connected
+    });
+    if (decision === "clear") {
+      stdinClosedAt = void 0;
+      stdinClosedReason = void 0;
+      return;
+    }
+    if (decision === "shutdown_now") {
+      console.error("[codex-mcp] stdin closed with no active sessions \u2014 shutting down");
+      void shutdown(`stdin_${stdinClosedReason ?? "closed"}`);
+      return;
+    }
+    if (decision === "shutdown_timeout") {
+      console.error(
+        `[codex-mcp] stdin closed and drain period (${STDIN_SHUTDOWN_MAX_WAIT_MS}ms) elapsed \u2014 forcing shutdown`
+      );
+      void shutdown(`stdin_${stdinClosedReason ?? "closed"}_timeout`);
+      return;
+    }
+    if (active) {
+      console.error(
+        `[codex-mcp] stdin closed; ${sessionManager.getActiveSessionCount()} active session(s) \u2014 waiting up to ${STDIN_SHUTDOWN_MAX_WAIT_MS}ms (elapsed: ${elapsedMs}ms)`
+      );
+    }
+    stdinShutdownTimer = setTimeout(evaluateStdinTermination, STDIN_SHUTDOWN_CHECK_MS);
+    if (stdinShutdownTimer.unref) stdinShutdownTimer.unref();
   };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-  process.on("SIGBREAK", shutdown);
+  function handleStdinTerminated(event) {
+    if (closing) return;
+    if (stdinClosedAt === void 0) {
+      stdinClosedAt = Date.now();
+      stdinClosedReason = event;
+      console.error(`[codex-mcp] stdin ${event} observed \u2014 entering guarded shutdown checks`);
+    }
+    clearStdinShutdownTimer();
+    stdinShutdownTimer = setTimeout(evaluateStdinTermination, STDIN_SHUTDOWN_CHECK_MS);
+    if (stdinShutdownTimer.unref) stdinShutdownTimer.unref();
+  }
+  const handleUnexpectedError = (error) => {
+    console.error("[codex-mcp] Unhandled runtime error:", error);
+    lastExitCode = 1;
+    void shutdown("runtime_error");
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  process.on("SIGBREAK", () => void shutdown("SIGBREAK"));
+  process.on("beforeExit", () => {
+    if (!server.isConnected()) {
+      void shutdown("beforeExit");
+    }
+  });
+  process.on("uncaughtException", handleUnexpectedError);
+  process.on("unhandledRejection", handleUnexpectedError);
+  if (typeof process.stdin.resume === "function") {
+    process.stdin.resume();
+  }
+  process.stdin.on("error", handleStdinError);
+  process.stdin.on("end", onStdinEnd);
+  process.stdin.on("close", onStdinClose);
   await server.connect(transport);
   console.error(`codex-mcp server started (cwd: ${serverCwd})`);
 }