@hasna/todos 0.9.34 → 0.9.35

package/dist/mcp/index.js

@@ -192,6 +192,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");
@@ -216,6 +218,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 {
@@ -515,6 +519,13 @@ 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);
   `
   ];
 });
@@ -4789,6 +4800,8 @@ 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;
@@ -4800,14 +4813,30 @@ class VersionConflictError extends Error {
 
 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;
     this.name = "TaskNotFoundError";
   }
 }
+
+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;
+    this.name = "ProjectNotFoundError";
+  }
+}
+
 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;
@@ -4818,6 +4847,8 @@ class PlanNotFoundError extends Error {
 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;
@@ -4825,8 +4856,22 @@ class LockError extends Error {
     this.name = "LockError";
   }
 }
+
+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";
+  }
+}
+
 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;
@@ -4837,6 +4882,8 @@ class TaskListNotFoundError extends Error {
 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;
@@ -4848,6 +4895,8 @@ class DependencyCycleError extends Error {
 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;
@@ -5074,6 +5123,95 @@ function checkCompletionGuard(task, agentId, db, configOverride) {
 
 // src/db/tasks.ts
 init_audit();
+
+// src/lib/recurrence.ts
+var 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
+};
+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}"`);
+}
+
+// src/db/tasks.ts
 function rowToTask(row) {
   return {
     ...row,
@@ -5104,8 +5242,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,
@@ -5128,7 +5266,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);
@@ -5228,6 +5368,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) {
@@ -5243,6 +5388,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);
@@ -5314,6 +5522,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) {
@@ -5387,7 +5599,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)
@@ -5396,7 +5608,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]);
   }
@@ -5404,7 +5618,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) {
@@ -5467,6 +5688,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];
@@ -5484,6 +5965,91 @@ 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 };
+}
 
 // src/db/comments.ts
 init_database();
@@ -5657,19 +6223,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,
@@ -6199,28 +6810,41 @@ function syncWithAgents(agents, taskListIdByAgent, projectId, direction = "both"
 init_database();
 var server = new McpServer({
   name: "todos",
-  version: "0.9.33"
+  version: "0.9.35"
 });
 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 error.message;
-  return String(error);
+  if (error instanceof Error) {
+    return JSON.stringify({ code: "UNKNOWN_ERROR", message: error.message });
+  }
+  return JSON.stringify({ code: "UNKNOWN_ERROR", message: String(error) });
 }
 function resolveId(partialId, table = "tasks") {
   const db = getDatabase();
@@ -6243,7 +6867,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 = [
@@ -6268,6 +6893,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)
@@ -6291,7 +6920,8 @@ server.tool("create_task", "Create a new task", {
   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 };
@@ -6309,7 +6939,7 @@ server.tool("create_task", "Create a new task", {
     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"]),
@@ -6322,7 +6952,10 @@ server.tool("list_tasks", "List tasks with optional filters", {
   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 };
@@ -6333,8 +6966,10 @@ server.tool("list_tasks", "List tasks with optional filters", {
     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}]` : "";
@@ -6342,13 +6977,15 @@ server.tool("list_tasks", "List tasks with optional filters", {
       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 {
@@ -6417,7 +7054,7 @@ server.tool("update_task", "Update task fields. Version required for optimistic
     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 {
@@ -6433,7 +7070,7 @@ server.tool("delete_task", "Delete a task permanently", {
     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 }) => {
@@ -6445,19 +7082,26 @@ server.tool("start_task", "Claim, lock, and set task status to in_progress.", {
     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 }) => {
@@ -6472,7 +7116,7 @@ server.tool("lock_task", "Acquire exclusive lock on a task", {
     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 }) => {
@@ -6484,7 +7128,7 @@ server.tool("unlock_task", "Release exclusive lock on a task", {
     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 }) => {
@@ -6497,7 +7141,7 @@ server.tool("add_dependency", "Add a dependency: task_id depends on depends_on."
     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 }) => {
@@ -6515,7 +7159,7 @@ server.tool("remove_dependency", "Remove a dependency between tasks", {
     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(),
@@ -6546,7 +7190,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(),
@@ -6565,7 +7209,7 @@ server.tool("create_project", "Register a new project", {
     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(),
@@ -6590,7 +7234,7 @@ server.tool("create_plan", "Create a new plan", {
     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 {
@@ -6610,7 +7254,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 {
@@ -6635,7 +7279,7 @@ server.tool("get_plan", "Get plan details", {
     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(),
@@ -6659,7 +7303,7 @@ server.tool("update_plan", "Update a plan", {
     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 {
@@ -6675,15 +7319,34 @@ server.tool("delete_plan", "Delete a plan", {
     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}".` }] };
     }
@@ -6695,7 +7358,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(),
@@ -6743,7 +7406,7 @@ server.tool("sync", "Sync tasks with an agent task list.", {
     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 }) => {
@@ -6780,7 +7443,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 }) => {
@@ -6809,9 +7472,9 @@ server.tool("get_agent", "Get agent details by ID or name", {
   }
 });
 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) {
@@ -6834,8 +7497,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) {
@@ -6857,7 +7520,7 @@ server.tool("delete_agent", "Delete an agent permanently. Resolve by id or name.
     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(),
@@ -6883,7 +7546,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 {
@@ -6903,7 +7566,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 {
@@ -6931,7 +7594,7 @@ server.tool("get_task_list", "Get task list details", {
     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()
@@ -6952,7 +7615,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 {
@@ -6968,7 +7631,7 @@ server.tool("delete_task_list", "Delete a task list. Tasks lose association but
     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 {
@@ -6985,7 +7648,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 {
@@ -7001,7 +7664,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()
@@ -7028,7 +7691,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 {
@@ -7094,7 +7757,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);
@@ -7103,7 +7766,7 @@ server.tool("delete_template", "Delete a task template", { id: exports_external.
     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 }) => {
@@ -7122,7 +7785,31 @@ server.tool("approve_task", "Approve a task that requires approval.", {
     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 {
@@ -7155,7 +7842,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) => {
@@ -7177,7 +7864,7 @@ server.tool("get_org_chart", "Get agent org chart \u2014 who reports to who.", {
     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 }) => {
@@ -7200,7 +7887,326 @@ server.tool("set_reports_to", "Set who an agent reports to in the org chart.", {
     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",
@@ -7209,6 +8215,7 @@ server.tool("search_tools", "List tool names matching a query.", { query: export
     "delete_task",
     "start_task",
     "complete_task",
+    "fail_task",
     "lock_task",
     "unlock_task",
     "approve_task",
@@ -7225,7 +8232,11 @@ server.tool("search_tools", "List tool names matching a query.", { query: export
     "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",
@@ -7233,6 +8244,10 @@ server.tool("search_tools", "List tool names matching a query.", { query: export
     "delete_task_list",
     "search_tasks",
     "sync",
+    "clone_task",
+    "move_task",
+    "get_next_task",
+    "claim_next_task",
     "get_task_history",
     "get_recent_activity",
     "create_webhook",
@@ -7242,6 +8257,13 @@ server.tool("search_tools", "List tool names matching a query.", { query: export
     "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"
   ];
@@ -7249,27 +8271,175 @@ server.tool("search_tools", "List tool names matching a query.", { query: export
   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 }] };
 });