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

package/dist/commands/tasks/tasks.js

@@ -17,7 +17,6 @@ import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
 import { commitWriteTargetBoundary, deleteAssetFromSource, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
-import { listAgentProfileNames } from "../../integrations/agent/index.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
 import { parseTaskDocument } from "../../tasks/parser.js";
@@ -25,7 +24,7 @@ import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
 import { exitCodeForStatus, readTaskHistory, runTask } from "../../tasks/runner.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../../tasks/schedule.js";
 import { validateTaskDocument } from "../../tasks/validator.js";
-import { resolveImproveProfile } from "../improve/improve-profiles.js";
+import { resolveImproveStrategy } from "../improve/improve-strategies.js";
 export async function akmTasksAdd(input) {
     const id = normaliseTaskId(input.id);
     const hasCommand = input.command !== undefined &&
@@ -36,6 +35,12 @@ export async function akmTasksAdd(input) {
     if (targetCount !== 1) {
         throw new UsageError("Pass exactly one of --workflow <ref>, --prompt <asset-ref|./file.md|text>, or --command <shell-command>.", "INVALID_FLAG_VALUE");
     }
+    if (input.workflow && (input.engine !== undefined || input.model !== undefined || input.timeoutMs !== undefined)) {
+        throw new UsageError("Workflow tasks accept only --params; engine, model, and timeout are prompt-task fields.", "INVALID_FLAG_VALUE");
+    }
+    if (hasCommand && (input.engine !== undefined || input.model !== undefined)) {
+        throw new UsageError("Command tasks accept --timeout-ms but not --engine or --model.", "INVALID_FLAG_VALUE");
+    }
     // Validate the schedule for the active backend before writing anything.
     const backend = backendNameForPlatform();
     parseSchedule(input.schedule, backend);
@@ -56,7 +61,9 @@ export async function akmTasksAdd(input) {
         workflow: input.workflow,
         prompt: input.prompt,
         command: input.command,
-        profile: input.profile,
+        engine: input.engine,
+        model: input.model,
+        timeoutMs: input.timeoutMs,
         params: input.params,
         name: input.name,
         description: input.description,
@@ -137,11 +144,12 @@ export async function akmTasksList() {
     const stashDir = resolveStashDir();
     const typeRoot = path.join(stashDir, "tasks");
     if (!fs.existsSync(typeRoot))
-        return { tasks: [] };
+        return { tasks: [], stale: [] };
     const entries = fs.readdirSync(typeRoot);
     warnLegacyMdTaskFiles(typeRoot);
     const files = entries.filter((f) => f.endsWith(".yml"));
     const tasks = [];
+    const stale = [];
     for (const file of files) {
         const id = file.slice(0, -4);
         const filePath = path.join(typeRoot, file);
@@ -149,7 +157,9 @@ export async function akmTasksList() {
         try {
             task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
         }
-        catch {
+        catch (err) {
+            if (isStaleTaskError(err))
+                stale.push(id);
             continue; // skip malformed files; `akm tasks show <id>` will surface the error
         }
         tasks.push({
@@ -165,7 +175,9 @@ export async function akmTasksList() {
             tags: task.tags,
         });
     }
-    return { tasks };
+    if (stale.length > 0)
+        warnStaleTaskFiles(stale);
+    return { tasks, stale };
 }
 export async function akmTasksShow(id) {
     const normalised = normaliseTaskId(id);
@@ -234,6 +246,9 @@ export async function akmTasksSetEnabled(id, enabled) {
         warnLegacyMdTaskFiles(typeRoot);
     const filePath = await resolveAssetPath(stashDir, "task", normalised);
     const yaml = fs.readFileSync(filePath, "utf8");
+    // Parse before writing so stale v1 tasks are diagnosed without changing the
+    // source file or its installed scheduler entry.
+    parseTaskDocument({ yaml, filePath, id: normalised });
     const updated = setEnabledInYaml(yaml, enabled);
     const ref = taskAssetRef(normalised);
     await writeAssetToSource(target.source, target.config, ref, updated);
@@ -374,16 +389,15 @@ export async function akmTasksDoctor() {
     }
     const backend = backendNameForPlatform();
     const config = loadConfig();
-    // v2: prefer profiles.agent / defaults.agent; fall back to legacy agent.default
-    const defaultProfile = config.defaults?.agent;
-    const profiles = config.profiles?.agent ? Object.keys(config.profiles.agent) : listAgentProfileNames(config);
+    const defaultEngine = config.defaults?.engine;
+    const engines = Object.keys(config.engines ?? {});
     // §6.1: surface the effective triage settings for the default improve
-    // profile. The struct is a fixed shape, so this is a deliberate addition.
-    const improveProfileName = typeof config.defaults?.improve === "string" ? config.defaults.improve : "default";
-    const triage = resolveImproveProfile(config.defaults?.improve, config).processes?.triage;
+    // strategy. The struct is a fixed shape, so this is a deliberate addition.
+    const improveStrategyName = typeof config.defaults?.improveStrategy === "string" ? config.defaults.improveStrategy : "default";
+    const triage = resolveImproveStrategy(config.defaults?.improveStrategy, config).config.processes?.triage;
     const improveTriage = triage
         ? {
-            defaultProfile: improveProfileName,
+            defaultStrategy: improveStrategyName,
             enabled: triage.enabled === true,
             applyMode: triage.applyMode ?? "queue",
             policy: triage.policy ?? "personal-stash",
@@ -394,7 +408,9 @@ export async function akmTasksDoctor() {
         akm: invocation,
         logDir: getTaskLogDir(),
         historyDir: getTaskHistoryDir(),
-        agent: { defaultProfile, available: profiles },
+        engine: { defaultEngine, available: engines },
+        stale: collectStaleTaskIds(),
+        staleGeneratedCommands: collectStaleGeneratedCommands(),
         scheduleSubset: SCHEDULE_SUPPORTED_SUBSET_HINT,
         warnings,
         ...(improveTriage ? { improveTriage } : {}),
@@ -421,7 +437,7 @@ function resolveTaskWriteTarget() {
     return resolveWriteTarget(loadConfig());
 }
 function renderTaskYaml(input) {
-    const obj = { schedule: input.schedule };
+    const obj = { version: 2, schedule: input.schedule, enabled: input.enabled };
     if (input.workflow) {
         obj.workflow = input.workflow;
         if (input.params) {
@@ -430,16 +446,21 @@ function renderTaskYaml(input) {
     }
     else if (input.prompt) {
         obj.prompt = input.prompt;
-        if (input.profile)
-            obj.profile = input.profile;
+        if (input.engine)
+            obj.engine = input.engine;
+        if (input.model)
+            obj.model = input.model;
+        if (input.timeoutMs !== undefined)
+            obj.timeoutMs = input.timeoutMs;
     }
     else if (input.command !== undefined) {
         // Emit a string when given a string, an array when given an array. The
         // parser accepts both forms; preserving the caller's shape keeps the YAML
         // ergonomic for humans editing the file later.
         obj.command = input.command;
+        if (input.timeoutMs !== undefined)
+            obj.timeoutMs = input.timeoutMs;
     }
-    obj.enabled = input.enabled;
     if (input.name)
         obj.name = input.name;
     if (input.description)
@@ -450,6 +471,80 @@ function renderTaskYaml(input) {
         obj.tags = input.tags;
     return yamlStringify(obj);
 }
+function isStaleTaskError(err) {
+    return err instanceof UsageError && err.code === "TASK_SCHEMA_VERSION_UNSUPPORTED";
+}
+function warnStaleTaskFiles(ids) {
+    process.stderr.write(`WARNING: ${ids.length} task file(s) use retired task schema v1 and were not loaded.\n` +
+        `         Rewrite them with version: 2 and replace profile with engine. See docs/migration/v0.8-to-v0.9.md#task-assets.\n` +
+        `         Affected: ${ids.map((id) => `tasks/${id}.yml`).join(", ")}\n`);
+}
+function collectStaleTaskIds() {
+    const typeRoot = path.join(resolveStashDir(), "tasks");
+    if (!fs.existsSync(typeRoot))
+        return [];
+    const stale = [];
+    for (const file of fs.readdirSync(typeRoot)) {
+        if (!file.endsWith(".yml"))
+            continue;
+        const id = file.slice(0, -4);
+        try {
+            parseTaskDocument({
+                yaml: fs.readFileSync(path.join(typeRoot, file), "utf8"),
+                filePath: path.join(typeRoot, file),
+                id,
+            });
+        }
+        catch (err) {
+            if (isStaleTaskError(err))
+                stale.push(id);
+        }
+    }
+    return stale;
+}
+const STALE_GENERATED_COMMANDS = {
+    "akm-improve-frequent": {
+        command: "akm improve --profile frequent --auto-accept safe",
+        replacement: "akm improve --strategy frequent --auto-accept safe",
+    },
+    "akm-improve-consolidate": {
+        command: "akm improve --profile consolidate --auto-accept safe",
+        replacement: "akm improve --strategy consolidate --auto-accept safe",
+    },
+    "akm-improve-nightly": {
+        command: "akm improve --profile thorough --auto-accept safe",
+        replacement: "akm improve --strategy thorough --auto-accept safe",
+    },
+    "akm-improve-catchup": {
+        command: "akm improve --profile catchup --auto-accept safe",
+        replacement: "akm improve --strategy catchup --auto-accept safe",
+    },
+    "akm-graph-refresh-weekly": {
+        command: "akm improve --profile graph-refresh --auto-accept safe",
+        replacement: "akm improve --strategy graph-refresh --auto-accept safe",
+    },
+};
+function collectStaleGeneratedCommands() {
+    const typeRoot = path.join(resolveStashDir(), "tasks");
+    if (!fs.existsSync(typeRoot))
+        return [];
+    const stale = [];
+    for (const [id, expected] of Object.entries(STALE_GENERATED_COMMANDS)) {
+        const filePath = path.join(typeRoot, `${id}.yml`);
+        if (!fs.existsSync(filePath))
+            continue;
+        try {
+            const task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
+            if (task.target.kind === "command" && task.target.cmd.join(" ") === expected.command) {
+                stale.push({ id, replacement: expected.replacement });
+            }
+        }
+        catch {
+            // Stale-schema reporting owns files that cannot be parsed.
+        }
+    }
+    return stale;
+}
 function parseJsonObjectArg(raw) {
     let parsed;
     try {

package/dist/commands/wiki-cli.js

@@ -220,13 +220,13 @@ const wikiLintCommand = defineCommand({
 const wikiIngestCommand = defineJsonCommand({
     meta: {
         name: "ingest",
-        description: "Dispatch an agent to execute the ingest workflow for this wiki. Uses --profile or config.defaults.agent.",
+        description: "Dispatch an agent to execute the ingest workflow for this wiki. Uses --engine or config.defaults.engine.",
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
-        profile: {
+        engine: {
             type: "string",
-            description: "Agent profile to use (default: config.defaults.agent).",
+            description: "Agent engine to use (default: config.defaults.engine).",
         },
         model: {
             type: "string",
@@ -239,17 +239,15 @@ const wikiIngestCommand = defineJsonCommand({
         const stashDir = resolveStashDir();
         const built = buildIngestWorkflow(stashDir, args.name);
         const config = loadConfig();
-        const profileName = getStringArg(args, "profile") ?? config.defaults?.agent;
-        if (!profileName) {
-            throw new UsageError("akm wiki ingest requires an agent profile. Pass --profile <name> or set defaults.agent in config.", "MISSING_REQUIRED_ARGUMENT", "Available profiles are listed under profiles.agent in your config. Run `akm config get profiles.agent` to inspect.");
+        const engine = getStringArg(args, "engine") ?? config.defaults?.engine;
+        if (!engine) {
+            throw new UsageError("akm wiki ingest requires an agent engine. Pass --engine <name> or set defaults.engine in config.", "MISSING_REQUIRED_ARGUMENT", "Available engines are listed under engines in your config. Run `akm config get engines` to inspect.");
         }
         const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
         const model = getStringArg(args, "model");
-        const { getDefaultLlmConfig } = await import("../core/config/config.js");
         const dispatchResult = await akmAgentDispatch({
-            profileName,
+            engine,
             agentConfig: config,
-            llmConfig: getDefaultLlmConfig(config),
             prompt: built.workflow,
             dispatch: {
                 prompt: built.workflow,
@@ -258,11 +256,12 @@ const wikiIngestCommand = defineJsonCommand({
             ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
         });
         output("wiki-ingest", {
+            schemaVersion: 2,
             wiki: built.wiki,
             path: built.path,
             schemaPath: built.schemaPath,
             dispatched: true,
-            profile: profileName,
+            engine,
             agentResult: dispatchResult,
         });
     },

package/dist/commands/workflow-cli.js

@@ -12,6 +12,7 @@
  * `looksLikeWorkflowRunId` and `resolveWorkflowFilePath` move with the family.
  */
 import { defineCommand } from "citty";
+import { getStringArg } from "../cli/parse-args.js";
 import { defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { parseAssetRef } from "../core/asset/asset-ref.js";
@@ -22,8 +23,9 @@ import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { hasBooleanFlag } from "../output/context.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { resolveAssetPath } from "../sources/resolve.js";
-import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "../workflows/authoring/authoring.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";
 const workflowStartCommand = defineJsonCommand({
     meta: {
@@ -140,9 +142,16 @@ const workflowStatusCommand = defineJsonCommand({
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref (workflow:<name>)", required: true },
+        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).",
+            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 {
@@ -161,11 +170,11 @@ const workflowStatusCommand = defineJsonCommand({
             const mostRecent = runs[0];
             if (!mostRecent)
                 throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            const result = await getWorkflowStatus(mostRecent.id);
+            const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
             output("workflow-status", result);
         }
         else {
-            const result = await getWorkflowStatus(target);
+            const result = await getWorkflowStatus(target, { includeUnits });
             output("workflow-status", result);
         }
     },
@@ -187,19 +196,22 @@ const workflowListCommand = defineJsonCommand({
 const workflowCreateCommand = defineJsonCommand({
     meta: {
         name: "create",
-        description: "Create a workflow markdown document in the working stash",
+        description: "Create a workflow in the working stash (markdown document by default; a .yaml/.yml name writes a YAML program)",
     },
     args: {
         name: {
             type: "positional",
-            description: "Workflow name (flat, no '/'; use --path for a subdirectory)",
+            description: "Workflow name (flat, no '/'; use --path for a subdirectory). A .yaml/.yml suffix creates a YAML program.",
             required: true,
         },
         path: {
             type: "string",
             description: "Relative subdirectory under workflows/ to place the workflow in (e.g. 'release'). The filename comes from the name.",
         },
-        from: { type: "string", description: "Import and validate markdown from an existing file" },
+        from: {
+            type: "string",
+            description: "Import and validate content from an existing file (parsed per the destination extension)",
+        },
         force: {
             type: "boolean",
             description: "Overwrite an existing workflow (requires --from or --reset)",
@@ -237,26 +249,54 @@ const workflowCreateCommand = defineJsonCommand({
 const workflowTemplateCommand = defineCommand({
     meta: {
         name: "template",
-        description: "Print a valid workflow markdown 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() {
-        process.stdout.write(getWorkflowTemplate());
+    run({ args }) {
+        process.stdout.write(args.yaml ? getWorkflowProgramTemplate() : getWorkflowTemplate());
     },
 });
 const workflowValidateCommand = defineJsonCommand({
     meta: {
         name: "validate",
-        description: "Validate a workflow markdown file or ref and print any errors",
+        description: "Validate a workflow file or ref (markdown document or YAML program) and print any errors",
     },
     args: {
         target: {
             type: "positional",
-            description: "Workflow ref (workflow:<name>) or filesystem path to a workflow .md",
+            description: "Workflow ref (workflow:<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", {
@@ -271,7 +311,15 @@ const workflowValidateCommand = defineJsonCommand({
     },
 });
 async function resolveWorkflowFilePath(target) {
-    if (!target.startsWith("workflow:"))
+    // A bare (`workflow:<name>`) OR origin-qualified (`<origin>//workflow:<name>`)
+    // ref resolves through the source search, exactly like `workflow start` /
+    // `status` / `next`. Anything else is treated as a filesystem path. Detecting
+    // the origin-qualified form here (not just the bare prefix) keeps `validate`'s
+    // ref contract in lockstep with the rest of the workflow command family — an
+    // `extra//workflow:foo` ref validates the file that `extra//workflow:foo`
+    // starts, rather than being mistaken for a relative path that does not exist.
+    const looksLikeWorkflowRef = target.startsWith("workflow:") || target.includes("//workflow:");
+    if (!looksLikeWorkflowRef)
         return target;
     const parsed = parseAssetRef(target);
     if (parsed.type !== "workflow") {
@@ -290,6 +338,218 @@ async function resolveWorkflowFilePath(target) {
     }
     throw new UsageError(`Workflow not found for ref: workflow:${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",
+    },
+    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,
+        },
+    },
+    async run({ args }) {
+        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 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);
+    },
+});
+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 { 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;
+        }
+        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 (!WORKFLOW_REPORT_STATES.includes(status)) {
+            throw new UsageError(`Invalid --status "${status}". Expected one of: ${WORKFLOW_REPORT_STATES.join(", ")}.`, "INVALID_FLAG_VALUE");
+        }
+        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");
+        }
+        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");
+            }
+        }
+        // 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 { 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");
+            }
+        }
+        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 });
+    },
+});
 const workflowAbandonCommand = defineJsonCommand({
     meta: {
         name: "abandon",
@@ -332,6 +592,10 @@ export const workflowCommand = defineCommand({
         resume: workflowResumeCommand,
         abandon: workflowAbandonCommand,
         validate: workflowValidateCommand,
+        run: workflowRunCommand,
+        brief: workflowBriefCommand,
+        report: workflowReportCommand,
+        watch: workflowWatchCommand,
     },
     run({ args }) {
         return runWithJsonErrors(async () => {