akm-cli 0.9.0 → 0.9.1-beta.1

package/dist/tasks/parser.js

@@ -12,6 +12,10 @@
  * workflow: workflows/daily-backup
  * params:
  *   region: us-east-1
+ * timeoutMs: 3600000               # whole-run bound; omit for the unattended
+ *                                  # default, `null` to opt out entirely
+ * maxSteps: 20                     # optional run bounds, same as the
+ * maxRetries: 1                    # `akm workflow run` flags
  * # ...or:
  * prompt: agents/my-agent           # asset ref
  * # ...or:
@@ -27,6 +31,8 @@
  * description: …
  * when_to_use: …
  * tags: [scheduled, backup]
+ * redact: [ACME_DEPLOY_TOKEN]     # optional: env var NAMES (never values) to
+ *                                 # scrub from this task's persisted log
  * ```
  *
  * Validation lives in {@link validateTaskDocument}. The parser enforces the
@@ -38,7 +44,8 @@ import { parse as parseYaml } from "yaml";
 import { isFullRefInput } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
-import { TASK_SCHEMA_VERSION } from "./schema.js";
+import { WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_RETRIES } from "../workflows/resource-limits.js";
+import { TASK_MAX_REDACT_NAMES, TASK_MAX_TIMEOUT_MS, TASK_SCHEMA_VERSION, } from "./schema.js";
 import { validateTaskId } from "./task-id.js";
 export function parseTaskDocument(input) {
     const { yaml, filePath } = input;
@@ -79,15 +86,25 @@ export function parseTaskDocument(input) {
     }
     let target;
     if (hasWorkflow) {
-        rejectTargetFields(data, ["params"], id, filePath);
+        rejectTargetFields(data, ["params", "timeoutMs", "maxSteps", "maxRetries"], id, filePath);
         const ref = requireString(data.workflow, "workflow", filePath);
         if (!ref) {
             throw new UsageError(`Task "${id}" has empty \`workflow\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
         }
+        // The three run bounds `akm workflow run` takes as flags, declared in the
+        // task file instead: an unattended run gets the same abort path the
+        // interactive CLI has. `timeoutMs` left unset falls back to the runner's
+        // default (see DEFAULT_WORKFLOW_TASK_TIMEOUT_MS); `null` opts out.
+        const workflowTimeoutMs = readTimeout(data.timeoutMs, filePath);
+        const maxSteps = readBoundedInteger(data.maxSteps, "maxSteps", 1, undefined, filePath);
+        const maxRetries = readBoundedInteger(data.maxRetries, "maxRetries", 0, WORKFLOW_MAX_RETRIES, filePath);
         target = {
             kind: "workflow",
             ref,
             params: readParams(data.params, filePath),
+            ...(workflowTimeoutMs !== undefined ? { timeoutMs: workflowTimeoutMs } : {}),
+            ...(maxSteps !== undefined ? { maxSteps } : {}),
+            ...(maxRetries !== undefined ? { maxRetries } : {}),
         };
     }
     else if (hasCommand) {
@@ -114,6 +131,7 @@ export function parseTaskDocument(input) {
         };
     }
     const timeoutMs = hasCommand ? readTimeout(data.timeoutMs, filePath) : undefined;
+    const redact = readRedactNames(data.redact, filePath);
     return {
         version: TASK_SCHEMA_VERSION,
         schemaVersion: TASK_SCHEMA_VERSION,
@@ -127,6 +145,7 @@ export function parseTaskDocument(input) {
         ...(tags ? { tags } : {}),
         source: { path: filePath },
         timeoutMs,
+        ...(redact ? { redact } : {}),
     };
 }
 const TASK_KEYS = new Set([
@@ -144,9 +163,22 @@ const TASK_KEYS = new Set([
     "engine",
     "model",
     "timeoutMs",
+    "maxSteps",
+    "maxRetries",
     "llm",
+    "redact",
+]);
+const SHARED_KEYS = new Set([
+    "version",
+    "name",
+    "description",
+    "when_to_use",
+    "tags",
+    "schedule",
+    "enabled",
+    // `redact:` is target-agnostic: every kind funnels through the same log sink.
+    "redact",
 ]);
-const SHARED_KEYS = new Set(["version", "name", "description", "when_to_use", "tags", "schedule", "enabled"]);
 function requireVersion(data, id, filePath) {
     if (data.version === TASK_SCHEMA_VERSION)
         return;
@@ -258,9 +290,54 @@ function readTimeout(value, filePath) {
         return undefined;
     if (value === null)
         return null;
-    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+    // The ceiling is `setTimeout`'s, not a policy: a larger delay overflows and
+    // fires immediately, turning a generous timeout into an instant abort.
+    if (typeof value === "number" && Number.isInteger(value) && value > 0 && value <= TASK_MAX_TIMEOUT_MS)
         return value;
-    throw new UsageError(`Key "timeoutMs" must be a positive integer or null. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    throw new UsageError(`Key "timeoutMs" must be an integer from 1 through ${TASK_MAX_TIMEOUT_MS}, or null. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}
+/**
+ * Read the `redact:` opt-in list — environment variable NAMES whose values are
+ * scrubbed from this task's persisted log (#755).
+ *
+ * A value that looks like a secret rather than a name is rejected outright, not
+ * silently accepted: a literal in a task file would be indexed, searchable and
+ * printed verbatim by `akm show`, so accepting one would leak the secret
+ * through a wider channel than the redaction closes.
+ */
+function readRedactNames(value, filePath) {
+    if (value === undefined || value === null)
+        return undefined;
+    const invalid = (detail) => {
+        throw new UsageError(`Key "redact" ${detail}. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    };
+    if (!Array.isArray(value))
+        return invalid("must be a list of environment variable names");
+    if (value.length > TASK_MAX_REDACT_NAMES) {
+        return invalid(`accepts at most ${TASK_MAX_REDACT_NAMES} names (got ${value.length})`);
+    }
+    const names = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || !WORKFLOW_ENV_VAR_NAME_PATTERN.test(entry)) {
+            return invalid(`takes environment variable NAMES only (matching ${WORKFLOW_ENV_VAR_NAME_PATTERN.source}), not values — ` +
+                `got ${JSON.stringify(entry)}. A secret written here would be indexed and printed by \`akm show\``);
+        }
+        if (!names.includes(entry))
+            names.push(entry);
+    }
+    return names.length > 0 ? names : undefined;
+}
+function readBoundedInteger(value, key, minimum, maximum, filePath) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= minimum &&
+        (maximum === undefined || value <= maximum)) {
+        return value;
+    }
+    const range = maximum === undefined ? `at least ${minimum}` : `from ${minimum} through ${maximum}`;
+    throw new UsageError(`Key "${key}" must be an integer ${range}. File: ${filePath}`, "INVALID_FLAG_VALUE");
 }
 function readLlmOverrides(value, filePath) {
     if (value === undefined)

package/dist/tasks/runner.js

@@ -15,7 +15,10 @@
  *   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 → `runWorkflowSteps({ target: ref, params })`
+ *        • workflow → `runWorkflowSteps({ target: ref, params, signal, … })`
+ *                     under a whole-run timeout (issue 11): an unattended run
+ *                     gets the same abort path `akm workflow run --timeout`
+ *                     gives an interactive one.
  *        • 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`
@@ -28,6 +31,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { armAbortDeadline } from "../core/abort-deadline.js";
 import { shouldSkipUnactivatedTask } from "../core/activation-policy.js";
 import { assertNever } from "../core/assert.js";
 import { placementSpecFor } from "../core/asset/asset-placement.js";
@@ -36,7 +40,7 @@ import { loadConfig } from "../core/config/config.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 { redactCredentialPatterns, redactSensitiveText } from "../core/redaction.js";
 import { withStateDb } from "../core/state-db.js";
 import { runManagedSubprocess } from "../core/subprocess.js";
 import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../integrations/agent/engine-fallback.js";
@@ -48,6 +52,7 @@ import { resolveAssetPath } from "../sources/resolve.js";
 import { decodeTaskHistoryMetadata, finalizeTaskHistoryAttempt, getTaskHistory, queryTaskHistory, reserveTaskHistoryAttempt, upsertTaskHistory, } from "../storage/repositories/task-history-repository.js";
 import { runWorkflowSteps } from "../workflows/exec/run-workflow.js";
 import { findBareAkmExecutableIndex } from "./command-executable.js";
+import { collectTaskLogSensitiveValues } from "./log-redaction.js";
 import { parseTaskDocument } from "./parser.js";
 import { resolveAkmInvocation } from "./resolve-akm-bin.js";
 import { validateTaskId } from "./task-id.js";
@@ -109,6 +114,7 @@ export async function runTask(id, options) {
                 logPath,
                 fileText: `${disabledLine}\n`,
                 dbLines: [{ line: disabledLine }],
+                redactNames: task.redact,
             });
             appendHistory(result, attempt.historyReserved);
             return result;
@@ -121,6 +127,8 @@ export async function runTask(id, options) {
                 now,
                 runWorkflowStepsImpl,
                 historyReserved: attempt.historyReserved,
+                ...(options.setTimeoutFn ? { setTimeoutFn: options.setTimeoutFn } : {}),
+                ...(options.clearTimeoutFn ? { clearTimeoutFn: options.clearTimeoutFn } : {}),
             });
         }
         if (task.target.kind === "command") {
@@ -225,6 +233,7 @@ async function runCommandTask(input) {
         logPath,
         fileText: `${logLines.join("\n")}\n`,
         dbLines,
+        redactNames: task.redact,
     });
     const status = exitCode === 0 ? "completed" : "failed";
     const result = {
@@ -248,14 +257,53 @@ function resolveNestedAkmCommand(cmd) {
     return [...cmd.slice(0, akmIndex), ...resolveAkmInvocation().argv, ...cmd.slice(akmIndex + 1)];
 }
 // ── workflow target ─────────────────────────────────────────────────────────
+/**
+ * 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;
 async function runWorkflowTask(input) {
     const { task, logPath, startedAt, now, runWorkflowStepsImpl, historyReserved } = input;
     if (task.target.kind !== "workflow")
         throw new Error("invariant: workflow target");
-    const ref = parseRefInput(task.target.ref);
+    const workflowTarget = task.target;
+    const ref = parseRefInput(workflowTarget.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");
-    }
+        throw new NotFoundError(`Task "${task.id}" workflow target must be a workflow ref (got "${workflowTarget.ref}").`, "WORKFLOW_NOT_FOUND");
+    }
+    // Unset → the unattended default; `null` → the explicit no-timeout opt-out.
+    const timeoutMs = workflowTarget.timeoutMs === undefined ? DEFAULT_WORKFLOW_TASK_TIMEOUT_MS : workflowTarget.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.id}" timed out after ${timeoutMs}ms.`,
+        ...(input.setTimeoutFn ? { setTimeoutFn: input.setTimeoutFn } : {}),
+        ...(input.clearTimeoutFn ? { clearTimeoutFn: input.clearTimeoutFn } : {}),
+    });
     let detail;
     let gateError;
     let error;
@@ -263,7 +311,13 @@ async function runWorkflowTask(input) {
     // task must leave the same trace rather than silently using a chosen engine.
     let runWarnings = [];
     try {
-        const execution = await runWorkflowStepsImpl({ target: task.target.ref, params: task.target.params });
+        const execution = await runWorkflowStepsImpl({
+            target: workflowTarget.ref,
+            params: workflowTarget.params,
+            signal: controller.signal,
+            ...(workflowTarget.maxSteps !== undefined ? { maxSteps: workflowTarget.maxSteps } : {}),
+            ...(workflowTarget.maxRetries !== undefined ? { maxRetries: workflowTarget.maxRetries } : {}),
+        });
         detail = execution.run;
         runWarnings = execution.warnings ?? [];
         if (execution.gateRejection) {
@@ -275,13 +329,37 @@ async function runWorkflowTask(input) {
             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 = error || gateError ? "failed" : mapWorkflowStatus(detail?.status);
+    const status = failure ? "failed" : mapWorkflowStatus(detail?.status);
     const log = renderWorkflowLog({
         task,
         detail,
-        error: error ?? (gateError ? new Error(gateError) : undefined),
+        error: failure,
         warnings: runWarnings,
+        ...(timedOutAfterMs !== undefined ? { timedOutAfterMs } : {}),
     });
     persistRunLog({
         taskId: task.id,
@@ -290,6 +368,7 @@ async function runWorkflowTask(input) {
         logPath,
         fileText: log.fileText,
         dbLines: log.dbLines,
+        redactNames: task.redact,
     });
     const result = {
         id: task.id,
@@ -301,7 +380,7 @@ async function runWorkflowTask(input) {
         target: { kind: "workflow", ref: task.target.ref },
         detail: {
             runId: detail?.id,
-            ...(error ? { error: error.message } : gateError ? { error: gateError } : {}),
+            ...(failure ? { error: failure.message } : {}),
         },
     };
     appendHistory(result, historyReserved);
@@ -345,6 +424,9 @@ function renderWorkflowLog(input) {
     ];
     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}` });
@@ -432,6 +514,7 @@ async function runPromptTask(input) {
         logPath,
         fileText: log.fileText,
         dbLines: log.dbLines,
+        redactNames: task.redact,
     });
     const status = result.ok ? "completed" : "failed";
     const out = {
@@ -535,11 +618,56 @@ function streamLines(text, stream, level) {
  * The DB write is best-effort, mirroring {@link appendHistory}: an unwritable
  * logs.db must never fail a task run.
  */
+/**
+ * Exact secret values to scrub from this run's persisted output (#755).
+ *
+ * Best-effort by construction: this runs on the persistence path of a run that
+ * has already finished, so a config that will not load must degrade to
+ * "pattern-based redaction only" rather than fail the run. It does NOT degrade
+ * to "log it anyway with no redaction at all" — `redactCredentialPatterns`
+ * still runs unconditionally in the caller.
+ */
+function taskLogSensitiveValues(redactNames) {
+    try {
+        return collectTaskLogSensitiveValues({
+            env: process.env,
+            config: loadConfig(),
+            declaredNames: redactNames,
+        });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        // No config — the name heuristic and the task's own `redact:` list still apply.
+        try {
+            return collectTaskLogSensitiveValues({ env: process.env, declaredNames: redactNames });
+        }
+        catch (fallbackError) {
+            rethrowIfTestIsolationError(fallbackError);
+            return [];
+        }
+    }
+}
 function persistRunLog(input) {
-    const fileText = redactCredentialPatterns(input.fileText);
-    const dbLines = input.dbLines.map((entry) => ({ ...entry, line: redactCredentialPatterns(entry.line) }));
+    // Two arms, and both are needed. `redactCredentialPatterns` catches
+    // credential SHAPES nobody listed; the exact-value pass catches configured
+    // secrets whose value is shaped like nothing in particular (#755). The
+    // command target had only the first, so a scheduled command that echoed an
+    // ordinary-looking secret persisted it verbatim to both sinks. Applying the
+    // exact pass here — the one sink all three target kinds funnel through —
+    // covers every arm once rather than per-arm; prompt/workflow runs already
+    // scrub upstream, and redaction is idempotent, so the overlap is free.
+    const sensitive = taskLogSensitiveValues(input.redactNames);
+    const scrub = (text) => sensitive.length > 0
+        ? redactSensitiveText(redactCredentialPatterns(text), sensitive)
+        : redactCredentialPatterns(text);
+    const fileText = scrub(input.fileText);
+    const dbLines = input.dbLines.map((entry) => ({ ...entry, line: scrub(entry.line) }));
     if (input.logPath) {
         try {
+            // Written at the process umask. #756 pinned 0600/0700 here; that went out
+            // with the rest of akm's permission enforcement (#791) — the operator owns
+            // the mode of their own data directory, and akm neither sets nor reports
+            // on it.
             fs.mkdirSync(path.dirname(input.logPath), { recursive: true });
             fs.writeFileSync(input.logPath, fileText);
         }

package/dist/tasks/schema.js

@@ -12,7 +12,35 @@
  * Tasks are stored as pure YAML files at `<stash>/tasks/<id>.yml`. Multi-line
  * inline prompts use a YAML block scalar (`prompt: |`).
  */
+import { parse as parseYaml } from "yaml";
+import { WORKFLOW_MAX_EXEC_PASS_ENV, WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/resource-limits.js";
 export const TASK_SCHEMA_VERSION = 2;
+/** The ONE recognized on-disk task extension (spec §6 task row). */
+export const TASK_EXTENSION = ".yml";
+/**
+ * The near-miss spelling. `.yaml` is NOT a task extension: the indexer's
+ * `tasks` matcher (`indexer/walk/matchers.ts`) gates on `.yml`, so a
+ * `tasks/<id>.yaml` file is never indexed, never scheduled, and never runs.
+ * It is recognized HERE only so lint can say so out loud instead of walking
+ * past it (issue #760).
+ */
+export const TASK_NEAR_MISS_EXTENSION = ".yaml";
+/**
+ * Largest expressible `timeoutMs` — `setTimeout`'s 32-bit signed ceiling
+ * (2^31-1, ~24.8 days). A larger delay overflows and fires almost immediately,
+ * which would silently abort a run seconds after it started instead of hours
+ * later. One definition with the workflow bound (`WORKFLOW_MAX_TIMEOUT_MS`) —
+ * it is a platform fact, not a per-surface policy. Mirrored as `maximum` on
+ * `timeoutMs` in `schemas/akm-task.json`.
+ */
+export const TASK_MAX_TIMEOUT_MS = WORKFLOW_MAX_TIMEOUT_MS;
+/**
+ * Most names a task's `redact:` list may carry. Shares its bound with exec
+ * units' `pass_env:` — both are "name the one or two the defaults miss", not a
+ * way to declare the whole environment secret. Mirrored as `maxItems` on
+ * `redact` in `schemas/akm-task.json`.
+ */
+export const TASK_MAX_REDACT_NAMES = WORKFLOW_MAX_EXEC_PASS_ENV;
 /**
  * Lint-level shape problems for a parsed task YAML mapping: the field rules
  * `src/tasks/parser.ts` enforces at load time, phrased as diagnostics. The ONE
@@ -36,3 +64,40 @@ export function taskFieldProblems(data) {
         problems.push("enabled (must be a boolean when present)");
     return problems;
 }
+/**
+ * Parse a task YAML document into a plain mapping. Non-mapping documents (a
+ * scalar, a sequence, an empty file) are NOT a parse failure — they parse fine
+ * and simply carry no fields, which the field rules above already describe.
+ *
+ * The ONE parse used by all three task-lint surfaces (`commands/lint/index.ts`'s
+ * akm sweep, the `akm` adapter's `validate`, and the `akm-task` adapter) so a
+ * malformed file cannot be a finding on one surface and silence on another.
+ */
+export function parseTaskYaml(raw) {
+    try {
+        const doc = parseYaml(raw);
+        if (doc && typeof doc === "object" && !Array.isArray(doc))
+            return { ok: true, data: doc };
+        return { ok: true, data: {} };
+    }
+    catch (e) {
+        // yaml's errors carry a multi-line source excerpt; keep the first line so
+        // the diagnostic stays one readable finding.
+        const message = (e instanceof Error ? e.message : String(e)).split("\n")[0]?.trim() ?? "unknown parse error";
+        return { ok: false, data: {}, error: message };
+    }
+}
+/** The `invalid-task-yaml` detail for a file whose YAML could not be parsed. */
+export function taskYamlParseDetail(error) {
+    return `task YAML does not parse: ${error}`;
+}
+/**
+ * The `invalid-task-yaml` detail for a task file using the `.yaml` near-miss
+ * spelling. See {@link TASK_NEAR_MISS_EXTENSION} for why this is an error and
+ * not a style nit.
+ */
+export function taskExtensionDetail(relPath) {
+    const base = relPath.replace(/\.yaml$/i, "");
+    return (`task file uses the ${TASK_NEAR_MISS_EXTENSION} extension; akm recognizes tasks only as ` +
+        `${TASK_EXTENSION}, so this file is never indexed or scheduled — rename it to ${base}${TASK_EXTENSION}.`);
+}

package/dist/workflows/concurrency-policy.js

@@ -2,7 +2,16 @@
 // 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 os from "node:os";
-export const WORKFLOW_MAX_CONCURRENCY_CEILING = 64;
+import { isLoopbackEndpoint } from "../core/loopback.js";
+import { WORKFLOW_MAX_CONCURRENCY } from "./resource-limits.js";
+/**
+ * Run-level ceiling on `workflow.maxConcurrency`. It is deliberately the SAME
+ * value the frozen-plan decoder enforces on `execution.maxConcurrency` and on
+ * per-step `map.concurrency` — a clamp above the decoder's bound would freeze
+ * plans the decoder then rejects — so it reads the single shared constant
+ * (`./resource-limits`) rather than repeating the literal.
+ */
+export const WORKFLOW_MAX_CONCURRENCY_CEILING = WORKFLOW_MAX_CONCURRENCY;
 export function cpuDerivedUnitConcurrency(cpuCount = os.cpus()?.length ?? 4) {
     return Math.min(16, Math.max(1, cpuCount - 2));
 }
@@ -13,3 +22,88 @@ export function clampMaxConcurrency(value) {
 export function workflowMaxConcurrency(configured, cpuCount = os.cpus()?.length ?? 4) {
     return configured === undefined ? cpuDerivedUnitConcurrency(cpuCount) : clampMaxConcurrency(configured);
 }
+// ── Fan-out defaults ─────────────────────────────────────────────────────────
+//
+// Four independent limits clamp a `map` step's real width, and the effective
+// value is their minimum:
+//
+//   1. the step's own `map.concurrency`            (this file's default below)
+//   2. the run's frozen `execution.maxConcurrency` ({@link workflowMaxConcurrency})
+//   3. the selected LLM engine's frozen concurrency ({@link defaultLlmEngineConcurrency})
+//   4. the CURRENT host's CPU safety cap           ({@link cpuDerivedUnitConcurrency})
+//
+// (1) and (3) both defaulted to 1 before 0.9.1, which made every fan-out serial
+// unless the author opted in at BOTH layers — so (2) and (4), the limits that
+// actually encode machine capacity, never bound anything. The defaults below
+// replace those two 1s. They are deliberately modest rather than "as wide as
+// the host allows": a `map` is independent by construction, but its units call
+// out to rate-limited providers and RAM-hungry agent processes, so the value
+// that a plan freezes should be one a laptop and a CI box can both survive.
+/**
+ * Default width of a `map` step that declares no `concurrency:` (0.9.1+).
+ *
+ * 4 is chosen over the host cap on purpose. It is a real, predictable speedup
+ * (4× on any fan-out longer than four items) while staying below
+ * {@link cpuDerivedUnitConcurrency} on every machine with ≥6 cores, so the
+ * frozen number — not the host — is what an author reasons about, and a plan
+ * frozen on a 32-core CI box behaves the same when it resumes on a laptop.
+ *
+ * Overridable in both directions:
+ *   - per step: `map.concurrency: <n>` (an explicit `1` still means serial),
+ *   - per install: `workflow.defaultMapConcurrency` — set it to `1` to restore
+ *     the pre-0.9.1 serial default for every workflow at once.
+ */
+export const DEFAULT_MAP_CONCURRENCY = 4;
+/**
+ * Default `engines.<name>.concurrency` for an LLM engine on a LOOPBACK
+ * endpoint. Stays at 1, matching `getDefaultLlmConcurrency`
+ * (`src/indexer/indexer.ts`) and AGENTS.md's "lowest common denominator — a
+ * slow local model on a single-threaded server" rule. A local model server
+ * (LM Studio, Ollama) holds ONE loaded model; parallel inference triggers
+ * reload thrash and HTTP 500s, which is a hard failure, not a slow one.
+ */
+export const DEFAULT_LOCAL_LLM_ENGINE_CONCURRENCY = 1;
+/**
+ * Default `engines.<name>.concurrency` for an LLM engine on a REMOTE endpoint.
+ *
+ * Deliberately equal to {@link DEFAULT_MAP_CONCURRENCY} so this limit does not
+ * silently re-serialize a fan-out the author already asked for: the step's own
+ * `concurrency:` stays the number that decides. Indexing's remote default is a
+ * lower 2 because indexing fans out implicitly over the whole stash; a
+ * workflow `map` is an explicit, bounded, author-declared fan-out, and four
+ * concurrent completions sit far inside any hosted provider's entry tier.
+ * Rate-limited installs set `engines.<name>.concurrency` to pin their own.
+ */
+export const DEFAULT_REMOTE_LLM_ENGINE_CONCURRENCY = 4;
+// ── Loopback classification ──────────────────────────────────────────────────
+//
+// Everything above turns on ONE question: does this endpoint name a model
+// server running on THIS machine? The classifier lives in `core/loopback.ts`
+// (shared with the indexer's LLM pool default); the re-export keeps this
+// module the policy surface workflow callers and the boundary-case table in
+// `tests/workflows/concurrency-defaults.test.ts` import from. The check is
+// purely syntactic — no DNS, no interface list — so freeze produces the same
+// plan on a laptop, on CI, and on a machine with no network.
+export { isLoopbackEndpoint, isLoopbackHost } from "../core/loopback.js";
+/**
+ * Concurrency to freeze for an LLM engine. An explicit
+ * `engines.<name>.concurrency` always wins (clamped into the decoder's
+ * `[1, 64]` range so a fat-fingered config cannot freeze an unloadable plan);
+ * otherwise the endpoint decides.
+ */
+export function defaultLlmEngineConcurrency(endpoint, configured) {
+    if (typeof configured === "number" && Number.isFinite(configured))
+        return clampMaxConcurrency(configured);
+    return isLoopbackEndpoint(endpoint) ? DEFAULT_LOCAL_LLM_ENGINE_CONCURRENCY : DEFAULT_REMOTE_LLM_ENGINE_CONCURRENCY;
+}
+/**
+ * Width to freeze for a `map` step that declared no `concurrency:`. `configured`
+ * is `workflow.defaultMapConcurrency`; unset means {@link DEFAULT_MAP_CONCURRENCY}.
+ * An explicit `map.concurrency` never reaches this function — the caller keeps
+ * "author wrote 1" distinguishable from "author wrote nothing".
+ */
+export function defaultMapConcurrency(configured) {
+    return configured === undefined || !Number.isFinite(configured)
+        ? DEFAULT_MAP_CONCURRENCY
+        : clampMaxConcurrency(configured);
+}