@agentex/agent 0.0.33 → 0.0.35

package/src/providers/codex/session.ts

@@ -27,7 +27,7 @@ import { translateEndpoint } from "../../utils/endpoint.js";
 import { injectWorkspaceSkills } from "../../utils/skills.js";
 import { resolveInstructions } from "../../utils/instructions.js";
 import { createToolNameTracker } from "../../utils/tool-names.js";
-import { parseCodexStreamLine } from "./parse.js";
+import { parseCodexStreamLines } from "./parse.js";
 import { withPlanModePreamble } from "./plan-mode.js";
 import { scanCodexSessionUsage } from "./usage-scanner.js";
 import { codexSessionCodec } from "./codec.js";
@@ -130,6 +130,12 @@ interface PendingResult {
   settled?: boolean;
   /** Tear down this send's timeout timer / abort listener. */
   cleanup?: () => void;
+  /**
+   * Turn generation this send joined. Result delivery drains only the
+   * generation it belongs to, so a send that starts a NEW turn while the
+   * previous turn's result is still draining cannot be settled by it.
+   */
+  generation: number;
 }
 
 interface TrackedBackgroundTask {
@@ -138,14 +144,42 @@ interface TrackedBackgroundTask {
   summary: string | null;
   parentTaskId: string | null;
   terminal: boolean;
+  generation: number;
+  activeTurnId: string | null;
+}
+
+interface CodexBackgroundTaskState {
+  terminal: boolean;
+  status: "running" | "completed" | "failed" | "stopped";
+  summary: string | null;
 }
 
+const BACKGROUND_TASK_POLL_INTERVAL_MS = 2_000;
+const BACKGROUND_TASK_READ_TIMEOUT_MS = 5_000;
+
 /** Identity latch for the root turn currently represented by this session. */
+/**
+ * One turn's outcome, frozen at the terminal frame.
+ *
+ * Delivery is asynchronous (event chain, and an on-disk usage scan when the
+ * stream carried no usage), so reading the live accumulators at delivery time
+ * reads whatever turn is running *then*. Snapshotting decouples the two: the
+ * accumulators reset immediately and belong to the next turn from that moment.
+ */
+interface TurnOutcome {
+  summary: string | null;
+  isError: boolean;
+  errorMessage: string | null;
+  wasInterrupted: boolean;
+}
+
 interface ActiveTurnReady {
   promise: Promise<string | null>;
   resolve: (turnId: string | null) => void;
   reject: (err: Error) => void;
   settled: boolean;
+  /** Monotonic id for this turn, used to fence late result delivery. */
+  generation: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -179,6 +213,32 @@ function asObj(parent: Record<string, unknown>, key: string): Record<string, unk
     : {};
 }
 
+function obj(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0)
+    : [];
+}
+
+function codexAgentState(value: unknown): CodexBackgroundTaskState {
+  const state = obj(value);
+  const nativeStatus = str(state, "status");
+  const summary = str(state, "message") || null;
+  if (nativeStatus === "completed") return { terminal: true, status: "completed", summary };
+  if (nativeStatus === "errored" || nativeStatus === "notFound") {
+    return { terminal: true, status: "failed", summary };
+  }
+  if (nativeStatus === "interrupted" || nativeStatus === "shutdown") {
+    return { terminal: true, status: "stopped", summary };
+  }
+  return { terminal: false, status: "running", summary };
+}
+
 /** Discriminated incoming message from the Codex CLI. */
 type IncomingMessage =
   | { kind: "response"; id: number; result?: Record<string, unknown>; error?: { code: number; message: string } }
@@ -366,6 +426,8 @@ export class CodexSessionImpl implements AgentSession {
    */
   private _activeTurnId: string | null = null;
   private _activeTurnReady: ActiveTurnReady | null = null;
+  /** Incremented per turn latch. Never reused, so staleness is decidable. */
+  private _turnGeneration = 0;
   /** Successful repeated interrupts coalesce until the terminal notification. */
   private _interruptPromise: Promise<void> | null = null;
   /** Prevents a late interrupt request after the terminal frame was observed. */
@@ -387,6 +449,16 @@ export class CodexSessionImpl implements AgentSession {
   /** Child-agent lifecycle is informational and never participates in root turn settlement. */
   private readonly _backgroundTasks = new Map<string, TrackedBackgroundTask>();
   private readonly _backgroundTaskIdsByPath = new Map<string, string>();
+  /** One protocol-native thread/read poller per child when Codex does not multiplex its notifications. */
+  private readonly _backgroundTaskPollers = new Map<string, {
+    generation: number;
+    promise: Promise<void>;
+  }>();
+  /** Cancellable retry delay for each poller. Cleared when the session closes. */
+  private readonly _backgroundTaskPollTimers = new Map<string, {
+    timer: ReturnType<typeof setTimeout>;
+    resolve: () => void;
+  }>();
 
   /**
    * Serial dispatch chain for `onEvent`. Each dispatched event appends a
@@ -456,7 +528,14 @@ export class CodexSessionImpl implements AgentSession {
     proc.on("exit", (code, signal) => {
       if (this._state !== "closed") {
         this._state = "closed";
-        const err = new Error(`Codex process exited unexpectedly (code=${code}, signal=${signal})`);
+        const message = `Codex process exited unexpectedly (code=${code}, signal=${signal})`;
+        this.finalizeActiveBackgroundTasks("failed", message, {
+          method: "process/exit",
+          code,
+          signal,
+        });
+        this.cancelBackgroundTaskPollTimers();
+        const err = new Error(message);
         this.rejectAllPending(err);
       }
     });
@@ -464,11 +543,59 @@ export class CodexSessionImpl implements AgentSession {
     proc.on("error", (err) => {
       if (this._state !== "closed") {
         this._state = "closed";
+        this.finalizeActiveBackgroundTasks("failed", err.message, {
+          method: "process/error",
+          message: err.message,
+        });
+        this.cancelBackgroundTaskPollTimers();
         this.rejectAllPending(err);
       }
     });
   }
 
+  private cancelBackgroundTaskPollTimers(): void {
+    for (const pending of this._backgroundTaskPollTimers.values()) {
+      clearTimeout(pending.timer);
+      pending.resolve();
+    }
+    this._backgroundTaskPollTimers.clear();
+  }
+
+  private finalizeActiveBackgroundTasks(
+    status: "failed" | "stopped",
+    summary: string,
+    raw: Record<string, unknown>,
+  ): void {
+    for (const task of this._backgroundTasks.values()) {
+      if (task.terminal) continue;
+      this.dispatchEvent(this.backgroundTaskEvent(task.taskId, "completed", status, {
+        description: task.description,
+        summary,
+        parentTaskId: task.parentTaskId,
+        eventId: this._threadId
+          ? `codex:${this._threadId}:background-task:${task.taskId}:session-${status}:completed`
+          : null,
+        raw,
+      }));
+    }
+  }
+
+  /**
+   * Remove and return the pending sends belonging to one turn generation.
+   *
+   * `undefined` matches entries with no generation, which is how tests that
+   * drive the session without `send()` enqueue resolvers.
+   */
+  private takePendingResults(generation: number | undefined): PendingResult[] {
+    const mine: PendingResult[] = [];
+    const others: PendingResult[] = [];
+    for (const entry of this._pendingResults) {
+      (entry.generation === generation ? mine : others).push(entry);
+    }
+    this._pendingResults = others;
+    return mine;
+  }
+
   /** Reject every pending send() Promise and outgoing JSON-RPC call. */
   private rejectAllPending(err: Error): void {
     const pending = this._pendingResults.splice(0);
@@ -503,6 +630,7 @@ export class CodexSessionImpl implements AgentSession {
       resolve: resolveFn,
       reject: rejectFn,
       settled: false,
+      generation: ++this._turnGeneration,
     };
     this._activeTurnId = null;
     this._activeTurnReady = ready;
@@ -528,9 +656,16 @@ export class CodexSessionImpl implements AgentSession {
     expected.reject(err);
   }
 
-  /** Clear the current turn and release an interrupt waiting for its id. */
-  private clearActiveTurn(err?: Error): void {
+  /**
+   * Clear the current turn and release an interrupt waiting for its id.
+   *
+   * `expected` fences the clear against a turn that started after the one being
+   * torn down. Without it, a late teardown nulls the latch a newer, running
+   * turn is relying on, which is the same silent-Stop failure by another route.
+   */
+  private clearActiveTurn(err?: Error, expected?: ActiveTurnReady): void {
     const ready = this._activeTurnReady;
+    if (expected && ready !== expected) return;
     if (ready && !ready.settled) {
       ready.settled = true;
       if (err) ready.reject(err);
@@ -584,6 +719,35 @@ export class CodexSessionImpl implements AgentSession {
     });
   }
 
+  /** A bounded RPC whose pending-map entry is removed if Codex never replies. */
+  private boundedRpcRequest(
+    method: string,
+    params: Record<string, unknown>,
+    timeoutMs = BACKGROUND_TASK_READ_TIMEOUT_MS,
+  ): Promise<Record<string, unknown>> {
+    const id = this._nextId++;
+    this.proc.stdin!.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (!this._pendingRpc.delete(id)) return;
+        reject(new Error(`codex ${method} timed out`));
+      }, timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+
+      this._pendingRpc.set(id, {
+        resolve: (result) => {
+          clearTimeout(timer);
+          resolve(result);
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+      });
+    });
+  }
+
   /**
    * Bounded RPC for experimental, best-effort methods (the `thread/goal/*`
    * family). An app-server build that doesn't recognize the method may never
@@ -719,9 +883,17 @@ export class CodexSessionImpl implements AgentSession {
     // and pass through. If the second `turn/start` lands during the first
     // turn, the per-turn accumulators continue collecting until the result
     // event fires; the result then drains all pending resolvers.
+    // Joining the active turn requires that it still be active. The latch
+    // survives the terminal frame until deliverTurnResult() clears it, and that
+    // gap is real time: it spans `await this._eventChain` (a host persisting
+    // events) and, when turn/completed carried no usage, an on-disk usage scan.
+    // A send landing in that gap belongs to a NEW turn — joining the dead one
+    // would leave it with no interrupt latch and no turn/start capture, so Stop
+    // would find nothing to interrupt and return as if it had succeeded.
     const existingTurnReady = this._activeTurnReady;
-    const isTurnLeader = existingTurnReady === null;
-    const turnReady = existingTurnReady ?? this.beginActiveTurn();
+    const canJoinActiveTurn = existingTurnReady !== null && !this._turnTerminalObserved;
+    const isTurnLeader = !canJoinActiveTurn;
+    const turnReady = canJoinActiveTurn ? existingTurnReady! : this.beginActiveTurn();
 
     if (this._state === "idle") {
       this._state = "thinking";
@@ -753,7 +925,11 @@ export class CodexSessionImpl implements AgentSession {
       rejectFn = reject;
     });
 
-    const entry: PendingResult = { resolve: resolveFn, reject: rejectFn };
+    const entry: PendingResult = {
+      resolve: resolveFn,
+      reject: rejectFn,
+      generation: turnReady.generation,
+    };
     this._pendingResults.push(entry);
 
     // Track the in-flight turn so drain() can await it; drop it on settle.
@@ -953,6 +1129,14 @@ export class CodexSessionImpl implements AgentSession {
   async close(): Promise<void> {
     if (this._state === "closed") return;
     this._state = "closed";
+    this.finalizeActiveBackgroundTasks("stopped", "Codex session closed", {
+      method: "session/closed",
+    });
+    this.cancelBackgroundTaskPollTimers();
+    // finalizeActiveBackgroundTasks above has already emitted the terminal
+    // edges, so nothing downstream needs these records any more.
+    this._backgroundTasks.clear();
+    this._backgroundTaskIdsByPath.clear();
     this.rejectAllPending(new Error("Codex session closed"));
 
     this.proc.stdin!.end();
@@ -1043,6 +1227,8 @@ export class CodexSessionImpl implements AgentSession {
       method === "item/fileChange/requestApproval"
     ) {
       void this.handleApproval(id, method, params);
+    } else if (method === "item/permissions/requestApproval") {
+      void this.handlePermissionsApproval(id, params);
     } else if (
       method === "item/tool/requestUserInput" ||
       method === "tool/requestUserInput"
@@ -1050,7 +1236,13 @@ export class CodexSessionImpl implements AgentSession {
       // `tool/requestUserInput` is the legacy method name on older codex builds.
       void this.handleUserInputRequest(id, params);
     } else {
-      // Unknown server request — ack to unblock the turn.
+      // Unknown server request. `{}` is a best-effort reply, NOT a guarantee
+      // that the turn proceeds: every server request the protocol defines but
+      // this file does not handle declares required response fields, so an
+      // empty result is schema-invalid for all of them. A JSON-RPC error reply
+      // would be the honest answer, but `rpcResponse` has no error path and
+      // introducing one changes behavior (an error can abort a turn where this
+      // limps along), so that is a deliberate follow-up rather than a fix here.
       this.rpcResponse(id, {});
     }
   }
@@ -1067,14 +1259,23 @@ export class CodexSessionImpl implements AgentSession {
   }
 
   private async handleApproval(id: number, method: string, params: Record<string, unknown>): Promise<void> {
-    this._state = "waiting_for_approval";
+    // A child thread's approval still has to be answered — somebody must decide
+    // whether that subagent may run its command — but it is not the root turn's
+    // business. Driving root state from it would show the session as blocked on
+    // approval when the root turn is running fine, and `restoreStateAfter` would
+    // then recompute root state from a child's lifecycle. The protocol makes
+    // `threadId` mandatory on every approval, so the attribution is free.
+    const requestThreadId = str(params, "threadId") || null;
+    const foreign = this.isForeignThread(requestThreadId);
+    if (!foreign) this._state = "waiting_for_approval";
+    const restore = () => { if (!foreign) this.restoreStateAfter("waiting_for_approval"); };
 
     // Codex's app-server expects `{ decision: "accept" | "decline" | "cancel" }`
     // (NOT `{ approved: boolean }`). agentex's UserInputResponse has no interrupt
     // concept, so allow → accept and deny → decline.
     if (!this.ctx.onUserInputRequest) {
       this.rpcResponse(id, { decision: "accept" });
-      this.restoreStateAfter("waiting_for_approval");
+      restore();
       return;
     }
 
@@ -1086,15 +1287,67 @@ export class CodexSessionImpl implements AgentSession {
       const resp = await this.ctx.onUserInputRequest({
         toolName,
         input: params,
-        toolUseId: str(params, "id"),
-        description: str(params, "command") || str(params, "path") || undefined,
+        // `itemId`, not `id` — the protocol has no `id` here, so this was
+        // always "". It is the field that lets a host line an approval up with
+        // the tool_call event carrying the same item id.
+        toolUseId: str(params, "itemId"),
+        // FileChangeRequestApprovalParams carries `grantRoot`, never `path`,
+        // so file-change approvals reached hosts with no description at all.
+        description: str(params, "command")
+          || str(params, "grantRoot")
+          || str(params, "reason")
+          || undefined,
+        // Which subagent is asking. The child thread id is also its
+        // `background_task.taskId`, so a host can line the approval up with
+        // the task it already renders. Absent for the root turn.
+        ...(foreign && requestThreadId ? { agentId: requestThreadId } : {}),
       });
       this.rpcResponse(id, { decision: resp.allow ? "accept" : "decline" });
     } catch {
       this.rpcResponse(id, { decision: "decline" });
     }
 
-    this.restoreStateAfter("waiting_for_approval");
+    restore();
+  }
+
+  /**
+   * Handle `item/permissions/requestApproval`.
+   *
+   * Unlike the accept/decline approvals, the response here IS the grant: the
+   * schema requires a `permissions` profile, so the generic "ack with `{}` to
+   * unblock the turn" fallback this used to land in was schema-invalid.
+   * Granting means echoing back the profile the agent asked for; refusing means
+   * an empty profile, which is valid and grants nothing beyond what it already
+   * has. With no host handler we refuse, because silently widening a sandbox is
+   * not a safe default for an unattended session.
+   */
+  private async handlePermissionsApproval(id: number, params: Record<string, unknown>): Promise<void> {
+    const requestThreadId = str(params, "threadId") || null;
+    const foreign = this.isForeignThread(requestThreadId);
+    if (!foreign) this._state = "waiting_for_approval";
+    const restore = () => { if (!foreign) this.restoreStateAfter("waiting_for_approval"); };
+    const requested = asObj(params, "permissions");
+
+    if (!this.ctx.onUserInputRequest) {
+      this.rpcResponse(id, { permissions: {} });
+      restore();
+      return;
+    }
+
+    try {
+      const resp = await this.ctx.onUserInputRequest({
+        toolName: "permissions",
+        input: params,
+        toolUseId: str(params, "itemId"),
+        description: str(params, "reason") || undefined,
+        ...(foreign && requestThreadId ? { agentId: requestThreadId } : {}),
+      });
+      this.rpcResponse(id, { permissions: resp.allow ? requested : {} });
+    } catch {
+      this.rpcResponse(id, { permissions: {} });
+    }
+
+    restore();
   }
 
   /**
@@ -1104,9 +1357,17 @@ export class CodexSessionImpl implements AgentSession {
    * back in Codex's `{ answers: { [questionId]: { answers: string[] } } }` shape.
    */
   private async handleUserInputRequest(id: number, params: Record<string, unknown>): Promise<void> {
+    // Same scoping as the approval handlers: a child subagent's question still
+    // has to be answered, but it is not the root turn's business. Blocking root
+    // state on it shows the session as waiting for input when the root turn is
+    // running fine. `ToolRequestUserInputParams` requires `threadId`, so the
+    // attribution is read from the wire rather than inferred.
+    const requestThreadId = str(params, "threadId") || null;
+    const foreign = this.isForeignThread(requestThreadId);
     // Questions are user *input*, not a tool-permission gate — distinct state so a
     // host UI can render a question form vs an approval prompt.
-    this._state = "waiting_for_input";
+    if (!foreign) this._state = "waiting_for_input";
+    const restore = () => { if (!foreign) this.restoreStateAfter("waiting_for_input"); };
 
     const questions = parseCodexQuestions(params);
 
@@ -1114,7 +1375,7 @@ export class CodexSessionImpl implements AgentSession {
     // agent proceeds without hanging.
     if (!this.ctx.onUserInputRequest || questions.length === 0) {
       this.rpcResponse(id, { answers: {} });
-      this.restoreStateAfter("waiting_for_input");
+      restore();
       return;
     }
 
@@ -1122,14 +1383,16 @@ export class CodexSessionImpl implements AgentSession {
       const resp = await this.ctx.onUserInputRequest({
         toolName: "AskUserQuestion",
         input: { questions },
-        toolUseId: str(params, "id") || "codex-user-input",
+        toolUseId: str(params, "itemId") || "codex-user-input",
+        // Which subagent is asking, matching its `background_task.taskId`.
+        ...(foreign && requestThreadId ? { agentId: requestThreadId } : {}),
       });
       this.rpcResponse(id, { answers: buildCodexUserInputAnswers(questions, resp) });
     } catch {
       this.rpcResponse(id, { answers: {} });
     }
 
-    this.restoreStateAfter("waiting_for_input");
+    restore();
   }
 
   // -------------------------------------------------------------------------
@@ -1175,6 +1438,280 @@ export class CodexSessionImpl implements AgentSession {
     return null;
   }
 
+  private backgroundTaskEvent(
+    taskId: string,
+    phase: "started" | "progress" | "completed",
+    status: "running" | "completed" | "failed" | "stopped",
+    options: {
+      description?: string | null;
+      summary?: string | null;
+      parentTaskId?: string | null;
+      turnId?: string | null;
+      eventId?: string | null;
+      raw: Record<string, unknown>;
+    },
+  ): Extract<StreamEvent, { type: "background_task" }> {
+    const rootThreadId = this._threadId ?? this._expectedThreadId;
+    return {
+      type: "background_task",
+      taskId,
+      taskType: "subagent",
+      phase,
+      status,
+      description: options.description ?? null,
+      summary: options.summary ?? null,
+      parentTaskId: options.parentTaskId ?? null,
+      timestamp: new Date().toISOString(),
+      providerType: "codex",
+      sessionId: rootThreadId,
+      messageId: null,
+      eventId: options.eventId ?? null,
+      turnId: options.turnId ?? null,
+      parentToolCallId: null,
+      raw: options.raw,
+    };
+  }
+
+  private reconciledBackgroundTaskRaw(
+    threadId: string,
+    turn: Record<string, unknown> | null,
+  ): Record<string, unknown> {
+    const error = turn ? str(asObj(turn, "error"), "message") || null : null;
+    return {
+      method: "thread/read",
+      reconciled: true,
+      threadId,
+      turnId: turn ? str(turn, "id") || null : null,
+      status: turn ? str(turn, "status") || null : null,
+      error,
+    };
+  }
+
+  /**
+   * Codex 0.144+ represents collaboration as a root collabAgentToolCall item.
+   * A completed spawn call only means the child was created. Register every
+   * receiver and then follow the child thread itself for the real terminus.
+   */
+  /** @returns whether the item produced at least one background-task edge. */
+  private handleCollabAgentToolCall(
+    item: Record<string, unknown>,
+    raw: Record<string, unknown>,
+    parentTaskId: string | null,
+  ): boolean {
+    if (this._state === "closed" || !this.ctx.onEvent) return false;
+    let dispatched = false;
+
+    const tool = str(item, "tool");
+    const states = asObj(item, "agentsStates");
+    const receiverIds = stringArray(item["receiverThreadIds"]);
+    const taskIds = [...new Set([...receiverIds, ...Object.keys(states)])];
+    const canStart = tool === "spawnAgent";
+    const metadataOnly = tool === "resumeAgent" || tool === "sendInput";
+    const canStopWithoutState = tool === "closeAgent" && str(item, "status") === "completed";
+
+    for (const taskId of taskIds) {
+      const previous = this._backgroundTasks.get(taskId);
+      const description = str(item, "prompt") || previous?.description || null;
+      const resolvedParentTaskId = previous?.parentTaskId ?? parentTaskId;
+
+      // The child thread's own turn/started notification is the only
+      // authoritative reactivation edge. Root resume/send calls can arrive
+      // before or after that child turn, so they only enrich an active task.
+      if (metadataOnly) {
+        if (!previous || previous.terminal) continue;
+        if (description && description !== previous.description) {
+          this.dispatchEvent(this.backgroundTaskEvent(taskId, "progress", "running", {
+            description,
+            summary: previous.summary,
+            parentTaskId: resolvedParentTaskId,
+            eventId: this._threadId
+              ? `codex:${this._threadId}:background-task:${taskId}:${str(item, "id") || "metadata"}:progress`
+              : null,
+            raw,
+          }));
+          dispatched = true;
+        }
+        continue;
+      }
+
+      if (!previous && !canStart) continue;
+      if (!canStart && !canStopWithoutState && !(taskId in states)) continue;
+
+      const hasState = taskId in states;
+      const state = !hasState && canStopWithoutState
+        ? { terminal: true, status: "stopped" as const, summary: null }
+        : codexAgentState(states[taskId]);
+
+      if (!previous) {
+        this.dispatchEvent(this.backgroundTaskEvent(taskId, "started", "running", {
+          description,
+          summary: null,
+          parentTaskId: resolvedParentTaskId,
+          eventId: this._threadId
+            ? `codex:${this._threadId}:background-task:${taskId}:started`
+            : null,
+          raw,
+        }));
+        dispatched = true;
+      } else if (previous.terminal) {
+        continue;
+      } else if (description && description !== previous.description) {
+        // thread/started can beat the richer root collab item. Preserve one
+        // start edge, then publish the prompt as ordinary progress metadata.
+        this.dispatchEvent(this.backgroundTaskEvent(taskId, "progress", "running", {
+          description,
+          summary: previous.summary,
+          parentTaskId: resolvedParentTaskId,
+          eventId: this._threadId
+            ? `codex:${this._threadId}:background-task:${taskId}:${str(item, "id") || "metadata"}:progress`
+            : null,
+          raw,
+        }));
+        dispatched = true;
+      }
+
+      if (state.terminal) {
+        this.dispatchEvent(this.backgroundTaskEvent(taskId, "completed", state.status, {
+          description,
+          summary: state.summary,
+          parentTaskId: resolvedParentTaskId,
+          eventId: this._threadId
+            ? `codex:${this._threadId}:background-task:${taskId}:${str(item, "id") || "state"}:completed`
+            : null,
+          raw,
+        }));
+        dispatched = true;
+      }
+    }
+    return dispatched;
+  }
+
+  private waitForBackgroundTaskPoll(pollKey: string): Promise<void> {
+    if (this._state === "closed") return Promise.resolve();
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._backgroundTaskPollTimers.delete(pollKey);
+        resolve();
+      }, BACKGROUND_TASK_POLL_INTERVAL_MS);
+      if (typeof timer.unref === "function") timer.unref();
+      this._backgroundTaskPollTimers.set(pollKey, { timer, resolve });
+    });
+  }
+
+  private startBackgroundTaskPoller(taskId: string): void {
+    if (this._state === "closed") return;
+    const task = this._backgroundTasks.get(taskId);
+    if (!task || task.terminal) return;
+    const existing = this._backgroundTaskPollers.get(taskId);
+    if (existing?.generation === task.generation) return;
+
+    const generation = task.generation;
+    const pollKey = `${taskId}:${generation}`;
+    let poller!: Promise<void>;
+    poller = this.pollBackgroundTask(taskId, generation, pollKey).finally(() => {
+      if (this._backgroundTaskPollers.get(taskId)?.promise === poller) {
+        this._backgroundTaskPollers.delete(taskId);
+      }
+      const pending = this._backgroundTaskPollTimers.get(pollKey);
+      if (pending) clearTimeout(pending.timer);
+      this._backgroundTaskPollTimers.delete(pollKey);
+    });
+    this._backgroundTaskPollers.set(taskId, { generation, promise: poller });
+  }
+
+  private async pollBackgroundTask(
+    taskId: string,
+    generation: number,
+    pollKey: string,
+  ): Promise<void> {
+    while (this._state !== "closed") {
+      const task = this._backgroundTasks.get(taskId);
+      if (!task || task.generation !== generation || task.terminal) return;
+
+      try {
+        const response = await this.boundedRpcRequest("thread/read", {
+          threadId: taskId,
+          includeTurns: true,
+        });
+        if (this.observeBackgroundTaskThread(response, taskId, generation)) return;
+      } catch {
+        // A child can briefly be pendingInit before thread/read can load it.
+      }
+
+      const current = this._backgroundTasks.get(taskId);
+      if (!current || current.generation !== generation || current.terminal) return;
+      await this.waitForBackgroundTaskPoll(pollKey);
+    }
+  }
+
+  /** Return true once thread/read proves that the child's latest turn ended. */
+  private observeBackgroundTaskThread(
+    response: Record<string, unknown>,
+    taskId: string,
+    generation: number,
+  ): boolean {
+    const task = this._backgroundTasks.get(taskId);
+    if (!task || task.generation !== generation || task.terminal) return true;
+
+    const thread = asObj(response, "thread");
+    const turns = Array.isArray(thread["turns"])
+      ? thread["turns"].map(obj)
+      : [];
+
+    const latestTurn = turns[turns.length - 1];
+    if (!latestTurn) {
+      const threadStatus = str(asObj(thread, "status"), "type");
+      if (threadStatus !== "systemError") return false;
+      const failureTurn = { status: "systemError", error: { message: "Subagent failed to initialize" } };
+      this.dispatchEvent(this.backgroundTaskEvent(taskId, "completed", "failed", {
+        description: task.description,
+        summary: "Subagent failed to initialize",
+        parentTaskId: task.parentTaskId,
+        eventId: this._threadId
+          ? `codex:${this._threadId}:background-task:${taskId}:system-error:completed`
+          : null,
+        raw: this.reconciledBackgroundTaskRaw(taskId, failureTurn),
+      }));
+      return true;
+    }
+
+    const nativeStatus = str(latestTurn, "status");
+    if (nativeStatus === "inProgress" || !nativeStatus) return false;
+
+    const turnId = str(latestTurn, "id") || null;
+    // The child turn/started notification is authoritative for a reactivated
+    // generation. thread/read can briefly lag and still end at an older turn.
+    if (task.activeTurnId && turnId !== task.activeTurnId) return false;
+
+    const items = Array.isArray(latestTurn["items"])
+      ? latestTurn["items"].map(obj)
+      : [];
+    let summary: string | null = null;
+    for (let index = items.length - 1; index >= 0; index--) {
+      const item = items[index]!;
+      if (str(item, "type") !== "agentMessage") continue;
+      summary = this.agentMessageText(item);
+      if (summary) break;
+    }
+    const errorMessage = str(asObj(latestTurn, "error"), "message") || null;
+    const status = nativeStatus === "failed"
+      ? "failed"
+      : nativeStatus === "interrupted" || nativeStatus === "cancelled"
+        ? "stopped"
+        : "completed";
+    this.dispatchEvent(this.backgroundTaskEvent(taskId, "completed", status, {
+      description: task.description,
+      summary: summary ?? errorMessage,
+      parentTaskId: task.parentTaskId,
+      turnId,
+      eventId: this._threadId && turnId
+        ? `codex:${this._threadId}:background-task:${taskId}:${turnId}:completed`
+        : null,
+      raw: this.reconciledBackgroundTaskRaw(taskId, latestTurn),
+    }));
+    return true;
+  }
+
   /**
    * Maintain just enough child metadata to turn a later foreign-thread
    * terminal notification into one provider-neutral task event. This reducer
@@ -1188,6 +1725,9 @@ export class CodexSessionImpl implements AgentSession {
     // a task that already reached a terminal state. A later child turn/started
     // explicitly reactivates the record below in handleForeignNotification.
     if (previous?.terminal) return false;
+    // collabAgentToolCall and child thread/started can both announce the same
+    // spawn. The first edge is sufficient and gives hosts one durable start.
+    if (previous && event.phase === "started") return false;
 
     const description = event.description ?? previous?.description ?? null;
     const summary = event.summary ?? previous?.summary ?? null;
@@ -1199,14 +1739,38 @@ export class CodexSessionImpl implements AgentSession {
     event.summary = summary;
     event.parentTaskId = parentTaskId;
 
+    const terminal = event.phase === "completed";
     this._backgroundTasks.set(event.taskId, {
       taskId: event.taskId,
+      // `description` survives termination: the reactivation path in
+      // handleForeignNotification reads it precisely BECAUSE the record is
+      // terminal, and dropping it lost a reactivated child's label forever.
+      // It is one bounded string per child. `summary` is the unbounded one —
+      // full agent messages, appended per item — and has no reader that
+      // outlives the task, so it is released.
       description,
-      summary,
+      summary: terminal ? null : summary,
       parentTaskId,
-      terminal: event.phase === "completed",
+      terminal,
+      generation: previous?.generation ?? 0,
+      activeTurnId: terminal ? null : event.turnId ?? previous?.activeTurnId ?? null,
     });
+    // Kept past termination too: a grandchild can spawn after its parent has
+    // finished, and lineage resolves through this index.
     if (description) this._backgroundTaskIdsByPath.set(description, event.taskId);
+    // Every registration route converges here, so this is the one place that
+    // can guarantee a reconciliation poller exists. Registering by way of the
+    // parser's subAgentActivity branch previously produced a task with no
+    // safety net at all, wholly dependent on the child notification arriving.
+    //
+    // Correctness rests on `startBackgroundTaskPoller` and the poll loop both
+    // re-reading the record and bailing when it is terminal — NOT on the
+    // microtask. The deferral is an optimization: one wire item can emit
+    // several edges in a tick (a collab spawn whose child is already finished
+    // dispatches `started` then `completed`), and yielding first means the
+    // common case declines before spawning a `thread/read` rather than after.
+    // Do not remove the terminal checks on the grounds that this defers.
+    if (!terminal) queueMicrotask(() => this.startBackgroundTaskPoller(event.taskId));
     return true;
   }
 
@@ -1229,7 +1793,23 @@ export class CodexSessionImpl implements AgentSession {
       // App-server can publish child thread/started before the corresponding
       // root subAgentActivity item. Register only descendants of this session,
       // not unrelated foreign threads multiplexed by a future server version.
-      if (parentThreadId !== rootThreadId && !parentTask) return;
+      if (parentThreadId !== rootThreadId && !parentTask) {
+        // Say so. A wire shape that omits parentThreadId takes this branch for
+        // every child, which silently disables the whole registration and
+        // reconciliation path — the safety net that exists precisely because
+        // child notifications cannot be relied on. Degrading quietly here
+        // hides the one failure this machinery was built to survive.
+        if (!parentThreadId && this.ctx.onOutput) {
+          try {
+            void this.ctx.onOutput(
+              "stderr",
+              `agentex: codex child thread ${childThreadId} announced no parent thread id; `
+              + "background-task tracking and reconciliation are disabled for it\n",
+            );
+          } catch { /* swallow */ }
+        }
+        return;
+      }
 
       const source = asObj(thread, "source");
       const subAgent = Object.keys(asObj(source, "subAgent")).length > 0
@@ -1275,6 +1855,7 @@ export class CodexSessionImpl implements AgentSession {
       if (!task.terminal) return;
       task.terminal = false;
       task.summary = null;
+      task.generation += 1;
       const turn = asObj(params, "turn");
       const turnId = str(turn, "id") || str(params, "turnId") || null;
       const rootThreadId = this._threadId ?? this._expectedThreadId;
@@ -1304,6 +1885,10 @@ export class CodexSessionImpl implements AgentSession {
     if (method === "item/completed") {
       const item = asObj(params, "item");
       const itemType = str(item, "type");
+      if (itemType === "collabAgentToolCall") {
+        this.handleCollabAgentToolCall(item, parseJson(rawLine) ?? params, childThreadId);
+        return;
+      }
       if ((itemType === "agentMessage" || itemType === "agent_message") && str(item, "phase") !== "commentary") {
         const summary = this.agentMessageText(item);
         if (summary) task.summary = summary;
@@ -1344,11 +1929,19 @@ export class CodexSessionImpl implements AgentSession {
         : null,
       turnId,
       parentToolCallId: null,
-      raw: parseJson(rawLine) ?? params,
+      raw: {
+        method,
+        reconciled: false,
+        threadId: childThreadId,
+        turnId,
+        status: nativeStatus || null,
+        error: errorMessage || null,
+      },
     });
   }
 
   private handleNotification(method: string, params: Record<string, unknown>, rawLine: string): void {
+    if (this._state === "closed") return;
     // codex/event — legacy wrapper
     if (method === "codex/event") {
       const innerMsg = str(params, "msg");
@@ -1394,6 +1987,17 @@ export class CodexSessionImpl implements AgentSession {
     if (method === "item/completed") {
       this._state = "thinking";
       this.extractSummaryFromItem(params);
+      const item = asObj(params, "item");
+      if (str(item, "type") === "collabAgentToolCall") {
+        // Shapes we model become background_task edges. Anything that produced
+        // no edge still reaches the host as a raw `unknown` event rather than
+        // vanishing — that escape hatch is how unmodeled wire shapes stay
+        // visible, and collab is exactly where new shapes keep appearing.
+        if (!this.handleCollabAgentToolCall(item, parseJson(rawLine) ?? params, null)) {
+          this.emitStreamEvent(rawLine);
+        }
+        return;
+      }
       this.emitStreamEvent(rawLine);
       return;
     }
@@ -1434,6 +2038,7 @@ export class CodexSessionImpl implements AgentSession {
   // -------------------------------------------------------------------------
 
   private handleLegacyEvent(event: Record<string, unknown>, rawLine: string): void {
+    if (this._state === "closed") return;
     const type = str(event, "type");
     const eventThreadId =
       str(event, "thread_id") || str(event, "threadId") || str(event, "session_id") || null;
@@ -1577,11 +2182,37 @@ export class CodexSessionImpl implements AgentSession {
   }
 
   private resolveTurn(): void {
+    // Bind delivery to the turn that just terminated. Everything below this
+    // point can yield (usage scan, event chain), and a send() arriving in the
+    // meantime starts a new turn that must not be settled by this result.
+    const delivering = this._activeTurnReady;
     const resolvedModel = this._turnModel ?? this.model;
     let usage = this._turnUsage && resolvedModel
       ? { [resolvedModel]: { inputTokens: this._turnUsage.inputTokens, outputTokens: this._turnUsage.outputTokens } }
       : undefined;
 
+    // Freeze this turn's outcome and clear the accumulators NOW, while we are
+    // still synchronous with the terminal frame. Delivery reads the snapshot,
+    // so a turn that starts during the async gap below neither inherits these
+    // values nor has its own overwritten. Resetting inside beginActiveTurn()
+    // instead would not work: the usage-scan path re-reads state after an
+    // await, so the new turn's reset would eat the old turn's summary.
+    const outcome: TurnOutcome = {
+      summary: this._turnSummary,
+      isError: this._turnIsError,
+      errorMessage: this._turnErrorMessage,
+      wasInterrupted: this._turnWasInterrupted,
+    };
+    this._turnSummary = null;
+    this._turnUsage = null;
+    this._turnModel = null;
+    this._turnIsError = false;
+    this._turnWasInterrupted = false;
+    this._turnErrorMessage = null;
+    // Captured before clearing: the usage-scan fallback below still needs it.
+    const turnStartedAt = this._turnStartedAt;
+    this._turnStartedAt = null;
+
     // Usage precedence: the `turn.completed` payload is authoritative when
     // present (captured above into _turnUsage). Only when the stream carried no
     // usage do we fall back to scanning Codex's on-disk session logs.
@@ -1591,8 +2222,8 @@ export class CodexSessionImpl implements AgentSession {
     // latest turn or read partially-written totals. We therefore scan ONLY when
     // there is no in-band usage, and never let a scan failure fail the turn
     // (usage simply stays undefined). Prefer the in-band payload always.
-    if (!usage && this._turnStartedAt) {
-      const startedAt = this._turnStartedAt;
+    if (!usage && turnStartedAt) {
+      const startedAt = turnStartedAt;
       const threadId = this._threadId ?? undefined;
       // Fire-and-forget: scan logs then deliver result
       void scanCodexSessionUsage({ startedAfter: startedAt, threadId }).then((scanned) => {
@@ -1600,22 +2231,26 @@ export class CodexSessionImpl implements AgentSession {
       }).catch(() => {
         // Non-fatal — usage stays undefined
       }).finally(() => {
-        void this.deliverTurnResult(usage);
+        void this.deliverTurnResult(usage, delivering, outcome);
       });
       return;
     }
 
-    void this.deliverTurnResult(usage);
+    void this.deliverTurnResult(usage, delivering, outcome);
   }
 
-  private async deliverTurnResult(usage: Record<string, import("../../types.js").TokenUsage> | undefined): Promise<void> {
+  private async deliverTurnResult(
+    usage: Record<string, import("../../types.js").TokenUsage> | undefined,
+    delivering: ActiveTurnReady | null,
+    outcome: TurnOutcome,
+  ): Promise<void> {
     const result: TurnResult = {
-      summary: this._turnSummary,
+      summary: outcome.summary,
       usage,
       costUsd: null,
-      status: this._turnWasInterrupted ? "aborted" : this._turnIsError ? "failed" : "completed",
-      errorCode: this._turnWasInterrupted ? "aborted" : this._turnIsError ? "execution_error" : null,
-      errorMessage: this._turnWasInterrupted ? "Turn was interrupted" : this._turnErrorMessage,
+      status: outcome.wasInterrupted ? "aborted" : outcome.isError ? "failed" : "completed",
+      errorCode: outcome.wasInterrupted ? "aborted" : outcome.isError ? "execution_error" : null,
+      errorMessage: outcome.wasInterrupted ? "Turn was interrupted" : outcome.errorMessage,
     };
 
     // Drain pending onEvent handlers so callers awaiting send() see a settled
@@ -1631,22 +2266,29 @@ export class CodexSessionImpl implements AgentSession {
     // session whose stdin is dead.
     if (this._state === "closed") return;
 
-    this._state = "idle";
-
-    // Drain ALL pending send() resolvers with this turn's result. Multiple
-    // concurrent sends coalesced into one turn share the same TurnResult.
-    const pending = this._pendingResults.splice(0);
-
-    // Clear per-turn accumulators so a subsequent turn doesn't inherit
-    // stale summary / usage / model.
-    this._turnSummary = null;
-    this._turnUsage = null;
-    this._turnModel = null;
-    this._turnIsError = false;
-    this._turnWasInterrupted = false;
-    this._turnErrorMessage = null;
-    this._turnStartedAt = null;
-    this.clearActiveTurn();
+    // A send() that landed while this delivery was suspended has already begun
+    // a new turn and owns the session. Its result is still owed to it, so this
+    // delivery settles only its OWN generation and touches neither the state
+    // nor the interrupt latch the new turn needs to stay stoppable.
+    //
+    // `delivering === null` must take this branch too. A duplicate terminal
+    // frame for an already-delivered turn (codex can report failure through
+    // both `turn/completed` with a failed status and a separate `turn/failed`)
+    // reaches here with a null latch, and exempting it restored every symptom
+    // the fence exists to prevent: silent Stop, idle-while-running, and a
+    // stale settle.
+    const superseded = this._activeTurnReady !== delivering;
+
+    // Drain the pending send() resolvers belonging to this turn. Several
+    // concurrent sends coalesced into one turn share the same TurnResult; a
+    // send from a later turn is left in place for its own delivery.
+    const pending = this.takePendingResults(delivering?.generation);
+
+    if (!superseded) {
+      this._state = "idle";
+      // Accumulators were already snapshotted and cleared in resolveTurn().
+      this.clearActiveTurn(undefined, delivering ?? undefined);
+    }
 
     for (const p of pending) {
       // Skip sends already settled early by timeout / abort.
@@ -1667,8 +2309,9 @@ export class CodexSessionImpl implements AgentSession {
     // Pass current threadId so NDJSON-shaped events (via codex/event wrapper)
     // carry sessionId. v2 notifications parse threadId from params directly
     // and ignore this arg.
-    const event = parseCodexStreamLine(rawLine, this._threadId);
-    if (event) this.dispatchEvent(event);
+    for (const event of parseCodexStreamLines(rawLine, this._threadId)) {
+      this.dispatchEvent(event);
+    }
   }
 
   /**