@hasna/todos 0.9.69 → 0.9.70

package/dist/mcp/index.js

@@ -533,6 +533,58 @@ var init_database = __esm(() => {
   ALTER TABLE task_comments ADD COLUMN type TEXT DEFAULT 'comment' CHECK(type IN ('comment', 'progress', 'note'));
   ALTER TABLE task_comments ADD COLUMN progress_pct INTEGER CHECK(progress_pct IS NULL OR (progress_pct >= 0 AND progress_pct <= 100));
   INSERT OR IGNORE INTO _migrations (id) VALUES (14);
+  `,
+    `
+  CREATE VIRTUAL TABLE IF NOT EXISTS tasks_fts USING fts5(
+    task_id UNINDEXED,
+    title,
+    description,
+    tags,
+    tokenize='unicode61 remove_diacritics 2'
+  );
+
+  INSERT INTO tasks_fts(rowid, task_id, title, description, tags)
+  SELECT t.rowid, t.id, t.title, COALESCE(t.description, ''),
+    COALESCE((SELECT GROUP_CONCAT(tag, ' ') FROM task_tags WHERE task_id = t.id), '')
+  FROM tasks t;
+
+  CREATE TRIGGER IF NOT EXISTS tasks_fts_ai AFTER INSERT ON tasks BEGIN
+    INSERT INTO tasks_fts(rowid, task_id, title, description, tags)
+    VALUES (new.rowid, new.id, new.title, COALESCE(new.description, ''), '');
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS tasks_fts_ad AFTER DELETE ON tasks BEGIN
+    DELETE FROM tasks_fts WHERE rowid = old.rowid;
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS tasks_fts_au AFTER UPDATE OF title, description ON tasks BEGIN
+    DELETE FROM tasks_fts WHERE rowid = old.rowid;
+    INSERT INTO tasks_fts(rowid, task_id, title, description, tags)
+    SELECT new.rowid, new.id, new.title, COALESCE(new.description, ''),
+      COALESCE((SELECT GROUP_CONCAT(tag, ' ') FROM task_tags WHERE task_id = new.id), '');
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS task_tags_fts_ai AFTER INSERT ON task_tags BEGIN
+    DELETE FROM tasks_fts WHERE rowid = (SELECT rowid FROM tasks WHERE id = new.task_id);
+    INSERT INTO tasks_fts(rowid, task_id, title, description, tags)
+    SELECT t.rowid, t.id, t.title, COALESCE(t.description, ''),
+      COALESCE((SELECT GROUP_CONCAT(tag, ' ') FROM task_tags WHERE task_id = t.id), '')
+    FROM tasks t WHERE t.id = new.task_id;
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS task_tags_fts_ad AFTER DELETE ON task_tags BEGIN
+    DELETE FROM tasks_fts WHERE rowid = (SELECT rowid FROM tasks WHERE id = old.task_id);
+    INSERT INTO tasks_fts(rowid, task_id, title, description, tags)
+    SELECT t.rowid, t.id, t.title, COALESCE(t.description, ''),
+      COALESCE((SELECT GROUP_CONCAT(tag, ' ') FROM task_tags WHERE task_id = t.id), '')
+    FROM tasks t WHERE t.id = old.task_id;
+  END;
+
+  INSERT OR IGNORE INTO _migrations (id) VALUES (15);
+  `,
+    `
+  ALTER TABLE tasks ADD COLUMN spawns_template_id TEXT REFERENCES task_templates(id) ON DELETE SET NULL;
+  INSERT OR IGNORE INTO _migrations (id) VALUES (16);
   `
   ];
 });
@@ -615,6 +667,73 @@ var init_webhooks = __esm(() => {
   init_database();
 });
 
+// src/db/templates.ts
+var exports_templates = {};
+__export(exports_templates, {
+  taskFromTemplate: () => taskFromTemplate,
+  listTemplates: () => listTemplates,
+  getTemplate: () => getTemplate,
+  deleteTemplate: () => deleteTemplate,
+  createTemplate: () => createTemplate
+});
+function rowToTemplate(row) {
+  return {
+    ...row,
+    tags: JSON.parse(row.tags || "[]"),
+    metadata: JSON.parse(row.metadata || "{}"),
+    priority: row.priority || "medium"
+  };
+}
+function createTemplate(input, db) {
+  const d = db || getDatabase();
+  const id = uuid();
+  d.run(`INSERT INTO task_templates (id, name, title_pattern, description, priority, tags, project_id, plan_id, metadata, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+    id,
+    input.name,
+    input.title_pattern,
+    input.description || null,
+    input.priority || "medium",
+    JSON.stringify(input.tags || []),
+    input.project_id || null,
+    input.plan_id || null,
+    JSON.stringify(input.metadata || {}),
+    now()
+  ]);
+  return getTemplate(id, d);
+}
+function getTemplate(id, db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT * FROM task_templates WHERE id = ?").get(id);
+  return row ? rowToTemplate(row) : null;
+}
+function listTemplates(db) {
+  const d = db || getDatabase();
+  return d.query("SELECT * FROM task_templates ORDER BY name").all().map(rowToTemplate);
+}
+function deleteTemplate(id, db) {
+  const d = db || getDatabase();
+  return d.run("DELETE FROM task_templates WHERE id = ?", [id]).changes > 0;
+}
+function taskFromTemplate(templateId, overrides = {}, db) {
+  const t = getTemplate(templateId, db);
+  if (!t)
+    throw new Error(`Template not found: ${templateId}`);
+  return {
+    title: overrides.title || t.title_pattern,
+    description: overrides.description ?? t.description ?? undefined,
+    priority: overrides.priority ?? t.priority,
+    tags: overrides.tags ?? t.tags,
+    project_id: overrides.project_id ?? t.project_id ?? undefined,
+    plan_id: overrides.plan_id ?? t.plan_id ?? undefined,
+    metadata: overrides.metadata ?? t.metadata,
+    ...overrides
+  };
+}
+var init_templates = __esm(() => {
+  init_database();
+});
+
 // src/db/agents.ts
 var exports_agents = {};
 __export(exports_agents, {
@@ -758,73 +877,6 @@ var init_agents = __esm(() => {
   init_database();
 });
 
-// src/db/templates.ts
-var exports_templates = {};
-__export(exports_templates, {
-  taskFromTemplate: () => taskFromTemplate,
-  listTemplates: () => listTemplates,
-  getTemplate: () => getTemplate,
-  deleteTemplate: () => deleteTemplate,
-  createTemplate: () => createTemplate
-});
-function rowToTemplate(row) {
-  return {
-    ...row,
-    tags: JSON.parse(row.tags || "[]"),
-    metadata: JSON.parse(row.metadata || "{}"),
-    priority: row.priority || "medium"
-  };
-}
-function createTemplate(input, db) {
-  const d = db || getDatabase();
-  const id = uuid();
-  d.run(`INSERT INTO task_templates (id, name, title_pattern, description, priority, tags, project_id, plan_id, metadata, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
-    id,
-    input.name,
-    input.title_pattern,
-    input.description || null,
-    input.priority || "medium",
-    JSON.stringify(input.tags || []),
-    input.project_id || null,
-    input.plan_id || null,
-    JSON.stringify(input.metadata || {}),
-    now()
-  ]);
-  return getTemplate(id, d);
-}
-function getTemplate(id, db) {
-  const d = db || getDatabase();
-  const row = d.query("SELECT * FROM task_templates WHERE id = ?").get(id);
-  return row ? rowToTemplate(row) : null;
-}
-function listTemplates(db) {
-  const d = db || getDatabase();
-  return d.query("SELECT * FROM task_templates ORDER BY name").all().map(rowToTemplate);
-}
-function deleteTemplate(id, db) {
-  const d = db || getDatabase();
-  return d.run("DELETE FROM task_templates WHERE id = ?", [id]).changes > 0;
-}
-function taskFromTemplate(templateId, overrides = {}, db) {
-  const t = getTemplate(templateId, db);
-  if (!t)
-    throw new Error(`Template not found: ${templateId}`);
-  return {
-    title: overrides.title || t.title_pattern,
-    description: overrides.description ?? t.description ?? undefined,
-    priority: overrides.priority ?? t.priority,
-    tags: overrides.tags ?? t.tags,
-    project_id: overrides.project_id ?? t.project_id ?? undefined,
-    plan_id: overrides.plan_id ?? t.plan_id ?? undefined,
-    metadata: overrides.metadata ?? t.metadata,
-    ...overrides
-  };
-}
-var init_templates = __esm(() => {
-  init_database();
-});
-
 // src/mcp/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -5222,6 +5274,7 @@ function nextOccurrence(rule, from) {
 
 // src/db/tasks.ts
 init_webhooks();
+init_templates();
 function rowToTask(row) {
   return {
     ...row,
@@ -5252,8 +5305,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, recurrence_rule, recurrence_parent_id)
-     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, spawns_template_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
     id,
     shortId,
     input.project_id || null,
@@ -5278,7 +5331,8 @@ function createTask(input, db) {
     null,
     null,
     input.recurrence_rule || null,
-    input.recurrence_parent_id || null
+    input.recurrence_parent_id || null,
+    input.spawns_template_id || null
   ]);
   if (tags.length > 0) {
     insertTaskTags(id, tags, d);
@@ -5385,19 +5439,25 @@ function listTasks(filter = {}, db) {
   } else if (filter.has_recurrence === false) {
     conditions.push("recurrence_rule IS NULL");
   }
+  const PRIORITY_RANK = `CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END`;
+  if (filter.cursor) {
+    try {
+      const decoded = JSON.parse(Buffer.from(filter.cursor, "base64").toString("utf8"));
+      conditions.push(`(${PRIORITY_RANK} > ? OR (${PRIORITY_RANK} = ? AND created_at < ?) OR (${PRIORITY_RANK} = ? AND created_at = ? AND id > ?))`);
+      params.push(decoded.p, decoded.p, decoded.c, decoded.p, decoded.c, decoded.i);
+    } catch {}
+  }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   let limitClause = "";
   if (filter.limit) {
     limitClause = " LIMIT ?";
     params.push(filter.limit);
-    if (filter.offset) {
+    if (!filter.cursor && filter.offset) {
       limitClause += " OFFSET ?";
       params.push(filter.offset);
     }
   }
-  const rows = d.query(`SELECT * FROM tasks ${where} ORDER BY
-       CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END,
-       created_at DESC${limitClause}`).all(...params);
+  const rows = d.query(`SELECT * FROM tasks ${where} ORDER BY ${PRIORITY_RANK}, created_at DESC${limitClause}`).all(...params);
   return rows.map(rowToTask);
 }
 function countTasks(filter = {}, db) {
@@ -5642,10 +5702,25 @@ function completeTask(id, agentId, db, options) {
   if (task.recurrence_rule && !options?.skip_recurrence) {
     spawnedTask = spawnNextRecurrence(task, d);
   }
+  let spawnedFromTemplate = null;
+  if (task.spawns_template_id) {
+    try {
+      const input = taskFromTemplate(task.spawns_template_id, {
+        project_id: task.project_id ?? undefined,
+        plan_id: task.plan_id ?? undefined,
+        task_list_id: task.task_list_id ?? undefined,
+        assigned_to: task.assigned_to ?? undefined
+      }, d);
+      spawnedFromTemplate = createTask(input, d);
+    } catch {}
+  }
   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 };
   }
+  if (spawnedFromTemplate) {
+    meta._spawned_task = { id: spawnedFromTemplate.id, short_id: spawnedFromTemplate.short_id, title: spawnedFromTemplate.title };
+  }
   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) {
@@ -5853,11 +5928,21 @@ function getNextTask(agentId, filters, db) {
   }
   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 recentProjectIds = [];
+  if (agentId) {
+    const recentRows = d.query(`SELECT DISTINCT project_id FROM tasks WHERE assigned_to = ? AND status = 'completed' AND project_id IS NOT NULL ORDER BY completed_at DESC LIMIT 3`).all(agentId);
+    recentProjectIds = recentRows.map((r) => r.project_id);
+  }
   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);
   }
+  if (recentProjectIds.length > 0) {
+    const placeholders = recentProjectIds.map(() => "?").join(",");
+    sql += `CASE WHEN project_id IN (${placeholders}) THEN 0 ELSE 1 END, `;
+    params.push(...recentProjectIds);
+  }
   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;
@@ -6363,68 +6448,95 @@ function rowToTask2(row) {
     requires_approval: Boolean(row.requires_approval)
   };
 }
+function hasFts(db) {
+  try {
+    const result = db.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name='tasks_fts'").get();
+    return result !== null;
+  } catch {
+    return false;
+  }
+}
+function escapeFtsQuery(q) {
+  return q.replace(/["*^()]/g, " ").trim().split(/\s+/).filter(Boolean).map((token) => `"${token}"*`).join(" ");
+}
 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 = `%${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];
+  const params = [];
+  let sql;
+  if (hasFts(d) && opts.query.trim()) {
+    const ftsQuery = escapeFtsQuery(opts.query);
+    sql = `SELECT t.* FROM tasks t
+      INNER JOIN tasks_fts fts ON fts.rowid = t.rowid
+      WHERE tasks_fts MATCH ?`;
+    params.push(ftsQuery);
+  } else {
+    const pattern = `%${opts.query}%`;
+    sql = `SELECT * FROM tasks t WHERE (t.title LIKE ? OR t.description LIKE ? OR EXISTS (SELECT 1 FROM task_tags WHERE task_tags.task_id = t.id AND tag LIKE ?))`;
+    params.push(pattern, pattern, pattern);
+  }
   if (opts.project_id) {
-    sql += " AND project_id = ?";
+    sql += " AND t.project_id = ?";
     params.push(opts.project_id);
   }
   if (opts.task_list_id) {
-    sql += " AND task_list_id = ?";
+    sql += " AND t.task_list_id = ?";
     params.push(opts.task_list_id);
   }
   if (opts.status) {
     if (Array.isArray(opts.status)) {
-      sql += ` AND status IN (${opts.status.map(() => "?").join(",")})`;
+      sql += ` AND t.status IN (${opts.status.map(() => "?").join(",")})`;
       params.push(...opts.status);
     } else {
-      sql += " AND status = ?";
+      sql += " AND t.status = ?";
       params.push(opts.status);
     }
   }
   if (opts.priority) {
     if (Array.isArray(opts.priority)) {
-      sql += ` AND priority IN (${opts.priority.map(() => "?").join(",")})`;
+      sql += ` AND t.priority IN (${opts.priority.map(() => "?").join(",")})`;
       params.push(...opts.priority);
     } else {
-      sql += " AND priority = ?";
+      sql += " AND t.priority = ?";
       params.push(opts.priority);
     }
   }
   if (opts.assigned_to) {
-    sql += " AND assigned_to = ?";
+    sql += " AND t.assigned_to = ?";
     params.push(opts.assigned_to);
   }
   if (opts.agent_id) {
-    sql += " AND agent_id = ?";
+    sql += " AND t.agent_id = ?";
     params.push(opts.agent_id);
   }
   if (opts.created_after) {
-    sql += " AND created_at > ?";
+    sql += " AND t.created_at > ?";
     params.push(opts.created_after);
   }
   if (opts.updated_after) {
-    sql += " AND updated_at > ?";
+    sql += " AND t.updated_at > ?";
     params.push(opts.updated_after);
   }
   if (opts.has_dependencies === true) {
-    sql += " AND id IN (SELECT task_id FROM task_dependencies)";
+    sql += " AND t.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)";
+    sql += " AND t.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')";
+    sql += " AND t.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 += " AND t.id NOT IN (SELECT td.task_id FROM task_dependencies td JOIN tasks dep ON dep.id = td.depends_on WHERE dep.status != 'completed')";
+  }
+  if (hasFts(d) && opts.query.trim()) {
+    sql += ` ORDER BY bm25(tasks_fts),
+      CASE t.priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END,
+      t.created_at DESC`;
+  } else {
+    sql += ` ORDER BY
+      CASE t.priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END,
+      t.created_at DESC`;
   }
-  sql += ` ORDER BY
-    CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END,
-    created_at DESC`;
   const rows = d.query(sql).all(...params);
   return rows.map(rowToTask2);
 }
@@ -6974,7 +7086,9 @@ var MINIMAL_TOOLS = new Set([
   "get_task",
   "start_task",
   "add_comment",
-  "get_next_task"
+  "get_next_task",
+  "bootstrap",
+  "get_tasks_changed_since"
 ]);
 var STANDARD_EXCLUDED = new Set([
   "get_org_chart",
@@ -7055,15 +7169,17 @@ function formatTask(task) {
   const recur = task.recurrence_rule ? ` [\u21BB]` : "";
   return `${id} ${task.status.padEnd(11)} ${task.priority.padEnd(8)} ${task.title}${assigned}${lock}${recur}`;
 }
-function formatTaskDetail(task) {
+function formatTaskDetail(task, maxDescriptionChars) {
   const parts = [
     `ID: ${task.id}`,
     `Title: ${task.title}`,
     `Status: ${task.status}`,
     `Priority: ${task.priority}`
   ];
-  if (task.description)
-    parts.push(`Description: ${task.description}`);
+  if (task.description) {
+    const desc = maxDescriptionChars && task.description.length > maxDescriptionChars ? task.description.slice(0, maxDescriptionChars) + "\u2026" : task.description;
+    parts.push(`Description: ${desc}`);
+  }
   if (task.assigned_to)
     parts.push(`Assigned to: ${task.assigned_to}`);
   if (task.agent_id)
@@ -7107,7 +7223,8 @@ if (shouldRegisterTool("create_task")) {
     metadata: exports_external.record(exports_external.unknown()).optional(),
     estimated_minutes: exports_external.number().optional(),
     requires_approval: exports_external.boolean().optional(),
-    recurrence_rule: exports_external.string().optional()
+    recurrence_rule: exports_external.string().optional(),
+    spawns_template_id: exports_external.string().optional().describe("Template ID to auto-create as next task when this task is completed (pipeline/handoff chains)")
   }, async (params) => {
     try {
       const resolved = { ...params };
@@ -7127,7 +7244,7 @@ if (shouldRegisterTool("create_task")) {
   });
 }
 if (shouldRegisterTool("list_tasks")) {
-  server.tool("list_tasks", "List tasks with optional filters and pagination.", {
+  server.tool("list_tasks", "List tasks with optional filters and pagination. Default limit is 50 \u2014 use offset to page through results.", {
     project_id: exports_external.string().optional(),
     status: exports_external.union([
       exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]),
@@ -7145,11 +7262,15 @@ if (shouldRegisterTool("list_tasks")) {
     due_today: exports_external.boolean().optional(),
     overdue: exports_external.boolean().optional(),
     limit: exports_external.number().optional(),
-    offset: exports_external.number().optional()
+    offset: exports_external.number().optional(),
+    summary_only: exports_external.boolean().optional().describe("When true, return only id, short_id, title, status, priority \u2014 minimal tokens for navigation"),
+    cursor: exports_external.string().optional().describe("Opaque cursor from a prior response for stable pagination. Use next_cursor from the previous page. Mutually exclusive with offset.")
   }, async (params) => {
     try {
-      const { due_today, overdue, ...rest } = params;
+      const { due_today, overdue, summary_only, ...rest } = params;
       const resolved = { ...rest };
+      if (resolved.limit === undefined)
+        resolved.limit = 50;
       if (resolved.project_id)
         resolved.project_id = resolveId(resolved.project_id, "projects");
       if (resolved.plan_id)
@@ -7171,6 +7292,9 @@ if (shouldRegisterTool("list_tasks")) {
         return { content: [{ type: "text", text: total > 0 ? `No tasks in this page (total: ${total}).` : "No tasks found." }] };
       }
       const text = tasks.map((t) => {
+        if (summary_only) {
+          return `${t.short_id || t.id.slice(0, 8)} [${t.status}] ${t.priority} ${t.title}`;
+        }
         const lock = t.locked_by ? ` [locked by ${t.locked_by}]` : "";
         const assigned = t.assigned_to ? ` -> ${t.assigned_to}` : "";
         const due = t.due_at ? ` due:${t.due_at.slice(0, 10)}` : "";
@@ -7178,10 +7302,23 @@ if (shouldRegisterTool("list_tasks")) {
         return `[${t.status}] ${t.id.slice(0, 8)} | ${t.priority} | ${t.title}${assigned}${lock}${due}${recur}`;
       }).join(`
 `);
-      const pagination = resolved.limit ? `
-(showing ${tasks.length} of ${total}, offset: ${resolved.offset || 0})` : "";
+      const currentOffset = resolved.offset || 0;
+      const hasMore = total > (resolved.cursor ? tasks.length : currentOffset + tasks.length);
+      let paginationNote = `
+(showing ${tasks.length} of ${total}`;
+      if (hasMore) {
+        if (resolved.cursor || tasks.length > 0) {
+          const last = tasks[tasks.length - 1];
+          const priorityRank = { critical: 0, high: 1, medium: 2, low: 3 }[last.priority] ?? 3;
+          const cursorPayload = Buffer.from(JSON.stringify({ p: priorityRank, c: last.created_at, i: last.id })).toString("base64");
+          paginationNote += ` \u2014 next_cursor: ${cursorPayload}`;
+        } else {
+          paginationNote += ` \u2014 use offset: ${currentOffset + tasks.length} to get next page`;
+        }
+      }
+      paginationNote += ")";
       return { content: [{ type: "text", text: `${tasks.length} task(s):
-${text}${pagination}` }] };
+${text}${paginationNote}` }] };
     } catch (e) {
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
@@ -7189,14 +7326,15 @@ ${text}${pagination}` }] };
 }
 if (shouldRegisterTool("get_task")) {
   server.tool("get_task", "Get full task details with subtasks, deps, and comments.", {
-    id: exports_external.string()
-  }, async ({ id }) => {
+    id: exports_external.string(),
+    max_description_chars: exports_external.number().optional().describe("Truncate description to this many characters (default: unlimited). Use 300-500 for quick checks.")
+  }, async ({ id, max_description_chars }) => {
     try {
       const resolvedId = resolveId(id);
       const task = getTaskWithRelations(resolvedId);
       if (!task)
         return { content: [{ type: "text", text: `Task not found: ${id}` }], isError: true };
-      const parts = [formatTaskDetail(task)];
+      const parts = [formatTaskDetail(task, max_description_chars)];
       if (task.subtasks.length > 0) {
         parts.push(`
 Subtasks (${task.subtasks.length}):`);
@@ -8424,7 +8562,7 @@ if (shouldRegisterTool("get_next_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)}` }] };
+${formatTaskDetail(task, 300)}` }] };
     } catch (e) {
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
@@ -8510,7 +8648,7 @@ if (shouldRegisterTool("claim_next_task")) {
         return { content: [{ type: "text", text: "No tasks available to claim." }] };
       }
       return { content: [{ type: "text", text: `claimed: ${formatTask(task)}
-${formatTaskDetail(task)}` }] };
+${formatTaskDetail(task, 300)}` }] };
     } catch (e) {
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
@@ -8595,6 +8733,8 @@ No pending tasks available.`);
           }
         }
       }
+      lines.push(`
+as_of: ${new Date().toISOString()} (pass to get_tasks_changed_since for incremental polling)`);
       return { content: [{ type: "text", text: lines.join(`
 `) }] };
     } catch (e) {
@@ -8706,6 +8846,58 @@ if (shouldRegisterTool("get_context")) {
       }
       if (next)
         lines.push(`Next up: ${next.short_id || next.id.slice(0, 8)} [${next.priority}] ${next.title}`);
+      lines.push(`as_of: ${new Date().toISOString()}`);
+      return { content: [{ type: "text", text: lines.join(`
+`) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: formatError(e) }], isError: true };
+    }
+  });
+}
+if (shouldRegisterTool("bootstrap")) {
+  server.tool("bootstrap", "Single call for session start. Returns agent's in-progress task (if resuming), next claimable task, and project health \u2014 no side effects. Replaces 3-4 round trips at cold start.", {
+    agent_id: exports_external.string().optional().describe("Your agent ID \u2014 used to find your active tasks and preferred next task"),
+    project_id: exports_external.string().optional()
+  }, async ({ agent_id, project_id }) => {
+    try {
+      const filters = {};
+      if (project_id)
+        filters.project_id = resolveId(project_id, "projects");
+      const f = Object.keys(filters).length > 0 ? filters : undefined;
+      const status = getStatus(f, agent_id);
+      const next = getNextTask(agent_id, f);
+      const lines = [];
+      const myActive = agent_id ? status.active_work.filter((w) => w.assigned_to === agent_id || w.locked_by === agent_id) : [];
+      if (myActive.length > 0) {
+        lines.push(`## Resuming`);
+        for (const w of myActive) {
+          lines.push(`[${w.short_id || w.id.slice(0, 8)}] ${w.priority} \u2014 ${w.title}`);
+        }
+        lines.push("");
+      }
+      if (next) {
+        lines.push(`## Next task to claim`);
+        lines.push(`[${next.short_id || next.id.slice(0, 8)}] ${next.priority} \u2014 ${next.title}`);
+        if (next.description)
+          lines.push(next.description.slice(0, 300) + (next.description.length > 300 ? "\u2026" : ""));
+        lines.push(`  call: claim_next_task(agent_id: "${agent_id || "<your-id>"}")`);
+        lines.push("");
+      } else {
+        lines.push(`## No tasks available to claim`);
+        lines.push("");
+      }
+      lines.push(`## Health`);
+      lines.push(`${status.pending} pending | ${status.in_progress} active | ${status.completed} done`);
+      if (status.stale_count > 0)
+        lines.push(`\u26A0 ${status.stale_count} stale task(s)`);
+      if (status.overdue_recurring > 0)
+        lines.push(`\uD83D\uDD01 ${status.overdue_recurring} overdue recurring`);
+      if (status.active_work.length > 0) {
+        const others = agent_id ? status.active_work.filter((w) => w.assigned_to !== agent_id && w.locked_by !== agent_id) : status.active_work;
+        if (others.length > 0) {
+          lines.push(`Other agents active: ${others.slice(0, 3).map((w) => `${w.short_id || w.id.slice(0, 8)} (${w.assigned_to || "?"})`).join(", ")}`);
+        }
+      }
       return { content: [{ type: "text", text: lines.join(`
 `) }] };
     } catch (e) {
@@ -8776,6 +8968,7 @@ if (shouldRegisterTool("search_tools")) {
       "get_status",
       "get_context",
       "get_health",
+      "bootstrap",
       "decompose_task",
       "set_task_status",
       "set_task_priority",
@@ -8793,9 +8986,9 @@ if (shouldRegisterTool("describe_tools")) {
       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}`,
+      list_tasks: `List tasks with optional filters. Default limit is 50 to avoid context overflow \u2014 always paginate with offset for large lists.
+  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, default 50), offset(number)
+  Example: {status: ['pending', 'in_progress'], limit: 50, offset: 0}`,
       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'}`,
@@ -8945,8 +9138,8 @@ if (shouldRegisterTool("describe_tools")) {
       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)
+      get_tasks_changed_since: `PREFERRED POLLING PATTERN: Get only tasks modified after a timestamp \u2014 much cheaper than re-fetching everything. Save the as_of timestamp from bootstrap/get_status/get_context and pass it here on your next check.
+  Params: since(string, req \u2014 ISO date from prior as_of), 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)
@@ -8954,6 +9147,9 @@ if (shouldRegisterTool("describe_tools")) {
       get_status: `Get a full project health snapshot \u2014 pending/in_progress/completed counts, active work, next recommended task, stale task count, overdue recurring tasks. Saves 4+ round trips at session start.
   Params: agent_id(string, optional \u2014 prefers tasks assigned to this agent for next_task), project_id(string, optional), task_list_id(string, optional)
   Example: {agent_id: 'a1b2c3d4', project_id: 'e5f6g7h8'}`,
+      bootstrap: `CALL THIS FIRST at session start. Returns your in-progress task (if resuming), next claimable task with description, and project health \u2014 all in one call, no side effects. Eliminates 3-4 round trips.
+  Params: agent_id(string, optional but recommended), project_id(string, optional)
+  Example: {agent_id: 'a1b2c3d4'}`,
       decompose_task: `Break a task into subtasks in one call. Subtasks inherit project/plan/list from parent.
   Params: parent_id(string, req), subtasks(array, req \u2014 [{title, description, priority, assigned_to, estimated_minutes, tags}]), depends_on_prev(boolean \u2014 chain subtasks sequentially)
   Example: {parent_id: 'a1b2c3d4', subtasks: [{title: 'Research'}, {title: 'Implement'}, {title: 'Test'}], depends_on_prev: true}`,