Archive closed Codex desktop threads

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

Author: xuio

README.md

@@ -123,7 +123,10 @@ turns, Claude should set `background: true`.
 When app-server sessions use the Codex desktop binary, they are recorded as
 normal top-level Codex threads rather than hidden daemon work. The plugin sets the
 thread name from Claude's task label when the installed Codex app-server supports
-thread naming.
+thread naming. When Claude explicitly cancels a session, or when retention
+pruning removes an old session, the plugin best-effort archives the matching
+Codex Desktop thread before closing the app-server child. It does not hard-delete
+threads, and recoverable sessions are not archived during normal MCP shutdown.
 
 ## Safety Model
 

dist/index.js

@@ -24375,6 +24375,26 @@ var CodexAppServerSession = class _CodexAppServerSession {
       });
     }
   }
+  async archiveThread(timeoutMs = 2e3) {
+    if (!this.threadId) return false;
+    try {
+      await this.request("thread/archive", { threadId: this.threadId }, timeoutMs);
+      logger.info("codex.app_server.thread_archived", {
+        ...this.logContext,
+        appServerId: this.id,
+        threadId: this.threadId
+      });
+      return true;
+    } catch (error2) {
+      logger.warn("codex.app_server.thread_archive_failed", {
+        ...this.logContext,
+        appServerId: this.id,
+        threadId: this.threadId,
+        error: errorForLog(error2)
+      });
+      return false;
+    }
+  }
   get activeTurnId() {
     return this.activeTurn?.turnId;
   }
@@ -25678,12 +25698,11 @@ var CodexSessionManager = class {
     if (session.controller) {
       session.status = "cancelled";
       session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-      void session.appServer?.close("cancelled");
       session.controller.abort();
     } else {
       session.status = "cancelled";
       session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-      void session.appServer?.close("cancelled");
+      this.closeAppServer(session, "cancelled", "cancel");
     }
     this.appendMilestones(session, [
       {
@@ -25968,6 +25987,9 @@ var CodexSessionManager = class {
       this.notifyTurn(turn);
       this.notifySession(session);
       this.persist();
+      if (controller.signal.aborted && !session.runtimeShutdownRecoverable) {
+        this.closeAppServer(session, "cancelled", "cancel");
+      }
       throw error2;
     } finally {
       session.controller = void 0;
@@ -26096,7 +26118,7 @@ var CodexSessionManager = class {
       turn: summarizeRawTrafficForLog(turnSnapshot(turn)),
       result: summarizeRawTrafficForLog(result)
     });
-    if (session.cancelRequested && session.appServer) void session.appServer.close("cancelled");
+    if (session.cancelRequested && session.appServer) this.closeAppServer(session, "cancelled", "cancel");
     this.notifyTurn(turn);
     this.notifySession(session);
     this.persist();
@@ -26273,12 +26295,28 @@ var CodexSessionManager = class {
     this.sessions.delete(id);
     if (session.resourceNotifyTimer) clearTimeout(session.resourceNotifyTimer);
     if (session.resourceNotifyMaxTimer) clearTimeout(session.resourceNotifyMaxTimer);
-    void session.appServer?.close("cancelled").catch(() => {
-    });
+    this.closeAppServer(session, "cancelled", `prune_${reason}`);
     this.notifySession(session);
     this.emitSessionChanged(id);
     this.persist();
   }
+  closeAppServer(session, status, archiveReason) {
+    const appServer = session.appServer;
+    if (!appServer) return;
+    const close = () => appServer.close(status).catch(() => {
+    });
+    if (appServer.status().closed) return;
+    if (!archiveReason || session.protocol !== "app-server" || !session.codexThreadId) {
+      void close();
+      return;
+    }
+    logger.info("session.archive_app_server_thread", {
+      sessionId: session.id,
+      threadId: session.codexThreadId,
+      reason: archiveReason
+    });
+    void appServer.archiveThread().finally(close);
+  }
   loadPersistedSessions() {
     const store = this.stateStore;
     if (!store) return;
@@ -26400,7 +26438,7 @@ var usageGuide = [
   "- Approvals are non-interactive; do not expect Codex to ask permission.",
   '- If codex_followup mode wait returns completed false with timeoutReason "wait_timeout", the session is still running unless its status says otherwise.',
   "- Use codex_wait_any after launching several background Codex tasks to harvest whichever one finishes first without busy-polling.",
-  "- Use codex_followup mode cancel to stop a background or actively running Codex session early. The response includes whatever partial output streamed before the interrupt.",
+  "- Use codex_followup mode cancel to stop a background or actively running Codex session early. The response includes whatever partial output streamed before the interrupt, and the matching Codex Desktop thread is archived best-effort when supported.",
   '- If a tool returns error.kind "backpressure", reduce max_parallel or wait before retrying. codex://status exposes current queue/session limits.',
   "- If a response mentions outputArtifacts, use the artifact paths for full retained output instead of asking Codex to resend huge stdout/stderr.",
   '- Do not use model_preset "spark" by default. Use Spark only when the user asks for Spark or when a quick focused sidecar check is clearly more appropriate than the default Codex model.',
@@ -28177,8 +28215,9 @@ registerTool(
           const activeTurn = sessionBefore.activeTurn;
           const lastResult = sessionBefore.lastResult;
           if (!wasActive && sessionBefore.queuedTurns.length === 0 && lastResult?.status === "completed") {
+            const cancelled2 = sessionManager.cancel(args.session_id, args.reason ?? "closed after completion");
             await progress.flush();
-            const compactSession3 = compactSessionSnapshotForMcp(sessionBefore);
+            const compactSession3 = compactSessionSnapshotForMcp(cancelled2 ?? sessionBefore);
             const compactResult = compactAgentResultForMcp(lastResult);
             const resultValue = compactResult.structuredOutput ?? compactResult.finalMessage;
             const resultText = stringifyResultValue(resultValue, compactResult.finalMessage);

docs/ARCHITECTURE.md

@@ -33,7 +33,10 @@ MCP server, there is no background daemon left behind.
 App-server threads are started as normal top-level Codex threads, not as nested
 Codex subagent threads. When the Codex app-server supports `thread/name/set`, the
 plugin best-effort names the thread from Claude's task label so the run is easy
-to find in Codex Desktop history.
+to find in Codex Desktop history. When the app-server supports `thread/archive`,
+explicit session cancellation and retention pruning best-effort archive the
+Desktop thread before the child process is closed. Archive failures are logged and
+do not block cancellation.
 
 ## Binary Resolution
 
@@ -96,7 +99,9 @@ When limits are exceeded, tools return structured recovery hints instead of
 accepting unbounded work.
 
 Completed jobs, idle sessions, and terminal sessions are pruned according to the
-configured retention windows.
+configured retention windows. Pruning an app-server-backed session also
+best-effort archives the Codex Desktop thread. Normal MCP runtime shutdown keeps
+recoverable sessions unarchived so Claude can reattach with the same `session_id`.
 
 ## Logging And Diagnostics
 

docs/USAGE.md

@@ -74,6 +74,10 @@ Use this decision path when writing prompts or debugging Claude tool choice:
 | Wait for a background session | `codex_followup` with `mode: "wait"` |
 | Stop a background or running session | `codex_followup` with `mode: "cancel"` |
 
+`mode: "cancel"` also closes the associated app-server session. If Codex Desktop
+supports thread archiving, the plugin best-effort archives that Desktop thread so
+stopped Claude subagent work does not keep cluttering the active thread list.
+
 When in doubt, read `codex://usage` and then choose among the native front-door tools.
 
 ## When To Prefer Codex

src/app-server.ts

@@ -33,6 +33,7 @@ type AppServerRequestMethod =
   | "thread/start"
   | "thread/resume"
   | "thread/name/set"
+  | "thread/archive"
   | "turn/start"
   | "turn/steer"
   | "turn/interrupt"
@@ -396,6 +397,27 @@ export class CodexAppServerSession {
     }
   }
 
+  async archiveThread(timeoutMs = 2_000): Promise<boolean> {
+    if (!this.threadId) return false;
+    try {
+      await this.request("thread/archive", { threadId: this.threadId }, timeoutMs);
+      logger.info("codex.app_server.thread_archived", {
+        ...this.logContext,
+        appServerId: this.id,
+        threadId: this.threadId,
+      });
+      return true;
+    } catch (error) {
+      logger.warn("codex.app_server.thread_archive_failed", {
+        ...this.logContext,
+        appServerId: this.id,
+        threadId: this.threadId,
+        error: errorForLog(error),
+      });
+      return false;
+    }
+  }
+
   get activeTurnId(): string | undefined {
     return this.activeTurn?.turnId;
   }

src/index.ts

@@ -87,7 +87,7 @@ const usageGuide = [
   "- Approvals are non-interactive; do not expect Codex to ask permission.",
   "- If codex_followup mode wait returns completed false with timeoutReason \"wait_timeout\", the session is still running unless its status says otherwise.",
   "- Use codex_wait_any after launching several background Codex tasks to harvest whichever one finishes first without busy-polling.",
-  "- Use codex_followup mode cancel to stop a background or actively running Codex session early. The response includes whatever partial output streamed before the interrupt.",
+  "- Use codex_followup mode cancel to stop a background or actively running Codex session early. The response includes whatever partial output streamed before the interrupt, and the matching Codex Desktop thread is archived best-effort when supported.",
   "- If a tool returns error.kind \"backpressure\", reduce max_parallel or wait before retrying. codex://status exposes current queue/session limits.",
   "- If a response mentions outputArtifacts, use the artifact paths for full retained output instead of asking Codex to resend huge stdout/stderr.",
   "- Do not use model_preset \"spark\" by default. Use Spark only when the user asks for Spark or when a quick focused sidecar check is clearly more appropriate than the default Codex model.",
@@ -2619,8 +2619,9 @@ registerTool(
           const activeTurn = sessionBefore.activeTurn;
           const lastResult = sessionBefore.lastResult;
           if (!wasActive && sessionBefore.queuedTurns.length === 0 && lastResult?.status === "completed") {
+            const cancelled = sessionManager.cancel(args.session_id, args.reason ?? "closed after completion");
             await progress.flush();
-            const compactSession = compactSessionSnapshotForMcp(sessionBefore);
+            const compactSession = compactSessionSnapshotForMcp(cancelled ?? sessionBefore);
             const compactResult = compactAgentResultForMcp(lastResult);
             const resultValue = compactResult.structuredOutput ?? compactResult.finalMessage;
             const resultText = stringifyResultValue(resultValue, compactResult.finalMessage);

src/sessions.ts

@@ -880,12 +880,11 @@ export class CodexSessionManager {
     if (session.controller) {
       session.status = "cancelled";
       session.updatedAt = new Date().toISOString();
-      void session.appServer?.close("cancelled");
       session.controller.abort();
     } else {
       session.status = "cancelled";
       session.updatedAt = new Date().toISOString();
-      void session.appServer?.close("cancelled");
+      this.closeAppServer(session, "cancelled", "cancel");
     }
     this.appendMilestones(session, [
       {
@@ -1195,6 +1194,9 @@ export class CodexSessionManager {
       this.notifyTurn(turn);
       this.notifySession(session);
       this.persist();
+      if (controller.signal.aborted && !session.runtimeShutdownRecoverable) {
+        this.closeAppServer(session, "cancelled", "cancel");
+      }
       throw error;
     } finally {
       session.controller = undefined;
@@ -1355,7 +1357,7 @@ export class CodexSessionManager {
       turn: summarizeRawTrafficForLog(turnSnapshot(turn)),
       result: summarizeRawTrafficForLog(result),
     });
-    if (session.cancelRequested && session.appServer) void session.appServer.close("cancelled");
+    if (session.cancelRequested && session.appServer) this.closeAppServer(session, "cancelled", "cancel");
     this.notifyTurn(turn);
     this.notifySession(session);
     this.persist();
@@ -1570,12 +1572,33 @@ export class CodexSessionManager {
     this.sessions.delete(id);
     if (session.resourceNotifyTimer) clearTimeout(session.resourceNotifyTimer);
     if (session.resourceNotifyMaxTimer) clearTimeout(session.resourceNotifyMaxTimer);
-    void session.appServer?.close("cancelled").catch(() => {});
+    this.closeAppServer(session, "cancelled", `prune_${reason}`);
     this.notifySession(session);
     this.emitSessionChanged(id);
     this.persist();
   }
 
+  private closeAppServer(
+    session: CodexSessionRecord,
+    status: "failed" | "cancelled",
+    archiveReason?: string,
+  ): void {
+    const appServer = session.appServer;
+    if (!appServer) return;
+    const close = () => appServer.close(status).catch(() => {});
+    if (appServer.status().closed) return;
+    if (!archiveReason || session.protocol !== "app-server" || !session.codexThreadId) {
+      void close();
+      return;
+    }
+    logger.info("session.archive_app_server_thread", {
+      sessionId: session.id,
+      threadId: session.codexThreadId,
+      reason: archiveReason,
+    });
+    void appServer.archiveThread().finally(close);
+  }
+
   private loadPersistedSessions(): void {
     const store = this.stateStore;
     if (!store) return;

test/app-server-hardening.test.ts

@@ -269,16 +269,50 @@ describe("app-server hardening", () => {
 
     const becameActive = await waitFor(() => Boolean(manager.get(session.id)?.appServer?.activeTurnId));
     expect(becameActive).toBe(true);
+    const codexThreadId = manager.get(session.id)?.codexThreadId;
+    expect(codexThreadId).toBeTruthy();
     const cancelled = manager.cancel(session.id);
     expect(cancelled?.status).toBe("cancelled");
 
-    const sawSigterm = await waitFor(async () => {
-      const calls = await recordedCalls(recordDir);
-      return calls.some((call) => call.method === "process/sigterm");
+    let finalCalls: Array<Record<string, unknown>> = [];
+    const sawCleanup = await waitFor(async () => {
+      finalCalls = await recordedCalls(recordDir);
+      return (
+        finalCalls.some((call) => call.method === "turn/interrupt") &&
+        finalCalls.some((call) => call.method === "thread/archive") &&
+        finalCalls.some((call) => call.method === "process/sigterm")
+      );
     }, 10_000);
-    expect(sawSigterm).toBe(true);
+    expect(sawCleanup).toBe(true);
+    expect(finalCalls.some((call) => call.method === "thread/archive" && call.threadId === codexThreadId)).toBe(true);
   }, 15_000);
 
+  it("still closes app-server sessions when desktop thread archiving is unsupported", async () => {
+    const manager = new CodexSessionManager();
+    const projectDir = await tempDir("codex-subagents-app-archive-unsupported-project-");
+    const recordDir = await tempDir("codex-subagents-app-archive-unsupported-record-");
+
+    const { session, result } = await manager.start({
+      prompt: "archive unsupported session",
+      projectDir,
+      codexBin: fakeCodex,
+      env: {
+        FAKE_CODEX_RECORD_DIR: recordDir,
+        FAKE_CODEX_APP_SERVER_MODE: "THREAD_ARCHIVE_ERROR",
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    const cancelled = manager.cancel(session.id);
+    expect(cancelled?.status).toBe("cancelled");
+
+    const sawCleanup = await waitFor(async () => {
+      const calls = await recordedCalls(recordDir);
+      return calls.some((call) => call.method === "thread/archive") && calls.some((call) => call.method === "process/sigterm");
+    });
+    expect(sawCleanup).toBe(true);
+  });
+
   it("keeps concurrent app-server sessions isolated", async () => {
     const manager = new CodexSessionManager();
     const projectDir = await tempDir("codex-subagents-app-concurrent-project-");

test/app-server-protocol-contract.mjs

@@ -38,6 +38,8 @@ try {
     "v2/ThreadStartParams.json",
     "v2/ThreadResumeParams.json",
     "v2/ThreadResumeResponse.json",
+    "v2/ThreadArchiveParams.json",
+    "v2/ThreadArchiveResponse.json",
     "v2/TurnStartParams.json",
     "v2/TurnSteerParams.json",
     "v2/TurnInterruptParams.json",
@@ -68,6 +70,9 @@ try {
   assert(threadResume.properties?.model, "thread/resume must keep model override support");
   assert(threadResume.properties?.sandbox, "thread/resume must keep sandbox override support");
 
+  const threadArchive = await readSchema(out, "v2/ThreadArchiveParams.json");
+  assert(required(threadArchive).has("threadId"), "thread/archive must require threadId", threadArchive.required);
+
   const turnSteer = await readSchema(out, "v2/TurnSteerParams.json");
   assert(required(turnSteer).has("threadId"), "turn/steer must require threadId", turnSteer.required);
   assert(required(turnSteer).has("expectedTurnId"), "turn/steer must require expectedTurnId", turnSteer.required);

test/fixtures/fake-codex.mjs

@@ -59,6 +59,7 @@ if (args[0] === "app-server") {
   let activePrompt = "";
   let activeSteers = [];
   let threadName = null;
+  let threadArchived = false;
   let activeTimer = undefined;
 
   function modeText() {
@@ -217,6 +218,7 @@ if (args[0] === "app-server") {
       }
       threadId = `fake-thread-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
       threadName = null;
+      threadArchived = false;
       recordCall({
         protocol: "app-server",
         method,
@@ -277,6 +279,16 @@ if (args[0] === "app-server") {
       send({ id, result: {} });
       return;
     }
+    if (method === "thread/archive") {
+      threadArchived = true;
+      recordCall({ protocol: "app-server", method, threadId: params?.threadId ?? threadId });
+      if (hasMode("THREAD_ARCHIVE_ERROR")) {
+        send({ id, error: { code: -32000, message: "fake thread archive error" } });
+        return;
+      }
+      send({ id, result: {} });
+      return;
+    }
     if (method === "thread/resume") {
       if (hasMode("THREAD_RESUME_ERROR")) {
         send({ id, error: { code: -32000, message: "fake thread resume error" } });
@@ -461,7 +473,7 @@ if (args[0] === "app-server") {
         send({ id, error: { code: -32000, message: "fake thread read error" } });
         return;
       }
-      send({ id, result: { thread: { id: threadId, name: threadName, turns: [] } } });
+      send({ id, result: { thread: { id: threadId, name: threadName, archived: threadArchived, turns: [] } } });
       return;
     }
     send({ id, error: { code: -32601, message: `unknown method ${method}` } });