Fix Codex resume agent discovery

Author: markwylde

packages/server-core/src/activity/agentJournal.ts

@@ -33,13 +33,16 @@ interface WatchedTerminal {
   provider: AgentProvider | null;
   discovery?: ReturnType<typeof setInterval>;
   discoveryAttempts?: number;
+  discoveryBusy?: boolean;
+  discoveryPersistent?: boolean;
   tail?: JournalTail;
 }
 
 interface JournalTail { path: string; offset: number; partial: string; timer: ReturnType<typeof setInterval>; busy: boolean }
 
 export interface NodeAgentJournalSourceOptions {
   readonly codexHome?: string;
+  readonly discoveryAttemptLimit?: number;
   readonly platform?: NodeJS.Platform;
   readonly pollMs?: number;
 }
@@ -54,13 +57,15 @@ export class NodeAgentJournalSource implements AgentJournalSource {
   private readonly root: string;
   private readonly platform: NodeJS.Platform;
   private readonly pollMs: number;
+  private readonly discoveryAttemptLimit: number;
   private listener: AgentJournalListener | undefined;
   private enabled = true;
 
   constructor(options: NodeAgentJournalSourceOptions = {}) {
     this.root = resolve(options.codexHome ?? (process.env.CODEX_HOME?.trim() || join(homedir(), ".codex")));
     this.platform = options.platform ?? process.platform;
     this.pollMs = Math.max(50, options.pollMs ?? POLL_MS);
+    this.discoveryAttemptLimit = Math.max(1, Math.floor(options.discoveryAttemptLimit ?? 80));
   }
 
   async start(listener: AgentJournalListener): Promise<void> { this.listener = listener; }
@@ -89,8 +94,9 @@ export class NodeAgentJournalSource implements AgentJournalSource {
     const terminal = this.exactTerminal(identity);
     if (!terminal) return;
     terminal.provider = provider;
-    if (provider === "codex") this.startDiscovery(terminal);
+    if (provider === "codex") this.startDiscovery(terminal, true);
     else if (shellForeground) this.stopWatching(terminal);
+    else this.startDiscovery(terminal);
   }
 
   unregisterTerminal(identity: ActivitySessionIdentity): void {
@@ -113,26 +119,32 @@ export class NodeAgentJournalSource implements AgentJournalSource {
     return terminal?.identity.serverId === identity.serverId && terminal.identity.projectId === identity.projectId ? terminal : undefined;
   }
 
-  private startDiscovery(terminal: WatchedTerminal): void {
+  private startDiscovery(terminal: WatchedTerminal, persistent = false): void {
+    if (persistent) terminal.discoveryPersistent = true;
     if (!this.enabled || terminal.shellPid === undefined || terminal.tail !== undefined || terminal.discovery !== undefined) return;
     terminal.discoveryAttempts = 0;
     const discover = async () => {
-      if (terminal.tail !== undefined || terminal.shellPid === undefined) return;
-      terminal.discoveryAttempts = (terminal.discoveryAttempts ?? 0) + 1;
-      const path = await findProcessBoundCodexRollout(terminal.shellPid, join(this.root, "sessions"), this.platform).catch(() => undefined);
-      if (!path) {
-        if ((terminal.discoveryAttempts ?? 0) >= 80 && terminal.discovery !== undefined) {
-          clearInterval(terminal.discovery); terminal.discovery = undefined;
+      if (terminal.tail !== undefined || terminal.shellPid === undefined || terminal.discoveryBusy) return;
+      terminal.discoveryBusy = true;
+      try {
+        terminal.discoveryAttempts = (terminal.discoveryAttempts ?? 0) + 1;
+        const path = await findProcessBoundCodexRollout(terminal.shellPid, join(this.root, "sessions"), this.platform).catch(() => undefined);
+        if (!path) {
+          if (!terminal.discoveryPersistent && (terminal.discoveryAttempts ?? 0) >= this.discoveryAttemptLimit && terminal.discovery !== undefined) {
+            clearInterval(terminal.discovery); terminal.discovery = undefined;
+          }
+          return;
         }
-        return;
+        if (terminal.discovery !== undefined) clearInterval(terminal.discovery);
+        terminal.discovery = undefined;
+        await this.startTail(terminal, path).catch(() => undefined);
+      } finally {
+        terminal.discoveryBusy = false;
       }
-      if (terminal.discovery !== undefined) clearInterval(terminal.discovery);
-      terminal.discovery = undefined;
-      await this.startTail(terminal, path).catch(() => undefined);
     };
-    void discover();
     terminal.discovery = setInterval(() => void discover(), this.pollMs);
     terminal.discovery.unref?.();
+    void discover();
   }
 
   private async startTail(terminal: WatchedTerminal, path: string): Promise<void> {
@@ -205,6 +217,8 @@ export class NodeAgentJournalSource implements AgentJournalSource {
     if (terminal.tail !== undefined) clearInterval(terminal.tail.timer);
     terminal.discovery = undefined;
     terminal.discoveryAttempts = undefined;
+    terminal.discoveryBusy = undefined;
+    terminal.discoveryPersistent = undefined;
     terminal.tail = undefined;
   }
 }

packages/server-core/test/agent-journal.test.mjs

@@ -4,7 +4,7 @@ import { mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { findProcessBoundCodexRollout } from "../dist/activity/agentJournal.js";
+import { findProcessBoundCodexRollout, NodeAgentJournalSource } from "../dist/activity/agentJournal.js";
 
 test("rollout discovery requires an open writer below the exact process tree", { skip: !["darwin", "linux"].includes(process.platform) }, async () => {
   const root = await mkdtemp(join(tmpdir(), "terminay-agent-journal-"));
@@ -26,3 +26,33 @@ test("rollout discovery requires an open writer below the exact process tree", {
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("a generic foreground wrapper restarts discovery for Codex resume after the startup scan expires", { skip: !["darwin", "linux"].includes(process.platform) }, async () => {
+  const root = await mkdtemp(join(tmpdir(), "terminay-agent-resume-"));
+  const sessions = join(root, "sessions", "2026", "08", "05");
+  const path = join(sessions, "rollout-resumed.jsonl");
+  await mkdir(sessions, { recursive: true });
+  const record = JSON.stringify({ type: "session_meta", payload: { id: "resumed-session", cli_version: "0.146.1" } });
+  const identity = Object.freeze({ serverId: "server-1", projectId: "project-1", sessionId: "terminal-1" });
+  const source = new NodeAgentJournalSource({ codexHome: root, discoveryAttemptLimit: 2, pollMs: 50 });
+  const observations = [];
+  let child;
+  try {
+    await source.start((observation) => observations.push(observation));
+    source.registerTerminal(identity);
+    source.terminalStarted(identity, process.pid);
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    child = spawn(process.execPath, ["-e", "const fs=require('fs');const fd=fs.openSync(process.argv[1],'a');fs.writeSync(fd,process.argv[2]+'\\n');setInterval(()=>{},1000)", path, record], { stdio: "ignore" });
+    source.foregroundProcessChanged(identity, null, false);
+    for (let attempt = 0; attempt < 30 && observations.length === 0; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    assert.equal(observations[0]?.record?.payload?.id, "resumed-session");
+    assert.deepEqual(observations[0]?.identity, identity);
+  } finally {
+    await source.stop();
+    child?.kill();
+    if (child?.exitCode === null) await new Promise((resolve) => child.once("exit", resolve));
+    await rm(root, { recursive: true, force: true });
+  }
+});

specs/features/agent-status-and-sidebar.md

@@ -72,6 +72,14 @@ provider session may reopen the same journal in another terminal; the new
 writer creates a new binding incarnation and activation terminal without
 allowing stale events from the previous incarnation to mutate it.
 
+The Codex launcher may expose a generic wrapper such as `node` as the PTY
+foreground process. Every transition away from the shell therefore starts a
+new bounded journal-discovery window even when the foreground name is not a
+recognized provider. This lets a resumed session launched long after terminal
+startup bind its reopened journal without treating the wrapper itself as an
+agent. The journal is still admitted only after a writable handle is proven
+beneath the exact PTY process tree.
+
 CWD, filename timestamps, terminal title, active tab, and “closest match” logic
 must not establish an authoritative binding. A host that cannot prove the
 writer relationship uses terminal fallback instead.
@@ -88,11 +96,14 @@ A provider journal source:
 6. emits raw records only to the selected privileged driver;
 7. stops all file/process observation when the terminal, integration, or server stops.
 
-Discovery is retried briefly because foreground observation can arrive before
-the journal is opened. Expensive open-file/process inspection is used for
-initial binding, not for every appended record. Symlinks, non-regular files,
-paths outside the canonical sessions root, oversized records, invalid JSON,
-and unbounded growth are handled defensively.
+Discovery is retried briefly after terminal startup and whenever the shell
+loses foreground because either transition can arrive before the journal is
+opened. Once a supported provider is known to be foreground, discovery remains
+armed until that incarnation is bound or leaves the foreground. Expensive
+open-file/process inspection is used for initial binding, not for every
+appended record. Symlinks, non-regular files, paths outside the canonical
+sessions root, oversized records, invalid JSON, and unbounded growth are
+handled defensively.
 
 ## Versioned driver contract