Harden Claude Codex session reliability

Add progress heartbeats for long blocking MCP calls, preserve persistent session project directories across follow-up prompts, and make the Claude live harnesses deterministic with explicit plugin loading.

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

Author: xuio

.gitignore

@@ -5,3 +5,4 @@ node_modules/
 coverage/
 .vitest/
 tmp/
+.in_use/

README.md

@@ -33,6 +33,7 @@ Optional environment overrides:
 - `CODEX_SUBAGENTS_JOB_TTL_SECONDS`: completed async job retention window. Defaults to one hour.
 - `CODEX_SUBAGENTS_LOG_LEVEL`: `debug`, `info`, `warn`, `error`, or `silent`. Defaults to `debug`.
 - `CODEX_SUBAGENTS_LOG_MAX_STRING_CHARS`: maximum string payload retained per log field before truncation metadata is used. Defaults to `20000`.
+- `CODEX_SUBAGENTS_PROGRESS_HEARTBEAT_MS`: interval for progress heartbeats on blocking tool calls. Defaults to `10000`.
 
 ## Spark And Nested Subagents
 
@@ -130,7 +131,9 @@ npm run test:claude-desktop
 
 `test:claude-real-codex` is the full opt-in live path: Claude Code loads the plugin and calls real Codex through the desktop app binary, including one single agent, one parallel run, and one nested Spark subagent run. It spends both Claude and Codex tokens, so it is intentionally not part of the default suite.
 
-`test:claude-autodiscovery` is an opt-in live Claude Code test for automatic tool selection. It gives Claude a natural "ask Codex" request, uses the installed plugin and fake Codex binary, and verifies that Claude chooses the Codex MCP tool without being told the exact tool name.
+`test:claude-real-session` is an opt-in live Claude Code test for daemonless persistent sessions. It loads the symlinked installed plugin, starts a real Codex session, sends a follow-up without `project_dir`, and verifies the session stays pinned to the original project directory.
+
+`test:claude-autodiscovery` is an opt-in live Claude Code test for automatic tool selection. It gives Claude a natural "ask Codex" request, loads the local plugin with the fake Codex binary, and verifies that Claude chooses the Codex MCP tool without being told the exact tool name.
 
 Run Claude Code with the local plugin:
 
@@ -172,7 +175,7 @@ Prefer `start_agent_run` or `start_agents_run` for work that may run longer than
 
 Async job snapshots expose partial stdout/stderr and parsed event summaries through `get_agent_run` while work is still running.
 
-When a client supports MCP progress tokens, `run_agent`, `run_agents`, `start_agent_run`, `start_agents_run`, `get_agent_run`, `wait_agent_run`, and `cancel_agent_run` send progress notifications. SDK clients should pass an `onprogress` handler and enable timeout reset on progress for long waits.
+When a client supports MCP progress tokens, `run_agent`, `run_agents`, `run_agents_aggregate`, `start_session`, `send_session_prompt`, `start_agent_run`, `start_agents_run`, `get_agent_run`, `wait_agent_run`, and `cancel_agent_run` send progress notifications. SDK clients should pass an `onprogress` handler and enable timeout reset on progress for long waits.
 
 ## License
 

dist/index.js

@@ -22930,6 +22930,11 @@ function isParallelResult(value) {
 }
 
 // src/sessions.ts
+function withoutUndefined(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, child]) => child !== void 0)
+  );
+}
 function snapshot2(session) {
   return {
     id: session.id,
@@ -23006,7 +23011,7 @@ var CodexSessionManager = class {
     });
     const result = await this.runTurn(session, {
       ...session.baseOptions,
-      ...overrides,
+      ...withoutUndefined(overrides),
       prompt,
       resumeSessionId: session.codexThreadId,
       ephemeral: false
@@ -23064,6 +23069,12 @@ var CodexSessionManager = class {
       session.lastResult = result;
       session.codexThreadId = result.eventSummary.threadId ?? session.codexThreadId;
       session.projectDir = result.cwd;
+      session.cwd = result.cwd;
+      session.baseOptions = {
+        ...session.baseOptions,
+        projectDir: result.cwd,
+        cwd: void 0
+      };
       session.status = result.ok ? "active" : result.status === "cancelled" ? "cancelled" : "failed";
       session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
       logger.rawInfo("session.turn.finish", {
@@ -23347,6 +23358,22 @@ async function reportAgentResult(progress, result) {
   const status = result.status ?? (result.ok ? "completed" : "failed");
   await progress.send(result.ok ? "Codex run completed" : `Codex run ${status}`);
 }
+function progressHeartbeatMs() {
+  const parsed = Number(process.env.CODEX_SUBAGENTS_PROGRESS_HEARTBEAT_MS);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 1e4;
+  return Math.max(25, Math.min(Math.floor(parsed), 6e4));
+}
+async function withProgressHeartbeat(progress, message, operation) {
+  const interval = setInterval(() => {
+    void progress.send(message);
+  }, progressHeartbeatMs());
+  interval.unref();
+  try {
+    return await operation();
+  } finally {
+    clearInterval(interval);
+  }
+}
 function toRunOptions(args) {
   return {
     prompt: args.prompt,
@@ -23505,11 +23532,15 @@ server.registerTool(
       const progress = createProgressReporter(extra);
       try {
         await progress.send("Queued Codex run");
-        const result = await runQueuedAgent(toRunOptions(args), {
-          onStart: (queuedMs) => {
-            void progress.send(`Started Codex run after ${queuedMs}ms queued`);
-          }
-        });
+        const result = await withProgressHeartbeat(
+          progress,
+          "Still running Codex run",
+          () => runQueuedAgent(toRunOptions(args), {
+            onStart: (queuedMs) => {
+              void progress.send(`Started Codex run after ${queuedMs}ms queued`);
+            }
+          })
+        );
         await reportAgentResult(progress, result);
         await progress.flush();
         return jsonResult({ agent: compactAgentResultForMcp(result) }, !result.ok);
@@ -23611,18 +23642,22 @@ server.registerTool(
         let completed = 0;
         let failed = 0;
         await progress.send(`Queued ${args.agents.length} Codex agents`, { total });
-        const results = await runQueuedAgents(toParallelRunOptions(args), {
-          onStart: (queuedMs, label) => {
-            void progress.send(`Started ${label ?? "Codex agent"} after ${queuedMs}ms queued`, { total });
-          },
-          onComplete: async (result) => {
-            completed += 1;
-            if (!result.ok) failed += 1;
-            const last = completed === args.agents.length;
-            const message = last ? failed === 0 ? `Parallel Codex run completed (${completed}/${args.agents.length})` : `Parallel Codex run finished with errors (${completed}/${args.agents.length})` : `${result.ok ? "Completed" : "Finished"} ${result.name ?? "Codex agent"} (${completed}/${args.agents.length})`;
-            await progress.send(message, last ? { progress: total, total } : { total });
-          }
-        });
+        const results = await withProgressHeartbeat(
+          progress,
+          `Still running ${args.agents.length} Codex agents`,
+          () => runQueuedAgents(toParallelRunOptions(args), {
+            onStart: (queuedMs, label) => {
+              void progress.send(`Started ${label ?? "Codex agent"} after ${queuedMs}ms queued`, { total });
+            },
+            onComplete: async (result) => {
+              completed += 1;
+              if (!result.ok) failed += 1;
+              const last = completed === args.agents.length;
+              const message = last ? failed === 0 ? `Parallel Codex run completed (${completed}/${args.agents.length})` : `Parallel Codex run finished with errors (${completed}/${args.agents.length})` : `${result.ok ? "Completed" : "Finished"} ${result.name ?? "Codex agent"} (${completed}/${args.agents.length})`;
+              await progress.send(message, last ? { progress: total, total } : { total });
+            }
+          })
+        );
         const ok = results.every((result) => result.ok);
         await progress.flush();
         return jsonResult(
@@ -23663,19 +23698,23 @@ server.registerTool(
         const total = args.agents.length * 2 + 1;
         let completed = 0;
         await progress.send(`Queued ${args.agents.length} Codex agents for aggregation`, { total });
-        const results = await runQueuedAgents(toParallelRunOptions(args), {
-          onStart: (queuedMs, label) => {
-            void progress.send(`Started ${label ?? "Codex agent"} after ${queuedMs}ms queued`, { total });
-          },
-          onComplete: async () => {
-            completed += 1;
-            const last = completed === args.agents.length;
-            await progress.send(
-              last ? `Aggregating ${completed}/${args.agents.length} Codex results` : `Completed ${completed}/${args.agents.length} Codex agents`,
-              last ? { progress: total, total } : { total }
-            );
-          }
-        });
+        const results = await withProgressHeartbeat(
+          progress,
+          `Still running ${args.agents.length} Codex agents for aggregation`,
+          () => runQueuedAgents(toParallelRunOptions(args), {
+            onStart: (queuedMs, label) => {
+              void progress.send(`Started ${label ?? "Codex agent"} after ${queuedMs}ms queued`, { total });
+            },
+            onComplete: async () => {
+              completed += 1;
+              const last = completed === args.agents.length;
+              await progress.send(
+                last ? `Aggregating ${completed}/${args.agents.length} Codex results` : `Completed ${completed}/${args.agents.length} Codex agents`,
+                last ? { progress: total, total } : { total }
+              );
+            }
+          })
+        );
         const aggregation = aggregateAgentResults(results);
         await progress.flush();
         return jsonResult(
@@ -23820,12 +23859,16 @@ server.registerTool(
       const progress = createProgressReporter(extra);
       try {
         await progress.send("Starting persistent Codex session");
-        const { session, result } = await sessionManager.start(
-          {
-            ...toRunOptions(args),
-            ephemeral: false
-          },
-          { sessionName: args.session_name }
+        const { session, result } = await withProgressHeartbeat(
+          progress,
+          "Still starting persistent Codex session",
+          () => sessionManager.start(
+            {
+              ...toRunOptions(args),
+              ephemeral: false
+            },
+            { sessionName: args.session_name }
+          )
         );
         await reportAgentResult(progress, result);
         await progress.flush();
@@ -23857,7 +23900,11 @@ server.registerTool(
       const progress = createProgressReporter(extra);
       try {
         await progress.send(`Resuming Codex session ${args.session_id}`);
-        const { session, result, error: error2 } = await sessionManager.send(args.session_id, args.prompt, toRunOptions(args));
+        const { session, result, error: error2 } = await withProgressHeartbeat(
+          progress,
+          `Still running Codex session ${args.session_id}`,
+          () => sessionManager.send(args.session_id, args.prompt, toRunOptions(args))
+        );
         if (error2 || !session || !result) {
           await progress.flush();
           return jsonResult(

package.json

@@ -34,6 +34,7 @@
     "test:claude-autodiscovery": "node test/claude-autodiscovery.mjs",
     "test:claude-large-output": "node test/claude-large-output.mjs",
     "test:claude-real-codex": "node test/claude-real-codex.mjs",
+    "test:claude-real-session": "node test/claude-real-session.mjs",
     "test:ci": "npm run build && npm test && npm run smoke:mcp && npm run test:reliability && npm run test:stress && npm run test:progress && npm run test:advanced && npm run test:dev-link",
     "test:comprehensive": "npm run build && npm test && npm run smoke:mcp && npm run test:reliability && npm run test:stress && npm run test:progress && npm run test:advanced && npm run test:codex-runtime && npm run validate:plugin && npm run test:claude-desktop",
     "test:claude-desktop": "node test/claude-desktop-cli.mjs"

scripts/link-claude-dev-plugin.mjs

@@ -1,4 +1,4 @@
-import { lstat, mkdir, readFile, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, rename, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -91,9 +91,6 @@ const marketplaceLink = await replaceWithSymlink(marketplacePluginPath, root);
 const cacheLink = await replaceWithSymlink(installPath, root);
 const entry = await ensureInstalledPluginsEntry();
 
-// Remove stale Claude marker files that can be left behind when replacing cache copies.
-await rm(path.join(installPath, ".in_use"), { force: true });
-
 console.log(`Marketplace plugin path: ${marketplaceLink.path} -> ${root}`);
 console.log(`Installed plugin path: ${cacheLink.path} -> ${root}`);
 console.log(`Installed plugin entry: ${entry.installPath}`);