@wrenai/genbi 0.0.3 → 0.0.5

package/dist-server/server/native-sessions.js

@@ -1,20 +1,31 @@
+import { startCodexTerminal } from "./runtime-host/codex-terminal.js";
+import { CodexConversation } from "./runtime-host/codex-conversation.js";
+import { runNativeDispatchProcess } from "./native-dispatch-process.js";
+import { NativeComponentAdmission, nativeComponentHostContract, readNativeComponentPlans } from "./native-components.js";
 /**
  * Durable native-session control plane.  SQLite owns identity/lifecycle;
  * the PTY remains deliberately process-local and contains the only replay.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { execFileSync, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { accessSync, chmodSync, constants, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { InteractiveLaunchError, NO_INTERACTIVE_TERMINAL_LEASES, interactiveExecutableAvailable } from "./interactive-terminal.js";
+import { isDeepStrictEqual } from "node:util";
+import { WarbleBinaryNotFoundError } from "../harness/compile/errors.js";
+import { InteractiveLaunchError, NO_INTERACTIVE_TERMINAL_LEASES } from "./interactive-terminal.js";
 import { newId } from "./db.js";
 import { NATIVE_MCP_CREDENTIAL_ENV_VAR } from "./native-artifacts.js";
 import { dispatchForPurpose, NATIVE_DISPATCH_REGISTRY, NATIVE_PURPOSES, nativeTargetLabel, sameNativeRuntimeBinding, targetForProvider } from "./native-dispatch-registry.js";
 import { createNativeSessionWorkspace, initializeNativeSessionStateBase, nativeSessionStateBaseAvailable, nativeSessionStateBaseAvailableForProject, validateNativeSessionWorkspace } from "./native-session-workspace.js";
 import { NativeWrenRuntimeError, resolveNativeWrenRuntime } from "./native-wren-runtime.js";
+import { ManagedWrenRuntimeError } from "./managed-wren-runtime.js";
+import { assertNativeExecutableIdentity, assertNativeRuntimeSpec, attestNativeExecutable, buildNativeChildEnvironment, buildNativeRuntimeSpec, nativeProcessEnvironment, resolveNativeExecutable } from "./native-runtime-spec.js";
+import { createEmptyCodexWrenHome, materializeCodexWrenHome } from "./native-wren-home.js";
 import { runtimeSettingsCorrection } from "./runtime-binding.js";
 import { sealNativeClaudeResumeHandle, sealNativeResumeHandle, unsealNativeResumeHandle } from "./native-session-resume.js";
+import { RuntimeHost } from "./runtime-host/local.js";
+import { runtimeNotReady } from "./runtime-host/policy.js";
 export const NATIVE_VENDORS = ["claude", "codex"];
 export { NATIVE_PURPOSES };
 export const NATIVE_SETUP_RECOVERY_MCP_TOOL_NAME = "report_setup_recovery";
@@ -38,12 +49,15 @@ const START_SEPARATE_REPLAY_LIMIT = 128;
 const CODEX_NATIVE_PERMISSION_HEADER = "[permissions.warble_native_wren.filesystem]";
 const PROVIDER_SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const CODEX_RESUME_HANDLE_FILE = path.join(".warble", "codex-thread-id");
+const CODEX_WREN_RUNTIME_UNPROVISIONED = runtimeNotReady("codex-app-server", "unprovisioned", "codex_wren_runtime_unprovisioned");
 function logNativeLaunchFailure(purpose, vendor, phase, error) {
-    const category = error instanceof InteractiveLaunchError ? "rejected" : "unexpected";
-    // Keep the precise boundary server-side without logging exception text,
-    // paths, credentials, argv, or other launch material. Browser/API callers
-    // continue through nativeSessionLaunchFailure's closed public projection.
-    console.error(`[native-sessions] launch failed purpose=${purpose} vendor=${vendor} phase=${phase} category=${category}`);
+    const rejected = error instanceof InteractiveLaunchError;
+    // Exception text, paths, credentials and argv stay out of the log for an
+    // unexpected error, which may carry any of them. A rejection carries a
+    // sentence authored here, and suppressing that turned every diagnosis into a
+    // guess: an operator saw a phase and a category and no cause.
+    const detail = rejected ? ` reason=${error.message}` : "";
+    console.error(`[native-sessions] launch failed purpose=${purpose} vendor=${vendor} phase=${phase} category=${rejected ? "rejected" : "unexpected"}${detail}`);
 }
 /**
  * The producer deliberately sees only a sealed binding identity, never a caller-supplied path.
@@ -71,60 +85,6 @@ export function grantCodexBoundProjectRead(cwd, projectPath, dataRoots = []) {
     writeFileSync(configPath, updated, { encoding: "utf8", mode: 0o600 });
     chmodSync(configPath, 0o600);
 }
-const MATERIALIZE_WREN_HOME_SCRIPT = String.raw `
-import os
-import pathlib
-import shutil
-import sys
-import yaml
-from wren.profile import expand_profile_secrets, resolve_profile_for_project
-
-project = pathlib.Path(sys.argv[1]).resolve(strict=True)
-destination = pathlib.Path(sys.argv[2])
-name, profile = resolve_profile_for_project(project, strict=True)
-if not name or not profile:
-    raise SystemExit(2)
-destination.mkdir(mode=0o700, parents=False, exist_ok=False)
-profile_path = destination / "profiles.yml"
-profile_path.write_text(yaml.safe_dump({"active": name, "profiles": {name: profile}}, sort_keys=False), encoding="utf-8")
-os.chmod(profile_path, 0o600)
-project_env = project / ".env"
-if project_env.exists():
-    if project_env.is_symlink() or not project_env.is_file():
-        raise SystemExit(3)
-    session_env = destination / ".env"
-    shutil.copyfile(project_env, session_env)
-    os.chmod(session_env, 0o600)
-
-expanded = expand_profile_secrets(profile)
-data_source = expanded.get("datasource")
-data_root = None
-if data_source in ("duckdb", "local_file"):
-    data_root = expanded.get("url")
-elif data_source == "datafusion":
-    data_root = expanded.get("source")
-if data_root:
-    root = pathlib.Path(data_root).expanduser()
-    if not root.is_absolute():
-        root = project / root
-    print(root.resolve(strict=True))
-`;
-function materializeCodexWrenHome(runtime, projectPath, cwd) {
-    const destination = path.join(cwd, ".wren");
-    try {
-        const output = execFileSync(runtime.venv_python, ["-c", MATERIALIZE_WREN_HOME_SCRIPT, projectPath, destination], {
-            cwd: projectPath,
-            env: process.env,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            timeout: 10_000,
-        });
-        return { home: destination, dataRoots: output.trim() ? [output.trim()] : [] };
-    }
-    catch {
-        throw new InteractiveLaunchError("native Wren project profile is unavailable");
-    }
-}
 function nativeSessionRestartReason(target, cause) {
     switch (cause) {
         case "not_terminal":
@@ -172,6 +132,13 @@ export class NativeSetupRecoveryError extends Error {
  * whichever verb the scope declares, after checking the declaration against the compiled IR.
  */
 const entryVerbFor = (purpose) => purpose === "analysis" ? "answer_query" : purpose === "setup" ? "connect_source" : "draft_enrichment";
+/** User-selected analysis entry is a single pin; it never widens Claude scope. */
+export function selectedNativeEntry(purpose, vendor, entryVerb) {
+    if (entryVerb != null && (vendor !== "codex" || purpose !== "analysis" || !["answer_query", "generate_dashboard"].includes(entryVerb))) {
+        throw new InteractiveLaunchError("native session entry is invalid");
+    }
+    return vendor === "codex" && purpose === "analysis" ? entryVerb ?? "answer_query" : undefined;
+}
 const agentFor = (purpose, vendor) => vendor === "claude" ? entryVerbFor(purpose) : `genbi-${purpose === "context_enrichment" ? "enrich-context" : purpose}`;
 /**
  * Closed v4 Claude entry contract. This host is the only place the mapping exists: Warble used to
@@ -200,9 +167,9 @@ const claudeScopeEntry = (purpose, vendor) => vendor === "claude" && !PINNED_CLA
  * most by pinning: its profile mounts four selectable components, and a pinned session can only
  * reach the other three by delegating out of the one it was forced to start as.
  */
-const nativeEntryFor = (purpose, vendor) => claudeScopeEntry(purpose, vendor)
+const nativeEntryFor = (purpose, vendor, entryVerb) => claudeScopeEntry(purpose, vendor)
     ? { kind: "scope", prompt: welcomePromptFor(purpose) }
-    : { verb: entryVerbFor(purpose), prompt: welcomePromptFor(purpose) };
+    : { verb: selectedNativeEntry(purpose, vendor, entryVerb) ?? entryVerbFor(purpose), prompt: welcomePromptFor(purpose) };
 /** Closed producer/host contract for the one initial native TUI prompt. */
 const welcomePromptFor = (purpose) => {
     switch (purpose) {
@@ -214,6 +181,50 @@ const welcomePromptFor = (purpose) => {
             return "Help me inspect this project's context and draft a read-only enrichment proposal. Do not apply changes; ask what context I want to review.";
     }
 };
+export const DEFAULT_CONVERSATION_PROFILE = NATIVE_DISPATCH_REGISTRY.analysis.profile;
+const DEFAULT_PROFILE_SELECTION = Object.freeze({ id: DEFAULT_CONVERSATION_PROFILE, entry: { kind: "scope" } });
+const PROFILE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const CODEX_CUSTOM_PROFILE_UNAVAILABLE = "conversation profiles other than the default are not available on the Codex CLI";
+/**
+ * A selection that departs from the purpose's fixed profile, or `undefined` when the registry's
+ * rules for that purpose apply unchanged. System purposes never have one.
+ */
+const customSelection = (purpose, selection) => purpose === "analysis" && selection !== undefined && selection.id !== NATIVE_DISPATCH_REGISTRY[purpose].profile ? selection : undefined;
+/**
+ * The profile id a launch request names, validated for shape and purpose. Only analysis sessions
+ * run inside a selectable profile; the system purposes keep their fixed ones.
+ */
+function requestedProfileId(purpose, profile) {
+    if (profile === undefined)
+        return purpose === "analysis" ? DEFAULT_CONVERSATION_PROFILE : NATIVE_DISPATCH_REGISTRY[purpose].profile;
+    if (purpose !== "analysis")
+        throw new InteractiveLaunchError("native session profile is only selectable for analysis");
+    if (!PROFILE_ID_PATTERN.test(profile))
+        throw new InteractiveLaunchError("native session profile is invalid");
+    return profile;
+}
+const scopeEntryFor = (purpose, vendor, selection) => {
+    const custom = customSelection(purpose, selection);
+    return custom ? custom.entry.kind === "scope" : claudeScopeEntry(purpose, vendor);
+};
+/** The agent a pinned launch names, or the component a scope session is recorded under. */
+const expectedAgentFor = (purpose, vendor, selection) => {
+    const custom = customSelection(purpose, selection);
+    if (!custom)
+        return agentFor(purpose, vendor);
+    return custom.entry.kind === "agent" ? custom.entry.verb : custom.id;
+};
+/** The entry declared in the scope descriptor; a custom profile's form comes from admission. */
+const entryFor = (purpose, vendor, entryVerb, selection) => {
+    const custom = customSelection(purpose, selection);
+    if (!custom)
+        return nativeEntryFor(purpose, vendor, entryVerb);
+    // The welcome text is purpose text, not profile text: every conversation profile is entered the
+    // same way, so the first turn stays the one string the launch gate already checks.
+    return custom.entry.kind === "scope"
+        ? { kind: "scope", prompt: welcomePromptFor(purpose) }
+        : { verb: custom.entry.verb, prompt: welcomePromptFor(purpose) };
+};
 function sameBinding(a, b) {
     return b !== undefined && a.path === b.path && a.identity === b.identity && a.generation === b.generation && a.revision === b.revision;
 }
@@ -222,6 +233,7 @@ function resumeScopeFingerprint(row) {
         row.id, row.purpose, row.vendor, row.scopeKind, row.projectIdentity,
         row.bindingGeneration, row.projectRevision, row.dispatchProfile,
         row.dispatchTarget, row.runtimeGeneration,
+        ...(row.entryVerb && row.entryVerb !== "answer_query" ? [row.entryVerb] : []),
     ])).digest("hex");
 }
 function record(value) {
@@ -234,25 +246,6 @@ function contained(root, candidate) {
     const relative = path.relative(root, candidate);
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
-function localExecutableAvailable(executable, pathValue = process.env["PATH"]) {
-    return localExecutablePath(executable, pathValue) !== undefined;
-}
-function localExecutablePath(executable, pathValue = process.env["PATH"]) {
-    const candidates = path.isAbsolute(executable) || executable.includes(path.sep)
-        ? [path.resolve(executable)]
-        : (pathValue ?? "").split(path.delimiter).filter(Boolean).map((directory) => path.join(directory, executable));
-    for (const candidate of candidates) {
-        try {
-            const stat = statSync(candidate);
-            if (stat.isFile() && (stat.mode & 0o111) !== 0)
-                return realpathSync(candidate);
-        }
-        catch {
-            // Try the next PATH entry. The public readiness response never learns this path.
-        }
-    }
-    return undefined;
-}
 function configuredWorkspace(cwd, create) {
     try {
         if (create)
@@ -352,6 +345,16 @@ export function nativeSessionLaunchFailure(error) {
         return "native session launch artifacts are unavailable";
     if (message === "native session launch paths are unavailable" || message === "native session launch paths are outside its server-owned scope")
         return "native session launch artifacts are unavailable";
+    // Every InteractiveLaunchError message is authored in this file: a fixed
+    // sentence, a fixed profile name, or a reason readiness already publishes.
+    // None is built from a path, argv, or process output. Falling through to the
+    // generic string threw away the cause of eighteen distinct failures, which is
+    // what left "native session launch failed" as the only thing a user could see.
+    if (error instanceof InteractiveLaunchError)
+        return message;
+    // This one is NOT safe to forward: its text embeds the configured binary path.
+    if (error instanceof WarbleBinaryNotFoundError)
+        return "the Warble binary could not be resolved";
     return "native session launch failed";
 }
 const NATIVE_PRODUCER_CATEGORY = "native_session_producer_incompatible";
@@ -394,25 +397,14 @@ function nativeProducerResult(available, identity, phase, detail, reason, produc
         vendors: everyVendorUnavailable(available ? { available: true, diagnostic } : { available: false, reason, diagnostic }),
     };
 }
-function executableIdentity(executable) {
-    try {
-        const metadata = statSync(executable);
-        if (!metadata.isFile() || (metadata.mode & 0o111) === 0)
-            return undefined;
-        return `sha256:${createHash("sha256").update(readFileSync(executable)).digest("hex")}`;
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * The configured spelling may be a PATH lookup or retargetable symlink. A
  * preflight result instead owns the resolved executable and its digest. Check
  * both again before creating a durable row and directly before spawning.
  */
 function assertNativeProducerIdentity(producer) {
-    const resolved = localExecutablePath(producer.executable);
-    if (resolved !== producer.executable || executableIdentity(producer.executable) !== producer.identity) {
+    const current = attestNativeExecutable("producer", producer.executable);
+    if (current.executable !== producer.executable || current.digest !== producer.identity) {
         throw new InteractiveLaunchError("native session producer is incompatible");
     }
 }
@@ -421,7 +413,7 @@ function assertNativeProducerIdentity(producer) {
  * output is used only for local help-marker parsing and is never logged or
  * returned: a third-party executable may print arbitrary sensitive text.
  */
-function runNativeProbe(command, args) {
+function runNativeProbe(command, args, env) {
     return new Promise((resolve) => {
         let output = "";
         let timedOut = false;
@@ -438,9 +430,10 @@ function runNativeProbe(command, args) {
         };
         let child;
         try {
-            child = spawn(command, [...args], {
+            assertNativeExecutableIdentity(command);
+            child = spawn(command.executable, [...args], {
                 cwd: os.tmpdir(),
-                env: { PATH: process.env["PATH"] ?? "" },
+                env: nativeProcessEnvironment(env),
                 shell: false,
                 stdio: ["ignore", "pipe", "pipe"],
             });
@@ -475,14 +468,23 @@ function runNativeProbe(command, args) {
  * validator used just before a PTY starts.
  */
 export async function probeNativeSessionProducer(input) {
-    const executable = localExecutablePath(input.warbleBin);
-    if (!executable)
+    const producerExecutable = resolveNativeExecutable("producer", input.warbleBin, input.pathValue);
+    if (!producerExecutable)
         return nativeProducerResult(false, undefined, "resolve", "result=binary_not_found", "the Warble binary could not be resolved");
-    const identity = executableIdentity(executable);
-    if (!identity)
-        return nativeProducerResult(false, undefined, "identity", "result=identity_unavailable", "the Warble binary could not be identified");
+    const identity = producerExecutable.digest;
+    const executable = producerExecutable.executable;
     const producer = { executable, identity };
-    const help = await runNativeProbe(executable, ["dispatch", "--help"]);
+    const nodeExecutable = input.nodeExecutable ?? attestNativeExecutable("node", process.execPath);
+    const childToolDirectories = [...new Set([
+            ...(input.childToolDirectories ?? []),
+            path.dirname(nodeExecutable.executable),
+            path.dirname(executable),
+        ])];
+    const probeEnv = buildNativeChildEnvironment({
+        toolDirectories: childToolDirectories,
+        home: input.nativeHome ?? os.homedir(),
+    });
+    const help = await runNativeProbe(producerExecutable, ["dispatch", "--help"], probeEnv);
     if (help.spawnFailed)
         return nativeProducerResult(false, identity, "dispatch_help", "result=spawn_failed", "the Warble binary could not be started");
     if (help.timedOut)
@@ -497,65 +499,97 @@ export async function probeNativeSessionProducer(input) {
     // reported the producer incompatible even for a Claude-only install, which is
     // exactly what an installed package produces.
     const vendors = {};
+    const purposes = Object.fromEntries(NATIVE_PURPOSES.map((purpose) => [purpose, {}]));
     for (const vendor of NATIVE_PROBE_TARGETS) {
-        let outcome = { available: true, diagnostic: producerDiagnostic(identity, `complete_${vendor}`, "result=compatible") };
-        for (const purpose of NATIVE_PURPOSES) {
-            const irPath = input.irPaths[purpose];
-            if (!irPath || !configuredIrPath(irPath))
-                continue;
-            const phase = `dispatch_${purpose}_${vendor}`;
-            const fail = (detail, reason) => ({ available: false, reason, diagnostic: producerDiagnostic(identity, phase, detail) });
-            let root;
-            try {
-                root = mkdtempSync(path.join(os.tmpdir(), "genbi-native-preflight-"));
-                chmodSync(root, 0o700);
-                root = realpathSync(root);
-                const outputRoot = path.join(root, "out");
-                mkdirSync(outputRoot, { mode: 0o700 });
-                const bootstrapRoot = path.join(root, "bootstrap");
-                mkdirSync(bootstrapRoot, { mode: 0o700 });
-                const scopeId = `preflight-${purpose}-${vendor}`;
-                const scopePath = path.join(root, "scope.json");
-                const mcpPath = path.join(root, "mcp.json");
-                const wrenRuntime = vendor === "codex" ? resolveNativeWrenRuntime(input.wrenShim) : undefined;
-                const binding = NATIVE_DISPATCH_REGISTRY[purpose].scopeKind === "bound_project"
-                    ? { project_identity: "native-preflight-project", generation: "1", revision: "native-preflight-revision" }
-                    : undefined;
-                writeFileSync(scopePath, JSON.stringify({ version: "3", kind: NATIVE_DISPATCH_REGISTRY[purpose].scopeKind, scope_id: scopeId, cwd: outputRoot, entry: nativeEntryFor(purpose, vendor), ...(purpose === "setup" ? { bootstrap_root: bootstrapRoot } : {}), ...(wrenRuntime ? { wren_runtime: wrenRuntime } : {}), ...(binding ? { binding } : {}) }), { encoding: "utf8", mode: 0o600, flag: "wx" });
-                writeFileSync(mcpPath, JSON.stringify({ version: "1", url: "http://127.0.0.1:0/api/native-sessions/mcp", credential: "native-preflight-nonsecret" }), { encoding: "utf8", mode: 0o600, flag: "wx" });
-                const dispatched = await runNativeProbe(executable, ["dispatch", irPath, "--target", targetForProvider(vendor), "--purpose", purpose, "--native-scope", scopePath, "--native-mcp", mcpPath, "--out", outputRoot]);
-                if (dispatched.spawnFailed) {
-                    outcome = fail("result=spawn_failed", "the Warble binary could not be started for this vendor");
-                    break;
-                }
-                if (dispatched.timedOut) {
-                    outcome = fail("result=timed_out", "the Warble binary did not respond for this vendor");
-                    break;
-                }
-                if (dispatched.exitCode !== 0) {
-                    outcome = fail(`result=exit_code_${dispatched.exitCode ?? "signal"}`, "Warble could not dispatch this profile for this vendor");
-                    break;
-                }
+        for (const selectedPurpose of NATIVE_PURPOSES) {
+            let outcome = { available: true, diagnostic: producerDiagnostic(identity, `complete_${vendor}`, "result=compatible") };
+            const probes = [selectedPurpose].flatMap((purpose) => purpose === "analysis" && vendor === "codex" && input.prepareComponents
+                ? [{ purpose, entryVerb: "answer_query" }, { purpose, entryVerb: "generate_dashboard" }]
+                : [{ purpose, entryVerb: undefined }]);
+            for (const { purpose, entryVerb } of probes) {
+                const irPath = input.irPaths[purpose];
+                if (!irPath || !configuredIrPath(irPath))
+                    continue;
+                const phase = `dispatch_${purpose}_${vendor}${entryVerb ? `_${entryVerb}` : ""}`;
+                const fail = (detail, reason) => ({ available: false, reason, diagnostic: producerDiagnostic(identity, phase, detail) });
+                let root;
                 try {
-                    readNativeLaunchSpec(outputRoot, purpose, vendor, scopeId, undefined, { version: "1", url: "http://127.0.0.1:0/api/native-sessions/mcp", credential: "native-preflight-nonsecret" });
+                    root = mkdtempSync(path.join(os.tmpdir(), "genbi-native-preflight-"));
+                    chmodSync(root, 0o700);
+                    root = realpathSync(root);
+                    const outputRoot = path.join(root, "out");
+                    mkdirSync(outputRoot, { mode: 0o700 });
+                    const bootstrapRoot = path.join(root, "bootstrap");
+                    mkdirSync(bootstrapRoot, { mode: 0o700 });
+                    const scopeId = `preflight-${purpose}-${vendor}`;
+                    const scopePath = path.join(root, "scope.json");
+                    const mcpPath = path.join(root, "mcp.json");
+                    // Production passes the sealed managed record. The legacy resolver is a
+                    // compatibility seam for deterministic fixture tests only; bin.ts does
+                    // not provide a shim and so can never select an editable installation.
+                    const wrenRuntime = vendor === "codex"
+                        ? input.resolveManagedCodexWrenRuntime
+                            ? input.resolveManagedCodexWrenRuntime()
+                            : resolveNativeWrenRuntime(input.wrenShim)
+                        : undefined;
+                    const binding = NATIVE_DISPATCH_REGISTRY[purpose].scopeKind === "bound_project"
+                        ? { project_identity: "native-preflight-project", generation: "1", revision: "native-preflight-revision" }
+                        : undefined;
+                    const scope = { version: "3", kind: NATIVE_DISPATCH_REGISTRY[purpose].scopeKind, scope_id: scopeId, cwd: outputRoot, entry: nativeEntryFor(purpose, vendor, entryVerb), ...(purpose === "setup" ? { bootstrap_root: bootstrapRoot } : {}), ...(wrenRuntime ? { wren_runtime: wrenRuntime } : {}), ...(binding ? { binding } : {}) };
+                    const scopeDocument = JSON.stringify(scope);
+                    writeFileSync(scopePath, scopeDocument, { encoding: "utf8", mode: 0o600, flag: "wx" });
+                    const irDocument = input.prepareComponents && purpose === "analysis" ? readFileSync(irPath, "utf8") : undefined;
+                    const prepared = irDocument ? input.prepareComponents?.({ vendor, purpose, irDocument, scope }) : undefined;
+                    const hostPath = path.join(root, "component-host.json");
+                    let receipt;
+                    if (prepared && irDocument) {
+                        if (prepared.identity.vendor !== vendor || !isDeepStrictEqual(prepared.identity.binding, binding))
+                            throw new Error("Incompatible component probe identity");
+                        writeFileSync(hostPath, JSON.stringify(nativeComponentHostContract(prepared)), { encoding: "utf8", mode: 0o600, flag: "wx" });
+                        receipt = { identity: structuredClone(prepared.identity), irDocument, scopeDocument,
+                            hostRoots: structuredClone(prepared.hostRoots), contexts: structuredClone(prepared.contexts) };
+                    }
+                    writeFileSync(mcpPath, JSON.stringify({ version: "1", url: "http://127.0.0.1:0/api/native-sessions/mcp", credential: "native-preflight-nonsecret" }), { encoding: "utf8", mode: 0o600, flag: "wx" });
+                    const dispatched = await runNativeProbe(producerExecutable, ["dispatch", irPath, "--target", targetForProvider(vendor), "--purpose", purpose, "--native-scope", scopePath, "--native-mcp", mcpPath, ...(prepared ? ["--native-host", hostPath] : []), "--out", outputRoot], probeEnv);
+                    if (dispatched.spawnFailed) {
+                        outcome = fail("result=spawn_failed", "the Warble binary could not be started for this vendor");
+                        break;
+                    }
+                    if (dispatched.timedOut) {
+                        outcome = fail("result=timed_out", "the Warble binary did not respond for this vendor");
+                        break;
+                    }
+                    if (dispatched.exitCode !== 0) {
+                        const missingHost = !prepared && dispatched.output.includes("component_invocation")
+                            && dispatched.output.includes("no trusted invocation handler is installed");
+                        outcome = missingHost
+                            ? fail("result=component_runtime_unprovisioned", "Native component execution has not been provisioned for this profile.")
+                            : fail(`result=exit_code_${dispatched.exitCode ?? "signal"}`, "Warble could not dispatch this profile for this vendor");
+                        break;
+                    }
+                    try {
+                        readNativeLaunchSpec(outputRoot, purpose, vendor, scopeId, undefined, { version: "1", url: "http://127.0.0.1:0/api/native-sessions/mcp", credential: "native-preflight-nonsecret" }, undefined, undefined, undefined, receipt);
+                    }
+                    catch {
+                        outcome = fail("result=launch_spec_incompatible", "Warble emitted a launch spec this build cannot run");
+                        break;
+                    }
                 }
-                catch {
-                    outcome = fail("result=launch_spec_incompatible", "Warble emitted a launch spec this build cannot run");
+                catch (error) {
+                    outcome = error instanceof NativeWrenRuntimeError || error instanceof ManagedWrenRuntimeError
+                        ? fail(`result=wren_runtime_unavailable (${error.message})`, error.message)
+                        : fail("result=preflight_workspace_unavailable", "the preflight could not create its temporary workspace");
                     break;
                 }
+                finally {
+                    if (root)
+                        rmSync(root, { recursive: true, force: true });
+                }
             }
-            catch (error) {
-                outcome = error instanceof NativeWrenRuntimeError
-                    ? fail(`result=wren_runtime_unavailable (${error.message})`, error.message)
-                    : fail("result=preflight_workspace_unavailable", "the preflight could not create its temporary workspace");
-                break;
-            }
-            finally {
-                if (root)
-                    rmSync(root, { recursive: true, force: true });
-            }
+            purposes[selectedPurpose][vendor] = outcome;
         }
-        vendors[vendor] = outcome;
+        vendors[vendor] = NATIVE_PURPOSES.map((purpose) => purposes[purpose][vendor]).find((probe) => !probe.available)
+            ?? { available: true, diagnostic: producerDiagnostic(identity, `complete_${vendor}`, "result=compatible") };
     }
     const usable = NATIVE_PROBE_TARGETS.filter((vendor) => vendors[vendor].available);
     const available = usable.length > 0;
@@ -571,6 +605,7 @@ export async function probeNativeSessionProducer(input) {
         producer,
         diagnostic: producerDiagnostic(identity, "complete", available ? `result=compatible_${usable.join("+")}` : `result=no_compatible_vendor ${vendorResults}`),
         vendors,
+        purposes,
     };
 }
 function parseNativeSetupRecoveryReport(value) {
@@ -600,7 +635,7 @@ function parseNativeSetupRecoveryReport(value) {
  * omits the host-issued scope; Setup exposes only its separately authorized
  * bootstrap root, which is revalidated against the durable host configuration.
  */
-export function readNativeLaunchSpec(cwd, purpose, vendor, scopeId, binding, mcp, materializationState, authorizedWorkspace, providerLaunch) {
+export function readNativeLaunchSpec(cwd, purpose, vendor, scopeId, binding, mcp, materializationState, authorizedWorkspace, providerLaunch, componentReceipt, selection) {
     const ownershipRoot = binding?.path ?? authorizedWorkspace;
     const root = materializationState && ownershipRoot
         ? validateNativeSessionWorkspace(materializationState, ownershipRoot, cwd)
@@ -616,19 +651,28 @@ export function readNativeLaunchSpec(cwd, purpose, vendor, scopeId, binding, mcp
         throw new InteractiveLaunchError("native session launch specification is invalid");
     }
     const value = record(raw);
+    const isV5 = componentReceipt !== undefined;
+    if (isV5 && (!mcp || purpose !== "analysis"))
+        throw new InteractiveLaunchError("native component launch requires a bound analysis session");
     const isV4 = mcp !== undefined;
     const isSetupV4 = isV4 && purpose === "setup";
-    const keys = ["version", "target", "purpose", "executable", "argv", "agent", ...(isV4 ? ["mcp", ...(isSetupV4 ? ["bootstrap_root"] : [])] : ["scope"]), "cwd", "artifact_root", "handoff_path"];
+    const keys = ["version", "target", "purpose", "executable", "argv", "agent", ...(isV5 ? ["component_host"] : []), ...(isV4 ? ["mcp", ...(isSetupV4 ? ["bootstrap_root"] : [])] : ["scope"]), "cwd", "artifact_root", "handoff_path"];
     const target = targetForProvider(vendor);
     const executable = vendor === "claude" ? "claude" : "codex";
-    const expectedAgent = agentFor(purpose, vendor);
-    const scopeEntry = claudeScopeEntry(purpose, vendor);
+    const expectedAgent = expectedAgentFor(purpose, vendor, selection);
+    const scopeEntry = scopeEntryFor(purpose, vendor, selection);
     if (!value || !hasExactlyKeys(value, keys) ||
-        value.version !== (isV4 ? "4" : "2") || value.target !== target || value.purpose !== purpose || value.executable !== executable ||
+        value.version !== (isV5 ? "5" : isV4 ? "4" : "2") || value.target !== target || value.purpose !== purpose || value.executable !== executable ||
         !Array.isArray(value.argv) || !value.argv.every((arg) => typeof arg === "string") || !record(value.agent) ||
         (!isV4 && !record(value.scope)) || (isV4 && !record(value.mcp)) || (isSetupV4 && typeof value.bootstrap_root !== "string") || typeof value.cwd !== "string" || typeof value.artifact_root !== "string" || typeof value.handoff_path !== "string") {
         throw new InteractiveLaunchError("native session launch specification is incompatible");
     }
+    if (componentReceipt) {
+        const planPath = path.join(root, ".warble", "component-plans.json");
+        if (lstatSync(planPath).isSymbolicLink() || !contained(root, realpathSync(planPath)))
+            throw new InteractiveLaunchError("native component plan is outside its scope");
+        readNativeComponentPlans(readFileSync(planPath, "utf8"), value.component_host, componentReceipt);
+    }
     const welcome = welcomePromptFor(purpose);
     const baseArgv = scopeEntry
         ? isV4 ? [welcome] : []
@@ -648,7 +692,7 @@ export function readNativeLaunchSpec(cwd, purpose, vendor, scopeId, binding, mcp
     // "agent" descriptor is a distinct kind (`claude_scope`) carrying the profile id rather than
     // `claude_agent`/`expectedAgent`. See `claudeScopeEntry` above.
     const expectedAgentKind = scopeEntry ? "claude_scope" : vendor === "claude" ? "claude_agent" : "codex_skill";
-    const expectedAgentName = scopeEntry ? NATIVE_DISPATCH_REGISTRY[purpose].profile : expectedAgent;
+    const expectedAgentName = scopeEntry ? (customSelection(purpose, selection)?.id ?? NATIVE_DISPATCH_REGISTRY[purpose].profile) : expectedAgent;
     if (!hasExactlyKeys(agent, ["kind", "name"]) || (!isV4 && !validV2Scope) ||
         JSON.stringify(value.argv) !== JSON.stringify(baseArgv) || agent.kind !== expectedAgentKind || agent.name !== expectedAgentName ||
         (isV4 && (!launchMcp || !hasExactlyKeys(launchMcp, ["server_name", "credential_env_var"]) || launchMcp.server_name !== "genbi_session" || launchMcp.credential_env_var !== NATIVE_MCP_CREDENTIAL_ENV_VAR)))
@@ -703,7 +747,7 @@ export function readNativeLaunchSpec(cwd, purpose, vendor, scopeId, binding, mcp
                 ? [...(scopeEntry ? [] : ["--agent", expectedAgent]), "--resume", providerLaunch.handle, ...(isV4 ? [welcome] : [])]
                 : ["--dangerously-bypass-hook-trust", "-c", 'tui.resume_cwd="current"', "resume", providerLaunch.handle, ...(isV4 ? [welcome] : [])]
             : spawnBaseArgv;
-    return { version: isV4 ? "4" : "2", target, executable, argv, cwd: root, artifact_root: root, handoff_path: handoffPath, ...(bootstrapRoot ? { bootstrap_root: bootstrapRoot } : {}) };
+    return { version: isV5 ? "5" : isV4 ? "4" : "2", target, executable, argv, cwd: root, artifact_root: root, handoff_path: handoffPath, ...(bootstrapRoot ? { bootstrap_root: bootstrapRoot } : {}) };
 }
 /**
  * Materializes only host-owned, short-lived producer inputs. The scope and
@@ -722,6 +766,7 @@ export async function dispatchNativeArtifacts(input) {
     const dir = mkdtempSync(path.join(tempRoot, "genbi-native-dispatch-"));
     const scopePath = path.join(dir, "scope.json");
     const mcpPath = path.join(dir, "mcp.json");
+    const hostPath = path.join(dir, "host.json");
     try {
         const directory = lstatSync(dir);
         if (!directory.isDirectory() || directory.isSymbolicLink() || !contained(tempRoot, dir))
@@ -737,18 +782,20 @@ export async function dispatchNativeArtifacts(input) {
             if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o777) !== 0o600)
                 throw new InteractiveLaunchError("native session materialization failed");
         };
+        if (input.componentHost) {
+            writeFileSync(hostPath, JSON.stringify(input.componentHost), { encoding: "utf8", mode: 0o600, flag: "wx" });
+            validateDescriptorFile(hostPath);
+        }
         validateDescriptorFile(scopePath);
         if (input.mcp)
             validateDescriptorFile(mcpPath);
-        const executable = input.producer?.executable ?? input.warbleBin;
-        if (input.producer)
-            assertNativeProducerIdentity(input.producer);
-        const args = ["dispatch", input.irPath, "--target", input.target, "--purpose", input.purpose, "--native-scope", scopePath, ...(input.mcp ? ["--native-mcp", mcpPath] : []), "--out", input.cwd];
-        await new Promise((resolve, reject) => {
-            const child = spawn(executable, args, { cwd: input.cwd, shell: false, stdio: "ignore" });
-            child.once("error", () => reject(new InteractiveLaunchError("native session materialization failed")));
-            child.once("exit", (code) => code === 0 ? resolve() : reject(new InteractiveLaunchError("native session materialization failed")));
-        });
+        assertNativeProducerIdentity(input.producer);
+        if (input.producer.executable !== input.warbleBin)
+            throw new InteractiveLaunchError("native session materialization failed");
+        const executable = input.producer.executable;
+        const args = ["dispatch", input.irPath, "--target", input.target, "--purpose", input.purpose, "--native-scope", scopePath, ...(input.mcp ? ["--native-mcp", mcpPath] : []), ...(input.componentHost ? ["--native-host", hostPath] : []), "--out", input.cwd];
+        await runNativeDispatchProcess({ executable, args, cwd: input.cwd, env: nativeProcessEnvironment(input.env),
+            ...(input.signal ? { signal: input.signal } : {}) }).catch(() => { throw new InteractiveLaunchError("native session materialization failed"); });
     }
     finally {
         rmSync(dir, { recursive: true, force: true });
@@ -756,7 +803,28 @@ export async function dispatchNativeArtifacts(input) {
 }
 export class NativeSessionService {
     options;
+    runtimeHost;
+    nativeHome;
+    wrenShim;
+    sourceWrenHome;
+    nodeExecutable;
+    producerExecutable;
+    vendorExecutables;
+    childToolDirectories;
+    conversations = new Map();
     sessions = new Map();
+    componentAdmissions = new Map();
+    componentCleanups = new Set();
+    componentCleanupFailed = false;
+    runtimeCleanupFailed = false;
+    pendingTerminalCleanup = new Set();
+    pendingHomeCleanup = new Set();
+    shuttingDown = false;
+    shutdownController = new AbortController();
+    shutdownPromise;
+    pendingCreates = new Set();
+    runtimeSpecs = new Map();
+    codexWrenHomes = new Map();
     leaseTimers = new Map();
     /** Open/reconnect coalescing only lasts while a matching launch is in flight. */
     launches = new Map();
@@ -773,6 +841,41 @@ export class NativeSessionService {
     fixtureMaterializationState;
     constructor(options) {
         this.options = options;
+        if (options.prepareComponents && !options.prepareComponentProbe)
+            throw new Error("Native component execution requires a producer probe");
+        this.runtimeHost = options.runtimeHost ?? new RuntimeHost({
+            // Compatibility default for server-side unit seams only. The real BFF
+            // composes and injects its one policy-owned host in `bin.ts`.
+            selected: "local",
+            deployment: "development",
+            localAvailable: options.terminalHostAvailable ?? (async () => true),
+        });
+        this.nativeHome = realpathSync(options.nativeHome ?? os.homedir());
+        this.wrenShim = options.wrenShim ?? path.join(this.nativeHome, ".local", "bin", "wren");
+        const capturedSourceWrenHome = options.sourceWrenHome
+            ? undefined
+            : process.env["WREN_HOME"]?.trim() || path.join(os.homedir(), ".wren");
+        this.sourceWrenHome = options.sourceWrenHome ?? (() => capturedSourceWrenHome);
+        this.nodeExecutable = options.nodeExecutable ?? attestNativeExecutable("node", process.execPath);
+        const capturedPath = options.pathValue;
+        this.producerExecutable = resolveNativeExecutable("producer", options.warbleBin, capturedPath);
+        const capturedVendors = {
+            ...options.vendorExecutables,
+        };
+        for (const vendor of NATIVE_VENDORS) {
+            if (!capturedVendors[vendor]) {
+                const resolved = resolveNativeExecutable("vendor", vendor, capturedPath)
+                    ?? (this.legacyFixtureMode() ? attestNativeExecutable("vendor", process.execPath) : undefined);
+                if (resolved)
+                    capturedVendors[vendor] = resolved;
+            }
+        }
+        this.vendorExecutables = Object.freeze(capturedVendors);
+        this.childToolDirectories = Object.freeze([...new Set([
+                ...(options.childToolDirectories ?? []),
+                path.dirname(this.nodeExecutable.executable),
+                ...Object.values(capturedVendors).filter((value) => value !== undefined).map((value) => path.dirname(value.executable)),
+            ])]);
         this.idleTtlMs = options.idleTtlMs ?? options.postClaimDetachGraceMs ?? NATIVE_SESSION_IDLE_TTL_MS;
         if (!Number.isSafeInteger(this.idleTtlMs) || this.idleTtlMs <= 0)
             throw new RangeError("native session idle TTL must be a positive integer");
@@ -810,11 +913,27 @@ export class NativeSessionService {
     async productionProducerPreflight() {
         if (this.legacyFixtureMode())
             return undefined;
-        const result = await probeNativeSessionProducer({ warbleBin: this.options.warbleBin, irPaths: this.options.irPaths, ...(this.options.wrenShim !== undefined ? { wrenShim: this.options.wrenShim } : {}) });
+        const result = await probeNativeSessionProducer({
+            warbleBin: this.options.warbleBin,
+            irPaths: this.options.irPaths,
+            ...(this.options.prepareComponents && this.options.prepareComponentProbe ? { prepareComponents: this.options.prepareComponentProbe } : {}),
+            nativeHome: this.nativeHome,
+            nodeExecutable: this.nodeExecutable,
+            childToolDirectories: this.childToolDirectories,
+            ...(this.options.resolveManagedCodexWrenRuntime ? { resolveManagedCodexWrenRuntime: this.options.resolveManagedCodexWrenRuntime } : {}),
+            ...(this.options.pathValue !== undefined ? { pathValue: this.options.pathValue } : {}),
+            wrenShim: this.wrenShim,
+        });
         const log = result.available ? console.info : console.warn;
         log(`[native-sessions] producer preflight ${result.diagnostic}`);
         return result;
     }
+    async assertSelectedRuntimeReady() {
+        const readiness = await this.runtimeHost.probe();
+        if (readiness.selectedReadiness.state !== "ready")
+            throw new InteractiveLaunchError(readiness.selectedReadiness.message);
+        return readiness;
+    }
     /**
      * SQLite is the durable source of truth, but a native PTY and its attach
      * capability are deliberately process-local.  A BFF restart (or a lease
@@ -837,7 +956,7 @@ export class NativeSessionService {
         // yield while the durable row is still being initialized. It has never
         // owned an attachable capability, so treating it as a missing terminal
         // would race creation and could terminalize a PTY that is about to start.
-        if ((row.status !== "running" && row.status !== "detached") || this.sessions.has(row.id))
+        if ((row.status !== "running" && row.status !== "detached") || this.liveCapability(row.id))
             return row;
         // Commit the durable fence first.  The cleanup below is best effort and
         // cannot leave a browser-facing row claiming that it can reattach.
@@ -850,10 +969,13 @@ export class NativeSessionService {
         this.recoveryCapabilities.delete(row.id);
         this.options.artifactService?.revoke(this.artifactCredentials.get(row.id));
         this.artifactCredentials.delete(row.id);
+        this.cleanupRuntime(row.id);
         return stopped;
     }
     /** A legacy persisted Runtime must be repaired before it can authorize a PTY. */
     assertRuntimeDispatchable() {
+        if (this.shuttingDown)
+            throw new InteractiveLaunchError("native session host is shutting down");
         if (!this.options.store.hasExplicitRuntimeSettings())
             return;
         const correction = runtimeSettingsCorrection(this.options.store.getRuntimeSettings());
@@ -877,14 +999,17 @@ export class NativeSessionService {
         if (!dispatch)
             throw new InteractiveLaunchError("native sessions require a saved Runtime & authentication binding");
         const binding = input.purpose === "setup" ? undefined : this.options.getBinding();
-        const reusable = this.list().find((row) => this.matchesOpenScope(row, input.purpose, dispatch.target, runtime.generation, binding));
+        const profileId = requestedProfileId(input.purpose, input.profile);
+        const entryVerb = selectedNativeEntry(input.purpose, dispatch.provider, input.entryVerb);
+        const reusable = this.list().find((row) => this.matchesOpenScope(row, input.purpose, dispatch.target, runtime.generation, binding, profileId) && selectedNativeEntry(row.purpose, row.vendor, row.entryVerb) === entryVerb);
         if (reusable) {
             const recoveryCapability = this.recoveryCapabilities.get(reusable.id);
-            return { row: reusable, capability: this.sessions.get(reusable.id).capability, ...(recoveryCapability ? { recoveryCapability } : {}) };
+            return { row: reusable, capability: this.liveCapability(reusable.id), ...(recoveryCapability ? { recoveryCapability } : {}) };
         }
+        const selectedEntry = selectedNativeEntry(input.purpose, dispatch.provider, input.entryVerb);
         const scopeKey = input.purpose === "setup"
             ? JSON.stringify([input.purpose, dispatch.target, runtime.generation, "bootstrap"])
-            : JSON.stringify([input.purpose, dispatch.target, runtime.generation, binding?.identity ?? "unbound", binding?.generation ?? null, binding?.revision ?? null]);
+            : JSON.stringify([input.purpose, dispatch.target, runtime.generation, binding?.identity ?? "unbound", binding?.generation ?? null, binding?.revision ?? null, selectedEntry, profileId]);
         return this.singleFlight(`open:${scopeKey}`, scopeKey, input, binding, runtime);
     }
     /** Opens the exact row selected by the browser after revalidating its scope. */
@@ -902,7 +1027,7 @@ export class NativeSessionService {
         if (!row || !this.matchesOpenScope(row, input.purpose, dispatch.target, runtime.generation, binding))
             throw new InteractiveLaunchError("native session is unavailable");
         const recoveryCapability = this.recoveryCapabilities.get(row.id);
-        return { row, capability: this.sessions.get(row.id).capability, ...(recoveryCapability ? { recoveryCapability } : {}) };
+        return { row, capability: this.liveCapability(row.id), ...(recoveryCapability ? { recoveryCapability } : {}) };
     }
     /**
      * Starts a separate TUI even when a matching session is live.  The caller's
@@ -920,9 +1045,11 @@ export class NativeSessionService {
         if (!dispatch)
             throw new InteractiveLaunchError("native sessions require a saved Runtime & authentication binding");
         const binding = input.purpose === "setup" ? undefined : this.options.getBinding();
+        const profileId = requestedProfileId(input.purpose, input.profile);
+        const selectedEntry = selectedNativeEntry(input.purpose, dispatch.provider, input.entryVerb);
         const scopeKey = input.purpose === "setup"
             ? JSON.stringify([input.purpose, dispatch.target, runtime.generation, "bootstrap"])
-            : JSON.stringify([input.purpose, dispatch.target, runtime.generation, binding?.identity ?? "unbound", binding?.generation ?? null, binding?.revision ?? null]);
+            : JSON.stringify([input.purpose, dispatch.target, runtime.generation, binding?.identity ?? "unbound", binding?.generation ?? null, binding?.revision ?? null, selectedEntry, profileId]);
         return this.replayStartSeparate(`start:${input.idempotencyKey}`, scopeKey, input, binding, runtime);
     }
     /**
@@ -961,6 +1088,8 @@ export class NativeSessionService {
     }
     /** Browser-visible resume state uses the same current-scope fence as launch, plus *why* when it fails. */
     resumeAvailability(row) {
+        if (row.transport === "conversation" || (row.vendor === "codex" && this.options.directCodex?.terminal))
+            return { available: false, cause: "no_resume_handle" };
         if (row.status !== "exited" && row.status !== "stopped" && row.status !== "interrupted" && row.status !== "failed" && row.status !== "stale") {
             return { available: false, cause: "not_terminal" };
         }
@@ -987,7 +1116,7 @@ export class NativeSessionService {
      * no global Codex state and persists only a provider-bound encrypted envelope.
      */
     captureCodexResumeHandle(row) {
-        if (row.vendor !== "codex" || this.options.store.hasAvailableNativeSessionResume(row.id, "codex"))
+        if (row.vendor !== "codex" || this.options.directCodex?.terminal || this.options.store.hasAvailableNativeSessionResume(row.id, "codex"))
             return;
         const state = this.materializationState();
         if (!state)
@@ -1016,7 +1145,12 @@ export class NativeSessionService {
         const runtime = !storedRuntime.configured && this.legacyFixtureMode()
             ? { configured: true, generation: 0, provider: row.vendor, target: targetForProvider(row.vendor), targetLabel: nativeTargetLabel(row.vendor) }
             : storedRuntime;
-        const dispatch = dispatchForPurpose(row.purpose, runtime);
+        const registryDispatch = dispatchForPurpose(row.purpose, runtime);
+        // An analysis row resumes inside the profile it ran in; whether that profile is still admitted is
+        // the launch's question (it resolves the id again), not this scope fence's.
+        const dispatch = registryDispatch && row.purpose === "analysis" && row.dispatchProfile !== null
+            ? { ...registryDispatch, profile: row.dispatchProfile }
+            : registryDispatch;
         const binding = row.purpose === "setup" ? undefined : this.options.getBinding();
         const matches = dispatch?.provider === row.vendor && row.dispatchProfile === dispatch.profile && row.dispatchTarget === dispatch.target && row.runtimeGeneration === runtime.generation
             && (row.purpose === "setup"
@@ -1059,7 +1193,7 @@ export class NativeSessionService {
         const reserved = this.options.store.reserveNativeSessionResume({
             sourceSessionId: source.id, idempotencyKey, scopeFingerprint: fingerprint, sealedHandle: sealedChild,
             child: {
-                id: childId, purpose: source.purpose, vendor: source.vendor, agent: agentFor(source.purpose, source.vendor), scopeKind: source.scopeKind, scopeId: childScopeId,
+                id: childId, purpose: source.purpose, vendor: source.vendor, agent: source.agent, entryVerb: selectedNativeEntry(source.purpose, source.vendor, source.entryVerb), scopeKind: source.scopeKind, scopeId: childScopeId,
                 dispatchProfile: scope.dispatch.profile, dispatchTarget: scope.dispatch.target, runtimeGeneration: scope.runtime.generation,
                 ...(scope.binding ? { projectIdentity: scope.binding.identity, bindingGeneration: scope.binding.generation, projectRevision: scope.binding.revision } : {}),
             },
@@ -1068,7 +1202,7 @@ export class NativeSessionService {
             throw new InteractiveLaunchError("native session resume is unavailable");
         if (!reserved.created)
             return this.recoverReservedResume(reserved.row.id, scope);
-        return this.create({ purpose: source.purpose, ...(this.legacyFixtureMode() ? { vendor: source.vendor } : {}) }, scope.binding, scope.runtime, { row: reserved.row, handle });
+        return this.create({ purpose: source.purpose, entryVerb: selectedNativeEntry(source.purpose, source.vendor, source.entryVerb), ...(source.purpose === "analysis" && source.dispatchProfile !== null ? { profile: source.dispatchProfile } : {}), ...(this.legacyFixtureMode() ? { vendor: source.vendor } : {}) }, scope.binding, scope.runtime, { row: reserved.row, handle });
     }
     async recoverReservedResume(id, scope) {
         const row = this.get(id);
@@ -1096,7 +1230,7 @@ export class NativeSessionService {
             this.failReservedResume(row.id, "native session resume reservation cannot be recovered");
             throw error;
         }
-        return this.create({ purpose: row.purpose, ...(this.legacyFixtureMode() ? { vendor: row.vendor } : {}) }, scope.binding, scope.runtime, { row, handle });
+        return this.create({ purpose: row.purpose, entryVerb: selectedNativeEntry(row.purpose, row.vendor, row.entryVerb), ...(row.purpose === "analysis" && row.dispatchProfile !== null ? { profile: row.dispatchProfile } : {}), ...(this.legacyFixtureMode() ? { vendor: row.vendor } : {}) }, scope.binding, scope.runtime, { row, handle });
     }
     failReservedResume(id, failure) {
         const row = this.options.store.getNativeSession(id);
@@ -1104,8 +1238,11 @@ export class NativeSessionService {
             this.options.store.transitionNativeSession(id, "failed", { failure, ended: true });
         this.options.store.invalidateNativeSessionResume(id);
     }
-    matchesOpenScope(row, purpose, target, generation, binding) {
-        if (row.purpose !== purpose || row.dispatchTarget !== target || row.runtimeGeneration !== generation || !this.sessions.has(row.id))
+    matchesOpenScope(row, purpose, target, generation, binding, profileId) {
+        if (row.purpose !== purpose || row.dispatchTarget !== target || row.runtimeGeneration !== generation || !this.liveCapability(row.id))
+            return false;
+        // A live session inside another conversation profile is not this one, however its scope matches.
+        if (profileId !== undefined && (row.dispatchProfile ?? NATIVE_DISPATCH_REGISTRY[purpose].profile) !== profileId)
             return false;
         if (row.status !== "creating" && row.status !== "running" && row.status !== "detached")
             return false;
@@ -1141,7 +1278,7 @@ export class NativeSessionService {
         // A successful response may contain an attach capability. Never replay it
         // after the owning PTY/capability has gone away; failures carry no terminal
         // capability and remain safely replayable within the same fenced scope.
-        return !replay.result?.capability || this.sessions.get(replay.result.row.id)?.capability === replay.result.capability;
+        return !replay.result?.capability || this.liveCapability(replay.result.row.id) === replay.result.capability;
     }
     trimStartSeparateReplays() {
         for (const [key, replay] of this.startSeparateReplays) {
@@ -1177,12 +1314,110 @@ export class NativeSessionService {
                 this.launches.delete(launchKey);
         }
     }
+    /**
+     * Resolves the profile a launch runs inside. The default needs no registry; any other id is
+     * Claude-only (the Codex entry is a purpose skill with no scope form), accepts no entry verb
+     * (its entry form was decided at admission), and must still be admitted right now.
+     */
+    async selectProfile(purpose, profile, provider, entryVerb, resumedRow) {
+        const id = requestedProfileId(purpose, profile);
+        if (resumedRow && (resumedRow.dispatchProfile ?? NATIVE_DISPATCH_REGISTRY[purpose].profile) !== id)
+            throw new InteractiveLaunchError("native session profile changed during resume");
+        // A system purpose always runs its registry profile; the analysis default needs no registry either.
+        if (purpose !== "analysis")
+            return { id, entry: { kind: "scope" } };
+        if (id === DEFAULT_CONVERSATION_PROFILE)
+            return DEFAULT_PROFILE_SELECTION;
+        if (provider !== "claude")
+            throw new InteractiveLaunchError(CODEX_CUSTOM_PROFILE_UNAVAILABLE);
+        // An entry verb beside a selected profile was already refused by `selectedNativeEntry`: Claude
+        // never takes one, and the Codex vendor was refused just above. Nothing to re-check here.
+        void entryVerb;
+        if (!this.options.resolveConversationProfile)
+            throw new InteractiveLaunchError("conversation profile selection is not configured");
+        try {
+            const resolved = await this.options.resolveConversationProfile(id);
+            if (resolved.id !== id)
+                throw new InteractiveLaunchError("conversation profile resolution is inconsistent");
+            return resolved;
+        }
+        catch (error) {
+            if (error instanceof InteractiveLaunchError)
+                throw error;
+            throw new InteractiveLaunchError(error instanceof Error ? error.message : "conversation profile is unavailable");
+        }
+    }
+    /** Analysis readiness, narrowed per conversation profile by the registry's verdict and the vendor. */
+    async conversationProfileReadiness(analysis, provider) {
+        if (!this.options.listConversationProfiles)
+            return undefined;
+        let summaries;
+        try {
+            summaries = await this.options.listConversationProfiles();
+        }
+        catch {
+            return undefined;
+        }
+        const result = {};
+        for (const summary of summaries) {
+            const custom = summary.id !== DEFAULT_CONVERSATION_PROFILE;
+            // A profile the registry refused is refused for good; say that before any runtime reason,
+            // which may come and go, so a picker can tell the two apart.
+            const reason = (!summary.selectable ? summary.reason ?? "this profile is unavailable" : undefined)
+                ?? analysis.reason
+                ?? (custom && provider !== undefined && provider !== "claude" ? CODEX_CUSTOM_PROFILE_UNAVAILABLE : undefined);
+            result[summary.id] = {
+                id: summary.id,
+                scopeKind: "bound_project",
+                profile: summary.id,
+                ...(analysis.target !== undefined ? { target: analysis.target } : {}),
+                ...(analysis.targetLabel !== undefined ? { targetLabel: analysis.targetLabel } : {}),
+                available: analysis.available && reason === undefined,
+                ...(reason !== undefined ? { reason } : {}),
+                ...(custom
+                    ? { ...(summary.entryKind !== undefined ? { entryKind: summary.entryKind } : {}), ...(summary.entryVerb !== undefined ? { entryVerb: summary.entryVerb } : {}) }
+                    : { entryKind: provider === "codex" ? "agent" : "scope" }),
+            };
+        }
+        return result;
+    }
     async readiness() {
         const terminalHostAvailable = this.options.terminalHostAvailable ?? (async () => true);
         const executableAvailable = (vendor) => this.options.executableAvailable
-            ? this.options.executableAvailable(vendor)
-            : interactiveExecutableAvailable(vendor);
+            ? this.options.executableAvailable(vendor) && this.vendorExecutables[vendor] !== undefined
+            : this.vendorExecutables[vendor] !== undefined;
+        const runtimeHostReadiness = await this.runtimeHost.probe();
+        if (runtimeHostReadiness.selected === "codex-app-server") {
+            const runtime = this.options.store.getNativeRuntimeBinding();
+            const binding = this.options.getBinding();
+            const reason = runtimeHostReadiness.selectedReadiness.state !== "ready" ? runtimeHostReadiness.selectedReadiness.message
+                : this.options.store.hasExplicitRuntimeSettings() && runtimeSettingsCorrection(this.options.store.getRuntimeSettings()) ? runtimeSettingsCorrection(this.options.store.getRuntimeSettings())
+                    : !this.options.directCodex ? "Direct Codex preparation is unavailable."
+                        : !runtime.configured || runtime.provider !== "codex" ? "Select a Codex Runtime binding."
+                            : !binding ? "Bind a project before starting a conversation."
+                                : this.options.directCodex.terminal && !this.options.directCodex.terminalCertified?.("answer_query") ? "Native terminal version is not certified."
+                                    : this.options.directCodex.terminal && !(await terminalHostAvailable()) ? "Native terminal host is unavailable." : undefined;
+            const purposes = Object.fromEntries(NATIVE_PURPOSES.map((purpose) => {
+                const unavailable = reason ?? (purpose !== "analysis" ? "This purpose is not supported by direct Codex sessions." : undefined);
+                return [purpose, { scopeKind: NATIVE_DISPATCH_REGISTRY[purpose].scopeKind, profile: NATIVE_DISPATCH_REGISTRY[purpose].profile,
+                        target: "codex:interactive", targetLabel: "Codex CLI", available: !unavailable, ...(unavailable ? { reason: unavailable } : {}),
+                        vendors: { codex: { available: !unavailable }, claude: { available: false } } }];
+            }));
+            const profiles = await this.conversationProfileReadiness(purposes.analysis, "codex");
+            return { runtime, runtimeHost: runtimeHostReadiness, purposes, ...(profiles ? { profiles } : {}), ...purposes, mcp: { server: "GenBI MCP", tool: "save_dashboard", destination: "GenBI Artifacts", available: false, reason: "Direct conversations use host-owned tools." } };
+        }
         const hostAvailable = await terminalHostAvailable();
+        const selectedRuntimeUnavailable = runtimeHostReadiness.selectedReadiness.state === "ready"
+            ? undefined
+            : runtimeHostReadiness.selectedReadiness.message;
+        const codexBackendReadiness = runtimeHostReadiness.backends["codex-app-server"];
+        const codexWrenRuntimeUnavailable = this.legacyFixtureMode()
+            ? undefined
+            : this.options.resolveManagedCodexWrenRuntime === undefined
+                ? CODEX_WREN_RUNTIME_UNPROVISIONED.message
+                : codexBackendReadiness.state === "ready"
+                    ? undefined
+                    : codexBackendReadiness.message;
         const mcpReadiness = this.options.artifactService?.readiness();
         const runtime = this.options.store.getNativeRuntimeBinding();
         const runtimeCorrection = this.options.store.hasExplicitRuntimeSettings()
@@ -1190,7 +1425,7 @@ export class NativeSessionService {
             : undefined;
         const legacyFixture = !runtime.configured && this.legacyFixtureMode();
         const producer = this.legacyFixtureMode() ? undefined : await this.productionProducerPreflight();
-        const legacyProducerAvailable = this.options.producerAvailable ?? (() => this.options.dispatch !== undefined || localExecutableAvailable(this.options.warbleBin));
+        const legacyProducerAvailable = this.options.producerAvailable ?? (() => this.options.dispatch !== undefined || this.producerExecutable !== undefined);
         const result = {};
         for (const purpose of NATIVE_PURPOSES) {
             const definition = NATIVE_DISPATCH_REGISTRY[purpose];
@@ -1210,21 +1445,22 @@ export class NativeSessionService {
             // Only the configured vendor's own probe may block this purpose. Probing
             // both and collapsing them into one boolean let an unselected vendor veto
             // the selected one.
-            const selectedProducer = producer && dispatch ? producer.vendors[dispatch.provider] : undefined;
-            const reason = runtimeCorrection
-                ?? (!dispatch && !legacyFixture
-                    ? "native sessions require a saved Runtime & authentication binding"
-                    : !cwd
-                        ? purpose === "setup" ? "native setup sessions require a workspace root" : "native sessions require a current bound project"
-                        : workspaceUnavailable
-                            ? "native session workspace is unavailable"
-                            : selectedProducer && !selectedProducer.available
-                                ? selectedProducer.reason ?? "native session producer is incompatible"
-                                : !irPath || !(this.options.dispatch !== undefined || configuredIrPath(irPath)) || !legacyProducerAvailable()
-                                    ? "native session materialization prerequisites are unavailable"
-                                    : mcpReadiness && !mcpReadiness.available
-                                        ? mcpReadiness.reason
-                                        : undefined);
+            const selectedProducer = producer && dispatch ? (producer.purposes?.[purpose][dispatch.provider] ?? producer.vendors[dispatch.provider]) : undefined;
+            const sharedReason = !dispatch && !legacyFixture
+                ? "native sessions require a saved Runtime & authentication binding"
+                : !cwd
+                    ? purpose === "setup" ? "native setup sessions require a workspace root" : "native sessions require a current bound project"
+                    : workspaceUnavailable
+                        ? "native session workspace is unavailable"
+                        : selectedProducer && !selectedProducer.available
+                            ? selectedProducer.reason ?? "native session producer is incompatible"
+                            : !irPath || !(this.options.dispatch !== undefined || configuredIrPath(irPath)) || !legacyProducerAvailable()
+                                ? "native session materialization prerequisites are unavailable"
+                                : mcpReadiness && !mcpReadiness.available
+                                    ? mcpReadiness.reason
+                                    : undefined;
+            const vendorRuntimeUnavailable = dispatch?.provider === "codex" ? codexWrenRuntimeUnavailable : undefined;
+            const reason = runtimeCorrection ?? selectedRuntimeUnavailable ?? vendorRuntimeUnavailable ?? sharedReason;
             const executable = dispatch?.provider === "claude" ? "claude" : "codex";
             const unavailable = reason ?? (!hostAvailable
                 ? "native terminal host cannot spawn local processes on this machine"
@@ -1236,12 +1472,14 @@ export class NativeSessionService {
             // one is unusable and why instead of only that "the producer" is.
             if (!legacyFixture && producer)
                 for (const vendor of NATIVE_VENDORS) {
-                    const probe = producer.vendors[vendor];
-                    vendorReadiness[vendor] = probe?.available === false
-                        ? { available: false, reason: probe.reason ?? "native session producer is incompatible" }
-                        : !executableAvailable(vendor)
-                            ? { available: false, reason: `the ${vendor === "claude" ? "claude" : "codex"} interactive CLI is not available on this machine` }
-                            : { available: true };
+                    const probe = producer.purposes?.[purpose][vendor] ?? producer.vendors[vendor];
+                    vendorReadiness[vendor] = vendor === "codex" && codexWrenRuntimeUnavailable
+                        ? { available: false, reason: codexWrenRuntimeUnavailable }
+                        : probe?.available === false
+                            ? { available: false, reason: probe.reason ?? "native session producer is incompatible" }
+                            : !executableAvailable(vendor)
+                                ? { available: false, reason: `the ${vendor === "claude" ? "claude" : "codex"} interactive CLI is not available on this machine` }
+                                : { available: true };
                 }
             if (legacyFixture)
                 for (const vendor of NATIVE_VENDORS) {
@@ -1279,9 +1517,12 @@ export class NativeSessionService {
             }));
             return legacy;
         }
+        const profiles = await this.conversationProfileReadiness(result.analysis, runtime.configured ? runtime.provider : undefined);
         return {
             runtime,
+            runtimeHost: runtimeHostReadiness,
             purposes: result,
+            ...(profiles ? { profiles } : {}),
             mcp: this.options.artifactService?.health() ?? {
                 server: "GenBI MCP",
                 tool: "save_dashboard",
@@ -1294,27 +1535,74 @@ export class NativeSessionService {
     }
     async create(input, binding = input.purpose === "setup" ? undefined : this.options.getBinding(), capturedRuntime = this.options.store.getNativeRuntimeBinding(), resumed) {
         this.assertRuntimeDispatchable();
+        const pending = this.createCaptured(input, binding, capturedRuntime, resumed);
+        this.pendingCreates.add(pending);
+        void pending.finally(() => this.pendingCreates.delete(pending)).catch(() => { });
+        return pending;
+    }
+    async createCaptured(input, binding = input.purpose === "setup" ? undefined : this.options.getBinding(), capturedRuntime = this.options.store.getNativeRuntimeBinding(), resumed) {
+        this.assertRuntimeDispatchable();
+        const runtimeReadiness = await this.assertSelectedRuntimeReady();
         const purpose = input.purpose;
         const legacyRuntime = !capturedRuntime.configured && input.vendor
             ? { configured: true, generation: 0, provider: input.vendor, target: targetForProvider(input.vendor), targetLabel: nativeTargetLabel(input.vendor) }
             : capturedRuntime;
-        const dispatchDefinition = dispatchForPurpose(purpose, legacyRuntime);
-        if (!dispatchDefinition)
+        const registryDispatch = dispatchForPurpose(purpose, legacyRuntime);
+        if (!registryDispatch)
             throw new InteractiveLaunchError("native sessions require a saved Runtime & authentication binding");
+        const entryVerb = selectedNativeEntry(purpose, registryDispatch.provider, input.entryVerb);
+        if (resumed && selectedNativeEntry(purpose, registryDispatch.provider, resumed.row.entryVerb) !== entryVerb)
+            throw new InteractiveLaunchError("native session entry changed during resume");
+        const selection = await this.selectProfile(purpose, input.profile, registryDispatch.provider, input.entryVerb, resumed?.row);
+        // The launch tuple names the selected profile; everything else is the registry's for the purpose.
+        const dispatchDefinition = { ...registryDispatch, profile: selection.id };
+        if (runtimeReadiness.selected === "codex-app-server") {
+            if (dispatchDefinition.provider !== "codex" || purpose !== "analysis" || !binding || resumed || !this.options.directCodex || customSelection(purpose, selection)) {
+                throw new InteractiveLaunchError("direct Codex session preparation is unavailable");
+            }
+            return this.createDirectCodex(binding, legacyRuntime, entryVerb);
+        }
+        if (runtimeReadiness.selected !== "local")
+            throw new InteractiveLaunchError("native session backend is unavailable");
+        let managedCodexWrenRuntime;
+        if (dispatchDefinition.provider === "codex" && !this.legacyFixtureMode()) {
+            const codexReadiness = runtimeReadiness.backends["codex-app-server"];
+            if (codexReadiness.state !== "ready")
+                throw new InteractiveLaunchError(codexReadiness.message);
+            if (!this.options.resolveManagedCodexWrenRuntime)
+                throw new InteractiveLaunchError(CODEX_WREN_RUNTIME_UNPROVISIONED.message);
+            try {
+                managedCodexWrenRuntime = this.options.resolveManagedCodexWrenRuntime();
+            }
+            catch {
+                throw new InteractiveLaunchError(CODEX_WREN_RUNTIME_UNPROVISIONED.message);
+            }
+        }
         if (purpose !== "setup" && !binding)
             throw new InteractiveLaunchError("native session requires a current bound project");
         const configuredCwd = binding?.path ?? this.options.workspaceRoot;
         const configuredIr = this.options.irPaths[purpose];
         if (!configuredCwd || !configuredIr)
-            throw new InteractiveLaunchError(`native ${dispatchDefinition.profile} session is not configured`);
+            throw new InteractiveLaunchError(`native ${selection.id} session is not configured`);
         // Compile for this binding rather than dispatching the profile's golden.
         // Falls back to the configured path only where no resolver is wired (the
         // fixture-mode tests), never silently in production — see `bin.ts`.
-        const irPath = this.options.resolveDispatchIr === undefined
-            ? configuredIr
-            : await this.options.resolveDispatchIr(purpose, binding);
+        // Compiling for this binding runs before the launch try/catch below, so a
+        // failure here reached the HTTP route unlogged and unclassified — the case
+        // where the server printed nothing at all and the browser said only "native
+        // session launch failed".
+        let irPath;
+        try {
+            irPath = this.options.resolveDispatchIr === undefined
+                ? configuredIr
+                : await this.options.resolveDispatchIr(purpose, binding, selection.sourceDir);
+        }
+        catch (error) {
+            logNativeLaunchFailure(purpose, dispatchDefinition.provider, "dispatch_ir", error);
+            throw error;
+        }
         const producer = this.legacyFixtureMode() ? undefined : await this.productionProducerPreflight();
-        const launchProducer = producer ? producer.vendors[dispatchDefinition.provider] : undefined;
+        const launchProducer = producer ? (producer.purposes?.[purpose][dispatchDefinition.provider] ?? producer.vendors[dispatchDefinition.provider]) : undefined;
         if (producer && (!launchProducer?.available || !producer.producer)) {
             throw new InteractiveLaunchError(launchProducer?.reason ?? "native session producer is incompatible");
         }
@@ -1334,7 +1622,8 @@ export class NativeSessionService {
             initialSealedHandle = sealNativeClaudeResumeHandle(state, id, sessionId);
             providerLaunch = { kind: "initial", sessionId };
         }
-        const row = resumed?.row ?? this.options.store.createNativeSession({ id, purpose, vendor: dispatchDefinition.provider, agent: agentFor(purpose, dispatchDefinition.provider), scopeKind: dispatchDefinition.scopeKind, scopeId,
+        this.assertRuntimeDispatchable();
+        const row = resumed?.row ?? this.options.store.createNativeSession({ id, purpose, vendor: dispatchDefinition.provider, agent: expectedAgentFor(purpose, dispatchDefinition.provider, selection), entryVerb, scopeKind: dispatchDefinition.scopeKind, scopeId,
             dispatchProfile: dispatchDefinition.profile, dispatchTarget: dispatchDefinition.target, runtimeGeneration: legacyRuntime.generation,
             ...(binding ? { projectIdentity: binding.identity, bindingGeneration: binding.generation, projectRevision: binding.revision } : {}) });
         if (initialSealedHandle)
@@ -1360,7 +1649,7 @@ export class NativeSessionService {
             if (!authorizedWorkspace || !materializationState)
                 throw new InteractiveLaunchError("native session workspace is unavailable");
             const cwd = createNativeSessionWorkspace(materializationState, authorizedWorkspace, id);
-            const producerAvailable = this.options.producerAvailable ?? (() => this.options.dispatch !== undefined || localExecutableAvailable(this.options.warbleBin));
+            const producerAvailable = this.options.producerAvailable ?? (() => this.options.dispatch !== undefined || this.producerExecutable !== undefined);
             if (!(this.options.dispatch !== undefined || configuredIrPath(irPath)) || !producerAvailable())
                 throw new InteractiveLaunchError("native session materialization prerequisites are unavailable");
             const mcpReadiness = artifactService?.readiness();
@@ -1370,19 +1659,58 @@ export class NativeSessionService {
             if (mcp)
                 this.artifactCredentials.set(id, mcp.credential);
             let wrenRuntime;
-            try {
-                wrenRuntime = dispatchDefinition.provider === "codex" && !this.legacyFixtureMode() ? resolveNativeWrenRuntime(this.options.wrenShim) : undefined;
-            }
-            catch (error) {
-                if (error instanceof NativeWrenRuntimeError)
-                    throw new InteractiveLaunchError("native Wren runtime is unavailable");
-                throw error;
+            wrenRuntime = managedCodexWrenRuntime;
+            const vendorExecutable = this.vendorExecutables[dispatchDefinition.provider];
+            if (!vendorExecutable)
+                throw new InteractiveLaunchError(`the ${dispatchDefinition.provider} interactive CLI is not available on this machine`);
+            const producerExecutable = producer?.producer
+                ? attestNativeExecutable("producer", producer.producer.executable)
+                : this.options.dispatch !== undefined
+                    ? attestNativeExecutable("producer", this.nodeExecutable.executable)
+                    : resolveNativeExecutable("producer", this.options.warbleBin, undefined);
+            if (!producerExecutable)
+                throw new InteractiveLaunchError("native session materialization prerequisites are unavailable");
+            const toolDirectories = [...new Set([
+                    ...this.childToolDirectories,
+                    path.dirname(producerExecutable.executable),
+                    ...(wrenRuntime ? [path.join(wrenRuntime.tool_root, "bin"), path.dirname(wrenRuntime.interpreter)] : []),
+                ])];
+            const dispatchEnvironment = buildNativeChildEnvironment({
+                toolDirectories,
+                home: this.nativeHome,
+                ...(binding ? { projectPath: binding.path } : {}),
+                ...(mcp ? { mcpCredential: mcp.credential } : {}),
+                ...(purpose === "setup" ? { setupBootstrapRoot: authorizedWorkspace } : {}),
+            });
+            const scope = { version: "3", kind: row.scopeKind, scope_id: scopeId, cwd, entry: entryFor(purpose, dispatchDefinition.provider, entryVerb, selection), ...(purpose === "setup" ? { bootstrap_root: authorizedWorkspace } : {}), ...(wrenRuntime ? { wren_runtime: wrenRuntime } : {}), ...(binding ? { binding: { project_identity: binding.identity, generation: String(binding.generation), revision: binding.revision } } : {}) };
+            const componentIr = this.options.prepareComponents && binding && purpose === "analysis" ? readFileSync(irPath, "utf8") : undefined;
+            const preparedComponents = componentIr && binding ? await this.options.prepareComponents({ session: row, binding, irDocument: componentIr, scope }) : undefined;
+            if (preparedComponents) {
+                const identity = preparedComponents.identity;
+                if (!mcp || identity.session_id !== id || identity.vendor !== row.vendor || identity.runtime_generation !== String(row.runtimeGeneration)
+                    || identity.binding.project_identity !== binding?.identity || identity.binding.generation !== String(binding?.generation) || identity.binding.revision !== binding?.revision)
+                    throw new InteractiveLaunchError("native component execution identity is incompatible");
             }
-            const scope = { version: "3", kind: row.scopeKind, scope_id: scopeId, cwd, entry: nativeEntryFor(purpose, dispatchDefinition.provider), ...(purpose === "setup" ? { bootstrap_root: authorizedWorkspace } : {}), ...(wrenRuntime ? { wren_runtime: wrenRuntime } : {}), ...(binding ? { binding: { project_identity: binding.identity, generation: String(binding.generation), revision: binding.revision } } : {}) };
+            const componentReceipt = preparedComponents && componentIr ? {
+                identity: structuredClone(preparedComponents.identity), irDocument: componentIr, scopeDocument: JSON.stringify(scope),
+                hostRoots: structuredClone(preparedComponents.hostRoots), contexts: structuredClone(preparedComponents.contexts),
+            } : undefined;
             const dispatch = this.options.dispatch ?? dispatchNativeArtifacts;
             validateNativeSessionWorkspace(materializationState, authorizedWorkspace, cwd);
             launchPhase = "dispatch";
-            await dispatch({ warbleBin: producer?.producer?.executable ?? this.options.warbleBin, ...(producer?.producer ? { producer: producer.producer } : {}), irPath, target: dispatchDefinition.target, cwd, purpose, scope, ...(mcp ? { mcp } : {}) });
+            await dispatch({
+                warbleBin: producerExecutable.executable,
+                producer: producer?.producer ?? { executable: producerExecutable.executable, identity: producerExecutable.digest },
+                irPath,
+                target: dispatchDefinition.target,
+                cwd,
+                purpose,
+                scope,
+                ...(preparedComponents ? { componentHost: nativeComponentHostContract(preparedComponents) } : {}),
+                ...(mcp ? { mcp } : {}),
+                env: dispatchEnvironment,
+                signal: this.shutdownController.signal,
+            });
             if (!input.vendor && !sameNativeRuntimeBinding(capturedRuntime, this.options.store.getNativeRuntimeBinding())) {
                 this.options.store.transitionNativeSession(id, "stale", { failure: "native runtime binding changed before launch", ended: true });
                 throw new InteractiveLaunchError("native session is stale because the runtime binding changed");
@@ -1392,20 +1720,75 @@ export class NativeSessionService {
                 throw new InteractiveLaunchError("native session is stale because the bound project changed");
             }
             launchPhase = "launch_spec";
-            const spec = readNativeLaunchSpec(cwd, purpose, dispatchDefinition.provider, scopeId, binding, mcp, materializationState, authorizedWorkspace, providerLaunch);
+            const launchSpec = readNativeLaunchSpec(cwd, purpose, dispatchDefinition.provider, scopeId, binding, mcp, materializationState, authorizedWorkspace, providerLaunch, componentReceipt, selection);
+            if (componentReceipt && preparedComponents) {
+                const launch = JSON.parse(readFileSync(path.join(cwd, ".warble", "interactive-launch.json"), "utf8"));
+                const plans = readNativeComponentPlans(readFileSync(path.join(cwd, ".warble", "component-plans.json"), "utf8"), launch.component_host, componentReceipt);
+                const current = () => {
+                    const live = this.options.store.getNativeSession(id);
+                    if (!live || !["creating", "running", "detached"].includes(live.status) || !sameBinding(binding, this.options.getBinding())
+                        || (!input.vendor && !sameNativeRuntimeBinding(capturedRuntime, this.options.store.getNativeRuntimeBinding())))
+                        return undefined;
+                    try {
+                        preparedComponents.assertCurrent();
+                    }
+                    catch {
+                        return undefined;
+                    }
+                    return componentReceipt.identity;
+                };
+                this.assertRuntimeDispatchable();
+                this.componentAdmissions.set(id, new NativeComponentAdmission(plans, current, (root, plan, signal) => preparedComponents.host(root, plan, signal)));
+            }
             let codexWrenHome;
-            if (spec.version === "4" && dispatchDefinition.provider === "codex" && binding) {
-                if (wrenRuntime) {
+            // Hosted v5 entries route work through fixed MCP roots. Their outer Codex
+            // session retains the producer's read-only, network-disabled profile; only
+            // the direct v4 route receives a Wren home and bound-project read grant.
+            if (launchSpec.version === "4" && dispatchDefinition.provider === "codex") {
+                if (wrenRuntime && binding) {
                     launchPhase = "codex_wren_home";
-                    codexWrenHome = (this.options.prepareCodexWrenHome ?? ((input) => materializeCodexWrenHome(input.runtime, input.projectPath, input.cwd)))({
+                    codexWrenHome = (this.options.prepareCodexWrenHome ?? materializeCodexWrenHome)({
                         runtime: wrenRuntime,
                         projectPath: binding.path,
                         cwd,
+                        sourceWrenHome: this.sourceWrenHome(),
+                        home: this.nativeHome,
+                        toolDirectories,
                     });
                 }
-                launchPhase = "codex_project_read";
-                grantCodexBoundProjectRead(cwd, binding.path, codexWrenHome?.dataRoots);
+                else if (wrenRuntime && purpose === "setup") {
+                    launchPhase = "codex_wren_home";
+                    codexWrenHome = createEmptyCodexWrenHome(cwd);
+                }
+                if (binding) {
+                    launchPhase = "codex_project_read";
+                    grantCodexBoundProjectRead(cwd, binding.path, codexWrenHome?.dataRoots);
+                }
+            }
+            codexWrenHome?.assertActive?.();
+            if (codexWrenHome)
+                this.codexWrenHomes.set(id, codexWrenHome);
+            const executableIdentities = [this.nodeExecutable, producerExecutable, vendorExecutable];
+            if (wrenRuntime) {
+                executableIdentities.push(attestNativeExecutable("wren", wrenRuntime.launcher), attestNativeExecutable("python", wrenRuntime.interpreter));
             }
+            // Legacy Claude tools use the same server-selected profile store as Setup.
+            // Hosted v5 entries receive only their broker and must not inherit this store.
+            const claudeWrenHome = launchSpec.version === "4" && dispatchDefinition.provider === "claude"
+                && binding && this.options.sourceWrenHome ? this.sourceWrenHome() : undefined;
+            const runtimeSpec = buildNativeRuntimeSpec({
+                backend: runtimeReadiness.selected,
+                vendor: dispatchDefinition.provider,
+                executables: executableIdentities,
+                toolDirectories,
+                workspace: cwd,
+                home: this.nativeHome,
+                ...(binding ? { binding } : {}),
+                ...(codexWrenHome ? { sessionWrenHome: codexWrenHome.home } : claudeWrenHome ? { sessionWrenHome: claudeWrenHome } : {}),
+                ...(dispatchDefinition.provider === "codex" && this.options.codexHome ? { codexHome: this.options.codexHome } : {}),
+                ...(mcp ? { mcpCredential: mcp.credential } : {}),
+                ...(launchSpec.bootstrap_root ? { setupBootstrapRoot: launchSpec.bootstrap_root } : {}),
+            });
             launchPhase = "terminal_manager";
             const terminalManager = await this.options.terminalManager();
             if (binding && !sameBinding(binding, this.options.getBinding())) {
@@ -1417,20 +1800,13 @@ export class NativeSessionService {
                 throw new InteractiveLaunchError("native session is stale because the runtime binding changed");
             }
             validateNativeSessionWorkspace(materializationState, authorizedWorkspace, cwd);
-            const terminalEnv = {
-                ...process.env,
-                ...(mcp ? { [NATIVE_MCP_CREDENTIAL_ENV_VAR]: mcp.credential } : {}),
-                ...(binding ? { WREN_PROJECT_HOME: binding.path } : {}),
-                ...(codexWrenHome ? { WREN_HOME: codexWrenHome.home } : {}),
-            };
-            // Never inherit a caller/operator value: only the launch spec's already
-            // revalidated Setup root may reach the native TUI.
-            delete terminalEnv[NATIVE_SETUP_BOOTSTRAP_ROOT_ENV_VAR];
-            if (spec.bootstrap_root)
-                terminalEnv[NATIVE_SETUP_BOOTSTRAP_ROOT_ENV_VAR] = spec.bootstrap_root;
+            codexWrenHome?.assertActive?.();
+            assertNativeRuntimeSpec(runtimeSpec);
+            this.assertRuntimeDispatchable();
             launchPhase = "terminal_start";
-            const terminal = terminalManager.start(spec, { id, capability }, terminalEnv, NO_INTERACTIVE_TERMINAL_LEASES);
+            const terminal = terminalManager.start({ ...launchSpec, hostExecutable: vendorExecutable.executable }, { id, capability }, runtimeSpec.childEnvironment, NO_INTERACTIVE_TERMINAL_LEASES);
             this.sessions.set(id, terminal);
+            this.runtimeSpecs.set(id, runtimeSpec);
             // Mark running before registering a replaying exit listener. A PTY can
             // exit between start() and this registration; `onExit` immediately
             // replays that state and must win over this transition, never be
@@ -1445,6 +1821,7 @@ export class NativeSessionService {
                 this.recoveryCapabilities.delete(id);
                 artifactService?.revoke(this.artifactCredentials.get(id));
                 this.artifactCredentials.delete(id);
+                this.cleanupRuntime(id);
                 const current = this.options.store.getNativeSession(id);
                 if (current && (current.status === "running" || current.status === "detached"))
                     this.options.store.transitionNativeSession(id, "exited", { exitCode, ended: true });
@@ -1455,6 +1832,7 @@ export class NativeSessionService {
         }
         catch (error) {
             logNativeLaunchFailure(purpose, dispatchDefinition.provider, launchPhase, error);
+            this.cleanupRuntime(id);
             this.recoveryCapabilities.delete(id);
             artifactService?.revoke(this.artifactCredentials.get(id));
             this.artifactCredentials.delete(id);
@@ -1476,6 +1854,153 @@ export class NativeSessionService {
             throw error;
         }
     }
+    liveCapability(id) {
+        return this.sessions.get(id)?.capability ?? this.conversations.get(id)?.conversation.capability;
+    }
+    async createDirectCodex(binding, runtime, entryVerb) {
+        const provisioner = this.options.directCodex;
+        if (provisioner.terminal && !provisioner.terminalCertified?.(entryVerb))
+            throw new InteractiveLaunchError("Native terminal version is not certified");
+        const permit = provisioner.backend.prepareLaunch(); // before rows, credentials or workspace writes
+        const capturedBinding = structuredClone(binding);
+        const capturedRuntime = structuredClone(runtime);
+        const id = newId("native-session");
+        const controller = new AbortController();
+        const signal = AbortSignal.any([controller.signal, this.shutdownController.signal]);
+        let prepared;
+        let conversation;
+        let renderer;
+        let closing;
+        const assertActive = () => {
+            signal.throwIfAborted();
+            this.assertRuntimeDispatchable();
+            const row = this.options.store.getNativeSession(id);
+            if (!sameBinding(capturedBinding, this.options.getBinding()) || !sameNativeRuntimeBinding(capturedRuntime, this.options.store.getNativeRuntimeBinding())
+                || (row && !["creating", "running", "detached"].includes(row.status)))
+                throw new InteractiveLaunchError("native session scope is stale");
+        };
+        const close = () => closing ??= (async () => {
+            controller.abort();
+            const results = await Promise.allSettled([renderer?.close(), conversation?.close(), prepared?.input.tools.close()]);
+            // Keep materialized resources if process/tool cleanup could not be confirmed.
+            if (results.some((result) => result.status === "rejected"))
+                throw new InteractiveLaunchError("native conversation cleanup failed");
+            await prepared?.dispose();
+        })();
+        try {
+            assertActive();
+            permit.assertActive();
+            const row = this.options.store.createNativeSession({ id, ...(!provisioner.terminal ? { transport: "conversation" } : {}), purpose: "analysis", vendor: "codex", agent: agentFor("analysis", "codex"),
+                entryVerb, scopeKind: "bound_project", scopeId: newId("native-scope"), dispatchProfile: NATIVE_DISPATCH_REGISTRY.analysis.profile,
+                dispatchTarget: "codex:interactive", runtimeGeneration: capturedRuntime.generation,
+                projectIdentity: capturedBinding.identity, bindingGeneration: capturedBinding.generation, projectRevision: capturedBinding.revision });
+            prepared = await provisioner.prepare({ session: row, binding: capturedBinding, permit, signal, assertActive });
+            assertActive();
+            permit.assertActive();
+            prepared.input.tools.assertCurrent();
+            const hostGuard = prepared.input.assertScopeActive;
+            conversation = new CodexConversation(provisioner.backend, permit, { ...prepared.input,
+                assertScopeActive: () => { assertActive(); hostGuard(); },
+            }, (state, failure) => {
+                if (state !== "closed" && state !== "failed")
+                    return;
+                const current = this.options.store.getNativeSession(id);
+                if (current && ["creating", "running", "detached"].includes(current.status)) {
+                    this.options.store.transitionNativeSession(id, state === "failed" ? "failed" : "exited", { ended: true,
+                        ...(failure ? { failure: `Codex conversation ${failure}` } : {}) });
+                }
+                // Schedule after transition delivers its terminal frame to the attachment.
+                queueMicrotask(() => this.revokeCapabilities([id]));
+            });
+            this.conversations.set(id, { conversation, assertActive, close });
+            await conversation.ready;
+            assertActive();
+            if (provisioner.terminal) {
+                const vendor = prepared.input.spec.executables.vendor;
+                if (!vendor || !prepared.input.model)
+                    throw new InteractiveLaunchError("Native terminal configuration is unavailable");
+                renderer = await startCodexTerminal({ id, conversation, manager: await this.options.terminalManager(), vendor,
+                    cwd: prepared.input.spec.workspace, model: prepared.input.model, assertActive });
+                this.sessions.set(id, renderer.terminal);
+            }
+            this.options.store.transitionNativeSession(id, "running", { started: true });
+            if (renderer) {
+                renderer.terminal.onExit((exitCode) => {
+                    const current = this.options.store.getNativeSession(id);
+                    if (current && ["creating", "running", "detached"].includes(current.status)) {
+                        this.options.store.transitionNativeSession(id, exitCode === 0 ? "exited" : "failed", { ended: true,
+                            ...(exitCode !== 0 ? { failure: "Codex terminal exited" } : {}) });
+                    }
+                    queueMicrotask(() => this.revokeCapabilities([id]));
+                });
+            }
+            assertActive();
+            this.armLease(id, "native session attachment timed out", NATIVE_SESSION_INITIAL_ATTACHMENT_GRACE_MS);
+            return { row: this.options.store.getNativeSession(id), capability: conversation.capability };
+        }
+        catch (error) {
+            const row = this.options.store.getNativeSession(id);
+            if (row && ["creating", "running", "detached"].includes(row.status))
+                this.options.store.transitionNativeSession(id, "failed", { ended: true, failure: "Direct Codex launch failed" });
+            this.sessions.delete(id);
+            this.conversations.delete(id);
+            permit.release();
+            try {
+                await close();
+            }
+            catch {
+                this.componentCleanupFailed = true;
+                throw new InteractiveLaunchError("native conversation cleanup failed");
+            }
+            throw error;
+        }
+    }
+    attachConversation(id, capability, listener, afterSequence = 0) {
+        if (this.options.directCodex?.terminal)
+            return undefined;
+        const direct = this.conversations.get(id);
+        if (!direct)
+            return undefined;
+        let attachment;
+        try {
+            direct.assertActive();
+            attachment = direct.conversation.attach(capability, listener, afterSequence);
+        }
+        catch {
+            return undefined;
+        }
+        if (!["ready", "running"].includes(direct.conversation.snapshot().state)) {
+            attachment.detach();
+            return undefined;
+        }
+        this.clearLease(id);
+        this.options.store.transitionNativeSession(id, "running");
+        let detached = false;
+        const check = () => { if (detached)
+            throw new InteractiveLaunchError("native attachment is unavailable"); direct.assertActive(); };
+        return { submit: (text) => { check(); return attachment.submit(text); }, interrupt: () => { check(); return attachment.interrupt(); },
+            detach: () => {
+                if (detached)
+                    return;
+                detached = true;
+                attachment.detach();
+                if (this.conversations.get(id) === direct && ["ready", "running"].includes(direct.conversation.snapshot().state)) {
+                    this.options.store.transitionNativeSession(id, "detached");
+                    this.armLease(id, "native session idle TTL expired", this.idleTtlMs);
+                }
+            } };
+    }
+    async stopAndWait(id, capability) {
+        const direct = this.conversations.get(id);
+        if (!direct)
+            return this.stop(id, capability);
+        if (direct.conversation.capability !== capability)
+            return false;
+        this.options.store.stopNativeSessionAndRevokeRecoveryAction(id);
+        this.revokeCapabilities([id]);
+        await direct.close();
+        return true;
+    }
     attach(id, capability) {
         const row = this.get(id);
         const runtime = this.options.store.getNativeRuntimeBinding();
@@ -1493,6 +2018,7 @@ export class NativeSessionService {
         return terminal;
     }
     detach(id) {
+        this.componentAdmissions.get(id)?.cancelActive();
         this.sessions.get(id)?.detach();
         if (this.sessions.has(id)) {
             this.options.store.transitionNativeSession(id, "detached");
@@ -1520,12 +2046,25 @@ export class NativeSessionService {
             this.options.artifactService?.revoke(this.artifactCredentials.get(id));
             this.artifactCredentials.delete(id);
             this.sessions.delete(id);
+            const direct = this.conversations.get(id);
+            this.conversations.delete(id);
+            if (direct) {
+                const cleanup = direct.close();
+                this.componentCleanups.add(cleanup);
+                void cleanup.catch(() => { this.componentCleanupFailed = true; }).finally(() => this.componentCleanups.delete(cleanup));
+            }
+            this.cleanupRuntime(id);
             try {
                 terminal?.close();
+                if (terminal)
+                    this.pendingTerminalCleanup.delete(terminal);
             }
             catch {
                 // A process kill may fail after the durable session fence committed.
                 // Capabilities are already unreachable; continue revoking every id.
+                this.runtimeCleanupFailed = true;
+                if (terminal)
+                    this.pendingTerminalCleanup.add(terminal);
                 console.warn("[native-sessions] terminal close failed during capability revocation");
             }
         }
@@ -1534,6 +2073,81 @@ export class NativeSessionService {
     revokeRuntimeCapabilities(ids) { this.revokeCapabilities(ids); }
     /** Called after the store advances the bound-project generation. */
     revokeBindingCapabilities(ids) { this.revokeCapabilities(ids); }
+    componentTools(id) { return this.componentAdmissions.get(id)?.list() ?? []; }
+    async callComponent(id, tool, input, requestId, signal) {
+        const admission = this.componentAdmissions.get(id);
+        if (!admission)
+            throw new InteractiveLaunchError("native component execution is unavailable");
+        return admission.call(tool, input, requestId, signal);
+    }
+    async drainComponentCleanup() {
+        const cleanup = await Promise.allSettled([...this.componentCleanups]);
+        if (this.componentCleanupFailed || cleanup.some((result) => result.status === "rejected"))
+            throw new InteractiveLaunchError("native component cleanup failed");
+    }
+    shutdown() {
+        this.shuttingDown = true;
+        this.shutdownController.abort();
+        return this.shutdownPromise ??= (async () => {
+            const ids = [...new Set([...this.sessions.keys(), ...this.conversations.keys(), ...this.componentAdmissions.keys()])];
+            for (const id of ids)
+                this.options.store.stopNativeSessionAndRevokeRecoveryAction(id);
+            this.revokeCapabilities(ids);
+            let timer;
+            try {
+                await Promise.race([Promise.allSettled([...this.pendingCreates]), new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new InteractiveLaunchError("native launch cleanup timed out")), 5_000);
+                    })]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            this.revokeCapabilities([...this.componentAdmissions.keys()]);
+            // Failed resources remain owned after capability revocation, for one final retry.
+            for (const terminal of this.pendingTerminalCleanup) {
+                try {
+                    terminal.close();
+                    this.pendingTerminalCleanup.delete(terminal);
+                }
+                catch {
+                    this.runtimeCleanupFailed = true;
+                }
+            }
+            for (const cleanup of this.pendingHomeCleanup) {
+                try {
+                    cleanup();
+                    this.pendingHomeCleanup.delete(cleanup);
+                }
+                catch {
+                    this.runtimeCleanupFailed = true;
+                }
+            }
+            await this.drainComponentCleanup();
+            if (this.runtimeCleanupFailed)
+                throw new InteractiveLaunchError("native runtime cleanup failed");
+        })();
+    }
+    cleanupRuntime(id) {
+        const admission = this.componentAdmissions.get(id);
+        this.componentAdmissions.delete(id);
+        if (admission) {
+            const cleanup = admission.close();
+            this.componentCleanups.add(cleanup);
+            void cleanup.catch(() => { this.componentCleanupFailed = true; console.warn("[native-sessions] component cleanup failed"); }).finally(() => this.componentCleanups.delete(cleanup));
+        }
+        const home = this.codexWrenHomes.get(id);
+        this.codexWrenHomes.delete(id);
+        this.runtimeSpecs.delete(id);
+        try {
+            home?.cleanup?.();
+        }
+        catch {
+            this.runtimeCleanupFailed = true;
+            if (home?.cleanup)
+                this.pendingHomeCleanup.add(home.cleanup.bind(home));
+            console.warn("[native-sessions] Wren session home cleanup failed");
+        }
+    }
     /**
      * Records only the producer's closed redacted report. Completion remains a
      * host decision supplied by the canonical-artifact validator at the route.
@@ -1598,14 +2212,19 @@ export class NativeSessionService {
     }
     armLease(id, reason, timeoutMs) {
         this.clearLease(id);
-        this.leaseTimers.set(id, setTimeout(() => {
-            const terminal = this.sessions.get(id);
-            if (!terminal) {
+        const timer = setTimeout(() => {
+            if (this.options.store.isClosed()) {
+                this.leaseTimers.delete(id);
+                return;
+            }
+            if (!this.liveCapability(id)) {
                 this.leaseTimers.delete(id);
                 return;
             }
             this.options.store.transitionNativeSession(id, "stopped", { failure: reason, ended: true });
             this.revokeCapabilities([id]);
-        }, timeoutMs));
+        }, timeoutMs);
+        timer.unref();
+        this.leaseTimers.set(id, timer);
     }
 }