@cleocode/core 2026.9.23 → 2026.9.25

package/dist/store/sqlite-data-accessor.js

@@ -12,21 +12,26 @@
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { resolve } from 'node:path';
-import { ARCHIVE_REASON_TOMBSTONE, } from '@cleocode/contracts';
-import { and, eq, getTableColumns, inArray, isNull, like, ne, notInArray, or, sql, } from 'drizzle-orm';
+import { ARCHIVE_REASON_TOMBSTONE, ExitCode, } from '@cleocode/contracts';
+import { and, eq, getTableColumns, inArray, isNull, like, lte, ne, notInArray, or, sql, } from 'drizzle-orm';
+import { CleoError } from '../errors.js';
 import { captureProjectScope as captureTaskAccessorScope, getProjectRoot, worktreeScope, } from '../project-scope.js';
+import { acTextHash, buildAcRowId } from '../tasks/ac-table.js';
+import { generateAuditLogId, pruneAcBindingsForAcIds, pruneAcBindingsForTask, pruneOrphanAcBindings, selectOrphanAcBindings, } from './ac-binding-prune.js';
 import { withBackgroundOpCommitBoundary } from './background-ops.js';
 import { archivedTaskToRow, rowToSession, rowToTask, taskToRow } from './converters.js';
 import { cleanupBrainRefsOnSessionDelete } from './cross-db-cleanup.js';
-import { batchUpdateDependencies, loadDependenciesForTasks, loadRelationsForTasks, parseLabels, updateDependencies, updateTaskLabels, upsertSession, upsertTask, } from './db-helpers.js';
+import { batchUpdateDependencies, insertNewTask, loadDependenciesForTasks, loadRelationsForTasks, parseLabels, updateDependencies, updateTaskLabels, upsertSession, upsertTask, } from './db-helpers.js';
+import { registerRowIdentityWriters } from './row-identity.js';
 import { tasksAuditLog } from './schema/cleo-project/audit.js';
 import { resolveCurrentSession } from './session-store.js';
 import { closeDb, getDb, getNativeTasksDb } from './sqlite.js';
 import { TERMINAL_TASK_STATUSES } from './status-registry.js';
-import { assertTaskVersion, nextTaskVersion } from './task-version.js';
+import { claimAllows, claimColumnsOf, claimFromColumns, isClaimExpired, leaseExpiresAtFrom, taskClaimedError, taskClaimLeaseMs, } from './task-claim.js';
+import { nextTaskVersion, taskConflictError, taskVersion } from './task-version.js';
 import * as schema from './tasks-schema.js';
 import { assertTwinCollapseWritable, bareCounterOf, mirrorCounterToBare } from './twin-collapse.js';
-import { withWriteRetry } from './with-retry.js';
+import { runHeartbeatWrite, withWriteRetry } from './with-retry.js';
 /**
  * Per-process monotonic counter for unique nested SAVEPOINT names (T9814).
  * Only used when DataAccessor.transaction() is called from within an
@@ -35,13 +40,67 @@ import { withWriteRetry } from './with-retry.js';
  */
 let _txSavepointCounter = 0;
 /**
- * Generate a unique audit log entry ID.
- * @task T4837
+ * Evidence bindings for a set of CURRENT AC ids (T12341).
+ *
+ * A binding is matched through the criterion's uid (`ac_uid`), which survives
+ * an AC edit, and falls back to `ac_id` for a binding whose uid is not filled.
+ * A binding recorded against an older text of a criterion is reported under
+ * the criterion's current id, so callers keyed by AC id keep working, and is
+ * marked `stale` when the text hash it recorded (`ac_text_hash`) differs from
+ * the criterion's current text: evidence for different text never satisfies a
+ * gate (spec §8.2).
  */
-function generateAuditLogId() {
-    const epoch = Math.floor(Date.now() / 1000);
-    const rand = Math.random().toString(36).slice(2, 8);
-    return `log-${epoch}-${rand}`;
+async function selectAcBindings(db, acIds) {
+    if (acIds.length === 0)
+        return [];
+    const b = schema.evidenceAcBindings;
+    const ac = schema.taskAcceptanceCriteria;
+    const ids = acIds;
+    const columns = {
+        id: b.id,
+        evidenceAtomId: b.evidenceAtomId,
+        acId: b.acId,
+        currentAcId: ac.id,
+        currentAcText: ac.text,
+        recordedTextHash: b.acTextHash,
+        bindingType: b.bindingType,
+        createdAt: b.createdAt,
+    };
+    // Two indexed lookups rather than one OR across the join: by the current
+    // criterion's uid, then by the recorded ac_id.
+    const byUid = await db
+        .select(columns)
+        .from(b)
+        .innerJoin(ac, eq(ac.uid, b.acUid))
+        .where(inArray(ac.id, ids))
+        .all();
+    const byId = await db
+        .select(columns)
+        .from(b)
+        .leftJoin(ac, eq(ac.uid, b.acUid))
+        .where(inArray(b.acId, ids))
+        .all();
+    const rows = [...byUid, ...byId];
+    const wanted = new Set(ids);
+    const seen = new Set();
+    const out = [];
+    for (const r of rows) {
+        if (seen.has(r.id))
+            continue;
+        seen.add(r.id);
+        const stale = r.recordedTextHash !== null &&
+            r.currentAcText !== null &&
+            acTextHash(r.currentAcText) !== r.recordedTextHash;
+        out.push({
+            id: r.id,
+            evidenceAtomId: r.evidenceAtomId,
+            acId: r.currentAcId && wanted.has(r.currentAcId) ? r.currentAcId : r.acId,
+            bindingType: r.bindingType,
+            createdAt: r.createdAt,
+            ...(stale ? { stale: true } : {}),
+        });
+    }
+    return out;
 }
 // ---- Schema meta helpers ----
 /** Read a JSON blob from the schema_meta table by key. */
@@ -70,7 +129,7 @@ export async function setMetaValue(cwd, key, value) {
 async function writeMetaValue(cwd, key, value) {
     const db = await getDb(cwd);
     // T12535: fail fast on a store degraded by a failed twin collapse.
-    assertTwinCollapseWritable(getNativeTasksDb(cwd));
+    assertTwinCollapseWritable(getNativeTasksDb(cwd), 'schema_meta');
     const json = JSON.stringify(value);
     await db
         .insert(schema.schemaMeta)
@@ -105,7 +164,7 @@ async function writeMetaValue(cwd, key, value) {
  * @task T12535
  */
 export function advanceTaskIdSequence(nativeDb, floor) {
-    assertTwinCollapseWritable(nativeDb);
+    assertTwinCollapseWritable(nativeDb, 'schema_meta');
     // T12535: an id the older build reserved in the bare counter is taken too.
     const lowest = Math.max(floor, bareCounterOf(nativeDb, 'task_id_sequence'));
     nativeDb
@@ -130,6 +189,398 @@ export function advanceTaskIdSequence(nativeDb, floor) {
         .get();
     return row?.counter;
 }
+/**
+ * Give the task with `uid` the display id `toId`: a compare-and-set on the
+ * stored version AND claim lease that advances the version (so a stale
+ * `--if-match` writer fails, #1698), with the claim columns carried unchanged
+ * (#1701), then every local reference rewritten. Runs in the caller's
+ * transaction with foreign keys deferred to its commit.
+ *
+ * A collision re-mint is a system write: it passes no claim guard and never
+ * takes or drops a lease, but the version bump makes the lease holder's next
+ * guarded write re-read. A caller acting for a session (a manual rename)
+ * passes `guard`: `expectedUpdatedAt` fails with `E_CONFLICT` when the task
+ * moved on, `claim` fails with `E_TASK_CLAIMED` when another session holds it.
+ *
+ * @param nativeDb - The project `cleo.db` handle holding the transaction.
+ * @param uid - Uid of the task to rename.
+ * @param toId - Its new display id.
+ * @param refs - Columns that hold task display ids.
+ * @param guard - Optional version / claim guard.
+ * @returns The id it had and the rows rewritten per `table.column`.
+ * @task T12341
+ * @task T12748
+ */
+export function renameTaskDisplayIdNative(nativeDb, uid, toId, refs, guard = {}) {
+    const current = nativeDb
+        .prepare(`SELECT id, updated_at AS updatedAt, created_at AS createdAt,
+              claimed_by_session AS claimedBySession, claimed_by_agent AS claimedByAgent,
+              claimed_at AS claimedAt, lease_expires_at AS leaseExpiresAt
+         FROM tasks_tasks WHERE uid = ?`)
+        .get(uid);
+    if (!current)
+        throw new Error(`No task with uid ${uid}`);
+    if (guard.expectedUpdatedAt !== undefined && guard.expectedUpdatedAt !== taskVersion(current)) {
+        throw taskConflictError(current.id, guard.expectedUpdatedAt, current);
+    }
+    if (guard.claim)
+        assertClaimAllowed(current.id, current, guard.claim, []);
+    nativeDb.exec('PRAGMA defer_foreign_keys = ON');
+    const changed = nativeDb
+        .prepare(`UPDATE tasks_tasks SET id = ?, updated_at = ?
+        WHERE uid = ? AND id = ? AND updated_at IS ? AND claimed_by_session IS ?
+          AND lease_expires_at IS ?`)
+        .run(toId, nextTaskVersion(current), uid, current.id, current.updatedAt, current.claimedBySession, current.leaseExpiresAt).changes;
+    if (Number(changed) !== 1) {
+        throw taskConflictError(current.id, taskVersion(current), null);
+    }
+    const rewritten = {};
+    const q = (name) => `"${name.replaceAll('"', '""')}"`;
+    for (const ref of refs) {
+        const table = `main.${q(ref.table)}`;
+        const col = q(ref.column);
+        const n = ref.jsonArray
+            ? nativeDb
+                .prepare(`UPDATE ${table} SET ${col} = (
+               SELECT json_group_array(CASE WHEN j.value = ? THEN ? ELSE j.value END)
+                 FROM json_each(${table}.${col}) j)
+             WHERE json_valid(${col}) AND EXISTS (
+               SELECT 1 FROM json_each(${table}.${col}) j WHERE j.value = ?)`)
+                .run(current.id, toId, current.id).changes
+            : nativeDb.prepare(`UPDATE ${table} SET ${col} = ? WHERE ${col} = ?`).run(toId, current.id)
+                .changes;
+        if (Number(n) > 0)
+            rewritten[`${ref.table}.${ref.column}`] = Number(n);
+    }
+    for (const [key, n] of Object.entries(rederiveAcIdsNative(nativeDb, current.id, toId))) {
+        if (n > 0)
+            rewritten[key] = n;
+    }
+    return { fromId: current.id, rewritten };
+}
+/**
+ * After a task's display id changed from `fromId` to `toId`, re-derive the
+ * ids of the acceptance criteria derived from it (`buildAcRowId(taskId,
+ * identity)`): the task's own criteria, and a parent's child-projection
+ * criteria (`child:<id>`, whose source key is rewritten too). The binding and
+ * history rows that point at a re-derived id follow. A criterion whose id was
+ * not derived from the old id (an explicit id) keeps it. Without this, two
+ * tasks that once shared a display id keep identical ids for same-text
+ * criteria ("tests pass") and collide on every merge (T12799).
+ *
+ * @param nativeDb - The project `cleo.db` handle, inside the rename's transaction.
+ * @param fromId - The task's old display id.
+ * @param toId - Its new display id (the task row already carries it).
+ * @returns Rows rewritten per `table.column`.
+ * @task T12799
+ */
+export function rederiveAcIdsNative(nativeDb, fromId, toId) {
+    const count = {};
+    const bump = (key, n) => {
+        count[key] = (count[key] ?? 0) + Number(n);
+    };
+    const has = (table) => nativeDb
+        .prepare("SELECT 1 AS x FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(table) !== undefined;
+    if (!has('tasks_task_acceptance_criteria'))
+        return count;
+    const oldChild = `child:${fromId}`;
+    const rows = nativeDb
+        .prepare(`SELECT id, task_id AS taskId, kind, text, source_key AS sourceKey
+         FROM tasks_task_acceptance_criteria WHERE task_id = ? OR source_key = ?`)
+        .all(toId, oldChild);
+    const followers = ['tasks_evidence_ac_bindings', 'tasks_task_acceptance_criteria_history'].filter(has);
+    for (const row of rows) {
+        const ownerBefore = row.taskId === toId ? fromId : row.taskId;
+        const sourceAfter = row.sourceKey === oldChild ? `child:${toId}` : row.sourceKey;
+        const identity = (source) => (row.kind === 'text' ? row.text : (source ?? ''));
+        const derived = row.id === buildAcRowId(ownerBefore, identity(row.sourceKey));
+        const newId = derived ? buildAcRowId(row.taskId, identity(sourceAfter)) : row.id;
+        if (newId === row.id && sourceAfter === row.sourceKey)
+            continue;
+        bump('tasks_task_acceptance_criteria.id', nativeDb
+            .prepare('UPDATE tasks_task_acceptance_criteria SET id = ?, source_key = ? WHERE id = ?')
+            .run(newId, sourceAfter, row.id).changes);
+        if (newId === row.id)
+            continue;
+        for (const table of followers) {
+            bump(`${table}.ac_id`, nativeDb.prepare(`UPDATE ${table} SET ac_id = ? WHERE ac_id = ?`).run(newId, row.id)
+                .changes);
+        }
+    }
+    return count;
+}
+/**
+ * Insert a display-id alias row (idempotent on its uid).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param row - The alias.
+ * @task T12341
+ */
+export function insertDisplayIdAliasNative(nativeDb, row) {
+    nativeDb
+        .prepare(`INSERT OR IGNORE INTO tasks_display_id_aliases
+         (uid, entity_table, display_id, entity_uid, reason, origin, displaced_hlc, created_at,
+          entity_birth_fp)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(row.uid, row.entityTable, row.displayId, row.entityUid, row.reason, row.origin, row.displacedHlc, row.createdAt, row.entityBirthFp);
+}
+/**
+ * Delete one display-id alias row (a local alias whose entity was re-keyed is
+ * re-inserted under its new entity uid by the caller).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param uid - The alias row's uid.
+ * @task T12341
+ */
+export function deleteDisplayIdAliasNative(nativeDb, uid) {
+    nativeDb.prepare('DELETE FROM tasks_display_id_aliases WHERE uid = ?').run(uid);
+}
+/**
+ * Insert a uid re-key alias row (idempotent on its uid).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param row - The alias.
+ * @task T12341
+ */
+export function insertUidAliasNative(nativeDb, row) {
+    nativeDb
+        .prepare(`INSERT OR IGNORE INTO tasks_uid_aliases
+         (uid, entity_table, old_uid, old_birth_fp, new_uid, origin, displaced_hlc, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(row.uid, row.entityTable, row.oldUid, row.oldBirthFp, row.newUid, row.origin, row.displacedHlc, row.createdAt);
+}
+/**
+ * Hold an incoming row the merge cannot place yet (replacing an older hold of
+ * the same row).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param row - The held row.
+ * @task T12341
+ */
+export function insertQuarantineNative(nativeDb, row) {
+    nativeDb
+        .prepare(`INSERT INTO tasks_identity_quarantine
+         (entity_table, uid, birth_fp, reason, contested_id, row_json, received_hlc, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(entity_table, uid, birth_fp) DO UPDATE SET
+         reason = excluded.reason, contested_id = excluded.contested_id,
+         row_json = excluded.row_json, received_hlc = excluded.received_hlc,
+         created_at = excluded.created_at`)
+        .run(row.entityTable, row.uid, row.birthFp, row.reason, row.contestedId, row.rowJson, row.receivedHlc, row.createdAt);
+}
+/**
+ * Drop a held row (released or superseded).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param key - The held row's table, uid and birth fingerprint.
+ * @task T12341
+ */
+export function deleteQuarantineNative(nativeDb, key) {
+    nativeDb
+        .prepare('DELETE FROM tasks_identity_quarantine WHERE entity_table = ? AND uid = ? AND birth_fp = ?')
+        .run(key.entityTable, key.uid, key.birthFp);
+}
+/**
+ * Write a row-identity meta value (the recipe marker, a re-mint record).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param key - Meta key.
+ * @param value - Meta value.
+ * @task T12341
+ */
+export function writeRowIdentityMetaNative(nativeDb, key, value) {
+    nativeDb
+        .prepare(`INSERT INTO tasks_row_identity_meta (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
+        .run(key, value);
+}
+/**
+ * Hand a criterion back the uid its deleted predecessor carried (AC uid
+ * graveyard re-link, spec §6.5), with that predecessor's birth fingerprint.
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param acId - The criterion to re-link (its uid is NULL).
+ * @param uid - The uid to hand back.
+ * @param birthFp - The fingerprint that goes with it, when recorded.
+ * @returns Rows changed (0 or 1).
+ * @task T12341
+ */
+export function relinkAcUidNative(nativeDb, acId, uid, birthFp) {
+    return Number(nativeDb
+        .prepare('UPDATE tasks_task_acceptance_criteria SET uid = ?, birth_fp = COALESCE(?, birth_fp) WHERE id = ? AND uid IS NULL')
+        .run(uid, birthFp, acId).changes);
+}
+/**
+ * Empty the AC uid graveyard (after the open pass consumed it).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @task T12341
+ */
+export function clearAcUidGraveyardNative(nativeDb) {
+    nativeDb.exec('DELETE FROM tasks_ac_uid_graveyard');
+}
+/** Quote an identifier for the dynamic row-identity writes below. */
+function quoteIdent(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/**
+ * Fill a NULL identity column (`uid`, `birth_fp`, a stored reference uid) of a
+ * declared table from its recipe SQL (the row-uid open pass, spec §6.1).
+ *
+ * @param nativeDb - The `cleo.db` handle holding the cold-open lease.
+ * @param table - Declared table.
+ * @param column - Identity column.
+ * @param valueSql - Recipe expression over `main."<table>"` columns.
+ * @param rowid - One row only (the clash fallback); all NULL rows otherwise.
+ * @returns Rows written.
+ * @task T12341
+ */
+export function fillIdentityColumnNative(nativeDb, table, column, valueSql, rowid) {
+    const col = quoteIdent(column);
+    const sql = `UPDATE main.${quoteIdent(table)} SET ${col} = ${valueSql} WHERE ${col} IS NULL`;
+    const changes = rowid === undefined
+        ? nativeDb.prepare(sql).run().changes
+        : nativeDb.prepare(`${sql} AND rowid = ?`).run(rowid).changes;
+    return Number(changes);
+}
+/**
+ * Clear one pre-release birth fingerprint so the fill re-derives it (spec §12.1).
+ *
+ * @param nativeDb - The `cleo.db` handle holding the cold-open lease.
+ * @param table - Declared minted table.
+ * @param rowid - The row.
+ * @task T12341
+ */
+export function clearBirthFpNative(nativeDb, table, rowid) {
+    nativeDb
+        .prepare(`UPDATE main.${quoteIdent(table)} SET birth_fp = NULL WHERE rowid = ?`)
+        .run(rowid);
+}
+/**
+ * Insert one row into a declared identity table, with the columns the row
+ * carries that the table has (a row released from the identity quarantine).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Declared table.
+ * @param row - Column → value.
+ * @task T12341
+ */
+export function insertIdentityRowNative(nativeDb, table, row) {
+    const have = new Set(nativeDb.prepare('SELECT name FROM pragma_table_info(?)').all(table).map((c) => c.name));
+    const cols = Object.keys(row).filter((c) => have.has(c));
+    nativeDb
+        .prepare(`INSERT INTO main.${quoteIdent(table)} (${cols.map(quoteIdent).join(', ')}) VALUES (${cols
+        .map(() => '?')
+        .join(', ')})`)
+        .run(...cols.map((c) => row[c] ?? null));
+}
+/**
+ * Give the row of `table` identified by (`oldUid`, `birthFp`) the uid
+ * `newUid` (a uid re-key; the birth fingerprint never changes).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Declared minted table.
+ * @param oldUid - The colliding uid.
+ * @param birthFp - The row's birth fingerprint.
+ * @param newUid - Its new uid.
+ * @returns Rows changed (0 or 1).
+ * @task T12341
+ */
+export function setRowUidNative(nativeDb, table, oldUid, birthFp, newUid) {
+    return Number(nativeDb
+        .prepare(`UPDATE main.${quoteIdent(table)} SET uid = ? WHERE uid = ? AND birth_fp = ?`)
+        .run(newUid, oldUid, birthFp).changes);
+}
+/**
+ * Point a stored reference uid column (`ac_uid`) of the rows that reference
+ * the re-keyed row by key at its new uid. Scoped by the key column, so a row
+ * referencing the OTHER holder of a colliding uid is never touched.
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Table holding the column.
+ * @param column - The stored reference uid column.
+ * @param fromColumn - The column that references the row by key (`ac_id`).
+ * @param key - The re-keyed row's local key.
+ * @param oldUid - Old referenced uid.
+ * @param newUid - New referenced uid.
+ * @returns Rows changed.
+ * @task T12341
+ */
+export function rewriteStoredRefUidNative(nativeDb, table, column, fromColumn, key, oldUid, newUid) {
+    const col = quoteIdent(column);
+    return Number(nativeDb
+        .prepare(`UPDATE main.${quoteIdent(table)} SET ${col} = ? WHERE ${col} = ? AND ${quoteIdent(fromColumn)} = ?`)
+        .run(newUid, oldUid, key).changes);
+}
+/**
+ * Clear one row's uid so the natural recipe re-derives it (a uid re-key
+ * changed an endpoint's uid).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Declared natural table.
+ * @param rowid - The row.
+ * @task T12341
+ */
+export function clearRowUidNative(nativeDb, table, rowid) {
+    nativeDb.prepare(`UPDATE main.${quoteIdent(table)} SET uid = NULL WHERE rowid = ?`).run(rowid);
+}
+/**
+ * Delete a row-identity meta value (a re-mint record that moved with a re-key).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param key - Meta key.
+ * @task T12341
+ */
+export function deleteRowIdentityMetaNative(nativeDb, key) {
+    nativeDb.prepare('DELETE FROM tasks_row_identity_meta WHERE key = ?').run(key);
+}
+/**
+ * Set a natural row's uid by its current uid (a re-key re-derives the natural
+ * uids keyed by the re-keyed row; a receiver applies the published values).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param table - Declared natural table.
+ * @param oldUid - Current uid.
+ * @param newUid - New uid.
+ * @returns Rows changed.
+ * @task T12341
+ */
+export function setNaturalUidNative(nativeDb, table, oldUid, newUid) {
+    return Number(nativeDb
+        .prepare(`UPDATE main.${quoteIdent(table)} SET uid = ? WHERE uid = ?`)
+        .run(newUid, oldUid).changes);
+}
+/**
+ * Rewrite a held row (identity quarantine) under a new uid: a uid re-key of a
+ * row this replica holds but has not placed.
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param key - The held row's table, uid and birth fingerprint.
+ * @param newUid - Its new uid.
+ * @param rowJson - Its wire form with the new uid.
+ * @task T12341
+ */
+export function rekeyQuarantineNative(nativeDb, key, newUid, rowJson) {
+    nativeDb
+        .prepare(`UPDATE tasks_identity_quarantine SET uid = ?, row_json = ?
+        WHERE entity_table = ? AND uid = ? AND birth_fp = ?`)
+        .run(newUid, rowJson, key.entityTable, key.uid, key.birthFp);
+}
+/**
+ * Add labels to a task's label junction (idempotent), for writers that
+ * insert a task with raw SQL (the sentient proposal ticks).
+ *
+ * @param nativeDb - The project `cleo.db` handle.
+ * @param taskId - The task.
+ * @param labels - Labels to add.
+ * @task T12341
+ */
+export function addTaskLabelsNative(nativeDb, taskId, labels) {
+    const stmt = nativeDb.prepare('INSERT OR IGNORE INTO tasks_task_labels (task_id, label) VALUES (?, ?)');
+    for (const label of labels)
+        stmt.run(taskId, label);
+}
 // One queue per shared native handle, independent of accessor identity. These
 // hold coordination state only; the ProjectStore remains the owner of handles.
 const taskTransactionQueue = new WeakMap();
@@ -189,6 +640,87 @@ async function scheduleTaskBackground(native, work) {
  * ```
  */
 export { captureProjectScope as captureTaskAccessorScope } from '../project-scope.js';
+/** The claim lease columns, selected alongside a row's version (T12502). */
+const CLAIM_COLUMNS = {
+    claimedBySession: schema.tasks.claimedBySession,
+    claimedByAgent: schema.tasks.claimedByAgent,
+    claimedAt: schema.tasks.claimedAt,
+    leaseExpiresAt: schema.tasks.leaseExpiresAt,
+};
+/**
+ * The claim compare-and-set predicate for an UPDATE's WHERE clause (T12502).
+ * The SQL mirror of `claimAllows`; `force` adds no predicate.
+ *
+ * @param guard - The claim guard.
+ * @param allowedHolders - Holders `acquire` / `take-over` may replace even
+ *   while live (hand-off source, spawn-edge parent and children).
+ */
+function claimPredicate(guard, allowedHolders) {
+    const holder = schema.tasks.claimedBySession;
+    if (guard.mode === 'force')
+        return undefined;
+    const mine = guard.sessionId === null ? undefined : eq(holder, guard.sessionId);
+    if (guard.mode === 'renew' || guard.mode === 'release')
+        return mine ?? sql `0`;
+    const related = allowedHolders.length > 0 ? inArray(holder, [...allowedHolders]) : undefined;
+    const expired = guard.mode === 'take-over'
+        ? or(isNull(schema.tasks.leaseExpiresAt), lte(schema.tasks.leaseExpiresAt, guard.now))
+        : undefined;
+    return or(isNull(holder), mine, related, expired);
+}
+/** Throw `E_TASK_CLAIMED` when the stored holder refuses this claim write. */
+function assertClaimAllowed(taskId, row, guard, allowedHolders) {
+    const stored = claimFromColumns(row);
+    if (claimAllows(stored, guard.mode, guard.sessionId, guard.now, allowedHolders))
+        return;
+    if (!stored) {
+        throw new CleoError(ExitCode.NOT_FOUND, `Task ${taskId} has no claim held by session ${guard.sessionId ?? '(unbound)'} to ${guard.mode}`, { fix: `Take the claim first: cleo claim ${taskId}` });
+    }
+    throw taskClaimedError(taskId, stored, { sessionId: guard.sessionId, agentId: null }, guard.now);
+}
+/**
+ * The holders an `acquire` / `take-over` claim write may replace even while
+ * their lease is live (T12502): the explicit hand-off source, plus the
+ * caller's claim family — the session that spawned it and the sessions it
+ * spawned (`tasks_sessions.spawned_by_session_id`, written only by the spawn
+ * itself). The self-declared `parent_session_id` (from
+ * `CLEO_PARENT_SESSION_ID` at `session start`) is NOT trusted here: any
+ * process can name any parent, so honouring it would let a forged child take
+ * a live lease silently. A spawned worker whose calls
+ * resolve to its orchestrator's session, or an orchestrator taking a task
+ * back from its own worker, is a hand-off, not a conflict.
+ *
+ * @param db - The project DB handle (inside the write transaction).
+ * @param guard - The claim guard.
+ * @returns Distinct session ids other than the caller's.
+ */
+async function claimAllowedHolders(db, guard) {
+    if (guard.mode !== 'acquire' && guard.mode !== 'take-over')
+        return [];
+    const holders = new Set();
+    if (guard.handoffFrom)
+        holders.add(guard.handoffFrom);
+    const sessionId = guard.sessionId;
+    if (sessionId) {
+        const [self] = await db
+            .select({ parent: schema.sessions.spawnedBySessionId })
+            .from(schema.sessions)
+            .where(eq(schema.sessions.id, sessionId))
+            .limit(1)
+            .all();
+        if (self?.parent)
+            holders.add(self.parent);
+        const children = await db
+            .select({ id: schema.sessions.id })
+            .from(schema.sessions)
+            .where(eq(schema.sessions.spawnedBySessionId, sessionId))
+            .all();
+        for (const child of children)
+            holders.add(child.id);
+        holders.delete(sessionId);
+    }
+    return [...holders];
+}
 /**
  * Bind all asynchronous accessor methods, including transaction ports, to one project.
  * @typeParam T - Concrete accessor contract retained by the scoped wrapper.
@@ -445,6 +977,9 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
         async upsertSingleTask(task) {
             await accessor.transaction((tx) => tx.upsertSingleTask(task));
         },
+        async insertNewTask(task) {
+            await accessor.transaction((tx) => tx.insertNewTask(task));
+        },
         async addRelation(taskId, relatedTo, relationType, reason) {
             return accessor.transaction(async () => {
                 const db = await getDb(cwd);
@@ -521,6 +1056,8 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                 createdAt: schema.taskAcceptanceCriteria.createdAt,
                 updatedAt: schema.taskAcceptanceCriteria.updatedAt,
                 contentHash: schema.taskAcceptanceCriteria.contentHash,
+                uid: schema.taskAcceptanceCriteria.uid,
+                birthFp: schema.taskAcceptanceCriteria.birthFp,
             })
                 .from(schema.taskAcceptanceCriteria)
                 .where(eq(schema.taskAcceptanceCriteria.taskId, taskId))
@@ -538,31 +1075,20 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                 createdAt: r.createdAt,
                 updatedAt: r.updatedAt ?? null,
                 contentHash: r.contentHash ?? null,
+                uid: r.uid ?? null,
+                birthFp: r.birthFp ?? null,
             }));
         },
         // ---- AC bindings (T10509 — AC-coverage gate) ----
         async getAcBindings(acIds) {
             if (acIds.length === 0)
                 return [];
+            return selectAcBindings(await getDb(cwd), acIds);
+        },
+        // ---- AC bindings — orphan scan (T12790) ----
+        async findOrphanAcBindings() {
             const db = await getDb(cwd);
-            const rows = await db
-                .select({
-                id: schema.evidenceAcBindings.id,
-                evidenceAtomId: schema.evidenceAcBindings.evidenceAtomId,
-                acId: schema.evidenceAcBindings.acId,
-                bindingType: schema.evidenceAcBindings.bindingType,
-                createdAt: schema.evidenceAcBindings.createdAt,
-            })
-                .from(schema.evidenceAcBindings)
-                .where(inArray(schema.evidenceAcBindings.acId, acIds))
-                .all();
-            return rows.map((r) => ({
-                id: r.id,
-                evidenceAtomId: r.evidenceAtomId,
-                acId: r.acId,
-                bindingType: r.bindingType,
-                createdAt: r.createdAt,
-            }));
+            return selectOrphanAcBindings(db);
         },
         async archiveSingleTask(taskId, fields) {
             return accessor.transaction(async () => {
@@ -606,6 +1132,9 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                         .delete(schema.taskDependencies)
                         .where(eq(schema.taskDependencies.dependsOn, taskId))
                         .run();
+                    // T12790: the bindings table has no FK to the AC rows that cascade
+                    // from tasks_tasks — remove (and audit) them explicitly.
+                    await pruneAcBindingsForTask(db, taskId);
                     // Delete the task itself
                     await db.delete(schema.tasks).where(eq(schema.tasks.id, taskId)).run();
                 });
@@ -1018,24 +1547,54 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                 // E_CONFLICT, and advance the version strictly so a same-millisecond
                 // write can never reproduce a version a stale reader already holds.
                 const [current] = await db
-                    .select({ updatedAt: schema.tasks.updatedAt, createdAt: schema.tasks.createdAt })
+                    .select({
+                    updatedAt: schema.tasks.updatedAt,
+                    createdAt: schema.tasks.createdAt,
+                    ...CLAIM_COLUMNS,
+                })
                     .from(schema.tasks)
                     .where(eq(schema.tasks.id, taskId))
                     .limit(1)
                     .all();
                 if (!current)
                     throw new Error(`Task not found: ${taskId}`);
-                assertTaskVersion(taskId, current, guard?.expectedUpdatedAt);
+                // T12502: refuse a claim write the stored holder does not allow before
+                // touching anything, with the holder named. The WHERE clause below
+                // repeats the predicate, so the write itself is the compare-and-set.
+                const claimGuard = guard?.claim;
+                const allowedHolders = claimGuard ? await claimAllowedHolders(db, claimGuard) : [];
+                if (claimGuard)
+                    assertClaimAllowed(taskId, current, claimGuard, allowedHolders);
+                const expected = guard?.expectedUpdatedAt;
+                if (expected !== undefined && taskVersion(current) !== expected) {
+                    throw taskConflictError(taskId, expected, (await accessor.loadSingleTask(taskId)) ?? current, guard?.baseline);
+                }
                 const updateRow = {
                     ...fields,
-                    updatedAt: fields.updatedAt ?? nextTaskVersion(current),
+                    updatedAt: fields.updatedAt ?? (guard?.keepVersion ? current.updatedAt : nextTaskVersion(current)),
                 };
+                // T12503: a guarded write is a compare-and-set in SQL — the UPDATE
+                // matches only while the stored version is still the expected one, so
+                // the check and the write are one statement, not a read-then-write.
+                const versionMatch = expected === undefined
+                    ? undefined
+                    : current.updatedAt === null
+                        ? isNull(schema.tasks.updatedAt)
+                        : eq(schema.tasks.updatedAt, current.updatedAt);
+                const where = and(eq(schema.tasks.id, taskId), versionMatch, claimGuard ? claimPredicate(claimGuard, allowedHolders) : undefined);
                 // gh#391: this is the chokepoint for `cleo update <id> --add-labels`.
                 // Parallel invocations from a single shell used to lose ~50% of writes
                 // to SQLITE_BUSY; withWriteRetry recovers them.
-                const result = await withWriteRetry(() => db.update(schema.tasks).set(updateRow).where(eq(schema.tasks.id, taskId)).run());
-                if (Number(result.changes) !== 1)
-                    throw new Error(`Task not found: ${taskId}`);
+                const result = await withWriteRetry(() => db.update(schema.tasks).set(updateRow).where(where).run());
+                if (Number(result.changes) !== 1) {
+                    const stored = await accessor.loadSingleTask(taskId);
+                    if (!stored)
+                        throw new Error(`Task not found: ${taskId}`);
+                    if (claimGuard) {
+                        assertClaimAllowed(taskId, claimColumnsOf(stored.claim), claimGuard, allowedHolders);
+                    }
+                    throw taskConflictError(taskId, expected ?? taskVersion(current), stored, guard?.baseline);
+                }
                 if (fields.labelsJson !== undefined) {
                     await updateTaskLabels(db, taskId, parseLabels(fields.labelsJson));
                 }
@@ -1089,6 +1648,14 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                         await updateDependencies(db, task.id, task.depends ?? []);
                                     });
                                 },
+                                async insertNewTask(task) {
+                                    scope.assertActive();
+                                    return accessor.transaction(async () => {
+                                        scope.assertActive();
+                                        await insertNewTask(db, taskToRow(task));
+                                        await updateDependencies(db, task.id, task.depends ?? []);
+                                    });
+                                },
                                 async archiveSingleTask(taskId, fields) {
                                     scope.assertActive();
                                     return accessor.transaction(async () => {
@@ -1118,6 +1685,8 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             .delete(schema.taskDependencies)
                                             .where(eq(schema.taskDependencies.dependsOn, taskId))
                                             .run();
+                                        // T12790: bindings of the cascading AC rows (no FK).
+                                        await pruneAcBindingsForTask(db, taskId);
                                         await db.delete(schema.tasks).where(eq(schema.tasks.id, taskId)).run();
                                     });
                                 },
@@ -1197,6 +1766,9 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             projection: r.projection ?? 'legacy',
                                             text: r.text,
                                             contentHash: r.contentHash ?? null,
+                                            // A kept criterion keeps its uid (T12341); else one is minted.
+                                            ...(r.uid ? { uid: r.uid } : {}),
+                                            ...(r.uid && r.birthFp ? { birthFp: r.birthFp } : {}),
                                         })))
                                             .run();
                                     });
@@ -1216,6 +1788,8 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                         createdAt: schema.taskAcceptanceCriteria.createdAt,
                                         updatedAt: schema.taskAcceptanceCriteria.updatedAt,
                                         contentHash: schema.taskAcceptanceCriteria.contentHash,
+                                        uid: schema.taskAcceptanceCriteria.uid,
+                                        birthFp: schema.taskAcceptanceCriteria.birthFp,
                                     })
                                         .from(schema.taskAcceptanceCriteria)
                                         .where(eq(schema.taskAcceptanceCriteria.taskId, taskId))
@@ -1233,18 +1807,70 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                         createdAt: r.createdAt,
                                         updatedAt: r.updatedAt ?? null,
                                         contentHash: r.contentHash ?? null,
+                                        uid: r.uid ?? null,
+                                        birthFp: r.birthFp ?? null,
                                     }));
                                 },
                                 async deleteAcRowsForTask(taskId) {
                                     scope.assertActive();
                                     return accessor.transaction(async () => {
                                         scope.assertActive();
+                                        // T12790: remove (and audit) the departing rows' bindings.
+                                        await pruneAcBindingsForTask(db, taskId, 'ac-removed');
                                         await db
                                             .delete(schema.taskAcceptanceCriteria)
                                             .where(eq(schema.taskAcceptanceCriteria.taskId, taskId))
                                             .run();
                                     });
                                 },
+                                async deleteAcRowsByIds(taskId, ids, keepBindingsForUids = []) {
+                                    scope.assertActive();
+                                    if (ids.length === 0)
+                                        return;
+                                    return accessor.transaction(async () => {
+                                        scope.assertActive();
+                                        // T12790: only ids this task actually owns leave the set —
+                                        // prune (and audit) exactly their bindings.
+                                        const owned = await db
+                                            .select({ id: schema.taskAcceptanceCriteria.id })
+                                            .from(schema.taskAcceptanceCriteria)
+                                            .where(and(eq(schema.taskAcceptanceCriteria.taskId, taskId), inArray(schema.taskAcceptanceCriteria.id, ids)))
+                                            .all();
+                                        await pruneAcBindingsForAcIds(db, taskId, owned.map((r) => r.id), 'ac-removed', keepBindingsForUids);
+                                        await db
+                                            .delete(schema.taskAcceptanceCriteria)
+                                            .where(and(eq(schema.taskAcceptanceCriteria.taskId, taskId), inArray(schema.taskAcceptanceCriteria.id, ids)))
+                                            .run();
+                                    });
+                                },
+                                async updateAcRows(rows) {
+                                    scope.assertActive();
+                                    if (rows.length === 0)
+                                        return;
+                                    return accessor.transaction(async () => {
+                                        scope.assertActive();
+                                        const updatedAt = new Date().toISOString();
+                                        for (const r of rows) {
+                                            const result = await db
+                                                .update(schema.taskAcceptanceCriteria)
+                                                .set({
+                                                ordinal: r.ordinal,
+                                                kind: r.kind ?? 'text',
+                                                sourceKey: r.sourceKey ?? `text:${r.ordinal}`,
+                                                targetTaskId: r.targetTaskId ?? null,
+                                                projection: r.projection ?? 'legacy',
+                                                text: r.text,
+                                                contentHash: r.contentHash ?? null,
+                                                updatedAt,
+                                            })
+                                                .where(and(eq(schema.taskAcceptanceCriteria.id, r.id), eq(schema.taskAcceptanceCriteria.taskId, r.taskId)))
+                                                .run();
+                                            if (Number(result.changes) === 0) {
+                                                throw new CleoError(ExitCode.VALIDATION_ERROR, `Acceptance criterion ${r.id} does not exist on task ${r.taskId}; refusing to update it`);
+                                            }
+                                        }
+                                    });
+                                },
                                 async appendAcHistory(rows) {
                                     scope.assertActive();
                                     return accessor.transaction(async () => {
@@ -1257,6 +1883,7 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             acId: r.acId,
                                             previousText: r.previousText,
                                             reason: r.reason,
+                                            ...(r.acUid ? { acUid: r.acUid } : {}),
                                         })))
                                             .run();
                                     });
@@ -1264,26 +1891,7 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                 // ---- AC bindings (T10509 — AC-coverage gate) ----
                                 async getAcBindings(acIds) {
                                     scope.assertActive();
-                                    if (acIds.length === 0)
-                                        return [];
-                                    const out = await db
-                                        .select({
-                                        id: schema.evidenceAcBindings.id,
-                                        evidenceAtomId: schema.evidenceAcBindings.evidenceAtomId,
-                                        acId: schema.evidenceAcBindings.acId,
-                                        bindingType: schema.evidenceAcBindings.bindingType,
-                                        createdAt: schema.evidenceAcBindings.createdAt,
-                                    })
-                                        .from(schema.evidenceAcBindings)
-                                        .where(inArray(schema.evidenceAcBindings.acId, acIds))
-                                        .all();
-                                    return out.map((r) => ({
-                                        id: r.id,
-                                        evidenceAtomId: r.evidenceAtomId,
-                                        acId: r.acId,
-                                        bindingType: r.bindingType,
-                                        createdAt: r.createdAt,
-                                    }));
+                                    return selectAcBindings(db, acIds);
                                 },
                                 // ---- AC bindings — writer (T10511, Validator SDK tools) ----
                                 async insertAcBindings(rows) {
@@ -1312,6 +1920,14 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                                             .run();
                                     });
                                 },
+                                // ---- AC bindings — orphan repair (T12790) ----
+                                async pruneOrphanAcBindings() {
+                                    scope.assertActive();
+                                    return accessor.transaction(async () => {
+                                        scope.assertActive();
+                                        return pruneOrphanAcBindings(db);
+                                    });
+                                },
                             };
                             const result = await fn(bindTaskAccessorScope(tx, accessorScope));
                             await scope.pending;
@@ -1378,52 +1994,134 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
             const { getAgentInstance: getAgent } = await import('../agents/registry.js');
             return getAgent(agentId, cwd);
         },
-        // ---- Agent task claiming ----
-        async claimTask(taskId, agentId) {
+        // ---- Agent task claiming (leased, T12502) ----
+        async claimTask(taskId, request) {
+            const now = request.now ?? new Date().toISOString();
+            const guard = {
+                sessionId: request.sessionId,
+                mode: request.mode,
+                now,
+                handoffFrom: request.handoffFrom ?? null,
+            };
             return accessor.transaction(async () => {
-                const nativeDb = await requireNativeDb();
-                if (!nativeDb) {
-                    throw new Error('Native database not initialized');
-                }
-                // Verify the task exists first
-                const existsRow = nativeDb
-                    .prepare('SELECT assignee FROM tasks_tasks WHERE id = ?')
-                    .get(taskId);
-                if (!existsRow) {
+                const task = await accessor.loadSingleTask(taskId);
+                if (!task)
                     throw new Error(`Task not found: ${taskId}`);
+                const before = task.claim;
+                if (request.sessionId === null) {
+                    // An override names who takes the task; an unbound caller has no
+                    // session to record, so it is refused rather than silently ignored.
+                    if (request.mode === 'take-over' || request.mode === 'force') {
+                        const flag = request.mode === 'force' ? '--force-claim' : '--take-over';
+                        throw new CleoError(ExitCode.SESSION_UNBOUND, `Cannot ${flag} task ${taskId}: this caller is not bound to a session, so there is no session to hand the claim to.`, {
+                            fix: `Bind a session first (cleo session start --scope global --name "<work>", cleo session resume <id>, or export CLEO_SESSION_ID=<id>), then retry with ${flag}.`,
+                        });
+                    }
+                    // An unbound caller holds no lease; the guarded no-op write still
+                    // proves, under the write lock, that no other session holds it.
+                    await accessor.updateTaskFields(taskId, {}, { claim: guard, keepVersion: true });
+                    return null;
                 }
-                // Atomic claim: only succeeds if assignee IS NULL or already claimed by this agent.
-                // This prevents race conditions between concurrent agents.
-                const result = nativeDb
-                    .prepare('UPDATE tasks_tasks SET assignee = ?, updated_at = ? WHERE id = ? AND (assignee IS NULL OR assignee = ?)')
-                    .run(agentId, new Date().toISOString(), taskId, agentId);
-                if (result.changes === 0) {
-                    // Row was not updated — task is claimed by a different agent
-                    const currentRow = nativeDb
-                        .prepare('SELECT assignee FROM tasks_tasks WHERE id = ?')
-                        .get(taskId);
-                    throw new Error(`Task ${taskId} is already claimed by agent: ${currentRow?.assignee ?? 'unknown'}`);
+                const renewing = before?.sessionId === request.sessionId;
+                const lease = {
+                    sessionId: request.sessionId,
+                    agentId: request.agentId ?? (renewing ? (before?.agentId ?? null) : null),
+                    claimedAt: renewing && before ? before.claimedAt : now,
+                    leaseExpiresAt: leaseExpiresAtFrom(now, request.leaseMs ?? taskClaimLeaseMs()),
+                };
+                await accessor.updateTaskFields(taskId, {
+                    claimedBySession: lease.sessionId,
+                    claimedByAgent: lease.agentId,
+                    claimedAt: lease.claimedAt,
+                    leaseExpiresAt: lease.leaseExpiresAt,
+                }, 
+                // Renewing one's own lease is bookkeeping, not an edit: it must not
+                // move the version another writer holds for --if-match.
+                { claim: guard, keepVersion: renewing });
+                const replaced = before && before.sessionId !== request.sessionId ? before : undefined;
+                if (replaced) {
+                    // A write the predicate allowed over a LIVE lease without `force` is
+                    // a claim-family hand-off (spawn source, spawn-edge parent or child).
+                    const handoff = request.mode !== 'force' && !isClaimExpired(replaced, now);
+                    await accessor.appendLog({
+                        action: handoff
+                            ? 'task_claim_handoff'
+                            : request.mode === 'force'
+                                ? 'task_claim_force'
+                                : 'task_claim_takeover',
+                        taskId,
+                        actor: request.agentId ?? request.sessionId,
+                        sessionId: request.sessionId,
+                        timestamp: now,
+                        details: {
+                            mode: request.mode,
+                            leaseExpired: replaced.leaseExpiresAt <= now,
+                        },
+                        before: replaced,
+                        after: lease,
+                    });
                 }
+                return lease;
             });
         },
-        async unclaimTask(taskId) {
+        async unclaimTask(taskId, release) {
+            const now = new Date().toISOString();
             return accessor.transaction(async () => {
-                const nativeDb = await requireNativeDb();
-                if (!nativeDb) {
-                    throw new Error('Native database not initialized');
-                }
-                // Verify the task exists
-                const existsRow = nativeDb.prepare('SELECT id FROM tasks_tasks WHERE id = ?').get(taskId);
-                if (!existsRow) {
+                const task = await accessor.loadSingleTask(taskId);
+                if (!task)
                     throw new Error(`Task not found: ${taskId}`);
+                const held = task.claim;
+                if (!held)
+                    return false;
+                await accessor.updateTaskFields(taskId, { claimedBySession: null, claimedByAgent: null, claimedAt: null, leaseExpiresAt: null }, {
+                    claim: { sessionId: release.sessionId, mode: release.force ? 'force' : 'release', now },
+                    keepVersion: true,
+                });
+                if (held.sessionId !== release.sessionId) {
+                    await accessor.appendLog({
+                        action: 'task_claim_force_release',
+                        taskId,
+                        actor: release.sessionId ?? 'unbound',
+                        sessionId: release.sessionId,
+                        timestamp: now,
+                        details: { mode: 'force', leaseExpired: held.leaseExpiresAt <= now },
+                        before: held,
+                    });
                 }
-                // Clear the assignee — no-op if already null
-                nativeDb
-                    .prepare('UPDATE tasks_tasks SET assignee = NULL, updated_at = ? WHERE id = ?')
-                    .run(new Date().toISOString(), taskId);
+                return true;
             });
         },
+        async renewSessionClaims(sessionId, leaseExpiresAt) {
+            // The heartbeat follows EVERY mutation of a bound session, and almost no
+            // session holds a lease. Probe the claimed_by_session index first and
+            // write only when there is a lease to extend, so the common case costs
+            // one indexed read and no lock.
+            const db = await getDb(cwd);
+            const [held] = await db
+                .select({ id: schema.tasks.id })
+                .from(schema.tasks)
+                .where(eq(schema.tasks.claimedBySession, sessionId))
+                .limit(1)
+                .all();
+            if (!held)
+                return 0;
+            // Bounded lock wait, skipped on SQLITE_BUSY or inside another caller's
+            // transaction — see runHeartbeatWrite. The next mutation renews.
+            return (runHeartbeatWrite(db, getNativeTasksDb(cwd), () => Number(db
+                .update(schema.tasks)
+                .set({ leaseExpiresAt })
+                .where(eq(schema.tasks.claimedBySession, sessionId))
+                .run().changes)) ?? 0);
+        },
     };
     return accessor;
 }
+// T12341: the row-identity open pass writes through these chokepoint helpers.
+registerRowIdentityWriters({
+    relinkAcUidNative,
+    clearAcUidGraveyardNative,
+    writeRowIdentityMetaNative,
+    fillIdentityColumnNative,
+    clearBirthFpNative,
+});
 //# sourceMappingURL=sqlite-data-accessor.js.map