@wrenai/genbi 0.0.3 → 0.0.5

package/dist-server/server/auth-choice.js

@@ -1,13 +1,16 @@
+import { GATEWAY_API_KEY_ENV } from "./env-detect.js";
 /**
  * Maps the wizard's persisted `RuntimeSettings` to the harness-level `AuthChoice` that should
  * actually be dispatched with. `RuntimeSettings.authMode` is the wire/persisted vocabulary
- * (`"subscription" | "byo" | "local"`); `AuthChoice.mode` is the harness vocabulary
+ * (`"subscription" | "byo" | "local" | "gateway"`); `AuthChoice.mode` is the harness vocabulary
  * (`"subscription" | "api-key" | "local" | "gateway"`) — `"byo"` maps to `"api-key"`.
  *
  * For the `openai-compatible` adapter, the BFF reads `OPENAI_API_KEY` from its own process env
  * and injects it explicitly as `config.apiKey` — that adapter has no env self-read of its own.
  * For `anthropic`, `config.apiKey` is deliberately omitted so the adapter self-reads
  * `ANTHROPIC_API_KEY` from the process env itself (see `harness/providers/adapters/anthropic.ts`).
+ * For `gateway` (the `pi-ai` adapter), the BFF reads `GENBI_GATEWAY_API_KEY` and injects it as
+ * `config.apiKey` the same way — pi-ai never reads env vars or credential files on its own.
  * The key value is never read into `RuntimeSettings`, SQLite, or any log — only referenced here,
  * transiently, to build the in-memory `AuthChoice` passed straight to the adapter factory.
  */
@@ -17,6 +20,19 @@ export function toAuthChoiceFromRuntimeSettings(settings) {
             return { mode: "subscription", provider: settings.subscriptionProvider ?? "claude" };
         case "local":
             return { mode: "local" };
+        case "gateway": {
+            const config = {};
+            if (settings.gatewayProvider !== undefined)
+                config["provider"] = settings.gatewayProvider;
+            if (settings.gatewayModel !== undefined)
+                config["model"] = settings.gatewayModel;
+            if (settings.gatewayBaseURL?.trim())
+                config["baseUrl"] = settings.gatewayBaseURL;
+            const apiKey = process.env[GATEWAY_API_KEY_ENV];
+            if (apiKey?.trim())
+                config["apiKey"] = apiKey;
+            return { mode: "gateway", config };
+        }
         case "byo": {
             const adapter = settings.apiKeyAdapter ?? "anthropic";
             if (adapter === "openai-compatible") {
@@ -34,3 +50,52 @@ export function toAuthChoiceFromRuntimeSettings(settings) {
         }
     }
 }
+const RUNTIME_AUTH_MODES = new Set(["subscription", "byo", "local", "gateway"]);
+/** True for the wire `authMode` values `toAuthChoiceFromRuntimeSettings` can map. */
+export function isRuntimeAuthMode(value) {
+    return typeof value === "string" && RUNTIME_AUTH_MODES.has(value);
+}
+function stringField(config, key) {
+    const value = config?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+/**
+ * The inverse of `toAuthChoiceFromRuntimeSettings`, for reporting the auth the BFF booted with
+ * (`WREN_HARNESS_MODE` / `MODEL` / `ENDPOINT` / flags) before the user has saved a runtime.
+ * Overlays only the auth-selection fields onto `base`; tier rows, deployment and hybrid stay the
+ * store's. Credentials never appear in the result. A boot adapter the wizard cannot represent
+ * leaves `base` untouched.
+ */
+export function runtimeSettingsFromAuthChoice(choice, base) {
+    switch (choice.mode) {
+        case "subscription":
+            return { ...base, authMode: "subscription", subscriptionProvider: choice.provider };
+        case "local":
+            return { ...base, authMode: "local" };
+        case "gateway": {
+            const provider = stringField(choice.config, "provider");
+            const model = stringField(choice.config, "model");
+            const baseURL = stringField(choice.config, "baseUrl");
+            return {
+                ...base,
+                authMode: "gateway",
+                ...(provider !== undefined ? { gatewayProvider: provider } : {}),
+                ...(model !== undefined ? { gatewayModel: model } : {}),
+                ...(baseURL !== undefined ? { gatewayBaseURL: baseURL } : {}),
+            };
+        }
+        case "api-key": {
+            if (choice.adapter !== "anthropic" && choice.adapter !== "openai-compatible")
+                return base;
+            const model = stringField(choice.config, "model");
+            const baseURL = choice.adapter === "openai-compatible" ? stringField(choice.config, "baseURL") : undefined;
+            return {
+                ...base,
+                authMode: "byo",
+                apiKeyAdapter: choice.adapter,
+                ...(model !== undefined ? { apiKeyModel: model } : {}),
+                ...(baseURL !== undefined ? { apiKeyBaseURL: baseURL } : {}),
+            };
+        }
+    }
+}

package/dist-server/server/bin.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import { createCodexRuntimeComposition, readCodexBootConfiguration } from "./codex-runtime-composition.js";
+import { createCodexStructuredAdapter } from "./codex-structured-ask.js";
+import { StructuredRuntime } from "./structured-runtime.js";
+import { shutdownNativeResources } from "./native-shutdown.js";
 /**
  * The BFF's process entrypoint. This is the ONLY file
  * in `server/` that wires real production values (env vars, a real `Store`
@@ -30,15 +34,21 @@
  *                               clear 500 at dispatch time instead.
  *   WREN_HARNESS_PROFILE        profileSource; default resolveDefaultProfileSource()
  *   WREN_HARNESS_MODE           subscription|api-key|local|gateway (auth mode)
- *   WREN_HARNESS_PROVIDER       subscription provider: claude|codex
+ *   WREN_HARNESS_PROVIDER       subscription provider: claude|codex; gateway mode: pi-ai provider id
  *   WREN_HARNESS_ADAPTER        api-key adapter name
  *   WREN_HARNESS_API_KEY        api-key credential
  *   WREN_HARNESS_MODEL          model override
- *   WREN_HARNESS_ENDPOINT       local/gateway endpoint URL
+ *   WREN_HARNESS_ENDPOINT       local endpoint URL; gateway mode: optional custom base URL
+ *   GENBI_GATEWAY_API_KEY       gateway-mode credential for the selected pi-ai provider. Read by
+ *                               the BFF and passed per request; never persisted, and pi-ai's own
+ *                               provider env vars / credential files are never consulted
  *   WREN_HARNESS_WARBLE_BIN     path to the warble CLI binary
- *   WREN_HARNESS_WREN_SHIM      optional absolute server-owned Wren shim for
- *                               native Codex runtime permissions; defaults to
- *                               the fixed local installation when unset
+ *   WREN_HARNESS_CONTEXT_LOADER_BIN
+ *                               path to the wren-context-loader binary, which renders the bound
+ *                               wren project into the prepared-context document a `kind: prepared`
+ *                               binding reads. Falls back to this repo's own Rust build; resolution
+ *                               loud-fails rather than degrading to Warble's built-in MDL adapter
+ *                               (see harness/compile/context-loader.ts)
  *   WREN_HARNESS_AGENT_SDK_BIN  path to the agent-sdk CLI binary (dispatched)
  *   WREN_HARNESS_CODEX_LOCAL_BIN path to the warble-codex-local dispatcher CLI
  *   WREN_HARNESS_CODEX_BIN       optional path to the Codex CLI used by that dispatcher
@@ -95,7 +105,8 @@
  */
 import { serve } from "@hono/node-server";
 import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { WebSocketServer } from "ws";
@@ -104,7 +115,10 @@ import { buildTierBindingFromFlags, parseChatTimeoutMs, parseSetupMaxTurns, reso
 import { createApp } from "./app.js";
 import { recoverBootstrapProjectBinding } from "./bootstrap-project-binding.js";
 import { createHarnessProfileSources } from "./harness-profile-sources.js";
+import { ProfileRegistry } from "./profile-registry.js";
+import { getWarbleIdentity } from "../harness/compile/warble-identity.js";
 import { compileProfile, compileRawProfile } from "../harness/compile/index.js";
+import { resolveWarbleBinary } from "../harness/compile/resolve-binary.js";
 import { toAuthChoiceFromRuntimeSettings } from "./auth-choice.js";
 import { Store } from "./db.js";
 import { resolveEnrichmentBinding, resolveProjectIdentity } from "./enrichment.js";
@@ -113,6 +127,9 @@ import { dispatchInteractiveArtifacts, getInteractiveTerminalReadiness, Interact
 import { createProbedPtyFactory, ensureDarwinNodePtySpawnHelper } from "./node-pty-host.js";
 import { NativeSessionService } from "./native-sessions.js";
 import { NativeArtifactService } from "./native-artifacts.js";
+import { RuntimeHost } from "./runtime-host/local.js";
+import { resolveManagedWrenRuntime } from "./managed-wren-runtime.js";
+import { assertNativeExecutableIdentity, assertNativeRuntimeSpec, attestNativeExecutable, buildNativeChildEnvironment, buildNativeRuntimeSpec, resolveNativeExecutable } from "./native-runtime-spec.js";
 import { initializeNativeSessionStateBase, legacyInteractiveWorkspace, validateLegacyInteractiveWorkspace } from "./native-session-workspace.js";
 import { codexModelsForRuntime, compileUnboundProfileTierNames, effectiveTierModel, materializeRuntimeRouteOptions, } from "./runtime-binding.js";
 import { invalidateBundleAgentIdsCache } from "./turn.js";
@@ -170,6 +187,42 @@ async function main() {
     // (server/turn.ts) and `server/spa.ts`.
     const candidateStaticDir = path.join(packageRoot, "dist");
     const staticDir = existsSync(path.join(candidateStaticDir, "index.html")) ? candidateStaticDir : undefined;
+    // Resolve the Warble binary once, here, and hand the resolved path to every
+    // consumer. Passing the bare name `"warble"` looked like a harmless default and
+    // was not: `resolveWarbleBinary` treats any value it is given as an explicit
+    // path and only searches when given nothing, so that default disabled the one
+    // lookup that finds the `@warble/cli` an install actually ships. It also made
+    // two resolvers disagree about the same string — the native preflight resolves
+    // a bare name through PATH and reported the producer healthy, while every
+    // compile failed.
+    const resolvedWarbleBin = await resolveWarbleBinary(flags.warbleBin).catch((error) => {
+        // Not fatal: the app still starts, and readiness reports the reason per
+        // vendor rather than the process dying at boot over a feature the user may
+        // not reach.
+        process.stderr.write(`warning: ${error instanceof Error ? error.message : String(error)}\n`);
+        return undefined;
+    });
+    const warbleBinOption = resolvedWarbleBin !== undefined ? { warbleBin: resolvedWarbleBin } : {};
+    const nativeHome = realpathSync(os.homedir());
+    const nodeExecutable = attestNativeExecutable("node", process.execPath);
+    const producerExecutable = resolvedWarbleBin ? attestNativeExecutable("producer", resolvedWarbleBin) : undefined;
+    const bootPath = process.env["PATH"];
+    const claudeExecutable = resolveNativeExecutable("vendor", "claude", bootPath);
+    const codexExecutable = resolveNativeExecutable("vendor", "codex", bootPath);
+    const vendorExecutables = Object.freeze({
+        ...(claudeExecutable ? { claude: claudeExecutable } : {}),
+        ...(codexExecutable ? { codex: codexExecutable } : {}),
+    });
+    const nativeWrenExecutable = resolveNativeExecutable("wren", "wren", bootPath);
+    const nativeToolDirectories = Object.freeze([...new Set([
+            path.dirname(nodeExecutable.executable),
+            // Native auth and CLI tools need fixed OS utilities, even with a sanitized PATH.
+            ...(["darwin", "linux"].includes(process.platform) ? ["/usr/bin", "/bin", "/usr/sbin", "/sbin"].map((directory) => realpathSync(directory)) : []),
+            ...(nativeWrenExecutable ? [path.dirname(nativeWrenExecutable.executable)] : []),
+            ...Object.values(vendorExecutables).filter((value) => value !== undefined).map((value) => path.dirname(value.executable)),
+            ...(producerExecutable ? [path.dirname(producerExecutable.executable)] : []),
+        ])]);
+    const nativeHostEnvironment = buildNativeChildEnvironment({ toolDirectories: nativeToolDirectories, home: nativeHome });
     const profileSource = flags.profile ?? resolveDefaultProfileSource();
     // Frozen at boot: GET /api/harness accepts only a purpose and must never
     // inherit a caller-supplied RouteOptions.profileSource.
@@ -186,6 +239,19 @@ async function main() {
     // Initialization creates the fixed private namespaces once at startup.
     const nativeMaterializationState = initializeNativeSessionStateBase(dbPath);
     const store = new Store(dbPath);
+    // Conversation profiles a session may start inside: the shipped ones under this package's
+    // `profiles/` plus any the operator adds under the workspace. Registration compiles each one, so
+    // it runs in the background; the first `/api/profiles` request awaits the same promise.
+    const profileRegistry = new ProfileRegistry({
+        store,
+        builtinProfilesDir: path.dirname(harnessProfileSources.analysis),
+        userProfilesDir: path.join(workspaceRoot, "profiles"),
+        compileRaw: (source) => compileRawProfile({ profileSource: source, mode: "native", ...warbleBinOption }),
+        warbleIdentity: async () => (resolvedWarbleBin !== undefined ? getWarbleIdentity(resolvedWarbleBin) : "warble:unresolved"),
+    });
+    void profileRegistry.ensureReady().catch((error) => {
+        process.stderr.write(`warning: profile registry failed to initialize: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
     const getCodexModels = () => codexModelsForRuntime(store.getRuntimeSettings());
     const getRuntimeTierNames = () => compileUnboundProfileTierNames({
         profileSource,
@@ -243,9 +309,11 @@ async function main() {
         boundProject = identity.path;
         const { revokedNativeSessionIds } = store.activateEnrichmentBindingAndRevokeBoundNativeSessions(identity);
         nativeSessions.revokeBindingCapabilities(revokedNativeSessionIds);
+        deps?.structuredRuntime?.revoke();
         invalidateBundleAgentIdsCache(deps);
     }
     function unbindProject() {
+        deps?.structuredRuntime?.revoke();
         boundProject = undefined;
         invalidateBundleAgentIdsCache(deps);
     }
@@ -274,6 +342,10 @@ async function main() {
     // a reset) later in the same boot. The actual logic lives in `./wren-home.js` so it's directly
     // unit-testable without going through a mocked `TurnDeps`.
     const originalWrenHome = process.env["WREN_HOME"];
+    const operatorWrenHome = originalWrenHome?.trim() || path.join(nativeHome, ".wren");
+    const nativeSourceWrenHome = () => store.getSetupMode() === "create"
+        ? path.join(workspaceRoot, ".wren")
+        : operatorWrenHome;
     const setWrenHomeForSetupMode = createSetWrenHomeForSetupMode(workspaceRoot, originalWrenHome);
     // Mutable auth-choice binding — the auth-choice mirror of boundProject above. Starts at the
     // boot-resolved `authChoice` and can be rebound later by PUT /api/config/runtime
@@ -436,7 +508,12 @@ async function main() {
             try {
                 const require = createRequire(import.meta.url);
                 ensureDarwinNodePtySpawnHelper(require.resolve("node-pty"));
-                return await createProbedPtyFactory(await import("node-pty"));
+                assertNativeExecutableIdentity(nodeExecutable);
+                return await createProbedPtyFactory(await import("node-pty"), {
+                    cwd: nativeMaterializationState.root,
+                    env: nativeHostEnvironment,
+                    probeExecutable: nodeExecutable.executable,
+                });
             }
             catch {
                 throw new InteractiveLaunchError("interactive terminal host cannot spawn local processes on this machine");
@@ -453,14 +530,24 @@ async function main() {
     async function prepareInteractiveTerminal(target, binding) {
         if (enrichIrPath === undefined)
             throw new InteractiveLaunchError("interactive enrichment artifacts are not configured");
+        if (producerExecutable === undefined)
+            throw new InteractiveLaunchError("interactive enrichment materialization failed");
         const artifactRoot = legacyInteractiveWorkspace(nativeMaterializationState, binding.path, target);
+        const dispatchEnvironment = buildNativeChildEnvironment({
+            toolDirectories: nativeToolDirectories,
+            home: nativeHome,
+            projectPath: binding.path,
+        });
         return prepareInteractiveHandoff({
             target,
             binding,
             artifactRoot,
             materializationState: nativeMaterializationState,
-            materialize: () => dispatchInteractiveArtifacts({ warbleBin: flags.warbleBin ?? "warble", irPath: enrichIrPath, target, cwd: artifactRoot, boundProject: binding.path, materializationState: nativeMaterializationState }),
-        }, { getCurrentBinding: currentInteractiveBinding });
+            materialize: () => dispatchInteractiveArtifacts({ producer: producerExecutable, irPath: enrichIrPath, target, cwd: artifactRoot, env: dispatchEnvironment, boundProject: binding.path, materializationState: nativeMaterializationState }),
+        }, {
+            getCurrentBinding: currentInteractiveBinding,
+            resolveExecutable: (executable) => executable === "claude" ? vendorExecutables.claude : vendorExecutables.codex,
+        });
     }
     const nativeMcpUrl = `http://127.0.0.1:${port}/api/native-sessions/mcp`;
     const nativeArtifacts = new NativeArtifactService({
@@ -470,6 +557,27 @@ async function main() {
         mcpUrl: process.env["WREN_HARNESS_NATIVE_MCP_URL"] ?? nativeMcpUrl,
         getBinding: currentInteractiveBinding,
     });
+    const nativeTerminalHostAvailable = async () => {
+        try {
+            await loadPty();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    // This is the sole production composition of the Phase-1 policy. Browser
+    // requests never reach this selection or its executable/policy inputs.
+    const codexConfiguration = readCodexBootConfiguration(process.env);
+    const codexComposition = createCodexRuntimeComposition({ configuration: codexConfiguration, packageRoot,
+        producerBinary: producerExecutable?.executable ?? "", profileSource: harnessProfileSources.analysis, store,
+        getBinding: currentInteractiveBinding, sourceWrenHome: nativeSourceWrenHome, artifacts: nativeArtifacts });
+    const nativeRuntimeHost = new RuntimeHost({
+        selected: codexConfiguration.selected,
+        deployment: process.env["NODE_ENV"] === "production" ? "production" : "development",
+        localAvailable: () => codexConfiguration.allowLocal ? nativeTerminalHostAvailable() : false,
+        vendorProbes: { "codex-app-server": codexComposition.probe },
+    });
     const nativeSessions = new NativeSessionService({
         store,
         terminalManager,
@@ -486,30 +594,56 @@ async function main() {
         // Setup has no binding by definition, so it compiles the profile's authored
         // context with no user project composed in; its golden resolves nothing
         // either, which is why Setup never showed this symptom.
-        resolveDispatchIr: async (purpose, binding) => {
-            const profileSource = harnessProfileSources[purpose];
+        resolveDispatchIr: async (purpose, binding, selectedProfileSource) => {
+            // A selected conversation profile compiles from the registry's copy; everything else from the
+            // boot-time source for its purpose.
+            const profileSource = selectedProfileSource ?? harnessProfileSources[purpose];
             const compiled = purpose === "setup" || binding === undefined
-                ? await compileRawProfile({ profileSource, mode: "native", warbleBin: flags.warbleBin ?? "warble" })
-                : await compileProfile({ profileSource, userProject: binding.path, mode: "native", warbleBin: flags.warbleBin ?? "warble" });
+                ? await compileRawProfile({ profileSource, mode: "native", ...warbleBinOption })
+                : await compileProfile({ profileSource, userProject: binding.path, mode: "native", ...warbleBinOption });
             return compiled.irPath;
         },
-        warbleBin: flags.warbleBin ?? "warble",
-        ...(process.env["WREN_HARNESS_WREN_SHIM"] !== undefined ? { wrenShim: process.env["WREN_HARNESS_WREN_SHIM"] } : {}),
-        terminalHostAvailable: async () => {
-            try {
-                await loadPty();
-                return true;
-            }
-            catch {
-                return false;
-            }
+        resolveConversationProfile: async (id) => {
+            const { row, sourceDir } = await profileRegistry.resolveConversationProfileSource(id);
+            return { id: row.id, sourceDir, entry: row.entryKind === "agent" && row.entryVerb !== null ? { kind: "agent", verb: row.entryVerb } : { kind: "scope" } };
         },
+        listConversationProfiles: async () => (await profileRegistry.list())
+            .filter((row) => row.role === "conversation")
+            .map((row) => ({
+            id: row.id,
+            selectable: row.admissionStatus === "admitted",
+            ...(row.admissionReason !== null ? { reason: row.admissionReason } : {}),
+            ...(row.entryKind !== null ? { entryKind: row.entryKind } : {}),
+            ...(row.entryVerb !== null ? { entryVerb: row.entryVerb } : {}),
+        })),
+        // The service's option is a required string; when resolution failed the bare
+        // name is what the preflight will report as unresolvable, with its reason.
+        warbleBin: producerExecutable?.executable ?? "warble",
+        terminalHostAvailable: nativeTerminalHostAvailable,
+        runtimeHost: nativeRuntimeHost,
+        directCodex: codexComposition.native,
+        resolveManagedCodexWrenRuntime: () => resolveManagedWrenRuntime({ packageRoot }),
+        nativeHome,
+        sourceWrenHome: nativeSourceWrenHome,
+        ...(baseRouteOptions.codexHome ? { codexHome: baseRouteOptions.codexHome } : {}),
+        vendorExecutables,
+        nodeExecutable,
+        childToolDirectories: nativeToolDirectories,
+        ...(bootPath !== undefined ? { pathValue: bootPath } : {}),
         artifactService: nativeArtifacts,
     });
+    // Explicit opt-in remains behind the packaged exact-version certification gate.
+    const structuredRuntime = new StructuredRuntime({
+        selected: { codex: codexConfiguration.selected, claude: "local" }, allowLocal: codexConfiguration.allowLocal, deployment,
+        adapters: { codex: createCodexStructuredAdapter(codexComposition.structured) },
+        localRoute: route, localSetupFor: (choice) => setupRunnerFor?.(choice) ?? setupRunner,
+    });
     deps = {
         store,
+        structuredRuntime,
         nativeSessions,
         nativeArtifacts,
+        profileRegistry,
         route,
         baseRouteOptions,
         describeBundle: (options) => {
@@ -521,8 +655,8 @@ async function main() {
                     : {}),
             });
         },
-        describeHarnessBundle: (purpose, options) => {
-            const profileSource = harnessProfileSources[purpose];
+        describeHarnessBundle: (purpose, options, selectedProfileSource) => {
+            const profileSource = selectedProfileSource ?? harnessProfileSources[purpose];
             const common = {
                 ...options,
                 profileSource,
@@ -551,7 +685,24 @@ async function main() {
             const { spec } = await prepareInteractiveTerminal(target, binding);
             const manager = await terminalManager();
             validateLegacyInteractiveWorkspace(nativeMaterializationState, binding.path, spec.cwd);
-            return manager.start(spec, undefined, { ...process.env, WREN_PROJECT_HOME: binding.path });
+            if (producerExecutable === undefined || spec.hostExecutable === undefined)
+                throw new InteractiveLaunchError("interactive enrichment materialization failed");
+            const runtimeSpec = buildNativeRuntimeSpec({
+                backend: "local",
+                vendor: target === "claude-code:interactive" ? "claude" : "codex",
+                executables: [
+                    nodeExecutable,
+                    producerExecutable,
+                    attestNativeExecutable("vendor", spec.hostExecutable),
+                ],
+                toolDirectories: nativeToolDirectories,
+                workspace: spec.cwd,
+                home: nativeHome,
+                binding,
+                ...(target === "codex:interactive" && baseRouteOptions.codexHome ? { codexHome: baseRouteOptions.codexHome } : {}),
+            });
+            assertNativeRuntimeSpec(runtimeSpec);
+            return manager.start(spec, undefined, runtimeSpec.childEnvironment);
         },
         prepareInteractiveTerminal: async ({ target, binding }) => {
             return (await prepareInteractiveTerminal(target, binding)).handoff;
@@ -573,6 +724,7 @@ async function main() {
                         return false;
                     }
                 },
+                resolveExecutable: (executable) => executable === "claude" ? vendorExecutables.claude : vendorExecutables.codex,
             });
         },
         workspaceRoot,
@@ -586,6 +738,25 @@ async function main() {
     const server = serve({ fetch: app.fetch, websocket: { server: websocket }, hostname: "127.0.0.1", port }, (info) => {
         process.stdout.write(`wren-harness BFF listening on http://127.0.0.1:${info.port} (db: ${dbPath})\n`);
     });
+    const shutdown = () => {
+        const deadline = setTimeout(() => process.exit(1), 12_000);
+        void shutdownNativeResources({
+            shutdownSessions: async () => {
+                const results = await Promise.allSettled([nativeSessions.shutdown(), structuredRuntime.shutdown(), codexComposition.shutdown()]);
+                if (results.some((result) => result.status === "rejected"))
+                    throw new Error("Session cleanup failed");
+            },
+            closeTerminals: () => interactiveTerminal?.closeAll(),
+            closeServer: () => { server.close(); },
+        }).then((code) => {
+            if (code)
+                process.stderr.write("error: native session cleanup did not complete\n");
+            clearTimeout(deadline);
+            process.exit(code);
+        });
+    };
+    process.once("SIGTERM", shutdown);
+    process.once("SIGINT", shutdown);
     // Without this, a port that is already taken surfaces as an unhandled 'error' event and a raw
     // Node stack trace -- the first thing a new user is likely to hit, and the least readable.
     server.on("error", (error) => {

package/dist-server/server/codex-local-grounding.d.ts

@@ -0,0 +1,18 @@
+import type { HostQueryObservation } from "../harness/route/codex-host-query.js";
+import { type RenderEnvelope } from "../harness/render/envelope.js";
+/**
+ * Grounds a codex:local answer against the queries this turn's host query service executed,
+ * with the component path's predicate (`citedGroundedQuery`: a tool-proven definition that
+ * reads at least one table, cited by `query_id`, else by whitespace-insensitive SQL).
+ *
+ * Verified only when the answer cites at least one query and every citation grounds. The
+ * envelope is then rebuilt from the observations alone: one `table` and one `definition` block
+ * (carrying the observed `query_id`) per cited query, plus the model's `summary` text as written.
+ * A cited result the host saw truncated still grounds the rows it shows; the host then appends
+ * a note to `summary`, the only place the render contract carries such text. Anything else stays the model's answer with
+ * `verified: false`: no citation, a citation to a query this turn never ran (including one from
+ * an earlier turn), a query that read no table, or chart / KPI blocks the host cannot rebuild.
+ */
+export declare function groundCodexLocalEnvelope(envelope: RenderEnvelope, finalText: string, observations: readonly HostQueryObservation[]): RenderEnvelope;
+/** Host-written, never model-written: a cited table that is only the first rows of its result. */
+export declare function truncationNote(shown: number): string;

package/dist-server/server/codex-local-grounding.js

@@ -0,0 +1,92 @@
+import { citedGroundedQuery } from "../harness/components/normalize.js";
+import { extractJsonCandidateFromText } from "../harness/render/envelope.js";
+import { namedAnswerQueryId, namedAnswerSql, sqlKey } from "../harness/render/answering-query.js";
+/** Blocks whose values the host cannot rebuild from one observed table; their presence leaves an answer unverified. */
+const UNREBUILDABLE_DATA_BLOCKS = new Set(["chart", "kpi_card"]);
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * The queries a codex:local answer names. A `{blocks}` answer cites through its `definition`
+ * blocks; a flat or query-result answer through its own `definition` / top-level fields, read
+ * from the raw text because envelope normalization drops a cited `query_id`. A host id wins over
+ * SQL, like the component path.
+ */
+function citations(envelope, finalText) {
+    const raw = extractJsonCandidateFromText(finalText);
+    if (!Array.isArray(record(raw)?.blocks)) {
+        const queryId = namedAnswerQueryId(raw);
+        if (queryId !== undefined)
+            return [{ queryId }];
+        const sql = namedAnswerSql(raw);
+        return sql !== undefined ? [{ sql }] : [];
+    }
+    const found = [];
+    const seen = new Set();
+    for (const block of Array.isArray(envelope.blocks) ? envelope.blocks : []) {
+        const fields = record(block);
+        if (fields?.type !== "definition")
+            continue;
+        const queryId = typeof fields.query_id === "string" && fields.query_id.length > 0 ? fields.query_id : undefined;
+        const sql = typeof fields.sql === "string" && fields.sql.trim() ? fields.sql : undefined;
+        const citation = queryId !== undefined ? { queryId } : sql !== undefined ? { sql } : undefined;
+        if (!citation)
+            continue;
+        const key = queryId !== undefined ? `id:${queryId}` : `sql:${sqlKey(sql)}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        found.push(citation);
+    }
+    return found;
+}
+/**
+ * Grounds a codex:local answer against the queries this turn's host query service executed,
+ * with the component path's predicate (`citedGroundedQuery`: a tool-proven definition that
+ * reads at least one table, cited by `query_id`, else by whitespace-insensitive SQL).
+ *
+ * Verified only when the answer cites at least one query and every citation grounds. The
+ * envelope is then rebuilt from the observations alone: one `table` and one `definition` block
+ * (carrying the observed `query_id`) per cited query, plus the model's `summary` text as written.
+ * A cited result the host saw truncated still grounds the rows it shows; the host then appends
+ * a note to `summary`, the only place the render contract carries such text. Anything else stays the model's answer with
+ * `verified: false`: no citation, a citation to a query this turn never ran (including one from
+ * an earlier turn), a query that read no table, or chart / KPI blocks the host cannot rebuild.
+ */
+export function groundCodexLocalEnvelope(envelope, finalText, observations) {
+    const unverified = { ...envelope, verified: false };
+    if (observations.length === 0)
+        return unverified;
+    const blocks = Array.isArray(envelope.blocks) ? envelope.blocks : [];
+    if (blocks.some((block) => UNREBUILDABLE_DATA_BLOCKS.has(String(record(block)?.type))))
+        return unverified;
+    const cited = citations(envelope, finalText);
+    if (cited.length === 0)
+        return unverified;
+    const rebuilt = [];
+    const notes = [];
+    for (const citation of cited) {
+        const query = citedGroundedQuery(observations, citation);
+        if (!query)
+            return unverified;
+        const observation = observations.find((call) => call.output?.query_id === query.queryId);
+        if (observation?.output?.truncated === true)
+            notes.push(truncationNote(query.table.rows.length));
+        // The definition keeps the observed query's host id, so grounding the rebuilt envelope
+        // again (the artifact path does) resolves to the very same observation.
+        rebuilt.push({ type: "table", columns: query.table.columns, rows: query.table.rows }, { type: "definition", ...query.definition, ...(query.queryId !== undefined ? { query_id: query.queryId } : {}) });
+    }
+    const summary = withNotes(typeof envelope.summary === "string" ? envelope.summary : undefined, notes);
+    return { blocks: rebuilt, ...(summary !== undefined ? { summary } : {}), verified: true };
+}
+/** Host-written, never model-written: a cited table that is only the first rows of its result. */
+export function truncationNote(shown) {
+    return `Host note: this query returned more than ${shown} rows; the table shows only the first ${shown}.`;
+}
+/** Appends each host note once, so grounding an already-grounded envelope again changes nothing. */
+function withNotes(summary, notes) {
+    const missing = [...new Set(notes)].filter((note) => !summary?.includes(note));
+    if (missing.length === 0)
+        return summary;
+    return [summary, ...missing].filter((part) => part !== undefined && part.length > 0).join("\n\n");
+}

package/dist-server/server/codex-native-session.d.ts

@@ -0,0 +1,25 @@
+import type { CodexAppServerBackend, CodexLaunchPermit } from "./runtime-host/codex-app-server.js";
+import type { CodexSessionTools } from "./runtime-host/codex-direct-tools.js";
+import type { EnrichmentBinding } from "./enrichment.js";
+import type { NativeSessionRow } from "./db.js";
+/** Server-only provisioner. A ready probe alone never authorizes materialization. */
+export interface DirectCodexProvisioner {
+    /** Official remote CLI renderer; the host still owns the governed thread. */
+    readonly terminal?: boolean;
+    readonly terminalCertified?: (entry: string) => boolean;
+    readonly backend: Pick<CodexAppServerBackend, "prepareLaunch" | "open">;
+    /** Own and clean partial allocations on failure. Never receives browser paths or credentials. */
+    prepare(input: {
+        readonly session: NativeSessionRow;
+        readonly binding: EnrichmentBinding;
+        readonly permit: CodexLaunchPermit;
+        readonly signal: AbortSignal;
+        readonly assertActive: () => void;
+    }): Promise<{
+        readonly input: Omit<Parameters<CodexAppServerBackend["open"]>[1], "onEvent" | "tools"> & {
+            readonly tools: CodexSessionTools;
+        };
+        /** Runs after the conversation and scoped tools have closed. */
+        dispose(): Promise<void>;
+    }>;
+}

package/dist-server/server/codex-native-session.js

@@ -0,0 +1 @@
+export {};

package/dist-server/server/codex-runtime-composition.d.ts

@@ -0,0 +1,34 @@
+import type { Store } from "./db.js";
+import type { EnrichmentBinding } from "./enrichment.js";
+import type { NativeArtifactService } from "./native-artifacts.js";
+import type { RuntimeBackendProbeResult } from "./runtime-host/types.js";
+import type { DirectCodexProvisioner } from "./codex-native-session.js";
+import type { CodexStructuredProvisioner } from "./codex-structured-ask.js";
+export interface CodexBootConfiguration {
+    readonly selected: "local" | "codex-app-server";
+    readonly allowLocal: boolean;
+    readonly executable?: string;
+    readonly source?: string;
+    readonly loginHome?: string;
+    readonly accountEmail?: string;
+}
+/** Read once at composition. No browser values, PATH discovery or credential copying. */
+export declare function readCodexBootConfiguration(env: NodeJS.ProcessEnv): CodexBootConfiguration;
+interface Options {
+    readonly configuration: CodexBootConfiguration;
+    readonly packageRoot: string;
+    readonly producerBinary: string;
+    readonly profileSource: string;
+    readonly store: Store;
+    readonly getBinding: () => EnrichmentBinding | undefined;
+    readonly sourceWrenHome: () => string;
+    readonly artifacts: NativeArtifactService;
+}
+/** Real composition for both entry surfaces; certification is enforced by the packaged backend. */
+export declare function createCodexRuntimeComposition(options: Options): {
+    probe: () => Promise<RuntimeBackendProbeResult<"codex-app-server">>;
+    native: DirectCodexProvisioner;
+    structured: CodexStructuredProvisioner;
+    shutdown: () => Promise<void>;
+};
+export {};