@hasna/todos 0.15.19 → 0.15.20

package/dist/index.js

@@ -3662,7 +3662,7 @@ function isBlockingDependencyStatus(status) {
 function isTerminalStatus(status) {
   return status === "completed" || status === "failed" || status === "cancelled";
 }
-var TASK_STATUSES, TASK_PRIORITIES, PLAN_STATUSES, VersionConflictError, TaskNotFoundError, TaskNotStartableError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanRevisionConflictError, PlanNotFoundError, LockError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DISPATCH_STATUSES, DispatchNotFoundError;
+var TASK_STATUSES, TASK_PRIORITIES, PLAN_STATUSES, VersionConflictError, TaskNotFoundError, TaskNotStartableError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanRevisionConflictError, PlanNotFoundError, LockError, StaleLockHandoffError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DISPATCH_STATUSES, DispatchNotFoundError;
 var init_types = __esm(() => {
   TASK_STATUSES = [
     "pending",
@@ -3785,6 +3785,16 @@ var init_types = __esm(() => {
       this.name = "LockError";
     }
   };
+  StaleLockHandoffError = class StaleLockHandoffError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+      super(message);
+      this.code = code;
+      this.details = details;
+      this.name = "StaleLockHandoffError";
+    }
+  };
   AgentNotFoundError = class AgentNotFoundError extends Error {
     agentId;
     static code = "AGENT_NOT_FOUND";
@@ -7503,28 +7513,55 @@ var init_activity_audit = __esm(() => {
 function sanitizeHistoryValue(value, context) {
   return value === undefined || value === null ? null : sanitizePreWriteText(String(value), context);
 }
-function logTaskChange(taskId, action, field2, oldValue, newValue, agentId, db) {
+function insertTaskHistory(entry, db) {
   const d = db || getDatabase();
-  const id = uuid();
-  const timestamp2 = now();
-  const machineId = currentStorageMachineId(d);
-  const safeOldValue = sanitizeHistoryValue(oldValue, "task_history.old_value");
-  const safeNewValue = sanitizeHistoryValue(newValue, "task_history.new_value");
+  const safeEntry = {
+    ...entry,
+    field: entry.field || null,
+    old_value: sanitizeHistoryValue(entry.old_value, "task_history.old_value"),
+    new_value: sanitizeHistoryValue(entry.new_value, "task_history.new_value"),
+    agent_id: entry.agent_id || null,
+    machine_id: entry.machine_id ?? currentStorageMachineId(d)
+  };
   d.run(`INSERT INTO task_history (id, task_id, action, field, old_value, new_value, agent_id, created_at, machine_id)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [id, taskId, action, field2 || null, safeOldValue, safeNewValue, agentId || null, timestamp2, machineId]);
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+    safeEntry.id,
+    safeEntry.task_id,
+    safeEntry.action,
+    safeEntry.field,
+    safeEntry.old_value,
+    safeEntry.new_value,
+    safeEntry.agent_id,
+    safeEntry.created_at,
+    safeEntry.machine_id ?? null
+  ]);
   try {
     const { logActivity: logActivity2 } = (init_activity_audit(), __toCommonJS(exports_activity_audit));
     logActivity2({
       entity_type: "task",
-      entity_id: taskId,
-      action,
-      field: field2,
-      old_value: safeOldValue,
-      new_value: safeNewValue,
-      actor_id: agentId ?? undefined
+      entity_id: safeEntry.task_id,
+      action: safeEntry.action,
+      field: safeEntry.field ?? undefined,
+      old_value: safeEntry.old_value,
+      new_value: safeEntry.new_value,
+      actor_id: safeEntry.agent_id ?? undefined
     }, d);
   } catch {}
-  return { id, task_id: taskId, action, field: field2 || null, old_value: safeOldValue, new_value: safeNewValue, agent_id: agentId || null, created_at: timestamp2, machine_id: machineId };
+  return safeEntry;
+}
+function logTaskChange(taskId, action, field2, oldValue, newValue, agentId, db) {
+  const d = db || getDatabase();
+  return insertTaskHistory({
+    id: uuid(),
+    task_id: taskId,
+    action,
+    field: field2 || null,
+    old_value: oldValue ?? null,
+    new_value: newValue ?? null,
+    agent_id: agentId || null,
+    created_at: now(),
+    machine_id: currentStorageMachineId(d)
+  }, d);
 }
 function getTaskHistory(taskId, db) {
   const d = db || getDatabase();
@@ -8547,6 +8584,145 @@ var init_task_graph = __esm(() => {
   init_task_crud();
 });
 
+// src/lib/stale-lock-handoff.ts
+function normalizeExactTaskId(value) {
+  if (typeof value !== "string" || !EXACT_TASK_UUID_RE.test(value.trim())) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_TASK_ID", "stale-lock handoff requires one exact full task UUID", { task_id: typeof value === "string" ? value : null });
+  }
+  return value.trim().toLowerCase();
+}
+function requireNonEmptyString(value, field2) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", `${field2} must be a non-empty string`, { field: field2 });
+  }
+  const trimmed = value.trim();
+  if (field2 === "reason" && trimmed.length > MAX_REASON_LENGTH) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", `reason must be at most ${MAX_REASON_LENGTH} characters`, { field: field2, max_length: MAX_REASON_LENGTH });
+  }
+  return trimmed;
+}
+function requireCanonicalLockVersion(value) {
+  if (typeof value !== "string" || !CANONICAL_LOCK_VERSION_RE.test(value)) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "expected_lock_version must be the exact canonical locked_at timestamp (YYYY-MM-DDTHH:mm:ss.sssZ)", { field: "expected_lock_version" });
+  }
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed) || new Date(parsed).toISOString() !== value) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "expected_lock_version must name a real canonical UTC instant", { field: "expected_lock_version" });
+  }
+  return value;
+}
+function requireStaleThreshold(value) {
+  if (!Number.isSafeInteger(value) || Number(value) <= 0) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "stale_after_seconds must be a positive safe integer", { field: "stale_after_seconds" });
+  }
+  return Number(value);
+}
+function prepareStaleLockHandoff(input, options = {}) {
+  const taskId = normalizeExactTaskId(input.task_id);
+  const actor = requireNonEmptyString(input.actor, "actor");
+  const expectedHolder = requireNonEmptyString(input.expected_holder, "expected_holder");
+  const newHolder = requireNonEmptyString(input.new_holder, "new_holder");
+  const expectedLockVersion = requireCanonicalLockVersion(input.expected_lock_version);
+  const staleAfterSeconds = requireStaleThreshold(input.stale_after_seconds);
+  const reason = sanitizePreWriteText(requireNonEmptyString(input.reason, "reason"), "stale_lock_handoff.reason").trim();
+  if (!reason) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "reason must remain non-empty after safety filtering", { field: "reason" });
+  }
+  if (canonicalAgentRef(actor) !== canonicalAgentRef(newHolder)) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_ACTOR_MISMATCH", "new_holder must match the authenticated actor", { actor, new_holder: newHolder });
+  }
+  if (canonicalAgentRef(expectedHolder) === canonicalAgentRef(newHolder)) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "new_holder must differ from expected_holder", { field: "new_holder" });
+  }
+  const operationTimestamp = options.now ?? new Date().toISOString();
+  if (!CANONICAL_LOCK_VERSION_RE.test(operationTimestamp) || new Date(Date.parse(operationTimestamp)).toISOString() !== operationTimestamp) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "operation timestamp must be a canonical UTC instant");
+  }
+  const staleCutoff = new Date(Date.parse(operationTimestamp) - staleAfterSeconds * 1000).toISOString();
+  return {
+    task_id: taskId,
+    actor,
+    expected_holder: expectedHolder,
+    expected_lock_version: expectedLockVersion,
+    stale_after_seconds: staleAfterSeconds,
+    new_holder: newHolder,
+    reason,
+    operation_timestamp: operationTimestamp,
+    stale_cutoff: staleCutoff,
+    receipt_id: options.receiptId ?? crypto.randomUUID()
+  };
+}
+function buildStaleLockHandoffReceipt(input) {
+  return {
+    schema_version: STALE_LOCK_HANDOFF_SCHEMA_VERSION,
+    receipt_id: input.receipt_id,
+    task_id: input.task_id,
+    actor: input.actor,
+    previous_holder: input.expected_holder,
+    previous_lock_version: input.expected_lock_version,
+    new_holder: input.new_holder,
+    new_lock_version: input.operation_timestamp,
+    stale_after_seconds: input.stale_after_seconds,
+    stale_cutoff: input.stale_cutoff,
+    reason: input.reason,
+    created_at: input.operation_timestamp
+  };
+}
+function staleLockHandoffHistory(receipt, machineId) {
+  return {
+    id: receipt.receipt_id,
+    task_id: receipt.task_id,
+    action: STALE_LOCK_HANDOFF_ACTION,
+    field: STALE_LOCK_HANDOFF_FIELD,
+    old_value: JSON.stringify({
+      holder: receipt.previous_holder,
+      lock_version: receipt.previous_lock_version
+    }),
+    new_value: JSON.stringify(receipt),
+    agent_id: receipt.actor,
+    created_at: receipt.created_at,
+    machine_id: machineId
+  };
+}
+function throwStaleLockHandoffConflict(task, input) {
+  if (!task.locked_by || !task.locked_at) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_NOT_LOCKED", `Task ${input.task_id} does not have a complete lock to hand off`, { task_id: input.task_id });
+  }
+  if (task.locked_at !== input.expected_lock_version) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_VERSION_MISMATCH", `Task ${input.task_id} lock version changed`, {
+      task_id: input.task_id,
+      expected_lock_version: input.expected_lock_version,
+      current_lock_version: task.locked_at
+    });
+  }
+  if (task.locked_by !== input.expected_holder) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_HOLDER_MISMATCH", `Task ${input.task_id} lock holder changed`, {
+      task_id: input.task_id,
+      expected_holder: input.expected_holder,
+      current_holder: task.locked_by
+    });
+  }
+  if (isTerminalStatus(task.status)) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_TERMINAL", `Task ${input.task_id} is ${task.status} and cannot transfer a lock`, { task_id: input.task_id, status: task.status });
+  }
+  if (task.locked_at >= input.stale_cutoff) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_NOT_STALE", `Task ${input.task_id} lock is not older than the supplied stale threshold`, {
+      task_id: input.task_id,
+      current_lock_version: task.locked_at,
+      stale_cutoff: input.stale_cutoff
+    });
+  }
+  throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_CONFLICT", `Task ${input.task_id} changed during stale-lock handoff`, { task_id: input.task_id });
+}
+var STALE_LOCK_HANDOFF_SCHEMA_VERSION = "todos.stale-lock-handoff.v1", STALE_LOCK_HANDOFF_ACTION = "stale_lock_handoff", STALE_LOCK_HANDOFF_FIELD = "lock", EXACT_TASK_UUID_RE, CANONICAL_LOCK_VERSION_RE, MAX_REASON_LENGTH = 4096;
+var init_stale_lock_handoff = __esm(() => {
+  init_types();
+  init_creator_identity();
+  init_prewrite_secrets();
+  EXACT_TASK_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  CANONICAL_LOCK_VERSION_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+});
+
 // src/db/task-lifecycle.ts
 var exports_task_lifecycle = {};
 __export(exports_task_lifecycle, {
@@ -8555,6 +8731,7 @@ __export(exports_task_lifecycle, {
   startTask: () => startTask,
   spawnNextRecurrence: () => spawnNextRecurrence,
   lockTask: () => lockTask,
+  handoffStaleTaskLock: () => handoffStaleTaskLock,
   getTasksChangedSince: () => getTasksChangedSince,
   getTaskLockStatus: () => getTaskLockStatus,
   getStaleTasks: () => getStaleTasks,
@@ -8823,6 +9000,38 @@ function unlockTask(id, agentId, db) {
      WHERE id = ?`, [timestamp2, id]);
   return true;
 }
+function handoffStaleTaskLock(input, db) {
+  const d = db || getDatabase();
+  const prepared = prepareStaleLockHandoff(input);
+  const receipt = buildStaleLockHandoffReceipt(prepared);
+  const history = staleLockHandoffHistory(receipt, null);
+  const transfer = d.transaction(() => {
+    const result = d.run(`UPDATE tasks
+       SET locked_by = ?, locked_at = ?, updated_at = ?, version = version + 1
+       WHERE id = ?
+         AND locked_by = ?
+         AND locked_at = ?
+         AND julianday(locked_at) < julianday(?)
+         AND status NOT IN ('completed', 'failed', 'cancelled')`, [
+      prepared.new_holder,
+      prepared.operation_timestamp,
+      prepared.operation_timestamp,
+      prepared.task_id,
+      prepared.expected_holder,
+      prepared.expected_lock_version,
+      prepared.stale_cutoff
+    ]);
+    if (result.changes === 0) {
+      const current = getTask(prepared.task_id, d);
+      if (!current)
+        throw new TaskNotFoundError(prepared.task_id);
+      throwStaleLockHandoffConflict(current, prepared);
+    }
+    insertTaskHistory(history, d);
+  });
+  transfer();
+  return receipt;
+}
 function getTaskLockStatus(id, db) {
   const d = db || getDatabase();
   const task = getTask(id, d);
@@ -9123,6 +9332,7 @@ var init_task_lifecycle = __esm(() => {
   init_task_crud();
   init_task_graph();
   init_prewrite_secrets();
+  init_stale_lock_handoff();
 });
 
 // src/db/task-crud.ts
@@ -12548,7 +12758,7 @@ var init_dispatches = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/todos",
-  version: "0.15.19",
+  version: "0.15.20",
   description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
   type: "module",
   main: "dist/index.js",
@@ -12619,6 +12829,8 @@ var package_default = {
     "dev:mcp": "bun run src/mcp/index.ts",
     "dev:serve": "bun run src/server/index.ts",
     "verify:release": "bun run scripts/verify-public-release.ts --mode=review",
+    "verify:release-review": "bun run scripts/verify-npm-release-agent-review.ts",
+    "issue:release-review": "bun run scripts/issue-npm-release-agent-review.ts",
     prepublishOnly: "bun run scripts/verify-public-release.ts --mode=publish",
     postinstall: "mkdir -p $HOME/.hasna/todos $HOME/.hasna/todos/training 2>/dev/null || true"
   },
@@ -25619,6 +25831,36 @@ init_task_lists();
 init_tasks();
 init_templates();
 init_storage_tombstones();
+
+// src/storage/audit-history-import.ts
+var AUDIT_HISTORY_DIVERGENT_REPLAY = "AUDIT_HISTORY_DIVERGENT_REPLAY";
+var AUDIT_HISTORY_TOMBSTONE_FORBIDDEN = "AUDIT_HISTORY_TOMBSTONE_FORBIDDEN";
+var AUDIT_HISTORY_FIELDS = [
+  "id",
+  "task_id",
+  "action",
+  "field",
+  "old_value",
+  "new_value",
+  "agent_id",
+  "created_at",
+  "machine_id"
+];
+function auditHistoryRowsAreFieldIdentical(left, right) {
+  return AUDIT_HISTORY_FIELDS.every((field2) => {
+    const leftValue = field2 === "machine_id" ? left[field2] ?? null : left[field2];
+    const rightValue = field2 === "machine_id" ? right[field2] ?? null : right[field2];
+    return leftValue === rightValue;
+  });
+}
+function divergentAuditHistoryReplayError(id) {
+  return `${AUDIT_HISTORY_DIVERGENT_REPLAY}: immutable audit_history row ${id} differs from stored row`;
+}
+function forbiddenAuditHistoryTombstoneError(id) {
+  return `${AUDIT_HISTORY_TOMBSTONE_FORBIDDEN}: audit_history tombstone ${id} is not allowed`;
+}
+
+// src/storage/sqlite-snapshot.ts
 var PROJECT_COLUMNS = [
   "id",
   "name",
@@ -25819,8 +26061,11 @@ function importSqliteTodosStorageSnapshot(snapshot, db) {
     const existingTaskLists = d.query("SELECT id, project_id, slug FROM task_lists").all();
     result.errors.push(...validateSnapshotRoutingDestinationConflicts(snapshot.projects, snapshot.taskLists, existingProjects, existingTaskLists));
   }
+  const auditImport = preflightAuditHistoryImport(d, snapshot.auditHistory, snapshot.tombstones ?? []);
+  result.errors.push(...auditImport.errors);
   if (result.errors.length > 0)
     return result;
+  result.skipped += auditImport.identicalReplayCount;
   const applyRows = (objectType, table, columns, rows, updateClockColumn, acceptEqualClock = true, afterUpsert) => {
     for (const row of rows) {
       try {
@@ -25855,10 +26100,72 @@ function importSqliteTodosStorageSnapshot(snapshot, db) {
       replaceTaskTags(row["id"], row["tags"].filter((tag) => typeof tag === "string"), d);
     }
   });
-  applyRows("audit_history", "task_history", AUDIT_COLUMNS, snapshot.auditHistory);
+  insertAuditHistoryRows(d, auditImport.rowsToInsert, result);
   applyTombstones(d, snapshot.tombstones ?? [], result);
   return result;
 }
+function preflightAuditHistoryImport(db, rows, tombstones) {
+  const errors = tombstones.filter((tombstone) => tombstone.object_type === "audit_history").map((tombstone) => forbiddenAuditHistoryTombstoneError(tombstone.object_id));
+  const rowsToInsert = [];
+  const seen = new Map;
+  let identicalReplayCount = 0;
+  for (const rawRow of rows) {
+    try {
+      const row = asRecord2(rawRow);
+      if (typeof row.id !== "string" || !row.id) {
+        throw new Error("task_history row is missing id");
+      }
+      const prior = seen.get(row.id);
+      if (prior) {
+        if (auditHistoryRowsAreFieldIdentical(prior, row))
+          identicalReplayCount += 1;
+        else
+          errors.push(divergentAuditHistoryReplayError(row.id));
+        continue;
+      }
+      seen.set(row.id, row);
+      const existing = getAuditHistoryById(db, row.id);
+      if (!existing) {
+        rowsToInsert.push(row);
+      } else if (auditHistoryRowsAreFieldIdentical(existing, row)) {
+        identicalReplayCount += 1;
+      } else {
+        errors.push(divergentAuditHistoryReplayError(row.id));
+      }
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return { rowsToInsert, identicalReplayCount, errors };
+}
+function insertAuditHistoryRows(db, rows, result) {
+  for (const rawRow of rows) {
+    try {
+      const row = asRecord2(rawRow);
+      const presentColumns = AUDIT_COLUMNS.filter((column) => (column in row));
+      if (!presentColumns.includes("id"))
+        presentColumns.unshift("id");
+      const placeholders = presentColumns.map(() => "?").join(", ");
+      const values = presentColumns.map((column) => valueForColumn(column, row[column]));
+      const changes = db.run(`INSERT OR IGNORE INTO task_history (${presentColumns.join(", ")}) VALUES (${placeholders})`, values).changes;
+      if (changes > 0) {
+        result.inserted += 1;
+        continue;
+      }
+      const existing = getAuditHistoryById(db, String(row["id"]));
+      if (existing && auditHistoryRowsAreFieldIdentical(existing, row)) {
+        result.skipped += 1;
+      } else {
+        result.errors.push(divergentAuditHistoryReplayError(String(row["id"])));
+      }
+    } catch (error) {
+      result.errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+}
+function getAuditHistoryById(db, id) {
+  return db.query(`SELECT ${AUDIT_COLUMNS.join(", ")} FROM task_history WHERE id = ? LIMIT 1`).get(id);
+}
 function upsertById(db, table, columns, row, updateClockColumn, acceptEqualClock = true) {
   const id = row["id"];
   if (typeof id !== "string" || !id)
@@ -25956,7 +26263,7 @@ function tableForTombstone(objectType) {
     return "task_templates";
   if (objectType === "template_tasks")
     return "template_tasks";
-  return "task_history";
+  throw new Error(`unsupported storage tombstone object_type: ${String(objectType)}`);
 }
 function listRows(db, table, columns) {
   return db.query(`SELECT ${columns.join(", ")} FROM ${table} ORDER BY id`).all();
@@ -26088,6 +26395,7 @@ function createLocalSqliteTodosStorageAdapter(options = {}) {
         unlockTask(id, agentId, database());
         return true;
       },
+      handoffStaleLock: (input) => handoffStaleTaskLock(input, database()),
       delete: (id) => deleteTask(id, database()),
       start: (id, agentId) => startTask(id, agentId, database()),
       complete: (id, agentId, options2) => completeTask(id, agentId, database(), options2),
@@ -26185,6 +26493,7 @@ function createLocalSqliteTodosStorageAdapter(options = {}) {
 init_types();
 import { randomUUID as randomUUID3 } from "crypto";
 init_creator_identity();
+init_stale_lock_handoff();
 
 // src/storage/postgres-sync.ts
 var DEFAULT_TODOS_POSTGRES_SYNC_TABLE = "todos_sync_records";
@@ -26620,6 +26929,7 @@ function createPostgresTodosStorageAdapter(options) {
       getChangedSince: (since, filters) => getChangedSince(since, filters, store),
       lock: (id, agentId) => lockTask2(id, agentId, store),
       unlock: (id, agentId) => unlockTask2(id, agentId, store),
+      handoffStaleLock: (input, context) => store.handoffStaleLock(input, context),
       getByFingerprint: (fingerprint2) => store.getTaskByFingerprint(fingerprint2)
     },
     dependencies: {
@@ -26766,6 +27076,91 @@ class PostgresJsonRecordStore {
        LIMIT 1`, [this.service, type, id]);
     return result.rows[0] ? payloadRecord2(result.rows[0].payload) : null;
   }
+  async handoffStaleLock(input, context = {}) {
+    const prepared = prepareStaleLockHandoff(input);
+    const receipt = buildStaleLockHandoffReceipt(prepared);
+    const history = staleLockHandoffHistory(receipt, this.machineId(context));
+    await this.ensureSchema();
+    const result = await this.options.client.query(`/* todos:stale-lock-handoff-atomic */ WITH
+       target AS MATERIALIZED (
+         SELECT payload
+         FROM ${this.tableName}
+         WHERE service = $1
+           AND object_type = 'tasks'
+           AND object_id = $2
+           AND deleted_at IS NULL
+         FOR UPDATE
+       ),
+       updated AS (
+         UPDATE ${this.tableName} AS task_record
+         SET payload = jsonb_set(
+               jsonb_set(
+                 jsonb_set(
+                   jsonb_set(
+                     task_record.payload,
+                     '{locked_by}',
+                     to_jsonb($6::text),
+                     true
+                   ),
+                   '{locked_at}',
+                   to_jsonb($7::text),
+                   true
+                 ),
+                 '{updated_at}',
+                 to_jsonb($7::text),
+                 true
+               ),
+               '{version}',
+               to_jsonb(COALESCE((task_record.payload->>'version')::integer, 0) + 1),
+               true
+             ),
+             updated_at = $7::timestamptz,
+             source_machine_id = $10,
+             version = COALESCE(task_record.version, 0) + 1
+         FROM target
+         WHERE task_record.service = $1
+           AND task_record.object_type = 'tasks'
+           AND task_record.object_id = $2
+           AND task_record.deleted_at IS NULL
+           AND target.payload->>'locked_by' = $3
+           AND target.payload->>'locked_at' = $4
+           AND todos_try_timestamptz(target.payload->>'locked_at') < $5::timestamptz
+           AND COALESCE(target.payload->>'status', '') NOT IN ('completed', 'failed', 'cancelled')
+         RETURNING task_record.payload
+       ),
+       audit AS (
+         INSERT INTO ${this.tableName} (
+           service, object_type, object_id, payload, updated_at,
+           deleted_at, source_machine_id, version
+         )
+         SELECT $1, 'audit_history', $8, $9::jsonb, $7::timestamptz,
+                NULL, $10, NULL
+         FROM updated
+         RETURNING payload
+       )
+       SELECT
+         (SELECT payload FROM target) AS current_payload,
+         (SELECT payload FROM updated) AS updated_payload,
+         (SELECT payload FROM audit) AS audit_payload`, [
+      this.service,
+      prepared.task_id,
+      prepared.expected_holder,
+      prepared.expected_lock_version,
+      prepared.stale_cutoff,
+      prepared.new_holder,
+      prepared.operation_timestamp,
+      receipt.receipt_id,
+      jsonbParam(history),
+      this.machineId(context)
+    ]);
+    const row = result.rows[0];
+    if (!row?.current_payload)
+      throw new TaskNotFoundError(prepared.task_id);
+    if (!row.updated_payload || !row.audit_payload) {
+      throwStaleLockHandoffConflict(payloadRecord2(row.current_payload), prepared);
+    }
+    return receipt;
+  }
   async list(type) {
     return (await this.listRecords(type)).map((record) => record.payload);
   }
@@ -27035,6 +27430,28 @@ class PostgresJsonRecordStore {
     }
     return value;
   }
+  async insertImmutableAuditHistory(value, context = {}) {
+    await this.ensureSchema();
+    const inserted = await this.options.client.query(`INSERT INTO ${this.tableName} (
+        service, object_type, object_id, payload, updated_at,
+        deleted_at, source_machine_id, version
+      ) VALUES ($1, $2, $3, $4::jsonb, $5::timestamptz, NULL, $6, NULL)
+      ON CONFLICT (service, object_type, object_id) DO NOTHING
+      RETURNING object_id`, [
+      this.service,
+      "audit_history",
+      value.id,
+      jsonbParam(value),
+      value.created_at,
+      context.requestId ?? this.sourceMachineId ?? null
+    ]);
+    if (inserted.rows.length > 0)
+      return "inserted";
+    const existing = await this.get("audit_history", value.id);
+    if (existing && auditHistoryRowsAreFieldIdentical(existing, value))
+      return "identical";
+    throw new Error(divergentAuditHistoryReplayError(value.id));
+  }
   async upsertTaskWithPlanMembershipGuard(value, guardedPlanIds, explicitProject, context = {}) {
     const planIds = [...new Set(guardedPlanIds.filter(Boolean))].sort();
     if (planIds.length === 0)
@@ -28526,6 +28943,11 @@ async function importSnapshot(snapshot, store, context) {
   result.errors.push(...validateSnapshotRoutingDestinationConflicts(snapshot.projects, snapshot.taskLists, existingProjects, existingTaskLists));
   if (result.errors.length > 0)
     return result;
+  const auditHistory = await preflightAuditHistoryImport2(snapshot.auditHistory, snapshot.tombstones ?? [], store);
+  result.errors.push(...auditHistory.errors);
+  if (result.errors.length > 0)
+    return result;
+  result.skipped += auditHistory.identical;
   const entries = [
     ...snapshot.tasks.map((row) => ["tasks", row]),
     ...snapshot.projects.map((row) => ["projects", row]),
@@ -28534,9 +28956,20 @@ async function importSnapshot(snapshot, store, context) {
     ...snapshot.agents.map((row) => ["agents", row]),
     ...snapshot.taskLists.map((row) => ["task_lists", row]),
     ...snapshot.templates.map((row) => ["templates", row]),
-    ...(snapshot.templateTasks ?? []).map((row) => ["template_tasks", row]),
-    ...snapshot.auditHistory.map((row) => ["audit_history", row])
+    ...(snapshot.templateTasks ?? []).map((row) => ["template_tasks", row])
   ];
+  for (const row of auditHistory.rowsToInsert) {
+    try {
+      const outcome = await store.insertImmutableAuditHistory(row, context);
+      if (outcome === "inserted")
+        result.inserted += 1;
+      else
+        result.skipped += 1;
+    } catch (error) {
+      result.errors.push(error instanceof Error ? error.message : String(error));
+      return result;
+    }
+  }
   for (const [type, row] of entries) {
     try {
       const existing = await store.get(type, row.id);
@@ -28570,6 +29003,32 @@ async function importSnapshot(snapshot, store, context) {
   }
   return result;
 }
+async function preflightAuditHistoryImport2(rows, tombstones, store) {
+  const errors = tombstones.filter((tombstone) => tombstone.object_type === "audit_history").map((tombstone) => forbiddenAuditHistoryTombstoneError(tombstone.object_id));
+  const rowsToInsert = [];
+  const seen = new Map;
+  let identical = 0;
+  for (const row of rows) {
+    const prior = seen.get(row.id);
+    if (prior) {
+      if (auditHistoryRowsAreFieldIdentical(prior, row))
+        identical += 1;
+      else
+        errors.push(divergentAuditHistoryReplayError(row.id));
+      continue;
+    }
+    seen.set(row.id, row);
+    const existing = await store.get("audit_history", row.id);
+    if (!existing) {
+      rowsToInsert.push(row);
+    } else if (auditHistoryRowsAreFieldIdentical(existing, row)) {
+      identical += 1;
+    } else {
+      errors.push(divergentAuditHistoryReplayError(row.id));
+    }
+  }
+  return { rowsToInsert, identical, errors };
+}
 async function requireRecord(type, id, store) {
   const record = await store.get(type, id);
   if (!record)

package/dist/lib/cli-help.d.ts

@@ -36,8 +36,9 @@ export interface CreateCliManualOptions {
     /**
      * Predicate deciding whether a top-level command is advertised in the manual.
      * Defaults to advertising everything (local route). In a remote route the
-     * caller passes the authority visibility predicate so the manual never
-     * documents commands the CLI will reject at runtime.
+     * caller passes the authority visibility predicate so the manual describes
+     * the shared authority surface; explicitly named local-only commands select a
+     * separate local route.
      */
     isCommandVisible?: (topLevelCommand: string) => boolean;
     /** Whether the resolved route serves entirely from local state. */

package/dist/lib/cli-help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-help.d.ts","sourceRoot":"","sources":["../../src/lib/cli-help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAEjD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjD,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,eAAO,MAAM,iBAAiB,EAAE,eAAe,EAA4B,CAAC;AAoC5E,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG,eAAe,EAAE,CAenG;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC;IACxD,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAOD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAoBjG;AAMD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CA+DjE;AA+BD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,EACtB,gBAAgB,GAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAoB,GAClE,MAAM,CAwFR"}
+{"version":3,"file":"cli-help.d.ts","sourceRoot":"","sources":["../../src/lib/cli-help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAEjD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjD,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,eAAO,MAAM,iBAAiB,EAAE,eAAe,EAA4B,CAAC;AAoC5E,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG,eAAe,EAAE,CAenG;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC;IACxD,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAOD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAoBjG;AAMD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CA+DjE;AA+BD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,EACtB,gBAAgB,GAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAoB,GAClE,MAAM,CAwFR"}