akm-cli 0.7.5 → 0.8.0-rc2

package/dist/tasks/validator.js

@@ -0,0 +1,59 @@
+/**
+ * Validate a parsed {@link TaskDocument} for runnability.
+ *
+ * Enforces:
+ *   • the schedule is parseable and translates to the active backend
+ *   • the workflow ref resolves (workflow targets)
+ *   • the asset/file source exists (prompt targets)
+ *   • the agent profile resolves (prompt targets)
+ *
+ * Validation is deliberately split from parsing: callers that only want to
+ * read frontmatter (e.g. `tasks list`) can skip these checks, while
+ * `tasks add` and `tasks run` should always run them.
+ */
+import fs from "node:fs";
+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 { requireAgentProfile } from "../integrations/agent";
+import { resolveAssetPath } from "../sources/resolve";
+import { parseSchedule } from "./schedule";
+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);
+        if (ref.type !== "workflow") {
+            throw new NotFoundError(`Task "${task.id}" workflow target must be a workflow ref (got "${task.target.ref}").`, "WORKFLOW_NOT_FOUND");
+        }
+        await resolveAssetPath(stashDir, "workflow", ref.name);
+        return;
+    }
+    if (task.target.kind !== "prompt") {
+        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
+    // `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);
+    const src = task.target.source;
+    if (src.kind === "asset") {
+        const stashDir = options.stashDir ?? resolveStashDir();
+        const ref = parseAssetRef(src.ref);
+        await resolveAssetPath(stashDir, ref.type, ref.name);
+    }
+    else if (src.kind === "file") {
+        const taskDir = path.dirname(task.source.path);
+        const resolved = path.isAbsolute(src.path) ? src.path : path.resolve(taskDir, src.path);
+        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+            throw new NotFoundError(`Prompt file not found for task "${task.id}": ${src.path} (resolved to ${resolved}).`, "FILE_NOT_FOUND");
+        }
+    }
+    // inline source is always valid post-parse.
+}

package/dist/wiki/index-template.md

@@ -0,0 +1,12 @@
+---
+description: Catalog of pages in the {{WIKI_NAME}} wiki. Regenerated by `akm index`.
+wikiRole: index
+---
+
+# {{WIKI_NAME}} — index
+
+_This file is regenerated on every `akm index` run. Manual edits are
+preserved until the next regeneration, then replaced._
+
+_(no pages yet — create one with your editor, or ingest a source with `akm
+wiki stash {{WIKI_NAME}} <path>`.)_

package/dist/wiki/ingest-workflow-template.md

@@ -0,0 +1,54 @@
+# Ingest workflow for wiki:{{WIKI_NAME}}
+
+Wiki location: {{WIKI_DIR}}
+Schema: {{SCHEMA_PATH}}
+
+Follow these steps. akm commands handle the invariants; use your native
+Read/Write/Edit tools for page edits.
+
+1. **Read the schema.** Open `{{SCHEMA_PATH}}`. It defines the voice, page
+   kinds, contradiction policy, and any wiki-specific conventions. Do not
+   skip this step even on familiar wikis — the schema may have changed.
+
+2. **File the source under `raw/`.**
+   ```sh
+   akm wiki stash {{WIKI_NAME}} <path-or-url-to-source>
+   # or: cat <source> | akm wiki stash {{WIKI_NAME}} -
+   ```
+   Returns `{ slug, path, ref }`. The raw copy is immutable — never edit it.
+
+3. **Find related existing pages.**
+   ```sh
+   akm wiki search {{WIKI_NAME}} "<key terms from the source>"
+   ```
+   Read the top hits with `akm show wiki:{{WIKI_NAME}}/<page>`. Use
+   `akm show wiki:{{WIKI_NAME}}/<page> toc` for large pages.
+
+4. **Decide for each candidate.** For each related page:
+   - **Append**: add a section or paragraph under the relevant heading.
+     Include the raw source in the page's `sources:` frontmatter list.
+   - **Contradict**: note the tension explicitly; don't silently overwrite.
+     Follow the schema's contradiction policy.
+   - **Skip**: source doesn't add to this page — move on.
+
+5. **Create new pages for concepts/entities the source introduces.** Each
+   new page must have frontmatter with `description`, `pageKind`,
+   `xrefs`, and `sources`. Cross-reference with related pages both
+   directions.
+
+6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
+   page A. `akm wiki lint {{WIKI_NAME}}` will flag violations.
+
+7. **Append to `log.md`.** One entry per ingest: date, source slug, one-line
+   summary, refs to created/edited pages. Newest at the top.
+
+8. **Regenerate the index + verify.**
+   ```sh
+   akm index
+   akm wiki lint {{WIKI_NAME}}
+   ```
+   Resolve any lint findings before calling the ingest done.
+
+That's it. `akm` never calls an LLM — reasoning is your job; it just owns
+the invariants (raw immutability, unique slugs, ref validation, index
+regeneration, structural lint).

package/dist/wiki/log-template.md

@@ -0,0 +1,8 @@
+---
+description: Append-only log for the {{WIKI_NAME}} wiki. Newest entries at the top.
+wikiRole: log
+---
+
+# {{WIKI_NAME}} — log
+
+_Each entry: ISO date, operation, brief summary._

package/dist/wiki/schema-template.md

@@ -0,0 +1,61 @@
+---
+description: Rules that govern this wiki. Read before ingesting, searching, or editing pages.
+wikiRole: schema
+---
+
+# {{WIKI_NAME}} wiki schema
+
+This wiki follows the three-layer pattern:
+
+- `raw/` — immutable ingested sources (never edit)
+- `<page>.md` and `<topic>/<page>.md` — agent-authored pages
+- `schema.md` (this file), `index.md`, `log.md` — wiki-level metadata
+
+## Page frontmatter
+
+Every page should carry frontmatter so akm can index and link it:
+
+```yaml
+---
+description: one-sentence summary used in search and lint
+pageKind: entity | concept | question | note | <your-custom-kind>
+xrefs:
+  - wiki:{{WIKI_NAME}}/other-page
+sources:
+  - raw/<slug>.md
+---
+```
+
+`pageKind` accepts any non-empty string. Add new categories freely; they
+will surface in `index.md` as new sections after the next `akm index` run.
+
+## Three operations
+
+### Ingest
+
+1. Copy the new source into `raw/` with `akm wiki stash {{WIKI_NAME}} <path>`.
+2. Find related pages: `akm wiki search {{WIKI_NAME}} "<terms>"`.
+3. For each related page: append a section, note a contradiction, or create a
+   new page. Update xrefs on both sides.
+4. Cite the raw source in each touched page's `sources:` frontmatter.
+5. Append one entry to `log.md` describing what was assimilated.
+
+### Query
+
+1. `akm wiki search {{WIKI_NAME}} "<question>"` — find candidate pages.
+2. `akm show wiki:{{WIKI_NAME}}/<page>` — read the top hits.
+3. Compose the answer from the wiki; cite raw sources only when the wiki
+   points at them.
+
+### Lint
+
+1. `akm wiki lint {{WIKI_NAME}}` — deterministic structural checks.
+2. Resolve each finding: link orphans, fix broken xrefs, add descriptions,
+   cite uncited raws, refresh the index.
+
+## Hard rules
+
+- `raw/` is immutable. Never edit ingested sources.
+- Cross-references must point at pages that actually exist.
+- Prefer appending to an existing page over duplicating one.
+- Cite the raw source id (e.g. `raw/2026-04-foo.md`) when copying claims.

package/dist/wiki/wiki-templates.js

@@ -0,0 +1,12 @@
+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" };
+export function buildSchemaMd(wikiName) {
+    return schemaTemplate.replaceAll("{{WIKI_NAME}}", wikiName);
+}
+export function buildIndexMd(wikiName) {
+    return indexTemplate.replaceAll("{{WIKI_NAME}}", wikiName);
+}
+export function buildLogMd(wikiName) {
+    return logTemplate.replaceAll("{{WIKI_NAME}}", wikiName);
+}

package/dist/wiki/wiki.js

@@ -42,12 +42,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as yamlParse } from "yaml";
 import { akmSearch } from "../commands/search";
-import { isWithin } from "../core/common";
-import { loadUserConfig, saveConfig } from "../core/config";
+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 { buildIndexMd, buildLogMd, buildSchemaMd } from "../templates/wiki-templates";
+import ingestWorkflowTemplate from "./ingest-workflow-template.md" with { type: "text" };
+import { buildIndexMd, buildLogMd, buildSchemaMd } from "./wiki-templates";
 // ── Constants ───────────────────────────────────────────────────────────────
 export const WIKIS_SUBDIR = "wikis";
 export const SCHEMA_MD = "schema.md";
@@ -399,12 +400,11 @@ export function removeWiki(stashDir, name, options = {}) {
     const isStashWiki = fs.existsSync(wikiDir) && isRecognizedStashWiki(wikiDir);
     if (!isStashWiki && external) {
         const config = loadUserConfig();
-        const filteredSources = (config.sources ?? config.stashes ?? []).filter((entry) => entry.wikiName !== name);
+        const filteredSources = getSources(config).filter((entry) => entry.wikiName !== name);
         const installed = (config.installed ?? []).filter((entry) => entry.wikiName !== name);
         saveConfig({
             ...config,
             sources: filteredSources.length > 0 ? filteredSources : undefined,
-            stashes: undefined,
             installed: installed.length > 0 ? installed : undefined,
         });
         return {
@@ -665,7 +665,7 @@ function withRawFrontmatter(content, slug) {
     // tag the wikiRole for the indexer.
     if (content.startsWith("---"))
         return content;
-    const date = new Date().toISOString().slice(0, 10);
+    const date = todayIso();
     return `---\nwikiRole: raw\ningestedAt: ${date}\nslug: ${slug}\n---\n\n${content}`;
 }
 function ensureTrailingNewline(value) {
@@ -960,60 +960,9 @@ export function regenerateAllWikiIndexes(stashDir) {
 export function buildIngestWorkflow(stashDir, name) {
     const wikiDir = resolveWikiSource(stashDir, name).path;
     const schemaPath = path.join(wikiDir, SCHEMA_MD);
-    const workflow = `# Ingest workflow for wiki:${name}
-
-Wiki location: ${wikiDir}
-Schema: ${schemaPath}
-
-Follow these steps. akm commands handle the invariants; use your native
-Read/Write/Edit tools for page edits.
-
-1. **Read the schema.** Open \`${schemaPath}\`. It defines the voice, page
-   kinds, contradiction policy, and any wiki-specific conventions. Do not
-   skip this step even on familiar wikis — the schema may have changed.
-
-2. **File the source under \`raw/\`.**
-   \`\`\`sh
-   akm wiki stash ${name} <path-or-url-to-source>
-   # or: cat <source> | akm wiki stash ${name} -
-   \`\`\`
-   Returns \`{ slug, path, ref }\`. The raw copy is immutable — never edit it.
-
-3. **Find related existing pages.**
-   \`\`\`sh
-   akm wiki search ${name} "<key terms from the source>"
-   \`\`\`
-   Read the top hits with \`akm show wiki:${name}/<page>\`. Use
-   \`akm show wiki:${name}/<page> toc\` for large pages.
-
-4. **Decide for each candidate.** For each related page:
-   - **Append**: add a section or paragraph under the relevant heading.
-     Include the raw source in the page's \`sources:\` frontmatter list.
-   - **Contradict**: note the tension explicitly; don't silently overwrite.
-     Follow the schema's contradiction policy.
-   - **Skip**: source doesn't add to this page — move on.
-
-5. **Create new pages for concepts/entities the source introduces.** Each
-   new page must have frontmatter with \`description\`, \`pageKind\`,
-   \`xrefs\`, and \`sources\`. Cross-reference with related pages both
-   directions.
-
-6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
-   page A. \`akm wiki lint ${name}\` will flag violations.
-
-7. **Append to \`log.md\`.** One entry per ingest: date, source slug, one-line
-   summary, refs to created/edited pages. Newest at the top.
-
-8. **Regenerate the index + verify.**
-   \`\`\`sh
-   akm index
-   akm wiki lint ${name}
-   \`\`\`
-   Resolve any lint findings before calling the ingest done.
-
-That's it. \`akm\` never calls an LLM — reasoning is your job; it just owns
-the invariants (raw immutability, unique slugs, ref validation, index
-regeneration, structural lint).
-`;
+    const workflow = ingestWorkflowTemplate
+        .replaceAll("{{WIKI_NAME}}", name)
+        .replaceAll("{{WIKI_DIR}}", wikiDir)
+        .replaceAll("{{SCHEMA_PATH}}", schemaPath);
     return { wiki: name, path: wikiDir, schemaPath, workflow };
 }

package/dist/workflows/authoring.js

@@ -5,6 +5,7 @@ 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",
@@ -134,29 +135,8 @@ export function validateWorkflowSource(target) {
     return { path: target, parse: parseWorkflow(content, { path: target }) };
 }
 function renderWorkflowTemplate(input) {
-    return `---
-description: Describe what this workflow accomplishes
-tags:
-  - example
-params:
-  example_param: Explain this parameter
----
-
-# Workflow: ${input.title}
-
-## Step: ${input.firstStepTitle}
-Step ID: ${input.firstStepId}
-
-### Instructions
-Describe what to do in this step.
-
-### Completion Criteria
-- Confirm the first step is complete
-
-## Step: Second Step
-Step ID: second-step
-
-### Instructions
-Describe what happens next.
-`;
+    return workflowTemplate
+        .replace("{{TITLE}}", input.title)
+        .replace("{{FIRST_STEP_TITLE}}", input.firstStepTitle)
+        .replace("{{FIRST_STEP_ID}}", input.firstStepId);
 }

package/dist/workflows/renderer.js

@@ -8,6 +8,7 @@
  */
 import { makeAssetRef } from "../core/asset-ref";
 import { UsageError } from "../core/errors";
+import { registerMetadataContributor } from "../indexer/metadata-contributors";
 import { cacheWorkflowDocument } from "./document-cache";
 import { parseWorkflow } from "./parser";
 function shellQuote(value) {
@@ -54,8 +55,12 @@ export const workflowMdRenderer = {
             })),
         };
     },
-    extractMetadata(entry, ctx) {
-        const doc = loadDocument(ctx);
+};
+registerMetadataContributor({
+    name: "workflow-document-metadata",
+    appliesTo: ({ rendererName }) => rendererName === "workflow-md",
+    contribute(entry, { renderContext }) {
+        const doc = loadDocument(renderContext);
         const hints = new Set(entry.searchHints ?? []);
         hints.add(doc.title);
         for (const step of doc.steps) {
@@ -75,4 +80,4 @@ export const workflowMdRenderer = {
         }
         cacheWorkflowDocument(entry, doc);
     },
-};
+});

package/dist/workflows/runs.js

@@ -13,64 +13,58 @@ import { formatWorkflowErrors } from "./authoring";
 import { closeWorkflowDatabase, openWorkflowDatabase } from "./db";
 import { parseWorkflow } from "./parser";
 import { getCurrentWorkflowScopeKey } from "./scope-key";
+async function withWorkflowDb(fn) {
+    const db = openWorkflowDatabase();
+    try {
+        return await Promise.resolve(fn(db));
+    }
+    finally {
+        closeWorkflowDatabase(db);
+    }
+}
 export async function startWorkflowRun(ref, params = {}) {
     const asset = await loadWorkflowAsset(ref);
-    const workflowDb = openWorkflowDatabase();
-    try {
+    return withWorkflowDb(async (db) => {
         const now = new Date().toISOString();
         const runId = randomUUID();
         const scopeKey = getCurrentWorkflowScopeKey();
         const currentStepId = asset.steps[0]?.id ?? null;
         const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
-        workflowDb.transaction(() => {
-            workflowDb
-                .prepare(`INSERT INTO workflow_runs (
+        db.transaction(() => {
+            db.prepare(`INSERT INTO workflow_runs (
           id, workflow_ref, scope_key, workflow_entry_id, workflow_title, status, params_json, current_step_id, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)`)
-                .run(runId, asset.ref, scopeKey, workflowEntryId, asset.title, JSON.stringify(params), currentStepId, now, now);
-            const insertStep = workflowDb.prepare(`INSERT INTO workflow_run_steps (
+        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)`).run(runId, asset.ref, scopeKey, workflowEntryId, asset.title, JSON.stringify(params), currentStepId, now, now);
+            const insertStep = db.prepare(`INSERT INTO workflow_run_steps (
           run_id, step_id, step_title, instructions, completion_json, sequence_index, status
         ) VALUES (?, ?, ?, ?, ?, ?, 'pending')`);
             for (const step of asset.steps) {
                 insertStep.run(runId, step.id, step.title, step.instructions, step.completionCriteria ? JSON.stringify(step.completionCriteria) : null, step.sequenceIndex ?? 0);
             }
         })();
-        const result = getWorkflowStatus(runId);
+        const result = await getWorkflowStatus(runId);
         appendEvent({
             eventType: "workflow_started",
             ref: ref,
             metadata: { runId: result.run.id, title: result.run.workflowTitle },
         });
         return result;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function getWorkflowStatus(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const run = readWorkflowRun(workflowDb, runId);
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+export async function getWorkflowStatus(runId) {
+    return withWorkflowDb((db) => {
+        const run = readWorkflowRun(db, runId);
+        const steps = readWorkflowRunSteps(db, run.id);
         return buildWorkflowRunDetail(run, steps);
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function hasWorkflowRun(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const row = workflowDb.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
+export async function hasWorkflowRun(runId) {
+    return withWorkflowDb((db) => {
+        const row = db.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
         return !!row;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function listWorkflowRuns(input) {
-    const workflowDb = openWorkflowDatabase();
-    try {
+export async function listWorkflowRuns(input) {
+    return withWorkflowDb((db) => {
         const filters = [];
         const params = [];
         const scopeKey = getCurrentWorkflowScopeKey();
@@ -88,20 +82,16 @@ export function listWorkflowRuns(input) {
             filters.push("status IN ('active', 'blocked')");
         }
         const where = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
-        const rows = workflowDb
+        const rows = db
             .prepare(`SELECT * FROM workflow_runs ${where} ORDER BY updated_at DESC, created_at DESC`)
             .all(...params);
         return { runs: rows.map(toWorkflowRunSummary) };
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
 export async function getNextWorkflowStep(specifier, params) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const { run, autoStarted } = await resolveRunSpecifier(workflowDb, specifier, params);
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+    return withWorkflowDb(async (db) => {
+        const { run, autoStarted } = await resolveRunSpecifier(db, specifier, params);
+        const steps = readWorkflowRunSteps(db, run.id);
         const currentStep = resolveCurrentStep(run, steps);
         const done = run.status === "completed" ? true : undefined;
         return {
@@ -115,54 +105,44 @@ export async function getNextWorkflowStep(specifier, params) {
             ...(done ? { done } : {}),
             ...(autoStarted ? { autoStarted } : {}),
         };
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function resumeWorkflowRun(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const run = readWorkflowRun(workflowDb, runId);
+export async function resumeWorkflowRun(runId) {
+    return withWorkflowDb((db) => {
+        const run = readWorkflowRun(db, runId);
         if (run.status === "completed") {
             throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
         }
         if (run.status === "active") {
-            const steps = readWorkflowRunSteps(workflowDb, run.id);
+            const steps = readWorkflowRunSteps(db, run.id);
             return buildWorkflowRunDetail(run, steps);
         }
         // blocked or failed → flip back to active and re-open the current step so
         // it can be reclassified (completed, failed, skipped) after resuming.
         const now = new Date().toISOString();
-        workflowDb.transaction(() => {
+        db.transaction(() => {
             if (run.current_step_id) {
-                workflowDb
-                    .prepare(`UPDATE workflow_run_steps
+                db.prepare(`UPDATE workflow_run_steps
              SET status = 'pending', notes = NULL, evidence_json = NULL, completed_at = NULL
-             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`)
-                    .run(run.id, run.current_step_id);
+             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`).run(run.id, run.current_step_id);
             }
-            workflowDb.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
+            db.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
         })();
         const updated = { ...run, status: "active", updated_at: now };
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+        const steps = readWorkflowRunSteps(db, run.id);
         return buildWorkflowRunDetail(updated, steps);
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function completeWorkflowStep(input) {
-    const workflowDb = openWorkflowDatabase();
-    try {
+export async function completeWorkflowStep(input) {
+    return withWorkflowDb((db) => {
         let updatedRun;
         let refreshedSteps = [];
-        workflowDb.transaction(() => {
-            const run = readWorkflowRun(workflowDb, input.runId);
+        db.transaction(() => {
+            const run = readWorkflowRun(db, input.runId);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
-            const existing = workflowDb
+            const existing = db
                 .prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? AND step_id = ?")
                 .get(run.id, input.stepId);
             if (!existing) {
@@ -175,18 +155,14 @@ export function completeWorkflowStep(input) {
                 throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
             }
             const completedAt = new Date().toISOString();
-            workflowDb
-                .prepare(`UPDATE workflow_run_steps
+            db.prepare(`UPDATE workflow_run_steps
            SET status = ?, notes = ?, evidence_json = ?, completed_at = ?
-           WHERE run_id = ? AND step_id = ?`)
-                .run(input.status, input.notes?.trim() || null, input.evidence ? JSON.stringify(input.evidence) : null, completedAt, run.id, input.stepId);
-            refreshedSteps = readWorkflowRunSteps(workflowDb, run.id);
+           WHERE run_id = ? AND step_id = ?`).run(input.status, input.notes?.trim() || null, input.evidence ? JSON.stringify(input.evidence) : null, completedAt, run.id, input.stepId);
+            refreshedSteps = readWorkflowRunSteps(db, run.id);
             const state = deriveRunState(refreshedSteps);
-            workflowDb
-                .prepare(`UPDATE workflow_runs
+            db.prepare(`UPDATE workflow_runs
            SET status = ?, current_step_id = ?, updated_at = ?, completed_at = ?
-           WHERE id = ?`)
-                .run(state.status, state.currentStepId, completedAt, state.completedAt, run.id);
+           WHERE id = ?`).run(state.status, state.currentStepId, completedAt, state.completedAt, run.id);
             updatedRun = {
                 ...run,
                 status: state.status,
@@ -205,10 +181,7 @@ export function completeWorkflowStep(input) {
             appendEvent({ eventType: "workflow_finished", ref: detail.run.workflowRef, metadata: { runId: input.runId } });
         }
         return detail;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
 async function resolveRunSpecifier(db, specifier, params) {
     const explicitRun = db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(specifier);
@@ -262,7 +235,7 @@ async function loadWorkflowAsset(ref) {
     if (!assetPath) {
         throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
     }
-    const resolvedSourcePath = sourcePath ?? loadConfig().stashDir ?? assetPath;
+    const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
     const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
     const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
     const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
@@ -452,18 +425,13 @@ function parseJsonArray(value) {
     }
     return undefined;
 }
-export function getActiveWorkflowRun(scopeKey = getCurrentWorkflowScopeKey()) {
-    try {
-        const workflowDb = openWorkflowDatabase();
-        const row = workflowDb
+export async function getActiveWorkflowRun(scopeKey = getCurrentWorkflowScopeKey()) {
+    return withWorkflowDb((db) => {
+        const row = db
             .query("SELECT id, current_step_id, workflow_ref FROM workflow_runs WHERE scope_key = ? AND status IN ('active', 'blocked') ORDER BY updated_at DESC LIMIT 1")
             .get(scopeKey);
-        closeWorkflowDatabase(workflowDb);
         if (!row)
             return null;
         return { runId: row.id, stepId: row.current_step_id, workflowRef: row.workflow_ref };
-    }
-    catch {
-        return null; // fail-open: never crash show output due to DB error
-    }
+    }).catch(() => null); // fail-open: never crash show output due to DB error
 }

package/dist/workflows/validator.js

@@ -6,7 +6,7 @@
  * step-id format, and the frontmatter key whitelist.
  */
 const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params"]);
+const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated"]);
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
     checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
     checkStepIdFormat(draft, errors);