akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/tasks/prepare/prepare-support.js

@@ -0,0 +1,154 @@
+// 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/.
+/**
+ * File-private helpers prepareTaskV3Execution depends on, moved body-intact
+ * out of the pre-P1b src/tasks/runtime-v3.ts (spec
+ * docs/plans/specs/p1b-model-extraction.md §4.1, Lane B / D4 module map).
+ * None of these was exported at head either; only the subset prepare.ts's
+ * moved function body calls is exported here.
+ */
+import path from "node:path";
+import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { COMPOSITION_INVALID_MULTI_JOB_HINT, ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { DURATION_UNITS, parseDuration } from "../../core/time.js";
+import { isPortableExecutionAgentSelector } from "../../execution/source.js";
+import { requireAuthorizedExecutionPlan } from "../../integrations/agent/execution-cascade.js";
+import { lowerResolvedExecutionRequest } from "../../integrations/agent/execution-lowering.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
+import { detectSecretShapedParams } from "../../workflows/exec/param-secrets.js";
+import { compileWorkflowPlan } from "../../workflows/ir/compile.js";
+import { compileWorkflowSource } from "../../workflows/source-ir/compile.js";
+import { isInferredSecretName } from "../log-redaction.js";
+import { SCHEDULED_TASK_CONTEXT_KEYS } from "../scheduler-invocation.js";
+function own(value, key) {
+    return value !== undefined && Object.hasOwn(value, key);
+}
+export function environmentSnapshot(environment) {
+    const out = Object.create(null);
+    for (const key of Object.keys(environment ?? {}).sort()) {
+        const raw = environment?.[key];
+        if (raw === undefined)
+            continue;
+        const value = String(raw);
+        if (isInferredSecretName(key) || detectSecretShapedParams({ [key]: value }).length > 0) {
+            throw new UsageError(`Task env.${key} is a secret-shaped literal env value. Store credentials in a secret/env binding rather than durable task source.`, "TASK_SOURCE_INVALID");
+        }
+        Object.defineProperty(out, key, { value, enumerable: true, configurable: false, writable: false });
+    }
+    return Object.freeze(out);
+}
+/** Merge source env with the authoritative, closed scheduler directory context. */
+export function commandEnvironmentSnapshot(environment, schedulerContext) {
+    const out = Object.create(null);
+    for (const key of Object.keys(environment)) {
+        Object.defineProperty(out, key, { value: environment[key], enumerable: true, configurable: true, writable: true });
+    }
+    for (const key of SCHEDULED_TASK_CONTEXT_KEYS) {
+        const value = schedulerContext?.[key];
+        if (!value)
+            continue;
+        Object.defineProperty(out, key, { value, enumerable: true, configurable: true, writable: true });
+    }
+    return Object.freeze(out);
+}
+function normalizeTimeout(value) {
+    if (value === undefined || value === null || typeof value === "number")
+        return value;
+    const parsed = parseDuration(value, DURATION_UNITS);
+    if (parsed === null)
+        throw new UsageError(`Invalid task timeout ${JSON.stringify(value)}.`, "TASK_SOURCE_INVALID");
+    return parsed;
+}
+export function qualifyOwnedRef(ref, context) {
+    const parsed = parseBundleRef(ref);
+    const bundle = parsed.bundle ?? context.bundleName;
+    return { parsed, qualified: makeBundleRef(bundle, parsed.conceptId) };
+}
+export function currentExecutionValues(document, context, environment) {
+    const akm = document.akm;
+    const agent = akm?.agent;
+    return Object.freeze({
+        ...(own(akm, "agent")
+            ? {
+                agent: typeof agent === "string" && isPortableExecutionAgentSelector(agent)
+                    ? qualifyOwnedRef(agent, context).qualified
+                    : agent,
+            }
+            : {}),
+        ...(own(akm, "engine") ? { engine: akm?.engine } : {}),
+        ...(own(akm, "model") ? { model: akm?.model } : {}),
+        ...(own(akm, "inference") ? { inference: akm?.inference } : {}),
+        ...(own(akm, "outputSchema") ? { outputSchema: akm?.outputSchema } : {}),
+        ...(own(akm, "tools") ? { tools: akm?.tools } : {}),
+        ...(own(akm, "timeout") ? { timeout: akm?.timeout } : {}),
+        workspace: context.bundleRoot,
+        environment,
+    });
+}
+export function base(document, context, environment) {
+    const timeoutMs = normalizeTimeout(document.akm?.timeout);
+    return Object.freeze({
+        taskId: context.taskId,
+        taskRef: context.taskRef,
+        environment,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        redact: Object.freeze([...(document.akm?.redact ?? [])]),
+    });
+}
+export async function resolvedOwnedAsset(qualified, type, context) {
+    const parsed = parseBundleRef(qualified);
+    const prefix = `${type}s/`;
+    const name = parsed.conceptId.slice(prefix.length);
+    if (context.resolveAsset) {
+        const resolved = await context.resolveAsset({ bundle: parsed.bundle, type, name, ref: qualified });
+        return typeof resolved === "string"
+            ? Object.freeze({ file: resolved, bundleRoot: context.bundleRoot })
+            : Object.freeze({ file: resolved.file, bundleRoot: resolved.bundleRoot });
+    }
+    if (parsed.bundle !== context.bundleName) {
+        throw new NotFoundError(`Task target ${JSON.stringify(qualified)} names bundle ${JSON.stringify(parsed.bundle)}, but no bundle resolver was provided.`, "ASSET_NOT_FOUND");
+    }
+    return Object.freeze({
+        file: await resolveAssetPath(context.bundleRoot, type, name),
+        bundleRoot: context.bundleRoot,
+    });
+}
+export function defaultTaskShell(platform) {
+    return platform === "win32" ? "powershell" : "sh";
+}
+export function validatePreparedCommand(invocation, context) {
+    const request = requireAuthorizedExecutionPlan(invocation.plan);
+    if (!request.engine.name) {
+        throw new ConfigError(`Task ${JSON.stringify(context.taskRef)} has no resolved execution engine. Configure defaults.engine or akm.engine before running it.`, "INVALID_CONFIG_FILE");
+    }
+    // Lowering is pure. Running it before the durable-attempt boundary proves
+    // the selected target is transport-projectable; dispatch repeats the same
+    // deterministic projection from this frozen request/config snapshot.
+    lowerResolvedExecutionRequest(request, invocation.config);
+    return invocation;
+}
+export function validateWorkflowRuntimeSource(file, workspaceRoot, readFile) {
+    const source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readFile(file, workspaceRoot));
+    const compiled = compileWorkflowSource(source, { path: file, workspaceRoot });
+    if (!compiled.ok) {
+        // P4-N2's mapping (docs/plans/specs/p4-deletions-closeout.md §3.3.4): a
+        // task-wrapped workflow target's own multi-job source is a composition
+        // failure, same as freezing it directly would be; any other compile
+        // failure is WORKFLOW_SOURCE_INVALID.
+        const detail = compiled.errors.map((error) => `${error.path}:${error.line}: ${error.message}`).join("; ");
+        const isMultiJob = compiled.errors.length === 1 && compiled.errors[0]?.code === "multi-job-unsupported";
+        const code = isMultiJob ? "COMPOSITION_INVALID" : "WORKFLOW_SOURCE_INVALID";
+        throw new UsageError(`Task workflow target is not projectable: ${detail}`, code, isMultiJob ? COMPOSITION_INVALID_MULTI_JOB_HINT : undefined);
+    }
+    const planned = compileWorkflowPlan(compiled.ir, path.basename(file, path.extname(file)));
+    if (!planned.ok) {
+        // Same mapping applied for consistency; `compiled.ir` is already
+        // guaranteed exactly one job here, so this arm always resolves to
+        // WORKFLOW_SOURCE_INVALID in practice.
+        const detail = planned.errors.map((error) => `${file}:${error.line}: ${error.message}`).join("; ");
+        const isMultiJob = planned.errors.length === 1 && planned.errors[0]?.code === "multi-job-unsupported";
+        const code = isMultiJob ? "COMPOSITION_INVALID" : "WORKFLOW_SOURCE_INVALID";
+        throw new UsageError(`Task workflow target is not projectable: ${detail}`, code, isMultiJob ? COMPOSITION_INVALID_MULTI_JOB_HINT : undefined);
+    }
+}

package/dist/tasks/prepare/prepare.js

@@ -0,0 +1,117 @@
+// 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/.
+/**
+ * Pure task runtime projection.
+ *
+ * This is the only bridge from an already-parsed, already-projected task
+ * source document (the `PreparableTaskDocument` seam, P4-N4) into executable
+ * work. It performs all source/config/asset reads before the task runner
+ * reserves a durable attempt and returns immutable snapshots. In particular,
+ * script work contains frozen bytes and their digest, never a path that can
+ * be reread when a delayed or resumed dispatch begins.
+ *
+ * `prepareTaskV3Execution`'s three production callers are
+ * `src/tasks/run/load-task.ts`, `src/tasks/scheduler-sync.ts`, and
+ * `src/workflows/freeze/targets/task.ts`'s `taskDispatch`. The name and the
+ * `TaskV3*` type family it takes stay (spec docs/plans/specs/p4-deletions-closeout.md
+ * §0, R-R1) — only task source v4 ever reaches this function now, always via
+ * `src/tasks/source/project-v4.ts`'s `projectTaskSourceV4()`.
+ */
+import fs from "node:fs";
+import { prepareCommandInvocation } from "../../commands/command/command-execution.js";
+import { UsageError } from "../../core/errors.js";
+import { base, commandEnvironmentSnapshot, currentExecutionValues, defaultTaskShell, environmentSnapshot, qualifyOwnedRef, resolvedOwnedAsset, validatePreparedCommand, validateWorkflowRuntimeSource, } from "./prepare-support.js";
+import { captureDirectoryIdentity, captureScriptTarget } from "./script-capture.js";
+/** Project one canonical task-v3 source into immutable executable work. */
+export async function prepareTaskV3Execution(document, context) {
+    const environment = environmentSnapshot(document.env);
+    const commandEnvironment = commandEnvironmentSnapshot(environment, context.schedulerContext);
+    const common = base(document, context, environment);
+    if (document.target.kind === "run") {
+        const cwdIdentity = captureDirectoryIdentity(context.bundleRoot, document.target.workingDirectory);
+        return Object.freeze({
+            ...common,
+            kind: "shell",
+            command: document.target.run,
+            shell: document.target.shell ?? defaultTaskShell(context.platform ?? process.platform),
+            cwd: cwdIdentity.realCwd,
+            cwdIdentity,
+        });
+    }
+    const target = document.target.uses;
+    if (target.kind === "builtin-command") {
+        const command = document.target.command;
+        if (!command)
+            throw new Error("invariant: parsed built-in command target has no command action");
+        const action = command.kind === "stored"
+            ? {
+                ref: qualifyOwnedRef(command.ref, context).qualified,
+                ...(command.arguments !== undefined ? { arguments: command.arguments } : {}),
+            }
+            : { content: command.content, ...(command.arguments !== undefined ? { arguments: command.arguments } : {}) };
+        const invocation = validatePreparedCommand(await (context.prepareCommand ?? prepareCommandInvocation)({
+            action,
+            config: context.config,
+            invocationKind: "task",
+            current: currentExecutionValues(document, context, commandEnvironment),
+            ...(context.commandSourceLoader ? { sourceLoader: context.commandSourceLoader } : {}),
+        }), context);
+        return Object.freeze({ ...common, kind: "command", invocation });
+    }
+    const { qualified } = qualifyOwnedRef(target.ref, context);
+    if (target.kind === "command") {
+        // Unreachable from any parsed source: task source v4 accepts with: only
+        // on uses: akm/command. Kept as a seam invariant — this function takes a
+        // structurally-typed document.
+        if (document.target.with !== undefined) {
+            throw new UsageError("Command refs do not accept with; use akm/command with {ref, arguments} for portable arguments.", "COMPOSITION_INVALID");
+        }
+        const invocation = validatePreparedCommand(await (context.prepareCommand ?? prepareCommandInvocation)({
+            action: { ref: qualified },
+            config: context.config,
+            invocationKind: "task",
+            current: currentExecutionValues(document, context, commandEnvironment),
+            ...(context.commandSourceLoader ? { sourceLoader: context.commandSourceLoader } : {}),
+        }), context);
+        return Object.freeze({ ...common, kind: "command", invocation });
+    }
+    if (target.kind === "workflow") {
+        // Stays reachable — task source v4 still has a top-level env: (P4-N4).
+        if (Object.keys(environment).length > 0) {
+            // P4 (docs/plans/specs/p4-deletions-closeout.md §5.5, row P-04): PRESERVED,
+            // not re-coded — tests/integration/tasks-with-classification-characterization.test.ts's
+            // P-04 block pins this exact code (CONVERT, not FLIP, per §7.2 F-A2.8:
+            // "the P-04 block ... stays reachable and stays pinned"). §5.2's target
+            // table predicted all 3 of this file's remaining sites → COMPOSITION_INVALID;
+            // this is the recorded deviation for the one site a preservation gate blocks.
+            throw new UsageError("Task workflow env cannot be consumed by the durable workflow runtime in 0.9.2; remove env or use a command target.", "INVALID_FLAG_VALUE");
+        }
+        const resolved = await resolvedOwnedAsset(qualified, "workflow", context);
+        validateWorkflowRuntimeSource(resolved.file, resolved.bundleRoot, context.readFile ?? ((targetPath) => fs.readFileSync(targetPath)));
+        return Object.freeze({
+            ...common,
+            kind: "workflow",
+            ref: qualified,
+            params: Object.freeze({ ...(document.target.with ?? {}) }),
+            ...(document.akm?.maxSteps !== undefined ? { maxSteps: document.akm.maxSteps } : {}),
+            ...(document.akm?.maxRetries !== undefined ? { maxRetries: document.akm.maxRetries } : {}),
+        });
+    }
+    // Unreachable from any parsed source: task source v4 accepts with: only on
+    // uses: akm/command. Kept as a seam invariant — this function takes a
+    // structurally-typed document.
+    if (document.target.with !== undefined) {
+        throw new UsageError("Script refs do not accept with.", "COMPOSITION_INVALID");
+    }
+    const resolved = await resolvedOwnedAsset(qualified, "script", context);
+    // Shared with prepare-script-target.ts's prepareScriptTarget() (spec §4.3):
+    // one implementation of the byte/interpreter capture, not two.
+    const captured = captureScriptTarget(qualified, resolved.file, resolved.bundleRoot, context.readFile ?? ((targetPath) => fs.readFileSync(targetPath)));
+    return Object.freeze({
+        ...common,
+        kind: "script",
+        sourceRef: qualified,
+        ...captured,
+    });
+}

package/dist/tasks/prepare/prepared-execution.js

@@ -0,0 +1,4 @@
+// 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/.
+export {};

package/dist/tasks/prepare/script-capture.js

@@ -0,0 +1,80 @@
+// 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 one shared implementation of frozen-script byte/interpreter capture
+ * (spec docs/plans/specs/p1b-model-extraction.md §4.3). Both prepare.ts's
+ * script arm (the moved prepareTaskV3Execution) and
+ * prepare-script-target.ts's typed prepareScriptTarget() call
+ * captureScriptTarget() below, so the two never drift into two copies of the
+ * same capture logic. scriptInterpreter() and captureDirectoryIdentity() are
+ * moved body-intact out of the pre-P1b src/tasks/runtime-v3.ts.
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { UsageError } from "../../core/errors.js";
+import { captureFrozenDirectoryIdentity } from "../../execution/directory-identity.js";
+import { isBunStandaloneMain } from "../resolve-akm-bin.js";
+const SCRIPT_INTERPRETERS = Object.freeze({
+    ".sh": "sh",
+    ".ts": "bun",
+    ".js": "bun",
+    ".ps1": "powershell",
+    ".cmd": "cmd",
+    ".bat": "cmd",
+    ".py": "python",
+    ".rb": "ruby",
+    ".go": "go",
+    ".pl": "perl",
+    ".php": "php",
+    ".lua": "lua",
+    ".r": "rscript",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".kts": "kotlin",
+});
+export function scriptInterpreter(extension, ref) {
+    const interpreter = SCRIPT_INTERPRETERS[extension];
+    if (!interpreter) {
+        throw new UsageError(`Task v3 script target ${JSON.stringify(ref)} has no closed runtime interpreter for extension ${JSON.stringify(extension)}.`, "TASK_TARGET_UNSUPPORTED");
+    }
+    if (interpreter !== "bun")
+        return interpreter;
+    if (!process.versions.bun) {
+        throw new UsageError(`Task v3 script target ${JSON.stringify(ref)} requires Bun for ${extension} execution, but this runtime cannot provide it.`, "TASK_TARGET_UNSUPPORTED");
+    }
+    return isBunStandaloneMain() ? "bun-standalone" : "bun";
+}
+export function captureDirectoryIdentity(bundleRoot, workingDirectory) {
+    try {
+        return captureFrozenDirectoryIdentity(bundleRoot, workingDirectory);
+    }
+    catch (cause) {
+        if (cause instanceof UsageError)
+            throw cause;
+        throw new UsageError(`Task working directory ${JSON.stringify(workingDirectory ?? ".")} cannot be physically verified: ${cause instanceof Error ? cause.message : String(cause)}`, "TASK_SOURCE_INVALID");
+    }
+}
+/**
+ * Read a script's bytes off disk (or the caller's own read seam) and freeze
+ * the interpreter/digest/directory-identity shape every script dispatch
+ * needs. `ref` is used only for interpreter-selection error messages — it is
+ * the script's own qualified ref, never a synthetic task ref. `bundleRoot` is
+ * where directory identity is captured from (one level above the script file
+ * itself, matching prepareTaskV3Execution's historical behavior).
+ */
+export function captureScriptTarget(ref, file, bundleRoot, readFile) {
+    const extension = path.extname(file).toLowerCase();
+    const raw = readFile(file, bundleRoot);
+    const bytes = Uint8Array.from(raw);
+    const cwdIdentity = captureDirectoryIdentity(bundleRoot);
+    return Object.freeze({
+        interpreter: scriptInterpreter(extension, ref),
+        extension,
+        bytesBase64: Buffer.from(bytes).toString("base64"),
+        byteLength: bytes.byteLength,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        cwd: cwdIdentity.realCwd,
+        cwdIdentity,
+    });
+}

package/dist/tasks/run/attempt-lifecycle.js

@@ -0,0 +1,165 @@
+// 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 task-attempt reservation/finalization lifecycle: `reserveTaskAttempt`
+ * (called before any dispatch), `finishAttempt` (the monotonic finish-time
+ * clamp every arm's result uses), and `recordTaskAttemptFailure` (the
+ * catch-all for a dispatch that threw after an attempt was reserved).
+ *
+ * Moved from src/tasks/runner.ts (spec docs/plans/specs/p1b-model-extraction.md
+ * §5.1, §9, runner.ts:970-1069). `reserveTaskAttempt` and `finishAttempt`
+ * were module-private at head; both are exported here because run-task.ts and
+ * every dispatch arm (run-native-task.ts, run-workflow-task.ts,
+ * run-command-task.ts), now separate files, call them.
+ *
+ * F-4 (P1a advisory, spec §5.5): `SAFE_TASK_ATTEMPT_ERROR_CODES` gains
+ * `TASK_SOURCE_INVALID` and `COMPOSITION_INVALID` — see the comment on the
+ * set for the verified reachability path. `SAFE_TASK_ATTEMPT_ERROR_CODES` and
+ * `safeTaskAttemptErrorCode` stay unexported: their membership is observed
+ * the same way production code observes it, through
+ * `recordTaskAttemptFailure`'s one externally-visible effect (the stored
+ * `detail.error` code).
+ *
+ * P4 (docs/plans/specs/p4-deletions-closeout.md §4.1, row B-55): the set
+ * additionally gains `TARGET_REF_INVALID`, `WORKFLOW_SOURCE_INVALID`,
+ * `INPUT_BINDING_INVALID`, and `TASK_TARGET_UNSUPPORTED` — every code P4's
+ * `INVALID_FLAG_VALUE` re-coding sweep (spec §5.2) makes reachable from the
+ * same post-reservation dispatch catch. `TARGET_REF_INVALID`
+ * (`execution/target-ref.ts`) and `INPUT_BINDING_INVALID`
+ * (`workflows/freeze/task-bindings.ts`) already reach it today through the
+ * same WORKFLOW arm as `COMPOSITION_INVALID` above — freezing a composed
+ * child (a `tasks/<ref>` or `workflows/<ref>` step) during dispatch can
+ * classify a malformed `uses:` or an invalid `with:` binding after the
+ * attempt is reserved. `WORKFLOW_SOURCE_INVALID` and `TASK_TARGET_UNSUPPORTED`
+ * get their first live throw sites in this same phase (the freeze wrapper's
+ * P4-N2 mapping, and `prepare/script-capture.ts`'s interpreter rejections,
+ * respectively) — added here ahead of / alongside that wiring rather than
+ * split across two commits, since an unreachable member of an allowlist Set
+ * is inert, not a defect.
+ */
+import { AkmError, rethrowIfTestIsolationError } from "../../core/errors.js";
+import { withStateDb } from "../../core/state-db.js";
+import { reserveTaskHistoryAttempt } from "../../storage/repositories/task-history-repository.js";
+import { validateTaskId } from "../task-id.js";
+import { appendHistory } from "./task-history.js";
+import { persistRunLog, resolveTaskLogPath } from "./task-log.js";
+export const INVALID_TASK_ATTEMPT_ID = "_invalid-task-id";
+/** Reserve a collision-free identity through state.db's existing unique index. */
+export 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 };
+    }
+}
+/** Clamp a finish observation to never precede its own start (a mocked clock can otherwise report a negative duration). */
+export function finishAttempt(startedAt, observedFinishedAt) {
+    return observedFinishedAt.getTime() < startedAt.getTime() ? new Date(startedAt) : observedFinishedAt;
+}
+/**
+ * Error codes safe to surface verbatim in a task-history `detail.error`
+ * (rather than the generic `"INTERNAL"`) — user-actionable configuration and
+ * usage failures, never an unclassified internal error that might leak
+ * implementation detail.
+ *
+ * F-4 (P1a advisory, spec §5.5): `TASK_SOURCE_INVALID` and
+ * `COMPOSITION_INVALID` join the allowlist. Verified reachability: the only
+ * caller of `recordTaskAttemptFailure` inside the runner is the
+ * post-reservation catch in run-task.ts; task-source parsing happens BEFORE
+ * reservation (load-task.ts), so the direct parse path never reaches it.
+ * Both codes reach it through the WORKFLOW arm instead: a workflow task whose
+ * plan freezes a `tasks/<ref>` step raises `TASK_SOURCE_INVALID` (via
+ * `taskDispatch`'s `parseTaskSource`/`parseTaskSourceV4Document` —
+ * `src/workflows/freeze/targets/task.ts`; `parseTaskV3Yaml` no longer exists
+ * in `src`, P4 deleted task v3 acceptance, spec
+ * docs/plans/specs/p4-deletions-closeout.md §3.2) or `COMPOSITION_INVALID`
+ * (the P1a with-rejection guard) DURING dispatch, after the attempt was
+ * already reserved. Before this widening, both were recorded as
+ * `"INTERNAL"`.
+ */
+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",
+    "TASK_SOURCE_INVALID",
+    "COMPOSITION_INVALID",
+    "TARGET_REF_INVALID",
+    "WORKFLOW_SOURCE_INVALID",
+    "INPUT_BINDING_INVALID",
+    "TASK_TARGET_UNSUPPORTED",
+]);
+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);
+}

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

@@ -0,0 +1,117 @@
+// 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/.
+/**
+ * Load and project one task asset into immutable executable work: id
+ * validation, adapter detection, owner resolution, source read, strict task
+ * source parsing, config selection, bundle-name resolution, and the
+ * `prepareTaskV3Execution` call. Everything here is non-mutating — run-task.ts
+ * reserves a durable attempt only after this resolves.
+ */
+import fs from "node:fs";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { makeBundleRef } from "../../core/asset/asset-ref.js";
+import { loadConfig } from "../../core/config/config.js";
+import { NotFoundError } from "../../core/errors.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
+import { applyInputDefaults, materializeInputFlags, validateInputs, } from "../../execution/input-contract.js";
+import { resolveAdapterConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
+import { prepareTaskV3Execution } from "../prepare/prepare.js";
+import { scheduledTaskContextEnv } from "../scheduler-invocation.js";
+import { parseTaskSource } from "../source/parse-task-source.js";
+import { projectTaskSourceV4 } from "../source/project-v4.js";
+import { TASK_INPUT_DIAGNOSTICS } from "../source/task-input-diagnostics.js";
+import { validateTaskConceptId, validateTaskId } from "../task-id.js";
+/**
+ * F-3 (spec §5.4): the literal bundle-name fallback, hoisted to a named
+ * constant — the VALUE does not change (it is user-visible data, R-09's
+ * observable behavior). The now-deleted `runner.ts:173`'s (P4) bare
+ * `"stash"` became this at the P1b runner.ts split.
+ */
+export const DEFAULT_BUNDLE_NAME = "stash";
+const CONFIG_FREE_TASK_RUNTIME = Object.freeze({
+    configVersion: "0.9.0",
+    semanticSearchMode: "off",
+});
+/** Resolve, parse, and project one task-v3 asset into a frozen, executable projection. */
+export async function loadPreparedTask(id, options) {
+    const bundleDir = options.bundleDir;
+    const adapterId = options.adapterId ?? detectAdapterId(bundleDir);
+    if (adapterId === "akm-task")
+        validateTaskConceptId(id);
+    else
+        validateTaskId(id);
+    const taskConceptId = adapterId === "akm" ? `tasks/${id}` : id;
+    const owner = resolveAdapterConceptOwner(bundleDir, adapterId, taskConceptId);
+    if (!owner) {
+        throw new NotFoundError(`Task ${JSON.stringify(id)} was not found in the configured ${JSON.stringify(adapterId)} component.`, "ASSET_NOT_FOUND");
+    }
+    const filePath = owner.path;
+    const yaml = fs.readFileSync(filePath, "utf8");
+    const parsed = parseTaskSource({ yaml, filePath, workspaceRoot: bundleDir });
+    const source = projectTaskSourceV4(parsed.v4);
+    const requiresCommandConfig = source.target.kind === "uses" &&
+        (source.target.uses.kind === "builtin-command" || source.target.uses.kind === "command");
+    const config = requiresCommandConfig ? loadConfig() : CONFIG_FREE_TASK_RUNTIME;
+    const bundleName = options.bundleName ?? config.defaultBundle ?? DEFAULT_BUNDLE_NAME;
+    // P2a Lane C, Stage 2 (spec docs/plans/specs/p2a-task-source-v4.md §5.1):
+    // materialize akm task run's raw input flags (Stage 1,
+    // src/commands/tasks/tasks-cli.ts) against the task's own declared
+    // inputs: contract (empty when the document declares none, so any input
+    // flag on such a task fails UNKNOWN_FLAG — there is nothing declared to
+    // match against).
+    // materializeInputFlags already validates the flag-supplied values; a
+    // required input satisfied only by its own default (never supplied as a
+    // flag) needs the SEPARATE validateInputs call below, run after defaults
+    // are applied — materializeInputFlags returns {} immediately for zero
+    // flags, before ever checking `required` (spec §5.1, input-contract.ts's
+    // own header).
+    const inputContract = parsed.v4.inputs ?? {};
+    const materializedInputs = materializeInputFlags(inputContract, options.inputFlags ?? [], TASK_INPUT_DIAGNOSTICS);
+    const defaultedInputs = applyInputDefaults(inputContract, materializedInputs);
+    const requiredErrors = validateInputs(inputContract, defaultedInputs);
+    if (requiredErrors.length > 0)
+        throw TASK_INPUT_DIAGNOSTICS.contractViolation(requiredErrors);
+    const inputBindings = Object.entries(defaultedInputs).map(([name, value]) => Object.freeze({ kind: "literal", name, value }));
+    if (options.captureTaskInvocation) {
+        const invocation = Object.freeze({
+            taskRef: makeBundleRef(bundleName, taskConceptId),
+            caller: Object.freeze({ kind: "cli" }),
+            ...(inputBindings.length > 0 ? { inputs: Object.freeze(inputBindings) } : {}),
+        });
+        options.captureTaskInvocation(invocation);
+    }
+    // P2b Lane B (spec docs/plans/specs/p2b-input-bindings.md §4.3, B-40): a
+    // task source v4 document's own declared `inputs:` deliver into a
+    // `uses: workflows/<ref>` target's child-run params through the EXISTING
+    // with-> params path (prepare.ts's workflow branch already reads
+    // `document.target.with`) — task source v4 never authors `with:` on a
+    // workflow target itself (task-source-v4.ts's own parser accepts `with:`
+    // only on `uses: akm/command`, source/task-source-v4.ts:329-333), so this
+    // override is purely additive for a workflow-target task.
+    const deliverySource = source.target.kind === "uses" && source.target.uses.kind === "workflow"
+        ? { ...source, target: { ...source.target, with: defaultedInputs } }
+        : source;
+    return prepareTaskV3Execution(deliverySource, {
+        taskId: id,
+        taskRef: makeBundleRef(bundleName, taskConceptId),
+        bundleName,
+        bundleRoot: bundleDir,
+        config,
+        // Agent profiles build child env from an allowlist, so freeze the closed
+        // scheduler-restored AKM directory context before command preparation.
+        ...(options.scheduled ? { schedulerContext: scheduledTaskContextEnv() } : {}),
+        resolveAsset: async ({ bundle, type, name }) => {
+            if (bundle === bundleName) {
+                return { file: await resolveAssetPath(bundleDir, type, name), bundleRoot: bundleDir };
+            }
+            const resolutionConfig = requiresCommandConfig ? config : loadConfig();
+            const resolvedBundle = resolveWriteTarget(resolutionConfig, bundle, { requireWritable: false });
+            return {
+                file: await resolveAssetPath(resolvedBundle.source.path, type, name),
+                bundleRoot: resolvedBundle.source.path,
+            };
+        },
+    });
+}

package/dist/tasks/run/provenance.js

@@ -0,0 +1,20 @@
+// 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/.
+/**
+ * Build the default task-run provenance context: `eventSource` is always
+ * `"task"` (D5-N1); `scheduled` carries the caller's own scheduled flag.
+ */
+export function createExecutionProvenanceContext(scheduled) {
+    return Object.freeze({ eventSource: "task", scheduled });
+}
+/**
+ * Resolve the effective provenance for one `runTask()` call: an explicit
+ * `RunTaskOptions.provenance` always wins; absent, this is the default
+ * context (§5.2 "Threading") — what keeps every pre-P1b caller (and any
+ * future in-repo caller that never sets `provenance`) byte-equivalent to
+ * today's behavior.
+ */
+export function resolveProvenanceContext(explicit, scheduled) {
+    return explicit ?? createExecutionProvenanceContext(scheduled);
+}