akm-cli 0.9.1 → 0.9.2-alpha.2

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

@@ -183,10 +183,8 @@ export function proposalRowToProposal(row) {
         throw new Error("Proposal row has invalid metadata_json.", { cause: error });
     }
     validatePresentMetadata(meta);
-    const changes = Object.hasOwn(meta, "changes")
-        ? storedToChanges(meta.changes, row.content)
-        : [{ path: "", op: "update", after: row.content }];
-    const proposedTarget = Object.hasOwn(meta, "proposedTarget") ? currentProposalTarget(meta.proposedTarget) : undefined;
+    const changes = storedToChanges(meta.changes, row.content);
+    const proposedTarget = currentProposalTarget(meta.proposedTarget);
     return {
         id: row.id,
         ref: currentProposalRef(row.ref),
@@ -200,7 +198,7 @@ export function proposalRowToProposal(row) {
             ...(frontmatter !== undefined ? { frontmatter } : {}),
         },
         changes,
-        ...(proposedTarget !== undefined ? { proposedTarget } : {}),
+        proposedTarget,
         ...(typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {}),
         ...(meta.review !== undefined ? { review: meta.review } : {}),
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
@@ -212,110 +210,6 @@ export function proposalRowToProposal(row) {
             : {}),
     };
 }
-/**
- * Lenient counterpart to {@link proposalRowToProposal} for the terminal-status
- * (reject/archive) read paths (repository.ts `archiveProposal` /
- * `rejectProposalDurably`). Those paths must succeed even on legacy rows
- * minted before a field was required — e.g. 0.8-era rows missing
- * `proposedTarget` and/or carrying empty/missing `changes[].path` metadata —
- * so an operator can reject them instead of resorting to manual SQL.
- *
- * Per-field decode failures are swallowed: the offending field degrades to a
- * safe placeholder (matching the strict decoder's own "no changes recorded"
- * fallback) and the failure is appended to `decodeWarnings` instead of
- * throwing. `id` / `status` / timestamps / `source` are trusted verbatim (the
- * schema guarantees they're non-null strings). The strict decoder remains the
- * default everywhere else, including every other read of a `pending` or
- * `accepted` proposal (accept/revert must keep failing exactly as today on a
- * malformed row).
- */
-export function proposalRowToProposalLenient(row) {
-    const warnings = [];
-    let meta = {};
-    try {
-        const parsed = JSON.parse(row.metadata_json);
-        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-            throw new Error("metadata_json must contain an object.");
-        }
-        meta = parsed;
-        validatePresentMetadata(meta);
-    }
-    catch (error) {
-        warnings.push(`metadata_json is invalid (${error instanceof Error ? error.message : String(error)}); optional fields dropped.`);
-        meta = {};
-    }
-    let frontmatter;
-    if (row.frontmatter_json !== null) {
-        try {
-            const parsed = JSON.parse(row.frontmatter_json);
-            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-                throw new Error("frontmatter_json must contain an object.");
-            }
-            frontmatter = parsed;
-        }
-        catch (error) {
-            warnings.push(`frontmatter_json is invalid (${error instanceof Error ? error.message : String(error)}); frontmatter dropped.`);
-        }
-    }
-    let ref;
-    try {
-        ref = currentProposalRef(row.ref);
-    }
-    catch (error) {
-        warnings.push(`ref is invalid (${error instanceof Error ? error.message : String(error)}); keeping the raw stored value.`);
-        ref = row.ref;
-    }
-    let changes;
-    try {
-        changes = Object.hasOwn(meta, "changes")
-            ? storedToChanges(meta.changes, row.content)
-            : [{ path: "", op: "update", after: row.content }];
-    }
-    catch (error) {
-        warnings.push(`changes metadata is invalid (${error instanceof Error ? error.message : String(error)}); degraded to a single placeholder change.`);
-        changes = [{ path: "", op: "update", after: row.content }];
-    }
-    let proposedTarget;
-    if (Object.hasOwn(meta, "proposedTarget")) {
-        try {
-            proposedTarget = currentProposalTarget(meta.proposedTarget);
-        }
-        catch (error) {
-            warnings.push(`proposedTarget is invalid (${error instanceof Error ? error.message : String(error)}); omitted.`);
-        }
-    }
-    else {
-        warnings.push("proposedTarget is missing (pre-WI-6.2 legacy row).");
-    }
-    if (!["pending", "accepted", "rejected", "reverted"].includes(row.status)) {
-        warnings.push(`status "${row.status}" is not a recognized value.`);
-    }
-    return {
-        id: row.id,
-        ref,
-        status: row.status,
-        source: row.source,
-        ...(typeof meta.sourceRun === "string" ? { sourceRun: meta.sourceRun } : {}),
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-        payload: {
-            content: row.content,
-            ...(frontmatter !== undefined ? { frontmatter } : {}),
-        },
-        changes,
-        ...(proposedTarget !== undefined ? { proposedTarget } : {}),
-        ...(typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {}),
-        ...(meta.review !== undefined ? { review: meta.review } : {}),
-        ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
-        ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
-        ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
-        ...(meta.acceptedTarget !== undefined ? { acceptedTarget: meta.acceptedTarget } : {}),
-        ...(typeof meta.eligibilitySource === "string"
-            ? { eligibilitySource: meta.eligibilitySource }
-            : {}),
-        ...(warnings.length > 0 ? { decodeWarnings: warnings } : {}),
-    };
-}
 /**
  * Convert a public `Proposal` to column values ready for an INSERT/UPDATE.
  * The `stash_dir` comes from the call site (proposals.ts has it in scope).
@@ -413,12 +307,7 @@ export function listStateProposals(db, options = {}) {
               content, frontmatter_json, metadata_json
        FROM proposals ${where} ORDER BY created_at ASC, rowid ASC`)
         .all(...params);
-    // Archived rows (accepted/rejected/reverted) decode leniently so a
-    // terminal-status row that was rejected via the lenient path (or predates
-    // a required field) remains listable — a strict throw here would defeat
-    // the point of tolerating it at reject/archive time. Pending rows keep the
-    // strict decoder; nothing about the live queue changes here.
-    return rows.map((row) => (row.status === "pending" ? proposalRowToProposal(row) : proposalRowToProposalLenient(row)));
+    return rows.map(proposalRowToProposal);
 }
 /**
  * Look up a single proposal by id, optionally scoped to one stash root.
@@ -431,18 +320,6 @@ export function getStateProposal(db, id, stashDir) {
     const row = (stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id));
     return row ? proposalRowToProposal(row) : undefined;
 }
-/**
- * Lenient counterpart to {@link getStateProposal} — used ONLY by the
- * terminal-status (reject/archive) read paths in repository.ts that must
- * tolerate a malformed row (see {@link proposalRowToProposalLenient}).
- */
-export function getStateProposalLenient(db, id, stashDir) {
-    const sql = `SELECT id, stash_dir, ref, status, source, created_at, updated_at,
-              content, frontmatter_json, metadata_json
-       FROM proposals WHERE id = ?${stashDir ? " AND stash_dir = ?" : ""}`;
-    const row = (stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id));
-    return row ? proposalRowToProposalLenient(row) : undefined;
-}
 /**
  * Find PENDING proposal ids in one stash whose id starts with `idPrefix`.
  * Backs the UUID-prefix form of `akm proposal show/accept/... <prefix>` —

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

@@ -2,6 +2,7 @@
 // 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 { formatRegistryError } from "../../core/registry-url.js";
 import { warn } from "../../core/warn.js";
 import { closeDatabase, openIndexDatabase } from "./index-connection.js";
 import { getRegistryIndexCache, upsertRegistryIndexCache } from "./registry-index-cache-repository.js";
@@ -96,7 +97,7 @@ export async function fetchCachedJson(opts) {
                 if (expiredRow) {
                     const stale = parseCache(expiredRow.indexJson, { stale: true });
                     if (stale !== undefined) {
-                        warn(`Registry fetch failed (${err instanceof Error ? err.message : String(err)}); ` +
+                        warn(`Registry fetch failed (${formatRegistryError(err)}); ` +
                             "serving the last cached index, which is past its refresh interval.");
                         return stale;
                     }

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

@@ -24,7 +24,7 @@ function validateDetail(value) {
         metadataError("detail.exitCode must be a number or null");
     }
 }
-/** Decode supported historical and current task-history metadata. */
+/** Decode the current task-history metadata shape. */
 export function decodeTaskHistoryMetadata(input) {
     let parsed = input;
     if (typeof input === "string") {
@@ -37,46 +37,26 @@ export function decodeTaskHistoryMetadata(input) {
     }
     if (!isRecord(parsed))
         metadataError("root must be an object");
-    if (parsed.metadataVersion === undefined || parsed.metadataVersion === 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.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,
-            durationMs: parsed.durationMs ?? 0,
-            detail: parsed.detail ?? null,
-            ...(parsed.profile !== undefined ? { legacyProfile: parsed.profile } : {}),
-        };
-    }
-    if (parsed.metadataVersion === 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 } : {}),
-        };
+    if (parsed.metadataVersion !== 2)
+        metadataError(`unsupported metadataVersion: ${String(parsed.metadataVersion)}`);
+    const allowed = new Set(["metadataVersion", "durationMs", "detail", "engine"]);
+    const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        metadataError(`unknown fields: ${unknown.sort().join(", ")}`);
+    if (typeof parsed.durationMs !== "number")
+        metadataError("durationMs must be a number");
+    if (!("detail" in parsed))
+        metadataError("detail is required");
+    if (parsed.engine !== undefined && parsed.engine !== null && typeof parsed.engine !== "string") {
+        metadataError("engine must be a string or null");
     }
-    metadataError(`unsupported metadataVersion: ${String(parsed.metadataVersion)}`);
+    validateDetail(parsed.detail);
+    return {
+        metadataVersion: 2,
+        durationMs: parsed.durationMs,
+        detail: parsed.detail ?? null,
+        ...(parsed.engine !== undefined ? { engine: parsed.engine } : {}),
+    };
 }
 /**
  * Atomically reserve one task-attempt identity.

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

@@ -1,16 +1,30 @@
 // 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 { randomUUID } from "node:crypto";
+import { UsageError } from "../../core/errors.js";
 import { openStateDatabase, withImmediateTransaction } from "../../core/state-db.js";
 import { borrowScopedStateDb, withStateDbScope } from "../../core/state-db-scope.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");
+    }
+}
 /**
  * Repository owning every raw SQL statement against `workflow_runs` and
  * `workflow_run_steps`. It is DB-location-agnostic: the lifecycle helper
- * {@link withWorkflowRunsRepo} binds it to {@link StorageLocations.stateDb}
- * (the three-DB cutover folded workflow.db into state.db; the tables exist via
- * state migration `020-three-db-cutover`) so a future storage move (#489)
- * changes only `locations.ts`.
+ * {@link withWorkflowRunsRepo} binds it to {@link StorageLocations.stateDb}, so
+ * a future storage move changes only `locations.ts`.
  *
  * ## Connection-lifetime contract (WS5)
  *
@@ -44,7 +58,8 @@ export class WorkflowRunsRepository {
             .get(...refs, scopeKey);
     }
     getRunById(runId) {
-        return this.db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(runId);
+        return (this.db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(runId) ??
+            undefined);
     }
     getActiveRunRowForScope(workflowRefs, scopeKey) {
         const refs = typeof workflowRefs === "string" ? [workflowRefs] : [...workflowRefs];
@@ -157,16 +172,34 @@ export class WorkflowRunsRepository {
         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).
+     * 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.
      */
-    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);
+    publishWorkflowRunV4(input) {
+        this.immediateTransaction((db) => {
+            input.revalidateSources();
+            if (!input.force) {
+                const existing = this.findActiveRunForScope(input.workflowRefs, input.run.scopeKey);
+                if (existing) {
+                    throw new UsageError(`Workflow ${input.run.workflowRef} already has an active run in this scope ` +
+                        `(id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
+                        `Use 'akm workflow run ${input.run.workflowRef}' to resume it or ` +
+                        `'akm workflow abandon ${existing.id}' to give up on it.`, "RESOURCE_ALREADY_EXISTS");
+                }
+            }
+            this.insertRun(input.run);
+            this.insertSteps(input.steps);
+            db.prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ?, plan_ir_version = 4 WHERE id = ?").run(input.planJson, input.planHash, input.run.id);
+            insertEventOnce(db, {
+                eventType: "workflow_started",
+                ts: input.run.createdAt,
+                ref: input.run.workflowRef,
+                metadata: { runId: input.run.id, status: "active" },
+                idempotencyKey: input.run.id,
+                idempotencyMetadataKey: "runId",
+            });
+        });
     }
     // ── engine run lease (migration 006 columns, R2 enforcement) ──────────────
     //
@@ -211,7 +244,186 @@ export class WorkflowRunsRepository {
             .prepare("UPDATE workflow_runs SET engine_lease_holder = NULL, engine_lease_until = NULL WHERE id = ? AND engine_lease_holder = ? AND status <> 'failed'")
             .run(runId, holder);
     }
-    // ── unit rows (migration 004) ──────────────────────────────────────────────
+    // ── durable v4 append-only dispatch attempts (migration 022) ─────────────
+    getUnitAttempts(runId, unitId) {
+        return this.db
+            .prepare(`SELECT * FROM workflow_run_unit_attempts
+          WHERE run_id = ? AND unit_id = ?
+          ORDER BY attempt`)
+            .all(runId, unitId);
+    }
+    getAttemptAccounting(runId) {
+        const row = this.db
+            .prepare(`SELECT
+           COUNT(*) AS total_attempts,
+           COALESCE(SUM(tokens), 0) AS total_tokens,
+           COALESCE(SUM(CASE WHEN phase = 'unit' THEN 1 ELSE 0 END), 0) AS dispatch_attempts,
+           COALESCE(SUM(CASE WHEN phase = 'unit' THEN COALESCE(tokens, 0) ELSE 0 END), 0) AS dispatch_tokens,
+           COALESCE(SUM(CASE WHEN phase = 'gate' THEN 1 ELSE 0 END), 0) AS gate_attempts,
+           COALESCE(SUM(CASE WHEN phase = 'gate' THEN COALESCE(tokens, 0) ELSE 0 END), 0) AS gate_tokens
+         FROM workflow_run_unit_attempts
+        WHERE run_id = ?`)
+            .get(runId);
+        return {
+            totalAttempts: Number(row.total_attempts),
+            totalTokens: Number(row.total_tokens),
+            dispatchAttempts: Number(row.dispatch_attempts),
+            dispatchTokens: Number(row.dispatch_tokens),
+            gateAttempts: Number(row.gate_attempts),
+            gateTokens: Number(row.gate_tokens),
+        };
+    }
+    /**
+     * 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.
+     */
+    reserveUnitAttempt(input) {
+        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);
+            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 };
+            }
+            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);
+            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
+         ) 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 = 'running',
+           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 = 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);
+            insertEventStrict(db, {
+                eventType: "workflow_unit_started",
+                ts: input.now,
+                ref: run.workflow_ref,
+                metadata: {
+                    runId: input.runId,
+                    stepId: input.stepId,
+                    unitId: input.unitId,
+                    attempt: attemptNumber,
+                    dispatchId,
+                    phase: input.phase,
+                    status: "running",
+                },
+            });
+            const attempt = db
+                .prepare(`SELECT * FROM workflow_run_unit_attempts
+            WHERE run_id = ? AND unit_id = ? AND attempt = ?`)
+                .get(input.runId, input.unitId, attemptNumber);
+            return { kind: "reserved", attempt };
+        });
+    }
+    /** Commit one CAS-valid v4 terminal result, known usage, and finish 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);
+            if (Number(changed.changes) !== 1)
+                return false;
+            const attempt = db
+                .prepare(`SELECT * FROM workflow_run_unit_attempts
+            WHERE run_id = ? AND unit_id = ? AND attempt = ?`)
+                .get(input.runId, input.unitId, input.attempt);
+            const projection = db
+                .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);
+            if (Number(projection.changes) !== 1) {
+                throw new Error(`Durable attempt ${input.unitId} has no matching live workflow_run_units projection.`);
+            }
+            const run = db.prepare("SELECT workflow_ref FROM workflow_runs WHERE id = ?").get(input.runId);
+            if (!run)
+                throw new Error(`Durable attempt ${input.unitId} has no owning workflow run.`);
+            insertEventStrict(db, {
+                eventType: "workflow_unit_finished",
+                ts: input.finishedAt,
+                ref: run.workflow_ref,
+                metadata: {
+                    runId: input.runId,
+                    stepId: attempt.step_id,
+                    unitId: input.unitId,
+                    attempt: input.attempt,
+                    dispatchId: input.dispatchId,
+                    phase: attempt.phase,
+                    status: input.status,
+                    ...(input.failureReason ? { failureReason: input.failureReason } : {}),
+                    ...(input.tokens !== null ? { tokens: input.tokens } : {}),
+                },
+            });
+            return true;
+        });
+    }
+    // ── current unit status projection ─────────────────────────────────────────
     //
     // Writes to `workflow_run_units` should go through the serialized writer
     // queue (`src/workflows/exec/unit-writer.ts`) when N units may complete
@@ -229,123 +441,10 @@ export class WorkflowRunsRepository {
             .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 for guarded read-then-write
-     * (idempotency / replay-divergence / claim checks). */
+    /** One unit row by primary key, or undefined. */
     getUnit(runId, unitId) {
         return this.db.prepare("SELECT * FROM workflow_run_units WHERE run_id = ? AND unit_id = ?").get(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 `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. Must be called
-     * inside a transaction that has ALREADY validated 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) {
-        const result = this.db
-            .prepare(`UPDATE workflow_run_units
-           SET status = 'running', last_checkin_at = ?, claim_holder = ?, claim_expires_at = ?
-           WHERE run_id = ? AND unit_id = ?
-             AND EXISTS (SELECT 1 FROM workflow_runs WHERE id = ? AND status = 'active')`)
-            .run(lastCheckinAt, holder, expiresAt, runId, unitId, runId);
-        return Number(result.changes) === 1;
-    }
-    /**
-     * 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.`);
-        }
-    }
-    /**
-     * Finish a unit row ONLY while it is still the exact row a specific dispatch
-     * inserted: `running`, with that dispatch's `started_at`. The native
-     * executor's guarded finish (single-driver invariant): a run stolen by
-     * another engine re-dispatches the unit through {@link insertUnit}, which
-     * REPLACES the row (fresh `started_at`, bumped `attempts`) — the stale
-     * driver's finish then matches NOTHING instead of clobbering the new
-     * driver's live dispatch. Returns whether the row was finished; a zero-row
-     * match is a caller-classified outcome here (the executor distinguishes
-     * "replaced by another driver" from "row vanished"), unlike
-     * {@link finishUnit}'s loud throw, whose callers guarantee their row exists.
-     */
-    finishUnitFromDispatch(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 = ? AND status = 'running' AND started_at = ?`)
-            .run(input.status, input.resultJson, input.tokens, input.failureReason, input.sessionId ?? null, input.finishedAt, input.runId, input.unitId, input.dispatchStartedAt);
-        return Number(result.changes) === 1;
-    }
 }
 /**
  * Run `fn` against a {@link WorkflowRunsRepository} bound to state.db