@wrenai/genbi 0.0.3 → 0.0.5

package/dist-server/server/runtime-binding.js

@@ -9,6 +9,7 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { resolveHubDir, resolveWarbleBinary, runWarble } from "../harness/index.js";
+import { GATEWAY_API_KEY_ENV } from "./env-detect.js";
 export class RuntimeBindingError extends Error {
 }
 /**
@@ -43,9 +44,13 @@ function bindingByTier(settings) {
     }
     return bindings;
 }
-/** The old single Model field is the default for every tier without a model override. */
+/**
+ * The old single Model field is the default for every tier without a model
+ * override; in gateway mode the gateway's own default model comes first.
+ */
 export function effectiveTierModel(binding, settings) {
-    return nonEmpty(binding.model) ?? nonEmpty(settings.apiKeyModel);
+    const gatewayDefault = settings.authMode === "gateway" ? nonEmpty(settings.gatewayModel) : undefined;
+    return nonEmpty(binding.model) ?? gatewayDefault ?? nonEmpty(settings.apiKeyModel);
 }
 /**
  * Returns a browser-safe correction for an already persisted Runtime. This is
@@ -96,8 +101,24 @@ function effectiveAdapter(binding, settings) {
         return binding.adapter;
     if (settings.authMode === "local")
         return "local";
+    if (settings.authMode === "gateway")
+        return "pi-ai";
     return settings.apiKeyAdapter ?? "anthropic";
 }
+function requireGatewayProvider(tier, settings) {
+    const provider = nonEmpty(settings.gatewayProvider);
+    if (!provider)
+        throw new RuntimeBindingError(`A gateway provider is required for the pi-ai adapter on tier "${tier}".`);
+    return provider;
+}
+/** The pi-ai base URL is optional: without one the provider's own catalogued endpoint is used. */
+function optionalGatewayBaseUrl(tier, binding, settings) {
+    const baseURL = nonEmpty(binding.baseURL) ?? nonEmpty(settings.gatewayBaseURL);
+    if (baseURL !== undefined && !absoluteHttpUrl(baseURL)) {
+        throw new RuntimeBindingError(`Tier "${tier}": gateway Base URL must be an absolute http(s) URL — got "${baseURL}".`);
+    }
+    return baseURL;
+}
 /** Credential env vars used by the materialized in-process rows (local rows need none). */
 export function requiredInProcessCredentialEnvVars(settings) {
     const required = new Set();
@@ -107,6 +128,8 @@ export function requiredInProcessCredentialEnvVars(settings) {
             required.add("ANTHROPIC_API_KEY");
         if (adapter === "openai-compatible")
             required.add("OPENAI_API_KEY");
+        if (adapter === "pi-ai")
+            required.add(GATEWAY_API_KEY_ENV);
     }
     return [...required];
 }
@@ -131,6 +154,14 @@ export function validateRuntimeTierBindings(settings, bundleTiers) {
         const adapter = effectiveAdapter(binding, settings);
         if (adapter === "openai-compatible" || adapter === "local")
             requireBaseUrl(tier, binding, settings);
+        if (adapter === "pi-ai") {
+            // The subscription dispatchers have no pi-ai backend; gateway rows run in-process only.
+            if (settings.authMode === "subscription") {
+                throw new RuntimeBindingError(`Tier "${tier}": the pi-ai adapter runs in-process only and cannot be used with a subscription dispatcher.`);
+            }
+            requireGatewayProvider(tier, settings);
+            optionalGatewayBaseUrl(tier, binding, settings);
+        }
     }
     if (settings.authMode === "subscription" && !nonEmpty(settings.subscriptionDriverModel)) {
         throw new RuntimeBindingError("A subscription dispatcher driver model is required.");
@@ -149,12 +180,29 @@ function inProcessSpec(tier, binding, settings) {
             return { adapter: "openai-compatible", config: { model, baseURL: requireBaseUrl(tier, binding, settings), apiKey: process.env["OPENAI_API_KEY"] ?? "" } };
         case "local":
             return { adapter: "openai-compatible", config: { model, baseURL: requireBaseUrl(tier, binding, settings) } };
+        case "pi-ai": {
+            // Like openai-compatible: the env-backed key lives only in this
+            // transient spec, never in the persisted settings.
+            const baseUrl = optionalGatewayBaseUrl(tier, binding, settings);
+            const apiKey = nonEmpty(process.env[GATEWAY_API_KEY_ENV]);
+            return {
+                adapter: "pi-ai",
+                config: {
+                    provider: requireGatewayProvider(tier, settings),
+                    model,
+                    ...(baseUrl !== undefined ? { baseUrl } : {}),
+                    ...(apiKey !== undefined ? { apiKey } : {}),
+                },
+            };
+        }
     }
 }
 function dispatchedTierYaml(tier, binding, settings) {
     const model = requireModel(tier, binding, settings);
     const adapter = effectiveAdapter(binding, settings);
     const key = JSON.stringify(tier);
+    if (adapter === "pi-ai")
+        throw new RuntimeBindingError(`Tier "${tier}": the pi-ai adapter has no subscription dispatcher equivalent.`);
     if (adapter === "anthropic")
         return [`  ${key}: ${JSON.stringify(model)}`];
     return [

package/dist-server/server/runtime-host/claude-component-step.d.ts

@@ -0,0 +1,25 @@
+import { type Options, type Query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { StepRun, StepResponse } from "../../harness/components/runner.js";
+/** Supplied only by the certified same-account process provisioner. No default spawn. */
+export interface ClaudeComponentRuntime {
+    readonly cwd: string;
+    readonly executable: string;
+    readonly model: string;
+    readonly account: {
+        readonly email: string;
+        readonly tokenSource: string;
+        readonly subscriptionType: string;
+    };
+    readonly environment: Readonly<Record<string, string>>;
+    readonly spawn: NonNullable<Options["spawnClaudeCodeProcess"]>;
+    readonly query: (input: {
+        prompt: AsyncIterable<SDKUserMessage>;
+        options: Options;
+    }) => Query;
+    /** Revalidates approved login, isolated home, SDK/CLI/SRT and runtime generation. */
+    assertCurrent(): void;
+    /** Resolves only after all owned vendor processes and descendants are gone. */
+    close(): Promise<void>;
+}
+/** One fresh SDK query and SDK MCP server per step; never reuse the outer PTY. */
+export declare function runClaudeComponentStep(runtime: ClaudeComponentRuntime, run: StepRun): Promise<StepResponse>;

package/dist-server/server/runtime-host/claude-component-step.js

@@ -0,0 +1,186 @@
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+class ClaudeComponentError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Claude component ${reason}`);
+        this.reason = reason;
+    }
+}
+function deny() { throw new ClaudeComponentError("protocol"); }
+const record = z.record(z.string(), z.unknown());
+const messageIdentity = z.object({ session_id: z.string().min(1), uuid: z.string().min(1) });
+const allowedEnvironment = new Set(["PATH", "HOME", "CLAUDE_CONFIG_DIR", "TMPDIR", "LANG", "LC_ALL"]);
+/** One fresh SDK query and SDK MCP server per step; never reuse the outer PTY. */
+export async function runClaudeComponentStep(runtime, run) {
+    const { cwd, executable, model } = runtime;
+    const account = structuredClone(runtime.account);
+    const environment = Object.freeze({ ...runtime.environment });
+    const assertCurrent = runtime.assertCurrent.bind(runtime);
+    const query = runtime.query.bind(runtime);
+    const spawn = runtime.spawn;
+    const close = runtime.close.bind(runtime);
+    const controller = new AbortController();
+    const signal = AbortSignal.any([run.signal, controller.signal]);
+    let active = true;
+    let initialized = false;
+    let sessionId;
+    let pending = 0;
+    let calls = 0;
+    let failed = false;
+    let toolQueue = Promise.resolve();
+    let releaseInput;
+    const inputReady = new Promise((resolve) => { releaseInput = resolve; });
+    const check = () => { if (!active || failed)
+        deny(); if (signal.aborted)
+        throw new ClaudeComponentError("cancelled"); assertCurrent(); };
+    let session;
+    const timeout = setTimeout(() => controller.abort(), 120_000);
+    const abort = new Promise((_, reject) => {
+        signal.addEventListener("abort", () => reject(new ClaudeComponentError("cancelled")), { once: true });
+    });
+    void abort.catch(() => { });
+    const wait = (value) => Promise.race([value, abort]);
+    const tools = Object.keys(run.tools).map((name) => ({ name, wire: `mcp__component__${name}` }));
+    try {
+        check();
+        if (!cwd.startsWith("/") || !executable.startsWith("/") || !model || !account.email || !account.tokenSource || !account.subscriptionType
+            || !environment.HOME || !environment.CLAUDE_CONFIG_DIR || Object.keys(environment).some((name) => !allowedEnvironment.has(name)))
+            deny();
+        const sdkTools = tools.map(({ name }) => {
+            const schema = z.fromJSONSchema(run.toolSchemas[name] ?? deny());
+            if (!(schema instanceof z.ZodObject))
+                deny();
+            return tool(name, run.toolDescriptions[name] ?? name, schema.shape, async (input) => {
+                check();
+                if (!initialized || ++calls > 32)
+                    deny();
+                pending++;
+                const result = toolQueue.then(async () => {
+                    check();
+                    const parsed = schema.parse(input);
+                    if (Buffer.byteLength(JSON.stringify(parsed)) > 65_536)
+                        deny();
+                    const output = await wait(run.tools[name](parsed));
+                    check();
+                    const text = JSON.stringify(output);
+                    if (text === undefined || Buffer.byteLength(text) > 1_048_000)
+                        deny();
+                    return { content: [{ type: "text", text }] };
+                });
+                toolQueue = result.catch(() => { failed = true; controller.abort(); });
+                try {
+                    return await result;
+                }
+                finally {
+                    pending--;
+                }
+            });
+        });
+        async function* prompt() {
+            try {
+                await wait(inputReady);
+                check();
+                yield { type: "user", session_id: "", parent_tool_use_id: null,
+                    message: { role: "user", content: JSON.stringify({ request: run.request, input: run.input, consumes: run.consumes }) } };
+                // Keep the SDK input channel open while governed tool exchanges run.
+                await wait(new Promise(() => { }));
+            }
+            catch {
+                if (!signal.aborted) {
+                    failed = true;
+                    controller.abort();
+                }
+            }
+        }
+        session = query({ prompt: prompt(), options: {
+                abortController: controller, cwd, model, pathToClaudeCodeExecutable: executable,
+                spawnClaudeCodeProcess: spawn, env: { ...environment },
+                tools: [], allowedTools: tools.map(({ wire }) => wire),
+                mcpServers: { component: createSdkMcpServer({ name: "component", tools: sdkTools }) },
+                canUseTool: async () => { failed = true; controller.abort(); return { behavior: "deny", message: "Undeclared tool is unavailable" }; },
+                permissionMode: "default", settingSources: [], plugins: [], agents: {}, additionalDirectories: [],
+                persistSession: false, enableFileCheckpointing: false, maxTurns: 12,
+                systemPrompt: [run.brief, run.prompt].filter(Boolean).join("\n\n"),
+                extraArgs: { "strict-mcp-config": null, "disable-slash-commands": null },
+            } });
+        const observed = z.object({ email: z.literal(account.email), tokenSource: z.literal(account.tokenSource), subscriptionType: z.literal(account.subscriptionType), apiKeySource: z.literal("none") }).parse(await wait(session.accountInfo()));
+        if (!observed.email)
+            deny();
+        check();
+        releaseInput();
+        const seen = new Set();
+        while (true) {
+            const next = await wait(session.next());
+            check();
+            if (next.done)
+                deny();
+            const message = record.parse(next.value);
+            if (Buffer.byteLength(JSON.stringify(message)) > 1_048_576)
+                deny();
+            const identity = messageIdentity.parse(message);
+            if (seen.has(identity.uuid) || seen.size >= 512)
+                deny();
+            seen.add(identity.uuid);
+            if (message.type === "system" && message.subtype === "init") {
+                if (initialized)
+                    deny();
+                const init = z.object({ apiKeySource: z.literal("none"), claude_code_version: z.literal("2.1.259"), cwd: z.literal(cwd), model: z.literal(model),
+                    tools: z.array(z.string()), mcp_servers: z.array(z.object({ name: z.literal("component"), status: z.literal("connected") })),
+                    skills: z.array(z.never()), plugins: z.array(z.never()), agents: z.array(z.never()).optional(),
+                    slash_commands: z.array(z.never()), permissionMode: z.literal("default"),
+                }).parse(message);
+                if (init.tools.length !== tools.length || new Set(init.tools).size !== tools.length || init.tools.some((name) => !tools.some(({ wire }) => wire === name)))
+                    deny();
+                if (init.mcp_servers.length !== 1)
+                    deny();
+                initialized = true;
+                sessionId = identity.session_id;
+                continue;
+            }
+            if (!initialized || identity.session_id !== sessionId)
+                deny();
+            if (message.type === "result") {
+                const result = z.object({ subtype: z.literal("success"), is_error: z.literal(false), result: z.string().max(1_048_576),
+                    permission_denials: z.array(z.never()), modelUsage: z.record(z.string(), z.object({ webSearchRequests: z.literal(0), inputTokens: z.number().int().nonnegative(), outputTokens: z.number().int().nonnegative(), cacheReadInputTokens: z.number().int().nonnegative(), cacheCreationInputTokens: z.number().int().nonnegative() })), usage: z.object({ input_tokens: z.number().int().nonnegative(), output_tokens: z.number().int().nonnegative() }),
+                }).parse(message);
+                if (pending || failed || Object.keys(result.modelUsage).length !== 1 || !Object.hasOwn(result.modelUsage, model))
+                    deny();
+                await wait(session.accountInfo()).then((value) => z.object({ email: z.literal(account.email), tokenSource: z.literal(account.tokenSource), subscriptionType: z.literal(account.subscriptionType), apiKeySource: z.literal("none") }).parse(value));
+                check();
+                const totals = result.modelUsage[model];
+                return { value: result.result, usage: { inputTokens: totals.inputTokens + totals.cacheReadInputTokens + totals.cacheCreationInputTokens, outputTokens: totals.outputTokens } };
+            }
+            if (message.type !== "assistant" && message.type !== "user")
+                deny();
+            if (message.parent_tool_use_id !== null)
+                deny();
+            const content = z.object({ content: z.union([z.string(), z.array(record)]) }).parse(message.message).content;
+            if (Array.isArray(content))
+                for (const block of content) {
+                    if (block.type === "tool_use") {
+                        if (!tools.some(({ wire }) => wire === block.name))
+                            deny();
+                    }
+                    else if (!["text", "thinking", "redacted_thinking", "tool_result"].includes(String(block.type)))
+                        deny();
+                }
+        }
+    }
+    catch (error) {
+        throw new ClaudeComponentError(error instanceof ClaudeComponentError ? error.reason : "protocol");
+    }
+    finally {
+        active = false;
+        clearTimeout(timeout);
+        controller.abort();
+        releaseInput();
+        // The provisioner owns process-tree cleanup; iterator cleanup alone is insufficient.
+        try {
+            await close();
+        }
+        catch {
+            throw new ClaudeComponentError("cleanup");
+        }
+    }
+}

package/dist-server/server/runtime-host/codex-app-server.d.ts

@@ -0,0 +1,75 @@
+import { type ManagedWrenRuntimeRecord } from "../managed-wren-runtime.js";
+import { type NativeRuntimeSpec } from "../native-runtime-spec.js";
+import type { CodexWrenHome } from "../native-wren-home.js";
+import { type CodexIdentityDiagnostic } from "./codex-compatibility.js";
+import { CodexSession } from "./codex-session.js";
+import type { CodexComponentPolicy } from "./codex-component-step.js";
+import type { RpcTransport } from "./codex-rpc.js";
+import type { CodexEvent } from "./codex-events.js";
+import type { RuntimeBackendProbeResult, RuntimeBackendReasonCode } from "./types.js";
+import type { CodexSessionTools } from "./codex-direct-tools.js";
+type Reason = RuntimeBackendReasonCode<"codex-app-server">;
+export declare class CodexBackendError extends Error {
+    readonly code: Reason;
+    /** Host-only drift detail for `codex_dependencies_drifted`; never part of the readiness text. */
+    readonly drift?: readonly string[];
+    constructor(code: Reason, drift?: readonly string[]);
+}
+export interface CodexBackendOptions {
+    /** Captured at BFF composition, not discovered from command/session input. */
+    readonly executable: string;
+    readonly source: string;
+    readonly packageRoot?: string;
+    readonly runtimeRoot?: string;
+}
+export interface CodexLaunchPermit {
+    readonly runtime: ManagedWrenRuntimeRecord;
+    /** Recheck immediately before each host-side materialization/persistence step. */
+    assertActive(): void;
+    /** Abandon before materialization or open; never deletes any runtime bytes. */
+    release(): void;
+}
+/** Disabled unless the package contains an approved runtime AND certified row. */
+export declare class CodexAppServerBackend {
+    private permits;
+    private leases;
+    private sessions;
+    private steps;
+    private stopped;
+    private shutdownPromise?;
+    private readonly options;
+    constructor(options: CodexBackendOptions);
+    private resolve;
+    private inspect;
+    probe(): Promise<RuntimeBackendProbeResult<"codex-app-server"> & {
+        readonly diagnostic: CodexIdentityDiagnostic;
+    }>;
+    /** Call BEFORE durable rows or workspace materialization in Phase 5. */
+    prepareLaunch(): CodexLaunchPermit;
+    /** Include these generations in the provisioner's cleanup retain set. */
+    retainedManifestDigests(): readonly string[];
+    private assertRecord;
+    open(permit: CodexLaunchPermit, input: {
+        readonly model?: string;
+        readonly tools?: CodexSessionTools;
+        readonly spec: NativeRuntimeSpec;
+        readonly wrenHome: CodexWrenHome;
+        /** Existing host-owned binding/generation guard, never a browser callback. */
+        readonly assertScopeActive: () => void;
+        readonly onEvent: (event: CodexEvent) => void;
+    }): Promise<CodexSession>;
+    /** A fresh, governed transport per component step; same certification gate as the outer session. */
+    openStep(permit: CodexLaunchPermit, input: {
+        readonly spec: NativeRuntimeSpec;
+        readonly wrenHome: CodexWrenHome;
+        readonly model: string;
+        readonly accountEmail: string;
+        readonly signal: AbortSignal;
+        readonly assertScopeActive: () => void;
+    }): {
+        transport: RpcTransport;
+        policy: CodexComponentPolicy;
+    };
+    shutdown(): Promise<void>;
+}
+export {};

package/dist-server/server/runtime-host/codex-app-server.js

@@ -0,0 +1,239 @@
+import { execFileSync } from "node:child_process";
+import { arch, platform } from "node:os";
+import { ManagedWrenRuntimeError, resolveManagedWrenRuntime } from "../managed-wren-runtime.js";
+import { attestNativeExecutable, assertNativeExecutableIdentity } from "../native-runtime-spec.js";
+import { CODEX_CERTIFIED_ROWS, codexCertificationSchema, evaluateCodexIdentity } from "./codex-compatibility.js";
+import { buildCodexSessionPolicy } from "./codex-policy.js";
+import { spawnCodexTransport } from "./codex-process.js";
+import { CodexSession } from "./codex-session.js";
+import { CodexRpcError } from "./codex-rpc.js";
+import { runtimeNotReady } from "./policy.js";
+export class CodexBackendError extends Error {
+    code;
+    /** Host-only drift detail for `codex_dependencies_drifted`; never part of the readiness text. */
+    drift;
+    constructor(code, drift) {
+        super(runtimeNotReady("codex-app-server", "unavailable", code).message);
+        this.code = code;
+        if (drift)
+            this.drift = drift;
+    }
+}
+/** Disabled unless the package contains an approved runtime AND certified row. */
+export class CodexAppServerBackend {
+    permits = new WeakMap();
+    leases = new Set();
+    sessions = new Set();
+    steps = new Set();
+    stopped = false;
+    shutdownPromise;
+    options;
+    constructor(options) { this.options = Object.freeze({ ...options }); }
+    resolve() {
+        try {
+            return resolveManagedWrenRuntime(this.options);
+        }
+        catch (error) {
+            throw new CodexBackendError(error instanceof ManagedWrenRuntimeError ? error.code : "codex_wren_runtime_unprovisioned");
+        }
+    }
+    inspect() {
+        if (this.stopped)
+            throw new CodexBackendError("codex_app_server_unreachable");
+        if (platform() !== "darwin" || arch() !== "arm64")
+            throw new CodexBackendError("runtime_platform_unsupported");
+        const runtime = this.resolve(); // no fetch, install, mkdir, workspace or session side effects
+        let vendor;
+        try {
+            vendor = attestNativeExecutable("vendor", this.options.executable);
+        }
+        catch {
+            throw new CodexBackendError("codex_cli_missing");
+        }
+        // Hash before executing --version. An unknown executable never gets a probe
+        // process merely because the caller labels it Codex.
+        const row = CODEX_CERTIFIED_ROWS.map((value) => codexCertificationSchema.safeParse(value))
+            .find((value) => value.success && value.data.executableSha256 === vendor.digest.slice(7) && value.data.source === this.options.source);
+        if (!row?.success)
+            throw new CodexBackendError("codex_identity_uncertified");
+        let versionOutput;
+        try {
+            versionOutput = execFileSync(vendor.executable, ["--version"], { encoding: "utf8", timeout: 5_000, maxBuffer: 1024,
+                env: { PATH: "/usr/bin:/bin" }, stdio: ["ignore", "pipe", "ignore"] });
+            assertNativeExecutableIdentity(vendor);
+        }
+        catch {
+            throw new CodexBackendError("codex_app_server_unreachable");
+        }
+        // The exact executable digest binds the generated protocol schema and
+        // behavior evidence in its reviewed row; never generate schema files during
+        // readiness or equate an initialize acknowledgement with certification.
+        const result = evaluateCodexIdentity({ platform: "darwin-arm64", versionOutput,
+            executableSha256: vendor.digest.slice(7), source: this.options.source,
+            protocolSha256: row.data.protocolSha256, contracts: row.data.contracts }, CODEX_CERTIFIED_ROWS);
+        if (result.readiness.state !== "ready")
+            throw new CodexBackendError(result.readiness.code, result.diagnostic.drift);
+        return { runtime, vendor, result };
+    }
+    async probe() {
+        try {
+            return this.inspect().result;
+        }
+        catch (error) {
+            const code = error instanceof CodexBackendError ? error.code : "runtime_probe_failed";
+            const drift = error instanceof CodexBackendError ? error.drift : undefined;
+            return { readiness: runtimeNotReady("codex-app-server", code.startsWith("codex_wren_") ? "unprovisioned" : "incompatible", code),
+                diagnostic: { phase: code.startsWith("codex_wren_") ? "provisioning" : "identity", ...(drift ? { drift } : {}) } };
+        }
+    }
+    /** Call BEFORE durable rows or workspace materialization in Phase 5. */
+    prepareLaunch() {
+        const { runtime, vendor } = this.inspect();
+        const state = { runtime, vendor, consumed: false, released: false };
+        const permit = Object.freeze({ runtime, assertActive: () => {
+                if (state.released || state.consumed || this.stopped)
+                    throw new CodexBackendError("runtime_policy_unavailable");
+                this.assertRecord(state);
+            }, release: () => {
+                if (state.consumed)
+                    return;
+                state.released = true;
+                this.leases.delete(state);
+            } });
+        this.permits.set(permit, state);
+        this.leases.add(state);
+        return permit;
+    }
+    /** Include these generations in the provisioner's cleanup retain set. */
+    retainedManifestDigests() { return Object.freeze([...new Set([...this.leases].map((state) => state.runtime.manifest_digest))]); }
+    assertRecord(state) {
+        const current = this.resolve();
+        if (JSON.stringify(current) !== JSON.stringify(state.runtime))
+            throw new CodexBackendError("codex_wren_closure_mismatch");
+        try {
+            assertNativeExecutableIdentity(state.vendor);
+        }
+        catch {
+            throw new CodexBackendError("codex_identity_uncertified");
+        }
+        return current;
+    }
+    async open(permit, input) {
+        const state = this.permits.get(permit);
+        if (!state || state.consumed || state.released || this.stopped)
+            throw new CodexBackendError("runtime_policy_unavailable");
+        state.consumed = true;
+        const revalidate = () => {
+            const current = this.assertRecord(state);
+            if (input.spec.executables.vendor?.digest !== state.vendor.digest || input.spec.executables.vendor?.executable !== state.vendor.executable)
+                throw new CodexBackendError("codex_identity_uncertified");
+            try {
+                input.assertScopeActive();
+            }
+            catch {
+                throw new CodexBackendError("runtime_policy_unavailable");
+            }
+            try {
+                return buildCodexSessionPolicy(input.spec, current, input.wrenHome, input.tools !== undefined, input.model);
+            }
+            catch {
+                throw new CodexBackendError("codex_wren_child_env_invalid");
+            }
+        };
+        let spawned = false;
+        try {
+            const policy = revalidate();
+            const transport = spawnCodexTransport({ executable: state.vendor.executable, args: policy.args, cwd: policy.cwd, env: { ...policy.environment } });
+            spawned = true;
+            const session = await CodexSession.connect(transport, policy, () => {
+                if (this.stopped || JSON.stringify(revalidate()) !== JSON.stringify(policy))
+                    throw new CodexBackendError("runtime_policy_unavailable");
+            }, input.onEvent, (opening) => {
+                // Own the connection before initialization: shutdown must also cancel
+                // a peer that never acknowledges the handshake.
+                this.sessions.add(opening);
+                const originalClose = opening.close.bind(opening);
+                opening.close = async () => { await originalClose(); this.sessions.delete(opening); this.leases.delete(state); };
+            }, input.tools);
+            if (this.stopped) {
+                await session.close();
+                this.leases.delete(state);
+                throw new CodexBackendError("codex_app_server_unreachable");
+            }
+            return session;
+        }
+        catch (error) {
+            // Pre-spawn failures have no process to retain. A post-spawn cleanup
+            // failure conservatively pins the generation for operator reconciliation.
+            if (!spawned || !(error instanceof CodexRpcError && error.reason === "cleanup"))
+                this.leases.delete(state);
+            if (error instanceof CodexBackendError)
+                throw error;
+            if (error instanceof CodexRpcError && error.reason === "cleanup")
+                throw new CodexBackendError("codex_app_server_cleanup_failed");
+            if (error instanceof CodexRpcError && error.reason === "permission")
+                throw new CodexBackendError("codex_permission_profile_unavailable");
+            throw new CodexBackendError("codex_app_server_protocol_incompatible");
+        }
+    }
+    /** A fresh, governed transport per component step; same certification gate as the outer session. */
+    openStep(permit, input) {
+        const state = this.permits.get(permit);
+        if (!state || state.consumed || state.released || this.stopped)
+            throw new CodexBackendError("runtime_policy_unavailable");
+        const checkLive = () => {
+            input.signal.throwIfAborted();
+            input.assertScopeActive();
+            if (this.stopped)
+                throw new CodexBackendError("runtime_policy_unavailable");
+        };
+        const check = () => {
+            checkLive();
+            const runtime = this.assertRecord(state);
+            if (input.spec.executables.vendor?.digest !== state.vendor.digest || input.spec.executables.vendor?.executable !== state.vendor.executable)
+                throw new CodexBackendError("codex_identity_uncertified");
+            return buildCodexSessionPolicy(input.spec, runtime, input.wrenHome, true, input.model);
+        };
+        const launch = check();
+        state.consumed = true;
+        let raw;
+        try {
+            raw = spawnCodexTransport({ executable: state.vendor.executable, args: launch.args, cwd: launch.cwd, env: { ...launch.environment } });
+        }
+        catch (error) {
+            this.leases.delete(state);
+            throw error;
+        }
+        let closing;
+        const transport = { listen: raw.listen.bind(raw), write: raw.write.bind(raw), close: () => closing ??= (async () => {
+                await raw.close();
+                this.steps.delete(transport);
+                this.leases.delete(state);
+                input.signal.removeEventListener("abort", abort);
+            })() };
+        const abort = () => { void transport.close().catch(() => { }); };
+        this.steps.add(transport);
+        input.signal.addEventListener("abort", abort, { once: true });
+        if (input.signal.aborted)
+            abort();
+        return { transport, policy: { cwd: launch.cwd, codexHome: launch.codexHome, permissionProfile: launch.profile,
+                model: input.model, accountEmail: input.accountEmail, configuration: launch.configuration,
+                assertLive: checkLive,
+                assertCurrent() { if (JSON.stringify(check()) !== JSON.stringify(launch))
+                    throw new CodexBackendError("runtime_policy_unavailable"); } } };
+    }
+    shutdown() {
+        this.stopped = true;
+        this.shutdownPromise ??= (async () => {
+            const results = await Promise.allSettled([...this.sessions, ...this.steps].map((session) => session.close()));
+            for (const state of this.leases)
+                if (!state.consumed) {
+                    state.released = true;
+                    this.leases.delete(state);
+                }
+            if (results.some((result) => result.status === "rejected"))
+                throw new CodexBackendError("codex_app_server_cleanup_failed");
+        })();
+        return this.shutdownPromise;
+    }
+}