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

package/dist/workflows/runtime/runs.js

@@ -2,24 +2,100 @@
 // 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 { 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 { 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 { loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
+import { assertWorkflowSpineMatchesPlan, classifyWorkflowRunPlan, frozenStepRows, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
+import { evaluateStaleUnits } from "./unit-checkin.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) {
+    let diagnostic = null;
+    if (row.result_json !== null) {
+        // `result_json` is a JSON-encoded value: a bare JSON string for a free-text
+        // unit, an object/array for a schema unit. Render the decoded string as-is
+        // (no surrounding quotes) and other shapes as compact JSON, then clip so a
+        // large artifact can't flood the diagnostic surface.
+        let text = row.result_json;
+        try {
+            const parsed = JSON.parse(row.result_json);
+            text = typeof parsed === "string" ? parsed : JSON.stringify(parsed);
+        }
+        catch {
+            /* leave the raw journaled text */
+        }
+        diagnostic = text.length > UNIT_DIAGNOSTIC_CLIP ? `${text.slice(0, UNIT_DIAGNOSTIC_CLIP)}…` : text;
+    }
+    return {
+        unitId: row.unit_id,
+        nodeId: row.node_id,
+        stepId: row.step_id,
+        phase: row.phase,
+        status: row.status,
+        attempts: row.attempts,
+        tokens: row.tokens,
+        failureReason: row.failure_reason,
+        sessionId: row.session_id,
+        diagnostic,
+        startedAt: row.started_at,
+        finishedAt: row.finished_at,
+        stale: stale !== undefined,
+        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) {
     const asset = await loadWorkflowAsset(ref);
+    // Frozen plan (redesign addendum, R1): compile the plan ONCE at start and
+    // 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: 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
+    // 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);
+    if (paramErrors.length > 0) {
+        throw new UsageError(`Cannot start ${asset.ref}: the supplied --params do not satisfy the workflow's declared parameter 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 = 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.
@@ -30,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,
@@ -57,16 +134,26 @@ 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.
+            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
+        // 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);
+        if (secretWarnings.length > 0)
+            result.warnings = [...(result.warnings ?? []), ...secretWarnings];
         // 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
@@ -74,78 +161,145 @@ 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;
     });
 }
-export async function getWorkflowStatus(runId) {
+export async function getWorkflowStatus(runId, opts) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
         const steps = readWorkflowRunSteps(repo, run.id);
-        return buildWorkflowRunDetail(run, steps);
+        const detail = buildWorkflowRunDetail(run, steps);
+        if (opts?.includeUnits) {
+            // The honest diagnostic surface (#22): read the unit journal straight and
+            // 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`.
+            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;
+            detail.units = rows.map((row) => toUnitDiagnostic(row, staleById.get(row.unit_id), row.engine ? engines?.[row.engine] : undefined));
+        }
+        return detail;
     });
 }
 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:${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 currentStep = resolveCurrentStep(run, steps);
-        const done = run.status === "completed" ? true : undefined;
-        // #506: surface a check-in directive through the normal command output when
-        // the run looks stalled. Pure timestamp evaluation — no background thread.
-        const checkin = evaluateCheckin({
-            status: run.status,
-            updatedAt: run.updated_at,
-            checkinArmedAt: run.checkin_armed_at,
-            agentHarness: run.agent_harness,
-            agentSessionId: run.agent_session_id,
-        }) ?? undefined;
-        return {
-            run: toWorkflowRunSummary(run),
-            workflow: {
-                ref: run.workflow_ref,
-                title: run.workflow_title,
-                steps: steps.map(toWorkflowRunStepState),
-            },
-            step: currentStep ? toWorkflowRunStepState(currentStep) : null,
-            ...(done ? { done } : {}),
-            ...(autoStarted ? { autoStarted } : {}),
-            ...(checkin ? { checkin } : {}),
-        };
+        const plan = requireExecutableWorkflowPlan(run);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
+        return { ...projectNextResult(run, steps), ...(autoStarted ? { autoStarted: true } : {}) };
     });
 }
+/**
+ * Project a run row + its step rows into a {@link WorkflowNextResult}. The pure
+ * read-shaping half of {@link getNextWorkflowStep}, extracted so the driver
+ * snapshot below reproduces the exact same projection without re-running the
+ * auto-start-capable {@link resolveRunSpecifier}.
+ */
+function projectNextResult(run, steps) {
+    const currentStep = resolveCurrentStep(run, steps);
+    const done = run.status === "completed" ? true : undefined;
+    // #506: surface a check-in directive through the normal command output when
+    // the run looks stalled. Pure timestamp evaluation — no background thread.
+    const checkin = evaluateCheckin({
+        status: run.status,
+        updatedAt: run.updated_at,
+        checkinArmedAt: run.checkin_armed_at,
+        agentHarness: run.agent_harness,
+        agentSessionId: run.agent_session_id,
+    }) ?? undefined;
+    return {
+        run: toWorkflowRunSummary(run),
+        workflow: {
+            ref: run.workflow_ref,
+            title: run.workflow_title,
+            steps: steps.map(toWorkflowRunStepState),
+        },
+        step: currentStep ? toWorkflowRunStepState(currentStep) : null,
+        ...(done ? { done } : {}),
+        ...(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);
+        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
@@ -158,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);
     });
 }
 /**
@@ -170,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,
@@ -192,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;
     });
 }
@@ -203,9 +360,13 @@ 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.`);
         }
+        assertLeaseAllowsSpineAdvance(run, input.leaseHolder);
         const existing = repo.getStep(run.id, input.stepId);
         if (!existing) {
             throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
@@ -216,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.
@@ -227,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);
+        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.
@@ -250,9 +416,16 @@ 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.`);
             }
+            // Re-checked inside the write transaction (like every other preflight
+            // condition): an engine may have claimed the run while the summary gate
+            // above was awaiting its LLM judge.
+            assertLeaseAllowsSpineAdvance(run, input.leaseHolder);
             const existing = repo.getStep(run.id, input.stepId);
             if (!existing) {
                 throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
@@ -295,10 +468,16 @@ export async function completeWorkflowStep(input) {
             };
         });
         const detail = buildWorkflowRunDetail(updatedRun, refreshedSteps);
+        // #11: emit `workflow_step_completed` ONLY for a genuine `completed`
+        // transition; every other non-pending status (failed/skipped/blocked)
+        // carries the honest `workflow_step_updated` name. The status is ALWAYS
+        // in metadata so consumers never infer it from the event name. Raw `notes`
+        // are workflow/model-authored content — an event-stream prompt-injection
+        // surface — and never enter the events log; they live on the step row only.
         appendEvent({
-            eventType: "workflow_step_completed",
+            eventType: input.status === "completed" ? "workflow_step_completed" : "workflow_step_updated",
             ref: detail.run.workflowRef,
-            metadata: { runId: input.runId, stepId: input.stepId, notes: input.notes },
+            metadata: { runId: input.runId, stepId: input.stepId, status: input.status },
         });
         if (detail.run.status === "completed") {
             appendEvent({ eventType: "workflow_finished", ref: detail.run.workflowRef, metadata: { runId: input.runId } });
@@ -314,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:${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`);
@@ -333,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) {
@@ -344,6 +591,16 @@ function readWorkflowRunSteps(repo, runId) {
     return repo.getStepsForRun(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 —
+    // no background thread (see checkin.ts).
+    const checkin = evaluateCheckin({
+        status: run.status,
+        updatedAt: run.updated_at,
+        checkinArmedAt: run.checkin_armed_at,
+        agentHarness: run.agent_harness,
+        agentSessionId: run.agent_session_id,
+    });
     return {
         run: toWorkflowRunSummary(run),
         workflow: {
@@ -351,9 +608,11 @@ function buildWorkflowRunDetail(run, steps) {
             title: run.workflow_title,
             steps: steps.map(toWorkflowRunStepState),
         },
+        ...(checkin ? { checkin } : {}),
     };
 }
 function toWorkflowRunSummary(run) {
+    const plan = classifyWorkflowRunPlan(run);
     return {
         id: run.id,
         workflowRef: run.workflow_ref,
@@ -368,8 +627,33 @@ 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
+            ? { engineLease: { holder: run.engine_lease_holder, until: run.engine_lease_until } }
+            : {}),
     };
 }
+/**
+ * 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
+ * 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.
+ */
+function assertLeaseAllowsSpineAdvance(run, leaseHolder) {
+    if (!run.engine_lease_holder || !run.engine_lease_until)
+        return;
+    if (leaseHolder === run.engine_lease_holder)
+        return;
+    if (run.engine_lease_until < new Date().toISOString())
+        return; // expired ⇒ claimable, not live
+    throw new UsageError(`Workflow run ${run.id} is being driven by engine ${run.engine_lease_holder} ` +
+        `(run lease expires ${run.engine_lease_until}). The engine owns the step spine while it runs — ` +
+        `wait for it to finish or for the lease to expire before advancing steps manually.`);
+}
 function toWorkflowRunStepState(step) {
     return {
         id: step.step_id,
@@ -410,33 +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.
- */
-function buildDefaultSummaryJudge() {
-    let llm;
-    try {
-        const config = loadConfig();
-        const { getDefaultLlmConfig } = require("../../core/config/config");
-        llm = getDefaultLlmConfig(config);
-    }
-    catch {
-        return null;
-    }
-    if (!llm)
-        return null;
-    const resolved = llm;
-    return async ({ system, user }) => {
-        const { chatCompletion } = require("../../llm/client");
-        return chatCompletion(resolved, [
-            { role: "system", content: system },
-            { role: "user", content: user },
-        ]);
-    };
-}
 function parseJsonObject(value) {
     if (!value)
         return undefined;