akm-cli 0.8.0-rc2 → 0.8.1

package/dist/tasks/backends/schtasks.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * schtasks.exe backend for `akm tasks` (Windows default).
  *
@@ -29,12 +32,12 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import schtasksTemplate from "../../assets/backends/schtasks-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors";
 import { getTaskLogDir } from "../../core/paths";
 import { resolveAkmInvocation } from "../resolveAkmBin";
 import { parseSchedule, translateToSchtasks } from "../schedule";
 import { escapeXml, spawnCommand } from "./exec-utils";
-import schtasksTemplate from "./schtasks-template.xml" with { type: "text" };
 export const DEFAULT_FOLDER_PREFIX = "\\akm\\";
 export function SCHTASKS_BACKEND(options = {}) {
     const exec = options.exec ?? defaultSchtasksExec();

package/dist/tasks/parser.js

@@ -1,28 +1,32 @@
+// 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/.
 /**
- * Parse a task markdown file (frontmatter + body) into a {@link TaskDocument}.
+ * Parse a task YAML file into a {@link TaskDocument}.
  *
- * The on-disk shape is:
+ * The on-disk shape is a pure YAML file at `<stash>/tasks/<id>.yml`:
  *
- * ```markdown
- * ---
+ * ```yaml
  * schedule: "0 9 * * *"
  * # one of:
  * workflow: workflow:daily-backup
  * params:
  *   region: us-east-1
  * # ...or:
- * prompt: inline                    # body is the prompt
- * profile: opencode                 # optional
- * # ...or:
  * prompt: agent:my-agent            # asset ref
  * # ...or:
  * prompt: ./prompts/my-prompt.md    # relative file path
+ * # ...or:
+ * prompt: |                         # inline multi-line prompt (block scalar)
+ *   Do the thing.
+ *   And the other thing.
+ * # ...or:
+ * command: akm improve --auto-accept=90 --limit 25
  * enabled: true                     # default true
+ * name: Daily backup
  * description: …
+ * when_to_use: …
  * tags: [scheduled, backup]
- * ---
- *
- * # Task: Daily backup           (optional notes; for prompt:inline this is the prompt)
  * ```
  *
  * Validation lives in {@link validateTaskDocument}. The parser only enforces
@@ -30,29 +34,42 @@
  * checked separately so callers can choose how strictly to surface errors.
  */
 import path from "node:path";
+import { parse as parseYaml } from "yaml";
 import { UsageError } from "../core/errors";
-import { parseFrontmatter } from "../core/frontmatter";
 import { TASK_SCHEMA_VERSION } from "./schema";
 export function parseTaskDocument(input) {
-    const { markdown, filePath, id } = input;
-    const fm = parseFrontmatter(markdown);
-    const data = fm.data;
+    const { yaml, filePath, id } = input;
+    let data;
+    try {
+        const parsed = parseYaml(yaml);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new UsageError(`Task "${id}" YAML must be a mapping (key: value pairs). File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        data = parsed;
+    }
+    catch (err) {
+        if (err instanceof UsageError)
+            throw err;
+        throw new UsageError(`Task "${id}" has invalid YAML: ${err instanceof Error ? err.message : String(err)}. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
     const schedule = readString(data.schedule, "schedule", filePath);
     if (!schedule) {
-        throw new UsageError(`Task "${id}" is missing a schedule (frontmatter key "schedule"). File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+        throw new UsageError(`Task "${id}" is missing a schedule (YAML key "schedule"). File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
     }
     const enabled = data.enabled === undefined ? true : data.enabled === true;
+    const name = readString(data.name, "name", filePath);
     const description = readString(data.description, "description", filePath);
+    const when_to_use = readString(data.when_to_use, "when_to_use", filePath);
     const tags = readStringArray(data.tags);
-    const hasWorkflow = "workflow" in data && data.workflow !== "";
-    const hasPrompt = "prompt" in data && data.prompt !== "";
-    const hasCommand = "command" in data && data.command !== "" && data.command !== null && data.command !== undefined;
+    const hasWorkflow = "workflow" in data && data.workflow !== "" && data.workflow != null;
+    const hasPrompt = "prompt" in data && data.prompt !== "" && data.prompt != null;
+    const hasCommand = "command" in data && data.command !== "" && data.command != null;
     const targetCount = [hasWorkflow, hasPrompt, hasCommand].filter(Boolean).length;
     if (targetCount > 1) {
         throw new UsageError(`Task "${id}" sets more than one of \`workflow\`, \`prompt\`, \`command\`; pick exactly one. File: ${filePath}`, "INVALID_FLAG_VALUE");
     }
     if (targetCount === 0) {
-        throw new UsageError(`Task "${id}" must set one of \`workflow\`, \`prompt\`, or \`command\` in frontmatter. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+        throw new UsageError(`Task "${id}" must set one of \`workflow\`, \`prompt\`, or \`command\`. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
     }
     let target;
     if (hasWorkflow) {
@@ -78,7 +95,7 @@ export function parseTaskDocument(input) {
         const profile = readString(data.profile, "profile", filePath);
         target = {
             kind: "prompt",
-            source: resolvePromptSource(promptRaw, fm.content, filePath, id),
+            source: resolvePromptSource(promptRaw, filePath, id),
             profile: profile && profile.length > 0 ? profile : undefined,
         };
     }
@@ -101,30 +118,24 @@ export function parseTaskDocument(input) {
         schedule,
         enabled,
         target,
+        name: name && name.length > 0 ? name : undefined,
         description: description && description.length > 0 ? description : undefined,
+        when_to_use: when_to_use && when_to_use.length > 0 ? when_to_use : undefined,
         tags: tags && tags.length > 0 ? tags : undefined,
         source: { path: filePath },
         timeoutMs,
     };
 }
 /**
- * Split `prompt:` frontmatter into one of {@link TaskPromptSource} variants.
+ * Resolve a `prompt:` value into a {@link TaskPromptSource} variant.
  *
- *   • "inline"                          → body is the prompt
- *   • "<type>:<name>" (asset ref)       → asset
- *   • "./foo.md", "../foo.md", "/abs"   → file
- *   • anything else                     → treated as inline prompt text
- *     (the value itself is the prompt)
+ *   • "<type>:<name>" (asset ref)              → asset
+ *   • "./foo.md", "../foo.md", "/abs"          → file
+ *   • "C:\\abs" (Windows absolute)             → file
+ *   • anything else (incl. block scalars)      → inline text
  */
-function resolvePromptSource(raw, body, filePath, id) {
+function resolvePromptSource(raw, filePath, id) {
     const trimmed = raw.trim();
-    if (trimmed === "inline") {
-        const text = body.trim();
-        if (!text) {
-            throw new UsageError(`Task "${id}" sets \`prompt: inline\` but the markdown body is empty. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
-        }
-        return { kind: "inline", text };
-    }
     if (trimmed.startsWith("./") || trimmed.startsWith("../") || path.isAbsolute(trimmed)) {
         return { kind: "file", path: trimmed };
     }
@@ -134,7 +145,9 @@ function resolvePromptSource(raw, body, filePath, id) {
     if (/^[a-z][a-z0-9_-]*:[^\s]/i.test(trimmed)) {
         return { kind: "asset", ref: trimmed };
     }
-    // Fallback: treat the literal value as the prompt text.
+    if (!trimmed) {
+        throw new UsageError(`Task "${id}" has empty \`prompt\`. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+    }
     return { kind: "inline", text: trimmed };
 }
 function readString(value, key, filePath) {
@@ -144,7 +157,7 @@ function readString(value, key, filePath) {
         return value.trim();
     if (typeof value === "number" || typeof value === "boolean")
         return String(value);
-    throw new UsageError(`Frontmatter key "${key}" must be a string. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    throw new UsageError(`Key "${key}" must be a string. File: ${filePath}`, "INVALID_FLAG_VALUE");
 }
 function readStringArray(value) {
     if (value === undefined || value === null)
@@ -175,7 +188,7 @@ function readCommand(value, filePath, id) {
         }
         return parts;
     }
-    throw new UsageError(`Frontmatter key "command" must be a string or array of strings. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    throw new UsageError(`Key "command" must be a string or array of strings. File: ${filePath}`, "INVALID_FLAG_VALUE");
 }
 function readParams(value, filePath) {
     if (value === undefined || value === null)
@@ -194,5 +207,5 @@ function readParams(value, filePath) {
             // fall through
         }
     }
-    throw new UsageError(`Frontmatter key "params" must be a mapping or a JSON object. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    throw new UsageError(`Key "params" must be a mapping or a JSON object. File: ${filePath}`, "INVALID_FLAG_VALUE");
 }

package/dist/tasks/resolveAkmBin.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Resolve the absolute invocation that the OS scheduler should run.
  *

package/dist/tasks/runner.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * `akm tasks run <id>` — what cron / launchd / schtasks invoke at the
  * scheduled moment.
@@ -24,12 +27,13 @@ import path from "node:path";
 import { parseAssetRef } from "../core/asset-ref";
 import { resolveStashDir } from "../core/common";
 import { loadConfig } from "../core/config";
-import { NotFoundError } from "../core/errors";
+import { NotFoundError, rethrowIfTestIsolationError } from "../core/errors";
 import { getTaskLogDir } from "../core/paths";
 import { getTaskHistory, openStateDatabase, queryTaskHistory, upsertTaskHistory } from "../core/state-db";
 import { error } from "../core/warn";
 import { requireAgentProfile, runAgent } from "../integrations/agent";
 import { resolveProcessAgentProfile } from "../integrations/agent/config";
+import { resolveRunner } from "../integrations/agent/runner";
 import { resolveAssetPath } from "../sources/resolve";
 import { startWorkflowRun } from "../workflows/runs";
 import { parseTaskDocument } from "./parser";
@@ -40,8 +44,8 @@ export async function runTask(id, options = {}) {
     const now = options.now ?? (() => new Date());
     const logDir = options.logDir ?? getTaskLogDir();
     const filePath = await resolveAssetPath(stashDir, "task", id);
-    const markdown = fs.readFileSync(filePath, "utf8");
-    const task = parseTaskDocument({ markdown, filePath, id });
+    const yaml = fs.readFileSync(filePath, "utf8");
+    const task = parseTaskDocument({ yaml, filePath, id });
     const startedAt = now();
     const startedIso = startedAt.toISOString();
     const tsSlug = startedIso.replace(/[:.]/g, "-");
@@ -91,8 +95,8 @@ export async function runTask(id, options = {}) {
         now,
         runAgentImpl,
         agentOptions: options.agentOptions,
-        agentConfig: config.agent,
-        agentTimeoutMs: config.agent?.timeoutMs ?? undefined,
+        agentConfig: config,
+        agentTimeoutMs: undefined,
     });
 }
 // ── command target ──────────────────────────────────────────────────────────
@@ -111,6 +115,7 @@ async function runCommandTask(input) {
             stdin: "ignore",
             stdout: "pipe",
             stderr: "pipe",
+            cwd: process.env.HOME ?? "/tmp",
         });
         let timer;
         let timedOut = false;
@@ -249,15 +254,35 @@ async function runPromptTask(input) {
     // Use pre-resolved agent config when available to avoid redundant loadConfig()
     // calls in batch task runs (Fix C6). Fall back to loadConfig() for callers
     // that invoke runPromptTask directly without threading config.
-    const agentCfg = input.agentConfig !== undefined ? input.agentConfig : loadConfig().agent;
+    const fullConfig = loadConfig();
+    const agentCfg = input.agentConfig !== undefined ? input.agentConfig : fullConfig;
     // Resolve the profile for this task. When the task doc specifies a profile,
     // use it directly. Otherwise fall back to the per-process config for "task"
     // (agent.processes["task"]), which itself falls back to agent.default.
     let profile;
     let processTimeoutMs;
     if (task.target.profile) {
-        // Task doc explicitly names a profile — honour it directly.
-        profile = requireAgentProfile(agentCfg, task.target.profile);
+        // v2: if profiles.agent is configured, resolve through new runner
+        if (fullConfig.profiles?.agent) {
+            const mode = task.target.mode ?? "agent";
+            if (mode !== "llm") {
+                const runnerSpec = resolveRunner(mode, task.target.profile, fullConfig);
+                if (runnerSpec.kind === "agent" || runnerSpec.kind === "sdk") {
+                    profile = runnerSpec.profile;
+                    processTimeoutMs = runnerSpec.timeoutMs;
+                }
+                else {
+                    profile = requireAgentProfile(agentCfg, task.target.profile);
+                }
+            }
+            else {
+                profile = requireAgentProfile(agentCfg, task.target.profile);
+            }
+        }
+        else {
+            // v1: Task doc explicitly names a profile — honour it directly.
+            profile = requireAgentProfile(agentCfg, task.target.profile);
+        }
     }
     else {
         // No per-task profile: use process config for "task" as a fallback.
@@ -273,7 +298,7 @@ async function runPromptTask(input) {
             ? processTimeoutMs
             : input.agentTimeoutMs !== undefined
                 ? input.agentTimeoutMs
-                : agentCfg?.timeoutMs;
+                : undefined;
     const promptText = await resolvePromptText(task, stashDir);
     const result = await runAgentImpl(profile, promptText, {
         stdio: "captured",
@@ -362,6 +387,7 @@ function appendHistory(result) {
         }
     }
     catch (err) {
+        rethrowIfTestIsolationError(err);
         error(`[akm] task history DB write failed: ${String(err)}`);
     }
 }

package/dist/tasks/schedule.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Cross-platform schedule parsing and translation.
  *
@@ -38,7 +41,7 @@ const FIELD_LIMITS = {
     month: { min: 1, max: 12 },
     dow: { min: 0, max: 6 },
 };
-const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), and step-on-star (`*/N`). " +
+const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), step-on-star (`*/N`), and comma lists (`7,37`). " +
     "Aliases: `@hourly`, `@daily`, `@weekly`, `@monthly`. " +
     "Lists, ranges, and named days/months are not supported.";
 export function parseSchedule(input, backend) {
@@ -103,6 +106,19 @@ function parseField(raw, name, limit, original) {
         }
         return { kind: "value", value };
     }
+    // Comma-separated list: `7,37` or `0,15,30,45`. Each element must be an
+    // integer within [limit.min, limit.max]. Duplicates and unsorted input
+    // are accepted but the parsed form is deduped + ascending so downstream
+    // consumers can rely on a canonical shape.
+    if (/^\d+(,\d+)+$/.test(raw)) {
+        const values = [...new Set(raw.split(",").map((s) => Number(s)))].sort((a, b) => a - b);
+        for (const v of values) {
+            if (!Number.isInteger(v) || v < limit.min || v > limit.max) {
+                throw new UsageError(`Invalid ${name} list value "${v}" in schedule "${original}" (allowed ${limit.min}-${limit.max}).`, "INVALID_FLAG_VALUE");
+            }
+        }
+        return { kind: "list", values };
+    }
     throw new UsageError(`Unsupported ${name} expression "${raw}" in schedule "${original}". ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE");
 }
 // ── Backend translators ─────────────────────────────────────────────────────
@@ -161,6 +177,9 @@ function rejectStepInsideCalendar(field, name, spec) {
     if (field.kind === "step") {
         throw new UsageError(`Schedule "${spec.raw}" uses step (${name} = */N) in a position macOS launchd cannot express. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Either restrict the step to the minute or hour field only, or rewrite the schedule with concrete values.");
     }
+    if (field.kind === "list") {
+        throw new UsageError(`Schedule "${spec.raw}" uses comma list (${name} = a,b,...) which macOS launchd cannot express as a single trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Either install one task per list element, or rewrite the schedule with a step (`*/N`) or single value.");
+    }
 }
 export function translateToSchtasks(spec) {
     const f = spec.fields;

package/dist/tasks/schema.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Task asset schema. A task pairs a cron-style schedule with exactly one of:
  *
@@ -6,8 +9,7 @@
  *                          agent harness (e.g. `opencode run`)
  *   • a command target   — invoked directly via `Bun.spawn()`, no AI agent
  *
- * Tasks are stored as markdown files at `<stash>/tasks/<id>.md`. The
- * frontmatter holds the schedule and target; for inline-prompt tasks the
- * markdown body is the prompt text.
+ * Tasks are stored as pure YAML files at `<stash>/tasks/<id>.yml`. Multi-line
+ * inline prompts use a YAML block scalar (`prompt: |`).
  */
 export const TASK_SCHEMA_VERSION = 1;

package/dist/tasks/validator.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Validate a parsed {@link TaskDocument} for runnability.
  *
@@ -36,12 +39,12 @@ export async function validateTaskDocument(task, options) {
         return;
     }
     // Prompt target. Resolve the profile unconditionally — when no profile is
-    // set on the task, requireAgentProfile falls back to config.agent.default
-    // and throws a clear error if neither is configured. Catching this at
+    // set on the task, requireAgentProfile falls back to defaults.agent and
+    // throws a clear error if neither is configured. Catching this at
     // `tasks add` / `tasks sync` time is much more useful than failing only
     // when the OS scheduler fires.
     const config = loadConfig();
-    requireAgentProfile(config.agent, task.target.profile);
+    requireAgentProfile(config, task.target.profile);
     const src = task.target.source;
     if (src.kind === "asset") {
         const stashDir = options.stashDir ?? resolveStashDir();

package/dist/version.js

@@ -1,3 +1,6 @@
+// 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 fs from "node:fs";
 import path from "node:path";
 // Version: prefer compile-time define, then package.json, then fallback

package/dist/wiki/wiki-templates.js

@@ -1,6 +1,9 @@
-import indexTemplate from "./index-template.md" with { type: "text" };
-import logTemplate from "./log-template.md" with { type: "text" };
-import schemaTemplate from "./schema-template.md" with { type: "text" };
+// 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 indexTemplate from "../assets/wiki/index-template.md" with { type: "text" };
+import logTemplate from "../assets/wiki/log-template.md" with { type: "text" };
+import schemaTemplate from "../assets/wiki/schema-template.md" with { type: "text" };
 export function buildSchemaMd(wikiName) {
     return schemaTemplate.replaceAll("{{WIKI_NAME}}", wikiName);
 }

package/dist/wiki/wiki.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Multi-wiki support for akm (issue #119).
  *
@@ -41,13 +44,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as yamlParse } from "yaml";
+import ingestWorkflowTemplate from "../assets/wiki/ingest-workflow-template.md" with { type: "text" };
 import { akmSearch } from "../commands/search";
 import { isWithin, todayIso } from "../core/common";
 import { getSources, loadUserConfig, saveConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { parseFrontmatter, parseFrontmatterBlock } from "../core/frontmatter";
 import { resolveSourceEntries } from "../indexer/search-source";
-import ingestWorkflowTemplate from "./ingest-workflow-template.md" with { type: "text" };
 import { buildIndexMd, buildLogMd, buildSchemaMd } from "./wiki-templates";
 // ── Constants ───────────────────────────────────────────────────────────────
 export const WIKIS_SUBDIR = "wikis";

package/dist/workflows/authoring.js

@@ -1,11 +1,14 @@
+// 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 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-spec";
 import { isWithin, resolveStashDir } from "../core/common";
 import { UsageError } from "../core/errors";
 import { warn } from "../core/warn";
 import { parseWorkflow } from "./parser";
-import workflowTemplate from "./workflow-template.md" with { type: "text" };
 const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
     title: "Example Workflow",
     firstStepTitle: "First Step",

package/dist/workflows/cli.js

@@ -1,3 +1,6 @@
+// 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 { UsageError } from "../core/errors";
 export const WORKFLOW_STEP_STATES = [
     "completed",

package/dist/workflows/db.js

@@ -1,7 +1,44 @@
+// 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 { Database } from "bun:sqlite";
 import fs from "node:fs";
 import path from "node:path";
 import { getWorkflowDbPath } from "../core/paths";
+/**
+ * workflow.db — Durable SQLite database for workflow run state.
+ *
+ * Owns the `workflow_runs` and `workflow_run_steps` tables that track active /
+ * completed workflow executions. Like `state.db` (and unlike `index.db`), the
+ * rows here are NON-REGENERABLE — losing them is data loss. Schema must evolve
+ * via incremental, additive migrations recorded in `schema_migrations`.
+ *
+ * ## Migration-safety contract
+ *
+ * The `schema_migrations` table records every applied migration by a stable
+ * string ID. `runMigrations(db)` is idempotent: new installs run every
+ * migration in order; upgrades run only the ones not yet applied. The
+ * migration framework here intentionally mirrors `src/core/state-db.ts` so
+ * future schema evolution follows a single proven pattern.
+ *
+ * Permitted schema evolution operations (always migration-safe in SQLite):
+ *   - ALTER TABLE … ADD COLUMN <name> <type> DEFAULT <value>
+ *   - CREATE INDEX IF NOT EXISTS …
+ *   - CREATE TABLE IF NOT EXISTS … (additive new tables)
+ *
+ * ## Bootstrapping pre-versioning databases
+ *
+ * Workflow databases created before this file gained `schema_migrations`
+ * already have the `workflow_runs.scope_key` column applied by the previous
+ * ad-hoc `PRAGMA table_info` + `ALTER TABLE` code. To avoid re-running the
+ * migration (which would no-op but still wastes work and clutters logs), the
+ * runner detects this state and back-fills the `schema_migrations` row for
+ * the scope-key migration before evaluating the migration list. See
+ * `bootstrapPreVersioningDb()`.
+ *
+ * @module workflows/db
+ */
+// ── Public API ───────────────────────────────────────────────────────────────
 export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     const dir = path.dirname(dbPath);
     if (!fs.existsSync(dir)) {
@@ -10,18 +47,29 @@ export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
     const db = new Database(dbPath);
     db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA foreign_keys = ON");
-    ensureWorkflowSchema(db);
+    ensureBaseSchema(db);
+    runMigrations(db);
     return db;
 }
 export function closeWorkflowDatabase(db) {
     db.close();
 }
-function ensureWorkflowSchema(db) {
+// ── Base schema ──────────────────────────────────────────────────────────────
+/**
+ * Create the baseline `workflow_runs` and `workflow_run_steps` tables if they
+ * do not exist. These statements are idempotent: existing databases keep their
+ * current schema, and migrations evolve them further.
+ *
+ * NOTE: the `scope_key` column on `workflow_runs` is intentionally NOT declared
+ * here. It is added by migration `001-add-scope-key`. Fresh databases will run
+ * the migration immediately on first open; pre-versioning databases that
+ * already have the column are bootstrapped — see {@link runMigrations}.
+ */
+function ensureBaseSchema(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS workflow_runs (
       id                TEXT PRIMARY KEY,
       workflow_ref      TEXT NOT NULL,
-      scope_key         TEXT,
       workflow_entry_id INTEGER,
       workflow_title    TEXT NOT NULL,
       status            TEXT NOT NULL CHECK (status IN ('active', 'completed', 'blocked', 'failed')),
@@ -53,12 +101,94 @@ function ensureWorkflowSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_workflow_run_steps_run_sequence
       ON workflow_run_steps(run_id, sequence_index);
   `);
-    const columns = db
-        .query("PRAGMA table_info(workflow_runs)")
-        .all()
-        .map((column) => column.name);
-    if (!columns.includes("scope_key")) {
-        db.exec("ALTER TABLE workflow_runs ADD COLUMN scope_key TEXT");
+}
+/**
+ * All workflow.db migrations in application order. New migrations are
+ * APPENDED — never inserted in the middle or reordered.
+ */
+const MIGRATIONS = [
+    // ── Migration 001 — add scope_key column ────────────────────────────────────
+    //
+    // Adds the `scope_key` column to `workflow_runs` so runs can be partitioned
+    // per stash/scope. Pre-versioning databases that already have this column
+    // are bootstrapped before this migration runs — see runMigrations().
+    {
+        id: "001-add-scope-key",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN scope_key TEXT;
+
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_scope_ref_status
+        ON workflow_runs(scope_key, workflow_ref, status);
+    `,
+    },
+];
+/**
+ * Stable id of the scope_key migration. Exported for bootstrap detection and
+ * tests.
+ */
+const SCOPE_KEY_MIGRATION_ID = "001-add-scope-key";
+/**
+ * Create the migrations table if it does not exist. Called unconditionally on
+ * every open so a fresh database bootstraps correctly.
+ */
+function ensureMigrationsTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id         TEXT    PRIMARY KEY,
+      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+/**
+ * Detect whether a column exists on a given table.
+ */
+function hasColumn(db, table, column) {
+    const rows = db.query(`PRAGMA table_info(${table})`).all();
+    return rows.some((r) => r.name === column);
+}
+/**
+ * Back-fill `schema_migrations` rows for any schema state that existed before
+ * this file gained migration tracking.
+ *
+ * The pre-versioning code added the `scope_key` column on `workflow_runs` via
+ * an ad-hoc PRAGMA / ALTER TABLE pair. Those databases must not re-run the
+ * scope_key migration (the ALTER would fail with "duplicate column name"
+ * since the migration body does not use IF NOT EXISTS — SQLite does not
+ * support that clause on ALTER TABLE ADD COLUMN). Instead, we mark the
+ * migration as already applied.
+ *
+ * This function is a no-op on fresh databases: the `scope_key` column does
+ * not exist, so the migration runs normally and records itself.
+ */
+function bootstrapPreVersioningDb(db) {
+    const alreadyRecorded = db.prepare("SELECT 1 FROM schema_migrations WHERE id = ?").get(SCOPE_KEY_MIGRATION_ID);
+    if (alreadyRecorded)
+        return;
+    if (hasColumn(db, "workflow_runs", "scope_key")) {
+        db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(SCOPE_KEY_MIGRATION_ID);
+    }
+}
+/**
+ * Apply every pending migration in a single transaction per migration.
+ *
+ * Each migration is applied in its own transaction so a failure in migration N
+ * does not roll back already-applied migrations 1..N-1. The migration row is
+ * inserted AFTER the DDL succeeds — a crash mid-migration leaves no row and
+ * the migration is retried on next open.
+ *
+ * Called automatically by {@link openWorkflowDatabase}.
+ */
+export function runMigrations(db) {
+    ensureMigrationsTable(db);
+    bootstrapPreVersioningDb(db);
+    const appliedRows = db.prepare("SELECT id FROM schema_migrations").all();
+    const applied = new Set(appliedRows.map((r) => r.id));
+    for (const migration of MIGRATIONS) {
+        if (applied.has(migration.id))
+            continue;
+        db.transaction(() => {
+            db.exec(migration.up);
+            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
+        })();
     }
-    db.exec("CREATE INDEX IF NOT EXISTS idx_workflow_runs_scope_ref_status ON workflow_runs(scope_key, workflow_ref, status)");
 }