@hasna/todos 0.9.5 → 0.9.7

package/README.md

@@ -1,18 +1,23 @@
 # @hasna/todos
 
-Universal task management for AI coding agents. CLI + MCP server + web dashboard + library, all sharing a single SQLite database.
+Universal task management for AI coding agents. CLI + MCP server + library, all sharing a single SQLite database.
 
 ## Features
 
-- **CLI** with interactive TUI (React/Ink) and JSON output
-- **MCP server** for Claude, Codex, Gemini, and any MCP-compatible agent
+- **CLI** with interactive TUI (React/Ink) and JSON output mode
+- **MCP server** (29 tools) for Claude, Codex, Gemini, and any MCP-compatible agent
 - **Library** for programmatic access from Node.js/Bun
+- **Agent registration** with short UUID identity system
+- **Task lists** for organizing tasks into named containers (backlog, sprint-1, bugs)
+- **Task prefixes** with auto-incrementing short IDs per project (e.g., `APP-00001`)
+- **Plans** as execution groups, separate from task list containers
 - **SQLite** with WAL mode, optimistic locking, and automatic migrations
 - Task dependencies with cycle detection
-- Exclusive agent locking with auto-expiry
+- Exclusive agent locking with 30-minute auto-expiry
 - Full-text search across tasks
 - Project auto-detection from git repositories
 - Subtask hierarchies with cascade deletion
+- Bidirectional sync with Claude Code, Codex, Gemini task lists
 
 ## Installation
 
@@ -20,31 +25,126 @@ Universal task management for AI coding agents. CLI + MCP server + web dashboard
 bun add -g @hasna/todos
 ```
 
+Or with npm:
+
+```bash
+npm install -g @hasna/todos
+```
+
 ## Quick Start
 
 ```bash
+# Register your agent (get a short UUID for identity)
+todos init my-agent
+
 # Create a task
 todos add "Fix login bug" --priority high --tags bug,auth
 
-# List tasks
+# List active tasks
 todos list
 
-# Start working on a task
+# Start working on a task (claims + locks it)
 todos start <id>
 
 # Mark complete
 todos done <id>
 
-# Launch interactive TUI
-todos
+# Create a task list
+todos lists --add "sprint-1"
+
+# Add task to a list
+todos add "Build search" --list <list-id>
 
 # Register MCP server with AI agents
 todos mcp --register all
+
+# Launch interactive TUI
+todos
+```
+
+## Agent Registration
+
+Agents register once to get a persistent 8-character UUID. This ID is used to track task ownership, locking, and activity.
+
+```bash
+# Register (idempotent — same name returns same ID)
+todos init claude
+# Agent registered:
+#   ID:   56783129
+#   Name: claude
+
+# Use the ID on future commands
+todos add "Fix bug" --agent 56783129
+
+# List all registered agents
+todos agents
+```
+
+Registration is idempotent: calling `init` with the same name returns the existing agent and updates `last_seen_at`.
+
+## Task Lists
+
+Task lists are named containers for organizing tasks (like folders). They're separate from plans.
+
+```bash
+# Create a task list
+todos lists --add "backlog"
+todos lists --add "sprint-1" --slug sprint-1 -d "Current sprint"
+
+# List all task lists
+todos lists
+
+# Add tasks to a list
+todos add "Build feature" --list <list-id>
+
+# Filter tasks by list
+todos list --list <list-id>
+
+# Move a task to a different list
+todos update <task-id> --list <list-id>
+
+# Delete a list (tasks keep their data, just lose the list association)
+todos lists --delete <list-id>
+```
+
+Task lists can be project-scoped or standalone. Slugs must be unique within a project.
+
+## Task Prefixes & Short IDs
+
+Every project gets an auto-generated prefix (e.g., "APP" from "My App"). When tasks are created under a project, they get a short ID prepended to the title:
+
+```bash
+# Project "My App" has prefix "MYA"
+todos add "Fix login bug"
+# Creates: "MYA-00001: Fix login bug"
+
+todos add "Add dark mode"
+# Creates: "MYA-00002: Add dark mode"
+```
+
+Custom prefixes can be set when creating a project. Counters auto-increment per project.
+
+## Plans
+
+Plans are execution groups for organizing work. A task can belong to both a task list AND a plan.
+
+```bash
+# Create a plan
+todos plans --add "v2.0 Release"
+
+# Show plan details
+todos plans --show <plan-id>
+
+# Complete a plan
+todos plans --complete <plan-id>
+
+# Assign tasks to a plan
+todos add "Build API" --plan <plan-id>
 ```
 
 ## MCP Server
 
-Register with your AI coding agents:
+Register the MCP server with AI coding agents:
 
 ```bash
 todos mcp --register claude    # Claude Code
@@ -59,23 +159,60 @@ Or start manually via stdio:
 todos-mcp
 ```
 
-## Sync (Optional)
+### MCP Tools (29)
+
+| Category | Tools |
+|----------|-------|
+| **Tasks** | `create_task`, `list_tasks`, `get_task`, `update_task`, `delete_task`, `start_task`, `complete_task` |
+| **Locking** | `lock_task`, `unlock_task` |
+| **Dependencies** | `add_dependency`, `remove_dependency` |
+| **Comments** | `add_comment` |
+| **Projects** | `create_project`, `list_projects` |
+| **Plans** | `create_plan`, `list_plans`, `get_plan`, `update_plan`, `delete_plan` |
+| **Agents** | `register_agent`, `list_agents`, `get_agent` |
+| **Task Lists** | `create_task_list`, `list_task_lists`, `get_task_list`, `update_task_list`, `delete_task_list` |
+| **Search** | `search_tasks` |
+| **Sync** | `sync` |
+
+### MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `todos://tasks` | All active tasks (pending + in_progress) |
+| `todos://projects` | All registered projects |
+| `todos://agents` | All registered agents |
+| `todos://task-lists` | All task lists |
+
+## Sync
 
-Claude supports a native task list. Other agents use JSON task lists under `~/.todos/agents/<agent>/<task_list_id>/`.
+Bidirectional sync with agent-specific task lists.
 
 ```bash
 todos sync --agent claude --task-list <id>
 todos sync --agent codex --task-list default
 todos sync --all --task-list <id>
-todos sync --prefer local
+todos sync --prefer local          # Resolve conflicts favoring local
+todos sync --push                  # One-way: local → agent
+todos sync --pull                  # One-way: agent → local
 ```
 
-Env overrides:
-- `TODOS_SYNC_AGENTS` (comma-separated list for `--all`)
-- `TODOS_TASK_LIST_ID` or `TODOS_<AGENT>_TASK_LIST`
-- `TODOS_AGENT_TASKS_DIR` or `TODOS_<AGENT>_TASKS_DIR`
+Claude uses native Claude Code task lists. Other agents use JSON files under `~/.todos/agents/<agent>/<task_list_id>/`.
 
-Config file: `~/.todos/config.json`
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TODOS_DB_PATH` | Database file path (`:memory:` for testing) |
+| `TODOS_DB_SCOPE` | Set to `project` to force project-level DB |
+| `TODOS_AUTO_PROJECT` | Set to `false` to disable auto-project detection |
+| `TODOS_SYNC_AGENTS` | Comma-separated agent list for `--all` |
+| `TODOS_TASK_LIST_ID` | Default task list ID for sync |
+| `TODOS_<AGENT>_TASK_LIST` | Agent-specific task list ID |
+| `TODOS_AGENT_TASKS_DIR` | Base directory for agent task files |
+
+### Config File
+
+`~/.todos/config.json`:
 
 ```json
 {
@@ -84,51 +221,119 @@ Config file: `~/.todos/config.json`
   "agent_tasks_dir": "/Users/you/.todos/agents",
   "agents": {
     "claude": { "task_list_id": "session-or-project-id" },
-    "codex": { "task_list_id": "default", "tasks_dir": "/Users/you/.todos/agents" }
+    "codex": { "task_list_id": "default" }
   }
 }
 ```
 
 ## CLI Commands
 
+### Task Operations
+
+| Command | Description |
+|---------|-------------|
+| `todos add <title>` | Create a task (`-p` priority, `--tags`, `--list`, `--plan`, `--assign`, `--parent`) |
+| `todos list` | List tasks (`-s` status, `-p` priority, `--list`, `--tags`, `-a` all) |
+| `todos show <id>` | Show full task details with relations |
+| `todos update <id>` | Update fields (`--title`, `-s`, `-p`, `--tags`, `--list`, `--assign`) |
+| `todos start <id>` | Claim task, lock it, set to in_progress |
+| `todos done <id>` | Mark task completed, release lock |
+| `todos delete <id>` | Delete permanently |
+| `todos lock <id>` | Acquire exclusive lock |
+| `todos unlock <id>` | Release lock |
+
+### Organization
+
+| Command | Description |
+|---------|-------------|
+| `todos lists` | List task lists (`--add`, `--delete`, `--slug`, `-d`) |
+| `todos plans` | List plans (`--add`, `--show`, `--delete`, `--complete`) |
+| `todos projects` | List projects (`--add`, `--name`, `--task-list-id`) |
+| `todos deps <id>` | Manage dependencies (`--needs`, `--remove`) |
+| `todos comment <id> <text>` | Add a comment to a task |
+| `todos search <query>` | Full-text search across tasks |
+
+### Agent & System
+
 | Command | Description |
 |---------|-------------|
-| `todos add <title>` | Create a task |
-| `todos list` | List tasks (active by default) |
-| `todos show <id>` | Show full task details |
-| `todos update <id>` | Update task fields |
-| `todos start <id>` | Claim and start a task |
-| `todos done <id>` | Mark task completed |
-| `todos delete <id>` | Delete a task |
-| `todos plan <title>` | Create a plan with subtasks |
-| `todos comment <id> <text>` | Add a comment |
-| `todos search <query>` | Search tasks |
-| `todos deps <id>` | Manage dependencies |
-| `todos projects` | List/manage projects |
-| `todos export` | Export tasks (JSON or Markdown) |
-| `todos mcp` | Start MCP server |
-
-Use `--json` for JSON output on any command. Use `--agent <name>` to identify the calling agent.
+| `todos init <name>` | Register agent, get short UUID (`-d` description) |
+| `todos agents` | List registered agents |
+| `todos sync` | Sync with agent task lists |
+| `todos mcp` | MCP server (`--register`, `--unregister`) |
+| `todos hooks install` | Install Claude Code auto-sync hooks |
+| `todos export` | Export tasks (`-f json\|md`) |
+| `todos upgrade` | Self-update to latest version |
+
+### Global Options
+
+All commands support: `--project <path>`, `--json`, `--agent <name>`, `--session <id>`.
+
+Partial IDs work everywhere — use the first 8+ characters of any UUID.
 
 ## Library Usage
 
 ```typescript
-import { createTask, listTasks, completeTask } from "@hasna/todos";
-
-const task = createTask({ title: "My task", priority: "high" });
-const tasks = listTasks({ status: "pending" });
+import {
+  createTask,
+  listTasks,
+  completeTask,
+  registerAgent,
+  createTaskList,
+  createProject,
+  searchTasks,
+} from "@hasna/todos";
+
+// Register an agent
+const agent = registerAgent({ name: "my-bot" });
+
+// Create a project
+const project = createProject({ name: "My App", path: "/app" });
+
+// Create a task list
+const backlog = createTaskList({ name: "Backlog", project_id: project.id });
+
+// Create a task (gets short_id like "MYA-00001" auto-prepended)
+const task = createTask({
+  title: "Fix login bug",
+  priority: "high",
+  project_id: project.id,
+  task_list_id: backlog.id,
+  agent_id: agent.id,
+  tags: ["bug", "auth"],
+});
+
+// List and filter
+const pending = listTasks({ status: "pending", task_list_id: backlog.id });
+
+// Search
+const results = searchTasks("login", project.id);
+
+// Complete
 completeTask(task.id);
 ```
 
 ## Database
 
-SQLite database with automatic location detection:
+SQLite with automatic location detection:
 
 1. `TODOS_DB_PATH` environment variable (`:memory:` for testing)
 2. Nearest `.todos/todos.db` in current directory or any parent
 3. `~/.todos/todos.db` global fallback
 
-Set `TODOS_DB_SCOPE=project` to force project-level DB at the git root (if found).
+**Schema** (6 migrations, auto-applied):
+
+| Table | Purpose |
+|-------|---------|
+| `projects` | Project registry with task prefix and counter |
+| `tasks` | Main task table with short_id, versioning, locking |
+| `task_lists` | Named containers for tasks |
+| `agents` | Registered agent identities |
+| `plans` | Execution groups |
+| `task_dependencies` | DAG edges between tasks |
+| `task_comments` | Notes on tasks |
+| `task_tags` | Tag index for filtering |
+| `sessions` | Agent session tracking |
 
 ## Development
 
@@ -136,9 +341,10 @@ Set `TODOS_DB_SCOPE=project` to force project-level DB at the git root (if found
 git clone https://github.com/hasna/todos.git
 cd todos
 bun install
-bun test                    # Run 112 tests
+bun test                    # Run 172 tests
 bun run typecheck           # TypeScript checking
 bun run dev:cli             # Run CLI in dev mode
+bun run dev:mcp             # Run MCP server in dev mode
 ```
 
 ## Architecture
@@ -146,10 +352,10 @@ bun run dev:cli             # Run CLI in dev mode
 ```
 src/
   types/     TypeScript types, enums, custom errors
-  db/        SQLite data layer (tasks, projects, comments, sessions)
-  lib/       Business logic (search, sync)
+  db/        SQLite data layer (tasks, projects, agents, task-lists, plans, comments, sessions)
+  lib/       Business logic (search, sync, config)
   cli/       Commander.js CLI + React/Ink TUI
-  mcp/       MCP server (stdio transport)
+  mcp/       MCP server (stdio transport, 29 tools)
   index.ts   Library re-exports
 ```
 

package/dist/cli/index.js

@@ -2379,7 +2379,7 @@ var init_database = __esm(() => {
 });
 
 // src/types/index.ts
-var VersionConflictError, TaskNotFoundError, ProjectNotFoundError, PlanNotFoundError, LockError, TaskListNotFoundError, DependencyCycleError;
+var VersionConflictError, TaskNotFoundError, ProjectNotFoundError, PlanNotFoundError, LockError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError;
 var init_types = __esm(() => {
   VersionConflictError = class VersionConflictError extends Error {
     taskId;
@@ -2445,6 +2445,16 @@ var init_types = __esm(() => {
       this.name = "DependencyCycleError";
     }
   };
+  CompletionGuardError = class CompletionGuardError extends Error {
+    reason;
+    retryAfterSeconds;
+    constructor(reason, retryAfterSeconds) {
+      super(reason);
+      this.reason = reason;
+      this.retryAfterSeconds = retryAfterSeconds;
+      this.name = "CompletionGuardError";
+    }
+  };
 });
 
 // src/db/projects.ts
@@ -2546,6 +2556,173 @@ var init_projects = __esm(() => {
   init_database();
 });
 
+// src/lib/sync-utils.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+function ensureDir2(dir) {
+  if (!existsSync2(dir))
+    mkdirSync2(dir, { recursive: true });
+}
+function listJsonFiles(dir) {
+  if (!existsSync2(dir))
+    return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json"));
+}
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + `
+`);
+}
+function readHighWaterMark(dir) {
+  const path = join2(dir, ".highwatermark");
+  if (!existsSync2(path))
+    return 1;
+  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
+  return isNaN(val) ? 1 : val;
+}
+function writeHighWaterMark(dir, value) {
+  writeFileSync(join2(dir, ".highwatermark"), String(value));
+}
+function getFileMtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+function parseTimestamp(value) {
+  if (typeof value !== "string")
+    return null;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function appendSyncConflict(metadata, conflict, limit = 5) {
+  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
+  const next = [conflict, ...current].slice(0, limit);
+  return { ...metadata, sync_conflicts: next };
+}
+var HOME;
+var init_sync_utils = __esm(() => {
+  HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+});
+
+// src/lib/config.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+function normalizeAgent(agent) {
+  return agent.trim().toLowerCase();
+}
+function loadConfig() {
+  if (cached)
+    return cached;
+  if (!existsSync3(CONFIG_PATH)) {
+    cached = {};
+    return cached;
+  }
+  const config = readJsonFile(CONFIG_PATH) || {};
+  if (typeof config.sync_agents === "string") {
+    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
+  }
+  cached = config;
+  return cached;
+}
+function getSyncAgentsFromConfig() {
+  const config = loadConfig();
+  const agents = config.sync_agents;
+  if (Array.isArray(agents) && agents.length > 0)
+    return agents.map(normalizeAgent);
+  return null;
+}
+function getAgentTaskListId(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.task_list_id || config.task_list_id || null;
+}
+function getAgentTasksDir(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
+}
+function getTaskPrefixConfig() {
+  const config = loadConfig();
+  return config.task_prefix || null;
+}
+function getCompletionGuardConfig(projectPath) {
+  const config = loadConfig();
+  const global = { ...GUARD_DEFAULTS, ...config.completion_guard };
+  if (projectPath && config.project_overrides?.[projectPath]?.completion_guard) {
+    return { ...global, ...config.project_overrides[projectPath].completion_guard };
+  }
+  return global;
+}
+var CONFIG_PATH, cached = null, GUARD_DEFAULTS;
+var init_config = __esm(() => {
+  init_sync_utils();
+  CONFIG_PATH = join3(HOME, ".todos", "config.json");
+  GUARD_DEFAULTS = {
+    enabled: false,
+    min_work_seconds: 30,
+    max_completions_per_window: 5,
+    window_minutes: 10,
+    cooldown_seconds: 60
+  };
+});
+
+// src/lib/completion-guard.ts
+function checkCompletionGuard(task, agentId, db, configOverride) {
+  let config;
+  if (configOverride) {
+    config = configOverride;
+  } else {
+    const projectPath = task.project_id ? getProject(task.project_id, db)?.path : null;
+    config = getCompletionGuardConfig(projectPath);
+  }
+  if (!config.enabled)
+    return;
+  if (task.status !== "in_progress") {
+    throw new CompletionGuardError(`Task must be in 'in_progress' status before completing (current: '${task.status}'). Use start_task first.`);
+  }
+  const agent = agentId || task.assigned_to || task.agent_id;
+  if (config.min_work_seconds && task.locked_at) {
+    const startedAt = new Date(task.locked_at).getTime();
+    const elapsedSeconds = (Date.now() - startedAt) / 1000;
+    if (elapsedSeconds < config.min_work_seconds) {
+      const remaining = Math.ceil(config.min_work_seconds - elapsedSeconds);
+      throw new CompletionGuardError(`Too fast: task was started ${Math.floor(elapsedSeconds)}s ago. Minimum work duration is ${config.min_work_seconds}s. Wait ${remaining}s.`, remaining);
+    }
+  }
+  if (agent && config.max_completions_per_window && config.window_minutes) {
+    const windowStart = new Date(Date.now() - config.window_minutes * 60 * 1000).toISOString();
+    const result = db.query(`SELECT COUNT(*) as count FROM tasks
+         WHERE completed_at > ? AND (assigned_to = ? OR agent_id = ?)`).get(windowStart, agent, agent);
+    if (result.count >= config.max_completions_per_window) {
+      throw new CompletionGuardError(`Rate limit: ${result.count} tasks completed in the last ${config.window_minutes} minutes (max ${config.max_completions_per_window}). Slow down.`);
+    }
+  }
+  if (agent && config.cooldown_seconds) {
+    const result = db.query(`SELECT MAX(completed_at) as last_completed FROM tasks
+         WHERE completed_at IS NOT NULL AND (assigned_to = ? OR agent_id = ?) AND id != ?`).get(agent, agent, task.id);
+    if (result.last_completed) {
+      const elapsedSeconds = (Date.now() - new Date(result.last_completed).getTime()) / 1000;
+      if (elapsedSeconds < config.cooldown_seconds) {
+        const remaining = Math.ceil(config.cooldown_seconds - elapsedSeconds);
+        throw new CompletionGuardError(`Cooldown: last completion was ${Math.floor(elapsedSeconds)}s ago. Wait ${remaining}s between completions.`, remaining);
+      }
+    }
+  }
+}
+var init_completion_guard = __esm(() => {
+  init_types();
+  init_config();
+  init_projects();
+});
+
 // src/db/tasks.ts
 function rowToTask(row) {
   return {
@@ -2723,6 +2900,9 @@ function updateTask(id, input, db) {
     params.push(input.description);
   }
   if (input.status !== undefined) {
+    if (input.status === "completed") {
+      checkCompletionGuard(task, task.assigned_to || task.agent_id || null, d);
+    }
     sets.push("status = ?");
     params.push(input.status);
     if (input.status === "completed") {
@@ -2794,6 +2974,7 @@ function completeTask(id, agentId, db) {
   if (agentId && task.locked_by && task.locked_by !== agentId && !isLockExpired(task.locked_at)) {
     throw new LockError(id, task.locked_by);
   }
+  checkCompletionGuard(task, agentId || null, d);
   const timestamp = now();
   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]);
@@ -2876,6 +3057,7 @@ var init_tasks = __esm(() => {
   init_types();
   init_database();
   init_projects();
+  init_completion_guard();
 });
 
 // src/db/agents.ts
@@ -3111,109 +3293,6 @@ var init_search = __esm(() => {
   init_database();
 });
 
-// src/lib/sync-utils.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
-function ensureDir2(dir) {
-  if (!existsSync2(dir))
-    mkdirSync2(dir, { recursive: true });
-}
-function listJsonFiles(dir) {
-  if (!existsSync2(dir))
-    return [];
-  return readdirSync(dir).filter((f) => f.endsWith(".json"));
-}
-function readJsonFile(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-function writeJsonFile(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2) + `
-`);
-}
-function readHighWaterMark(dir) {
-  const path = join2(dir, ".highwatermark");
-  if (!existsSync2(path))
-    return 1;
-  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
-  return isNaN(val) ? 1 : val;
-}
-function writeHighWaterMark(dir, value) {
-  writeFileSync(join2(dir, ".highwatermark"), String(value));
-}
-function getFileMtimeMs(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-function parseTimestamp(value) {
-  if (typeof value !== "string")
-    return null;
-  const parsed = Date.parse(value);
-  return Number.isNaN(parsed) ? null : parsed;
-}
-function appendSyncConflict(metadata, conflict, limit = 5) {
-  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
-  const next = [conflict, ...current].slice(0, limit);
-  return { ...metadata, sync_conflicts: next };
-}
-var HOME;
-var init_sync_utils = __esm(() => {
-  HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-});
-
-// src/lib/config.ts
-import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
-function normalizeAgent(agent) {
-  return agent.trim().toLowerCase();
-}
-function loadConfig() {
-  if (cached)
-    return cached;
-  if (!existsSync3(CONFIG_PATH)) {
-    cached = {};
-    return cached;
-  }
-  const config = readJsonFile(CONFIG_PATH) || {};
-  if (typeof config.sync_agents === "string") {
-    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
-  }
-  cached = config;
-  return cached;
-}
-function getSyncAgentsFromConfig() {
-  const config = loadConfig();
-  const agents = config.sync_agents;
-  if (Array.isArray(agents) && agents.length > 0)
-    return agents.map(normalizeAgent);
-  return null;
-}
-function getAgentTaskListId(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.task_list_id || config.task_list_id || null;
-}
-function getAgentTasksDir(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
-}
-function getTaskPrefixConfig() {
-  const config = loadConfig();
-  return config.task_prefix || null;
-}
-var CONFIG_PATH, cached = null;
-var init_config = __esm(() => {
-  init_sync_utils();
-  CONFIG_PATH = join3(HOME, ".todos", "config.json");
-});
-
 // src/lib/claude-tasks.ts
 import { existsSync as existsSync4, readFileSync as readFileSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join4 } from "path";
@@ -7729,6 +7808,10 @@ function formatError(error) {
     return `Lock error: ${error.message}`;
   if (error instanceof DependencyCycleError)
     return `Dependency cycle: ${error.message}`;
+  if (error instanceof CompletionGuardError) {
+    const retry = error.retryAfterSeconds ? ` (retry after ${error.retryAfterSeconds}s)` : "";
+    return `Completion blocked: ${error.reason}${retry}`;
+  }
   if (error instanceof Error)
     return error.message;
   return String(error);

package/dist/index.js

@@ -417,6 +417,17 @@ class DependencyCycleError extends Error {
   }
 }
 
+class CompletionGuardError extends Error {
+  reason;
+  retryAfterSeconds;
+  constructor(reason, retryAfterSeconds) {
+    super(reason);
+    this.reason = reason;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.name = "CompletionGuardError";
+  }
+}
+
 // src/db/projects.ts
 function slugify(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
@@ -517,6 +528,159 @@ function ensureProject(name, path, db) {
   return createProject({ name, path }, d);
 }
 
+// src/lib/config.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+
+// src/lib/sync-utils.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+var HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+function ensureDir2(dir) {
+  if (!existsSync2(dir))
+    mkdirSync2(dir, { recursive: true });
+}
+function listJsonFiles(dir) {
+  if (!existsSync2(dir))
+    return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json"));
+}
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + `
+`);
+}
+function readHighWaterMark(dir) {
+  const path = join2(dir, ".highwatermark");
+  if (!existsSync2(path))
+    return 1;
+  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
+  return isNaN(val) ? 1 : val;
+}
+function writeHighWaterMark(dir, value) {
+  writeFileSync(join2(dir, ".highwatermark"), String(value));
+}
+function getFileMtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+function parseTimestamp(value) {
+  if (typeof value !== "string")
+    return null;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function appendSyncConflict(metadata, conflict, limit = 5) {
+  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
+  const next = [conflict, ...current].slice(0, limit);
+  return { ...metadata, sync_conflicts: next };
+}
+
+// src/lib/config.ts
+var CONFIG_PATH = join3(HOME, ".todos", "config.json");
+var cached = null;
+function normalizeAgent(agent) {
+  return agent.trim().toLowerCase();
+}
+function loadConfig() {
+  if (cached)
+    return cached;
+  if (!existsSync3(CONFIG_PATH)) {
+    cached = {};
+    return cached;
+  }
+  const config = readJsonFile(CONFIG_PATH) || {};
+  if (typeof config.sync_agents === "string") {
+    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
+  }
+  cached = config;
+  return cached;
+}
+function getSyncAgentsFromConfig() {
+  const config = loadConfig();
+  const agents = config.sync_agents;
+  if (Array.isArray(agents) && agents.length > 0)
+    return agents.map(normalizeAgent);
+  return null;
+}
+function getAgentTasksDir(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
+}
+function getTaskPrefixConfig() {
+  const config = loadConfig();
+  return config.task_prefix || null;
+}
+var GUARD_DEFAULTS = {
+  enabled: false,
+  min_work_seconds: 30,
+  max_completions_per_window: 5,
+  window_minutes: 10,
+  cooldown_seconds: 60
+};
+function getCompletionGuardConfig(projectPath) {
+  const config = loadConfig();
+  const global = { ...GUARD_DEFAULTS, ...config.completion_guard };
+  if (projectPath && config.project_overrides?.[projectPath]?.completion_guard) {
+    return { ...global, ...config.project_overrides[projectPath].completion_guard };
+  }
+  return global;
+}
+
+// src/lib/completion-guard.ts
+function checkCompletionGuard(task, agentId, db, configOverride) {
+  let config;
+  if (configOverride) {
+    config = configOverride;
+  } else {
+    const projectPath = task.project_id ? getProject(task.project_id, db)?.path : null;
+    config = getCompletionGuardConfig(projectPath);
+  }
+  if (!config.enabled)
+    return;
+  if (task.status !== "in_progress") {
+    throw new CompletionGuardError(`Task must be in 'in_progress' status before completing (current: '${task.status}'). Use start_task first.`);
+  }
+  const agent = agentId || task.assigned_to || task.agent_id;
+  if (config.min_work_seconds && task.locked_at) {
+    const startedAt = new Date(task.locked_at).getTime();
+    const elapsedSeconds = (Date.now() - startedAt) / 1000;
+    if (elapsedSeconds < config.min_work_seconds) {
+      const remaining = Math.ceil(config.min_work_seconds - elapsedSeconds);
+      throw new CompletionGuardError(`Too fast: task was started ${Math.floor(elapsedSeconds)}s ago. Minimum work duration is ${config.min_work_seconds}s. Wait ${remaining}s.`, remaining);
+    }
+  }
+  if (agent && config.max_completions_per_window && config.window_minutes) {
+    const windowStart = new Date(Date.now() - config.window_minutes * 60 * 1000).toISOString();
+    const result = db.query(`SELECT COUNT(*) as count FROM tasks
+         WHERE completed_at > ? AND (assigned_to = ? OR agent_id = ?)`).get(windowStart, agent, agent);
+    if (result.count >= config.max_completions_per_window) {
+      throw new CompletionGuardError(`Rate limit: ${result.count} tasks completed in the last ${config.window_minutes} minutes (max ${config.max_completions_per_window}). Slow down.`);
+    }
+  }
+  if (agent && config.cooldown_seconds) {
+    const result = db.query(`SELECT MAX(completed_at) as last_completed FROM tasks
+         WHERE completed_at IS NOT NULL AND (assigned_to = ? OR agent_id = ?) AND id != ?`).get(agent, agent, task.id);
+    if (result.last_completed) {
+      const elapsedSeconds = (Date.now() - new Date(result.last_completed).getTime()) / 1000;
+      if (elapsedSeconds < config.cooldown_seconds) {
+        const remaining = Math.ceil(config.cooldown_seconds - elapsedSeconds);
+        throw new CompletionGuardError(`Cooldown: last completion was ${Math.floor(elapsedSeconds)}s ago. Wait ${remaining}s between completions.`, remaining);
+      }
+    }
+  }
+}
+
 // src/db/tasks.ts
 function rowToTask(row) {
   return {
@@ -694,6 +858,9 @@ function updateTask(id, input, db) {
     params.push(input.description);
   }
   if (input.status !== undefined) {
+    if (input.status === "completed") {
+      checkCompletionGuard(task, task.assigned_to || task.agent_id || null, d);
+    }
     sets.push("status = ?");
     params.push(input.status);
     if (input.status === "completed") {
@@ -765,6 +932,7 @@ function completeTask(id, agentId, db) {
   if (agentId && task.locked_by && task.locked_by !== agentId && !isLockExpired(task.locked_at)) {
     throw new LockError(id, task.locked_by);
   }
+  checkCompletionGuard(task, agentId || null, d);
   const timestamp = now();
   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]);
@@ -1140,102 +1308,6 @@ function searchTasks(query, projectId, taskListId, db) {
 // src/lib/claude-tasks.ts
 import { existsSync as existsSync4, readFileSync as readFileSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join4 } from "path";
-
-// src/lib/config.ts
-import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
-
-// src/lib/sync-utils.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
-var HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-function ensureDir2(dir) {
-  if (!existsSync2(dir))
-    mkdirSync2(dir, { recursive: true });
-}
-function listJsonFiles(dir) {
-  if (!existsSync2(dir))
-    return [];
-  return readdirSync(dir).filter((f) => f.endsWith(".json"));
-}
-function readJsonFile(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-function writeJsonFile(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2) + `
-`);
-}
-function readHighWaterMark(dir) {
-  const path = join2(dir, ".highwatermark");
-  if (!existsSync2(path))
-    return 1;
-  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
-  return isNaN(val) ? 1 : val;
-}
-function writeHighWaterMark(dir, value) {
-  writeFileSync(join2(dir, ".highwatermark"), String(value));
-}
-function getFileMtimeMs(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-function parseTimestamp(value) {
-  if (typeof value !== "string")
-    return null;
-  const parsed = Date.parse(value);
-  return Number.isNaN(parsed) ? null : parsed;
-}
-function appendSyncConflict(metadata, conflict, limit = 5) {
-  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
-  const next = [conflict, ...current].slice(0, limit);
-  return { ...metadata, sync_conflicts: next };
-}
-
-// src/lib/config.ts
-var CONFIG_PATH = join3(HOME, ".todos", "config.json");
-var cached = null;
-function normalizeAgent(agent) {
-  return agent.trim().toLowerCase();
-}
-function loadConfig() {
-  if (cached)
-    return cached;
-  if (!existsSync3(CONFIG_PATH)) {
-    cached = {};
-    return cached;
-  }
-  const config = readJsonFile(CONFIG_PATH) || {};
-  if (typeof config.sync_agents === "string") {
-    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
-  }
-  cached = config;
-  return cached;
-}
-function getSyncAgentsFromConfig() {
-  const config = loadConfig();
-  const agents = config.sync_agents;
-  if (Array.isArray(agents) && agents.length > 0)
-    return agents.map(normalizeAgent);
-  return null;
-}
-function getAgentTasksDir(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
-}
-function getTaskPrefixConfig() {
-  const config = loadConfig();
-  return config.task_prefix || null;
-}
-
-// src/lib/claude-tasks.ts
 function getTaskListDir(taskListId) {
   return join4(HOME, ".claude", "tasks", taskListId);
 }
@@ -1789,6 +1861,7 @@ export {
   getProject,
   getPlan,
   getDatabase,
+  getCompletionGuardConfig,
   getComment,
   getAgentByName,
   getAgent,
@@ -1809,6 +1882,7 @@ export {
   createPlan,
   completeTask,
   closeDatabase,
+  checkCompletionGuard,
   addDependency,
   addComment,
   VersionConflictError,
@@ -1821,5 +1895,6 @@ export {
   PLAN_STATUSES,
   LockError,
   DependencyCycleError,
+  CompletionGuardError,
   AgentNotFoundError
 };

package/dist/mcp/index.js

@@ -4049,6 +4049,17 @@ class DependencyCycleError extends Error {
   }
 }
 
+class CompletionGuardError extends Error {
+  reason;
+  retryAfterSeconds;
+  constructor(reason, retryAfterSeconds) {
+    super(reason);
+    this.reason = reason;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.name = "CompletionGuardError";
+  }
+}
+
 // src/db/database.ts
 import { Database } from "bun:sqlite";
 import { existsSync, mkdirSync } from "fs";
@@ -4417,6 +4428,164 @@ function nextTaskShortId(projectId, db) {
   return `${updated.task_prefix}-${padded}`;
 }
 
+// src/lib/config.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+
+// src/lib/sync-utils.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+var HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+function ensureDir2(dir) {
+  if (!existsSync2(dir))
+    mkdirSync2(dir, { recursive: true });
+}
+function listJsonFiles(dir) {
+  if (!existsSync2(dir))
+    return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json"));
+}
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + `
+`);
+}
+function readHighWaterMark(dir) {
+  const path = join2(dir, ".highwatermark");
+  if (!existsSync2(path))
+    return 1;
+  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
+  return isNaN(val) ? 1 : val;
+}
+function writeHighWaterMark(dir, value) {
+  writeFileSync(join2(dir, ".highwatermark"), String(value));
+}
+function getFileMtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+function parseTimestamp(value) {
+  if (typeof value !== "string")
+    return null;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function appendSyncConflict(metadata, conflict, limit = 5) {
+  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
+  const next = [conflict, ...current].slice(0, limit);
+  return { ...metadata, sync_conflicts: next };
+}
+
+// src/lib/config.ts
+var CONFIG_PATH = join3(HOME, ".todos", "config.json");
+var cached = null;
+function normalizeAgent(agent) {
+  return agent.trim().toLowerCase();
+}
+function loadConfig() {
+  if (cached)
+    return cached;
+  if (!existsSync3(CONFIG_PATH)) {
+    cached = {};
+    return cached;
+  }
+  const config = readJsonFile(CONFIG_PATH) || {};
+  if (typeof config.sync_agents === "string") {
+    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
+  }
+  cached = config;
+  return cached;
+}
+function getSyncAgentsFromConfig() {
+  const config = loadConfig();
+  const agents = config.sync_agents;
+  if (Array.isArray(agents) && agents.length > 0)
+    return agents.map(normalizeAgent);
+  return null;
+}
+function getAgentTaskListId(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.task_list_id || config.task_list_id || null;
+}
+function getAgentTasksDir(agent) {
+  const config = loadConfig();
+  const key = normalizeAgent(agent);
+  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
+}
+function getTaskPrefixConfig() {
+  const config = loadConfig();
+  return config.task_prefix || null;
+}
+var GUARD_DEFAULTS = {
+  enabled: false,
+  min_work_seconds: 30,
+  max_completions_per_window: 5,
+  window_minutes: 10,
+  cooldown_seconds: 60
+};
+function getCompletionGuardConfig(projectPath) {
+  const config = loadConfig();
+  const global = { ...GUARD_DEFAULTS, ...config.completion_guard };
+  if (projectPath && config.project_overrides?.[projectPath]?.completion_guard) {
+    return { ...global, ...config.project_overrides[projectPath].completion_guard };
+  }
+  return global;
+}
+
+// src/lib/completion-guard.ts
+function checkCompletionGuard(task, agentId, db, configOverride) {
+  let config;
+  if (configOverride) {
+    config = configOverride;
+  } else {
+    const projectPath = task.project_id ? getProject(task.project_id, db)?.path : null;
+    config = getCompletionGuardConfig(projectPath);
+  }
+  if (!config.enabled)
+    return;
+  if (task.status !== "in_progress") {
+    throw new CompletionGuardError(`Task must be in 'in_progress' status before completing (current: '${task.status}'). Use start_task first.`);
+  }
+  const agent = agentId || task.assigned_to || task.agent_id;
+  if (config.min_work_seconds && task.locked_at) {
+    const startedAt = new Date(task.locked_at).getTime();
+    const elapsedSeconds = (Date.now() - startedAt) / 1000;
+    if (elapsedSeconds < config.min_work_seconds) {
+      const remaining = Math.ceil(config.min_work_seconds - elapsedSeconds);
+      throw new CompletionGuardError(`Too fast: task was started ${Math.floor(elapsedSeconds)}s ago. Minimum work duration is ${config.min_work_seconds}s. Wait ${remaining}s.`, remaining);
+    }
+  }
+  if (agent && config.max_completions_per_window && config.window_minutes) {
+    const windowStart = new Date(Date.now() - config.window_minutes * 60 * 1000).toISOString();
+    const result = db.query(`SELECT COUNT(*) as count FROM tasks
+         WHERE completed_at > ? AND (assigned_to = ? OR agent_id = ?)`).get(windowStart, agent, agent);
+    if (result.count >= config.max_completions_per_window) {
+      throw new CompletionGuardError(`Rate limit: ${result.count} tasks completed in the last ${config.window_minutes} minutes (max ${config.max_completions_per_window}). Slow down.`);
+    }
+  }
+  if (agent && config.cooldown_seconds) {
+    const result = db.query(`SELECT MAX(completed_at) as last_completed FROM tasks
+         WHERE completed_at IS NOT NULL AND (assigned_to = ? OR agent_id = ?) AND id != ?`).get(agent, agent, task.id);
+    if (result.last_completed) {
+      const elapsedSeconds = (Date.now() - new Date(result.last_completed).getTime()) / 1000;
+      if (elapsedSeconds < config.cooldown_seconds) {
+        const remaining = Math.ceil(config.cooldown_seconds - elapsedSeconds);
+        throw new CompletionGuardError(`Cooldown: last completion was ${Math.floor(elapsedSeconds)}s ago. Wait ${remaining}s between completions.`, remaining);
+      }
+    }
+  }
+}
+
 // src/db/tasks.ts
 function rowToTask(row) {
   return {
@@ -4594,6 +4763,9 @@ function updateTask(id, input, db) {
     params.push(input.description);
   }
   if (input.status !== undefined) {
+    if (input.status === "completed") {
+      checkCompletionGuard(task, task.assigned_to || task.agent_id || null, d);
+    }
     sets.push("status = ?");
     params.push(input.status);
     if (input.status === "completed") {
@@ -4665,6 +4837,7 @@ function completeTask(id, agentId, db) {
   if (agentId && task.locked_by && task.locked_by !== agentId && !isLockExpired(task.locked_at)) {
     throw new LockError(id, task.locked_by);
   }
+  checkCompletionGuard(task, agentId || null, d);
   const timestamp = now();
   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]);
@@ -4960,107 +5133,6 @@ function searchTasks(query, projectId, taskListId, db) {
 // src/lib/claude-tasks.ts
 import { existsSync as existsSync4, readFileSync as readFileSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join4 } from "path";
-
-// src/lib/config.ts
-import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
-
-// src/lib/sync-utils.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
-var HOME = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-function ensureDir2(dir) {
-  if (!existsSync2(dir))
-    mkdirSync2(dir, { recursive: true });
-}
-function listJsonFiles(dir) {
-  if (!existsSync2(dir))
-    return [];
-  return readdirSync(dir).filter((f) => f.endsWith(".json"));
-}
-function readJsonFile(path) {
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-function writeJsonFile(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2) + `
-`);
-}
-function readHighWaterMark(dir) {
-  const path = join2(dir, ".highwatermark");
-  if (!existsSync2(path))
-    return 1;
-  const val = parseInt(readFileSync(path, "utf-8").trim(), 10);
-  return isNaN(val) ? 1 : val;
-}
-function writeHighWaterMark(dir, value) {
-  writeFileSync(join2(dir, ".highwatermark"), String(value));
-}
-function getFileMtimeMs(path) {
-  try {
-    return statSync(path).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-function parseTimestamp(value) {
-  if (typeof value !== "string")
-    return null;
-  const parsed = Date.parse(value);
-  return Number.isNaN(parsed) ? null : parsed;
-}
-function appendSyncConflict(metadata, conflict, limit = 5) {
-  const current = Array.isArray(metadata["sync_conflicts"]) ? metadata["sync_conflicts"] : [];
-  const next = [conflict, ...current].slice(0, limit);
-  return { ...metadata, sync_conflicts: next };
-}
-
-// src/lib/config.ts
-var CONFIG_PATH = join3(HOME, ".todos", "config.json");
-var cached = null;
-function normalizeAgent(agent) {
-  return agent.trim().toLowerCase();
-}
-function loadConfig() {
-  if (cached)
-    return cached;
-  if (!existsSync3(CONFIG_PATH)) {
-    cached = {};
-    return cached;
-  }
-  const config = readJsonFile(CONFIG_PATH) || {};
-  if (typeof config.sync_agents === "string") {
-    config.sync_agents = config.sync_agents.split(",").map((a) => a.trim()).filter(Boolean);
-  }
-  cached = config;
-  return cached;
-}
-function getSyncAgentsFromConfig() {
-  const config = loadConfig();
-  const agents = config.sync_agents;
-  if (Array.isArray(agents) && agents.length > 0)
-    return agents.map(normalizeAgent);
-  return null;
-}
-function getAgentTaskListId(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.task_list_id || config.task_list_id || null;
-}
-function getAgentTasksDir(agent) {
-  const config = loadConfig();
-  const key = normalizeAgent(agent);
-  return config.agents?.[key]?.tasks_dir || config.agent_tasks_dir || null;
-}
-function getTaskPrefixConfig() {
-  const config = loadConfig();
-  return config.task_prefix || null;
-}
-
-// src/lib/claude-tasks.ts
 function getTaskListDir(taskListId) {
   return join4(HOME, ".claude", "tasks", taskListId);
 }
@@ -5593,6 +5665,10 @@ function formatError(error) {
     return `Lock error: ${error.message}`;
   if (error instanceof DependencyCycleError)
     return `Dependency cycle: ${error.message}`;
+  if (error instanceof CompletionGuardError) {
+    const retry = error.retryAfterSeconds ? ` (retry after ${error.retryAfterSeconds}s)` : "";
+    return `Completion blocked: ${error.reason}${retry}`;
+  }
   if (error instanceof Error)
     return error.message;
   return String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/todos",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
   "type": "module",
   "main": "dist/index.js",