@cleocode/core 2026.9.22 → 2026.9.24

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

@@ -12,21 +12,23 @@
  */
 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 { 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 { 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
@@ -70,7 +72,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 +107,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
@@ -189,6 +191,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.
@@ -390,6 +473,8 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                     detailsJson: entry.details ? JSON.stringify(entry.details) : '{}',
                     beforeJson: entry.before ? JSON.stringify(entry.before) : null,
                     afterJson: entry.after ? JSON.stringify(entry.after) : null,
+                    // T12693: the session a ranking change ran in.
+                    sessionId: typeof entry.sessionId === 'string' ? entry.sessionId : null,
                 })
                     .run());
             });
@@ -397,6 +482,9 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
         async queryAuditLog(query) {
             const db = await getDb(cwd);
             const conditions = [];
+            if (query.ids && query.ids.length > 0) {
+                conditions.push(inArray(tasksAuditLog.id, [...query.ids]));
+            }
             if (query.taskIds && query.taskIds.length > 0) {
                 conditions.push(inArray(tasksAuditLog.taskId, [...query.taskIds]));
             }
@@ -417,6 +505,7 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                 detailsJson: tasksAuditLog.detailsJson,
                 beforeJson: tasksAuditLog.beforeJson,
                 afterJson: tasksAuditLog.afterJson,
+                sessionId: tasksAuditLog.sessionId,
             })
                 .from(tasksAuditLog)
                 .where(conditions.length > 0 ? and(...conditions) : undefined)
@@ -432,12 +521,16 @@ async function createOwnedSqliteDataAccessor(cwd, accessorScope) {
                 detailsJson: row.detailsJson ?? null,
                 beforeJson: row.beforeJson ?? null,
                 afterJson: row.afterJson ?? null,
+                sessionId: row.sessionId ?? null,
             }));
         },
         // ---- Fine-grained task operations (T5034) ----
         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);
@@ -1011,24 +1104,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));
                 }
@@ -1082,6 +1205,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 () => {
@@ -1371,51 +1502,125 @@ 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;
 }