akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/storage/sqlite-pragmas.js

@@ -0,0 +1,146 @@
+// 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/.
+/**
+ * Shared SQLite PRAGMA application + journal-mode resolution (#628).
+ *
+ * Every AKM SQLite opener applies the same opening PRAGMAs: a journal mode, a
+ * 30 s busy_timeout, and (for most) foreign_keys = ON. Historically each opener
+ * hard-coded `PRAGMA journal_mode = WAL`. WAL is impossible on network
+ * filesystems (NFS/SMB) because its `-shm` shared-memory wal-index cannot be
+ * mmap'd over a network mount, so AKM could not run with its data dir on a
+ * network share.
+ *
+ * This module centralises that PRAGMA block behind {@link applyStandardPragmas}
+ * and makes the journal mode configurable via the `AKM_SQLITE_JOURNAL_MODE`
+ * env var (WAL | DELETE | TRUNCATE; default WAL = unchanged behaviour). When the
+ * mode is the WAL default and the data directory is detected to live on a
+ * network filesystem, it auto-falls-back to DELETE with a one-line warning.
+ *
+ * Boundary note: this is a PLAIN module, not a runtime-boundary file. It only
+ * does pure string work plus `db.exec()` (allowed everywhere). The single
+ * runtime primitive it needs — a filesystem-type probe (statfs) — lives in
+ * src/runtime.ts and is injected here, keeping the network-FS classifier a
+ * pure, unit-testable function.
+ *
+ * @module storage/sqlite-pragmas
+ */
+import { warn } from "../core/warn.js";
+import { statfsType } from "../runtime.js";
+const VALID_MODES = new Set(["WAL", "DELETE", "TRUNCATE"]);
+// One-shot warning guards so a misconfigured env var or a network-FS fallback
+// each emit AT MOST ONCE per process rather than on every db open.
+let warnedInvalid = false;
+let warnedNetworkFallback = false;
+/**
+ * Resolve a raw `AKM_SQLITE_JOURNAL_MODE` value to a canonical {@link JournalMode}.
+ *
+ * PURE and unit-testable: the raw string is passed in (not read from
+ * `process.env` here). Trims + uppercases; an empty/undefined value yields the
+ * WAL default; a recognised value yields its canonical form; any other
+ * non-empty value warns once and falls back to WAL. Never throws.
+ */
+export function resolveJournalMode(raw) {
+    if (raw === undefined)
+        return "WAL";
+    const normalized = raw.trim().toUpperCase();
+    if (normalized === "")
+        return "WAL";
+    if (VALID_MODES.has(normalized)) {
+        return normalized;
+    }
+    warnInvalidJournalModeOnce(raw);
+    return "WAL";
+}
+/**
+ * The single env-reading seam: resolve the configured journal mode from
+ * `process.env.AKM_SQLITE_JOURNAL_MODE`. Read at call time (per open) so tests
+ * that set the env per-case see the right value and we avoid stale-env flakes.
+ */
+export function resolveConfiguredJournalMode(env = process.env) {
+    return resolveJournalMode(env.AKM_SQLITE_JOURNAL_MODE);
+}
+function warnInvalidJournalModeOnce(raw) {
+    if (warnedInvalid)
+        return;
+    warnedInvalid = true;
+    warn(`[akm] invalid AKM_SQLITE_JOURNAL_MODE=${JSON.stringify(raw)} — using WAL (valid: WAL, DELETE, TRUNCATE)`);
+}
+// Known Linux f_type magic numbers for network filesystems. node's statfs
+// normalises `type` to this numeric f_type magic on all platforms.
+const FS_MAGIC_NFS = 0x6969; // 26985    — NFS
+const FS_MAGIC_SMB = 0x517b; // 20859    — older SMB_SUPER_MAGIC
+const FS_MAGIC_CIFS = 0xff534d42; // 4283649346 — SMB/CIFS
+const FS_MAGIC_SMB2 = 0xfe534d42; // 4267272514 — SMB2
+const FS_MAGIC_FUSE = 0x65735546; // 1702057286 — FUSE (sshfs + many network FUSE mounts)
+const NETWORK_FS_MAGICS = new Set([
+    FS_MAGIC_NFS,
+    FS_MAGIC_SMB,
+    FS_MAGIC_CIFS,
+    FS_MAGIC_SMB2,
+    // FUSE is a judgment call: it backs BOTH network mounts (sshfs) and local
+    // mounts (some encrypted/overlay FS). Treating it as network falls back to
+    // DELETE — conservative-but-safe (DELETE works everywhere; the only cost is
+    // losing WAL concurrency). An operator can always force WAL via the env var.
+    FS_MAGIC_FUSE,
+]);
+/**
+ * PURE classifier: is `fsType` a known network-filesystem magic number?
+ * Returns false for `undefined` (probe failed/unsupported) and for local
+ * magics (ext4 0xEF53, btrfs, xfs, tmpfs, apfs, …). Unit-testable with
+ * injected magic numbers — no real mount required.
+ */
+export function isNetworkFilesystem(fsType) {
+    if (fsType === undefined)
+        return false;
+    return NETWORK_FS_MAGICS.has(fsType);
+}
+/**
+ * Apply AKM's standard opening PRAGMAs to `db`, in order:
+ *   1. `journal_mode` = the configured mode (with WAL→DELETE network-FS fallback)
+ *   2. `busy_timeout = 30000`
+ *   3. `foreign_keys = ON`  (unless `opts.foreignKeys === false`)
+ *   4. `synchronous = FULL` (only in a rollback-journal mode — DELETE/TRUNCATE)
+ *
+ * Returns the effective {@link JournalMode} so callers/tests can assert it.
+ *
+ * `synchronous = FULL` is set explicitly only in DELETE/TRUNCATE so durability
+ * intent is clear: rollback journals need FULL for crash-durability across
+ * power loss, whereas WAL is durable at NORMAL. SQLite's default synchronous is
+ * already FULL when unset, so this never changes WAL-default behaviour — the
+ * WAL path emits no `synchronous` pragma, exactly as before.
+ */
+export function applyStandardPragmas(db, opts = {}) {
+    let mode = resolveConfiguredJournalMode(opts.env);
+    // Network-FS fallback only fires for the WAL default and only when we have a
+    // directory to probe. An explicitly-requested DELETE/TRUNCATE is never
+    // overridden, and a failed/unsupported probe (undefined) keeps WAL.
+    if (mode === "WAL" && opts.dataDir) {
+        const probe = opts.fsTypeProbe ?? statfsType;
+        if (isNetworkFilesystem(probe(opts.dataDir))) {
+            mode = "DELETE";
+            warnNetworkFallbackOnce(opts.dataDir);
+        }
+    }
+    // PRAGMAs must run before any DDL or DML. busy_timeout is applied FIRST so a
+    // journal-mode change that must reclaim a leftover `-wal` file (WAL→DELETE on
+    // reopen of an unclean WAL db, e.g. after a crash) can wait out a transient
+    // lock instead of failing immediately with SQLITE_BUSY. For the WAL default
+    // this is a no-op (WAL→WAL changes nothing), so byte-identical behaviour is
+    // preserved.
+    db.exec("PRAGMA busy_timeout = 30000");
+    db.exec(`PRAGMA journal_mode = ${mode}`);
+    if (opts.foreignKeys !== false) {
+        db.exec("PRAGMA foreign_keys = ON");
+    }
+    if (mode !== "WAL") {
+        db.exec("PRAGMA synchronous = FULL");
+    }
+    return mode;
+}
+function warnNetworkFallbackOnce(dataDir) {
+    if (warnedNetworkFallback)
+        return;
+    warnedNetworkFallback = true;
+    warn(`[akm] network filesystem detected at ${dataDir} — WAL unsupported, using DELETE journal mode`);
+}

package/dist/tasks/backends/cron.js

@@ -29,7 +29,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
 const BEGIN = (id) => `# akm:task ${id} BEGIN`;
 const END = (id) => `# akm:task ${id} END`;

package/dist/tasks/backends/index.js

@@ -4,7 +4,14 @@
 import { CRON_BACKEND } from "./cron.js";
 import { LAUNCHD_BACKEND } from "./launchd.js";
 import { SCHTASKS_BACKEND } from "./schtasks.js";
+let backendsOverrides;
+/** TEST-ONLY. Swap backend selection; pass undefined to restore the real implementations. */
+export function _setBackendsForTests(fakes) {
+    backendsOverrides = fakes;
+}
 export function selectBackend(options = {}) {
+    if (backendsOverrides?.selectBackend)
+        return backendsOverrides.selectBackend(options);
     const platform = options.platform ?? process.platform;
     switch (platform) {
         case "win32":
@@ -16,6 +23,8 @@ export function selectBackend(options = {}) {
     }
 }
 export function backendNameForPlatform(platform = process.platform) {
+    if (backendsOverrides?.backendNameForPlatform)
+        return backendsOverrides.backendNameForPlatform(platform);
     if (platform === "win32")
         return "schtasks";
     if (platform === "darwin")

package/dist/tasks/backends/launchd.js

@@ -27,7 +27,7 @@ import path from "node:path";
 import launchdTemplate from "../../assets/backends/launchd-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
 import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
 export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";

package/dist/tasks/backends/schtasks.js

@@ -35,7 +35,7 @@ import path from "node:path";
 import schtasksTemplate from "../../assets/backends/schtasks-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToSchtasks } from "../schedule.js";
 import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
 export const DEFAULT_FOLDER_PREFIX = "\\akm\\";

package/dist/tasks/{resolveAkmBin.js → resolve-akm-bin.js}

@@ -44,8 +44,8 @@ export function resolveAkmInvocation(options = {}) {
 /**
  * From the URL of a module inside `src/tasks/` figure out the CLI entry.
  *
- *   • dev      `…/src/tasks/resolveAkmBin.ts`   → `…/src/cli.ts`
- *   • build    `…/dist/tasks/resolveAkmBin.js`  → `…/dist/cli.js`
+ *   • dev      `…/src/tasks/resolve-akm-bin.ts`   → `…/src/cli.ts`
+ *   • build    `…/dist/tasks/resolve-akm-bin.js`  → `…/dist/cli.js`
  */
 function resolveCliEntry(moduleUrl) {
     let modulePath;

package/dist/tasks/runner.js

@@ -33,13 +33,14 @@ import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError } from "../core/errors.js";
 import { buildTaskRunId, insertTaskLogLines, openLogsDatabase, } from "../core/logs-db.js";
 import { getTaskLogDir } from "../core/paths.js";
-import { getTaskHistory, openStateDatabase, queryTaskHistory, upsertTaskHistory } from "../core/state-db.js";
+import { withStateDb } from "../core/state-db.js";
 import { error } from "../core/warn.js";
 import { requireAgentProfile, runAgent } from "../integrations/agent/index.js";
 import { resolveProcessAgentProfile } from "../integrations/agent/config.js";
 import { resolveRunner } from "../integrations/agent/runner.js";
 import { spawn } from "../runtime.js";
 import { resolveAssetPath } from "../sources/resolve.js";
+import { getTaskHistory, queryTaskHistory, upsertTaskHistory } from "../storage/repositories/task-history-repository.js";
 import { startWorkflowRun } from "../workflows/runtime/runs.js";
 import { parseTaskDocument } from "./parser.js";
 export async function runTask(id, options = {}) {
@@ -131,6 +132,11 @@ async function runCommandTask(input) {
             stdout: "pipe",
             stderr: "pipe",
             cwd: process.env.HOME ?? "/tmp",
+            // 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" },
         });
         let timer;
         let timedOut = false;
@@ -351,6 +357,10 @@ async function runPromptTask(input) {
         timeoutMs: agentTimeoutMs,
         cwd: stashDir,
         ...agentOptions,
+        // 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 },
     });
     const finishedAt = now();
     const log = renderPromptLog({ task, profileName: profile.name, result });
@@ -460,8 +470,7 @@ function persistRunLog(input) {
 // ── history ─────────────────────────────────────────────────────────────────
 function appendHistory(result) {
     try {
-        const db = openStateDatabase();
-        try {
+        withStateDb((db) => {
             upsertTaskHistory(db, {
                 task_id: result.id,
                 status: result.status,
@@ -477,10 +486,7 @@ function appendHistory(result) {
                     profile: result.target.kind === "prompt" ? result.target.profile : undefined,
                 }),
             });
-        }
-        finally {
-            db.close();
-        }
+        });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
@@ -488,8 +494,7 @@ function appendHistory(result) {
     }
 }
 export function readTaskHistory(options = {}) {
-    const db = openStateDatabase();
-    try {
+    return withStateDb((db) => {
         let rows;
         if (options.id) {
             const row = getTaskHistory(db, options.id);
@@ -503,10 +508,7 @@ export function readTaskHistory(options = {}) {
             return rows.slice(0, options.limit);
         }
         return rows;
-    }
-    finally {
-        db.close();
-    }
+    });
 }
 /**
  * Convert a `TaskHistoryRow` from state.db back to a `TaskRunResult` shape

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"]);
+const TEXT_EXTENSIONS = new Set([".md", ".xml", ".txt", ".sql", ".yaml", ".yml"]);
 
 function isTextImport(url, importAttributes) {
   if (importAttributes && importAttributes.type === "text") return true;

package/dist/wiki/wiki.js

@@ -58,6 +58,8 @@ export const SCHEMA_MD = "schema.md";
 export const INDEX_MD = "index.md";
 export const LOG_MD = "log.md";
 export const RAW_SUBDIR = "raw";
+/** Canonical location for agent-authored pages, mirroring RAW_SUBDIR. */
+export const PAGES_SUBDIR = "pages";
 /** Files at a wiki root that are not pages. */
 const WIKI_SPECIAL_FILES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
 const WIKI_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
@@ -224,6 +226,43 @@ function readSchemaDescription(wikiDir) {
         return undefined;
     }
 }
+/**
+ * Load a wiki's `schema.md` body and frontmatter.
+ *
+ * Unlike {@link readSchemaDescription} (which returns only the frontmatter
+ * `description` for `listWikis` summaries), this returns the markdown **body**
+ * — everything after the closing `---` of the frontmatter — which is where the
+ * page contract, operations, and hard rules live. The body is the rulebook
+ * injected into the write-time prompt for wiki-page edits.
+ *
+ * Swallow-and-degrade like the existing reader: a missing file, an unresolvable
+ * wiki dir, or malformed content yields `{ body: "", frontmatter: {} }`. Never
+ * throws.
+ */
+export function loadWikiSchema(stashRoot, name) {
+    const empty = { body: "", frontmatter: {} };
+    let wikiDir;
+    try {
+        wikiDir = resolveWikiDir(stashRoot, name);
+    }
+    catch {
+        return empty;
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(wikiDir, SCHEMA_MD), "utf8");
+    }
+    catch {
+        return empty;
+    }
+    try {
+        const parsed = parseFrontmatter(raw);
+        return { body: parsed.content, frontmatter: parsed.data };
+    }
+    catch {
+        return empty;
+    }
+}
 function toIsoDate(ms) {
     return new Date(ms).toISOString();
 }
@@ -369,18 +408,20 @@ export function createWiki(stashDir, name) {
         fs.writeFileSync(absPath, content, "utf8");
         created.push(absPath);
     }
-    // Ensure raw/ exists with a .gitkeep so empty wikis survive clean clones.
-    // Handle the dir-exists-but-no-.gitkeep case too (partial scaffolds,
+    // Ensure raw/ and pages/ exist with a .gitkeep so empty wikis survive clean
+    // clones. Handle the dir-exists-but-no-.gitkeep case too (partial scaffolds,
     // user-created directories) so the invariant always holds after `create`.
-    const rawDir = path.join(wikiDir, RAW_SUBDIR);
-    fs.mkdirSync(rawDir, { recursive: true });
-    const gitkeepPath = path.join(rawDir, ".gitkeep");
-    if (fs.existsSync(gitkeepPath)) {
-        skipped.push(gitkeepPath);
-    }
-    else {
-        fs.writeFileSync(gitkeepPath, "", "utf8");
-        created.push(gitkeepPath);
+    for (const subdir of [RAW_SUBDIR, PAGES_SUBDIR]) {
+        const dir = path.join(wikiDir, subdir);
+        fs.mkdirSync(dir, { recursive: true });
+        const gitkeepPath = path.join(dir, ".gitkeep");
+        if (fs.existsSync(gitkeepPath)) {
+            skipped.push(gitkeepPath);
+        }
+        else {
+            fs.writeFileSync(gitkeepPath, "", "utf8");
+            created.push(gitkeepPath);
+        }
     }
     return { name, ref: `wiki:${name}`, path: wikiDir, created, skipped };
 }

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 (redesign addendum, v1).
+# Save under workflows/<name>.yaml and lint with:
+#   akm workflow validate workflows/<name>.yaml
+version: 1
+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
+  runner: inherit # llm | agent | sdk | inherit
+  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

@@ -17,7 +17,12 @@ export const WORKFLOW_SUBCOMMANDS = new Set([
     "create",
     "template",
     "resume",
+    "abandon",
     "validate",
+    "run",
+    "brief",
+    "report",
+    "watch",
 ]);
 export function parseWorkflowJsonObject(raw, flagName) {
     if (!raw)