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

package/dist/workflows/authoring/authoring.js

@@ -4,109 +4,78 @@
 import fs from "node:fs";
 import path from "node:path";
 import workflowTemplate from "../../assets/workflows/workflow-template.md" with { type: "text" };
-import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../../core/asset/asset-spec.js";
-import { isWithin, resolveStashDir } from "../../core/common.js";
+import { ensureAkmMarkdownType } from "../../core/asset/akm-markdown.js";
+import { makeBundleRef } from "../../core/asset/asset-ref.js";
+import { isWithin, writeFileAtomic } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
+import { defaultBundleForTarget } from "../../core/mutation-target.js";
+import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../../core/recognition-util.js";
 import { warn } from "../../core/warn.js";
-import { compileWorkflowProgram } from "../ir/compile.js";
+import { prepareWriteTargetForMutation, resolveWriteTarget, withWriteTargetMutation } from "../../core/write-source.js";
+import { compileWorkflowPlan } from "../ir/compile.js";
 import { parseWorkflow } from "../parser.js";
-import { parseWorkflowProgram } from "../program/parser.js";
-import workflowProgramTemplate from "./workflow-program-template.yaml" with { type: "text" };
-const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
-    title: "Example Workflow",
-    firstStepTitle: "First Step",
-    firstStepId: "first-step",
-});
+const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate("New Workflow");
 export function getWorkflowTemplate() {
     return DEFAULT_WORKFLOW_TEMPLATE;
 }
-/**
- * Minimal valid YAML workflow *program* (redesign addendum, R1), printed by
- * `akm workflow template --yaml`. Kept as an external asset file per the repo
- * convention (see `workflow-program-template.yaml` next to this module);
- * `tests/workflows/program-assets.test.ts` pins that it parses AND compiles.
- */
-export function getWorkflowProgramTemplate() {
-    return workflowProgramTemplate;
-}
 export function buildWorkflowTemplate(name) {
     if (!name)
         return DEFAULT_WORKFLOW_TEMPLATE;
-    const title = humanizeWorkflowName(name);
-    const stepId = slugifyWorkflowStepId(name);
-    const customized = renderWorkflowTemplate({
-        title,
-        firstStepTitle: `${title} Setup`,
-        firstStepId: `${stepId}-setup`,
-    });
-    const result = parseWorkflow(customized, { path: `<template:${name}>` });
-    if (!result.ok) {
-        throw new UsageError(formatWorkflowErrors(`<template:${name}>`, result.errors));
-    }
+    // Only the H1 is customized. Step ids are STRUCTURAL under the unified format
+    // — each appears in `steps[].id`, as a body `## <id>` heading, and possibly in
+    // another step's `inputs:` — so rewriting them from a name would have to patch
+    // three places consistently to stay parseable. Generic `first-step`/
+    // `second-step` are the author's to rename.
+    const customized = renderWorkflowTemplate(humanizeWorkflowName(name));
+    validateWorkflowContent(customized, `<template:${name}>`);
     return customized;
 }
-/**
- * Customize the shipped YAML program template ({@link getWorkflowProgramTemplate})
- * for a named workflow: swap the placeholder `name:` for the workflow's slug so
- * a freshly created `.yaml`/`.yml` asset round-trips through the program parser
- * (its `title` becomes the slug). Parses AND compiles the result — mirroring
- * {@link buildWorkflowTemplate} — so a create never writes an asset that
- * `show`/`start`/`validate` would then reject.
- */
-export function buildWorkflowProgramTemplate(name) {
-    if (!name)
-        return workflowProgramTemplate;
-    const programName = slugifyWorkflowStepId(name);
-    const customized = workflowProgramTemplate.replace(/^name:.*$/m, `name: ${programName}`);
-    const parsed = parseWorkflowProgram(customized, { path: `<template:${name}>` });
-    if (!parsed.ok) {
-        throw new UsageError(formatWorkflowErrors(`<template:${name}>`, parsed.errors));
+/** Parse AND compile `content`, so a create never writes an asset that `show`/`start`/`validate` would then reject. */
+function validateWorkflowContent(content, sourcePath) {
+    const result = parseWorkflow(content, { path: sourcePath });
+    if (!result.ok) {
+        throw new UsageError(formatWorkflowErrors(sourcePath, result.errors));
     }
-    const compiled = compileWorkflowProgram(parsed.program);
+    const compiled = compileWorkflowPlan(result.document, slugifyWorkflowStepId(sourcePath));
     if (!compiled.ok) {
-        throw new UsageError(formatWorkflowErrors(`<template:${name}>`, compiled.errors));
+        throw new UsageError(formatWorkflowErrors(sourcePath, compiled.errors));
     }
-    return customized;
 }
-/** Recognized YAML workflow-program suffixes (see {@link WORKFLOW_EXTENSIONS}). */
-const WORKFLOW_PROGRAM_SUFFIX_RE = /\.ya?ml$/i;
+/** Recognized workflow-program suffixes — creating one is a lint-time usage error (workflow-format-unification). */
+const YAML_SUFFIX_RE = /\.ya?ml$/i;
+export function assertWorkflowMarkdownName(name) {
+    if (!YAML_SUFFIX_RE.test(name.trim()))
+        return;
+    throw new UsageError(`Workflows are markdown-only now (workflow-format-unification) — "${name}" cannot be created. ` +
+        `Use a plain name (no ".yaml"/".yml" suffix); the orchestration graph lives in the ".md" file's frontmatter.`);
+}
 export function createWorkflowAsset(input) {
-    const stashDir = resolveStashDir();
-    const typeRoot = path.join(stashDir, "workflows");
-    fs.mkdirSync(typeRoot, { recursive: true });
-    // A `.yaml`/`.yml` name selects the YAML *program* format (redesign
-    // addendum, R1); capture the exact suffix the user typed so the written file
-    // keeps it, then strip every workflow extension to get the canonical name.
-    const suffixMatch = input.name.trim().replace(/\\/g, "/").match(WORKFLOW_PROGRAM_SUFFIX_RE);
-    const programSuffix = suffixMatch ? suffixMatch[0].toLowerCase() : undefined;
-    const isProgram = programSuffix !== undefined;
+    assertWorkflowMarkdownName(input.name);
+    const config = loadConfig();
+    const resolvedTarget = resolveWriteTarget(config);
+    const target = prepareWriteTargetForMutation(resolvedTarget, { allowedAdapters: ["akm", "akm-workflow"] });
+    const stashDir = target.source.path;
+    const standaloneWorkflowBundle = target.source.adapterId === "akm-workflow";
+    const typeRoot = standaloneWorkflowBundle ? stashDir : path.join(stashDir, "workflows");
     const normalizedName = normalizeWorkflowName(input.name);
-    // The write target is DEFINITIVE — the canonical name plus the chosen format's
-    // extension (`.yaml`/`.yml` for a program, `.md` for markdown). We deliberately
-    // do NOT go through `resolveAssetPathFromName`, which PROBES existing files and
-    // would redirect a markdown create onto an existing `foo.yaml` (writing
-    // markdown into a `.yaml`). Computing the target directly makes a markdown
-    // create always write `.md`, so the finding-C cross-extension check below sees
-    // the real collision instead of a self-match.
-    const targetSuffix = isProgram ? programSuffix : ".md";
-    const assetPath = path.join(typeRoot, `${normalizedName}${targetSuffix}`);
-    if (!isWithin(assetPath, typeRoot)) {
-        throw new UsageError(`Resolved workflow path escapes the stash: "${normalizedName}"`, "PATH_ESCAPE_VIOLATION");
-    }
-    // Codex round-3 finding C: a `workflow:<name>` ref is canonical across every
-    // recognized extension (`.md`/`.yaml`/`.yml`) and resolves `.md` BEFORE
-    // `.yaml`. So creating `foo.yaml` while `foo.md` exists would return the ref
-    // `workflow:foo` that still starts the OLD markdown workflow — a silently
-    // shadowed asset. Reject creation when ANY recognized extension already holds
-    // the same canonical name, naming the existing file. A same-extension collision
-    // (the target path itself exists) keeps the classic `--force` overwrite escape;
-    // a DIFFERENT-extension collision cannot be force-overwritten (writing a new
-    // file would leave the old one shadowing it) — remove the existing file first.
-    const existingPaths = WORKFLOW_EXTENSIONS.map((ext) => path.join(typeRoot, `${normalizedName}${ext}`)).filter((candidate) => fs.existsSync(candidate));
-    const conflicting = existingPaths.find((p) => p !== assetPath);
-    if (conflicting !== undefined) {
-        throw new UsageError(`Workflow "${normalizedName}" already exists as ${path.relative(stashDir, conflicting)} — the ` +
-            `\`workflow:${normalizedName}\` ref resolves to that file, so creating this one would shadow it. ` +
+    const conceptId = standaloneWorkflowBundle ? normalizedName : `workflows/${normalizedName}`;
+    const assetPath = path.join(typeRoot, `${normalizedName}.md`);
+    const relativeAssetPath = path.relative(path.resolve(typeRoot), path.resolve(assetPath));
+    if (relativeAssetPath === ".." ||
+        relativeAssetPath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeAssetPath)) {
+        throw new UsageError(`Resolved workflow path escapes the bundle: "${normalizedName}"`, "PATH_ESCAPE_VIOLATION");
+    }
+    // A file whose canonical name matches but whose PATH differs can only be a
+    // case variant now (`upper.MD` vs `upper.md`) — the cross-EXTENSION case this
+    // guard also covered is gone with the unified `.md`-only format. It still
+    // matters: on a case-insensitive filesystem the two spellings are one file,
+    // so writing the target would silently clobber or shadow the existing asset.
+    const shadowing = findExistingWorkflowPaths(typeRoot, normalizedName).find((p) => p !== assetPath);
+    if (shadowing !== undefined) {
+        throw new UsageError(`Workflow "${normalizedName}" already exists as ${path.relative(stashDir, shadowing)} — the ` +
+            `\`${conceptId}\` ref resolves to that file, so creating this one would shadow it. ` +
             `Remove or rename the existing file first, or create the workflow under a different name.`, "RESOURCE_ALREADY_EXISTS");
     }
     if (fs.existsSync(assetPath) && !input.force) {
@@ -114,33 +83,19 @@ export function createWorkflowAsset(input) {
     }
     const content = input.from
         ? readWorkflowSource(input.from, stashDir)
-        : (input.content ??
-            (isProgram ? buildWorkflowProgramTemplate(normalizedName) : buildWorkflowTemplate(normalizedName)));
-    const sourcePath = input.from ?? `workflows/${normalizedName}${isProgram ? programSuffix : ".md"}`;
-    // Validate against the format the destination extension selects — a YAML
-    // program parses+compiles as a program, markdown as a document — so the
-    // created asset is guaranteed usable by show/start/validate, which pick
-    // their parser by the same extension.
-    if (isProgram) {
-        const parsed = parseWorkflowProgram(content, { path: sourcePath });
-        if (!parsed.ok) {
-            throw new UsageError(formatWorkflowErrors(sourcePath, parsed.errors));
-        }
-        const compiled = compileWorkflowProgram(parsed.program);
-        if (!compiled.ok) {
-            throw new UsageError(formatWorkflowErrors(sourcePath, compiled.errors));
-        }
-    }
-    else {
-        const result = parseWorkflow(content, { path: sourcePath });
-        if (!result.ok) {
-            throw new UsageError(formatWorkflowErrors(sourcePath, result.errors));
-        }
-    }
-    fs.mkdirSync(path.dirname(assetPath), { recursive: true });
-    fs.writeFileSync(assetPath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
+        : (input.content ?? buildWorkflowTemplate(normalizedName));
+    const sourcePath = input.from ?? `workflows/${normalizedName}.md`;
+    validateWorkflowContent(content, sourcePath);
+    const authoredContent = ensureAkmMarkdownType(content, "workflow");
+    const mode = fs.existsSync(assetPath) ? fs.lstatSync(assetPath).mode & 0o777 : 0o644;
+    const defaultBundle = defaultBundleForTarget(config);
+    const ref = makeBundleRef(target.source.name === defaultBundle ? undefined : target.source.name, conceptId);
+    withWriteTargetMutation(target, [assetPath], { ignored: "reject", purpose: "workflow-authoring", message: `Create ${ref}` }, () => {
+        fs.mkdirSync(path.dirname(assetPath), { recursive: true });
+        writeFileAtomic(assetPath, authoredContent.endsWith("\n") ? authoredContent : `${authoredContent}\n`, mode);
+    });
     return {
-        ref: `workflow:${normalizedName}`,
+        ref,
         path: assetPath,
         stashDir,
     };
@@ -167,10 +122,9 @@ function readWorkflowSource(source, stashDir) {
     return fs.readFileSync(resolved, "utf8");
 }
 function normalizeWorkflowName(name) {
-    // Strip any recognized workflow extension (.md/.yaml/.yml) so the canonical
-    // name — and thus the `workflow:<name>` ref — is extension-free regardless of
-    // how the user spelled it. The chosen format is recovered from the raw suffix
-    // by the caller (createWorkflowAsset).
+    // Strip a recognized workflow extension (.md) so the canonical name — and
+    // thus the `workflows/<name>` ref — is extension-free regardless of how the
+    // user spelled it.
     const normalized = canonicalizeWorkflowName(name
         .trim()
         .replace(/\\/g, "/")
@@ -190,7 +144,7 @@ function humanizeWorkflowName(name) {
         .pop()
         ?.replace(/[-_]+/g, " ")
         .replace(/\b\w/g, (match) => match.toUpperCase())
-        .trim() || "Example Workflow");
+        .trim() || "New Workflow");
 }
 function slugifyWorkflowStepId(name) {
     return (name
@@ -206,7 +160,7 @@ export function formatWorkflowErrors(path, errors) {
     return [heading, ...lines].join("\n");
 }
 /**
- * Validate a workflow by ref (`workflow:<name>`) or filesystem path.
+ * Validate a workflow filesystem path.
  *
  * Returns the parse result plus the source-relative path used. Throws
  * `UsageError` only when the target cannot be located on disk; parse
@@ -214,9 +168,6 @@ export function formatWorkflowErrors(path, errors) {
  * format them however they like.
  */
 export function validateWorkflowSource(target) {
-    if (target.startsWith("workflow:")) {
-        throw new UsageError(`validateWorkflowSource expects a filesystem path; resolve refs to paths in the caller before invoking.`);
-    }
     const resolved = path.resolve(target);
     if (!fs.existsSync(resolved)) {
         throw new UsageError(`Workflow file not found: "${target}".`);
@@ -225,34 +176,31 @@ export function validateWorkflowSource(target) {
     return { path: target, parse: parseWorkflow(content, { path: target }) };
 }
 /**
- * Validate a YAML workflow *program* by filesystem path: parse via
- * `parseWorkflowProgram`, then — only when the parse is clean — compile via
- * `compileWorkflowProgram` so expression/reference errors surface too. Both
- * error lists carry line numbers and are returned in the same
- * `WorkflowError[]` shape, ready for `formatWorkflowErrors`. Throws
- * `UsageError` only when the target cannot be located on disk.
+ * Every file under `typeRoot` whose canonical workflow name equals
+ * `normalizedName`. Extension matching is case-INSENSITIVE, so `foo.MD` and
+ * `foo.md` both match — the case-variant collision the create path must refuse
+ * rather than silently clobber on a case-insensitive filesystem.
  */
-export function validateWorkflowProgramSource(target) {
-    const resolved = path.resolve(target);
-    if (!fs.existsSync(resolved)) {
-        throw new UsageError(`Workflow file not found: "${target}".`);
-    }
-    const content = fs.readFileSync(resolved, "utf8");
-    const parse = parseWorkflowProgram(content, { path: target });
-    if (!parse.ok) {
-        return { path: target, result: { ok: false, errors: parse.errors } };
-    }
-    const compiled = compileWorkflowProgram(parse.program);
-    if (!compiled.ok) {
-        return { path: target, result: { ok: false, errors: compiled.errors } };
+function findExistingWorkflowPaths(typeRoot, normalizedName) {
+    const parent = path.join(typeRoot, path.dirname(normalizedName));
+    let entries;
+    try {
+        entries = fs.readdirSync(parent, { withFileTypes: true });
     }
-    // Non-fatal advisories ride along on a successful validation (additive) so
-    // `workflow validate` can surface them without changing the ok verdict.
-    return { path: target, result: { ok: true, program: parse.program, warnings: compiled.warnings } };
+    catch {
+        return [];
+    }
+    const basename = path.basename(normalizedName);
+    return WORKFLOW_EXTENSIONS.flatMap((extension) => entries
+        .filter((entry) => {
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            return false;
+        const entryExtension = path.extname(entry.name);
+        return entryExtension.toLowerCase() === extension && entry.name.slice(0, -entryExtension.length) === basename;
+    })
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((entry) => path.join(parent, entry.name)));
 }
-function renderWorkflowTemplate(input) {
-    return workflowTemplate
-        .replace("{{TITLE}}", input.title)
-        .replace("{{FIRST_STEP_TITLE}}", input.firstStepTitle)
-        .replace("{{FIRST_STEP_ID}}", input.firstStepId);
+function renderWorkflowTemplate(title) {
+    return workflowTemplate.replace("{{TITLE}}", title);
 }

package/dist/workflows/authoring/scope-key.js

@@ -21,7 +21,7 @@ export function resolveWorkflowScopeAnchor(startDir) {
     if (gitRoot)
         return gitRoot;
     try {
-        const stashDir = safeRealpath(resolveStashDir({ readOnly: true }));
+        const stashDir = safeRealpath(resolveStashDir());
         if (isWithin(cwd, stashDir))
             return stashDir;
     }

package/dist/workflows/cli.js

@@ -8,22 +8,6 @@ export const WORKFLOW_STEP_STATES = [
     "failed",
     "skipped",
 ];
-export const WORKFLOW_SUBCOMMANDS = new Set([
-    "start",
-    "next",
-    "complete",
-    "status",
-    "list",
-    "create",
-    "template",
-    "resume",
-    "abandon",
-    "validate",
-    "run",
-    "brief",
-    "report",
-    "watch",
-]);
 export function parseWorkflowJsonObject(raw, flagName) {
     if (!raw)
         return {};
@@ -47,7 +31,3 @@ export function parseWorkflowStepState(value) {
     }
     throw new UsageError(`Invalid workflow step state "${value}". Expected one of: ${WORKFLOW_STEP_STATES.join(", ")}`);
 }
-export function hasWorkflowSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && WORKFLOW_SUBCOMMANDS.has(command);
-}

package/dist/workflows/concurrency-policy.js

@@ -0,0 +1,15 @@
+// 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 os from "node:os";
+export const WORKFLOW_MAX_CONCURRENCY_CEILING = 64;
+export function cpuDerivedUnitConcurrency(cpuCount = os.cpus()?.length ?? 4) {
+    return Math.min(16, Math.max(1, cpuCount - 2));
+}
+export function clampMaxConcurrency(value) {
+    return Math.min(WORKFLOW_MAX_CONCURRENCY_CEILING, Math.max(1, Math.floor(value)));
+}
+/** Resolve and freeze the engine-wide cap once when a workflow run starts. */
+export function workflowMaxConcurrency(configured, cpuCount = os.cpus()?.length ?? 4) {
+    return configured === undefined ? cpuDerivedUnitConcurrency(cpuCount) : clampMaxConcurrency(configured);
+}

package/dist/workflows/exec/brief.js

@@ -29,16 +29,14 @@
  * driven run of the same frozen plan produce byte-identical unit graphs — the
  * invariant R4 asserts.
  */
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { canonicalizeWorkflowName } from "../../core/asset/asset-spec.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
-import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
-import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
+import { UsageError } from "../../core/errors.js";
 import { assertRunParamsSatisfyPlan } from "../ir/params.js";
-import { snapshotRunForDriver } from "../runtime/runs.js";
+import { frozenStepRows, requireExecutableWorkflowPlan } from "../runtime/plan-classifier.js";
+import { resolveExistingWorkflowRunId, snapshotRunForDriver } from "../runtime/runs.js";
 import { evaluateStaleUnits } from "../runtime/unit-checkin.js";
+import { GATE_EVALUATION_PHASE } from "../runtime/unit-phases.js";
 import { detectSecretShapedParams } from "./param-secrets.js";
-import { activeGateLoop, assertJournaledRouteSelectionsValid, computeStepWorkList, evaluateRoute, GATE_EVALUATION_PHASE, isWorkListFullyTerminal, parseFrozenPlan, recoverGateFeedback, selectUnitAttemptRow, stepOutputsFromEvidence, } from "./step-work.js";
+import { activeGateLoop, assertJournaledRouteSelectionsValid, computeStepWorkList, evaluateRoute, isWorkListFullyTerminal, recoverGateFeedback, selectUnitAttemptRow, stepOutputsFromEvidence, } from "./step-work.js";
 const EMPTY_WORK_LIST = { isFanOut: false, reducer: null, itemCount: 0, units: [] };
 // ── Entry point ──────────────────────────────────────────────────────────────
 /**
@@ -54,8 +52,6 @@ export async function buildWorkflowBrief(target) {
     // the active step between the spine read and the unit-journal read. A bare run
     // id never auto-starts (we resolved to a concrete id above).
     const { next, run: runRow, units } = await snapshotRunForDriver(runId);
-    const planJson = runRow.plan_json;
-    const planHash = runRow.plan_hash;
     const leaseHolder = runRow.engine_lease_holder;
     const leaseUntil = runRow.engine_lease_until;
     const run = {
@@ -141,10 +137,8 @@ export async function buildWorkflowBrief(target) {
             message: "Workflow run is active but has no current step.",
         };
     }
-    // Load the FROZEN plan the engine executes (migration 006). A legacy run
-    // (NULL plan_json) has no plan for brief to read — point at engine-driven
-    // mode, which still handles pre-006 runs by compiling from the asset.
-    const plan = loadFrozenPlanForBrief(run.id, planJson, planHash);
+    // Load the same frozen plan the engine executes.
+    const plan = requireExecutableWorkflowPlan(runRow);
     // Reviewer #12: the journaled params row must still satisfy the frozen param
     // schemas — a violation is post-start corruption, loud on the brief surface
     // too (mirrors the frozen-plan hash check and the tampered-params divergence).
@@ -171,19 +165,21 @@ export async function buildWorkflowBrief(target) {
     const gateFeedback = recoverGateFeedback(units, stepState.id, gateLoop);
     const isRouteOnly = !!stepPlan.route && !stepPlan.root;
     const kind = isRouteOnly ? "route" : stepPlan.route ? "execute-and-route" : "execute";
-    const criteria = stepState.completionCriteria ?? [];
+    const criteria = stepPlan.gate.criteria;
+    const instructions = frozenStepRows(plan).find((step) => step.stepId === stepState.id)?.instructions;
+    if (instructions === undefined)
+        throw new UsageError(`Step "${stepState.id}" has no frozen instructions.`);
     const step = {
         stepId: stepState.id,
-        title: stepState.title,
-        sequenceIndex: stepState.sequenceIndex ?? 0,
+        title: stepPlan.title,
+        sequenceIndex: stepPlan.sequenceIndex,
         kind,
-        instructions: stepState.instructions,
+        instructions,
         gate: {
             criteria,
             maxLoops: Math.max(1, stepPlan.gate.maxLoops ?? 1),
             currentLoop: gateLoop,
             judgesArtifact: !isRouteOnly && criteria.length > 0,
-            required: stepPlan.gate.required === true,
         },
         ...(stepPlan.outputSchema ? { outputSchema: stepPlan.outputSchema } : {}),
     };
@@ -209,6 +205,7 @@ export async function buildWorkflowBrief(target) {
             runId: run.id,
             params: run.params,
             stepOutputs,
+            engines: plan.execution.engines,
             gateLoop,
             ...(gateFeedback ? { gateFeedback } : {}),
         });
@@ -315,15 +312,19 @@ function makeSpineToken(runId, stepId, gateLoop, watermark) {
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
 function toBriefUnit(runId, unit, stepId, journaled, ctx) {
+    if (!unit.engine || !unit.invocation) {
+        throw new UsageError(`Unit "${unit.unitId}" has no complete frozen engine attribution.`);
+    }
     const action = deriveUnitAction(unit, journaled, ctx);
     const report = reportCommandForAction(runId, unit, stepId, action, journaled?.claim_holder ?? null);
     return {
         unitId: unit.unitId,
         nodeId: unit.nodeId,
         index: unit.index,
-        runner: unit.runner,
-        ...(unit.profile ? { profile: unit.profile } : {}),
-        ...(unit.model ? { model: unit.model } : {}),
+        engine: unit.invocation.engine,
+        runtimeKind: unit.runner,
+        platform: unit.engine.kind === "agent" ? unit.engine.platform : null,
+        model: unit.invocation.model,
         timeoutMs: unit.timeoutMs,
         ...(unit.schema ? { outputSchema: unit.schema } : {}),
         // Env asset REF names only — brief never resolves bindings, so no secret
@@ -428,33 +429,16 @@ function buildMessage(step, workList, route, gateLoop, settleState) {
     if (settleState === "finalize") {
         // Fully-terminal work-list on a still-active step: everything ran, nothing
         // remains to execute — the step only needs finalization (the run was
-        // gate-blocked then resumed, or a crash interrupted completion). A required
-        // gate with no judge available will re-block, which is correct behavior.
-        const gateNote = step.gate.required && step.gate.criteria.length > 0
-            ? " If this step's REQUIRED gate has no judge available it will re-block, pending a configured judge or a manual `akm workflow complete`."
-            : "";
+        // gate-rejected then resumed, or a crash interrupted completion).
         return (`Active step "${step.stepId}" has run all ${n} unit(s) to a terminal state${loopNote} — nothing remains to ` +
             `execute or report. Finalize it with \`akm workflow report --settle\` (see settleCommand): the gate is judged ` +
-            `and the step advances.${gateNote}`);
+            "and the step advances.");
     }
     if (settleState === "non-dispatching") {
         return `Active step "${step.stepId}" dispatches no reportable units${loopNote}.${settleNote}`;
     }
     return `Active step "${step.stepId}" expects ${n} unit(s)${loopNote}. Execute them, then report each result.`;
 }
-/**
- * brief-specific frozen-plan loader: unlike the engine's loader, a NULL
- * plan_json is a hard, actionable error rather than a warn-and-compile — brief
- * describes the frozen plan the engine executes, and a legacy run has none.
- */
-function loadFrozenPlanForBrief(runId, planJson, planHash) {
-    if (!planJson) {
-        throw new UsageError(`Workflow run ${runId} predates frozen plans (no plan_json on the run row) and cannot be described by ` +
-            `\`akm workflow brief\`. Drive it with engine-driven mode instead: \`akm workflow run ${runId}\` ` +
-            `(which compiles a legacy run's plan from the live asset).`);
-    }
-    return parseFrozenPlan(runId, planJson, planHash);
-}
 /**
  * Resolve `target` to a concrete run id WITHOUT starting anything. A run id
  * resolves directly; a workflow ref resolves to its active run in the current
@@ -462,23 +446,5 @@ function loadFrozenPlanForBrief(runId, planJson, planHash) {
  * would mutate).
  */
 export async function resolveRunId(target) {
-    return withWorkflowRunsRepo((repo) => {
-        const byId = repo.getRunById(target);
-        if (byId)
-            return byId.id;
-        if (!target.includes(":")) {
-            throw new NotFoundError(`Workflow run "${target}" not found.`, "WORKFLOW_NOT_FOUND");
-        }
-        const parsed = parseAssetRef(target);
-        if (parsed.type !== "workflow") {
-            throw new UsageError(`Expected a workflow run id or workflow ref (workflow:<name>), got "${target}".`);
-        }
-        const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalizeWorkflowName(parsed.name)}`;
-        const active = repo.getActiveRunRowForScope(ref, getCurrentWorkflowScopeKey());
-        if (!active) {
-            throw new NotFoundError(`No active workflow run for ${ref} in this scope. \`akm workflow brief\` describes an existing run and never ` +
-                `starts one — run \`akm workflow start ${ref}\` (or \`akm workflow run ${ref}\`) first.`, "WORKFLOW_NOT_FOUND");
-        }
-        return active.id;
-    });
+    return resolveExistingWorkflowRunId(target);
 }

package/dist/workflows/exec/frozen-judge.js

@@ -0,0 +1,47 @@
+// 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 { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { ConfigError } from "../../core/errors.js";
+/** Build a gate judge from a v3 catalog entry without consulting live config. */
+export function frozenSummaryJudge(plan, invocation) {
+    if (!invocation)
+        return null;
+    const engine = plan.execution?.engines[invocation.engine];
+    if (!engine || engine.kind !== "llm")
+        throw new ConfigError(`Frozen gate engine "${invocation.engine}" is unavailable.`, "INVALID_CONFIG_FILE");
+    return async ({ system, user }) => {
+        const { chatCompletion } = await import("../../llm/client.js");
+        return chatCompletion(materialize(engine, invocation), [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ], {
+            timeoutMs: invocation.timeoutMs,
+        });
+    };
+}
+function materialize(engine, invocation) {
+    let apiKey;
+    for (const name of engine.credential?.names ?? []) {
+        const value = process.env[name]?.trim();
+        if (value) {
+            apiKey = value;
+            break;
+        }
+    }
+    if (engine.credential?.required && !apiKey)
+        throw new ConfigError(`Required engine credential ${engine.credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
+    const base = {
+        provider: engine.provider,
+        endpoint: engine.endpoint,
+        model: invocation.model ?? engine.model,
+        ...(engine.temperature !== undefined ? { temperature: engine.temperature } : {}),
+        ...(engine.maxTokens !== undefined ? { maxTokens: engine.maxTokens } : {}),
+        ...(engine.supportsJsonSchema !== undefined ? { supportsJsonSchema: engine.supportsJsonSchema } : {}),
+        ...(engine.extraParams ? { extraParams: engine.extraParams } : {}),
+        ...(engine.contextLength !== undefined ? { contextLength: engine.contextLength } : {}),
+        ...(engine.enableThinking !== undefined ? { enableThinking: engine.enableThinking } : {}),
+        ...(apiKey ? { apiKey } : {}),
+    };
+    return (invocation.llm ? deepMergeConfig(base, invocation.llm) : base);
+}