akm-cli 0.9.16 → 0.9.17-alpha.10

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

@@ -2,69 +2,16 @@
 // 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 { NotFoundError, TransientError, UsageError } from "../../core/errors.js";
-import { isSqliteContentionError, openStateDatabase, withImmediateTransaction } from "../../core/state-db.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 { WORKFLOW_PLAN_VERSION } from "../../workflows/plan.js";
 import { escapeLikePattern } from "../like-pattern.js";
 import { resolveStorageLocations } from "../locations.js";
 import { insertEventOnce, insertEventStrict } from "./events-repository.js";
-function assertAttemptReservationLease(input, run) {
-    if (input.leaseMode === "direct") {
-        if (run.engine_lease_holder === null)
-            return;
-        throw new UsageError(`Workflow run ${input.runId} is leased by another engine; direct durable dispatch reservation is forbidden.`, "RESOURCE_ALREADY_EXISTS");
-    }
-    if (run.engine_lease_holder !== input.claimHolder) {
-        throw new UsageError(`Workflow run ${input.runId} lease holder changed; refusing a stale durable dispatch reservation.`, "RESOURCE_ALREADY_EXISTS");
-    }
-    if (run.engine_lease_until === null || run.engine_lease_until < input.now) {
-        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:
- * the shared {@link isSqliteContentionError} classifier (SQLITE_BUSY/LOCKED,
- * "database is locked", "database table is locked", the phantom-BEGIN
- * marker) plus two corruption-shaped message texts a transient contention
- * blip has been observed producing on this specific race, "disk I/O error"
- * and "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) {
-    if (isSqliteContentionError(error))
-        return true;
-    const message = error instanceof Error ? error.message : String(error);
-    return 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;
+/** Informational `claim_holder` value stamped on attempt rows: the dispatching process. */
+function dispatchingProcess() {
+    return `pid:${process.pid}`;
 }
 /**
  * Repository owning every raw SQL statement against `workflow_runs` and
@@ -245,7 +192,7 @@ export class WorkflowRunsRepository {
     // ── writes ─────────────────────────────────────────────────────────────────
     insertRun(input) {
         // R-R3 (P3a Review log; docs/plans/specs/p4-deletions-closeout.md §8):
-        // this 13-column list is hand-duplicated by publishChildWorkflowRun's own
+        // this 12-column list is hand-duplicated by publishChildWorkflowRun's own
         // INSERT below, which extends it with parent_run_id/parent_unit_id/
         // invocation_key. A signature refactor to share one INSERT builder was
         // considered and deliberately deferred — see
@@ -254,9 +201,9 @@ export class WorkflowRunsRepository {
         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);
+          agent_harness, agent_session_id
+        ) 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);
     }
     insertSteps(steps) {
         const insertStep = this.db.prepare(`INSERT INTO workflow_run_steps (
@@ -274,9 +221,7 @@ export class WorkflowRunsRepository {
             .run(runId, currentStepId);
     }
     markRunActive(runId, updatedAt) {
-        this.db
-            .prepare("UPDATE workflow_runs SET status = 'active', updated_at = ?, engine_lease_holder = NULL, engine_lease_until = NULL WHERE id = ?")
-            .run(updatedAt, runId);
+        this.db.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(updatedAt, runId);
     }
     updateStepCompletion(input) {
         this.db
@@ -288,29 +233,25 @@ export class WorkflowRunsRepository {
     updateRunState(input) {
         this.db
             .prepare(`UPDATE workflow_runs
-           SET status = ?, current_step_id = ?, updated_at = ?, completed_at = ?, checkin_armed_at = ?
+           SET status = ?, current_step_id = ?, updated_at = ?, completed_at = ?
            WHERE id = ?`)
-            .run(input.status, input.currentStepId, input.updatedAt, input.completedAt, input.checkinArmedAt, input.runId);
+            .run(input.status, input.currentStepId, input.updatedAt, input.completedAt, input.runId);
     }
     markRunAbandoned(runId, updatedAt) {
         const result = this.db
             .prepare(`UPDATE workflow_runs
-           SET status = 'failed', updated_at = ?, completed_at = ?, checkin_armed_at = ?
+           SET status = 'failed', updated_at = ?, completed_at = ?
            WHERE id = ? AND status IN ('active', 'blocked')`)
-            .run(updatedAt, updatedAt, updatedAt, runId);
+            .run(updatedAt, updatedAt, runId);
         return Number(result.changes) === 1;
     }
-    rearmCheckin(runId, checkinArmedAt) {
-        this.db.prepare("UPDATE workflow_runs SET checkin_armed_at = ? WHERE id = ?").run(checkinArmedAt, runId);
-    }
     /**
-     * Atomically publish the entire durable-v4 run spine after the final source
-     * CAS. No run row, partial spine, plan attachment, or started event can
-     * escape independently across a crash or statement failure.
+     * Atomically publish the entire run spine. No run row, partial spine, plan
+     * attachment, or started event can escape independently across a crash or
+     * statement failure.
      */
     publishWorkflowRunV4(input) {
         this.immediateTransaction((db) => {
-            input.revalidateSources();
             if (!input.force) {
                 // The uniqueness guard must never silently skip its scope predicate
                 // (#942) — every real caller (`startWorkflowRun`) stamps a concrete
@@ -329,7 +270,7 @@ export class WorkflowRunsRepository {
             }
             this.insertRun(input.run);
             this.insertSteps(input.steps);
-            db.prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ?, plan_ir_version = 5 WHERE id = ?").run(input.planJson, input.planHash, input.run.id);
+            db.prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ?, plan_ir_version = ? WHERE id = ?").run(input.planJson, input.planHash, WORKFLOW_PLAN_VERSION, input.run.id);
             insertEventOnce(db, {
                 eventType: "workflow_started",
                 ts: input.run.createdAt,
@@ -350,15 +291,12 @@ export class WorkflowRunsRepository {
      * `(parent_run_id, invocation_key)` and return the existing child if
      * present; otherwise INSERT the child run row (parentage columns +
      * `invocation_key`), its step rows, attach the embedded frozen child plan
-     * (`plan_ir_version = 5`), and append its `workflow_started` event — then
-     * return the freshly-inserted row.
+     * (`plan_ir_version` = the current plan version), and append its
+     * `workflow_started` event — then return the freshly-inserted row.
      *
-     * Deliberately does NOT: call {@link findActiveRunForScope} or raise
+     * Deliberately does NOT call {@link findActiveRunForScope} or raise
      * `RESOURCE_ALREADY_EXISTS` (top-level scope-conflict rules do not apply to
-     * a child, C-10); call `revalidateSources` or read the filesystem in any
-     * way (the child plan was frozen and CAS'd into the PARENT's read set at
-     * parent freeze, C-11); or touch {@link publishWorkflowRunV4} /
-     * `startWorkflowRun` (untouched, C-12).
+     * a child), and reads no source: the child plan was frozen into the parent's.
      *
      * This method's serialization guarantee holds only when it is the
      * OUTERMOST transaction on the connection (spec Review log R10,
@@ -394,16 +332,16 @@ export class WorkflowRunsRepository {
             if (existing)
                 return existing;
             // R-R3 (P3a Review log; docs/plans/specs/p4-deletions-closeout.md §8):
-            // the first 13 columns here must stay byte-identical to insertRun's own
+            // the first 12 columns here must stay byte-identical to insertRun's own
             // column list above (hand-duplicated, not shared, by deliberate choice
             // — see docs/architecture/decisions/0009-child-run-publication-column-parity.md).
             // Keep both column lists in sync by hand.
             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, parent_run_id, parent_unit_id, invocation_key
-        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.run.id, input.run.workflowRef, input.run.scopeKey, input.run.workflowEntryId, input.run.workflowTitle, input.run.paramsJson, input.run.currentStepId, input.run.createdAt, input.run.updatedAt, input.run.agentHarness, input.run.agentSessionId, input.run.checkinArmedAt, input.parentRunId, input.spawnedByUnitId, input.invocationKey);
+          agent_harness, agent_session_id, parent_run_id, parent_unit_id, invocation_key
+        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.run.id, input.run.workflowRef, input.run.scopeKey, input.run.workflowEntryId, input.run.workflowTitle, input.run.paramsJson, input.run.currentStepId, input.run.createdAt, input.run.updatedAt, input.run.agentHarness, input.run.agentSessionId, input.parentRunId, input.spawnedByUnitId, input.invocationKey);
             this.insertSteps(input.steps);
-            db.prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ?, plan_ir_version = 5 WHERE id = ?").run(input.planJson, input.planHash, input.run.id);
+            db.prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ?, plan_ir_version = ? WHERE id = ?").run(input.planJson, input.planHash, WORKFLOW_PLAN_VERSION, input.run.id);
             insertEventOnce(db, {
                 eventType: "workflow_started",
                 ts: input.run.createdAt,
@@ -436,111 +374,6 @@ export class WorkflowRunsRepository {
             .prepare("SELECT * FROM workflow_runs WHERE parent_run_id = ? AND invocation_key = ?")
             .get(parentRunId, key) ?? undefined);
     }
-    // ── engine run lease (migration 006 columns, R2 enforcement) ──────────────
-    //
-    // Single-driver invariant: at most one `akm workflow run` invocation drives
-    // a run at a time. The lease is (holder id, expiry); all timestamps are
-    // ISO-8601 UTC strings, which compare correctly with SQL `<` (lexicographic
-    // order matches chronological order for a fixed-format UTC ISO string).
-    /**
-     * Atomically claim the run lease: succeeds when the run is unleased OR the
-     * existing lease has expired (`engine_lease_until < now` — crash recovery).
-     * 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) {
-        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 TransientError(`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. 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 = runLeaseStatementWithRetry(() => this.db
-            .prepare("UPDATE workflow_runs SET engine_lease_until = ? WHERE id = ? AND engine_lease_holder = ? AND status = 'active'")
-            .run(until, runId, holder));
-        return Number(result.changes) > 0;
-    }
-    /**
-     * Clear the lease only while `holder` still owns a non-failed run. Failed
-     * runs retain the final holder/expiry for forensics until explicit resume.
-     * Releasing an already-lost lease is a harmless no-op.
-     */
-    releaseEngineLease(runId, holder) {
-        this.db
-            .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
@@ -571,61 +404,37 @@ export class WorkflowRunsRepository {
         };
     }
     /**
-     * Reserve or reclaim one v4 external dispatch. The attempt row, legacy
-     * projection, and directly-paired started event share one IMMEDIATE
-     * transaction. Reclaim keeps the stable dispatch id and emits no duplicate
-     * start event: the external effect remains explicitly at-least-once.
+     * Reserve or reclaim one dispatch attempt. The attempt row, the unit
+     * projection, and the directly-paired started event share one IMMEDIATE
+     * transaction. A latest attempt still `running` is reclaimed in place —
+     * same attempt number, same stable dispatch id, no duplicate start event —
+     * so a re-dispatch after a crash stays explicitly at-least-once with an
+     * idempotency key a downstream can dedupe on. One process drives a run at a
+     * time (the per-run lock file in `workflows/exec/run-workflow.ts`), so a
+     * `running` attempt found here is never another live driver's.
      */
     reserveUnitAttempt(input) {
+        const holder = dispatchingProcess();
         return this.immediateTransaction((db) => {
-            const run = db
-                .prepare("SELECT workflow_ref, status, engine_lease_holder, engine_lease_until FROM workflow_runs WHERE id = ?")
-                .get(input.runId);
+            const run = db.prepare("SELECT workflow_ref, status FROM workflow_runs WHERE id = ?").get(input.runId);
             if (!run || run.status !== "active") {
                 throw new UsageError(`Workflow run ${input.runId} is not active; refusing to reserve a durable dispatch attempt.`, "RESOURCE_ALREADY_EXISTS");
             }
-            assertAttemptReservationLease(input, run);
             const latest = db
                 .prepare(`SELECT * FROM workflow_run_unit_attempts
             WHERE run_id = ? AND unit_id = ?
             ORDER BY attempt DESC
             LIMIT 1`)
                 .get(input.runId, input.unitId);
-            if (latest?.status === "running") {
-                if (latest.claim_holder === input.claimHolder) {
-                    return { kind: "existing", attempt: latest };
-                }
-                const currentRunLeaseDisplacedClaim = run.engine_lease_holder === input.claimHolder;
-                const expired = latest.claim_expires_at < input.now;
-                if (!expired && !currentRunLeaseDisplacedClaim) {
-                    return { kind: "busy", attempt: latest };
-                }
-                const reclaimed = db
-                    .prepare(`UPDATE workflow_run_unit_attempts
-                SET claim_holder = ?, claim_expires_at = ?
-              WHERE run_id = ? AND unit_id = ? AND attempt = ?
-                AND status = 'running' AND dispatch_id = ? AND claim_holder = ?
-                AND claim_expires_at = ?`)
-                    .run(input.claimHolder, input.claimExpiresAt, input.runId, input.unitId, latest.attempt, latest.dispatch_id, latest.claim_holder, latest.claim_expires_at);
-                if (Number(reclaimed.changes) !== 1) {
-                    throw new Error(`Durable attempt ${input.unitId} changed while its displaced claim was reclaimed.`);
-                }
-                db.prepare(`UPDATE workflow_run_units
-              SET claim_holder = ?, claim_expires_at = ?, last_checkin_at = ?
-            WHERE run_id = ? AND unit_id = ? AND status = 'running'`).run(input.claimHolder, input.claimExpiresAt, input.now, input.runId, input.unitId);
-                const attempt = db
-                    .prepare(`SELECT * FROM workflow_run_unit_attempts
-              WHERE run_id = ? AND unit_id = ? AND attempt = ?`)
-                    .get(input.runId, input.unitId, latest.attempt);
-                return { kind: "reclaimed", attempt };
-            }
+            if (latest?.status === "running")
+                return { kind: "reclaimed", attempt: latest };
             const attemptNumber = (latest?.attempt ?? 0) + 1;
             const dispatchId = randomUUID();
             db.prepare(`INSERT INTO workflow_run_unit_attempts (
            run_id, unit_id, attempt, dispatch_id, step_id, node_id, phase,
            runner, engine, model, input_hash, status, worktree_path, started_at,
            claim_holder, claim_expires_at
-         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', ?, ?, ?, ?)`).run(input.runId, input.unitId, attemptNumber, dispatchId, input.stepId, input.nodeId, input.phase, input.runner, input.engine, input.model, input.inputHash, input.worktreePath ?? null, input.now, input.claimHolder, input.claimExpiresAt);
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', ?, ?, ?, ?)`).run(input.runId, input.unitId, attemptNumber, dispatchId, input.stepId, input.nodeId, input.phase, input.runner, input.engine, input.model, input.inputHash, input.worktreePath ?? null, input.now, holder, input.now);
             db.prepare(`INSERT INTO workflow_run_units (
            run_id, unit_id, step_id, node_id, parent_unit_id, phase, runner, engine, model,
            status, input_hash, worktree_path, started_at, claim_holder, claim_expires_at, attempts
@@ -649,8 +458,7 @@ export class WorkflowRunsRepository {
            failure_reason = NULL,
            session_id = NULL,
            finished_at = NULL,
-           last_checkin_at = NULL,
-           attempts = excluded.attempts`).run(input.runId, input.unitId, input.stepId, input.nodeId, input.parentUnitId ?? null, input.phase, input.runner, input.engine, input.model, input.inputHash, input.worktreePath ?? null, input.now, input.claimHolder, input.claimExpiresAt, attemptNumber);
+           attempts = excluded.attempts`).run(input.runId, input.unitId, input.stepId, input.nodeId, input.parentUnitId ?? null, input.phase, input.runner, input.engine, input.model, input.inputHash, input.worktreePath ?? null, input.now, holder, input.now, attemptNumber);
             insertEventStrict(db, {
                 eventType: "workflow_unit_started",
                 ts: input.now,
@@ -672,16 +480,19 @@ export class WorkflowRunsRepository {
             return { kind: "reserved", attempt };
         });
     }
-    /** Commit one CAS-valid v4 terminal result, known usage, and finish event. */
+    /**
+     * Commit one terminal result, known usage, and finish event. Returns false
+     * when the attempt is no longer `running` (already finished) — a duplicate
+     * terminal callback never adds usage or a second event.
+     */
     finishUnitAttempt(input) {
         return this.immediateTransaction((db) => {
             const changed = db
                 .prepare(`UPDATE workflow_run_unit_attempts
               SET status = ?, result_json = ?, tokens = ?, failure_reason = ?,
                   session_id = ?, finished_at = ?
-            WHERE run_id = ? AND unit_id = ? AND attempt = ? AND dispatch_id = ?
-              AND claim_holder = ? AND status = 'running'`)
-                .run(input.status, input.resultJson, input.tokens, input.failureReason, input.sessionId ?? null, input.finishedAt, input.runId, input.unitId, input.attempt, input.dispatchId, input.claimHolder);
+            WHERE run_id = ? AND unit_id = ? AND attempt = ? AND dispatch_id = ? AND status = 'running'`)
+                .run(input.status, input.resultJson, input.tokens, input.failureReason, input.sessionId ?? null, input.finishedAt, input.runId, input.unitId, input.attempt, input.dispatchId);
             if (Number(changed.changes) !== 1)
                 return false;
             const attempt = db
@@ -692,9 +503,8 @@ export class WorkflowRunsRepository {
                 .prepare(`UPDATE workflow_run_units
               SET status = ?, result_json = ?, tokens = ?, failure_reason = ?,
                   session_id = ?, finished_at = ?
-            WHERE run_id = ? AND unit_id = ? AND status = 'running'
-              AND attempts = ? AND claim_holder = ?`)
-                .run(input.status, input.resultJson, input.tokens, input.failureReason, input.sessionId ?? null, input.finishedAt, input.runId, input.unitId, input.attempt, input.claimHolder);
+            WHERE run_id = ? AND unit_id = ? AND status = 'running' AND attempts = ?`)
+                .run(input.status, input.resultJson, input.tokens, input.failureReason, input.sessionId ?? null, input.finishedAt, input.runId, input.unitId, input.attempt);
             if (Number(projection.changes) !== 1) {
                 throw new Error(`Durable attempt ${input.unitId} has no matching live workflow_run_units projection.`);
             }
@@ -754,9 +564,8 @@ export class WorkflowRunsRepository {
  *   - Inside a {@link withWorkflowRunsConnection} scope, the ambient handle is
  *     BORROWED and left open for the rest of the scope. A wide `map` fan-out
  *     therefore opens ONE connection for the whole step instead of two per unit
- *     (insert + finish) — `openStateDatabase` registers a maintenance activity
- *     lockfile and opens a read-only ledger-preflight handle on every call, so
- *     the per-call cost is milliseconds, not microseconds.
+ *     (insert + finish) — `openStateDatabase` opens a read-only ledger-preflight
+ *     handle on every call, so the per-call cost is milliseconds, not microseconds.
  *   - Outside a scope the behaviour is unchanged: open a fresh connection, run
  *     `fn`, close it in a `finally`.
  *
@@ -789,7 +598,7 @@ export async function withWorkflowRunsRepo(fn) {
  * logically concurrent units cannot interleave statements on the shared handle
  * in a single-threaded event loop — sharing REMOVES in-process writer
  * contention instead of creating it. Cross-process arbitration (WAL,
- * `busy_timeout`, the run lease) is untouched. See `core/state-db-scope.ts` for
+ * `busy_timeout`, the per-run lock file) is untouched. See `core/state-db-scope.ts` for
  * the escaped-async-work guard.
  */
 export function withWorkflowRunsConnection(fn) {

package/dist/storage/sqlite-migrations.js

@@ -0,0 +1,136 @@
+// 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 { withImmediateTransaction } from "./sqlite-transaction.js";
+/**
+ * Reject a `MIGRATIONS` array containing a duplicate `id`.
+ *
+ * A compiled-in registry can't diverge at runtime, so this is a dev-time
+ * invariant, not a per-open guard: each consumer (state.db, logs.db) calls it
+ * once on its own array at module load, and `tests/storage/sqlite-migrations.test.ts`
+ * pins the duplicate-detection behavior directly. {@link inspectMigrationLedger}
+ * does NOT call this — re-scanning the same compiled-in array on every DB open
+ * added no safety over the module-load check, only repeated O(n) cost.
+ */
+export function assertMigrationRegistry(migrations) {
+    const seen = new Set();
+    for (const migration of migrations) {
+        if (seen.has(migration.id))
+            throw new Error(`Migration registry contains duplicate ID ${migration.id}.`);
+        seen.add(migration.id);
+    }
+}
+export function migrationLedgerExists(db) {
+    return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'").get();
+}
+/** Inspect the database's applied IDs against the exact ordered registry prefix. */
+function inspectLedgerAgainst(db, registryIds) {
+    if (!migrationLedgerExists(db))
+        return { status: registryIds.length === 0 ? "current" : "old", migrationIds: [] };
+    const rows = db.prepare("SELECT id FROM schema_migrations ORDER BY rowid").all();
+    const migrationIds = rows.map((row) => row.id);
+    for (const [index, row] of rows.entries()) {
+        const expectedId = registryIds[index];
+        // Every id this binary knows matched in order and the ledger carries more:
+        // the database was migrated by a newer akm. Nothing here is applicable —
+        // this binary's whole registry is already applied — so this is version
+        // skew, not divergence.
+        if (!expectedId) {
+            return {
+                status: "newer",
+                migrationIds,
+                detail: `applied migration ID${rows.length - registryIds.length === 1 ? "" : "s"} ${migrationIds
+                    .slice(registryIds.length)
+                    .join(", ")} unknown to this akm`,
+            };
+        }
+        // A mismatch at a position this binary has a migration for is divergence,
+        // whether or not the id is one this binary knows later: this binary's
+        // migration at `index` was never applied, and something else was.
+        if (row.id !== expectedId) {
+            return {
+                status: "inconsistent",
+                migrationIds,
+                detail: `migration ledger is not an exact ordered prefix at position ${index + 1} (found '${row.id}', expected '${expectedId}'). ` +
+                    `Applied, in order: [${migrationIds.join(", ")}]. This akm's expected order: [${registryIds.join(", ")}].`,
+            };
+        }
+    }
+    return {
+        status: rows.length === registryIds.length ? "current" : "old",
+        migrationIds,
+    };
+}
+export function inspectMigrationLedger(db, migrations) {
+    return inspectLedgerAgainst(db, migrations.map((migration) => migration.id));
+}
+/**
+ * Reject only a ledger this binary cannot reason about at all.
+ *
+ * A `newer` ledger — an exact ordered prefix of this binary's registry plus
+ * migrations a later akm added — is NOT rejected. Two akm versions sharing one
+ * data directory is a supported deployment (a bundled CLI alongside a newer
+ * global install), and refusing the open bricked the older one for every
+ * command while protecting nothing: its entire registry is already applied, so
+ * it has no pending migration to run. Callers that want to tell an operator
+ * about the skew read {@link MigrationLedgerState.status}.
+ *
+ * An `inconsistent` ledger is different: this binary has a migration that was
+ * never applied and something else was applied in its place, so running the
+ * pending set could conflict with schema it cannot see. That still refuses.
+ */
+export function assertMigrationLedger(db, migrations) {
+    const state = inspectMigrationLedger(db, migrations);
+    if (state.status === "inconsistent") {
+        throw new Error(`Refusing a database whose migrations are not an exact ordered prefix: ${state.detail} ` +
+            "Applying this binary's missing migration now could run it against a schema a later migration already " +
+            "changed underneath it, which is a real risk of producing a wrong schema — not something akm can guess " +
+            "its way out of safely. This usually means the database was migrated by an incompatible akm build or " +
+            "fork, or schema_migrations was edited by hand. Restore this file from a backup taken before the " +
+            "divergence, or — if there is no backup and the data is not needed — delete it and let akm rebuild it " +
+            "from scratch (a derived index.db regenerates from your sources on the next 'akm index'; state.db loses " +
+            "durable history such as improve/proposal state and must be treated as a last resort).");
+    }
+    return state;
+}
+/** Create the migrations ledger table if it does not exist. */
+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'))
+    );
+  `);
+}
+/** The registry entries not yet recorded in the ledger, in order. Throws on a divergent ledger. */
+export function pendingMigrations(db, migrations) {
+    return migrations.slice(assertMigrationLedger(db, migrations).migrationIds.length);
+}
+/**
+ * Apply every pending migration in one `BEGIN IMMEDIATE` transaction.
+ *
+ * A database with nothing pending is only read, never write-locked. Otherwise
+ * the write lock is taken up front — a second process bootstrapping the same
+ * database WAITS for the first to commit instead of racing it — and the
+ * pending set is re-read under that lock, so the process that lost the race
+ * finds nothing left to do rather than re-running DDL. Each migration's ledger
+ * row is inserted right after its SQL inside the same transaction: a failing
+ * migration rolls back every migration this call applied, and their ledger
+ * rows with them. Contention that outlasts every BEGIN retry surfaces as
+ * `TransientError("STATE_DB_CONTENDED")` (`../sqlite-transaction`). Returns the
+ * IDs this call applied, in order — empty when another process got there first.
+ */
+export function runMigrations(db, migrations) {
+    if (pendingMigrations(db, migrations).length === 0)
+        return [];
+    return withImmediateTransaction(db, () => {
+        ensureMigrationsTable(db);
+        const applied = [];
+        for (const migration of pendingMigrations(db, migrations)) {
+            db.exec(migration.up);
+            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
+            applied.push(migration.id);
+        }
+        return applied;
+    });
+}

package/dist/storage/sqlite-pragmas.js

@@ -95,17 +95,19 @@ export function isNetworkFilesystem(fsType) {
         return false;
     return NETWORK_FS_MAGICS.has(fsType);
 }
-/** Options for {@link applyStandardPragmas}. */
+/** How long a statement waits for a lock before failing with SQLITE_BUSY. */
+export const SQLITE_BUSY_TIMEOUT_MS = 30_000;
 /**
- * How long a statement waits for a lock before failing with SQLITE_BUSY.
- *
- * Exported so read-only openers can apply it too. They cannot run the rest of
- * the standard set (journal_mode and foreign_keys are write operations), but
- * the default of 0 makes reads fail INSTANTLY under writer contention — which
- * matters in the DELETE/TRUNCATE journal modes 0.9.1's network-filesystem
- * fallback and `AKM_SQLITE_JOURNAL_MODE` can select, where readers do block.
+ * The standard set for a READ-ONLY handle: just `busy_timeout`. A read-only
+ * connection cannot run the rest (journal_mode and foreign_keys are write
+ * operations), but SQLite's default timeout of 0 makes reads fail INSTANTLY
+ * under writer contention — which matters in the DELETE/TRUNCATE journal modes
+ * the network-filesystem fallback and `AKM_SQLITE_JOURNAL_MODE` can select,
+ * where readers do block.
  */
-export const SQLITE_BUSY_TIMEOUT_MS = 30_000;
+export function applyReadonlyPragmas(db) {
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+}
 /**
  * Apply AKM's standard opening PRAGMAs to `db`, in order:
  *   1. `journal_mode` = the configured mode (with WAL→DELETE network-FS fallback)