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

package/dist/workflows/authoring/authoring.js

@@ -4,11 +4,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import workflowTemplate from "../../assets/workflows/workflow-template.md" with { type: "text" };
-import { resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
+import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../../core/asset/asset-spec.js";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
+import { compileWorkflowProgram } from "../ir/compile.js";
 import { parseWorkflow } from "../parser.js";
+import { parseWorkflowProgram } from "../program/parser.js";
+import workflowProgramTemplate from "./workflow-program-template.yaml" with { type: "text" };
 const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
     title: "Example Workflow",
     firstStepTitle: "First Step",
@@ -17,6 +20,15 @@ const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
 export function getWorkflowTemplate() {
     return DEFAULT_WORKFLOW_TEMPLATE;
 }
+/**
+ * Minimal valid YAML workflow *program* (redesign addendum, R1), printed by
+ * `akm workflow template --yaml`. Kept as an external asset file per the repo
+ * convention (see `workflow-program-template.yaml` next to this module);
+ * `tests/workflows/program-assets.test.ts` pins that it parses AND compiles.
+ */
+export function getWorkflowProgramTemplate() {
+    return workflowProgramTemplate;
+}
 export function buildWorkflowTemplate(name) {
     if (!name)
         return DEFAULT_WORKFLOW_TEMPLATE;
@@ -33,25 +45,97 @@ export function buildWorkflowTemplate(name) {
     }
     return customized;
 }
+/**
+ * Customize the shipped YAML program template ({@link getWorkflowProgramTemplate})
+ * for a named workflow: swap the placeholder `name:` for the workflow's slug so
+ * a freshly created `.yaml`/`.yml` asset round-trips through the program parser
+ * (its `title` becomes the slug). Parses AND compiles the result — mirroring
+ * {@link buildWorkflowTemplate} — so a create never writes an asset that
+ * `show`/`start`/`validate` would then reject.
+ */
+export function buildWorkflowProgramTemplate(name) {
+    if (!name)
+        return workflowProgramTemplate;
+    const programName = slugifyWorkflowStepId(name);
+    const customized = workflowProgramTemplate.replace(/^name:.*$/m, `name: ${programName}`);
+    const parsed = parseWorkflowProgram(customized, { path: `<template:${name}>` });
+    if (!parsed.ok) {
+        throw new UsageError(formatWorkflowErrors(`<template:${name}>`, parsed.errors));
+    }
+    const compiled = compileWorkflowProgram(parsed.program);
+    if (!compiled.ok) {
+        throw new UsageError(formatWorkflowErrors(`<template:${name}>`, compiled.errors));
+    }
+    return customized;
+}
+/** Recognized YAML workflow-program suffixes (see {@link WORKFLOW_EXTENSIONS}). */
+const WORKFLOW_PROGRAM_SUFFIX_RE = /\.ya?ml$/i;
 export function createWorkflowAsset(input) {
     const stashDir = resolveStashDir();
     const typeRoot = path.join(stashDir, "workflows");
     fs.mkdirSync(typeRoot, { recursive: true });
+    // A `.yaml`/`.yml` name selects the YAML *program* format (redesign
+    // addendum, R1); capture the exact suffix the user typed so the written file
+    // keeps it, then strip every workflow extension to get the canonical name.
+    const suffixMatch = input.name.trim().replace(/\\/g, "/").match(WORKFLOW_PROGRAM_SUFFIX_RE);
+    const programSuffix = suffixMatch ? suffixMatch[0].toLowerCase() : undefined;
+    const isProgram = programSuffix !== undefined;
     const normalizedName = normalizeWorkflowName(input.name);
-    const assetPath = resolveAssetPathFromName("workflow", typeRoot, normalizedName);
+    // 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
+    // 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
+    // the real collision instead of a self-match.
+    const targetSuffix = isProgram ? programSuffix : ".md";
+    const assetPath = path.join(typeRoot, `${normalizedName}${targetSuffix}`);
     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
+    // 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
+    // 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;
+    // a DIFFERENT-extension collision cannot be force-overwritten (writing a new
+    // file would leave the old one shadowing it) — remove the existing file first.
+    const existingPaths = WORKFLOW_EXTENSIONS.map((ext) => path.join(typeRoot, `${normalizedName}${ext}`)).filter((candidate) => fs.existsSync(candidate));
+    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. ` +
+            `Remove or rename the existing file first, or create the workflow under a different name.`, "RESOURCE_ALREADY_EXISTS");
+    }
     if (fs.existsSync(assetPath) && !input.force) {
         throw new UsageError(`Workflow "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
     }
     const content = input.from
         ? readWorkflowSource(input.from, stashDir)
-        : (input.content ?? buildWorkflowTemplate(normalizedName));
-    const sourcePath = input.from ?? `workflows/${normalizedName}.md`;
-    const result = parseWorkflow(content, { path: sourcePath });
-    if (!result.ok) {
-        throw new UsageError(formatWorkflowErrors(sourcePath, result.errors));
+        : (input.content ??
+            (isProgram ? buildWorkflowProgramTemplate(normalizedName) : buildWorkflowTemplate(normalizedName)));
+    const sourcePath = input.from ?? `workflows/${normalizedName}${isProgram ? programSuffix : ".md"}`;
+    // Validate against the format the destination extension selects — a YAML
+    // program parses+compiles as a program, markdown as a document — so the
+    // created asset is guaranteed usable by show/start/validate, which pick
+    // their parser by the same extension.
+    if (isProgram) {
+        const parsed = parseWorkflowProgram(content, { path: sourcePath });
+        if (!parsed.ok) {
+            throw new UsageError(formatWorkflowErrors(sourcePath, parsed.errors));
+        }
+        const compiled = compileWorkflowProgram(parsed.program);
+        if (!compiled.ok) {
+            throw new UsageError(formatWorkflowErrors(sourcePath, compiled.errors));
+        }
+    }
+    else {
+        const result = parseWorkflow(content, { path: sourcePath });
+        if (!result.ok) {
+            throw new UsageError(formatWorkflowErrors(sourcePath, result.errors));
+        }
     }
     fs.mkdirSync(path.dirname(assetPath), { recursive: true });
     fs.writeFileSync(assetPath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
@@ -83,11 +167,14 @@ function readWorkflowSource(source, stashDir) {
     return fs.readFileSync(resolved, "utf8");
 }
 function normalizeWorkflowName(name) {
-    const normalized = name
+    // Strip any recognized workflow extension (.md/.yaml/.yml) so the canonical
+    // name — and thus the `workflow:<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
         .trim()
         .replace(/\\/g, "/")
-        .replace(/^\/+|\/+$/g, "")
-        .replace(/\.md$/i, "");
+        .replace(/^\/+|\/+$/g, ""));
     if (!normalized) {
         throw new UsageError("Workflow name cannot be empty.");
     }
@@ -137,6 +224,32 @@ export function validateWorkflowSource(target) {
     const content = fs.readFileSync(resolved, "utf8");
     return { path: target, parse: parseWorkflow(content, { path: target }) };
 }
+/**
+ * Validate a YAML workflow *program* by filesystem path: parse via
+ * `parseWorkflowProgram`, then — only when the parse is clean — compile via
+ * `compileWorkflowProgram` so expression/reference errors surface too. Both
+ * error lists carry line numbers and are returned in the same
+ * `WorkflowError[]` shape, ready for `formatWorkflowErrors`. Throws
+ * `UsageError` only when the target cannot be located on disk.
+ */
+export function validateWorkflowProgramSource(target) {
+    const resolved = path.resolve(target);
+    if (!fs.existsSync(resolved)) {
+        throw new UsageError(`Workflow file not found: "${target}".`);
+    }
+    const content = fs.readFileSync(resolved, "utf8");
+    const parse = parseWorkflowProgram(content, { path: target });
+    if (!parse.ok) {
+        return { path: target, result: { ok: false, errors: parse.errors } };
+    }
+    const compiled = compileWorkflowProgram(parse.program);
+    if (!compiled.ok) {
+        return { path: target, result: { ok: false, errors: compiled.errors } };
+    }
+    // Non-fatal advisories ride along on a successful validation (additive) so
+    // `workflow validate` can surface them without changing the ok verdict.
+    return { path: target, result: { ok: true, program: parse.program, warnings: compiled.warnings } };
+}
 function renderWorkflowTemplate(input) {
     return workflowTemplate
         .replace("{{TITLE}}", input.title)

package/dist/workflows/authoring/workflow-program-template.yaml

@@ -0,0 +1,31 @@
+# akm YAML workflow program (binding YAML v2).
+# Save under workflows/<name>.yaml and lint with:
+#   akm workflow validate workflows/<name>.yaml
+version: 2
+name: example-workflow
+description: Describe what this workflow accomplishes.
+
+params:
+  example_param: { type: string, description: Explain this parameter }
+
+defaults: # run-level defaults, overridable per unit
+  # engine: my-engine # optional; otherwise defaults.engine from config
+  timeout: 10m # "<n>ms" | "<n>s" | "<n>m" | "none"
+  on_error: fail # fail | continue
+
+steps:
+  - id: first-step
+    title: First Step
+    unit:
+      instructions: |
+        Describe what to do in this step.
+        Reference run parameters explicitly: ${{ params.example_param }}.
+    gate:
+      criteria:
+        - Confirm the first step is complete
+
+  - id: second-step
+    title: Second Step
+    unit:
+      instructions: |
+        Describe what happens next.

package/dist/workflows/cli.js

@@ -19,6 +19,10 @@ export const WORKFLOW_SUBCOMMANDS = new Set([
     "resume",
     "abandon",
     "validate",
+    "run",
+    "brief",
+    "report",
+    "watch",
 ]);
 export function parseWorkflowJsonObject(raw, flagName) {
     if (!raw)

package/dist/workflows/concurrency-policy.js

@@ -0,0 +1,15 @@
+// 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/.
+import os from "node:os";
+export const WORKFLOW_MAX_CONCURRENCY_CEILING = 64;
+export function cpuDerivedUnitConcurrency(cpuCount = os.cpus()?.length ?? 4) {
+    return Math.min(16, Math.max(1, cpuCount - 2));
+}
+export function clampMaxConcurrency(value) {
+    return Math.min(WORKFLOW_MAX_CONCURRENCY_CEILING, Math.max(1, Math.floor(value)));
+}
+/** Resolve and freeze the engine-wide cap once when a workflow run starts. */
+export function workflowMaxConcurrency(configured, cpuCount = os.cpus()?.length ?? 4) {
+    return configured === undefined ? cpuDerivedUnitConcurrency(cpuCount) : clampMaxConcurrency(configured);
+}

package/dist/workflows/db.js

@@ -3,6 +3,8 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
+import { acquireMaintenanceActivitySync } from "../core/maintenance-barrier.js";
+import { ensureMigrationBackup, getMigrationBackupDir } from "../core/migration-backup.js";
 import { getWorkflowDbPath } from "../core/paths.js";
 import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
@@ -42,18 +44,55 @@ import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
  */
 // ── Public API ───────────────────────────────────────────────────────────────
 export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
-    const dir = path.dirname(dbPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
+    const isCanonical = path.resolve(dbPath) === path.resolve(getWorkflowDbPath());
+    const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("workflow-db") : undefined;
+    let db;
+    try {
+        // Preserve an originally absent workflow.db in the recovery manifest. SQLite
+        // creates the file at open time, so the cutover bundle must exist first.
+        if (isCanonical && !fs.existsSync(getMigrationBackupDir()))
+            ensureMigrationBackup();
+        const dir = path.dirname(dbPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        db = openDatabase(dbPath);
+        // #589: 30 s busy timeout, matching index.db / state.db. Without it the
+        // default is 0 ms, so any concurrent writer fails immediately with
+        // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
+        applyStandardPragmas(db, { dataDir: dir });
+        ensureBaseSchema(db);
+        runMigrations(db, { ensureCutoverBackup: isCanonical });
+        if (!releaseActivity)
+            return db;
+        const openedDb = db;
+        let closed = false;
+        return {
+            prepare: openedDb.prepare.bind(openedDb),
+            exec: openedDb.exec.bind(openedDb),
+            run: openedDb.run.bind(openedDb),
+            transaction: openedDb.transaction.bind(openedDb),
+            get inTransaction() {
+                return openedDb.inTransaction;
+            },
+            close() {
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    openedDb.close();
+                }
+                finally {
+                    releaseActivity();
+                }
+            },
+        };
+    }
+    catch (error) {
+        db?.close();
+        releaseActivity?.();
+        throw error;
     }
-    const db = openDatabase(dbPath);
-    // #589: 30 s busy timeout, matching index.db / state.db. Without it the
-    // default is 0 ms, so any concurrent writer fails immediately with
-    // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
-    applyStandardPragmas(db, { dataDir: dir });
-    ensureBaseSchema(db);
-    runMigrations(db);
-    return db;
 }
 export function closeWorkflowDatabase(db) {
     db.close();
@@ -165,6 +204,148 @@ const MIGRATIONS = [
       ALTER TABLE workflow_run_steps ADD COLUMN summary TEXT;
     `,
     },
+    // ── Migration 004 — per-unit run state (orchestration plan P1) ──────────────
+    //
+    // A step's execution may now fan out into N concurrent units (native
+    // executor, docs/technical/akm-workflows-orchestration-plan.md). Units hang
+    // off the gated step spine: `workflow_run_steps` stays the durable top-level
+    // record; each dispatched unit gets its own row here so a crash-and-resume
+    // re-dispatches only incomplete units (durable-row resume) and budget/usage
+    // is attributable per unit. `input_hash` is reserved for the P5 deterministic
+    // replay mode; `failure_reason` carries runAgent's structured failure
+    // vocabulary so retry/continue-on-error policy has semantics to act on.
+    {
+        id: "004-workflow-run-units",
+        up: `
+      CREATE TABLE IF NOT EXISTS workflow_run_units (
+        run_id         TEXT NOT NULL,
+        unit_id        TEXT NOT NULL,
+        step_id        TEXT,
+        node_id        TEXT NOT NULL,
+        parent_unit_id TEXT,
+        phase          TEXT,
+        runner         TEXT,
+        model          TEXT,
+        status         TEXT NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed', 'skipped')),
+        input_hash     TEXT,
+        result_json    TEXT,
+        tokens         INTEGER,
+        failure_reason TEXT,
+        worktree_path  TEXT,
+        started_at     TEXT,
+        finished_at    TEXT,
+        PRIMARY KEY (run_id, unit_id),
+        FOREIGN KEY (run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_workflow_run_units_run_step
+        ON workflow_run_units(run_id, step_id);
+    `,
+    },
+    // ── Migration 005 — harness-native unit session id (plan P2) ────────────────
+    //
+    // The P2 harness adapters' result extractors reveal the harness-native
+    // session id of a dispatched unit (codex `session_configured`, gemini/pi
+    // JSON envelopes, the opencode SDK session). It is stored opportunistically
+    // on the unit row so resume can replay the harness's own context cache
+    // (e.g. `codex exec resume <id>`, `gemini --resume <id>`); akm never
+    // *depends* on it — `workflow_run_units` remains the durable source of
+    // truth (plan §"Session, MCP, and identity across harnesses").
+    {
+        id: "005-unit-session-id",
+        up: `
+      ALTER TABLE workflow_run_units ADD COLUMN session_id TEXT;
+    `,
+    },
+    // ── Migration 006 — frozen plan + engine lease (redesign addendum, R1) ──────
+    //
+    // `workflow start` now compiles the workflow into its plan graph ONCE and
+    // freezes it on the run row: `plan_json` holds the canonical plan JSON
+    // (`ir/plan-hash.ts`) and `plan_hash` its sha256, so every subsequent
+    // invocation executes the frozen snapshot with an integrity check — the
+    // source file is never re-read for an in-flight run. Runs created before
+    // this migration have NULL plan_json (legacy) and fall back to
+    // compile-from-asset with a warning.
+    //
+    // `engine_lease_until` / `engine_lease_holder` reserve the run-lease columns
+    // (a second `workflow run` on a leased run refuses up front). TODO(R2):
+    // lease ENFORCEMENT is engine-rework scope — only the columns land now.
+    {
+        id: "006-frozen-plan-and-lease",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN plan_json TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN plan_hash TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN engine_lease_until TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN engine_lease_holder TEXT;
+    `,
+    },
+    // ── Migration 007 — unit-level check-in heartbeat (redesign addendum, R3) ────
+    //
+    // The harness-neutral driver protocol lets ANY agent session claim and
+    // heartbeat a unit it is executing via `akm workflow report --status running`.
+    // `last_checkin_at` records the most recent heartbeat (distinct from
+    // `started_at`, the first claim) so a pure timestamp evaluator
+    // (`runtime/unit-checkin.ts`) can surface a claimed-but-silent unit as stale
+    // in `workflow brief` without any background thread. Nullable and additive;
+    // engine-dispatched rows never set it (they finish before a heartbeat window
+    // could elapse), so their transient `running` state is judged from
+    // `started_at`.
+    {
+        id: "007-unit-last-checkin",
+        up: `
+      ALTER TABLE workflow_run_units ADD COLUMN last_checkin_at TEXT;
+    `,
+    },
+    // ── Migration 008 — per-unit dispatch-attempt counter (PR #714 review, P2) ───
+    //
+    // `workflow_run_units.unit_id` is CONTENT-derived and stable across
+    // crash/resume (retries/loops carry `~r<n>`/`~l<loop>` suffixes, so they are
+    // DISTINCT rows). A crash between a unit's dispatch (`insertUnit`, status
+    // `running`) and its finish leaves a stale `running` row; durable-row resume
+    // re-dispatches the SAME unit_id and `insertUnit` REPLACES that single row.
+    // Because the run's budget/lifetime seed was derived from the NUMBER of unit
+    // rows, each crash/resume of one unit erased the prior dispatch from
+    // `budget.max_units` / lifetime-cap accounting, letting a run spend past its
+    // declared ceiling. `attempts` counts how many times a row was (re)dispatched
+    // — incremented by `insertUnit` on every REPLACE of an existing row — so both
+    // budget seeds sum `attempts` instead of counting rows and crash-retried
+    // dispatches are charged. Existing rows back-fill to 1 (one dispatch each).
+    {
+        id: "008-unit-attempts",
+        up: `
+      ALTER TABLE workflow_run_units ADD COLUMN attempts INTEGER NOT NULL DEFAULT 1;
+    `,
+    },
+    // ── Migration 009 — per-unit claim ownership (PR #714 review round 2) ─────────
+    //
+    // `akm workflow report --status running` claims a unit before executing it.
+    // Round-2 review (#3): a running row had no claim owner, no compare-and-set,
+    // and no stale-hash guard, so a stale/tampered `running` row could be
+    // finalized by anyone with a fresh result while keeping an old input_hash.
+    // These columns record who holds the claim (`claim_holder` — the driver's
+    // `--session-id` or a token report mints and returns) and until when
+    // (`claim_expires_at`, ISO-8601 UTC). Heartbeating or finishing a live-claimed
+    // running row requires the matching holder; an EXPIRED claim is reclaimable by
+    // a new holder (crash recovery). The TTL equals the unit-checkin stale window
+    // (`runtime/unit-checkin.UNIT_STALE_MS`), so an expired claim is exactly a unit
+    // that `workflow brief` already surfaces as stale. Both columns are nullable
+    // and additive: engine-dispatched rows and simple claimless drivers leave them
+    // NULL, and finishing a never-claimed unit stays allowed (input_hash is still
+    // validated always).
+    {
+        id: "009-unit-claim",
+        up: `
+      ALTER TABLE workflow_run_units ADD COLUMN claim_holder TEXT;
+      ALTER TABLE workflow_run_units ADD COLUMN claim_expires_at TEXT;
+    `,
+    },
+    {
+        id: "010-ir-v3-engine",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN plan_ir_version INTEGER;
+      ALTER TABLE workflow_run_units ADD COLUMN engine TEXT;
+    `,
+    },
 ];
 /**
  * Stable id of the scope_key migration. Exported for bootstrap detection and
@@ -210,6 +391,12 @@ function bootstrapPreVersioningDb(db) {
  *
  * Called automatically by {@link openWorkflowDatabase}.
  */
-export function runMigrations(db) {
-    runSqliteMigrations(db, MIGRATIONS, { bootstrap: bootstrapPreVersioningDb });
+export function runMigrations(db, options) {
+    runSqliteMigrations(db, MIGRATIONS, {
+        bootstrap: bootstrapPreVersioningDb,
+        beforeMigration(migration) {
+            if (options?.ensureCutoverBackup && migration.id === "010-ir-v3-engine")
+                ensureMigrationBackup();
+        },
+    });
 }