@rynx-ai/runtime 0.1.10 → 0.1.11-beta.2

package/dist/host.js

@@ -1,23 +1,24 @@
 import { spawn } from "node:child_process";
-import { mkdtemp, rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { cp, mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import readline from "node:readline";
-import { resolveAgent, resolveAgentExecution, buildAgentSkillEnvironment, SessionNormalizer, } from "@rynx-ai/core";
+import { buildAgentSkillEnvironment, hashPluginPackageTree, scanSkillsDir, SessionNormalizer, } from "@rynx-ai/core";
 import { getRuntimeProfile, } from "@rynx-ai/core";
-import { resolveRuntimeBinary, resolveRuntimeModel, } from "@rynx-ai/core";
+import { resolveRuntimeBinary, } from "@rynx-ai/core";
 import { createCodexChildEnv } from "./codex-child-env.js";
-import { prepareRuntimeHome, populateCodexSkills, } from "./codex-home.js";
+import { prepareRuntimeHome, populateCodexSkills, runtimeHomePath, } from "./codex-home.js";
 import { materializeSkillPlugin } from "./claude/executor.js";
 import { listClaudeModels } from "./claude/models.js";
 import { CodexAppServerClient, buildRuntimeUserInput, } from "./codex-app-server/client.js";
-import { buildAppServerBaseArgs } from "./codex-app-server/transport.js";
+import { buildAppServerBaseArgs, CodexTransportError, } from "./codex-app-server/transport.js";
 import { WsRpcChannel, ExternalWsChannel } from "./codex-app-server/ws-channel.js";
 import { CodexSessionForwarder } from "./codex-app-server/forwarder.js";
 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 { claudeTranscriptPath } from "./claude/transcript.js";
 import { claudeAttachmentToken, claudeInputText, runtimeUserContent, } from "./input-resources.js";
 import { claudeBridgeDir, prepareClaudeBridgeDir, removeManagedClaudeSettings, writeManagedClaudeSettings, } from "./claude/native-bridge.js";
 import { ClaudeLiveSession, injectViaTerminal, } from "./claude/native-integration.js";
@@ -156,10 +157,22 @@ export class SpawnCodexCommandRunner {
     }
     async capture({ args, cwd = process.cwd(), }) {
         const running = this.start({ args, cwd });
-        for await (const _ of running.stream) {
-            // Drain output so completion captures stdout/stderr for parsing.
+        const completion = running.completion.then((result) => ({ ok: true, result }), (error) => ({ ok: false, error }));
+        let streamError;
+        try {
+            for await (const _ of running.stream) {
+                // Drain output so completion captures stdout/stderr for parsing.
+            }
+        }
+        catch (error) {
+            streamError = error;
         }
-        return running.completion;
+        const outcome = await completion;
+        if (streamError)
+            throw streamError;
+        if (!outcome.ok)
+            throw outcome.error;
+        return outcome.result;
     }
 }
 /** Fraction of an agent's `contextWindow` budget at which the orchestrator
@@ -168,6 +181,13 @@ export class SpawnCodexCommandRunner {
  *  budget (set proactively); claude has no programmatic compaction, so this
  *  signal is the lever consumers surface to the user. */
 const CONTEXT_WARN_RATIO = 0.8;
+function providerPluginSkillName(namespace, name) {
+    const candidate = `${namespace}-${name}`;
+    if (candidate.length <= 128)
+        return candidate;
+    const digest = createHash("sha256").update(candidate).digest("hex").slice(0, 12);
+    return `${namespace.slice(0, 48)}-${name.slice(0, 65)}-${digest}`;
+}
 const MAX_CODEX_SETTLED_INTERACTIONS = 512;
 /**
  * The `OPENAI_*` retry env for a codex-lineage app-server spawn, or `undefined`
@@ -227,16 +247,15 @@ export class LocalAgentHost {
     // Keyed by `codexBackendKey` — the bare runtime id for budget-less agents, or
     // a `${runtime}::${retryHash}` composite for a per-agent retry budget.
     backends = new Map();
-    // The rynx session this host serves (set from `RYNX_RUNNER_SESSION`); the private
-    // CODEX_HOME is scoped to it so concurrent agents never share a `skills/` dir.
+    // The rynx Session this host serves (set from `RYNX_RUNNER_SESSION`).
     sessionId;
+    runtimeHomeSessionId;
     // Per-agent codex knobs resolved at live-session start, applied to this
     // session's app-server (host is per-session, so the app-server is private to
     // this agent). Absent ⇒ fall back to the daemon `config.*` default.
     sessionSandbox;
     sessionApprovalPolicy;
-    // Private CODEX_HOME / TRAE_HOME directories (login symlinked, settings
-    // copied, update/NUX state NOT inherited) for this session's app-server + TUI.
+    // Private CODEX_HOME / TRAE_HOME directories for this Session lineage.
     runtimeHomes = new Map();
     // Per-session codex-native live forwarders, keyed by localThreadId. The
     // single-writer of the session's canonical events + the target of turn injection.
@@ -250,9 +269,14 @@ export class LocalAgentHost {
     // In-flight `ensureLiveCodexSession` calls, so concurrent triggers (a web
     // `live.ensure` racing a `term.open`) share ONE forwarder — never two.
     liveEnsuring = new Map();
-    constructor({ config, commandRunner, sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config)), allowedRoots = resolveAllowedRoots(config), appServerClient, now = () => Date.now(), backendIdleTtlMs = 300_000, forwarderClientFactory, sessionId, }) {
+    forkingTargets = new Map();
+    /** Short-lived dedupe for managed fork notifications delivered after the
+     * `thread/fork` response. Values are expected source Provider thread ids. */
+    managedForkThreadStarts = new Map();
+    constructor({ config, commandRunner, sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config)), allowedRoots = resolveAllowedRoots(config), appServerClient, now = () => Date.now(), backendIdleTtlMs = 300_000, forwarderClientFactory, sessionId, runtimeHomeSessionId, }) {
         this.config = config;
         this.sessionId = sessionId ?? "__default__";
+        this.runtimeHomeSessionId = runtimeHomeSessionId ?? this.sessionId;
         this.sessionStore = sessionStore;
         this.allowedRoots = allowedRoots;
         this.defaultRuntime = config.AGENT_RUNTIME ?? "codex";
@@ -335,7 +359,9 @@ export class LocalAgentHost {
         const existing = this.runtimeHomes.get(runtime);
         if (existing)
             return existing;
-        const prepared = prepareRuntimeHome(this.sessionId, runtime);
+        const prepared = this.runtimeHomeSessionId === this.sessionId
+            ? prepareRuntimeHome(this.runtimeHomeSessionId, runtime)
+            : runtimeHomePath(this.runtimeHomeSessionId, runtime);
         this.runtimeHomes.set(runtime, prepared);
         return prepared;
     }
@@ -425,11 +451,11 @@ export class LocalAgentHost {
             return this.claudeTerminalSpec(localThreadId, record);
         }
         const live = this.liveSessions.get(localThreadId);
-        const runtime = record?.runtime ?? live?.runtime ?? this.defaultRuntime;
-        if (runtime === "claude") {
-            return this.claudeTerminalSpec(localThreadId, record);
+        if (!live) {
+            throw new CodexRuntimeError("session snapshots are not live", 409, "session_not_live");
         }
-        const backend = this.getBackend(runtime);
+        const runtime = live.runtime;
+        const backend = this.getBackend(runtime, live.execution.budget ?? undefined);
         const client = backend.appServerClient;
         if (!client) {
             throw new CodexRuntimeError(`no app-server for runtime ${runtime}`, 500, "app_server_unavailable");
@@ -444,29 +470,39 @@ export class LocalAgentHost {
         // The TUI shares this session's app-server, so it inherits the per-agent
         // sandbox already applied at boot; keep the network-access override aligned
         // to the same effective sandbox.
-        const configOverrides = (this.sessionSandbox ?? this.config.AGENT_SANDBOX) === "workspace-write"
+        const sandbox = live?.sandbox ?? this.sessionSandbox ?? this.config.AGENT_SANDBOX;
+        const approvalPolicy = live?.approvalPolicy ?? this.sessionApprovalPolicy ?? this.config.AGENT_APPROVAL_POLICY;
+        const configOverrides = sandbox === "workspace-write"
             ? ["sandbox_workspace_write.network_access=true"]
             : [];
+        configOverrides.push(`sandbox_mode=${JSON.stringify(sandbox)}`, `approval_policy=${JSON.stringify(approvalPolicy)}`);
+        // A managed TUI has no user at its stdin during startup. Codex's periodic
+        // "Update now / Skip" prompt would otherwise park the detached pane before
+        // it connects to the app-server, leaving the session only partially live.
+        if (runtime === "codex")
+            configOverrides.push("check_for_update_on_startup=false");
         // Apply the agent-spec model to the TUI (the private CODEX_HOME config.toml is
         // shared per-runtime, so a per-session model rides a launch `-c model=` instead).
-        const launchModel = live?.model;
+        const launchModel = live.model;
         if (launchModel)
             configOverrides.push(`model=${JSON.stringify(launchModel)}`);
-        const launchEffort = live?.reasoningEffort ?? record?.reasoningEffort;
+        const launchEffort = live.reasoningEffort;
         if (launchEffort)
             configOverrides.push(`model_reasoning_effort=${JSON.stringify(launchEffort)}`);
         if (live?.instructions) {
             configOverrides.push(`developer_instructions=${JSON.stringify(live.instructions)}`);
         }
         const profile = getRuntimeProfile(runtime);
+        const activeThreadId = live?.threadId ?? record?.codexSessionId;
         return {
             command: resolveRuntimeBinary(runtime),
             args: buildCodexRemoteArgs({
                 remoteUrl,
-                ...(record?.codexSessionId ? { threadId: record.codexSessionId } : {}),
+                ...(activeThreadId ? { threadId: activeThreadId } : {}),
                 configOverrides,
+                additionalDirs: providerAdditionalDirs(live.workspace),
             }),
-            cwd: record?.cwd ?? live?.cwd ?? process.cwd(),
+            cwd: live.workspace.cwd,
             // Share the app-server's private CODEX_HOME so the TUI inherits the same
             // login/settings and skips the real home's update/NUX prompt. RYNX_SESSION_ID
             // scopes agent-run CLIs (rynx-emulator) to this session at the daemon.
@@ -486,25 +522,33 @@ export class LocalAgentHost {
      * DETERMINISTIC (`resp_codex_<turnId>`) so items converge across snapshot/live.
      *
      * Returns false for claude / no app-server (the caller falls back to the
-     * streaming run path). This client CREATES the codex thread (`threadStart`) so
-     * it owns the thread's item/turn notification stream — the app-server delivers
-     * items to the thread-creating connection, for turns started by ANY client (web
-     * inject AND the co-driving `codex --remote` TUI). The TUI pane (launched by the
-     * runner child, which owns the terminal registry) merely `resume`s this thread
-     * to display it. The thread id is persisted so `codexTerminalSpec` resumes it.
+     * streaming run path). For a fresh session the native remote TUI creates the
+     * Codex thread and its `thread/started` notification supplies the id. For an
+     * existing session, the app-server resumes the persisted id. Rynx never writes
+     * or repairs Codex's private rollout files.
      */
     async ensureLiveCodexSession(localThreadId, emit, opts) {
-        const live = this.liveSessions.get(localThreadId);
-        if (live)
-            return this.refreshLiveCodexSession(localThreadId, live, opts);
-        if (this.liveClaudeSessions.has(localThreadId))
-            return true;
+        const snapshotOpts = {
+            workspace: structuredClone(opts.workspace),
+            execution: structuredClone(opts.execution),
+            ...(opts.retargetMirror ? { retargetMirror: opts.retargetMirror } : {}),
+        };
+        const existingClaude = this.liveClaudeSessions.get(localThreadId);
+        if (existingClaude) {
+            return sameSessionSnapshots(existingClaude.workspace, existingClaude.execution, snapshotOpts);
+        }
         // Dedupe concurrent triggers so only one forwarder is ever created per
-        // session (two would double-mirror every turn).
+        // session (two would double-mirror every turn). Check this before the live
+        // map: startLiveCodexSession publishes its partially initialized session
+        // before thread/start completes, so a concurrent Terminal start must await
+        // the thread id instead of launching a bare `codex --remote` pane.
         const inflight = this.liveEnsuring.get(localThreadId);
         if (inflight)
             return inflight;
-        const started = this.startLiveCodexSession(localThreadId, emit, opts);
+        const live = this.liveSessions.get(localThreadId);
+        if (live)
+            return sameSessionSnapshots(live.workspace, live.execution, snapshotOpts);
+        const started = this.startLiveCodexSession(localThreadId, emit, snapshotOpts);
         this.liveEnsuring.set(localThreadId, started);
         try {
             return await started;
@@ -522,48 +566,51 @@ export class LocalAgentHost {
             this.stopLiveCodexSession(localThreadId);
         }
         const record = await this.sessionStore.get(localThreadId);
-        // Runtime precedence: the thread's bound runtime, else the agent-resolved
-        // hint from the control plane, else the env default. This is what makes live
-        // co-drive follow the agent spec instead of the global default.
-        const runtime = record?.runtime ?? opts?.runtime ?? this.defaultRuntime;
+        const retargetMirror = opts.retargetMirror;
+        const workspace = structuredClone(opts.workspace);
+        const execution = structuredClone(opts.execution);
+        const runtime = execution.provider;
         if (runtime === "claude")
             return this.startLiveClaudeSession(localThreadId, emit, record, opts);
-        const cwd = record?.cwd ?? opts?.cwd ?? process.cwd();
-        const configSignature = liveConfigSignature(opts, runtime, cwd);
-        // Spec-load errors (a rejected legacy `skills` form, malformed JSON, …) are
-        // logged with the agent context and fail the live start loudly — never a
-        // bare mystery `false`.
-        let liveCfg;
+        let snapshotSkills = {
+            selectedSkills: [],
+            skillsCleanup: async () => undefined,
+        };
+        if (this.runtimeHomeSessionId === this.sessionId) {
+            try {
+                snapshotSkills = await this.prepareExecutionSkills(execution);
+            }
+            catch (err) {
+                console.error(`[session-snapshot] session=${localThreadId} skill materialization failed: ${err instanceof Error ? err.message : String(err)}`);
+                return false;
+            }
+        }
+        // Persist the owner's skills before the app-server boots. Fork targets reuse
+        // the owner's immutable copies and never mutate the shared Provider home.
+        const liveSkills = snapshotSkills.selectedSkills.map((s) => ({ name: s.name, dir: s.dir }));
         try {
-            liveCfg = await this.resolveLiveAgentConfig(localThreadId, opts, runtime, cwd);
+            populateCodexSkills(this.runtimeHome(runtime), liveSkills);
         }
         catch (err) {
-            console.error(`[agent-spec] session=${localThreadId} agent=${opts?.agentName ?? "-"} failed to resolve: ${err instanceof Error ? err.message : String(err)}`);
+            void snapshotSkills.skillsCleanup();
+            console.error(`[session-snapshot] session=${localThreadId} skill persistence failed: ${err instanceof Error ? err.message : String(err)}`);
             return false;
         }
-        // Link this session's skills into its private CODEX_HOME's `skills/` BEFORE the
-        // app-server boots (and before the `--remote` TUI attaches) so the native Codex
-        // discovers them — reference implementation's filesystem mechanism. The live thread is created by
-        // the TUI, not rynx, so skills can't ride `threadStart.developerInstructions` (as
-        // the non-live run did); `$CODEX_HOME/skills/` is the only channel that reaches it.
-        // The agent spec is the single skill source: its refs were replayed into a
-        // session-scoped dir (see resolveLiveAgentConfig); no spec / no `skills` means
-        // zero skills — the owner's catalog is never consulted.
-        const liveSkills = liveCfg.selectedSkills.map((s) => ({ name: s.name, dir: s.dir }));
-        populateCodexSkills(this.runtimeHome(runtime), liveSkills);
-        // Apply this agent's sandbox / approval policy to the session's app-server
-        // BEFORE it boots (getBackend below lazily creates it). Host is per-session,
-        // so these knobs are the agent's own — no cross-session bleed. Set even when
-        // absent (undefined) so a re-used host doesn't inherit a prior agent's values.
-        this.sessionSandbox = liveCfg.sandbox;
-        this.sessionApprovalPolicy = liveCfg.approvalPolicy;
+        const sandbox = execution.sandbox;
+        const approvalPolicy = execution.approvalPolicy;
+        if (!sandbox || !approvalPolicy) {
+            void snapshotSkills.skillsCleanup();
+            throw new CodexRuntimeError(`${runtime} execution snapshot is missing sandbox or approval policy`, 422, "invalid_execution_snapshot");
+        }
+        this.sessionSandbox = sandbox;
+        this.sessionApprovalPolicy = approvalPolicy;
         // Backend client owns the app-server + drives injection. Every failed-start
         // path below removes the session skills dir it would otherwise leak.
         const abandon = () => {
-            void liveCfg.skillsCleanup();
+            void snapshotSkills.skillsCleanup();
             return false;
         };
-        const injectClient = this.getBackend(runtime).appServerClient;
+        const injectClient = this.getBackend(runtime, execution.budget ?? undefined).appServerClient;
         if (!injectClient) {
             console.error(`[codex-live] session=${localThreadId} runtime=${runtime} no app-server client`);
             return abandon();
@@ -591,36 +638,40 @@ export class LocalAgentHost {
             console.error(`[codex-live] session=${localThreadId} runtime=${runtime} forwarder init failed: ${err instanceof Error ? err.message : String(err)}`);
             return abandon();
         }
-        // Apply the agent-spec model (skills were applied above via `$CODEX_HOME/skills/`).
-        // A resumed thread keeps its stored model; otherwise use the agent-spec model (or
-        // the runtime default). The model rides a launch `-c model=` on the TUI (see
-        // `codexTerminalSpec`) / `turn/start` on injection, since rynx doesn't create the thread.
-        const model = resolveRuntimeModel(this.config, runtime, record?.model ?? liveCfg.model);
-        const hasCurrentEffortSource = Boolean(opts?.agentName || opts?.agentSpec || opts?.reasoningEffort);
-        const reasoningEffort = hasCurrentEffortSource
-            ? liveCfg.reasoningEffort
-            : record?.reasoningEffort ?? liveCfg.reasoningEffort;
+        const model = execution.model;
+        const reasoningEffort = execution.reasoningEffort ?? undefined;
         let markReady;
         const ready = new Promise((resolve) => {
             markReady = resolve;
         });
+        let markTerminalReady;
+        const terminalReady = new Promise((resolve) => {
+            markTerminalReady = resolve;
+        });
         const live = {
             injectClient,
             forwarderClient,
             forwarder: null,
             runtime,
-            cwd,
+            workspace,
+            execution,
+            sandbox,
+            approvalPolicy,
             model,
             reasoningEffort,
-            ...(liveCfg.instructions ? { instructions: liveCfg.instructions } : {}),
+            ...(execution.instructions ? { instructions: execution.instructions } : {}),
             threadId: record?.codexSessionId ?? null,
             ready,
             markReady,
+            terminalReady,
+            markTerminalReady,
             injectLock: Promise.resolve(),
+            pendingInjectedInputs: [],
+            publishInjectedInput: () => undefined,
             subscribing: false,
+            rotationPending: false,
             stopped: false,
-            skillsCleanup: liveCfg.skillsCleanup,
-            configSignature,
+            skillsCleanup: snapshotSkills.skillsCleanup,
             interactionOwners: new Map(),
             interactionStandbys: new Map(),
             interactionSubmissions: new Map(),
@@ -630,15 +681,25 @@ export class LocalAgentHost {
             interactionFailedClients: new Map(),
             disconnectedClients: new Set(),
         };
+        let currentSessionId = localThreadId;
+        let pendingRotationEvents = null;
+        const emitCurrent = (event) => {
+            if (pendingRotationEvents) {
+                pendingRotationEvents.push(event);
+                return;
+            }
+            emit(event);
+        };
         let normalizer = null;
         let currentResponseId = null;
         const startNormalizer = (turnId) => {
-            const responseId = turnId ? `resp_codex_${turnId}` : "resp_codex_native";
+            const responseId = live.pendingInjectedInputs.find((entry) => entry.responseId)?.responseId ??
+                (turnId ? `resp_codex_${turnId}` : "resp_codex_native");
             if (normalizer && currentResponseId === responseId)
                 return normalizer;
             currentResponseId = responseId;
             normalizer = new SessionNormalizer({
-                sessionId: localThreadId,
+                sessionId: currentSessionId,
                 // turnId unknown → fixed literal (NEVER random): items arriving before
                 // `turn/started` land on ONE response instead of splitting into random
                 // ids (the DB `resp_codex_<uuid>` doubling). Mirrors reference implementation `_response_id`.
@@ -650,6 +711,19 @@ export class LocalAgentHost {
             });
             return normalizer;
         };
+        live.publishInjectedInput = (turnId, content) => {
+            const n = startNormalizer(turnId);
+            const pending = live.pendingInjectedInputs.find((entry) => entry.signature === JSON.stringify(content) && entry.responseId === undefined);
+            if (pending && currentResponseId)
+                pending.responseId = currentResponseId;
+            for (const se of n.userInput(content))
+                emitCurrent(se);
+        };
+        const clearPendingInputsForResponse = (responseId) => {
+            if (!responseId)
+                return;
+            live.pendingInjectedInputs = live.pendingInjectedInputs.filter((entry) => entry.responseId !== responseId);
+        };
         const rememberSettledInteraction = (interactionId) => {
             live.settledInteractions.add(interactionId);
             if (live.settledInteractions.size <= MAX_CODEX_SETTLED_INTERACTIONS)
@@ -692,7 +766,7 @@ export class LocalAgentHost {
                         ...(event.reason ? { reason: event.reason } : {}),
                     };
             for (const se of n.next(agentEvent))
-                emit(se);
+                emitCurrent(se);
         };
         const clearRecovery = (interactionId) => {
             live.interactionRecoveries.delete(interactionId);
@@ -848,24 +922,38 @@ export class LocalAgentHost {
         const sink = {
             onTurnStart: (turnId) => startNormalizer(turnId),
             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" || pending?.state === "prepublished") {
+                    live.pendingInjectedInputs.splice(live.pendingInjectedInputs.indexOf(pending), 1);
+                    return;
+                }
+                if (pending)
+                    pending.observed = true;
                 const n = normalizer ?? startNormalizer();
-                for (const se of n.userInput(content))
-                    emit(se);
+                for (const se of n.userInput(normalizedContent))
+                    emitCurrent(se);
             },
             onEvent: (event) => {
                 const n = normalizer ?? startNormalizer();
                 for (const se of n.next(event))
-                    emit(se);
+                    emitCurrent(se);
             },
             onTurnEnd: (usage) => {
                 closeCanonicalInteractions();
                 if (!normalizer)
                     return;
-                if (usage)
+                const completedResponseId = currentResponseId;
+                if (usage) {
                     for (const se of normalizer.next({ type: "turn_completed", usage }))
-                        emit(se);
+                        emitCurrent(se);
+                }
                 for (const se of normalizer.next({ type: "done" }))
-                    emit(se);
+                    emitCurrent(se);
+                clearPendingInputsForResponse(completedResponseId);
                 normalizer = null;
                 currentResponseId = null;
             },
@@ -873,6 +961,7 @@ export class LocalAgentHost {
                 closeCanonicalInteractions();
                 if (!normalizer)
                     return;
+                const failedResponseId = currentResponseId;
                 const responseStopped = error.message === "Codex turn was interrupted";
                 const providerName = runtime === "traex" ? "Traex" : "Codex";
                 const message = responseStopped
@@ -887,14 +976,14 @@ export class LocalAgentHost {
                     message,
                     source: "execution",
                 }))
-                    emit(se);
+                    emitCurrent(se);
+                clearPendingInputsForResponse(failedResponseId);
                 normalizer = null;
                 currentResponseId = null;
             },
-            // The TUI creates the thread; the forwarder connection sees its broadcast
-            // `thread/started`. Persist the id, unblock injection, and start the
-            // resume-subscribe loop (which parks until the thread's first turn).
-            onThreadStarted: (threadId) => this.onLiveThreadStarted(live, localThreadId, opts?.agentName ?? record?.agent, threadId),
+            // A resumed TUI may rebroadcast `thread/started`; binding is idempotent.
+            shouldIgnoreThreadStarted: (threadId, forkedFromId) => this.shouldIgnoreManagedForkThreadStarted(live, threadId, forkedFromId),
+            onThreadStarted: (threadId, forkedFromId) => this.onLiveThreadStarted(live, localThreadId, threadId, forkedFromId),
             onThreadActive: () => live.releaseActive?.(),
         };
         const forwarder = new CodexSessionForwarder(forwarderClient, sink, {
@@ -908,99 +997,169 @@ export class LocalAgentHost {
             surfaceQueueStatus: runtime === "traex",
         });
         live.forwarder = forwarder;
+        live.onNativeThreadRotated = (threadId, kind) => {
+            if (live.rotationPending) {
+                live.stopped = true;
+                return;
+            }
+            const previousSessionId = currentSessionId;
+            const newSessionId = makeSessionId();
+            live.rotationPending = true;
+            currentSessionId = newSessionId;
+            normalizer = null;
+            currentResponseId = null;
+            live.pendingInjectedInputs = [];
+            pendingRotationEvents = [];
+            void this.sessionStore
+                .get(previousSessionId)
+                .then((previous) => this.sessionStore.set({
+                localThreadId: newSessionId,
+                codexSessionId: threadId,
+                ...(kind === "fork" ? { parentSessionId: previousSessionId } : {}),
+                ...(previous?.runtimeHomeOwnerSessionId
+                    ? { runtimeHomeOwnerSessionId: previous.runtimeHomeOwnerSessionId }
+                    : {}),
+                updatedAt: new Date().toISOString(),
+            }))
+                .then(() => {
+                emit({
+                    type: "session.rotated",
+                    sessionId: previousSessionId,
+                    newSessionId,
+                    kind,
+                });
+                this.liveSessions.set(newSessionId, live);
+                retargetMirror?.(newSessionId, {
+                    kind,
+                    workspace: structuredClone(live.workspace),
+                    execution: structuredClone(live.execution),
+                    ...(kind === "fork" ? { parentSessionId: previousSessionId } : {}),
+                });
+                const queued = pendingRotationEvents ?? [];
+                pendingRotationEvents = null;
+                live.rotationPending = false;
+                for (const event of queued)
+                    emit(event);
+                void this.subscribeUntilReady(live, threadId);
+            })
+                .catch(() => {
+                pendingRotationEvents = null;
+                live.rotationPending = false;
+                live.stopped = true;
+            });
+        };
         bindInteractionClient(injectClient);
         bindInteractionClient(forwarderClient);
         this.liveSessions.set(localThreadId, live);
         forwarder.start();
-        // A resumed session already has a thread id — bind immediately; a fresh
-        // session waits for the TUI's broadcast `thread/started` (via onThreadStarted).
-        if (record?.codexSessionId) {
-            this.onLiveThreadStarted(live, localThreadId, record.agent, record.codexSessionId);
-        }
-        return true;
-    }
-    async refreshLiveCodexSession(localThreadId, live, opts) {
-        const desiredRuntime = opts?.runtime ?? live.runtime;
-        if (desiredRuntime !== live.runtime)
-            return false;
-        const configSignature = liveConfigSignature(opts, live.runtime, live.cwd);
-        if (live.configSignature === configSignature)
-            return true;
-        let liveCfg;
-        try {
-            liveCfg = await this.resolveLiveAgentConfig(localThreadId, opts, live.runtime, live.cwd);
-        }
-        catch (err) {
-            console.error(`[agent-spec] session=${localThreadId} agent=${opts?.agentName ?? "-"} failed to refresh: ${err instanceof Error ? err.message : String(err)}`);
-            return false;
-        }
-        const previousCleanup = live.skillsCleanup;
+        // Existing bindings resume through the public app-server API. A fresh thread
+        // is created by the native remote TUI instead: its `thread/started`
+        // notification binds this live handle in `onLiveThreadStarted`. Do not
+        // synthesize Codex's private rollout JSONL merely to make a just-created,
+        // turn-less app-server thread resumable by the TUI.
         try {
-            const liveSkills = liveCfg.selectedSkills.map((s) => ({ name: s.name, dir: s.dir }));
-            populateCodexSkills(this.runtimeHome(live.runtime), liveSkills);
-            void previousCleanup?.().catch(() => undefined);
-            this.sessionSandbox = liveCfg.sandbox;
-            this.sessionApprovalPolicy = liveCfg.approvalPolicy;
-            live.model = resolveRuntimeModel(this.config, live.runtime, liveCfg.model);
-            live.reasoningEffort = liveCfg.reasoningEffort;
-            live.instructions = liveCfg.instructions;
-            live.skillsCleanup = liveCfg.skillsCleanup;
-            live.configSignature = configSignature;
-            if (live.threadId) {
-                // Keep already-running TUI turns aligned too; turn/start below carries
-                // the same overrides for web injection. Older app-servers may not have
-                // thread/settings/update, so refresh remains best-effort.
-                await live.injectClient
-                    .threadSettingsUpdate({
-                    threadId: live.threadId,
-                    ...(live.model ? { model: live.model } : {}),
-                    effort: live.reasoningEffort ?? null,
-                })
-                    .catch(() => undefined);
-                void this.sessionStore
-                    .set({
-                    localThreadId,
-                    codexSessionId: live.threadId,
-                    cwd: live.cwd,
-                    model: live.model,
-                    reasoningEffort: live.reasoningEffort,
-                    runtime: live.runtime,
-                    agent: opts?.agentName,
-                    updatedAt: new Date().toISOString(),
-                })
-                    .catch(() => undefined);
+            if (record?.codexSessionId) {
+                let resumeError;
+                let resumedThreadId;
+                const attempts = 20;
+                for (let attempt = 0; attempt < attempts; attempt += 1) {
+                    try {
+                        const resumed = await injectClient.threadResume({
+                            threadId: record.codexSessionId,
+                            ...threadWorkspaceParams(runtime, workspace, sandbox),
+                            approvalPolicy,
+                            excludeTurns: true,
+                        });
+                        resumedThreadId = resumed.threadId;
+                        break;
+                    }
+                    catch (error) {
+                        resumeError = error;
+                        if (!isRetryableThreadResumeError(error))
+                            throw error;
+                        if (attempt + 1 < attempts) {
+                            await new Promise((resolve) => setTimeout(resolve, 150));
+                        }
+                    }
+                }
+                if (resumedThreadId) {
+                    this.onLiveThreadStarted(live, localThreadId, resumedThreadId);
+                }
+                else {
+                    // Never replace an existing binding. A delayed native index is
+                    // retryable; a genuinely missing thread remains an explicit error.
+                    throw resumeError;
+                }
+            }
+            else {
+                // No thread exists yet, so the TUI must launch without `resume`. Once it
+                // broadcasts `thread/started`, the normal ready + subscription path
+                // takes over and web injection can begin.
+                live.markTerminalReady(true);
             }
-            return true;
         }
         catch (err) {
-            void liveCfg.skillsCleanup().catch(() => undefined);
-            console.error(`[codex-live] session=${localThreadId} runtime=${live.runtime} skill refresh failed: ${err instanceof Error ? err.message : String(err)}`);
-            return false;
+            this.liveSessions.delete(localThreadId);
+            live.stopped = true;
+            forwarder.stop();
+            void forwarderClient.stop().catch(() => undefined);
+            console.error(`[codex-live] session=${localThreadId} runtime=${runtime} thread bind failed: ${err instanceof Error ? err.message : String(err)}`);
+            return abandon();
         }
+        return true;
     }
     /** Bind a session's codex thread id once known (TUI broadcast or store): persist
      *  it, unblock injection, and kick off the resume-subscribe loop (once). */
-    onLiveThreadStarted(live, localThreadId, agent, threadId) {
+    onLiveThreadStarted(live, localThreadId, threadId, forkedFromId) {
+        const previousThreadId = live.threadId;
+        if (previousThreadId && previousThreadId !== threadId) {
+            live.threadId = threadId;
+            live.subscribing = true;
+            live.onNativeThreadRotated?.(threadId, forkedFromId === previousThreadId ? "fork" : "clear");
+            return;
+        }
         if (live.subscribing)
             return;
         live.subscribing = true;
         live.threadId = threadId;
         void this.sessionStore
-            .set({
-            localThreadId,
-            codexSessionId: threadId,
-            cwd: live.cwd,
-            // Persist the agent-spec-resolved model (was the config default), so a
-            // resume/reconnect keeps running the agent's model, not the global one.
-            model: live.model,
-            reasoningEffort: live.reasoningEffort,
-            runtime: live.runtime,
-            agent,
-            updatedAt: new Date().toISOString(),
+            .get(localThreadId)
+            .then((existing) => {
+            if (existing?.codexSessionId === threadId)
+                return;
+            return this.sessionStore.set({
+                localThreadId,
+                codexSessionId: threadId,
+                ...(existing?.parentSessionId
+                    ? { parentSessionId: existing.parentSessionId }
+                    : {}),
+                ...(existing?.runtimeHomeOwnerSessionId
+                    ? { runtimeHomeOwnerSessionId: existing.runtimeHomeOwnerSessionId }
+                    : {}),
+                updatedAt: new Date().toISOString(),
+            });
         })
             .catch(() => undefined);
         live.markReady(); // thread id known → injection can turn/start
-        void this.subscribeUntilReady(live, threadId);
+        void this.subscribeUntilReady(live, threadId).then(live.markTerminalReady);
+    }
+    shouldIgnoreManagedForkThreadStarted(live, threadId, forkedFromId) {
+        const pending = live.managedFork;
+        if (pending && forkedFromId === pending.sourceThreadId) {
+            pending.observedThreadIds.add(threadId);
+            return true;
+        }
+        const expectedSource = this.managedForkThreadStarts.get(threadId);
+        return expectedSource !== undefined && expectedSource === forkedFromId;
+    }
+    rememberManagedForkThreadStart(threadId, sourceThreadId) {
+        this.managedForkThreadStarts.set(threadId, sourceThreadId);
+        const timer = setTimeout(() => {
+            if (this.managedForkThreadStarts.get(threadId) === sourceThreadId) {
+                this.managedForkThreadStarts.delete(threadId);
+            }
+        }, 5_000);
+        timer.unref?.();
     }
     /**
      * Subscribe the forwarder connection to a thread (reference implementation's
@@ -1016,17 +1175,18 @@ export class LocalAgentHost {
             try {
                 const resp = await live.forwarderClient.threadResume({
                     threadId,
-                    cwd: live.cwd,
+                    ...threadWorkspaceParams(live.runtime, live.workspace, live.sandbox),
+                    approvalPolicy: live.approvalPolicy,
                     excludeTurns: !sawNotReady,
                 });
                 if (sawNotReady && Array.isArray(resp.thread.turns) && resp.thread.turns.length > 0) {
                     live.forwarder.replayBackfill(resp.thread.turns);
                 }
-                return; // subscribed — live item/turn notifications now flow to the forwarder
+                return true; // subscribed — live item/turn notifications now flow to the forwarder
             }
             catch (error) {
                 if (!isThreadNotReadyError(error)) {
-                    return; // other failure — injection still works via the backend client
+                    return false; // other failure — injection still works via the backend client
                 }
                 sawNotReady = true;
                 // Park until the thread goes active (its first turn materializes the
@@ -1038,13 +1198,14 @@ export class LocalAgentHost {
                 live.releaseActive = undefined;
             }
         }
+        return false;
     }
     /** Await a live session's thread binding (bounded). Returns false on timeout /
      *  no live session. Injection and the runner's `live.ready` gate on this. */
     async waitLiveReady(localThreadId, timeoutMs = 20_000) {
         const claude = this.liveClaudeSessions.get(localThreadId);
         if (claude)
-            return raceReady(claude.ready, timeoutMs);
+            return raceReady(claude.ready, timeoutMs, claude.failed);
         const live = this.liveSessions.get(localThreadId);
         if (!live)
             return false;
@@ -1057,11 +1218,36 @@ export class LocalAgentHost {
             clearTimeout(timer);
         return ok;
     }
+    /** Await the stronger Terminal gate: another app-server connection has
+     * successfully resumed the thread, so the detached TUI cannot race rollout
+     * discovery or indexing. */
+    async waitTerminalReady(localThreadId, timeoutMs = 20_000) {
+        const claude = this.liveClaudeSessions.get(localThreadId);
+        // Claude has no separate app-server indexing gate. Its TUI must launch first;
+        // SessionStart then reveals the native id + actual transcript path.
+        if (claude)
+            return true;
+        const live = this.liveSessions.get(localThreadId);
+        if (!live)
+            return false;
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), timeoutMs);
+        });
+        const ready = await Promise.race([live.terminalReady, timeout]);
+        if (timer)
+            clearTimeout(timer);
+        return ready;
+    }
+    /** Diagnostic from the provider adapter when native discovery/resume failed. */
+    liveSessionError(localThreadId) {
+        return this.liveClaudeSessions.get(localThreadId)?.error;
+    }
     /**
      * Inject a user turn into a session's live codex thread — reference implementation's
      * single-writer web send. `turn/steer` when a turn is open (mid-turn
-     * supplement), else `turn/start`. NEVER creates a thread (the TUI owns creation;
-     * this targets the id the forwarder captured). Serialized per session so two
+     * supplement), else `turn/start`. The thread was created by the native TUI or
+     * resumed from the persisted native id. Serialized per session so two
      * injects can't double-open a turn.
      *
      * Returns an {@link InjectOutcome}: `notLive` when this session has no live
@@ -1077,15 +1263,34 @@ export class LocalAgentHost {
         const claude = this.liveClaudeSessions.get(localThreadId);
         if (claude) {
             const text = claudeInputText(runtimeInput);
+            const content = runtimeUserContent(runtimeInput);
+            const pendingInput = {
+                content,
+                signature: JSON.stringify(content),
+                state: runtimeInput.responseId ? "prepublished" : "awaiting",
+                observed: false,
+                ...(runtimeInput.responseId ? { responseId: runtimeInput.responseId } : {}),
+            };
+            claude.pendingInjectedInputs.push(pendingInput);
+            const forgetPendingInput = () => {
+                const index = claude.pendingInjectedInputs.indexOf(pendingInput);
+                if (index >= 0)
+                    claude.pendingInjectedInputs.splice(index, 1);
+            };
             const token = claudeAttachmentToken(text);
             if (token) {
-                claude.pendingImageInputs.set(token, runtimeUserContent(runtimeInput));
+                claude.pendingImageInputs.set(token, content);
                 const expiry = setTimeout(() => claude.pendingImageInputs.delete(token), 5 * 60_000);
                 expiry.unref?.();
             }
             const outcome = await this.injectClaude(claude, localThreadId, text);
-            if (token && (outcome === "notLive" || outcome === "notReady")) {
-                claude.pendingImageInputs.delete(token);
+            if (outcome !== "injected") {
+                forgetPendingInput();
+                if (token)
+                    claude.pendingImageInputs.delete(token);
+            }
+            else if (pendingInput.observed) {
+                forgetPendingInput();
             }
             return outcome;
         }
@@ -1093,6 +1298,8 @@ export class LocalAgentHost {
         if (!live)
             return "notLive";
         const run = live.injectLock.then(async () => {
+            if (live.rotationPending || live.stopped)
+                return "failed";
             // Park until the thread binds (~60s, reference implementation codex_native_executor:177-186),
             // not a 20s race that returns false and lets the caller re-run on a 2nd path.
             const bound = await this.waitLiveReady(localThreadId, 60_000);
@@ -1100,34 +1307,74 @@ export class LocalAgentHost {
             if (!bound || !threadId)
                 return "notReady";
             const nativeInput = buildRuntimeUserInput(runtimeInput);
+            const content = runtimeUserContent(runtimeInput);
+            const pendingInput = {
+                content,
+                signature: JSON.stringify(content),
+                state: runtimeInput.responseId ? "prepublished" : "awaiting",
+                observed: false,
+                ...(runtimeInput.responseId ? { responseId: runtimeInput.responseId } : {}),
+            };
+            live.pendingInjectedInputs.push(pendingInput);
+            const forgetPendingInput = () => {
+                const index = live.pendingInjectedInputs.indexOf(pendingInput);
+                if (index >= 0)
+                    live.pendingInjectedInputs.splice(index, 1);
+            };
             try {
                 // Inject via the BACKEND client (the forwarder connection only observes).
                 if (live.forwarder.isTurnOpen()) {
                     const turnId = live.forwarder.currentTurnId();
                     if (turnId) {
-                        await live.injectClient.turnSteer({
+                        const steered = await live.injectClient.turnSteer({
                             threadId,
                             expectedTurnId: turnId,
                             input: nativeInput,
                         });
+                        if (pendingInput.state === "prepublished") {
+                            // The caller already persisted and published this user input
+                            // before waiting for the native Terminal to become ready.
+                        }
+                        else if (pendingInput.observed) {
+                            forgetPendingInput();
+                        }
+                        else {
+                            live.publishInjectedInput(steered.turnId, pendingInput.content);
+                            pendingInput.state = "optimistic";
+                        }
                         return "injected";
                     }
                 }
                 // Carry the agent-spec model on the turn so a web-injected turn runs the
                 // agent's model even if the TUI's config default differs.
-                await live.injectClient.turnStart({
+                const started = await live.injectClient.turnStart({
                     threadId,
                     input: nativeInput,
-                    cwd: live.cwd,
+                    ...turnWorkspaceParams(live.runtime, live.workspace, live.sandbox),
+                    approvalPolicy: live.approvalPolicy,
                     ...(live.model ? { model: live.model } : {}),
                     ...(live.reasoningEffort ? { effort: live.reasoningEffort } : {}),
                 });
+                if (pendingInput.state === "prepublished") {
+                    // The caller already persisted and published this user input before
+                    // waiting for the native Terminal to become ready.
+                }
+                else if (pendingInput.observed) {
+                    forgetPendingInput();
+                }
+                else {
+                    live.publishInjectedInput(started.turnId, pendingInput.content);
+                    pendingInput.state = "optimistic";
+                }
                 return "injected";
             }
-            catch {
-                // RPC failed → hard error; caller reports it and does NOT re-run
-                // (reference implementation: inject failure ⇒ response.failed, never local re-run).
-                return "failed";
+            catch (error) {
+                forgetPendingInput();
+                // Preserve the app-server's error instead of collapsing every failure
+                // into the unactionable `live injection failed` string.
+                const detail = codexInjectionError(error);
+                console.error(`[codex-live] session=${localThreadId} runtime=${live.runtime} injection failed: ${detail}`);
+                throw new Error(detail, { cause: error });
             }
         });
         live.injectLock = run.then(() => undefined, () => undefined);
@@ -1236,6 +1483,15 @@ export class LocalAgentHost {
         for (const forwarder of this.pendingClaudeFinalizers)
             forwarder.finalizeStop();
         this.pendingClaudeFinalizers.clear();
+        // A runner owns its app-server processes. Stopping only the forwarder leaves
+        // those children re-parented after the runner exits, along with remote TUIs
+        // that can only reconnect to a dead session. `stop()` sends SIGTERM before
+        // its returned promise yields, so this remains safe in the synchronous
+        // runner shutdown path.
+        for (const backend of this.backends.values()) {
+            void backend.appServerClient?.stop().catch(() => undefined);
+        }
+        this.backends.clear();
     }
     // --- claude-native live session (parallel to the codex methods above) -----
     /** The interactive `claude` TUI spec for a claude-native live session: the real
@@ -1245,7 +1501,10 @@ export class LocalAgentHost {
      *  generic interaction bridge and remain inside the active Turn. */
     claudeTerminalSpec(localThreadId, record) {
         const live = this.liveClaudeSessions.get(localThreadId);
-        const cwd = record?.cwd ?? live?.cwd ?? process.cwd();
+        if (!live) {
+            throw new CodexRuntimeError("session snapshots are not live", 409, "session_not_live");
+        }
+        const cwd = live.workspace.cwd;
         try {
             ensureProjectTrusted(cwd);
         }
@@ -1253,24 +1512,17 @@ export class LocalAgentHost {
             // A malformed ~/.claude.json shouldn't block launch; claude re-prompts.
         }
         const inheritedSettings = buildManagedClaudeSettings(cwd, {});
-        const inheritedPermissions = inheritedSettings.permissions;
-        const inheritedPermissionMode = inheritedPermissions &&
-            typeof inheritedPermissions === "object" &&
-            !Array.isArray(inheritedPermissions) &&
-            typeof inheritedPermissions.defaultMode === "string"
-            ? inheritedPermissions.defaultMode
-            : undefined;
-        const hookPermissionMode = live?.permissionMode ?? inheritedPermissionMode;
+        const effectiveSettings = applyClaudePermissionModeSnapshot(inheritedSettings, live.permissionMode);
+        const hookPermissionMode = live.permissionMode;
         const hookSettings = buildClaudeHookSettings({
             bridgeDir: claudeBridgeDir(localThreadId),
             ...(hookPermissionMode ? { permissionMode: hookPermissionMode } : {}),
             messageDisplay: true,
             statusLine: true,
         });
-        const settings = { ...inheritedSettings, ...hookSettings };
+        const settings = { ...effectiveSettings, ...hookSettings };
         const settingsPath = writeManagedClaudeSettings(claudeBridgeDir(localThreadId), settings);
-        // The live session (created by startLiveClaudeSession before the pane launches)
-        // carries the agent-spec launch config: model, instructions, and skills.
+        // The live session carries the immutable execution snapshot used by Chat.
         const args = buildClaudeTuiArgs({
             settingsJson: settingsPath,
             // A rynx-managed Session must have one interaction owner. Loading host or
@@ -1278,10 +1530,21 @@ export class LocalAgentHost {
             // resolve the same native request while rynx still exposes it as pending.
             // Explicit rynx hooks and selected-skill plugin dirs remain enabled.
             settingSources: "",
-            model: live?.launchModel ?? resolveRuntimeModel(this.config, "claude", record?.model),
-            ...(live?.launchInstructions ? { appendSystemPrompt: live.launchInstructions } : {}),
-            ...(record?.codexSessionId ? { resume: record.codexSessionId } : {}),
-            ...(live?.launchExtraArgs?.length ? { extraArgs: live.launchExtraArgs } : {}),
+            model: live.execution.model,
+            ...(live.execution.instructions
+                ? { appendSystemPrompt: live.execution.instructions }
+                : {}),
+            additionalDirs: providerAdditionalDirs(live.workspace),
+            ...(live.forkIntent
+                ? {
+                    resume: live.forkIntent.sourceClaudeSessionId,
+                    forkSession: true,
+                    sessionId: live.forkIntent.targetClaudeSessionId,
+                }
+                : record?.codexSessionId
+                    ? { resume: record.codexSessionId }
+                    : {}),
+            ...(live.launchExtraArgs.length ? { extraArgs: live.launchExtraArgs } : {}),
         });
         return {
             command: resolveRuntimeBinary("claude"),
@@ -1292,44 +1555,15 @@ export class LocalAgentHost {
             env: { ...process.env, RYNX_SESSION_ID: localThreadId },
         };
     }
-    /** Bring up a claude-native live forwarder: prepare the bridge dir (the TUI's
-     *  hooks write into it), then tail bridge + transcript and drive a per-turn
-     *  {@link SessionNormalizer} → `emit` (the SAME sink shape the codex path uses). */
-    /** Resolve an agent spec's launch config — model, instructions, and the session skill env —
-     *  for a LIVE native session, reusing the same core resolvers the non-live
-     *  run path uses ({@link resolveAgentExecution} for the model,
-     *  {@link resolveAgent} for instructions and skills).
-     *
-     *  Skills are spec-rooted: each declared ref is replayed into a
-     *  SESSION-scoped temp dir (cache-accelerated); the owner's catalog plays no
-     *  role, and no spec / no `skills` means ZERO skills. Every declared skill
-     *  must resolve at its declared content hash; missing, failed, or drifted
-     *  materialization aborts launch before a native session starts.
-     *  `skillsCleanup` removes the session dir (call on session stop). */
-    async resolveLiveAgentConfig(localThreadId, opts, runtime, cwd) {
-        // Inline spec needs an id only so a relative instructions-file path can
-        // resolve (mirrors runLocked); a preset agent loads by name.
-        const spec = opts?.agentSpec
-            ? { ...opts.agentSpec, id: opts.agentName ?? "inline" }
-            : undefined;
-        const exec = await resolveAgentExecution({
-            config: this.config,
-            ...(opts?.agentName ? { agentName: opts.agentName } : {}),
-            ...(opts?.agentSpec ? { spec: opts.agentSpec } : {}),
-            runtime,
-            ...(opts?.reasoningEffort ? { reasoningEffort: opts.reasoningEffort } : {}),
-        });
-        const resolved = await resolveAgent({
-            config: this.config,
-            cwd,
-            ...(opts?.agentName ? { agentName: opts.agentName } : {}),
-            ...(spec ? { spec } : {}),
-        });
+    /** Materialize only the immutable skill declarations stored on the Session.
+     * Provider startup never re-opens an Agent template or process-level plugin
+     * snapshot. */
+    async prepareExecutionSkills(execution) {
         const sessionSkillsDir = await mkdtemp(path.join(tmpdir(), "rynx-session-skills-"));
         let skillEnv;
         try {
-            skillEnv = await buildAgentSkillEnvironment(resolved.skills, sessionSkillsDir);
-            const declaredNames = (resolved.skills ?? []).map((skill) => skill.name);
+            skillEnv = await buildAgentSkillEnvironment(execution.skills, sessionSkillsDir);
+            const declaredNames = execution.skills.map((skill) => skill.name);
             const resolvedNames = skillEnv.resolved.map((skill) => skill.name);
             const { report } = skillEnv;
             if (report.errors.length > 0 ||
@@ -1351,52 +1585,89 @@ export class LocalAgentHost {
             await rm(sessionSkillsDir, { recursive: true, force: true }).catch(() => undefined);
             throw error;
         }
-        const agent = opts?.agentName ?? resolved.name ?? "-";
         const { report } = skillEnv;
         if (report.installed.length > 0) {
-            console.error(`[skills] session=${localThreadId} agent=${agent} installed=[${report.installed.join(", ")}]`);
+            console.error(`[skills] installed=[${report.installed.join(", ")}]`);
+        }
+        try {
+            const materializedPluginSkills = await Promise.allSettled(execution.pluginSkills.map(async (source, sourceIndex) => {
+                const packageRoot = await realpath(source.packageRoot);
+                const skillRoot = await realpath(source.root);
+                const relativeSkillRoot = path.relative(packageRoot, skillRoot);
+                if (relativeSkillRoot === ".." ||
+                    relativeSkillRoot.startsWith(`..${path.sep}`) ||
+                    path.isAbsolute(relativeSkillRoot)) {
+                    throw new Error(`plugin skill root escaped package: ${source.installationId}`);
+                }
+                const snapshotPackageRoot = path.join(sessionSkillsDir, ".plugin-packages", `source-${sourceIndex}`);
+                await mkdir(path.dirname(snapshotPackageRoot), { recursive: true });
+                await cp(packageRoot, snapshotPackageRoot, {
+                    recursive: true,
+                    errorOnExist: true,
+                    force: false,
+                    dereference: false,
+                });
+                const canonicalSnapshotPackageRoot = await realpath(snapshotPackageRoot);
+                const integrity = await hashPluginPackageTree(canonicalSnapshotPackageRoot);
+                if (integrity !== source.integrity) {
+                    throw new Error(`plugin package integrity changed: ${source.installationId}`);
+                }
+                const snapshotSkillRoot = await realpath(path.join(canonicalSnapshotPackageRoot, relativeSkillRoot));
+                const relativeSnapshotSkillRoot = path.relative(canonicalSnapshotPackageRoot, snapshotSkillRoot);
+                if (relativeSnapshotSkillRoot === ".." ||
+                    relativeSnapshotSkillRoot.startsWith(`..${path.sep}`) ||
+                    path.isAbsolute(relativeSnapshotSkillRoot)) {
+                    throw new Error(`snapshotted plugin skill root escaped package: ${source.installationId}`);
+                }
+                const discovered = await scanSkillsDir(snapshotSkillRoot);
+                if (discovered.length === 0) {
+                    throw new Error(`plugin skill root is empty: ${source.installationId}`);
+                }
+                return discovered.map((skill) => ({
+                    ...skill,
+                    name: providerPluginSkillName(source.namespace, skill.name),
+                }));
+            }));
+            const failedPluginSkill = materializedPluginSkills.find((result) => result.status === "rejected");
+            if (failedPluginSkill?.status === "rejected") {
+                throw failedPluginSkill.reason;
+            }
+            const pluginSkills = materializedPluginSkills.flatMap((result) => result.status === "fulfilled" ? result.value : []);
+            return {
+                selectedSkills: [...skillEnv.resolved, ...pluginSkills],
+                skillsCleanup: () => rm(sessionSkillsDir, { recursive: true, force: true }),
+            };
+        }
+        catch (error) {
+            await rm(sessionSkillsDir, { recursive: true, force: true }).catch(() => undefined);
+            throw error;
         }
-        return {
-            model: exec.model,
-            ...((opts?.agentName || opts?.agentSpec) && resolved.instructions
-                ? { instructions: resolved.instructions }
-                : {}),
-            selectedSkills: skillEnv.resolved,
-            skillsCleanup: () => rm(sessionSkillsDir, { recursive: true, force: true }),
-            ...(resolved.sandbox ? { sandbox: resolved.sandbox } : {}),
-            ...(resolved.approvalPolicy ? { approvalPolicy: resolved.approvalPolicy } : {}),
-            ...(resolved.permissionMode ? { permissionMode: resolved.permissionMode } : {}),
-            ...(exec.reasoningEffort ? { reasoningEffort: exec.reasoningEffort } : {}),
-        };
     }
     async startLiveClaudeSession(localThreadId, emit, record, opts) {
-        const retargetMirror = opts?.retargetMirror;
+        const retargetMirror = opts.retargetMirror;
+        const forkIntent = await this.sessionStore.getClaudeForkIntent?.(localThreadId) ?? null;
+        if (forkIntent && forkIntent.targetSessionId !== localThreadId) {
+            throw new CodexRuntimeError("Claude fork intent targets a different Session", 409, "invalid_fork_intent");
+        }
         const bridgeDir = prepareClaudeBridgeDir(localThreadId);
-        const cwd = record?.cwd ?? opts?.cwd ?? process.cwd();
-        // Apply the agent spec (model / skills / instructions) to the live TUI launch —
-        // NOT just the config default. The stored record model wins if present (a
-        // resumed thread), else the agent-spec resolution. Spec-load errors are logged
-        // and fail the start loudly (mirrors the codex path).
-        let liveCfg;
+        const workspace = structuredClone(opts.workspace);
+        const execution = structuredClone(opts.execution);
+        if (execution.provider !== "claude") {
+            throw new CodexRuntimeError(`cannot launch Claude from ${execution.provider} execution snapshot`, 422, "invalid_execution_snapshot");
+        }
+        const cwd = workspace.cwd;
+        let snapshotSkills;
         try {
-            liveCfg = await this.resolveLiveAgentConfig(localThreadId, opts, "claude", cwd);
+            snapshotSkills = await this.prepareExecutionSkills(execution);
         }
         catch (err) {
-            console.error(`[agent-spec] session=${localThreadId} agent=${opts?.agentName ?? "-"} failed to resolve: ${err instanceof Error ? err.message : String(err)}`);
+            console.error(`[session-snapshot] session=${localThreadId} skill materialization failed: ${err instanceof Error ? err.message : String(err)}`);
             return false;
         }
-        const model = resolveRuntimeModel(this.config, "claude", record?.model ?? liveCfg.model);
-        // Skills → throwaway `--plugin-dir`; instructions → Claude Code's native
-        // `--append-system-prompt`. The plugin dir gets its own copy, so the session
-        // skills dir is disposable here.
-        const skillPlugin = await materializeSkillPlugin(liveCfg.selectedSkills);
-        void liveCfg.skillsCleanup();
-        // Agent-spec permission mode → claude's `--permission-mode` (claude-private
-        // approval axis). Unset sends no flag (claude's own default); any set value
-        // is passed through (`bypassPermissions` is how an agent opts out of the
-        // approval prompt). The shared `sandbox` axis is intentionally NOT applied
-        // here — the live co-drive TUI runs unsandboxed (matches reference implementation's native).
-        const permissionMode = liveCfg.permissionMode;
+        const model = execution.model;
+        const skillPlugin = await materializeSkillPlugin(snapshotSkills.selectedSkills);
+        void snapshotSkills.skillsCleanup();
+        const permissionMode = execution.permissionMode;
         const launchExtraArgs = [
             ...(skillPlugin?.pluginDir ? ["--plugin-dir", skillPlugin.pluginDir] : []),
             ...(permissionMode ? ["--permission-mode", permissionMode] : []),
@@ -1406,9 +1677,18 @@ export class LocalAgentHost {
         let currentSessionId = localThreadId;
         let normalizer = null;
         let currentResponseId;
+        let pendingRotationEvents = null;
+        const emitCurrent = (event) => {
+            if (pendingRotationEvents) {
+                pendingRotationEvents.push(event);
+                return;
+            }
+            emit(event);
+        };
         const startNormalizer = (turnId) => {
             // turnId unknown → fixed literal (never random), aligning reference implementation `_response_id`.
-            const responseId = turnId ? `resp_claude_${turnId}` : "resp_claude_native";
+            const responseId = live.pendingInjectedInputs.find((entry) => entry.responseId)?.responseId ??
+                (turnId ? `resp_claude_${turnId}` : "resp_claude_native");
             if (normalizer && currentResponseId === responseId)
                 return normalizer;
             currentResponseId = responseId;
@@ -1435,26 +1715,33 @@ export class LocalAgentHost {
                         ...(event.reason ? { reason: event.reason } : {}),
                     };
             for (const se of n.next(agentEvent))
-                emit(se);
+                emitCurrent(se);
         };
         let markReady;
         const ready = new Promise((resolve) => {
             markReady = resolve;
         });
+        let markFailed;
+        const failed = new Promise((resolve) => {
+            markFailed = resolve;
+        });
         const live = {
             forwarder: null,
-            cwd,
+            workspace,
+            execution,
             bridgeDir,
             injectLock: Promise.resolve(),
             pendingImageInputs: new Map(),
+            pendingInjectedInputs: [],
             ready,
             markReady,
+            failed,
+            markFailed,
             discoveredReady: false,
             stopped: false,
-            launchModel: model,
-            ...(liveCfg.instructions ? { launchInstructions: liveCfg.instructions } : {}),
             launchExtraArgs,
-            ...(permissionMode ? { permissionMode } : {}),
+            permissionMode,
+            ...(forkIntent ? { forkIntent } : {}),
             ...(skillPlugin?.cleanup ? { skillCleanup: skillPlugin.cleanup } : {}),
         };
         const sink = {
@@ -1465,19 +1752,28 @@ export class LocalAgentHost {
                 const content = token ? live.pendingImageInputs.get(token) : undefined;
                 if (token && content)
                     live.pendingImageInputs.delete(token);
-                for (const se of n.userInput(content ?? text))
-                    emit(se);
+                const normalizedContent = content ?? [{ type: "input_text", text }];
+                const signature = JSON.stringify(normalizedContent);
+                const pending = live.pendingInjectedInputs.find((entry) => entry.signature === signature);
+                if (pending?.state === "prepublished" || pending?.state === "optimistic") {
+                    live.pendingInjectedInputs.splice(live.pendingInjectedInputs.indexOf(pending), 1);
+                    return;
+                }
+                if (pending)
+                    pending.observed = true;
+                for (const se of n.userInput(normalizedContent))
+                    emitCurrent(se);
             },
             onTerminalCommand: (cmd) => {
                 const n = normalizer ?? startNormalizer();
                 for (const se of n.terminalCommand(cmd))
-                    emit(se);
+                    emitCurrent(se);
             },
-            onTodos: (todos) => emit({ type: "session.todos", sessionId: currentSessionId, todos }),
+            onTodos: (todos) => emitCurrent({ type: "session.todos", sessionId: currentSessionId, todos }),
             onEvent: (event) => {
                 const n = normalizer ?? startNormalizer();
                 for (const se of n.next(event))
-                    emit(se);
+                    emitCurrent(se);
             },
             onInteraction: forwardInteraction,
             onTurnEnd: (usage) => {
@@ -1485,11 +1781,13 @@ export class LocalAgentHost {
                     return;
                 const rid = currentResponseId;
                 // statusLine usage (context/cost) rides the turn's response.completed.
-                if (usage)
+                if (usage) {
                     for (const se of normalizer.next({ type: "turn_completed", usage }))
-                        emit(se);
+                        emitCurrent(se);
+                }
                 for (const se of normalizer.next({ type: "done" }))
-                    emit(se);
+                    emitCurrent(se);
+                live.pendingInjectedInputs = live.pendingInjectedInputs.filter((entry) => entry.responseId !== rid);
                 normalizer = null;
                 currentResponseId = undefined;
                 // One-time context-window banner past CONTEXT_WARN_RATIO (a transient note,
@@ -1497,7 +1795,7 @@ export class LocalAgentHost {
                 const pct = usage && typeof usage.used_percentage === "number" ? usage.used_percentage : undefined;
                 if (rid && pct !== undefined && !live.contextWarned && pct >= CONTEXT_WARN_RATIO * 100) {
                     live.contextWarned = true;
-                    emit({
+                    emitCurrent({
                         type: "session.status",
                         sessionId: currentSessionId,
                         responseId: rid,
@@ -1510,7 +1808,7 @@ export class LocalAgentHost {
                 // 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) {
-                    emit({
+                    emitCurrent({
                         type: "session.status",
                         sessionId: currentSessionId,
                         responseId: currentResponseId,
@@ -1521,87 +1819,115 @@ export class LocalAgentHost {
             onTurnError: () => {
                 if (!normalizer)
                     return;
+                const rid = currentResponseId;
                 for (const se of normalizer.fail({
                     code: "agent_error",
                     message: "Agent turn failed",
                     source: "execution",
                 }))
-                    emit(se);
+                    emitCurrent(se);
+                live.pendingInjectedInputs = live.pendingInjectedInputs.filter((entry) => entry.responseId !== rid);
                 normalizer = null;
                 currentResponseId = undefined;
             },
-            onSessionDiscovered: (claudeSessionId) => this.onClaudeDiscovered(live, localThreadId, opts?.agentName ?? record?.agent, claudeSessionId),
+            onSessionDiscovered: (claudeSessionId) => this.onClaudeDiscovered(live, localThreadId, claudeSessionId),
+            onSessionResumeError: (error) => {
+                live.error = error.message;
+                live.markFailed();
+            },
             onSessionRotated: (kind, claudeSessionId) => {
+                if (pendingRotationEvents) {
+                    live.error = "Claude reported another Session rotation before publication completed";
+                    live.markFailed();
+                    return;
+                }
                 // The forwarder already closed the old turn (onTurnEnd) + re-pointed to the
-                // new transcript. Rotate the rynx session: announce on the OLD session (the
-                // mirror still targets it), mint a fresh one, persist it, and re-target the
-                // mirror + terminal transfer so the new session is live AND injectable.
+                // new transcript. Persist the Provider binding first, then announce on
+                // the OLD session and re-target the mirror. Events produced during the
+                // file-store commit are buffered so none can land under the old identity.
                 const previousSessionId = currentSessionId;
                 const newSessionId = makeSessionId();
-                emit({ type: "session.rotated", sessionId: previousSessionId, newSessionId, kind });
+                currentSessionId = newSessionId;
+                normalizer = null;
+                currentResponseId = undefined;
+                live.contextWarned = false;
+                pendingRotationEvents = [];
+                this.liveClaudeSessions.set(newSessionId, live);
                 void this.sessionStore
                     .set({
                     localThreadId: newSessionId,
                     codexSessionId: claudeSessionId,
-                    cwd: live.cwd,
-                    model,
-                    runtime: "claude",
-                    ...(record?.agent ? { agent: record.agent } : {}),
                     ...(kind === "fork" ? { parentSessionId: previousSessionId } : {}),
                     updatedAt: new Date().toISOString(),
                 })
-                    .catch(() => undefined);
-                currentSessionId = newSessionId;
-                normalizer = null;
-                live.contextWarned = false;
-                // Route the new session to THIS live session (host map) + this runner (daemon).
-                this.liveClaudeSessions.set(newSessionId, live);
-                retargetMirror?.(newSessionId, {
-                    kind,
-                    ...(record?.agent ? { agent: record.agent } : {}),
-                    model,
-                    cwd: live.cwd,
-                    parentSessionId: previousSessionId,
+                    .then(() => {
+                    emit({
+                        type: "session.rotated",
+                        sessionId: previousSessionId,
+                        newSessionId,
+                        kind,
+                    });
+                    retargetMirror?.(newSessionId, {
+                        kind,
+                        workspace: structuredClone(live.workspace),
+                        execution: structuredClone(live.execution),
+                        ...(kind === "fork" ? { parentSessionId: previousSessionId } : {}),
+                    });
+                    const queued = pendingRotationEvents ?? [];
+                    pendingRotationEvents = null;
+                    for (const event of queued)
+                        emit(event);
+                })
+                    .catch((error) => {
+                    pendingRotationEvents = null;
+                    live.error = error instanceof Error ? error.message : String(error);
+                    live.markFailed();
                 });
             },
         };
-        // Resume: a known claude session id → tail its transcript immediately.
-        const transcriptPath = record?.codexSessionId
-            ? claudeTranscriptPath(cwd, record.codexSessionId)
-            : undefined;
+        // Claude itself resolves `--resume <id>`. The SessionStart hook is the
+        // authoritative source for the actual transcript path; do not infer or
+        // generate Claude's private on-disk format here.
         live.forwarder = new ClaudeLiveSession({
             bridgeDir,
             sink,
-            ...(transcriptPath ? { transcriptPath } : {}),
-            ...(record?.codexSessionId ? { claudeSessionId: record.codexSessionId } : {}),
+            ...(forkIntent
+                ? { claudeSessionId: forkIntent.targetClaudeSessionId }
+                : record?.codexSessionId
+                    ? { claudeSessionId: record.codexSessionId }
+                    : {}),
+            ...((forkIntent || record?.codexSessionId) ? { resumeAtEndOnDiscovery: true } : {}),
         });
         this.liveClaudeSessions.set(localThreadId, live);
         live.forwarder.start();
-        if (record?.codexSessionId) {
-            live.discoveredReady = true;
-            markReady(); // resumed → injection can proceed without awaiting discovery
-        }
         return true;
     }
     /** Persist claude's discovered session id (reusing the `codexSessionId` store
      *  field, as the claude executor already does) and release the readiness gate. */
-    onClaudeDiscovered(live, localThreadId, agent, claudeSessionId) {
+    onClaudeDiscovered(live, localThreadId, claudeSessionId) {
         if (live.discoveredReady)
             return;
+        const forkIntent = live.forkIntent;
+        if (forkIntent && claudeSessionId !== forkIntent.targetClaudeSessionId) {
+            live.error =
+                `Claude fork created ${claudeSessionId} instead of ${forkIntent.targetClaudeSessionId}`;
+            live.markFailed();
+            return;
+        }
         live.discoveredReady = true;
         void this.sessionStore
             .set({
             localThreadId,
             codexSessionId: claudeSessionId,
-            cwd: live.cwd,
-            // Persist the agent-spec-resolved launch model (was the config default).
-            model: live.launchModel,
-            runtime: "claude",
-            agent,
+            ...(forkIntent ? { parentSessionId: forkIntent.sourceSessionId } : {}),
             updatedAt: new Date().toISOString(),
         })
-            .catch(() => undefined);
-        live.markReady();
+            .then(() => this.sessionStore.deleteClaudeForkIntent?.(localThreadId))
+            .then(() => live.markReady())
+            .catch((error) => {
+            live.error = error instanceof Error ? error.message : String(error);
+            live.markFailed();
+        });
     }
     /** Inject a web message into a claude-native pane via tmux (reference implementation recipe),
      *  serialized per session. Parks until the thread is ready AND the tmux injector
@@ -1683,12 +2009,12 @@ export class LocalAgentHost {
         if (!record?.codexSessionId) {
             return { ok: false, reason: "no_active_thread" };
         }
-        const backend = this.getBackend(record.runtime ?? "codex");
-        if (!backend.appServerClient) {
+        const live = this.liveSessions.get(localThreadId);
+        if (!live) {
             return { ok: false, reason: "unsupported" };
         }
         try {
-            return { ok: true, data: await fn(backend.appServerClient, record.codexSessionId) };
+            return { ok: true, data: await fn(live.injectClient, record.codexSessionId) };
         }
         catch (error) {
             return {
@@ -1714,30 +2040,108 @@ export class LocalAgentHost {
             await client.threadGoalClear({ threadId });
         });
     }
-    async forkSession(currentLocalThreadId, newLocalThreadId) {
+    async forkSession(currentLocalThreadId, newLocalThreadId, options) {
+        const inflight = this.forkingTargets.get(newLocalThreadId);
+        if (inflight)
+            return inflight;
+        const operation = this.performForkSession(currentLocalThreadId, newLocalThreadId, options);
+        this.forkingTargets.set(newLocalThreadId, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.forkingTargets.get(newLocalThreadId) === operation) {
+                this.forkingTargets.delete(newLocalThreadId);
+            }
+        }
+    }
+    async performForkSession(currentLocalThreadId, newLocalThreadId, options) {
         const record = await this.sessionStore.get(currentLocalThreadId);
         if (!record) {
             return { ok: false, reason: "no_active_thread" };
         }
-        const runtime = record.runtime ?? "codex";
-        const backend = this.getBackend(runtime);
-        if (!backend.appServerClient) {
-            return { ok: false, reason: "unsupported" };
+        const live = this.liveSessions.get(currentLocalThreadId);
+        const workspace = live?.workspace ?? options?.workspace;
+        const execution = live?.execution ?? options?.execution;
+        if (!workspace || !execution) {
+            return { ok: false, reason: "no_active_thread" };
+        }
+        if (execution.provider === "claude") {
+            return {
+                ok: false,
+                reason: "unsupported",
+                message: "Claude fork must be materialized by the target runner",
+            };
         }
         try {
-            const forked = await backend.appServerClient.threadFork({
-                threadId: record.codexSessionId,
-                model: record.model,
-                cwd: record.cwd,
-            });
+            const existingTarget = await this.sessionStore.get(newLocalThreadId);
+            if (existingTarget) {
+                if (existingTarget.parentSessionId !== currentLocalThreadId) {
+                    return {
+                        ok: false,
+                        reason: "error",
+                        message: "target Session already belongs to a different fork",
+                    };
+                }
+                return { ok: true, data: undefined };
+            }
+            const runtime = execution.provider;
+            const client = live?.injectClient ??
+                this.getBackend(runtime, execution.budget ?? undefined).appServerClient;
+            if (!client) {
+                return { ok: false, reason: "unsupported" };
+            }
+            await client.ensureInitialized();
+            if (live?.managedFork) {
+                return {
+                    ok: false,
+                    reason: "error",
+                    message: "source Session already has a managed fork in progress",
+                };
+            }
+            const managedFork = live
+                ? {
+                    sourceThreadId: record.codexSessionId,
+                    observedThreadIds: new Set(),
+                }
+                : undefined;
+            const forked = await (async () => {
+                if (live && managedFork)
+                    live.managedFork = managedFork;
+                try {
+                    return await client.threadFork({
+                        threadId: record.codexSessionId,
+                        excludeTurns: true,
+                        ...threadWorkspaceParams(runtime, workspace, execution.sandbox ?? "workspace-write"),
+                        model: execution.model,
+                        approvalPolicy: execution.approvalPolicy,
+                    });
+                }
+                finally {
+                    if (live && live.managedFork === managedFork)
+                        delete live.managedFork;
+                    for (const observedThreadId of managedFork?.observedThreadIds ?? []) {
+                        this.rememberManagedForkThreadStart(observedThreadId, record.codexSessionId);
+                    }
+                }
+            })();
             const forkedThreadId = forked.thread.id;
+            if (live && forkedThreadId) {
+                this.rememberManagedForkThreadStart(forkedThreadId, record.codexSessionId);
+            }
+            if (!forkedThreadId ||
+                forkedThreadId === record.codexSessionId ||
+                (forked.thread.forkedFromId !== undefined &&
+                    forked.thread.forkedFromId !== null &&
+                    forked.thread.forkedFromId !== record.codexSessionId)) {
+                throw new Error("Provider returned an invalid forked thread");
+            }
+            const sourceHomeOwner = record.runtimeHomeOwnerSessionId ?? this.runtimeHomeSessionId;
             await this.sessionStore.set({
                 localThreadId: newLocalThreadId,
                 codexSessionId: forkedThreadId,
-                cwd: record.cwd,
-                model: record.model,
-                reasoningEffort: record.reasoningEffort,
-                runtime,
+                parentSessionId: currentLocalThreadId,
+                runtimeHomeOwnerSessionId: sourceHomeOwner,
                 updatedAt: new Date().toISOString(),
             });
             return { ok: true, data: undefined };
@@ -1751,6 +2155,12 @@ export class LocalAgentHost {
         }
     }
 }
+function codexInjectionError(error) {
+    if (error instanceof CodexTransportError) {
+        return `Codex app-server rejected turn/start: ${error.message} (code ${error.code})`;
+    }
+    return `Codex turn/start failed: ${error instanceof Error ? error.message : String(error)}`;
+}
 export function parseCodexLoginStatus(exitCode, output) {
     const normalized = output.trim();
     const match = normalized.match(/Logged in using (.+)$/im);
@@ -1774,25 +2184,48 @@ export function parseCodexLoginStatus(exitCode, output) {
         issues: normalized ? [normalized] : [],
     };
 }
-/** Race a live session's `ready` promise against a timeout → resolves boolean. */
-function raceReady(ready, timeoutMs) {
+/** Race a live session's `ready` promise against failure / timeout. */
+function raceReady(ready, timeoutMs, failed) {
     let timer;
     const timeout = new Promise((resolve) => {
         timer = setTimeout(() => resolve(false), timeoutMs);
     });
-    return Promise.race([ready.then(() => true), timeout]).finally(() => {
+    const outcomes = [ready.then(() => true), timeout];
+    if (failed)
+        outcomes.push(failed.then(() => false));
+    return Promise.race(outcomes).finally(() => {
         if (timer)
             clearTimeout(timer);
     });
 }
-function liveConfigSignature(opts, runtime, cwd) {
+function sameSessionSnapshots(workspace, execution, opts) {
     return JSON.stringify(stableValue({
-        runtime,
-        cwd,
-        agentName: opts?.agentName,
-        agentSpec: opts?.agentSpec,
+        workspace,
+        execution,
+    })) === JSON.stringify(stableValue({
+        workspace: opts.workspace,
+        execution: opts.execution,
     }));
 }
+/** Freeze the Session's permission choice into the explicit managed settings.
+ * Host/project settings may still contribute allow/deny rules, but changing
+ * their defaultMode cannot silently mutate an existing Session on resume. */
+function applyClaudePermissionModeSnapshot(settings, permissionMode) {
+    const next = { ...settings };
+    const inherited = settings.permissions;
+    const permissions = inherited && typeof inherited === "object" && !Array.isArray(inherited)
+        ? { ...inherited }
+        : {};
+    if (permissionMode)
+        permissions.defaultMode = permissionMode;
+    else
+        delete permissions.defaultMode;
+    if (Object.keys(permissions).length > 0)
+        next.permissions = permissions;
+    else
+        delete next.permissions;
+    return next;
+}
 function stableValue(value) {
     if (Array.isArray(value))
         return value.map(stableValue);
@@ -1826,3 +2259,10 @@ export function isThreadNotReadyError(error) {
     const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
     return message.includes("no rollout found") || (message.includes("rollout") && message.includes("empty"));
 }
+/** A persisted thread id that a freshly started app-server cannot load yet.
+ * During startup, both errors can be transient while the rollout index catches
+ * up. Retry the same id; never use either error as permission to replace it. */
+export function isRetryableThreadResumeError(error) {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return message.includes("thread not found") || isThreadNotReadyError(error);
+}