akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

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

@@ -0,0 +1,213 @@
+// 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/.
+/**
+ * Record an induction of a recombine hypothesis and return the new consecutive
+ * count. INSERT … ON CONFLICT increments the streak, but the `last_run` guard
+ * makes a repeated call within the SAME run idempotent (no double-increment if
+ * the same ref appears twice in one run). On insert the streak starts at 1.
+ */
+export function recordRecombineInduction(db, input) {
+    const row = db
+        .prepare(`
+      INSERT INTO recombine_hypotheses
+        (hypothesis_ref, signature, member_key, consecutive_count, first_seen_at, last_seen_at, last_run)
+      VALUES (?, ?, ?, 1, ?, ?, ?)
+      ON CONFLICT(hypothesis_ref) DO UPDATE SET
+        consecutive_count = consecutive_count + (CASE WHEN last_run IS excluded.last_run THEN 0 ELSE 1 END),
+        last_seen_at = excluded.last_seen_at,
+        last_run = excluded.last_run,
+        signature = excluded.signature,
+        member_key = excluded.member_key
+      RETURNING consecutive_count
+    `)
+        .get(input.hypothesisRef, input.signature, input.memberKey, input.seenAt, input.seenAt, input.run);
+    return row?.consecutive_count ?? 0;
+}
+/**
+ * #633 — find an existing pending (non-promoted) hypothesis row whose cluster
+ * is the SAME generalization as a newly-induced one, matched by SIGNATURE plus
+ * a Jaccard membership-overlap test, rather than an exact member-set hash.
+ *
+ * In a growing stash any added/removed memory changes the exact member set, so
+ * the ref hash (and member_key) shift every run → a fresh row at count=1 → the
+ * streak never reaches `confirmThreshold` and nothing ever promotes. Matching
+ * on overlap lets a drifting-but-stable cluster keep accumulating under one row.
+ *
+ * Returns the matched row with the HIGHEST overlap (ties broken by most-recent
+ * `last_seen_at`), or `undefined` when none clears `minOverlap`. Already-promoted
+ * rows are ignored so a confirmed lesson is not reopened by a later induction.
+ *
+ * @param memberKey  the candidate cluster's membership fingerprint
+ *                   (sorted member entryKeys joined by `|`).
+ * @param minOverlap Jaccard threshold in [0,1]; a candidate matches when
+ *                   |A∩B| / |A∪B| >= minOverlap.
+ */
+export function findMatchingRecombineHypothesis(db, input) {
+    const candidateMembers = new Set(input.memberKey.split("|").filter((m) => m.length > 0));
+    if (candidateMembers.size === 0)
+        return undefined;
+    const rows = db
+        .prepare("SELECT * FROM recombine_hypotheses WHERE signature = ? AND promoted_at IS NULL ORDER BY last_seen_at DESC")
+        .all(input.signature);
+    let best;
+    let bestOverlap = -1;
+    for (const row of rows) {
+        const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+        if (rowMembers.length === 0)
+            continue;
+        let intersection = 0;
+        for (const m of rowMembers) {
+            if (candidateMembers.has(m))
+                intersection += 1;
+        }
+        const union = candidateMembers.size + rowMembers.length - intersection;
+        const overlap = union === 0 ? 0 : intersection / union;
+        // rows are ordered last_seen_at DESC, so a strict `>` keeps the most-recent
+        // row on ties.
+        if (overlap >= input.minOverlap && overlap > bestOverlap) {
+            best = row;
+            bestOverlap = overlap;
+        }
+    }
+    return best;
+}
+/**
+ * Fetch a single recombine hypothesis row, or `undefined` when the ref has
+ * never been induced. Normalizes bun:sqlite null → undefined like
+ * {@link getExtractedSession}.
+ */
+export function getRecombineHypothesis(db, hypothesisRef) {
+    const row = db
+        .prepare("SELECT * FROM recombine_hypotheses WHERE hypothesis_ref = ?")
+        .get(hypothesisRef);
+    return row ?? undefined;
+}
+/**
+ * Mark a hypothesis promoted: stamp `promoted_at` and reset the consecutive
+ * count to 0, so it must re-accumulate a full confirmation streak before it can
+ * promote again. The `promoted_at` non-null state is the double-promotion guard.
+ */
+export function markRecombineHypothesisPromoted(db, hypothesisRef, promotedAt) {
+    db.prepare("UPDATE recombine_hypotheses SET promoted_at = ?, consecutive_count = 0 WHERE hypothesis_ref = ?").run(promotedAt, hypothesisRef);
+}
+/**
+ * #658 — does any current-run cluster match this hypothesis row under the SAME
+ * signature + Jaccard-overlap rule used for re-induction? A match means the
+ * cluster genuinely re-formed this run (it was merely cap-displaced out of the
+ * processed top-`maxClustersPerRun` slice), so its streak must NOT be reset.
+ */
+function hypothesisMatchesAnyPresentCluster(row, presentClusters, minOverlap) {
+    const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+    if (rowMembers.length === 0)
+        return false;
+    const rowSet = new Set(rowMembers);
+    for (const cluster of presentClusters) {
+        if (cluster.signature !== row.signature)
+            continue;
+        const clusterMembers = cluster.memberKey.split("|").filter((m) => m.length > 0);
+        if (clusterMembers.length === 0)
+            continue;
+        let intersection = 0;
+        for (const m of clusterMembers) {
+            if (rowSet.has(m))
+                intersection += 1;
+        }
+        const union = rowSet.size + clusterMembers.length - intersection;
+        const overlap = union === 0 ? 0 : intersection / union;
+        if (overlap >= minOverlap)
+            return true;
+    }
+    return false;
+}
+/**
+ * Decay-to-zero every NON-promoted hypothesis NOT re-induced in the current run.
+ *
+ * A generalization that stops being supported by the corpus has lost its
+ * confirmation streak, so we hard-reset `consecutive_count` to 0 (the
+ * alternative — `count - 1` floored at 0 — tolerates a single noisy run but
+ * blurs the "consecutive" semantics; hard-reset is the conservative choice).
+ *
+ * Only rows whose `hypothesis_ref` is NOT in `seenRefs` AND whose `last_run` is
+ * NOT the current run are decayed. Already-promoted rows are left alone.
+ *
+ * #658 — CAP-AWARE decay. The recombine pass only re-inducts (and thus marks
+ * `seen`) the top-`maxClustersPerRun` clusters, but a cluster genuinely
+ * re-forms every run even when it is displaced below that cap. Resetting such a
+ * row treats a SCHEDULING miss as a SUBSTANCE miss and traps the hypothesis
+ * below `confirmThreshold` forever. When `opts.presentClusters` is supplied, a
+ * row is SPARED from decay if it Jaccard-matches any present cluster (same
+ * signature, overlap >= `opts.minOverlap`) — i.e. its cluster re-formed this run
+ * but was cap-displaced. This does NOT advance the streak (only re-induction in
+ * the processed slice does that, via {@link recordRecombineInduction}), so the
+ * recurrence bar for promotion is unchanged; it only stops the cap from
+ * manufacturing artificial misses. Omitting `presentClusters` preserves the
+ * pre-#658 hard-reset-after-one-miss behaviour exactly.
+ *
+ * Returns the number of rows reset.
+ */
+export function decayUnseenRecombineHypotheses(db, currentRun, seenRefs, opts) {
+    // #658 — when cap-aware sparing is requested, fold the cap-displaced rows into
+    // the "seen" exclusion set: the underlying reset SQL already protects every
+    // ref it is given, so sparing == treating a spared row exactly like a seen
+    // row for this sweep (its count is left untouched, never advanced).
+    let effectiveSeen = seenRefs;
+    if (opts && opts.presentClusters.length > 0) {
+        const candidates = db
+            .prepare("SELECT hypothesis_ref, signature, member_key FROM recombine_hypotheses WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .all(currentRun);
+        const seenSet = new Set(seenRefs);
+        for (const row of candidates) {
+            if (seenSet.has(row.hypothesis_ref))
+                continue;
+            if (hypothesisMatchesAnyPresentCluster(row, opts.presentClusters, opts.minOverlap)) {
+                seenSet.add(row.hypothesis_ref);
+            }
+        }
+        effectiveSeen = [...seenSet];
+    }
+    return decayUnseenRecombineHypothesesInner(db, currentRun, effectiveSeen);
+}
+/**
+ * The raw reset sweep shared by the cap-aware wrapper above. Resets every
+ * non-promoted row from a prior run whose ref is NOT in `seenRefs`. Kept private
+ * so the param-ceiling chunking logic lives in one place.
+ */
+function decayUnseenRecombineHypothesesInner(db, currentRun, seenRefs) {
+    // Reset every eligible row, then exclude the seen refs in chunks to respect
+    // the ~999 SQLite param ceiling. With no seen refs we reset all non-promoted
+    // rows from prior runs in a single statement.
+    if (seenRefs.length === 0) {
+        const res = db
+            .prepare("UPDATE recombine_hypotheses SET consecutive_count = 0 WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .run(currentRun);
+        return Number(res.changes);
+    }
+    // A single NOT IN keeps the exclusion atomic (a chunked NOT IN would let a ref
+    // excluded by one chunk still be reset by another chunk's statement). The
+    // recombine pass caps RE-INDUCED clusters at `maxClustersPerRun` (a handful) —
+    // but with #658 cap-aware sparing the caller folds every cap-displaced
+    // (present-but-unprocessed) hypothesis into `effectiveSeen` too, so on a large
+    // stash `seenRefs` here can carry MANY spared refs, not just the handful that
+    // were processed. We cap defensively at ~900 (under SQLite's ~999 param
+    // ceiling): if `effectiveSeen` somehow exceeds it we fall back to resetting all
+    // eligible rows — which re-introduces the cap-displacement trap for THAT run
+    // (spared rows get decayed because the NOT IN protection is dropped). That is a
+    // rare, bounded degradation; a stash with >900 simultaneously-spared
+    // hypotheses is far beyond current scale.
+    if (seenRefs.length > 900) {
+        const res = db
+            .prepare("UPDATE recombine_hypotheses SET consecutive_count = 0 WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .run(currentRun);
+        return Number(res.changes);
+    }
+    const placeholders = seenRefs.map(() => "?").join(",");
+    const res = db
+        .prepare(`UPDATE recombine_hypotheses SET consecutive_count = 0
+       WHERE promoted_at IS NULL
+         AND (last_run IS NULL OR last_run != ?)
+         AND consecutive_count != 0
+         AND hypothesis_ref NOT IN (${placeholders})`)
+        .run(currentRun, ...seenRefs);
+    return Number(res.changes);
+}

package/dist/storage/repositories/registry-cache.js

@@ -0,0 +1,93 @@
+// 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 { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { closeDatabase, openIndexDatabase } from "../../indexer/db/db.js";
+import { getRegistryIndexCache, upsertRegistryIndexCache } from "./registry-index-cache-repository.js";
+/**
+ * RAII-style lifecycle helper for the registry cache DB. Opens the DB (treating
+ * a failed open exactly like the legacy fall-through: the bun-test isolation
+ * guard is re-thrown, any other failure yields `db = undefined`), runs `fn`,
+ * and guarantees the DB is closed in a `finally` after `fn` has fully settled
+ * (the await is required: the callbacks are async, and closing before they
+ * settle would tear the DB down mid-write).
+ */
+export async function withRegistryCacheDb(fn) {
+    let db;
+    try {
+        db = openIndexDatabase();
+    }
+    catch (err) {
+        // Never mask the bun-test isolation guard as "DB unavailable".
+        rethrowIfTestIsolationError(err);
+        db = undefined;
+    }
+    try {
+        return await fn(db);
+    }
+    finally {
+        if (db) {
+            try {
+                closeDatabase(db);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/**
+ * Shared registry index-cache fetch template. Opens the cache DB, returns a
+ * fresh cache hit when present, otherwise fetches live (writing the result back
+ * to the cache best-effort), and falls back to a stale cache row when the fetch
+ * fails. Behaviour-preserving extraction of the logic previously duplicated in
+ * `skills-sh.ts` (`fetchSkills`) and `static-index.ts` (`loadIndex`).
+ */
+export async function fetchCachedJson(opts) {
+    const { cacheKey, ttlMs, parseCache, fetchFresh } = opts;
+    return withRegistryCacheDb(async (db) => {
+        // ── Step 1: Try DB cache (index.db) ─────────────────────────────────────
+        let dbCacheResult;
+        try {
+            if (db) {
+                dbCacheResult = getRegistryIndexCache(db, cacheKey, ttlMs);
+            }
+        }
+        catch (err) {
+            // Never mask the bun-test isolation guard as "DB unavailable" — see
+            // rethrowIfTestIsolationError in src/core/errors.ts. Without this, a
+            // leaky test silently gets a cold cache instead of the loud
+            // TEST_ISOLATION_MISSING failure the guard intends.
+            rethrowIfTestIsolationError(err);
+            // index.db read failed (pre-migration install or test env) — fall through
+        }
+        if (dbCacheResult) {
+            const cached = parseCache(dbCacheResult.indexJson, { stale: false });
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        // ── Step 2: Fetch fresh ──────────────────────────────────────────────────
+        try {
+            const { value, cacheJson, cacheOpts } = await fetchFresh(db);
+            if (db) {
+                try {
+                    upsertRegistryIndexCache(db, cacheKey, cacheJson, cacheOpts);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            return value;
+        }
+        catch (err) {
+            // Fetch failed — use stale DB cache if available.
+            if (dbCacheResult) {
+                const stale = parseCache(dbCacheResult.indexJson, { stale: true });
+                if (stale !== undefined)
+                    return stale;
+            }
+            throw err;
+        }
+    });
+}

package/dist/storage/repositories/registry-index-cache-repository.js

@@ -0,0 +1,46 @@
+// 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/.
+/**
+ * Upsert a registry index cache entry in index.db.
+ *
+ * @param db          - Open index.db connection (from openDatabase / openExistingDatabase).
+ * @param registryUrl - Canonical URL of the registry (used as primary key).
+ * @param indexJson   - Serialised registry index document (JSON string).
+ * @param opts.etag        - HTTP ETag from the response (optional).
+ * @param opts.lastModified - HTTP Last-Modified from the response (optional).
+ */
+export function upsertRegistryIndexCache(db, registryUrl, indexJson, opts) {
+    db.prepare(`
+    INSERT INTO registry_index_cache (registry_url, fetched_at, etag, last_modified, index_json)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(registry_url) DO UPDATE SET
+      fetched_at    = excluded.fetched_at,
+      etag          = excluded.etag,
+      last_modified = excluded.last_modified,
+      index_json    = excluded.index_json
+  `).run(registryUrl, new Date().toISOString(), opts?.etag ?? null, opts?.lastModified ?? null, indexJson);
+}
+/**
+ * Look up a cached registry index entry from index.db.
+ * Returns undefined when not found or when the entry is older than `maxAgeMs`.
+ *
+ * TTL check: if `Date.now() - new Date(fetched_at).getTime() > maxAgeMs` the
+ * entry is considered a cache miss and undefined is returned.
+ *
+ * @param db          - Open index.db connection.
+ * @param registryUrl - Canonical URL of the registry (primary key).
+ * @param maxAgeMs    - Maximum age in milliseconds before the entry is stale (default: 1 hour).
+ */
+export function getRegistryIndexCache(db, registryUrl, maxAgeMs = 3_600_000 /* 1 hour */) {
+    const row = db
+        .prepare(`SELECT fetched_at, etag, last_modified, index_json
+       FROM registry_index_cache WHERE registry_url = ?`)
+        .get(registryUrl);
+    if (!row)
+        return undefined;
+    const fetchedAt = Date.parse(row.fetched_at);
+    if (Number.isNaN(fetchedAt) || Date.now() - fetchedAt > maxAgeMs)
+        return undefined;
+    return { indexJson: row.index_json, etag: row.etag, lastModified: row.last_modified };
+}

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

@@ -0,0 +1,93 @@
+// 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/.
+/**
+ * Upsert a task history row.
+ */
+export function upsertTaskHistory(db, row) {
+    // INSERT OR IGNORE: if a run with the same (task_id, started_at) was already
+    // imported (e.g. by the migration script), skip it silently.
+    db.prepare(`
+    INSERT OR IGNORE INTO task_history
+      (task_id, status, started_at, completed_at, failed_at, log_path,
+       target_kind, target_ref, metadata_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(row.task_id, row.status, row.started_at, row.completed_at ?? null, row.failed_at ?? null, row.log_path ?? null, row.target_kind ?? null, row.target_ref ?? null, row.metadata_json);
+}
+/**
+ * Look up a task history row by task_id. Returns undefined when not found.
+ */
+/**
+ * Return the most recent run for a given task_id, or undefined if no runs exist.
+ */
+export function getTaskHistory(db, taskId) {
+    return db
+        .prepare(`SELECT id, task_id, status, started_at, completed_at, failed_at, log_path,
+              target_kind, target_ref, metadata_json
+       FROM task_history WHERE task_id = ? ORDER BY started_at DESC LIMIT 1`)
+        .get(taskId);
+}
+/**
+ * Return all runs for a given task_id, newest first.
+ */
+export function getTaskHistoryRuns(db, taskId, limit = 50) {
+    return db
+        .prepare(`SELECT id, task_id, status, started_at, completed_at, failed_at, log_path,
+              target_kind, target_ref, metadata_json
+       FROM task_history WHERE task_id = ? ORDER BY started_at DESC LIMIT ?`)
+        .all(taskId, limit);
+}
+/**
+ * Query task history rows by started_at range and/or status.
+ */
+export function queryTaskHistory(db, options = {}) {
+    const conditions = [];
+    const params = [];
+    if (options.since) {
+        conditions.push("started_at >= ?");
+        params.push(options.since);
+    }
+    if (options.until) {
+        conditions.push("started_at <= ?");
+        params.push(options.until);
+    }
+    if (options.status) {
+        conditions.push("status = ?");
+        params.push(options.status);
+    }
+    if (options.targetKind) {
+        conditions.push("target_kind = ?");
+        params.push(options.targetKind);
+    }
+    if (options.targetRef) {
+        conditions.push("target_ref = ?");
+        params.push(options.targetRef);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    return db
+        .prepare(`SELECT task_id, status, started_at, completed_at, failed_at, log_path,
+              target_kind, target_ref, metadata_json
+       FROM task_history ${where} ORDER BY started_at DESC`)
+        .all(...params);
+}
+/**
+ * Read COMPLETED `akm-improve` task_history runs whose `started_at` falls in
+ * `[since, until)` (or `started_at >= since` when `until` is omitted), ordered
+ * oldest-first by `started_at`. Only rows with a non-null `completed_at` are
+ * returned (in-flight runs are excluded). The `task_id = 'akm-improve'`
+ * predicate is fixed because the only caller (commands/health.ts
+ * `loadTaskIntervals`) builds wall-time intervals for the improve cron task.
+ *
+ * Owns the SQL formerly inlined in commands/health.ts. Note the bound is
+ * EXCLUSIVE on the upper end (`started_at < ?`) — callers pass an already
+ * widened window; this helper does not widen.
+ *
+ * Connection-lifetime rule (WS5): `.all()` materializes a plain array before
+ * returning.
+ */
+export function queryCompletedTaskIntervals(db, since, until) {
+    const sql = until
+        ? "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND started_at < ? AND completed_at IS NOT NULL ORDER BY started_at"
+        : "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND completed_at IS NOT NULL ORDER BY started_at";
+    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
+}

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

@@ -56,7 +56,17 @@ export class WorkflowRunsRepository {
             params.push(filter.workflowRef);
         }
         if (filter.activeOnly) {
-            filters.push("status IN ('active', 'blocked')");
+            // `activeOnly` means EXACTLY status='active' — a run currently
+            // executable. A `blocked` run is NOT active (it is parked awaiting a
+            // human `resume`), so it must never appear under `--active`, or a script
+            // treating `--active` output as executable work would pick up a blocked
+            // run (owner manual-validation finding 1). Blocked runs stay visible in
+            // plain `list` (all statuses) with their `blocked` status. The
+            // active-OR-blocked scope semantics some call sites want (the `akm show`
+            // scope guard, which surfaces a blocked run as the scope's occupant) live
+            // in the SEPARATE {@link findActiveOrBlockedRunForScope} — never folded
+            // into this shared list filter.
+            filters.push("status = 'active'");
         }
         const where = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
         return this.db
@@ -120,6 +130,184 @@ export class WorkflowRunsRepository {
     rearmCheckin(runId, checkinArmedAt) {
         this.db.prepare("UPDATE workflow_runs SET checkin_armed_at = ? WHERE id = ?").run(checkinArmedAt, runId);
     }
+    /**
+     * Freeze the compiled plan on the run row (migration 006, redesign addendum
+     * R1): `planJson` is the CANONICAL plan JSON (`ir/plan-hash.ts`), `planHash`
+     * its sha256. Called by `startWorkflowRun` inside the same transaction as
+     * `insertRun`, so a run row never exists without its frozen plan. Read back
+     * via {@link getRunById} (`plan_json` / `plan_hash` on the row).
+     */
+    setRunPlan(runId, planJson, planHash) {
+        this.db
+            .prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ? WHERE id = ?")
+            .run(planJson, planHash, runId);
+    }
+    // ── 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.
+     */
+    acquireEngineLease(runId, holder, until, now) {
+        const result = this.db
+            .prepare(`UPDATE workflow_runs
+           SET engine_lease_holder = ?, engine_lease_until = ?
+           WHERE id = ? 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;
+    }
+    /**
+     * 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.
+     */
+    renewEngineLease(runId, holder, until) {
+        const result = this.db
+            .prepare("UPDATE workflow_runs SET engine_lease_until = ? WHERE id = ? AND engine_lease_holder = ?")
+            .run(until, runId, holder);
+        return Number(result.changes) > 0;
+    }
+    /**
+     * Clear the lease — only while `holder` still owns it, so a crashed-then-
+     * recovered invocation can never release a lease another engine has since
+     * claimed. 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 = ?")
+            .run(runId, holder);
+    }
+    // ── unit rows (migration 004) ──────────────────────────────────────────────
+    //
+    // Writes to `workflow_run_units` should go through the serialized writer
+    // queue (`src/workflows/exec/unit-writer.ts`) when N units may complete
+    // concurrently — SQLite has a single writer and `withWorkflowRunsRepo`
+    // opens a fresh connection per call.
+    getUnitsForRun(runId) {
+        return this.db
+            .prepare("SELECT * FROM workflow_run_units WHERE run_id = ? ORDER BY started_at ASC, unit_id ASC")
+            .all(runId);
+    }
+    getUnitsForStep(runId, stepId) {
+        return this.db
+            .prepare("SELECT * FROM workflow_run_units WHERE run_id = ? AND step_id = ? ORDER BY started_at ASC, unit_id ASC")
+            .all(runId, stepId);
+    }
+    /** One unit row by primary key, or undefined. Used by the R3 report path's
+     * guarded read-then-write (idempotency / replay-divergence / claim checks). */
+    getUnit(runId, unitId) {
+        return this.db.prepare("SELECT * FROM workflow_run_units WHERE run_id = ? AND unit_id = ?").get(runId, unitId);
+    }
+    /**
+     * Stamp a unit-level check-in heartbeat (migration 007, R3 driver protocol):
+     * a driver executing a unit calls `report --status running` to claim (first
+     * call) or heartbeat (subsequent) it. Sets `status = 'running'` and
+     * `last_checkin_at`; NEVER touches `started_at` (the first-claim marker set by
+     * {@link insertUnit}) so the heartbeat window advances without resetting the
+     * claim time. The caller guards against re-claiming a terminal unit inside its
+     * transaction.
+     */
+    updateUnitCheckin(runId, unitId, lastCheckinAt) {
+        this.db
+            .prepare("UPDATE workflow_run_units SET status = 'running', last_checkin_at = ? WHERE run_id = ? AND unit_id = ?")
+            .run(lastCheckinAt, runId, unitId);
+    }
+    /**
+     * Insert a unit row in `running` state (a dispatch is starting now).
+     *
+     * Upsert on the (run_id, unit_id) primary key: durable-row resume
+     * re-dispatches units whose previous attempt never reached a terminal status
+     * (a crash mid-step leaves `running` rows). The fresh dispatch REPLACES the
+     * stale row — value columns (`result_json`/`tokens`/`failure_reason`/
+     * `session_id`/`finished_at`/`last_checkin_at`) are reset exactly as the old
+     * `INSERT OR REPLACE` reset them, and the dispatch metadata is overwritten —
+     * but `attempts` is INCREMENTED rather than reset (migration 008). A first
+     * insert lands `attempts = 1` (column default); each re-dispatch bumps it, so
+     * budget/lifetime seeds that sum `attempts` charge every crash-retried
+     * dispatch instead of collapsing them into one row. Using `ON CONFLICT DO
+     * UPDATE` (not `INSERT OR REPLACE`, which deletes+reinserts) is what lets the
+     * increment read the prior row's counter.
+     */
+    insertUnit(input) {
+        this.db
+            .prepare(`INSERT INTO workflow_run_units (
+          run_id, unit_id, step_id, node_id, parent_unit_id, phase, runner, model,
+          status, input_hash, worktree_path, started_at, claim_holder, claim_expires_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', ?, ?, ?, ?, ?)
+        ON CONFLICT(run_id, unit_id) DO UPDATE SET
+          step_id          = excluded.step_id,
+          node_id          = excluded.node_id,
+          parent_unit_id   = excluded.parent_unit_id,
+          phase            = excluded.phase,
+          runner           = excluded.runner,
+          model            = excluded.model,
+          status           = excluded.status,
+          input_hash       = excluded.input_hash,
+          worktree_path    = excluded.worktree_path,
+          started_at       = excluded.started_at,
+          claim_holder     = excluded.claim_holder,
+          claim_expires_at = excluded.claim_expires_at,
+          result_json      = NULL,
+          tokens           = NULL,
+          failure_reason   = NULL,
+          session_id       = NULL,
+          finished_at      = NULL,
+          last_checkin_at  = NULL,
+          attempts         = workflow_run_units.attempts + 1`)
+            .run(input.runId, input.unitId, input.stepId, input.nodeId, input.parentUnitId, input.phase, input.runner, input.model, input.inputHash, input.worktreePath ?? null, input.startedAt, input.claimHolder ?? null, input.claimExpiresAt ?? null);
+    }
+    /**
+     * Stamp a `--status running` claim + heartbeat on a unit row (migration 009,
+     * PR #714 review round 2). Sets `status = 'running'`, refreshes the heartbeat
+     * (`last_checkin_at`), and (re)writes the claim owner + expiry. Called inside
+     * the report path's running-claim transaction AFTER it has validated that the
+     * claim is free / expired / already held by this holder, so the write is the
+     * final step of a checked reclaim. Never touches `started_at` (the first-claim
+     * marker set by {@link insertUnit}).
+     */
+    updateUnitClaim(runId, unitId, holder, expiresAt, lastCheckinAt) {
+        this.db
+            .prepare(`UPDATE workflow_run_units
+           SET status = 'running', last_checkin_at = ?, claim_holder = ?, claim_expires_at = ?
+           WHERE run_id = ? AND unit_id = ?`)
+            .run(lastCheckinAt, holder, expiresAt, runId, unitId);
+    }
+    /**
+     * Record a unit's terminal state (completed / failed / skipped).
+     *
+     * ## Loud contract (must update exactly one row)
+     *
+     * A finish ALWAYS targets a row a prior dispatch/claim inserted: every caller
+     * ({@link insertUnit} in the executor and the report path,
+     * {@link journalGateEvaluationStart} for gate rows) writes the `running` row
+     * before finishing it, inside the same writer-queue task or SQLite
+     * transaction. If the UPDATE matches NO `(run_id, unit_id)` row the journal is
+     * inconsistent — a finish against a missing or mismatched unit id — and the
+     * unit's terminal state would silently vanish (the row stays `running`, or no
+     * row exists at all). That is a journaling BUG, so we throw loudly at the
+     * source instead of no-oping: a stuck-`running` unit would wedge resume
+     * (durable-row reuse never matches it) or corrupt budget/gate accounting.
+     */
+    finishUnit(input) {
+        const result = this.db
+            .prepare(`UPDATE workflow_run_units
+           SET status = ?, result_json = ?, tokens = ?, failure_reason = ?, session_id = ?, finished_at = ?
+           WHERE run_id = ? AND unit_id = ?`)
+            .run(input.status, input.resultJson, input.tokens, input.failureReason, input.sessionId ?? null, input.finishedAt, input.runId, input.unitId);
+        if (Number(result.changes) === 0) {
+            throw new Error(`finishUnit updated no row: no unit "${input.unitId}" exists for run "${input.runId}". ` +
+                `A unit must be inserted (dispatched or claimed) before it can be finished — a finish that ` +
+                `matches no row indicates a journaling bug (mismatched unit id or a lost dispatch row), not a ` +
+                `recoverable state.`);
+        }
+    }
 }
 /**
  * Open the workflow database (bound to {@link StorageLocations.workflowDb}),