akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/tasks/run/run-command-task.js

@@ -0,0 +1,92 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { dispatchPreparedCommandInvocation } from "../../commands/command/command-execution.js";
+import { finishAttempt } from "./attempt-lifecycle.js";
+import { appendHistory } from "./task-history.js";
+import { persistRunLog, scrubTaskOutput, streamLines } from "./task-log.js";
+export async function runPreparedCommandTask(input) {
+    const { task, logPath, startedAt, now, agentOptions, provenance } = input;
+    const dispatchOptions = {
+        ...(input.runAgentImpl ? { runAgent: input.runAgentImpl } : {}),
+        ...(input.chatCompletionImpl ? { chat: input.chatCompletionImpl } : {}),
+        ...(agentOptions ? { runOptions: agentOptions } : {}),
+        // F-1 (R-07 fix, spec §5.2 point 3): threads the resolved event source
+        // into the dispatched engine's child env and the recorded usage events.
+        eventSource: provenance.eventSource,
+    };
+    const result = await dispatchPreparedCommandInvocation(task.invocation, dispatchOptions);
+    const engineName = result.engine;
+    const finishedAt = finishAttempt(startedAt, now());
+    const log = renderPromptLog({ task, engineName, result, notices: result.notices, warnings: result.warnings });
+    persistRunLog({
+        taskId: task.taskId,
+        startedAtIso: startedAt.toISOString(),
+        finishedAtIso: finishedAt.toISOString(),
+        logPath,
+        fileText: log.fileText,
+        dbLines: log.dbLines,
+        redactNames: task.redact,
+        environment: task.environment,
+    });
+    const status = result.ok ? "completed" : "failed";
+    const out = {
+        id: task.taskId,
+        status,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        log: logPath,
+        target: { kind: "command", engine: engineName },
+        detail: result.ok
+            ? { exitCode: result.exitCode }
+            : {
+                reason: result.reason === undefined ? undefined : scrubTaskOutput(task, result.reason),
+                error: result.error === undefined ? undefined : scrubTaskOutput(task, result.error),
+                exitCode: result.exitCode,
+            },
+        ...(result.notices && result.notices.length > 0
+            ? {
+                notices: result.notices.map((notice) => ({
+                    ...notice,
+                    message: scrubTaskOutput(task, notice.message),
+                })),
+            }
+            : {}),
+    };
+    appendHistory(out, input.historyReserved);
+    return out;
+}
+function renderPromptLog(input) {
+    const lines = [];
+    const dbLines = [];
+    const header = `[akm task] task=${input.task.taskId} kind=prompt engine=${input.engineName}`;
+    const summary = `ok=${input.result.ok} exit_code=${input.result.exitCode ?? "null"} duration_ms=${input.result.durationMs}`;
+    lines.push(header, summary);
+    dbLines.push({ line: header }, { level: input.result.ok ? "info" : "error", line: summary });
+    for (const warning of input.warnings ?? []) {
+        lines.push(warning);
+        dbLines.push({ level: "warn", line: warning });
+    }
+    for (const notice of input.notices ?? []) {
+        const line = `lowering_notice=${notice.code} adapter=${notice.adapter} field=${notice.field ?? ""} message=${notice.message}`;
+        lines.push(line);
+        dbLines.push({ level: notice.severity === "warning" ? "warn" : "info", line });
+    }
+    if (!input.result.ok) {
+        const failure = `reason=${input.result.reason ?? ""} error=${input.result.error ?? ""}`;
+        lines.push(failure);
+        dbLines.push({ level: "error", line: failure });
+    }
+    if (input.result.stdout) {
+        lines.push("--- agent stdout ---");
+        lines.push(input.result.stdout);
+        dbLines.push(...streamLines(input.result.stdout, "stdout", "info"));
+    }
+    if (input.result.stderr) {
+        lines.push("--- agent stderr ---");
+        lines.push(input.result.stderr);
+        dbLines.push(...streamLines(input.result.stderr, "stderr", "error"));
+    }
+    return { fileText: `${lines.join("\n")}\n`, dbLines };
+}

package/dist/tasks/run/run-native-task.js

@@ -0,0 +1,222 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The shell + frozen-script dispatch arm: `runNativeTask`, plus its
+ * shell-command builders (`shellCommand`, `resolveLeadingBareAkmCommand`,
+ * `quoteShellArgument`).
+ *
+ * Moved from src/tasks/runner.ts (spec docs/plans/specs/p1b-model-extraction.md
+ * §5.1, §9, runner.ts:294-455).
+ *
+ * F-1 (spec §5.2 point 1): the child env's `AKM_EVENT_SOURCE` stamp now reads
+ * `provenance.eventSource` instead of the hardcoded literal `"task"` — with
+ * the default provenance context (run/provenance.ts) this is byte-equivalent
+ * to before (P-06 stays green unchanged).
+ *
+ * F-2 (D8, spec §5.3): the result's `target` is now `{kind:"shell", cmd}` or
+ * `{kind:"script", cmd}` — formerly one shared `{kind:"command", cmd}`.
+ */
+import path from "node:path";
+import { assertNever } from "../../core/assert.js";
+import { runManagedSubprocess, streamCaptureFailure } from "../../core/subprocess.js";
+import { assertFrozenDirectoryIdentity } from "../../execution/directory-identity.js";
+import { cleanupFrozenScript, frozenScriptCommand, materializeFrozenScript } from "../frozen-script.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
+import { finishAttempt } from "./attempt-lifecycle.js";
+import { DEFAULT_SCHEDULED_TASK_TIMEOUT_MS } from "./run-workflow-task.js";
+import { appendHistory } from "./task-history.js";
+import { persistRunLog, streamLines } from "./task-log.js";
+/**
+ * Resolve the host shell to something spawnable in a scheduler-fired process.
+ *
+ * A scheduled run restores the PATH captured at install time
+ * (scheduler-invocation.ts), which can be minimal — the native-scheduler CI
+ * gate installs with PATH = System32 + SystemRoot, modeling what a real
+ * scheduler hands a job. powershell.exe does not live in System32 itself but
+ * in the WindowsPowerShell\v1.0 subdirectory, so a bare "powershell" spawn
+ * resolves only when that PATH happens to carry the extra entry; cmd.exe has
+ * a canonical ComSpec location for the same reason. Resolve both absolutely
+ * on Windows. pwsh has no fixed install location and the POSIX shells always
+ * live on the scheduler's default /bin:/usr/bin, so those stay PATH-resolved.
+ *
+ * Exported for direct unit testing with an explicit platform/env.
+ */
+export function shellExecutable(shell, platform = process.platform, env = process.env) {
+    if (platform !== "win32")
+        return shell;
+    const systemRoot = env.SystemRoot ?? "C:\\Windows";
+    if (shell === "powershell") {
+        return path.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    }
+    if (shell === "cmd") {
+        return env.ComSpec ?? path.win32.join(systemRoot, "System32", "cmd.exe");
+    }
+    return shell;
+}
+/** Exported for direct unit testing with an explicit platform/env. */
+export function shellCommand(task, platform = process.platform, env = process.env) {
+    const command = resolveLeadingBareAkmCommand(task.command, task.shell);
+    switch (task.shell) {
+        case "sh":
+        case "bash":
+        case "zsh":
+            return [task.shell, "-c", command];
+        case "pwsh":
+        case "powershell":
+            return [shellExecutable(task.shell, platform, env), "-NoProfile", "-NonInteractive", "-Command", command];
+        case "cmd":
+            return [shellExecutable("cmd", platform, env), "/d", "/s", "/c", command];
+        default:
+            return assertNever(task.shell, "shellCommand");
+    }
+}
+/**
+ * Bind an unambiguous leading bare `akm` (including the task-v2 migrator's
+ * quoted form) to this installation. Explicit paths and arbitrary shell
+ * fragments remain author-controlled.
+ */
+function resolveLeadingBareAkmCommand(command, shell) {
+    const leadingBareAkm = /^(\s*)(?:akm(?:\.exe)?|'akm(?:\.exe)?'|"akm(?:\.exe)?")(?=$|[\s;|&])/i;
+    if (!leadingBareAkm.test(command))
+        return command;
+    const quoted = resolveAkmInvocation()
+        .argv.map((part) => quoteShellArgument(part, shell))
+        .join(" ");
+    // PowerShell parses a quoted string in command position as a string
+    // EXPRESSION, not an invocation — `'C:\akm.exe' --version` is a parse
+    // error. The call operator makes it a command. sh and cmd both treat a
+    // quoted word in command position as the command, so only PowerShell
+    // needs the prefix.
+    const invocation = shell === "pwsh" || shell === "powershell" ? `& ${quoted}` : quoted;
+    return command.replace(leadingBareAkm, (_match, leadingWhitespace) => `${leadingWhitespace}${invocation}`);
+}
+function quoteShellArgument(value, shell) {
+    switch (shell) {
+        case "sh":
+        case "bash":
+        case "zsh":
+            return `'${value.replaceAll("'", `'"'"'`)}'`;
+        case "pwsh":
+        case "powershell":
+            return `'${value.replaceAll("'", "''")}'`;
+        case "cmd":
+            return `"${value.replaceAll('"', '""')}"`;
+        default:
+            return assertNever(shell, "quoteShellArgument");
+    }
+}
+export async function runNativeTask(input) {
+    const { task, logPath, startedAt, now, historyReserved, provenance } = input;
+    let materialized;
+    let cmd = task.kind === "shell" ? shellCommand(task) : [];
+    // Unset → the unattended default; `null` → the explicit no-timeout opt-out.
+    const timeoutMs = task.timeoutMs !== undefined ? task.timeoutMs : DEFAULT_SCHEDULED_TASK_TIMEOUT_MS;
+    const header = task.kind === "shell"
+        ? `[akm task] task=${task.taskId} kind=run shell=${task.shell}`
+        : `[akm task] task=${task.taskId} kind=script ref=${task.sourceRef} sha256=${task.sha256}`;
+    const logLines = [header];
+    const dbLines = [{ line: header }];
+    let exitCode = null;
+    try {
+        // The projector froze both canonical paths and filesystem identities before
+        // history mutation. Re-resolve the authored root/cwd immediately before
+        // spawn so a symlink, ancestor, bundle-root, or directory/file swap cannot
+        // redirect execution outside that physical workspace.
+        assertFrozenDirectoryIdentity(task.cwdIdentity);
+        if (task.kind === "script") {
+            materialized = materializeFrozenScript(task);
+            cmd = frozenScriptCommand(task, materialized.file);
+        }
+        // Managed spawn (src/core/subprocess.ts): process-GROUP kill so a timeout
+        // reaps the whole command tree (no orphans), and a SIGTERM→SIGKILL ladder
+        // so a child that ignores SIGTERM can't wedge the run forever.
+        const result = await runManagedSubprocess(cmd, {
+            capture: true,
+            cwd: task.cwd,
+            // Stamp task-runner provenance so any akm invocation in the command tree
+            // records usage events as machine traffic, not user demand (DRIFT-6).
+            // A more specific stamp already in the environment (e.g. improve's
+            // AKM_EVENT_SOURCE=improve on its child spawns) still wins in children.
+            env: {
+                ...process.env,
+                ...task.environment,
+                AKM_EVENT_SOURCE: process.env.AKM_EVENT_SOURCE ?? provenance.eventSource,
+            },
+            // cmd.exe's `/S /C` reads its tail as one hand-quoted command line, not
+            // standard argv — shellCommand() already built and quoted it for that.
+            // The default per-argument escaping would add an incompatible second
+            // layer on top and break any resolved path containing a space.
+            windowsVerbatimArguments: task.kind === "shell" && task.shell === "cmd",
+            timeoutMs,
+            ...(input.spawnFn ? { spawnFn: input.spawnFn } : {}),
+            ...(input.setTimeoutFn ? { setTimeoutFn: input.setTimeoutFn } : {}),
+            ...(input.clearTimeoutFn ? { clearTimeoutFn: input.clearTimeoutFn } : {}),
+        });
+        // A synchronous spawn throw / exit rejection surfaces as spawn_error below.
+        if (result.spawnError)
+            throw result.spawnError;
+        const { stdout, stderr, timedOut } = result;
+        exitCode = result.exitCode ?? (timedOut ? 143 : 1);
+        // A pipe that errored or stopped draining yields EMPTY output that is
+        // otherwise indistinguishable from a command that printed nothing — the
+        // log reads like a clean success. Say so instead, the way the workflow
+        // (exec-unit.ts) and agent (agent/spawn.ts) capture paths already do.
+        const captureFailure = streamCaptureFailure(result.stdoutRead, result.stderrRead);
+        if (captureFailure) {
+            const line = `output_capture_incomplete=${captureFailure}`;
+            logLines.push(line);
+            dbLines.push({ level: "warn", line });
+        }
+        if (timedOut) {
+            logLines.push(`timed_out=true timeout_ms=${timeoutMs}`);
+            dbLines.push({ level: "error", line: `timed_out=true timeout_ms=${timeoutMs}` });
+        }
+        logLines.push(`exit_code=${exitCode}`);
+        dbLines.push({ level: exitCode === 0 ? "info" : "error", line: `exit_code=${exitCode}` });
+        if (stdout) {
+            logLines.push("--- stdout ---");
+            logLines.push(stdout);
+            dbLines.push(...streamLines(stdout, "stdout", "info"));
+        }
+        if (stderr) {
+            logLines.push("--- stderr ---");
+            logLines.push(stderr);
+            dbLines.push(...streamLines(stderr, "stderr", "error"));
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        logLines.push(`spawn_error=${msg}`);
+        dbLines.push({ level: "error", line: `spawn_error=${msg}` });
+        exitCode = 1;
+    }
+    finally {
+        if (materialized)
+            cleanupFrozenScript(materialized);
+    }
+    const finishedAt = finishAttempt(startedAt, now());
+    persistRunLog({
+        taskId: task.taskId,
+        startedAtIso: startedAt.toISOString(),
+        finishedAtIso: finishedAt.toISOString(),
+        logPath,
+        fileText: `${logLines.join("\n")}\n`,
+        dbLines,
+        redactNames: task.redact,
+        environment: task.environment,
+    });
+    const status = exitCode === 0 ? "completed" : "failed";
+    const result = {
+        id: task.taskId,
+        status,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        log: logPath,
+        target: task.kind === "shell" ? { kind: "shell", cmd } : { kind: "script", cmd },
+        detail: { exitCode },
+    };
+    appendHistory(result, historyReserved);
+    return result;
+}

package/dist/tasks/run/run-task.js

@@ -0,0 +1,99 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm task run <id>` — what cron / launchd / schtasks invoke at the
+ * scheduled moment.
+ *
+ * The durable boundary is intentional: id/bundle resolution, source read,
+ * strict task source parsing, target resolution, command
+ * authorization/lowering, workflow projectability, and frozen script-byte
+ * capture (load-task.ts) all finish before an attempt is reserved or a log is
+ * created (attempt-lifecycle.ts). Once prepared, the runner dispatches the
+ * immutable command, workflow, shell, or script projection to its own arm
+ * module (run-command-task.ts, run-workflow-task.ts, run-native-task.ts) and
+ * records that actual attempt. Task source v4 has no document-level disabled
+ * state to skip at fire time (P4-N6) — a schedule binding that should not
+ * fire is never installed with the OS scheduler in the first place
+ * (scheduler-sync.ts), so every invocation that reaches `runTask` dispatches.
+ *
+ * Orchestration only.
+ *
+ * D5 (spec §1.2/§5.2, "Threading"): resolves `options.provenance` against the
+ * default context (run/provenance.ts) ONCE per call, and threads the result
+ * into every dispatch arm.
+ */
+import { runWorkflowSteps } from "../../workflows/exec/run-workflow.js";
+import { recordTaskAttemptFailure, reserveTaskAttempt } from "./attempt-lifecycle.js";
+import { loadPreparedTask } from "./load-task.js";
+import { resolveProvenanceContext } from "./provenance.js";
+import { runPreparedCommandTask } from "./run-command-task.js";
+import { runNativeTask } from "./run-native-task.js";
+import { runWorkflowTask } from "./run-workflow-task.js";
+import { resolveTaskLogPath } from "./task-log.js";
+export async function runTask(id, options) {
+    const runWorkflowStepsImpl = options.runWorkflowStepsImpl ?? runWorkflowSteps;
+    const now = options.now ?? (() => new Date());
+    const requestedStartedAt = now();
+    const provenance = resolveProvenanceContext(options.provenance, options.scheduled === true);
+    const task = await loadPreparedTask(id, options);
+    // All validation, parsing, source resolution, command cascade preparation,
+    // and frozen-byte capture above is non-mutating. Only a fully projectable
+    // task may reserve durable history or create a log.
+    const attempt = reserveTaskAttempt(id, requestedStartedAt);
+    const startedAt = attempt.startedAt;
+    const startedIso = startedAt.toISOString();
+    const logPath = resolveTaskLogPath(options.logDir, id, startedIso);
+    try {
+        if (task.kind === "workflow") {
+            return await runWorkflowTask({
+                task,
+                logPath,
+                startedAt,
+                now,
+                runWorkflowStepsImpl,
+                historyReserved: attempt.historyReserved,
+                provenance,
+                ...(options.setTimeoutFn ? { setTimeoutFn: options.setTimeoutFn } : {}),
+                ...(options.clearTimeoutFn ? { clearTimeoutFn: options.clearTimeoutFn } : {}),
+            });
+        }
+        if (task.kind === "command") {
+            return await runPreparedCommandTask({
+                task,
+                logPath,
+                startedAt,
+                now,
+                historyReserved: attempt.historyReserved,
+                provenance,
+                runAgentImpl: options.runAgentImpl,
+                agentOptions: options.agentOptions,
+                chatCompletionImpl: options.chatCompletionImpl,
+            });
+        }
+        options.beforeNativeDispatch?.(task);
+        return await runNativeTask({
+            task,
+            logPath,
+            startedAt,
+            now,
+            historyReserved: attempt.historyReserved,
+            provenance,
+            ...(options.spawnFn ? { spawnFn: options.spawnFn } : {}),
+            ...(options.setTimeoutFn ? { setTimeoutFn: options.setTimeoutFn } : {}),
+            ...(options.clearTimeoutFn ? { clearTimeoutFn: options.clearTimeoutFn } : {}),
+        });
+    }
+    catch (failure) {
+        recordTaskAttemptFailure({
+            taskId: id,
+            reason: "task_dispatch_failed",
+            failure,
+            startedAt,
+            finishedAt: now(),
+            logDir: options.logDir,
+            historyReserved: attempt.historyReserved,
+        });
+        throw failure;
+    }
+}

package/dist/tasks/run/run-workflow-task.js

@@ -0,0 +1,222 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The workflow dispatch arm: `runWorkflowTask`, `mapWorkflowStatus`,
+ * `renderWorkflowLog`, plus the shared unattended-timeout defaults
+ * (`DEFAULT_WORKFLOW_TASK_TIMEOUT_MS`, `DEFAULT_SCHEDULED_TASK_TIMEOUT_MS`)
+ * every arm reads.
+ *
+ * Moved from src/tasks/runner.ts (spec docs/plans/specs/p1b-model-extraction.md
+ * §5.1, §9, runner.ts:456-675).
+ *
+ * F-1 (spec §5.2 point 2): the global `process.env.AKM_EVENT_SOURCE` stamp
+ * and its `finally` restore are DELETED outright — `process.env` is never
+ * written by this arm any more. The resolved event source is instead passed
+ * into `runWorkflowStepsImpl` via a new optional `eventSource` option,
+ * `process.env.AKM_EVENT_SOURCE ?? provenance.eventSource` (ambient still
+ * wins, matching the native arm's own precedence — D5 clause d). Threading
+ * that option to an exec-unit child's env is owned by
+ * src/workflows/exec/run-workflow.ts / step-work.ts / exec-unit.ts, not this
+ * file.
+ */
+import { armAbortDeadline } from "../../core/abort-deadline.js";
+import { assertNever } from "../../core/assert.js";
+import { AkmError } from "../../core/errors.js";
+import { finishAttempt } from "./attempt-lifecycle.js";
+import { appendHistory } from "./task-history.js";
+import { persistRunLog, scrubTaskOutput } from "./task-log.js";
+/**
+ * Whole-run timeout applied to a workflow-bound task that does not declare its
+ * own `timeoutMs` — six hours.
+ *
+ * `akm workflow run` deliberately has NO default `--timeout`: a human is
+ * watching, and Ctrl-C aborts the very same signal the flag's timer would.
+ * A scheduled task has nobody watching. Without a default, its only bound is
+ * the per-unit timeout — and a frozen plan may set `timeout: null` (unbounded),
+ * so one wedged agent unit hangs the run until the machine reboots, holding the
+ * run lease and silently skipping every later firing (issue 11).
+ *
+ * Six hours is deliberately generous rather than tight: the abort is graceful
+ * (the engine breaks at the next step boundary and the run stays resumable), so
+ * the cost of over-waiting is bounded while the cost of cutting a legitimate
+ * long run short is a lost step. It matches the 6h idle window `akm health`
+ * already uses to call a run stale (`commands/health/report-view-model.ts`),
+ * and it lands well inside a `@daily` cadence, so a wedged run can never still
+ * be holding the lease when the next day's firing arrives.
+ *
+ * An explicit `timeoutMs:` in the task file always wins; `timeoutMs: null` is
+ * the explicit opt-out back to unbounded.
+ */
+export const DEFAULT_WORKFLOW_TASK_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+/**
+ * The same unattended default for command and prompt tasks.
+ *
+ * The reasoning above is about SCHEDULED runs, not about workflows: nobody is
+ * watching, and one wedged run silently stops the schedule. Command tasks
+ * defaulted to `null` (no kill timer) and prompt tasks inherited
+ * DEFAULT_AGENT_TIMEOUT_MS, also null — so a hung `curl`, a prompting agent
+ * waiting on stdin, or a stuck engine wedged the task forever while the
+ * workflow arm was protected. Same value, same opt-out: an explicit
+ * `timeoutMs:` wins, and `timeoutMs: null` restores unbounded.
+ */
+export const DEFAULT_SCHEDULED_TASK_TIMEOUT_MS = DEFAULT_WORKFLOW_TASK_TIMEOUT_MS;
+export async function runWorkflowTask(input) {
+    const { task, logPath, startedAt, now, runWorkflowStepsImpl, historyReserved, provenance } = input;
+    // Unset → the unattended default; `null` → the explicit no-timeout opt-out.
+    const timeoutMs = task.timeoutMs === undefined ? DEFAULT_WORKFLOW_TASK_TIMEOUT_MS : task.timeoutMs;
+    // The shared deadline `akm workflow run --timeout` also arms
+    // ({@link armAbortDeadline}): one AbortController for the run's lifetime,
+    // aborted by a timer. The engine reads `options.signal` at every step
+    // boundary and breaks GRACEFULLY — in-flight units are cancelled, the journal
+    // and the run lease are retained, and the run is left `active`, i.e.
+    // resumable with `akm workflow resume`.
+    const controller = new AbortController();
+    const deadline = armAbortDeadline(controller, {
+        timeoutMs,
+        reason: `Workflow task "${task.taskId}" timed out after ${timeoutMs}ms.`,
+        ...(input.setTimeoutFn ? { setTimeoutFn: input.setTimeoutFn } : {}),
+        ...(input.clearTimeoutFn ? { clearTimeoutFn: input.clearTimeoutFn } : {}),
+    });
+    let detail;
+    let gateError;
+    let error;
+    // The prompt path logs the engine-fallback announcement; a workflow-backed
+    // task must leave the same trace rather than silently using a chosen engine.
+    let runWarnings = [];
+    // F-1 (D5, spec §5.2 point 2): thread the resolved event source through
+    // explicitly instead of stamping process.env — this arm executes IN-PROCESS,
+    // so a global stamp used to be how child akm invocations made by workflow
+    // steps inherited it; the explicit eventSource option (threaded to
+    // src/workflows/exec/run-workflow.ts -> step-work.ts -> exec-unit.ts's
+    // childEnv) now does that job without ever mutating process.env. A more
+    // specific ambient stamp already present still wins, matching the native arm.
+    const eventSource = process.env.AKM_EVENT_SOURCE ?? provenance.eventSource;
+    try {
+        const execution = await runWorkflowStepsImpl({
+            target: task.ref,
+            params: task.params,
+            signal: controller.signal,
+            eventSource,
+            ...(task.maxSteps !== undefined ? { maxSteps: task.maxSteps } : {}),
+            ...(task.maxRetries !== undefined ? { maxRetries: task.maxRetries } : {}),
+        });
+        detail = execution.run;
+        runWarnings = execution.warnings ?? [];
+        if (execution.gateRejection) {
+            gateError = `Verification rejected step "${execution.gateRejection.stepId}": ${execution.gateRejection.feedback}`;
+        }
+    }
+    catch (e) {
+        if (e instanceof AkmError && e.kind === "config")
+            throw e;
+        error = e instanceof Error ? e : new Error(String(e));
+    }
+    finally {
+        deadline.disarm();
+    }
+    // A timeout is a failed ATTEMPT even though the engine stopped cleanly: the
+    // aborted run comes back `active` (resumable), which on its own would map to
+    // task status "active" and a 0 exit code, telling the OS scheduler nothing
+    // went wrong. Surface it like the command target's `timed_out=true` instead.
+    //
+    // Unless the run COMPLETED anyway. The abort is observed between steps, so a
+    // deadline landing in the run's final bookkeeping can set the flag on a run
+    // that then finishes — and reporting that as a failure would tell an operator
+    // to resume a run with nothing left to resume.
+    const ranToCompletion = detail?.status === "completed";
+    const timedOutAfterMs = deadline.timedOut() && timeoutMs !== null && !ranToCompletion ? timeoutMs : undefined;
+    const timeoutError = timedOutAfterMs === undefined
+        ? undefined
+        : new Error(`Workflow run timed out after ${timedOutAfterMs}ms and was aborted at a step boundary` +
+            (detail?.id ? ` — resume it with \`akm workflow resume ${detail.id}\`.` : "."));
+    // One failure value for the three sinks below (status, log line, history
+    // detail): a thrown error outranks a gate rejection, which outranks the
+    // deadline. Re-laddering per sink is how a log line ends up naming a
+    // different cause than the history row it was written beside.
+    const failure = error ?? (gateError ? new Error(gateError) : timeoutError);
+    const finishedAt = finishAttempt(startedAt, now());
+    const status = failure ? "failed" : mapWorkflowStatus(detail?.status);
+    const log = renderWorkflowLog({
+        task,
+        detail,
+        error: failure,
+        warnings: runWarnings,
+        ...(timedOutAfterMs !== undefined ? { timedOutAfterMs } : {}),
+    });
+    persistRunLog({
+        taskId: task.taskId,
+        startedAtIso: startedAt.toISOString(),
+        finishedAtIso: finishedAt.toISOString(),
+        logPath,
+        fileText: log.fileText,
+        dbLines: log.dbLines,
+        redactNames: task.redact,
+        environment: task.environment,
+    });
+    const result = {
+        id: task.taskId,
+        status,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        log: logPath,
+        target: { kind: "workflow", ref: task.ref },
+        detail: {
+            runId: detail?.id,
+            ...(failure ? { error: scrubTaskOutput(task, failure.message) } : {}),
+        },
+    };
+    appendHistory(result, historyReserved);
+    // Don't re-throw on workflow failure: the OS scheduler reads exit codes,
+    // not exceptions, and the CLI maps `status: "failed"` to a non-zero exit
+    // via exitCodeForStatus(). Throwing here would route through the generic
+    // runWithJsonErrors path and lose the structured result/history we just
+    // recorded.
+    return result;
+}
+/**
+ * Map the workflow runtime's status into the task-runner status space.
+ * A workflow normally reaches completed or failed in one orchestration call.
+ * Active remains representable for explicit engine stops such as a gate.
+ *
+ * The parameter is typed as the runtime's `WorkflowRunStatus` union (plus the
+ * `undefined` that `detail?.run.status` can produce when no detail is present).
+ * Every union member is handled explicitly and the `default` arm calls
+ * `assertNever`, so adding a new `WorkflowRunStatus` variant without mapping it
+ * here is a *compile* error rather than silently collapsing to "completed".
+ * The previous silent `default: "completed"` is preserved only for the
+ * `undefined` (no-detail) case, which is handled up front.
+ */
+function mapWorkflowStatus(status) {
+    // No run detail → treat as completed (unchanged from the prior silent default).
+    if (status === undefined)
+        return "completed";
+    switch (status) {
+        case "completed":
+        case "blocked":
+        case "failed":
+        case "active":
+            return status;
+        default:
+            return assertNever(status, "mapWorkflowStatus");
+    }
+}
+function renderWorkflowLog(input) {
+    const dbLines = [
+        { line: `[akm task] task=${input.task.taskId} kind=workflow ref=${input.task.ref}` },
+    ];
+    for (const warning of input.warnings ?? [])
+        dbLines.push({ level: "warn", line: warning });
+    if (input.timedOutAfterMs !== undefined) {
+        dbLines.push({ level: "error", line: `timed_out=true timeout_ms=${input.timedOutAfterMs}` });
+    }
+    if (input.detail) {
+        dbLines.push({ line: `run_id=${input.detail.id} status=${input.detail.status}` });
+        dbLines.push({ line: `workflow_title=${input.detail.workflowTitle}` });
+    }
+    if (input.error) {
+        dbLines.push({ level: "error", line: `error=${input.error.message}` });
+    }
+    return { fileText: `${dbLines.map((entry) => entry.line).join("\n")}\n`, dbLines };
+}