@rynx-ai/runtime 0.1.11-beta.33 → 0.1.11-beta.35

package/dist/host.js

@@ -8,15 +8,17 @@ import { buildAgentSkillEnvironment, hashPluginPackageTree, scanSkillsDir, Sessi
 import { getRuntimeProfile, } from "@rynx-ai/core";
 import { resolveRuntimeBinary, } from "@rynx-ai/core";
 import { createCodexChildEnv } from "./codex-child-env.js";
-import { prepareRuntimeHome, populateCodexSkills, runtimeHomePath, } from "./codex-home.js";
+import { applyCodexProviderRetryPolicy, codexLaunchRequiresLogin, prepareRuntimeHome, populateCodexSkills, readCodexDeveloperInstructionsState, runtimeHomePath, syncCodexDeveloperInstructions, trustCodexProject, } 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";
+import { reapRuntimeProcessesForStateDir } from "./codex-app-server/process-registry.js";
 import { CodexSessionForwarder } from "./codex-app-server/forwarder.js";
 import { readMcpStartupPlan } from "./codex-app-server/mcp-startup.js";
+import { runtimeSessionStateDir } from "./runtime-state-paths.js";
 import { buildCodexRemoteArgs } from "./terminal/codex-tui.js";
 import { buildClaudeTuiArgs } from "./terminal/claude-tui.js";
 import { providerAdditionalDirs, threadWorkspaceParams, turnWorkspaceParams, } from "./provider-workspace.js";
@@ -273,45 +275,6 @@ async function dismissCodexPlanImplementationPrompt(injector, ownsPrompt) {
         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
- * its retry budget per-run in `buildOptions` (see the claude executor), so it
- * never needs a dedicated app-server.
- */
-export function codexRetryEnv(runtime, budget) {
-    if (runtime === "claude") {
-        return undefined;
-    }
-    const retry = budget?.retry;
-    if (!retry) {
-        return undefined;
-    }
-    const env = {};
-    if (retry.maxRetries != null) {
-        env.OPENAI_MAX_RETRIES = String(retry.maxRetries);
-    }
-    if (retry.timeoutPerRequestSeconds != null) {
-        env.OPENAI_TIMEOUT = String(Math.round(retry.timeoutPerRequestSeconds));
-    }
-    return Object.keys(env).length > 0 ? env : undefined;
-}
-/**
- * The cache key for a runtime backend. A retry budget on a codex-lineage
- * runtime forks a dedicated app-server (its own retry env) under a composite
- * `${runtime}::${hash}` key; everything else shares the base `${runtime}`
- * backend — so budget-less agents keep today's shared-process behaviour.
- */
-function hashRetryEnv(env) {
-    return Object.keys(env)
-        .sort()
-        .map((key) => `${key}=${env[key]}`)
-        .join("&");
-}
-export function codexBackendKey(runtime, budget) {
-    const env = codexRetryEnv(runtime, budget);
-    return env ? `${runtime}::${hashRetryEnv(env)}` : runtime;
-}
 export class LocalAgentHost {
     config;
     sessionStore;
@@ -322,8 +285,6 @@ export class LocalAgentHost {
     // auto-create. The command runner override backs the status probe.
     injectedCommandRunner;
     injectedAppServerClient;
-    clock;
-    backendIdleTtlMs;
     // Builds the SEPARATE forwarder connection for a live codex session (reference implementation's
     // multi-connection model). Defaults to an ExternalWsChannel client attached to
     // the backend's app-server; tests inject a fake.
@@ -335,8 +296,8 @@ export class LocalAgentHost {
     preloadClientFactory;
     /** Builds one short-lived message/interrupt client. */
     injectionClientFactory;
-    // Keyed by `codexBackendKey` — the bare runtime id for budget-less agents, or
-    // a `${runtime}::${retryHash}` composite for a per-agent retry budget.
+    // One backend per runtime. The host belongs to one Session runner, and Codex
+    // retry settings live in that Session's private config rather than process env.
     backends = new Map();
     // The rynx Session this host serves (set from `RYNX_RUNNER_SESSION`).
     sessionId;
@@ -361,6 +322,7 @@ export class LocalAgentHost {
     /** Claude forwarders stopped before their terminal is killed. Runner shutdown
      * finalizes these synchronously afterwards to scrub raw interaction answers. */
     pendingClaudeFinalizers = new Set();
+    pendingCleanupTasks = new Set();
     // In-flight `ensureLiveCodexSession` calls, so concurrent triggers (a web
     // `live.ensure` racing a `term.open`) share ONE forwarder — never two.
     liveEnsuring = new Map();
@@ -368,7 +330,7 @@ export class LocalAgentHost {
     /** 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, preloadClientFactory, injectionClientFactory, sessionId, runtimeHomeSessionId, }) {
+    constructor({ config, commandRunner, sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config)), allowedRoots = resolveAllowedRoots(config), appServerClient, forwarderClientFactory, preloadClientFactory, injectionClientFactory, sessionId, runtimeHomeSessionId, }) {
         this.config = config;
         this.sessionId = sessionId ?? "__default__";
         this.runtimeHomeSessionId = runtimeHomeSessionId ?? this.sessionId;
@@ -377,62 +339,22 @@ export class LocalAgentHost {
         this.defaultRuntime = config.DEFAULT_RUNTIME ?? "codex";
         this.injectedCommandRunner = commandRunner;
         this.injectedAppServerClient = appServerClient;
-        this.clock = now;
-        this.backendIdleTtlMs = backendIdleTtlMs;
         const defaultAttachedClientFactory = (appServerUrl) => new CodexAppServerClient({ channel: new ExternalWsChannel(appServerUrl) });
         this.forwarderClientFactory = forwarderClientFactory ?? defaultAttachedClientFactory;
         this.preloadClientFactory = preloadClientFactory ?? defaultAttachedClientFactory;
         this.injectionClientFactory = injectionClientFactory ?? defaultAttachedClientFactory;
     }
-    getBackend(runtime, budget) {
-        this.reapIdleBackends();
-        // In forced exec mode (the default runtime's injected app-server is null) a
-        // retry budget must NOT fork a composite backend: there is no app-server to
-        // carry the retry env, and forking one would spawn a real app-server and
-        // defeat the forced-exec override. Fall back to the base key — codex retry is
-        // then a no-op in exec mode (consistent with the broader codex-retry caveat).
-        const execMode = runtime === this.defaultRuntime && this.injectedAppServerClient === null;
-        const retryEnv = execMode ? undefined : codexRetryEnv(runtime, budget);
-        const key = retryEnv ? `${runtime}::${hashRetryEnv(retryEnv)}` : runtime;
-        const existing = this.backends.get(key);
-        if (existing) {
-            existing.lastUsedAt = this.clock();
+    getBackend(runtime) {
+        const existing = this.backends.get(runtime);
+        if (existing)
             return existing;
-        }
-        const backend = this.createBackend(runtime, retryEnv);
-        backend.lastUsedAt = this.clock();
-        this.backends.set(key, backend);
+        const backend = this.createBackend(runtime);
+        this.backends.set(runtime, backend);
         return backend;
     }
-    /**
-     * Stop + drop per-budget composite backends that have been idle longer than
-     * the TTL and have no in-flight run. Base per-runtime backends (key === the
-     * bare runtime id) are never reaped — they live for the process lifetime, as
-     * before. There are no per-conversation close hooks, so this lazy sweep (run
-     * on every `getBackend`) is how dedicated app-servers get reclaimed.
-     */
-    reapIdleBackends() {
-        const now = this.clock();
-        for (const [key, backend] of this.backends) {
-            if (!key.includes("::")) {
-                continue;
-            }
-            if ((backend.inFlight ?? 0) > 0 || backend.lastUsedAt === undefined) {
-                continue;
-            }
-            if (now - backend.lastUsedAt < this.backendIdleTtlMs) {
-                continue;
-            }
-            void backend.appServerClient?.stop();
-            this.backends.delete(key);
-        }
-    }
-    createBackend(runtime, retryEnv) {
+    createBackend(runtime) {
         const profile = getRuntimeProfile(runtime);
-        // A composite (per-budget) backend is inherently non-default: it gets a
-        // fresh app-server with the retry env, never the test-injected default deps.
-        const isComposite = retryEnv !== undefined;
-        const isDefault = runtime === this.defaultRuntime && !isComposite;
+        const isDefault = runtime === this.defaultRuntime;
         const commandRunner = (isDefault && this.injectedCommandRunner) ||
             new SpawnCodexCommandRunner(resolveRuntimeBinary(runtime));
         // The claude runtime is not codex-lineage: it has no app-server (its live
@@ -447,7 +369,7 @@ export class LocalAgentHost {
             ? this.injectedAppServerClient === null
                 ? null
                 : this.injectedAppServerClient ?? this.createAppServerClient(runtime)
-            : this.createAppServerClient(runtime, retryEnv);
+            : this.createAppServerClient(runtime);
         return { runtime, profile, appServerClient, commandRunner };
     }
     /** This session's private native home, shared by its app-server + TUI. */
@@ -461,7 +383,7 @@ export class LocalAgentHost {
         this.runtimeHomes.set(runtime, prepared);
         return prepared;
     }
-    createAppServerClient(runtime, extraEnv) {
+    createAppServerClient(runtime) {
         const cliPath = resolveRuntimeBinary(runtime);
         // Per-agent knobs (resolved at live-session start) win over the daemon
         // default — the app-server is private to this session's agent.
@@ -477,8 +399,8 @@ export class LocalAgentHost {
         const channel = new WsRpcChannel({
             cliPath,
             baseArgs: buildAppServerBaseArgs(sandbox),
+            stateDir: runtimeSessionStateDir(this.runtimeHomeSessionId),
             extraEnv: {
-                ...(extraEnv ?? {}),
                 [profile.homeEnvVar]: this.runtimeHome(runtime),
             },
         });
@@ -540,7 +462,7 @@ export class LocalAgentHost {
             const modelChanged = desiredModel !== live.appliedModel;
             const effortChanged = desiredReasoningEffort !== live.appliedReasoningEffort;
             const collaborationMode = mode && live.appliedCollaborationMode !== mode
-                ? await resolveLiveCollaborationMode(client, live, mode)
+                ? await resolveLiveCollaborationMode(client, live, mode, live.runtime === "codex" ? this.runtimeHome(live.runtime) : undefined)
                 : undefined;
             const settings = {
                 threadId,
@@ -596,7 +518,7 @@ export class LocalAgentHost {
             throw new CodexRuntimeError("session snapshots are not live", 409, "session_not_live");
         }
         const runtime = live.runtime;
-        const backend = this.getBackend(runtime, live.execution.budget ?? undefined);
+        const backend = this.getBackend(runtime);
         const client = backend.appServerClient;
         if (!client) {
             throw new CodexRuntimeError(`no app-server for runtime ${runtime}`, 500, "app_server_unavailable");
@@ -616,6 +538,10 @@ export class LocalAgentHost {
         const traexYolo = runtime === "traex" &&
             sandbox === "danger-full-access" &&
             approvalPolicy === "never";
+        // Runner-owned Codex terminals start detached, so nobody can answer the
+        // interactive hook-review prompt. The private CODEX_HOME is provisioned
+        // before launch; use Codex's native bypass flag for this managed TUI.
+        const bypassHookTrust = runtime === "codex" || traexYolo;
         const configOverrides = sandbox === "workspace-write"
             ? ["sandbox_workspace_write.network_access=true"]
             : [];
@@ -633,21 +559,26 @@ export class LocalAgentHost {
         const launchEffort = live.reasoningEffort;
         if (launchEffort)
             configOverrides.push(`model_reasoning_effort=${JSON.stringify(launchEffort)}`);
-        if (live?.instructions) {
+        if (runtime === "traex" && live?.instructions) {
             configOverrides.push(`developer_instructions=${JSON.stringify(live.instructions)}`);
         }
         const profile = getRuntimeProfile(runtime);
         const activeThreadId = live?.threadId ?? record?.codexSessionId;
         return {
+            lifecycle: "auxiliary",
             command: resolveRuntimeBinary(runtime),
             args: buildCodexRemoteArgs({
                 remoteUrl,
                 ...(activeThreadId ? { threadId: activeThreadId } : {}),
                 configOverrides,
-                codexArgs: traexYolo ? ["--dangerously-bypass-hook-trust"] : [],
+                codexArgs: bypassHookTrust ? ["--dangerously-bypass-hook-trust"] : [],
                 additionalDirs: providerAdditionalDirs(live.workspace),
             }),
             cwd: live.workspace.cwd,
+            scrollback: 100_000,
+            tmuxAllowPassthrough: true,
+            tmuxStartOnAttach: false,
+            keepAliveAfterExit: false,
             ...(runtime === "traex" ? { skipTraexStartupPrompts: true } : {}),
             // 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
@@ -739,11 +670,25 @@ export class LocalAgentHost {
                 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.
+        // Persist headless project trust before the app-server boots. Fork targets
+        // reuse the owner's immutable Provider home.
         const liveSkills = snapshotSkills.selectedSkills.map((s) => ({ name: s.name, dir: s.dir }));
+        const runtimeHome = this.runtimeHome(runtime);
+        if (runtime === "codex") {
+            try {
+                trustCodexProject(runtimeHome, workspace.cwd);
+                syncCodexDeveloperInstructions(runtimeHome, nativeAuthoredInstructions(execution));
+                applyCodexProviderRetryPolicy(runtimeHome, execution.budget?.retry);
+            }
+            catch (err) {
+                void snapshotSkills.skillsCleanup();
+                this.liveStartupErrors.set(localThreadId, nativeLiveFailure(runtime, "native_project_trust_failed", "project trust preparation failed", err));
+                console.error(`[session-snapshot] session=${localThreadId} project trust preparation failed: ${err instanceof Error ? err.message : String(err)}`);
+                return false;
+            }
+        }
         try {
-            populateCodexSkills(this.runtimeHome(runtime), liveSkills);
+            populateCodexSkills(runtimeHome, liveSkills);
         }
         catch (err) {
             void snapshotSkills.skillsCleanup();
@@ -765,12 +710,20 @@ export class LocalAgentHost {
             void snapshotSkills.skillsCleanup();
             return false;
         };
-        const appServerOwner = this.getBackend(runtime, execution.budget ?? undefined).appServerClient;
+        reapRuntimeProcessesForStateDir(runtimeSessionStateDir(this.runtimeHomeSessionId));
+        const backend = this.getBackend(runtime);
+        const appServerOwner = backend.appServerClient;
         if (!appServerOwner) {
             this.liveStartupErrors.set(localThreadId, nativeLiveFailure(runtime, "native_app_server_unavailable", "app-server is unavailable for this Session"));
             console.error(`[codex-live] session=${localThreadId} runtime=${runtime} no app-server client`);
             return abandon();
         }
+        let loginRequired;
+        if (!coldResume &&
+            runtime === "codex" &&
+            codexLaunchRequiresLogin(runtimeHome, createCodexChildEnv({ ...process.env, CODEX_HOME: runtimeHome }))) {
+            loginRequired = new CodexRuntimeError("Codex is not signed in and no configured Provider can run this Session, so the Terminal is waiting at the sign-in screen. Sign in from the Session Terminal, then send the message again.", 401, "login_required");
+        }
         try {
             await appServerOwner.ensureInitialized();
         }
@@ -863,12 +816,15 @@ export class LocalAgentHost {
             appliedModel: coldResume ? "" : model,
             appliedReasoningEffort: coldResume ? undefined : reasoningEffort,
             appliedCollaborationMode: undefined,
-            ...(execution.instructions ? { instructions: execution.instructions } : {}),
+            ...(runtime === "traex" && execution.instructions
+                ? { instructions: execution.instructions }
+                : {}),
             threadId: record?.codexSessionId ?? null,
             ready,
             markReady,
             startupFailed,
             markStartupFailed,
+            ...(loginRequired ? { startupError: loginRequired } : {}),
             terminalReady,
             markTerminalReady,
             injectLock: Promise.resolve(),
@@ -1080,7 +1036,7 @@ export class LocalAgentHost {
                         const client = this.injectionClientFactory(live.appServerUrl);
                         try {
                             await client.ensureInitialized();
-                            const collaborationMode = await resolveLiveCollaborationMode(client, live, "default");
+                            const collaborationMode = await resolveLiveCollaborationMode(client, live, "default", live.runtime === "codex" ? this.runtimeHome(live.runtime) : undefined);
                             let threadId = prompt.threadId;
                             let text = CODEX_PLAN_IMPLEMENTATION_CODING_MESSAGE;
                             if (choice === CODEX_PLAN_IMPLEMENTATION_CLEAR_CONTEXT) {
@@ -1418,6 +1374,7 @@ export class LocalAgentHost {
                     kind,
                 });
                 this.liveSessions.set(newSessionId, live);
+                this.liveSessions.delete(previousSessionId);
                 retargetMirror?.(newSessionId, {
                     kind,
                     workspace: structuredClone(live.workspace),
@@ -1447,6 +1404,8 @@ export class LocalAgentHost {
         };
         bindObserverClient(forwarderClient);
         this.liveSessions.set(localThreadId, live);
+        if (loginRequired)
+            this.liveStartupErrors.set(localThreadId, loginRequired);
         forwarder.start();
         // Existing bindings resume through the public app-server API. A fresh thread
         // is created by the native remote TUI instead: its `thread/started`
@@ -1526,12 +1485,19 @@ export class LocalAgentHost {
             console.error(`[codex-live] session=${localThreadId} runtime=${runtime} thread bind failed: ${err instanceof Error ? err.message : String(err)}`);
             return abandon();
         }
-        this.liveStartupErrors.delete(localThreadId);
+        if (!loginRequired)
+            this.liveStartupErrors.delete(localThreadId);
         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, threadId, forkedFromId) {
+        if (live.startupError?.code === "login_required") {
+            delete live.startupError;
+            if (this.liveStartupErrors.get(localThreadId)?.code === "login_required") {
+                this.liveStartupErrors.delete(localThreadId);
+            }
+        }
         const previousThreadId = live.threadId;
         if (previousThreadId !== threadId) {
             live.threadActive = false;
@@ -1843,7 +1809,8 @@ export class LocalAgentHost {
                     claude.pendingImageInputs.delete(token);
             }
             else {
-                pendingInput.responseId = result.responseId;
+                if (result.responseId)
+                    pendingInput.responseId = result.responseId;
                 if (pendingInput.observed)
                     forgetPendingInput();
                 else
@@ -1854,6 +1821,8 @@ export class LocalAgentHost {
         const live = this.liveSessions.get(localThreadId);
         if (!live)
             return { outcome: "notLive" };
+        if (live.startupError?.code === "login_required")
+            return { outcome: "notReady" };
         const run = live.injectLock.then(async () => {
             if (live.rotationPending || live.stopped)
                 return { outcome: "failed" };
@@ -1923,7 +1892,7 @@ export class LocalAgentHost {
                 const desiredCollaborationMode = options?.collaborationMode ?? live.execution.collaborationMode;
                 const collaborationMode = desiredCollaborationMode &&
                     desiredCollaborationMode !== live.appliedCollaborationMode
-                    ? await resolveLiveCollaborationMode(injectionClient, live, desiredCollaborationMode)
+                    ? await resolveLiveCollaborationMode(injectionClient, live, desiredCollaborationMode, live.runtime === "codex" ? this.runtimeHome(live.runtime) : undefined)
                     : undefined;
                 const settings = {
                     threadId,
@@ -1978,7 +1947,8 @@ export class LocalAgentHost {
             catch (error) {
                 forgetPendingInput();
                 if (error instanceof CodexRuntimeError &&
-                    error.code === "collaboration_mode_model_unknown") {
+                    (error.code === "collaboration_mode_model_unknown" ||
+                        error.code === "collaboration_mode_instructions_unknown")) {
                     throw error;
                 }
                 // Preserve the app-server's error instead of collapsing every failure
@@ -2088,6 +2058,7 @@ export class LocalAgentHost {
             this.liveClaudeSessions.delete(localThreadId);
             claude.stopped = true;
             claude.forwarder.stop();
+            this.trackCleanup(claude.forwarder.waitForStop());
             if (opts.deferClaudeInteractionCleanup) {
                 this.pendingClaudeFinalizers.add(claude.forwarder);
             }
@@ -2118,9 +2089,10 @@ export class LocalAgentHost {
         live.canonicalInteractions.clear();
         live.settledInteractions.clear();
         live.syntheticInteractions.clear();
-        void live.forwarderClient.stop().catch(() => undefined);
+        this.trackCleanup(live.forwarderClient.stop().catch(() => undefined));
         // Remove the session-scoped skills dir — the machine keeps zero task residue.
-        void live.skillsCleanup?.();
+        if (live.skillsCleanup)
+            this.trackCleanup(live.skillsCleanup());
     }
     /** Tear down one codex-lineage native runtime without deleting its durable
      * session-store binding. reference implementation couples its auxiliary Terminal, observer,
@@ -2131,21 +2103,26 @@ export class LocalAgentHost {
         if (!live)
             return false;
         const turnFailed = error ? live.forwarder.failOpenTurn(error) : false;
-        const backendKey = codexBackendKey(live.runtime, live.execution.budget ?? undefined);
+        const backendKey = live.runtime;
         const backend = this.backends.get(backendKey);
         const appServerOwner = live.appServerOwner;
         this.stopLiveCodexSession(localThreadId);
         if (backend?.appServerClient === appServerOwner) {
             this.backends.delete(backendKey);
         }
-        void appServerOwner.stop().catch((stopError) => {
+        this.trackCleanup(appServerOwner.stop().catch((stopError) => {
             console.warn(`[codex-live] session=${localThreadId} runtime=${live.runtime} app-server teardown failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
-        });
+        }));
         return turnFailed;
     }
+    async teardownAuxiliaryTerminalRuntime(localThreadId) {
+        const owner = this.liveSessions.get(localThreadId)?.appServerOwner;
+        this.teardownLiveCodexSession(localThreadId);
+        await owner?.stop().catch(() => undefined);
+    }
     /** Complete the second shutdown phase after the runner has killed all native
      * terminals and hook subprocesses. Must run before the runner process exits. */
-    finalizeStoppedLiveSessions() {
+    async finalizeStoppedLiveSessions() {
         for (const forwarder of this.pendingClaudeFinalizers)
             forwarder.finalizeStop();
         this.pendingClaudeFinalizers.clear();
@@ -2154,10 +2131,20 @@ export class LocalAgentHost {
         // 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);
-        }
+        const backendStops = [...this.backends.values()].map((backend) => backend.appServerClient?.stop().catch(() => undefined));
         this.backends.clear();
+        await Promise.all([
+            ...backendStops,
+            ...this.pendingCleanupTasks,
+        ]);
+        this.pendingCleanupTasks.clear();
+    }
+    trackCleanup(task) {
+        const guarded = task.catch((error) => {
+            console.warn(`[native-runtime] cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        this.pendingCleanupTasks.add(guarded);
+        void guarded.then(() => this.pendingCleanupTasks.delete(guarded));
     }
     // --- claude-native live session (parallel to the codex methods above) -----
     /** The interactive `claude` TUI spec for a claude-native live session: the real
@@ -2200,8 +2187,8 @@ export class LocalAgentHost {
             ...(live.execution.reasoningEffort
                 ? { reasoningEffort: live.execution.reasoningEffort }
                 : {}),
-            ...(live.execution.instructions
-                ? { appendSystemPrompt: live.execution.instructions }
+            ...(nativeAuthoredInstructions(live.execution)
+                ? { appendSystemPrompt: nativeAuthoredInstructions(live.execution) }
                 : {}),
             additionalDirs: providerAdditionalDirs(live.workspace),
             ...(live.forkIntent
@@ -2216,9 +2203,14 @@ export class LocalAgentHost {
             ...(live.launchExtraArgs.length ? { extraArgs: live.launchExtraArgs } : {}),
         });
         return {
+            lifecycle: "required",
             command: resolveRuntimeBinary("claude"),
             args,
             cwd,
+            scrollback: 50_000,
+            tmuxAllowPassthrough: false,
+            tmuxStartOnAttach: false,
+            keepAliveAfterExit: true,
             // Same env the pane would inherit by default, plus the session scope for
             // agent-run CLIs (rynx-emulator resolves device-less commands via it).
             env: { ...process.env, RYNX_SESSION_ID: localThreadId },
@@ -2598,6 +2590,7 @@ export class LocalAgentHost {
                 live.contextWarned = false;
                 pendingRotationEvents = [];
                 this.liveClaudeSessions.set(newSessionId, live);
+                this.liveClaudeSessions.delete(previousSessionId);
                 void this.sessionStore
                     .set({
                     localThreadId: newSessionId,
@@ -2703,11 +2696,10 @@ export class LocalAgentHost {
                 if (!ok)
                     return { outcome: "failed" };
                 const responseId = pendingInput.responseId ?? live.currentResponseId();
-                if (!responseId) {
-                    live.error = "Claude accepted the message but did not publish its native Turn identity";
-                    return { outcome: "failed" };
-                }
-                return { outcome: steered ? "steered" : "injected", responseId };
+                return {
+                    outcome: steered ? "steered" : "injected",
+                    ...(responseId ? { responseId } : {}),
+                };
             }
             catch (error) {
                 live.error = error instanceof Error ? error.message : String(error);
@@ -2860,7 +2852,7 @@ export class LocalAgentHost {
             }
             const runtime = execution.provider;
             const client = live?.appServerOwner ??
-                this.getBackend(runtime, execution.budget ?? undefined).appServerClient;
+                this.getBackend(runtime).appServerClient;
             if (!client) {
                 return { ok: false, reason: "unsupported" };
             }
@@ -2995,7 +2987,7 @@ function adoptResumedThreadSettings(live, settings) {
 /** Resolve the model required by a full collaboration-mode snapshot. Only a
  * fresh thread with no explicit/config model may use the catalog default; a
  * resumed thread must report its own authoritative model. */
-async function resolveLiveCollaborationMode(client, live, mode) {
+async function resolveLiveCollaborationMode(client, live, mode, codexHome) {
     let model = live.model.trim();
     if (!model && live.mayUseProviderDefaultModel) {
         let catalog;
@@ -3014,11 +3006,21 @@ async function resolveLiveCollaborationMode(client, live, mode) {
         }
         model = defaults[0];
     }
-    return buildCollaborationMode(mode, model, live.reasoningEffort);
+    let developerInstructions = null;
+    if (live.runtime === "codex") {
+        const state = codexHome
+            ? readCodexDeveloperInstructionsState(codexHome)
+            : { state: "unreadable" };
+        if (state.state === "unreadable") {
+            throw new CodexRuntimeError("collaboration mode requires the current developer instructions, but the private Codex config could not be read", 503, "collaboration_mode_instructions_unknown");
+        }
+        developerInstructions = state.state === "present" ? state.value : null;
+    }
+    return buildCollaborationMode(mode, model, live.reasoningEffort, developerInstructions);
 }
 /** Expand the public mode enum into the App Server's required settings
  * snapshot using the Session's tracked effective model. */
-function buildCollaborationMode(mode, desiredModel, desiredReasoningEffort) {
+function buildCollaborationMode(mode, desiredModel, desiredReasoningEffort, developerInstructions) {
     const model = desiredModel.trim();
     if (!model) {
         throw new CodexRuntimeError("collaboration mode requires the current model, but the Provider did not report one", 503, "collaboration_mode_model_unknown");
@@ -3028,12 +3030,19 @@ function buildCollaborationMode(mode, desiredModel, desiredReasoningEffort) {
         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,
+            developer_instructions: developerInstructions,
         },
     };
 }
+/** New snapshots distinguish authored Agent text from framework-rendered
+ * instructions. Older persisted snapshots fall back to their only available
+ * field so existing sessions preserve their launch behavior. */
+function nativeAuthoredInstructions(execution) {
+    const value = execution.authoredInstructions === undefined
+        ? execution.instructions
+        : execution.authoredInstructions;
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
 function sameSessionSnapshots(workspace, execution, opts) {
     return JSON.stringify(stableValue({
         workspace,
@@ -3090,6 +3099,12 @@ function applyClaudePermissionModeSnapshot(settings, permissionMode) {
         permissions.defaultMode = permissionMode;
     else
         delete permissions.defaultMode;
+    if (permissionMode === "bypassPermissions") {
+        next.skipDangerousModePermissionPrompt = true;
+    }
+    else {
+        delete next.skipDangerousModePermissionPrompt;
+    }
     if (Object.keys(permissions).length > 0)
         next.permissions = permissions;
     else

package/dist/index.d.ts

@@ -13,6 +13,6 @@ export type { InjectOutcome, InjectResult, TerminalOpenErrorCode, TerminalRole }
 export type { ResolveInteractionResult, RuntimeInteractionEvent, RuntimeInteractionListener, } from "./interactions.js";
 export { probeRuntimeStatus } from "./runtime-status.js";
 export { listRuntimeModels } from "./models-catalog.js";
-export { TmuxTerminal, isTmuxAvailable, terminateTmuxServer, tmuxSocketPath, } from "./terminal/tmux.js";
-export type { TerminalAttachment, TmuxTerminalOptions } from "./terminal/tmux.js";
+export { TmuxTerminal, isTmuxAvailable, resolveTmuxBin, terminateTmuxServer, tmuxSocketPath, } from "./terminal/tmux.js";
+export type { PreparedTerminalAttachment, PullTerminalAttachment, TmuxTerminalOptions, } from "./terminal/tmux.js";
 export { TerminalRegistry } from "./terminal/registry.js";

package/dist/index.js

@@ -12,5 +12,5 @@ export { RunnerManager, TerminalOpenError } from "./runner/manager.js";
 export { probeRuntimeStatus } from "./runtime-status.js";
 export { listRuntimeModels } from "./models-catalog.js";
 // Live-terminal subsystem (Phase C): tmux-backed terminals + per-runner registry.
-export { TmuxTerminal, isTmuxAvailable, terminateTmuxServer, tmuxSocketPath, } from "./terminal/tmux.js";
+export { TmuxTerminal, isTmuxAvailable, resolveTmuxBin, terminateTmuxServer, tmuxSocketPath, } from "./terminal/tmux.js";
 export { TerminalRegistry } from "./terminal/registry.js";