@wrenai/genbi 0.0.4 → 0.0.5

package/dist-server/server/native-components.d.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { type ExecutionPlan, type RunnerHost } from "../harness/components/runner.js";
+import type { ComponentInvocationResult } from "@warble/claude-agent-sdk";
+export declare const NATIVE_COMPONENT_REQUEST_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly request: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 65536;
+        };
+    };
+    readonly required: readonly ["request"];
+};
+declare const launchHost: z.ZodObject<{
+    protocol: z.ZodLiteral<"warble-component-host/1">;
+    execution: z.ZodLiteral<"host_owned_steps">;
+    session_id: z.ZodString;
+    vendor: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+    }>;
+    auth_identity: z.ZodString;
+    runtime_generation: z.ZodString;
+    binding: z.ZodObject<{
+        project_identity: z.ZodString;
+        generation: z.ZodString;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    host_plan_sha256: z.ZodString;
+    plan_path: z.ZodLiteral<".warble/component-plans.json">;
+    root_tools: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+export type NativeComponentIdentity = Pick<z.infer<typeof launchHost>, "session_id" | "vendor" | "auth_identity" | "runtime_generation" | "binding">;
+export interface NativeComponentReceipt {
+    readonly identity: NativeComponentIdentity;
+    readonly irDocument: string;
+    readonly scopeDocument: string;
+    readonly hostRoots: Readonly<Record<string, unknown>>;
+    readonly contexts: Readonly<Record<string, unknown>>;
+}
+export interface NativeComponentPlans {
+    readonly identity: NativeComponentIdentity;
+    readonly digest: string;
+    readonly roots: Readonly<Record<string, ExecutionPlan>>;
+    readonly tools: Readonly<Record<string, string>>;
+}
+/** Supplied by a certified server-side provisioner, never browser/runtime settings JSON. */
+export interface NativeComponentPreparation {
+    readonly identity: NativeComponentIdentity;
+    readonly hostRoots: Readonly<Record<string, unknown>>;
+    readonly contexts: Readonly<Record<string, unknown>>;
+    /** Revalidates the approved account and exact vendor execution generation. */
+    assertCurrent(): void;
+    host(root: string, plan: ExecutionPlan, signal: AbortSignal): Promise<RunnerHost>;
+}
+export declare function nativeComponentHostContract(prepared: NativeComponentPreparation): Readonly<Record<string, unknown>>;
+/** Correlate emitted launch/plan data with host-owned inputs, never model arguments. */
+export declare function readNativeComponentPlans(document: string, launch: unknown, receipt: NativeComponentReceipt): NativeComponentPlans;
+/** Per-session fixed-root admission. A tool name selects a root, never an active step. */
+export declare class NativeComponentAdmission {
+    private readonly current;
+    private readonly host;
+    private readonly controller;
+    private readonly requests;
+    private active;
+    private activeController;
+    private cleanupFailure;
+    private closing?;
+    private readonly plans;
+    constructor(plans: NativeComponentPlans, current: () => NativeComponentIdentity | undefined, host: (root: string, plan: ExecutionPlan, signal: AbortSignal) => Promise<RunnerHost>);
+    private check;
+    list(): readonly {
+        name: string;
+        description: string;
+        inputSchema: typeof NATIVE_COMPONENT_REQUEST_SCHEMA;
+    }[];
+    call(name: string, input: unknown, requestId: string | number, signal?: AbortSignal): Promise<ComponentInvocationResult>;
+    /** Browser detach cancels work while allowing the retained terminal to reconnect. */
+    cancelActive(): void;
+    close(): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { canonicalPlanJson, planDigest, readExecutionPlan } from "../harness/components/plan.js";
+import { ComponentRunner } from "../harness/components/runner.js";
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const binding = z.object({ project_identity: z.string().min(1), generation: z.string().min(1), revision: z.string().min(1) }).strict();
+const identity = {
+    protocol: z.literal("warble-component-host/1"), execution: z.literal("host_owned_steps"),
+    session_id: z.string().min(1), vendor: z.enum(["claude", "codex"]), auth_identity: z.string().min(1),
+    runtime_generation: z.string().min(1), binding,
+};
+export const NATIVE_COMPONENT_REQUEST_SCHEMA = { type: "object", additionalProperties: false,
+    properties: { request: { type: "string", minLength: 1, maxLength: 65_536 } }, required: ["request"],
+};
+const rootTools = z.record(z.string(), z.string().regex(/^warble_run_[a-f0-9]{32}$/));
+const launchHost = z.object({ ...identity, host_plan_sha256: digest,
+    plan_path: z.literal(".warble/component-plans.json"), root_tools: rootTools,
+}).strict();
+const nativePlan = z.object({ ...identity, version: z.literal("1"), execution_status: z.literal("not_executed"),
+    host_plan_sha256: digest, input_ir_sha256: digest, scope_sha256: digest,
+    plans: z.record(z.string(), z.record(z.string(), z.unknown())), prepared_contexts: z.record(z.string(), digest),
+    root_tools: rootTools, request_schema: z.unknown(),
+}).strict();
+export function nativeComponentHostContract(prepared) {
+    prepared.assertCurrent();
+    return { version: "1", protocol: "warble-component-host/1", ...structuredClone(prepared.identity),
+        roots: structuredClone(prepared.hostRoots),
+        prepared_contexts: Object.fromEntries(Object.entries(prepared.contexts).map(([id, context]) => [id, planDigest(context)])),
+    };
+}
+function equal(left, right) {
+    if (!isDeepStrictEqual(left, right))
+        throw new Error("Native component receipt mismatch");
+}
+function bytesDigest(value) { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
+/** Correlate emitted launch/plan data with host-owned inputs, never model arguments. */
+export function readNativeComponentPlans(document, launch, receipt) {
+    if (Buffer.byteLength(document) > 4 * 1024 * 1024)
+        throw new Error("Native component plan exceeds byte limit");
+    const raw = JSON.parse(document);
+    const parsed = nativePlan.parse(raw);
+    const descriptor = launchHost.parse(launch);
+    const { host_plan_sha256: claimed, ...payload } = raw;
+    equal(claimed, planDigest(payload));
+    equal(descriptor.host_plan_sha256, claimed);
+    for (const key of ["session_id", "vendor", "auth_identity", "runtime_generation", "binding"]) {
+        equal(parsed[key], receipt.identity[key]);
+        equal(descriptor[key], receipt.identity[key]);
+    }
+    equal(parsed.input_ir_sha256, bytesDigest(receipt.irDocument));
+    const scope = JSON.parse(receipt.scopeDocument);
+    // The v3 scope contract defaults an omitted entry kind to the pinned agent form.
+    if (scope.entry?.kind === undefined && typeof scope.entry?.verb === "string")
+        scope.entry.kind = "agent";
+    equal(parsed.scope_sha256, planDigest(scope));
+    equal(parsed.root_tools, descriptor.root_tools);
+    equal(parsed.request_schema, NATIVE_COMPONENT_REQUEST_SCHEMA);
+    equal(Object.keys(parsed.plans).sort(), Object.keys(receipt.hostRoots).sort());
+    equal(Object.keys(parsed.root_tools).sort(), Object.keys(parsed.plans).sort());
+    if (new Set(Object.values(parsed.root_tools)).size !== Object.keys(parsed.root_tools).length)
+        throw new Error("Duplicate native admission tool");
+    equal(parsed.prepared_contexts, Object.fromEntries(Object.entries(receipt.contexts).map(([id, context]) => [id, planDigest(context)])));
+    const ir = z.object({ context_binding: z.record(z.string(), z.unknown()), components: z.array(z.object({ id: z.string() }).passthrough()) }).passthrough().parse(JSON.parse(receipt.irDocument));
+    const declarations = Object.fromEntries(ir.components.map((component) => [component.id, component]));
+    const roots = Object.fromEntries(Object.entries(parsed.plans).map(([root, plan]) => {
+        equal(plan.entry, root);
+        const executable = readExecutionPlan(JSON.stringify(plan), { digest: digest.parse(plan.plan_sha256), inputIrDigest: parsed.input_ir_sha256,
+            contextBinding: ir.context_binding, declarations, directHostDocument: canonicalPlanJson(receipt.hostRoots[root]),
+        });
+        for (const id of Object.keys(executable.components))
+            if (!Object.hasOwn(receipt.contexts, id))
+                throw new Error("Missing native component context");
+        return [root, executable];
+    }));
+    return { identity: structuredClone(receipt.identity), digest: parsed.host_plan_sha256, roots, tools: parsed.root_tools };
+}
+/** Per-session fixed-root admission. A tool name selects a root, never an active step. */
+export class NativeComponentAdmission {
+    current;
+    host;
+    controller = new AbortController();
+    requests = new Set();
+    active;
+    activeController;
+    cleanupFailure = false;
+    closing;
+    plans;
+    constructor(plans, current, host) {
+        this.current = current;
+        this.host = host;
+        this.plans = structuredClone(plans);
+    }
+    check() {
+        this.controller.signal.throwIfAborted();
+        if (this.cleanupFailure)
+            throw new Error("Native component cleanup failed");
+        if (!isDeepStrictEqual(this.current(), this.plans.identity)) {
+            this.controller.abort();
+            throw new Error("Native component session expired");
+        }
+    }
+    list() {
+        this.check();
+        return Object.entries(this.plans.tools).map(([root, name]) => ({ name,
+            description: String(this.plans.roots[root].components[root].declaration.description ?? `Run ${root}`), inputSchema: NATIVE_COMPONENT_REQUEST_SCHEMA, }));
+    }
+    async call(name, input, requestId, signal) {
+        this.check();
+        const root = Object.entries(this.plans.tools).find(([, tool]) => tool === name)?.[0];
+        const parsed = z.object({ request: z.string().trim().min(1).max(65_536) }).strict().parse(input);
+        if (!root || Buffer.byteLength(JSON.stringify(parsed)) > 65_536)
+            throw new Error("Invalid native component request");
+        const key = JSON.stringify(requestId);
+        if (this.active || this.requests.has(key) || this.requests.size >= 1024)
+            throw new Error("Native component request is busy or replayed");
+        this.requests.add(key);
+        const activeController = new AbortController();
+        this.activeController = activeController;
+        const combined = AbortSignal.any([this.controller.signal, activeController.signal, ...(signal ? [signal] : [])]);
+        const plan = this.plans.roots[root];
+        const run = (async () => {
+            const host = await this.host(root, plan, combined);
+            this.check();
+            combined.throwIfAborted();
+            const runner = new ComponentRunner(plan, host);
+            const result = await runner.run(root, parsed, combined);
+            this.cleanupFailure ||= runner.cleanupFailed;
+            this.check();
+            combined.throwIfAborted();
+            return result;
+        })();
+        this.active = run;
+        try {
+            return await run;
+        }
+        finally {
+            this.active = undefined;
+            this.activeController = undefined;
+        }
+    }
+    /** Browser detach cancels work while allowing the retained terminal to reconnect. */
+    cancelActive() { this.activeController?.abort(); }
+    close() {
+        this.controller.abort();
+        return this.closing ??= (async () => {
+            let timer;
+            try {
+                await Promise.race([this.active?.catch(() => { }), new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("Native component cleanup timed out")), 5_000);
+                    })]);
+                if (this.cleanupFailure)
+                    throw new Error("Native component cleanup failed");
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        })();
+    }
+}

package/dist-server/server/native-dispatch-process.d.ts

@@ -0,0 +1,8 @@
+/** Bounded compiler process group; cancellation also reaps descendants before returning. */
+export declare function runNativeDispatchProcess(input: {
+    executable: string;
+    args: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist-server/server/native-dispatch-process.js

@@ -0,0 +1,65 @@
+import { spawn } from "node:child_process";
+/** Bounded compiler process group; cancellation also reaps descendants before returning. */
+export async function runNativeDispatchProcess(input) {
+    input.signal?.throwIfAborted();
+    if (process.platform === "win32")
+        throw new Error("Native dispatch cleanup is unavailable");
+    const child = spawn(input.executable, [...input.args], { cwd: input.cwd, env: input.env, detached: true, stdio: "ignore" });
+    let aborted = false;
+    const failure = () => new Error("Native dispatch process failed");
+    const alive = () => {
+        if (!child.pid)
+            return false;
+        try {
+            process.kill(-child.pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code !== "ESRCH";
+        }
+    };
+    const kill = (signal) => {
+        if (!child.pid)
+            return;
+        try {
+            process.kill(-child.pid, signal);
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                throw failure();
+        }
+    };
+    const gone = async (ms) => {
+        const deadline = performance.now() + ms;
+        while (alive() && performance.now() < deadline)
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        return !alive();
+    };
+    let cancel;
+    const completion = new Promise((resolve, reject) => {
+        child.once("error", () => reject(failure()));
+        child.once("exit", resolve);
+        cancel = () => { aborted = true; reject(failure()); };
+    });
+    const timer = setTimeout(cancel, 30_000);
+    input.signal?.addEventListener("abort", cancel, { once: true });
+    if (input.signal?.aborted)
+        cancel();
+    try {
+        const code = await completion;
+        if (code !== 0 || aborted)
+            throw failure();
+    }
+    finally {
+        clearTimeout(timer);
+        input.signal?.removeEventListener("abort", cancel);
+        if (!(await gone(100))) {
+            kill("SIGTERM");
+            if (!(await gone(300))) {
+                kill("SIGKILL");
+                if (!(await gone(2_000)))
+                    throw new Error("Native dispatch cleanup failed");
+            }
+        }
+    }
+}

package/dist-server/server/native-runtime-spec.d.ts

@@ -0,0 +1,89 @@
+import type { EnrichmentBinding } from "./enrichment.js";
+import type { RuntimeBackendId } from "./runtime-host/types.js";
+import type { NativeVendor } from "./native-dispatch-registry.js";
+export type NativeExecutableName = "node" | "producer" | "vendor" | "wren" | "python";
+export type NativeSha256 = `sha256:${string}`;
+/** Server-attested executable identity. Paths and digests never cross the API boundary. */
+export interface NativeExecutableIdentity {
+    readonly name: NativeExecutableName;
+    readonly executable: string;
+    readonly identity: NativeSha256;
+    readonly digest: NativeSha256;
+}
+/**
+ * The complete environment admitted at a native-session child boundary.
+ * An index signature is intentionally absent: callers cannot append an
+ * operator or browser-provided variable without first widening this contract.
+ */
+export interface NativeChildEnvironment {
+    readonly PATH: string;
+    readonly HOME: string;
+    readonly USER?: string;
+    readonly LOGNAME?: string;
+    readonly TERM: "xterm-256color";
+    readonly COLORTERM: "truecolor";
+    readonly WREN_PROJECT_HOME?: string;
+    readonly WREN_HOME?: string;
+    readonly CODEX_HOME?: string;
+    readonly WARBLE_MCP_CONNECTION_CREDENTIAL?: string;
+    readonly WARBLE_SETUP_BOOTSTRAP_ROOT?: string;
+    readonly PYTHONNOUSERSITE?: "1";
+    readonly PYTHONUTF8?: "1";
+}
+/** Adapt the exact allowlist to Node's index-signature API at the spawn seam. */
+export declare function nativeProcessEnvironment(environment: NativeChildEnvironment): NodeJS.ProcessEnv;
+export interface NativeRuntimeSpec {
+    readonly version: "1";
+    readonly backend: RuntimeBackendId;
+    readonly vendor: NativeVendor;
+    readonly executables: Readonly<Partial<Record<NativeExecutableName, NativeExecutableIdentity>>>;
+    readonly toolDirectories: readonly string[];
+    readonly workspace: string;
+    readonly project?: {
+        readonly identity: string;
+        readonly path: string;
+        readonly generation: number;
+        readonly revision: string;
+    };
+    readonly sessionWrenHome?: string;
+    readonly mcp?: {
+        readonly credentialEnvironmentVariable: "WARBLE_MCP_CONNECTION_CREDENTIAL";
+        readonly credential: string;
+    };
+    readonly terminal: {
+        readonly TERM: "xterm-256color";
+        readonly COLORTERM: "truecolor";
+    };
+    readonly childEnvironment: NativeChildEnvironment;
+}
+export declare function attestNativeExecutable(name: NativeExecutableName, executable: string): NativeExecutableIdentity;
+export declare function assertNativeExecutableIdentity(identity: NativeExecutableIdentity): void;
+export declare function resolveNativeExecutable(name: NativeExecutableName, executable: string, pathValue: string | undefined): NativeExecutableIdentity | undefined;
+export interface NativeChildEnvironmentInput {
+    readonly toolDirectories: readonly string[];
+    readonly home: string;
+    readonly projectPath?: string;
+    readonly wrenHome?: string;
+    readonly codexHome?: string;
+    readonly mcpCredential?: string;
+    readonly setupBootstrapRoot?: string;
+    readonly python?: boolean;
+}
+export declare function buildNativeChildEnvironment(input: NativeChildEnvironmentInput): NativeChildEnvironment;
+export interface NativeRuntimeSpecInput {
+    readonly backend: RuntimeBackendId;
+    readonly vendor: NativeVendor;
+    readonly executables: readonly NativeExecutableIdentity[];
+    readonly toolDirectories: readonly string[];
+    readonly workspace: string;
+    readonly home: string;
+    readonly binding?: EnrichmentBinding;
+    readonly sessionWrenHome?: string;
+    readonly codexHome?: string;
+    readonly mcpCredential?: string;
+    readonly setupBootstrapRoot?: string;
+}
+/** Build the sealed launch object exclusively from server-owned inputs. */
+export declare function buildNativeRuntimeSpec(input: NativeRuntimeSpecInput): NativeRuntimeSpec;
+/** Revalidate identities and the derived environment immediately before spawn. */
+export declare function assertNativeRuntimeSpec(spec: NativeRuntimeSpec): void;

package/dist-server/server/native-runtime-spec.js

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { userInfo } from "node:os";
+import { InteractiveLaunchError } from "./native-session-workspace.js";
+/** Adapt the exact allowlist to Node's index-signature API at the spawn seam. */
+export function nativeProcessEnvironment(environment) {
+    return { ...environment };
+}
+function unavailable() {
+    throw new InteractiveLaunchError("native child environment is invalid");
+}
+function canonicalDirectory(directory) {
+    if (!path.isAbsolute(directory))
+        return unavailable();
+    try {
+        // Parent aliases such as macOS /var -> /private/var are acceptable, but
+        // the admitted directory itself must not be replaceable through a final
+        // symlink component.
+        if (lstatSync(path.resolve(directory)).isSymbolicLink())
+            return unavailable();
+        const canonical = realpathSync(directory);
+        if (!statSync(canonical).isDirectory())
+            return unavailable();
+        return canonical;
+    }
+    catch {
+        return unavailable();
+    }
+}
+function canonicalExecutable(executable) {
+    if (!path.isAbsolute(executable))
+        return unavailable();
+    try {
+        const canonical = realpathSync(executable);
+        const metadata = statSync(canonical);
+        if (!metadata.isFile() || (metadata.mode & 0o111) === 0)
+            return unavailable();
+        return canonical;
+    }
+    catch {
+        return unavailable();
+    }
+}
+function digestExecutable(executable) {
+    return `sha256:${createHash("sha256").update(readFileSync(executable)).digest("hex")}`;
+}
+export function attestNativeExecutable(name, executable) {
+    const canonical = canonicalExecutable(executable);
+    const digest = digestExecutable(canonical);
+    return Object.freeze({ name, executable: canonical, identity: digest, digest });
+}
+export function assertNativeExecutableIdentity(identity) {
+    const current = attestNativeExecutable(identity.name, identity.executable);
+    if (current.executable !== identity.executable || current.identity !== identity.identity || current.digest !== identity.digest)
+        unavailable();
+}
+export function resolveNativeExecutable(name, executable, pathValue) {
+    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 {
+            return attestNativeExecutable(name, candidate);
+        }
+        catch {
+            // Discovery happens once at server composition. Launches consume only
+            // the returned canonical identity and never repeat an ambient PATH lookup.
+        }
+    }
+    return undefined;
+}
+export function buildNativeChildEnvironment(input) {
+    const toolDirectories = [...new Set(input.toolDirectories.map(canonicalDirectory))];
+    if (toolDirectories.length === 0)
+        return unavailable();
+    const environment = {
+        PATH: toolDirectories.join(path.delimiter),
+        HOME: canonicalDirectory(input.home),
+        // Claude locates the macOS login keychain account by username. Derive it
+        // from the OS, never from mutable shell or browser-provided environment.
+        ...(process.platform === "darwin" ? { USER: userInfo().username, LOGNAME: userInfo().username } : {}),
+        TERM: "xterm-256color",
+        COLORTERM: "truecolor",
+        ...(input.projectPath ? { WREN_PROJECT_HOME: canonicalDirectory(input.projectPath) } : {}),
+        ...(input.wrenHome ? { WREN_HOME: canonicalDirectory(input.wrenHome) } : {}),
+        ...(input.codexHome ? { CODEX_HOME: canonicalDirectory(input.codexHome) } : {}),
+        ...(input.mcpCredential ? { WARBLE_MCP_CONNECTION_CREDENTIAL: input.mcpCredential } : {}),
+        ...(input.setupBootstrapRoot ? { WARBLE_SETUP_BOOTSTRAP_ROOT: canonicalDirectory(input.setupBootstrapRoot) } : {}),
+        ...(input.python ? { PYTHONNOUSERSITE: "1", PYTHONUTF8: "1" } : {}),
+    };
+    return Object.freeze(environment);
+}
+/** Build the sealed launch object exclusively from server-owned inputs. */
+export function buildNativeRuntimeSpec(input) {
+    if (input.executables.length === 0)
+        return unavailable();
+    const executables = {};
+    for (const executable of input.executables) {
+        assertNativeExecutableIdentity(executable);
+        if (executables[executable.name])
+            return unavailable();
+        executables[executable.name] = executable;
+    }
+    if (!executables.vendor || !executables.producer)
+        return unavailable();
+    const toolDirectories = [...new Set(input.toolDirectories.map(canonicalDirectory))];
+    const workspace = canonicalDirectory(input.workspace);
+    const sessionWrenHome = input.sessionWrenHome ? canonicalDirectory(input.sessionWrenHome) : undefined;
+    const childEnvironment = buildNativeChildEnvironment({
+        toolDirectories,
+        home: input.home,
+        ...(input.binding ? { projectPath: input.binding.path } : {}),
+        ...(sessionWrenHome ? { wrenHome: sessionWrenHome } : {}),
+        ...(input.codexHome ? { codexHome: input.codexHome } : {}),
+        ...(input.mcpCredential ? { mcpCredential: input.mcpCredential } : {}),
+        ...(input.setupBootstrapRoot ? { setupBootstrapRoot: input.setupBootstrapRoot } : {}),
+    });
+    const spec = {
+        version: "1",
+        backend: input.backend,
+        vendor: input.vendor,
+        executables: Object.freeze(executables),
+        toolDirectories: Object.freeze(toolDirectories),
+        workspace,
+        ...(input.binding ? {
+            project: Object.freeze({
+                identity: input.binding.identity,
+                path: canonicalDirectory(input.binding.path),
+                generation: input.binding.generation,
+                revision: input.binding.revision,
+            }),
+        } : {}),
+        ...(sessionWrenHome ? { sessionWrenHome } : {}),
+        ...(input.mcpCredential ? {
+            mcp: Object.freeze({
+                credentialEnvironmentVariable: "WARBLE_MCP_CONNECTION_CREDENTIAL",
+                credential: input.mcpCredential,
+            }),
+        } : {}),
+        terminal: Object.freeze({ TERM: "xterm-256color", COLORTERM: "truecolor" }),
+        childEnvironment,
+    };
+    return Object.freeze(spec);
+}
+/** Revalidate identities and the derived environment immediately before spawn. */
+export function assertNativeRuntimeSpec(spec) {
+    for (const identity of Object.values(spec.executables)) {
+        if (identity)
+            assertNativeExecutableIdentity(identity);
+    }
+    const rebuilt = buildNativeRuntimeSpec({
+        backend: spec.backend,
+        vendor: spec.vendor,
+        executables: Object.values(spec.executables).filter((value) => value !== undefined),
+        toolDirectories: spec.toolDirectories,
+        workspace: spec.workspace,
+        home: spec.childEnvironment.HOME,
+        ...(spec.project ? { binding: { ...spec.project } } : {}),
+        ...(spec.sessionWrenHome ? { sessionWrenHome: spec.sessionWrenHome } : {}),
+        ...(spec.childEnvironment.CODEX_HOME ? { codexHome: spec.childEnvironment.CODEX_HOME } : {}),
+        ...(spec.mcp ? { mcpCredential: spec.mcp.credential } : {}),
+        ...(spec.childEnvironment.WARBLE_SETUP_BOOTSTRAP_ROOT ? { setupBootstrapRoot: spec.childEnvironment.WARBLE_SETUP_BOOTSTRAP_ROOT } : {}),
+    });
+    if (JSON.stringify(rebuilt) !== JSON.stringify(spec))
+        return unavailable();
+    if (lstatSync(spec.workspace).isSymbolicLink())
+        return unavailable();
+}