akm-cli 0.10.261012-beta → 0.10.261014-beta

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

@@ -4,12 +4,12 @@
 /**
  * Native executor — executes one frozen step subgraph (`WorkflowPlanStep.root`)
  * locally: fan-out through the scheduler, structured output through
- * `runStructured`, per-unit journaling through the serialized writer queue,
+ * `structuredLoop`, per-unit journaling through the serialized writer queue,
  * and `workflow_unit_*` events. It never writes step rows; advancing the spine
  * is `run-workflow.ts`'s job.
  *
  *  - Data flow: instructions are the step's prose byte-exact; data reaches a
- *    unit as attached context (docs/architecture/decisions/0001-…).
+ *    unit as attached context.
  *  - An empty successful free-text output is journaled as absent, so a live
  *    run and a resume promote the same artifact.
  *  - A declared step `output` schema is validated before the step completes;
@@ -23,26 +23,28 @@
  *  - Run `budget` ceilings are consumed per actual dispatch and abort the step
  *    when crossed, regardless of `on_error`.
  */
-import { appendEvent } from "../../core/events.js";
+import { resolveRefToken } from "../../commands/env/env-binding.js";
+import { isInstalledBundle } from "../../core/env-secret-ref.js";
+import { NotFoundError } from "../../core/errors.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
-import { runStructured } from "../../core/structured.js";
+import { substituteRefTokens } from "../../core/ref-token.js";
 import { warn } from "../../core/warn.js";
-import { assertFrozenDirectoryContained } from "../../execution/directory-identity.js";
+import { mergeNotices } from "../../execution/notices.js";
+import { isRefused, jsonParser, structuredLoop } from "../../llm/structured.js";
 import { withWorkflowRunsConnection, withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
 import { WORKFLOW_UNIT_DIAGNOSTIC_CLIP } from "../resource-limits.js";
+import { resolveRunBundleRoot } from "../runtime/workflow-asset-loader.js";
 // The ONE child-workflow drive — publishes and drives a
 // `child-workflow`-targeted unit; this module's dispatch seam is its only
 // production caller.
 import { driveChildWorkflowUnit } from "./child-workflow.js";
-// The ONE dispatch redaction contract, shared with the gate-judge path
-// (exec/frozen-judge.ts). Consumers import the leaf directly — this module is
+// The unit outcome scrub. Consumers import the leaf directly — this module is
 // not a second front door onto the seam.
 import { collectWorkflowDispatchSensitiveValues, redactUnitOutcome } from "./dispatch-redaction.js";
 import { materializeFrozenWorkflowEnvironment } from "./environment.js";
 // The exec (shell) unit runner — a leaf that owns argv spawning, containment,
 // and the process-outcome → failure-reason mapping.
 import { runExecUnit } from "./exec-unit.js";
-import { mergeLoweringNotices } from "./lowering-notices.js";
 import { secretShapedParamValues } from "./param-secrets.js";
 import { scheduleUnits } from "./scheduler.js";
 // Shared step semantics — the ONE implementation consumed by the engine
@@ -167,22 +169,28 @@ function openDispatchBudget(ctx, dispatched) {
 }
 /** Resolve the live-at-dispatch prerequisites once, after durable-row reuse is known. */
 async function prepareStepDispatchPrerequisites(input) {
-    const { plan, workUnits, willDispatch, dispatched } = input;
+    const { plan, ctx, workUnits, willDispatch, dispatched } = input;
     let env;
     let sensitiveValues;
+    // The run's bundle is found again here, never frozen: a bundle update moves it to a new directory.
+    let cwd = ctx.bundleRootOverride;
+    if (willDispatch && cwd === undefined) {
+        try {
+            cwd = resolveRunBundleRoot(ctx.workflowRef);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                result: failedStep(dispatched, `Step "${plan.stepId}" cannot run: ${message(err).replace(/\.$/, "")}.`),
+            };
+        }
+    }
     const frozenEnvironment = workUnits[0]?.environment;
     if (willDispatch && frozenEnvironment && frozenEnvironment.length > 0) {
         try {
             const materialized = materializeFrozenWorkflowEnvironment(frozenEnvironment);
             env = materialized.values;
             sensitiveValues = materialized.sensitiveValues;
-            for (const audit of materialized.audits) {
-                appendEvent({
-                    eventType: audit.eventType,
-                    ref: audit.ref,
-                    metadata: { keys: audit.keys, secretNames: audit.secretNames },
-                });
-            }
         }
         catch (err) {
             return {
@@ -193,6 +201,7 @@ async function prepareStepDispatchPrerequisites(input) {
     }
     return {
         ok: true,
+        ...(cwd !== undefined ? { cwd } : {}),
         ...(env ? { env } : {}),
         ...(sensitiveValues ? { sensitiveValues } : {}),
     };
@@ -229,13 +238,14 @@ async function executeStepPlanInConnection(plan, ctx) {
     const willDispatch = reuseDecisions.some((decision) => decision.kind === "dispatch");
     const prerequisites = await prepareStepDispatchPrerequisites({
         plan,
+        ctx,
         workUnits,
         willDispatch,
         dispatched,
     });
     if (!prerequisites.ok)
         return prerequisites.result;
-    const { env, sensitiveValues } = prerequisites;
+    const { cwd, env, sensitiveValues } = prerequisites;
     // Budget ceilings + lifetime-cap accounting, and the budget-chained abort
     // signal they trip. Extracted verbatim (behavior-identical) — see
     // {@link openDispatchBudget}.
@@ -246,6 +256,7 @@ async function executeStepPlanInConnection(plan, ctx) {
         outcomes = await scheduleUnits(workUnits, (workUnit, index) => runUnit({
             plan,
             workUnit,
+            cwd,
             env,
             sensitiveValues,
             ctx,
@@ -267,7 +278,7 @@ async function executeStepPlanInConnection(plan, ctx) {
     // list with a failed-step envelope. Budget/cap and journal-write failures
     // must not erase notices already observed from real dispatches; durable row
     // reuses naturally contribute none.
-    const notices = mergeLoweringNotices(...outcomes.map((outcome) => outcome?.notices));
+    const notices = mergeNotices(...outcomes.map((outcome) => outcome?.notices));
     // A declared budget ceiling is a hard backstop: a step that hit one FAILS
     // regardless of on_error policy (a capped run must never quietly pass its
     // gate). The budget message names WHICH ceiling tripped.
@@ -299,7 +310,7 @@ async function executeStepPlanInConnection(plan, ctx) {
     };
 }
 async function runUnit(input) {
-    const { plan, workUnit, env, sensitiveValues, ctx, dispatcher } = input;
+    const { plan, workUnit, cwd, env, sensitiveValues, ctx, dispatcher } = input;
     const unitId = workUnit.unitId;
     // Target validity is a WHOLE-LIST invariant, never a per-unit condition:
     // computeStepWorkList rejects a step before building any unit when its sole
@@ -317,10 +328,7 @@ async function runUnit(input) {
         prompt,
         frozenTarget: workUnit.frozenTarget,
         ...(workUnit.execContext ? { execContext: workUnit.execContext } : {}),
-        // An exec unit spawns in the engine invocation's working directory. Only
-        // exec units get it: handing an agent unit a cwd it never had would change
-        // harness behavior, and the agent path already takes its cwd from its profile.
-        ...(workUnit.frozenTarget.kind !== "command" && ctx.workDir !== undefined ? { cwd: ctx.workDir } : {}),
+        ...(cwd !== undefined ? { cwd } : {}),
         timeoutMs: workUnit.timeoutMs,
         ...(workUnit.schema ? { schema: workUnit.schema } : {}),
         ...(env ? { env } : {}),
@@ -432,8 +440,8 @@ async function reserveJournaledDispatch(input, startedAt) {
                 parentUnitId: workUnit.isFanOut ? `${plan.stepId}.map` : null,
                 phase: "unit",
                 runner: workUnit.runner,
-                engine: target.kind === "command" ? target.request.engine.name : null,
-                model: target.kind === "command" ? (target.request.model?.resolved ?? null) : null,
+                engine: target.kind === "command" ? target.request.target.name : null,
+                model: target.kind === "command" ? (target.request.model?.model ?? null) : null,
                 inputHash,
                 now: startedAt,
             }).attempt;
@@ -498,6 +506,7 @@ async function dispatchJournaledAttempt(input) {
     };
     // A child-workflow unit goes to the child executor instead of the
     // dispatcher, after its attempt row is reserved, so it journals like any unit.
+    const resolvedSecrets = new Set();
     const dispatched = request.frozenTarget.kind === "child-workflow"
         ? await driveChildWorkflowUnit({
             request,
@@ -507,17 +516,18 @@ async function dispatchJournaledAttempt(input) {
             inputHash: input.inputHash,
             dispatcher,
         })
-        : await dispatchUnit(request, dispatcher);
+        : await dispatchUnit(request, dispatcher, resolvedSecrets);
     // Credential and passthrough values are intentionally sampled only AFTER
-    // the default dispatcher has authorized/lowered the frozen request and
+    // the default dispatcher has lowered the frozen request and
     // materialized credentials at its terminal dispatch boundary. Custom test
     // dispatchers receive the same post-dispatch journal scrub. Secret-shaped
     // run params join the set: they must reach the prompt in clear (the unit
-    // needs them), but nothing about them needs to reach the journal.
+    // needs them), but nothing about them needs to reach the journal. So do the
+    // secrets the dispatcher resolved itself (an exec unit's argv/cwd tokens).
     const sensitiveValues = collectWorkflowDispatchSensitiveValues({
         ...(request.frozenTarget.kind === "command" ? { runner: request.frozenTarget.runner } : {}),
-        sensitiveValues: [...(request.sensitiveValues ?? []), ...secretShapedParamValues(ctx.params)],
-    }, request.env);
+        sensitiveValues: [...(request.sensitiveValues ?? []), ...resolvedSecrets, ...secretShapedParamValues(ctx.params)],
+    });
     const outcome = redactUnitOutcome(dispatched, sensitiveValues);
     const finishedAt = new Date().toISOString();
     // A dispatched unit's outcome is NEVER silently discarded: the attempt is
@@ -566,7 +576,7 @@ async function dispatchJournaledAttempt(input) {
  * and hunts for a JSON island inside prose, which is the right forgiving
  * behavior for an LLM and the wrong one for a command, where it would silently
  * promote a JSON fragment found in unrelated log noise as the typed artifact.
- * Returning `undefined` makes `runStructured` report `parse_error` (a real
+ * Returning `undefined` makes the structured loop report `parse_error` (a real
  * member of the retry taxonomy), so `retry.on: [parse_error]` still works.
  */
 function parseExecJson(raw) {
@@ -580,16 +590,9 @@ function parseExecJson(raw) {
         return undefined;
     }
 }
-/** Transport failures surface as this sentinel so runStructured doesn't retry them. */
-class UnitTransportError extends Error {
-    result;
-    constructor(result) {
-        super(result.error ?? "unit dispatch failed");
-        this.result = result;
-        this.name = "UnitTransportError";
-    }
-}
-async function dispatchUnit(request, dispatcher) {
+async function dispatchUnit(request, dispatcher, 
+/** Receives the secret values the dispatcher resolved, for the caller's journal scrub. */
+resolvedSecrets) {
     let tokens = 0;
     let sawUsage = false;
     let loweringNotices;
@@ -600,20 +603,36 @@ async function dispatchUnit(request, dispatcher) {
     let sessionId;
     const dispatchOnce = async (feedback) => {
         const result = await dispatcher(request, feedback);
+        for (const value of result.sensitiveValues ?? [])
+            resolvedSecrets.add(value);
         if (result.usage) {
             sawUsage = true;
             tokens +=
                 (result.usage.inputTokens ?? 0) + (result.usage.outputTokens ?? 0) + (result.usage.reasoningTokens ?? 0);
         }
-        loweringNotices = mergeLoweringNotices(loweringNotices, result.notices);
+        loweringNotices = mergeNotices(loweringNotices, result.notices);
         // Capture before the ok-check: a failed attempt can still have configured
         // a session (e.g. codex `session_configured` then a tool crash).
         if (result.sessionId !== undefined)
             sessionId = result.sessionId;
-        if (!result.ok)
-            throw new UnitTransportError(result);
-        return result.text;
+        if (!result.ok) {
+            return {
+                ok: false,
+                failureReason: result.failureReason ?? "dispatch_error",
+                error: result.error ?? "unit dispatch failed",
+                text: result.text,
+            };
+        }
+        return { ok: true, raw: result.text };
     };
+    const transportFailed = (failure) => ({
+        unitId: request.unitId,
+        ok: false,
+        failureReason: failure.failureReason,
+        error: failure.error,
+        text: failure.text,
+        ...captured(),
+    });
     const captured = () => ({
         ...(sawUsage ? { tokens } : {}),
         ...(sessionId !== undefined ? { sessionId } : {}),
@@ -622,28 +641,42 @@ async function dispatchUnit(request, dispatcher) {
     try {
         if (request.schema) {
             const schema = request.schema;
-            const structured = await runStructured({
-                dispatch: dispatchOnce,
+            const validate = (candidate) => {
+                const errors = validateJsonSchemaSubset(candidate, schema);
+                return errors.length === 0
+                    ? { ok: true, value: candidate }
+                    : { ok: false, errors, reason: "validation_error" };
+            };
+            const structured = await structuredLoop({
+                dispatch: (correction) => dispatchOnce(correction?.text),
                 // A command is not re-promptable. Its stdout must be EXACTLY one JSON
                 // value: the default embedded-JSON scan (fences, think-blocks, "find the
                 // JSON inside the prose") is right for an LLM and wrong for a command,
                 // where it would pluck a JSON fragment out of unrelated log noise and
-                // promote it as the typed artifact. And it gets exactly ONE attempt —
-                // `runStructured`'s corrective retry re-dispatches with feedback, which
+                // promote it as the typed artifact. And it gets exactly ONE attempt:
+                // the loop's corrective retry re-dispatches with feedback, which
                 // for a command means running a SIDE-EFFECTING process a second time
                 // with byte-identical argv: it cannot produce different output, and it
                 // can produce a second deployment. Declared `retry:` still applies (the
                 // executor's own loop), because that is a policy the author opted into
                 // per failure reason.
-                ...(request.frozenTarget.kind !== "command" ? { parse: parseExecJson, maxAttempts: 1 } : {}),
-                validate: (candidate) => {
-                    const errors = validateJsonSchemaSubset(candidate, schema);
-                    return errors.length === 0 ? { ok: true, value: candidate } : { ok: false, errors };
-                },
+                ...(request.frozenTarget.kind !== "command"
+                    ? {
+                        attempts: 1,
+                        parse: (raw) => {
+                            const candidate = parseExecJson(raw);
+                            return candidate === undefined
+                                ? { ok: false, errors: ["no JSON structure found in response"], reason: "parse_error" }
+                                : validate(candidate);
+                        },
+                    }
+                    : { parse: jsonParser(validate) }),
             });
             if (structured.ok) {
                 return { unitId: request.unitId, ok: true, result: structured.value, ...captured() };
             }
+            if (!isRefused(structured))
+                return transportFailed(structured);
             return {
                 unitId: request.unitId,
                 ok: false,
@@ -661,7 +694,10 @@ async function dispatchUnit(request, dispatcher) {
                 ...captured(),
             };
         }
-        const text = await dispatchOnce();
+        const dispatched = await dispatchOnce();
+        if (!dispatched.ok)
+            return transportFailed(dispatched);
+        const text = dispatched.raw;
         // Normalize an EMPTY successful output to "no text". `finishUnitAttempt` journals
         // result_json = NULL for a falsy text, so durable-reuse rehydrates NO text
         // from the row (unitOutcomeFromRow). Preserving `text: ""` only in this live
@@ -672,16 +708,6 @@ async function dispatchUnit(request, dispatcher) {
         return { unitId: request.unitId, ok: true, ...(text ? { text } : {}), ...captured() };
     }
     catch (err) {
-        if (err instanceof UnitTransportError) {
-            return {
-                unitId: request.unitId,
-                ok: false,
-                failureReason: err.result.failureReason ?? "dispatch_error",
-                error: err.result.error ?? "unit dispatch failed",
-                text: err.result.text,
-                ...captured(),
-            };
-        }
         return {
             unitId: request.unitId,
             ok: false,
@@ -693,19 +719,21 @@ async function dispatchUnit(request, dispatcher) {
 }
 // ── Default dispatcher (production substrate) ───────────────────────────────
 /**
- * Dispatch a frozen engine through the common prepare → lower → dispatch seam.
+ * Dispatch a frozen connection or harness through the common prepare → lower → dispatch seam.
  * No live profile/default/model map is consulted, and credentials remain
  * symbolic until the final dispatch boundary.
  */
 export const defaultUnitDispatcher = async (request, feedback) => {
     const frozenTarget = request.frozenTarget;
     if (frozenTarget.kind === "shell") {
-        if (frozenTarget.cwdIdentity)
-            assertFrozenDirectoryContained(frozenTarget.cwdIdentity);
-        return runExecUnit({
+        if (request.cwd === undefined) {
+            throw new Error(`exec unit "${request.unitId}" was dispatched with no working directory.`);
+        }
+        const { exec, secretValues } = substituteExecRefs(request.unitId, frozenTarget.exec);
+        const outcome = await runExecUnit({
             unitId: request.unitId,
-            exec: frozenTarget.exec,
-            baseDir: request.cwd ?? frozenTarget.cwdIdentity?.realCwd ?? process.cwd(),
+            exec,
+            baseDir: request.cwd,
             ...(request.env ? { env: request.env } : {}),
             ...(request.execContext ? { context: request.execContext } : {}),
             ...(request.schema ? { hasOutputSchema: true } : {}),
@@ -713,9 +741,36 @@ export const defaultUnitDispatcher = async (request, feedback) => {
             ...(request.signal ? { signal: request.signal } : {}),
             ...(request.eventSource !== undefined ? { eventSource: request.eventSource } : {}),
         });
+        // A secret substituted into argv joins the redaction set, like one bound through an env asset: the
+        // executor scrubs after the structured parse, so a quoted or numeric secret is not missed or corrupted.
+        return { ...outcome, sensitiveValues: secretValues };
     }
     return dispatchWorkflowExecution(request, feedback);
 };
+/**
+ * Replace the `${ref}` tokens in an exec unit's argv and `cwd` (prompts are not substituted): a
+ * `secrets/` ref with the secret's value, any other asset ref with its absolute path. A ref no
+ * bundle owns fails the unit before anything is spawned.
+ */
+function substituteExecRefs(unitId, exec) {
+    const slots = Object.fromEntries(exec.command.entries());
+    if (exec.cwd !== undefined)
+        slots.cwd = exec.cwd;
+    const { values, missing, secretValues } = substituteRefTokens(slots, resolveRefToken, isInstalledBundle);
+    if (missing.length > 0) {
+        throw new NotFoundError(`exec unit "${unitId}" references asset(s) that no bundle owns: ${missing.join(", ")}. Nothing was run.`, "FILE_NOT_FOUND", 
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: literal `${ref}` token syntax documented for users, not interpolation
+        "Write each `${ref}` as a full akm ref that exists, e.g. `${team//scripts/run.sh}`.");
+    }
+    return {
+        exec: {
+            ...exec,
+            command: exec.command.map((_, index) => values[index]),
+            ...(exec.cwd !== undefined ? { cwd: values.cwd } : {}),
+        },
+        secretValues,
+    };
+}
 // ── Small helpers ────────────────────────────────────────────────────────────
 /**
  * Rehydrate a journaled completed unit row into a UnitOutcome (durable-row

package/dist/workflows/exec/run-workflow.js

@@ -6,25 +6,22 @@
  * execute path. akm walks the frozen plan (read from `plan_json`, never live
  * source) and dispatches every unit itself; every step advances through
  * `completeWorkflowStep`; one O_EXCL lock file per run keeps a second driver
- * off (a dead holder's lock is reclaimed); gate loops are bounded; and the
- * SDK dispatch registry is drained on every exit so the process can exit.
- * See docs/architecture/decisions/0011-engine-run-loop-invariants.md.
+ * off (a dead holder's lock is reclaimed); and gate loops are bounded.
  */
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { TransientError, UsageError } from "../../core/errors.js";
-import { releaseLock } from "../../core/file-lock.js";
+import { probeLock, releaseLock } from "../../core/file-lock.js";
 import { formatLockHolderPid, tryAcquireRunLock } from "../../core/run-lock.js";
-import { disposeDispatchResources } from "../../integrations/agent/runner-dispatch.js";
+import { mergeNotices } from "../../execution/notices.js";
 import { resolveStorageLocations } from "../../storage/locations.js";
 import { withWorkflowRunsConnection, withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
 import { computePlanHash } from "../ir/plan-hash.js";
 import { decodeWorkflowPlan, readRunPlan } from "../runtime/run-plan.js";
-import { abandonWorkflowRun, getNextWorkflowStep, resumeWorkflowRun } from "../runtime/runs.js";
+import { abandonWorkflowRun, getNextWorkflowStep, listWorkflowRuns, resolveWorkflowRunTarget, resumeWorkflowRun, } from "../runtime/runs.js";
 import { loadWorkflowAsset } from "../runtime/workflow-asset-loader.js";
-import { frozenSummaryJudge } from "./frozen-judge.js";
-import { mergeLoweringNotices } from "./lowering-notices.js";
+import { frozenSummaryJudge, resolveJudgeCwd } from "./frozen-judge.js";
 import { defaultUnitDispatcher, executeStepPlan, } from "./native-executor.js";
 // Shared step semantics — gate-evaluation journaling, and the whole step-completion path
 // (`finalizeExecutedStep`) live in step-work.ts as ONE implementation, so the
@@ -34,10 +31,6 @@ export async function runWorkflowSteps(options) {
     let target = options.target;
     let params = options.params;
     let parameterFlags = options.parameterFlags;
-    // `--new` only applies to the FIRST resolution of `target` (a ref); every
-    // retry re-targets the run id `startWorkflowRun` already created, so it is
-    // cleared alongside `params`/`parameterFlags` below (#919).
-    let newRun = options.newRun;
     let remainingRetries = options.maxRetries ?? 0;
     let remainingSteps = options.maxSteps;
     const executed = [];
@@ -53,12 +46,11 @@ export async function runWorkflowSteps(options) {
             target,
             ...(params !== undefined ? { params } : { params: undefined }),
             ...(parameterFlags !== undefined ? { parameterFlags } : { parameterFlags: undefined }),
-            newRun,
             ...(remainingSteps !== undefined ? { maxSteps: remainingSteps } : { maxSteps: undefined }),
         }, liveEvidence);
         executed.push(...result.executed);
         stepsProcessed += result.stepsProcessed;
-        const notices = mergeLoweringNotices(...executed.map((step) => step.notices));
+        const notices = mergeNotices(...executed.map((step) => step.notices));
         const aggregate = { ...result, executed, stepsProcessed, ...(notices ? { notices } : {}) };
         // An attempt that executed nothing (an abandoned, undecodable plan) has no
         // failed step for a retry to re-open.
@@ -81,14 +73,12 @@ export async function runWorkflowSteps(options) {
         target = result.run.id;
         params = undefined;
         parameterFlags = undefined;
-        newRun = undefined;
         remainingRetries -= 1;
     }
 }
 async function runWorkflowAttempt(options, liveEvidence) {
     const next = await getNextWorkflowStep(options.target, options.params, {
         parameterFlags: options.parameterFlags,
-        newRun: options.newRun,
     });
     // Refuse non-active runs BEFORE any dispatch — completeWorkflowStep would
     // reject the completion anyway, but only after the units already ran (and
@@ -125,7 +115,6 @@ async function runWorkflowAttempt(options, liveEvidence) {
                     executed: [],
                     stepsProcessed: 0,
                     warnings: [...warnings, message],
-                    ...(next.resumed ? { resumed: true } : {}),
                 };
             }
             plan = read.plan;
@@ -141,37 +130,43 @@ async function runWorkflowAttempt(options, liveEvidence) {
         // Creation/resume-time notices reach the caller only here: the run row
         // has no warnings column, and a later invocation of the same run must
         // stay silent about a decision it did not make. `driveRun` never sets
-        // `warnings` or `resumed` — both are properties of THIS resolution of
-        // `target`, not of the run row (#919).
+        // `warnings` — it is a property of THIS resolution of `target`, not of
+        // the run row.
         return {
             ...result,
-            ...(next.resumed ? { resumed: true } : {}),
             ...(warnings.length > 0 ? { warnings } : {}),
         };
     }
     finally {
-        try {
-            if (lock)
-                releaseLock(lock);
-        }
-        finally {
-            // Process-lifecycle drain (owner finding 4): release any cached SDK server
-            // child processes so a one-shot CLI invocation exits cleanly instead of
-            // hanging on the leaked handle. Runs even if the lock release itself
-            // fails; a teardown-time error must not skip dispatch cleanup.
-            try {
-                await (options.disposeDispatchResources ?? disposeDispatchResources)();
-            }
-            catch {
-                /* disposal is best-effort; never let cleanup mask the run outcome */
-            }
-        }
+        if (lock)
+            releaseLock(lock);
     }
 }
 /** The per-run lock file: `<data dir>/workflow-run-locks/<run id>.lock`, next to `state.db`. */
 export function workflowRunLockPath(runId) {
     return path.join(path.dirname(resolveStorageLocations().stateDb), "workflow-run-locks", `${runId}.lock`);
 }
+/**
+ * `--skip-if-locked` for a workflow REF (#1239): an active run of `ref` whose
+ * lock a live process holds, or `undefined`. A run id (which drives that one
+ * run, and fails with `RUN_LEASE_HELD` if it is held) is never a ref. Read-only:
+ * `probeLock` reports a dead holder as stale without reclaiming it.
+ */
+export async function findLiveLockedRunOfRef(target) {
+    if ((await resolveWorkflowRunTarget(target)) !== undefined)
+        return undefined;
+    const { runs } = await listWorkflowRuns({ workflowRef: target, activeOnly: true });
+    for (const run of runs) {
+        const probe = probeLock(workflowRunLockPath(run.id));
+        if (probe.state === "held") {
+            return {
+                runId: run.id,
+                holder: formatLockHolderPid({ pid: probe.holderPid, launcherPid: probe.launcherPid ?? null }),
+            };
+        }
+    }
+    return undefined;
+}
 /**
  * Take the run's O_EXCL lock file, or refuse with `RUN_LEASE_HELD` (exit 75)
  * naming the live holder. A lock whose holder pid is dead is reclaimed by
@@ -215,7 +210,7 @@ async function workflowSourceDriftWarning(runId, workflowRef, plan) {
     if (current === plan.sourceHash)
         return undefined;
     return (`Workflow run ${runId}: ${workflowRef} (${sourcePath}) has changed since this run was frozen; ` +
-        `continuing with the frozen plan. Start a new run with 'akm workflow run ${workflowRef} --new' to pick up the edit.`);
+        `continuing with the frozen plan. Start a new run with 'akm workflow run ${workflowRef}' to pick up the edit.`);
 }
 /**
  * A terminal run is a pure no-op: do not load or integrity-check its frozen
@@ -230,11 +225,11 @@ async function completedRunResult(runId) {
         ...(doneState.run.status === "completed" ? { done: true } : {}),
     };
 }
-function workflowSummaryJudge(options, stepPlan, signal, owner) {
+function workflowSummaryJudge(options, stepPlan, signal, owner, workflowRef) {
     if (options.summaryJudge !== undefined)
         return options.summaryJudge;
     // The judge dispatches under the real run/step identity and the same event source as units.
-    return frozenSummaryJudge(stepPlan.gate.frozenJudge, signal, options.dispatcher ?? defaultUnitDispatcher, owner, options.eventSource);
+    return frozenSummaryJudge(stepPlan.gate.frozenJudge, signal, options.dispatcher ?? defaultUnitDispatcher, owner, options.eventSource, options.bundleRootOverride ?? resolveJudgeCwd(stepPlan.gate.frozenJudge, workflowRef));
 }
 /**
  * Seed the run's budget from the append-only attempt journal so a resumed run
@@ -307,6 +302,7 @@ async function executeStepSubgraph(ctx, loop) {
         ...(options.eventSource !== undefined ? { eventSource: options.eventSource } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
         ...(options.dispatcher ? { dispatcher: options.dispatcher } : {}),
+        ...(options.bundleRootOverride !== undefined ? { bundleRootOverride: options.bundleRootOverride } : {}),
         maxConcurrency: Math.min(options.maxConcurrency ?? Number.POSITIVE_INFINITY, plan.execution?.maxConcurrency ?? 1),
     });
 }
@@ -484,7 +480,7 @@ liveEvidence) {
             break;
         }
         // Judge-outage contract: resolve the step's frozen completion judge BEFORE
-        // any dispatch. An unresolvable judge (missing frozen engine, no dispatcher
+        // any dispatch. An unresolvable judge (missing frozen connection or harness, no dispatcher
         // for an agent judge) is verifier INFRASTRUCTURE failure — block the step
         // for `akm workflow resume` instead of spending on units the gate can never
         // verify. No gate loop is consumed and nothing is dispatched.
@@ -493,7 +489,7 @@ liveEvidence) {
             summaryJudge = workflowSummaryJudge(options, stepPlan, options.signal, {
                 runId: next.run.id,
                 stepId: step.id,
-            });
+            }, next.run.workflowRef);
         }
         catch (error) {
             const detail = error instanceof Error && error.message ? ` (${error.message})` : "";
@@ -541,7 +537,7 @@ liveEvidence) {
     }
     // Re-read for the freshest run state (the loop may have exited on maxSteps).
     const finalState = await getNextWorkflowStep(next.run.id);
-    const notices = mergeLoweringNotices(...executed.map((step) => step.notices));
+    const notices = mergeNotices(...executed.map((step) => step.notices));
     return {
         run: finalState.run,
         executed,