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

package/dist/tasks/runner.js

@@ -2,7 +2,7 @@
 // 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 tasks run <id>` — what cron / launchd / schtasks invoke at the
+ * `akm task run <id>` — what cron / launchd / schtasks invoke at the
  * scheduled moment.
  *
  * Responsibilities:
@@ -12,155 +12,187 @@
  *      `tasks sync` time, not here — at run time we still want to attempt
  *      execution and surface the actual failure rather than re-fail on a
  *      validation error that the user already knows about.)
- *   3. Refuse to run when `enabled === false` (defense-in-depth).
+ *   3. Skip disabled tasks only when the invocation is scheduler-generated;
+ *      explicit manual runs are allowed for catch-up and testing.
  *   4. Dispatch by target kind:
  *        • workflow → `startWorkflowRun(ref, params)`
- *        • prompt   → `runAgent(profile, prompt, { stdio: "captured" })`
+ *        • prompt   → `executeRunner(engine, prompt, { stdio: "captured" })`
  *   5. Capture stdout / stderr as structured rows in logs.db (task_logs) and,
  *      transitionally, as a flat text tail at `<cacheDir>/tasks/logs/<id>/<ts>.log`
- *      (see docs/technical/logs-audit.md).
+ *      (per the #579 logs audit).
  *   6. Write a history row to state.db task_history table.
  *
  * Returns a structured result so the CLI handler can shape it for `output()`
  * and so tests can assert against it without scraping stdout.
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { shouldSkipUnactivatedTask } from "../core/activation-policy.js";
 import { assertNever } from "../core/assert.js";
-import { parseAssetRef } from "../core/asset/asset-ref.js";
-import { resolveStashDir } from "../core/common.js";
+import { placementSpecFor } from "../core/asset/asset-placement.js";
+import { parseRefInput } from "../core/asset/resolve-ref.js";
 import { loadConfig } from "../core/config/config.js";
-import { NotFoundError, rethrowIfTestIsolationError } from "../core/errors.js";
+import { AkmError, NotFoundError, rethrowIfTestIsolationError } from "../core/errors.js";
 import { buildTaskRunId, insertTaskLogLines, openLogsDatabase, } from "../core/logs-db.js";
 import { getTaskLogDir } from "../core/paths.js";
+import { redactCredentialPatterns } from "../core/redaction.js";
 import { withStateDb } from "../core/state-db.js";
-import { error } from "../core/warn.js";
-import { requireAgentProfile, runAgent } from "../integrations/agent/index.js";
-import { resolveProcessAgentProfile } from "../integrations/agent/config.js";
-import { resolveRunner } from "../integrations/agent/runner.js";
-import { spawn } from "../runtime.js";
+import { runManagedSubprocess } from "../core/subprocess.js";
+import { resolveEngine, resolveLlmEngineUse } from "../integrations/agent/engine-resolution.js";
+import { resolveModel } from "../integrations/agent/model-aliases.js";
+import { executeRunner } from "../integrations/agent/runner-dispatch.js";
+import { chatCompletion } from "../llm/client.js";
 import { resolveAssetPath } from "../sources/resolve.js";
-import { getTaskHistory, queryTaskHistory, upsertTaskHistory } from "../storage/repositories/task-history-repository.js";
+import { decodeTaskHistoryMetadata, finalizeTaskHistoryAttempt, getTaskHistory, queryTaskHistory, reserveTaskHistoryAttempt, upsertTaskHistory, } from "../storage/repositories/task-history-repository.js";
 import { startWorkflowRun } from "../workflows/runtime/runs.js";
+import { findBareAkmExecutableIndex } from "./command-executable.js";
 import { parseTaskDocument } from "./parser.js";
-export async function runTask(id, options = {}) {
-    const stashDir = options.stashDir ?? resolveStashDir();
-    const runAgentImpl = options.runAgentImpl ?? runAgent;
+import { resolveAkmInvocation } from "./resolve-akm-bin.js";
+import { validateTaskId } from "./task-id.js";
+export const INVALID_TASK_ATTEMPT_ID = "_invalid-task-id";
+export async function runTask(id, options) {
+    const runAgentImpl = options.runAgentImpl;
     const startWorkflowRunImpl = options.startWorkflowRunImpl ?? startWorkflowRun;
     const now = options.now ?? (() => new Date());
-    const logDir = options.logDir ?? getTaskLogDir();
-    const filePath = await resolveAssetPath(stashDir, "task", id);
-    const yaml = fs.readFileSync(filePath, "utf8");
-    const task = parseTaskDocument({ yaml, filePath, id });
-    const startedAt = now();
-    const startedIso = startedAt.toISOString();
-    const tsSlug = startedIso.replace(/[:.]/g, "-");
-    const taskLogDir = path.join(logDir, id);
-    fs.mkdirSync(taskLogDir, { recursive: true });
-    const logPath = path.join(taskLogDir, `${tsSlug}.log`);
-    if (!task.enabled) {
-        const finishedAt = now();
-        const disabledTarget = task.target.kind === "workflow"
-            ? { kind: "workflow", ref: task.target.ref }
-            : task.target.kind === "command"
-                ? { kind: "prompt", profile: undefined }
-                : { kind: "prompt", profile: task.target.profile };
-        const result = {
-            id,
-            status: "disabled",
-            startedAt: startedIso,
-            finishedAt: finishedAt.toISOString(),
-            durationMs: finishedAt.getTime() - startedAt.getTime(),
-            log: logPath,
-            target: disabledTarget,
-        };
-        const disabledLine = `[akm tasks] task "${id}" is disabled — skipping run.`;
-        persistRunLog({
-            taskId: id,
-            startedAtIso: startedIso,
-            finishedAtIso: result.finishedAt,
-            logPath,
-            fileText: `${disabledLine}\n`,
-            dbLines: [{ line: disabledLine }],
+    const requestedStartedAt = now();
+    try {
+        validateTaskId(id);
+    }
+    catch (failure) {
+        const attempt = reserveTaskAttempt(INVALID_TASK_ATTEMPT_ID, requestedStartedAt);
+        recordTaskAttemptFailure({
+            taskId: INVALID_TASK_ATTEMPT_ID,
+            reason: "invalid_task_id",
+            failure,
+            startedAt: attempt.startedAt,
+            finishedAt: now(),
+            logDir: options.logDir,
+            historyReserved: attempt.historyReserved,
         });
-        appendHistory(result);
-        return result;
+        throw failure;
     }
-    if (task.target.kind === "workflow") {
-        return await runWorkflowTask({
+    const attempt = reserveTaskAttempt(id, requestedStartedAt);
+    const startedAt = attempt.startedAt;
+    let failureReason = "task_load_failed";
+    try {
+        const stashDir = options.stashDir;
+        const filePath = await resolveAssetPath(stashDir, "task", id);
+        const yaml = fs.readFileSync(filePath, "utf8");
+        failureReason = "task_parse_failed";
+        const task = parseTaskDocument({ yaml, filePath, id });
+        failureReason = "task_dispatch_failed";
+        const startedIso = startedAt.toISOString();
+        const logPath = resolveTaskLogPath(options.logDir, id, startedIso);
+        if (shouldSkipUnactivatedTask({ enabled: task.enabled, scheduled: options.scheduled === true })) {
+            const finishedAt = finishAttempt(startedAt, now());
+            const disabledTarget = task.target.kind === "workflow"
+                ? { kind: "workflow", ref: task.target.ref }
+                : task.target.kind === "command"
+                    ? { kind: "command", cmd: task.target.cmd }
+                    : { kind: "prompt", engine: task.target.engine ?? null };
+            const result = {
+                id,
+                status: "disabled",
+                startedAt: startedIso,
+                finishedAt: finishedAt.toISOString(),
+                durationMs: finishedAt.getTime() - startedAt.getTime(),
+                log: logPath,
+                target: disabledTarget,
+            };
+            const disabledLine = `[akm task] task "${id}" is disabled — skipping run.`;
+            persistRunLog({
+                taskId: id,
+                startedAtIso: startedIso,
+                finishedAtIso: result.finishedAt,
+                logPath,
+                fileText: `${disabledLine}\n`,
+                dbLines: [{ line: disabledLine }],
+            });
+            appendHistory(result, attempt.historyReserved);
+            return result;
+        }
+        if (task.target.kind === "workflow") {
+            return await runWorkflowTask({
+                task,
+                logPath,
+                startedAt,
+                now,
+                startWorkflowRunImpl,
+                historyReserved: attempt.historyReserved,
+            });
+        }
+        if (task.target.kind === "command") {
+            return await runCommandTask({
+                task,
+                logPath,
+                startedAt,
+                now,
+                historyReserved: attempt.historyReserved,
+                ...(options.spawnFn ? { spawnFn: options.spawnFn } : {}),
+                ...(options.setTimeoutFn ? { setTimeoutFn: options.setTimeoutFn } : {}),
+                ...(options.clearTimeoutFn ? { clearTimeoutFn: options.clearTimeoutFn } : {}),
+            });
+        }
+        return await runPromptTask({
             task,
+            stashDir,
             logPath,
             startedAt,
             now,
-            startWorkflowRunImpl,
+            runAgentImpl,
+            agentOptions: options.agentOptions,
+            chatCompletionImpl: options.chatCompletionImpl ?? chatCompletion,
+            historyReserved: attempt.historyReserved,
         });
     }
-    if (task.target.kind === "command") {
-        return await runCommandTask({ task, logPath, startedAt, now });
+    catch (failure) {
+        recordTaskAttemptFailure({
+            taskId: id,
+            reason: failureReason,
+            failure,
+            startedAt,
+            finishedAt: now(),
+            logDir: options.logDir,
+            historyReserved: attempt.historyReserved,
+        });
+        throw failure;
     }
-    // Resolve config once here so runPromptTask does not call loadConfig()
-    // on every dispatch in a batch run (Fix C6).
-    const config = loadConfig();
-    return await runPromptTask({
-        task,
-        stashDir,
-        logPath,
-        startedAt,
-        now,
-        runAgentImpl,
-        agentOptions: options.agentOptions,
-        agentConfig: config,
-        agentTimeoutMs: undefined,
-    });
 }
 // ── command target ──────────────────────────────────────────────────────────
 async function runCommandTask(input) {
-    const { task, logPath, startedAt, now } = input;
+    const { task, logPath, startedAt, now, historyReserved } = input;
     if (task.target.kind !== "command")
         throw new Error("invariant: command target");
     const { cmd } = task.target;
+    const spawnCmd = resolveNestedAkmCommand(cmd);
     const timeoutMs = task.timeoutMs !== undefined ? task.timeoutMs : null;
-    const header = `[akm tasks] task=${task.id} kind=command cmd=${cmd.join(" ")}`;
+    const header = `[akm task] task=${task.id} kind=command cmd=${cmd.join(" ")}`;
     const logLines = [header];
     const dbLines = [{ line: header }];
-    let stdout = "";
-    let stderr = "";
     let exitCode = null;
     try {
-        const proc = spawn(cmd, {
-            stdin: "ignore",
-            stdout: "pipe",
-            stderr: "pipe",
-            cwd: process.env.HOME ?? "/tmp",
+        // 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(spawnCmd, {
+            capture: true,
+            cwd: process.env.HOME ?? os.tmpdir(),
             // 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, AKM_EVENT_SOURCE: process.env.AKM_EVENT_SOURCE ?? "task" },
+            timeoutMs,
+            ...(input.spawnFn ? { spawnFn: input.spawnFn } : {}),
+            ...(input.setTimeoutFn ? { setTimeoutFn: input.setTimeoutFn } : {}),
+            ...(input.clearTimeoutFn ? { clearTimeoutFn: input.clearTimeoutFn } : {}),
         });
-        let timer;
-        let timedOut = false;
-        if (timeoutMs !== null) {
-            timer = setTimeout(() => {
-                timedOut = true;
-                try {
-                    proc.kill("SIGTERM");
-                }
-                catch {
-                    /* ignore */
-                }
-            }, timeoutMs);
-        }
-        const [stdoutBuf, stderrBuf] = await Promise.all([
-            new Response(proc.stdout).text(),
-            new Response(proc.stderr).text(),
-        ]);
-        await proc.exited;
-        if (timer !== undefined)
-            clearTimeout(timer);
-        stdout = stdoutBuf;
-        stderr = stderrBuf;
-        exitCode = proc.exitCode ?? (timedOut ? 143 : 1);
+        // 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);
         if (timedOut) {
             logLines.push(`timed_out=true timeout_ms=${timeoutMs}`);
             dbLines.push({ level: "error", line: `timed_out=true timeout_ms=${timeoutMs}` });
@@ -184,7 +216,7 @@ async function runCommandTask(input) {
         dbLines.push({ level: "error", line: `spawn_error=${msg}` });
         exitCode = 1;
     }
-    const finishedAt = now();
+    const finishedAt = finishAttempt(startedAt, now());
     persistRunLog({
         taskId: task.id,
         startedAtIso: startedAt.toISOString(),
@@ -201,18 +233,25 @@ async function runCommandTask(input) {
         finishedAt: finishedAt.toISOString(),
         durationMs: finishedAt.getTime() - startedAt.getTime(),
         log: logPath,
-        target: { kind: "prompt", profile: undefined },
+        target: { kind: "command", cmd },
         detail: { exitCode },
     };
-    appendHistory(result);
+    appendHistory(result, historyReserved);
     return result;
 }
+/** Avoid a second PATH lookup when a task invokes the same AKM installation. */
+function resolveNestedAkmCommand(cmd) {
+    const akmIndex = findBareAkmExecutableIndex(cmd);
+    if (akmIndex === undefined)
+        return cmd;
+    return [...cmd.slice(0, akmIndex), ...resolveAkmInvocation().argv, ...cmd.slice(akmIndex + 1)];
+}
 // ── workflow target ─────────────────────────────────────────────────────────
 async function runWorkflowTask(input) {
-    const { task, logPath, startedAt, now, startWorkflowRunImpl } = input;
+    const { task, logPath, startedAt, now, startWorkflowRunImpl, historyReserved } = input;
     if (task.target.kind !== "workflow")
         throw new Error("invariant: workflow target");
-    const ref = parseAssetRef(task.target.ref);
+    const ref = parseRefInput(task.target.ref);
     if (ref.type !== "workflow") {
         throw new NotFoundError(`Task "${task.id}" workflow target must be a workflow ref (got "${task.target.ref}").`, "WORKFLOW_NOT_FOUND");
     }
@@ -222,9 +261,11 @@ async function runWorkflowTask(input) {
         detail = await startWorkflowRunImpl(task.target.ref, task.target.params);
     }
     catch (e) {
+        if (e instanceof AkmError && e.kind === "config")
+            throw e;
         error = e instanceof Error ? e : new Error(String(e));
     }
-    const finishedAt = now();
+    const finishedAt = finishAttempt(startedAt, now());
     const status = error ? "failed" : mapWorkflowStatus(detail?.run.status);
     const log = renderWorkflowLog({ task, detail, error });
     persistRunLog({
@@ -248,7 +289,7 @@ async function runWorkflowTask(input) {
             ...(error ? { error: error.message } : {}),
         },
     };
-    appendHistory(result);
+    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
@@ -287,7 +328,7 @@ function mapWorkflowStatus(status) {
 }
 function renderWorkflowLog(input) {
     const dbLines = [
-        { line: `[akm tasks] task=${input.task.id} kind=workflow ref=${input.task.target.ref}` },
+        { line: `[akm task] task=${input.task.id} kind=workflow ref=${input.task.target.ref}` },
     ];
     if (input.detail) {
         dbLines.push({ line: `run_id=${input.detail.run.id} status=${input.detail.run.status}` });
@@ -300,70 +341,70 @@ function renderWorkflowLog(input) {
 }
 // ── prompt target ───────────────────────────────────────────────────────────
 async function runPromptTask(input) {
-    const { task, stashDir, logPath, startedAt, now, runAgentImpl, agentOptions } = input;
+    const { task, stashDir, logPath, startedAt, now, agentOptions } = input;
     if (task.target.kind !== "prompt")
         throw new Error("invariant: prompt target");
-    // Use pre-resolved agent config when available to avoid redundant loadConfig()
-    // calls in batch task runs (Fix C6). Fall back to loadConfig() for callers
-    // that invoke runPromptTask directly without threading config.
-    const fullConfig = loadConfig();
-    const agentCfg = input.agentConfig !== undefined ? input.agentConfig : fullConfig;
-    // Resolve the profile for this task. When the task doc specifies a profile,
-    // use it directly. Otherwise fall back to the per-process config for "task"
-    // (agent.processes["task"]), which itself falls back to agent.default.
-    let profile;
-    let processTimeoutMs;
-    if (task.target.profile) {
-        // v2: if profiles.agent is configured, resolve through new runner
-        if (fullConfig.profiles?.agent) {
-            const mode = task.target.mode ?? "agent";
-            if (mode !== "llm") {
-                const runnerSpec = resolveRunner(mode, task.target.profile, fullConfig);
-                if (runnerSpec.kind === "agent" || runnerSpec.kind === "sdk") {
-                    profile = runnerSpec.profile;
-                    processTimeoutMs = runnerSpec.timeoutMs;
-                }
-                else {
-                    profile = requireAgentProfile(agentCfg, task.target.profile);
-                }
-            }
-            else {
-                profile = requireAgentProfile(agentCfg, task.target.profile);
-            }
-        }
-        else {
-            // v1: Task doc explicitly names a profile — honour it directly.
-            profile = requireAgentProfile(agentCfg, task.target.profile);
-        }
+    const promptTarget = task.target;
+    const config = loadConfig();
+    const engineName = promptTarget.engine ?? config.defaults?.engine;
+    if (!engineName)
+        throw new NotFoundError(`Task "${task.id}" has no selected engine.`, "ASSET_NOT_FOUND");
+    let runner = resolveEngine(engineName, config);
+    if (runner.kind === "llm") {
+        const resolved = resolveLlmEngineUse(config, [
+            {
+                engine: engineName,
+                ...(promptTarget.model !== undefined ? { model: promptTarget.model } : {}),
+                ...(promptTarget.timeoutMs !== undefined ? { timeoutMs: promptTarget.timeoutMs } : {}),
+                ...(promptTarget.llm !== undefined ? { llm: promptTarget.llm } : {}),
+            },
+        ]);
+        runner = {
+            kind: "llm",
+            engine: resolved.engine,
+            connection: resolved.connection,
+            ...(resolved.credential ? { credential: resolved.credential } : {}),
+            timeoutMs: resolved.timeoutMs,
+        };
     }
     else {
-        // No per-task profile: use process config for "task" as a fallback.
-        const resolved = resolveProcessAgentProfile("task", agentCfg);
-        profile = resolved.profile;
-        processTimeoutMs = resolved.timeoutMs;
+        if (promptTarget.llm !== undefined) {
+            throw new NotFoundError(`Task "${task.id}" uses llm overrides with non-LLM engine "${engineName}".`, "ASSET_NOT_FOUND");
+        }
+        const requestedModel = promptTarget.model;
+        const platform = runner.profile.platform;
+        if (!platform)
+            throw new Error(`Engine "${engineName}" resolved without a platform.`);
+        const model = requestedModel
+            ? resolveModel(requestedModel, platform, runner.profile.modelAliases, runner.profile.globalModelAliases)
+            : runner.profile.model;
+        runner = {
+            ...runner,
+            profile: { ...runner.profile, ...(model ? { model, modelIsExact: true } : {}) },
+            ...(promptTarget.timeoutMs !== undefined ? { timeoutMs: promptTarget.timeoutMs } : {}),
+        };
     }
-    // Task-level timeoutMs (including null = disabled) wins over global config.
-    // Resolution: task.timeoutMs → process entry timeoutMs → input.agentTimeoutMs → agentCfg.timeoutMs.
-    const agentTimeoutMs = task.timeoutMs !== undefined
-        ? task.timeoutMs
-        : processTimeoutMs !== undefined
-            ? processTimeoutMs
-            : input.agentTimeoutMs !== undefined
-                ? input.agentTimeoutMs
-                : undefined;
     const promptText = await resolvePromptText(task, stashDir);
-    const result = await runAgentImpl(profile, promptText, {
+    const result = await executeRunner(runner, promptText, {
         stdio: "captured",
-        timeoutMs: agentTimeoutMs,
         cwd: stashDir,
         ...agentOptions,
         // Stamp task-runner provenance for any akm invocation the agent makes
         // (DRIFT-6: agent-task traffic must not be recorded as user demand).
         // Caller-supplied env still wins on conflicts.
         env: { AKM_EVENT_SOURCE: "task", ...agentOptions?.env },
+    }, {
+        ...(input.runAgentImpl ? { runAgent: input.runAgentImpl } : {}),
+        llm: async (spec, prompt, options) => {
+            const started = Date.now();
+            const stdout = await input.chatCompletionImpl(spec.connection, [{ role: "user", content: prompt }], {
+                ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+            });
+            return { ok: true, exitCode: 0, stdout, stderr: "", durationMs: Date.now() - started };
+        },
     });
-    const finishedAt = now();
-    const log = renderPromptLog({ task, profileName: profile.name, result });
+    const finishedAt = finishAttempt(startedAt, now());
+    const log = renderPromptLog({ task, engineName, result });
     persistRunLog({
         taskId: task.id,
         startedAtIso: startedAt.toISOString(),
@@ -380,12 +421,12 @@ async function runPromptTask(input) {
         finishedAt: finishedAt.toISOString(),
         durationMs: finishedAt.getTime() - startedAt.getTime(),
         log: logPath,
-        target: { kind: "prompt", profile: profile.name },
+        target: { kind: "prompt", engine: engineName },
         detail: result.ok
             ? { exitCode: result.exitCode }
             : { reason: result.reason, error: result.error, exitCode: result.exitCode },
     };
-    appendHistory(out);
+    appendHistory(out, input.historyReserved);
     return out;
 }
 async function resolvePromptText(task, stashDir) {
@@ -403,14 +444,20 @@ async function resolvePromptText(task, stashDir) {
         return fs.readFileSync(filePath, "utf8");
     }
     // asset
-    const ref = parseAssetRef(src.ref);
+    const ref = parseRefInput(src.ref);
+    // D11 — see the matching guard in validator.ts: `resolveAssetPath`
+    // (src/sources/resolve.ts) is placement-dir-only and cannot route an
+    // opaque adapter conceptId, which `parseRefInput` now otherwise accepts.
+    if (placementSpecFor(ref.type) === undefined) {
+        throw new NotFoundError(`Task "${task.id}" prompt asset ref "${src.ref}" is not an AKM-placed asset — adapter-owned (opaque) prompt sources are not resolvable as task inputs yet.`, "ASSET_NOT_FOUND");
+    }
     const assetPath = await resolveAssetPath(stashDir, ref.type, ref.name);
     return fs.readFileSync(assetPath, "utf8");
 }
 function renderPromptLog(input) {
     const lines = [];
     const dbLines = [];
-    const header = `[akm tasks] task=${input.task.id} kind=prompt profile=${input.profileName}`;
+    const header = `[akm task] task=${input.task.id} 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 });
@@ -431,6 +478,19 @@ function renderPromptLog(input) {
     }
     return { fileText: `${lines.join("\n")}\n`, dbLines };
 }
+function taskLogPath(logDir, taskId, startedAtIso) {
+    const tsSlug = startedAtIso.replace(/[:.]/g, "-");
+    return path.join(logDir, taskId, `${tsSlug}.log`);
+}
+function resolveTaskLogPath(logDir, taskId, startedAtIso) {
+    try {
+        return taskLogPath(logDir ?? getTaskLogDir(), taskId, startedAtIso);
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        return "";
+    }
+}
 /** Split captured pipe output into per-line logs.db rows (blank lines dropped). */
 function streamLines(text, stream, level) {
     return text
@@ -443,11 +503,27 @@ function streamLines(text, stream, level) {
  * task_history keeps resolving for humans and older consumers) plus
  * structured rows in logs.db keyed by `buildTaskRunId(taskId, startedAt)`.
  *
+ * Both sinks are pattern-redacted (`redactCredentialPatterns`) before being
+ * written — task output is raw command/agent/LLM text that can echo a
+ * credential-bearing URL (e.g. a Discord webhook) nothing upstream expects to
+ * scrub.
+ *
  * The DB write is best-effort, mirroring {@link appendHistory}: an unwritable
  * logs.db must never fail a task run.
  */
 function persistRunLog(input) {
-    fs.writeFileSync(input.logPath, input.fileText);
+    const fileText = redactCredentialPatterns(input.fileText);
+    const dbLines = input.dbLines.map((entry) => ({ ...entry, line: redactCredentialPatterns(entry.line) }));
+    if (input.logPath) {
+        try {
+            fs.mkdirSync(path.dirname(input.logPath), { recursive: true });
+            fs.writeFileSync(input.logPath, fileText);
+        }
+        catch (error) {
+            rethrowIfTestIsolationError(error);
+            // Transitional file logging is fully best-effort.
+        }
+    }
     try {
         const db = openLogsDatabase();
         try {
@@ -455,59 +531,147 @@ function persistRunLog(input) {
                 taskId: input.taskId,
                 runId: buildTaskRunId(input.taskId, input.startedAtIso),
                 ts: input.finishedAtIso,
-                lines: input.dbLines,
+                lines: dbLines,
             });
         }
         finally {
             db.close();
         }
     }
-    catch (err) {
-        rethrowIfTestIsolationError(err);
-        error(`[akm] task log DB write failed: ${String(err)}`);
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        // Structured logging is fully best-effort and must not alter CLI output.
+    }
+}
+/** Reserve a collision-free identity through state.db's existing unique index. */
+function reserveTaskAttempt(taskId, requestedStartedAt) {
+    try {
+        return withStateDb((db) => {
+            for (let offsetMs = 0;; offsetMs++) {
+                const startedAt = new Date(requestedStartedAt.getTime() + offsetMs);
+                const reserved = reserveTaskHistoryAttempt(db, {
+                    task_id: taskId,
+                    status: "active",
+                    started_at: startedAt.toISOString(),
+                    completed_at: null,
+                    failed_at: null,
+                    log_path: null,
+                    target_kind: null,
+                    target_ref: null,
+                    metadata_json: JSON.stringify({ metadataVersion: 2, durationMs: 0, detail: null }),
+                });
+                if (reserved)
+                    return { startedAt, historyReserved: true };
+            }
+        });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        // Attempt recording cannot prevent or replace task execution.
+        return { startedAt: requestedStartedAt, historyReserved: false };
     }
 }
+function finishAttempt(startedAt, observedFinishedAt) {
+    return observedFinishedAt.getTime() < startedAt.getTime() ? new Date(startedAt) : observedFinishedAt;
+}
+const SAFE_TASK_ATTEMPT_ERROR_CODES = new Set([
+    "CONFIG_DIR_UNRESOLVABLE",
+    "STASH_DIR_NOT_FOUND",
+    "STASH_DIR_NOT_A_DIRECTORY",
+    "STASH_DIR_UNREADABLE",
+    "LLM_NOT_CONFIGURED",
+    "INVALID_CONFIG_FILE",
+    "UNSUPPORTED_CONFIG_VERSION",
+    "TEST_ISOLATION_MISSING",
+    "INVALID_FLAG_VALUE",
+    "MISSING_REQUIRED_ARGUMENT",
+    "PATH_ESCAPE_VIOLATION",
+    "TASK_SCHEMA_VERSION_UNSUPPORTED",
+    "ASSET_NOT_FOUND",
+    "WORKFLOW_NOT_FOUND",
+    "FILE_NOT_FOUND",
+]);
+function safeTaskAttemptErrorCode(failure) {
+    if (failure instanceof AkmError && SAFE_TASK_ATTEMPT_ERROR_CODES.has(failure.code))
+        return failure.code;
+    return "INTERNAL";
+}
+export function recordTaskAttemptFailure(input) {
+    let taskId = input.taskId;
+    try {
+        validateTaskId(taskId);
+    }
+    catch {
+        taskId = INVALID_TASK_ATTEMPT_ID;
+    }
+    const attempt = input.historyReserved === undefined
+        ? reserveTaskAttempt(taskId, input.startedAt)
+        : { startedAt: input.startedAt, historyReserved: input.historyReserved };
+    const finishedAt = finishAttempt(attempt.startedAt, input.finishedAt ?? new Date());
+    const startedAtIso = attempt.startedAt.toISOString();
+    const finishedAtIso = finishedAt.toISOString();
+    const errorCode = safeTaskAttemptErrorCode(input.failure);
+    const logPath = resolveTaskLogPath(input.logDir, taskId, startedAtIso);
+    const line = `[akm task] status=failed reason=${input.reason} code=${errorCode}`;
+    const result = {
+        id: taskId,
+        status: "failed",
+        startedAt: startedAtIso,
+        finishedAt: finishedAtIso,
+        durationMs: Math.max(0, finishedAt.getTime() - attempt.startedAt.getTime()),
+        log: logPath,
+        target: { kind: "unknown" },
+        detail: { reason: input.reason, error: errorCode },
+    };
+    persistRunLog({
+        taskId,
+        startedAtIso,
+        finishedAtIso,
+        logPath,
+        fileText: `${line}\n`,
+        dbLines: [{ level: "error", line }],
+    });
+    appendHistory(result, attempt.historyReserved);
+}
 // ── history ─────────────────────────────────────────────────────────────────
-function appendHistory(result) {
+function appendHistory(result, historyReserved = false) {
+    const row = {
+        task_id: result.id,
+        status: result.status,
+        started_at: result.startedAt,
+        completed_at: result.finishedAt,
+        failed_at: result.status === "failed" ? result.finishedAt : null,
+        log_path: result.log || null,
+        target_kind: result.target.kind === "unknown" ? null : result.target.kind,
+        target_ref: result.target.kind === "workflow" ? result.target.ref : null,
+        metadata_json: JSON.stringify({
+            metadataVersion: 2,
+            durationMs: result.durationMs,
+            detail: result.detail ?? null,
+            ...(result.target.kind === "prompt" ? { engine: result.target.engine } : {}),
+        }),
+    };
     try {
         withStateDb((db) => {
-            upsertTaskHistory(db, {
-                task_id: result.id,
-                status: result.status,
-                started_at: result.startedAt,
-                completed_at: result.finishedAt,
-                failed_at: result.status === "failed" ? result.finishedAt : null,
-                log_path: result.log,
-                target_kind: result.target.kind,
-                target_ref: result.target.kind === "workflow" ? result.target.ref : null,
-                metadata_json: JSON.stringify({
-                    durationMs: result.durationMs,
-                    detail: result.detail ?? null,
-                    profile: result.target.kind === "prompt" ? result.target.profile : undefined,
-                }),
-            });
+            if (historyReserved && finalizeTaskHistoryAttempt(db, row))
+                return;
+            upsertTaskHistory(db, row);
         });
     }
-    catch (err) {
-        rethrowIfTestIsolationError(err);
-        error(`[akm] task history DB write failed: ${String(err)}`);
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        // History recording is fully best-effort and must not alter CLI output.
     }
 }
 export function readTaskHistory(options = {}) {
     return withStateDb((db) => {
-        let rows;
+        if (options.limit === 0)
+            return [];
         if (options.id) {
             const row = getTaskHistory(db, options.id);
-            rows = row ? [taskHistoryRowToResult(row)] : [];
-        }
-        else {
-            rows = queryTaskHistory(db, {}).map(taskHistoryRowToResult);
-        }
-        rows.sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
-        if (options.limit !== undefined && options.limit >= 0) {
-            return rows.slice(0, options.limit);
+            return row ? [taskHistoryRowToResult(row)] : [];
         }
-        return rows;
+        return queryTaskHistory(db, options.limit !== undefined && options.limit > 0 ? { limit: options.limit } : {}).map(taskHistoryRowToResult);
     });
 }
 /**
@@ -515,25 +679,29 @@ export function readTaskHistory(options = {}) {
  * that callers of `readTaskHistory()` expect.
  */
 function taskHistoryRowToResult(row) {
-    let meta = {};
-    try {
-        meta = JSON.parse(row.metadata_json);
-    }
-    catch {
-        // ignore corrupt JSON
-    }
+    const meta = decodeTaskHistoryMetadata(row.metadata_json);
     const target = row.target_kind === "workflow"
         ? { kind: "workflow", ref: row.target_ref ?? "" }
-        : { kind: "prompt", profile: meta.profile };
+        : row.target_kind === "command"
+            ? { kind: "command" }
+            : row.target_kind === "prompt"
+                ? meta.metadataVersion === 1
+                    ? {
+                        kind: "prompt",
+                        engine: null,
+                        ...(meta.legacyProfile !== undefined ? { legacyProfile: meta.legacyProfile } : {}),
+                    }
+                    : { kind: "prompt", engine: meta.engine ?? null }
+                : { kind: "unknown" };
     return {
         id: row.task_id,
         status: row.status,
         startedAt: row.started_at,
         finishedAt: row.completed_at ?? row.failed_at ?? row.started_at,
-        durationMs: meta.durationMs ?? 0,
+        durationMs: meta.durationMs,
         log: row.log_path ?? "",
         target,
-        ...(meta.detail !== undefined ? { detail: meta.detail } : {}),
+        ...(meta.detail ? { detail: meta.detail } : {}),
     };
 }
 /**