akm-cli 0.9.11 → 0.9.13

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

@@ -15,12 +15,12 @@ import { createRequire } from "node:module";
 import { ConfigError } from "../../core/errors.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
-import { warn } from "../../core/warn.js";
+import { warn, warnOnce } from "../../core/warn.js";
 import { openDatabase } from "../database.js";
 import { openManagedDatabase } from "../managed-db.js";
 import { SQLITE_BUSY_TIMEOUT_MS } from "../sqlite-pragmas.js";
-import { openSqliteReadSnapshot } from "../sqlite-read-snapshot.js";
-import { isCanonicalIndexGeneration } from "./index-entry-schema.js";
+import { openSqliteReadSnapshot, SqliteReadSnapshotUnavailableError } from "../sqlite-read-snapshot.js";
+import { CANONICAL_INDEX_DB_VERSION, classifyIndexGeneration, isCanonicalIndexGeneration } from "./index-entry-schema.js";
 import { ensureSchema } from "./index-schema.js";
 import { loadVecExtension, warnIfVecMissing } from "./index-vec-repository.js";
 /**
@@ -130,15 +130,19 @@ export function openExistingDatabase(dbPath) {
         path: resolvedPath,
         init: (db) => {
             loadVecExtension(db);
-            assertCanonicalIndexGeneration(db, resolvedPath);
+            warnIfNonCanonicalIndexGeneration(db, resolvedPath);
         },
         create: false,
     });
 }
-function assertCanonicalIndexGeneration(db, resolvedPath) {
+function warnIfNonCanonicalIndexGeneration(db, resolvedPath) {
     if (isCanonicalIndexGeneration(db))
         return;
-    throw new ConfigError(`Index database uses an incompatible derived schema: ${resolvedPath}.`, "INDEX_SCHEMA_INCOMPATIBLE");
+    const classification = classifyIndexGeneration(db);
+    warnOnce(`index-read-noncanonical:${resolvedPath}`, `Index database at ${resolvedPath} does not match this akm's derived schema (stored generation ` +
+        `${classification.storedVersion ?? "unknown"}; this binary understands ${CANONICAL_INDEX_DB_VERSION}). ` +
+        "Reading it as-is; a query that needs a table or column this generation lacks will fail on its own. " +
+        "Run 'akm index' to rebuild it for this binary.");
 }
 /**
  * Refuse to treat an UNREADABLE index as a missing one (#791).
@@ -160,6 +164,21 @@ export function assertIndexPathReadable(resolvedPath) {
         return;
     throw new ConfigError(`Index database exists but is not readable: ${describeInaccessiblePath(resolvedPath, code)}.`, "DATA_DIR_UNREADABLE");
 }
+function openPlainReadonly(resolvedPath) {
+    return openDatabase(resolvedPath, { readonly: true, create: false });
+}
+function openIsolatedSnapshotOrFallBack(resolvedPath) {
+    try {
+        return openSqliteReadSnapshot(resolvedPath);
+    }
+    catch (error) {
+        if (!(error instanceof SqliteReadSnapshotUnavailableError))
+            throw error;
+        warnOnce(`index-read-snapshot-unavailable:${resolvedPath}`, `Could not take a non-mutating snapshot of ${resolvedPath} (${error.message}) — falling back to a plain ` +
+            "read-only open of the index database.");
+        return openPlainReadonly(resolvedPath);
+    }
+}
 /**
  * Open an existing index for queries without changing the source database or
  * running schema initialization. The default path attaches read-only to the
@@ -173,9 +192,7 @@ export function openReadonlyExistingDatabase(dbPath, options) {
     assertIndexPathReadable(resolvedPath);
     if (classifyPathAccess(resolvedPath).access === "absent")
         return undefined;
-    const db = options?.isolatedSnapshot
-        ? openSqliteReadSnapshot(resolvedPath)
-        : openDatabase(resolvedPath, { readonly: true, create: false });
+    const db = options?.isolatedSnapshot ? openIsolatedSnapshotOrFallBack(resolvedPath) : openPlainReadonly(resolvedPath);
     if (!db)
         return undefined;
     // This opener bypasses openManagedDatabase/applyStandardPragmas by design (no
@@ -187,7 +204,7 @@ export function openReadonlyExistingDatabase(dbPath, options) {
     // connection, so apply just that one.
     try {
         db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
-        assertCanonicalIndexGeneration(db, resolvedPath);
+        warnIfNonCanonicalIndexGeneration(db, resolvedPath);
         return db;
     }
     catch (error) {

package/dist/storage/repositories/index-entry-schema.js

@@ -244,10 +244,27 @@ export function hasCanonicalEntrySchema(db) {
         return false;
     }
 }
-export function isCanonicalIndexGeneration(db) {
+export function classifyIndexGeneration(db) {
+    let storedVersion;
     try {
         const row = db.prepare("SELECT value FROM index_meta WHERE key = 'version'").get();
-        return row?.value === String(CANONICAL_INDEX_DB_VERSION) && hasCanonicalEntrySchema(db);
+        storedVersion = row?.value;
+    }
+    catch {
+        storedVersion = undefined;
+    }
+    if (storedVersion === String(CANONICAL_INDEX_DB_VERSION) && hasCanonicalEntrySchema(db)) {
+        return { status: "canonical", storedVersion };
+    }
+    const storedNumeric = storedVersion === undefined ? undefined : Number(storedVersion);
+    if (storedNumeric !== undefined && Number.isFinite(storedNumeric) && storedNumeric > CANONICAL_INDEX_DB_VERSION) {
+        return { status: "newer", storedVersion };
+    }
+    return { status: "older", storedVersion };
+}
+export function isCanonicalIndexGeneration(db) {
+    try {
+        return classifyIndexGeneration(db).status === "canonical";
     }
     catch {
         return false;

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

@@ -1,7 +1,18 @@
 // 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 { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, isCanonicalIndexGeneration, } from "./index-entry-schema.js";
+/**
+ * index.db schema and version stamps, kept in the
+ * storage layer. This isolates the one genuinely risky area (schema
+ * evolution) from the CRUD/FTS/vector queries.
+ *
+ * The meta accessors, embedding purge, and vec-availability probe that
+ * `ensureSchema` leans on live in the sibling `index-meta-repository` /
+ * `index-vec-repository` modules.
+ */
+import { ConfigError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
+import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, classifyIndexGeneration, isCanonicalIndexGeneration, } from "./index-entry-schema.js";
 import { getMeta, setMeta } from "./index-meta-repository.js";
 import { isVecAvailable, purgeEmbeddings } from "./index-vec-repository.js";
 // ── Constants ───────────────────────────────────────────────────────────────
@@ -165,6 +176,15 @@ function rebuildIncompatibleIndexGeneration(db) {
         return;
     if (isCanonicalIndexGeneration(db))
         return;
+    const classification = classifyIndexGeneration(db);
+    if (classification.status === "newer") {
+        throw new ConfigError(`Index database was built by a newer akm (stored generation ${classification.storedVersion ?? "unknown"}; ` +
+            `this binary understands generation ${CANONICAL_INDEX_DB_VERSION}). Refusing to modify it — upgrade akm to ` +
+            "write to this index, or delete index.db to rebuild it from scratch with this binary.", "INDEX_SCHEMA_INCOMPATIBLE");
+    }
+    warn(`Index database generation ${classification.storedVersion ?? "unknown"} is older than this akm's generation ` +
+        `${CANONICAL_INDEX_DB_VERSION} — rebuilding the derived index (entries, FTS, embeddings, graph tables, ` +
+        "utility scores, and the LLM enrichment cache). This re-walks and re-indexes every source on the next run.");
     let vecResetPending = false;
     try {
         db.exec("DROP TABLE IF EXISTS entries_vec");
@@ -326,12 +346,16 @@ export function ensureSchema(db, embeddingDim) {
     //   - When `embeddingDim` is a number, the caller explicitly asked for
     //     that dim and owns the dim-change/backup/wipe semantics.
     const dimExplicit = embeddingDim !== undefined;
-    const effectiveDim = embeddingDim ?? (Number(getMeta(db, "embeddingDim")) || EMBEDDING_DIM);
+    const requestedDim = embeddingDim ?? (Number(getMeta(db, "embeddingDim")) || EMBEDDING_DIM);
+    const effectiveDim = Number.isInteger(requestedDim) && requestedDim > 0 ? requestedDim : EMBEDDING_DIM;
+    if (effectiveDim !== requestedDim) {
+        warn(`Invalid embedding dimension ${requestedDim} — falling back to the default (${EMBEDDING_DIM}).`);
+    }
     if (isVecAvailable(db)) {
         // Check if stored embedding dimension differs from configured one
         if (dimExplicit) {
             const storedDim = getMeta(db, "embeddingDim");
-            if (storedDim && storedDim !== String(embeddingDim)) {
+            if (storedDim && storedDim !== String(effectiveDim)) {
                 // Stored vectors are incompatible with the new dimension. Drop the vec
                 // table so the block below recreates it at the new width; the BLOB rows
                 // go too. Regenerable from markdown — re-embedded by the next index.
@@ -340,9 +364,6 @@ export function ensureSchema(db, embeddingDim) {
         }
         const vecExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entries_vec'").get();
         if (!vecExists) {
-            if (!Number.isInteger(effectiveDim) || effectiveDim <= 0 || effectiveDim > 4096) {
-                throw new Error(`Invalid embedding dimension: ${effectiveDim}`);
-            }
             db.exec(`
         CREATE VIRTUAL TABLE entries_vec USING vec0(
           id       INTEGER PRIMARY KEY,
@@ -351,7 +372,7 @@ export function ensureSchema(db, embeddingDim) {
       `);
         }
         if (dimExplicit) {
-            setMeta(db, "embeddingDim", String(embeddingDim));
+            setMeta(db, "embeddingDim", String(effectiveDim));
         }
     }
     else {
@@ -361,11 +382,11 @@ export function ensureSchema(db, embeddingDim) {
         // changes, those stored BLOBs become silently incompatible.
         if (dimExplicit) {
             const storedDim = getMeta(db, "embeddingDim");
-            if (storedDim && storedDim !== String(embeddingDim)) {
+            if (storedDim && storedDim !== String(effectiveDim)) {
                 // JS-fallback path: no vec table, just clear the stale BLOB vectors.
                 purgeEmbeddings(db);
             }
-            setMeta(db, "embeddingDim", String(embeddingDim));
+            setMeta(db, "embeddingDim", String(effectiveDim));
         }
     }
     // Usage telemetry (usage_events) lives in state.db since Chunk-8 WI-8.3 —

package/dist/storage/repositories/proposals-repository.js

@@ -13,6 +13,7 @@ import path from "node:path";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { bundleRefToString, isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { warnOnce } from "../../core/warn.js";
+import { escapeLikePattern } from "../like-pattern.js";
 /** Serialize `Proposal.changes` for `metadata_json` (see {@link StoredFileChange}). */
 function changesToStored(changes) {
     return changes.map((c, i) => ({
@@ -390,7 +391,7 @@ export function getStateProposal(db, id, stashDir) {
  * `%` / `_` / `\` in the prefix are escaped so the LIKE pattern is literal.
  */
 export function listStateProposalIdsByPrefix(db, stashDir, idPrefix) {
-    const escaped = idPrefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+    const escaped = escapeLikePattern(idPrefix);
     const rows = db
         .prepare(`SELECT id FROM proposals
        WHERE stash_dir = ? AND status = 'pending' AND id LIKE ? ESCAPE '\\'

package/dist/storage/repositories/task-history-repository.js

@@ -10,6 +10,7 @@
  * @module task-history-repository
  */
 import { isRecord } from "../../core/common.js";
+import { warnOnce } from "../../core/warn.js";
 function metadataError(message) {
     throw new Error(`invalid task_history metadata_json: ${message}`);
 }
@@ -18,10 +19,6 @@ function validateDetail(value) {
         return;
     if (!isRecord(value))
         metadataError("detail must be an object or null");
-    const allowed = new Set(["runId", "reason", "error", "exitCode"]);
-    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
-    if (unknown.length > 0)
-        metadataError(`unknown detail fields: ${unknown.sort().join(", ")}`);
     for (const field of ["runId", "reason", "error"]) {
         if (value[field] !== undefined && typeof value[field] !== "string")
             metadataError(`detail.${field} must be a string`);
@@ -60,7 +57,8 @@ export function decodeTaskHistoryMetadata(input) {
     if (!isRecord(parsed))
         metadataError("root must be an object");
     if (parsed.metadataVersion !== undefined && parsed.metadataVersion !== 2) {
-        metadataError(`unsupported metadataVersion: ${String(parsed.metadataVersion)}`);
+        warnOnce(`task-history-metadata-version:${String(parsed.metadataVersion)}`, `task_history row has metadataVersion ${String(parsed.metadataVersion)}, newer than this akm's 2 — ` +
+            "decoding it best-effort as version 2 rather than rejecting the row.");
     }
     if (typeof parsed.durationMs !== "number")
         metadataError("durationMs must be a number");
@@ -69,13 +67,22 @@ export function decodeTaskHistoryMetadata(input) {
         metadataError("engine must be a string or null");
     }
     if (parsed.targetVocab !== undefined && parsed.targetVocab !== 2) {
-        metadataError("targetVocab must be 2 when present");
+        warnOnce(`task-history-target-vocab:${String(parsed.targetVocab)}`, `task_history row has targetVocab ${String(parsed.targetVocab)}, newer than this akm's 2 — falling back to ` +
+            "the legacy target_kind mapping rather than rejecting the row.");
     }
     validateDetail(detail);
+    const cleanDetail = detail
+        ? {
+            ...(detail.runId !== undefined ? { runId: detail.runId } : {}),
+            ...(detail.reason !== undefined ? { reason: detail.reason } : {}),
+            ...(detail.error !== undefined ? { error: detail.error } : {}),
+            ...(detail.exitCode !== undefined ? { exitCode: detail.exitCode } : {}),
+        }
+        : null;
     return {
         metadataVersion: 2,
         durationMs: parsed.durationMs,
-        detail: detail ?? null,
+        detail: cleanDetail,
         ...(parsed.engine !== undefined ? { engine: parsed.engine } : {}),
         ...(parsed.targetVocab === 2 ? { targetVocab: 2 } : {}),
     };

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

@@ -2,9 +2,11 @@
 // 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 { randomUUID } from "node:crypto";
-import { UsageError } from "../../core/errors.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
 import { openStateDatabase, withImmediateTransaction } from "../../core/state-db.js";
 import { borrowScopedStateDb, withStateDbScope } from "../../core/state-db-scope.js";
+import { sleepSync } from "../../runtime.js";
+import { escapeLikePattern } from "../like-pattern.js";
 import { resolveStorageLocations } from "../locations.js";
 import { insertEventOnce, insertEventStrict } from "./events-repository.js";
 function assertAttemptReservationLease(input, run) {
@@ -20,6 +22,51 @@ function assertAttemptReservationLease(input, run) {
         throw new UsageError(`Workflow run ${input.runId} engine lease expired before durable dispatch reservation.`, "RESOURCE_ALREADY_EXISTS");
     }
 }
+/**
+ * Whether `error` is one of the specific SQLite conditions a run-lease
+ * statement can throw under real cross-process contention on the same row:
+ * `SQLITE_BUSY`/`SQLITE_LOCKED` (both drivers), or the message text a
+ * transient contention blip has been observed producing, "database is
+ * locked", "disk I/O error", or "database disk image is malformed".
+ * Matching on this set alone is never sufficient to call something lease
+ * contention — see {@link WorkflowRunsRepository.acquireEngineLease}, which
+ * additionally requires a fresh read confirming a live lease before
+ * substituting the lease-held message for the original error.
+ */
+function isLeaseContentionSqliteError(error) {
+    const code = error?.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED")
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return (message.includes("database is locked") ||
+        message.includes("disk I/O error") ||
+        message.includes("database disk image is malformed"));
+}
+const LEASE_RETRY_ATTEMPTS = 4;
+const LEASE_RETRY_BASE_DELAY_MS = 15;
+/**
+ * Retry a single lease statement across a short, bounded set of attempts when
+ * it throws one of {@link isLeaseContentionSqliteError}'s conditions —
+ * absorbing a blip that a fresh attempt on the same connection clears on its
+ * own. Any other error, or the same error surviving every attempt, propagates
+ * unchanged; this never converts a persistent failure into a false success.
+ */
+function runLeaseStatementWithRetry(fn) {
+    let lastError;
+    for (let attempt = 0; attempt < LEASE_RETRY_ATTEMPTS; attempt += 1) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            if (!isLeaseContentionSqliteError(error))
+                throw error;
+            lastError = error;
+            if (attempt < LEASE_RETRY_ATTEMPTS - 1)
+                sleepSync(LEASE_RETRY_BASE_DELAY_MS * 2 ** attempt);
+        }
+    }
+    throw lastError;
+}
 /**
  * Repository owning every raw SQL statement against `workflow_runs` and
  * `workflow_run_steps`. It is DB-location-agnostic: the lifecycle helper
@@ -96,6 +143,19 @@ export class WorkflowRunsRepository {
         const row = this.db.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
         return !!row;
     }
+    /** The one run id starting with `prefix` (#919); `UsageError` on several, `NotFoundError` on none. */
+    resolveRunIdPrefix(prefix) {
+        const escaped = escapeLikePattern(prefix);
+        const rows = this.db
+            .prepare("SELECT id FROM workflow_runs WHERE id LIKE ? ESCAPE '\\' ORDER BY id ASC")
+            .all(`${escaped}%`);
+        if (rows.length === 1)
+            return rows[0].id;
+        if (rows.length > 1) {
+            throw new UsageError(`Ambiguous workflow run id prefix "${prefix}" — matches: ${rows.map((r) => r.id).join(", ")}`, "INVALID_FLAG_VALUE");
+        }
+        throw new NotFoundError(`Workflow run "${prefix}" not found.`, "WORKFLOW_NOT_FOUND");
+    }
     listRuns(filter) {
         const filters = [];
         const params = [];
@@ -351,25 +411,57 @@ export class WorkflowRunsRepository {
      * A live lease held by anyone (including a stale copy of the same holder)
      * is NOT reclaimable through this method; the single UPDATE is the whole
      * claim, so two racing invocations cannot both win.
+     *
+     * The UPDATE can throw instead of cleanly returning `changes: 0` under real
+     * cross-process contention on this row: a `SQLITE_BUSY`/`SQLITE_LOCKED`
+     * from two engines racing the same statement, occasionally surfacing as
+     * "database is locked" or even "database disk image is malformed" text that
+     * reads as corruption but is not. `runLeaseStatementWithRetry` absorbs a
+     * blip that a fresh attempt clears on its own. If it is still failing after
+     * every retry, the row is read fresh (a plain SELECT, far less likely to
+     * trip whatever the write hit) to get independent evidence of what is
+     * actually going on: a live lease there means this really was contention,
+     * so the caller gets the same lease-held message `akm workflow run` already
+     * shows for the clean (non-throwing) case, now with `RUN_LEASE_HELD`. No
+     * live lease — or the verifying read itself fails — means the error was
+     * never actually about the lease, so it is rethrown exactly as raised.
+     * Nothing here invents a diagnosis from error text alone or suppresses a
+     * genuine SQLite failure.
      */
     acquireEngineLease(runId, holder, until, now) {
-        const result = this.db
-            .prepare(`UPDATE workflow_runs
-           SET engine_lease_holder = ?, engine_lease_until = ?
-           WHERE id = ? AND status = 'active'
-             AND (engine_lease_holder IS NULL OR engine_lease_until IS NULL OR engine_lease_until < ?)`)
-            .run(holder, until, runId, now);
-        return Number(result.changes) > 0;
+        try {
+            const result = runLeaseStatementWithRetry(() => this.db
+                .prepare(`UPDATE workflow_runs
+               SET engine_lease_holder = ?, engine_lease_until = ?
+               WHERE id = ? AND status = 'active'
+                 AND (engine_lease_holder IS NULL OR engine_lease_until IS NULL OR engine_lease_until < ?)`)
+                .run(holder, until, runId, now));
+            return Number(result.changes) > 0;
+        }
+        catch (error) {
+            if (!isLeaseContentionSqliteError(error))
+                throw error;
+            const row = this.tryReadLeaseColumns(runId);
+            if (row?.engine_lease_holder && row.engine_lease_until && row.engine_lease_until >= now) {
+                throw new UsageError(`Workflow run ${runId} is already being driven by engine ${row.engine_lease_holder} ` +
+                    `(run lease expires ${row.engine_lease_until}). A second \`akm workflow run\` would race it — ` +
+                    `wait for that invocation to finish or for the lease to expire.`, "RUN_LEASE_HELD");
+            }
+            throw error;
+        }
     }
     /**
      * Extend the lease expiry — only while `holder` still owns it. Returns
      * false when the lease was lost (expired and claimed by another engine),
-     * so the caller can stop driving instead of racing the new owner.
+     * so the caller can stop driving instead of racing the new owner. Wrapped
+     * in the same transient-error retry as {@link acquireEngineLease}; a
+     * renewal that still fails after retries is rethrown as-is (no confirmed
+     * "lost lease" diagnosis to substitute, unlike the acquire case above).
      */
     renewEngineLease(runId, holder, until) {
-        const result = this.db
+        const result = runLeaseStatementWithRetry(() => this.db
             .prepare("UPDATE workflow_runs SET engine_lease_until = ? WHERE id = ? AND engine_lease_holder = ? AND status = 'active'")
-            .run(until, runId, holder);
+            .run(until, runId, holder));
         return Number(result.changes) > 0;
     }
     /**
@@ -382,6 +474,36 @@ export class WorkflowRunsRepository {
             .prepare("UPDATE workflow_runs SET engine_lease_holder = NULL, engine_lease_until = NULL WHERE id = ? AND engine_lease_holder = ? AND status <> 'failed'")
             .run(runId, holder);
     }
+    /**
+     * Self-heal an engine lease its holder crashed without releasing: once
+     * `engine_lease_until` has passed, clear it so a read (`workflow status`,
+     * `workflow list`) stops reporting a run as engine-driven when the engine is
+     * long gone — mirroring the maintenance barrier's self-reclaim of a wedged
+     * sentinel (`tryAcquireMaintenanceBarrier`) rather than a bespoke mechanism.
+     * The WHERE clause repeats the exact (holder, until) snapshot the caller
+     * read, so a lease renewed or re-acquired in between never gets clobbered —
+     * same compare-and-swap shape as the claim above. Never touches a lease
+     * that is still live.
+     */
+    reclaimExpiredEngineLease(runId, holder, until, now) {
+        if (until >= now)
+            return false;
+        const result = this.db
+            .prepare(`UPDATE workflow_runs
+           SET engine_lease_holder = NULL, engine_lease_until = NULL
+           WHERE id = ? AND engine_lease_holder = ? AND engine_lease_until = ? AND engine_lease_until < ?`)
+            .run(runId, holder, until, now);
+        return Number(result.changes) > 0;
+    }
+    /** Best-effort lease-column read used only to confirm genuine contention after {@link acquireEngineLease} exhausts its retries. `undefined` on any failure — never a diagnosis, just "couldn't confirm". */
+    tryReadLeaseColumns(runId) {
+        try {
+            return (this.db.prepare("SELECT engine_lease_holder, engine_lease_until FROM workflow_runs WHERE id = ?").get(runId) ?? undefined);
+        }
+        catch {
+            return undefined;
+        }
+    }
     // ── durable v4 append-only dispatch attempts (migration 022) ─────────────
     getUnitAttempts(runId, unitId) {
         return this.db

package/dist/storage/sqlite-read-snapshot.js

@@ -13,7 +13,10 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { sleepSync } from "../runtime.js";
 import { openDatabaseFinalizing } from "./database.js";
+const SNAPSHOT_MAX_ATTEMPTS = 8;
+const SNAPSHOT_BACKOFF_MS = 25;
 export class SqliteReadSnapshotUnavailableError extends Error {
     constructor(message) {
         super(message);
@@ -67,19 +70,17 @@ function fingerprintsEqual(left, right) {
 export function openSqliteReadSnapshot(dbPath) {
     if (!pathExists(dbPath))
         return undefined;
-    if (pathExists(`${dbPath}-journal`)) {
-        throw new SqliteReadSnapshotUnavailableError("an active SQLite rollback journal is present; a non-mutating point-in-time snapshot is unavailable");
-    }
     const snapshotDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-sqlite-read-"));
     const snapshotPath = path.join(snapshotDir, "snapshot.db");
     let db;
     try {
         let copied = false;
-        for (let attempt = 0; attempt < 3; attempt++) {
+        for (let attempt = 0; attempt < SNAPSHOT_MAX_ATTEMPTS; attempt++) {
+            if (attempt > 0)
+                sleepSync(SNAPSHOT_BACKOFF_MS * attempt);
             try {
-                if (pathExists(`${dbPath}-journal`)) {
-                    throw new SqliteReadSnapshotUnavailableError("an active SQLite rollback journal appeared while taking the non-mutating snapshot");
-                }
+                if (pathExists(`${dbPath}-journal`))
+                    continue;
                 const before = databaseFingerprint(dbPath);
                 fs.copyFileSync(dbPath, snapshotPath);
                 if (before.wal)
@@ -87,7 +88,7 @@ export function openSqliteReadSnapshot(dbPath) {
                 else
                     fs.rmSync(`${snapshotPath}-wal`, { force: true });
                 const after = databaseFingerprint(dbPath);
-                if (fingerprintsEqual(before, after)) {
+                if (fingerprintsEqual(before, after) && !pathExists(`${dbPath}-journal`)) {
                     copied = true;
                     break;
                 }
@@ -99,7 +100,8 @@ export function openSqliteReadSnapshot(dbPath) {
             }
         }
         if (!copied) {
-            throw new SqliteReadSnapshotUnavailableError("SQLite main/WAL files kept changing while taking the non-mutating snapshot");
+            throw new SqliteReadSnapshotUnavailableError(`SQLite main/WAL files did not settle after ${SNAPSHOT_MAX_ATTEMPTS} attempts with backoff — ` +
+                "a writer may be continuously active, or a hot rollback journal never cleared");
         }
         db = openDatabaseFinalizing(snapshotPath, { readonly: true, create: false });
         const closeSnapshot = db.close.bind(db);

package/dist/tasks/backends/cron.js

@@ -29,6 +29,7 @@
 //
 // Tests inject a fake exec so unit tests don't touch the real crontab.
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
@@ -60,9 +61,16 @@ export function CRON_BACKEND(options = {}) {
             // Create the log directory before writing the crontab line — cron
             // appends with `>>` and the surrounding shell will fail the entire
             // entry if the parent directory doesn't exist.
-            const cronLine = buildCronLine(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            const cronLineParts = buildCronLineParts(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            const cronLine = cronLineParts.line;
             assertPortableCronLine(cronLine);
             fsLike.ensureDir(logDir);
+            if (cronLineParts.wrapper) {
+                if (!fsLike.writeFile) {
+                    throw new ConfigError("Cron backend needs to write a wrapper script for this task's long invocation, but the configured filesystem cannot write files.", "INVALID_CONFIG_FILE");
+                }
+                fsLike.writeFile(cronLineParts.wrapper.path, cronLineParts.wrapper.content);
+            }
             const existing = readCrontab(exec);
             const nativeId = schedulerBindingNativeId(task);
             const blocks = listBlocks(existing);
@@ -245,14 +253,35 @@ function isCronBindingSnapshot(value) {
         value.kind === CRON_SNAPSHOT &&
         typeof value.crontab === "string");
 }
-// ── helpers (exported for tests) ────────────────────────────────────────────
-export function buildCronLine(task, akmArgv, logDir, contextPath, _target) {
+function buildCronLineParts(task, akmArgv, logDir, contextPath, _target) {
     const spec = parseSchedule(task.cron, "cron");
     const cronExpr = translateToCron(spec);
-    const logPath = path.join(logDir, `${schedulerBindingNativeId(task)}.log`);
+    const nativeId = schedulerBindingNativeId(task);
+    const logPath = path.join(logDir, `${nativeId}.log`);
     const invocation = buildScheduledBindingInvocation(akmArgv, contextPath, task.invocation);
     const cmd = invocation.argv.map((part) => quoteForCron(part)).join(" ");
-    return `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
+    const directLine = `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
+    if (Buffer.byteLength(directLine, "utf8") <= PORTABLE_CRON_LINE_LIMIT) {
+        return { line: directLine };
+    }
+    const content = cronWrapperScriptContent(invocation.argv);
+    const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+    const wrapperPath = path.join(logDir, `${CRON_WRAPPER_PREFIX}${nativeId}-${contentHash}.sh`);
+    const line = `${cronExpr} sh ${quoteForCron(wrapperPath)} >> ${quoteForCron(logPath)} 2>&1`;
+    return { line, wrapper: { path: wrapperPath, content } };
+}
+const CRON_WRAPPER_PREFIX = ".akm-cron-wrapper-";
+function quoteForShellScript(part) {
+    if (/^[A-Za-z0-9_\-./@:=+,]+$/.test(part))
+        return part;
+    return `'${part.replace(/'/g, `'\\''`)}'`;
+}
+function cronWrapperScriptContent(argv) {
+    const cmd = argv.map(quoteForShellScript).join(" ");
+    return `#!/bin/sh\nexec ${cmd}\n`;
+}
+export function buildCronLine(task, akmArgv, logDir, contextPath, _target) {
+    return buildCronLineParts(task, akmArgv, logDir, contextPath, _target).line;
 }
 /** The crontab line as it appears inside a block — commented when disabled. */
 export function cronBlockBody(cronLine, enabled, executionEvidenceDigest) {