@rynx-ai/runtime 0.1.0 → 0.1.9

package/dist/host.js

@@ -18,9 +18,10 @@ import { buildCodexRemoteArgs } from "./terminal/codex-tui.js";
 import { buildClaudeTuiArgs } from "./terminal/claude-tui.js";
 import { ensureProjectTrusted } from "./claude/trust.js";
 import { claudeTranscriptPath } from "./claude/transcript.js";
-import { claudeBridgeDir, prepareClaudeBridgeDir } from "./claude/native-bridge.js";
+import { claudeBridgeDir, prepareClaudeBridgeDir, removeManagedClaudeSettings, writeManagedClaudeSettings, } from "./claude/native-bridge.js";
 import { ClaudeLiveSession, injectViaTerminal, } from "./claude/native-integration.js";
 import { buildClaudeHookSettings } from "./claude/native-hooks.js";
+import { buildManagedClaudeSettings } from "./claude/settings.js";
 import { FileCodexSessionStore, resolveCodexSessionStorePath, } from "./codex-session-store.js";
 import { AgentRuntimeError as CodexRuntimeError } from "@rynx-ai/core";
 import { newSessionId as makeSessionId } from "@rynx-ai/core";
@@ -161,11 +162,12 @@ export class SpawnCodexCommandRunner {
     }
 }
 /** Fraction of an agent's `contextWindow` budget at which the orchestrator
- *  emits a one-time `context.threshold` observability signal. Mirrors omnigent's
+ *  emits a one-time `context.threshold` observability signal. Mirrors reference implementation's
  *  compaction `trigger_threshold` (0.8). codex self-compacts via its token
  *  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;
+const MAX_CODEX_SETTLED_INTERACTIONS = 512;
 /**
  * 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
@@ -217,7 +219,7 @@ export class LocalAgentHost {
     injectedAppServerClient;
     clock;
     backendIdleTtlMs;
-    // Builds the SEPARATE forwarder connection for a live codex session (omnigent's
+    // 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.
     forwarderClientFactory;
@@ -241,6 +243,9 @@ export class LocalAgentHost {
     // Per-session claude-native live forwarders (parallel to liveSessions; claude
     // has no app-server, so it tails the bridge + transcript instead of RPC).
     liveClaudeSessions = new Map();
+    /** Claude forwarders stopped before their terminal is killed. Runner shutdown
+     * finalizes these synchronously afterwards to scrub raw interaction answers. */
+    pendingClaudeFinalizers = 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();
@@ -337,7 +342,7 @@ export class LocalAgentHost {
         const policy = approvalPolicy === "never" ? "auto-approve-session" : "auto-decline";
         // Native co-drive: run the app-server on a loopback ws (multi-client) so a
         // `codex --remote` TUI can attach to the same thread (stdio admits only one
-        // client). This is the sole transport — always native, aligning with omnigent.
+        // client). This is the sole transport — always native, aligning with reference implementation.
         // Point it at the private CODEX_HOME so it shares the TUI's login/settings and
         // never trips the real home's update/NUX state.
         const channel = new WsRpcChannel({
@@ -348,23 +353,50 @@ export class LocalAgentHost {
         return new CodexAppServerClient({
             channel,
             approvalDecisionPolicy: policy,
-            interactiveApprovals: this.config.AGENT_INTERACTIVE_APPROVALS,
         });
     }
-    /**
-     * Deliver a user's decision for a pending interactive approval (Phase D).
-     * Routes to the codex app-server client for the thread's runtime. Returns
-     * false when no matching pending approval exists (unknown id / already
-     * resolved / claude runtime).
-     */
-    async resolveApproval(localThreadId, approvalId, decision) {
-        const record = await this.sessionStore.get(localThreadId);
-        const runtime = record?.runtime ?? this.defaultRuntime;
-        if (runtime === "claude") {
-            return false;
+    /** Resolve a pending native question/approval without opening a new Turn. */
+    async resolveInteraction(localThreadId, interactionId, resolution) {
+        const claude = this.liveClaudeSessions.get(localThreadId);
+        if (claude) {
+            return claude.forwarder.resolveInteraction(interactionId, resolution);
         }
-        const client = this.getBackend(runtime).appServerClient;
-        return client ? client.resolveApproval(approvalId, decision) : false;
+        const live = this.liveSessions.get(localThreadId);
+        if (!live)
+            return { disposition: "not_found" };
+        if (live.settledInteractions.has(interactionId)) {
+            return { disposition: "already_resolved" };
+        }
+        if (live.interactionRecoveries.has(interactionId)) {
+            return {
+                disposition: "invalid",
+                message: "interaction delivery is recovering; retry shortly",
+            };
+        }
+        const submit = (client) => {
+            // Store before entering the client: a transport can report a synchronous
+            // write failure, and failover must already have the exact accepted answer
+            // available for replay. A synchronous terminal event may delete it again.
+            const hadPrevious = live.interactionSubmissions.has(interactionId);
+            const previous = live.interactionSubmissions.get(interactionId);
+            live.interactionSubmissions.set(interactionId, resolution);
+            const result = client.resolveInteraction(interactionId, resolution);
+            if (result.disposition !== "applied") {
+                if (hadPrevious && previous)
+                    live.interactionSubmissions.set(interactionId, previous);
+                else
+                    live.interactionSubmissions.delete(interactionId);
+            }
+            return result;
+        };
+        const owner = live.interactionOwners.get(interactionId);
+        if (owner)
+            return submit(owner);
+        const injected = submit(live.injectClient);
+        if (injected.disposition !== "not_found") {
+            return injected;
+        }
+        return submit(live.forwarderClient);
     }
     /**
      * The command to run in a session's live terminal so it co-drives the codex
@@ -382,7 +414,8 @@ export class LocalAgentHost {
         if (this.liveClaudeSessions.has(localThreadId)) {
             return this.claudeTerminalSpec(localThreadId, record);
         }
-        const runtime = record?.runtime ?? this.defaultRuntime;
+        const live = this.liveSessions.get(localThreadId);
+        const runtime = record?.runtime ?? live?.runtime ?? this.defaultRuntime;
         if (runtime === "claude") {
             return this.claudeTerminalSpec(localThreadId, record);
         }
@@ -392,7 +425,7 @@ export class LocalAgentHost {
             throw new CodexRuntimeError(`no app-server for runtime ${runtime}`, 500, "app_server_unavailable");
         }
         // Native-only: an app-server failure surfaces as a terminal error, never a
-        // silent bash fallback (aligns with omnigent). ensureInitialized throws on its own.
+        // silent bash fallback (aligns with reference implementation). ensureInitialized throws on its own.
         await client.ensureInitialized();
         const remoteUrl = client.terminalRemoteUrl();
         if (!remoteUrl) {
@@ -406,9 +439,15 @@ export class LocalAgentHost {
             : [];
         // 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 = this.liveSessions.get(localThreadId)?.model;
+        const launchModel = live?.model;
         if (launchModel)
             configOverrides.push(`model=${JSON.stringify(launchModel)}`);
+        const launchEffort = live?.reasoningEffort ?? record?.reasoningEffort;
+        if (launchEffort)
+            configOverrides.push(`model_reasoning_effort=${JSON.stringify(launchEffort)}`);
+        if (live?.instructions) {
+            configOverrides.push(`developer_instructions=${JSON.stringify(live.instructions)}`);
+        }
         return {
             command: resolveRuntimeBinary(runtime),
             args: buildCodexRemoteArgs({
@@ -416,7 +455,7 @@ export class LocalAgentHost {
                 ...(record?.codexSessionId ? { threadId: record.codexSessionId } : {}),
                 configOverrides,
             }),
-            cwd: record?.cwd ?? process.cwd(),
+            cwd: record?.cwd ?? live?.cwd ?? process.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.
@@ -429,7 +468,7 @@ export class LocalAgentHost {
     }
     /**
      * Bring up (idempotently) a session's persistent codex forwarder and emit its
-     * mirrored {@link SessionEvent}s. omnigent's codex-native single-writer model:
+     * mirrored {@link SessionEvent}s. reference implementation's codex-native single-writer model:
      * this forwarder is the SOLE producer of the session's canonical events — every
      * turn on the thread, web-composer-injected AND co-driving-`codex --remote`-TUI
      * initiated. Each turn gets a {@link SessionNormalizer} whose `responseId` is
@@ -444,7 +483,10 @@ export class LocalAgentHost {
      * to display it. The thread id is persisted so `codexTerminalSpec` resumes it.
      */
     async ensureLiveCodexSession(localThreadId, emit, opts) {
-        if (this.liveSessions.has(localThreadId) || this.liveClaudeSessions.has(localThreadId))
+        const live = this.liveSessions.get(localThreadId);
+        if (live)
+            return this.refreshLiveCodexSession(localThreadId, live, opts);
+        if (this.liveClaudeSessions.has(localThreadId))
             return true;
         // Dedupe concurrent triggers so only one forwarder is ever created per
         // session (two would double-mirror every turn).
@@ -461,7 +503,7 @@ export class LocalAgentHost {
         }
     }
     async startLiveCodexSession(localThreadId, emit, opts) {
-        // cancel-before-recreate (omnigent Layer 2, runner/app.py `_cancel_auto_forwarder_task`):
+        // cancel-before-recreate (reference implementation Layer 2, runner/app.py `_cancel_auto_forwarder_task`):
         // never run a new forwarder alongside a stale one for this id. ensureLive's has()
         // fast-path normally makes this a no-op; it closes the stop→re-ensure race that
         // could otherwise leave a half-dead forwarder mirroring in parallel.
@@ -475,7 +517,8 @@ export class LocalAgentHost {
         const runtime = record?.runtime ?? opts?.runtime ?? this.defaultRuntime;
         if (runtime === "claude")
             return this.startLiveClaudeSession(localThreadId, emit, record, opts);
-        const cwd = record?.cwd ?? process.cwd();
+        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`.
@@ -489,7 +532,7 @@ export class LocalAgentHost {
         }
         // 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 — omnigent's filesystem mechanism. The live thread is created by
+        // 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
@@ -510,25 +553,31 @@ export class LocalAgentHost {
             return false;
         };
         const injectClient = this.getBackend(runtime).appServerClient;
-        if (!injectClient)
+        if (!injectClient) {
+            console.error(`[codex-live] session=${localThreadId} runtime=${runtime} no app-server client`);
             return abandon();
+        }
         try {
             await injectClient.ensureInitialized();
         }
-        catch {
+        catch (err) {
+            console.error(`[codex-live] session=${localThreadId} runtime=${runtime} app-server init failed: ${err instanceof Error ? err.message : String(err)}`);
             return abandon();
         }
         const appServerUrl = injectClient.terminalRemoteUrl();
-        if (!appServerUrl)
+        if (!appServerUrl) {
+            console.error(`[codex-live] session=${localThreadId} runtime=${runtime} app-server has no remote url`);
             return abandon(); // needs the ws app-server (live-terminal mode)
-        // omnigent multi-connection: a SEPARATE forwarder connection to the SAME
+        }
+        // reference implementation multi-connection: a SEPARATE forwarder connection to the SAME
         // app-server, which `thread/resume`s to subscribe to the thread's item/turn
         // notifications (the backend client injects; this one only observes).
         const forwarderClient = this.forwarderClientFactory(appServerUrl);
         try {
             await forwarderClient.ensureInitialized();
         }
-        catch {
+        catch (err) {
+            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/`).
@@ -536,6 +585,10 @@ export class LocalAgentHost {
         // 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 = getCodexModel(this.config, record?.model ?? liveCfg.model);
+        const hasCurrentEffortSource = Boolean(opts?.agentName || opts?.agentSpec || opts?.reasoningEffort);
+        const reasoningEffort = hasCurrentEffortSource
+            ? liveCfg.reasoningEffort
+            : record?.reasoningEffort ?? liveCfg.reasoningEffort;
         let markReady;
         const ready = new Promise((resolve) => {
             markReady = resolve;
@@ -547,6 +600,8 @@ export class LocalAgentHost {
             runtime,
             cwd,
             model,
+            reasoningEffort,
+            ...(liveCfg.instructions ? { instructions: liveCfg.instructions } : {}),
             threadId: record?.codexSessionId ?? null,
             ready,
             markReady,
@@ -554,19 +609,228 @@ export class LocalAgentHost {
             subscribing: false,
             stopped: false,
             skillsCleanup: liveCfg.skillsCleanup,
+            configSignature,
+            interactionOwners: new Map(),
+            interactionStandbys: new Map(),
+            interactionSubmissions: new Map(),
+            canonicalInteractions: new Set(),
+            settledInteractions: new Set(),
+            interactionRecoveries: new Map(),
+            interactionFailedClients: new Map(),
+            disconnectedClients: new Set(),
         };
         let normalizer = null;
+        let currentResponseId = null;
         const startNormalizer = (turnId) => {
+            const responseId = turnId ? `resp_codex_${turnId}` : "resp_codex_native";
+            if (normalizer && currentResponseId === responseId)
+                return normalizer;
+            currentResponseId = responseId;
             normalizer = new SessionNormalizer({
                 sessionId: localThreadId,
                 // 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 omnigent `_response_id`.
-                responseId: turnId ? `resp_codex_${turnId}` : "resp_codex_native",
+                // ids (the DB `resp_codex_<uuid>` doubling). Mirrors reference implementation `_response_id`.
+                responseId,
                 model,
             });
             return normalizer;
         };
+        const rememberSettledInteraction = (interactionId) => {
+            live.settledInteractions.add(interactionId);
+            if (live.settledInteractions.size <= MAX_CODEX_SETTLED_INTERACTIONS)
+                return;
+            const oldest = live.settledInteractions.values().next().value;
+            if (oldest)
+                live.settledInteractions.delete(oldest);
+        };
+        const forwardInteraction = (event) => {
+            const interactionId = event.type === "requested"
+                ? event.request.interactionId
+                : event.interactionId;
+            if (event.type === "requested") {
+                if (live.canonicalInteractions.has(interactionId) ||
+                    live.settledInteractions.has(interactionId))
+                    return;
+                live.canonicalInteractions.add(interactionId);
+            }
+            else {
+                // The forwarder may have completed the Turn before another app-server
+                // connection publishes its terminal copy. Never create a fresh
+                // normalizer/response for that late duplicate.
+                if (!live.canonicalInteractions.delete(interactionId))
+                    return;
+                rememberSettledInteraction(interactionId);
+            }
+            const turnId = event.turnId ?? live.forwarder?.currentTurnId() ?? undefined;
+            const n = normalizer ?? startNormalizer(turnId);
+            const agentEvent = event.type === "requested"
+                ? { type: "interaction_requested", interaction: event.request }
+                : event.type === "resolved"
+                    ? {
+                        type: "interaction_resolved",
+                        interactionId: event.interactionId,
+                        resolution: event.resolution,
+                    }
+                    : {
+                        type: "interaction_cancelled",
+                        interactionId: event.interactionId,
+                        ...(event.reason ? { reason: event.reason } : {}),
+                    };
+            for (const se of n.next(agentEvent))
+                emit(se);
+        };
+        const clearRecovery = (interactionId) => {
+            live.interactionRecoveries.delete(interactionId);
+        };
+        const clearInteractionRouting = (interactionId) => {
+            clearRecovery(interactionId);
+            live.interactionOwners.delete(interactionId);
+            live.interactionStandbys.delete(interactionId);
+            live.interactionSubmissions.delete(interactionId);
+            live.interactionFailedClients.delete(interactionId);
+        };
+        const markInteractionClientFailed = (interactionId, client) => {
+            const failed = live.interactionFailedClients.get(interactionId) ?? new Set();
+            failed.add(client);
+            live.interactionFailedClients.set(interactionId, failed);
+        };
+        const interactionClientUnavailable = (interactionId, client) => live.disconnectedClients.has(client) ||
+            live.interactionFailedClients.get(interactionId)?.has(client) === true;
+        const allInteractionClientsUnavailable = (interactionId) => [live.injectClient, live.forwarderClient].every((client) => interactionClientUnavailable(interactionId, client));
+        const finishRecovery = (interactionId, event) => {
+            clearInteractionRouting(interactionId);
+            forwardInteraction(event);
+        };
+        const beginRecovery = (interactionId, event) => {
+            live.interactionOwners.delete(interactionId);
+            live.interactionRecoveries.set(interactionId, { event });
+        };
+        const promoteInteractionOwner = (interactionId, replacement) => {
+            const recovery = live.interactionRecoveries.get(interactionId);
+            live.interactionOwners.set(interactionId, replacement);
+            const submission = live.interactionSubmissions.get(interactionId);
+            if (!submission) {
+                clearRecovery(interactionId);
+                return true;
+            }
+            const replayed = replacement.resolveInteraction(interactionId, submission);
+            // A write failure can synchronously re-enter the listener and remove this
+            // owner. Only clear recovery when the replacement still owns the request.
+            if (replayed.disposition === "applied" &&
+                live.interactionOwners.get(interactionId) === replacement) {
+                clearRecovery(interactionId);
+                return true;
+            }
+            if (live.interactionOwners.get(interactionId) === replacement) {
+                live.interactionOwners.delete(interactionId);
+            }
+            if (recovery &&
+                live.canonicalInteractions.has(interactionId) &&
+                !live.settledInteractions.has(interactionId) &&
+                !live.interactionRecoveries.has(interactionId)) {
+                live.interactionRecoveries.set(interactionId, recovery);
+            }
+            return false;
+        };
+        const bindInteractionClient = (client) => {
+            client.setInteractionListener((event) => {
+                const interactionId = event.type === "requested"
+                    ? event.request.interactionId
+                    : event.interactionId;
+                const owner = live.interactionOwners.get(interactionId);
+                if (event.type === "requested") {
+                    // Receiving a native request proves this connection is alive and can
+                    // be retried even if an earlier copy failed on it.
+                    live.disconnectedClients.delete(client);
+                    const failed = live.interactionFailedClients.get(interactionId);
+                    failed?.delete(client);
+                    if (failed?.size === 0)
+                        live.interactionFailedClients.delete(interactionId);
+                    if (live.settledInteractions.has(interactionId))
+                        return;
+                    const recovery = live.interactionRecoveries.get(interactionId);
+                    if (recovery) {
+                        promoteInteractionOwner(interactionId, client);
+                        return;
+                    }
+                    if (owner && owner !== client) {
+                        const standbys = live.interactionStandbys.get(interactionId) ?? new Set();
+                        standbys.add(client);
+                        live.interactionStandbys.set(interactionId, standbys);
+                        return;
+                    }
+                    live.interactionOwners.set(interactionId, client);
+                    forwardInteraction(event);
+                    return;
+                }
+                const recoverableOwnerFailure = event.type === "cancelled" &&
+                    (event.reason === "app_server_disconnected" || event.reason === "response_write_failed");
+                if (recoverableOwnerFailure)
+                    markInteractionClientFailed(interactionId, client);
+                if (!owner || owner !== client) {
+                    const standbys = live.interactionStandbys.get(interactionId);
+                    standbys?.delete(client);
+                    if (standbys?.size === 0)
+                        live.interactionStandbys.delete(interactionId);
+                    const recovery = live.interactionRecoveries.get(interactionId);
+                    if (recoverableOwnerFailure &&
+                        live.canonicalInteractions.has(interactionId) &&
+                        allInteractionClientsUnavailable(interactionId)) {
+                        finishRecovery(interactionId, recovery?.event ?? event);
+                    }
+                    return;
+                }
+                if (recoverableOwnerFailure) {
+                    const standbys = live.interactionStandbys.get(interactionId);
+                    while (standbys && standbys.size > 0) {
+                        const replacement = standbys.values().next().value;
+                        if (!replacement)
+                            break;
+                        standbys.delete(replacement);
+                        if (interactionClientUnavailable(interactionId, replacement))
+                            continue;
+                        if (promoteInteractionOwner(interactionId, replacement)) {
+                            if (standbys.size === 0)
+                                live.interactionStandbys.delete(interactionId);
+                            return;
+                        }
+                        if (live.settledInteractions.has(interactionId))
+                            return;
+                    }
+                    if (!live.settledInteractions.has(interactionId)) {
+                        if (allInteractionClientsUnavailable(interactionId)) {
+                            finishRecovery(interactionId, event);
+                        }
+                        else {
+                            beginRecovery(interactionId, event);
+                        }
+                        return;
+                    }
+                }
+                clearInteractionRouting(interactionId);
+                forwardInteraction(event);
+            });
+            client.setConnectionListener((state) => {
+                if (state === "connected") {
+                    live.disconnectedClients.delete(client);
+                    return;
+                }
+                live.disconnectedClients.add(client);
+                for (const [interactionId, recovery] of [...live.interactionRecoveries]) {
+                    if (allInteractionClientsUnavailable(interactionId)) {
+                        finishRecovery(interactionId, recovery.event);
+                    }
+                }
+            });
+        };
+        const closeCanonicalInteractions = () => {
+            for (const interactionId of live.canonicalInteractions) {
+                rememberSettledInteraction(interactionId);
+                clearInteractionRouting(interactionId);
+            }
+            live.canonicalInteractions.clear();
+        };
         const sink = {
             onTurnStart: (turnId) => startNormalizer(turnId),
             onUserMessage: (text) => {
@@ -580,6 +844,7 @@ export class LocalAgentHost {
                     emit(se);
             },
             onTurnEnd: (usage) => {
+                closeCanonicalInteractions();
                 if (!normalizer)
                     return;
                 if (usage)
@@ -588,13 +853,16 @@ export class LocalAgentHost {
                 for (const se of normalizer.next({ type: "done" }))
                     emit(se);
                 normalizer = null;
+                currentResponseId = null;
             },
             onTurnError: (error) => {
+                closeCanonicalInteractions();
                 if (!normalizer)
                     return;
                 for (const se of normalizer.fail({ code: "codex_error", message: error.message, source: "execution" }))
                     emit(se);
                 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
@@ -604,6 +872,8 @@ export class LocalAgentHost {
         };
         const forwarder = new CodexSessionForwarder(forwarderClient, sink);
         live.forwarder = forwarder;
+        bindInteractionClient(injectClient);
+        bindInteractionClient(forwarderClient);
         this.liveSessions.set(localThreadId, live);
         forwarder.start();
         // A resumed session already has a thread id — bind immediately; a fresh
@@ -613,6 +883,65 @@ export class LocalAgentHost {
         }
         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;
+        try {
+            const liveSkills = liveCfg.selectedSkills.map((s) => ({ name: s.name, dir: s.dir }));
+            populateCodexSkills(this.codexHome(), liveSkills);
+            void previousCleanup?.().catch(() => undefined);
+            this.sessionSandbox = liveCfg.sandbox;
+            this.sessionApprovalPolicy = liveCfg.approvalPolicy;
+            live.model = getCodexModel(this.config, 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,
+                    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);
+            }
+            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;
+        }
+    }
     /** 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) {
@@ -628,6 +957,7 @@ export class LocalAgentHost {
             // 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(),
@@ -637,7 +967,7 @@ export class LocalAgentHost {
         void this.subscribeUntilReady(live, threadId);
     }
     /**
-     * Subscribe the forwarder connection to a thread (omnigent's
+     * Subscribe the forwarder connection to a thread (reference implementation's
      * `_subscribe_until_ready`). A fresh TUI thread has no rollout until its first
      * turn, so `thread/resume` is retried: park until the forwarder observes the
      * thread active, then retry WITHOUT `excludeTurns` so the response backfills the
@@ -692,7 +1022,7 @@ export class LocalAgentHost {
         return ok;
     }
     /**
-     * Inject a user turn into a session's live codex thread — omnigent's
+     * 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
@@ -701,7 +1031,7 @@ export class LocalAgentHost {
      * Returns an {@link InjectOutcome}: `notLive` when this session has no live
      * forwarder (caller may use the run path); `notReady`/`failed` are hard errors
      * the caller reports WITHOUT re-running (re-running double-writes alongside the
-     * forwarder). Park-until-ready (~60s), aligning omnigent's executor waiting for
+     * forwarder). Park-until-ready (~60s), aligning reference implementation's executor waiting for
      * the bridge instead of a short race that falls back to a second output path.
      */
     async injectMessage(localThreadId, text) {
@@ -712,7 +1042,7 @@ export class LocalAgentHost {
         if (!live)
             return "notLive";
         const run = live.injectLock.then(async () => {
-            // Park until the thread binds (~60s, omnigent codex_native_executor:177-186),
+            // 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);
             const threadId = live.threadId ?? live.forwarder.threadId();
@@ -730,12 +1060,18 @@ export class LocalAgentHost {
                 }
                 // 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({ threadId, input, cwd: live.cwd, model: live.model });
+                await live.injectClient.turnStart({
+                    threadId,
+                    input,
+                    cwd: live.cwd,
+                    model: live.model,
+                    ...(live.reasoningEffort ? { effort: live.reasoningEffort } : {}),
+                });
                 return "injected";
             }
             catch {
                 // RPC failed → hard error; caller reports it and does NOT re-run
-                // (omnigent: inject failure ⇒ response.failed, never local re-run).
+                // (reference implementation: inject failure ⇒ response.failed, never local re-run).
                 return "failed";
             }
         });
@@ -745,8 +1081,8 @@ export class LocalAgentHost {
     /**
      * Interrupt the session's active turn — the web Stop button. codex: the
      * app-server `turn/interrupt` on the active `{threadId, turnId}` (exactly what
-     * codex's own TUI interrupt key sends — omnigent `_handle_codex_native_interrupt`).
-     * claude: an Escape keystroke into the pane (no app-server — omnigent
+     * codex's own TUI interrupt key sends — reference implementation `_handle_codex_native_interrupt`).
+     * claude: an Escape keystroke into the pane (no app-server — reference implementation
      * `inject_interrupt`). Returns false as a no-op when there is no active turn.
      */
     async interruptLive(localThreadId) {
@@ -780,7 +1116,7 @@ export class LocalAgentHost {
         if (!live)
             return false;
         // Only interrupt an OPEN turn — codex's app-server rejects a stale turnId, and
-        // omnigent no-ops (204) when no turn is active.
+        // reference implementation no-ops (204) when no turn is active.
         if (!live.forwarder.isTurnOpen())
             return false;
         const threadId = live.threadId ?? live.forwarder.threadId();
@@ -797,12 +1133,19 @@ export class LocalAgentHost {
     }
     /** Stop + drop a session's live forwarder and its dedicated connection (session
      *  close / runner shutdown). The backend inject client is shared — left running. */
-    stopLiveCodexSession(localThreadId) {
+    stopLiveCodexSession(localThreadId, opts = {}) {
         const claude = this.liveClaudeSessions.get(localThreadId);
         if (claude) {
             this.liveClaudeSessions.delete(localThreadId);
             claude.stopped = true;
             claude.forwarder.stop();
+            if (opts.deferClaudeInteractionCleanup) {
+                this.pendingClaudeFinalizers.add(claude.forwarder);
+            }
+            else {
+                claude.forwarder.finalizeStop();
+            }
+            removeManagedClaudeSettings(claude.bridgeDir);
             // Remove the throwaway skills --plugin-dir temp so it doesn't leak per launch.
             void claude.skillCleanup?.();
             return;
@@ -813,37 +1156,75 @@ export class LocalAgentHost {
         this.liveSessions.delete(localThreadId);
         live.stopped = true;
         live.releaseActive?.();
+        live.injectClient.cancelInteractions("session_stopped");
+        live.forwarderClient.cancelInteractions("session_stopped");
+        live.injectClient.setInteractionListener(null);
+        live.forwarderClient.setInteractionListener(null);
+        live.injectClient.setConnectionListener(null);
+        live.forwarderClient.setConnectionListener(null);
+        live.interactionOwners.clear();
+        live.interactionStandbys.clear();
+        live.interactionSubmissions.clear();
         live.forwarder.stop();
+        live.interactionRecoveries.clear();
+        live.interactionFailedClients.clear();
+        live.disconnectedClients.clear();
+        live.canonicalInteractions.clear();
+        live.settledInteractions.clear();
         void live.forwarderClient.stop().catch(() => undefined);
         // Remove the session-scoped skills dir — the machine keeps zero task residue.
         void live.skillsCleanup?.();
     }
+    /** Complete the second shutdown phase after the runner has killed all native
+     * terminals and hook subprocesses. Must run before the runner process exits. */
+    finalizeStoppedLiveSessions() {
+        for (const forwarder of this.pendingClaudeFinalizers)
+            forwarder.finalizeStop();
+        this.pendingClaudeFinalizers.clear();
+    }
     // --- claude-native live session (parallel to the codex methods above) -----
     /** The interactive `claude` TUI spec for a claude-native live session: the real
      *  `claude` binary with rynx's hooks (`--settings`), resuming the bound session.
      *  Trust is pre-seeded so the daemon-spawned TUI never blocks on a first-run
-     *  prompt. (PermissionRequest approvals land in Phase 6; until then the TUI
-     *  surfaces its own permission prompt in the co-driven pane.) */
+     *  prompt. Questions and PermissionRequest approvals use the runtime-local
+     *  generic interaction bridge and remain inside the active Turn. */
     claudeTerminalSpec(localThreadId, record) {
-        const cwd = record?.cwd ?? process.cwd();
+        const live = this.liveClaudeSessions.get(localThreadId);
+        const cwd = record?.cwd ?? live?.cwd ?? process.cwd();
         try {
             ensureProjectTrusted(cwd);
         }
         catch {
             // A malformed ~/.claude.json shouldn't block launch; claude re-prompts.
         }
-        const settings = buildClaudeHookSettings({
+        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 hookSettings = buildClaudeHookSettings({
             bridgeDir: claudeBridgeDir(localThreadId),
-            permission: Boolean(process.env.RYNX_CONTROL_URL?.trim()),
+            ...(hookPermissionMode ? { permissionMode: hookPermissionMode } : {}),
             messageDisplay: true,
             statusLine: true,
         });
+        const settings = { ...inheritedSettings, ...hookSettings };
+        const settingsPath = writeManagedClaudeSettings(claudeBridgeDir(localThreadId), settings);
         // The live session (created by startLiveClaudeSession before the pane launches)
-        // carries the agent-spec launch config: model + `--plugin-dir` (skills; no persona).
-        const live = this.liveClaudeSessions.get(localThreadId);
+        // carries the agent-spec launch config: model, instructions, and skills.
         const args = buildClaudeTuiArgs({
-            settingsJson: JSON.stringify(settings),
+            settingsJson: settingsPath,
+            // A rynx-managed Session must have one interaction owner. Loading host or
+            // project hooks here would let a second PermissionRequest/PreToolUse hook
+            // 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 } : {}),
         });
@@ -859,19 +1240,17 @@ export class LocalAgentHost {
     /** 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 + the session skill env —
+    /** 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 skills). Instructions are intentionally NOT
-     *  returned: the co-driven TUI runs on vendor defaults (see
-     *  startLiveClaudeSession).
+     *  {@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. The env-build report
-     *  (installs, failures, content drift) is logged — a declared skill that
-     *  can't be provisioned is loudly absent, never silent; the session still
-     *  starts. `skillsCleanup` removes the session dir (call on session stop). */
+     *  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.
@@ -883,6 +1262,7 @@ export class LocalAgentHost {
             ...(opts?.agentName ? { agentName: opts.agentName } : {}),
             ...(opts?.agentSpec ? { spec: opts.agentSpec } : {}),
             runtime,
+            ...(opts?.reasoningEffort ? { reasoningEffort: opts.reasoningEffort } : {}),
         });
         const resolved = await resolveAgent({
             config: this.config,
@@ -891,31 +1271,53 @@ export class LocalAgentHost {
             ...(spec ? { spec } : {}),
         });
         const sessionSkillsDir = await mkdtemp(path.join(tmpdir(), "rynx-session-skills-"));
-        const skillEnv = await buildAgentSkillEnvironment(resolved.skills, sessionSkillsDir);
+        let skillEnv;
+        try {
+            skillEnv = await buildAgentSkillEnvironment(resolved.skills, sessionSkillsDir);
+            const declaredNames = (resolved.skills ?? []).map((skill) => skill.name);
+            const resolvedNames = skillEnv.resolved.map((skill) => skill.name);
+            const { report } = skillEnv;
+            if (report.errors.length > 0 ||
+                report.missing.length > 0 ||
+                report.drift.length > 0 ||
+                resolvedNames.length !== declaredNames.length ||
+                resolvedNames.some((name, index) => name !== declaredNames[index])) {
+                const details = [
+                    `declared=[${declaredNames.join(", ")}]`,
+                    `resolved=[${resolvedNames.join(", ")}]`,
+                    ...(report.missing.length > 0 ? [`missing=[${report.missing.join(", ")}]`] : []),
+                    ...(report.drift.length > 0 ? [`drift=[${report.drift.join("; ")}]`] : []),
+                    ...report.errors,
+                ].join("; ");
+                throw new Error(`failed to provision declared skills: ${details}`);
+            }
+        }
+        catch (error) {
+            await rm(sessionSkillsDir, { recursive: true, force: true }).catch(() => undefined);
+            throw error;
+        }
         const agent = opts?.agentName ?? resolved.name ?? "-";
         const { report } = skillEnv;
-        if (report.errors.length > 0 || report.missing.length > 0) {
-            console.error(`[skills] session=${localThreadId} agent=${agent} missing=[${report.missing.join(", ")}] ${report.errors.join("; ")}`);
-        }
         if (report.installed.length > 0) {
             console.error(`[skills] session=${localThreadId} agent=${agent} installed=[${report.installed.join(", ")}]`);
         }
-        for (const note of report.drift) {
-            console.error(`[skills] session=${localThreadId} agent=${agent} drift: ${note}`);
-        }
         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 bridgeDir = prepareClaudeBridgeDir(localThreadId, this.claudePermissionConfig(localThreadId));
-        const cwd = record?.cwd ?? process.cwd();
+        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
@@ -929,18 +1331,16 @@ export class LocalAgentHost {
             return false;
         }
         const model = resolveRuntimeModel(this.config, "claude", record?.model ?? liveCfg.model);
-        // Skills → throwaway `--plugin-dir`. Persona/instructions are deliberately NOT
-        // injected into the co-driven TUI: omnigent's claude-native and codex-native both
-        // leave the live thread on the vendor's built-in defaults (+ workspace AGENTS.md),
-        // so rynx matches (the non-live run path still injects persona for both runtimes).
-        // The plugin dir gets its own copy, so the session skills dir is disposable here.
+        // 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 omnigent's native).
+        // here — the live co-drive TUI runs unsandboxed (matches reference implementation's native).
         const permissionMode = liveCfg.permissionMode;
         const launchExtraArgs = [
             ...(skillPlugin?.pluginDir ? ["--plugin-dir", skillPlugin.pluginDir] : []),
@@ -952,15 +1352,36 @@ export class LocalAgentHost {
         let normalizer = null;
         let currentResponseId;
         const startNormalizer = (turnId) => {
-            // turnId unknown → fixed literal (never random), aligning omnigent `_response_id`.
-            currentResponseId = turnId ? `resp_claude_${turnId}` : "resp_claude_native";
+            // turnId unknown → fixed literal (never random), aligning reference implementation `_response_id`.
+            const responseId = turnId ? `resp_claude_${turnId}` : "resp_claude_native";
+            if (normalizer && currentResponseId === responseId)
+                return normalizer;
+            currentResponseId = responseId;
             normalizer = new SessionNormalizer({
                 sessionId: currentSessionId,
-                responseId: currentResponseId,
+                responseId,
                 model,
             });
             return normalizer;
         };
+        const forwardInteraction = (event) => {
+            const n = normalizer ?? startNormalizer(event.turnId);
+            const agentEvent = event.type === "requested"
+                ? { type: "interaction_requested", interaction: event.request }
+                : event.type === "resolved"
+                    ? {
+                        type: "interaction_resolved",
+                        interactionId: event.interactionId,
+                        resolution: event.resolution,
+                    }
+                    : {
+                        type: "interaction_cancelled",
+                        interactionId: event.interactionId,
+                        ...(event.reason ? { reason: event.reason } : {}),
+                    };
+            for (const se of n.next(agentEvent))
+                emit(se);
+        };
         let markReady;
         const ready = new Promise((resolve) => {
             markReady = resolve;
@@ -975,7 +1396,9 @@ export class LocalAgentHost {
             discoveredReady: false,
             stopped: false,
             launchModel: model,
+            ...(liveCfg.instructions ? { launchInstructions: liveCfg.instructions } : {}),
             launchExtraArgs,
+            ...(permissionMode ? { permissionMode } : {}),
             ...(skillPlugin?.cleanup ? { skillCleanup: skillPlugin.cleanup } : {}),
         };
         const sink = {
@@ -996,6 +1419,7 @@ export class LocalAgentHost {
                 for (const se of n.next(event))
                     emit(se);
             },
+            onInteraction: forwardInteraction,
             onTurnEnd: (usage) => {
                 if (!normalizer)
                     return;
@@ -1007,6 +1431,7 @@ export class LocalAgentHost {
                 for (const se of normalizer.next({ type: "done" }))
                     emit(se);
                 normalizer = null;
+                currentResponseId = undefined;
                 // One-time context-window banner past CONTEXT_WARN_RATIO (a transient note,
                 // cleared by the next turn's first item). statusLine pre-computes the %.
                 const pct = usage && typeof usage.used_percentage === "number" ? usage.used_percentage : undefined;
@@ -1039,6 +1464,7 @@ export class LocalAgentHost {
                 for (const se of normalizer.fail({ code: "claude_error", message: error.message, source: "execution" }))
                     emit(se);
                 normalizer = null;
+                currentResponseId = undefined;
             },
             onSessionDiscovered: (claudeSessionId) => this.onClaudeDiscovered(live, localThreadId, opts?.agentName ?? record?.agent, claudeSessionId),
             onSessionRotated: (kind, claudeSessionId) => {
@@ -1113,10 +1539,10 @@ export class LocalAgentHost {
             .catch(() => undefined);
         live.markReady();
     }
-    /** Inject a web message into a claude-native pane via tmux (omnigent recipe),
+    /** 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
      *  is (re)attached, then pastes; `injectViaTerminal` RAISES if the prompt never
-     *  appears (omnigent RAISE), so a not-ready pane is a hard error — NOT a
+     *  appears (reference implementation RAISE), so a not-ready pane is a hard error — NOT a
      *  fall-through-to-run signal. Returns {@link InjectOutcome}. */
     injectClaude(live, localThreadId, text) {
         const run = live.injectLock.then(async () => {
@@ -1150,7 +1576,7 @@ export class LocalAgentHost {
     /** Park until the claude session's tmux injector is (re)attached by the
      *  runner-child, or the deadline passes. Pane relaunch re-attaches it via
      *  {@link attachTerminalInjector}; without this a message during that window
-     *  would fail and (pre-omnigent) fall through to a second output path. */
+     *  would fail and (pre-reference implementation) fall through to a second output path. */
     async waitInjector(live, timeoutMs) {
         const deadline = Date.now() + timeoutMs;
         while (!live.injector && Date.now() < deadline) {
@@ -1166,15 +1592,6 @@ export class LocalAgentHost {
         if (live)
             live.injector = injector;
     }
-    /** The PermissionRequest hook's server target from the runner-child env (the
-     *  daemon control URL + token), or undefined when unset — then no permission
-     *  hook is registered and claude surfaces its own TUI prompt in the pane. */
-    claudePermissionConfig(localThreadId) {
-        const serverUrl = process.env.RYNX_CONTROL_URL?.trim();
-        if (!serverUrl)
-            return undefined;
-        return { sessionId: localThreadId, serverUrl };
-    }
     /** List the models a runtime exposes (App Server for codex/traex; static for claude). */
     async listModels(runtime) {
         const resolved = runtime ?? this.defaultRuntime;
@@ -1251,6 +1668,7 @@ export class LocalAgentHost {
                 codexSessionId: forkedThreadId,
                 cwd: record.cwd,
                 model: record.model,
+                reasoningEffort: record.reasoningEffort,
                 runtime,
                 updatedAt: new Date().toISOString(),
             });
@@ -1299,6 +1717,28 @@ function raceReady(ready, timeoutMs) {
             clearTimeout(timer);
     });
 }
+function liveConfigSignature(opts, runtime, cwd) {
+    return JSON.stringify(stableValue({
+        runtime,
+        cwd,
+        agentName: opts?.agentName,
+        agentSpec: opts?.agentSpec,
+    }));
+}
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const item = value[key];
+            if (item !== undefined)
+                out[key] = stableValue(item);
+        }
+        return out;
+    }
+    return value;
+}
 export function getCodexModel(config, override) {
     return override?.trim() || config.CODEX_MODEL;
 }
@@ -1316,7 +1756,7 @@ export function isUnsupportedMethodError(error) {
 }
 /** A `thread/resume` failure meaning the thread has no (or an empty) rollout yet
  *  — a fresh TUI thread before its first turn. Retryable (park until active).
- *  Mirrors omnigent's `_is_thread_not_ready_error`. */
+ *  Mirrors reference implementation's `_is_thread_not_ready_error`. */
 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"));