@rynx-ai/runtime 0.1.11-beta.24 → 0.1.11-beta.26

package/dist/host.js

@@ -11,6 +11,7 @@ import { createCodexChildEnv } from "./codex-child-env.js";
 import { prepareRuntimeHome, populateCodexSkills, runtimeHomePath, } from "./codex-home.js";
 import { materializeClaudePlugin, reuseClaudePlugin, } from "./claude/executor.js";
 import { listClaudeModels } from "./claude/models.js";
+import { validateInteractionResolution } from "./interactions.js";
 import { CodexAppServerClient, buildRuntimeUserInput, } from "./codex-app-server/client.js";
 import { buildAppServerBaseArgs, CodexTransportError, } from "./codex-app-server/transport.js";
 import { WsRpcChannel, ExternalWsChannel } from "./codex-app-server/ws-channel.js";
@@ -20,7 +21,7 @@ import { buildCodexRemoteArgs } from "./terminal/codex-tui.js";
 import { buildClaudeTuiArgs } from "./terminal/claude-tui.js";
 import { providerAdditionalDirs, threadWorkspaceParams, turnWorkspaceParams, } from "./provider-workspace.js";
 import { ensureProjectTrusted } from "./claude/trust.js";
-import { claudeAttachmentToken, claudeInputText, runtimeUserContent, } from "./input-resources.js";
+import { claudeAttachmentToken, claudeInputText, codexUserEchoContent, runtimeUserContent, } from "./input-resources.js";
 import { claudeBridgeDir, prepareClaudeBridgeDir, removeManagedClaudeSettings, writeManagedClaudeSettings, } from "./claude/native-bridge.js";
 import { ClaudeLiveSession, injectViaTerminal, } from "./claude/native-integration.js";
 import { buildClaudeHookSettings } from "./claude/native-hooks.js";
@@ -192,6 +193,85 @@ function providerPluginSkillName(namespace, name) {
     return `${namespace.slice(0, 48)}-${name.slice(0, 65)}-${digest}`;
 }
 const MAX_CODEX_SETTLED_INTERACTIONS = 512;
+const CODEX_PLAN_IMPLEMENTATION_YES = "Yes, implement this plan";
+const CODEX_PLAN_IMPLEMENTATION_CLEAR_CONTEXT = "Yes, clear context and implement";
+const CODEX_PLAN_IMPLEMENTATION_NO = "No, stay in Plan mode";
+const CODEX_PLAN_IMPLEMENTATION_CODING_MESSAGE = "Implement the plan.";
+const CODEX_PLAN_PROMPT_DISMISS_TIMEOUT_MS = 1_500;
+const CODEX_PLAN_PROMPT_DISMISS_POLL_MS = 50;
+const CODEX_PLAN_IMPLEMENTATION_CLEAR_CONTEXT_PREFIX = "A previous agent produced the plan below to accomplish the user's task. " +
+    "Implement the plan in a fresh context. Treat the plan as the source of " +
+    "user intent, re-read files as needed, and carry the work through " +
+    "implementation and verification.";
+function codexPlanImplementationRequest(interactionId) {
+    return {
+        interactionId,
+        kind: "question",
+        title: "Plan",
+        fields: [{
+                id: "plan_implementation",
+                type: "select",
+                label: "Implement this plan?",
+                required: true,
+                options: [
+                    {
+                        value: CODEX_PLAN_IMPLEMENTATION_YES,
+                        label: CODEX_PLAN_IMPLEMENTATION_YES,
+                        description: "Switch to Default and start coding.",
+                    },
+                    {
+                        value: CODEX_PLAN_IMPLEMENTATION_CLEAR_CONTEXT,
+                        label: CODEX_PLAN_IMPLEMENTATION_CLEAR_CONTEXT,
+                        description: "Fresh thread with this plan.",
+                    },
+                    {
+                        value: CODEX_PLAN_IMPLEMENTATION_NO,
+                        label: CODEX_PLAN_IMPLEMENTATION_NO,
+                        description: "Continue planning with the model.",
+                    },
+                ],
+            }],
+        actions: [{ id: "submit", label: "Submit", style: "primary", requiresAnswers: true }],
+        createdAt: Date.now(),
+    };
+}
+function codexPlanImplementationPromptVisible(pane) {
+    return pane.includes("Implement this plan?") &&
+        pane.includes(CODEX_PLAN_IMPLEMENTATION_YES) &&
+        pane.includes(CODEX_PLAN_IMPLEMENTATION_NO);
+}
+/** Codex's final Plan picker is owned by the TUI and is not an app-server
+ * request that Web can resolve. Once the synthetic Web form takes ownership,
+ * close only that exact picker with its documented Escape action. The owner
+ * predicate is checked both before and after capture: app-server notifications
+ * cannot interleave between the two synchronous tmux calls, so a newly observed
+ * Turn cannot receive a blind Escape. This is deliberately best-effort — a
+ * cosmetic Terminal redraw failure must not make an otherwise valid Web Plan
+ * decision fail when the structured app-server path can still proceed. */
+async function dismissCodexPlanImplementationPrompt(injector, ownsPrompt) {
+    if (!injector || !ownsPrompt())
+        return "not_visible";
+    try {
+        const pane = injector.capturePane();
+        if (!ownsPrompt())
+            return "superseded";
+        if (!codexPlanImplementationPromptVisible(pane))
+            return "not_visible";
+        injector.interrupt();
+        const deadline = Date.now() + CODEX_PLAN_PROMPT_DISMISS_TIMEOUT_MS;
+        while (ownsPrompt()) {
+            if (!codexPlanImplementationPromptVisible(injector.capturePane()))
+                return "dismissed";
+            if (Date.now() >= deadline)
+                return "failed";
+            await new Promise((resolve) => setTimeout(resolve, CODEX_PLAN_PROMPT_DISMISS_POLL_MS));
+        }
+        return "superseded";
+    }
+    catch {
+        return "failed";
+    }
+}
 /**
  * The `OPENAI_*` retry env for a codex-lineage app-server spawn, or `undefined`
  * when the budget declares no retry or the runtime is claude. claude applies
@@ -247,7 +327,7 @@ export class LocalAgentHost {
     // multi-connection model). Defaults to an ExternalWsChannel client attached to
     // the backend's app-server; tests inject a fake.
     forwarderClientFactory;
-    // Builds Omnigent's short-lived cold-resume preload connection. This must be
+    // Builds reference implementation's short-lived cold-resume preload connection. This must be
     // distinct from both the app-server owner/injector and the background
     // observer: the owner's initialize handshake is the readiness probe, then a
     // freshly initialized connection performs the one resume and closes.
@@ -418,8 +498,51 @@ export class LocalAgentHost {
         if (live.settledInteractions.has(interactionId)) {
             return { disposition: "already_resolved" };
         }
+        const synthetic = live.syntheticInteractions.get(interactionId);
+        if (synthetic)
+            return synthetic.resolve(resolution);
         return live.forwarderClient.resolveInteraction(interactionId, resolution);
     }
+    /** Apply collaboration mode to an already-loaded Codex-lineage thread. The
+     * caller persists only after this native RPC succeeds. */
+    async updateCollaborationMode(localThreadId, mode) {
+        const live = this.liveSessions.get(localThreadId);
+        if (!live || live.stopped || live.rotationPending) {
+            throw new CodexRuntimeError("Native Session is not live", 409, "native_session_not_live");
+        }
+        const run = live.injectLock.then(async () => {
+            const bound = await this.waitLiveReady(localThreadId, CODEX_BRIDGE_READY_TIMEOUT_MS);
+            const threadId = live.threadId ?? live.forwarder.threadId();
+            if (!bound || !threadId) {
+                throw new CodexRuntimeError("Native thread is not ready", 503, "native_thread_not_ready");
+            }
+            await this.applyLiveCollaborationMode(live, threadId, mode);
+        });
+        live.injectLock = run.then(() => undefined, () => undefined);
+        await run;
+    }
+    /** Apply one explicit collaboration mode to the current native thread and
+     * remember only a successful RPC. A supplied client is already initialized
+     * and remains owned by its caller (used by cold-resume preload). */
+    async applyLiveCollaborationMode(live, threadId, mode, suppliedClient) {
+        if (live.appliedCollaborationMode === mode)
+            return;
+        const client = suppliedClient ?? this.injectionClientFactory(live.appServerUrl);
+        try {
+            if (!suppliedClient)
+                await client.ensureInitialized();
+            await client.threadSettingsUpdate({
+                threadId,
+                collaborationMode: await buildCollaborationMode(client, mode, live.model, live.reasoningEffort),
+            });
+            live.appliedCollaborationMode = mode;
+            live.execution = { ...live.execution, collaborationMode: mode };
+        }
+        finally {
+            if (!suppliedClient)
+                await client.stop().catch(() => undefined);
+        }
+    }
     /**
      * The command to run in a session's live terminal so it co-drives the codex
      * app-server thread (Phase D). Returns `null` when live-terminal is off, the
@@ -634,7 +757,7 @@ export class LocalAgentHost {
         // notifications (the backend client injects; this one only observes).
         // Fresh sessions must connect this listener before the TUI launches so its
         // one-shot `thread/started` cannot race discovery. A known-thread cold resume
-        // already has its durable id: like Omnigent's `_codex_forward_known_thread`,
+        // already has its durable id: like reference implementation's `_codex_forward_known_thread`,
         // its observer starts in the background only after the replacement TUI has
         // launched and is never part of the resume admission boundary.
         const forwarderClient = this.forwarderClientFactory(appServerUrl);
@@ -677,6 +800,7 @@ export class LocalAgentHost {
             reasoningEffort,
             appliedModel: model,
             appliedReasoningEffort: reasoningEffort,
+            appliedCollaborationMode: undefined,
             ...(execution.instructions ? { instructions: execution.instructions } : {}),
             threadId: record?.codexSessionId ?? null,
             ready,
@@ -699,6 +823,8 @@ export class LocalAgentHost {
             skillsCleanup: snapshotSkills.skillsCleanup,
             canonicalInteractions: new Set(),
             settledInteractions: new Set(),
+            syntheticInteractions: new Map(),
+            cancelSyntheticInteractions: () => undefined,
         };
         let currentSessionId = localThreadId;
         let pendingRotationEvents = null;
@@ -721,6 +847,9 @@ export class LocalAgentHost {
         };
         let normalizer = null;
         let currentResponseId = null;
+        /** State for content-only events, keyed by Provider response so consecutive
+         * late deltas retain one canonical item id without owning lifecycle. */
+        const contentNormalizers = new Map();
         const startNormalizer = (turnId) => {
             const responseId = turnId ? `resp_codex_${turnId}` : "resp_codex_native";
             if (normalizer && currentResponseId === responseId)
@@ -766,6 +895,40 @@ export class LocalAgentHost {
                 return;
             live.pendingInjectedInputs = live.pendingInjectedInputs.filter((entry) => entry.responseId !== responseId);
         };
+        const turnContentEvents = (turnId, produce) => {
+            const responseId = turnId ? `resp_codex_${turnId}` : "resp_codex_native";
+            let contentNormalizer = contentNormalizers.get(responseId);
+            if (!contentNormalizer) {
+                contentNormalizer = new SessionNormalizer({
+                    sessionId: currentSessionId,
+                    responseId,
+                    model: live.model || live.runtime,
+                });
+                contentNormalizers.set(responseId, contentNormalizer);
+            }
+            for (const event of produce(contentNormalizer)) {
+                // Omnigent posts item/transient content under the Turn's response id
+                // independently of lifecycle status. Reuse Rynx's canonical item
+                // normalization but suppress its synthetic lifecycle edges.
+                if (event.type !== "response.created" && event.type !== "session.status") {
+                    emitCurrent(event);
+                }
+            }
+        };
+        const observedUserContent = (content) => {
+            const normalizedContent = typeof content === "string"
+                ? [{ type: "input_text", text: content }]
+                : content;
+            const signature = JSON.stringify(normalizedContent);
+            const pending = live.pendingInjectedInputs.find((entry) => entry.signature === signature || entry.providerEchoSignature === signature);
+            if (pending?.state === "optimistic") {
+                live.pendingInjectedInputs.splice(live.pendingInjectedInputs.indexOf(pending), 1);
+                return null;
+            }
+            if (pending)
+                pending.observed = true;
+            return normalizedContent;
+        };
         const rememberSettledInteraction = (interactionId) => {
             live.settledInteractions.add(interactionId);
             if (live.settledInteractions.size <= MAX_CODEX_SETTLED_INTERACTIONS)
@@ -774,11 +937,168 @@ export class LocalAgentHost {
             if (oldest)
                 live.settledInteractions.delete(oldest);
         };
+        const cancelSyntheticInteractions = (reason) => {
+            for (const interaction of live.syntheticInteractions.values())
+                interaction.cancel(reason);
+        };
+        live.cancelSyntheticInteractions = cancelSyntheticInteractions;
+        const publishPlanImplementationPrompt = (prompt) => {
+            const suffix = createHash("sha256")
+                .update(`${prompt.threadId}\0${prompt.turnId}`)
+                .digest("hex")
+                .slice(0, 24);
+            const interactionId = `codex_plan_implementation_${suffix}`;
+            if (live.syntheticInteractions.has(interactionId) ||
+                live.settledInteractions.has(interactionId))
+                return;
+            const responseId = `resp_codex_plan_approval_${suffix}`;
+            const request = codexPlanImplementationRequest(interactionId);
+            const interactionNormalizer = new SessionNormalizer({
+                sessionId: currentSessionId,
+                responseId,
+                model: live.model || live.runtime,
+            });
+            let submitted = false;
+            const finish = (kind, resolution, reason) => {
+                if (!live.syntheticInteractions.delete(interactionId))
+                    return;
+                rememberSettledInteraction(interactionId);
+                const event = kind === "resolved"
+                    ? {
+                        type: "interaction_resolved",
+                        interactionId,
+                        resolution: resolution,
+                    }
+                    : {
+                        type: "interaction_cancelled",
+                        interactionId,
+                        ...(reason ? { reason } : {}),
+                    };
+                // This interaction belongs to the Session that produced the Plan. A
+                // clear-context choice can rotate the native thread before turn/start
+                // returns, so never retarget its resolution to the new Session.
+                for (const sessionEvent of interactionNormalizer.next(event))
+                    emit(sessionEvent);
+                for (const sessionEvent of interactionNormalizer.next({ type: "done" })) {
+                    emit(sessionEvent);
+                }
+            };
+            live.syntheticInteractions.set(interactionId, {
+                cancel: (reason) => {
+                    // The selected implementation itself starts a native Turn and the
+                    // clear-context variant also starts a new thread. Their observer
+                    // notifications can beat the short-lived RPC response; they are not
+                    // competing user actions and must not cancel the card being resolved.
+                    if (submitted &&
+                        (reason === "superseded_by_native_turn" || reason === "native_thread_rotated"))
+                        return;
+                    finish("cancelled", undefined, reason);
+                },
+                resolve: async (resolution) => {
+                    if (submitted)
+                        return { disposition: "already_resolved" };
+                    const invalid = validateInteractionResolution(request, resolution);
+                    if (invalid)
+                        return { disposition: "invalid", message: invalid };
+                    const choice = resolution.answers?.plan_implementation;
+                    if (typeof choice !== "string") {
+                        return { disposition: "invalid", message: "plan implementation choice is required" };
+                    }
+                    submitted = true;
+                    const run = live.injectLock.then(async () => {
+                        if (live.stopped || live.rotationPending) {
+                            throw new CodexRuntimeError("Native Session is not available for plan implementation", 409, "native_session_not_live");
+                        }
+                        const promptDismissal = await dismissCodexPlanImplementationPrompt(live.injector, () => !live.stopped &&
+                            !live.rotationPending &&
+                            live.syntheticInteractions.has(interactionId) &&
+                            live.forwarder.threadId() === prompt.threadId &&
+                            !live.forwarder.isTurnOpen());
+                        if (promptDismissal === "failed") {
+                            console.warn(`[codex-live] session=${currentSessionId} native Plan picker remained visible after the Web decision; continuing through the app-server`);
+                        }
+                        if (choice === CODEX_PLAN_IMPLEMENTATION_NO) {
+                            finish("resolved", resolution);
+                            return;
+                        }
+                        const client = this.injectionClientFactory(live.appServerUrl);
+                        try {
+                            await client.ensureInitialized();
+                            const collaborationMode = await buildCollaborationMode(client, "default", live.model, live.reasoningEffort);
+                            let threadId = prompt.threadId;
+                            let text = CODEX_PLAN_IMPLEMENTATION_CODING_MESSAGE;
+                            if (choice === CODEX_PLAN_IMPLEMENTATION_CLEAR_CONTEXT) {
+                                live.nextThreadCollaborationMode = "default";
+                                let startedThread;
+                                try {
+                                    startedThread = await client.threadStart({
+                                        ...(live.model ? { model: live.model } : {}),
+                                        ...threadWorkspaceParams(live.runtime, live.workspace, live.sandbox),
+                                        approvalPolicy: live.approvalPolicy,
+                                        ...(live.instructions ? { developerInstructions: live.instructions } : {}),
+                                        sessionStartSource: "clear",
+                                    });
+                                }
+                                catch (error) {
+                                    live.nextThreadCollaborationMode = undefined;
+                                    throw error;
+                                }
+                                threadId = startedThread.threadId;
+                                text = `${CODEX_PLAN_IMPLEMENTATION_CLEAR_CONTEXT_PREFIX}\n\n${prompt.text}`;
+                            }
+                            else if (choice !== CODEX_PLAN_IMPLEMENTATION_YES) {
+                                throw new CodexRuntimeError("Unknown plan implementation choice", 400, "invalid_interaction_resolution");
+                            }
+                            const started = await client.turnStart({
+                                threadId,
+                                input: [{ type: "text", text }],
+                                ...turnWorkspaceParams(live.runtime, live.workspace, live.sandbox),
+                                approvalPolicy: live.approvalPolicy,
+                                collaborationMode,
+                            });
+                            live.execution = { ...live.execution, collaborationMode: "default" };
+                            live.appliedCollaborationMode = "default";
+                            emitCurrent({
+                                type: "session.collaboration_mode",
+                                sessionId: currentSessionId,
+                                mode: "default",
+                            });
+                            live.forwarder.noteTurnAccepted(started.turnId);
+                            finish("resolved", resolution);
+                        }
+                        finally {
+                            await client.stop().catch(() => undefined);
+                        }
+                    });
+                    live.injectLock = run.then(() => undefined, () => undefined);
+                    try {
+                        await run;
+                        return { disposition: "applied" };
+                    }
+                    catch (error) {
+                        submitted = false;
+                        return {
+                            disposition: "invalid",
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                    }
+                },
+            });
+            for (const sessionEvent of interactionNormalizer.next({
+                type: "interaction_requested",
+                interaction: request,
+            }))
+                emit(sessionEvent);
+        };
         const forwardInteraction = (event) => {
             const interactionId = event.type === "requested"
                 ? event.request.interactionId
                 : event.interactionId;
             if (event.type === "requested") {
+                if (event.request.fields.some((field) => field.id === "plan_implementation")) {
+                    live.forwarder.noteNativePlanImplementationPrompt(event.turnId);
+                    cancelSyntheticInteractions("superseded_by_native_plan_prompt");
+                }
                 if (live.canonicalInteractions.has(interactionId) ||
                     live.settledInteractions.has(interactionId))
                     return;
@@ -896,32 +1216,34 @@ export class LocalAgentHost {
         const sink = {
             onTurnStart: (turnId) => startNormalizer(turnId),
             onTurnObserved: (turnId) => {
+                cancelSyntheticInteractions("superseded_by_native_turn");
                 const n = startNormalizer(turnId);
                 for (const event of n.next({ type: "turn_started", ...(turnId ? { turnId } : {}) })) {
                     emitCurrent(event);
                 }
             },
             onUserMessage: (content) => {
-                const normalizedContent = typeof content === "string"
-                    ? [{ type: "input_text", text: content }]
-                    : content;
-                const signature = JSON.stringify(normalizedContent);
-                const pending = live.pendingInjectedInputs.find((entry) => entry.signature === signature);
-                if (pending?.state === "optimistic") {
-                    live.pendingInjectedInputs.splice(live.pendingInjectedInputs.indexOf(pending), 1);
+                const normalizedContent = observedUserContent(content);
+                if (!normalizedContent)
                     return;
-                }
-                if (pending)
-                    pending.observed = true;
                 const n = normalizer ?? startNormalizer();
                 for (const se of n.userInput(normalizedContent))
                     emitCurrent(se);
             },
+            onTurnContentUserMessage: (turnId, content) => {
+                const normalizedContent = observedUserContent(content);
+                if (!normalizedContent)
+                    return;
+                turnContentEvents(turnId, (n) => n.userInput(normalizedContent));
+            },
             onEvent: (event) => {
                 const n = normalizer ?? startNormalizer();
                 for (const se of n.next(event))
                     emitCurrent(se);
             },
+            onTurnContentEvent: (turnId, event) => {
+                turnContentEvents(turnId, (n) => n.next(event));
+            },
             onStatus: (note, statusKind) => {
                 const responseId = currentResponseId ??
                     live.pendingInjectedInputs.find((entry) => entry.responseId)?.responseId;
@@ -961,6 +1283,16 @@ export class LocalAgentHost {
             shouldIgnoreThreadStarted: (threadId, forkedFromId) => this.shouldIgnoreManagedForkThreadStarted(live, threadId, forkedFromId),
             onThreadStarted: (threadId, forkedFromId) => this.onLiveThreadStarted(live, localThreadId, threadId, forkedFromId),
             onThreadActive: () => live.releaseActive?.(),
+            onCollaborationModeChanged: (mode) => {
+                live.appliedCollaborationMode = mode;
+                live.execution = { ...live.execution, collaborationMode: mode };
+                emitCurrent({
+                    type: "session.collaboration_mode",
+                    sessionId: currentSessionId,
+                    mode,
+                });
+            },
+            onPlanImplementationPrompt: publishPlanImplementationPrompt,
         };
         const forwarder = new CodexSessionForwarder(forwarderClient, sink, {
             // Traex 0.200 can publish a final reasoning item immediately after
@@ -979,12 +1311,20 @@ export class LocalAgentHost {
                 live.stopped = true;
                 return;
             }
+            cancelSyntheticInteractions("native_thread_rotated");
             const previousSessionId = currentSessionId;
             const newSessionId = makeSessionId();
+            const rotationMode = live.nextThreadCollaborationMode;
+            live.nextThreadCollaborationMode = undefined;
+            live.appliedCollaborationMode = undefined;
+            if (rotationMode) {
+                live.execution = { ...live.execution, collaborationMode: rotationMode };
+            }
             live.rotationPending = true;
             currentSessionId = newSessionId;
             normalizer = null;
             currentResponseId = null;
+            contentNormalizers.clear();
             live.pendingInjectedInputs = [];
             pendingRotationEvents = [];
             void this.sessionStore
@@ -1017,6 +1357,14 @@ export class LocalAgentHost {
                 live.rotationPending = false;
                 for (const event of queued)
                     emit(event);
+                const desiredMode = live.execution.collaborationMode;
+                if (desiredMode) {
+                    const restore = live.injectLock.then(() => this.applyLiveCollaborationMode(live, threadId, desiredMode));
+                    live.injectLock = restore.then(() => undefined, () => undefined);
+                    void restore.catch((error) => {
+                        this.failObserverLifecycle(newSessionId, live, nativeLiveFailure(live.runtime, "native_collaboration_mode_restore_failed", "rotated native thread could not restore the Session collaboration mode", error));
+                    });
+                }
                 void this.subscribeUntilReady(newSessionId, live, threadId);
             })
                 .catch(() => {
@@ -1035,7 +1383,7 @@ export class LocalAgentHost {
         // turn-less app-server thread resumable by the TUI.
         try {
             if (record?.codexSessionId) {
-                // Match Omnigent's cold-resume preload exactly: one history-free
+                // Match reference implementation's cold-resume preload exactly: one history-free
                 // `thread/resume` on a short-lived, separately initialized connection.
                 // The backend owner's handshake above is the app-server readiness
                 // probe; reusing that first connection here races Codex's startup state
@@ -1052,6 +1400,9 @@ export class LocalAgentHost {
                             approvalPolicy,
                             excludeTurns: true,
                         });
+                        if (execution.collaborationMode) {
+                            await this.applyLiveCollaborationMode(live, resumed.threadId, execution.collaborationMode, preloadClient);
+                        }
                     }
                     finally {
                         await preloadClient.stop().catch((error) => {
@@ -1138,16 +1489,38 @@ export class LocalAgentHost {
             });
         })
             .catch(() => undefined);
-        live.markReady(); // thread id known → injection can turn/start
-        if (live.observerAvailable) {
-            void this.subscribeUntilReady(localThreadId, live, threadId).then(live.markTerminalReady);
-        }
-        else {
-            // Known-thread cold resume has already completed the dedicated preload. Its
-            // observer is deliberately post-TUI background work, not Terminal
-            // readiness. RunnerSession calls startLiveCodexObserver after launch.
-            live.markTerminalReady(true);
+        const finishBinding = () => {
+            if (live.stopped)
+                return;
+            live.markReady(); // thread id + explicit Session mode are ready for turns
+            if (live.observerAvailable) {
+                void this.subscribeUntilReady(localThreadId, live, threadId).then(live.markTerminalReady);
+            }
+            else {
+                // Known-thread cold resume has already completed the dedicated preload. Its
+                // observer is deliberately post-TUI background work, not Terminal
+                // readiness. RunnerSession calls startLiveCodexObserver after launch.
+                live.markTerminalReady(true);
+            }
+        };
+        const desiredMode = live.execution.collaborationMode;
+        if (!desiredMode || live.appliedCollaborationMode === desiredMode) {
+            finishBinding();
+            return;
         }
+        // A fresh thread does not exist until the TUI broadcasts thread/started.
+        // Apply the Session-owned mode immediately at that boundary, before Web
+        // injection is released. This also narrows the window in which a user can
+        // type into the native pane before its explicit startup mode is installed.
+        const restore = live.injectLock.then(() => this.applyLiveCollaborationMode(live, threadId, desiredMode));
+        live.injectLock = restore.then(() => undefined, () => undefined);
+        void restore.then(finishBinding).catch((error) => {
+            const failure = nativeLiveFailure(live.runtime, "native_collaboration_mode_restore_failed", "native thread could not apply the Session collaboration mode", error);
+            live.startupError = failure;
+            live.markStartupFailed();
+            this.liveStartupErrors.set(localThreadId, failure);
+            this.teardownLiveCodexSession(localThreadId, failure);
+        });
     }
     /** Start the known-thread observer after the replacement TUI has launched.
      * Fresh sessions already connected their discovery listener before launch;
@@ -1165,7 +1538,7 @@ export class LocalAgentHost {
                 if (live.stopped)
                     return;
                 live.observerAvailable = true;
-                // Omnigent starts subscription as a sibling task after the transport
+                // reference implementation starts subscription as a sibling task after the transport
                 // connects. A no/empty rollout remains event-driven retryable; any
                 // other subscription rejection is diagnostic only and must not tear
                 // down the otherwise usable Terminal/injection lifecycle.
@@ -1176,7 +1549,7 @@ export class LocalAgentHost {
             }
         })();
     }
-    /** Omnigent treats the forwarder as a required component of one native
+    /** reference implementation treats the forwarder as a required component of one native
      * lifecycle: if its transport dies, it closes the app-server instead of
      * accepting turns that can no longer reach the canonical mirror. */
     failObserverLifecycle(localThreadId, live, error) {
@@ -1208,7 +1581,7 @@ export class LocalAgentHost {
      * Subscribe the forwarder connection to a thread (reference implementation's
      * `_subscribe_until_ready`). A fresh TUI thread has no rollout until its first
      * turn, so `thread/resume` is retried: park until the forwarder observes the
-     * thread active, then retry. Like Omnigent, the first attempt always uses
+     * thread active, then retry. Like reference implementation, the first attempt always uses
      * `excludeTurns`: a known-session cold resume therefore never reconstructs
      * historical running/completed state. Only a fresh thread whose first attempt
      * failed as not-ready retries without `excludeTurns`, backfilling the newly
@@ -1345,7 +1718,7 @@ export class LocalAgentHost {
      * forwarder). Park-until-ready (~60s), aligning reference implementation's executor waiting for
      * the bridge instead of a short race that falls back to a second output path.
      */
-    async injectMessage(localThreadId, input) {
+    async injectMessage(localThreadId, input, options) {
         const runtimeInput = typeof input === "string"
             ? { content: [{ type: "text", text: input }] }
             : input;
@@ -1405,9 +1778,16 @@ export class LocalAgentHost {
                 return { outcome: "notReady" };
             const nativeInput = buildRuntimeUserInput(runtimeInput);
             const content = runtimeUserContent(runtimeInput);
+            const providerEcho = codexUserEchoContent(nativeInput);
+            const providerEchoContent = typeof providerEcho === "string"
+                ? [{ type: "input_text", text: providerEcho }]
+                : providerEcho;
             const pendingInput = {
                 content,
                 signature: JSON.stringify(content),
+                ...(providerEchoContent
+                    ? { providerEchoSignature: JSON.stringify(providerEchoContent) }
+                    : {}),
                 state: "awaiting",
                 observed: false,
             };
@@ -1427,14 +1807,14 @@ export class LocalAgentHost {
             };
             const injectionClient = this.injectionClientFactory(live.appServerUrl);
             try {
-                // Omnigent publishes codex-native running only after the native Terminal
+                // reference implementation publishes codex-native running only after the native Terminal
                 // is ready and the runner has accepted the message, but before the
                 // short-lived app-server client initializes and starts the Turn. Claude
                 // deliberately has no matching synthesized edge.
                 if (!live.forwarder.isTurnOpen())
                     publishAdmission();
                 await injectionClient.ensureInitialized();
-                // Match Omnigent's executor: each message uses one initialized client
+                // Match reference implementation's executor: each message uses one initialized client
                 // that closes as soon as turn/start or turn/steer is acknowledged.
                 if (live.forwarder.isTurnOpen()) {
                     const turnId = live.forwarder.currentTurnId();
@@ -1456,11 +1836,20 @@ export class LocalAgentHost {
                         return { outcome: "steered", responseId: `resp_codex_${steered.turnId}` };
                     }
                 }
-                // Match Omnigent's turn boundary: change the native thread settings
+                // Match reference implementation's turn boundary: change the native thread settings
                 // under the same lock immediately before starting the next Turn. Never
                 // put settings on turn/start or mutate a Turn that is already open.
                 const desiredModel = live.model;
                 const desiredReasoningEffort = live.reasoningEffort;
+                // A Session-owned mode survives runner restarts. Normal Web messages do
+                // not carry per-Turn options, so a cold-resumed native thread must fall
+                // back to the persisted execution snapshot before its first new Turn.
+                // An explicit session.run option still wins for that invocation.
+                const desiredCollaborationMode = options?.collaborationMode ?? live.execution.collaborationMode;
+                const collaborationMode = desiredCollaborationMode &&
+                    desiredCollaborationMode !== live.appliedCollaborationMode
+                    ? await buildCollaborationMode(injectionClient, desiredCollaborationMode, desiredModel, desiredReasoningEffort)
+                    : undefined;
                 const settings = {
                     threadId,
                     ...(desiredModel !== live.appliedModel
@@ -1469,6 +1858,7 @@ export class LocalAgentHost {
                     ...(desiredReasoningEffort !== live.appliedReasoningEffort
                         ? { effort: desiredReasoningEffort ?? null }
                         : {}),
+                    ...(collaborationMode ? { collaborationMode } : {}),
                 };
                 if (Object.keys(settings).length > 1) {
                     await injectionClient.threadSettingsUpdate(settings);
@@ -1477,6 +1867,13 @@ export class LocalAgentHost {
                     // the following new Turn.
                     live.appliedModel = desiredModel;
                     live.appliedReasoningEffort = desiredReasoningEffort;
+                    if (desiredCollaborationMode) {
+                        live.appliedCollaborationMode = desiredCollaborationMode;
+                        live.execution = {
+                            ...live.execution,
+                            collaborationMode: desiredCollaborationMode,
+                        };
+                    }
                 }
                 publishAdmission();
                 const started = await injectionClient.turnStart({
@@ -1500,6 +1897,10 @@ export class LocalAgentHost {
             }
             catch (error) {
                 forgetPendingInput();
+                if (error instanceof CodexRuntimeError &&
+                    error.code === "collaboration_mode_model_unknown") {
+                    throw error;
+                }
                 // Preserve the app-server's error instead of collapsing every failure
                 // into the unactionable `live injection failed` string.
                 const baseDetail = codexRpcError(error, injectionMethod);
@@ -1626,6 +2027,7 @@ export class LocalAgentHost {
             live.markStartupFailed();
         }
         live.releaseActive?.();
+        live.cancelSyntheticInteractions("session_stopped");
         live.appServerOwner.cancelInteractions("session_stopped");
         live.forwarderClient.cancelInteractions("session_stopped");
         live.appServerOwner.setInteractionListener(null);
@@ -1635,12 +2037,13 @@ export class LocalAgentHost {
         live.forwarder.stop();
         live.canonicalInteractions.clear();
         live.settledInteractions.clear();
+        live.syntheticInteractions.clear();
         void live.forwarderClient.stop().catch(() => undefined);
         // Remove the session-scoped skills dir — the machine keeps zero task residue.
         void live.skillsCleanup?.();
     }
     /** Tear down one codex-lineage native runtime without deleting its durable
-     * session-store binding. Omnigent couples its auxiliary Terminal, observer,
+     * session-store binding. reference implementation couples its auxiliary Terminal, observer,
      * forwarder and per-session app-server as one disposable runtime envelope;
      * the next message recreates that envelope and cold-resumes the native id. */
     teardownLiveCodexSession(localThreadId, error) {
@@ -1958,7 +2361,7 @@ export class LocalAgentHost {
                 responseId,
             });
         };
-        const settleClaudeTurn = (interrupted, usage) => {
+        const settleClaudeTurn = (interrupted, usage, backgroundTaskCount) => {
             if (!normalizer)
                 return;
             const rid = currentResponseId;
@@ -1977,8 +2380,11 @@ export class LocalAgentHost {
                     for (const se of normalizer.next({ type: "turn_completed", usage }))
                         emitCurrent(se);
                 }
-                for (const se of normalizer.next({ type: "done" }))
-                    emitCurrent(se);
+                for (const se of normalizer.next({ type: "done" })) {
+                    emitCurrent(se.type === "session.status" && backgroundTaskCount !== undefined
+                        ? { ...se, backgroundTaskCount }
+                        : se);
+                }
             }
             live.pendingInjectedInputs = live.pendingInjectedInputs.filter((entry) => entry.responseId !== rid);
             normalizer = null;
@@ -2041,30 +2447,42 @@ export class LocalAgentHost {
                     ...(blockedOn ? { note: blockedOn } : {}),
                 });
             },
-            onTurnEnd: (usage) => settleClaudeTurn(false, usage),
+            onTurnEnd: (usage, backgroundTaskCount) => settleClaudeTurn(false, usage, backgroundTaskCount),
             onTurnInterrupted: (usage) => settleClaudeTurn(true, usage),
             onTurnInterruptRequested: () => {
                 const responseId = currentResponseId;
                 if (responseId)
                     live.publishInterrupted(responseId);
             },
-            onIdle: () => {
-                // Surface idle on the current turn WITHOUT finalizing it (see the sink's
-                // onIdle doc): a late assistant record still joins this response.
-                if (currentResponseId) {
+            onIdle: (backgroundTaskCount) => {
+                // Surface Stop even after its Turn has already closed: a later
+                // authoritative zero is what clears a sticky background-shell tally.
+                // When the Turn is still open, retain its identity without finalizing it
+                // so a late assistant record continues to join the same Response.
+                emitCurrent({
+                    type: "session.status",
+                    sessionId: currentSessionId,
+                    ...(currentResponseId ? { responseId: currentResponseId } : {}),
+                    status: "idle",
+                    ...(backgroundTaskCount === undefined ? {} : { backgroundTaskCount }),
+                });
+            },
+            onTurnError: (error) => {
+                const message = error.message || "Agent turn failed";
+                if (!normalizer) {
+                    // Native pane/forwarder death is Session-level even when Claude is
+                    // between Turns. Omnigent publishes the same bare failed edge; the
+                    // explicit zero also retires any sticky background-shell tally.
                     emitCurrent({
                         type: "session.status",
                         sessionId: currentSessionId,
-                        responseId: currentResponseId,
-                        status: "idle",
+                        status: "failed",
+                        backgroundTaskCount: 0,
+                        note: message,
                     });
-                }
-            },
-            onTurnError: (error) => {
-                if (!normalizer)
                     return;
+                }
                 const rid = currentResponseId;
-                const message = error.message || "Agent turn failed";
                 for (const se of normalizer.fail({
                     code: "agent_error",
                     message,
@@ -2236,8 +2654,9 @@ export class LocalAgentHost {
         return live.injector ?? null;
     }
     /** Attach a session's tmux pane injector (from the runner-child, which owns the
-     *  terminal registry — the host does not hold tmux). Ignored for codex sessions
-     *  (they inject via the app-server). Idempotent. */
+     *  terminal registry — the host does not hold tmux). Claude uses it for normal
+     *  message injection; Codex uses it only to dismiss the exact TUI-local Plan
+     *  picker after its synthetic Web form is submitted. Idempotent. */
     attachTerminalInjector(localThreadId, injector) {
         const live = this.liveClaudeSessions.get(localThreadId);
         if (live) {
@@ -2245,7 +2664,11 @@ export class LocalAgentHost {
                 return;
             live.injector = injector;
             live.forwarder.attachStatusSource({ panePid: () => injector.panePid?.() });
+            return;
         }
+        const codex = this.liveSessions.get(localThreadId);
+        if (codex)
+            codex.injector = injector;
     }
     /** Close an active native response when its terminal or runner disappears. */
     failLiveSession(localThreadId, error) {
@@ -2472,6 +2895,40 @@ function raceReady(ready, timeoutMs, failed) {
             clearTimeout(timer);
     });
 }
+/** Expand the public mode enum into the App Server's required settings
+ * snapshot. This mirrors Omnigent: an explicit Session model wins; otherwise
+ * the Provider's advertised native default is required, and an unknown model
+ * fails the update instead of silently dropping collaboration mode. */
+async function buildCollaborationMode(client, mode, desiredModel, desiredReasoningEffort) {
+    let model = desiredModel.trim();
+    if (!model) {
+        let catalog;
+        try {
+            catalog = await client.modelList();
+        }
+        catch (error) {
+            throw new CodexRuntimeError(`collaboration mode requires the current model: ${error instanceof Error ? error.message : String(error)}`, 503, "collaboration_mode_model_unknown");
+        }
+        const defaults = [...new Set(catalog.data
+                .filter((candidate) => candidate.isDefault === true)
+                .map((candidate) => (candidate.model || candidate.id).trim())
+                .filter(Boolean))];
+        if (defaults.length !== 1) {
+            throw new CodexRuntimeError(`collaboration mode requires exactly one current default model; Provider advertised ${defaults.length}`, 503, "collaboration_mode_model_unknown");
+        }
+        model = defaults[0];
+    }
+    return {
+        mode,
+        settings: {
+            model,
+            reasoning_effort: desiredReasoningEffort ?? null,
+            // `null` asks the App Server to install the built-in instructions for
+            // the selected mode; thread-level Agent instructions remain separate.
+            developer_instructions: null,
+        },
+    };
+}
 function sameSessionSnapshots(workspace, execution, opts) {
     return JSON.stringify(stableValue({
         workspace,
@@ -2482,8 +2939,18 @@ function sameSessionSnapshots(workspace, execution, opts) {
     }));
 }
 function sameImmutableSessionSnapshots(workspace, execution, opts) {
-    const current = { ...execution, model: null, reasoningEffort: null };
-    const requested = { ...opts.execution, model: null, reasoningEffort: null };
+    const current = {
+        ...execution,
+        model: null,
+        reasoningEffort: null,
+        collaborationMode: undefined,
+    };
+    const requested = {
+        ...opts.execution,
+        model: null,
+        reasoningEffort: null,
+        collaborationMode: undefined,
+    };
     return JSON.stringify(stableValue({ workspace, execution: current })) ===
         JSON.stringify(stableValue({ workspace: opts.workspace, execution: requested }));
 }