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

package/dist/commands/sources/self-update.js

@@ -5,7 +5,7 @@ import * as childProcess from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, IS_WINDOWS, ResponseTooLargeError, readBodyWithByteCap } from "../../core/common.js";
+import { fetchWithRetry, IS_WINDOWS, ResponseTooLargeError, readBodyWithByteCap, readChunkWithDeadline, } from "../../core/common.js";
 import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { githubHeaders } from "../../integrations/github.js";
@@ -29,7 +29,19 @@ export function defaultMigrationCommand(preparedConfigPath) {
         apply: (akmBin) => runRequiredCommand(akmBin, ["migrate", "apply", ...configArgs], "Migration apply"),
     };
 }
-async function streamResponseToFile(response, destination, maxBytes) {
+/**
+ * Bounds on the binary body read. `fetchWithTimeout`'s timer only covers
+ * time-to-HEADERS — it is cleared the moment `fetch` resolves — so without
+ * these a compromised or misconfigured endpoint could dribble bytes forever
+ * and hang `akm upgrade` with no output and no way out but Ctrl-C. Two
+ * bounds, because either alone is evadable: a per-chunk STALL deadline (a
+ * connection making no progress dies quickly, while a slow-but-progressing
+ * one is left alone) and an OVERALL deadline (a trickle that sends one byte
+ * per stall-window can't stretch the download indefinitely).
+ */
+const BINARY_STALL_TIMEOUT_MS = 60_000;
+const BINARY_TOTAL_TIMEOUT_MS = 30 * 60_000;
+export async function streamResponseToFile(response, destination, maxBytes, limits) {
     const declaredText = response.headers.get("content-length");
     if (declaredText) {
         const declared = Number(declaredText);
@@ -40,22 +52,30 @@ async function streamResponseToFile(response, destination, maxBytes) {
     }
     if (!response.body)
         throw new Error("Binary download response did not provide a streaming body.");
+    const url = response.url || "binary download";
+    const stallTimeoutMs = limits?.stallTimeoutMs ?? BINARY_STALL_TIMEOUT_MS;
+    const totalTimeoutMs = limits?.totalTimeoutMs ?? BINARY_TOTAL_TIMEOUT_MS;
+    const overallDeadlineAt = Date.now() + totalTimeoutMs;
     const fd = fs.openSync(destination, "w", 0o600);
     const reader = response.body.getReader();
     const hash = createHash("sha256");
     let byteSize = 0;
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            // Whichever bound bites first wins, and the error reports THAT bound —
+            // "no data for 60s" and "download exceeded 30m" are different diagnoses.
+            const stallDeadlineAt = Date.now() + stallTimeoutMs;
+            const deadlineAt = Math.min(stallDeadlineAt, overallDeadlineAt);
+            const reportedTimeoutMs = deadlineAt === overallDeadlineAt ? totalTimeoutMs : stallTimeoutMs;
+            const { done, value } = await readChunkWithDeadline(reader, deadlineAt, undefined, url, reportedTimeoutMs);
             if (done)
                 break;
             if (!value)
                 continue;
             byteSize += value.byteLength;
-            if (byteSize > maxBytes) {
-                await reader.cancel().catch(() => undefined);
-                throw new ResponseTooLargeError(response.url || "binary download", maxBytes, byteSize);
-            }
+            // The catch block cancels the reader for every throw path, this included.
+            if (byteSize > maxBytes)
+                throw new ResponseTooLargeError(url, maxBytes, byteSize);
             hash.update(value);
             let written = 0;
             while (written < value.byteLength)
@@ -65,6 +85,9 @@ async function streamResponseToFile(response, destination, maxBytes) {
         return { byteSize, sha256: hash.digest("hex") };
     }
     catch (error) {
+        // Cancel so a timed-out (still-open) connection releases its socket rather
+        // than lingering until process exit. Already-cancelled readers no-op.
+        await reader.cancel().catch(() => undefined);
         removeFileBestEffort(destination);
         throw error;
     }

package/dist/commands/sources/source-add.js

@@ -14,6 +14,7 @@ import { readLockfile, removeLockEntry, upsertLockEntry } from "../../integratio
 import { parseRegistryRef } from "../../registry/resolve.js";
 import { detectStashRoot } from "../../sources/providers/provider-utils.js";
 import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
+import { storeSecretResolver } from "../../sources/snapshot-fetchers/secret-seam.js";
 import { ensureWebsiteMirror, shouldAllowPrivateWebsiteUrlForTests, validateWebsiteInputUrl, } from "../../sources/snapshot-fetchers/website-ingest.js";
 import { bundleKeyForPath, bundleKeyForUrl, nextBundleKey } from "./bundle-config-ops.js";
 export async function akmAdd(input) {
@@ -95,13 +96,26 @@ async function addLocalSource(ref, sourcePath, stashDir, explicitName) {
 async function addWebsiteSource(ref, stashDir, name, options) {
     const allowPrivateHosts = shouldAllowPrivateWebsiteUrlForTests(ref);
     const normalizedUrl = validateWebsiteInputUrl(ref, { allowPrivateHosts });
-    const maxPages = typeof options?.maxPages === "number" ? options.maxPages : undefined;
+    const numberOption = (value) => (typeof value === "number" ? value : undefined);
+    const maxPages = numberOption(options?.maxPages);
+    const maxDepth = numberOption(options?.maxDepth);
     let entry;
     mutateConfig((config) => {
         const bundles = { ...(config.bundles ?? {}) };
         const existingKey = bundleKeyForUrl(config, normalizedUrl);
         const key = existingKey ?? nextBundleKey(bundles, name ?? toWebsiteName(normalizedUrl), normalizedUrl);
-        const website = { url: normalizedUrl, ...(maxPages !== undefined ? { maxPages } : {}) };
+        // Merge onto the existing descriptor rather than replacing it: re-running
+        // `bundle add` for a URL that already has a bundle would otherwise drop
+        // respectRobots / refresh, silently restoring default robots enforcement
+        // and changing what the next update fetches. Explicitly-passed maxPages /
+        // maxDepth still win over the stored values.
+        const existingWebsite = existingKey ? (bundles[key]?.website ?? {}) : {};
+        const website = {
+            ...existingWebsite,
+            url: normalizedUrl,
+            ...(maxPages !== undefined ? { maxPages } : {}),
+            ...(maxDepth !== undefined ? { maxDepth } : {}),
+        };
         const nextBundle = {
             ...(existingKey ? bundles[key] : {}),
             website,
@@ -117,6 +131,7 @@ async function addWebsiteSource(ref, stashDir, name, options) {
     });
     const cachePaths = await ensureWebsiteMirror(entry, {
         requireStashDir: true,
+        resolveSecret: storeSecretResolver.resolveSecret,
         ...(allowPrivateHosts ? { allowPrivateHosts: true } : {}),
     });
     const index = await akmIndex({ stashDir });

package/dist/commands/tasks/tasks.js

@@ -19,6 +19,7 @@ import { IMPROVE_AUTONOMY_CONFIG_KEY, isImproveAutonomyEnabled } from "../../cor
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
 import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
 import { parseTaskDocument } from "../../tasks/parser.js";
 import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
@@ -27,7 +28,6 @@ import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/sched
 import { schedulerContextDescriptor, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
 import { normaliseTaskId } from "../../tasks/task-id.js";
 import { validateTaskDocument } from "../../tasks/validator.js";
-import { isWorkflowEngineEnabled, WORKFLOW_ENGINE_CONFIG_KEY } from "../../workflows/exec/workflow-engine-gate.js";
 import { applyAutonomyGate, configuredDirectAutonomyLanes, describeGatedLanes } from "../improve/autonomy-gate.js";
 import { resolveImproveStrategy } from "../improve/improve-strategies.js";
 export async function akmTasksAdd(input, deps = {}) {
@@ -60,7 +60,12 @@ export async function akmTasksAdd(input, deps = {}) {
     if (!isWithin(assetPath, typeRoot)) {
         throw new UsageError(`Resolved task path escapes the stash: "${id}".`, "PATH_ESCAPE_VIOLATION");
     }
-    if (fs.existsSync(assetPath) && !input.force) {
+    // Pre-0.8.0 tasks were markdown; the 0.8.0 cutover moved them to pure YAML
+    // (see the tasks dir rule in src/indexer/walk/matchers.ts). A leftover
+    // `<id>.md` still names the same task, so creating `<id>.yml` beside it
+    // must collide loudly rather than silently minting a duplicate.
+    const legacyAssetPath = path.join(typeRoot, `${id}.md`);
+    if ((fs.existsSync(assetPath) || fs.existsSync(legacyAssetPath)) && !input.force) {
         throw new UsageError(`Task "${id}" already exists. Pass --force to overwrite, or delete its file and run \`akm task sync\` first.`, "RESOURCE_ALREADY_EXISTS");
     }
     const yaml = renderTaskYaml({
@@ -387,7 +392,9 @@ export async function akmTasksDoctor(deps = {}) {
         }
     }
     const bindings = groupInstalledBindings(installed, invocation);
-    const config = loadConfig();
+    // Report the EFFECTIVE engine view — the same one the runner resolves —
+    // so doctor never says "no engine" on an install where tasks actually run.
+    const { config } = withEngineFallback(loadConfig());
     const defaultEngine = config.defaults?.engine;
     const engines = Object.keys(config.engines ?? {});
     // §6.1: surface the effective triage settings for the default improve
@@ -408,12 +415,6 @@ export async function akmTasksDoctor(deps = {}) {
         configKey: IMPROVE_AUTONOMY_CONFIG_KEY,
         gatedLanes: allGated.map((entry) => ({ lane: entry.lane, reason: entry.reason })),
     };
-    // Q-05 — report the workflow engine gate's state alongside the autonomy
-    // gate: both are `experimental.*` opt-ins doctor exists to surface.
-    const workflowEngine = {
-        enabled: isWorkflowEngineEnabled(config),
-        configKey: WORKFLOW_ENGINE_CONFIG_KEY,
-    };
     const triage = effectiveStrategy.processes?.triage;
     const improveTriage = triage
         ? {
@@ -437,7 +438,6 @@ export async function akmTasksDoctor(deps = {}) {
         scheduleSubset: SCHEDULE_SUPPORTED_SUBSET_HINT,
         warnings,
         improveAutonomy,
-        workflowEngine,
         ...(improveTriage ? { improveTriage } : {}),
     };
 }

package/dist/commands/workflow-cli.js

@@ -2,111 +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.
- *
- * 0.9.0 CLI overhaul (S5): `workflow template` is dropped — `workflow create
- * --print` prints the same content without writing. `workflow validate` is
- * dropped — `akm lint --type workflows` covers structural validation.
- * `workflow watch` is dropped — poll `akm log --since '@offset:<id>' --run
- * <run-id>` instead. Workflows are markdown-only (workflow-format-
- * unification) — `workflow create <name>.yaml` is a usage error.
+ * `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 { getParsedInvocation } from "../cli/invocation.js";
 import { getStringArg } from "../cli/parse-args.js";
-import { defineGroupCommand, defineJsonCommand, output } 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 { loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
-import { parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES } from "../workflows/cli.js";
-import { requireWorkflowEngineEnabled } from "../workflows/exec/workflow-engine-gate.js";
-import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.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",
-            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;
-        const result = await getNextWorkflowStep(args.target, parsedParams);
-        output("workflow-next", result);
-    },
-});
-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 { 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",
@@ -219,7 +127,7 @@ 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 });
@@ -229,177 +137,148 @@ const workflowCreateCommand = defineJsonCommand({
 const workflowRunCommand = defineJsonCommand({
     meta: {
         name: "run",
-        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: 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" },
+        "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 }) {
-        requireWorkflowEngineEnabled(loadConfig(), "run");
+    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 } : {}),
-        });
-        output("workflow-run", result);
-    },
-});
-const workflowBriefCommand = defineJsonCommand({
-    meta: {
-        name: "brief",
-        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: 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 }) {
-        requireWorkflowEngineEnabled(loadConfig(), "brief");
-        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, gated behind `experimental.workflowEngine`: 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 }) {
-        requireWorkflowEngineEnabled(loadConfig(), "report");
-        // --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");
+        else {
+            flags.push({ name, value: true });
+        }
+    }
+    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: {
@@ -433,17 +312,12 @@ export const workflowCommand = defineGroupCommand({
         description: "Author, inspect, and execute step-by-step workflow assets",
     },
     subCommands: {
-        start: workflowStartCommand,
-        next: workflowNextCommand,
-        complete: workflowCompleteCommand,
         status: workflowStatusCommand,
         list: workflowListCommand,
         create: workflowCreateCommand,
         resume: workflowResumeCommand,
         abandon: workflowAbandonCommand,
         run: workflowRunCommand,
-        brief: workflowBriefCommand,
-        report: workflowReportCommand,
     },
     // No `defaultRun`: bare `akm workflow` is a usage error (exit 2), the
     // canonical bare-group behavior — owner ruling 12. Run `akm workflow list