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

package/dist/workflows/runtime/plan-classifier.js

@@ -0,0 +1,131 @@
+// 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 { UsageError } from "../../core/errors.js";
+import { decodeCanonicalPlan } from "../ir/plan-hash.js";
+import { WORKFLOW_IR_VERSION } from "../ir/schema.js";
+/** Validate that a live run carries exactly the current frozen-plan format. */
+export function classifyWorkflowRunPlan(row) {
+    const runId = row.id ?? "(unknown)";
+    if (!row.plan_json) {
+        return {
+            support: "missing-plan",
+            irVersion: row.plan_ir_version ?? null,
+            error: `Workflow run ${runId} has no frozen workflow plan.`,
+        };
+    }
+    if (row.plan_ir_version !== null &&
+        row.plan_ir_version !== undefined &&
+        row.plan_ir_version !== WORKFLOW_IR_VERSION) {
+        return {
+            support: "unsupported-version",
+            irVersion: row.plan_ir_version,
+            error: `Workflow run ${runId} uses unsupported workflow IR version ${row.plan_ir_version}; this runtime requires version ${WORKFLOW_IR_VERSION}.`,
+        };
+    }
+    if (row.plan_ir_version !== WORKFLOW_IR_VERSION) {
+        return {
+            support: "corrupt-plan",
+            irVersion: null,
+            error: `Workflow run ${runId} does not declare workflow IR version ${WORKFLOW_IR_VERSION}.`,
+        };
+    }
+    try {
+        return {
+            support: "supported",
+            irVersion: WORKFLOW_IR_VERSION,
+            plan: decodeCanonicalPlan(runId, row.plan_json, row.plan_hash),
+        };
+    }
+    catch (cause) {
+        return {
+            support: "corrupt-plan",
+            irVersion: WORKFLOW_IR_VERSION,
+            error: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+}
+/** Reject any operation that requires a valid current frozen plan. */
+export function requireExecutableWorkflowPlan(row) {
+    const classified = classifyWorkflowRunPlan(row);
+    if (classified.support === "supported")
+        return classified.plan;
+    throw new UsageError(classified.error, "INVALID_JSON_ARGUMENT");
+}
+/** Project persisted spine rows from the decoded plan, never from the mutable source asset. */
+export function frozenStepRows(plan) {
+    return plan.steps.map((step) => ({
+        stepId: step.stepId,
+        stepTitle: step.title,
+        instructions: step.root
+            ? step.root.kind === "map"
+                ? step.root.template.instructions
+                : step.root.instructions
+            : routeInstructions(step.route),
+        completionJson: step.gate.criteria.length > 0 ? JSON.stringify(step.gate.criteria) : null,
+        sequenceIndex: step.sequenceIndex,
+    }));
+}
+/** Verify the durable spine still agrees with the decoded/hash-verified plan before any mutation. */
+export function assertWorkflowSpineMatchesPlan(plan, run, rows) {
+    const expected = frozenStepRows(plan);
+    if (rows.length !== expected.length)
+        corruptSpine(run.id, "step count differs from the frozen plan");
+    for (let index = 0; index < expected.length; index++) {
+        const actual = rows[index];
+        const planned = expected[index];
+        // The length check above (corruptSpine returns `never`) guarantees both are
+        // present; the guard narrows them and preserves the "missing row" message.
+        if (!actual || !planned) {
+            corruptSpine(run.id, `step row ${index} differs from the frozen plan (missing row)`);
+        }
+        if (actual.step_id !== planned.stepId ||
+            actual.step_title !== planned.stepTitle ||
+            actual.instructions !== planned.instructions ||
+            actual.completion_json !== planned.completionJson ||
+            actual.sequence_index !== planned.sequenceIndex) {
+            const fields = [
+                actual.step_id !== planned.stepId ? "step_id" : "",
+                actual.step_title !== planned.stepTitle ? "step_title" : "",
+                actual.instructions !== planned.instructions ? "instructions" : "",
+                actual.completion_json !== planned.completionJson ? "completion_json" : "",
+                actual.sequence_index !== planned.sequenceIndex ? "sequence_index" : "",
+            ].filter(Boolean);
+            corruptSpine(run.id, `step row ${index} differs from the frozen plan (${fields.join(", ")})`);
+        }
+    }
+    if (run.current_step_id !== null && !expected.some((step) => step.stepId === run.current_step_id))
+        corruptSpine(run.id, `current step ${run.current_step_id} is not in the frozen plan`);
+    const current = run.current_step_id ? rows.find((row) => row.step_id === run.current_step_id) : undefined;
+    if (run.status === "active") {
+        const firstPending = rows.find((row) => row.status === "pending");
+        if (!current || current.status !== "pending" || firstPending?.step_id !== current.step_id)
+            corruptSpine(run.id, "active status/current step does not match the first pending plan step");
+    }
+    else if (run.status === "blocked") {
+        if (!current || current.status !== "blocked")
+            corruptSpine(run.id, `${run.status} status does not match the current plan step`);
+    }
+    else if (run.status === "failed") {
+        // `workflow abandon` marks the run failed while intentionally leaving its
+        // current step pending so `resume` can reopen the same work.
+        if (!current || (current.status !== "failed" && current.status !== "pending"))
+            corruptSpine(run.id, `${run.status} status does not match the current plan step`);
+    }
+    else if (run.status === "completed") {
+        if (run.current_step_id !== null ||
+            rows.some((row) => row.status === "pending" || row.status === "blocked" || row.status === "failed"))
+            corruptSpine(run.id, "completed status disagrees with the plan spine");
+    }
+}
+function routeInstructions(route) {
+    const branches = Object.entries(route.when)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([match, stepId]) => `"${match}" -> ${stepId}`);
+    if (route.defaultStepId !== undefined)
+        branches.push(`default -> ${route.defaultStepId}`);
+    return `Route on ${route.input}: ${branches.join(", ")}.`;
+}
+function corruptSpine(runId, detail) {
+    throw new UsageError(`Workflow run ${runId} has a corrupt durable step spine: ${detail}. Refusing to mutate state that disagrees with its frozen plan.`, "INVALID_JSON_ARGUMENT");
+}

package/dist/workflows/runtime/runs.js

@@ -2,26 +2,30 @@
 // 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 { randomUUID } from "node:crypto";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { canonicalizeWorkflowName } from "../../core/asset/asset-spec.js";
-import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
+import { insertEventOnce } from "../../storage/repositories/events-repository.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
 import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
+import { frozenSummaryJudge } from "../exec/frozen-judge.js";
 import { detectSecretShapedParams } from "../exec/param-secrets.js";
-import { collectProgramWarnings } from "../ir/compile.js";
+import { collectWorkflowWarnings } from "../ir/compile.js";
+import { compileResolveFreezeWorkflow } from "../ir/freeze.js";
 import { validateWorkflowParams } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
+import { decodeWorkflowPlanV3, WORKFLOW_IR_VERSION } from "../ir/schema.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
 import { evaluateCheckin } from "./checkin.js";
+import { assertWorkflowSpineMatchesPlan, classifyWorkflowRunPlan, frozenStepRows, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
 import { evaluateStaleUnits } from "./unit-checkin.js";
-import { compileWorkflowAssetPlan, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
+import { canonicalizeWorkflowRefInput, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
 /** Clip bound for a unit's `result_json` on the `--units` diagnostic surface. */
 const UNIT_DIAGNOSTIC_CLIP = 2000;
-function toUnitDiagnostic(row, stale) {
+function toUnitDiagnostic(row, stale, plannedEngine) {
     let diagnostic = null;
     if (row.result_json !== null) {
         // `result_json` is a JSON-encoded value: a bare JSON string for a free-text
@@ -55,6 +59,9 @@ function toUnitDiagnostic(row, stale) {
         staleIdleMs: stale ? (Number.isFinite(stale.idleMs) ? stale.idleMs : null) : null,
         claimHolder: row.claim_holder,
         claimExpiresAt: row.claim_expires_at,
+        engine: row.engine ?? null,
+        runtimeKind: row.engine && (row.runner === "llm" || row.runner === "agent" || row.runner === "sdk") ? row.runner : null,
+        platform: plannedEngine?.kind === "agent" ? plannedEngine.platform : null,
     };
 }
 export async function startWorkflowRun(ref, params = {}, options) {
@@ -63,15 +70,12 @@ export async function startWorkflowRun(ref, params = {}, options) {
     // persist it on the run row in the same transaction as the insert. Every
     // later invocation executes this snapshot — the asset file is never re-read
     // for an in-flight run; re-planning is an explicit new run.
-    const plan = compileWorkflowAssetPlan(asset);
-    // Non-fatal WARNINGS (redesign addendum): a YAML program's untyped-step and
-    // undeclared-param advisories surface as `warn()` lines at start (stderr,
-    // consistent with the repo's other author-facing warnings) without blocking
-    // the run. Markdown workflows carry no `program` and warn about nothing.
-    if (asset.program) {
-        for (const w of collectProgramWarnings(asset.program)) {
-            warn(`workflow start: ${asset.path}:${w.line} — ${w.message}`);
-        }
+    const plan = decodeWorkflowPlanV3(compileResolveFreezeWorkflow(asset, loadConfig()).plan);
+    // Non-fatal WARNINGS: untyped-step and undeclared-param advisories surface
+    // as `warn()` lines at start (stderr, consistent with the repo's other
+    // author-facing warnings) without blocking the run.
+    for (const w of collectWorkflowWarnings(asset.document)) {
+        warn(`workflow start: ${asset.path}:${w.line} — ${w.message}`);
     }
     // Reviewer #12: validate supplied `--params` against the frozen param
     // schemas BEFORE creating the run, so a type-mismatched param (e.g. a string
@@ -85,12 +89,13 @@ export async function startWorkflowRun(ref, params = {}, options) {
     }
     const planJson = canonicalPlanJson(plan);
     const planHash = computePlanHash(plan);
+    const workflowRefs = await workflowRunRefSet(asset.ref, ref);
     return withWorkflowRunsRepo(async (repo) => {
         const now = new Date().toISOString();
         const runId = randomUUID();
         const scopeKey = getCurrentWorkflowScopeKey();
-        const currentStepId = asset.steps[0]?.id ?? null;
-        const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
+        const currentStepId = plan.steps[0]?.stepId ?? null;
+        const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref, asset.adapterId);
         // Capture the agent harness + session driving this run. Explicit options
         // win; otherwise fall back to best-effort environment detection. This is
         // identity-only — no background thread or timer is started here.
@@ -101,19 +106,20 @@ export async function startWorkflowRun(ref, params = {}, options) {
         // (workflow_ref, scope_key) pair, refuse to create a parallel run unless
         // `force: true` is set. Previously every call inserted unconditionally,
         // so two terminals running `akm workflow start <ref>` left two runs
-        // racing; `akm workflow next` then non-deterministically picked one.
-        if (!options?.force) {
-            const existing = repo.findActiveRunForScope(asset.ref, scopeKey);
-            if (existing) {
-                throw new UsageError(`Workflow ${asset.ref} already has an active run in this scope (id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
-                    `Use 'akm workflow next ${asset.ref}' to resume it, 'akm workflow abandon ${existing.id}' to give up on it, or pass --force to start a parallel run.`, "RESOURCE_ALREADY_EXISTS");
-            }
-        }
+        // racing; `akm workflow next` then non-deterministically picked one. The
+        // active-alias query and all inserts now share this immediate transaction.
         // #506: arm a file-signal check-in (a timestamp, NOT a background thread —
-        // see docs/technical/workflow-agent-checkin-adr.md) so a stalled run can be
+        // per the workflow-agent check-in ADR) so a stalled run can be
         // re-targeted with a `continue` directive. The agent harness + session id
         // are already resolved above (agentHarness/agentSessionId, from #501).
-        repo.transaction(() => {
+        repo.immediateTransaction(() => {
+            if (!options?.force) {
+                const existing = repo.findActiveRunForScope(workflowRefs, scopeKey);
+                if (existing) {
+                    throw new UsageError(`Workflow ${asset.ref} already has an active run in this scope (id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
+                        `Use 'akm workflow next ${asset.ref}' to resume it, 'akm workflow abandon ${existing.id}' to give up on it, or pass --force to start a parallel run.`, "RESOURCE_ALREADY_EXISTS");
+                }
+            }
             repo.insertRun({
                 id: runId,
                 workflowRef: asset.ref,
@@ -128,17 +134,16 @@ export async function startWorkflowRun(ref, params = {}, options) {
                 agentSessionId,
                 checkinArmedAt: now,
             });
-            repo.insertSteps(asset.steps.map((step) => ({
+            repo.insertSteps(frozenStepRows(plan).map((step) => ({
                 runId,
-                stepId: step.id,
-                stepTitle: step.title,
+                stepId: step.stepId,
+                stepTitle: step.stepTitle,
                 instructions: step.instructions,
-                completionJson: step.completionCriteria ? JSON.stringify(step.completionCriteria) : null,
-                sequenceIndex: step.sequenceIndex ?? 0,
+                completionJson: step.completionJson,
+                sequenceIndex: step.sequenceIndex,
             })));
-            // Same transaction as the insert: a run row never exists without its
-            // frozen plan (rows with NULL plan_json are pre-006 legacy runs).
-            repo.setRunPlan(runId, planJson, planHash);
+            // Same transaction as the insert: a run row never exists without its frozen plan.
+            repo.setRunPlan(runId, planJson, planHash, WORKFLOW_IR_VERSION);
         });
         const result = await getWorkflowStatus(runId);
         // #13: params are declared non-secret (they are copied verbatim into every
@@ -156,7 +161,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
         // into agent context.
         appendEvent({
             eventType: "workflow_started",
-            ref: ref,
+            ref: asset.ref,
             metadata: { runId: result.run.id, status: result.run.status },
         });
         return result;
@@ -176,7 +181,9 @@ export async function getWorkflowStatus(runId, opts) {
             // uses (`now` injected for deterministic tests) so a dead driver's claimed
             // `running` unit surfaces as stale here too, not just as raw `running`.
             const staleById = new Map(evaluateStaleUnits(rows, opts.now ?? Date.now()).map((u) => [u.unitId, u]));
-            detail.units = rows.map((row) => toUnitDiagnostic(row, staleById.get(row.unit_id)));
+            const classified = classifyWorkflowRunPlan(run);
+            const engines = classified.support === "supported" ? classified.plan.execution?.engines : undefined;
+            detail.units = rows.map((row) => toUnitDiagnostic(row, staleById.get(row.unit_id), row.engine ? engines?.[row.engine] : undefined));
         }
         return detail;
     });
@@ -185,28 +192,50 @@ export async function hasWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => repo.hasRun(runId));
 }
 export async function listWorkflowRuns(input) {
-    return withWorkflowRunsRepo((repo) => {
-        const scopeKey = getCurrentWorkflowScopeKey();
-        let workflowRef;
-        if (input?.workflowRef) {
-            const parsed = parseAssetRef(input.workflowRef);
-            if (parsed.type !== "workflow") {
-                throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${input.workflowRef}".`);
-            }
-            workflowRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalizeWorkflowName(parsed.name)}`;
+    const scopeKey = getCurrentWorkflowScopeKey();
+    const activeOnly = input?.activeOnly === true;
+    if (input?.workflowRef === undefined) {
+        return withWorkflowRunsRepo((repo) => ({
+            runs: repo.listRuns({ scopeKey, ...(activeOnly ? { activeOnly: true } : {}) }).map(toWorkflowRunSummary),
+        }));
+    }
+    const exactRef = input.workflowRef.trim();
+    if (!exactRef) {
+        throw new UsageError("Workflow ref filter cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    const parsedExactRef = parseBundleRef(exactRef);
+    if (parsedExactRef.fragment !== undefined) {
+        throw new UsageError("Workflow ref filters do not accept fragments.", "INVALID_FLAG_VALUE");
+    }
+    let workflowRefs = [exactRef];
+    try {
+        const canonicalRef = await canonicalizeWorkflowSpecifier(exactRef);
+        workflowRefs = await workflowRunRefSet(canonicalRef, exactRef);
+    }
+    catch (error) {
+        if (parsedExactRef.bundle !== undefined) {
+            const exactRows = await withWorkflowRunsRepo((repo) => repo.listRuns({ scopeKey, workflowRef: exactRef }));
+            if (exactRows.length === 0)
+                throw error;
+            return {
+                runs: exactRows.filter((row) => !activeOnly || row.status === "active").map(toWorkflowRunSummary),
+            };
         }
-        const rows = repo.listRuns({
-            scopeKey,
-            ...(workflowRef ? { workflowRef } : {}),
-            ...(input?.activeOnly ? { activeOnly: true } : {}),
-        });
-        return { runs: rows.map(toWorkflowRunSummary) };
-    });
+        if (!(error instanceof NotFoundError))
+            throw error;
+    }
+    return withWorkflowRunsRepo((repo) => ({
+        runs: repo
+            .listRuns({ scopeKey, workflowRefs, ...(activeOnly ? { activeOnly: true } : {}) })
+            .map(toWorkflowRunSummary),
+    }));
 }
 export async function getNextWorkflowStep(specifier, params) {
     return withWorkflowRunsRepo(async (repo) => {
         const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params);
         const steps = readWorkflowRunSteps(repo, run.id);
+        const plan = requireExecutableWorkflowPlan(run);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
         return { ...projectNextResult(run, steps), ...(autoStarted ? { autoStarted: true } : {}) };
     });
 }
@@ -255,6 +284,8 @@ export async function snapshotRunForDriver(runId) {
     return withWorkflowRunsRepo((repo) => repo.transaction(() => {
         const run = readWorkflowRun(repo, runId);
         const steps = readWorkflowRunSteps(repo, run.id);
+        const plan = requireExecutableWorkflowPlan(run);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
         const units = repo.getUnitsForRun(run.id);
         return { next: projectNextResult(run, steps), run, units };
     }));
@@ -262,11 +293,13 @@ export async function snapshotRunForDriver(runId) {
 export async function resumeWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
+        const plan = requireExecutableWorkflowPlan(run);
+        const steps = readWorkflowRunSteps(repo, run.id);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
         if (run.status === "completed") {
             throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
         }
         if (run.status === "active") {
-            const steps = readWorkflowRunSteps(repo, run.id);
             return buildWorkflowRunDetail(run, steps);
         }
         // blocked or failed → flip back to active and re-open the current step so
@@ -279,8 +312,8 @@ export async function resumeWorkflowRun(runId) {
             repo.markRunActive(run.id, now);
         });
         const updated = { ...run, status: "active", updated_at: now };
-        const steps = readWorkflowRunSteps(repo, run.id);
-        return buildWorkflowRunDetail(updated, steps);
+        const refreshedSteps = readWorkflowRunSteps(repo, run.id);
+        return buildWorkflowRunDetail(updated, refreshedSteps);
     });
 }
 /**
@@ -291,18 +324,24 @@ export async function resumeWorkflowRun(runId) {
  */
 export async function abandonWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
-        const run = readWorkflowRun(repo, runId);
-        if (run.status === "completed" || run.status === "failed") {
-            throw new UsageError(`Workflow run ${run.id} is already ${run.status}.`);
-        }
         const now = new Date().toISOString();
-        repo.updateRunState({
-            status: "failed",
-            currentStepId: run.current_step_id,
-            updatedAt: now,
-            completedAt: now,
-            checkinArmedAt: now,
-            runId: run.id,
+        const run = repo.immediateTransaction((db) => {
+            const current = readWorkflowRun(repo, runId);
+            if (current.status === "completed" || current.status === "failed") {
+                throw new UsageError(`Workflow run ${current.id} is already ${current.status}.`);
+            }
+            if (!repo.markRunAbandoned(current.id, now)) {
+                throw new UsageError(`Workflow run ${current.id} is ${current.status} and cannot be abandoned.`);
+            }
+            insertEventOnce(db, {
+                eventType: "workflow_abandoned",
+                ts: now,
+                ref: current.workflow_ref,
+                metadata: { runId: current.id },
+                idempotencyKey: current.id,
+                idempotencyMetadataKey: "runId",
+            });
+            return current;
         });
         const updated = {
             ...run,
@@ -313,9 +352,6 @@ export async function abandonWorkflowRun(runId) {
         };
         const steps = readWorkflowRunSteps(repo, run.id);
         const detail = buildWorkflowRunDetail(updated, steps);
-        // Same injectable-footprint rule as workflow_started (07 P1-B): ids and
-        // status only, never the frontmatter-derived title.
-        appendEvent({ eventType: "workflow_abandoned", ref: run.workflow_ref, metadata: { runId: run.id } });
         return detail;
     });
 }
@@ -324,6 +360,9 @@ export async function completeWorkflowStep(input) {
     // the write transaction — a slow/hung LLM must never hold a db write lock.
     const preflight = await withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, input.runId);
+        const plan = requireExecutableWorkflowPlan(run);
+        const steps = readWorkflowRunSteps(repo, run.id);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
         if (run.status !== "active") {
             throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
         }
@@ -338,7 +377,10 @@ export async function completeWorkflowStep(input) {
         if (run.current_step_id !== existing.step_id) {
             throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
         }
-        return { existing };
+        const stepPlan = plan.steps.find((step) => step.stepId === input.stepId);
+        if (!stepPlan)
+            throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
+        return { existing, plan, stepPlan };
     });
     const summary = input.summary?.trim();
     // #506: completing a step requires a summary of the work done.
@@ -349,9 +391,11 @@ export async function completeWorkflowStep(input) {
     // completionCriteria via the configured LLM. Fail-open when no criteria or no
     // judge. Only a well-formed `complete: false` blocks completion.
     if (input.status === "completed" && summary) {
-        const criteria = parseJsonArray(preflight.existing.completion_json) ?? [];
-        const judge = input.summaryJudge === undefined ? buildDefaultSummaryJudge() : input.summaryJudge;
-        const verdict = await validateStepSummary({ stepTitle: preflight.existing.step_title, completionCriteria: criteria, summary }, judge ?? undefined, { required: input.requireGate === true });
+        const criteria = preflight.stepPlan.gate.criteria;
+        const judge = input.summaryJudge === undefined
+            ? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge)
+            : input.summaryJudge;
+        const verdict = await validateStepSummary({ stepTitle: preflight.stepPlan.title, completionCriteria: criteria, summary }, judge ?? undefined);
         if (!verdict.complete) {
             // Re-arm the check-in so a subsequent stall is still nudged, but leave the
             // step pending and return corrective feedback instead of completing.
@@ -364,9 +408,6 @@ export async function completeWorkflowStep(input) {
                 stepId: input.stepId,
                 missing: verdict.missing,
                 feedback: verdict.feedback ?? "The summary does not satisfy the step's completion criteria.",
-                // A REQUIRED gate that could not be judged (finding A): the caller BLOCKS
-                // rather than treating this as a normal, retryable gate rejection.
-                ...(verdict.errored ? { errored: true } : {}),
             };
         }
     }
@@ -375,6 +416,9 @@ export async function completeWorkflowStep(input) {
         let refreshedSteps = [];
         repo.transaction(() => {
             const run = readWorkflowRun(repo, input.runId);
+            const plan = requireExecutableWorkflowPlan(run);
+            const spine = readWorkflowRunSteps(repo, run.id);
+            assertWorkflowSpineMatchesPlan(plan, run, spine);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
@@ -449,16 +493,28 @@ async function resolveRunSpecifier(repo, specifier, params) {
         }
         return { run: explicitRun, autoStarted: false };
     }
-    if (!specifier.includes(":")) {
-        throw new NotFoundError(`Workflow run "${specifier}" not found.`, "WORKFLOW_NOT_FOUND");
+    const scopeKey = getCurrentWorkflowScopeKey();
+    const exactRef = specifier.trim();
+    const parsedExact = parseBundleRef(exactRef);
+    const qualifiedExact = parsedExact.bundle !== undefined && parsedExact.fragment === undefined;
+    const detached = qualifiedExact ? repo.getActiveRunRowForScope(exactRef, scopeKey) : undefined;
+    let ref;
+    try {
+        ref = await canonicalizeWorkflowSpecifier(specifier);
     }
-    const parsed = parseAssetRef(specifier);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref or workflow run id, got "${specifier}".`);
+    catch (error) {
+        if (detached) {
+            if (params && Object.keys(params).length > 0) {
+                throw new UsageError(`--params can only be set on a new run; ${specifier} already has an active run`);
+            }
+            return { run: detached, autoStarted: false };
+        }
+        if (error instanceof NotFoundError && !specifier.includes(":") && !specifier.includes("/")) {
+            throw new NotFoundError(`Workflow run or workflow "${specifier}" not found.`, "WORKFLOW_NOT_FOUND");
+        }
+        throw error;
     }
-    const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalizeWorkflowName(parsed.name)}`;
-    const scopeKey = getCurrentWorkflowScopeKey();
-    const active = repo.getActiveRunRowForScope(ref, scopeKey);
+    const active = repo.getActiveRunRowForScope(await workflowRunRefSet(ref, exactRef), scopeKey);
     if (active) {
         if (params && Object.keys(params).length > 0) {
             throw new UsageError(`--params can only be set on a new run; ${ref} already has an active run`);
@@ -468,6 +524,62 @@ async function resolveRunSpecifier(repo, specifier, params) {
     const started = await startWorkflowRun(ref, params ?? {});
     return { run: readWorkflowRun(repo, started.run.id), autoStarted: true };
 }
+async function canonicalizeWorkflowSpecifier(specifier) {
+    return canonicalizeWorkflowRefInput(specifier);
+}
+async function workflowRunRefSet(canonicalRef, exactRef) {
+    const parsed = parseBundleRef(canonicalRef);
+    const refs = new Set([canonicalRef, exactRef.trim()]);
+    const exact = parseBundleRef(exactRef.trim());
+    if (exact.bundle === undefined) {
+        refs.add(parsed.conceptId);
+    }
+    else {
+        try {
+            if ((await canonicalizeWorkflowSpecifier(parsed.conceptId)) === canonicalRef)
+                refs.add(parsed.conceptId);
+        }
+        catch (error) {
+            if (!(error instanceof NotFoundError))
+                throw error;
+        }
+    }
+    return [...refs];
+}
+/** Resolve an existing active run without auto-starting or rebinding a detached short ref. */
+export async function resolveExistingWorkflowRunId(target) {
+    return withWorkflowRunsRepo(async (repo) => {
+        const byId = repo.getRunById(target);
+        if (byId)
+            return byId.id;
+        const scopeKey = getCurrentWorkflowScopeKey();
+        const exactRef = target.trim();
+        if (!exactRef.includes(":") && !exactRef.includes("/")) {
+            throw new NotFoundError(`Workflow run or workflow "${target}" not found.`, "WORKFLOW_NOT_FOUND");
+        }
+        const parsedExact = parseBundleRef(exactRef);
+        const detached = parsedExact.bundle && parsedExact.fragment === undefined
+            ? repo.getActiveRunRowForScope(exactRef, scopeKey)
+            : undefined;
+        let canonicalRef;
+        try {
+            canonicalRef = await canonicalizeWorkflowSpecifier(exactRef);
+        }
+        catch (error) {
+            if (detached)
+                return detached.id;
+            if (error instanceof NotFoundError) {
+                throw new NotFoundError(`Workflow run or workflow "${target}" not found.`, "WORKFLOW_NOT_FOUND");
+            }
+            throw error;
+        }
+        const active = repo.getActiveRunRowForScope(await workflowRunRefSet(canonicalRef, exactRef), scopeKey);
+        if (!active) {
+            throw new NotFoundError(`No active workflow run for ${canonicalRef} in this scope.`, "WORKFLOW_NOT_FOUND");
+        }
+        return active.id;
+    });
+}
 function readWorkflowRun(repo, runId) {
     const run = repo.getRunById(runId);
     if (!run) {
@@ -500,6 +612,7 @@ function buildWorkflowRunDetail(run, steps) {
     };
 }
 function toWorkflowRunSummary(run) {
+    const plan = classifyWorkflowRunPlan(run);
     return {
         id: run.id,
         workflowRef: run.workflow_ref,
@@ -514,6 +627,8 @@ function toWorkflowRunSummary(run) {
         params: parseJsonObject(run.params_json),
         agentHarness: run.agent_harness ?? null,
         agentSessionId: run.agent_session_id ?? null,
+        planIrVersion: plan.irVersion,
+        executionSupport: plan.support,
         // Surface the engine lease (holder id + expiry — never workflow-authored
         // content) so `workflow next`/`status` show who is driving the run.
         ...(run.engine_lease_holder && run.engine_lease_until
@@ -579,34 +694,6 @@ function deriveRunState(steps) {
         .at(-1);
     return { status: "completed", currentStepId: null, completedAt: completedAt ?? null };
 }
-/**
- * Build the default summary-validation judge from the configured LLM, or return
- * `null` when no LLM is configured (gate is then skipped — fail-open). Lazily
- * imports the client/config so the workflow engine has no hard LLM dependency.
- *
- * Exported for the engine loop (`exec/run-workflow.ts`), which wraps the judge
- * to journal engine-driven gate evaluations as unit rows (addendum R2).
- */
-export function buildDefaultSummaryJudge() {
-    let llm;
-    try {
-        const config = loadConfig();
-        llm = getDefaultLlmConfig(config);
-    }
-    catch {
-        return null;
-    }
-    if (!llm)
-        return null;
-    const resolved = llm;
-    return async ({ system, user }) => {
-        const { chatCompletion } = await import("../../llm/client.js");
-        return chatCompletion(resolved, [
-            { role: "system", content: system },
-            { role: "user", content: user },
-        ]);
-    };
-}
 function parseJsonObject(value) {
     if (!value)
         return undefined;

package/dist/workflows/runtime/unit-checkin.js

@@ -1,7 +1,7 @@
 // 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 { GATE_EVALUATION_PHASE } from "../exec/step-work.js";
+import { GATE_EVALUATION_PHASE } from "./unit-phases.js";
 /**
  * Default staleness window. A unit claimed `running` whose last heartbeat (or,
  * absent any heartbeat, its first claim) is older than this is surfaced as