letagents 0.12.21 → 0.12.22

package/dist/mcp/local-state/local-chat.js

@@ -3,7 +3,8 @@ import { createRequire } from "node:module";
 import { mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { withWorkerStateFence } from "../worker-call-context.js";
+import { withWorkerStateFence, currentWorkerCall } from "../worker-call-context.js";
+import { ensureLocalWorkLeaseSchema, readLocalWorkLeases, assertLocalTaskLeaseMutation, assertLocalWorkLeaseWorker, claimLocalWorkLease, changeLocalWorkLease } from "../../../shared/local-work-leases.mjs";
 import { ensureLocalThreadRoutingProjectionSchemaAsync, getLocalThreadRoutingAgentKeysForRoots, projectLocalThreadRoutingMessage, runLocalSqliteWriteTransactionAsync, scheduleLocalThreadRoutingBackfill, } from "../../../shared/sqlite-thread-routing.mjs";
 import { MESSAGE_SENDER_MAX_CODE_POINTS, MESSAGE_SENDER_MAX_UTF8_BYTES, POSTGRES_INTEGER_MAX, isMessageSenderWithinBounds, parseAccountAgentRoutingEnvelope, parsePositivePgIntegerScopedId, } from "../../../shared/message-contracts.mjs";
 const localImportedRoutingAuthority = Symbol("localImportedRoutingAuthority");
@@ -287,6 +288,7 @@ async function initializeDb() {
             addColumnIfMissing(database, "local_tasks", "review_agent_key", "TEXT");
             addColumnIfMissing(database, "local_tasks", "review_agent_session_id", "TEXT");
             addColumnIfMissing(database, "local_tasks", "review_updated_at", "TEXT");
+            ensureLocalWorkLeaseSchema(database);
             database.exec(`
     CREATE UNIQUE INDEX IF NOT EXISTS local_chat_messages_sync_key_idx
       ON local_chat_messages (room_id, sync_key)
@@ -661,7 +663,7 @@ function allocateLocalTaskId(database, roomId) {
         .run(roomId);
     return `task_${number}`;
 }
-function mapTaskRow(row) {
+function mapTaskRow(row, database) {
     const reviewLeaseId = typeof row.review_lease_id === "string" && row.review_lease_id.trim()
         ? row.review_lease_id
         : null;
@@ -678,27 +680,28 @@ function mapTaskRow(row) {
         pr_url: typeof row.pr_url === "string" ? row.pr_url : null,
         workflow_artifacts: parseJsonArray(row.workflow_artifacts_json, []),
         workflow_refs: parseJsonArray(row.workflow_refs_json, []),
-        active_leases: reviewLeaseId
-            ? [
-                {
-                    id: reviewLeaseId,
-                    kind: "review",
-                    holder_label: typeof row.review_holder_label === "string"
-                        ? row.review_holder_label
-                        : null,
-                    agent_key: typeof row.review_agent_key === "string"
-                        ? row.review_agent_key
-                        : null,
-                    agent_session_id: typeof row.review_agent_session_id === "string"
-                        ? row.review_agent_session_id
-                        : null,
-                    status: "active",
-                    updated_at: typeof row.review_updated_at === "string"
-                        ? row.review_updated_at
-                        : null,
-                },
-            ]
-            : [],
+        active_leases: [...readLocalWorkLeases(database, String(row.room_id), String(row.task_id))
+                .map(lease => ({ ...lease, holder_label: lease.actor_label })), ...(reviewLeaseId
+                ? [
+                    {
+                        id: reviewLeaseId,
+                        kind: "review",
+                        holder_label: typeof row.review_holder_label === "string"
+                            ? row.review_holder_label
+                            : null,
+                        agent_key: typeof row.review_agent_key === "string"
+                            ? row.review_agent_key
+                            : null,
+                        agent_session_id: typeof row.review_agent_session_id === "string"
+                            ? row.review_agent_session_id
+                            : null,
+                        status: "active",
+                        updated_at: typeof row.review_updated_at === "string"
+                            ? row.review_updated_at
+                            : null,
+                    },
+                ]
+                : [])],
         created_at: String(row.created_at || ""),
         updated_at: String(row.updated_at || ""),
     };
@@ -762,7 +765,7 @@ export async function listLocalTasks(roomId, options = {}) {
       ORDER BY created_at ASC
     `)
         .all(...params)
-        .map(mapTaskRow);
+        .map(row => mapTaskRow(row, database));
     return { tasks, has_more: false };
 }
 export async function listLocalActiveTaskOwnerLeases(roomId) {
@@ -808,60 +811,111 @@ export async function getLocalTask(roomId, taskId) {
     const row = database
         .prepare("SELECT * FROM local_tasks WHERE room_id = ? AND task_id = ?")
         .get(roomId, taskId);
-    return row ? mapTaskRow(row) : null;
+    return row ? mapTaskRow(row, database) : null;
 }
 export async function updateLocalTask(roomId, taskId, patch) {
-    const current = await getLocalTask(roomId, taskId);
-    if (!current)
-        throw new Error("Task not found.");
-    const nextStatus = patch.skip_transition_validation === true
-        ? typeof patch.status === "string" && patch.status.trim()
-            ? patch.status.trim()
-            : current.status
-        : resolveLocalTaskStatus(current.status, patch.status);
-    const assigneeAgentKey = patch.assignee_agent_key === undefined
-        ? current.assignee_agent_key
-        : typeof patch.assignee_agent_key === "string"
-            ? patch.assignee_agent_key
-            : null;
-    const assigneeAgentInstanceId = patch.assignee_agent_key === undefined
-        ? current.assignee_agent_instance_id
-        : assigneeAgentKey && typeof patch.assignee_agent_instance_id === "string"
-            ? patch.assignee_agent_instance_id
-            : assigneeAgentKey && typeof patch.actor_instance_id === "string"
-                ? patch.actor_instance_id
-                : null;
-    const assigneeAgentSessionId = patch.assignee_agent_key === undefined
-        ? current.assignee_agent_session_id
-        : assigneeAgentKey && typeof patch.assignee_agent_session_id === "string"
-            ? patch.assignee_agent_session_id
-            : assigneeAgentKey && typeof patch.agent_session_id === "string"
-                ? patch.agent_session_id
+    const database = await getDb();
+    let observed = readLocalWorkLeases(database, roomId, taskId)[0] ?? null;
+    return runLocalSqliteWriteTransactionAsync(database, () => withWorkerStateFence(() => {
+        let row = database.prepare("SELECT * FROM local_tasks WHERE room_id=? AND task_id=?").get(roomId, taskId);
+        if (!row)
+            throw new Error("Task not found.");
+        if (patch.expected_no_work_lease === true && readLocalWorkLeases(database, roomId, taskId).length) {
+            throw new Error("The task lease changed. Refresh the task before trying again.");
+        }
+        const caller = currentWorkerCall();
+        const worker = caller?.agent_key ? {
+            agent_key: caller.agent_key, session_id: caller.session_id, actor_label: caller.actor_label || caller.agent_key,
+            agent_instance_id: caller.agent_instance_id,
+        } : null;
+        const supervised = worker ? assertLocalWorkLeaseWorker(database, roomId, worker) : false;
+        if (supervised && worker && patch.status === "assigned") {
+            if ((patch.assignee_agent_key != null && patch.assignee_agent_key !== worker.agent_key)
+                || (patch.assignee != null && patch.assignee !== worker.actor_label)) {
+                throw new Error("Use handoff_task_lease to assign work to another worker.");
+            }
+            observed = claimLocalWorkLease(database, roomId, taskId, worker);
+            row = database.prepare("SELECT * FROM local_tasks WHERE room_id=? AND task_id=?").get(roomId, taskId);
+        }
+        if (worker) {
+            assertLocalTaskLeaseMutation(database, row, worker, observed);
+            if ((supervised || observed) && ((patch.assignee !== undefined && patch.assignee !== row.assignee)
+                || (patch.assignee_agent_key !== undefined && patch.assignee_agent_key !== row.assignee_agent_key)
+                || (patch.assignee_agent_session_id !== undefined && patch.assignee_agent_session_id !== row.assignee_agent_session_id)
+                || (patch.assignee_agent_key !== undefined && patch.agent_session_id !== undefined && patch.agent_session_id !== row.assignee_agent_session_id)
+                || (patch.assignee_agent_instance_id !== undefined && patch.assignee_agent_instance_id !== row.assignee_agent_instance_id)
+                || (patch.assignee_agent_key !== undefined && patch.actor_instance_id !== undefined && patch.actor_instance_id !== row.assignee_agent_instance_id))) {
+                throw new Error("Use claim_task or handoff_task_lease to change task ownership.");
+            }
+        }
+        else if (observed || readLocalWorkLeases(database, roomId, taskId).length) {
+            throw new Error("A registered owning worker is required to update this leased task.");
+        }
+        const current = mapTaskRow(row, database);
+        const nextStatus = supervised && patch.status === "assigned" ? current.status
+            : patch.skip_transition_validation === true
+                ? typeof patch.status === "string" && patch.status.trim()
+                    ? patch.status.trim()
+                    : current.status
+                : resolveLocalTaskStatus(current.status, patch.status);
+        const assigneeAgentKey = patch.assignee_agent_key === undefined
+            ? current.assignee_agent_key
+            : typeof patch.assignee_agent_key === "string"
+                ? patch.assignee_agent_key
                 : null;
-    const workflowArtifacts = patch.workflow_artifacts === undefined
-        ? JSON.stringify(current.workflow_artifacts)
-        : JSON.stringify(Array.isArray(patch.workflow_artifacts) ? patch.workflow_artifacts : []);
-    const now = new Date().toISOString();
+        const assigneeAgentInstanceId = patch.assignee_agent_key === undefined || (worker && patch.assignee_agent_key === current.assignee_agent_key)
+            ? current.assignee_agent_instance_id
+            : assigneeAgentKey && typeof patch.assignee_agent_instance_id === "string"
+                ? patch.assignee_agent_instance_id
+                : assigneeAgentKey && typeof patch.actor_instance_id === "string"
+                    ? patch.actor_instance_id
+                    : null;
+        const assigneeAgentSessionId = patch.assignee_agent_key === undefined || (worker && patch.assignee_agent_key === current.assignee_agent_key)
+            ? current.assignee_agent_session_id
+            : assigneeAgentKey && typeof patch.assignee_agent_session_id === "string"
+                ? patch.assignee_agent_session_id
+                : assigneeAgentKey && typeof patch.agent_session_id === "string"
+                    ? patch.agent_session_id
+                    : null;
+        const workflowArtifacts = patch.workflow_artifacts === undefined
+            ? JSON.stringify(current.workflow_artifacts)
+            : JSON.stringify(Array.isArray(patch.workflow_artifacts) ? patch.workflow_artifacts : []);
+        const now = new Date().toISOString();
+        database
+            .prepare(`
+        UPDATE local_tasks
+        SET status = ?,
+            assignee = ?,
+            assignee_agent_key = ?,
+            assignee_agent_instance_id = ?,
+            assignee_agent_session_id = ?,
+            pr_url = ?,
+            workflow_artifacts_json = ?,
+            sync_dirty = 1,
+            updated_at = ?
+        WHERE room_id = ? AND task_id = ?
+      `)
+            .run(nextStatus, patch.assignee === undefined ? current.assignee : patch.assignee || null, assigneeAgentKey, assigneeAgentInstanceId, assigneeAgentSessionId, patch.pr_url === undefined ? current.pr_url : patch.pr_url || null, workflowArtifacts, now, roomId, taskId);
+        return mapTaskRow(database.prepare("SELECT * FROM local_tasks WHERE room_id=? AND task_id=?").get(roomId, taskId), database);
+    }));
+}
+export async function changeLocalTaskWorkLease(roomId, taskId, input) {
     const database = await getDb();
-    await runLocalSqliteWriteTransactionAsync(database, () => withWorkerStateFence(() => database
-        .prepare(`
-      UPDATE local_tasks
-      SET status = ?,
-          assignee = ?,
-          assignee_agent_key = ?,
-          assignee_agent_instance_id = ?,
-          assignee_agent_session_id = ?,
-          pr_url = ?,
-          workflow_artifacts_json = ?,
-          sync_dirty = 1,
-          updated_at = ?
-      WHERE room_id = ? AND task_id = ?
-    `)
-        .run(nextStatus, patch.assignee === undefined ? current.assignee : patch.assignee || null, assigneeAgentKey, assigneeAgentInstanceId, assigneeAgentSessionId, patch.pr_url === undefined ? current.pr_url : patch.pr_url || null, workflowArtifacts, now, roomId, taskId)));
-    const updated = await getLocalTask(roomId, taskId);
-    if (!updated)
-        throw new Error("Task not found.");
-    return updated;
+    const observed = readLocalWorkLeases(database, roomId, taskId)[0];
+    if (!observed)
+        throw new Error("This task has no active work lease.");
+    return runLocalSqliteWriteTransactionAsync(database, () => withWorkerStateFence(() => {
+        const worker = currentWorkerCall();
+        if (!worker?.agent_key)
+            throw new Error("A registered owning worker is required to change this work lease.");
+        const result = changeLocalWorkLease(database, roomId, taskId, {
+            ...input, lease_id: input.lease_id ?? observed.id, epoch: input.epoch ?? observed.epoch,
+        }, {
+            agent_key: worker.agent_key, session_id: worker.session_id, actor_label: worker.actor_label || worker.agent_key,
+        });
+        const task = mapTaskRow(database.prepare("SELECT * FROM local_tasks WHERE room_id=? AND task_id=?").get(roomId, taskId), database);
+        return { action: input.action, task, ...result };
+    }));
 }
 export async function claimLocalTaskReviewLease(roomId, taskId, input) {
     const current = await getLocalTask(roomId, taskId);

package/dist/mcp/server/tools/tasks/api.js

@@ -1,5 +1,6 @@
 import { encodeRoomIdPath } from "../../../room-id.js";
 import { addLocalTask, apiCall, claimLocalTaskReviewLease, getLocalTask, isLocalRoomStorageEnabled, listLocalTasks, releaseLocalTaskReviewLease, resolveLocalRoomStorageIdentifiers, roomScopedApiCall, updateLocalTask, } from "../../runtime.js";
+import { changeLocalTaskWorkLease } from "../../../local-state/local-chat.js";
 export function taskCollectionRoomPath(roomId) {
     return `/rooms/${encodeRoomIdPath(roomId)}/tasks`;
 }
@@ -129,6 +130,17 @@ export async function postCanonicalTaskAction(roomId, taskId, actionPath, body)
                 released_lease: null,
             };
         }
+        if ((action === "handoff" || action === "release") && existingTask.active_leases?.some(lease => lease.kind === "work")) {
+            return await changeLocalTaskWorkLease(sqliteRoomId, taskId, {
+                action, lease_id: typeof body.lease_id === "string" ? body.lease_id : null,
+                target_actor_key: typeof body.target_actor_key === "string" ? body.target_actor_key : null,
+                target_actor_instance_id: typeof body.target_actor_instance_id === "string" ? body.target_actor_instance_id : null,
+                target_agent_session_id: typeof body.target_agent_session_id === "string" ? body.target_agent_session_id : null,
+            });
+        }
+        if ((action === "handoff" || action === "release") && body.lease_id) {
+            throw new Error("The task lease changed. Refresh the task before trying again.");
+        }
         if (action === "handoff") {
             const targetActorKey = typeof body.target_actor_key === "string" && body.target_actor_key.trim()
                 ? body.target_actor_key.trim()
@@ -141,6 +153,7 @@ export async function postCanonicalTaskAction(roomId, taskId, actionPath, body)
                 : null;
             const task = targetActorKey
                 ? await updateLocalTask(sqliteRoomId, taskId, {
+                    expected_no_work_lease: true,
                     ...(existingTask.status === "accepted" ? { status: "assigned" } : {}),
                     assignee: targetActorKey,
                     assignee_agent_key: targetActorKey,
@@ -158,6 +171,7 @@ export async function postCanonicalTaskAction(roomId, taskId, actionPath, body)
         if (action === "release") {
             const releasableStatuses = new Set(["assigned", "in_progress", "blocked", "in_review"]);
             const patch = {
+                expected_no_work_lease: true,
                 assignee: null,
                 assignee_agent_key: null,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letagents",
-  "version": "0.12.21",
+  "version": "0.12.22",
   "description": "Let Agents Chat — MCP server for AI agent communication",
   "type": "module",
   "main": "dist/mcp/server.js",

package/shared/local-work-leases.d.mts

@@ -0,0 +1,24 @@
+import type { SqliteRoutingDatabase as SqliteDatabase } from './sqlite-thread-routing.mjs';
+export type LocalWorkLeaseWorker = {
+  agent_key: string; session_id: string; actor_label: string; agent_instance_id?: string | null; supervised?: boolean;
+};
+export type LocalWorkLease = {
+  id: string; room_id: string; task_id: string; kind: 'work'; status: string;
+  agent_key: string; agent_session_id: string; agent_instance_id: string | null; actor_label: string;
+  epoch: number; created_at: string; updated_at: string; last_heartbeat_at: string;
+  expires_at: string | null; revoked_reason: string | null;
+};
+export type LocalWorkLeaseAction = {
+  action: 'release' | 'handoff'; lease_id?: string | null; epoch?: number;
+  target_actor_key?: string | null; target_actor_instance_id?: string | null; target_agent_session_id?: string | null;
+};
+export function ensureLocalWorkLeaseSchema(db: SqliteDatabase): void;
+export function readLocalWorkLeases(db: SqliteDatabase, roomId: string, taskId: string): LocalWorkLease[];
+export function assertLocalWorkLeaseWorker(db: SqliteDatabase, roomId: string, worker: LocalWorkLeaseWorker): boolean;
+export function claimLocalWorkLease(db: SqliteDatabase, roomId: string, taskId: string, worker: LocalWorkLeaseWorker): LocalWorkLease;
+export function assertLocalTaskLeaseMutation(db: SqliteDatabase, task: Record<string, unknown>, worker: LocalWorkLeaseWorker,
+  expected?: Pick<LocalWorkLease, 'id' | 'epoch'> | null): void;
+export function changeLocalWorkLease(db: SqliteDatabase, roomId: string, taskId: string, input: LocalWorkLeaseAction,
+  worker: LocalWorkLeaseWorker | null): { released_lease: LocalWorkLease; new_lease: LocalWorkLease | null };
+export function endLocalWorkerLeases(db: SqliteDatabase, sessionId: string, now: string): void;
+export function heartbeatLocalWorkLeases(db: SqliteDatabase, sessionId: string, now: string): Array<{id: string; epoch: number}>;

package/shared/local-work-leases.mjs

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+
+/** Shared by desktop and MCP writers. All mutations run inside their write transaction. */
+export function ensureLocalWorkLeaseSchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS local_work_leases (
+      id TEXT PRIMARY KEY, room_id TEXT NOT NULL, task_id TEXT NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'work' CHECK(kind='work'),
+      status TEXT NOT NULL CHECK(status IN ('active','released','revoked','expired')),
+      agent_key TEXT NOT NULL, agent_session_id TEXT NOT NULL, agent_instance_id TEXT,
+      actor_label TEXT NOT NULL, epoch INTEGER NOT NULL CHECK(epoch>=0),
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL, last_heartbeat_at TEXT NOT NULL,
+      expires_at TEXT, revoked_reason TEXT,
+      FOREIGN KEY(room_id,task_id) REFERENCES local_tasks(room_id,task_id) ON DELETE CASCADE
+    ) STRICT;
+    CREATE UNIQUE INDEX IF NOT EXISTS local_work_lease_owner
+      ON local_work_leases(room_id,task_id) WHERE status='active';
+    CREATE INDEX IF NOT EXISTS local_work_lease_session ON local_work_leases(agent_session_id,status);
+    CREATE TRIGGER IF NOT EXISTS local_work_lease_task_changed
+      AFTER UPDATE OF status,assignee,assignee_agent_key,assignee_agent_session_id ON local_tasks
+      BEGIN
+        UPDATE local_work_leases SET status='revoked',revoked_reason='Task completed or ownership changed',updated_at=NEW.updated_at
+        WHERE room_id=NEW.room_id AND task_id=NEW.task_id AND status='active'
+          AND (NEW.status NOT IN ('assigned','in_progress','blocked','in_review')
+            OR NEW.assignee_agent_key IS NOT agent_key
+            OR NEW.assignee_agent_session_id IS NOT agent_session_id
+            OR NEW.assignee IS NOT actor_label);
+      END;
+    CREATE TRIGGER IF NOT EXISTS local_work_lease_task_deleted AFTER DELETE ON local_tasks
+      BEGIN DELETE FROM local_work_leases WHERE room_id=OLD.room_id AND task_id=OLD.task_id; END;
+  `);
+}
+
+export function readLocalWorkLeases(db, roomId, taskId) {
+  return db.prepare(`SELECT * FROM local_work_leases WHERE room_id=? AND task_id=? AND status='active'
+    AND (expires_at IS NULL OR expires_at>?)`).all(roomId, taskId, new Date().toISOString());
+}
+
+export function assertLocalWorkLeaseWorker(db, roomId, worker) {
+  if (!worker?.agent_key || !worker.session_id) throw new Error("A registered worker is required for task ownership.");
+  const hasSessions = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='local_supervisor_sessions'").get();
+  const session = hasSessions && db.prepare(`SELECT s.ended_at,g.revoked_at,g.room_id,g.agent_key FROM local_supervisor_sessions s
+    JOIN local_supervisor_grants g USING(grant_id) WHERE s.session_id=?`).get(worker.session_id);
+  if ((worker.supervised && !session) || (session && (session.ended_at || session.revoked_at
+    || session.room_id !== roomId || session.agent_key !== worker.agent_key))) {
+    throw new Error("Local worker authority ended before the task mutation.");
+  }
+  return Boolean(session);
+}
+
+function taskRow(db, roomId, taskId) {
+  const task = db.prepare("SELECT * FROM local_tasks WHERE room_id=? AND task_id=?").get(roomId, taskId);
+  if (!task) throw new Error("Task not found.");
+  return task;
+}
+
+function expireLeases(db, roomId, taskId, now) {
+  db.prepare(`UPDATE local_work_leases SET status='expired',updated_at=?
+    WHERE room_id=? AND task_id=? AND status='active' AND expires_at IS NOT NULL AND expires_at<=?`)
+    .run(now, roomId, taskId, now);
+}
+
+function mintLease(db, roomId, taskId, worker, now) {
+  const epoch = Number(db.prepare("SELECT COALESCE(MAX(epoch),-1)+1 AS epoch FROM local_work_leases WHERE room_id=? AND task_id=?")
+    .get(roomId, taskId).epoch);
+  const id = `local_work_${randomUUID()}`;
+  db.prepare(`INSERT INTO local_work_leases(id,room_id,task_id,status,agent_key,agent_session_id,agent_instance_id,
+    actor_label,epoch,created_at,updated_at,last_heartbeat_at) VALUES(?,?,?,'active',?,?,?,?,?,?,?,?)`)
+    .run(id, roomId, taskId, worker.agent_key, worker.session_id, worker.agent_instance_id ?? null,
+      worker.actor_label, epoch, now, now, now);
+  return db.prepare("SELECT * FROM local_work_leases WHERE id=?").get(id);
+}
+
+function assignTask(db, roomId, taskId, worker, status, now) {
+  db.prepare(`UPDATE local_tasks SET status=?,assignee=?,assignee_agent_key=?,assignee_agent_instance_id=?,
+    assignee_agent_session_id=?,sync_dirty=1,updated_at=? WHERE room_id=? AND task_id=?`)
+    .run(status, worker?.actor_label ?? null, worker?.agent_key ?? null, worker?.agent_instance_id ?? null,
+      worker?.session_id ?? null, now, roomId, taskId);
+}
+
+export function claimLocalWorkLease(db, roomId, taskId, worker) {
+  if (!assertLocalWorkLeaseWorker(db, roomId, worker)) throw new Error("A supervised worker is required for a local work lease.");
+  const task = taskRow(db, roomId, taskId);
+  const now = new Date().toISOString();
+  expireLeases(db, roomId, taskId, now);
+  const active = readLocalWorkLeases(db, roomId, taskId)[0];
+  if (active) {
+    if (active.agent_session_id !== worker.session_id || active.agent_key !== worker.agent_key) {
+      throw new Error("This task is already owned by another worker. Use a lease handoff.");
+    }
+    return active; // Retry never changes the failure-time cutoff or ownership fence.
+  }
+  const reclaim = ['assigned', 'in_progress', 'blocked', 'in_review'].includes(task.status)
+    && task.assignee_agent_key === worker.agent_key;
+  if (task.status !== 'accepted' && !reclaim) throw new Error("Claim an accepted task, or reclaim your own assigned task.");
+  if (task.assignee_agent_key && task.assignee_agent_key !== worker.agent_key) throw new Error("This task is assigned to another worker.");
+  assignTask(db, roomId, taskId, worker, reclaim ? task.status : 'assigned', now);
+  return mintLease(db, roomId, taskId, worker, now);
+}
+
+/** Worker APIs must call this after taking the write lock, before changing any task fields. */
+export function assertLocalTaskLeaseMutation(db, task, worker, expected) {
+  const supervised = assertLocalWorkLeaseWorker(db, task.room_id, worker);
+  const active = readLocalWorkLeases(db, task.room_id, task.task_id)[0];
+  if (expected !== undefined && ((active?.id ?? null) !== (expected?.id ?? null)
+    || (active?.epoch ?? null) !== (expected?.epoch ?? null))) throw new Error("The task lease changed before this update.");
+  const reviewOwner = task.review_lease_id && task.review_agent_key === worker.agent_key
+    && task.review_agent_session_id === worker.session_id && task.status === 'in_review';
+  if (active && (active.agent_session_id !== worker.session_id || active.agent_key !== worker.agent_key) && !reviewOwner) {
+    throw new Error("This task's work lease belongs to another worker.");
+  }
+  if (!active && supervised && ['assigned','in_progress','blocked','in_review'].includes(task.status) && !reviewOwner) {
+    throw new Error("Claim this task to establish a current work lease before updating it.");
+  }
+}
+
+/** A null actor is reserved for the desktop's explicit human lease controls. */
+export function changeLocalWorkLease(db, roomId, taskId, input, worker) {
+  if (worker) assertLocalWorkLeaseWorker(db, roomId, worker);
+  const task = taskRow(db, roomId, taskId);
+  const now = new Date().toISOString();
+  expireLeases(db, roomId, taskId, now);
+  const active = readLocalWorkLeases(db, roomId, taskId)[0];
+  if (!active) throw new Error("This task has no active work lease.");
+  if ((input.lease_id && active.id !== input.lease_id)
+    || (input.epoch !== undefined && active.epoch !== input.epoch)) throw new Error("The task lease changed. Refresh the task before trying again.");
+  if (worker && (active.agent_session_id !== worker.session_id || active.agent_key !== worker.agent_key)) {
+    throw new Error("Only the current worker can release or hand off this work lease.");
+  }
+  let target = null;
+  if (input.action === 'handoff') {
+    const targets = db.prepare(`SELECT s.session_id,s.instance_id,g.agent_key,s.public_json FROM local_supervisor_sessions s
+      JOIN local_supervisor_grants g USING(grant_id) WHERE g.room_id=? AND g.agent_key=?
+        AND g.revoked_at IS NULL AND s.ended_at IS NULL`)
+      .all(roomId, input.target_actor_key ?? '').filter(row =>
+        (!input.target_agent_session_id || row.session_id === input.target_agent_session_id)
+        && (!input.target_actor_instance_id || row.instance_id === input.target_actor_instance_id));
+    if (targets.length !== 1) throw new Error("Choose one active local worker session for this handoff.");
+    const session = JSON.parse(targets[0].public_json);
+    target = { ...session, supervised: true };
+    assertLocalWorkLeaseWorker(db, roomId, target);
+  } else if (input.action !== 'release') throw new Error("Unknown work lease action.");
+  db.prepare("UPDATE local_work_leases SET status='released',updated_at=? WHERE id=?").run(now, active.id);
+  assignTask(db, roomId, taskId, target, target ? (task.status === 'blocked' ? 'assigned' : task.status) : 'accepted', now);
+  return { released_lease: { ...active, status: 'released', updated_at: now },
+    new_lease: target ? mintLease(db, roomId, taskId, target, now) : null };
+}
+
+export function endLocalWorkerLeases(db, sessionId, now) {
+  db.prepare(`UPDATE local_work_leases SET status='revoked',revoked_reason='Worker session ended',updated_at=?
+    WHERE agent_session_id=? AND status='active'`).run(now, sessionId);
+}
+
+export function heartbeatLocalWorkLeases(db, sessionId, now) {
+  db.prepare(`UPDATE local_work_leases SET last_heartbeat_at=?,updated_at=?
+    WHERE agent_session_id=? AND status='active' AND (expires_at IS NULL OR expires_at>?)`)
+    .run(now, now, sessionId, now);
+  return db.prepare(`SELECT id,epoch FROM local_work_leases WHERE agent_session_id=? AND status='active'
+    AND (expires_at IS NULL OR expires_at>?)`).all(sessionId, now);
+}