akm-cli 0.9.0 → 0.9.1-beta.2

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";
@@ -45,11 +49,13 @@ 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 { decodeTaskHistoryMetadata, finalizeTaskHistoryAttempt, getTaskHistory, queryTaskHistory, reserveTaskHistoryAttempt, upsertTaskHistory, } from "../storage/repositories/task-history-repository.js";
+import { decodeTaskHistoryMetadata, finalizeTaskHistoryAttempt, getTaskHistory, getTaskHistoryRuns, 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 { scheduledTaskContextEnv } from "./scheduler-invocation.js";
 import { validateTaskId } from "./task-id.js";
 export const INVALID_TASK_ATTEMPT_ID = "_invalid-task-id";
 export async function runTask(id, options) {
@@ -109,6 +115,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 +128,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") {
@@ -167,7 +176,8 @@ async function runCommandTask(input) {
         throw new Error("invariant: command target");
     const { cmd } = task.target;
     const spawnCmd = resolveNestedAkmCommand(cmd);
-    const timeoutMs = task.timeoutMs !== undefined ? task.timeoutMs : null;
+    // Unset → the unattended default; `null` → the explicit no-timeout opt-out.
+    const timeoutMs = task.timeoutMs !== undefined ? task.timeoutMs : DEFAULT_SCHEDULED_TASK_TIMEOUT_MS;
     const header = `[akm task] task=${task.id} kind=command cmd=${cmd.join(" ")}`;
     const logLines = [header];
     const dbLines = [{ line: header }];
@@ -225,6 +235,7 @@ async function runCommandTask(input) {
         logPath,
         fileText: `${logLines.join("\n")}\n`,
         dbLines,
+        redactNames: task.redact,
     });
     const status = exitCode === 0 ? "completed" : "failed";
     const result = {
@@ -248,22 +259,86 @@ 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;
+/**
+ * The same unattended default for command and prompt tasks.
+ *
+ * The reasoning above is about SCHEDULED runs, not about workflows: nobody is
+ * watching, and one wedged run silently stops the schedule. Command tasks
+ * defaulted to `null` (no kill timer) and prompt tasks inherited
+ * DEFAULT_AGENT_TIMEOUT_MS, also null — so a hung `curl`, a prompting agent
+ * waiting on stdin, or a stuck engine wedged the task forever while the
+ * workflow arm was protected. Same value, same opt-out: an explicit
+ * `timeoutMs:` wins, and `timeoutMs: null` restores unbounded.
+ */
+export const DEFAULT_SCHEDULED_TASK_TIMEOUT_MS = DEFAULT_WORKFLOW_TASK_TIMEOUT_MS;
 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;
     // The prompt path logs the engine-fallback announcement; a workflow-backed
     // task must leave the same trace rather than silently using a chosen engine.
     let runWarnings = [];
+    // Stamp task-runner provenance for the duration of the run (DRIFT-6), as the
+    // command and prompt arms do. This arm executes IN-PROCESS, so the stamp goes
+    // on process.env — child akm invocations made by workflow steps inherit it.
+    // Without it, workflow-task traffic was recorded as user demand. A more
+    // specific stamp already present wins, matching the command arm.
+    const priorEventSource = process.env.AKM_EVENT_SOURCE;
+    process.env.AKM_EVENT_SOURCE = priorEventSource ?? "task";
     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 +350,41 @@ async function runWorkflowTask(input) {
             throw e;
         error = e instanceof Error ? e : new Error(String(e));
     }
+    finally {
+        deadline.disarm();
+        if (priorEventSource === undefined)
+            delete process.env.AKM_EVENT_SOURCE;
+        else
+            process.env.AKM_EVENT_SOURCE = priorEventSource;
+    }
+    // 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 +393,7 @@ async function runWorkflowTask(input) {
         logPath,
         fileText: log.fileText,
         dbLines: log.dbLines,
+        redactNames: task.redact,
     });
     const result = {
         id: task.id,
@@ -301,7 +405,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 +449,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}` });
@@ -401,7 +508,10 @@ async function runPromptTask(input) {
         runner = {
             ...runner,
             profile: { ...runner.profile, ...(model ? { model, modelIsExact: true } : {}) },
-            ...(promptTarget.timeoutMs !== undefined ? { timeoutMs: promptTarget.timeoutMs } : {}),
+            // Unset → the unattended default (DEFAULT_AGENT_TIMEOUT_MS is null, which
+            // let a prompting or wedged agent CLI hang the schedule); `null` → the
+            // explicit no-timeout opt-out.
+            timeoutMs: promptTarget.timeoutMs !== undefined ? promptTarget.timeoutMs : DEFAULT_SCHEDULED_TASK_TIMEOUT_MS,
         };
     }
     const promptText = await resolvePromptText(task, stashDir);
@@ -412,7 +522,13 @@ async function runPromptTask(input) {
         // 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 },
+        //
+        // The agent child env is built from an allowlist, not inherited, so the
+        // scheduler's AKM_* directory context was dropped here — an agent's `akm`
+        // sub-commands then targeted the DEFAULT stash and DB rather than the
+        // ones the scheduled run was configured for. The command arm keeps this
+        // context because it inherits process.env; forward it explicitly.
+        env: { AKM_EVENT_SOURCE: "task", ...scheduledTaskContextEnv(), ...agentOptions?.env },
     }, {
         ...(input.runAgentImpl ? { runAgent: input.runAgentImpl } : {}),
         llm: async (spec, prompt, options) => {
@@ -432,6 +548,7 @@ async function runPromptTask(input) {
         logPath,
         fileText: log.fileText,
         dbLines: log.dbLines,
+        redactNames: task.redact,
     });
     const status = result.ok ? "completed" : "failed";
     const out = {
@@ -515,12 +632,49 @@ function resolveTaskLogPath(logDir, taskId, startedAtIso) {
         return "";
     }
 }
+/**
+ * Redact logs.db rows against the SAME contiguous text the file sink sees.
+ *
+ * The rows arrive already split on "\n" (see {@link streamLines}), but the
+ * redaction needles are whole env values — and a needle containing a newline
+ * can never match inside a single line. Scrubbing row-by-row therefore left
+ * multi-line secrets (PEM keys, multi-line service-account credentials) intact
+ * in logs.db while the flat .log was correctly scrubbed, defeating all three
+ * tiers including the explicit `redact:` opt-in.
+ *
+ * Consecutive rows sharing a stream and level are rejoined, scrubbed as one
+ * string, and re-split, so a needle spanning lines matches. Collapsing a
+ * multi-line secret into a single [REDACTED] row is the intended outcome.
+ */
+export function scrubDbLines(dbLines, scrub) {
+    const out = [];
+    for (let i = 0; i < dbLines.length;) {
+        const { stream, level } = dbLines[i];
+        let end = i;
+        while (end < dbLines.length && dbLines[end].stream === stream && dbLines[end].level === level)
+            end++;
+        const joined = dbLines
+            .slice(i, end)
+            .map((entry) => entry.line)
+            .join("\n");
+        for (const line of scrub(joined).split("\n")) {
+            if (line.length > 0)
+                out.push({ stream, level, line });
+        }
+        i = end;
+    }
+    return out;
+}
 /** Split captured pipe output into per-line logs.db rows (blank lines dropped). */
 function streamLines(text, stream, level) {
-    return text
+    return (text
         .split("\n")
+        // Windows child output is CRLF-terminated. Splitting on "\n" alone left a
+        // trailing "\r" on every row and turned blank CRLF lines into phantom
+        // rows containing just "\r" (length 1 passes the filter below).
+        .map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line))
         .filter((line) => line.length > 0)
-        .map((line) => ({ stream, level, line }));
+        .map((line) => ({ stream, level, line })));
 }
 /**
  * Persist a finished run's log: the flat text file (so `log_path` in
@@ -535,11 +689,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 = scrubDbLines(input.dbLines, scrub);
     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);
         }
@@ -692,6 +891,12 @@ export function readTaskHistory(options = {}) {
         if (options.limit === 0)
             return [];
         if (options.id) {
+            // An id-scoped query used the single-row helper, so `--limit` was silently
+            // discarded and `akm task history --id X --limit 20` always returned one
+            // run. The CLI documents --limit as "Maximum rows to return"; honour it.
+            if (options.limit !== undefined && options.limit > 0) {
+                return getTaskHistoryRuns(db, options.id, options.limit).map(taskHistoryRowToResult);
+            }
             const row = getTaskHistory(db, options.id);
             return row ? [taskHistoryRowToResult(row)] : [];
         }

package/dist/tasks/scheduler-invocation.js

@@ -14,6 +14,25 @@ export const SCHEDULED_TASK_CONTEXT_KEYS = [
     "AKM_CACHE_DIR",
     "AKM_STATE_DIR",
 ];
+/**
+ * The AKM_* directory context currently in effect, as a plain env fragment.
+ *
+ * A scheduled run restores these into `process.env` from its
+ * `--scheduler-context` descriptor precisely because such installs have
+ * non-default directories. Paths that build a child environment from an
+ * allowlist rather than inheriting (the agent spawn) must forward this
+ * explicitly, or the child's `akm` sub-commands silently target the default
+ * stash and DB.
+ */
+export function scheduledTaskContextEnv(env = process.env) {
+    const out = {};
+    for (const key of SCHEDULED_TASK_CONTEXT_KEYS) {
+        const value = env[key];
+        if (value)
+            out[key] = value;
+    }
+    return out;
+}
 export const SCHEDULER_CONTEXT_ARG = "--scheduler-context";
 /** Resolve the complete non-secret AKM directory context captured by schedulers. */
 export function resolveScheduledTaskContext(env = process.env, platform = process.platform) {

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
@@ -24,8 +52,28 @@ export const TASK_SCHEMA_VERSION = 2;
  * at runtime with TASK_SCHEMA_VERSION_UNSUPPORTED). `schemas/akm-task.json`
  * agrees with the parser: `required: [version, schedule]`, `version:
  * {const: 2}`, `enabled` optional but boolean. Target-arity rules stay with
- * each caller (they legitimately differ: at-least-one vs exactly-one).
+ * each caller (they legitimately differ: at-least-one vs exactly-one), but
+ * what COUNTS as a target is shared — see {@link isPresentTarget}.
+ */
+/**
+ * Whether a task-target field counts as declared.
+ *
+ * The arity rules differ between the two linters, but the presence test must
+ * not: the runtime parser treats `""` as absent, so a key-existence check let
+ * `workflow: ""` lint clean and then die with MISSING_REQUIRED_ARGUMENT. An
+ * array target (`command`) counts only when it has entries, for the same
+ * reason. Kept beside {@link taskFieldProblems} so all three definitions of
+ * "valid task" stay in one file.
  */
+export function isPresentTarget(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === "string")
+        return value.trim() !== "";
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
 export function taskFieldProblems(data) {
     const problems = [];
     if (data.version !== TASK_SCHEMA_VERSION)
@@ -36,3 +84,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/text-import-hook.mjs

@@ -16,7 +16,7 @@
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
-const TEXT_EXTENSIONS = new Set([".md", ".xml", ".txt", ".sql", ".yaml", ".yml"]);
+const TEXT_EXTENSIONS = new Set([".md", ".xml", ".txt", ".sql", ".yaml", ".yml", ".html"]);
 
 function isTextImport(url, importAttributes) {
   if (importAttributes && importAttributes.type === "text") return true;

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);
+}