akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/workflows/db.js

@@ -3,6 +3,8 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
+import { acquireMaintenanceActivitySync } from "../core/maintenance-barrier.js";
+import { ensureMigrationBackup, getMigrationBackupDir } from "../core/migration-backup.js";
 import { getWorkflowDbPath } from "../core/paths.js";
 import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
@@ -42,18 +44,55 @@ import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
  */
 // ── Public API ───────────────────────────────────────────────────────────────
 export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
-    const dir = path.dirname(dbPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
+    const isCanonical = path.resolve(dbPath) === path.resolve(getWorkflowDbPath());
+    const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("workflow-db") : undefined;
+    let db;
+    try {
+        // Preserve an originally absent workflow.db in the recovery manifest. SQLite
+        // creates the file at open time, so the cutover bundle must exist first.
+        if (isCanonical && !fs.existsSync(getMigrationBackupDir()))
+            ensureMigrationBackup();
+        const dir = path.dirname(dbPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        db = openDatabase(dbPath);
+        // #589: 30 s busy timeout, matching index.db / state.db. Without it the
+        // default is 0 ms, so any concurrent writer fails immediately with
+        // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
+        applyStandardPragmas(db, { dataDir: dir });
+        ensureBaseSchema(db);
+        runMigrations(db, { ensureCutoverBackup: isCanonical });
+        if (!releaseActivity)
+            return db;
+        const openedDb = db;
+        let closed = false;
+        return {
+            prepare: openedDb.prepare.bind(openedDb),
+            exec: openedDb.exec.bind(openedDb),
+            run: openedDb.run.bind(openedDb),
+            transaction: openedDb.transaction.bind(openedDb),
+            get inTransaction() {
+                return openedDb.inTransaction;
+            },
+            close() {
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    openedDb.close();
+                }
+                finally {
+                    releaseActivity();
+                }
+            },
+        };
+    }
+    catch (error) {
+        db?.close();
+        releaseActivity?.();
+        throw error;
     }
-    const db = openDatabase(dbPath);
-    // #589: 30 s busy timeout, matching index.db / state.db. Without it the
-    // default is 0 ms, so any concurrent writer fails immediately with
-    // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
-    applyStandardPragmas(db, { dataDir: dir });
-    ensureBaseSchema(db);
-    runMigrations(db);
-    return db;
 }
 export function closeWorkflowDatabase(db) {
     db.close();
@@ -300,6 +339,13 @@ const MIGRATIONS = [
       ALTER TABLE workflow_run_units ADD COLUMN claim_expires_at TEXT;
     `,
     },
+    {
+        id: "010-ir-v3-engine",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN plan_ir_version INTEGER;
+      ALTER TABLE workflow_run_units ADD COLUMN engine TEXT;
+    `,
+    },
 ];
 /**
  * Stable id of the scope_key migration. Exported for bootstrap detection and
@@ -345,6 +391,12 @@ function bootstrapPreVersioningDb(db) {
  *
  * Called automatically by {@link openWorkflowDatabase}.
  */
-export function runMigrations(db) {
-    runSqliteMigrations(db, MIGRATIONS, { bootstrap: bootstrapPreVersioningDb });
+export function runMigrations(db, options) {
+    runSqliteMigrations(db, MIGRATIONS, {
+        bootstrap: bootstrapPreVersioningDb,
+        beforeMigration(migration) {
+            if (options?.ensureCutoverBackup && migration.id === "010-ir-v3-engine")
+                ensureMigrationBackup();
+        },
+    });
 }

package/dist/workflows/exec/brief.js

@@ -35,10 +35,11 @@ import { NotFoundError, UsageError } from "../../core/errors.js";
 import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
 import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
 import { assertRunParamsSatisfyPlan } from "../ir/params.js";
+import { frozenStepRows, requireExecutableWorkflowPlan } from "../runtime/plan-classifier.js";
 import { snapshotRunForDriver } from "../runtime/runs.js";
 import { evaluateStaleUnits } from "../runtime/unit-checkin.js";
 import { detectSecretShapedParams } from "./param-secrets.js";
-import { activeGateLoop, assertJournaledRouteSelectionsValid, computeStepWorkList, evaluateRoute, GATE_EVALUATION_PHASE, isWorkListFullyTerminal, parseFrozenPlan, recoverGateFeedback, selectUnitAttemptRow, stepOutputsFromEvidence, } from "./step-work.js";
+import { activeGateLoop, assertJournaledRouteSelectionsValid, computeStepWorkList, evaluateRoute, GATE_EVALUATION_PHASE, isWorkListFullyTerminal, recoverGateFeedback, selectUnitAttemptRow, stepOutputsFromEvidence, } from "./step-work.js";
 const EMPTY_WORK_LIST = { isFanOut: false, reducer: null, itemCount: 0, units: [] };
 // ── Entry point ──────────────────────────────────────────────────────────────
 /**
@@ -54,8 +55,6 @@ export async function buildWorkflowBrief(target) {
     // the active step between the spine read and the unit-journal read. A bare run
     // id never auto-starts (we resolved to a concrete id above).
     const { next, run: runRow, units } = await snapshotRunForDriver(runId);
-    const planJson = runRow.plan_json;
-    const planHash = runRow.plan_hash;
     const leaseHolder = runRow.engine_lease_holder;
     const leaseUntil = runRow.engine_lease_until;
     const run = {
@@ -144,7 +143,7 @@ export async function buildWorkflowBrief(target) {
     // Load the FROZEN plan the engine executes (migration 006). A legacy run
     // (NULL plan_json) has no plan for brief to read — point at engine-driven
     // mode, which still handles pre-006 runs by compiling from the asset.
-    const plan = loadFrozenPlanForBrief(run.id, planJson, planHash);
+    const plan = requireExecutableWorkflowPlan(runRow);
     // Reviewer #12: the journaled params row must still satisfy the frozen param
     // schemas — a violation is post-start corruption, loud on the brief surface
     // too (mirrors the frozen-plan hash check and the tampered-params divergence).
@@ -171,13 +170,16 @@ export async function buildWorkflowBrief(target) {
     const gateFeedback = recoverGateFeedback(units, stepState.id, gateLoop);
     const isRouteOnly = !!stepPlan.route && !stepPlan.root;
     const kind = isRouteOnly ? "route" : stepPlan.route ? "execute-and-route" : "execute";
-    const criteria = stepState.completionCriteria ?? [];
+    const criteria = stepPlan.gate.criteria;
+    const instructions = frozenStepRows(plan).find((step) => step.stepId === stepState.id)?.instructions;
+    if (instructions === undefined)
+        throw new UsageError(`Step "${stepState.id}" has no frozen instructions.`);
     const step = {
         stepId: stepState.id,
-        title: stepState.title,
-        sequenceIndex: stepState.sequenceIndex ?? 0,
+        title: stepPlan.title,
+        sequenceIndex: stepPlan.sequenceIndex,
         kind,
-        instructions: stepState.instructions,
+        instructions,
         gate: {
             criteria,
             maxLoops: Math.max(1, stepPlan.gate.maxLoops ?? 1),
@@ -209,6 +211,7 @@ export async function buildWorkflowBrief(target) {
             runId: run.id,
             params: run.params,
             stepOutputs,
+            engines: plan.execution.engines,
             gateLoop,
             ...(gateFeedback ? { gateFeedback } : {}),
         });
@@ -315,15 +318,19 @@ function makeSpineToken(runId, stepId, gateLoop, watermark) {
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
 function toBriefUnit(runId, unit, stepId, journaled, ctx) {
+    if (!unit.engine || !unit.invocation) {
+        throw new UsageError(`Unit "${unit.unitId}" has no complete frozen engine attribution.`);
+    }
     const action = deriveUnitAction(unit, journaled, ctx);
     const report = reportCommandForAction(runId, unit, stepId, action, journaled?.claim_holder ?? null);
     return {
         unitId: unit.unitId,
         nodeId: unit.nodeId,
         index: unit.index,
-        runner: unit.runner,
-        ...(unit.profile ? { profile: unit.profile } : {}),
-        ...(unit.model ? { model: unit.model } : {}),
+        engine: unit.invocation.engine,
+        runtimeKind: unit.runner,
+        platform: unit.engine.kind === "agent" ? unit.engine.platform : null,
+        model: unit.invocation.model,
         timeoutMs: unit.timeoutMs,
         ...(unit.schema ? { outputSchema: unit.schema } : {}),
         // Env asset REF names only — brief never resolves bindings, so no secret
@@ -442,19 +449,6 @@ function buildMessage(step, workList, route, gateLoop, settleState) {
     }
     return `Active step "${step.stepId}" expects ${n} unit(s)${loopNote}. Execute them, then report each result.`;
 }
-/**
- * brief-specific frozen-plan loader: unlike the engine's loader, a NULL
- * plan_json is a hard, actionable error rather than a warn-and-compile — brief
- * describes the frozen plan the engine executes, and a legacy run has none.
- */
-function loadFrozenPlanForBrief(runId, planJson, planHash) {
-    if (!planJson) {
-        throw new UsageError(`Workflow run ${runId} predates frozen plans (no plan_json on the run row) and cannot be described by ` +
-            `\`akm workflow brief\`. Drive it with engine-driven mode instead: \`akm workflow run ${runId}\` ` +
-            `(which compiles a legacy run's plan from the live asset).`);
-    }
-    return parseFrozenPlan(runId, planJson, planHash);
-}
 /**
  * Resolve `target` to a concrete run id WITHOUT starting anything. A run id
  * resolves directly; a workflow ref resolves to its active run in the current

package/dist/workflows/exec/frozen-judge.js

@@ -0,0 +1,47 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { ConfigError } from "../../core/errors.js";
+/** Build a gate judge from a v3 catalog entry without consulting live config. */
+export function frozenSummaryJudge(plan, invocation) {
+    if (!invocation)
+        return null;
+    const engine = plan.execution?.engines[invocation.engine];
+    if (!engine || engine.kind !== "llm")
+        throw new ConfigError(`Frozen gate engine "${invocation.engine}" is unavailable.`, "INVALID_CONFIG_FILE");
+    return async ({ system, user }) => {
+        const { chatCompletion } = await import("../../llm/client.js");
+        return chatCompletion(materialize(engine, invocation), [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ], {
+            timeoutMs: invocation.timeoutMs,
+        });
+    };
+}
+function materialize(engine, invocation) {
+    let apiKey;
+    for (const name of engine.credential?.names ?? []) {
+        const value = process.env[name]?.trim();
+        if (value) {
+            apiKey = value;
+            break;
+        }
+    }
+    if (engine.credential?.required && !apiKey)
+        throw new ConfigError(`Required engine credential ${engine.credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
+    const base = {
+        provider: engine.provider,
+        endpoint: engine.endpoint,
+        model: invocation.model ?? engine.model,
+        ...(engine.temperature !== undefined ? { temperature: engine.temperature } : {}),
+        ...(engine.maxTokens !== undefined ? { maxTokens: engine.maxTokens } : {}),
+        ...(engine.supportsJsonSchema !== undefined ? { supportsJsonSchema: engine.supportsJsonSchema } : {}),
+        ...(engine.extraParams ? { extraParams: engine.extraParams } : {}),
+        ...(engine.contextLength !== undefined ? { contextLength: engine.contextLength } : {}),
+        ...(engine.enableThinking !== undefined ? { enableThinking: engine.enableThinking } : {}),
+        ...(apiKey ? { apiKey } : {}),
+    };
+    return (invocation.llm ? deepMergeConfig(base, invocation.llm) : base);
+}

package/dist/workflows/exec/native-executor.js

@@ -129,9 +129,11 @@
  *   - This module NEVER writes step rows: advancing the gated spine is the
  *     engine loop's job (`run-workflow.ts`) via `completeWorkflowStep`.
  */
+import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { ConfigError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
+import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveValue } from "../../core/redaction.js";
 import { runStructured } from "../../core/structured.js";
 import { warn } from "../../core/warn.js";
 import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
@@ -254,6 +256,7 @@ export async function executeStepPlan(plan, ctx) {
         runId: ctx.runId,
         params: ctx.params,
         stepOutputs: stepOutputsFromEvidence(ctx.evidence),
+        engines: ctx.engines ?? {},
         ...(ctx.gateLoop !== undefined ? { gateLoop: ctx.gateLoop } : {}),
         ...(ctx.gateFeedback ? { gateFeedback: ctx.gateFeedback } : {}),
     });
@@ -310,7 +313,8 @@ export async function executeStepPlan(plan, ctx) {
     // attempt in dispatchJournaledAttempt.
     let worktreeBase;
     if (willDispatch && template.isolation === "worktree") {
-        if (template.runner === "llm") {
+        const engine = template.invocation ? ctx.engines?.[template.invocation.engine] : undefined;
+        if (engine?.kind === "llm") {
             return failedStep(dispatched, `Step "${plan.stepId}" declares isolation: worktree on an llm unit — the llm runner has no ` +
                 `working directory to isolate. Use the agent or sdk runner for worktree-isolated units.`);
         }
@@ -357,6 +361,12 @@ export async function executeStepPlan(plan, ctx) {
         ...(onExceeded ? { onExceeded } : {}),
     });
     let outcomes;
+    const selectedEngine = template.invocation ? ctx.engines?.[template.invocation.engine] : undefined;
+    const selectedLlmEngine = selectedEngine?.kind === "llm"
+        ? selectedEngine
+        : selectedEngine?.kind === "agent" && selectedEngine.fallbackLlmEngine
+            ? ctx.engines?.[selectedEngine.fallbackLlmEngine]
+            : undefined;
     try {
         outcomes = await scheduleUnits(workUnits, (workUnit) => runUnit({
             plan,
@@ -372,6 +382,7 @@ export async function executeStepPlan(plan, ctx) {
             concurrency: workList.list.concurrency,
             signal,
             maxConcurrency: ctx.maxConcurrency,
+            ...(selectedLlmEngine?.kind === "llm" ? { llmConcurrency: selectedLlmEngine.concurrency } : {}),
         });
     }
     finally {
@@ -427,22 +438,32 @@ async function runUnit(input) {
     if (!workUnit.resolved.ok) {
         return { unitId, ok: false, failureReason: "expression_error", error: workUnit.resolved.error };
     }
+    if (!workUnit.engine || !workUnit.invocation) {
+        return {
+            unitId,
+            ok: false,
+            failureReason: "dispatch_error",
+            error: `unit "${unitId}" has no frozen engine snapshot and cannot be dispatched`,
+        };
+    }
     // The prompt (and therefore the input hash) was built once with the BASE
     // unit id by computeStepWorkList: a retry re-dispatches the SAME input, the
     // `~r<n>` suffix is journal bookkeeping only.
     const { prompt, inputHash } = workUnit.resolved;
+    const sensitiveValues = collectWorkflowDispatchSensitiveValues(workUnit, env);
     const request = {
         runId: ctx.runId,
         stepId: plan.stepId,
         unitId,
         nodeId: workUnit.nodeId,
         prompt,
-        runner: workUnit.runner,
-        ...(workUnit.profile ? { profile: workUnit.profile } : {}),
-        ...(workUnit.model ? { model: workUnit.model } : {}),
+        engine: workUnit.engine,
+        ...(workUnit.fallbackEngine ? { fallbackEngine: workUnit.fallbackEngine } : {}),
+        invocation: workUnit.invocation,
         timeoutMs: workUnit.timeoutMs,
         ...(workUnit.schema ? { schema: workUnit.schema } : {}),
         ...(env ? { env } : {}),
+        ...(sensitiveValues.length > 0 ? { sensitiveValues } : {}),
         ...(input.signal ? { signal: input.signal } : {}),
     };
     // Bounded retry (IR v2 failure policy): attempt 0 journals under the base
@@ -560,7 +581,8 @@ async function dispatchJournaledAttempt(input) {
             parentUnitId: workUnit.isFanOut ? `${plan.stepId}.map` : null,
             phase: null,
             runner: workUnit.runner,
-            model: workUnit.model ?? null,
+            engine: request.engine.name,
+            model: request.invocation.model,
             inputHash,
             worktreePath: worktreePath ?? null,
             startedAt: new Date().toISOString(),
@@ -573,7 +595,7 @@ async function dispatchJournaledAttempt(input) {
         ref: ctx.workflowRef,
         metadata: { runId: ctx.runId, stepId: plan.stepId, unitId: attemptId },
     });
-    const outcome = await dispatchUnit(request, dispatcher);
+    const outcome = redactUnitOutcome(await dispatchUnit(request, dispatcher), request.sensitiveValues ?? []);
     await enqueueUnitWrite(async () => {
         await withWorkflowRunsRepo((repo) => repo.finishUnit({
             runId: ctx.runId,
@@ -729,8 +751,8 @@ async function resolveEnvBindings(refs) {
  *   agent → `executeRunner` → `runAgent` (per-harness AgentCommandBuilder)
  *   sdk   → `executeRunner` → `runOpencodeSdk`
  *
- * `inherit` resolves against config: the node/step profile, else
- * `defaults.agent` (sdk when the profile is opencode-sdk), else `defaults.llm`.
+ * Every v3 invocation names a frozen engine; no live profile/default fallback
+ * is consulted during dispatch.
  */
 /**
  * Build the platform-agnostic {@link import("../../integrations/agent/builder-shared.js").AgentDispatchRequest}
@@ -756,15 +778,14 @@ async function resolveEnvBindings(refs) {
 export function buildAgentDispatchRequest(request, prompt) {
     return {
         prompt,
-        ...(request.model ? { model: request.model } : {}),
+        ...(request.invocation.model ? { model: request.invocation.model } : {}),
+        ...(request.invocation.model ? { modelIsExact: true } : {}),
         ...(request.schema ? { schema: request.schema } : {}),
     };
 }
 export const defaultUnitDispatcher = async (request, feedback) => {
-    const { loadConfig } = await import("../../core/config/config.js");
-    const config = loadConfig();
     const prompt = feedback ? `${request.prompt}\n\n${feedback}` : request.prompt;
-    const resolved = await resolveUnitRunner(request, config);
+    const resolved = frozenUnitRunner(request);
     // `env` bindings can only reach a child process. The agent (CLI) runner
     // spawns one per call, and the sdk runner now injects them for real via the
     // env-keyed opencode server registry (sdk-runner.ts module doc, open seam
@@ -794,15 +815,10 @@ export const defaultUnitDispatcher = async (request, feedback) => {
     }
     if (resolved.kind === "llm") {
         const { chatCompletion, LlmCallError } = await import("../../llm/client.js");
-        const { resolveModel } = await import("../../integrations/agent/model-aliases.js");
-        const connection = request.model
-            ? { ...resolved.connection, model: resolveModel(request.model, "llm", undefined, config.modelAliases) }
-            : resolved.connection;
+        const connection = resolved.connection;
         try {
             const text = await chatCompletion(connection, [{ role: "user", content: prompt }], {
-                // null = author declared `timeout: none` — cap at the max signed
-                // 32-bit delay (setTimeout's ceiling, ~24.8 days ≈ unbounded here).
-                timeoutMs: request.timeoutMs === null ? 2 ** 31 - 1 : request.timeoutMs,
+                timeoutMs: request.timeoutMs,
                 ...(request.signal ? { signal: request.signal } : {}),
                 // Native structured output where the connection supports it; the
                 // executor's subset validator still runs downstream either way.
@@ -821,8 +837,16 @@ export const defaultUnitDispatcher = async (request, feedback) => {
         }
     }
     const { executeRunner } = await import("../../integrations/agent/runner-dispatch.js");
-    const profile = request.model ? { ...resolved.profile, model: request.model } : resolved.profile;
-    const result = await executeRunner({ kind: resolved.kind, profile }, prompt, {
+    const profile = request.invocation.model
+        ? { ...resolved.profile, model: request.invocation.model, modelIsExact: true }
+        : resolved.profile;
+    const result = await executeRunner(resolved.kind === "sdk"
+        ? {
+            kind: "sdk",
+            profile,
+            ...(resolved.fallbackConnection ? { fallbackConnection: resolved.fallbackConnection } : {}),
+        }
+        : { kind: "agent", profile }, prompt, {
         stdio: "captured",
         parseOutput: "text",
         timeoutMs: request.timeoutMs,
@@ -863,6 +887,36 @@ export const defaultUnitDispatcher = async (request, feedback) => {
         ...(result.usage ? { usage: result.usage } : {}),
     };
 };
+function collectWorkflowDispatchSensitiveValues(workUnit, env) {
+    const values = new Set(Object.values(env ?? {}));
+    const addCredential = (engine) => {
+        if (!engine)
+            return;
+        if (engine.kind === "llm") {
+            for (const name of engine.credential?.names ?? []) {
+                const value = process.env[name]?.trim();
+                if (value)
+                    values.add(value);
+            }
+            return;
+        }
+        for (const name of engine.envPassthrough) {
+            const value = process.env[name];
+            if (!isEnvPassthroughValueSafeToExpose(name, value) && value)
+                values.add(value);
+        }
+    };
+    addCredential(workUnit.engine);
+    addCredential(workUnit.fallbackEngine);
+    return collectSensitiveValues(values);
+}
+function redactUnitOutcome(outcome, sensitiveValues) {
+    const redacted = redactSensitiveValue(outcome, sensitiveValues);
+    if (outcome.failureReason !== undefined && redacted.failureReason !== outcome.failureReason) {
+        redacted.failureReason = "reported_failure";
+    }
+    return redacted;
+}
 /**
  * Map a typed {@link import("../../llm/client.js").LlmCallErrorCode} into the
  * persisted `AgentFailureReason` taxonomy (agent/spawn.ts) — the ONLY
@@ -897,58 +951,63 @@ export function llmFailureReasonFor(code) {
     }
 }
 /**
- * Resolve the harness `resultExtractor` for an agent profile, mirroring the
- * platform routing of `getCommandBuilder`: the profile's explicit
- * `commandBuilder` wins, else its name (with the `-headless` builtin-variant
- * suffix stripped, same derivation as BUILTIN_BUILDERS). Unknown/custom
- * platforms resolve to no extractor — raw stdout passes through unchanged.
+ * Resolve the harness `resultExtractor` from the canonical platform frozen
+ * from the named engine. Unknown platforms pass raw stdout through unchanged.
  */
 async function resolveHarnessExtractor(profile) {
     const { getHarness } = await import("../../integrations/harnesses/index.js");
-    const platform = profile.commandBuilder ?? profile.name;
-    const harness = getHarness(platform) ?? getHarness(platform.replace(/-headless$/, ""));
+    const harness = getHarness(profile.platform ?? profile.name);
     return harness?.resultExtractor;
 }
-async function resolveUnitRunner(request, config) {
-    const requested = request.runner;
-    if (requested === "llm") {
-        const connection = request.profile
-            ? config.profiles?.llm?.[request.profile]
-            : await requireDefaultLlm(config, request);
-        if (!connection) {
-            throw new ConfigError(`Workflow unit "${request.unitId}" wants llm profile "${request.profile}", which is not in profiles.llm.`, "LLM_NOT_CONFIGURED");
-        }
-        return { kind: "llm", connection };
-    }
-    const profileName = request.profile ?? config.defaults?.agent;
-    if (profileName) {
-        const { resolveProfileFromConfig } = await import("../../integrations/agent/config.js");
-        const profile = resolveProfileFromConfig(profileName, config);
-        if (!profile) {
-            throw new ConfigError(`Workflow unit "${request.unitId}" wants agent profile "${profileName}", which cannot be resolved. ` +
-                `Define profiles.agent."${profileName}" or set defaults.agent.`, "INVALID_CONFIG_FILE");
-        }
-        const inferred = profile.sdkMode ? "sdk" : "agent";
-        if (requested !== "inherit" && requested !== inferred) {
-            throw new ConfigError(`Workflow unit "${request.unitId}" declares runner "${requested}" but profile "${profileName}" is ${profile.sdkMode ? "an opencode-sdk (sdk) profile" : "a CLI (agent) profile"}.`, "INVALID_CONFIG_FILE");
-        }
-        return { kind: inferred, profile };
-    }
-    if (requested === "inherit") {
-        const connection = await requireDefaultLlm(config, request, /* soft */ true);
-        if (connection)
-            return { kind: "llm", connection };
+/** Reconstruct the existing RunnerSpec substrate from the frozen allowlist only. */
+function frozenUnitRunner(request) {
+    const snapshot = request.engine;
+    if (snapshot.kind === "llm") {
+        return { kind: "llm", connection: materializeFrozenLlm(snapshot, request.invocation) };
     }
-    throw new ConfigError(`Workflow unit "${request.unitId}" has no runnable backend: set defaults.agent or defaults.llm in config.json, ` +
-        `or declare a runner/profile on the unit.`, "INVALID_CONFIG_FILE");
+    const profile = {
+        name: snapshot.name,
+        platform: snapshot.platform,
+        bin: snapshot.bin,
+        args: snapshot.args,
+        stdio: "captured",
+        envPassthrough: snapshot.envPassthrough,
+        parseOutput: "text",
+        ...(snapshot.workspace ? { workspace: snapshot.workspace } : {}),
+        ...(request.invocation?.model ? { model: request.invocation.model } : {}),
+        ...(request.invocation?.model ? { modelIsExact: true } : {}),
+    };
+    if (snapshot.runnerKind === "agent")
+        return { kind: "agent", profile };
+    // The catalog is supplied transitively by the work-list only for hashing; the
+    // SDK runner receives a frozen fallback copied into the request by its caller.
+    const fallback = request.fallbackEngine ? materializeFrozenLlm(request.fallbackEngine, undefined) : undefined;
+    return { kind: "sdk", profile, ...(fallback ? { fallbackConnection: fallback } : {}) };
 }
-async function requireDefaultLlm(config, request, soft = false) {
-    const { getDefaultLlmConfig } = await import("../../core/config/config.js");
-    const connection = getDefaultLlmConfig(config);
-    if (!connection && !soft) {
-        throw new ConfigError(`Workflow unit "${request.unitId}" declares runner "llm" but no default LLM is configured (defaults.llm).`, "LLM_NOT_CONFIGURED");
+function materializeFrozenLlm(snapshot, invocation) {
+    let apiKey;
+    for (const name of snapshot.credential?.names ?? []) {
+        const candidate = process.env[name]?.trim();
+        if (candidate) {
+            apiKey = candidate;
+            break;
+        }
     }
-    return connection ?? undefined;
+    if (snapshot.credential?.required && !apiKey)
+        throw new ConfigError(`Required engine credential ${snapshot.credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
+    const base = {
+        provider: snapshot.provider,
+        endpoint: snapshot.endpoint,
+        model: invocation?.model ?? snapshot.model,
+        ...(snapshot.temperature !== undefined ? { temperature: snapshot.temperature } : {}),
+        ...(snapshot.maxTokens !== undefined ? { maxTokens: snapshot.maxTokens } : {}),
+        ...(snapshot.supportsJsonSchema !== undefined ? { supportsJsonSchema: snapshot.supportsJsonSchema } : {}),
+        ...(snapshot.extraParams ? { extraParams: snapshot.extraParams } : {}),
+        ...(snapshot.contextLength !== undefined ? { contextLength: snapshot.contextLength } : {}),
+        ...(snapshot.enableThinking !== undefined ? { enableThinking: snapshot.enableThinking } : {}),
+        ...(apiKey ? { apiKey } : {}),
+    };
+    return invocation?.llm ? deepMergeConfig(base, invocation.llm) : base;
 }
 // ── Small helpers ────────────────────────────────────────────────────────────
 /**