@hasna/todos 0.15.19 → 0.15.20

package/dist/cli/index.js

@@ -2123,7 +2123,7 @@ var package_default;
 var init_package = __esm(() => {
   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",
@@ -2194,6 +2194,8 @@ var init_package = __esm(() => {
       "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"
     },
@@ -2269,7 +2271,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",
@@ -2392,6 +2394,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";
@@ -5480,6 +5492,7 @@ var init_http_client = __esm(() => {
 // src/cli/cloud-router.ts
 import { resolveStorageClient } from "@hasna/contracts/client/storage";
 import { normalizeStorageMode } from "@hasna/contracts/mode";
+import { randomUUID } from "crypto";
 import { resolve as resolvePath } from "path";
 function cleanMode(value) {
   const normalized = value?.trim().toLowerCase();
@@ -5832,6 +5845,45 @@ async function requestRawCloudTaskPage(client, filter) {
     total: parseCloudTaskTotal(res.raw)
   };
 }
+function cloudPlanTaskListError(planId, detail) {
+  return new Error(`REMOTE_PLAN_TASK_LIST_INCOMPLETE: hosted authority returned an incomplete task set for plan ${planId}; ` + `${detail}; refusing an incomplete plan result`);
+}
+function appendExactPlanTaskPage(target, seen, page, planId) {
+  for (const task of page) {
+    if (task.plan_id !== planId) {
+      throw cloudPlanTaskListError(planId, `response includes task ${task.id} from plan ${task.plan_id ?? "null"}`);
+    }
+    if (seen.has(task.id)) {
+      throw cloudPlanTaskListError(planId, `pagination repeats task id ${task.id}`);
+    }
+    seen.add(task.id);
+    target.push(task);
+  }
+}
+async function cloudListPlanTasks(client, planId) {
+  const filter = { plan_id: planId, include_subtasks: true };
+  const firstPage = await requestRawCloudTaskPage(client, filter);
+  const tasks = [];
+  const seen = new Set;
+  appendExactPlanTaskPage(tasks, seen, firstPage.tasks, planId);
+  if (firstPage.total === undefined)
+    return tasks;
+  const total = firstPage.total;
+  if (tasks.length > total) {
+    throw cloudPlanTaskListError(planId, `first page contains ${tasks.length} rows but reports total ${total}`);
+  }
+  while (tasks.length < total) {
+    const page = await requestRawCloudTaskPage(client, { ...filter, offset: tasks.length });
+    if (page.total !== total) {
+      throw cloudPlanTaskListError(planId, `pagination total changed from ${total} to ${String(page.total)}`);
+    }
+    if (page.tasks.length === 0 || tasks.length + page.tasks.length > total) {
+      throw cloudPlanTaskListError(planId, "pagination did not make bounded progress toward the reported total");
+    }
+    appendExactPlanTaskPage(tasks, seen, page.tasks, planId);
+  }
+  return tasks;
+}
 function cloudTaskListFilterError(code, taskListId, detail) {
   return new Error(`${code}: hosted authority returned rows outside requested task_list_id ${taskListId}; ${detail}; refusing an incomplete exact-list result`);
 }
@@ -5948,7 +6000,10 @@ async function cloudGetTask(client, id) {
 }
 async function cloudCreateTask(client, input) {
   const expectedParentId = typeof input["parent_id"] === "string" ? input["parent_id"] : null;
-  const created = unwrapTask(await requiredRemoteRoute(client, "/v1/tasks", () => client.create("tasks", input, { retry: false }), ["PARENT_TASK_NOT_FOUND"]));
+  const created = unwrapTask(await requiredRemoteRoute(client, "/v1/tasks", () => client.transport.post("/tasks", input, {
+    idempotencyKey: randomUUID(),
+    retry: false
+  }), ["PARENT_TASK_NOT_FOUND"]));
   if (!created || typeof created.id !== "string" || !created.id.trim()) {
     throw new Error(`REMOTE_API_INCOMPATIBLE: configured Todos authority ${remoteAuthorityBase(client)} returned a task create ` + "response without a stored task id; no success row or local SQLite fallback is permitted");
   }
@@ -5959,7 +6014,7 @@ async function cloudCreateTask(client, input) {
   return persisted;
 }
 async function cloudUpdateTask(client, id, patch) {
-  return unwrapTask(await client.update("tasks", id, patch));
+  return unwrapTask(await client.transport.patch(`/tasks/${encodeURIComponent(id)}`, patch));
 }
 async function cloudDeleteTask(client, id) {
   try {
@@ -6710,6 +6765,19 @@ async function cloudUnlockTask(client, id, agentId, force = false) {
   }
   return true;
 }
+async function cloudHandoffStaleTaskLock(client, input) {
+  const raw = await client.transport.post(`/tasks/${encodeURIComponent(input.task_id)}/stale-lock-handoff`, {
+    expected_holder: input.expected_holder,
+    expected_lock_version: input.expected_lock_version,
+    stale_after_seconds: input.stale_after_seconds,
+    new_holder: input.new_holder,
+    reason: input.reason
+  });
+  if (raw && typeof raw === "object" && "receipt" in raw) {
+    return raw.receipt;
+  }
+  throw new Error("STALE_LOCK_HANDOFF_RECEIPT_MISSING: remote response did not include receipt");
+}
 async function cloudGetDependencies(client, id) {
   const raw = await client.transport.get(`/tasks/${encodeURIComponent(id)}/dependencies`);
   const env = raw ?? {};
@@ -7190,6 +7258,12 @@ var init_cloud_router = __esm(() => {
 });
 
 // src/cli/stage-a.ts
+function applyTodosCliAuthorityEnvironment(authority, env = process.env) {
+  if (authority.route !== "local" || authority.selected_by !== "local-only-command")
+    return;
+  env.HASNA_TODOS_STORAGE_MODE = "sqlite";
+  env.TODOS_STORAGE_MODE = "sqlite";
+}
 function isTodosCliCommandVisibleForRoute(command, route) {
   if (route === "local")
     return true;
@@ -7399,7 +7473,7 @@ function nearestCommands(command, limit = 3) {
   const threshold = command.length <= 4 ? 1 : command.length <= 8 ? 2 : 3;
   return [...COMMAND_CAPABILITY_MATRIX.entries()].filter(([, owner]) => owner !== "local-only").map(([candidate]) => candidate).map((candidate) => ({ candidate, distance: editDistance(command, candidate) })).filter(({ distance }) => distance <= threshold).sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate)).slice(0, limit).map(({ candidate }) => candidate);
 }
-function assertRemoteCommandSupported(invocation) {
+function assertInvocationRoutable(invocation) {
   if (invocation.invalidGlobalOption) {
     throw new Error(`REMOTE_COMMAND_UNSUPPORTED: the global option ${invocation.invalidGlobalOption} was given without a value; ` + `pass one as \`${invocation.invalidGlobalOption} <value>\``);
   }
@@ -7413,8 +7487,12 @@ function assertRemoteCommandSupported(invocation) {
     const didYouMean = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : "";
     throw new Error(`UNKNOWN_COMMAND: \`${command}\` is not a built-in todos command on the /v1 route.${didYouMean} ` + "Run `todos --help` for the commands available here; verbs contributed by optional packages are local-only. " + "(This is not a connectivity, storage-mode or credential problem.)");
   }
+  return owner;
+}
+function assertRemoteCommandSupported(invocation, owner) {
+  const command = invocation.command;
   if (command && owner === "local-only") {
-    throw new Error(`REMOTE_COMMAND_UNSUPPORTED: \`${command}\` is a local-only command and the Todos /v1 authority does not ` + "serve it; local SQLite fallback is disabled. Run `todos --help` to see the commands this route supports.");
+    throw new Error(`LOCAL_COMMAND_ROUTING_INVARIANT: \`${command}\` must select the local command route before remote authority validation`);
   }
   if (!command || !commandSupportsRemote(invocation)) {
     const blame = command ? disqualifyingArgument(invocation) : null;
@@ -7432,7 +7510,11 @@ function initializeTodosCliAuthority(args = process.argv.slice(2), env = process
     const status = getTodosRemoteAuthorityConfigStatus(env);
     return { route: "remote-diagnostic", v1_base_url: status.v1_base_url };
   }
-  assertRemoteCommandSupported(invocation);
+  const owner = assertInvocationRoutable(invocation);
+  if (owner === "local-only") {
+    return { route: "local", v1_base_url: null, selected_by: "local-only-command" };
+  }
+  assertRemoteCommandSupported(invocation, owner);
   const client = getTodosCloudClient(env);
   if (!client) {
     throw new Error("REMOTE_API_UNAVAILABLE: remote mode did not resolve an HTTP client; local SQLite fallback is disabled");
@@ -7566,6 +7648,7 @@ var init_stage_a = __esm(() => {
     "sprint",
     "stale",
     "standup",
+    "stale-lock-handoff",
     "start",
     "status",
     "steal",
@@ -7698,6 +7781,7 @@ var init_stage_a = __esm(() => {
     "tag",
     "task",
     "task-lists",
+    "stale-lock-handoff",
     "template-export",
     "template-import",
     "template-preview",
@@ -7705,6 +7789,7 @@ var init_stage_a = __esm(() => {
     "timeline",
     "tl",
     "unlock",
+    "unassign",
     "untag",
     "update"
   ]);
@@ -13590,7 +13675,7 @@ __export(exports_event_hooks, {
   emitLocalEventHooks: () => emitLocalEventHooks,
   LOCAL_EVENT_TYPES: () => LOCAL_EVENT_TYPES
 });
-import { createHash as createHash4, randomUUID } from "crypto";
+import { createHash as createHash4, randomUUID as randomUUID2 } from "crypto";
 import { appendFileSync, mkdirSync as mkdirSync4 } from "fs";
 import { dirname as dirname4, resolve as resolve7 } from "path";
 import { createConnection } from "net";
@@ -13651,7 +13736,7 @@ function canonicalEvent(input) {
 }
 function buildEnvelope(type, payload, timestamp2 = new Date().toISOString()) {
   const base = {
-    id: randomUUID(),
+    id: randomUUID2(),
     type,
     timestamp: timestamp2,
     payload: redactValue(payload ?? {}),
@@ -13854,7 +13939,7 @@ import { existsSync as existsSync6 } from "fs";
 import { homedir as homedir2 } from "os";
 import { join as join5 } from "path";
 import { createHmac, timingSafeEqual } from "crypto";
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { spawn } from "child_process";
 import { randomUUID as randomUUID22 } from "crypto";
 function getPathValue(input, path) {
@@ -14212,7 +14297,7 @@ async function dispatchChannel(event, channel, options = {}) {
 function createDeliveryResult(event, channel, attempts) {
   const status = attempts.some((attempt) => attempt.status === "success") ? "success" : attempts.every((attempt) => attempt.status === "skipped") ? "skipped" : "failed";
   return {
-    id: randomUUID2(),
+    id: randomUUID3(),
     eventId: event.id,
     channelId: channel.id,
     transport: channel.transport,
@@ -15214,6 +15299,7 @@ var init_activity_audit = __esm(() => {
 var exports_audit = {};
 __export(exports_audit, {
   logTaskChange: () => logTaskChange,
+  insertTaskHistory: () => insertTaskHistory,
   getTaskHistory: () => getTaskHistory,
   getRecentActivity: () => getRecentActivity,
   getRecap: () => getRecap
@@ -15221,28 +15307,55 @@ __export(exports_audit, {
 function sanitizeHistoryValue(value, context) {
   return value === undefined || value === null ? null : sanitizePreWriteText(String(value), context);
 }
-function logTaskChange(taskId, action, field, 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, field || 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,
-      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: field || null, old_value: safeOldValue, new_value: safeNewValue, agent_id: agentId || null, created_at: timestamp2, machine_id: machineId };
+  return safeEntry;
+}
+function logTaskChange(taskId, action, field, oldValue, newValue, agentId, db) {
+  const d = db || getDatabase();
+  return insertTaskHistory({
+    id: uuid(),
+    task_id: taskId,
+    action,
+    field: field || 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();
@@ -16303,6 +16416,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, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", `${field} must be a non-empty string`, { field });
+  }
+  const trimmed = value.trim();
+  if (field === "reason" && trimmed.length > MAX_REASON_LENGTH) {
+    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", `reason must be at most ${MAX_REASON_LENGTH} characters`, { field, 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, {
@@ -16311,6 +16563,7 @@ __export(exports_task_lifecycle, {
   startTask: () => startTask,
   spawnNextRecurrence: () => spawnNextRecurrence,
   lockTask: () => lockTask,
+  handoffStaleTaskLock: () => handoffStaleTaskLock,
   getTasksChangedSince: () => getTasksChangedSince,
   getTaskLockStatus: () => getTaskLockStatus,
   getStaleTasks: () => getStaleTasks,
@@ -16579,6 +16832,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);
@@ -16879,6 +17164,7 @@ var init_task_lifecycle = __esm(() => {
   init_task_crud();
   init_task_graph();
   init_prewrite_secrets();
+  init_stale_lock_handoff();
 });
 
 // src/db/task-crud.ts
@@ -20488,6 +20774,7 @@ __export(exports_tasks, {
   insertTaskTags: () => insertTaskTags,
   importTaskBoardBundle: () => importTaskBoardBundle,
   importCalendarIcs: () => importCalendarIcs,
+  handoffStaleTaskLock: () => handoffStaleTaskLock,
   getTimeReport: () => getTimeReport,
   getTimeLogs: () => getTimeLogs,
   getTasksChangedSince: () => getTasksChangedSince,
@@ -22130,7 +22417,7 @@ function registerTaskCommands(program2) {
     }
   });
   const task = program2.command("task").description("Task subcommands for deterministic automation");
-  task.command("upsert").description("Create or update a task by stable metadata fingerprint").requiredOption("--fingerprint <key>", "Stable dedupe fingerprint").requiredOption("--title <text>", "Task title").option("-d, --description <text>", "Task description").option("-p, --priority <level>", "Priority: low, medium, high, critical").option("-s, --status <status>", "Task status").option("--list <id>", "Task list ID").option("--task-list <id>", "Task list ID (alias for --list)").option("-t, --tags <tags>", "Comma-separated tags").option("--tag <tags>", "Comma-separated tags (alias for --tags)").option("--metadata-json <json>", "JSON object merged into task metadata").option("--working-dir <path>", "Working directory to store on create/update").option("--project <id>", "Assign to project by ID, slug, or path").option("--assign <agent>", "Assign to agent").option("--assign-seat", "Allow --assign to name a durable seat (a seat queue has no session watching it)").option("--expectation-id <id>", "Expectation metadata ID").option("--expectation-fingerprint <key>", "Expectation metadata fingerprint").option("--evidence-paths <paths>", "Comma-separated evidence paths").option("--origin-loop-id <id>", "Origin loop ID").option("--origin-run-id <id>", "Origin run ID").option("--expected <json-or-text>", "Expected value metadata").option("--observed <json-or-text>", "Observed value metadata").option("--acceptance <json-or-text>", "Acceptance metadata").action(async (opts) => {
+  task.command("upsert").description("Create or update a task by stable metadata fingerprint").requiredOption("--fingerprint <key>", "Stable dedupe fingerprint").requiredOption("--title <text>", "Task title").option("-d, --description <text>", "Task description").option("-p, --priority <level>", "Priority: low, medium, high, critical").option("-s, --status <status>", "Task status").option("--list <id>", "Task list ID").option("--task-list <id>", "Task list ID (alias for --list)").option("--plan <id>", "Assign to a plan").option("-t, --tags <tags>", "Comma-separated tags").option("--tag <tags>", "Comma-separated tags (alias for --tags)").option("--metadata-json <json>", "JSON object merged into task metadata").option("--working-dir <path>", "Working directory to store on create/update").option("--project <id>", "Assign to project by ID, slug, or path").option("--assign <agent>", "Assign to agent").option("--assign-seat", "Allow --assign to name a durable seat (a seat queue has no session watching it)").option("--expectation-id <id>", "Expectation metadata ID").option("--expectation-fingerprint <key>", "Expectation metadata fingerprint").option("--evidence-paths <paths>", "Comma-separated evidence paths").option("--origin-loop-id <id>", "Origin loop ID").option("--origin-run-id <id>", "Origin run ID").option("--expected <json-or-text>", "Expected value metadata").option("--observed <json-or-text>", "Observed value metadata").option("--acceptance <json-or-text>", "Acceptance metadata").action(async (opts) => {
     const globalOpts = program2.opts();
     opts.tags = opts.tags || opts.tag;
     opts.list = opts.list || opts.taskList;
@@ -22144,6 +22431,10 @@ function registerTaskCommands(program2) {
       try {
         const projectId2 = explicitProject ? await cloudResolveProjectRef(cloud, explicitProject) : undefined;
         const taskListId2 = opts.list ? await cloudResolveTaskListRef(cloud, opts.list, projectId2) : undefined;
+        const plan = opts.plan ? await cloudResolvePlan(cloud, opts.plan, projectId2) : null;
+        if (opts.plan && !plan) {
+          throw new Error(`Could not resolve plan ID or slug: ${opts.plan}`);
+        }
         cloudResult = await cloudUpsertTaskByFingerprint(cloud, {
           fingerprint: opts.fingerprint,
           title: opts.title,
@@ -22155,7 +22446,8 @@ function registerTaskCommands(program2) {
           metadata: buildExpectationMetadata(opts),
           working_dir: opts.workingDir ? resolve9(opts.workingDir) : process.cwd(),
           project_id: projectId2,
-          assigned_to: opts.assign
+          assigned_to: opts.assign,
+          plan_id: plan?.id
         });
       } catch (e) {
         handleError(e);
@@ -22177,6 +22469,7 @@ function registerTaskCommands(program2) {
       }
       return id;
     })() : undefined;
+    const planId = opts.plan ? resolvePlanId(opts.plan) : undefined;
     let result;
     try {
       result = upsertTaskByFingerprint({
@@ -22191,6 +22484,7 @@ function registerTaskCommands(program2) {
         working_dir: opts.workingDir ? resolve9(opts.workingDir) : process.cwd(),
         project_id: projectId,
         assigned_to: opts.assign,
+        plan_id: planId,
         agent_id: globalOpts.agent,
         session_id: globalOpts.session
       });
@@ -23184,6 +23478,44 @@ ${chalk3.cyan(sid)} ${statusColor(task2.status)} ${prioColor(task2.priority)} ${
       console.log(chalk3.green("Lock released."));
     }
   });
+  program2.command("stale-lock-handoff <id>").description("Atomically transfer one exact stale lock by holder and locked_at version").requiredOption("--expected-holder <agent>", "Exact current locked_by value").requiredOption("--expected-lock-version <timestamp>", "Exact current locked_at value (canonical UTC)").requiredOption("--stale-after-seconds <seconds>", "Required lock age threshold; no default").requiredOption("--new-holder <agent>", "New holder; must match the authenticated/--agent identity").requiredOption("--reason <text>", "Non-empty audit reason").action(async (id, opts) => {
+    const globalOpts = program2.opts();
+    const taskId = normalizeExactTaskId(id);
+    const actor = resolveClaimIdentity("handoff a stale lock on", globalOpts.agent);
+    const staleAfterSeconds = Number(opts.staleAfterSeconds);
+    const cloud = getTodosCloudClient();
+    let receipt;
+    try {
+      receipt = cloud ? await cloudHandoffStaleTaskLock(cloud, {
+        task_id: taskId,
+        expected_holder: opts.expectedHolder,
+        expected_lock_version: opts.expectedLockVersion,
+        stale_after_seconds: staleAfterSeconds,
+        new_holder: opts.newHolder,
+        reason: opts.reason
+      }) : handoffStaleTaskLock({
+        task_id: taskId,
+        actor,
+        expected_holder: opts.expectedHolder,
+        expected_lock_version: opts.expectedLockVersion,
+        stale_after_seconds: staleAfterSeconds,
+        new_holder: opts.newHolder,
+        reason: opts.reason
+      });
+    } catch (e) {
+      handleError(e);
+    }
+    if (globalOpts.json) {
+      output({ receipt }, true);
+      return;
+    }
+    console.log(chalk3.green(`Stale lock transferred on task ${escapeTerminalControls(receipt.task_id)}.`));
+    console.log(`  ${escapeTerminalControls(receipt.previous_holder)} @ ${escapeTerminalControls(receipt.previous_lock_version)}`);
+    console.log(`  -> ${escapeTerminalControls(receipt.new_holder)} @ ${escapeTerminalControls(receipt.new_lock_version)}`);
+    console.log(`  stale after ${receipt.stale_after_seconds}s (cutoff ${escapeTerminalControls(receipt.stale_cutoff)})`);
+    console.log(`  receipt ${escapeTerminalControls(receipt.receipt_id)}`);
+    console.log(`  reason ${escapeTerminalControls(receipt.reason)}`);
+  });
   program2.command("delete <id>").description("Delete a task").action(async (id) => {
     const globalOpts = program2.opts();
     const cloud = getTodosCloudClient();
@@ -23368,6 +23700,7 @@ var init_task_commands = __esm(() => {
   init_agents();
   init_helpers();
   init_output_redaction();
+  init_stale_lock_handoff();
 });
 
 // src/lib/plan-artifacts.ts
@@ -24355,6 +24688,58 @@ var init_plan_project_links = __esm(() => {
   init_tasks();
 });
 
+// src/storage/audit-history-import.ts
+function auditHistoryRowsAreFieldIdentical(left, right) {
+  return AUDIT_HISTORY_FIELDS.every((field) => {
+    const leftValue = field === "machine_id" ? left[field] ?? null : left[field];
+    const rightValue = field === "machine_id" ? right[field] ?? null : right[field];
+    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`;
+}
+function parseAuditHistoryImportFailure(message) {
+  const divergentPrefix = `${AUDIT_HISTORY_DIVERGENT_REPLAY}: immutable audit_history row `;
+  const divergentSuffix = " differs from stored row";
+  if (message.startsWith(divergentPrefix) && message.endsWith(divergentSuffix)) {
+    return {
+      code: AUDIT_HISTORY_DIVERGENT_REPLAY,
+      auditHistoryId: message.slice(divergentPrefix.length, -divergentSuffix.length),
+      conflict: true,
+      status: 409
+    };
+  }
+  const tombstonePrefix = `${AUDIT_HISTORY_TOMBSTONE_FORBIDDEN}: audit_history tombstone `;
+  const tombstoneSuffix = " is not allowed";
+  if (message.startsWith(tombstonePrefix) && message.endsWith(tombstoneSuffix)) {
+    return {
+      code: AUDIT_HISTORY_TOMBSTONE_FORBIDDEN,
+      auditHistoryId: message.slice(tombstonePrefix.length, -tombstoneSuffix.length),
+      conflict: false,
+      status: 400
+    };
+  }
+  return null;
+}
+var AUDIT_HISTORY_DIVERGENT_REPLAY = "AUDIT_HISTORY_DIVERGENT_REPLAY", AUDIT_HISTORY_TOMBSTONE_FORBIDDEN = "AUDIT_HISTORY_TOMBSTONE_FORBIDDEN", AUDIT_HISTORY_FIELDS;
+var init_audit_history_import = __esm(() => {
+  AUDIT_HISTORY_FIELDS = [
+    "id",
+    "task_id",
+    "action",
+    "field",
+    "old_value",
+    "new_value",
+    "agent_id",
+    "created_at",
+    "machine_id"
+  ];
+});
+
 // src/storage/sqlite-snapshot.ts
 function exportSqliteTodosStorageSnapshot(db) {
   const d = db ?? getDatabase();
@@ -24388,8 +24773,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 {
@@ -24424,10 +24812,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 = asRecord(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 = asRecord(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)
@@ -24525,7 +24975,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();
@@ -24572,6 +25022,7 @@ var init_sqlite_snapshot = __esm(() => {
   init_tasks();
   init_templates();
   init_storage_tombstones();
+  init_audit_history_import();
   PROJECT_COLUMNS = [
     "id",
     "name",
@@ -24836,6 +25287,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),
@@ -25592,7 +26044,7 @@ function registerPlanTemplateCommands(program2) {
         if (!plan2) {
           handleError(new Error(`Plan not found: ${opts.show}`));
         }
-        const tasks2 = await cloudListTasks(cloud, { plan_id: plan2.id, include_subtasks: true });
+        const tasks2 = await cloudListPlanTasks(cloud, plan2.id);
         if (globalOpts.json) {
           output({ plan: plan2, tasks: tasks2, artifact: null }, true);
           return;
@@ -34444,7 +34896,7 @@ var init_postgres_sync = __esm(() => {
 });
 
 // src/storage/postgres-adapter.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 function createPostgresTodosStorageAdapter(options) {
   const store = new PostgresJsonRecordStore(options);
   const adapter = {
@@ -34473,6 +34925,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: (fingerprint) => store.getTaskByFingerprint(fingerprint)
     },
     dependencies: {
@@ -34619,6 +35072,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);
   }
@@ -34888,6 +35426,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)
@@ -35714,7 +36274,7 @@ async function createTask2(input, store, context) {
   const effectiveProjectId = linkedPlan?.project_id ?? requestedProjectId;
   const shortId = effectiveProjectId ? await nextTaskShortId2(effectiveProjectId, store, context) : null;
   const task = {
-    id: randomUUID3(),
+    id: randomUUID4(),
     short_id: shortId,
     project_id: effectiveProjectId,
     parent_id: input.parent_id ?? null,
@@ -35960,7 +36520,7 @@ async function addVerification(input, store, context) {
     throw new Error(`Task not found: ${input.task_id}`);
   const timestamp2 = new Date().toISOString();
   const verification = {
-    id: randomUUID3(),
+    id: randomUUID4(),
     task_id: input.task_id,
     command: input.command,
     status: input.status ?? "unknown",
@@ -35981,7 +36541,7 @@ async function addCommit(input, store, context) {
     throw new Error(`Task not found: ${input.task_id}`);
   const timestamp2 = new Date().toISOString();
   const commit = {
-    id: randomUUID3(),
+    id: randomUUID4(),
     task_id: input.task_id,
     sha: input.sha,
     message: input.message ?? null,
@@ -36004,7 +36564,7 @@ async function addGitRef(input, store, context) {
     throw new Error(`Task not found: ${input.task_id}`);
   const timestamp2 = new Date().toISOString();
   const gitRef = {
-    id: randomUUID3(),
+    id: randomUUID4(),
     task_id: input.task_id,
     ref_type: input.ref_type,
     name: input.name,
@@ -36074,7 +36634,7 @@ async function createProject2(input, store, context) {
   if (!derivedSlug || !taskListId)
     throw new Error("Project name and task-list slug must be non-empty");
   const project = {
-    id: randomUUID3(),
+    id: randomUUID4(),
     name: input.name,
     path: input.path,
     description: input.description ?? null,
@@ -36106,7 +36666,7 @@ async function createPlan2(input, store, context) {
     store
   });
   return store.upsert("plans", {
-    id: randomUUID3(),
+    id: randomUUID4(),
     slug,
     project_id: projectId,
     task_list_id: input.task_list_id ?? context?.taskListId ?? null,
@@ -36158,7 +36718,7 @@ async function registerAgent2(input, store, context) {
   }
   const timestamp2 = new Date().toISOString();
   const agent = {
-    id: existing?.id ?? randomUUID3().slice(0, 8),
+    id: existing?.id ?? randomUUID4().slice(0, 8),
     name: canonicalName,
     description: input.description ?? existing?.description ?? null,
     role: input.role ?? existing?.role ?? null,
@@ -36231,7 +36791,7 @@ async function createTaskList2(input, store, context) {
   if (!slug)
     throw new Error("Invalid task-list slug \u2014 must be non-empty kebab-case");
   return store.upsert("task_lists", {
-    id: randomUUID3(),
+    id: randomUUID4(),
     project_id: input.project_id ?? context?.projectId ?? null,
     slug,
     name: input.name,
@@ -36266,7 +36826,7 @@ async function updateTaskList2(id, input, store) {
 async function createTemplate2(input, store, context) {
   const timestamp2 = new Date().toISOString();
   const template = {
-    id: randomUUID3(),
+    id: randomUUID4(),
     name: input.name,
     title_pattern: input.title_pattern,
     description: input.description ?? null,
@@ -36287,7 +36847,7 @@ async function createTemplate2(input, store, context) {
 }
 function buildTemplateTasks(templateId, inputs, timestamp2) {
   return inputs.map((input, position) => ({
-    id: randomUUID3(),
+    id: randomUUID4(),
     template_id: templateId,
     position,
     title_pattern: input.title_pattern,
@@ -36320,7 +36880,7 @@ async function updateTemplate2(id, input, store) {
 }
 async function logTaskChange2(taskId, action, field, oldValue, newValue, agentId, store, context) {
   const entry2 = {
-    id: randomUUID3(),
+    id: randomUUID4(),
     task_id: taskId,
     action,
     field: field ?? null,
@@ -36334,7 +36894,7 @@ async function logTaskChange2(taskId, action, field, oldValue, newValue, agentId
 }
 async function addComment2(input, store, context) {
   const comment = {
-    id: randomUUID3(),
+    id: randomUUID4(),
     task_id: input.task_id,
     agent_id: input.agent_id ?? context?.agentId ?? null,
     session_id: input.session_id ?? context?.sessionId ?? null,
@@ -36376,6 +36936,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]),
@@ -36384,9 +36949,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);
@@ -36420,6 +36996,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)
@@ -36526,9 +37128,11 @@ var init_postgres_adapter = __esm(() => {
   init_types();
   init_creator_identity();
   init_plan_project_link_contract();
+  init_stale_lock_handoff();
   init_postgres_sync();
   init_integrity();
   init_redaction();
+  init_audit_history_import();
   TASK_ORDER_BY = `ORDER BY ${TASK_ORDER_TIEBREAK}`;
 });
 
@@ -46532,6 +47136,8 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
         ProjectTaskListEnsureResult: projectTaskListEnsureResultSchema,
         ProjectTaskListRollbackResult: projectTaskListRollbackResultSchema,
         TaskComment: taskCommentSchema,
+        StaleLockHandoffInput: staleLockHandoffInputSchema,
+        StaleLockHandoffReceipt: staleLockHandoffReceiptSchema,
         TaskGitRef: taskGitRefSchema,
         Plan: planSchema,
         PlanProjectLinkReceipt: planProjectLinkReceiptSchema,
@@ -47739,6 +48345,51 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
           }
         }
       },
+      "/v1/tasks/{id}/stale-lock-handoff": {
+        post: {
+          operationId: "handoffStaleTaskLock",
+          summary: "Atomically transfer one exact stale task lock",
+          description: "Compares one full task UUID, current holder, and exact locked_at version, verifies the lock is strictly older than the supplied threshold, then transfers it directly and writes an immutable task-history receipt in the same backend transaction.",
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              schema: { type: "string", format: "uuid" },
+              description: "Exact full task UUID. Short ids and prefixes are rejected."
+            }
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/StaleLockHandoffInput" }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["receipt"],
+                    properties: {
+                      receipt: { $ref: "#/components/schemas/StaleLockHandoffReceipt" }
+                    }
+                  }
+                }
+              }
+            },
+            "400": { content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } } },
+            "403": { content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } } },
+            "404": { content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } } },
+            "409": { content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } } },
+            "501": { content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } } }
+          }
+        }
+      },
       "/v1/tasks/{id}/refs": {
         get: {
           operationId: "listTaskGitRefs",
@@ -48335,7 +48986,7 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
     }
   };
 }
-var taskSchema, projectSchema, taskManifestBindingLookupRequestSchema, taskManifestBindingLookupResultSchema, taskManifestBindingLookupResponseSchema, taskListSchema, projectTaskListEnsureReceiptSchema, projectTaskListEnsureResultSchema, projectTaskListRollbackResultSchema, taskCommentSchema, taskGitRefSchema, planSchema, planProjectLinkReceiptSchema, planProjectLinkResultSchema, planProjectLinkRollbackResultSchema, templateTaskSchema, templateSchema, templateVariableSchema, createTemplateTaskInputSchema;
+var taskSchema, projectSchema, taskManifestBindingLookupRequestSchema, taskManifestBindingLookupResultSchema, taskManifestBindingLookupResponseSchema, taskListSchema, projectTaskListEnsureReceiptSchema, projectTaskListEnsureResultSchema, projectTaskListRollbackResultSchema, taskCommentSchema, staleLockHandoffInputSchema, staleLockHandoffReceiptSchema, taskGitRefSchema, planSchema, planProjectLinkReceiptSchema, planProjectLinkResultSchema, planProjectLinkRollbackResultSchema, templateTaskSchema, templateSchema, templateVariableSchema, createTemplateTaskInputSchema;
 var init_openapi = __esm(() => {
   init_package_version();
   init_types();
@@ -48354,6 +49005,8 @@ var init_openapi = __esm(() => {
       reason: { type: "string", nullable: true },
       tags: { type: "array", items: { type: "string" } },
       version: { type: "number" },
+      locked_by: { type: "string", nullable: true },
+      locked_at: { type: "string", format: "date-time", nullable: true },
       created_at: { type: "string" },
       updated_at: { type: "string" }
     }
@@ -48518,6 +49171,69 @@ var init_openapi = __esm(() => {
       created_at: { type: "string", format: "date-time" }
     }
   };
+  staleLockHandoffInputSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "expected_holder",
+      "expected_lock_version",
+      "stale_after_seconds",
+      "new_holder",
+      "reason"
+    ],
+    properties: {
+      expected_holder: { type: "string", minLength: 1 },
+      expected_lock_version: {
+        type: "string",
+        format: "date-time",
+        pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
+        description: "Exact authoritative locked_at token read from the task; no default or normalization is applied."
+      },
+      stale_after_seconds: {
+        type: "integer",
+        minimum: 1,
+        description: "Lock age threshold supplied by the caller. The lock must be strictly older at the CAS instant."
+      },
+      new_holder: {
+        type: "string",
+        minLength: 1,
+        description: "Must match the agent bound to the authenticated API key."
+      },
+      reason: { type: "string", minLength: 1, maxLength: 4096 }
+    }
+  };
+  staleLockHandoffReceiptSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "schema_version",
+      "receipt_id",
+      "task_id",
+      "actor",
+      "previous_holder",
+      "previous_lock_version",
+      "new_holder",
+      "new_lock_version",
+      "stale_after_seconds",
+      "stale_cutoff",
+      "reason",
+      "created_at"
+    ],
+    properties: {
+      schema_version: { type: "string", enum: ["todos.stale-lock-handoff.v1"] },
+      receipt_id: { type: "string", format: "uuid" },
+      task_id: { type: "string", format: "uuid" },
+      actor: { type: "string" },
+      previous_holder: { type: "string" },
+      previous_lock_version: { type: "string", format: "date-time" },
+      new_holder: { type: "string" },
+      new_lock_version: { type: "string", format: "date-time" },
+      stale_after_seconds: { type: "integer", minimum: 1 },
+      stale_cutoff: { type: "string", format: "date-time" },
+      reason: { type: "string" },
+      created_at: { type: "string", format: "date-time" }
+    }
+  };
   taskGitRefSchema = {
     type: "object",
     additionalProperties: false,
@@ -49412,6 +50128,45 @@ async function handleV1Request(req, url, dependencies = {}) {
         return error(405, `method ${method} not allowed on /v1/tasks`);
       }
       if (action) {
+        if (action === "stale-lock-handoff") {
+          if (method !== "POST") {
+            return error(405, "method must be POST on /v1/tasks/:id/stale-lock-handoff");
+          }
+          const exactId = normalizeExactTaskId(id);
+          if (!principal.agent) {
+            return error(403, "stale-lock handoff requires an authenticated agent-bound key", {
+              code: "STALE_LOCK_HANDOFF_ACTOR_MISMATCH"
+            });
+          }
+          if (typeof store.tasks.handoffStaleLock !== "function") {
+            return error(501, "stale-lock handoff is not supported by this storage backend");
+          }
+          const body3 = await readJson3(req) ?? {};
+          const allowed = new Set([
+            "expected_holder",
+            "expected_lock_version",
+            "stale_after_seconds",
+            "new_holder",
+            "reason"
+          ]);
+          const unknown = Object.keys(body3).find((key2) => !allowed.has(key2));
+          if (unknown) {
+            return error(400, `unknown stale-lock handoff field: ${unknown}`, {
+              code: "STALE_LOCK_HANDOFF_INVALID_INPUT",
+              field: unknown
+            });
+          }
+          const receipt = await store.tasks.handoffStaleLock({
+            task_id: exactId,
+            actor: principal.agent,
+            expected_holder: body3.expected_holder,
+            expected_lock_version: body3.expected_lock_version,
+            stale_after_seconds: body3.stale_after_seconds,
+            new_holder: body3.new_holder,
+            reason: body3.reason
+          }, contextFromPrincipal(principal));
+          return json5({ receipt });
+        }
         if (action === "comments") {
           if (method === "GET") {
             if (!await store.tasks.get(id))
@@ -50200,7 +50955,24 @@ async function handleV1Request(req, url, dependencies = {}) {
       if (received === 0) {
         return error(400, "empty snapshot: provide at least one record array (tasks/projects/plans/...)");
       }
+      const forbiddenAuditTombstone = (snapshot.tombstones ?? []).find((tombstone) => tombstone.object_type === "audit_history");
+      if (forbiddenAuditTombstone) {
+        return error(400, forbiddenAuditHistoryTombstoneError(forbiddenAuditTombstone.object_id), {
+          code: AUDIT_HISTORY_TOMBSTONE_FORBIDDEN,
+          conflict: false,
+          audit_history_id: forbiddenAuditTombstone.object_id
+        });
+      }
       const result = await store.sync.importSnapshot(snapshot, contextFromPrincipal(principal));
+      const auditFailureMessage = result.errors.find((message) => parseAuditHistoryImportFailure(message) !== null);
+      if (auditFailureMessage) {
+        const failure = parseAuditHistoryImportFailure(auditFailureMessage);
+        return error(failure.status, auditFailureMessage, {
+          code: failure.code,
+          conflict: failure.conflict,
+          audit_history_id: failure.auditHistoryId
+        });
+      }
       return json5({ result, received });
     }
     return error(404, `unknown /v1 resource: ${resource ?? "(root)"}`);
@@ -50223,6 +50995,14 @@ async function handleV1Request(req, url, dependencies = {}) {
     if (e instanceof TaskNotFoundError) {
       return error(404, e.message, { code: TaskNotFoundError.code });
     }
+    if (e instanceof StaleLockHandoffError) {
+      const status2 = e.code === "STALE_LOCK_HANDOFF_INVALID_TASK_ID" || e.code === "STALE_LOCK_HANDOFF_INVALID_INPUT" ? 400 : e.code === "STALE_LOCK_HANDOFF_ACTOR_MISMATCH" ? 403 : 409;
+      return error(status2, e.message, {
+        code: e.code,
+        conflict: status2 === 409,
+        ...e.details
+      });
+    }
     if (e instanceof PlanNotFoundError) {
       return error(404, e.message, { code: PlanNotFoundError.code });
     }
@@ -50257,6 +51037,8 @@ var init_v1 = __esm(() => {
   init_redaction();
   init_project_task_list_ensure();
   init_plan_project_link();
+  init_stale_lock_handoff();
+  init_audit_history_import();
   JSON_HEADERS4 = { "Content-Type": "application/json" };
   RFC3339_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
 });
@@ -75778,8 +76560,29 @@ No task claimed (nothing available).`));
       handleError(new Error("Failed to assign"));
     }
   });
-  program2.command("unassign <id>").description("Remove task assignment").option("-j, --json", "Output as JSON").action((id, opts) => {
+  program2.command("unassign <id>").description("Remove task assignment").option("-j, --json", "Output as JSON").action(async (id, opts) => {
     const globalOpts = program2.opts();
+    const cloud = getTodosCloudClient();
+    if (cloud) {
+      try {
+        const resolvedId2 = await resolveTaskIdForCommand(id, cloud);
+        const task4 = await cloudGetTask(cloud, resolvedId2);
+        if (!task4) {
+          throw new Error(`Task not found: ${id}`);
+        }
+        const updated = await cloudUpdateTask(cloud, resolvedId2, {
+          assigned_to: null
+        });
+        if (opts.json || globalOpts.json) {
+          console.log(JSON.stringify(updated));
+          return;
+        }
+        console.log(chalk9.green(`Unassigned: ${formatTaskLine(updated)}`));
+      } catch (error2) {
+        handleError(error2);
+      }
+      return;
+    }
     const resolvedId = resolveTaskId(id);
     const db = getDatabase();
     const task3 = getTask(resolvedId, db);
@@ -88241,6 +89044,7 @@ program2.name("todos").description("Universal task management for AI coding agen
 var authority;
 try {
   authority = initializeTodosCliAuthority();
+  applyTodosCliAuthorityEnvironment(authority);
 } catch (error2) {
   console.error(error2 instanceof Error ? error2.message : String(error2));
   process.exit(1);