akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/workflow-cli.js

@@ -2,140 +2,19 @@
 // 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/.
 /**
- * `akm workflow` command family. Extracted verbatim from src/cli.ts (WS6) so the
- * God Module shrinks; the `main.subCommands.workflow` key and every subcommand's
- * args/output shape are byte-identical. Handlers whose body is a plain
- * `runWithJsonErrors(...) + output(...)` are migrated to `defineJsonCommand`,
- * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
- * form. `workflow template` keeps a plain `defineCommand` because it writes the
- * template straight to stdout with no JSON envelope. The private helpers
- * `looksLikeWorkflowRunId` and `resolveWorkflowFilePath` move with the family.
+ * `akm workflow` command family. `run` is the canonical start/resume/execute
+ * surface; the former public `start`, `next`, and `complete` lifecycle is gone.
+ * Workflows are markdown-only; authoring uses `create --print` and validation
+ * uses `akm lint --type workflows`.
  */
-import { defineCommand } from "citty";
-import { getParsedInvocation } from "../cli/invocation.js";
 import { getStringArg } from "../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
-import { parseRefInput } from "../core/asset/resolve-ref.js";
-import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
-import { resolveSourceEntries } from "../indexer/search/search-source.js";
-import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
-import { resolveAssetPath } from "../sources/resolve.js";
-import { createWorkflowAsset, formatWorkflowErrors, getWorkflowProgramTemplate, getWorkflowTemplate, validateWorkflowProgramSource, validateWorkflowSource, } from "../workflows/authoring/authoring.js";
-import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "../workflows/cli.js";
-import { isWorkflowProgramPath } from "../workflows/program/project.js";
-import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
-import { canonicalWorkflowRunRef } from "../workflows/runtime/workflow-asset-loader.js";
-const workflowStartCommand = defineJsonCommand({
-    meta: {
-        name: "start",
-        description: "Start a new workflow run in the current working scope",
-    },
-    args: {
-        ref: { type: "positional", description: "Workflow ref (workflows/<name>)", required: true },
-        params: { type: "string", description: "Workflow parameters as a JSON object" },
-        force: {
-            type: "boolean",
-            description: "Allow a parallel run when an active run already exists in this scope (#485)",
-            default: false,
-        },
-    },
-    async run({ args }) {
-        const result = await startWorkflowRun(args.ref, parseWorkflowJsonObject(args.params, "--params"), {
-            force: args.force === true,
-        });
-        output("workflow-start", result);
-    },
-});
-const workflowNextCommand = defineJsonCommand({
-    meta: {
-        name: "next",
-        description: "Show the next actionable workflow step in the current scope, auto-starting a run when passed a workflow ref",
-    },
-    args: {
-        target: { type: "positional", description: "Workflow run id or workflow ref", required: true },
-        params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
-    },
-    async run({ args }) {
-        // `--dry-run` is intentionally NOT a declared arg (so it stays out of
-        // --help). The guard reads it straight from the invocation singleton so
-        // existing callers still get a clear, actionable error instead of a
-        // generic "unknown flag" from citty.
-        if (getParsedInvocation().hasFlag("--dry-run")) {
-            throw new UsageError("`akm workflow next` does not support --dry-run. Remove the flag to start or resume a run.", "INVALID_FLAG_VALUE");
-        }
-        const parsedParams = args.params ? parseWorkflowJsonObject(args.params, "--params") : undefined;
-        // If the target looks like a UUID-style run id (no `:` and matches the
-        // run-id shape), short-circuit with a structured WORKFLOW_NOT_FOUND
-        // error before the ref parser throws an unhelpful ref-parse error.
-        if (looksLikeWorkflowRunId(args.target)) {
-            const { hasWorkflowRun } = await import("../workflows/runtime/runs.js");
-            if (!(await hasWorkflowRun(args.target))) {
-                throw new NotFoundError(`Workflow run "${args.target}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
-            }
-        }
-        const result = await getNextWorkflowStep(args.target, parsedParams);
-        output("workflow-next", result);
-    },
-});
-/**
- * Heuristic: a workflow run id is a UUID-shaped or hex-id-shaped string with
- * no `/` separator (canonical refs contain `workflows/<name>`). When this
- * matches we can give a much better
- * error than the ref parser's "Invalid asset type" failure.
- */
-function looksLikeWorkflowRunId(target) {
-    if (target.includes(":"))
-        return false;
-    if (target.includes("/"))
-        return false;
-    // UUID v4-ish: 8-4-4-4-12 hex digits separated by dashes.
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(target))
-        return true;
-    // Bare hex/alphanumeric run ids of >=8 chars (covers shortened ids).
-    if (/^[0-9a-z][0-9a-z_-]{7,}$/i.test(target) && /[0-9]/.test(target))
-        return true;
-    return false;
-}
-const workflowCompleteCommand = defineJsonCommand({
-    meta: {
-        name: "complete",
-        description: "Update a workflow step state and persist notes/evidence",
-    },
-    args: {
-        runId: { type: "positional", description: "Workflow run id", required: true },
-        step: { type: "string", description: "Workflow step id", required: true },
-        state: {
-            type: "string",
-            description: `Step state (default: completed). One of: ${WORKFLOW_STEP_STATES.join(", ")}.`,
-        },
-        notes: { type: "string", description: "Notes for the completed step" },
-        summary: {
-            type: "string",
-            description: "Summary of work done (required when completing a step); validated against completion criteria",
-        },
-        evidence: { type: "string", description: "Evidence JSON object for the step" },
-    },
-    async run({ args }) {
-        const result = await completeWorkflowStep({
-            runId: args.runId,
-            stepId: args.step,
-            status: parseWorkflowStepState(args.state),
-            notes: args.notes,
-            summary: args.summary,
-            evidence: args.evidence ? parseWorkflowJsonObject(args.evidence, "--evidence") : undefined,
-        });
-        if ("ok" in result && result.ok === false) {
-            // Summary failed the completion-criteria validation gate (#506): the
-            // step stays pending and the agent receives corrective feedback.
-            output("workflow-complete-rejected", result);
-            return;
-        }
-        output("workflow-complete", result);
-    },
-});
+import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
+import { WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
+import { abandonWorkflowRun, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
 const workflowStatusCommand = defineJsonCommand({
     meta: {
         name: "status",
@@ -146,38 +25,33 @@ const workflowStatusCommand = defineJsonCommand({
         units: {
             type: "boolean",
             description: "Also list per-unit rows from the run journal (unit id, status, failure_reason, and any result/error " +
-                "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected (#22).",
+                "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected.",
             default: false,
         },
     },
     async run({ args }) {
         const target = args.target;
         const includeUnits = args.units === true;
-        // Check if target looks like a workflow ref
-        const parsed = (() => {
-            try {
-                return parseRefInput(target);
-            }
-            catch {
-                return null;
-            }
-        })();
-        if (parsed?.type === "workflow") {
-            const ref = canonicalWorkflowRunRef(parsed.origin, parsed.name);
-            const { runs } = await listWorkflowRuns({ workflowRef: ref });
-            if (runs.length === 0) {
-                throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            }
-            const mostRecent = runs[0];
-            if (!mostRecent)
-                throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
-            output("workflow-status", result);
-        }
-        else {
+        if (await hasWorkflowRun(target)) {
             const result = await getWorkflowStatus(target, { includeUnits });
             output("workflow-status", result);
+            return;
+        }
+        let runs;
+        try {
+            ({ runs } = await listWorkflowRuns({ workflowRef: target }));
+        }
+        catch (error) {
+            if (!target.includes(":") && !target.includes("/")) {
+                throw new NotFoundError(`Workflow run "${target}" not found.`, "WORKFLOW_NOT_FOUND");
+            }
+            throw error;
         }
+        const mostRecent = runs[0];
+        if (!mostRecent)
+            throw new NotFoundError(`No workflow runs found for ${target}`, "WORKFLOW_NOT_FOUND");
+        const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
+        output("workflow-status", result);
     },
 });
 const workflowListCommand = defineJsonCommand({
@@ -197,12 +71,12 @@ const workflowListCommand = defineJsonCommand({
 const workflowCreateCommand = defineJsonCommand({
     meta: {
         name: "create",
-        description: "Create a workflow in the working stash (markdown document by default; a .yaml/.yml name writes a YAML program)",
+        description: "Create a workflow (markdown document) in the working bundle",
     },
     args: {
         name: {
             type: "positional",
-            description: "Workflow name (flat, no '/'; use --path for a subdirectory). A .yaml/.yml suffix creates a YAML program.",
+            description: "Workflow name (flat, no '/'; use --path for a subdirectory).",
             required: true,
         },
         path: {
@@ -211,7 +85,7 @@ const workflowCreateCommand = defineJsonCommand({
         },
         from: {
             type: "string",
-            description: "Import and validate content from an existing file (parsed per the destination extension)",
+            description: "Import and validate content from an existing file",
         },
         force: {
             type: "boolean",
@@ -223,6 +97,11 @@ const workflowCreateCommand = defineJsonCommand({
             description: "Explicitly replace an existing workflow with a fresh template (use with --force)",
             default: false,
         },
+        print: {
+            type: "boolean",
+            description: "Print the RAW template that would be written to stdout without creating anything — pipe it to a file as a starter document",
+            default: false,
+        },
     },
     async run({ args }) {
         // `name` is flat; subdirectory placement is `--path`'s job.
@@ -232,6 +111,14 @@ const workflowCreateCommand = defineJsonCommand({
         if (!namePattern.test(effectiveName)) {
             throw new UsageError("Workflow name must start with a lowercase letter or digit and contain only lowercase letters, digits, hyphens, dots, underscores, and slashes.");
         }
+        assertWorkflowMarkdownName(effectiveName);
+        if (args.print) {
+            // Raw document, not an envelope — the retired `workflow template` was
+            // format-exempt for the same reason: `--print > starter.md` must yield
+            // a usable starter file, not `{ok,template,kind}` JSON.
+            process.stdout.write(getWorkflowTemplate());
+            return;
+        }
         if (args.force && !args.from && !args.reset) {
             throw new UsageError("Refusing to overwrite with template: pass --from <file> to replace content, or --reset to explicitly replace with a fresh template.");
         }
@@ -240,312 +127,159 @@ const workflowCreateCommand = defineJsonCommand({
             from: args.from,
             force: args.force,
         });
-        // Index the newly-written workflow so `akm workflow start` can resolve
+        // Index the newly-written workflow so `akm workflow run` can resolve
         // a workflowEntryId without requiring an explicit `akm index` call
         // first. Uses the same incremental index path that `akm add` uses.
         await akmIndex({ stashDir: result.stashDir });
         output("workflow-create", { ok: true, ...result });
     },
 });
-const workflowTemplateCommand = defineCommand({
-    meta: {
-        name: "template",
-        description: "Print a valid workflow template (markdown by default, --yaml for a YAML program)",
-    },
-    args: {
-        yaml: {
-            type: "boolean",
-            description: "Print a minimal valid YAML workflow program instead of the markdown template",
-            default: false,
-        },
-    },
-    run({ args }) {
-        process.stdout.write(args.yaml ? getWorkflowProgramTemplate() : getWorkflowTemplate());
-    },
-});
-const workflowValidateCommand = defineJsonCommand({
-    meta: {
-        name: "validate",
-        description: "Validate a workflow file or ref (markdown document or YAML program) and print any errors",
-    },
-    args: {
-        target: {
-            type: "positional",
-            description: "Workflow ref (workflows/<name>) or filesystem path to a workflow .md/.yaml",
-            required: true,
-        },
-    },
-    async run({ args }) {
-        const filePath = await resolveWorkflowFilePath(args.target);
-        // YAML programs (redesign addendum, R1) validate through the program
-        // parser AND compiler so expression/reference errors surface at lint
-        // time; both error lists carry line numbers. Markdown is unchanged.
-        if (isWorkflowProgramPath(filePath)) {
-            const { result } = validateWorkflowProgramSource(filePath);
-            if (!result.ok) {
-                throw new UsageError(formatWorkflowErrors(filePath, result.errors));
-            }
-            // Non-fatal WARNINGS ride the envelope additively — `ok` stays true. The
-            // text formatter renders them clearly marked for humans; the JSON key is
-            // the machine channel. Empty array when the program is fully typed/declared.
-            output("workflow-validate", {
-                ok: true,
-                path: filePath,
-                format: "program",
-                title: result.program.name,
-                stepCount: result.program.steps.length,
-                warnings: result.warnings.map((w) => ({ line: w.line, message: w.message })),
-            });
-            return;
-        }
-        const { parse } = validateWorkflowSource(filePath);
-        if (parse.ok) {
-            output("workflow-validate", {
-                ok: true,
-                path: filePath,
-                title: parse.document.title,
-                stepCount: parse.document.steps.length,
-            });
-            return;
-        }
-        throw new UsageError(formatWorkflowErrors(filePath, parse.errors));
-    },
-});
-async function resolveWorkflowFilePath(target) {
-    // Canonical workflow refs resolve through the source search; anything else is
-    // treated as a filesystem path.
-    const looksLikeWorkflowRef = target.startsWith("workflows/") || target.includes("//workflows/");
-    if (!looksLikeWorkflowRef)
-        return target;
-    const parsed = parseRefInput(target);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref (workflows/<name>), got "${target}".`);
-    }
-    const config = loadConfig();
-    const allSources = resolveSourceEntries(undefined, config);
-    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-    for (const source of searchSources) {
-        try {
-            return await resolveAssetPath(source.path, "workflow", parsed.name);
-        }
-        catch {
-            /* try next source */
-        }
-    }
-    throw new UsageError(`Workflow not found for ref: workflows/${parsed.name}`);
-}
 const workflowRunCommand = defineJsonCommand({
     meta: {
         name: "run",
-        description: "EXPERIMENTAL: execute a workflow's steps with the native engine — akm dispatches each step's units " +
-            "(fan-out, schema output) to the configured runner and advances the run through the normal completion gates",
+        description: "Start or resume a workflow and execute it through completion, failure, a verification gate, or an explicit limit",
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref (auto-starts a run)", required: true },
-        params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
         "max-steps": { type: "string", description: "Stop after executing this many steps" },
-        "require-gates": {
-            type: "boolean",
-            description: "Treat every criteria-bearing completion gate as required: if no LLM judge is available, BLOCK the step " +
-                "(for a human to resolve via `akm workflow resume`) instead of failing open. A per-step `gate.required: true` " +
-                "in the workflow does the same on every surface; this is the run-wide override (#18).",
-            default: false,
-        },
+        "max-retries": { type: "string", description: "Retry a failed workflow step this many additional times" },
+        timeout: { type: "string", description: "Whole-run timeout: N, Nms, Ns, or Nm (bare N is milliseconds)" },
     },
-    async run({ args }) {
+    async run({ args, rawArgs }) {
         const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
-        const rawMaxSteps = getStringArg(args, "max-steps");
-        let maxSteps;
-        if (rawMaxSteps !== undefined) {
-            maxSteps = Number.parseInt(rawMaxSteps, 10);
-            if (!/^\d+$/.test(rawMaxSteps) || maxSteps <= 0) {
-                throw new UsageError(`--max-steps must be a positive integer, got "${rawMaxSteps}".`, "INVALID_FLAG_VALUE");
+        const parameterFlags = parseWorkflowParameterFlags(rawArgs, args.target);
+        const maxSteps = parseIntegerFlag(getStringArg(args, "max-steps"), "--max-steps", 1);
+        const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0, WORKFLOW_MAX_RETRIES);
+        const timeoutMs = parseWorkflowTimeout(getStringArg(args, "timeout"));
+        const controller = new AbortController();
+        let timedOut = false;
+        let signalExitCode;
+        const interrupt = (signal) => {
+            signalExitCode = signal === "SIGINT" ? 130 : 143;
+            controller.abort(new Error(`Workflow run interrupted by ${signal}.`));
+        };
+        const onSigint = () => interrupt("SIGINT");
+        const onSigterm = () => interrupt("SIGTERM");
+        process.once("SIGINT", onSigint);
+        process.once("SIGTERM", onSigterm);
+        const timer = timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                timedOut = true;
+                controller.abort(new Error(`Workflow run timed out after ${timeoutMs}ms.`));
+            }, timeoutMs);
+        timer?.unref?.();
+        try {
+            const result = await runWorkflowSteps({
+                target: args.target,
+                parameterFlags,
+                ...(maxSteps !== undefined ? { maxSteps } : {}),
+                ...(maxRetries !== undefined ? { maxRetries } : {}),
+                signal: controller.signal,
+            });
+            const rendered = { ...result, ...(timedOut ? { timedOut: true } : {}) };
+            output("workflow-run", rendered);
+            if (result.run.status === "failed" || result.gateRejection || result.aborted) {
+                process.exitCode = signalExitCode ?? EXIT_CODES.GENERAL;
             }
         }
-        const result = await runWorkflowSteps({
-            target: args.target,
-            ...(args.params ? { params: parseWorkflowJsonObject(args.params, "--params") } : {}),
-            ...(maxSteps !== undefined ? { maxSteps } : {}),
-            ...(args["require-gates"] === true ? { requireGates: true } : {}),
-        });
-        output("workflow-run", result);
-    },
-});
-const workflowBriefCommand = defineJsonCommand({
-    meta: {
-        name: "brief",
-        description: "EXPERIMENTAL: describe a run's active step as an executable work-list for ANY agent session (the " +
-            "harness-neutral driver protocol) — read-only, takes no engine lease, mutates nothing; prints per-unit " +
-            "instructions, output schema, env binding names, and the exact `akm workflow report` command lines",
-    },
-    args: {
-        target: {
-            type: "positional",
-            description: "Workflow run id (or a workflow ref with an active run)",
-            required: true,
-        },
-    },
-    async run({ args }) {
-        const { buildWorkflowBrief } = await import("../workflows/exec/brief.js");
-        const result = await buildWorkflowBrief(args.target);
-        output("workflow-brief", result);
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+        }
     },
 });
-const WORKFLOW_REPORT_STATES = ["completed", "failed", "running"];
-const workflowReportCommand = defineJsonCommand({
-    meta: {
-        name: "report",
-        description: "EXPERIMENTAL: report a unit's result back into a run (the mutating half of the harness-neutral driver " +
-            "protocol) — ingested through the SAME shared step semantics the engine uses. --status running claims/" +
-            "heartbeats a unit; completed/failed records it and, when the step's work-list is fully terminal, runs the " +
-            "engine's completion path (reducer, artifact + schema validation, gate). --settle (no --unit) advances a run " +
-            "parked on a route-only/empty step. Refused while a live engine lease exists",
-    },
-    args: {
-        target: {
-            type: "positional",
-            description: "Workflow run id (or a workflow ref with an active run)",
-            required: true,
-        },
-        unit: {
-            type: "string",
-            description: "Content-derived unit id from `akm workflow brief` (copy it verbatim). Omit with --settle.",
-        },
-        settle: {
-            type: "boolean",
-            description: "Advance/finalize a run whose active step has NO unit left to report: a non-dispatching step (params-based route, empty fan-out, all-unresolvable) OR a fully-terminal step still needing finalization (every unit ran but the gate never judged — e.g. after resuming a required-gate block). Runs the deterministic completion path. Mutually exclusive with --unit; refused when the step still has genuinely pending units",
-            default: false,
-        },
-        "expect-step": {
-            type: "string",
-            description: "Guard: the step id you briefed against. Refuses the report if the run's active step has since moved (from the `brief` report/settle command line)",
-        },
-        status: { type: "string", description: `Unit status: ${WORKFLOW_REPORT_STATES.join(", ")}` },
-        result: { type: "string", description: "Result payload (JSON for a schema unit, else text). completed only." },
-        "result-file": { type: "string", description: "Read the result payload from this file instead of --result/stdin" },
-        tokens: { type: "string", description: "Tokens spent on this unit (counts against a declared budget)" },
-        "session-id": { type: "string", description: "Harness-native session id revealed while executing the unit" },
-        "failure-reason": { type: "string", description: "Structured failure vocabulary for a --status failed report" },
-        note: { type: "string", description: "Short progress note for a --status running heartbeat (not persisted)" },
-        rerun: {
-            type: "boolean",
-            description: "Re-run an already-FAILED unit: record a NEW attempt (re-applies budget) instead of refusing a differing re-report",
-            default: false,
-        },
-    },
-    async run({ args }) {
-        // --settle: the unit-less verb that advances a run parked on a
-        // non-dispatching step. Mutually exclusive with the per-unit report flags.
-        if (args.settle === true) {
-            if (getStringArg(args, "unit") !== undefined || getStringArg(args, "status") !== undefined) {
-                throw new UsageError("--settle advances a route-only/empty step and takes no --unit or --status. Drop them, or report a " +
-                    "specific unit with `--unit <id> --status <state>` instead.", "INVALID_FLAG_VALUE");
+const WORKFLOW_RUN_VALUE_FLAGS = new Set([
+    "max-steps",
+    "maxSteps",
+    "max-retries",
+    "maxRetries",
+    "timeout",
+    "format",
+    "detail",
+    "shape",
+    "output",
+]);
+const WORKFLOW_RUN_BOOLEAN_FLAGS = new Set(["quiet", "verbose", "help", "no-quiet", "no-verbose"]);
+export function parseWorkflowParameterFlags(rawArgs, target) {
+    const flags = [];
+    let targetSeen = false;
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const token = rawArgs[index];
+        if (token === "--") {
+            throw new UsageError("`akm workflow run` does not accept positional arguments after `--`.", "INVALID_FLAG_VALUE");
+        }
+        if (!token.startsWith("-") || token === "-" || /^-\d/.test(token)) {
+            if (!targetSeen) {
+                if (token !== target) {
+                    throw new UsageError("Workflow parameter flags must come after the workflow ref or run id.", "INVALID_FLAG_VALUE");
+                }
+                targetSeen = true;
+                continue;
             }
-            const { settleWorkflowSpine } = await import("../workflows/exec/report.js");
-            const result = await settleWorkflowSpine({
-                target: args.target,
-                ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
-            });
-            output("workflow-report", result);
-            return;
+            throw new UsageError(`Unexpected positional workflow argument "${token}".`, "INVALID_FLAG_VALUE");
         }
-        const status = args.status;
-        if (!status) {
-            throw new UsageError("--status is required (completed | failed | running), or pass --settle to advance a non-dispatching step.", "MISSING_REQUIRED_ARGUMENT");
+        if (!token.startsWith("--"))
+            continue;
+        const body = token.slice(2);
+        const equalsAt = body.indexOf("=");
+        const name = equalsAt === -1 ? body : body.slice(0, equalsAt);
+        const inlineValue = equalsAt === -1 ? undefined : body.slice(equalsAt + 1);
+        if (name === "params") {
+            throw new UsageError("--params was removed. Pass each declared workflow parameter as its own flag, for example `--version=1.2.3`.", "INVALID_FLAG_VALUE");
         }
-        if (!WORKFLOW_REPORT_STATES.includes(status)) {
-            throw new UsageError(`Invalid --status "${status}". Expected one of: ${WORKFLOW_REPORT_STATES.join(", ")}.`, "INVALID_FLAG_VALUE");
+        if (WORKFLOW_RUN_VALUE_FLAGS.has(name)) {
+            if (inlineValue === undefined)
+                index += 1;
+            continue;
         }
-        const unitId = getStringArg(args, "unit");
-        if (!unitId) {
-            throw new UsageError("--unit is required (the content-derived unit id from `akm workflow brief`), or pass --settle for a route-only/empty step.", "MISSING_REQUIRED_ARGUMENT");
+        if (WORKFLOW_RUN_BOOLEAN_FLAGS.has(name))
+            continue;
+        if (!targetSeen) {
+            throw new UsageError("Workflow parameter flags must come after the workflow ref or run id.", "INVALID_FLAG_VALUE");
         }
-        let tokens;
-        const rawTokens = getStringArg(args, "tokens");
-        if (rawTokens !== undefined) {
-            tokens = Number.parseInt(rawTokens, 10);
-            if (!/^\d+$/.test(rawTokens)) {
-                throw new UsageError(`--tokens must be a non-negative integer, got "${rawTokens}".`, "INVALID_FLAG_VALUE");
-            }
+        if (inlineValue !== undefined) {
+            flags.push({ name, value: inlineValue });
+            continue;
         }
-        // Result payload precedence: --result, then --result-file, then stdin
-        // (completed/failed only; a running heartbeat carries no result).
-        let resultRaw;
-        if (status !== "running") {
-            const resultFile = getStringArg(args, "result-file");
-            if (args.result !== undefined && resultFile !== undefined) {
-                throw new UsageError("Pass at most one of --result or --result-file.", "INVALID_FLAG_VALUE");
-            }
-            if (args.result !== undefined) {
-                resultRaw = String(args.result);
-            }
-            else if (resultFile !== undefined) {
-                const fs = await import("node:fs");
-                resultRaw = fs.readFileSync(resultFile, "utf8");
-            }
-            else if (!process.stdin.isTTY) {
-                resultRaw = await readStdin();
-            }
+        const next = rawArgs[index + 1];
+        if (next !== undefined && (!next.startsWith("-") || /^-\d/.test(next))) {
+            flags.push({ name, value: next });
+            index += 1;
         }
-        const { reportWorkflowUnit } = await import("../workflows/exec/report.js");
-        const result = await reportWorkflowUnit({
-            target: args.target,
-            unitId,
-            status: status,
-            ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
-            ...(resultRaw !== undefined ? { resultRaw } : {}),
-            ...(tokens !== undefined ? { tokens } : {}),
-            ...(args.rerun === true ? { rerun: true } : {}),
-            ...(getStringArg(args, "session-id") !== undefined ? { sessionId: getStringArg(args, "session-id") } : {}),
-            ...(getStringArg(args, "failure-reason") !== undefined
-                ? { failureReason: getStringArg(args, "failure-reason") }
-                : {}),
-            ...(getStringArg(args, "note") !== undefined ? { note: getStringArg(args, "note") } : {}),
-        });
-        output("workflow-report", result);
-    },
-});
-async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(chunk);
-    return Buffer.concat(chunks).toString("utf8");
-}
-const workflowWatchCommand = defineJsonCommand({
-    meta: {
-        name: "watch",
-        description: "Print a run's workflow_* events (state.db events table) as NDJSON and exit; --stream polls in the " +
-            "foreground until the run reaches a terminal status (no daemon)",
-    },
-    args: {
-        runId: { type: "positional", description: "Workflow run id", required: true },
-        stream: {
-            type: "boolean",
-            description: "Keep polling for new events until the run leaves 'active' (completed/failed/blocked)",
-            default: false,
-        },
-        "interval-ms": { type: "string", description: "Poll interval in milliseconds for --stream (default: 1000)" },
-    },
-    async run({ args }) {
-        const rawInterval = getStringArg(args, "interval-ms");
-        let intervalMs;
-        if (rawInterval !== undefined) {
-            intervalMs = Number.parseInt(rawInterval, 10);
-            if (!/^\d+$/.test(rawInterval) || intervalMs <= 0) {
-                throw new UsageError(`--interval-ms must be a positive integer, got "${rawInterval}".`, "INVALID_FLAG_VALUE");
-            }
+        else {
+            flags.push({ name, value: true });
         }
-        const { watchWorkflowRun } = await import("../workflows/exec/watch.js");
-        const result = await watchWorkflowRun({
-            runId: args.runId,
-            stream: args.stream === true,
-            ...(intervalMs !== undefined ? { intervalMs } : {}),
-        });
-        // The event lines above are raw NDJSON on stdout; this trailing envelope
-        // is the machine-readable command result (counts + terminal status).
-        output("workflow-watch", { ok: true, ...result });
-    },
-});
+    }
+    return flags;
+}
+function parseIntegerFlag(raw, name, minimum, maximum) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    if (!/^\d+$/.test(raw) || value < minimum || (maximum !== undefined && value > maximum)) {
+        const range = maximum === undefined ? `at least ${minimum}` : `from ${minimum} through ${maximum}`;
+        throw new UsageError(`${name} must be an integer ${range}, got "${raw}".`, "INVALID_FLAG_VALUE");
+    }
+    return value;
+}
+function parseWorkflowTimeout(raw) {
+    if (raw === undefined)
+        return undefined;
+    const match = /^(\d+)(ms|s|m)?$/.exec(raw);
+    if (!match) {
+        throw new UsageError(`--timeout must be N, Nms, Ns, or Nm, got "${raw}".`, "INVALID_FLAG_VALUE");
+    }
+    const amount = Number(match[1]);
+    const multiplier = match[2] === "m" ? 60_000 : match[2] === "s" ? 1_000 : 1;
+    const timeoutMs = amount * multiplier;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > WORKFLOW_MAX_TIMEOUT_MS) {
+        throw new UsageError(`--timeout must resolve to 1 through ${WORKFLOW_MAX_TIMEOUT_MS} milliseconds, got "${raw}".`, "INVALID_FLAG_VALUE");
+    }
+    return timeoutMs;
+}
 const workflowAbandonCommand = defineJsonCommand({
     meta: {
         name: "abandon",
@@ -572,32 +306,23 @@ const workflowResumeCommand = defineJsonCommand({
         output("workflow-resume", result);
     },
 });
-export const workflowCommand = defineCommand({
+export const workflowCommand = defineGroupCommand({
     meta: {
         name: "workflow",
         description: "Author, inspect, and execute step-by-step workflow assets",
     },
     subCommands: {
-        start: workflowStartCommand,
-        next: workflowNextCommand,
-        complete: workflowCompleteCommand,
         status: workflowStatusCommand,
         list: workflowListCommand,
         create: workflowCreateCommand,
-        template: workflowTemplateCommand,
         resume: workflowResumeCommand,
         abandon: workflowAbandonCommand,
-        validate: workflowValidateCommand,
         run: workflowRunCommand,
-        brief: workflowBriefCommand,
-        report: workflowReportCommand,
-        watch: workflowWatchCommand,
-    },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasWorkflowSubcommand(args))
-                return;
-            output("workflow-list", await listWorkflowRuns({ activeOnly: true }));
-        });
     },
+    // No `defaultRun`: bare `akm workflow` is a usage error (exit 2), the
+    // canonical bare-group behavior — owner ruling 12. Run `akm workflow list
+    // --active` for what the bare form used to print. This group was previously
+    // hand-rolled on `defineCommand` with its own `hasWorkflowSubcommand` guard,
+    // which duplicated the subcommand names in a second hand-maintained set;
+    // `defineGroupCommand` derives the guard from `subCommands` directly.
 });