akm-cli 0.8.6 → 0.8.14

package/dist/sources/providers/git.js

@@ -5,15 +5,15 @@ import { spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "../../core/asset-spec";
-import { resolveStashDir } from "../../core/common";
-import { getSources, loadConfig } from "../../core/config";
-import { ConfigError, UsageError } from "../../core/errors";
-import { getRegistryCacheDir, getRegistryIndexCacheDir } from "../../core/paths";
-import { sanitizeCommitMessage } from "../../core/write-source";
-import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve";
-import { registerSourceProvider } from "../provider-factory";
-import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, isExpired, sanitizeString, } from "./provider-utils";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { resolveStashDir } from "../../core/common.js";
+import { getSources, loadConfig } from "../../core/config/config.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { getRegistryCacheDir, getRegistryIndexCacheDir } from "../../core/paths.js";
+import { sanitizeCommitMessage } from "../../core/write-source.js";
+import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve.js";
+import { registerSourceProvider } from "../provider-factory.js";
+import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, isExpired, sanitizeString, } from "./provider-utils.js";
 /** Cache TTL before refreshing the mirrored repo (12 hours). */
 const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 /** Maximum stale age allowed when refresh fails (7 days). */

package/dist/sources/providers/index.js

@@ -8,7 +8,7 @@
  * providers with the provider registry. This replaces the individual
  * side-effect imports that were duplicated in source-search.ts and source-show.ts.
  */
-import "./filesystem";
-import "./git";
-import "./npm";
-import "./website";
+import "./filesystem.js";
+import "./git.js";
+import "./npm.js";
+import "./website.js";

package/dist/sources/providers/npm.js

@@ -11,12 +11,12 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { ConfigError, UsageError } from "../../core/errors";
-import { getRegistryCacheDir } from "../../core/paths";
-import { parseRegistryRef, resolveRegistryArtifact } from "../../registry/resolve";
-import { registerSourceProvider } from "../provider-factory";
-import { applyAkmIncludeConfig, buildInstallCacheDir, computeFileHash, detectStashRoot, downloadArchive, isDirectory, } from "./provider-utils";
-import { extractTarGzSecure, verifyArchiveIntegrity } from "./tar-utils";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { getRegistryCacheDir } from "../../core/paths.js";
+import { parseRegistryRef, resolveRegistryArtifact } from "../../registry/resolve.js";
+import { registerSourceProvider } from "../provider-factory.js";
+import { applyAkmIncludeConfig, buildInstallCacheDir, computeFileHash, detectStashRoot, downloadArchive, isDirectory, } from "./provider-utils.js";
+import { extractTarGzSecure, verifyArchiveIntegrity } from "./tar-utils.js";
 /**
  * NPM source provider — fetches a tarball from the npm registry and extracts
  * it into a local cache. Implements the v1 {@link SourceProvider} interface

package/dist/sources/providers/provider-utils.js

@@ -1,12 +1,13 @@
 // 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 { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "../../core/asset-spec";
-import { fetchWithRetry } from "../../core/common";
-import { copyIncludedPaths, findNearestIncludeConfig } from "../include";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { fetchWithRetry } from "../../core/common.js";
+import { writeResponseToFile } from "../../runtime.js";
+import { copyIncludedPaths, findNearestIncludeConfig } from "../include.js";
 const REGISTRY_STASH_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
 /** Strip terminal control characters from untrusted strings. */
 export function sanitizeString(value, maxLength = 255) {
@@ -38,17 +39,19 @@ export function detectStashRoot(extractedDir) {
         return shallowest;
     return root;
 }
+/** A collision-resistant slug used to isolate cache dirs that lack a stable version. */
+function uniqueSlug() {
+    return randomUUID();
+}
 /**
  * Build a per-source cache directory under `cacheRootDir`.
  *
  * Versioned sources get `${source}-${id}/${version}` for cache reuse;
- * `local` sources get a unique timestamped slug so each install is isolated.
+ * `local` sources get a unique slug so each install is isolated.
  */
 export function buildInstallCacheDir(cacheRootDir, source, id, version) {
     const slug = `${source}-${id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "")}`;
-    const versionSlug = source === "local"
-        ? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
-        : (version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`);
+    const versionSlug = source === "local" ? uniqueSlug() : (version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? uniqueSlug());
     return path.join(cacheRootDir, slug || source, versionSlug);
 }
 /**
@@ -66,24 +69,14 @@ export function applyAkmIncludeConfig(sourceRoot, cacheDir, searchRoot = sourceR
     copyIncludedPaths(includeConfig.include, includeConfig.baseDir, selectedDir);
     return selectedDir;
 }
-/** Stream a remote archive to disk using Bun.write when available. */
+/** Stream a remote archive to disk via the runtime boundary's response writer. */
 export async function downloadArchive(url, destination) {
     const response = await fetchWithRetry(url, undefined, { timeout: 120_000 });
     if (!response.ok) {
         throw new Error(`Failed to download archive (${response.status}) from ${url}`);
     }
     // Stream response to disk instead of buffering the entire archive in memory.
-    // Uses Bun.write which handles Response streaming natively.
-    const BunRuntime = globalThis
-        .Bun;
-    if (BunRuntime?.write) {
-        await BunRuntime.write(destination, response);
-    }
-    else {
-        // Fallback for non-Bun environments (e.g., tests)
-        const arrayBuffer = await response.arrayBuffer();
-        fs.writeFileSync(destination, Buffer.from(arrayBuffer));
-    }
+    await writeResponseToFile(destination, response);
 }
 /** SHA-256 of a file, returned as `sha256:<hex>`. */
 export async function computeFileHash(filePath) {

package/dist/sources/providers/sync-from-ref.js

@@ -1,20 +1,20 @@
 // 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";
-import { parseRegistryRef } from "../../registry/resolve";
-import { detectStashRoot } from "./provider-utils";
+import { UsageError } from "../../core/errors.js";
+import { parseRegistryRef } from "../../registry/resolve.js";
+import { detectStashRoot } from "./provider-utils.js";
 export async function syncFromRef(ref, options) {
     const parsed = parseRegistryRef(ref);
     if (parsed.source === "local") {
         return syncLocalRef(parsed, options);
     }
     if (parsed.source === "npm") {
-        const { syncNpmRef } = await import("./npm");
+        const { syncNpmRef } = await import("./npm.js");
         return syncNpmRef(ref, options);
     }
     if (parsed.source === "git" || parsed.source === "github") {
-        const { syncRegistryGitRef } = await import("./git");
+        const { syncRegistryGitRef } = await import("./git.js");
         return syncRegistryGitRef(ref, options);
     }
     // Exhaustiveness — `parseRegistryRef` only emits the four sources above.

package/dist/sources/providers/tar-utils.js

@@ -16,8 +16,8 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { isWithin } from "../../core/common";
-import { warn } from "../../core/warn";
+import { isWithin } from "../../core/common.js";
+import { warn } from "../../core/warn.js";
 /**
  * Verify an archive's integrity against a known hash. Throws and removes
  * the archive when verification fails.

package/dist/sources/providers/website.js

@@ -1,8 +1,8 @@
 // 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 { registerSourceProvider } from "../provider-factory";
-import { ensureWebsiteMirror, getWebsiteCachePaths, validateWebsiteUrl } from "../website-ingest";
+import { registerSourceProvider } from "../provider-factory.js";
+import { ensureWebsiteMirror, getWebsiteCachePaths, validateWebsiteUrl } from "../website-ingest.js";
 /**
  * Website source provider — thin adapter over the shared website ingest module.
  */

package/dist/sources/resolve.js

@@ -3,11 +3,11 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS, } from "../core/asset-spec";
-import { hasErrnoCode, isWithin } from "../core/common";
-import { NotFoundError, UsageError } from "../core/errors";
-import { runMatchers } from "../indexer/file-context";
-import { walkStashFlat } from "../indexer/walker";
+import { deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS, } from "../core/asset/asset-spec.js";
+import { hasErrnoCode, isWithin } from "../core/common.js";
+import { NotFoundError, UsageError } from "../core/errors.js";
+import { runMatchers } from "../indexer/walk/file-context.js";
+import { walkStashFlat } from "../indexer/walk/walker.js";
 /**
  * Resolve an asset path from a stash directory, type, and name.
  */

package/dist/sources/website-ingest.js

@@ -4,11 +4,11 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, ResponseTooLargeError, readBodyWithByteCap } from "../core/common";
-import { ConfigError, UsageError } from "../core/errors";
-import { getRegistryIndexCacheDir } from "../core/paths";
-import { warn } from "../core/warn";
-import { isExpired, sanitizeString } from "./providers/provider-utils";
+import { fetchWithRetry, ResponseTooLargeError, readBodyWithByteCap } from "../core/common.js";
+import { ConfigError, UsageError } from "../core/errors.js";
+import { getRegistryIndexCacheDir } from "../core/paths.js";
+import { warn } from "../core/warn.js";
+import { isExpired, sanitizeString } from "./providers/provider-utils.js";
 /** Refresh website snapshots every 12 hours to balance freshness with scraping load. */
 const CACHE_REFRESH_INTERVAL_MS = 12 * 60 * 60 * 1000;
 /** Allow up to 7 days of stale snapshots when refresh fails so search remains available during outages. */

package/dist/storage/database.js

@@ -0,0 +1,102 @@
+// 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/.
+/**
+ * SQLite runtime boundary.
+ *
+ * Single source of truth for opening SQLite database handles. The rest of the
+ * codebase imports the {@link Database} type and {@link openDatabase} factory
+ * from here and NEVER imports `bun:sqlite` or `better-sqlite3` directly.
+ *
+ * Runtime selection:
+ *   - On Bun (the primary/test runtime) we use the built-in `bun:sqlite`.
+ *   - On Node.js (additive, not CI-tested this pass) we use `better-sqlite3`,
+ *     loaded via a runtime-gated dynamic `require` so the Bun path never
+ *     imports it (it is an optionalDependency and may be uninstalled or
+ *     uncompiled when running under Bun).
+ *
+ * Both driver handles are structurally compatible across the small surface AKM
+ * uses (`prepare`, `exec`, `run`, `transaction`, `close` on the handle;
+ * `get`, `all`, `run` on prepared statements). The Bun-specific `db.query()`
+ * helper is normalised away — callers use `db.prepare(sql).all(...)` instead.
+ *
+ * This file is intentionally NOT an adapter/DI/ports-and-adapters layer. It is
+ * a plain module: a structural type plus a factory function. The handle it
+ * returns is the real underlying driver instance (so e.g. `sqlite-vec`'s
+ * `load(db)` receives the genuine driver handle and works unchanged).
+ *
+ * @module storage/database
+ */
+import { createRequire } from "node:module";
+// Detect the runtime exactly once at module load.
+const isBun = !!process.versions?.bun;
+// A CommonJS-style require usable from this ESM module on both runtimes. Used
+// to load the runtime-specific driver lazily so that neither `bun:sqlite` (a
+// Bun built-in, unresolvable on Node) nor `better-sqlite3` (an optional native
+// dep, possibly absent under Bun) is statically imported.
+const nodeRequire = createRequire(import.meta.url);
+/**
+ * Open a SQLite database handle at `path`, selecting the driver for the current
+ * runtime. Returns a handle conforming to the structural {@link Database} type.
+ *
+ * The Node driver (`better-sqlite3`) is required lazily and ONLY when not on
+ * Bun, so importing this module under Bun never touches `better-sqlite3`.
+ */
+export function openDatabase(path, opts) {
+    if (isBun) {
+        return openBunDatabase(path, opts);
+    }
+    return openNodeDatabase(path, opts);
+}
+function openBunDatabase(path, opts) {
+    const { Database: BunDatabase } = loadBunSqlite();
+    // Only pass an options object when an option is actually set. bun:sqlite
+    // raises SQLITE_MISUSE if handed an options bag with all-undefined fields,
+    // and every current caller opens with just a path — so the no-opts path must
+    // remain byte-identical to the original `new Database(path)`.
+    const db = opts ? new BunDatabase(path, bunOptions(opts)) : new BunDatabase(path);
+    return db;
+}
+function bunOptions(opts) {
+    const out = {};
+    if (opts.readonly !== undefined)
+        out.readonly = opts.readonly;
+    if (opts.create !== undefined)
+        out.create = opts.create;
+    return out;
+}
+let bunSqliteModule;
+function loadBunSqlite() {
+    // `bun:sqlite` is a Bun built-in. This function is only ever called when
+    // `isBun` is true, so Node never resolves the `bun:` specifier. Loaded via
+    // require (not a static import) to keep Node's ESM resolver from choking on
+    // the `bun:` specifier when this module is merely imported under Node.
+    if (!bunSqliteModule) {
+        bunSqliteModule = nodeRequire("bun:sqlite");
+    }
+    return bunSqliteModule;
+}
+let betterSqlite3Ctor;
+function loadBetterSqlite3() {
+    if (!betterSqlite3Ctor) {
+        // Runtime-gated dynamic require: only reached when NOT on Bun, so Bun never
+        // resolves or loads the optional `better-sqlite3` native dependency.
+        const mod = nodeRequire("better-sqlite3");
+        betterSqlite3Ctor = mod.default ?? mod;
+    }
+    return betterSqlite3Ctor;
+}
+function openNodeDatabase(path, opts) {
+    const BetterSqlite3 = loadBetterSqlite3();
+    // better-sqlite3 validates option *values* strictly and throws
+    // `Expected the "readonly" option to be a boolean` if the key is present with
+    // an `undefined` value — so only include each option when it is actually set,
+    // matching the no-opts byte-identical path on the Bun side.
+    const options = {};
+    if (opts?.readonly !== undefined)
+        options.readonly = opts.readonly;
+    if (opts?.create === false)
+        options.fileMustExist = true;
+    const db = opts ? new BetterSqlite3(path, options) : new BetterSqlite3(path);
+    return db;
+}

package/dist/storage/engines/sqlite-migrations.js

@@ -0,0 +1,42 @@
+// 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/.
+/**
+ * Create the migrations ledger table if it does not exist. Must be called
+ * unconditionally on every open so a fresh database bootstraps correctly.
+ */
+export function ensureMigrationsTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id         TEXT    PRIMARY KEY,
+      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+/**
+ * Apply every pending migration, one 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, so a crash mid-migration leaves no row and
+ * the migration is retried on next open (all DDL in `up` uses IF NOT EXISTS so
+ * the retry is safe).
+ *
+ * @param db          The open SQLite database.
+ * @param migrations  The module's ordered, append-only migration list.
+ * @param opts        Optional `bootstrap` hook (see {@link RunMigrationsOptions}).
+ */
+export function runMigrations(db, migrations, opts) {
+    ensureMigrationsTable(db);
+    opts?.bootstrap?.(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);
+        })();
+    }
+}

package/dist/storage/locations.js

@@ -0,0 +1,25 @@
+// 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 { getCacheDir, getConfigDir, getDataDir, getDbPath, getDefaultStashDir, getLockfileLockPath, getLockfilePath, getWorkflowDbPath, } from "../core/paths.js";
+import { getStateDbPath } from "../core/state-db.js";
+/**
+ * Resolve the current {@link StorageLocations} by delegating to the existing
+ * path getters. Resolution honours the same environment overrides
+ * (`AKM_DATA_DIR`, XDG variables, transient-stash isolation) as the underlying
+ * getters, so this is safe to call at boot or per-operation — it carries no
+ * cached state of its own.
+ */
+export function resolveStorageLocations() {
+    return {
+        indexDb: getDbPath(),
+        stateDb: getStateDbPath(),
+        workflowDb: getWorkflowDbPath(),
+        lockfile: getLockfilePath(),
+        lockfileSentinel: getLockfileLockPath(),
+        dataDir: getDataDir(),
+        cacheDir: getCacheDir(),
+        configDir: getConfigDir(),
+        stashDir: getDefaultStashDir(),
+    };
+}

package/dist/storage/repositories/index-db.js

@@ -0,0 +1,43 @@
+// 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 { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
+import { resolveStorageLocations } from "../locations.js";
+/**
+ * Scoped-resource (loan pattern) helper for the index database (`index.db`).
+ *
+ * This is the `index.db` twin of {@link ../../workflows/db withWorkflowDb} /
+ * {@link ./workflow-runs-repository withWorkflowRunsRepo}: it opens the index
+ * database bound to {@link StorageLocations.indexDb}, runs `fn` against the live
+ * {@link Database}, and closes the connection exactly once when `fn` returns —
+ * even if `fn` throws. Callers no longer hand-roll `open / try / finally / close`
+ * around `index.db`, and the dead `existingDb?` caller-owns ownership flag
+ * (search.ts / show.ts) is eliminated: every former call site passed
+ * `undefined`, so the connection was always opened and always closed here.
+ *
+ * ## Connection-lifetime contract (WS5)
+ *
+ * `fn` MUST fully materialise any result set (`.all()` / `.get()` into plain
+ * values or array copies) and return plain values BEFORE it returns. It MUST
+ * NOT return a live statement iterator or cursor across the scope boundary,
+ * because the connection is closed the instant `fn` settles — a leaked cursor
+ * would be read against a closed database.
+ *
+ * This helper is intentionally **synchronous**. The migrated call sites are
+ * synchronous fire-and-forget telemetry writers; keeping the lifecycle sync
+ * preserves their exact (non-deferred) timing — opening the DB, doing the work,
+ * and closing it within the same tick, identical to the inline blocks it
+ * replaces.
+ *
+ * @param fn Receives the open index database; must finish all DB work before returning.
+ * @returns Whatever `fn` returns.
+ */
+export function withIndexDb(fn) {
+    const db = openExistingDatabase(resolveStorageLocations().indexDb);
+    try {
+        return fn(db);
+    }
+    finally {
+        closeDatabase(db);
+    }
+}

package/dist/storage/repositories/workflow-runs-repository.js

@@ -0,0 +1,141 @@
+// 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 { closeWorkflowDatabase, openWorkflowDatabase } from "../../workflows/db.js";
+import { resolveStorageLocations } from "../locations.js";
+/**
+ * Repository owning every raw SQL statement against `workflow_runs` and
+ * `workflow_run_steps`. It is DB-location-agnostic: the lifecycle helper
+ * {@link withWorkflowRunsRepo} binds it to {@link StorageLocations.workflowDb}
+ * so a future storage move (#489) changes only `locations.ts`.
+ *
+ * ## Connection-lifetime contract (WS5)
+ *
+ * Every read method fully materialises its result set (`.all()` / `.get()` into
+ * plain values/arrays) before returning. The repository NEVER hands a live
+ * statement iterator or cursor back across the {@link withWorkflowRunsRepo}
+ * scope boundary, so the connection can be closed immediately after `fn`
+ * resolves without truncating lazy iteration.
+ */
+export class WorkflowRunsRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Escape hatch for the transaction-bounded write paths still orchestrated
+     * in runs.ts. The repository owns the SQL; the caller owns the transaction
+     * boundary (unchanged from the pre-extraction `db.transaction(() => …)`). */
+    transaction(fn) {
+        return this.db.transaction(fn)();
+    }
+    // ── reads (fully materialised) ─────────────────────────────────────────────
+    findActiveRunForScope(workflowRef, scopeKey) {
+        return this.db
+            .prepare("SELECT id, current_step_id FROM workflow_runs WHERE workflow_ref = ? AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1")
+            .get(workflowRef, scopeKey);
+    }
+    getRunById(runId) {
+        return this.db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(runId);
+    }
+    getActiveRunRowForScope(workflowRef, scopeKey) {
+        return this.db
+            .prepare("SELECT * FROM workflow_runs WHERE workflow_ref = ? AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1")
+            .get(workflowRef, scopeKey);
+    }
+    hasRun(runId) {
+        const row = this.db.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
+        return !!row;
+    }
+    listRuns(filter) {
+        const filters = [];
+        const params = [];
+        filters.push("scope_key = ?");
+        params.push(filter.scopeKey);
+        if (filter.workflowRef) {
+            filters.push("workflow_ref = ?");
+            params.push(filter.workflowRef);
+        }
+        if (filter.activeOnly) {
+            filters.push("status IN ('active', 'blocked')");
+        }
+        const where = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
+        return this.db
+            .prepare(`SELECT * FROM workflow_runs ${where} ORDER BY updated_at DESC, created_at DESC`)
+            .all(...params);
+    }
+    getStepsForRun(runId) {
+        return this.db
+            .prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? ORDER BY sequence_index ASC")
+            .all(runId);
+    }
+    getStep(runId, stepId) {
+        return this.db.prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? AND step_id = ?").get(runId, stepId);
+    }
+    findActiveOrBlockedRunForScope(scopeKey) {
+        return (this.db
+            .prepare("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) ?? null);
+    }
+    // ── writes ─────────────────────────────────────────────────────────────────
+    insertRun(input) {
+        this.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,
+          agent_harness, agent_session_id, checkin_armed_at
+        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.id, input.workflowRef, input.scopeKey, input.workflowEntryId, input.workflowTitle, input.paramsJson, input.currentStepId, input.createdAt, input.updatedAt, input.agentHarness, input.agentSessionId, input.checkinArmedAt);
+    }
+    insertSteps(steps) {
+        const insertStep = this.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 steps) {
+            insertStep.run(step.runId, step.stepId, step.stepTitle, step.instructions, step.completionJson, step.sequenceIndex);
+        }
+    }
+    reopenStepsForResume(runId, currentStepId) {
+        this.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(runId, currentStepId);
+    }
+    markRunActive(runId, updatedAt) {
+        this.db.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(updatedAt, runId);
+    }
+    updateStepCompletion(input) {
+        this.db
+            .prepare(`UPDATE workflow_run_steps
+           SET status = ?, notes = ?, evidence_json = ?, summary = ?, completed_at = ?
+           WHERE run_id = ? AND step_id = ?`)
+            .run(input.status, input.notes, input.evidenceJson, input.summary, input.completedAt, input.runId, input.stepId);
+    }
+    updateRunState(input) {
+        this.db
+            .prepare(`UPDATE workflow_runs
+           SET status = ?, current_step_id = ?, updated_at = ?, completed_at = ?, checkin_armed_at = ?
+           WHERE id = ?`)
+            .run(input.status, input.currentStepId, input.updatedAt, input.completedAt, input.checkinArmedAt, input.runId);
+    }
+    rearmCheckin(runId, checkinArmedAt) {
+        this.db.prepare("UPDATE workflow_runs SET checkin_armed_at = ? WHERE id = ?").run(checkinArmedAt, runId);
+    }
+}
+/**
+ * Open the workflow database (bound to {@link StorageLocations.workflowDb}),
+ * run `fn` against a {@link WorkflowRunsRepository}, and close the connection
+ * exactly once when `fn` settles.
+ *
+ * Generalises the former `withWorkflowDb` loan pattern in runs.ts. Repository
+ * read methods fully materialise their results, so closing here never truncates
+ * lazy iteration (WS5 connection-lifetime rule).
+ */
+export async function withWorkflowRunsRepo(fn) {
+    const db = openWorkflowDatabase(resolveStorageLocations().workflowDb);
+    try {
+        return await Promise.resolve(fn(new WorkflowRunsRepository(db)));
+    }
+    finally {
+        closeWorkflowDatabase(db);
+    }
+}

package/dist/tasks/backends/cron.js

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

package/dist/tasks/backends/exec-utils.js

@@ -2,6 +2,38 @@
 // 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 { spawnSync } from "node:child_process";
+import fs from "node:fs";
+/**
+ * Default exec strategy: run commands synchronously via {@link spawnCommand}.
+ *
+ * This is the shared default for every task backend's `exec` seam. Backends
+ * that need extra fields (e.g. launchd's `uid()`) spread this and add them.
+ */
+export function nodeExec() {
+    return {
+        run(args) {
+            return spawnCommand(args);
+        },
+    };
+}
+/**
+ * Default filesystem strategy for the shared subset of the backend `fs` seam
+ * (`writeFile` + `ensureDir`), backed by `node:fs`.
+ *
+ * Backends spread this and add their own members. Note `removeFile` is NOT
+ * shared here: the launchd and schtasks defaults differ observably (schtasks
+ * swallows errors; launchd does not), so each keeps its own.
+ */
+export function nodeFs() {
+    return {
+        writeFile(file, content) {
+            fs.writeFileSync(file, content, { encoding: "utf8" });
+        },
+        ensureDir(dir) {
+            fs.mkdirSync(dir, { recursive: true });
+        },
+    };
+}
 /**
  * Run a command synchronously, normalizing null results to safe defaults.
  * args[0] is the binary; args[1..] are its arguments.

package/dist/tasks/backends/index.js

@@ -1,9 +1,9 @@
 // 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 { CRON_BACKEND } from "./cron";
-import { LAUNCHD_BACKEND } from "./launchd";
-import { SCHTASKS_BACKEND } from "./schtasks";
+import { CRON_BACKEND } from "./cron.js";
+import { LAUNCHD_BACKEND } from "./launchd.js";
+import { SCHTASKS_BACKEND } from "./schtasks.js";
 export function selectBackend(options = {}) {
     const platform = options.platform ?? process.platform;
     switch (platform) {