akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/workflows/program/expressions.js

@@ -1,110 +1,20 @@
 // 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>])*";
 /**
- * The deterministic expression language for YAML orchestration programs
- * (R1 redesign addendum). `${{ ... }}` delimits references; everything else
- * is literal text that passes through byte-exact.
- *
- * The grammar is CLOSED — exactly four roots, nothing else parses:
- *
- *   params.<ident>
- *   steps.<ident>.output( .<ident> | [<non-negative int>] )*
- *   item
- *   item_index
- *
- * where <ident> is `[A-Za-z_][A-Za-z0-9_-]*`. No functions, no clock, no
- * randomness, no ambient lookup — orchestration decisions stay pure
- * functions of (frozen plan, params, journaled unit results).
- *
- * Templates are parsed ONCE into literal/reference segments; resolution is a
- * single pass over that AST. Substituted content is data, never re-scanned,
- * so a value containing `${{ params.x }}` is inserted literally — the P1
- * re-scan injection bug class is structurally impossible.
- *
- * There is deliberately NO escape syntax in v1: a literal `${{` cannot
- * appear in instructions. Authors who write one get a parse error from the
- * validator (unterminated or invalid reference) telling them so.
- *
- * Pure module: no IO, no engine imports.
+ * Parse a bare reference string (a whole-value frontmatter field, already
+ * delimiter-free: `map.over`, `route.input`, or one entry of `inputs[]`).
  */
-const OPEN = "${{";
-const CLOSE = "}}";
-// ── Template parsing ─────────────────────────────────────────────────────────
-/**
- * Split a template into literal and reference segments. Literal text passes
- * through byte-exact, including `$`, `{`, `}`, `${`, `{{`, and `}}` sequences
- * that do not form the exact `${{` opener. Errors are returned, not thrown.
- */
-export function parseTemplate(template) {
-    const segments = [];
-    const errors = [];
-    let cursor = 0;
-    while (cursor < template.length) {
-        const open = template.indexOf(OPEN, cursor);
-        if (open === -1)
-            break;
-        if (open > cursor)
-            segments.push({ kind: "literal", text: template.slice(cursor, open) });
-        const close = template.indexOf(CLOSE, open + OPEN.length);
-        const nested = template.indexOf(OPEN, open + OPEN.length);
-        if (close === -1) {
-            errors.push({
-                index: open,
-                message: `Unterminated ${OPEN} reference (no matching ${CLOSE}). ` +
-                    `Note: there is no escape syntax — a literal ${OPEN} cannot appear in this text.`,
-            });
-            cursor = template.length;
-            break;
-        }
-        if (nested !== -1 && nested < close) {
-            errors.push({
-                index: nested,
-                message: `Nested ${OPEN} inside a reference — references cannot contain other references.`,
-            });
-            cursor = close + CLOSE.length;
-            continue;
-        }
-        const inner = template.slice(open + OPEN.length, close);
-        const parsed = parseExpression(inner);
-        if (parsed.ok) {
-            segments.push({
-                kind: "reference",
-                expr: parsed.expr,
-                raw: template.slice(open, close + CLOSE.length),
-                index: open,
-            });
-        }
-        else {
-            errors.push({ index: open, message: parsed.message });
-        }
-        cursor = close + CLOSE.length;
-    }
-    if (cursor < template.length)
-        segments.push({ kind: "literal", text: template.slice(cursor) });
-    return errors.length > 0 ? { ok: false, errors } : { ok: true, segments };
-}
-const GRAMMAR_HINT = "allowed forms: params.<name>, steps.<id>.output[...], item, item_index";
-/**
- * Parse a single expression (the text between `${{` and `}}`, or a bare
- * whole-value field such as `map.over` after delimiter stripping).
- */
-export function parseExpression(source) {
+export function parseReference(source) {
     const text = source.trim();
     if (text === "")
-        return { ok: false, message: `Empty expression inside ${OPEN} ${CLOSE}; ${GRAMMAR_HINT}.` };
+        return { ok: false, message: `Empty reference; ${GRAMMAR_HINT}.` };
     const root = readIdent(text, 0);
     if (!root) {
-        return { ok: false, message: `Invalid expression "${text}" — must start with an identifier; ${GRAMMAR_HINT}.` };
+        return { ok: false, message: `Invalid reference "${text}" — must start with an identifier; ${GRAMMAR_HINT}.` };
     }
     switch (root.name) {
-        case "item":
-        case "item_index": {
-            if (root.end !== text.length) {
-                return { ok: false, message: `"${root.name}" takes no path — found trailing "${text.slice(root.end)}".` };
-            }
-            return { ok: true, expr: root.name === "item" ? { kind: "item" } : { kind: "itemIndex" } };
-        }
         case "params": {
             if (text[root.end] !== ".") {
                 return { ok: false, message: `"params" requires a name: params.<name> (got "${text}").` };
@@ -188,78 +98,10 @@ function parsePath(text, start) {
     return { ok: true, path };
 }
 // ── Resolution ───────────────────────────────────────────────────────────────
-/**
- * Resolve parsed segments against a scope in a SINGLE pass — resolved values
- * are concatenated as data and never re-scanned for further references.
- * Strings insert verbatim; numbers/booleans via String(); objects/arrays as
- * canonical JSON (recursively sorted keys); null/undefined/missing paths are
- * resolution errors naming the reference.
- */
-export function resolveTemplate(segments, scope) {
-    const parts = [];
-    const errors = [];
-    for (const segment of segments) {
-        if (segment.kind === "literal") {
-            parts.push(segment.text);
-            continue;
-        }
-        const resolved = resolveReference(segment.expr, scope);
-        if (!resolved.ok) {
-            errors.push(resolved.error);
-            continue;
-        }
-        const value = resolved.value;
-        if (typeof value === "string") {
-            parts.push(value);
-        }
-        else if (typeof value === "number" || typeof value === "boolean") {
-            parts.push(String(value));
-        }
-        else if (typeof value === "object" && value !== null) {
-            parts.push(canonicalJson(value));
-        }
-        else {
-            errors.push({
-                reference: formatReference(segment.expr),
-                message: `${formatReference(segment.expr)} resolved to an unsupported value type (${typeof value}).`,
-            });
-        }
-    }
-    return errors.length > 0 ? { ok: false, errors } : { ok: true, text: parts.join("") };
-}
-/**
- * Resolve a whole-value field (`map.over`, `route.input`) from its RAW
- * template string: the text must be exactly one `${{ … }}` reference with no
- * surrounding literal text (the compiler enforces this for YAML programs;
- * frozen plans are re-checked here so a tampered/legacy plan fails loudly
- * instead of string-splicing). The reference resolves to its RAW value —
- * arrays stay arrays, objects stay objects.
- */
-export function resolveWholeValue(template, scope) {
-    const parsed = parseTemplate(template);
-    if (!parsed.ok) {
-        return {
-            ok: false,
-            error: { reference: template, message: parsed.errors.map((e) => e.message).join(" ") },
-        };
-    }
-    const [first] = parsed.segments;
-    if (parsed.segments.length !== 1 || first?.kind !== "reference") {
-        return {
-            ok: false,
-            error: {
-                reference: template,
-                message: `expected a single whole-value \${{ … }} reference with no surrounding text ` +
-                    `(e.g. "\${{ steps.discover.output.files }}"), got ${JSON.stringify(template)}.`,
-            },
-        };
-    }
-    return resolveReference(first.expr, scope);
-}
 /**
  * Resolve a single reference to its RAW value for whole-value contexts
- * (`map.over`, `route.input`): arrays stay arrays, objects stay objects.
- * null/undefined values and missing paths are errors, same as in templates.
+ * (`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);
@@ -271,16 +113,6 @@ export function resolveReference(expr, scope) {
             }
             return finish(scope.params[expr.name], reference, fail);
         }
-        case "item": {
-            if (scope.item === undefined)
-                return fail("item is only available inside a map unit.");
-            return finish(scope.item, reference, fail);
-        }
-        case "itemIndex": {
-            if (typeof scope.itemIndex !== "number")
-                return fail("item_index is only available inside a map unit.");
-            return { ok: true, value: scope.itemIndex };
-        }
         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.`);
@@ -313,6 +145,18 @@ export function resolveReference(expr, scope) {
         }
     }
 }
+/**
+ * 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.`);
@@ -321,24 +165,11 @@ function finish(value, reference, fail) {
     return { ok: true, value };
 }
 // ── Introspection helpers ────────────────────────────────────────────────────
-/** The reference ASTs of a parsed template, in document order — for validator edge checking. */
-export function listReferences(segments) {
-    const references = [];
-    for (const segment of segments) {
-        if (segment.kind === "reference")
-            references.push(segment.expr);
-    }
-    return references;
-}
 /** 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 "item":
-            return "item";
-        case "itemIndex":
-            return "item_index";
         case "stepOutput": {
             let text = `steps.${expr.stepId}.output`;
             for (const segment of expr.path) {
@@ -348,22 +179,3 @@ export function formatReference(expr) {
         }
     }
 }
-// ── Canonical JSON ───────────────────────────────────────────────────────────
-/**
- * Stable stringify with recursively sorted object keys, so equal values
- * render identically regardless of key insertion order. Same pattern as the
- * module-private helper in exec/native-executor.ts (not exported there).
- */
-function canonicalJson(value) {
-    return JSON.stringify(sortKeys(value));
-}
-function sortKeys(value) {
-    if (Array.isArray(value))
-        return value.map(sortKeys);
-    if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value)
-            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-            .map(([k, v]) => [k, sortKeys(v)]));
-    }
-    return value;
-}

package/dist/workflows/program/schema.js

@@ -1,14 +1,11 @@
 // 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_PROGRAM_VERSION = 2;
-/** @deprecated source v2 rejects runner; retained for TypeScript migration only. */
-export const PROGRAM_RUNNER_KINDS = ["llm", "agent", "sdk", "inherit"];
 /** 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 (enforcement is R2). */
+/** Filesystem isolation for file-mutating units. */
 export const PROGRAM_ISOLATION_KINDS = ["none", "worktree"];
 /**
  * `retry.on` vocabulary — exactly the persisted `AgentFailureReason` taxonomy
@@ -32,15 +29,15 @@ const RETRY_REASON_SET = {
 };
 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).
- *
- * This is EXACTLY the `<ident>` grammar `readIdent` accepts in
- * `program/expressions.ts` for `${{ steps.<id>.output }}` references: a
+ * 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 unit templates without renaming.
+ * 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
@@ -48,7 +45,7 @@ export const PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);
  */
 export const PROGRAM_STEP_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 /**
- * Param names must be `${{ params.<ident> }}`-addressable, so they are plain
+ * 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,31 +2,21 @@
 // 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 renderers for workflow assets.
- *
- * Two formats, one asset type:
- *
- *   - `workflow-md` — reads the classic linear 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.
- *   - `workflow-program-yaml` — reads a YAML workflow *program* (redesign
- *     addendum, R1) via `parseWorkflowProgram` and projects it through
- *     `program/project.ts`, including a compact orchestration summary per
- *     step (runner/model, `fanOut.over` expression, route table).
+ * 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 { displayRef } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
 import { parseWorkflow } from "./parser.js";
-import { parseWorkflowProgram } from "./program/parser.js";
-import { programStepInstructions, projectProgramParameters, summarizeProgramStepOrchestration, WORKFLOW_PROGRAM_RENDERER_NAME, } from "./program/project.js";
-export { WORKFLOW_PROGRAM_RENDERER_NAME };
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 export function buildWorkflowAction(ref) {
-    return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
+    return `Start or resume execution with \`akm workflow run ${shellQuote(ref)}\`.`;
 }
 function deriveName(ctx) {
     const metaName = ctx.matchResult.meta?.name;
@@ -42,73 +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);
-        // WI-8.5b (display flip): the `akm workflow next <ref>` action is DISPLAY
+        // WI-8.5b (display flip): the `akm workflow run <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 });
+        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,
-            })),
-        };
-    },
-};
-function loadProgram(ctx) {
-    const result = parseWorkflowProgram(ctx.content(), { path: ctx.relPath });
-    if (result.ok)
-        return result.program;
-    const summary = result.errors.map((e) => `${ctx.relPath}:${e.line} — ${e.message}`).join("\n");
-    throw new UsageError(`Workflow has errors:\n${summary}`);
-}
-/** Show renderer for YAML workflow programs — mirrors `workflowMdRenderer`. */
-export const workflowProgramRenderer = {
-    name: WORKFLOW_PROGRAM_RENDERER_NAME,
-    buildShowResponse(ctx) {
-        const name = deriveName(ctx);
-        const program = loadProgram(ctx);
-        // WI-8.5b (display flip): the `akm workflow next <ref>` action is DISPLAY
-        // output — its spelling follows the D-R5 display rule (`displayRef`), mirroring
-        // workflowMdRenderer above.
-        const ref = displayRef({ type: "workflow", name, bundleId: ctx.origin });
-        const parameters = projectProgramParameters(program);
-        return {
-            type: "workflow",
-            name,
-            path: ctx.absPath,
-            action: buildWorkflowAction(ref),
-            description: program.description,
-            workflowTitle: program.name,
+            // 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: program.steps.map((step, index) => {
-                const orchestration = summarizeProgramStepOrchestration(step, program.defaults);
-                return {
-                    id: step.id,
-                    title: step.title ?? step.id,
-                    instructions: programStepInstructions(step),
-                    ...(step.gate ? { completionCriteria: [...step.gate.criteria] } : {}),
-                    sequenceIndex: index,
-                    ...(orchestration ? { orchestration } : {}),
-                };
-            }),
+            steps: projectStepDefinitions(doc),
         };
     },
 };

package/dist/workflows/resource-limits.js

@@ -12,6 +12,8 @@ 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");
 }

package/dist/workflows/runtime/checkin.js

@@ -9,7 +9,7 @@
  * 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
- * row; the next time the agent polls the engine via `workflow next`/`status`,
+ * row; the next time the agent polls the engine via `workflow run`/`status`,
  * {@link evaluateCheckin} is called to decide — purely from timestamps — whether
  * the run looks stalled and a strong `continue` directive should be surfaced
  * through the normal command output.
@@ -48,8 +48,8 @@ export function evaluateCheckin(run, now = Date.now(), stallMs = CHECKIN_STALL_M
     return {
         signal: "continue",
         directive: "CONTINUE: this workflow run has stalled with no progress. Resume immediately — " +
-            "re-read the current step's instructions, finish the outstanding work, then call " +
-            "`akm workflow complete` with a summary. Do not stop until the step is complete.",
+            "inspect its status, then call `akm workflow run` with the run id to finish the outstanding work. " +
+            "Do not stop until the run reaches a terminal state or reports a verification rejection.",
         idleMs,
         agentHarness: run.agentHarness ?? null,
         agentSessionId: run.agentSessionId ?? null,