akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/setup/steps/connection.js

@@ -9,7 +9,8 @@ import * as p from "../../cli/clack.js";
 import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../../integrations/agent/index.js";
 import { probeLlmCapabilities } from "../../llm/client.js";
 import { detectLMStudio, detectOllama } from "../detect.js";
-import { cloneLlmConfig, getCurrentAgentBlock, getCurrentLlm } from "../legacy-config.js";
+import { verifyOpenAiCompatibleEndpoint } from "../detected-engines.js";
+import { cloneLlmConnection, readAgentEngineSelection, readCurrentLlmEngine, } from "../engine-config.js";
 import { prompt, promptOrBack } from "../prompt.js";
 export async function stepOllama(current) {
     const spin = p.spinner();
@@ -154,7 +155,7 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels, lmStudi
     options.push({ value: "lmstudio", label: "LM Studio / local server", hint: lmStudioHint });
     options.push({ value: "custom", label: "Custom OpenAI-compatible endpoint" });
     options.push({ value: "none", label: "Skip LLM", hint: "no metadata enhancement during indexing" });
-    const currentLlm = getCurrentLlm(current);
+    const currentLlm = readCurrentLlmEngine(current);
     if (currentLlm) {
         options.push({
             value: "keep",
@@ -169,7 +170,7 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels, lmStudi
         initialValue,
     }));
     if (choice === "keep")
-        return cloneLlmConfig(currentLlm);
+        return cloneLlmConnection(currentLlm);
     if (choice === "none")
         return undefined;
     // Handle "Import from <Harness>" choices
@@ -180,16 +181,28 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels, lmStudi
         // Show a summary before accepting
         p.log.info(`Importing LLM config from ${harness.harnessName}: ` +
             [harness.provider, harness.model, harness.baseUrl].filter(Boolean).join(", "));
+        if (!harness.baseUrl || !harness.model) {
+            p.log.warn(`Skipping ${harness.harnessName}: no complete endpoint/model was detected.`);
+            return undefined;
+        }
+        const verified = await verifyOpenAiCompatibleEndpoint({
+            endpoint: harness.baseUrl,
+            model: harness.model,
+            apiKeyEnvVar: harness.apiKeyEnvVar,
+        });
+        if (!verified.ok) {
+            p.log.warn(`Skipping ${harness.harnessName}: ${verified.reason}. Fix its endpoint/credential and retry setup.`);
+            return undefined;
+        }
         const llmConfig = {
-            endpoint: harness.baseUrl ?? "",
+            endpoint: verified.endpoint,
             model: harness.model ?? "",
             temperature: 0.3,
             maxTokens: 1024,
+            ...(harness.apiKeyEnvVar ? { apiKey: `\${${harness.apiKeyEnvVar}}` } : {}),
         };
         if (harness.provider)
             llmConfig.provider = harness.provider;
-        if (harness.baseUrl)
-            llmConfig.endpoint = harness.baseUrl;
         return llmConfig;
     }
     let llm;
@@ -376,7 +389,7 @@ export async function stepSmallModelConnection(current) {
         ? `${lmStudio.models.length} model${lmStudio.models.length === 1 ? "" : "s"} detected`
         : "http://localhost:1234";
     providerOptions.push({ value: "openai", label: "OpenAI", hint: "requires AKM_LLM_API_KEY" }, { value: "lmstudio", label: "LM Studio / local server", hint: lmStudioHint }, { value: "custom", label: "Custom OpenAI-compatible endpoint" }, { value: "skip", label: "Skip — disable enrichment features" });
-    const currentLlmSmall = getCurrentLlm(current);
+    const currentLlmSmall = readCurrentLlmEngine(current);
     if (currentLlmSmall) {
         providerOptions.push({
             value: "keep",
@@ -391,7 +404,7 @@ export async function stepSmallModelConnection(current) {
         initialValue,
     }));
     if (providerChoice === "keep") {
-        return { llm: cloneLlmConfig(currentLlmSmall), skipped: false, ollamaEndpoint };
+        return { llm: cloneLlmConnection(currentLlmSmall), skipped: false, ollamaEndpoint };
     }
     if (providerChoice === "skip") {
         p.note([
@@ -539,8 +552,11 @@ export async function stepSmallModelConnection(current) {
             validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
         }));
         const apiKeyInput = await promptOrBack(() => p.text({
-            message: "API key (optional — press Enter to skip):",
-            placeholder: "",
+            message: "API key environment variable name (optional):",
+            placeholder: "CUSTOM_LLM_API_KEY",
+            validate: (value) => value && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)
+                ? "Use an environment variable name, not a key value"
+                : undefined,
         }));
         llm = {
             provider: "custom",
@@ -548,7 +564,7 @@ export async function stepSmallModelConnection(current) {
             model: model.trim(),
             temperature: 0.3,
             maxTokens: 1024,
-            ...(apiKeyInput?.trim() ? { apiKey: apiKeyInput.trim() } : {}),
+            ...(apiKeyInput?.trim() ? { apiKey: `\${${apiKeyInput.trim()}}` } : {}),
         };
     }
     // Best-effort probe — never blocks setup.
@@ -584,7 +600,7 @@ export async function stepAgentConnection(current, smallModel) {
     ].join("\n"));
     // Detect available CLI agents.
     const detections = detectAgentCliProfiles(current);
-    const currentAgentBlock = getCurrentAgentBlock(current);
+    const currentAgentBlock = readAgentEngineSelection(current);
     const availableClis = detections.filter((d) => d.available);
     const agentOptions = [];
     if (!smallModel.skipped && smallModel.llm) {
@@ -606,8 +622,8 @@ export async function stepAgentConnection(current, smallModel) {
     if (currentAgentBlock) {
         const currentDesc = currentAgentBlock.default
             ? `CLI: ${currentAgentBlock.default}`
-            : currentAgentBlock.profiles?.default?.model
-                ? `SDK: ${currentAgentBlock.profiles.default.model}`
+            : currentAgentBlock.engines?.default?.model
+                ? `SDK: ${currentAgentBlock.engines.default.model}`
                 : "configured";
         agentOptions.push({ value: "keep", label: `Keep current: ${currentDesc}` });
     }
@@ -647,9 +663,9 @@ export async function stepAgentConnection(current, smallModel) {
         else {
             const baseEndpoint = smallModel.llm.endpoint.replace("/v1/chat/completions", "");
             p.log.info(`Endpoint: ${baseEndpoint} (from Step 1)`);
-            const profileName = smallModel.llm.provider ?? "default";
+            const profileName = `${smallModel.llm.provider ?? "default"}-agent`;
             // Pre-populate from existing agent profile for this provider, if any.
-            const existingAgentModel = currentAgentBlock?.profiles?.[profileName]?.model ?? smallModel.llm.model ?? undefined;
+            const existingAgentModel = currentAgentBlock?.engines?.[profileName]?.model ?? smallModel.llm.model ?? undefined;
             const agentModel = await prompt(() => p.text({
                 message: "Model to use for agent tasks (same model is fine, larger models work better):",
                 placeholder: existingAgentModel ?? "qwen2.5-coder:32b",
@@ -658,13 +674,14 @@ export async function stepAgentConnection(current, smallModel) {
             }));
             return {
                 ...(currentAgentBlock ?? {}),
-                profiles: {
-                    ...(currentAgentBlock?.profiles ?? {}),
+                engines: {
+                    ...(currentAgentBlock?.engines ?? {}),
                     [profileName]: {
-                        ...(currentAgentBlock?.profiles?.[profileName] ?? {}),
-                        sdkMode: true,
+                        ...(currentAgentBlock?.engines?.[profileName] ?? {}),
+                        kind: "agent",
+                        platform: "opencode-sdk",
                         model: agentModel.trim(),
-                        endpoint: smallModel.llm.endpoint,
+                        ...(current.defaults?.llmEngine ? { llmEngine: current.defaults.llmEngine } : {}),
                     },
                 },
                 default: profileName,
@@ -693,8 +710,8 @@ export async function stepAgentConnection(current, smallModel) {
     }
     // "new-connection" (also fall-through from "same-provider" when Step 1 was skipped)
     // Pre-populate from current "custom" agent profile if available.
-    const currentCustomAgentProfile = currentAgentBlock?.profiles?.custom;
-    const currentNewEndpoint = currentCustomAgentProfile?.endpoint ?? undefined;
+    const currentCustomAgentProfile = currentAgentBlock?.engines?.["custom-agent"];
+    const currentNewEndpoint = undefined;
     const currentNewModel = currentCustomAgentProfile?.model ?? undefined;
     const newEndpoint = await prompt(() => p.text({
         message: "OpenAI-compatible chat completions endpoint:",
@@ -708,8 +725,11 @@ export async function stepAgentConnection(current, smallModel) {
         },
     }));
     const newApiKeyInput = await promptOrBack(() => p.text({
-        message: "API key (optional — press Enter to skip):",
-        placeholder: "",
+        message: "API key environment variable name (optional):",
+        placeholder: "CUSTOM_LLM_API_KEY",
+        validate: (value) => value && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)
+            ? "Use an environment variable name, not a key value"
+            : undefined,
     }));
     const newModel = await prompt(() => p.text({
         message: "Model name (larger is better, e.g. gpt-4o):",
@@ -717,18 +737,27 @@ export async function stepAgentConnection(current, smallModel) {
         ...(currentNewModel ? { defaultValue: currentNewModel } : {}),
         validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
     }));
+    const llmEngineName = "custom-llm";
+    const agentEngineName = "custom-agent";
     const customProfile = {
-        sdkMode: true,
-        endpoint: newEndpoint.trim(),
+        kind: "agent",
+        platform: "opencode-sdk",
+        llmEngine: llmEngineName,
         model: newModel.trim(),
-        ...(newApiKeyInput?.trim() ? { apiKey: newApiKeyInput.trim() } : {}),
     };
     return {
         ...(currentAgentBlock ?? {}),
-        profiles: {
-            ...(currentAgentBlock?.profiles ?? {}),
-            custom: customProfile,
+        engines: {
+            ...(currentAgentBlock?.engines ?? {}),
+            [llmEngineName]: {
+                kind: "llm",
+                provider: "custom",
+                endpoint: newEndpoint.trim(),
+                model: newModel.trim(),
+                ...(newApiKeyInput?.trim() ? { apiKey: `\${${newApiKeyInput.trim()}}` } : {}),
+            },
+            [agentEngineName]: customProfile,
         },
-        default: "custom",
+        default: agentEngineName,
     };
 }

package/dist/setup/steps/platforms.js

@@ -8,7 +8,7 @@
 import * as p from "../../cli/clack.js";
 import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../../integrations/agent/index.js";
 import { detectAgentPlatforms } from "../detect.js";
-import { getCurrentAgentBlock } from "../legacy-config.js";
+import { readAgentEngineSelection } from "../engine-config.js";
 import { prompt } from "../prompt.js";
 export async function stepAgentPlatforms(current) {
     const platforms = detectAgentPlatforms();
@@ -66,7 +66,7 @@ export function printCapabilitySummary(smallModelSkipped, agentConfigured) {
     p.note(lines.join("\n"), "Feature Summary");
 }
 export async function stepAgentSelection(current, detections) {
-    const currentAgentBlock = getCurrentAgentBlock(current);
+    const currentAgentBlock = readAgentEngineSelection(current);
     const available = detections.filter((d) => d.available);
     if (available.length === 0) {
         return currentAgentBlock;
@@ -85,7 +85,7 @@ export async function stepAgentSelection(current, detections) {
         initialValue,
     }));
     if (selectedDefault === "disabled") {
-        if (!currentAgentBlock?.profiles && !currentAgentBlock?.timeoutMs) {
+        if (!currentAgentBlock?.engines) {
             return undefined;
         }
         return {
@@ -110,7 +110,7 @@ export async function stepAgentSelection(current, detections) {
  */
 export function stepAgentCliDetection(current, detectFn = detectAgentCliProfiles) {
     const detections = detectFn(current);
-    const currentAgentBlock = getCurrentAgentBlock(current);
+    const currentAgentBlock = readAgentEngineSelection(current);
     const defaultName = pickDefaultAgentProfile(detections, currentAgentBlock?.default);
     // No installed agents found and no existing config → leave block absent.
     if (!defaultName && !currentAgentBlock) {

package/dist/setup/steps.js

@@ -1,20 +1,21 @@
 // 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 { deepMergeConfig } from "../core/config/deep-merge.js";
 /**
  * Build a fresh `SetupContext` over a starting config. The returned context
  * applies deltas in-place onto an internal accumulator and exposes the
  * latest snapshot via `ctx.config`.
  */
 export function createSetupContext(initial, options) {
-    let acc = { ...initial };
+    let acc = deepMergeConfig({}, initial);
     return {
         get config() {
             return acc;
         },
         nonInteractive: options.nonInteractive,
         apply(delta) {
-            acc = { ...acc, ...delta };
+            acc = deepMergeConfig(acc, delta);
         },
     };
 }

package/dist/storage/database.js

@@ -133,5 +133,17 @@ function openNodeDatabase(path, opts) {
     if (opts?.create === false)
         options.fileMustExist = true;
     const db = opts ? new BetterSqlite3(path, options) : new BetterSqlite3(path);
-    return db;
+    return {
+        prepare: db.prepare.bind(db),
+        exec: db.exec.bind(db),
+        // better-sqlite3 exposes mutations on prepared statements, while
+        // bun:sqlite also provides db.run(). Normalize the latter at the provider
+        // boundary so callers and maintenance wrappers can rely on one contract.
+        run: (sql, ...params) => db.prepare(sql).run(...params),
+        transaction: db.transaction.bind(db),
+        get inTransaction() {
+            return db.inTransaction;
+        },
+        close: db.close.bind(db),
+    };
 }

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

@@ -34,6 +34,7 @@ export function runMigrations(db, migrations, opts) {
     for (const migration of migrations) {
         if (applied.has(migration.id))
             continue;
+        opts?.beforeMigration?.(migration);
         db.transaction(() => {
             db.exec(migration.up);
             db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);

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

@@ -103,10 +103,10 @@ export function recordImproveRun(db, input) {
     const metricsObj = input.metrics ?? computeImproveRunMetrics(input.result);
     db.prepare(`
     INSERT INTO improve_runs
-      (id, started_at, completed_at, stash_dir, dry_run, profile,
+       (id, started_at, completed_at, stash_dir, dry_run, profile, strategy,
        scope_mode, scope_value, guidance, ok, result_json, metrics_json, metadata_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.profile, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.legacyProfile ?? null, input.strategy ?? null, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
 }
 /**
  * Read real (non-dry-run) improve_runs rows whose `started_at` falls in the
@@ -124,8 +124,8 @@ export function recordImproveRun(db, input) {
  */
 export function queryImproveRuns(db, since, until) {
     const sql = until
-        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
-        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
+        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, profile AS legacyProfile, strategy, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
+        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, profile AS legacyProfile, strategy, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
     return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
 }
 /**

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

@@ -1,6 +1,84 @@
 // 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/.
+function metadataError(message) {
+    throw new Error(`invalid task_history metadata_json: ${message}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateDetail(value) {
+    if (value === undefined || value === null)
+        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`);
+    }
+    if (value.exitCode !== undefined && value.exitCode !== null && typeof value.exitCode !== "number") {
+        metadataError("detail.exitCode must be a number or null");
+    }
+}
+/** Decode historical v1 and current v2 metadata without cross-version aliases. */
+export function decodeTaskHistoryMetadata(input) {
+    let parsed = input;
+    if (typeof input === "string") {
+        try {
+            parsed = JSON.parse(input);
+        }
+        catch {
+            metadataError("not valid JSON");
+        }
+    }
+    if (!isRecord(parsed))
+        metadataError("root must be an object");
+    const version = parsed.metadataVersion ?? 1;
+    if (version === 1) {
+        const allowed = new Set(["metadataVersion", "durationMs", "detail", "profile"]);
+        const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
+        if (unknown.length > 0)
+            metadataError(`unknown v1 fields: ${unknown.sort().join(", ")}`);
+        if (parsed.metadataVersion !== undefined && parsed.metadataVersion !== 1)
+            metadataError("invalid v1 metadataVersion");
+        if (parsed.durationMs !== undefined && typeof parsed.durationMs !== "number")
+            metadataError("durationMs must be a number");
+        if (parsed.profile !== undefined && typeof parsed.profile !== "string")
+            metadataError("profile must be a string");
+        validateDetail(parsed.detail);
+        return {
+            metadataVersion: 1,
+            ...(typeof parsed.durationMs === "number" ? { durationMs: parsed.durationMs } : {}),
+            ...(parsed.detail !== undefined && parsed.detail !== null ? { detail: parsed.detail } : {}),
+            ...(typeof parsed.profile === "string" ? { legacyProfile: parsed.profile } : {}),
+        };
+    }
+    if (version === 2) {
+        const allowed = new Set(["metadataVersion", "durationMs", "detail", "engine"]);
+        const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
+        if (unknown.length > 0)
+            metadataError(`unknown v2 fields: ${unknown.sort().join(", ")}`);
+        if (typeof parsed.durationMs !== "number")
+            metadataError("durationMs must be a number");
+        if (!("detail" in parsed))
+            metadataError("detail is required in v2");
+        if (parsed.engine !== undefined && parsed.engine !== null && typeof parsed.engine !== "string") {
+            metadataError("engine must be a string or null");
+        }
+        validateDetail(parsed.detail);
+        return {
+            metadataVersion: 2,
+            durationMs: parsed.durationMs,
+            detail: parsed.detail ?? null,
+            ...(parsed.engine !== undefined ? { engine: parsed.engine } : {}),
+        };
+    }
+    metadataError(`unsupported metadataVersion: ${String(version)}`);
+}
 /**
  * Upsert a task history row.
  */

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,185 @@ 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, planIrVersion = 3) {
+        this.db
+            .prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ?, plan_ir_version = ? WHERE id = ?")
+            .run(planJson, planHash, planIrVersion, 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, engine, 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,
+           engine           = excluded.engine,
+          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.engine ?? null, 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}),