@rynx-ai/runtime 0.1.11-beta.4 → 0.1.11-beta.41

package/dist/codex-app-server/forwarder.js

@@ -1,9 +1,23 @@
-import { codexUserContent } from "../input-resources.js";
-import { mapCodexItem, mapCodexNotification } from "./mapping.js";
+import { codexUserEchoContent } from "../input-resources.js";
+import { codexResumeTerminalStatus, mapCodexItem, mapCodexNotification, } from "./mapping.js";
+const MCP_STARTUP_STATUS_METHOD = "mcpServer/startupStatus/updated";
+const MCP_TERMINAL_STATES = new Set(["ready", "failed", "cancelled"]);
 function threadIdFrom(params) {
     const p = params;
     return p?.threadId ?? p?.thread?.id;
 }
+/** Agent-control children announce their own thread on the shared app-server.
+ * They do not replace the parent TUI thread: only a top-level thread switch is
+ * a Session rotation boundary. */
+function isSubagentThreadStarted(params) {
+    const source = params?.thread?.source?.subAgent?.thread_spawn;
+    return source !== null && typeof source === "object" && !Array.isArray(source);
+}
+/** Internal system threads are non-persistable and never replace the parent
+ * TUI thread, even though the app-server broadcasts `thread/started`. */
+function isEphemeralThreadStarted(params) {
+    return params?.thread?.ephemeral === true;
+}
 function turnIdFrom(params) {
     const p = params;
     return p?.turnId ?? p?.turn?.id;
@@ -11,14 +25,7 @@ function turnIdFrom(params) {
 function userMessageContent(item) {
     if (item.type !== "userMessage")
         return undefined;
-    const parts = codexUserContent(item.content);
-    if (parts.length === 0)
-        return undefined;
-    if (parts.every((part) => part.type === "input_text")) {
-        const text = parts.map((part) => part.text).join("").trim();
-        return text || undefined;
-    }
-    return parts;
+    return codexUserEchoContent(item.content);
 }
 /** Whether a notification implies the thread is now active (its first turn has
  *  begun, so the rollout exists). Mirrors reference implementation's `_event_indicates_thread_active`. */
@@ -31,6 +38,46 @@ function indicatesActive(method, params) {
     }
     return false;
 }
+function isThreadIdle(method, params) {
+    if (method !== "thread/status/changed")
+        return false;
+    const status = params?.status;
+    return status === "idle" || (typeof status === "object" && status?.type === "idle");
+}
+function isModelOutput(method, params) {
+    if (method !== "item/started" && method !== "item/completed")
+        return false;
+    const item = params?.item;
+    return Boolean(item?.type && item.type !== "userMessage");
+}
+function isTerminalTurnMethod(method) {
+    return method === "turn/completed" || method === "turn/failed";
+}
+/** Turn-scoped notifications must never be reassigned to whichever newer turn
+ * happens to be current when an app-server frame arrives late. */
+function isTurnScopedMethod(method) {
+    return method.startsWith("turn/") || method.startsWith("item/") ||
+        method === "queue/status" || method === "error";
+}
+/** Recover a missed turn/started only from visible, fully-scoped assistant/plan
+ * deltas. Other deltas require an already matching active turn. */
+function canRecoverMissedTurnFrom(method) {
+    return method === "item/agentMessage/delta" || method === "item/plan/delta";
+}
+/** Live deltas require the bridge's exact active Codex turn. Assistant/plan
+ * deltas may recover a missed `turn/started` when
+ * fully scoped; command output never opens or recovers a Turn. */
+function requiresMatchingActiveTurn(method) {
+    return canRecoverMissedTurnFrom(method) || method === "item/commandExecution/outputDelta";
+}
+/** Turn content that remains valid independently of lifecycle status. */
+function isIndependentTurnContent(method) {
+    return method === "item/started" ||
+        method === "item/reasoning/textDelta" ||
+        method === "item/reasoning/summaryTextDelta" ||
+        method === "item/fileChange/patchUpdated" ||
+        method === "turn/plan/updated";
+}
 export class CodexSessionForwarder {
     client;
     sink;
@@ -41,9 +88,16 @@ export class CodexSessionForwarder {
     currentThreadIdValue = null;
     activeSignaled = false;
     completionTimer = null;
+    /** Turn id retained only for late-item dedup while a terminal response waits
+     * for its bounded output-ordering grace. It is not an active provider turn. */
+    pendingCompletionTurnId = null;
     assistantMessageTimer = null;
     deferredAssistantMessage = null;
     pendingCompletion = null;
+    pendingMcpServers = new Set();
+    failedMcpServers = new Map();
+    mcpStartupTimer = null;
+    lastMcpStatusNote = null;
     /** Completed-item dedup keys already mirrored (live vs resume backfill). Key =
      *  `threadId:turnId:item.id`; anonymous items use a per-(thread,turn) position
      *  counter. Mirrors reference implementation `_completed_item_key` + `synced_item_keys`. */
@@ -51,6 +105,11 @@ export class CodexSessionForwarder {
     /** Per-(thread,turn) position counter for items lacking a stable codex id
      *  (peek-then-advance; advanced only on a successful claim). reference implementation anon path. */
     anonCounters = new Map();
+    pendingPlanImplementation = null;
+    /** Latest aggregate diff per Turn. Codex republishes the complete diff after
+     * every edit; only the terminal snapshot belongs in transcript history. */
+    turnDiffByTurn = new Map();
+    replayingBackfill = false;
     constructor(client, sink, options = {}) {
         this.client = client;
         this.sink = sink;
@@ -61,31 +120,101 @@ export class CodexSessionForwarder {
         if (this.unsubscribe)
             return;
         this.unsubscribe = this.client.onNotification((method, params) => {
-            this.handle(method, params);
+            try {
+                this.handle(method, params);
+            }
+            catch (error) {
+                // One malformed or unsupported notification must not detach the
+                // long-lived observer from every later event in this session.
+                console.error(`[codex-forwarder] notification handler failed for ${method}; continuing:`, error);
+            }
         });
+        const startup = this.options.mcpStartup;
+        if (startup?.servers.length) {
+            for (const server of startup.servers)
+                this.pendingMcpServers.add(server);
+            this.mcpStartupTimer = setTimeout(() => this.settleMcpStartup(), startup.settleTimeoutMs);
+            this.mcpStartupTimer.unref?.();
+        }
     }
     stop() {
         this.unsubscribe?.();
         this.unsubscribe = null;
+        this.clearMcpStartupTimer();
         this.flushPendingCompletion();
         this.flushDeferredAssistantMessage();
         if (this.turnOpen) {
             this.turnOpen = false;
+            this.currentTurnIdValue = null;
             this.sink.onTurnEnd();
         }
+        else {
+            this.currentTurnIdValue = null;
+        }
+        this.turnDiffByTurn.clear();
     }
-    /** True while a turn is open — injection uses `turn/steer` then, else `turn/start`. */
+    /** True while the provider owns an active turn, including the short interval
+     * between injection acceptance and observer confirmation. */
     isTurnOpen() {
-        return this.turnOpen;
+        return this.turnOpen || this.currentTurnIdValue !== null;
     }
     /** The current turn's codex id (only meaningful while {@link isTurnOpen}). */
     currentTurnId() {
         return this.currentTurnIdValue;
     }
+    /**
+     * Record a turn accepted by the injection connection before the independent
+     * observer receives `turn/started`. This closes the read-decide-RPC-write race:
+     * another web message arriving in that window must steer this turn, not start
+     * a second one.
+     */
+    noteTurnAccepted(turnId) {
+        if (!turnId)
+            return;
+        if (this.pendingCompletion)
+            this.flushPendingCompletion();
+        this.currentTurnIdValue = turnId;
+        this.emitMcpStartupStatus();
+    }
+    hasPendingMcpStartup() {
+        return this.pendingMcpServers.size > 0;
+    }
+    /** Mark and return the startup servers cancelled by a web Stop. */
+    cancelMcpStartup() {
+        const pending = [...this.pendingMcpServers].sort();
+        if (pending.length === 0)
+            return pending;
+        this.pendingMcpServers.clear();
+        this.clearMcpStartupTimer();
+        if (this.isTurnOpen()) {
+            this.emitMcpStatus(`MCP startup cancelled: ${pending.join(", ")}`);
+        }
+        return pending;
+    }
+    /** Diagnostic suffix for an injection failure during Provider startup. */
+    mcpStartupDetail() {
+        const pending = [...this.pendingMcpServers].sort();
+        if (pending.length)
+            return `MCP startup still waiting on ${pending.join(", ")}`;
+        const failed = [...this.failedMcpServers.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([name, error]) => error ? `${name}: ${error}` : name);
+        return failed.length ? `MCP startup failed for ${failed.join(", ")}` : null;
+    }
     /** The bound codex thread id captured from `thread/started` (null until then). */
     threadId() {
         return this.currentThreadIdValue;
     }
+    /** Seed an already-persisted/resumed thread binding. The bridge retains this
+     * state even when app-server does not rebroadcast `thread/started`, so
+     * terminal-boundary recovery must know it too. */
+    noteThreadBound(threadId) {
+        if (!threadId || this.currentThreadIdValue === threadId)
+            return;
+        if (this.currentThreadIdValue !== null || this.turnOpen)
+            return;
+        this.currentThreadIdValue = threadId;
+    }
     /**
      * Replay the backlog turns from a `thread/resume` response as if they were live
      * `item/completed` notifications — the fresh-thread first-turn backfill. Each
@@ -94,25 +223,52 @@ export class CodexSessionForwarder {
      * not doubled.
      */
     replayBackfill(turns) {
-        for (const turn of turns) {
-            const turnId = turn.id ?? turn.turnId;
-            if (turnId)
-                this.currentTurnIdValue = turnId;
-            this.ensureTurn();
-            for (const item of turn.items ?? [])
-                this.processCompletedItem(item);
-            if (turn.status === "inProgress")
-                continue;
-            const mapped = mapCodexNotification("turn/completed", { turn });
-            this.turnOpen = false;
-            if (mapped.fatalError)
-                this.sink.onTurnError(mapped.fatalError);
-            else
-                this.sink.onTurnEnd(mapped.usage);
+        this.replayingBackfill = true;
+        try {
+            for (const turn of turns) {
+                const turnId = turn.id ?? turn.turnId;
+                if (turnId)
+                    this.currentTurnIdValue = turnId;
+                this.ensureTurn();
+                for (const item of turn.items ?? [])
+                    this.processCompletedItem(item);
+                if (codexResumeTerminalStatus(turn) === undefined)
+                    continue;
+                const mapped = mapCodexNotification("turn/completed", { turn });
+                this.turnOpen = false;
+                this.currentTurnIdValue = null;
+                if (mapped.fatalError)
+                    this.sink.onTurnError(mapped.fatalError);
+                else
+                    this.sink.onTurnEnd(mapped.usage);
+            }
+        }
+        finally {
+            this.replayingBackfill = false;
         }
     }
+    /** Suppress our synthesized picker when a future app-server emits the native
+     * `plan_implementation` request itself. */
+    noteNativePlanImplementationPrompt(turnId) {
+        if (!this.pendingPlanImplementation)
+            return;
+        if (!turnId || this.pendingPlanImplementation.turnId === turnId) {
+            this.pendingPlanImplementation = null;
+        }
+    }
+    /** Fail an open response exactly once when its observer or terminal exits. */
+    failOpenTurn(error) {
+        if (!this.isTurnOpen())
+            return false;
+        this.ensureTurn();
+        this.settle({ kind: "error", error });
+        return true;
+    }
     handle(method, params) {
         if (method === "thread/started" || method === "thread.started") {
+            if (method === "thread/started" &&
+                (isSubagentThreadStarted(params) || isEphemeralThreadStarted(params)))
+                return;
             const tid = threadIdFrom(params);
             if (tid && tid !== this.currentThreadIdValue) {
                 const forkedFromId = params?.thread?.forkedFromId;
@@ -128,6 +284,7 @@ export class CodexSessionForwarder {
                 }
                 this.currentTurnIdValue = null;
                 this.activeSignaled = false;
+                this.turnDiffByTurn.clear();
                 this.currentThreadIdValue = tid;
                 this.sink.onThreadStarted?.(tid, normalizedForkedFromId);
             }
@@ -138,6 +295,33 @@ export class CodexSessionForwarder {
             notificationThreadId &&
             notificationThreadId !== this.currentThreadIdValue)
             return;
+        if (method === MCP_STARTUP_STATUS_METHOD) {
+            this.handleMcpStartupStatus(params);
+            return;
+        }
+        if (method === "thread/settings/updated") {
+            const threadSettings = params?.threadSettings;
+            const model = typeof threadSettings?.model === "string" && threadSettings.model.trim()
+                ? threadSettings.model.trim()
+                : undefined;
+            const effort = threadSettings?.effort;
+            if (model !== undefined || effort === null || typeof effort === "string") {
+                this.sink.onThreadSettingsChanged?.({
+                    ...(model === undefined ? {} : { model }),
+                    ...(effort === null || typeof effort === "string"
+                        ? { reasoningEffort: effort }
+                        : {}),
+                });
+            }
+            const mode = (threadSettings?.collaborationMode ?? threadSettings?.collaboration_mode)?.mode;
+            if (mode === "plan" || mode === "default") {
+                this.sink.onCollaborationModeChanged?.(mode);
+            }
+            return;
+        }
+        if (isThreadIdle(method, params) || isModelOutput(method, params)) {
+            this.settleMcpStartup();
+        }
         // Release a parked resume as soon as the thread shows activity (rollout now
         // exists). Fire once.
         if (!this.activeSignaled && indicatesActive(method, params)) {
@@ -148,33 +332,147 @@ export class CodexSessionForwarder {
         // behavior unchanged unless the Traex host explicitly opts in.
         if (method === "queue/status" && !this.options.surfaceQueueStatus)
             return;
+        if (method === "queue/status" && this.currentTurnIdValue === null)
+            return;
         const carriedTurnId = turnIdFrom(params);
+        if (method === "turn/diff/updated") {
+            if (!carriedTurnId)
+                return;
+            const update = params;
+            const diff = typeof update?.diff === "string"
+                ? update.diff
+                : typeof update?.unifiedDiff === "string"
+                    ? update.unifiedDiff
+                    : "";
+            if (diff)
+                this.turnDiffByTurn.set(carriedTurnId, diff);
+            else
+                this.turnDiffByTurn.delete(carriedTurnId);
+            return;
+        }
         if (method === "turn/started") {
-            this.flushPendingCompletion();
-            this.flushDeferredAssistantMessage();
-            if (carriedTurnId)
+            this.beginTurn(carriedTurnId);
+            this.sink.onTurnObserved?.(carriedTurnId);
+            return;
+        }
+        if (isTerminalTurnMethod(method)) {
+            if (!this.terminalBoundaryMatchesActiveTurn(carriedTurnId, notificationThreadId)) {
+                const staleDiff = this.consumeTurnDiff(carriedTurnId);
+                if (staleDiff && carriedTurnId) {
+                    this.sink.onTurnContentEvent?.(carriedTurnId, staleDiff);
+                }
+                return;
+            }
+            const hadActiveTurn = this.currentTurnIdValue !== null;
+            const hadOpenResponse = this.turnOpen;
+            const mapped = mapCodexNotification(method, params);
+            const terminalTurnId = carriedTurnId ?? this.currentTurnIdValue;
+            const turnDiff = this.consumeTurnDiff(terminalTurnId);
+            if (!hadActiveTurn && !hadOpenResponse) {
+                if (turnDiff && terminalTurnId) {
+                    this.sink.onTurnContentEvent?.(terminalTurnId, turnDiff);
+                }
+                const turn = params?.turn;
+                const recoveredStatus = mapped.fatalError ||
+                    method === "turn/failed" ||
+                    codexResumeTerminalStatus(turn) === "failed"
+                    ? "failed"
+                    : "idle";
+                this.sink.onRecoveredTurnStatus?.(recoveredStatus, carriedTurnId, mapped.fatalError);
+                return;
+            }
+            if (carriedTurnId && this.currentTurnIdValue === null) {
                 this.currentTurnIdValue = carriedTurnId;
+            }
             this.ensureTurn();
+            this.pendingCompletionTurnId = carriedTurnId ?? this.currentTurnIdValue;
+            // The provider lifecycle closes immediately. A configured grace keeps
+            // only the canonical response open long enough to absorb late items.
+            this.currentTurnIdValue = null;
+            for (const event of mapped.events.filter((event) => event.type !== "runtime_debug")) {
+                this.sink.onEvent(event);
+            }
+            this.scheduleCompletion(mapped.fatalError
+                ? { kind: "error", error: mapped.fatalError, ...(turnDiff ? { turnDiff } : {}) }
+                : mapped.turnInterrupted
+                    ? {
+                        kind: "interrupted",
+                        ...(mapped.usage ? { usage: mapped.usage } : {}),
+                        ...(turnDiff ? { turnDiff } : {}),
+                    }
+                    : {
+                        kind: "end",
+                        ...(mapped.usage ? { usage: mapped.usage } : {}),
+                        ...(turnDiff ? { turnDiff } : {}),
+                    });
             return;
         }
-        if (carriedTurnId)
-            this.currentTurnIdValue = carriedTurnId;
+        // A late event from an older turn must not replace the app-server's active
+        // turn id. That was the source of stale completions closing a newer turn.
+        if (carriedTurnId &&
+            this.currentTurnIdValue &&
+            carriedTurnId !== this.currentTurnIdValue &&
+            isTurnScopedMethod(method)) {
+            // Durable completed items and passive content belong to their carried
+            // response even if a newer Turn is active. Only active-turn deltas and
+            // lifecycle edges are stale with respect to the newer Turn.
+            if (method === "item/completed") {
+                // Continue into the completed-item dedup/order path below.
+            }
+            else if (isIndependentTurnContent(method) && this.sink.onTurnContentEvent) {
+                const mapped = mapCodexNotification(method, params);
+                for (const event of mapped.events) {
+                    if (event.type !== "runtime_debug") {
+                        this.sink.onTurnContentEvent(carriedTurnId, event);
+                    }
+                }
+                return;
+            }
+            else {
+                return;
+            }
+        }
+        if (requiresMatchingActiveTurn(method)) {
+            if (this.currentTurnIdValue !== null) {
+                // An id-less delta is not attributable to the active Turn. Require
+                // the exact active Turn id before forwarding it.
+                if (carriedTurnId !== this.currentTurnIdValue)
+                    return;
+            }
+            else if (carriedTurnId &&
+                canRecoverMissedTurnFrom(method) &&
+                this.notificationMatchesCurrentThread(notificationThreadId)) {
+                this.currentTurnIdValue = carriedTurnId;
+                this.ensureTurn();
+            }
+            else {
+                return;
+            }
+        }
         // Completed items (user echo, assistant, tool, reasoning) go through the
         // deduped path so a resume backfill and the live stream never double them.
         if (method === "item/completed") {
             const item = params?.item;
             if (item) {
+                if (carriedTurnId &&
+                    this.currentTurnIdValue &&
+                    carriedTurnId !== this.currentTurnIdValue) {
+                    // This is durable content for an older response, not an ordering
+                    // signal for the newer Turn's deferred assistant message.
+                    this.processCompletedItem(item, carriedTurnId);
+                    return;
+                }
                 if (this.shouldDeferAssistantMessage(item)) {
-                    this.deferAssistantMessage(item);
+                    this.deferAssistantMessage(item, carriedTurnId);
                     this.refreshCompletionGrace();
                     return;
                 }
-                // A late reasoning item belongs before the held final answer. Any other
-                // completed item establishes that the held message was not final and
-                // must retain its original position.
+                // Within one Turn, a late reasoning item belongs before the held final
+                // answer. Any other completed item establishes that the held message
+                // was not final and must retain its original position.
                 if (item.type !== "reasoning")
                     this.flushDeferredAssistantMessage();
-                this.processCompletedItem(item);
+                this.processCompletedItem(item, carriedTurnId);
                 this.refreshCompletionGrace();
                 return;
             }
@@ -189,6 +487,19 @@ export class CodexSessionForwarder {
         if (canonicalEvents.some((event) => event.type !== "reasoning_delta" && event.type !== "reasoning_completed")) {
             this.flushDeferredAssistantMessage();
         }
+        // Item/content delivery is independent from turn lifecycle status. A
+        // scoped item or reasoning delta that arrives after the terminal
+        // edge remains visible, but must not synthesize another running response.
+        if (!this.turnOpen &&
+            this.currentTurnIdValue === null &&
+            !mapped.fatalError &&
+            canonicalEvents.length > 0 &&
+            this.sink.onTurnContentEvent) {
+            for (const event of canonicalEvents) {
+                this.sink.onTurnContentEvent(carriedTurnId, event);
+            }
+            return;
+        }
         if (canonicalEvents.length || mapped.turnCompleted || mapped.fatalError) {
             this.ensureTurn();
         }
@@ -200,7 +511,9 @@ export class CodexSessionForwarder {
             return;
         }
         if (mapped.turnCompleted) {
-            this.scheduleCompletion({ kind: "end", ...(mapped.usage ? { usage: mapped.usage } : {}) });
+            this.scheduleCompletion(mapped.turnInterrupted
+                ? { kind: "interrupted", ...(mapped.usage ? { usage: mapped.usage } : {}) }
+                : { kind: "end", ...(mapped.usage ? { usage: mapped.usage } : {}) });
         }
         else {
             this.refreshCompletionGrace();
@@ -237,39 +550,150 @@ export class CodexSessionForwarder {
     }
     settle(completion) {
         this.flushDeferredAssistantMessage();
+        const completedTurnId = this.pendingCompletionTurnId ?? this.currentTurnIdValue;
+        const planPrompt = completion.kind === "end" &&
+            this.pendingPlanImplementation?.turnId === completedTurnId
+            ? this.pendingPlanImplementation
+            : null;
+        if (this.pendingPlanImplementation?.turnId === completedTurnId) {
+            this.pendingPlanImplementation = null;
+        }
+        if (completion.turnDiff)
+            this.sink.onEvent(completion.turnDiff);
+        if (completedTurnId)
+            this.turnDiffByTurn.delete(completedTurnId);
         this.turnOpen = false;
+        this.currentTurnIdValue = null;
+        this.pendingCompletionTurnId = null;
         if (completion.kind === "error")
             this.sink.onTurnError(completion.error);
-        else
+        else if (completion.kind === "interrupted") {
+            if (this.sink.onTurnInterrupted)
+                this.sink.onTurnInterrupted(completion.usage);
+            else
+                this.sink.onTurnEnd(completion.usage);
+        }
+        else {
             this.sink.onTurnEnd(completion.usage);
+            if (planPrompt)
+                this.sink.onPlanImplementationPrompt?.(planPrompt);
+        }
+    }
+    handleMcpStartupStatus(params) {
+        const update = params;
+        const name = typeof update?.name === "string" ? update.name : "";
+        const status = typeof update?.status === "string" ? update.status : "";
+        if (!name || (status !== "starting" && !MCP_TERMINAL_STATES.has(status)))
+            return;
+        if (status === "starting") {
+            this.pendingMcpServers.add(name);
+            this.failedMcpServers.delete(name);
+        }
+        else {
+            this.pendingMcpServers.delete(name);
+            if (status === "failed") {
+                this.failedMcpServers.set(name, typeof update?.error === "string" && update.error ? update.error : undefined);
+            }
+            else {
+                this.failedMcpServers.delete(name);
+            }
+            if (this.pendingMcpServers.size === 0)
+                this.clearMcpStartupTimer();
+        }
+        this.emitMcpStartupStatus();
+    }
+    settleMcpStartup() {
+        if (this.pendingMcpServers.size === 0) {
+            this.clearMcpStartupTimer();
+            return;
+        }
+        this.pendingMcpServers.clear();
+        this.clearMcpStartupTimer();
+        this.emitMcpStartupStatus();
+    }
+    clearMcpStartupTimer() {
+        if (this.mcpStartupTimer)
+            clearTimeout(this.mcpStartupTimer);
+        this.mcpStartupTimer = null;
+    }
+    emitMcpStartupStatus() {
+        if (!this.isTurnOpen())
+            return;
+        const pending = [...this.pendingMcpServers].sort();
+        if (pending.length) {
+            this.emitMcpStatus(`Starting MCP servers: ${pending.join(", ")}`);
+            return;
+        }
+        const failed = [...this.failedMcpServers.keys()].sort();
+        if (failed.length) {
+            this.emitMcpStatus(`MCP startup failed: ${failed.join(", ")}`);
+            return;
+        }
+        if (this.lastMcpStatusNote !== null) {
+            this.lastMcpStatusNote = null;
+            if (this.sink.onStatus)
+                this.sink.onStatus(undefined);
+            else
+                this.sink.onEvent({ type: "status" });
+        }
+    }
+    emitMcpStatus(note) {
+        if (this.lastMcpStatusNote === note)
+            return;
+        this.lastMcpStatusNote = note;
+        if (this.sink.onStatus)
+            this.sink.onStatus(note, "startup");
+        else
+            this.sink.onEvent({ type: "status", statusKind: "startup", note });
     }
     /** Map + emit one completed codex item, deduped by a TOTAL key and routing the
      *  user echo to {@link CodexForwarderSink.onUserMessage}. Shared by live + backfill. */
-    processCompletedItem(item) {
-        if (!this.claimCompletedItem(item))
+    processCompletedItem(item, completedTurnId) {
+        if (!this.claimCompletedItem(item, completedTurnId))
             return;
-        this.emitCompletedItem(item);
+        this.emitCompletedItem(item, completedTurnId);
     }
-    claimCompletedItem(item) {
-        const { key, isAnon } = this.completedItemKey(item);
+    claimCompletedItem(item, completedTurnId) {
+        const { key, isAnon } = this.completedItemKey(item, completedTurnId);
         if (this.seenCompletedItems.has(key))
             return false;
         this.seenCompletedItems.add(key);
         if (isAnon)
-            this.advanceAnonCounter();
+            this.advanceAnonCounter(completedTurnId);
         return true;
     }
-    emitCompletedItem(item) {
+    emitCompletedItem(item, completedTurnId) {
+        const outsideTurnLifecycle = !this.turnOpen || Boolean(completedTurnId &&
+            this.currentTurnIdValue &&
+            completedTurnId !== this.currentTurnIdValue);
         const userContent = userMessageContent(item);
         if (userContent !== undefined) {
+            if (outsideTurnLifecycle && this.sink.onTurnContentUserMessage) {
+                this.sink.onTurnContentUserMessage(completedTurnId, userContent);
+                return;
+            }
             this.ensureTurn();
             this.sink.onUserMessage?.(userContent);
             return;
         }
+        if (item.type === "plan" && !this.replayingBackfill) {
+            const text = item.text?.trim();
+            const turnId = this.currentTurnIdValue ?? this.pendingCompletionTurnId;
+            const threadId = this.currentThreadIdValue;
+            if (text && turnId && threadId) {
+                this.pendingPlanImplementation = { threadId, turnId, text };
+            }
+        }
         const mapped = mapCodexItem("item/completed", item);
         const canonicalEvents = mapped.events.filter((event) => event.type !== "runtime_debug");
         if (canonicalEvents.length === 0)
             return;
+        if (outsideTurnLifecycle && this.sink.onTurnContentEvent) {
+            for (const event of canonicalEvents) {
+                this.sink.onTurnContentEvent(completedTurnId, event);
+            }
+            return;
+        }
         this.ensureTurn();
         for (const event of canonicalEvents)
             this.sink.onEvent(event);
@@ -280,11 +704,11 @@ export class CodexSessionForwarder {
         }
         return Boolean(item.text?.trim());
     }
-    deferAssistantMessage(item) {
-        if (!this.claimCompletedItem(item))
+    deferAssistantMessage(item, turnId) {
+        if (!this.claimCompletedItem(item, turnId))
             return;
         this.flushDeferredAssistantMessage();
-        this.deferredAssistantMessage = item;
+        this.deferredAssistantMessage = { item, ...(turnId ? { turnId } : {}) };
         const graceMs = this.options.assistantMessageGraceMs ?? 0;
         this.assistantMessageTimer = setTimeout(() => this.flushDeferredAssistantMessage(), graceMs);
         this.assistantMessageTimer.unref?.();
@@ -293,26 +717,27 @@ export class CodexSessionForwarder {
         if (this.assistantMessageTimer)
             clearTimeout(this.assistantMessageTimer);
         this.assistantMessageTimer = null;
-        const item = this.deferredAssistantMessage;
+        const deferred = this.deferredAssistantMessage;
         this.deferredAssistantMessage = null;
-        if (item)
-            this.emitCompletedItem(item);
+        if (deferred)
+            this.emitCompletedItem(deferred.item, deferred.turnId);
     }
     /** Build a total dedup key for one completed item. Stable-id items use
      *  `threadId:turnId:item.id` — identical across replay + live, so the second
      *  delivery is dropped. Items without a codex id fall back to a per-(thread,turn)
      *  position counter (peeked here; advanced only on a successful claim, via
      *  {@link advanceAnonCounter}). Mirrors reference implementation `_completed_item_key`. */
-    completedItemKey(item) {
+    completedItemKey(item, completedTurnId) {
         const threadId = this.currentThreadIdValue ?? "thread";
-        const turnId = this.currentTurnIdValue ?? "turn";
+        const turnId = completedTurnId ?? this.currentTurnIdValue ?? this.pendingCompletionTurnId ?? "turn";
         if (item.id)
             return { key: `${threadId}:${turnId}:${item.id}`, isAnon: false };
         const n = this.anonCounters.get(`${threadId}:${turnId}`) ?? 0;
         return { key: `${threadId}:${turnId}:anon:${n}`, isAnon: true };
     }
-    advanceAnonCounter() {
-        const k = `${this.currentThreadIdValue ?? "thread"}:${this.currentTurnIdValue ?? "turn"}`;
+    advanceAnonCounter(completedTurnId) {
+        const turnId = completedTurnId ?? this.currentTurnIdValue ?? this.pendingCompletionTurnId ?? "turn";
+        const k = `${this.currentThreadIdValue ?? "thread"}:${turnId}`;
         this.anonCounters.set(k, (this.anonCounters.get(k) ?? 0) + 1);
     }
     ensureTurn() {
@@ -321,4 +746,54 @@ export class CodexSessionForwarder {
             this.sink.onTurnStart(this.currentTurnIdValue ?? undefined);
         }
     }
+    consumeTurnDiff(turnId) {
+        if (!turnId)
+            return undefined;
+        const diff = this.turnDiffByTurn.get(turnId);
+        this.turnDiffByTurn.delete(turnId);
+        return diff
+            ? { type: "turn_diff", callId: `codex_turn_diff_${turnId}`, diff }
+            : undefined;
+    }
+    /** Start (or confirm) the app-server's authoritative active turn. A newer
+     * start supersedes an older response whose terminal edge arrived late; a
+     * pending Traex completion is flushed first so its final item grace remains
+     * intact. */
+    beginTurn(turnId) {
+        if (this.pendingCompletion)
+            this.flushPendingCompletion();
+        const nextTurnId = turnId ?? null;
+        const changesIdentifiedTurn = this.turnOpen &&
+            this.currentTurnIdValue !== null &&
+            nextTurnId !== null &&
+            this.currentTurnIdValue !== nextTurnId;
+        if (changesIdentifiedTurn) {
+            this.flushPendingCompletion();
+            this.flushDeferredAssistantMessage();
+            if (this.turnOpen) {
+                this.turnOpen = false;
+                this.sink.onTurnEnd(undefined, "superseded");
+            }
+        }
+        this.currentTurnIdValue = nextTurnId;
+        this.ensureTurn();
+    }
+    /** Active-turn clearing contract:
+     *
+     * - an identified active turn is closed only by the same id;
+     * - an id-less boundary cannot close an identified active turn;
+     * - with no observed active turn, an identified boundary may recover a
+     *   missed start only when it carries the currently-bound thread id. */
+    terminalBoundaryMatchesActiveTurn(terminalTurnId, notificationThreadId) {
+        if (this.currentTurnIdValue !== null) {
+            return terminalTurnId === this.currentTurnIdValue;
+        }
+        if (terminalTurnId === undefined)
+            return true;
+        return this.notificationMatchesCurrentThread(notificationThreadId);
+    }
+    notificationMatchesCurrentThread(notificationThreadId) {
+        return this.currentThreadIdValue !== null &&
+            notificationThreadId === this.currentThreadIdValue;
+    }
 }