akm-cli 0.9.0-rc.8 → 0.9.0

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

@@ -4,84 +4,30 @@
 import { UsageError } from "../../core/errors.js";
 import { decodeCanonicalPlan } from "../ir/plan-hash.js";
 import { WORKFLOW_IR_VERSION } from "../ir/schema.js";
-/** One policy authority for executable versus inspection-only historical runs. */
+/** 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) {
-        if (row.plan_ir_version === WORKFLOW_IR_VERSION) {
-            return {
-                support: "corrupt-plan",
-                irVersion: row.plan_ir_version,
-                error: `Workflow run ${runId} declares workflow IR version ${row.plan_ir_version} but has no frozen plan.`,
-            };
-        }
-        return {
-            support: row.plan_ir_version === null || row.plan_ir_version === undefined ? "missing-plan" : "unsupported-version",
-            irVersion: row.plan_ir_version ?? null,
-            error: row.plan_ir_version === null || row.plan_ir_version === undefined
-                ? `Workflow run ${runId} has no executable workflow IR plan.`
-                : `Workflow run ${runId} uses unsupported workflow IR version ${String(row.plan_ir_version)} and has no frozen plan.`,
-        };
-    }
-    let raw;
-    try {
-        raw = JSON.parse(row.plan_json);
-    }
-    catch {
-        if (row.plan_ir_version !== WORKFLOW_IR_VERSION) {
-            return {
-                support: row.plan_ir_version === null || row.plan_ir_version === undefined ? "missing-plan" : "unsupported-version",
-                irVersion: row.plan_ir_version ?? null,
-                error: `Workflow run ${runId} has malformed historical frozen plan JSON that cannot be executed.`,
-            };
-        }
-        return {
-            support: "corrupt-plan",
-            irVersion: row.plan_ir_version ?? null,
-            error: `Workflow run ${runId} has corrupt frozen plan JSON.`,
-        };
-    }
-    const decodedVersion = typeof raw === "object" && raw !== null ? raw.irVersion : null;
-    if (!Number.isSafeInteger(decodedVersion) || decodedVersion < 1) {
-        if (row.plan_ir_version !== WORKFLOW_IR_VERSION) {
-            return {
-                support: row.plan_ir_version === null || row.plan_ir_version === undefined ? "missing-plan" : "unsupported-version",
-                irVersion: row.plan_ir_version ?? null,
-                error: `Workflow run ${runId} has historical frozen plan data with no supported IR version.`,
-            };
-        }
         return {
-            support: "corrupt-plan",
+            support: "missing-plan",
             irVersion: row.plan_ir_version ?? null,
-            error: `Workflow run ${runId} has a missing or invalid frozen plan IR version.`,
+            error: `Workflow run ${runId} has no frozen workflow plan.`,
         };
     }
-    if (row.plan_ir_version !== null && row.plan_ir_version !== undefined && row.plan_ir_version !== decodedVersion) {
-        if (row.plan_ir_version !== WORKFLOW_IR_VERSION && decodedVersion !== WORKFLOW_IR_VERSION) {
-            return {
-                support: "unsupported-version",
-                irVersion: decodedVersion,
-                error: `Workflow run ${runId} uses unsupported workflow IR version ${String(decodedVersion)} with mismatched historical metadata.`,
-            };
-        }
-        return {
-            support: "corrupt-plan",
-            irVersion: decodedVersion,
-            error: `Workflow run ${runId} has mismatched stored plan IR version (${String(row.plan_ir_version)} != ${String(decodedVersion)}).`,
-        };
-    }
-    if (decodedVersion !== WORKFLOW_IR_VERSION) {
+    if (row.plan_ir_version !== null &&
+        row.plan_ir_version !== undefined &&
+        row.plan_ir_version !== WORKFLOW_IR_VERSION) {
         return {
             support: "unsupported-version",
-            irVersion: decodedVersion,
-            error: `Workflow run ${runId} uses unsupported workflow IR version ${String(decodedVersion)}.`,
+            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: row.plan_ir_version ?? null,
-            error: `Workflow run ${runId} has no stored plan IR version.`,
+            irVersion: null,
+            error: `Workflow run ${runId} does not declare workflow IR version ${WORKFLOW_IR_VERSION}.`,
         };
     }
     try {
@@ -92,25 +38,20 @@ export function classifyWorkflowRunPlan(row) {
         };
     }
     catch (cause) {
-        return { support: "corrupt-plan", irVersion: 3, error: cause instanceof Error ? cause.message : String(cause) };
+        return {
+            support: "corrupt-plan",
+            irVersion: WORKFLOW_IR_VERSION,
+            error: cause instanceof Error ? cause.message : String(cause),
+        };
     }
 }
-/** Reject an execution mutation while preserving inspection and abandon access. */
+/** 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;
-    if (classified.support === "missing-plan" || classified.support === "unsupported-version") {
-        throw new UsageError(`${classified.error} This historical run is inspection-only; abandon it with \`akm workflow abandon ${row.id ?? "<run>"}\` and start a new run.`, "WORKFLOW_IR_VERSION_UNSUPPORTED");
-    }
     throw new UsageError(classified.error, "INVALID_JSON_ARGUMENT");
 }
-/** Abandon is the sole mutation allowed for a historical run; corrupt v3 data is never mutated. */
-export function requireAbandonableWorkflowPlan(row) {
-    const classified = classifyWorkflowRunPlan(row);
-    if (classified.support === "corrupt-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) => ({

package/dist/workflows/runtime/runs.js

@@ -2,26 +2,27 @@
 // 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 { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { loadConfig } from "../../core/config/config.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
+import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { canonicalizeWorkflowName } from "../../core/recognition-util.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 { materializeWorkflowParameterFlags, 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, requireAbandonableWorkflowPlan, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
+import { assertWorkflowSpineMatchesPlan, classifyWorkflowRunPlan, frozenStepRows, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
 import { evaluateStaleUnits } from "./unit-checkin.js";
-import { canonicalWorkflowRunRef, loadWorkflowAsset, parseWorkflowRefInput, 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, plannedEngine) {
@@ -61,7 +62,6 @@ function toUnitDiagnostic(row, stale, plannedEngine) {
         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,
-        ...(!row.engine && row.runner ? { legacyRunnerSelector: row.runner } : {}),
     };
 }
 export async function startWorkflowRun(ref, params = {}, options) {
@@ -70,34 +70,39 @@ 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 = decodeWorkflowPlanV3(compileResolveFreezeWorkflow(asset, loadConfig()).plan);
-    // 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 frozen = compileResolveFreezeWorkflow(asset, loadConfig());
+    const plan = decodeWorkflowPlanV3(frozen.plan);
+    if (options?.parameterFlags?.length && Object.keys(params).length > 0) {
+        throw new UsageError("Workflow parameters must use either an object or per-parameter flags, not both.");
+    }
+    const effectiveParams = options?.parameterFlags?.length
+        ? materializeWorkflowParameterFlags(plan, options.parameterFlags)
+        : params;
+    // 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 run: ${asset.path}:${w.line} — ${w.message}`);
     }
-    // Reviewer #12: validate supplied `--params` against the frozen param
+    // Reviewer #12: validate supplied parameters against the frozen param
     // schemas BEFORE creating the run, so a type-mismatched param (e.g. a string
     // for a `{ type: array }` param) is rejected with actionable errors instead
     // of flowing silently into a unit prompt. Programs without declared param
     // schemas (and every Markdown workflow) validate trivially.
-    const paramErrors = validateWorkflowParams(plan, params);
+    const paramErrors = validateWorkflowParams(plan, effectiveParams);
     if (paramErrors.length > 0) {
-        throw new UsageError(`Cannot start ${asset.ref}: the supplied --params do not satisfy the workflow's declared parameter schemas:\n` +
+        throw new UsageError(`Cannot start ${asset.ref}: the supplied parameters do not satisfy the workflow's declared schemas:\n` +
             paramErrors.map((e) => `  - ${e}`).join("\n"), "INVALID_JSON_ARGUMENT");
     }
     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 = plan.steps[0]?.stepId ?? null;
-        const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
+        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.
@@ -107,27 +112,28 @@ export async function startWorkflowRun(ref, params = {}, options) {
         // Concurrency guard (#485): if an active run already exists in this
         // (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");
-            }
-        }
+        // so two terminals starting the same workflow could leave two runs racing.
+        // 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 —
         // 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 run ${asset.ref}' to resume it or 'akm workflow abandon ${existing.id}' to give up on it.`, "RESOURCE_ALREADY_EXISTS");
+                }
+            }
             repo.insertRun({
                 id: runId,
                 workflowRef: asset.ref,
                 scopeKey,
                 workflowEntryId,
                 workflowTitle: asset.title,
-                paramsJson: JSON.stringify(params),
+                paramsJson: JSON.stringify(effectiveParams),
                 currentStepId,
                 createdAt: now,
                 updatedAt: now,
@@ -143,19 +149,23 @@ export async function startWorkflowRun(ref, params = {}, options) {
                 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).
+            // 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
         // unit prompt and hashed into the unit identity, so they cannot be redacted
-        // without breaking the driver protocol). Surface a loud, best-effort warning
+        // without breaking replay determinism). Surface a loud, best-effort warning
         // when a param LOOKS like a credential so the author moves it to an env
         // binding. Advisory only — never blocks the start.
-        const secretWarnings = detectSecretShapedParams(params);
+        const secretWarnings = detectSecretShapedParams(effectiveParams);
         if (secretWarnings.length > 0)
             result.warnings = [...(result.warnings ?? []), ...secretWarnings];
+        // The implicit engine fallback is announced ONCE, here at run creation —
+        // the frozen plan records the engine actually used, so a resume never
+        // re-announces a decision it did not make.
+        if (frozen.engineAnnouncement)
+            result.warnings = [...(result.warnings ?? []), frozen.engineAnnouncement];
         // 07 P1-B: emit only the run id + status — NOT the raw workflowTitle (which
         // comes verbatim from the workflow asset's frontmatter and is therefore
         // attacker-influenceable). Keeping raw titles out of the events stream
@@ -163,7 +173,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;
@@ -179,9 +189,9 @@ export async function getWorkflowStatus(runId, opts) {
             // project each row, INCLUDING failures whose diagnostic text the
             // deterministic evidence graph drops. Read-only; never mutates the run.
             const rows = repo.getUnitsForRun(run.id);
-            // Codex round-3 finding B: run the SAME pure stale-claim evaluator `brief`
-            // uses (`now` injected for deterministic tests) so a dead driver's claimed
-            // `running` unit surfaces as stale here too, not just as raw `running`.
+            // Codex round-3 finding B: run the pure stale-claim evaluator (`now`
+            // injected for deterministic tests) so a unit left `running` by a process
+            // that died surfaces as stale here, not just as raw `running`.
             const staleById = new Map(evaluateStaleUnits(rows, opts.now ?? Date.now()).map((u) => [u.unitId, u]));
             const classified = classifyWorkflowRunPlan(run);
             const engines = classified.support === "supported" ? classified.plan.execution?.engines : undefined;
@@ -194,36 +204,60 @@ 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 = parseWorkflowRefInput(input.workflowRef);
-            if (parsed.type !== "workflow") {
-                throw new UsageError(`Expected a workflow ref (workflows/<name>), got "${input.workflowRef}".`);
-            }
-            workflowRef = canonicalWorkflowRunRef(parsed.origin, 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) {
+export async function getNextWorkflowStep(specifier, params, options) {
     return withWorkflowRunsRepo(async (repo) => {
-        const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params);
+        const { run, autoStarted, startWarnings } = await resolveRunSpecifier(repo, specifier, params, options?.parameterFlags);
         const steps = readWorkflowRunSteps(repo, run.id);
         const plan = requireExecutableWorkflowPlan(run);
         assertWorkflowSpineMatchesPlan(plan, run, steps);
-        return { ...projectNextResult(run, steps), ...(autoStarted ? { autoStarted: true } : {}) };
+        return {
+            ...projectNextResult(run, steps),
+            ...(autoStarted ? { autoStarted: true } : {}),
+            ...(startWarnings?.length ? { startWarnings } : {}),
+        };
     });
 }
 /**
  * Project a run row + its step rows into a {@link WorkflowNextResult}. The pure
- * read-shaping half of {@link getNextWorkflowStep}, extracted so the driver
+ * read-shaping half of {@link getNextWorkflowStep}, extracted so the run
  * snapshot below reproduces the exact same projection without re-running the
  * auto-start-capable {@link resolveRunSpecifier}.
  */
@@ -251,27 +285,6 @@ function projectNextResult(run, steps) {
         ...(checkin ? { checkin } : {}),
     };
 }
-/**
- * A consistent point-in-time snapshot of a run for the harness-neutral driver
- * protocol (PR #714 review round 2, #14). `brief`/`report` previously read the
- * spine (`getNextWorkflowStep`) and then, in a SEPARATE connection, the run row
- * + unit journal — so a concurrent `report`/`run`/manual completion could change
- * the active step BETWEEN the two reads, leaving the described work-list
- * inconsistent with the run row it was stamped against. This reads the run row,
- * its steps, AND its unit rows inside ONE transaction (one connection, one
- * snapshot) so all three agree. It never auto-starts — `runId` must already
- * resolve to a concrete run — because the driver protocol never mutates on read.
- */
-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 };
-    }));
-}
 export async function resumeWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
@@ -306,23 +319,24 @@ export async function resumeWorkflowRun(runId) {
  */
 export async function abandonWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
-        const run = readWorkflowRun(repo, runId);
-        requireAbandonableWorkflowPlan(run);
-        const classified = classifyWorkflowRunPlan(run);
-        const existingSteps = readWorkflowRunSteps(repo, run.id);
-        if (classified.support === "supported")
-            assertWorkflowSpineMatchesPlan(classified.plan, run, existingSteps);
-        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,
@@ -333,9 +347,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;
     });
 }
@@ -371,15 +382,20 @@ export async function completeWorkflowStep(input) {
     if (input.status === "completed" && !summary) {
         throw new UsageError(`Completing step "${input.stepId}" requires a --summary describing the work done.`, "MISSING_REQUIRED_ARGUMENT");
     }
-    // #506: validation gate — judge the summary against the step's
-    // completionCriteria via the configured LLM. Fail-open when no criteria or no
-    // judge. Only a well-formed `complete: false` blocks completion.
+    // #506: validation gate — a criteria-bearing step must have a frozen judge
+    // and receive an affirmative verdict before it can advance.
     if (input.status === "completed" && summary) {
         const criteria = preflight.stepPlan.gate.criteria;
+        if (input.signal?.aborted)
+            throw interruptionReason(input.signal);
         const judge = input.summaryJudge === undefined
-            ? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge)
+            ? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge, input.signal)
             : input.summaryJudge;
-        const verdict = await validateStepSummary({ stepTitle: preflight.stepPlan.title, completionCriteria: criteria, summary }, judge ?? undefined, { required: input.requireGate === true });
+        if (criteria.length > 0 && !judge) {
+            throw new ConfigError(`Workflow run ${input.runId} has completion criteria for step "${input.stepId}" but its frozen plan has no judge. ` +
+                "Set workflow.judgeEngine, abandon this run, and create a new one with `akm workflow run <ref>`.", "INVALID_CONFIG_FILE");
+        }
+        const verdict = await validateStepSummary({ stepTitle: preflight.stepPlan.title, completionCriteria: criteria, summary }, judge ?? undefined, input.signal);
         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.
@@ -392,12 +408,11 @@ 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 } : {}),
             };
         }
     }
+    if (input.signal?.aborted)
+        throw interruptionReason(input.signal);
     return withWorkflowRunsRepo((repo) => {
         let updatedRun;
         let refreshedSteps = [];
@@ -423,6 +438,8 @@ 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.`);
             }
+            if (input.signal?.aborted)
+                throw interruptionReason(input.signal);
             const completedAt = new Date().toISOString();
             repo.updateStepCompletion({
                 status: input.status,
@@ -472,34 +489,76 @@ export async function completeWorkflowStep(input) {
         return detail;
     });
 }
-async function resolveRunSpecifier(repo, specifier, params) {
+async function resolveRunSpecifier(repo, specifier, params, parameterFlags) {
+    const hasParameters = (params && Object.keys(params).length > 0) || (parameterFlags?.length ?? 0) > 0;
     const explicitRun = repo.getRunById(specifier);
     if (explicitRun) {
-        if (params && Object.keys(params).length > 0) {
-            throw new UsageError(`--params can only be used when starting a new run from a workflow ref, not with an existing run id ("${specifier}")`);
+        if (hasParameters) {
+            throw new UsageError(`Workflow parameter flags can only be used when starting a new run, not with existing run id "${specifier}".`);
         }
         return { run: explicitRun, autoStarted: false };
     }
-    // Run-id vs workflow-ref disambiguation: a run id is a bare token, while a
-    // canonical `workflows/name` ref carries a `/`.
-    if (!specifier.includes(":") && !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 = parseWorkflowRefInput(specifier);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref or workflow run id, got "${specifier}".`);
+    catch (error) {
+        if (detached) {
+            if (hasParameters) {
+                throw new UsageError(`Workflow parameter flags can only be set on a new run; ${specifier} is already active.`);
+            }
+            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 = canonicalWorkflowRunRef(parsed.origin, 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`);
+        if (hasParameters) {
+            throw new UsageError(`Workflow parameter flags can only be set on a new run; ${ref} is already active.`);
         }
         return { run: active, autoStarted: false };
     }
-    const started = await startWorkflowRun(ref, params ?? {});
-    return { run: readWorkflowRun(repo, started.run.id), autoStarted: true };
+    const started = await startWorkflowRun(ref, params ?? {}, {
+        ...(parameterFlags !== undefined ? { parameterFlags } : {}),
+    });
+    return {
+        run: readWorkflowRun(repo, started.run.id),
+        autoStarted: true,
+        ...(started.warnings?.length ? { startWarnings: started.warnings } : {}),
+    };
+}
+function interruptionReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error("Workflow run interrupted.");
+}
+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];
 }
 function readWorkflowRun(repo, runId) {
     const run = repo.getRunById(runId);
@@ -513,7 +572,7 @@ function readWorkflowRunSteps(repo, runId) {
 }
 function buildWorkflowRunDetail(run, steps) {
     // Review M1: `workflow status` (and every other detail-shaped response) now
-    // evaluates the check-in, not just `workflow next`. Pure timestamp check —
+    // evaluates the check-in, not just `workflow run`. Pure timestamp check —
     // no background thread (see checkin.ts).
     const checkin = evaluateCheckin({
         status: run.status,
@@ -551,7 +610,7 @@ function toWorkflowRunSummary(run) {
         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.
+        // content) so `workflow run`/`status` show who is driving the run.
         ...(run.engine_lease_holder && run.engine_lease_until
             ? { engineLease: { holder: run.engine_lease_holder, until: run.engine_lease_until } }
             : {}),
@@ -560,7 +619,7 @@ function toWorkflowRunSummary(run) {
 /**
  * Single-driver enforcement (R2 run lease): while a LIVE (unexpired) engine
  * lease is held, only the holding engine may advance the gate spine. Manual
- * `akm workflow complete` (no `leaseHolder`) — or a stale engine invocation
+ * A call with no `leaseHolder` — or a stale engine invocation
  * whose lease was claimed by another — is refused with the holder + expiry.
  * An EXPIRED lease never blocks: the engine that held it is presumed dead.
  */