@agentex/agent 0.0.33 → 0.0.35

package/dist/providers/codex/session.js

@@ -9,7 +9,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";
@@ -89,6 +89,8 @@ function buildCodexUserInputAnswers(questions, resp) {
     }
     return out;
 }
+const BACKGROUND_TASK_POLL_INTERVAL_MS = 2_000;
+const BACKGROUND_TASK_READ_TIMEOUT_MS = 5_000;
 // ---------------------------------------------------------------------------
 // JSON-RPC 2.0 helpers
 // ---------------------------------------------------------------------------
@@ -116,6 +118,30 @@ function asObj(parent, key) {
         ? v
         : {};
 }
+function obj(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string" && entry.length > 0)
+        : [];
+}
+function codexAgentState(value) {
+    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 };
+}
 function classifyMessage(msg) {
     // Detect JSON-RPC by *structure*, not by the `jsonrpc:"2.0"` discriminator.
     // codex-cli 0.130.0's `app-server` emits responses without the `jsonrpc`
@@ -279,6 +305,8 @@ export class CodexSessionImpl {
      */
     _activeTurnId = null;
     _activeTurnReady = null;
+    /** Incremented per turn latch. Never reused, so staleness is decidable. */
+    _turnGeneration = 0;
     /** Successful repeated interrupts coalesce until the terminal notification. */
     _interruptPromise = null;
     /** Prevents a late interrupt request after the terminal frame was observed. */
@@ -297,6 +325,10 @@ export class CodexSessionImpl {
     /** Child-agent lifecycle is informational and never participates in root turn settlement. */
     _backgroundTasks = new Map();
     _backgroundTaskIdsByPath = new Map();
+    /** One protocol-native thread/read poller per child when Codex does not multiplex its notifications. */
+    _backgroundTaskPollers = new Map();
+    /** Cancellable retry delay for each poller. Cleared when the session closes. */
+    _backgroundTaskPollTimers = new Map();
     /**
      * Serial dispatch chain for `onEvent`. Each dispatched event appends a
      * handler invocation; the chain enforces in-order delivery and lets
@@ -364,17 +396,66 @@ export class CodexSessionImpl {
         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);
             }
         });
         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);
             }
         });
     }
+    cancelBackgroundTaskPollTimers() {
+        for (const pending of this._backgroundTaskPollTimers.values()) {
+            clearTimeout(pending.timer);
+            pending.resolve();
+        }
+        this._backgroundTaskPollTimers.clear();
+    }
+    finalizeActiveBackgroundTasks(status, summary, raw) {
+        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.
+     */
+    takePendingResults(generation) {
+        const mine = [];
+        const others = [];
+        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. */
     rejectAllPending(err) {
         const pending = this._pendingResults.splice(0);
@@ -408,6 +489,7 @@ export class CodexSessionImpl {
             resolve: resolveFn,
             reject: rejectFn,
             settled: false,
+            generation: ++this._turnGeneration,
         };
         this._activeTurnId = null;
         this._activeTurnReady = ready;
@@ -433,9 +515,17 @@ export class CodexSessionImpl {
         expected.settled = true;
         expected.reject(err);
     }
-    /** Clear the current turn and release an interrupt waiting for its id. */
-    clearActiveTurn(err) {
+    /**
+     * 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.
+     */
+    clearActiveTurn(err, expected) {
         const ready = this._activeTurnReady;
+        if (expected && ready !== expected)
+            return;
         if (ready && !ready.settled) {
             ready.settled = true;
             if (err)
@@ -488,6 +578,30 @@ export class CodexSessionImpl {
             this._pendingRpc.set(id, { resolve, reject });
         });
     }
+    /** A bounded RPC whose pending-map entry is removed if Codex never replies. */
+    boundedRpcRequest(method, params, timeoutMs = BACKGROUND_TASK_READ_TIMEOUT_MS) {
+        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
@@ -616,9 +730,17 @@ export class CodexSessionImpl {
         // 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";
             this._turnStartedAt = new Date();
@@ -648,7 +770,11 @@ export class CodexSessionImpl {
             resolveFn = resolve;
             rejectFn = reject;
         });
-        const entry = { resolve: resolveFn, reject: rejectFn };
+        const entry = {
+            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.
         this._inFlight.add(result);
@@ -843,6 +969,14 @@ export class CodexSessionImpl {
         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();
         // Grace window before SIGKILL is configurable via ProviderConfig.graceSec
@@ -925,13 +1059,22 @@ export class CodexSessionImpl {
             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") {
             // `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, {});
         }
     }
@@ -947,13 +1090,24 @@ export class CodexSessionImpl {
         this._state = this._pendingResults.length > 0 ? "thinking" : "idle";
     }
     async handleApproval(id, method, params) {
-        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;
         }
         const toolName = method === "item/commandExecution/requestApproval"
@@ -963,15 +1117,66 @@ export class CodexSessionImpl {
             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.
+     */
+    async handlePermissionsApproval(id, params) {
+        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();
     }
     /**
      * Handle a Codex `requestUserInput` server→client request: the agent is asking
@@ -980,29 +1185,41 @@ export class CodexSessionImpl {
      * back in Codex's `{ answers: { [questionId]: { answers: string[] } } }` shape.
      */
     async handleUserInputRequest(id, params) {
+        // 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);
         // No host handler, or nothing answerable → return empty answers so the
         // agent proceeds without hanging.
         if (!this.ctx.onUserInputRequest || questions.length === 0) {
             this.rpcResponse(id, { answers: {} });
-            this.restoreStateAfter("waiting_for_input");
+            restore();
             return;
         }
         try {
             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();
     }
     // -------------------------------------------------------------------------
     // Notification handling (v2 format)
@@ -1046,6 +1263,253 @@ export class CodexSessionImpl {
         }
         return null;
     }
+    backgroundTaskEvent(taskId, phase, status, options) {
+        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,
+        };
+    }
+    reconciledBackgroundTaskRaw(threadId, turn) {
+        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. */
+    handleCollabAgentToolCall(item, raw, parentTaskId) {
+        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", 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;
+    }
+    waitForBackgroundTaskPoll(pollKey) {
+        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 });
+        });
+    }
+    startBackgroundTaskPoller(taskId) {
+        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;
+        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 });
+    }
+    async pollBackgroundTask(taskId, generation, pollKey) {
+        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. */
+    observeBackgroundTaskThread(response, taskId, generation) {
+        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 = 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
@@ -1060,6 +1524,10 @@ export class CodexSessionImpl {
         // 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;
         const parentTaskId = event.parentTaskId
@@ -1068,15 +1536,40 @@ export class CodexSessionImpl {
         event.description = description;
         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;
     }
     /**
@@ -1093,8 +1586,21 @@ export class CodexSessionImpl {
             // 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)
+            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
                 ? asObj(source, "subAgent")
@@ -1138,6 +1644,7 @@ export class CodexSessionImpl {
                 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;
@@ -1166,6 +1673,10 @@ export class CodexSessionImpl {
         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)
@@ -1205,10 +1716,19 @@ export class CodexSessionImpl {
                 : null,
             turnId,
             parentToolCallId: null,
-            raw: parseJson(rawLine) ?? params,
+            raw: {
+                method,
+                reconciled: false,
+                threadId: childThreadId,
+                turnId,
+                status: nativeStatus || null,
+                error: errorMessage || null,
+            },
         });
     }
     handleNotification(method, params, rawLine) {
+        if (this._state === "closed")
+            return;
         // codex/event — legacy wrapper
         if (method === "codex/event") {
             const innerMsg = str(params, "msg");
@@ -1251,6 +1771,17 @@ export class CodexSessionImpl {
         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;
         }
@@ -1286,6 +1817,8 @@ export class CodexSessionImpl {
     // Legacy event handling (NDJSON events with `type` field)
     // -------------------------------------------------------------------------
     handleLegacyEvent(event, rawLine) {
+        if (this._state === "closed")
+            return;
         const type = str(event, "type");
         const eventThreadId = str(event, "thread_id") || str(event, "threadId") || str(event, "session_id") || null;
         // Older NDJSON-shaped events can also carry explicit thread scope. Keep
@@ -1418,10 +1951,35 @@ export class CodexSessionImpl {
         this.resolveTurn();
     }
     resolveTurn() {
+        // 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 = {
+            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.
@@ -1431,8 +1989,8 @@ export class CodexSessionImpl {
         // 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) => {
@@ -1440,20 +1998,20 @@ export class CodexSessionImpl {
             }).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);
     }
-    async deliverTurnResult(usage) {
+    async deliverTurnResult(usage, delivering, outcome) {
         const result = {
-            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
         // DB / log / UI state by the time TurnResult resolves. The chain snapshot
@@ -1467,20 +2025,27 @@ export class CodexSessionImpl {
         // 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.
             if (p.settled)
@@ -1500,9 +2065,9 @@ export class CodexSessionImpl {
         // 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)
+        for (const event of parseCodexStreamLines(rawLine, this._threadId)) {
             this.dispatchEvent(event);
+        }
     }
     /**
      * Queue an event for in-order delivery to `onEvent`. Each call appends a