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

package/dist/workflows/runtime/runs.js

@@ -3,22 +3,101 @@
 // 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 { 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 { 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 { 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, requireAbandonableWorkflowPlan, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
+import { evaluateStaleUnits } from "./unit-checkin.js";
 import { 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,
+        ...(!row.engine && row.runner ? { legacyRunnerSelector: row.runner } : {}),
+    };
+}
 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 (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}`);
+        }
+    }
+    // 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);
     return withWorkflowRunsRepo(async (repo) => {
         const now = new Date().toISOString();
         const runId = randomUUID();
         const scopeKey = getCurrentWorkflowScopeKey();
-        const currentStepId = asset.steps[0]?.id ?? null;
+        const currentStepId = plan.steps[0]?.stepId ?? null;
         const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
         // Capture the agent harness + session driving this run. Explicit options
         // win; otherwise fall back to best-effort environment detection. This is
@@ -57,16 +136,27 @@ 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, 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
@@ -80,11 +170,25 @@ export async function startWorkflowRun(ref, params = {}, options) {
         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) {
@@ -99,7 +203,7 @@ export async function listWorkflowRuns(input) {
             if (parsed.type !== "workflow") {
                 throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${input.workflowRef}".`);
             }
-            workflowRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+            workflowRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalizeWorkflowName(parsed.name)}`;
         }
         const rows = repo.listRuns({
             scopeKey,
@@ -113,39 +217,72 @@ 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 +295,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);
     });
 }
 /**
@@ -171,6 +308,11 @@ 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}.`);
         }
@@ -203,9 +345,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 +362,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 +376,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, { required: input.requireGate === true });
         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.
@@ -242,6 +393,9 @@ 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 } : {}),
             };
         }
     }
@@ -250,9 +404,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 +456,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 } });
@@ -321,7 +488,7 @@ async function resolveRunSpecifier(repo, specifier, params) {
     if (parsed.type !== "workflow") {
         throw new UsageError(`Expected a workflow ref or workflow run id, got "${specifier}".`);
     }
-    const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+    const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalizeWorkflowName(parsed.name)}`;
     const scopeKey = getCurrentWorkflowScopeKey();
     const active = repo.getActiveRunRowForScope(ref, scopeKey);
     if (active) {
@@ -344,6 +511,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 +528,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 +547,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 +614,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;

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

@@ -0,0 +1,45 @@
+// 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";
+/**
+ * Default staleness window. A unit claimed `running` whose last heartbeat (or,
+ * absent any heartbeat, its first claim) is older than this is surfaced as
+ * stale. Matches the run-level {@link ../runtime/checkin.CHECKIN_STALL_MS}.
+ */
+export const UNIT_STALE_MS = 90_000;
+function parseIso(value) {
+    if (!value)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * Pure stale-unit evaluator. Returns every `running` DISPATCH unit whose last
+ * heartbeat (`last_checkin_at`, else the first-claim `started_at`) is older than
+ * `staleMs`. Gate-evaluation rows (`phase = "gate"`) are excluded — they are
+ * synchronous engine judge calls, never driver-claimed work. A running row with
+ * no usable timestamp at all is treated as stale (a claim we can no longer age).
+ * Deterministic in `now` — free of timer flakiness.
+ */
+export function evaluateStaleUnits(rows, now = Date.now(), staleMs = UNIT_STALE_MS) {
+    const stale = [];
+    for (const row of rows) {
+        if (row.status !== "running")
+            continue;
+        if (row.phase === GATE_EVALUATION_PHASE)
+            continue;
+        const lastSeenAt = row.last_checkin_at ?? row.started_at;
+        const lastSeen = parseIso(lastSeenAt);
+        const idleMs = lastSeen === null ? Number.POSITIVE_INFINITY : now - lastSeen;
+        if (idleMs < staleMs)
+            continue;
+        stale.push({
+            unitId: row.unit_id,
+            stepId: row.step_id,
+            idleMs,
+            lastSeenAt: lastSeenAt ?? null,
+        });
+    }
+    return stale;
+}

package/dist/workflows/runtime/workflow-asset-loader.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { canonicalizeWorkflowName } from "../../core/asset/asset-spec.js";
 import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
@@ -12,6 +13,8 @@ import { resolveAssetPath } from "../../sources/resolve.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
 import { formatWorkflowErrors } from "../authoring/authoring.js";
 import { parseWorkflow } from "../parser.js";
+import { parseWorkflowProgram } from "../program/parser.js";
+import { isWorkflowProgramPath, projectProgramParameters, projectProgramStepDefinitions } from "../program/project.js";
 /**
  * Resolve a `workflow:<name>` ref to a fully-projected {@link WorkflowAsset}.
  *
@@ -44,7 +47,19 @@ export async function loadWorkflowAsset(ref) {
         throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
     }
     const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
-    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+    // Canonicalize the stored ref: `workflow:foo.yaml` and `workflow:foo`
+    // resolve to the same file, so they MUST share one run identity. The raw
+    // `parsed.name` (with any extension) is what drives file resolution above;
+    // only the persisted/queried ref is collapsed (matches the index entry key,
+    // which is keyed by the extension-stripped canonical name).
+    const canonicalName = canonicalizeWorkflowName(parsed.name);
+    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalName}`;
+    // Format detection by extension: `.yaml`/`.yml` is a YAML workflow program
+    // (redesign addendum, R1); everything else is the markdown document format.
+    if (isWorkflowProgramPath(assetPath)) {
+        const program = loadWorkflowProgramFromDisk(assetPath);
+        return projectProgramAsset(program, fullRef, assetPath, resolvedSourcePath);
+    }
     const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
     const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
     return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
@@ -69,6 +84,14 @@ export function resolveWorkflowEntryId(sourcePath, ref) {
         return row?.id ?? null;
     });
 }
+function loadWorkflowProgramFromDisk(assetPath) {
+    const content = fs.readFileSync(assetPath, "utf8");
+    const result = parseWorkflowProgram(content, { path: assetPath });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
+    }
+    return result.program;
+}
 function loadWorkflowDocumentFromDisk(assetPath) {
     const content = fs.readFileSync(assetPath, "utf8");
     const result = parseWorkflow(content, { path: assetPath });
@@ -121,5 +144,23 @@ function projectAsset(doc, ref, assetPath, sourcePath) {
             ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
             sequenceIndex: s.sequenceIndex,
         })),
+        document: doc,
+    };
+}
+/**
+ * Project a parsed YAML program into the run-repository asset shape. Step
+ * instructions carry the RAW `${{ … }}` templates — resolution happens in
+ * the engine against the frozen plan, never here.
+ */
+function projectProgramAsset(program, ref, assetPath, sourcePath) {
+    const parameters = projectProgramParameters(program);
+    return {
+        ref,
+        path: assetPath,
+        sourcePath,
+        title: program.name,
+        ...(parameters ? { parameters } : {}),
+        steps: projectProgramStepDefinitions(program),
+        program,
     };
 }

package/dist/workflows/validate-summary.js

@@ -18,6 +18,9 @@
  */
 import validateSummaryJudgePrompt from "../assets/prompts/validate-summary-judge.md" with { type: "text" };
 import { parseJsonResponse } from "../core/parse.js";
+/** Feedback surfaced when a REQUIRED gate's judge could not be evaluated. */
+const REQUIRED_GATE_JUDGE_UNAVAILABLE_FEEDBACK = "The required completion gate could not be judged — the LLM threw, was unreachable, or returned an " +
+    "unparseable verdict. A required gate must be judged; refusing to pass it. Restore the judge and re-evaluate.";
 const JUDGE_SYSTEM = validateSummaryJudgePrompt;
 function buildUserPrompt(input) {
     const criteria = input.completionCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
@@ -36,14 +39,22 @@ function buildUserPrompt(input) {
 /**
  * Run the summary-validation gate.
  *
- * Fail-open contract:
+ * Fail-open contract (NON-required gates):
  *  - no criteria → `{ complete: true, skipped: true }`
  *  - no judge → `{ complete: true, skipped: true }`
  *  - judge throws / returns unparseable → `{ complete: true, skipped: true }`
  *
+ * REQUIRED gates (`opts.required`) do NOT fail open on an un-evaluable judge
+ * (Codex round-3 finding A): a judge that throws / is unreachable, or returns an
+ * unparseable / malformed verdict, yields `{ complete: false, errored: true }`
+ * so the caller BLOCKS the step rather than silently passing an unjudged gate.
+ * (A required gate with NO judge at all is blocked upstream in
+ * `finalizeExecutedStep` before this gate runs, so that branch stays fail-open.)
+ *
  * Only a well-formed `complete: false` verdict blocks completion.
  */
-export async function validateStepSummary(input, judge) {
+export async function validateStepSummary(input, judge, opts) {
+    const required = opts?.required === true;
     const criteria = input.completionCriteria.filter((c) => c.trim().length > 0);
     if (criteria.length === 0) {
         return { complete: true, missing: [], skipped: true };
@@ -56,11 +67,21 @@ export async function validateStepSummary(input, judge) {
         raw = await judge({ system: JUDGE_SYSTEM, user: buildUserPrompt({ ...input, completionCriteria: criteria }) });
     }
     catch {
-        // LLM unreachable / errored — fail open so offline use keeps working.
+        // LLM unreachable / errored. A REQUIRED gate must be judged — block rather
+        // than pass an unjudged gate; a non-required gate fails open so offline use
+        // keeps working.
+        if (required) {
+            return { complete: false, missing: [], errored: true, feedback: REQUIRED_GATE_JUDGE_UNAVAILABLE_FEEDBACK };
+        }
         return { complete: true, missing: [], skipped: true };
     }
     const parsed = parseJsonResponse(raw);
     if (!parsed || typeof parsed.complete !== "boolean") {
+        // An unparseable / malformed verdict is a judge that did not actually judge:
+        // a required gate blocks; a non-required gate fails open.
+        if (required) {
+            return { complete: false, missing: [], errored: true, feedback: REQUIRED_GATE_JUDGE_UNAVAILABLE_FEEDBACK };
+        }
         return { complete: true, missing: [], skipped: true };
     }
     if (parsed.complete) {