@hasna/todos 0.9.34 → 0.9.35

package/dist/cli/index.js

@@ -2258,6 +2258,8 @@ function ensureSchema(db) {
   ensureColumn("tasks", "requires_approval", "INTEGER NOT NULL DEFAULT 0");
   ensureColumn("tasks", "approved_by", "TEXT");
   ensureColumn("tasks", "approved_at", "TEXT");
+  ensureColumn("tasks", "recurrence_rule", "TEXT");
+  ensureColumn("tasks", "recurrence_parent_id", "TEXT REFERENCES tasks(id) ON DELETE SET NULL");
   ensureColumn("agents", "role", "TEXT DEFAULT 'agent'");
   ensureColumn("agents", "permissions", `TEXT DEFAULT '["*"]'`);
   ensureColumn("agents", "reports_to", "TEXT");
@@ -2282,6 +2284,8 @@ function ensureSchema(db) {
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_plans_agent ON plans(agent_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_history_task ON task_history(task_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_history_agent ON task_history(agent_id)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_tasks_recurrence_parent ON tasks(recurrence_parent_id)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_tasks_recurrence_rule ON tasks(recurrence_rule) WHERE recurrence_rule IS NOT NULL");
 }
 function backfillTaskTags(db) {
   try {
@@ -2581,17 +2585,26 @@ var init_database = __esm(() => {
   ALTER TABLE agents ADD COLUMN org_id TEXT REFERENCES orgs(id) ON DELETE SET NULL;
   ALTER TABLE projects ADD COLUMN org_id TEXT REFERENCES orgs(id) ON DELETE SET NULL;
   INSERT OR IGNORE INTO _migrations (id) VALUES (12);
+  `,
+    `
+  ALTER TABLE tasks ADD COLUMN recurrence_rule TEXT;
+  ALTER TABLE tasks ADD COLUMN recurrence_parent_id TEXT REFERENCES tasks(id) ON DELETE SET NULL;
+  CREATE INDEX IF NOT EXISTS idx_tasks_recurrence_parent ON tasks(recurrence_parent_id);
+  CREATE INDEX IF NOT EXISTS idx_tasks_recurrence_rule ON tasks(recurrence_rule) WHERE recurrence_rule IS NOT NULL;
+  INSERT OR IGNORE INTO _migrations (id) VALUES (13);
   `
   ];
 });
 
 // src/types/index.ts
-var VersionConflictError, TaskNotFoundError, ProjectNotFoundError, PlanNotFoundError, LockError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError;
+var VersionConflictError, TaskNotFoundError, ProjectNotFoundError, PlanNotFoundError, LockError, AgentNotFoundError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError;
 var init_types = __esm(() => {
   VersionConflictError = class VersionConflictError extends Error {
     taskId;
     expectedVersion;
     actualVersion;
+    static code = "VERSION_CONFLICT";
+    static suggestion = "Fetch the task with get_task to get the current version before updating.";
     constructor(taskId, expectedVersion, actualVersion) {
       super(`Version conflict for task ${taskId}: expected ${expectedVersion}, got ${actualVersion}`);
       this.taskId = taskId;
@@ -2602,6 +2615,8 @@ var init_types = __esm(() => {
   };
   TaskNotFoundError = class TaskNotFoundError extends Error {
     taskId;
+    static code = "TASK_NOT_FOUND";
+    static suggestion = "Verify the task ID. Use list_tasks or search_tasks to find the correct ID.";
     constructor(taskId) {
       super(`Task not found: ${taskId}`);
       this.taskId = taskId;
@@ -2610,6 +2625,8 @@ var init_types = __esm(() => {
   };
   ProjectNotFoundError = class ProjectNotFoundError extends Error {
     projectId;
+    static code = "PROJECT_NOT_FOUND";
+    static suggestion = "Use list_projects to see available projects.";
     constructor(projectId) {
       super(`Project not found: ${projectId}`);
       this.projectId = projectId;
@@ -2618,6 +2635,8 @@ var init_types = __esm(() => {
   };
   PlanNotFoundError = class PlanNotFoundError extends Error {
     planId;
+    static code = "PLAN_NOT_FOUND";
+    static suggestion = "Use list_plans to see available plans.";
     constructor(planId) {
       super(`Plan not found: ${planId}`);
       this.planId = planId;
@@ -2627,6 +2646,8 @@ var init_types = __esm(() => {
   LockError = class LockError extends Error {
     taskId;
     lockedBy;
+    static code = "LOCK_ERROR";
+    static suggestion = "Wait for the lock to expire (30 min) or contact the lock holder.";
     constructor(taskId, lockedBy) {
       super(`Task ${taskId} is locked by ${lockedBy}`);
       this.taskId = taskId;
@@ -2634,8 +2655,20 @@ var init_types = __esm(() => {
       this.name = "LockError";
     }
   };
+  AgentNotFoundError = class AgentNotFoundError extends Error {
+    agentId;
+    static code = "AGENT_NOT_FOUND";
+    static suggestion = "Use register_agent to create the agent first, or list_agents to find existing ones.";
+    constructor(agentId) {
+      super(`Agent not found: ${agentId}`);
+      this.agentId = agentId;
+      this.name = "AgentNotFoundError";
+    }
+  };
   TaskListNotFoundError = class TaskListNotFoundError extends Error {
     taskListId;
+    static code = "TASK_LIST_NOT_FOUND";
+    static suggestion = "Use list_task_lists to see available lists.";
     constructor(taskListId) {
       super(`Task list not found: ${taskListId}`);
       this.taskListId = taskListId;
@@ -2645,6 +2678,8 @@ var init_types = __esm(() => {
   DependencyCycleError = class DependencyCycleError extends Error {
     taskId;
     dependsOn;
+    static code = "DEPENDENCY_CYCLE";
+    static suggestion = "Check the dependency chain with get_task to avoid circular references.";
     constructor(taskId, dependsOn) {
       super(`Adding dependency ${taskId} -> ${dependsOn} would create a cycle`);
       this.taskId = taskId;
@@ -2655,6 +2690,8 @@ var init_types = __esm(() => {
   CompletionGuardError = class CompletionGuardError extends Error {
     reason;
     retryAfterSeconds;
+    static code = "COMPLETION_BLOCKED";
+    static suggestion = "Wait for the cooldown period, then retry.";
     constructor(reason, retryAfterSeconds) {
       super(reason);
       this.reason = reason;
@@ -2974,6 +3011,96 @@ var init_audit = __esm(() => {
   init_database();
 });
 
+// src/lib/recurrence.ts
+function parseRecurrenceRule(rule) {
+  const normalized = rule.trim().toLowerCase();
+  if (normalized === "every weekday" || normalized === "every weekdays") {
+    return { type: "specific_days", days: [1, 2, 3, 4, 5] };
+  }
+  if (normalized === "every day" || normalized === "daily") {
+    return { type: "interval", interval: 1, unit: "day" };
+  }
+  if (normalized === "every week" || normalized === "weekly") {
+    return { type: "interval", interval: 1, unit: "week" };
+  }
+  if (normalized === "every month" || normalized === "monthly") {
+    return { type: "interval", interval: 1, unit: "month" };
+  }
+  const intervalMatch = normalized.match(/^every\s+(\d+)\s+(day|week|month)s?$/);
+  if (intervalMatch) {
+    return {
+      type: "interval",
+      interval: parseInt(intervalMatch[1], 10),
+      unit: intervalMatch[2]
+    };
+  }
+  const daysMatch = normalized.match(/^every\s+(.+)$/);
+  if (daysMatch) {
+    const dayParts = daysMatch[1].split(/[,\s]+/).map((d) => d.trim()).filter(Boolean);
+    const days = [];
+    for (const part of dayParts) {
+      const dayNum = DAY_NAMES[part];
+      if (dayNum !== undefined) {
+        days.push(dayNum);
+      }
+    }
+    if (days.length > 0) {
+      return { type: "specific_days", days: days.sort((a, b) => a - b) };
+    }
+  }
+  throw new Error(`Invalid recurrence rule: "${rule}". Supported formats: "every day", "every weekday", "every week", "every 2 weeks", "every month", "every N days/weeks/months", "every monday", "every mon,wed,fri"`);
+}
+function nextOccurrence(rule, from) {
+  const parsed = parseRecurrenceRule(rule);
+  const base = from || new Date;
+  if (parsed.type === "interval") {
+    const next = new Date(base);
+    if (parsed.unit === "day") {
+      next.setDate(next.getDate() + parsed.interval);
+    } else if (parsed.unit === "week") {
+      next.setDate(next.getDate() + parsed.interval * 7);
+    } else if (parsed.unit === "month") {
+      next.setMonth(next.getMonth() + parsed.interval);
+    }
+    return next.toISOString();
+  }
+  if (parsed.type === "specific_days") {
+    const currentDay = base.getDay();
+    const days = parsed.days;
+    let daysToAdd = Infinity;
+    for (const day of days) {
+      let diff = day - currentDay;
+      if (diff <= 0)
+        diff += 7;
+      if (diff < daysToAdd)
+        daysToAdd = diff;
+    }
+    const next = new Date(base);
+    next.setDate(next.getDate() + daysToAdd);
+    return next.toISOString();
+  }
+  throw new Error(`Cannot calculate next occurrence for rule: "${rule}"`);
+}
+var DAY_NAMES;
+var init_recurrence = __esm(() => {
+  DAY_NAMES = {
+    sunday: 0,
+    sun: 0,
+    monday: 1,
+    mon: 1,
+    tuesday: 2,
+    tue: 2,
+    wednesday: 3,
+    wed: 3,
+    thursday: 4,
+    thu: 4,
+    friday: 5,
+    fri: 5,
+    saturday: 6,
+    sat: 6
+  };
+});
+
 // src/db/tasks.ts
 function rowToTask(row) {
   return {
@@ -3005,8 +3132,8 @@ function createTask(input, db) {
   const tags = input.tags || [];
   const shortId = input.project_id ? nextTaskShortId(input.project_id, d) : null;
   const title = shortId ? `${shortId}: ${input.title}` : input.title;
-  d.run(`INSERT INTO tasks (id, short_id, project_id, parent_id, plan_id, task_list_id, title, description, status, priority, agent_id, assigned_to, session_id, working_dir, tags, metadata, version, created_at, updated_at, due_at, estimated_minutes, requires_approval, approved_by, approved_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?)`, [
+  d.run(`INSERT INTO tasks (id, short_id, project_id, parent_id, plan_id, task_list_id, title, description, status, priority, agent_id, assigned_to, session_id, working_dir, tags, metadata, version, created_at, updated_at, due_at, estimated_minutes, requires_approval, approved_by, approved_at, recurrence_rule, recurrence_parent_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
     id,
     shortId,
     input.project_id || null,
@@ -3029,7 +3156,9 @@ function createTask(input, db) {
     input.estimated_minutes || null,
     input.requires_approval ? 1 : 0,
     null,
-    null
+    null,
+    input.recurrence_rule || null,
+    input.recurrence_parent_id || null
   ]);
   if (tags.length > 0) {
     insertTaskTags(id, tags, d);
@@ -3129,6 +3258,11 @@ function listTasks(filter = {}, db) {
     conditions.push("task_list_id = ?");
     params.push(filter.task_list_id);
   }
+  if (filter.has_recurrence === true) {
+    conditions.push("recurrence_rule IS NOT NULL");
+  } else if (filter.has_recurrence === false) {
+    conditions.push("recurrence_rule IS NULL");
+  }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   let limitClause = "";
   if (filter.limit) {
@@ -3144,6 +3278,69 @@ function listTasks(filter = {}, db) {
        created_at DESC${limitClause}`).all(...params);
   return rows.map(rowToTask);
 }
+function countTasks(filter = {}, db) {
+  const d = db || getDatabase();
+  const conditions = [];
+  const params = [];
+  if (filter.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filter.project_id);
+  }
+  if (filter.parent_id !== undefined) {
+    if (filter.parent_id === null) {
+      conditions.push("parent_id IS NULL");
+    } else {
+      conditions.push("parent_id = ?");
+      params.push(filter.parent_id);
+    }
+  }
+  if (filter.status) {
+    if (Array.isArray(filter.status)) {
+      conditions.push(`status IN (${filter.status.map(() => "?").join(",")})`);
+      params.push(...filter.status);
+    } else {
+      conditions.push("status = ?");
+      params.push(filter.status);
+    }
+  }
+  if (filter.priority) {
+    if (Array.isArray(filter.priority)) {
+      conditions.push(`priority IN (${filter.priority.map(() => "?").join(",")})`);
+      params.push(...filter.priority);
+    } else {
+      conditions.push("priority = ?");
+      params.push(filter.priority);
+    }
+  }
+  if (filter.assigned_to) {
+    conditions.push("assigned_to = ?");
+    params.push(filter.assigned_to);
+  }
+  if (filter.agent_id) {
+    conditions.push("agent_id = ?");
+    params.push(filter.agent_id);
+  }
+  if (filter.session_id) {
+    conditions.push("session_id = ?");
+    params.push(filter.session_id);
+  }
+  if (filter.tags && filter.tags.length > 0) {
+    const placeholders = filter.tags.map(() => "?").join(",");
+    conditions.push(`id IN (SELECT task_id FROM task_tags WHERE tag IN (${placeholders}))`);
+    params.push(...filter.tags);
+  }
+  if (filter.plan_id) {
+    conditions.push("plan_id = ?");
+    params.push(filter.plan_id);
+  }
+  if (filter.task_list_id) {
+    conditions.push("task_list_id = ?");
+    params.push(filter.task_list_id);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const row = d.query(`SELECT COUNT(*) as count FROM tasks ${where}`).get(...params);
+  return row.count;
+}
 function updateTask(id, input, db) {
   const d = db || getDatabase();
   const task = getTask(id, d);
@@ -3215,6 +3412,10 @@ function updateTask(id, input, db) {
     sets.push("approved_at = ?");
     params.push(now());
   }
+  if (input.recurrence_rule !== undefined) {
+    sets.push("recurrence_rule = ?");
+    params.push(input.recurrence_rule);
+  }
   params.push(id, input.version);
   const result = d.run(`UPDATE tasks SET ${sets.join(", ")} WHERE id = ? AND version = ?`, params);
   if (result.changes === 0) {
@@ -3288,7 +3489,7 @@ function startTask(id, agentId, db) {
   logTaskChange(id, "start", "status", "pending", "in_progress", agentId, d);
   return { ...task, status: "in_progress", assigned_to: agentId, locked_by: agentId, locked_at: timestamp, version: task.version + 1, updated_at: timestamp };
 }
-function completeTask(id, agentId, db, evidence) {
+function completeTask(id, agentId, db, options) {
   const d = db || getDatabase();
   const task = getTask(id, d);
   if (!task)
@@ -3297,7 +3498,9 @@ function completeTask(id, agentId, db, evidence) {
     throw new LockError(id, task.locked_by);
   }
   checkCompletionGuard(task, agentId || null, d);
-  if (evidence) {
+  const evidence = options ? { files_changed: options.files_changed, test_results: options.test_results, commit_hash: options.commit_hash, notes: options.notes } : undefined;
+  const hasEvidence = evidence && (evidence.files_changed || evidence.test_results || evidence.commit_hash || evidence.notes);
+  if (hasEvidence) {
     const meta2 = { ...task.metadata, _evidence: evidence };
     d.run("UPDATE tasks SET metadata = ? WHERE id = ?", [JSON.stringify(meta2), id]);
   }
@@ -3305,7 +3508,14 @@ function completeTask(id, agentId, db, evidence) {
   d.run(`UPDATE tasks SET status = 'completed', locked_by = NULL, locked_at = NULL, completed_at = ?, version = version + 1, updated_at = ?
      WHERE id = ?`, [timestamp, timestamp, id]);
   logTaskChange(id, "complete", "status", task.status, "completed", agentId || null, d);
-  const meta = evidence ? { ...task.metadata, _evidence: evidence } : task.metadata;
+  let spawnedTask = null;
+  if (task.recurrence_rule && !options?.skip_recurrence) {
+    spawnedTask = spawnNextRecurrence(task, d);
+  }
+  const meta = hasEvidence ? { ...task.metadata, _evidence: evidence } : task.metadata;
+  if (spawnedTask) {
+    meta._next_recurrence = { id: spawnedTask.id, short_id: spawnedTask.short_id, due_at: spawnedTask.due_at };
+  }
   return { ...task, status: "completed", locked_by: null, locked_at: null, completed_at: timestamp, version: task.version + 1, updated_at: timestamp, metadata: meta };
 }
 function lockTask(id, agentId, db) {
@@ -3368,6 +3578,266 @@ function getTaskDependencies(taskId, db) {
   const d = db || getDatabase();
   return d.query("SELECT * FROM task_dependencies WHERE task_id = ?").all(taskId);
 }
+function cloneTask(taskId, overrides, db) {
+  const d = db || getDatabase();
+  const source = getTask(taskId, d);
+  if (!source)
+    throw new TaskNotFoundError(taskId);
+  const input = {
+    title: overrides?.title ?? source.title,
+    description: overrides?.description ?? source.description ?? undefined,
+    priority: overrides?.priority ?? source.priority,
+    project_id: overrides?.project_id ?? source.project_id ?? undefined,
+    parent_id: overrides?.parent_id ?? source.parent_id ?? undefined,
+    plan_id: overrides?.plan_id ?? source.plan_id ?? undefined,
+    task_list_id: overrides?.task_list_id ?? source.task_list_id ?? undefined,
+    status: overrides?.status ?? "pending",
+    agent_id: overrides?.agent_id ?? source.agent_id ?? undefined,
+    assigned_to: overrides?.assigned_to ?? source.assigned_to ?? undefined,
+    tags: overrides?.tags ?? source.tags,
+    metadata: overrides?.metadata ?? source.metadata,
+    estimated_minutes: overrides?.estimated_minutes ?? source.estimated_minutes ?? undefined,
+    recurrence_rule: overrides?.recurrence_rule ?? source.recurrence_rule ?? undefined
+  };
+  return createTask(input, d);
+}
+function getTaskGraph(taskId, direction = "both", db) {
+  const d = db || getDatabase();
+  const task = getTask(taskId, d);
+  if (!task)
+    throw new TaskNotFoundError(taskId);
+  function toNode(t) {
+    const deps = getTaskDependencies(t.id, d);
+    const hasUnfinishedDeps = deps.some((dep) => {
+      const depTask = getTask(dep.depends_on, d);
+      return depTask && depTask.status !== "completed";
+    });
+    return { id: t.id, short_id: t.short_id, title: t.title, status: t.status, priority: t.priority, is_blocked: hasUnfinishedDeps };
+  }
+  function buildUp(id, visited) {
+    if (visited.has(id))
+      return [];
+    visited.add(id);
+    const deps = d.query("SELECT depends_on FROM task_dependencies WHERE task_id = ?").all(id);
+    return deps.map((dep) => {
+      const depTask = getTask(dep.depends_on, d);
+      if (!depTask)
+        return null;
+      return { task: toNode(depTask), depends_on: buildUp(dep.depends_on, visited), blocks: [] };
+    }).filter(Boolean);
+  }
+  function buildDown(id, visited) {
+    if (visited.has(id))
+      return [];
+    visited.add(id);
+    const dependents = d.query("SELECT task_id FROM task_dependencies WHERE depends_on = ?").all(id);
+    return dependents.map((dep) => {
+      const depTask = getTask(dep.task_id, d);
+      if (!depTask)
+        return null;
+      return { task: toNode(depTask), depends_on: [], blocks: buildDown(dep.task_id, visited) };
+    }).filter(Boolean);
+  }
+  const rootNode = toNode(task);
+  const depends_on = direction === "up" || direction === "both" ? buildUp(taskId, new Set) : [];
+  const blocks = direction === "down" || direction === "both" ? buildDown(taskId, new Set) : [];
+  return { task: rootNode, depends_on, blocks };
+}
+function moveTask(taskId, target, db) {
+  const d = db || getDatabase();
+  const task = getTask(taskId, d);
+  if (!task)
+    throw new TaskNotFoundError(taskId);
+  const sets = ["updated_at = ?", "version = version + 1"];
+  const params = [now()];
+  if (target.task_list_id !== undefined) {
+    sets.push("task_list_id = ?");
+    params.push(target.task_list_id);
+  }
+  if (target.project_id !== undefined) {
+    sets.push("project_id = ?");
+    params.push(target.project_id);
+  }
+  if (target.plan_id !== undefined) {
+    sets.push("plan_id = ?");
+    params.push(target.plan_id);
+  }
+  params.push(taskId);
+  d.run(`UPDATE tasks SET ${sets.join(", ")} WHERE id = ?`, params);
+  return getTask(taskId, d);
+}
+function spawnNextRecurrence(completedTask, db) {
+  const dueAt = nextOccurrence(completedTask.recurrence_rule, new Date);
+  let title = completedTask.title;
+  if (completedTask.short_id && title.startsWith(completedTask.short_id + ": ")) {
+    title = title.slice(completedTask.short_id.length + 2);
+  }
+  const recurrenceParentId = completedTask.recurrence_parent_id || completedTask.id;
+  return createTask({
+    title,
+    description: completedTask.description ?? undefined,
+    priority: completedTask.priority,
+    project_id: completedTask.project_id ?? undefined,
+    task_list_id: completedTask.task_list_id ?? undefined,
+    plan_id: completedTask.plan_id ?? undefined,
+    assigned_to: completedTask.assigned_to ?? undefined,
+    tags: completedTask.tags,
+    metadata: completedTask.metadata,
+    estimated_minutes: completedTask.estimated_minutes ?? undefined,
+    recurrence_rule: completedTask.recurrence_rule,
+    recurrence_parent_id: recurrenceParentId,
+    due_at: dueAt
+  }, db);
+}
+function claimNextTask(agentId, filters, db) {
+  const d = db || getDatabase();
+  const tx = d.transaction(() => {
+    const task = getNextTask(agentId, filters, d);
+    if (!task)
+      return null;
+    return startTask(task.id, agentId, d);
+  });
+  return tx();
+}
+function getNextTask(agentId, filters, db) {
+  const d = db || getDatabase();
+  clearExpiredLocks(d);
+  const conditions = ["status = 'pending'", "(locked_by IS NULL OR locked_at < ?)"];
+  const params = [lockExpiryCutoff()];
+  if (filters?.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filters.project_id);
+  }
+  if (filters?.task_list_id) {
+    conditions.push("task_list_id = ?");
+    params.push(filters.task_list_id);
+  }
+  if (filters?.plan_id) {
+    conditions.push("plan_id = ?");
+    params.push(filters.plan_id);
+  }
+  if (filters?.tags && filters.tags.length > 0) {
+    const placeholders = filters.tags.map(() => "?").join(",");
+    conditions.push(`id IN (SELECT task_id FROM task_tags WHERE tag IN (${placeholders}))`);
+    params.push(...filters.tags);
+  }
+  conditions.push("id NOT IN (SELECT td.task_id FROM task_dependencies td JOIN tasks dep ON dep.id = td.depends_on WHERE dep.status != 'completed')");
+  const where = conditions.join(" AND ");
+  let sql = `SELECT * FROM tasks WHERE ${where} ORDER BY `;
+  if (agentId) {
+    sql += `CASE WHEN assigned_to = ? THEN 0 WHEN assigned_to IS NULL THEN 1 ELSE 2 END, `;
+    params.push(agentId);
+  }
+  sql += `CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END, created_at ASC LIMIT 1`;
+  const row = d.query(sql).get(...params);
+  return row ? rowToTask(row) : null;
+}
+function getActiveWork(filters, db) {
+  const d = db || getDatabase();
+  clearExpiredLocks(d);
+  const conditions = ["status = 'in_progress'"];
+  const params = [];
+  if (filters?.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filters.project_id);
+  }
+  if (filters?.task_list_id) {
+    conditions.push("task_list_id = ?");
+    params.push(filters.task_list_id);
+  }
+  const where = conditions.join(" AND ");
+  const rows = d.query(`SELECT id, short_id, title, priority, assigned_to, locked_by, locked_at, updated_at FROM tasks WHERE ${where} ORDER BY
+    CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END,
+    updated_at DESC`).all(...params);
+  return rows;
+}
+function getTasksChangedSince(since, filters, db) {
+  const d = db || getDatabase();
+  const conditions = ["updated_at > ?"];
+  const params = [since];
+  if (filters?.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filters.project_id);
+  }
+  if (filters?.task_list_id) {
+    conditions.push("task_list_id = ?");
+    params.push(filters.task_list_id);
+  }
+  const where = conditions.join(" AND ");
+  const rows = d.query(`SELECT * FROM tasks WHERE ${where} ORDER BY updated_at DESC`).all(...params);
+  return rows.map(rowToTask);
+}
+function failTask(id, agentId, reason, options, db) {
+  const d = db || getDatabase();
+  const task = getTask(id, d);
+  if (!task)
+    throw new TaskNotFoundError(id);
+  const meta = {
+    ...task.metadata,
+    _failure: {
+      reason: reason || "Unknown failure",
+      error_code: options?.error_code || null,
+      failed_by: agentId || null,
+      failed_at: now(),
+      retry_requested: options?.retry || false
+    }
+  };
+  const timestamp = now();
+  d.run(`UPDATE tasks SET status = 'failed', locked_by = NULL, locked_at = NULL, metadata = ?, version = version + 1, updated_at = ?
+     WHERE id = ?`, [JSON.stringify(meta), timestamp, id]);
+  logTaskChange(id, "fail", "status", task.status, "failed", agentId || null, d);
+  const failedTask = {
+    ...task,
+    status: "failed",
+    locked_by: null,
+    locked_at: null,
+    metadata: meta,
+    version: task.version + 1,
+    updated_at: timestamp
+  };
+  let retryTask;
+  if (options?.retry) {
+    let title = task.title;
+    if (task.short_id && title.startsWith(task.short_id + ": ")) {
+      title = title.slice(task.short_id.length + 2);
+    }
+    retryTask = createTask({
+      title,
+      description: task.description ?? undefined,
+      priority: task.priority,
+      project_id: task.project_id ?? undefined,
+      task_list_id: task.task_list_id ?? undefined,
+      plan_id: task.plan_id ?? undefined,
+      assigned_to: task.assigned_to ?? undefined,
+      tags: task.tags,
+      metadata: { ...task.metadata, _retry: { original_id: task.id, retry_after: options.retry_after || null, failure_reason: reason } },
+      estimated_minutes: task.estimated_minutes ?? undefined,
+      recurrence_rule: task.recurrence_rule ?? undefined,
+      due_at: options.retry_after || task.due_at || undefined
+    }, d);
+  }
+  return { task: failedTask, retryTask };
+}
+function getStaleTasks(staleMinutes = 30, filters, db) {
+  const d = db || getDatabase();
+  const cutoff = new Date(Date.now() - staleMinutes * 60 * 1000).toISOString();
+  const conditions = [
+    "status = 'in_progress'",
+    "(updated_at < ? OR (locked_at IS NOT NULL AND locked_at < ?))"
+  ];
+  const params = [cutoff, cutoff];
+  if (filters?.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filters.project_id);
+  }
+  if (filters?.task_list_id) {
+    conditions.push("task_list_id = ?");
+    params.push(filters.task_list_id);
+  }
+  const where = conditions.join(" AND ");
+  const rows = d.query(`SELECT * FROM tasks WHERE ${where} ORDER BY updated_at ASC`).all(...params);
+  return rows.map(rowToTask);
+}
 function wouldCreateCycle(taskId, dependsOn, db) {
   const visited = new Set;
   const queue = [dependsOn];
@@ -3385,12 +3855,98 @@ function wouldCreateCycle(taskId, dependsOn, db) {
   }
   return false;
 }
+function getTaskStats(filters, db) {
+  const d = db || getDatabase();
+  const conditions = [];
+  const params = [];
+  if (filters?.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filters.project_id);
+  }
+  if (filters?.task_list_id) {
+    conditions.push("task_list_id = ?");
+    params.push(filters.task_list_id);
+  }
+  if (filters?.agent_id) {
+    conditions.push("(agent_id = ? OR assigned_to = ?)");
+    params.push(filters.agent_id, filters.agent_id);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const totalRow = d.query(`SELECT COUNT(*) as count FROM tasks ${where}`).get(...params);
+  const statusRows = d.query(`SELECT status, COUNT(*) as count FROM tasks ${where} GROUP BY status`).all(...params);
+  const by_status = {};
+  for (const r of statusRows)
+    by_status[r.status] = r.count;
+  const priorityRows = d.query(`SELECT priority, COUNT(*) as count FROM tasks ${where} GROUP BY priority`).all(...params);
+  const by_priority = {};
+  for (const r of priorityRows)
+    by_priority[r.priority] = r.count;
+  const agentRows = d.query(`SELECT COALESCE(assigned_to, agent_id, 'unassigned') as agent, COUNT(*) as count FROM tasks ${where} GROUP BY agent`).all(...params);
+  const by_agent = {};
+  for (const r of agentRows)
+    by_agent[r.agent] = r.count;
+  const completed = by_status["completed"] || 0;
+  const completion_rate = totalRow.count > 0 ? Math.round(completed / totalRow.count * 100) : 0;
+  return { total: totalRow.count, by_status, by_priority, completion_rate, by_agent };
+}
+function bulkCreateTasks(inputs, db) {
+  const d = db || getDatabase();
+  const tempIdToRealId = new Map;
+  const created = [];
+  const tx = d.transaction(() => {
+    for (const input of inputs) {
+      const { temp_id, depends_on_temp_ids: _deps, ...createInput } = input;
+      const task = createTask(createInput, d);
+      if (temp_id)
+        tempIdToRealId.set(temp_id, task.id);
+      created.push({ temp_id: temp_id || null, id: task.id, short_id: task.short_id, title: task.title });
+    }
+    for (const input of inputs) {
+      if (input.depends_on_temp_ids && input.depends_on_temp_ids.length > 0) {
+        const taskId = input.temp_id ? tempIdToRealId.get(input.temp_id) : null;
+        if (!taskId)
+          continue;
+        for (const depTempId of input.depends_on_temp_ids) {
+          const depRealId = tempIdToRealId.get(depTempId);
+          if (depRealId) {
+            addDependency(taskId, depRealId, d);
+          }
+        }
+      }
+    }
+  });
+  tx();
+  return { created };
+}
+function bulkUpdateTasks(taskIds, updates, db) {
+  const d = db || getDatabase();
+  let updated = 0;
+  const failed = [];
+  const tx = d.transaction(() => {
+    for (const id of taskIds) {
+      try {
+        const task = getTask(id, d);
+        if (!task) {
+          failed.push({ id, error: "Task not found" });
+          continue;
+        }
+        updateTask(id, { ...updates, version: task.version }, d);
+        updated++;
+      } catch (e) {
+        failed.push({ id, error: e instanceof Error ? e.message : String(e) });
+      }
+    }
+  });
+  tx();
+  return { updated, failed };
+}
 var init_tasks = __esm(() => {
   init_types();
   init_database();
   init_projects();
   init_completion_guard();
   init_audit();
+  init_recurrence();
 });
 
 // src/db/agents.ts
@@ -3715,19 +4271,64 @@ function rowToTask2(row) {
     requires_approval: Boolean(row.requires_approval)
   };
 }
-function searchTasks(query, projectId, taskListId, db) {
+function searchTasks(options, projectId, taskListId, db) {
+  const opts = typeof options === "string" ? { query: options, project_id: projectId, task_list_id: taskListId } : options;
   const d = db || getDatabase();
   clearExpiredLocks(d);
-  const pattern = `%${query}%`;
+  const pattern = `%${opts.query}%`;
   let sql = `SELECT * FROM tasks WHERE (title LIKE ? OR description LIKE ? OR EXISTS (SELECT 1 FROM task_tags WHERE task_tags.task_id = tasks.id AND tag LIKE ?))`;
   const params = [pattern, pattern, pattern];
-  if (projectId) {
+  if (opts.project_id) {
     sql += " AND project_id = ?";
-    params.push(projectId);
+    params.push(opts.project_id);
   }
-  if (taskListId) {
+  if (opts.task_list_id) {
     sql += " AND task_list_id = ?";
-    params.push(taskListId);
+    params.push(opts.task_list_id);
+  }
+  if (opts.status) {
+    if (Array.isArray(opts.status)) {
+      sql += ` AND status IN (${opts.status.map(() => "?").join(",")})`;
+      params.push(...opts.status);
+    } else {
+      sql += " AND status = ?";
+      params.push(opts.status);
+    }
+  }
+  if (opts.priority) {
+    if (Array.isArray(opts.priority)) {
+      sql += ` AND priority IN (${opts.priority.map(() => "?").join(",")})`;
+      params.push(...opts.priority);
+    } else {
+      sql += " AND priority = ?";
+      params.push(opts.priority);
+    }
+  }
+  if (opts.assigned_to) {
+    sql += " AND assigned_to = ?";
+    params.push(opts.assigned_to);
+  }
+  if (opts.agent_id) {
+    sql += " AND agent_id = ?";
+    params.push(opts.agent_id);
+  }
+  if (opts.created_after) {
+    sql += " AND created_at > ?";
+    params.push(opts.created_after);
+  }
+  if (opts.updated_after) {
+    sql += " AND updated_at > ?";
+    params.push(opts.updated_after);
+  }
+  if (opts.has_dependencies === true) {
+    sql += " AND id IN (SELECT task_id FROM task_dependencies)";
+  } else if (opts.has_dependencies === false) {
+    sql += " AND id NOT IN (SELECT task_id FROM task_dependencies)";
+  }
+  if (opts.is_blocked === true) {
+    sql += " AND id IN (SELECT td.task_id FROM task_dependencies td JOIN tasks dep ON dep.id = td.depends_on WHERE dep.status != 'completed')";
+  } else if (opts.is_blocked === false) {
+    sql += " AND id NOT IN (SELECT td.task_id FROM task_dependencies td JOIN tasks dep ON dep.id = td.depends_on WHERE dep.status != 'completed')";
   }
   sql += ` ORDER BY
     CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END,
@@ -8360,25 +8961,38 @@ var exports_mcp = {};
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 function formatError(error) {
-  if (error instanceof VersionConflictError)
-    return `Version conflict: ${error.message}`;
-  if (error instanceof TaskNotFoundError)
-    return `Not found: ${error.message}`;
-  if (error instanceof PlanNotFoundError)
-    return `Not found: ${error.message}`;
-  if (error instanceof TaskListNotFoundError)
-    return `Not found: ${error.message}`;
-  if (error instanceof LockError)
-    return `Lock error: ${error.message}`;
-  if (error instanceof DependencyCycleError)
-    return `Dependency cycle: ${error.message}`;
+  if (error instanceof VersionConflictError) {
+    return JSON.stringify({ code: VersionConflictError.code, message: error.message, suggestion: VersionConflictError.suggestion });
+  }
+  if (error instanceof TaskNotFoundError) {
+    return JSON.stringify({ code: TaskNotFoundError.code, message: error.message, suggestion: TaskNotFoundError.suggestion });
+  }
+  if (error instanceof ProjectNotFoundError) {
+    return JSON.stringify({ code: ProjectNotFoundError.code, message: error.message, suggestion: ProjectNotFoundError.suggestion });
+  }
+  if (error instanceof PlanNotFoundError) {
+    return JSON.stringify({ code: PlanNotFoundError.code, message: error.message, suggestion: PlanNotFoundError.suggestion });
+  }
+  if (error instanceof TaskListNotFoundError) {
+    return JSON.stringify({ code: TaskListNotFoundError.code, message: error.message, suggestion: TaskListNotFoundError.suggestion });
+  }
+  if (error instanceof LockError) {
+    return JSON.stringify({ code: LockError.code, message: error.message, suggestion: LockError.suggestion });
+  }
+  if (error instanceof AgentNotFoundError) {
+    return JSON.stringify({ code: AgentNotFoundError.code, message: error.message, suggestion: AgentNotFoundError.suggestion });
+  }
+  if (error instanceof DependencyCycleError) {
+    return JSON.stringify({ code: DependencyCycleError.code, message: error.message, suggestion: DependencyCycleError.suggestion });
+  }
   if (error instanceof CompletionGuardError) {
-    const retry = error.retryAfterSeconds ? ` (retry after ${error.retryAfterSeconds}s)` : "";
-    return `Completion blocked: ${error.reason}${retry}`;
+    const retry = error.retryAfterSeconds ? { retryAfterSeconds: error.retryAfterSeconds } : {};
+    return JSON.stringify({ code: CompletionGuardError.code, message: error.reason, suggestion: CompletionGuardError.suggestion, ...retry });
+  }
+  if (error instanceof Error) {
+    return JSON.stringify({ code: "UNKNOWN_ERROR", message: error.message });
   }
-  if (error instanceof Error)
-    return error.message;
-  return String(error);
+  return JSON.stringify({ code: "UNKNOWN_ERROR", message: String(error) });
 }
 function resolveId(partialId, table = "tasks") {
   const db = getDatabase();
@@ -8401,7 +9015,8 @@ function formatTask(task) {
   const id = task.short_id || task.id.slice(0, 8);
   const assigned = task.assigned_to ? ` -> ${task.assigned_to}` : "";
   const lock = task.locked_by ? ` [locked:${task.locked_by}]` : "";
-  return `${id} ${task.status.padEnd(11)} ${task.priority.padEnd(8)} ${task.title}${assigned}${lock}`;
+  const recur = task.recurrence_rule ? ` [\u21BB]` : "";
+  return `${id} ${task.status.padEnd(11)} ${task.priority.padEnd(8)} ${task.title}${assigned}${lock}${recur}`;
 }
 function formatTaskDetail(task) {
   const parts = [
@@ -8426,6 +9041,10 @@ function formatTaskDetail(task) {
     parts.push(`Plan: ${task.plan_id}`);
   if (task.tags.length > 0)
     parts.push(`Tags: ${task.tags.join(", ")}`);
+  if (task.recurrence_rule)
+    parts.push(`Recurrence: ${task.recurrence_rule}`);
+  if (task.recurrence_parent_id)
+    parts.push(`Recurrence parent: ${task.recurrence_parent_id}`);
   parts.push(`Version: ${task.version}`);
   parts.push(`Created: ${task.created_at}`);
   if (task.completed_at)
@@ -8453,7 +9072,7 @@ var init_mcp = __esm(() => {
   init_types();
   server = new McpServer({
     name: "todos",
-    version: "0.9.33"
+    version: "0.9.35"
   });
   server.tool("create_task", "Create a new task", {
     title: exports_external.string(),
@@ -8471,7 +9090,8 @@ var init_mcp = __esm(() => {
     tags: exports_external.array(exports_external.string()).optional(),
     metadata: exports_external.record(exports_external.unknown()).optional(),
     estimated_minutes: exports_external.number().optional(),
-    requires_approval: exports_external.boolean().optional()
+    requires_approval: exports_external.boolean().optional(),
+    recurrence_rule: exports_external.string().optional()
   }, async (params) => {
     try {
       const resolved = { ...params };
@@ -8489,7 +9109,7 @@ var init_mcp = __esm(() => {
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("list_tasks", "List tasks with optional filters", {
+  server.tool("list_tasks", "List tasks with optional filters and pagination.", {
     project_id: exports_external.string().optional(),
     status: exports_external.union([
       exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]),
@@ -8502,7 +9122,10 @@ var init_mcp = __esm(() => {
     assigned_to: exports_external.string().optional(),
     tags: exports_external.array(exports_external.string()).optional(),
     plan_id: exports_external.string().optional(),
-    task_list_id: exports_external.string().optional()
+    task_list_id: exports_external.string().optional(),
+    has_recurrence: exports_external.boolean().optional(),
+    limit: exports_external.number().optional(),
+    offset: exports_external.number().optional()
   }, async (params) => {
     try {
       const resolved = { ...params };
@@ -8513,8 +9136,10 @@ var init_mcp = __esm(() => {
       if (resolved.task_list_id)
         resolved.task_list_id = resolveId(resolved.task_list_id, "task_lists");
       const tasks = listTasks(resolved);
+      const { limit: _limit, offset: _offset, ...countFilter } = resolved;
+      const total = countTasks(countFilter);
       if (tasks.length === 0) {
-        return { content: [{ type: "text", text: "No tasks found." }] };
+        return { content: [{ type: "text", text: total > 0 ? `No tasks in this page (total: ${total}).` : "No tasks found." }] };
       }
       const text = tasks.map((t) => {
         const lock = t.locked_by ? ` [locked by ${t.locked_by}]` : "";
@@ -8522,13 +9147,15 @@ var init_mcp = __esm(() => {
         return `[${t.status}] ${t.id.slice(0, 8)} | ${t.priority} | ${t.title}${assigned}${lock}`;
       }).join(`
 `);
+      const pagination = resolved.limit ? `
+(showing ${tasks.length} of ${total}, offset: ${resolved.offset || 0})` : "";
       return { content: [{ type: "text", text: `${tasks.length} task(s):
-${text}` }] };
+${text}${pagination}` }] };
     } catch (e) {
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("get_task", "Get full task details with relations", {
+  server.tool("get_task", "Get full task details with subtasks, deps, and comments.", {
     id: exports_external.string()
   }, async ({ id }) => {
     try {
@@ -8597,7 +9224,7 @@ Parent: ${task.parent.id.slice(0, 8)} | ${task.parent.title}`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("delete_task", "Delete a task permanently", {
+  server.tool("delete_task", "Delete a task permanently. Subtasks cascade-deleted.", {
     id: exports_external.string()
   }, async ({ id }) => {
     try {
@@ -8613,7 +9240,7 @@ Parent: ${task.parent.id.slice(0, 8)} | ${task.parent.title}`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("start_task", "Claim, lock, and set task status to in_progress.", {
+  server.tool("start_task", "Claim, lock, and set task to in_progress.", {
     id: exports_external.string(),
     agent_id: exports_external.string()
   }, async ({ id, agent_id }) => {
@@ -8625,19 +9252,26 @@ Parent: ${task.parent.id.slice(0, 8)} | ${task.parent.title}`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("complete_task", "Mark task completed and release lock.", {
+  server.tool("complete_task", "Complete a task. For recurring tasks, auto-spawns next instance.", {
     id: exports_external.string(),
-    agent_id: exports_external.string().optional()
-  }, async ({ id, agent_id }) => {
+    agent_id: exports_external.string().optional(),
+    skip_recurrence: exports_external.boolean().optional()
+  }, async ({ id, agent_id, skip_recurrence }) => {
     try {
       const resolvedId = resolveId(id);
-      const task = completeTask(resolvedId, agent_id);
-      return { content: [{ type: "text", text: `completed: ${formatTask(task)}` }] };
+      const task = completeTask(resolvedId, agent_id, undefined, { skip_recurrence });
+      let text = `completed: ${formatTask(task)}`;
+      if (task.metadata._next_recurrence) {
+        const next = task.metadata._next_recurrence;
+        text += `
+next: ${next.short_id || next.id.slice(0, 8)} due ${next.due_at}`;
+      }
+      return { content: [{ type: "text", text }] };
     } catch (e) {
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("lock_task", "Acquire exclusive lock on a task", {
+  server.tool("lock_task", "Acquire exclusive lock. Expires after 30 min. Idempotent per agent.", {
     id: exports_external.string(),
     agent_id: exports_external.string()
   }, async ({ id, agent_id }) => {
@@ -8652,7 +9286,7 @@ Parent: ${task.parent.id.slice(0, 8)} | ${task.parent.title}`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("unlock_task", "Release exclusive lock on a task", {
+  server.tool("unlock_task", "Release exclusive lock on a task.", {
     id: exports_external.string(),
     agent_id: exports_external.string().optional()
   }, async ({ id, agent_id }) => {
@@ -8664,7 +9298,7 @@ Parent: ${task.parent.id.slice(0, 8)} | ${task.parent.title}`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("add_dependency", "Add a dependency: task_id depends on depends_on.", {
+  server.tool("add_dependency", "Add a dependency. Prevents cycles via BFS detection.", {
     task_id: exports_external.string(),
     depends_on: exports_external.string()
   }, async ({ task_id, depends_on }) => {
@@ -8677,7 +9311,7 @@ Parent: ${task.parent.id.slice(0, 8)} | ${task.parent.title}`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("remove_dependency", "Remove a dependency between tasks", {
+  server.tool("remove_dependency", "Remove a dependency link between two tasks.", {
     task_id: exports_external.string(),
     depends_on: exports_external.string()
   }, async ({ task_id, depends_on }) => {
@@ -8695,7 +9329,7 @@ Parent: ${task.parent.id.slice(0, 8)} | ${task.parent.title}`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("add_comment", "Add a comment/note to a task", {
+  server.tool("add_comment", "Add a comment or note to a task. Comments are append-only.", {
     task_id: exports_external.string(),
     content: exports_external.string(),
     agent_id: exports_external.string().optional(),
@@ -8726,7 +9360,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("create_project", "Register a new project", {
+  server.tool("create_project", "Register a new project with auto-generated task prefix.", {
     name: exports_external.string(),
     path: exports_external.string(),
     description: exports_external.string().optional(),
@@ -8745,7 +9379,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("create_plan", "Create a new plan", {
+  server.tool("create_plan", "Create a plan to group related tasks.", {
     name: exports_external.string(),
     project_id: exports_external.string().optional(),
     description: exports_external.string().optional(),
@@ -8770,7 +9404,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("list_plans", "List plans with optional project filter", {
+  server.tool("list_plans", "List all plans, optionally filtered by project.", {
     project_id: exports_external.string().optional()
   }, async ({ project_id }) => {
     try {
@@ -8790,7 +9424,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("get_plan", "Get plan details", {
+  server.tool("get_plan", "Get plan details including status and timestamps.", {
     id: exports_external.string()
   }, async ({ id }) => {
     try {
@@ -8815,7 +9449,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("update_plan", "Update a plan", {
+  server.tool("update_plan", "Update plan fields (name, description, status).", {
     id: exports_external.string(),
     name: exports_external.string().optional(),
     description: exports_external.string().optional(),
@@ -8839,7 +9473,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("delete_plan", "Delete a plan", {
+  server.tool("delete_plan", "Delete a plan. Tasks in the plan are orphaned (not deleted).", {
     id: exports_external.string()
   }, async ({ id }) => {
     try {
@@ -8855,15 +9489,34 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("search_tasks", "Full-text search across task titles, descriptions, tags.", {
+  server.tool("search_tasks", "Full-text search across tasks with filters.", {
     query: exports_external.string(),
     project_id: exports_external.string().optional(),
-    task_list_id: exports_external.string().optional()
-  }, async ({ query, project_id, task_list_id }) => {
+    task_list_id: exports_external.string().optional(),
+    status: exports_external.union([
+      exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]),
+      exports_external.array(exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]))
+    ]).optional(),
+    priority: exports_external.union([
+      exports_external.enum(["low", "medium", "high", "critical"]),
+      exports_external.array(exports_external.enum(["low", "medium", "high", "critical"]))
+    ]).optional(),
+    assigned_to: exports_external.string().optional(),
+    agent_id: exports_external.string().optional(),
+    created_after: exports_external.string().optional(),
+    updated_after: exports_external.string().optional(),
+    has_dependencies: exports_external.boolean().optional(),
+    is_blocked: exports_external.boolean().optional()
+  }, async ({ query, project_id, task_list_id, ...filters }) => {
     try {
       const resolvedProjectId = project_id ? resolveId(project_id, "projects") : undefined;
       const resolvedTaskListId = task_list_id ? resolveId(task_list_id, "task_lists") : undefined;
-      const tasks = searchTasks(query, resolvedProjectId, resolvedTaskListId);
+      const tasks = searchTasks({
+        query,
+        project_id: resolvedProjectId,
+        task_list_id: resolvedTaskListId,
+        ...filters
+      });
       if (tasks.length === 0) {
         return { content: [{ type: "text", text: `No tasks matching "${query}".` }] };
       }
@@ -8875,7 +9528,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("sync", "Sync tasks with an agent task list.", {
+  server.tool("sync", "Sync tasks between local DB and agent task list.", {
     task_list_id: exports_external.string().optional(),
     agent: exports_external.string().optional(),
     all_agents: exports_external.boolean().optional(),
@@ -8923,7 +9576,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("register_agent", "Register an agent (idempotent by name).", {
+  server.tool("register_agent", "Register an agent (idempotent by name). Updates last_seen_at.", {
     name: exports_external.string(),
     description: exports_external.string().optional()
   }, async ({ name, description }) => {
@@ -8960,7 +9613,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("get_agent", "Get agent details by ID or name", {
+  server.tool("get_agent", "Get agent details by ID or name. Provide one of id or name.", {
     id: exports_external.string().optional(),
     name: exports_external.string().optional()
   }, async ({ id, name }) => {
@@ -8989,9 +9642,9 @@ ${text}` }] };
     }
   });
   server.tool("rename_agent", "Rename an agent. Resolve by id or current name.", {
-    id: exports_external.string().optional().describe("Agent ID"),
-    name: exports_external.string().optional().describe("Current agent name"),
-    new_name: exports_external.string().describe("New name for the agent")
+    id: exports_external.string().optional(),
+    name: exports_external.string().optional(),
+    new_name: exports_external.string()
   }, async ({ id, name, new_name }) => {
     try {
       if (!id && !name) {
@@ -9014,8 +9667,8 @@ ID: ${updated.id}`
     }
   });
   server.tool("delete_agent", "Delete an agent permanently. Resolve by id or name.", {
-    id: exports_external.string().optional().describe("Agent ID"),
-    name: exports_external.string().optional().describe("Agent name")
+    id: exports_external.string().optional(),
+    name: exports_external.string().optional()
   }, async ({ id, name }) => {
     try {
       if (!id && !name) {
@@ -9037,7 +9690,7 @@ ID: ${updated.id}`
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("create_task_list", "Create a new task list", {
+  server.tool("create_task_list", "Create a task list container for organizing tasks.", {
     name: exports_external.string(),
     slug: exports_external.string().optional(),
     project_id: exports_external.string().optional(),
@@ -9063,7 +9716,7 @@ Description: ${list.description}` : ""}`
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("list_task_lists", "List task lists, optionally filtered by project", {
+  server.tool("list_task_lists", "List all task lists, optionally filtered by project.", {
     project_id: exports_external.string().optional()
   }, async ({ project_id }) => {
     try {
@@ -9083,7 +9736,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("get_task_list", "Get task list details", {
+  server.tool("get_task_list", "Get task list details including slug and metadata.", {
     id: exports_external.string()
   }, async ({ id }) => {
     try {
@@ -9111,7 +9764,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("update_task_list", "Update a task list", {
+  server.tool("update_task_list", "Update a task list's name or description.", {
     id: exports_external.string(),
     name: exports_external.string().optional(),
     description: exports_external.string().optional()
@@ -9132,7 +9785,7 @@ Slug: ${list.slug}`
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("delete_task_list", "Delete a task list. Tasks lose association but keep data.", {
+  server.tool("delete_task_list", "Delete a task list. Tasks are orphaned, not deleted.", {
     id: exports_external.string()
   }, async ({ id }) => {
     try {
@@ -9148,7 +9801,7 @@ Slug: ${list.slug}`
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("get_task_history", "Get audit log for a task.", {
+  server.tool("get_task_history", "Get audit log \u2014 field changes with timestamps and actors.", {
     task_id: exports_external.string()
   }, async ({ task_id }) => {
     try {
@@ -9165,7 +9818,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("get_recent_activity", "Get recent task changes across all tasks.", {
+  server.tool("get_recent_activity", "Get recent task changes \u2014 global activity feed.", {
     limit: exports_external.number().optional()
   }, async ({ limit }) => {
     try {
@@ -9181,7 +9834,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("create_webhook", "Register a webhook to receive task change events.", {
+  server.tool("create_webhook", "Register a webhook for task change events.", {
     url: exports_external.string(),
     events: exports_external.array(exports_external.string()).optional(),
     secret: exports_external.string().optional()
@@ -9208,7 +9861,7 @@ ${text}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("delete_webhook", "Delete a webhook", {
+  server.tool("delete_webhook", "Delete a webhook by ID.", {
     id: exports_external.string()
   }, async ({ id }) => {
     try {
@@ -9274,7 +9927,7 @@ ${task.id.slice(0, 8)} | ${task.priority} | ${task.title}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("delete_template", "Delete a task template", { id: exports_external.string() }, async ({ id }) => {
+  server.tool("delete_template", "Delete a task template by ID.", { id: exports_external.string() }, async ({ id }) => {
     try {
       const { deleteTemplate: deleteTemplate2 } = await Promise.resolve().then(() => (init_templates(), exports_templates));
       const deleted = deleteTemplate2(id);
@@ -9283,7 +9936,7 @@ ${task.id.slice(0, 8)} | ${task.priority} | ${task.title}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("approve_task", "Approve a task that requires approval.", {
+  server.tool("approve_task", "Approve a task with requires_approval=true.", {
     id: exports_external.string(),
     agent_id: exports_external.string().optional()
   }, async ({ id, agent_id }) => {
@@ -9302,7 +9955,31 @@ ${task.id.slice(0, 8)} | ${task.priority} | ${task.title}` }] };
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("get_my_tasks", "Get assigned tasks and stats for an agent.", {
+  server.tool("fail_task", "Mark a task as failed with structured reason and optional auto-retry.", {
+    id: exports_external.string(),
+    agent_id: exports_external.string().optional(),
+    reason: exports_external.string().optional(),
+    error_code: exports_external.string().optional(),
+    retry: exports_external.boolean().optional(),
+    retry_after: exports_external.string().optional()
+  }, async ({ id, agent_id, reason, error_code, retry, retry_after }) => {
+    try {
+      const resolvedId = resolveId(id);
+      const result = failTask(resolvedId, agent_id, reason, { retry, retry_after, error_code });
+      let text = `failed: ${formatTask(result.task)}`;
+      if (reason)
+        text += `
+Reason: ${reason}`;
+      if (result.retryTask) {
+        text += `
+Retry task created: ${formatTask(result.retryTask)}`;
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("get_my_tasks", "Get tasks assigned to/created by an agent with stats.", {
     agent_name: exports_external.string()
   }, async ({ agent_name }) => {
     try {
@@ -9335,7 +10012,7 @@ In Progress:`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("get_org_chart", "Get agent org chart \u2014 who reports to who.", {}, async () => {
+  server.tool("get_org_chart", "Get agent org chart showing reporting hierarchy.", {}, async () => {
     try {
       let render = function(nodes, indent = 0) {
         return nodes.map((n) => {
@@ -9357,7 +10034,7 @@ In Progress:`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("set_reports_to", "Set who an agent reports to in the org chart.", {
+  server.tool("set_reports_to", "Set agent reporting relationship in org chart.", {
     agent_name: exports_external.string(),
     manager_name: exports_external.string().optional()
   }, async ({ agent_name, manager_name }) => {
@@ -9380,7 +10057,326 @@ In Progress:`);
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("search_tools", "List tool names matching a query.", { query: exports_external.string().optional() }, async ({ query }) => {
+  server.tool("bulk_update_tasks", "Update multiple tasks at once with the same changes.", {
+    task_ids: exports_external.array(exports_external.string()),
+    status: exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]).optional(),
+    priority: exports_external.enum(["low", "medium", "high", "critical"]).optional(),
+    assigned_to: exports_external.string().optional(),
+    tags: exports_external.array(exports_external.string()).optional()
+  }, async ({ task_ids, ...updates }) => {
+    try {
+      const resolvedIds = task_ids.map((id) => resolveId(id));
+      const result = bulkUpdateTasks(resolvedIds, updates);
+      const parts = [`Updated ${result.updated} task(s).`];
+      if (result.failed.length > 0) {
+        parts.push(`Failed ${result.failed.length}:`);
+        for (const f of result.failed)
+          parts.push(`  ${f.id.slice(0, 8)}: ${f.error}`);
+      }
+      return { content: [{ type: "text", text: parts.join(`
+`) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("clone_task", "Duplicate a task with optional field overrides.", {
+    task_id: exports_external.string(),
+    title: exports_external.string().optional(),
+    description: exports_external.string().optional(),
+    priority: exports_external.enum(["low", "medium", "high", "critical"]).optional(),
+    status: exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]).optional(),
+    project_id: exports_external.string().optional(),
+    plan_id: exports_external.string().optional(),
+    task_list_id: exports_external.string().optional(),
+    assigned_to: exports_external.string().optional(),
+    tags: exports_external.array(exports_external.string()).optional(),
+    estimated_minutes: exports_external.number().optional()
+  }, async ({ task_id, ...overrides }) => {
+    try {
+      const resolvedId = resolveId(task_id);
+      const resolved = { ...overrides };
+      if (resolved.project_id)
+        resolved.project_id = resolveId(resolved.project_id, "projects");
+      if (resolved.plan_id)
+        resolved.plan_id = resolveId(resolved.plan_id, "plans");
+      if (resolved.task_list_id)
+        resolved.task_list_id = resolveId(resolved.task_list_id, "task_lists");
+      const task = cloneTask(resolvedId, resolved);
+      return { content: [{ type: "text", text: `cloned: ${formatTask(task)}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("get_task_stats", "Get task analytics: counts by status, priority, agent.", {
+    project_id: exports_external.string().optional(),
+    task_list_id: exports_external.string().optional(),
+    agent_id: exports_external.string().optional()
+  }, async ({ project_id, task_list_id, agent_id }) => {
+    try {
+      const filters = {};
+      if (project_id)
+        filters.project_id = resolveId(project_id, "projects");
+      if (task_list_id)
+        filters.task_list_id = resolveId(task_list_id, "task_lists");
+      if (agent_id)
+        filters.agent_id = agent_id;
+      const stats = getTaskStats(Object.keys(filters).length > 0 ? filters : undefined);
+      return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("get_task_graph", "Get full dependency tree for a task.", {
+    id: exports_external.string(),
+    direction: exports_external.enum(["up", "down", "both"]).optional()
+  }, async ({ id, direction }) => {
+    try {
+      let formatNode = function(node, indent) {
+        const prefix = "  ".repeat(indent);
+        const idLabel = node.task.short_id || node.task.id.slice(0, 8);
+        const blocked = node.task.is_blocked ? " (blocked: yes)" : "";
+        let out = `${prefix}[${node.task.status}] ${idLabel} | ${node.task.title}${blocked}
+`;
+        if (node.depends_on.length > 0) {
+          out += `${prefix}  Depends on:
+`;
+          for (const dep of node.depends_on) {
+            out += formatNode(dep, indent + 2);
+          }
+        }
+        if (node.blocks.length > 0) {
+          out += `${prefix}  Blocks:
+`;
+          for (const dep of node.blocks) {
+            out += formatNode(dep, indent + 2);
+          }
+        }
+        return out;
+      };
+      const taskId = resolveId(id, "tasks");
+      const graph = getTaskGraph(taskId, direction || "both");
+      let text = `Task: ${formatNode(graph, 0)}`;
+      if (graph.depends_on.length > 0) {
+        text += `
+Depends on:
+`;
+        for (const dep of graph.depends_on) {
+          text += formatNode(dep, 1);
+        }
+      }
+      if (graph.blocks.length > 0) {
+        text += `
+Blocks:
+`;
+        for (const dep of graph.blocks) {
+          text += formatNode(dep, 1);
+        }
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("bulk_create_tasks", "Create multiple tasks atomically with dependency support.", {
+    tasks: exports_external.array(exports_external.object({
+      temp_id: exports_external.string().optional(),
+      title: exports_external.string(),
+      description: exports_external.string().optional(),
+      priority: exports_external.enum(["low", "medium", "high", "critical"]).optional(),
+      status: exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]).optional(),
+      project_id: exports_external.string().optional(),
+      plan_id: exports_external.string().optional(),
+      task_list_id: exports_external.string().optional(),
+      agent_id: exports_external.string().optional(),
+      assigned_to: exports_external.string().optional(),
+      tags: exports_external.array(exports_external.string()).optional(),
+      estimated_minutes: exports_external.number().optional(),
+      depends_on_temp_ids: exports_external.array(exports_external.string()).optional()
+    })),
+    project_id: exports_external.string().optional(),
+    plan_id: exports_external.string().optional(),
+    task_list_id: exports_external.string().optional()
+  }, async ({ tasks, project_id, plan_id, task_list_id }) => {
+    try {
+      const resolvedProjectId = project_id ? resolveId(project_id, "projects") : undefined;
+      const resolvedPlanId = plan_id ? resolveId(plan_id, "plans") : undefined;
+      const resolvedTaskListId = task_list_id ? resolveId(task_list_id, "task_lists") : undefined;
+      const enrichedTasks = tasks.map((t) => ({
+        ...t,
+        project_id: t.project_id || resolvedProjectId,
+        plan_id: t.plan_id || resolvedPlanId,
+        task_list_id: t.task_list_id || resolvedTaskListId
+      }));
+      const result = bulkCreateTasks(enrichedTasks);
+      const lines = result.created.map((t) => {
+        const tid = t.temp_id ? `[${t.temp_id}] ` : "";
+        const sid = t.short_id || t.id.slice(0, 8);
+        return `  ${tid}${sid} | ${t.title}`;
+      });
+      return { content: [{ type: "text", text: `Created ${result.created.length} task(s):
+${lines.join(`
+`)}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("move_task", "Move a task to a different list, project, or plan.", {
+    task_id: exports_external.string(),
+    task_list_id: exports_external.string().nullable().optional(),
+    project_id: exports_external.string().nullable().optional(),
+    plan_id: exports_external.string().nullable().optional()
+  }, async ({ task_id, ...target }) => {
+    try {
+      const resolvedId = resolveId(task_id);
+      const resolvedTarget = {};
+      if (target.task_list_id !== undefined)
+        resolvedTarget.task_list_id = target.task_list_id ? resolveId(target.task_list_id, "task_lists") : null;
+      if (target.project_id !== undefined)
+        resolvedTarget.project_id = target.project_id ? resolveId(target.project_id, "projects") : null;
+      if (target.plan_id !== undefined)
+        resolvedTarget.plan_id = target.plan_id ? resolveId(target.plan_id, "plans") : null;
+      const task = moveTask(resolvedId, resolvedTarget);
+      return { content: [{ type: "text", text: `moved: ${formatTask(task)}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("get_next_task", "Get the best pending task to work on next.", {
+    agent_id: exports_external.string().optional(),
+    project_id: exports_external.string().optional(),
+    task_list_id: exports_external.string().optional(),
+    plan_id: exports_external.string().optional(),
+    tags: exports_external.array(exports_external.string()).optional()
+  }, async ({ agent_id, project_id, task_list_id, plan_id, tags }) => {
+    try {
+      const filters = {};
+      if (project_id)
+        filters.project_id = resolveId(project_id, "projects");
+      if (task_list_id)
+        filters.task_list_id = resolveId(task_list_id, "task_lists");
+      if (plan_id)
+        filters.plan_id = resolveId(plan_id, "plans");
+      if (tags)
+        filters.tags = tags;
+      const task = getNextTask(agent_id, Object.keys(filters).length > 0 ? filters : undefined);
+      if (!task) {
+        return { content: [{ type: "text", text: "No tasks available \u2014 all pending tasks are blocked, locked, or none exist." }] };
+      }
+      return { content: [{ type: "text", text: `next: ${formatTask(task)}
+${formatTaskDetail(task)}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("get_active_work", "See all in-progress tasks and who is working on them.", {
+    project_id: exports_external.string().optional(),
+    task_list_id: exports_external.string().optional()
+  }, async ({ project_id, task_list_id }) => {
+    try {
+      const filters = {};
+      if (project_id)
+        filters.project_id = resolveId(project_id, "projects");
+      if (task_list_id)
+        filters.task_list_id = resolveId(task_list_id, "task_lists");
+      const work = getActiveWork(Object.keys(filters).length > 0 ? filters : undefined);
+      if (work.length === 0) {
+        return { content: [{ type: "text", text: "No active work \u2014 no tasks are currently in progress." }] };
+      }
+      const text = work.map((w) => {
+        const id = w.short_id || w.id.slice(0, 8);
+        const agent = w.assigned_to || w.locked_by || "unassigned";
+        const since = w.updated_at;
+        return `${agent.padEnd(12)} | ${w.priority.padEnd(8)} | ${id} | ${w.title} (since ${since})`;
+      }).join(`
+`);
+      return { content: [{ type: "text", text: `${work.length} active task(s):
+${text}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("get_tasks_changed_since", "Get tasks modified after a timestamp for incremental sync.", {
+    since: exports_external.string(),
+    project_id: exports_external.string().optional(),
+    task_list_id: exports_external.string().optional()
+  }, async ({ since, project_id, task_list_id }) => {
+    try {
+      const filters = {};
+      if (project_id)
+        filters.project_id = resolveId(project_id, "projects");
+      if (task_list_id)
+        filters.task_list_id = resolveId(task_list_id, "task_lists");
+      const tasks = getTasksChangedSince(since, Object.keys(filters).length > 0 ? filters : undefined);
+      if (tasks.length === 0) {
+        return { content: [{ type: "text", text: `No tasks changed since ${since}.` }] };
+      }
+      const text = tasks.map((t) => {
+        const assigned = t.assigned_to ? ` -> ${t.assigned_to}` : "";
+        return `[${t.status}] ${t.id.slice(0, 8)} | ${t.priority} | ${t.title}${assigned} (updated: ${t.updated_at})`;
+      }).join(`
+`);
+      return { content: [{ type: "text", text: `${tasks.length} task(s) changed since ${since}:
+${text}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("claim_next_task", "Atomically claim, lock, and start the best pending task.", {
+    agent_id: exports_external.string(),
+    project_id: exports_external.string().optional(),
+    task_list_id: exports_external.string().optional(),
+    plan_id: exports_external.string().optional(),
+    tags: exports_external.array(exports_external.string()).optional()
+  }, async ({ agent_id, project_id, task_list_id, plan_id, tags }) => {
+    try {
+      const filters = {};
+      if (project_id)
+        filters.project_id = resolveId(project_id, "projects");
+      if (task_list_id)
+        filters.task_list_id = resolveId(task_list_id, "task_lists");
+      if (plan_id)
+        filters.plan_id = resolveId(plan_id, "plans");
+      if (tags)
+        filters.tags = tags;
+      const task = claimNextTask(agent_id, Object.keys(filters).length > 0 ? filters : undefined);
+      if (!task) {
+        return { content: [{ type: "text", text: "No tasks available to claim." }] };
+      }
+      return { content: [{ type: "text", text: `claimed: ${formatTask(task)}
+${formatTaskDetail(task)}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("get_stale_tasks", "Find stale in_progress tasks with no recent activity.", {
+    stale_minutes: exports_external.number().optional(),
+    project_id: exports_external.string().optional(),
+    task_list_id: exports_external.string().optional()
+  }, async ({ stale_minutes, project_id, task_list_id }) => {
+    try {
+      const filters = {};
+      if (project_id)
+        filters.project_id = resolveId(project_id, "projects");
+      if (task_list_id)
+        filters.task_list_id = resolveId(task_list_id, "task_lists");
+      const tasks = getStaleTasks(stale_minutes || 30, Object.keys(filters).length > 0 ? filters : undefined);
+      if (tasks.length === 0) {
+        return { content: [{ type: "text", text: "No stale tasks found." }] };
+      }
+      const text = tasks.map((t) => {
+        const id = t.short_id || t.id.slice(0, 8);
+        const agent = t.locked_by || t.assigned_to || "unknown";
+        const staleFor = Math.round((Date.now() - new Date(t.updated_at).getTime()) / 60000);
+        return `${id} | ${agent} | ${t.title} (stale ${staleFor}min)`;
+      }).join(`
+`);
+      return { content: [{ type: "text", text: `${tasks.length} stale task(s):
+${text}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+  server.tool("search_tools", "List all tool names, optionally filtered by substring.", { query: exports_external.string().optional() }, async ({ query }) => {
     const all = [
       "create_task",
       "list_tasks",
@@ -9389,6 +10385,7 @@ In Progress:`);
       "delete_task",
       "start_task",
       "complete_task",
+      "fail_task",
       "lock_task",
       "unlock_task",
       "approve_task",
@@ -9405,7 +10402,11 @@ In Progress:`);
       "register_agent",
       "list_agents",
       "get_agent",
+      "rename_agent",
+      "delete_agent",
       "get_my_tasks",
+      "get_org_chart",
+      "set_reports_to",
       "create_task_list",
       "list_task_lists",
       "get_task_list",
@@ -9413,6 +10414,10 @@ In Progress:`);
       "delete_task_list",
       "search_tasks",
       "sync",
+      "clone_task",
+      "move_task",
+      "get_next_task",
+      "claim_next_task",
       "get_task_history",
       "get_recent_activity",
       "create_webhook",
@@ -9422,6 +10427,13 @@ In Progress:`);
       "list_templates",
       "create_task_from_template",
       "delete_template",
+      "bulk_update_tasks",
+      "bulk_create_tasks",
+      "get_task_stats",
+      "get_task_graph",
+      "get_active_work",
+      "get_tasks_changed_since",
+      "get_stale_tasks",
       "search_tools",
       "describe_tools"
     ];
@@ -9429,27 +10441,175 @@ In Progress:`);
     const matches = q ? all.filter((n) => n.includes(q)) : all;
     return { content: [{ type: "text", text: matches.join(", ") }] };
   });
-  server.tool("describe_tools", "Get descriptions for specific tools by name.", { names: exports_external.array(exports_external.string()) }, async ({ names }) => {
+  server.tool("describe_tools", "Get detailed parameter info for specific tools by name.", { names: exports_external.array(exports_external.string()) }, async ({ names }) => {
     const descriptions = {
-      create_task: "Create a task. Params: title(req), description, priority, project_id, plan_id, tags, assigned_to, estimated_minutes, requires_approval",
-      list_tasks: "List tasks. Params: status, priority, project_id, plan_id, assigned_to, tags, limit",
-      get_task: "Get full task details. Params: id",
-      update_task: "Update task fields. Params: id, version(req), title, description, status, priority, tags, assigned_to, due_at",
-      delete_task: "Delete a task. Params: id",
-      start_task: "Claim, lock, and start a task. Params: id",
-      complete_task: "Mark task completed. Params: id, agent_id",
-      approve_task: "Approve task requiring approval. Params: id, agent_id",
-      create_plan: "Create a plan. Params: name, description, project_id, task_list_id, agent_id, status",
-      list_plans: "List plans. Params: project_id",
-      get_plan: "Get plan with tasks. Params: id",
-      search_tasks: "Full-text search tasks. Params: query, project_id, task_list_id",
-      get_my_tasks: "Get your tasks and stats. Params: agent_name",
-      get_task_history: "Get task audit log. Params: task_id",
-      get_recent_activity: "Recent changes across all tasks. Params: limit",
-      create_template: "Create task template. Params: name, title_pattern, description, priority, tags",
-      create_task_from_template: "Create task from template. Params: template_id, title, priority, assigned_to"
+      create_task: `Create a new task.
+  Params: title(string, req), description(string), priority(low|medium|high|critical, default:medium), status(pending|in_progress|completed|failed|cancelled, default:pending), project_id(string), parent_id(string \u2014 creates subtask), plan_id(string), task_list_id(string), agent_id(string), assigned_to(string), tags(string[]), metadata(object), estimated_minutes(number), requires_approval(boolean), recurrence_rule(string \u2014 e.g. 'every day', 'every weekday', 'every 2 weeks', 'every monday'), session_id(string), working_dir(string)
+  Example: {title: 'Daily standup', recurrence_rule: 'every weekday', priority: 'medium'}`,
+      list_tasks: `List tasks with optional filters. Supports pagination.
+  Params: status(string|string[]), priority(string|string[]), project_id(string), plan_id(string), task_list_id(string), assigned_to(string), tags(string[]), has_recurrence(boolean \u2014 true=only recurring, false=only non-recurring), limit(number), offset(number)
+  Example: {status: ['pending', 'in_progress'], has_recurrence: true, limit: 20}`,
+      get_task: `Get full task details with subtasks, deps, and comments.
+  Params: id(string, req \u2014 task ID, short_id like 'APP-00001', or partial ID)
+  Example: {id: 'a1b2c3d4'}`,
+      update_task: `Update task fields. Requires version for optimistic locking (get it from get_task first).
+  Params: id(string, req), version(number, req), title(string), description(string), status(pending|in_progress|completed|failed|cancelled), priority(low|medium|high|critical), assigned_to(string), tags(string[]), metadata(object), plan_id(string), task_list_id(string)
+  Example: {id: 'a1b2c3d4', version: 3, status: 'completed'}`,
+      delete_task: `Delete a task permanently. Subtasks cascade-delete. Dependencies removed.
+  Params: id(string, req)
+  Example: {id: 'a1b2c3d4'}`,
+      start_task: `Claim, lock, and set task status to in_progress in one call.
+  Params: id(string, req), agent_id(string, req \u2014 your 8-char agent ID)
+  Example: {id: 'a1b2c3d4', agent_id: 'e5f6g7h8'}`,
+      complete_task: `Mark task completed, release lock, set completed_at timestamp. For recurring tasks, auto-spawns next instance unless skip_recurrence is true.
+  Params: id(string, req), agent_id(string, optional \u2014 required if locked by different agent), skip_recurrence(boolean \u2014 set true to prevent auto-creating next recurring instance)
+  Example: {id: 'a1b2c3d4', skip_recurrence: false}`,
+      lock_task: `Acquire exclusive lock on a task. Locks auto-expire after 30 min. Re-locking by same agent is idempotent.
+  Params: id(string, req), agent_id(string, req)
+  Example: {id: 'a1b2c3d4', agent_id: 'e5f6g7h8'}`,
+      unlock_task: `Release exclusive lock on a task.
+  Params: id(string, req), agent_id(string, optional \u2014 omit to force-unlock)
+  Example: {id: 'a1b2c3d4', agent_id: 'e5f6g7h8'}`,
+      approve_task: `Approve a task with requires_approval=true. Must be approved before completion.
+  Params: id(string, req), agent_id(string, optional \u2014 defaults to 'system')
+  Example: {id: 'a1b2c3d4', agent_id: 'e5f6g7h8'}`,
+      fail_task: `Mark a task as failed with structured reason and optional auto-retry. Stores failure info in metadata._failure, releases lock.
+  Params: id(string, req), agent_id(string, optional), reason(string), error_code(string \u2014 e.g. 'TIMEOUT'), retry(boolean \u2014 create new pending copy), retry_after(ISO date)
+  Example: {id: 'a1b2c3d4', reason: 'Build timeout', error_code: 'TIMEOUT', retry: true}`,
+      add_dependency: `Add a dependency: task_id depends on depends_on. Prevents cycles via BFS.
+  Params: task_id(string, req), depends_on(string, req)
+  Example: {task_id: 'abc12345', depends_on: 'def67890'}`,
+      remove_dependency: `Remove a dependency link between two tasks.
+  Params: task_id(string, req), depends_on(string, req)
+  Example: {task_id: 'abc12345', depends_on: 'def67890'}`,
+      add_comment: `Add a comment/note to a task. Comments are append-only.
+  Params: task_id(string, req), content(string, req), agent_id(string), session_id(string)
+  Example: {task_id: 'a1b2c3d4', content: 'Blocked by API rate limit'}`,
+      create_project: `Register a new project. Auto-generates task prefix for short IDs (e.g. APP-00001).
+  Params: name(string, req), path(string, req \u2014 unique absolute path), description(string), task_list_id(string)
+  Example: {name: 'my-app', path: '/Users/dev/my-app'}`,
+      list_projects: "List all registered projects. No params.",
+      create_plan: `Create a plan to group related tasks.
+  Params: name(string, req), project_id(string), description(string), status(active|completed|archived, default:active), task_list_id(string), agent_id(string)
+  Example: {name: 'Sprint 1', project_id: 'a1b2c3d4'}`,
+      list_plans: `List all plans, optionally filtered by project.
+  Params: project_id(string)
+  Example: {project_id: 'a1b2c3d4'}`,
+      get_plan: `Get plan details (name, status, description, timestamps).
+  Params: id(string, req)
+  Example: {id: 'a1b2c3d4'}`,
+      update_plan: `Update plan fields.
+  Params: id(string, req), name(string), description(string), status(active|completed|archived), task_list_id(string), agent_id(string)
+  Example: {id: 'a1b2c3d4', status: 'completed'}`,
+      delete_plan: `Delete a plan. Tasks in the plan are orphaned, not deleted.
+  Params: id(string, req)
+  Example: {id: 'a1b2c3d4'}`,
+      register_agent: `Register an agent (idempotent by name). Returns existing agent if name matches.
+  Params: name(string, req \u2014 e.g. 'maximus'), description(string)
+  Example: {name: 'maximus', description: 'Backend developer'}`,
+      list_agents: "List all registered agents with IDs, names, and last seen timestamps. No params.",
+      get_agent: `Get agent details by ID or name. Provide one of id or name.
+  Params: id(string), name(string)
+  Example: {name: 'maximus'}`,
+      rename_agent: `Rename an agent. Resolve by id or current name.
+  Params: id(string), name(string \u2014 current name), new_name(string, req)
+  Example: {name: 'old-name', new_name: 'new-name'}`,
+      delete_agent: `Delete an agent permanently. Resolve by id or name.
+  Params: id(string), name(string)
+  Example: {name: 'maximus'}`,
+      get_my_tasks: `Get all tasks assigned to/created by an agent, with stats (pending/active/done/rate).
+  Params: agent_name(string, req)
+  Example: {agent_name: 'maximus'}`,
+      get_org_chart: "Get agent org chart showing reporting hierarchy. No params.",
+      set_reports_to: `Set who an agent reports to in the org chart. Omit manager_name for top-level.
+  Params: agent_name(string, req), manager_name(string, optional)
+  Example: {agent_name: 'brutus', manager_name: 'maximus'}`,
+      create_task_list: `Create a task list \u2014 a container/folder for organizing tasks.
+  Params: name(string, req), slug(string \u2014 auto-generated if omitted), project_id(string), description(string)
+  Example: {name: 'Sprint 1', project_id: 'a1b2c3d4'}`,
+      list_task_lists: `List all task lists, optionally filtered by project.
+  Params: project_id(string)
+  Example: {project_id: 'a1b2c3d4'}`,
+      get_task_list: `Get task list details (name, slug, project, metadata).
+  Params: id(string, req)
+  Example: {id: 'a1b2c3d4'}`,
+      update_task_list: `Update a task list's name or description.
+  Params: id(string, req), name(string), description(string)
+  Example: {id: 'a1b2c3d4', name: 'Sprint 2'}`,
+      delete_task_list: `Delete a task list. Tasks are orphaned (not deleted).
+  Params: id(string, req)
+  Example: {id: 'a1b2c3d4'}`,
+      search_tasks: `Full-text search across task titles, descriptions, and tags. Supports filters.
+  Params: query(string, req), project_id(string), task_list_id(string), status(string|string[]), priority(string|string[]), assigned_to(string), agent_id(string), created_after(ISO date), updated_after(ISO date), has_dependencies(boolean), is_blocked(boolean)
+  Example: {query: 'auth bug', status: 'pending'}`,
+      get_next_task: `Get the optimal next task to work on \u2014 finds highest-priority pending task that is not blocked or locked. Prefers tasks assigned to the given agent.
+  Params: agent_id(string \u2014 prefers your tasks), project_id(string), task_list_id(string), plan_id(string), tags(string[])
+  Example: {agent_id: 'a1b2c3d4', project_id: 'e5f6g7h8'}`,
+      claim_next_task: `Atomically find the best pending task, lock it, and start it \u2014 one call instead of get_next_task + start_task. Eliminates race conditions between agents.
+  Params: agent_id(string, req \u2014 used for lock and assignment), project_id(string), task_list_id(string), plan_id(string), tags(string[])
+  Example: {agent_id: 'a1b2c3d4', project_id: 'e5f6g7h8'}`,
+      sync: `Sync tasks between local DB and agent task list (e.g. Claude Code).
+  Params: agent(string, default:'claude'), task_list_id(string), all_agents(boolean), project_id(string), direction(push|pull|both, default:both), prefer(local|remote, default:remote)
+  Example: {agent: 'claude', direction: 'push'}`,
+      clone_task: `Duplicate a task with optional field overrides. Creates new independent copy.
+  Params: task_id(string, req), title(string), description(string), priority(low|medium|high|critical), status(pending|in_progress|completed|failed|cancelled), project_id(string), plan_id(string), task_list_id(string), assigned_to(string), tags(string[]), estimated_minutes(number)
+  Example: {task_id: 'a1b2c3d4', title: 'Cloned task', assigned_to: 'brutus'}`,
+      move_task: `Move a task to a different list, project, or plan.
+  Params: task_id(string, req), task_list_id(string|null), project_id(string|null), plan_id(string|null)
+  Example: {task_id: 'a1b2c3d4', task_list_id: 'e5f6g7h8'}`,
+      bulk_update_tasks: `Update multiple tasks at once with the same changes.
+  Params: task_ids(string[], req), status(pending|in_progress|completed|failed|cancelled), priority(low|medium|high|critical), assigned_to(string), tags(string[])
+  Example: {task_ids: ['abc12345', 'def67890'], status: 'completed'}`,
+      bulk_create_tasks: `Create multiple tasks atomically. Supports inter-task dependencies via temp_id references.
+  Params: tasks(array, req \u2014 [{temp_id, title, description, priority, status, project_id, plan_id, task_list_id, agent_id, assigned_to, tags, estimated_minutes, depends_on_temp_ids}]), project_id(string \u2014 default for all), plan_id(string \u2014 default for all), task_list_id(string \u2014 default for all)
+  Example: {tasks: [{temp_id: 'a', title: 'First'}, {temp_id: 'b', title: 'Second', depends_on_temp_ids: ['a']}]}`,
+      get_task_stats: `Get task analytics: counts by status, priority, agent, and completion rate. All via SQL.
+  Params: project_id(string), task_list_id(string), agent_id(string)
+  Example: {project_id: 'a1b2c3d4'}`,
+      get_task_graph: `Get full dependency tree for a task \u2014 upstream blockers and downstream dependents.
+  Params: id(string, req), direction(up|down|both, default:both)
+  Example: {id: 'a1b2c3d4', direction: 'up'}`,
+      get_task_history: `Get audit log for a task \u2014 all field changes with timestamps and actors.
+  Params: task_id(string, req)
+  Example: {task_id: 'a1b2c3d4'}`,
+      get_recent_activity: `Get recent task changes across all tasks \u2014 global activity feed.
+  Params: limit(number, default:50)
+  Example: {limit: 20}`,
+      create_webhook: `Register a webhook for task change events.
+  Params: url(string, req), events(string[] \u2014 empty=all), secret(string \u2014 HMAC signing)
+  Example: {url: 'https://example.com/hook', events: ['task.created', 'task.completed']}`,
+      list_webhooks: "List all registered webhooks. No params.",
+      delete_webhook: `Delete a webhook by ID.
+  Params: id(string, req)
+  Example: {id: 'a1b2c3d4'}`,
+      create_template: `Create a reusable task template.
+  Params: name(string, req), title_pattern(string, req \u2014 e.g. 'Fix: {description}'), description(string), priority(low|medium|high|critical), tags(string[]), project_id(string), plan_id(string)
+  Example: {name: 'Bug Report', title_pattern: 'Bug: {description}', priority: 'high', tags: ['bug']}`,
+      list_templates: "List all task templates. No params.",
+      create_task_from_template: `Create a task from a template with optional overrides.
+  Params: template_id(string, req), title(string), description(string), priority(low|medium|high|critical), assigned_to(string), project_id(string)
+  Example: {template_id: 'a1b2c3d4', assigned_to: 'maximus'}`,
+      delete_template: `Delete a task template.
+  Params: id(string, req)
+  Example: {id: 'a1b2c3d4'}`,
+      get_active_work: `See all in-progress tasks and who is working on them.
+  Params: project_id(string, optional), task_list_id(string, optional)
+  Example: {project_id: 'a1b2c3d4'}`,
+      get_tasks_changed_since: `Get tasks modified after a timestamp \u2014 incremental delta sync.
+  Params: since(string, req \u2014 ISO date), project_id(string, optional), task_list_id(string, optional)
+  Example: {since: '2026-03-14T10:00:00Z'}`,
+      get_stale_tasks: `Find stale in_progress tasks with no recent activity.
+  Params: stale_minutes(number, default:30), project_id(string, optional), task_list_id(string, optional)
+  Example: {stale_minutes: 60, project_id: 'a1b2c3d4'}`,
+      search_tools: `List all tool names or filter by substring.
+  Params: query(string, optional)
+  Example: {query: 'task'}`,
+      describe_tools: `Get detailed descriptions and parameter info for tools by name.
+  Params: names(string[], req)
+  Example: {names: ['create_task', 'update_task']}`
     };
-    const result = names.map((n) => `${n}: ${descriptions[n] || "See tool schema"}`).join(`
+    const result = names.map((n) => `${n}: ${descriptions[n] || "Unknown tool. Use search_tools to list available tools."}`).join(`
+
 `);
     return { content: [{ type: "text", text: result }] };
   });