akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

package/dist/tasks/runner.js

@@ -19,7 +19,7 @@
  *        • prompt   → `executeRunner(engine, prompt, { stdio: "captured" })`
  *   5. Capture stdout / stderr as structured rows in logs.db (task_logs) and,
  *      transitionally, as a flat text tail at `<cacheDir>/tasks/logs/<id>/<ts>.log`
- *      (see docs/technical/logs-audit.md).
+ *      (per the #579 logs audit).
  *   6. Write a history row to state.db task_history table.
  *
  * Returns a structured result so the CLI handler can shape it for `output()`
@@ -28,19 +28,19 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { shouldSkipUnactivatedTask } from "../core/activation-policy.js";
 import { assertNever } from "../core/assert.js";
-import { parseAssetRef } from "../core/asset/asset-ref.js";
-import { resolveStashDir } from "../core/common.js";
+import { parseRefInput } from "../core/asset/resolve-ref.js";
 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 { withStateDb } from "../core/state-db.js";
+import { runManagedSubprocess } from "../core/subprocess.js";
 import { resolveEngine, resolveLlmEngineUse } from "../integrations/agent/engine-resolution.js";
 import { resolveModel } from "../integrations/agent/model-aliases.js";
 import { executeRunner } from "../integrations/agent/runner-dispatch.js";
 import { chatCompletion } from "../llm/client.js";
-import { spawn } from "../runtime.js";
 import { resolveAssetPath } from "../sources/resolve.js";
 import { decodeTaskHistoryMetadata, finalizeTaskHistoryAttempt, getTaskHistory, queryTaskHistory, reserveTaskHistoryAttempt, upsertTaskHistory, } from "../storage/repositories/task-history-repository.js";
 import { startWorkflowRun } from "../workflows/runtime/runs.js";
@@ -49,7 +49,7 @@ import { parseTaskDocument } from "./parser.js";
 import { resolveAkmInvocation } from "./resolve-akm-bin.js";
 import { validateTaskId } from "./task-id.js";
 export const INVALID_TASK_ATTEMPT_ID = "_invalid-task-id";
-export async function runTask(id, options = {}) {
+export async function runTask(id, options) {
     const runAgentImpl = options.runAgentImpl;
     const startWorkflowRunImpl = options.startWorkflowRunImpl ?? startWorkflowRun;
     const now = options.now ?? (() => new Date());
@@ -74,7 +74,7 @@ export async function runTask(id, options = {}) {
     const startedAt = attempt.startedAt;
     let failureReason = "task_load_failed";
     try {
-        const stashDir = options.stashDir ?? resolveStashDir();
+        const stashDir = options.stashDir;
         const filePath = await resolveAssetPath(stashDir, "task", id);
         const yaml = fs.readFileSync(filePath, "utf8");
         failureReason = "task_parse_failed";
@@ -82,7 +82,7 @@ export async function runTask(id, options = {}) {
         failureReason = "task_dispatch_failed";
         const startedIso = startedAt.toISOString();
         const logPath = resolveTaskLogPath(options.logDir, id, startedIso);
-        if (!task.enabled && options.scheduled === true) {
+        if (shouldSkipUnactivatedTask({ enabled: task.enabled, scheduled: options.scheduled === true })) {
             const finishedAt = finishAttempt(startedAt, now());
             const disabledTarget = task.target.kind === "workflow"
                 ? { kind: "workflow", ref: task.target.ref }
@@ -121,7 +121,16 @@ export async function runTask(id, options = {}) {
             });
         }
         if (task.target.kind === "command") {
-            return await runCommandTask({ task, logPath, startedAt, now, historyReserved: attempt.historyReserved });
+            return await runCommandTask({
+                task,
+                logPath,
+                startedAt,
+                now,
+                historyReserved: attempt.historyReserved,
+                ...(options.spawnFn ? { spawnFn: options.spawnFn } : {}),
+                ...(options.setTimeoutFn ? { setTimeoutFn: options.setTimeoutFn } : {}),
+                ...(options.clearTimeoutFn ? { clearTimeoutFn: options.clearTimeoutFn } : {}),
+            });
         }
         return await runPromptTask({
             task,
@@ -159,44 +168,29 @@ async function runCommandTask(input) {
     const header = `[akm tasks] task=${task.id} kind=command cmd=${cmd.join(" ")}`;
     const logLines = [header];
     const dbLines = [{ line: header }];
-    let stdout = "";
-    let stderr = "";
     let exitCode = null;
     try {
-        const proc = spawn(spawnCmd, {
-            stdin: "ignore",
-            stdout: "pipe",
-            stderr: "pipe",
+        // Managed spawn (src/core/subprocess.ts): process-GROUP kill so a timeout
+        // reaps the whole command tree (no orphans), and a SIGTERM→SIGKILL ladder
+        // so a child that ignores SIGTERM can't wedge the run forever.
+        const result = await runManagedSubprocess(spawnCmd, {
+            capture: true,
             cwd: process.env.HOME ?? os.tmpdir(),
             // Stamp task-runner provenance so any akm invocation in the command tree
             // records usage events as machine traffic, not user demand (DRIFT-6).
             // A more specific stamp already in the environment (e.g. improve's
             // AKM_EVENT_SOURCE=improve on its child spawns) still wins in children.
             env: { ...process.env, AKM_EVENT_SOURCE: process.env.AKM_EVENT_SOURCE ?? "task" },
+            timeoutMs,
+            ...(input.spawnFn ? { spawnFn: input.spawnFn } : {}),
+            ...(input.setTimeoutFn ? { setTimeoutFn: input.setTimeoutFn } : {}),
+            ...(input.clearTimeoutFn ? { clearTimeoutFn: input.clearTimeoutFn } : {}),
         });
-        let timer;
-        let timedOut = false;
-        if (timeoutMs !== null) {
-            timer = setTimeout(() => {
-                timedOut = true;
-                try {
-                    proc.kill("SIGTERM");
-                }
-                catch {
-                    /* ignore */
-                }
-            }, timeoutMs);
-        }
-        const [stdoutBuf, stderrBuf] = await Promise.all([
-            new Response(proc.stdout).text(),
-            new Response(proc.stderr).text(),
-        ]);
-        await proc.exited;
-        if (timer !== undefined)
-            clearTimeout(timer);
-        stdout = stdoutBuf;
-        stderr = stderrBuf;
-        exitCode = proc.exitCode ?? (timedOut ? 143 : 1);
+        // A synchronous spawn throw / exit rejection surfaces as spawn_error below.
+        if (result.spawnError)
+            throw result.spawnError;
+        const { stdout, stderr, timedOut } = result;
+        exitCode = result.exitCode ?? (timedOut ? 143 : 1);
         if (timedOut) {
             logLines.push(`timed_out=true timeout_ms=${timeoutMs}`);
             dbLines.push({ level: "error", line: `timed_out=true timeout_ms=${timeoutMs}` });
@@ -255,7 +249,7 @@ async function runWorkflowTask(input) {
     const { task, logPath, startedAt, now, startWorkflowRunImpl, historyReserved } = input;
     if (task.target.kind !== "workflow")
         throw new Error("invariant: workflow target");
-    const ref = parseAssetRef(task.target.ref);
+    const ref = parseRefInput(task.target.ref);
     if (ref.type !== "workflow") {
         throw new NotFoundError(`Task "${task.id}" workflow target must be a workflow ref (got "${task.target.ref}").`, "WORKFLOW_NOT_FOUND");
     }
@@ -448,7 +442,7 @@ async function resolvePromptText(task, stashDir) {
         return fs.readFileSync(filePath, "utf8");
     }
     // asset
-    const ref = parseAssetRef(src.ref);
+    const ref = parseRefInput(src.ref);
     const assetPath = await resolveAssetPath(stashDir, ref.type, ref.name);
     return fs.readFileSync(assetPath, "utf8");
 }

package/dist/tasks/validator.js

@@ -16,8 +16,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset/asset-ref.js";
-import { resolveStashDir } from "../core/common.js";
+import { parseRefInput } from "../core/asset/resolve-ref.js";
 import { loadConfig } from "../core/config/config.js";
 import { NotFoundError } from "../core/errors.js";
 import { resolveEngine } from "../integrations/agent/engine-resolution.js";
@@ -27,8 +26,8 @@ export async function validateTaskDocument(task, options) {
     // Schedule must parse and translate.
     parseSchedule(task.schedule, options.backend);
     if (task.target.kind === "workflow") {
-        const stashDir = options.stashDir ?? resolveStashDir();
-        const ref = parseAssetRef(task.target.ref);
+        const stashDir = options.stashDir;
+        const ref = parseRefInput(task.target.ref);
         if (ref.type !== "workflow") {
             throw new NotFoundError(`Task "${task.id}" workflow target must be a workflow ref (got "${task.target.ref}").`, "WORKFLOW_NOT_FOUND");
         }
@@ -52,8 +51,8 @@ export async function validateTaskDocument(task, options) {
     }
     const src = task.target.source;
     if (src.kind === "asset") {
-        const stashDir = options.stashDir ?? resolveStashDir();
-        const ref = parseAssetRef(src.ref);
+        const stashDir = options.stashDir;
+        const ref = parseRefInput(src.ref);
         await resolveAssetPath(stashDir, ref.type, ref.name);
     }
     else if (src.kind === "file") {

package/dist/workflows/authoring/authoring.js

@@ -4,9 +4,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import workflowTemplate from "../../assets/workflows/workflow-template.md" with { type: "text" };
-import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../../core/asset/asset-spec.js";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
+import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../../core/recognition-util.js";
 import { warn } from "../../core/warn.js";
 import { compileWorkflowProgram } from "../ir/compile.js";
 import { parseWorkflow } from "../parser.js";
@@ -83,7 +83,7 @@ export function createWorkflowAsset(input) {
     const normalizedName = normalizeWorkflowName(input.name);
     // The write target is DEFINITIVE — the canonical name plus the chosen format's
     // extension (`.yaml`/`.yml` for a program, `.md` for markdown). We deliberately
-    // do NOT go through `resolveAssetPathFromName`, which PROBES existing files and
+    // do NOT go through `assetPathForName`, which PROBES existing files and
     // would redirect a markdown create onto an existing `foo.yaml` (writing
     // markdown into a `.yaml`). Computing the target directly makes a markdown
     // create always write `.md`, so the finding-C cross-extension check below sees
@@ -93,10 +93,10 @@ export function createWorkflowAsset(input) {
     if (!isWithin(assetPath, typeRoot)) {
         throw new UsageError(`Resolved workflow path escapes the stash: "${normalizedName}"`, "PATH_ESCAPE_VIOLATION");
     }
-    // Codex round-3 finding C: a `workflow:<name>` ref is canonical across every
+    // Codex round-3 finding C: a `workflows/<name>` ref is canonical across every
     // recognized extension (`.md`/`.yaml`/`.yml`) and resolves `.md` BEFORE
     // `.yaml`. So creating `foo.yaml` while `foo.md` exists would return the ref
-    // `workflow:foo` that still starts the OLD markdown workflow — a silently
+    // `workflows/foo` that still starts the OLD markdown workflow — a silently
     // shadowed asset. Reject creation when ANY recognized extension already holds
     // the same canonical name, naming the existing file. A same-extension collision
     // (the target path itself exists) keeps the classic `--force` overwrite escape;
@@ -106,7 +106,7 @@ export function createWorkflowAsset(input) {
     const conflicting = existingPaths.find((p) => p !== assetPath);
     if (conflicting !== undefined) {
         throw new UsageError(`Workflow "${normalizedName}" already exists as ${path.relative(stashDir, conflicting)} — the ` +
-            `\`workflow:${normalizedName}\` ref resolves to that file, so creating this one would shadow it. ` +
+            `\`workflows/${normalizedName}\` ref resolves to that file, so creating this one would shadow it. ` +
             `Remove or rename the existing file first, or create the workflow under a different name.`, "RESOURCE_ALREADY_EXISTS");
     }
     if (fs.existsSync(assetPath) && !input.force) {
@@ -140,7 +140,7 @@ export function createWorkflowAsset(input) {
     fs.mkdirSync(path.dirname(assetPath), { recursive: true });
     fs.writeFileSync(assetPath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
     return {
-        ref: `workflow:${normalizedName}`,
+        ref: `workflows/${normalizedName}`,
         path: assetPath,
         stashDir,
     };
@@ -168,7 +168,7 @@ function readWorkflowSource(source, stashDir) {
 }
 function normalizeWorkflowName(name) {
     // Strip any recognized workflow extension (.md/.yaml/.yml) so the canonical
-    // name — and thus the `workflow:<name>` ref — is extension-free regardless of
+    // name — and thus the `workflows/<name>` ref — is extension-free regardless of
     // how the user spelled it. The chosen format is recovered from the raw suffix
     // by the caller (createWorkflowAsset).
     const normalized = canonicalizeWorkflowName(name
@@ -206,7 +206,7 @@ export function formatWorkflowErrors(path, errors) {
     return [heading, ...lines].join("\n");
 }
 /**
- * Validate a workflow by ref (`workflow:<name>`) or filesystem path.
+ * Validate a workflow filesystem path.
  *
  * Returns the parse result plus the source-relative path used. Throws
  * `UsageError` only when the target cannot be located on disk; parse
@@ -214,9 +214,6 @@ export function formatWorkflowErrors(path, errors) {
  * format them however they like.
  */
 export function validateWorkflowSource(target) {
-    if (target.startsWith("workflow:")) {
-        throw new UsageError(`validateWorkflowSource expects a filesystem path; resolve refs to paths in the caller before invoking.`);
-    }
     const resolved = path.resolve(target);
     if (!fs.existsSync(resolved)) {
         throw new UsageError(`Workflow file not found: "${target}".`);

package/dist/workflows/exec/brief.js

@@ -29,17 +29,19 @@
  * driven run of the same frozen plan produce byte-identical unit graphs — the
  * invariant R4 asserts.
  */
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { canonicalizeWorkflowName } from "../../core/asset/asset-spec.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
+import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
 import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
 import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
 import { assertRunParamsSatisfyPlan } from "../ir/params.js";
 import { frozenStepRows, requireExecutableWorkflowPlan } from "../runtime/plan-classifier.js";
 import { snapshotRunForDriver } from "../runtime/runs.js";
 import { evaluateStaleUnits } from "../runtime/unit-checkin.js";
+import { GATE_EVALUATION_PHASE } from "../runtime/unit-phases.js";
+import { canonicalWorkflowRunRef } from "../runtime/workflow-asset-loader.js";
 import { detectSecretShapedParams } from "./param-secrets.js";
-import { activeGateLoop, assertJournaledRouteSelectionsValid, computeStepWorkList, evaluateRoute, GATE_EVALUATION_PHASE, isWorkListFullyTerminal, recoverGateFeedback, selectUnitAttemptRow, stepOutputsFromEvidence, } from "./step-work.js";
+import { activeGateLoop, assertJournaledRouteSelectionsValid, computeStepWorkList, evaluateRoute, isWorkListFullyTerminal, recoverGateFeedback, selectUnitAttemptRow, stepOutputsFromEvidence, } from "./step-work.js";
 const EMPTY_WORK_LIST = { isFanOut: false, reducer: null, itemCount: 0, units: [] };
 // ── Entry point ──────────────────────────────────────────────────────────────
 /**
@@ -460,14 +462,15 @@ export async function resolveRunId(target) {
         const byId = repo.getRunById(target);
         if (byId)
             return byId.id;
-        if (!target.includes(":")) {
+        // Run-id vs workflow-ref: a run id has no `/`; canonical workflow refs do.
+        if (!target.includes(":") && !target.includes("/")) {
             throw new NotFoundError(`Workflow run "${target}" not found.`, "WORKFLOW_NOT_FOUND");
         }
-        const parsed = parseAssetRef(target);
+        const parsed = parseRefInput(target);
         if (parsed.type !== "workflow") {
-            throw new UsageError(`Expected a workflow run id or workflow ref (workflow:<name>), got "${target}".`);
+            throw new UsageError(`Expected a workflow run id or workflow ref (workflows/<name>), got "${target}".`);
         }
-        const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalizeWorkflowName(parsed.name)}`;
+        const ref = canonicalWorkflowRunRef(parsed.origin, canonicalizeWorkflowName(parsed.name));
         const active = repo.getActiveRunRowForScope(ref, getCurrentWorkflowScopeKey());
         if (!active) {
             throw new NotFoundError(`No active workflow run for ${ref} in this scope. \`akm workflow brief\` describes an existing run and never ` +