@wrenai/genbi 0.0.1

package/dist-server/harness/setup/runner.js

@@ -0,0 +1,1314 @@
+/**
+ * Agentic setup/connect flow — BFF wiring.
+ *
+ * The Setup wizard's CONNECT step onboards a NEW wren project by dispatching
+ * warble's `connect_source` component via a dispatched (claude-agent-sdk)
+ * subprocess. Design decisions this file encodes (see the ticket for full
+ * rationale):
+ *
+ *  - Setup state lives on disk (the scaffolded project + its `.env`), not
+ *    only in the agent conversation: each setup turn is independently
+ *    re-verifiable via `parseSetupTerminal`'s on-disk artifact checks below,
+ *    regardless of which mechanism served the turn. Historically every setup
+ *    turn was ALSO a fresh dispatched dispatch with no SDK-level continuity
+ *    across turns (a disk-state-only "Plan B" re-composition — see
+ *    `server/compose.ts`'s `composeSetupPrompt`'s `resumeFromDisk` option).
+ *    `SetupStepRunOptions.resumeSessionId`/`SetupStepRunResult.sessionId`
+ *    below add the alternative "Plan A": resuming the SAME underlying
+ *    agent-sdk conversation (`DispatchedOptions.resumeSessionId` /
+ *    `DispatchedResult.sessionId`, `../route/dispatched.js`) when a caller has one to
+ *    resume from, so a `max_turns_continue` decision (`server/turn.ts`) can
+ *    give the agent a fresh turn budget without making it re-orient from
+ *    scratch (re-`ls`, re-`Read`, re-fetch skills). Both remain available:
+ *    a caller with no session id to resume gets the original disk-state
+ *    behavior unchanged.
+ *  - The terminal contract (`SETUP_STATUS: ok|needs_input|error`) lives in
+ *    the composed prompt, not in warble — `parseSetupTerminal` below parses
+ *    it back out of the turn's finalText, and independently verifies
+ *    `<root>/<name>/wren_project.yml` on disk before trusting an `ok`.
+ *  - `SetupStepRunner` is a backend-abstract seam: `DispatchedSetupRunner`
+ *    (claude-agent-sdk subprocess, subscription auth) and `InProcessSetupRunner`
+ *    (in-process vercel loop, api-key/local/gateway auth) both implement it,
+ *    and a caller picks between them purely on `authChoice.mode` without
+ *    otherwise caring which one served a given turn.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadBundleWithProvenance } from "../bundle/loader.js";
+import { runWarble } from "../compile/pipeline.js";
+import { resolveWarbleBinary } from "../compile/resolve-binary.js";
+import { createAgentEventEmitter } from "../events/index.js";
+import { createLocalExecutionEnv } from "../exec/index.js";
+import { executeAgent, StepBudgetExhaustedError } from "../loop/index.js";
+// Re-exported: `InProcessSetupRunner.run()` throws this (with an enriched,
+// Mode-A-specific `.message` — see its `catch` block below) whenever the
+// Dispatched agent's step budget is what ended the turn, not the model
+// finishing on its own. Callers that want to distinguish that from any
+// other setup-dispatch failure (e.g. via `instanceof`) can import it from
+// here without also reaching into `harness/loop/index.js`.
+export { StepBudgetExhaustedError };
+import { createDefaultProviderRegistry } from "../providers/index.js";
+import { deriveAdapterSpec } from "../route/adapter-spec.js";
+import { resolveCodexLocalCli } from "../route/codex-local-cli.js";
+import { runDispatchedDefault } from "../route/dispatched.js";
+import { buildUniformTierBinding } from "../route/tier-binding.js";
+import { createNativeToolRegistry, createSetupExecutionTool, SETUP_EXECUTION_TOOL_NAME } from "../tools/index.js";
+import { withResolvedTools } from "../tools/wiring.js";
+import { CodexSetupEventMapper } from "./codex-events.js";
+/** The warble component the setup wizard's connect step dispatches. */
+export const CONNECT_SOURCE_AGENT_ID = "connect_source";
+/** The Warble component the setup wizard's context step dispatches (`profiles/genbi-setup/components/build_context`). */
+export const BUILD_CONTEXT_AGENT_ID = "build_context";
+/**
+ * Default agent-loop budget for setup turns, forwarded as `warble-agent-sdk
+ * chat --max-turns`. Well above the dispatcher's own default (40) because
+ * `build_context` agentically generates an MDL — many read/introspect/write/
+ * build/validate tool calls — and routinely blows past 40, failing the turn
+ * with `error_max_turns`. Overridable via `DispatchedSetupRunnerOptions.maxTurns`
+ * (wired to `WREN_HARNESS_SETUP_MAX_TURNS` in `server/bin.ts`).
+ */
+export const DEFAULT_SETUP_MAX_TURNS = 120;
+/** Single provider-aware selection seam shared by boot wiring and tests. */
+export function selectSetupRunnerForAuth(authChoice, runners) {
+    if (authChoice.mode !== "subscription")
+        return runners.nonSubscription;
+    return authChoice.provider === "codex" ? runners.codexSubscription : runners.claudeSubscription;
+}
+/**
+ * Resolves the `--max-turns` budget for dispatching `agentId`, given an
+ * optional explicit override (`DispatchedSetupRunnerOptions.maxTurns`, wired from
+ * `WREN_HARNESS_SETUP_MAX_TURNS` in `server/bin.ts`). Shared by
+ * `DispatchedSetupRunner.run()` and `DispatchedSetupRunner.effectiveMaxTurns()` so the
+ * two can never disagree.
+ */
+function resolveEffectiveMaxTurns(configuredMaxTurns, agentId) {
+    return configuredMaxTurns ?? (agentId === BUILD_CONTEXT_AGENT_ID ? DEFAULT_SETUP_MAX_TURNS : undefined);
+}
+const SAFE_PROJECT_NAME = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Subscription dispatchers have one cwd per turn, while their guarded setup
+ * tool accepts a separately bounded working root. Keep the initial scaffold
+ * at the workspace root. Immediately before a project-bound dispatch,
+ * canonicalize the existing workspace/project dirs and require the latter to
+ * be a strict descendant of the former. This is a pre-dispatch guard, not a
+ * claim that filesystem paths cannot change after the child process starts.
+ */
+function resolveDispatchedUserProject(runOptions, agentId) {
+    const stepKey = runOptions.stepKey ?? (agentId === BUILD_CONTEXT_AGENT_ID ? "context" : "connect");
+    if (stepKey === "connect")
+        return runOptions.workspaceRoot;
+    const projectName = runOptions.projectName;
+    if (projectName === undefined || !SAFE_PROJECT_NAME.test(projectName)) {
+        throw new Error(`dispatched ${stepKey} requires a validated single-segment projectName`);
+    }
+    const canonicalDirectory = (directory, label) => {
+        if (!existsSync(directory))
+            throw new Error(`dispatched ${stepKey} ${label} must exist before dispatch`);
+        if (!statSync(directory).isDirectory())
+            throw new Error(`dispatched ${stepKey} ${label} must be a directory`);
+        return realpathSync(directory);
+    };
+    const canonicalWorkspace = canonicalDirectory(runOptions.workspaceRoot, "workspace root");
+    const projectDir = path.resolve(runOptions.workspaceRoot, projectName);
+    const canonicalProject = canonicalDirectory(projectDir, "project directory");
+    const relative = path.relative(canonicalWorkspace, canonicalProject);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`dispatched ${stepKey} project directory must be a strict descendant of the setup workspace root`);
+    }
+    return canonicalProject;
+}
+/**
+ * Dispatches a setup-wizard turn over dispatched, bypassing `route()` entirely
+ * (unlike the Ask turn path) so it can perform its own, setup-specific
+ * subscription-mode check with a clear, actionable error message rather than
+ * `route()`'s generic in-process/B branch. Uses `DispatchedOptions.irPath` to skip
+ * `compileProfile` — there is no bound wren project yet during setup, so
+ * there is nothing to compile a profile against; the setup dispatch always
+ * runs the same fixed, warble-committed IR regardless of which project is
+ * being onboarded.
+ */
+export class DispatchedSetupRunner {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    effectiveMaxTurns(agentId) {
+        return resolveEffectiveMaxTurns(this.options.maxTurns, agentId);
+    }
+    async run(runOptions) {
+        const { authChoice } = runOptions;
+        const agentId = runOptions.agentId ?? CONNECT_SOURCE_AGENT_ID;
+        // Only build_context needs the raised turn budget — generating an MDL is
+        // many tool calls. connect/connect_resume stay on the dispatcher's default
+        // (40) so a stuck connect (e.g. bad credentials retrying) still fails fast
+        // rather than burning 3x the runway first. An explicit
+        // DispatchedSetupRunnerOptions.maxTurns override, when set, applies to any turn.
+        // Kept in lockstep with `effectiveMaxTurns()` above via the shared
+        // `resolveEffectiveMaxTurns` helper.
+        const maxTurns = this.effectiveMaxTurns(agentId);
+        if (authChoice.mode !== "subscription") {
+            throw new Error(`Agentic setup requires subscription auth mode (dispatched) to dispatch "${agentId}" ` +
+                `via the claude-agent-sdk dispatcher — got "${authChoice.mode}". Set WREN_HARNESS_MODE=subscription ` +
+                "to enable the setup wizard's connect step.");
+        }
+        const modelsConfig = this.options.getModelsConfig?.();
+        const userProject = resolveDispatchedUserProject(runOptions, agentId);
+        const result = await runDispatchedDefault({
+            authChoice,
+            // Unused: `irPath` below makes `runDispatchedDefault` skip compileProfile
+            // entirely (see its short-circuit), so this value is never read. It is
+            // set to the same setup IR for clarity, not because it is consulted.
+            profileSource: this.options.irPath,
+            userProject,
+            question: runOptions.prompt,
+            agentId,
+            irPath: this.options.irPath,
+            ...(this.options.warbleBin !== undefined ? { warbleBin: this.options.warbleBin } : {}),
+            ...(this.options.agentSdkBin !== undefined ? { agentSdkBin: this.options.agentSdkBin } : {}),
+            ...(this.options.outDir !== undefined ? { outDir: this.options.outDir } : {}),
+            ...(this.options.workDir !== undefined ? { workDir: this.options.workDir } : {}),
+            ...(modelsConfig !== undefined ? { modelsConfig } : {}),
+            ...(maxTurns !== undefined ? { maxTurns } : {}),
+            ...(runOptions.onEvent !== undefined ? { onEvent: runOptions.onEvent } : {}),
+            ...(runOptions.resumeSessionId !== undefined ? { resumeSessionId: runOptions.resumeSessionId } : {}),
+        });
+        return { finalText: result.finalText, ...(result.sessionId !== undefined ? { sessionId: result.sessionId } : {}) };
+    }
+}
+const CODEX_BILLING_ENV_KEYS = new Set([
+    "OPENAI_API_KEY",
+    "CODEX_API_KEY",
+    "AZURE_OPENAI_API_KEY",
+    "OPENAI_ORGANIZATION",
+    "OPENAI_ORG_ID",
+    "OPENAI_PROJECT",
+    "OPENAI_PROJECT_ID",
+]);
+async function resolveCodexSetupProducedField(irPath, agentId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(irPath, "utf8"));
+    }
+    catch {
+        throw new Error("Codex setup IR is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("Codex setup IR does not contain a valid component contract");
+    }
+    const components = parsed.components;
+    if (!Array.isArray(components)) {
+        throw new Error("Codex setup IR does not contain a valid component contract");
+    }
+    const matches = components.filter((component) => typeof component === "object" && component !== null && component.id === agentId);
+    const component = matches[0];
+    if (matches.length !== 1 || component === undefined || !Array.isArray(component.llm_calls) || component.llm_calls.length !== 1) {
+        throw new Error(`Codex setup component "${agentId}" does not declare exactly one produced field`);
+    }
+    const produces = component.llm_calls[0]?.produces;
+    if (typeof produces !== "string" || !produces.trim()) {
+        throw new Error(`Codex setup component "${agentId}" does not declare exactly one produced field`);
+    }
+    return produces;
+}
+function unwrapCodexSetupEnvelope(rawFinalText, expectedField) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawFinalText);
+    }
+    catch {
+        throw new Error("Codex setup final response is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("Codex setup final response must be a single-field JSON object");
+    }
+    const fields = Object.keys(parsed);
+    if (fields.length !== 1 || fields[0] !== expectedField) {
+        throw new Error(`Codex setup final response must contain only the declared "${expectedField}" field`);
+    }
+    const produced = parsed[expectedField];
+    if (typeof produced !== "string") {
+        throw new Error(`Codex setup final response field "${expectedField}" must be a string`);
+    }
+    return produced;
+}
+/**
+ * Setup-only Codex subscription runner. It invokes the target's `dispatch`
+ * command directly against the committed setup IR and exposes exactly one
+ * guarded MCP tool. Normal Ask routing never calls this class.
+ */
+export class CodexSetupRunner {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async run(runOptions) {
+        if (runOptions.authChoice.mode !== "subscription" || runOptions.authChoice.provider !== "codex") {
+            throw new Error("Codex setup runner requires a Codex subscription auth choice");
+        }
+        const agentId = runOptions.agentId ?? CONNECT_SOURCE_AGENT_ID;
+        if (agentId !== CONNECT_SOURCE_AGENT_ID && agentId !== BUILD_CONTEXT_AGENT_ID) {
+            throw new Error(`Codex setup only supports "${CONNECT_SOURCE_AGENT_ID}" and "${BUILD_CONTEXT_AGENT_ID}"`);
+        }
+        const model = this.options.getStrongModel().trim();
+        if (!model)
+            throw new Error("Codex setup requires a configured strong-tier model");
+        const expectedProducedField = await resolveCodexSetupProducedField(this.options.irPath, agentId);
+        const cli = this.options.codexLocalCli ?? (await resolveCodexLocalCli(this.options.codexLocalBin));
+        const traceDir = this.options.mcpServer ? undefined : await mkdtemp(path.join(os.tmpdir(), "wren-codex-setup-trace-"));
+        const tracePath = traceDir ? path.join(traceDir, "setup-execution.jsonl") : undefined;
+        if (tracePath)
+            await writeFile(tracePath, "", { encoding: "utf8", mode: 0o600 });
+        const mcp = this.options.mcpServer ?? defaultCodexSetupMcpInvocation(tracePath);
+        const timeoutMs = this.options.timeoutMs ?? 10 * 60 * 1000;
+        const turnRoot = resolveDispatchedUserProject(runOptions, agentId);
+        const args = [
+            ...cli.prefixArgs,
+            "dispatch",
+            this.options.irPath,
+            runOptions.prompt,
+            "--component",
+            agentId,
+            "--project",
+            turnRoot,
+            "--model",
+            model,
+            "--server",
+            "setup",
+            "--server-command",
+            mcp.command,
+            ...mcp.prefixArgs.flatMap((arg) => (arg.startsWith("-") ? [`--server-arg=${arg}`] : ["--server-arg", arg])),
+            "--server-arg=--workspace-root",
+            "--server-arg",
+            turnRoot,
+            "--source-tool",
+            SETUP_EXECUTION_TOOL_NAME,
+            "--context-tool",
+            SETUP_EXECUTION_TOOL_NAME,
+            "--timeout",
+            String(timeoutMs),
+            ...(this.options.codexBin ? ["--codex-bin", this.options.codexBin] : []),
+            "--stream-json",
+        ];
+        const emitter = createAgentEventEmitter(runOptions.onEvent);
+        emitter.emit({ kind: "run.start", mode: "B", agentId });
+        const mapper = new CodexSetupEventMapper(tracePath);
+        try {
+            const rawFinalText = await spawnCodexSetup(cli.command, args, mapper, emitter.emit, timeoutMs + 5_000);
+            const finalText = unwrapCodexSetupEnvelope(rawFinalText, expectedProducedField);
+            emitter.emit({ kind: "run.finish", status: "answer" });
+            return { finalText };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            emitter.emit({ kind: "error", message });
+            emitter.emit({ kind: "run.finish", status: "error" });
+            throw error;
+        }
+        finally {
+            if (traceDir)
+                await rm(traceDir, { recursive: true, force: true });
+        }
+    }
+}
+function defaultCodexSetupMcpInvocation(tracePath) {
+    return {
+        command: process.execPath,
+        prefixArgs: [fileURLToPath(new URL("../../server/codex-setup-mcp.js", import.meta.url)), "--trace-path", tracePath],
+    };
+}
+function sanitizedCodexSetupEnvironment() {
+    return Object.fromEntries(Object.entries(process.env).filter(([key, value]) => value !== undefined && !CODEX_BILLING_ENV_KEYS.has(key.toUpperCase())));
+}
+function spawnCodexSetup(command, args, mapper, emit, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], {
+            env: sanitizedCodexSetupEnvironment(),
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: process.platform !== "win32",
+        });
+        let stderr = "";
+        let settled = false;
+        let timedOut = false;
+        let killTimer;
+        const terminate = (signal) => {
+            if (child.pid !== undefined && process.platform !== "win32") {
+                try {
+                    process.kill(-child.pid, signal);
+                    return;
+                }
+                catch {
+                    // Fall through to the direct child.
+                }
+            }
+            child.kill(signal);
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            terminate("SIGTERM");
+            killTimer = setTimeout(() => terminate("SIGKILL"), 1_000);
+        }, timeoutMs);
+        const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        lines.on("line", (line) => {
+            if (settled || !line.trim())
+                return;
+            try {
+                const event = mapper.nextLine(line);
+                if (event)
+                    emit(event);
+            }
+            catch (error) {
+                settled = true;
+                clearTimeout(timer);
+                terminate("SIGTERM");
+                killTimer = setTimeout(() => terminate("SIGKILL"), 1_000);
+                reject(error);
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < 8_192)
+                stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            reject(new Error(`warble-codex-local failed to start: ${error.message}`));
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            lines.close();
+            // Do not cancel an already-scheduled process-group SIGKILL here. The
+            // direct dispatcher can exit on SIGTERM while one of its descendants
+            // ignores the signal; the escalation still has to reap that descendant.
+            if (settled)
+                return;
+            settled = true;
+            if (timedOut) {
+                reject(new Error(`warble-codex-local timed out after ${timeoutMs}ms`));
+            }
+            else if (code !== 0) {
+                reject(new Error(`warble-codex-local exited with ${code ?? signal ?? "unknown"}: ${stderr.trim()}`));
+            }
+            else {
+                try {
+                    resolve(mapper.result());
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }
+        });
+    });
+}
+/**
+ * This package's bundled setup capability-provider fragment
+ * (`providers/setup.provider.yaml`) — the default `--provider` for
+ * `InProcessSetupRunner`'s dispatch, mirroring `compileProfile`'s own
+ * `DEFAULT_WREN_PROVIDER_PATH` constant (`harness/compile/pipeline.ts`).
+ */
+export const DEFAULT_SETUP_PROVIDER_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "providers", "setup.provider.yaml");
+/**
+ * Dispatches a setup-wizard turn over in-process: the in-process vercel loop
+ * (`harness/loop/executor.ts`'s `executeAgent`), instead of shelling a
+ * claude-agent-sdk subprocess. Mirrors `DispatchedSetupRunner`'s own shape
+ * (same `SetupStepRunner` interface, same "bypass the per-user compile
+ * pipeline and dispatch the fixed, warble-committed setup IR directly"
+ * design) but reuses the in-process building blocks `harness/route/in-process.ts`'s
+ * `runInProcessDefault` wires together, minus the two pieces that don't apply to
+ * setup:
+ *
+ *  - No `resolveWrenBinary()` preflight — the setup components' only tool
+ *    (`setup_execution`, see `harness/tools/setup-native.ts`) never shells
+ *    the `wren` CLI directly; it's a general scoped exec/write pair, not a
+ *    wren-specific one.
+ *  - No `deriveEnforcement(agent)` (`harness/guardrails/policy.ts`) — that
+ *    function maps `read_only`/`scoped_write`/threshold guardrails onto an
+ *    `EnforcementPolicy` and has no branch for the `setup_execution`
+ *    guardrail shape (`{name: "setup_execution", locked: true, scope: "."}`)
+ *    the two setup components declare. Rather than widen that shared module
+ *    for a guardrail only this path uses, this runner builds its own fixed
+ *    `ExecutionPolicy` below, matching what `setup_execution` actually grants
+ *    on the dispatched (claude-agent-sdk) side: unrestricted exec (subject only
+ *    to the native tool's own destructive/redirection denylist, never
+ *    `readOnly`-gated) and a write scope of the whole workspace root.
+ *
+ * Unlike `DispatchedSetupRunner`, which forwards its `--max-turns` budget to a
+ * subprocess CLI flag, this runner's turn budget is an in-process
+ * `ExecuteAgentContext.maxSteps` (an `isStepCount` stop condition on the
+ * step's underlying `ToolLoopAgent`) — see `effectiveMaxTurns()` below for
+ * how it's resolved, and `StepBudgetExhaustedError` (`harness/loop/errors.ts`)
+ * for how a turn that runs out of steps before finishing is reported.
+ *
+ * Also calls `executeAgent` directly rather than the higher-level
+ * `runAgent()` in-process's Ask-turn path uses: `runAgent` asserts every
+ * `agent.capabilities[]` entry against a `CapabilityRegistry`, but
+ * `connect_source`/`build_context` declare `source_connect`/`context_build`
+ * — capabilities outside the fixed `DEFAULT_CAPABILITIES` set a wren-project
+ * Ask turn resolves. `executeAgent` (confirmed via `ExecuteAgentContext`'s
+ * own shape) has no `capabilityRegistry` concept at all, so it runs the
+ * bundle's dataflow with no capability assertion — exactly what dispatching
+ * a setup-only capability needs, without inventing a parallel registry for
+ * two names nothing else provides.
+ */
+export class InProcessSetupRunner {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * The `ExecuteAgentContext.maxSteps` budget this runner will actually pass
+     * into `executeAgent` for a given `agentId` — the same value `run()`
+     * computes internally. This was previously documented as always
+     * `undefined` on the theory that "`executeAgent` has no turn-budget
+     * concept at all" — that was already false when it was written: every
+     * tools-bearing step ran as a `ToolLoopAgent` turn, and `ToolLoopAgent`
+     * itself silently defaults to a 20-step budget (`ai`'s
+     * `stopWhen: this.settings.stopWhen ?? isStepCount(20)`) whenever nothing
+     * overrides it. There was a real, unconfigurable ceiling the whole time;
+     * it just had no name and nothing here reported it. Now that `run()` below
+     * threads an explicit `maxSteps` through, this reports the real value —
+     * mirroring `DispatchedSetupRunner.effectiveMaxTurns` — via the same
+     * `resolveEffectiveMaxTurns` helper so the two can never disagree.
+     */
+    effectiveMaxTurns(agentId) {
+        return resolveEffectiveMaxTurns(this.options.maxTurns, agentId);
+    }
+    async run(runOptions) {
+        const { authChoice } = runOptions;
+        const agentId = runOptions.agentId ?? CONNECT_SOURCE_AGENT_ID;
+        if (authChoice.mode === "subscription") {
+            throw new Error(`in-process setup dispatch requires an api-key/local/gateway auth mode to dispatch "${agentId}" ` +
+                `via the in-process vercel loop — got "subscription". Use DispatchedSetupRunner ` +
+                "(WREN_HARNESS_MODE=subscription) for a subscription auth choice instead.");
+        }
+        const warbleBin = await resolveWarbleBinary(this.options.warbleBin);
+        const providerPath = this.options.providerPath ?? DEFAULT_SETUP_PROVIDER_PATH;
+        const callerSuppliedOutDir = this.options.outDir !== undefined;
+        const outDir = this.options.outDir ?? (await mkdtemp(path.join(os.tmpdir(), "wren-harness-setup-in-process-")));
+        // `executeAgent` emits the UN-stamped `AgentEventInput` shape (no
+        // `runId`/`seq` — it doesn't know either); `SetupStepRunOptions.onEvent`
+        // is the caller-facing, fully-stamped `AgentEvent` shape. Wrapping via
+        // `createAgentEventEmitter` (exactly how `runAgent` itself bridges the
+        // same two shapes in `harness/session/run.ts`) is what stamps every
+        // event from this turn with one shared `runId` and a monotonic `seq`
+        // before it reaches `runOptions.onEvent`. The emitter itself no-ops when
+        // `runOptions.onEvent` is undefined, so `emitter.emit` is always safe to
+        // pass unconditionally.
+        const emitter = createAgentEventEmitter(runOptions.onEvent);
+        emitter.emit({ kind: "run.start", mode: "A", agentId });
+        try {
+            await runWarble(warbleBin, [
+                "dispatch",
+                "--target",
+                "vercel",
+                "--provider",
+                providerPath,
+                this.options.irPath,
+                "--out",
+                outDir,
+            ]);
+            const bundlePath = path.join(outDir, "bundle.json");
+            const bundle = loadBundleWithProvenance(JSON.parse(await readFile(bundlePath, "utf-8")), {
+                warbleBin,
+                profileSource: this.options.irPath,
+            });
+            const agent = bundle.agents.find((candidate) => candidate.id === agentId);
+            if (!agent) {
+                throw new Error(`compiled setup bundle has no "${agentId}" agent`);
+            }
+            const adapterSpec = this.options.getStrongAdapterSpec
+                ? this.options.getStrongAdapterSpec(authChoice)
+                : deriveAdapterSpec(authChoice, this.options.model !== undefined ? { model: this.options.model } : {});
+            const binding = buildUniformTierBinding(agent, adapterSpec);
+            const registry = createDefaultProviderRegistry();
+            // Hardcoded, NOT `deriveEnforcement(agent)` — see this class's doc
+            // comment above for why. `artifactWriteScope: "."` resolves against
+            // `env`'s `rootDir` below, which IS `workspaceRoot` — so "." means
+            // "anywhere under workspaceRoot", matching `setup_execution`'s
+            // project-root write scope on the dispatched side.
+            const policy = { readOnly: false, artifactWriteScope: "." };
+            const env = createLocalExecutionEnv({ rootDir: runOptions.workspaceRoot });
+            const nativeTools = createNativeToolRegistry();
+            nativeTools.register(SETUP_EXECUTION_TOOL_NAME, () => createSetupExecutionTool({ env, policy, workspaceRoot: runOptions.workspaceRoot }));
+            // Kept in lockstep with `effectiveMaxTurns()` above via the shared
+            // `resolveEffectiveMaxTurns` helper, exactly like `DispatchedSetupRunner.run()`
+            // does for its own `--max-turns` flag.
+            const maxSteps = this.effectiveMaxTurns(agentId);
+            const artifacts = await withResolvedTools(agent, { nativeTools, enforcementPolicy: policy, executionEnv: env }, (tools) => executeAgent(agent, {
+                binding,
+                registry,
+                tools,
+                userInput: runOptions.prompt,
+                onEvent: emitter.emit,
+                ...(maxSteps !== undefined ? { maxSteps } : {}),
+            }));
+            // Every setup component has exactly one step (`connect` / `build`), so
+            // its `produces` artifact is the turn's final answer — mirroring
+            // `DispatchedSetupRunner`'s `result.finalText`, which is likewise "the last
+            // thing the dispatched turn said."
+            const producedName = agent.steps[0]?.produces;
+            const finalText = producedName !== undefined ? String(artifacts.get(producedName) ?? "") : "";
+            // `"answer"` is the closest of `RunFinishEvent.status`'s three literals
+            // ("answer" | "refusal" | "error") to "a setup turn completed" — setup
+            // has no envelope-gated refusal concept of its own (see this class's
+            // doc comment), so a completed dispatch is reported the same way
+            // `runAgent` reports a completed Ask turn that produced output.
+            emitter.emit({ kind: "answer", text: finalText });
+            emitter.emit({ kind: "run.finish", status: "answer" });
+            // `sessionId: null`, not omitted: in-process has no SDK subprocess
+            // conversation to resume (`executeAgent` re-runs the bundle's dataflow
+            // from scratch every call) — `null` is `SetupStepRunResult`'s
+            // documented "the dispatcher itself reported no session id at all,"
+            // which is exactly this case, distinct from a runner that simply never
+            // set the field.
+            return { finalText, sessionId: null };
+        }
+        catch (error) {
+            // A `StepBudgetExhaustedError` is a distinguishable, honest failure
+            // mode, not a generic one — surface that here rather than letting it
+            // fall through as a bare "final message did not contain a
+            // SETUP_STATUS line" once it reaches `parseSetupTerminal`'s caller
+            // (which never even runs `parseSetupTerminal` on a thrown `run()`
+            // error — see `executeSetupTurn`, `server/turn.ts` — it reports
+            // `error.message` directly). No literal "Continue" checkpoint is
+            // offered here (out of scope for this runner: in-process has no SDK
+            // session to resume — `sessionId: null` below, always) — just an
+            // honest message pointing at where any partial work may have landed.
+            if (error instanceof StepBudgetExhaustedError) {
+                // Mutate `.message` in place (legal — only the constructor
+                // parameters above are `readonly`, not the inherited `Error.message`)
+                // rather than wrapping in a fresh `Error`: callers upstream (or
+                // future ones) can still `instanceof StepBudgetExhaustedError` this
+                // and read `.maxSteps`/`.stepId`/`.stepsCompleted`, while
+                // `server/turn.ts`'s generic `failWithError(error.message, ...)`
+                // path — which only ever reads `.message` — sees the enriched,
+                // Mode-A-specific text instead of the generic one from
+                // `harness/loop/errors.ts`.
+                error.message =
+                    `setup step "${agentId}" ran out of steps (${error.maxSteps} max) before finishing — ` +
+                        `its partial work, if any, may still be on disk under ${runOptions.workspaceRoot}`;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            // Mirrors `runAgent`'s own catch/emit/rethrow in `harness/session/run.ts`:
+            // a thrown failure still gets a `run.finish` bookend (status "error")
+            // rather than leaving the event stream hanging with a `run.start` and
+            // nothing after it.
+            emitter.emit({ kind: "error", message });
+            emitter.emit({ kind: "run.finish", status: "error" });
+            throw error;
+        }
+        finally {
+            if (!callerSuppliedOutDir) {
+                await rm(outDir, { recursive: true, force: true });
+            }
+        }
+    }
+}
+/**
+ * Reads a single top-level `field: value` line out of a YAML file using the
+ * same lightweight line-scan convention already used elsewhere in this
+ * codebase (e.g. `server/compose.ts`'s `countRelationships`/`listModelNames`)
+ * rather than pulling in a YAML parser dependency. Matches only an unindented
+ * `field:` key (so it can't be fooled by a same-named key nested under
+ * another mapping), strips a single layer of surrounding quotes, and returns
+ * `undefined` if the file is missing/unreadable or the field isn't present.
+ */
+function readProjectYamlField(yamlPath, field) {
+    let content;
+    try {
+        content = readFileSync(yamlPath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    const pattern = new RegExp(`^${field}:\\s*(.+?)\\s*$`, "m");
+    const match = pattern.exec(content);
+    if (!match) {
+        return undefined;
+    }
+    const raw = match[1];
+    const unquoted = /^"(.*)"$/.exec(raw) ?? /^'(.*)'$/.exec(raw);
+    return (unquoted ? unquoted[1] : raw).trim();
+}
+/** Parses the small KEY=value subset of a project .env file used by Wren profiles. */
+function parseDotEnv(text) {
+    const values = new Map();
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const assignment = line.startsWith("export ") ? line.slice("export ".length) : line;
+        const separator = assignment.indexOf("=");
+        if (separator === -1)
+            continue;
+        const key = assignment.slice(0, separator).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        const rawValue = assignment.slice(separator + 1).trim();
+        const quoted = /^(".*"|'.*')$/.test(rawValue) ? rawValue.slice(1, -1) : rawValue;
+        values.set(key, quoted);
+    }
+    return values;
+}
+function normalizeConnectionScheme(scheme) {
+    const normalized = scheme.replace(/:$/, "").toLowerCase();
+    return normalized === "postgresql" ? "postgres" : normalized;
+}
+/**
+ * Closed URL-scheme allowlist for the source types accepted by Setup. Keep
+ * this local rather than importing `server/app.ts`: harness must not depend
+ * on its BFF consumer. A source without an unambiguous host/database URL
+ * shape (for example DuckDB's filesystem `url`) deliberately has no entries
+ * and therefore cannot retain lifecycle proof through this URL path.
+ */
+const URL_SCHEMES_BY_SOURCE = new Map([
+    ["postgres", new Set(["postgres"])],
+    ["mysql", new Set(["mysql", "mysql+pymysql", "mysql+mysqldb"])],
+    ["bigquery", new Set(["bigquery"])],
+    ["snowflake", new Set(["snowflake"])],
+    ["clickhouse", new Set(["clickhouse", "clickhouse+http", "clickhouse+https"])],
+    ["mssql", new Set(["mssql"])],
+    ["trino", new Set(["trino", "trino+https"])],
+    ["duckdb", new Set()],
+]);
+/**
+ * Only these Setup sources have the host/port/database fields represented by
+ * the generic field fallback below. Other supported sources use different
+ * identity shapes (for example BigQuery project/dataset and Trino
+ * catalog/schema), so accepting generic DB_HOST/DB_DATABASE for them would
+ * forge an identity rather than derive the effective connection target.
+ */
+const HOST_DATABASE_FIELD_SOURCES = new Set([
+    "postgres",
+    "mysql",
+    "clickhouse",
+    "mssql",
+    // Added when Setup began offering wren's full connector set. Each of these
+    // has host/port/database in its own wren connection model, so the generic
+    // fallback derives their identity rather than forging one. Sources whose
+    // identity is shaped differently — BigQuery's project/dataset, Trino's
+    // catalog/schema, Databricks' serverHostname/httpPath, Athena's S3 staging
+    // dir, Spark's bare host/port — are still deliberately absent.
+    "oracle",
+    "redshift",
+    "doris",
+]);
+function connectionTargetFromUrl(value, sourceType) {
+    try {
+        const url = new URL(value);
+        const database = decodeURIComponent(url.pathname).replace(/^\/+|\/+$/g, "");
+        const scheme = normalizeConnectionScheme(url.protocol);
+        if (!url.protocol || !url.hostname || !database || !URL_SCHEMES_BY_SOURCE.get(sourceType)?.has(scheme))
+            return undefined;
+        // Intentionally do not return username, password, query, or fragment.
+        return {
+            scheme,
+            host: url.hostname.toLowerCase(),
+            port: url.port,
+            database,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function connectionTargetFromFields(scheme, host, port, database) {
+    if (!host || !database)
+        return undefined;
+    return { scheme: normalizeConnectionScheme(scheme), host: host.toLowerCase(), port: port ?? "", database };
+}
+/**
+ * Resolves a single effective value using Wren's shell-over-.env precedence.
+ * Multiple aliases that disagree are ambiguous, so retained proof must not be
+ * reused. The returned value is never persisted directly.
+ */
+function effectiveConnectionValue(dotenv, aliases) {
+    const values = new Set();
+    for (const key of aliases) {
+        const value = process.env[key] ?? dotenv.get(key);
+        if (value !== undefined && value.trim())
+            values.add(value.trim());
+    }
+    return values.size === 1 ? [...values][0] : undefined;
+}
+function connectionAliases(sourceType) {
+    const source = sourceType.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+    const generic = {
+        urls: [`${source}_URL`, "DATABASE_URL", "DB_URL"],
+        hosts: [`${source}_HOST`, "DB_HOST"],
+        ports: [`${source}_PORT`, "DB_PORT"],
+        databases: [`${source}_DATABASE`, `${source}_DB`, "DB_DATABASE", "DB_NAME"],
+    };
+    if (source !== "POSTGRES" && source !== "POSTGRESQL")
+        return generic;
+    return {
+        urls: ["POSTGRES_URL", "POSTGRESQL_URL", "PG_URL", ...generic.urls],
+        hosts: ["POSTGRES_HOST", "PGHOST", ...generic.hosts],
+        ports: ["POSTGRES_PORT", "PGPORT", ...generic.ports],
+        databases: ["POSTGRES_DATABASE", "POSTGRES_DB", "PGDATABASE", "PG_DB", ...generic.databases],
+    };
+}
+/**
+ * Returns a digest of the effective, non-secret database target. It accepts a
+ * URL or host/database fields, but deliberately retains only scheme, host,
+ * port, and database; credentials and raw URLs never enter persisted state.
+ * Missing or contradictory target facts fail closed.
+ */
+function effectiveConnectionTargetDigest(projectDir, sourceType) {
+    let dotenv;
+    try {
+        dotenv = parseDotEnv(readFileSync(path.join(projectDir, ".env"), "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+    const aliases = connectionAliases(sourceType);
+    const targets = new Set();
+    for (const key of aliases.urls) {
+        const value = process.env[key] ?? dotenv.get(key);
+        if (value === undefined || !value.trim())
+            continue;
+        const target = connectionTargetFromUrl(value.trim(), sourceType);
+        if (target === undefined)
+            return undefined;
+        targets.add(JSON.stringify(target));
+    }
+    const fieldTarget = !HOST_DATABASE_FIELD_SOURCES.has(sourceType)
+        ? undefined
+        : connectionTargetFromFields(sourceType, effectiveConnectionValue(dotenv, aliases.hosts), effectiveConnectionValue(dotenv, aliases.ports), effectiveConnectionValue(dotenv, aliases.databases));
+    if (fieldTarget !== undefined)
+        targets.add(JSON.stringify(fieldTarget));
+    if (targets.size !== 1)
+        return undefined;
+    return createHash("sha256").update([...targets][0]).digest("hex");
+}
+/**
+ * A non-secret, host-derived identity for retained context lifecycle proof.
+ * It deliberately binds the canonical on-disk project, the BFF-selected
+ * source type, wren's project-level profile declaration, and a non-secret
+ * digest of the effective connection target. If any required filesystem fact
+ * cannot be read or is ambiguous, callers must fail closed and not reuse
+ * evidence from an earlier attempt.
+ */
+export function contextLifecycleIdentityFingerprint(root, name, selectedSourceType) {
+    try {
+        const projectDir = realpathSync(path.join(root, name));
+        if (!statSync(projectDir).isDirectory())
+            return undefined;
+        const projectYml = path.join(projectDir, "wren_project.yml");
+        const profile = readProjectYamlField(projectYml, "profile");
+        const declaredSourceType = readProjectYamlField(projectYml, "data_source");
+        const normalizedSelectedSourceType = selectedSourceType.trim().toLowerCase();
+        const normalizedDeclaredSourceType = declaredSourceType?.trim().toLowerCase();
+        if (profile === undefined || normalizedDeclaredSourceType === undefined || normalizedDeclaredSourceType !== normalizedSelectedSourceType)
+            return undefined;
+        const connectionTargetDigest = effectiveConnectionTargetDigest(projectDir, normalizedSelectedSourceType);
+        if (connectionTargetDigest === undefined)
+            return undefined;
+        return createHash("sha256")
+            .update(JSON.stringify({ version: 2, projectDir, selectedSourceType: normalizedSelectedSourceType, profile, declaredSourceType: normalizedDeclaredSourceType, connectionTargetDigest }))
+            .digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+function hostContractFailure(code, message, observed, expectedArtifactContract, failureKind) {
+    return {
+        status: "error",
+        message,
+        diagnostic: { kind: "host_contract", code, observed, expectedArtifactContract },
+        ...(failureKind !== undefined ? { failureKind } : {}),
+    };
+}
+const SETUP_STATUS_LINE = /^SETUP_STATUS:\s*(ok|needs_input|error)\b\s*[-:]?\s*(.*)$/i;
+function defaultMessageFor(status) {
+    switch (status) {
+        case "ok":
+            return "setup completed successfully";
+        case "needs_input":
+            return "waiting for user input";
+        case "error":
+            return "setup failed";
+    }
+}
+/** Counts the built MDL's models; unreadable/malformed content is deliberately treated as empty rather than trusted. */
+function countMdlModels(mdlPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(mdlPath, "utf-8"));
+        return Array.isArray(parsed.models) ? parsed.models.length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Returns the path of the first artifact `connect`'s prompt promises but
+ * that is missing from disk, or `undefined` if all three are present. Checked
+ * in the order a real `connect` run would produce them, so the message names
+ * the earliest failure (e.g. a missing project dir implies the other two are
+ * also missing, but naming the dir is the most useful signal).
+ */
+function missingConnectArtifact(context) {
+    const projectDir = path.join(context.root, context.name);
+    if (!existsSync(projectDir)) {
+        return projectDir;
+    }
+    const projectYml = path.join(projectDir, "wren_project.yml");
+    if (!existsSync(projectYml)) {
+        return projectYml;
+    }
+    const envFile = path.join(projectDir, ".env");
+    if (!existsSync(envFile)) {
+        return envFile;
+    }
+    return undefined;
+}
+/**
+ * Matches in-process's / Codex local's `setup_execution` "exec" call's
+ * `ToolStep.detail` — a `summarizeToolOutput`-bounded (200-char)
+ * `JSON.stringify` of `{exitCode, stdout, stderr, ...}` (see
+ * `harness/tools/setup-native.ts`) — and extracts the exit code. A regex, not
+ * `JSON.parse`: once `stdout`/`stderr` push a stringified object past 200
+ * characters (routine for a CLI usage/error message), the truncated detail
+ * is no longer valid JSON, but in-process serializes `exitCode` first so it
+ * always survives.
+ *
+ * Deliberately Mode-A/Codex-local-only. There used to be a sibling
+ * `MODE_B_BASH_EXIT_CODE` regex here matching a literal `"exit code: N"`
+ * phrase, on the theory that a dispatched Bash result might carry that text —
+ * but no real code path ever writes it: dispatched's `detail` is the command's
+ * raw (240-char-truncated) stdout via `summarizeResultContent` in warble's
+ * `dispatcher/claude-agent-sdk/src/events.ts`, with no such wrapping. That
+ * dead regex made `execSucceeded` return `undefined` for every genuine dispatched
+ * discovery/validate/build call, which made the `context` step's discovery
+ * gate structurally unsatisfiable in dispatched — see `execSucceeded` for the fix.
+ */
+const SETUP_EXEC_EXIT_CODE = /^\{"exitCode":(-?\d+)/;
+function inProcessExecExitCode(detail) {
+    if (detail === undefined)
+        return undefined;
+    const match = SETUP_EXEC_EXIT_CODE.exec(detail);
+    return match ? Number(match[1]) : undefined;
+}
+/**
+ * In-process registers the scoped execution capability under its policy name,
+ * while dispatched's streamed SDK events retain the underlying `Bash` tool name.
+ * Both names represent the same setup-only command boundary at this layer.
+ */
+const MODE_B_SETUP_EXECUTION_TOOL_NAME = "Bash";
+/** Codex local streams the same allowlisted tool with its MCP server prefix. */
+const CODEX_SETUP_EXECUTION_TOOL_NAME = `setup.${SETUP_EXECUTION_TOOL_NAME}`;
+function isSetupExecutionEntry(entry) {
+    return (entry.label === SETUP_EXECUTION_TOOL_NAME ||
+        entry.label === MODE_B_SETUP_EXECUTION_TOOL_NAME ||
+        entry.label === CODEX_SETUP_EXECUTION_TOOL_NAME);
+}
+/** In-process and Codex local share the same non-throwing `setup_execution` tool — see {@link execSucceeded}. */
+function isInProcessShapedExecEntry(entry) {
+    return entry.label === SETUP_EXECUTION_TOOL_NAME || entry.label === CODEX_SETUP_EXECUTION_TOOL_NAME;
+}
+/**
+ * Whether a setup-execution worklog entry represents a genuinely successful
+ * command run — `true`/`false` when that's known, `undefined` when it isn't
+ * recorded either way (e.g. a in-process file-write action, which has no exit
+ * code at all).
+ *
+ * In-process and Codex local share the same non-throwing `setup_execution` tool
+ * (`harness/tools/setup-native.ts`): the JS tool call itself only throws on a
+ * pre-flight denylist/scope violation (`SetupCommandDeniedError`), never on
+ * the shell command's own exit code — a nonexistent CLI subcommand still
+ * returns normally as `{exitCode: 2, ...}` structured output. That means
+ * `ToolStep.state` is ALWAYS `"done"` for these entries regardless of
+ * whether the shell command itself succeeded, so the only trustworthy signal
+ * for them is the structured exit code folded into `detail`
+ * ({@link inProcessExecExitCode}) — unchanged from before this fix.
+ *
+ * Dispatched's Bash tool has no such gap: `LiveWorkLog.ingest` (`server/fold.ts`)
+ * already sets `ToolStep.state` from the originating `AgentEvent`'s own
+ * `status` field ("success" -> "done", "error" -> "error") at fold time, for
+ * both a genuine command failure and a blocked/guardrail-denied execution —
+ * either way the tool call itself did not succeed, so `state` is sound to
+ * trust directly. It is also the ONLY signal available: dispatched's `detail` is
+ * the command's raw (240-char-truncated) stdout, never a structured exit
+ * code.
+ */
+function execSucceeded(entry) {
+    if (isInProcessShapedExecEntry(entry)) {
+        const exitCode = inProcessExecExitCode(entry.detail);
+        return exitCode === undefined ? undefined : exitCode === 0;
+    }
+    if (entry.state === "done")
+        return true;
+    if (entry.state === "error")
+        return false;
+    return undefined;
+}
+/** Best-effort extraction of the `command` an exec-action worklog entry ran, for a readable error message; `undefined` if the input isn't the expected shape. */
+function execCommandOf(entry) {
+    const input = entry.input;
+    if (typeof input !== "object" || input === null)
+        return undefined;
+    const command = input.command;
+    return typeof command === "string" ? command : undefined;
+}
+/**
+ * Finds the first setup execution call in `worklog` whose recorded result was
+ * a non-zero exit code — i.e. a command that genuinely ran and failed,
+ * as opposed to one whose tool invocation merely reported success. This
+ * distinction matters because `ToolStep.state` alone cannot make it: every
+ * setup execution call reports `state: "done"` as long as the TOOL MECHANISM
+ * itself didn't throw (it ran a shell command and captured
+ * whatever came back) — regardless of whether the underlying shell command
+ * itself succeeded. A nonexistent CLI subcommand (e.g. `wren generate-mdl` —
+ * `generate-mdl` is a skill document, not a command; see
+ * `composeSetupPrompt`'s `context` branch) still shows `state: "done"`; only
+ * the nested `detail` JSON's `exitCode` carries the real signal. See
+ * `parseSetupTerminal`'s use of this for why: an `error` status whose own
+ * claimed reason blames the connection/data source is only trustworthy if
+ * nothing in the trace shows a command failing outright first.
+ *
+ * KNOWN LIMITATION (disclosed, not silently assumed away): this flags ANY
+ * failed exec among the step's setup execution calls, without judging
+ * whether that particular command was expected to fail as part of ordinary
+ * exploration (e.g. a `grep` with no match, or a conditional shell test) —
+ * doing so reliably would require actually understanding the command's
+ * intent, which this module has no basis to do. The returned message is
+ * worded as advisory ("does not by itself confirm...") rather than as a
+ * counter-assertion for exactly this reason.
+ *
+ * `exitCode` is optional: in-process/Codex local failures carry a real numeric
+ * exit code; a dispatched (Bash) failure — including a blocked/guardrail-denied
+ * execution — has none (only the fact that it failed), so callers must
+ * degrade their wording gracefully rather than assume a number is present.
+ */
+function firstFailedExec(worklog) {
+    for (const entry of worklog) {
+        if (!isSetupExecutionEntry(entry))
+            continue;
+        if (execSucceeded(entry) === false) {
+            const exitCode = isInProcessShapedExecEntry(entry) ? inProcessExecExitCode(entry.detail) : undefined;
+            return { command: execCommandOf(entry), ...(exitCode !== undefined ? { exitCode } : {}) };
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether `command` has one of the schema-introspection shapes currently
+ * documented by the generate-mdl skill. This is deliberately an allowlist:
+ * a Wren SQL query, inline Python using SQLAlchemy or a documented database
+ * driver, or a connector CLI is only counted when its command text ALSO has
+ * recognizable Phase-2 discovery evidence: a schema/catalog query, a table
+ * listing command, or a documented table/column discovery API. In particular,
+ * connectivity probes such as `SELECT 1` and arbitrary data queries do NOT
+ * count; neither do skill fetches or the context build/validate lifecycle
+ * commands.
+ *
+ * KNOWN LIMITATIONS (disclosed, not silently assumed away): a worklog stores
+ * only the shell command, not an executed script's contents or its query
+ * result. Therefore this recognizes an ATTEMPT with recognizable discovery
+ * evidence, not a successful schema read; it cannot recognize opaque script
+ * paths, database-specific CLI metacommands, every future driver/CLI, or
+ * prove that a matched query returned schema rows. Expanding beyond the
+ * evidenced command shapes would turn this from an allowlist into guesswork,
+ * so unmatched commands intentionally do not count.
+ */
+const SCHEMA_DISCOVERY_EVIDENCE = /\b(?:information_schema|pg_catalog|sqlite_master|system\.tables|show\s+(?:full\s+)?(?:tables|columns)|describe\s+(?:table|schema)|\.tables|get_table_names|get_columns|get_foreign_keys|get_pk_constraint|get_unique_constraints|list_tables|get_table)\b/i;
+const SCHEMA_INTROSPECTION_COMMANDS = [
+    /\bwren(?:\s+query)?\s+--sql(?:\s|=)/i,
+    /\b(?:python(?:3(?:\.\d+)?)?|uv\s+run\s+python)\b[\s\S]*\b(?:sqlalchemy|psycopg|asyncpg|google\.cloud\.bigquery|snowflake\.connector|clickhouse_driver)\b/i,
+    /\b(?:python(?:3(?:\.\d+)?)?|uv\s+run\s+python)\b[\s\S]*\bwren\.profile\b[\s\S]*\bwren\.connector\b/i,
+    /\bWREN_PYTHON\b[\s\S]*\bcommand\s+-v\s+wren\b[\s\S]*\bwren\.profile\b[\s\S]*\bwren\.connector\b/i,
+    /\b(?:psql|mysql|sqlite3|duckdb|snowsql|clickhouse-client|trino(?:-cli)?)\b[\s\S]*(?:\s(?:-c|--command|--execute|--query)\s|\b(?:information_schema|show\s+(?:tables|columns)|describe\s+(?:table|schema)|\.tables)\b)/i,
+    /\bbq\s+query\b/i,
+];
+/**
+ * The single setup-workflow contract for recognisable schema discovery. A
+ * matching command is evidence only after it completed successfully (see
+ * {@link execSucceeded} for what "successfully" means per mode); command
+ * text alone proves neither execution nor a readable schema. Callers use
+ * this for both terminal acceptance and the no-introspection diagnostic,
+ * rather than reimplementing the allowlist elsewhere.
+ */
+export function classifyRecordedSchemaDiscovery(worklog) {
+    let failed;
+    for (const entry of worklog) {
+        const command = isSetupExecutionEntry(entry) ? execCommandOf(entry) : undefined;
+        if (command === undefined ||
+            !SCHEMA_DISCOVERY_EVIDENCE.test(command) ||
+            !SCHEMA_INTROSPECTION_COMMANDS.some((pattern) => pattern.test(command))) {
+            continue;
+        }
+        const succeeded = execSucceeded(entry);
+        if (succeeded === true)
+            return { kind: "successful", command };
+        if (succeeded === false && failed === undefined) {
+            const exitCode = isInProcessShapedExecEntry(entry) ? inProcessExecExitCode(entry.detail) : undefined;
+            failed = { kind: "failed", command, ...(exitCode !== undefined ? { exitCode } : {}) };
+        }
+    }
+    return failed ?? { kind: "none" };
+}
+const SHELL_ENV_ASSIGNMENT = String.raw `[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)`;
+const DIRECT_CONTEXT_LIFECYCLE_COMMAND = new RegExp(String.raw `^\s*(?:(?:${SHELL_ENV_ASSIGNMENT}\s+)*|env\s+(?:${SHELL_ENV_ASSIGNMENT}\s+)+)?wren\s+context\s+(validate|build)(?:\s+--path\s+(?:\.|"\."|'\.'))?\s*$`, "i");
+/**
+ * The mandatory foundation has a native, host-verifiable sequence. A context
+ * success needs schema discovery, then `wren context validate`, then `wren
+ * context build`, each recorded as a successful setup execution. An artifact
+ * alone or merely naming a command in the final message is not evidence.
+ */
+function contextLifecycleStage(command) {
+    // This evidence must describe the actual lifecycle invocation, rather than
+    // merely mention it. `setup_execution` already supplies the project cwd as
+    // a separate structured field; the only shell prefixes we accept here are
+    // environment assignments (including the standard `env KEY=value` form).
+    // The one accepted flag is `--path .`: setup_execution separately binds the
+    // command cwd to the canonical project, so this is the same project-local
+    // lifecycle operation emitted by some Wren guidance. Arbitrary paths, other
+    // flags, shell sequencing, quoted text, and wrappers remain unrecognized.
+    const match = DIRECT_CONTEXT_LIFECYCLE_COMMAND.exec(command);
+    return match?.[1]?.toLowerCase();
+}
+function stageAfter(prefix) {
+    if (prefix === "discovery")
+        return "validate";
+    if (prefix === "validate" || prefix === "build")
+        return "build";
+    return "discovery";
+}
+function prefixFor(stage) {
+    if (stage === "validate")
+        return "discovery";
+    return stage === "build" ? "validate" : "none";
+}
+function scanRecordedContextLifecycle(worklog, prior) {
+    let stage = stageAfter(prior);
+    let completed = prior === "build";
+    let outOfOrderObserved;
+    for (const entry of worklog) {
+        if (!isSetupExecutionEntry(entry) || execSucceeded(entry) !== true)
+            continue;
+        const command = execCommandOf(entry);
+        if (command === undefined)
+            continue;
+        if (stage === "discovery") {
+            if (classifyRecordedSchemaDiscovery([entry]).kind === "successful") {
+                stage = "validate";
+                continue;
+            }
+            if (contextLifecycleStage(command) !== undefined) {
+                outOfOrderObserved ??= `successful \`${command}\` ran before successful schema discovery`;
+            }
+            continue;
+        }
+        const nativeStage = contextLifecycleStage(command);
+        if (stage === "validate") {
+            if (nativeStage === "validate") {
+                stage = "build";
+            }
+            else if (nativeStage === "build") {
+                outOfOrderObserved ??= `successful \`${command}\` ran before successful \`wren context validate\``;
+            }
+            continue;
+        }
+        if (nativeStage === "build")
+            completed = true;
+    }
+    return { stage, completed, outOfOrderObserved };
+}
+/**
+ * Returns the greatest ordered prefix proved by the supplied successful tool
+ * calls. This intentionally retains an earlier valid prefix even if a later
+ * call in the same attempt is out of order, so a corrective attempt can ask
+ * only for the unproven suffix.
+ */
+export function recordedContextLifecyclePrefix(worklog, prior = "none") {
+    const scan = scanRecordedContextLifecycle(worklog, prior);
+    return scan.completed ? "build" : prefixFor(scan.stage);
+}
+export function classifyRecordedContextLifecycle(worklog, prior = "none") {
+    const { stage, completed, outOfOrderObserved } = scanRecordedContextLifecycle(worklog, prior);
+    if (completed)
+        return { kind: "successful" };
+    if (outOfOrderObserved !== undefined)
+        return { kind: "out_of_order", observed: outOfOrderObserved };
+    if (stage === "discovery")
+        return { kind: "missing_discovery" };
+    if (stage === "validate")
+        return { kind: "validate_missing", observed: "no successful `wren context validate` followed successful schema discovery" };
+    return { kind: "build_missing", observed: "no successful `wren context build` followed successful `wren context validate`" };
+}
+/** A narrow terminal-message check: only override a context error that explicitly claims a zero-table/model outcome. */
+function claimsNoTablesOrModels(message) {
+    return /\b(?:no|zero)\s+(?:tables?|models?)\b|\b0\s+(?:tables?|models?)\b/i.test(message);
+}
+/**
+ * Parses the LAST `SETUP_STATUS: ok|needs_input|error` line out of a setup
+ * turn's finalText (the terminal contract lives in the composed
+ * prompt, not warble — the agent is instructed to emit this line, and an
+ * agent narrating its plan mid-message could emit misleading earlier
+ * "SETUP_STATUS"-like text, so only the last line counts).
+ *
+ * For `ok`, independently verifies an on-disk artifact before trusting the
+ * agent's self-report, rather than blindly advancing the wizard — see
+ * `SetupTerminalContext.stepKey`'s doc comment for exactly which artifact each
+ * step checks (`wren_project.yml` / `.wren-validated` / `target/mdl.json`
+ * with at least one model).
+ *
+ * The `context` step's `ok` check also requires a successfully completed
+ * recognized schema-discovery command whenever a worklog is available. It
+ * does NOT try to infer fabrication from model names or columns. Two semantic
+ * heuristics were considered and rejected as unsafe:
+ *   - Flagging a model literally named "example": a real warehouse can
+ *     genuinely have a table named "example" (the composed `context` prompt
+ *     itself explicitly tolerates a pre-existing "example" placeholder
+ *     surviving on disk), so this would false-positive on a legitimate build.
+ *   - Flagging models with zero columns: a fabricating agent writes
+ *     plausible-looking column lists (that's what makes the fabrication
+ *     convincing), so this wouldn't even have caught the real incident —
+ *     it's a weak signal with no compensating safety benefit.
+ * No cheap structural signal reliably distinguishes fabricated MDL from a
+ * real one. The completed-discovery gate is therefore the deterministic
+ * provenance boundary here; the prompt still tells the agent to never
+ * fabricate and to report failed discovery honestly as additional guidance.
+ */
+export function parseSetupTerminal(finalText, context) {
+    const lines = finalText.split("\n");
+    let matched;
+    for (const line of lines) {
+        const match = SETUP_STATUS_LINE.exec(line.trim());
+        if (match) {
+            const status = match[1].toLowerCase();
+            const message = match[2]?.trim();
+            matched = { status, message: message && message.length > 0 ? message : defaultMessageFor(status) };
+        }
+    }
+    if (!matched) {
+        return {
+            status: "error",
+            message: "the setup agent's final message did not contain a SETUP_STATUS line",
+            failureKind: "missing_terminal_status",
+        };
+    }
+    if (matched.status === "ok") {
+        if (context.stepKey === "context") {
+            if (context.worklog !== undefined) {
+                const lifecycle = classifyRecordedContextLifecycle(context.worklog, context.priorContextLifecycle);
+                if (lifecycle.kind === "missing_discovery") {
+                    return hostContractFailure("context_schema_discovery_missing", "The agent never completed recognized schema discovery in its recorded worklog, so its model/build result cannot be accepted. This is an agent-workflow failure, not evidence that the connection or data source lacks tables.", "the recorded worklog has no successful recognized schema-discovery command", [
+                        "run a recognized schema-discovery command against the connected source and make sure it exits successfully",
+                        "build target/mdl.json only from that discovered schema, with at least one model",
+                    ], "no_successful_schema_discovery");
+                }
+                const discovery = classifyRecordedSchemaDiscovery(context.worklog);
+                if (discovery.kind === "failed") {
+                    const exitCodeSuffix = discovery.exitCode !== undefined ? ` with exit code ${discovery.exitCode}` : "";
+                    return hostContractFailure("context_schema_discovery_failed", `\`${discovery.command}\` failed${exitCodeSuffix} during schema discovery — a model/build result cannot be accepted until that command/tool failure is resolved; this is not evidence that the connection or data source lacks tables.`, discovery.exitCode !== undefined
+                        ? `the recorded schema-discovery command exited with code ${discovery.exitCode}`
+                        : "the recorded schema-discovery command failed", [
+                        "resolve the schema-discovery command failure and run a recognized discovery command successfully",
+                        "build target/mdl.json only from that discovered schema, with at least one model",
+                    ]);
+                }
+                if (lifecycle.kind === "validate_missing") {
+                    return hostContractFailure("context_validate_missing", "The agent did not successfully run `wren context validate` after recognized schema discovery, so its model/build result cannot be accepted.", lifecycle.observed, [
+                        "run a recognized schema-discovery command successfully",
+                        "run `wren context validate` successfully before `wren context build`",
+                        "build target/mdl.json only after validation, with at least one model",
+                    ]);
+                }
+                if (lifecycle.kind === "build_missing") {
+                    return hostContractFailure("context_build_missing", "The agent did not successfully run `wren context build` after `wren context validate`, so its claimed context success cannot be accepted.", lifecycle.observed, [
+                        "run a recognized schema-discovery command successfully",
+                        "run `wren context validate` successfully",
+                        "run `wren context build` successfully after validation and produce target/mdl.json with at least one model",
+                    ]);
+                }
+                if (lifecycle.kind === "out_of_order") {
+                    return hostContractFailure("context_lifecycle_out_of_order", "The native context lifecycle ran out of order; Setup requires successful schema discovery followed by `wren context validate` and then `wren context build`.", lifecycle.observed, [
+                        "run a recognized schema-discovery command successfully",
+                        "run `wren context validate` successfully before `wren context build`",
+                        "produce target/mdl.json with at least one schema-derived model",
+                    ]);
+                }
+            }
+            const mdlPath = path.join(context.root, context.name, "target", "mdl.json");
+            if (!existsSync(mdlPath)) {
+                return hostContractFailure("context_mdl_missing", `the setup agent reported "ok" but ${mdlPath} does not exist — treating this as a failed context build`, "target/mdl.json is missing after the claimed context build", ["target/mdl.json must exist", "target/mdl.json must contain at least one model"]);
+            }
+            const modelCount = countMdlModels(mdlPath);
+            if (modelCount < 1) {
+                return hostContractFailure("context_mdl_empty", `the setup agent reported "ok" but ${mdlPath} has ${modelCount} models — treating this as a failed context build`, `target/mdl.json has ${modelCount} models after the claimed context build`, ["target/mdl.json must contain at least one model"]);
+            }
+        }
+        else {
+            const markerName = context.stepKey === "connect_resume" ? ".wren-validated" : "wren_project.yml";
+            const marker = path.join(context.root, context.name, markerName);
+            if (!existsSync(marker)) {
+                return hostContractFailure(context.stepKey === "connect_resume" ? "connection_marker_missing" : "connect_artifact_missing", `the setup agent reported "ok" but ${marker} does not exist — treating this as a failed setup`, `${markerName} is missing after the claimed setup success`, context.stepKey === "connect_resume"
+                    ? ["create .wren-validated only after the connection profile validates successfully"]
+                    : ["create the project directory", "create wren_project.yml", "create the empty .env template"]);
+            }
+            if (context.stepKey === "connect_resume" && context.expectedSourceType !== undefined) {
+                const projectYml = path.join(context.root, context.name, "wren_project.yml");
+                const pinnedProfile = readProjectYamlField(projectYml, "profile");
+                if (pinnedProfile === undefined || pinnedProfile.length === 0) {
+                    return hostContractFailure("connection_profile_missing", `the setup agent reported "ok" but ${projectYml} has no "profile:" pin — the connection profile was never actually pinned to this project (check the profile, not .env)`, "wren_project.yml has no non-empty profile pin", ["wren_project.yml must have a non-empty profile pin", "the pinned profile must match the selected data source"]);
+                }
+                const pinnedDataSource = readProjectYamlField(projectYml, "data_source");
+                if ((pinnedDataSource ?? "").trim().toLowerCase() !== context.expectedSourceType.trim().toLowerCase()) {
+                    return hostContractFailure("connection_source_mismatch", `the setup agent reported "ok" but ${projectYml}'s "data_source: ${pinnedDataSource ?? "(missing)"}" does not match the selected data source "${context.expectedSourceType}" — the connection profile is for the wrong data source (check the profile, not .env)`, `the pinned data source does not match the selected ${context.expectedSourceType} source`, [
+                        "wren_project.yml must have a non-empty profile pin",
+                        `the pinned data_source must match the selected ${context.expectedSourceType} source`,
+                        "create .wren-validated only after the matching profile validates successfully",
+                    ]);
+                }
+            }
+        }
+    }
+    else if (matched.status === "needs_input" && (context.stepKey === undefined || context.stepKey === "connect")) {
+        const missing = missingConnectArtifact(context);
+        if (missing !== undefined) {
+            return {
+                status: "error",
+                message: `the setup agent reported "needs_input" but ${missing} does not exist — treating this as a failed connect`,
+            };
+        }
+    }
+    else if (matched.status === "error" && context.stepKey === "context" && context.worklog !== undefined) {
+        // The agent's own `SETUP_STATUS: error` line for the `context` step routinely
+        // blames the connection or data source (e.g. "schema introspection found no
+        // tables"), but that is only an honest conclusion if an introspection command
+        // actually ran and completed. If the agent instead ran a nonexistent or
+        // otherwise-failing CLI command (its own tool-use mistake, not a fact about
+        // the data source), the "no tables" framing is a false attribution. Before
+        // trusting the agent's message, check the turn's own worklog for a
+        // `setup_execution` call that exited non-zero, and reframe if one is found.
+        const failedExec = firstFailedExec(context.worklog);
+        if (failedExec !== undefined) {
+            const command = failedExec.command !== undefined ? `\`${failedExec.command}\`` : "a command";
+            const exitCodeSuffix = failedExec.exitCode !== undefined ? ` with exit code ${failedExec.exitCode}` : "";
+            return {
+                status: "error",
+                message: `${command} failed${exitCodeSuffix} during this step — a command in this step's own history failed, so this step's error framing can't be trusted until that's ruled out; this is a command/tool failure, not by itself evidence that the connection or data source lacks tables. The agent's own report was: "${matched.message}"`,
+            };
+        }
+        if (claimsNoTablesOrModels(matched.message) && classifyRecordedSchemaDiscovery(context.worklog).kind === "none") {
+            return {
+                status: "error",
+                failureKind: "no_successful_schema_discovery",
+                message: "The agent never attempted schema introspection in its recorded worklog — it reported a zero-table/model outcome without a recognized introspection command. This is an agent-workflow failure, not evidence that the connection or data source lacks tables.",
+            };
+        }
+    }
+    return matched;
+}