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

package/dist/workflows/program/expressions.js

@@ -0,0 +1,181 @@
+// 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/.
+const GRAMMAR_HINT = "allowed forms: params.<name>, steps.<id>.output(.<ident>|[<int>])*";
+/**
+ * Parse a bare reference string (a whole-value frontmatter field, already
+ * delimiter-free: `map.over`, `route.input`, or one entry of `inputs[]`).
+ */
+export function parseReference(source) {
+    const text = source.trim();
+    if (text === "")
+        return { ok: false, message: `Empty reference; ${GRAMMAR_HINT}.` };
+    const root = readIdent(text, 0);
+    if (!root) {
+        return { ok: false, message: `Invalid reference "${text}" — must start with an identifier; ${GRAMMAR_HINT}.` };
+    }
+    switch (root.name) {
+        case "params": {
+            if (text[root.end] !== ".") {
+                return { ok: false, message: `"params" requires a name: params.<name> (got "${text}").` };
+            }
+            const name = readIdent(text, root.end + 1);
+            if (!name) {
+                return { ok: false, message: `Invalid param name after "params." in "${text}".` };
+            }
+            if (name.end !== text.length) {
+                return {
+                    ok: false,
+                    message: `"params.${name.name}" takes exactly one name — found trailing "${text.slice(name.end)}".`,
+                };
+            }
+            return { ok: true, expr: { kind: "param", name: name.name } };
+        }
+        case "steps": {
+            if (text[root.end] !== ".") {
+                return { ok: false, message: `"steps" requires a step id: steps.<id>.output (got "${text}").` };
+            }
+            const stepId = readIdent(text, root.end + 1);
+            if (!stepId) {
+                return { ok: false, message: `Invalid step id after "steps." in "${text}".` };
+            }
+            if (text[stepId.end] !== ".") {
+                return { ok: false, message: `"steps.${stepId.name}" must be followed by ".output" (got "${text}").` };
+            }
+            const output = readIdent(text, stepId.end + 1);
+            if (!output || output.name !== "output") {
+                return { ok: false, message: `Expected ".output" after "steps.${stepId.name}" in "${text}".` };
+            }
+            const path = parsePath(text, output.end);
+            if (!path.ok)
+                return { ok: false, message: path.message };
+            return { ok: true, expr: { kind: "stepOutput", stepId: stepId.name, path: path.path } };
+        }
+        default:
+            return { ok: false, message: `Unknown root "${root.name}" in "${text}"; ${GRAMMAR_HINT}.` };
+    }
+}
+/** `<ident>` is `[A-Za-z_][A-Za-z0-9_-]*`. Returns null when no ident starts at `start`. */
+function readIdent(text, start) {
+    if (start >= text.length || !/[A-Za-z_]/.test(text[start]))
+        return null;
+    let end = start + 1;
+    while (end < text.length && /[A-Za-z0-9_-]/.test(text[end]))
+        end++;
+    return { name: text.slice(start, end), end };
+}
+/** Parse `( .<ident> | [<non-negative int>] )*` from `start` to end of text. */
+function parsePath(text, start) {
+    const path = [];
+    let i = start;
+    while (i < text.length) {
+        const char = text[i];
+        if (char === ".") {
+            const ident = readIdent(text, i + 1);
+            if (!ident) {
+                return { ok: false, message: `Invalid path segment after "." at position ${i} in "${text}".` };
+            }
+            path.push(ident.name);
+            i = ident.end;
+        }
+        else if (char === "[") {
+            let j = i + 1;
+            while (j < text.length && /[0-9]/.test(text[j]))
+                j++;
+            if (j === i + 1 || text[j] !== "]") {
+                return {
+                    ok: false,
+                    message: `Invalid indexer at position ${i} in "${text}" — expected [<non-negative integer>].`,
+                };
+            }
+            path.push(Number.parseInt(text.slice(i + 1, j), 10));
+            i = j + 1;
+        }
+        else {
+            return { ok: false, message: `Unexpected character "${char}" at position ${i} in "${text}".` };
+        }
+    }
+    return { ok: true, path };
+}
+// ── Resolution ───────────────────────────────────────────────────────────────
+/**
+ * Resolve a single reference to its RAW value for whole-value contexts
+ * (`map.over`, `route.input`, `inputs[]`): arrays stay arrays, objects stay
+ * objects. null/undefined values and missing paths are errors.
+ */
+export function resolveReference(expr, scope) {
+    const reference = formatReference(expr);
+    const fail = (message) => ({ ok: false, error: { reference, message } });
+    switch (expr.kind) {
+        case "param": {
+            if (!Object.hasOwn(scope.params, expr.name)) {
+                return fail(`${reference} is not defined in the run's params.`);
+            }
+            return finish(scope.params[expr.name], reference, fail);
+        }
+        case "stepOutput": {
+            if (!Object.hasOwn(scope.stepOutputs, expr.stepId)) {
+                return fail(`steps.${expr.stepId}.output is not available — step "${expr.stepId}" has no recorded output.`);
+            }
+            let current = scope.stepOutputs[expr.stepId];
+            let walked = `steps.${expr.stepId}.output`;
+            for (const segment of expr.path) {
+                if (typeof segment === "number") {
+                    if (!Array.isArray(current)) {
+                        return fail(`${walked} is not an array — cannot resolve index [${segment}].`);
+                    }
+                    if (segment >= current.length) {
+                        return fail(`${walked}[${segment}] is out of bounds (array length ${current.length}).`);
+                    }
+                    current = current[segment];
+                    walked += `[${segment}]`;
+                }
+                else {
+                    if (typeof current !== "object" || current === null || Array.isArray(current)) {
+                        return fail(`${walked} is not an object — cannot resolve property "${segment}".`);
+                    }
+                    if (!Object.hasOwn(current, segment)) {
+                        return fail(`${walked}.${segment} is missing (no such property, resolving ${reference}).`);
+                    }
+                    current = current[segment];
+                    walked += `.${segment}`;
+                }
+            }
+            return finish(current, reference, fail);
+        }
+    }
+}
+/**
+ * Resolve a bare reference STRING directly (parse + resolve in one call) —
+ * the shape every whole-value frontmatter position (`map.over`, `route.input`,
+ * one entry of `inputs[]`) actually needs.
+ */
+export function resolveReferenceString(text, scope) {
+    const parsed = parseReference(text);
+    if (!parsed.ok) {
+        return { ok: false, error: { reference: text, message: parsed.message } };
+    }
+    return resolveReference(parsed.expr, scope);
+}
+function finish(value, reference, fail) {
+    if (value === undefined)
+        return fail(`${reference} resolved to undefined.`);
+    if (value === null)
+        return fail(`${reference} resolved to null.`);
+    return { ok: true, value };
+}
+// ── Introspection helpers ────────────────────────────────────────────────────
+/** Canonical source spelling of a reference, e.g. `steps.review.output.files[2].name`. */
+export function formatReference(expr) {
+    switch (expr.kind) {
+        case "param":
+            return `params.${expr.name}`;
+        case "stepOutput": {
+            let text = `steps.${expr.stepId}.output`;
+            for (const segment of expr.path) {
+                text += typeof segment === "number" ? `[${segment}]` : `.${segment}`;
+            }
+            return text;
+        }
+    }
+}

package/dist/workflows/program/schema.js

@@ -0,0 +1,51 @@
+// 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/.
+/** How a map step folds its per-item unit results into the step artifact. */
+export const PROGRAM_REDUCERS = ["collect", "vote"];
+/** Failure policy: fail the step on first unit failure, or record and go on. */
+export const PROGRAM_ON_ERROR = ["fail", "continue"];
+/** Filesystem isolation for file-mutating units. */
+export const PROGRAM_ISOLATION_KINDS = ["none", "worktree"];
+/**
+ * `retry.on` vocabulary — exactly the persisted `AgentFailureReason` taxonomy
+ * from `src/integrations/agent/spawn.ts`. The `satisfies` clause fails the
+ * typecheck if spawn.ts adds/renames a reason without this list (and the JSON
+ * Schema, via the drift test) being updated.
+ */
+const RETRY_REASON_SET = {
+    timeout: true,
+    spawn_failed: true,
+    non_zero_exit: true,
+    parse_error: true,
+    cooldown: true,
+    llm_rate_limit: true,
+    llm_content_filter: true,
+    llm_invalid_json: true,
+    content_policy_reject: true,
+    unsupported_type: true,
+    no_change: true,
+    aborted: true,
+};
+export const PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);
+/**
+ * Step ids: `[A-Za-z_][A-Za-z0-9_-]*` (also pinned in the JSON Schema) — the
+ * ONE id grammar for the unified format (workflow-format-unification, spec
+ * §2.2). This is EXACTLY the `<ident>` grammar `readIdent` accepts in
+ * `program/expressions.ts` for `steps.<id>.output` references: a
+ * letter/underscore first char, then letters/digits/underscores/dashes, and
+ * NO dots (the expression parser treats `.` as the `.output` path separator,
+ * so a dotted id could never be addressed). Keeping step ids inside the
+ * addressable grammar guarantees every step can be referenced from map
+ * inputs, routes, and `inputs:` without renaming.
+ *
+ * Forbidding dots additionally keeps the engine's internal gate-row node id
+ * `<stepId>.gate` collision-free: no user step id can contain a dot, so it can
+ * never equal another step's `<stepId>.gate` synthetic id.
+ */
+export const PROGRAM_STEP_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * Param names must be `params.<ident>`-addressable, so they are plain
+ * identifiers (no dots/dashes).
+ */
+export const PROGRAM_PARAM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;

package/dist/workflows/renderer.js

@@ -2,18 +2,16 @@
 // 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/.
 /**
- * Show + indexing renderer for workflow assets.
- *
- * Reads the markdown via `parseWorkflow` and projects the validated
- * `WorkflowDocument` down to the public `ShowResponse` shape (which still
- * uses the flat `WorkflowStepDefinition` type for backwards compatibility)
- * and into search hints for the indexer.
+ * Show + indexing renderer for the unified workflow asset (workflow-format-
+ * unification). One format now: reads the frontmatter+body document via
+ * `parseWorkflow` and projects the validated `WorkflowDocument` down to the
+ * public `ShowResponse` shape and into search hints for the indexer,
+ * including a compact per-step orchestration summary (engine/model,
+ * `map.over` reference, route table) when the step declares one.
  */
-import { makeAssetRef } from "../core/asset/asset-ref.js";
+import { displayRef } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
-import { registerMetadataContributor } from "../indexer/passes/metadata-contributors.js";
 import { parseWorkflow } from "./parser.js";
-import { cacheWorkflowDocument } from "./runtime/document-cache.js";
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -34,53 +32,110 @@ function loadDocument(ctx) {
     const summary = result.errors.map((e) => `${ctx.relPath}:${e.line} — ${e.message}`).join("\n");
     throw new UsageError(`Workflow has errors:\n${summary}`);
 }
+/**
+ * The instruction text a step contributes to the flat step projection. A
+ * route step has no body requirement, so a deterministic description of the
+ * routing table stands in when it declares no section (the spine still needs
+ * a non-empty instructions string).
+ */
+function stepInstructions(step) {
+    if (step.instructions)
+        return step.instructions.text;
+    if (step.route) {
+        const branches = step.route.branches.map((b) => `"${b.match}" -> ${b.stepId}`);
+        if (step.route.defaultStepId !== undefined)
+            branches.push(`default -> ${step.route.defaultStepId}`);
+        return `Route on ${step.route.input}: ${branches.join(", ")}.`;
+    }
+    return "";
+}
+/** Project the `params` block into the flat `WorkflowParameter` list. */
+function projectParameters(document) {
+    if (!document.params)
+        return undefined;
+    const parameters = Object.entries(document.params).map(([name, schema]) => {
+        const description = schema.description;
+        return { name, ...(typeof description === "string" && description !== "" ? { description } : {}) };
+    });
+    return parameters.length > 0 ? parameters : undefined;
+}
+/**
+ * Compact, show-facing orchestration summary for one step. Field mapping:
+ * `engine`/`model`/`timeoutMs` merge the run-level `defaults` exactly like the
+ * compiler does (per-unit override wins), `fanOut.over` carries the raw
+ * reference string, and `route` carries the explicit input + branch table.
+ * Returns undefined when the step declares nothing worth summarizing.
+ */
+function summarizeStepOrchestration(step, defaults) {
+    const unit = step.unit ?? step.map?.unit;
+    const engine = unit?.engine ?? defaults?.engine;
+    const model = unit?.model ?? defaults?.model;
+    const timeoutMs = unit?.timeoutMs !== undefined ? unit.timeoutMs : defaults?.timeoutMs;
+    const summary = {
+        ...(engine !== undefined ? { engine } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(step.map
+            ? {
+                fanOut: {
+                    over: step.map.over,
+                    ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
+                    reducer: step.map.reducer ?? "collect",
+                },
+            }
+            : {}),
+        ...(unit?.output !== undefined || step.output !== undefined ? { hasSchema: true } : {}),
+        ...(unit?.env !== undefined ? { env: [...unit.env] } : {}),
+        ...(step.route
+            ? {
+                route: {
+                    input: step.route.input,
+                    branches: step.route.branches.map((b) => ({ match: b.match, stepId: b.stepId })),
+                    ...(step.route.defaultStepId !== undefined ? { defaultStepId: step.route.defaultStepId } : {}),
+                },
+            }
+            : {}),
+    };
+    return Object.keys(summary).length > 0 ? summary : undefined;
+}
+function projectStepDefinitions(document) {
+    return document.steps.map((step) => {
+        const orchestration = summarizeStepOrchestration(step, document.defaults);
+        return {
+            id: step.id,
+            // No titles anywhere in the unified format — a step IS its id.
+            title: step.id,
+            instructions: stepInstructions(step),
+            ...(step.gateRubric?.text.trim() ? { completionCriteria: [step.gateRubric.text] } : {}),
+            sequenceIndex: step.sequenceIndex,
+            ...(orchestration ? { orchestration } : {}),
+        };
+    });
+}
 export const workflowMdRenderer = {
     name: "workflow-md",
     buildShowResponse(ctx) {
         const name = deriveName(ctx);
         const doc = loadDocument(ctx);
-        const ref = makeAssetRef("workflow", name, ctx.origin);
+        // WI-8.5b (display flip): the `akm workflow next <ref>` action is DISPLAY
+        // output — its spelling follows the D-R5 display rule (`displayRef`). A
+        // primary/default-bundle workflow renders the SHORT conceptId
+        // (`workflows/<name>`); a named source qualifies it as
+        // (`<bundle>//workflows/<name>`).
+        const ref = displayRef({ type: "workflow", name, bundleId: ctx.origin }, ctx.defaultBundle);
+        const parameters = projectParameters(doc);
         return {
             type: "workflow",
             name,
             path: ctx.absPath,
             action: buildWorkflowAction(ref),
+            ...(doc.preamble ? { content: doc.preamble } : {}),
             description: doc.description,
-            workflowTitle: doc.title,
-            parameters: doc.parameters?.map((p) => p.name),
-            workflowParameters: doc.parameters?.map((p) => ({ name: p.name, description: p.description })),
-            steps: doc.steps.map((s) => ({
-                id: s.id,
-                title: s.title,
-                instructions: s.instructions.text,
-                ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
-                sequenceIndex: s.sequenceIndex,
-            })),
+            // No authored title in the unified format — the asset's human name is
+            // its `description`/H1 like any other asset; this is its canonical name.
+            workflowTitle: name,
+            ...(parameters ? { parameters: parameters.map((p) => p.name), workflowParameters: parameters } : {}),
+            steps: projectStepDefinitions(doc),
         };
     },
 };
-registerMetadataContributor({
-    name: "workflow-document-metadata",
-    appliesTo: ({ rendererName }) => rendererName === "workflow-md",
-    contribute(entry, { renderContext }) {
-        const doc = loadDocument(renderContext);
-        const hints = new Set(entry.searchHints ?? []);
-        hints.add(doc.title);
-        for (const step of doc.steps) {
-            hints.add(step.title);
-            hints.add(step.id);
-            hints.add(step.instructions.text);
-            for (const criterion of step.completionCriteria ?? []) {
-                hints.add(criterion.text);
-            }
-        }
-        entry.searchHints = Array.from(hints).filter(Boolean);
-        if (doc.parameters?.length) {
-            entry.parameters = doc.parameters.map((p) => ({
-                name: p.name,
-                ...(p.description ? { description: p.description } : {}),
-            }));
-        }
-        cacheWorkflowDocument(entry, doc);
-    },
-});

package/dist/workflows/resource-limits.js

@@ -0,0 +1,22 @@
+// 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/.
+export const WORKFLOW_MAX_PLAN_BYTES = 2 * 1024 * 1024;
+export const WORKFLOW_MAX_SOURCE_BYTES = 1024 * 1024;
+export const WORKFLOW_MAX_STEPS = 256;
+export const WORKFLOW_MAX_ENGINES = 64;
+export const WORKFLOW_MAX_PARAMS = 128;
+export const WORKFLOW_MAX_ROUTE_BRANCHES = 256;
+export const WORKFLOW_MAX_INSTRUCTION_BYTES = 256 * 1024;
+export const WORKFLOW_MAX_SCHEMA_BYTES = 256 * 1024;
+export const WORKFLOW_MAX_EXTRA_PARAMS_BYTES = 64 * 1024;
+export const WORKFLOW_MAX_JSON_DEPTH = 64;
+export const WORKFLOW_MAX_MAP_EXPANSION = 10_000;
+/** Max declared `inputs:` reference strings on one unit/map step. */
+export const WORKFLOW_MAX_INPUTS = 64;
+export function utf8Bytes(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+export function jsonBytes(value) {
+    return utf8Bytes(JSON.stringify(value));
+}

package/dist/workflows/runtime/agent-identity.js

@@ -11,14 +11,42 @@
  * already exposes via the environment.
  *
  * Resolution is best-effort and environment-driven:
- *   - harness:    AKM_AGENT_HARNESS, else inferred from a known harness env var.
+ *   - harness:    AKM_AGENT_HARNESS, else inferred from a harness session-id
+ *                 env var (`identityEnv`), else from a harness presence flag
+ *                 (`presenceEnv`).
  *   - sessionId:  AKM_SESSION_ID, else the harness-native session env var.
+ *                 Presence flags NEVER contribute a session id — their values
+ *                 (`CODEX_SANDBOX=seatbelt`, `GEMINI_CLI=1`) are modes/flags,
+ *                 not sessions, and must not be persisted as agent_session_id.
  *
  * Explicit values passed to `startWorkflowRun` always win over the environment.
  *
+ * The harness-native markers are DERIVED from `HARNESS_REGISTRY` (plan §"Kill
+ * registry drift", P2): each harness declares its session-id env vars via
+ * `identityEnv` and its presence-only flags via `presenceEnv`, so adding a
+ * harness never touches this module. Only the `AKM_*` explicit-override vars
+ * are non-registry (they are akm's own, not any harness's) and stay hardcoded
+ * here.
+ *
  * @module workflows/agent-identity
  */
-import { denormalizeRuntimeIdentity } from "../../integrations/harnesses/index.js";
+import { denormalizeRuntimeIdentity, HARNESS_REGISTRY } from "../../integrations/harnesses/index.js";
+/**
+ * Derive a marker table from one registry env-var field, ordered by canonical
+ * id. The sort keeps the pre-derivation precedence byte-identical ('claude'
+ * before 'opencode' — the old if/else chain's order) and independent of
+ * `HARNESS_REGISTRY` declaration order, which is pinned for JSON-schema enum
+ * stability, not detection precedence.
+ */
+function deriveMarkers(pick) {
+    return HARNESS_REGISTRY.filter((h) => (pick(h)?.length ?? 0) > 0)
+        .map((h) => ({ harnessId: h.id, envKeys: pick(h) ?? [] }))
+        .sort((a, b) => a.harnessId.localeCompare(b.harnessId));
+}
+/** Session-id-bearing markers — usable for BOTH harness inference and sessionId. */
+const SESSION_MARKERS = deriveMarkers((h) => h.identityEnv);
+/** Presence-only flags — harness inference ONLY; their values are never a session id. */
+const PRESENCE_MARKERS = deriveMarkers((h) => h.presenceEnv);
 function firstNonEmpty(env, keys) {
     for (const key of keys) {
         const value = env[key];
@@ -37,20 +65,37 @@ export function resolveAgentIdentity(env = process.env) {
     // Explicit override always wins.
     let harness = firstNonEmpty(env, ["AKM_AGENT_HARNESS"]);
     if (!harness) {
-        // Infer the harness from a harness-specific *session* env var. We only
-        // infer when a concrete session id is present: the bare "this process is
-        // Claude Code" flag does not mean a given run is owned by an agent session,
-        // so it must not silently stamp identity onto manual CLI invocations.
-        if (firstNonEmpty(env, ["CLAUDE_SESSION_ID"])) {
-            // Runtime identity for Claude Code is "claude-code" (vs the canonical
-            // config id "claude"). Derived from the unified registry's bridge (#562)
-            // so the persisted runtime string can't drift — still emits "claude-code".
-            harness = denormalizeRuntimeIdentity("claude");
+        // Infer the harness from a harness-specific *session* env var first
+        // (registry `identityEnv` markers). A concrete session id is the
+        // strongest evidence of the immediate driver, so it outranks any
+        // presence flag — e.g. opencode launched inside a codex sandbox
+        // (OPENCODE_SESSION_ID + CODEX_SANDBOX) attributes to opencode.
+        for (const marker of SESSION_MARKERS) {
+            if (firstNonEmpty(env, marker.envKeys)) {
+                // Report the harness's RUNTIME identity (e.g. canonical 'claude' →
+                // 'claude-code') via the registry's #562 bridge so the persisted
+                // runtime string can't drift.
+                harness = denormalizeRuntimeIdentity(marker.harnessId);
+                break;
+            }
         }
-        else if (firstNonEmpty(env, ["OPENCODE_SESSION_ID"])) {
-            harness = denormalizeRuntimeIdentity("opencode");
+    }
+    if (!harness) {
+        // Fall back to presence-only flags (registry `presenceEnv`). These are
+        // stamped by the harness on its OWN child processes (CODEX_SANDBOX,
+        // GEMINI_CLI=1), so they cannot mis-attribute manual CLI invocations —
+        // but they carry no session id, so sessionId stays null below.
+        for (const marker of PRESENCE_MARKERS) {
+            if (firstNonEmpty(env, marker.envKeys)) {
+                harness = denormalizeRuntimeIdentity(marker.harnessId);
+                break;
+            }
         }
     }
-    const sessionId = firstNonEmpty(env, ["AKM_SESSION_ID", "CLAUDE_SESSION_ID", "OPENCODE_SESSION_ID"]);
+    // Session id: the explicit AKM override first, then the session-id-bearing
+    // registry markers in the same precedence order as harness inference (so
+    // harness and session id agree when multiple harness env vars are present).
+    // Presence flags are deliberately excluded — their values are not sessions.
+    const sessionId = firstNonEmpty(env, ["AKM_SESSION_ID", ...SESSION_MARKERS.flatMap((m) => [...m.envKeys])]);
     return { harness, sessionId };
 }

package/dist/workflows/runtime/checkin.js

@@ -5,7 +5,7 @@
  * Agent check-in: a no-background-thread "continue" nudge for stalled workflow
  * runs (#506).
  *
- * The design decision (see docs/technical/workflow-agent-checkin-adr.md)
+ * The design decision (the workflow-agent check-in ADR)
  * reconciles #506 (file/command-loop signal) with #501 (background thread) in
  * favour of the former. There is intentionally NO timer or resident process
  * here. Arming a check-in writes a timestamp (`checkin_armed_at`) on the run

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

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