@hasna/todos 0.15.15 → 0.15.17

package/dist/cli/index.js

@@ -2123,7 +2123,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/todos",
-    version: "0.15.15",
+    version: "0.15.17",
     description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
     type: "module",
     main: "dist/index.js",
@@ -5805,10 +5805,72 @@ async function requireTagsFilterCapability(client) {
     throw new Error(`REMOTE_TAGS_FILTER_UNSUPPORTED: configured Todos authority ${authority} does not advertise the tags ` + "query param on GET /v1/tasks; deploy the current @hasna/todos /v1 server to filter by tag; " + "no unfiltered task read was issued");
   }
 }
-async function requestCloudTaskPage(client, filter) {
+function parseCloudTaskTotal(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    return;
+  const total = raw.total;
+  return typeof total === "number" && Number.isSafeInteger(total) && total >= 0 ? total : undefined;
+}
+async function requestRawCloudTaskPage(client, filter) {
   const res = await requiredRemoteRoute(client, "/v1/tasks", () => client.list("tasks", { query: toListQuery(filter) }));
   const envelope = res.raw;
-  return Array.isArray(envelope?.tasks) ? envelope.tasks : res.items;
+  return {
+    tasks: Array.isArray(envelope?.tasks) ? envelope.tasks : res.items,
+    total: parseCloudTaskTotal(res.raw)
+  };
+}
+function cloudTaskListFilterError(code, taskListId, detail) {
+  return new Error(`${code}: hosted authority returned rows outside requested task_list_id ${taskListId}; ${detail}; refusing an incomplete exact-list result`);
+}
+async function requestCloudTaskPage(client, filter) {
+  const firstPage = await requestRawCloudTaskPage(client, filter);
+  const tasks = firstPage.tasks;
+  if (filter.task_list_id === undefined)
+    return tasks;
+  const taskListId = filter.task_list_id;
+  if (tasks.every((task) => task.task_list_id === taskListId))
+    return tasks;
+  const scanLimit = filter.limit;
+  const startOffset = filter.offset ?? 0;
+  if (startOffset !== 0 || scanLimit === undefined || !Number.isSafeInteger(scanLimit) || scanLimit <= 0 || firstPage.total === undefined) {
+    throw cloudTaskListFilterError("REMOTE_TASK_LIST_FILTER_UNSUPPORTED", taskListId, "the response does not provide complete bounded total/offset pagination evidence");
+  }
+  const total = firstPage.total;
+  if (total > scanLimit) {
+    throw cloudTaskListFilterError("REMOTE_TASK_LIST_FILTER_INCOMPLETE", taskListId, `reported total ${total} exceeds bounded scan limit ${scanLimit}`);
+  }
+  if (tasks.length > total) {
+    throw cloudTaskListFilterError("REMOTE_TASK_LIST_FILTER_UNSUPPORTED", taskListId, `the first page contains ${tasks.length} rows but reports total ${total}`);
+  }
+  const seenTaskIds = new Set;
+  for (const task of tasks) {
+    if (seenTaskIds.has(task.id)) {
+      throw cloudTaskListFilterError("REMOTE_TASK_LIST_FILTER_UNSUPPORTED", taskListId, `the first page repeats task id ${task.id}`);
+    }
+    seenTaskIds.add(task.id);
+  }
+  while (tasks.length < total) {
+    const remaining = total - tasks.length;
+    const page = await requestRawCloudTaskPage(client, {
+      ...filter,
+      offset: tasks.length,
+      limit: Math.min(scanLimit - tasks.length, remaining)
+    });
+    if (page.total !== total) {
+      throw cloudTaskListFilterError("REMOTE_TASK_LIST_FILTER_UNSUPPORTED", taskListId, `pagination total changed from ${total} to ${String(page.total)}`);
+    }
+    if (page.tasks.length === 0 || tasks.length + page.tasks.length > total) {
+      throw cloudTaskListFilterError("REMOTE_TASK_LIST_FILTER_UNSUPPORTED", taskListId, "pagination did not make bounded progress toward the reported total");
+    }
+    for (const task of page.tasks) {
+      if (seenTaskIds.has(task.id)) {
+        throw cloudTaskListFilterError("REMOTE_TASK_LIST_FILTER_UNSUPPORTED", taskListId, `pagination repeats task id ${task.id}`);
+      }
+      seenTaskIds.add(task.id);
+    }
+    tasks.push(...page.tasks);
+  }
+  return tasks.filter((task) => task.task_list_id === taskListId);
 }
 async function cloudListTasks(client, filter = {}) {
   if (filter.tags?.length)
@@ -5873,12 +5935,10 @@ async function cloudGetTask(client, id) {
 }
 async function cloudCreateTask(client, input) {
   const expectedParentId = typeof input["parent_id"] === "string" ? input["parent_id"] : null;
-  const created = unwrapTask(await requiredRemoteRoute(client, "/v1/tasks", () => expectedParentId === null ? client.create("tasks", input) : client.create("tasks", input, { retry: false }), ["PARENT_TASK_NOT_FOUND"]));
+  const created = unwrapTask(await requiredRemoteRoute(client, "/v1/tasks", () => client.create("tasks", input, { retry: false }), ["PARENT_TASK_NOT_FOUND"]));
   if (!created || typeof created.id !== "string" || !created.id.trim()) {
     throw new Error(`REMOTE_API_INCOMPATIBLE: configured Todos authority ${remoteAuthorityBase(client)} returned a task create ` + "response without a stored task id; no success row or local SQLite fallback is permitted");
   }
-  if (expectedParentId === null)
-    return created;
   const persisted = await cloudGetTask(client, created.id);
   if (!persisted || persisted.id !== created.id || (persisted.parent_id ?? null) !== expectedParentId) {
     throw new Error(`TASK_CREATE_PERSISTENCE_UNVERIFIED: configured Todos authority ${remoteAuthorityBase(client)} accepted ` + `POST /v1/tasks but authoritative GET /v1/tasks/${encodeURIComponent(created.id)} did not return the same ` + "stored task id and parent_id; no success row or local SQLite fallback is permitted");
@@ -5944,6 +6004,23 @@ async function cloudTaskAction(client, id, action, body = {}) {
   const raw = await client.transport.post(`/tasks/${encodeURIComponent(id)}/${action}`, body);
   return unwrapTask(raw);
 }
+async function cloudFailTask(client, id, body = {}) {
+  const route = `/v1/tasks/${encodeURIComponent(id)}/fail`;
+  const raw = await requiredRemoteRoute(client, route, () => client.transport.post(`/tasks/${encodeURIComponent(id)}/fail`, body));
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an invalid failure response envelope`);
+  }
+  const result = raw["result"];
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} did not return result.task`);
+  }
+  const task = result["task"];
+  const retryTask = result["retryTask"];
+  if (!task || typeof task !== "object" || Array.isArray(task) || retryTask !== undefined && (!retryTask || typeof retryTask !== "object" || Array.isArray(retryTask))) {
+    throw new Error(`REMOTE_API_INCOMPATIBLE: ${route} returned an invalid failure result`);
+  }
+  return result;
+}
 function resolveOpenApiSchema(document, schema) {
   if (!schema || typeof schema !== "object" || Array.isArray(schema))
     return null;
@@ -7469,6 +7546,7 @@ var init_stage_a = __esm(() => {
     "delegate",
     "delete",
     "deps",
+    "fail",
     "doctor",
     "done",
     "find-commit",
@@ -16520,8 +16598,8 @@ function failTask(id, agentId, reason, options, db) {
   const safeMeta = sanitizePreWriteValue(meta, "task.failure.metadata");
   const timestamp2 = now();
   const failTx = d.transaction(() => {
-    const res = d.run(`UPDATE tasks SET status = 'failed', locked_by = NULL, locked_at = NULL, metadata = ?, version = version + 1, updated_at = ?
-       WHERE id = ? AND version = ?`, [JSON.stringify(safeMeta), timestamp2, id, task.version]);
+    const res = d.run(`UPDATE tasks SET status = 'failed', reason = ?, locked_by = NULL, locked_at = NULL, metadata = ?, version = version + 1, updated_at = ?
+       WHERE id = ? AND version = ?`, [safeReason, JSON.stringify(safeMeta), timestamp2, id, task.version]);
     if (res.changes === 0) {
       const current = getTask(id, d);
       throw new VersionConflictError(id, task.version, current?.version ?? -1);
@@ -16533,6 +16611,7 @@ function failTask(id, agentId, reason, options, db) {
     status: "failed",
     locked_by: null,
     locked_at: null,
+    reason: safeReason,
     metadata: safeMeta,
     version: task.version + 1,
     updated_at: timestamp2
@@ -21519,6 +21598,10 @@ function formatHumanComment(comment) {
   const agent = comment.agent_id ? chalk3.cyan(`[${escapeTerminalControls(comment.agent_id)}] `) : "";
   return `    ${agent}${chalk3.dim(escapeTerminalControls(comment.created_at))}: ${escapeTerminalControls(comment.content)}`;
 }
+function printTaskCreatedReceipt(task) {
+  console.log(chalk3.green(`Task created: ${escapeTerminalControls(task.id)}`));
+  console.log(formatTaskLine(task));
+}
 async function cloudDetailRelations(cloud, id) {
   try {
     return await cloudGetTaskRelations(cloud, id);
@@ -21834,8 +21917,7 @@ function registerTaskCommands(program2) {
       if (globalOpts.json) {
         output(task3, true);
       } else {
-        console.log(chalk3.green("Task created:"));
-        console.log(formatTaskLine(task3));
+        printTaskCreatedReceipt(task3);
       }
       return;
     }
@@ -21882,8 +21964,7 @@ function registerTaskCommands(program2) {
     if (globalOpts.json) {
       output(task2, true);
     } else {
-      console.log(chalk3.green("Task created:"));
-      console.log(formatTaskLine(task2));
+      printTaskCreatedReceipt(task2);
     }
   });
   const task = program2.command("task").description("Task subcommands for deterministic automation");
@@ -43364,6 +43445,22 @@ class PostgresTodosTaskManifestBackend {
   async markOutboxDelivered(outboxId, deliveredAt) {
     await this.ensureSchema();
     await this.client.transaction(async (tx) => {
+      const owned = await tx.query(`SELECT r.operation_id
+         FROM todos_task_manifest_outbox o
+         JOIN todos_task_manifest_receipts r
+           ON r.receipt_id = o.apply_receipt_id
+         WHERE r.tenant_id = $1
+           AND r.authority = 'todos'
+           AND r.route = 'todos.task-manifest.v1'
+           AND r.schema_version = 1
+           AND r.kind = 'apply'
+           AND o.id = $2
+         LIMIT 1`, [this.tenantId, outboxId]);
+      const operationId = owned.rows[0]?.operation_id;
+      if (operationId == null) {
+        throw new TodosTaskManifestError("TODOS_TASK_MANIFEST_GRAPH_CONFLICT", `Pending outbox row not found: ${outboxId}`);
+      }
+      await tx.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`${this.service}\x1F${String(operationId)}`]);
       const result = await tx.query(`UPDATE todos_task_manifest_outbox
         SET status = 'delivered', delivered_at = $1, attempts = attempts + 1
         WHERE id = $2 AND status = 'pending'
@@ -43371,10 +43468,28 @@ class PostgresTodosTaskManifestBackend {
             SELECT 1 FROM todos_task_manifest_receipts r
             WHERE r.receipt_id = todos_task_manifest_outbox.apply_receipt_id
               AND r.tenant_id = $3
+              AND r.authority = 'todos'
+              AND r.route = 'todos.task-manifest.v1'
+              AND r.schema_version = 1
+              AND r.kind = 'apply'
           )
         RETURNING id`, [deliveredAt, outboxId, this.tenantId]);
-      if (!result.rows[0])
-        throw new TodosTaskManifestError("TODOS_TASK_MANIFEST_GRAPH_CONFLICT", `Pending outbox row not found: ${outboxId}`);
+      if (result.rows[0])
+        return;
+      const existing = await tx.query(`SELECT o.status
+         FROM todos_task_manifest_outbox o
+         JOIN todos_task_manifest_receipts r
+           ON r.receipt_id = o.apply_receipt_id
+         WHERE r.tenant_id = $1
+           AND r.authority = 'todos'
+           AND r.route = 'todos.task-manifest.v1'
+           AND r.schema_version = 1
+           AND r.kind = 'apply'
+           AND o.id = $2
+         LIMIT 1`, [this.tenantId, outboxId]);
+      if (existing.rows[0]?.status === "delivered")
+        return;
+      throw new TodosTaskManifestError("TODOS_TASK_MANIFEST_GRAPH_CONFLICT", `Pending outbox row not found: ${outboxId}`);
     });
   }
   async compensate(input, receipt, compensationReceiptId, requestDigest, now4) {
@@ -43406,7 +43521,13 @@ class PostgresTodosTaskManifestBackend {
         throw new TodosTaskManifestError("TODOS_TASK_MANIFEST_COMPENSATION_REFUSED", "Graph is not applied");
       const delivered = await tx.query(`SELECT o.id FROM todos_task_manifest_outbox o
          JOIN todos_task_manifest_receipts r ON r.receipt_id = o.apply_receipt_id
-         WHERE r.tenant_id = $1 AND o.apply_receipt_id = $2 AND o.status = 'delivered'
+         WHERE r.tenant_id = $1
+           AND r.authority = 'todos'
+           AND r.route = 'todos.task-manifest.v1'
+           AND r.schema_version = 1
+           AND r.kind = 'apply'
+           AND o.apply_receipt_id = $2
+           AND o.status = 'delivered'
          LIMIT 1`, [this.tenantId, input.receipt_id]);
       if (delivered.rows[0])
         throw new TodosTaskManifestError("TODOS_TASK_MANIFEST_COMPENSATION_REFUSED", "Compensation refused: delivered outbox row exists");
@@ -43419,15 +43540,20 @@ class PostgresTodosTaskManifestBackend {
         },
         ...(manifest.effects ?? []).map((effect2) => ({ topic: effect2.topic, payload: effect2.payload }))
       ];
-      const outboxRows = await tx.query(`SELECT id, topic, payload, payload_digest, status, attempts, delivered_at
-        FROM todos_task_manifest_outbox
-        WHERE apply_receipt_id = $1
+      const outboxRows = await tx.query(`SELECT o.id, o.topic, o.payload, o.payload_digest, o.status, o.attempts, o.delivered_at
+        FROM todos_task_manifest_outbox o
+        WHERE o.apply_receipt_id = $1
           AND EXISTS (
             SELECT 1 FROM todos_task_manifest_receipts r
-            WHERE r.receipt_id = todos_task_manifest_outbox.apply_receipt_id
+            WHERE r.receipt_id = o.apply_receipt_id
               AND r.tenant_id = $2
+              AND r.authority = 'todos'
+              AND r.route = 'todos.task-manifest.v1'
+              AND r.schema_version = 1
+              AND r.kind = 'apply'
           )
-        ORDER BY id`, [input.receipt_id, this.tenantId]);
+        ORDER BY o.id
+        FOR UPDATE OF o`, [input.receipt_id, this.tenantId]);
       if (outboxRows.rows.length !== expectedEffects.length) {
         throw new TodosTaskManifestError("TODOS_TASK_MANIFEST_COMPENSATION_REFUSED", "Compensation refused: outbox changed since apply");
       }
@@ -43527,14 +43653,23 @@ class PostgresTodosTaskManifestBackend {
       }
       if (stored.rows.length !== managedIds.length)
         throw new TodosTaskManifestError("TODOS_TASK_MANIFEST_COMPENSATION_REFUSED", "Compensation refused: managed graph is incomplete");
-      await tx.query(`UPDATE todos_task_manifest_outbox
+      const cancelled = await tx.query(`UPDATE todos_task_manifest_outbox
         SET status = 'cancelled'
         WHERE apply_receipt_id = $1 AND status = 'pending'
           AND EXISTS (
             SELECT 1 FROM todos_task_manifest_receipts r
             WHERE r.receipt_id = todos_task_manifest_outbox.apply_receipt_id
               AND r.tenant_id = $2
-          )`, [input.receipt_id, this.tenantId]);
+              AND r.authority = 'todos'
+              AND r.route = 'todos.task-manifest.v1'
+              AND r.schema_version = 1
+              AND r.kind = 'apply'
+          )
+        RETURNING id`, [input.receipt_id, this.tenantId]);
+      const cancelledIds = new Set(cancelled.rows.map((row) => String(row.id)));
+      if (cancelledIds.size !== applyResult.outbox_ids.length || applyResult.outbox_ids.some((id) => !cancelledIds.has(id))) {
+        throw new TodosTaskManifestError("TODOS_TASK_MANIFEST_COMPENSATION_REFUSED", "Compensation refused: failed to cancel every expected outbox row");
+      }
       const typedIds = [
         ["dependencies", applyResult.graph.dependency_ids],
         ["comments", applyResult.graph.comment_ids],
@@ -43717,6 +43852,7 @@ class PackageOwnedTodosTaskManifestAuthority {
       deterministic_ids: true,
       immutable_receipts: true,
       transactional_outbox: true,
+      idempotent_outbox_delivery: true,
       exact_bounded_readback: true,
       conditional_compensation: true,
       transcript_safe: false,
@@ -46166,8 +46302,8 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
           properties: {
             title: { type: "string" },
             description: { type: "string", nullable: true },
-            status: { type: "string" },
-            priority: { type: "string" },
+            status: { type: "string", enum: [...TASK_STATUSES] },
+            priority: { type: "string", enum: [...TASK_PRIORITIES] },
             project_id: { type: "string" },
             parent_id: { type: "string" },
             plan_id: { type: "string" },
@@ -46181,8 +46317,8 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
           properties: {
             title: { type: "string" },
             description: { type: "string" },
-            status: { type: "string" },
-            priority: { type: "string" },
+            status: { type: "string", enum: [...TASK_STATUSES] },
+            priority: { type: "string", enum: [...TASK_PRIORITIES] },
             assigned_to: { type: "string" },
             project_id: { type: "string", nullable: true },
             plan_id: { type: "string", nullable: true },
@@ -46203,6 +46339,24 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
             confidence: { type: "number", minimum: 0, maximum: 1 }
           }
         },
+        FailTaskInput: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            agent_id: { type: "string", minLength: 1 },
+            reason: { type: "string" },
+            retry: { type: "boolean" }
+          }
+        },
+        TaskFailureResult: {
+          type: "object",
+          additionalProperties: false,
+          required: ["task"],
+          properties: {
+            task: { $ref: "#/components/schemas/Task" },
+            retryTask: { $ref: "#/components/schemas/Task" }
+          }
+        },
         CreateProjectInput: {
           type: "object",
           additionalProperties: false,
@@ -47446,6 +47600,30 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
           responses: { "200": { content: { "application/json": { schema: { type: "object", properties: { task: { $ref: "#/components/schemas/Task" } } } } } } }
         }
       },
+      "/v1/tasks/{id}/fail": {
+        post: {
+          operationId: "failTask",
+          summary: "Fail a task with an optional reason and retry copy",
+          parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+          requestBody: {
+            required: false,
+            content: { "application/json": { schema: { $ref: "#/components/schemas/FailTaskInput" } } }
+          },
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["result"],
+                    properties: { result: { $ref: "#/components/schemas/TaskFailureResult" } }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
       "/v1/projects": {
         get: {
           operationId: "listProjects",
@@ -47887,12 +48065,13 @@ var init_openapi = __esm(() => {
       id: { type: "string" },
       title: { type: "string" },
       description: { type: "string" },
-      status: { type: "string" },
-      priority: { type: "string" },
+      status: { type: "string", enum: [...TASK_STATUSES] },
+      priority: { type: "string", enum: [...TASK_PRIORITIES] },
       project_id: { type: "string", nullable: true },
       parent_id: { type: "string", nullable: true },
       assigned_to: { type: "string", nullable: true },
       agent_id: { type: "string", nullable: true },
+      reason: { type: "string", nullable: true },
       tags: { type: "array", items: { type: "string" } },
       version: { type: "number" },
       created_at: { type: "string" },
@@ -48425,6 +48604,44 @@ function validateTaskCompletion(value) {
     }
   };
 }
+function validateTaskFailure(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return { ok: false, message: "failure body must be an object" };
+  const body2 = value;
+  const allowed = new Set(["agent_id", "reason", "retry"]);
+  const unknown = Object.keys(body2).find((key2) => !allowed.has(key2));
+  if (unknown)
+    return { ok: false, message: `unknown failure field: ${unknown}` };
+  if (body2.agent_id !== undefined && (typeof body2.agent_id !== "string" || !body2.agent_id.trim())) {
+    return { ok: false, message: "agent_id must be a non-empty string" };
+  }
+  if (body2.reason !== undefined && typeof body2.reason !== "string")
+    return { ok: false, message: "reason must be a string" };
+  if (body2.retry !== undefined && typeof body2.retry !== "boolean")
+    return { ok: false, message: "retry must be a boolean" };
+  return {
+    ok: true,
+    ...typeof body2.agent_id === "string" ? { agentId: body2.agent_id } : {},
+    reason: typeof body2.reason === "string" && body2.reason ? body2.reason : "Unknown failure",
+    retry: body2.retry === true
+  };
+}
+function validateTaskPatchVocabulary(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return { ok: false, message: "task patch must be an object" };
+  const body2 = value;
+  for (const [name, vocabulary] of [["status", TASK_STATUSES], ["priority", TASK_PRIORITIES]]) {
+    const raw = body2[name];
+    if (raw === undefined)
+      continue;
+    if (typeof raw !== "string")
+      return { ok: false, message: `${name} must be a string. Allowed values: ${vocabulary.join(", ")}.` };
+    const parsed = resolveEnumVocabulary(raw, { name, vocabulary, allowList: false });
+    if (!parsed.ok)
+      return { ok: false, message: parsed.message };
+  }
+  return { ok: true, patch: body2 };
+}
 function validateProjectPatch(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return { ok: false, message: "project patch must be an object" };
@@ -49105,7 +49322,12 @@ async function handleV1Request(req, url, dependencies = {}) {
           });
         }
         if (action === "fail" && method === "POST") {
-          return json5({ result: await store.tasks.fail(id, agentId, typeof body2.reason === "string" ? body2.reason : "failed", {}) });
+          const parsed = validateTaskFailure(actionJson.value);
+          if (!parsed.ok)
+            return error(400, parsed.message);
+          return json5({
+            result: await store.tasks.fail(id, parsed.agentId || principal.agent || "todos-serve", parsed.reason, { retry: parsed.retry }, contextFromPrincipal(principal, body2))
+          });
         }
         if (action === "claim" && method === "POST") {
           return json5({ task: await store.tasks.claimNext(agentId, {}) });
@@ -49134,9 +49356,13 @@ async function handleV1Request(req, url, dependencies = {}) {
         return task2 ? json5({ task: task2 }) : error(404, "task not found");
       }
       if (method === "PATCH" || method === "PUT") {
-        const body2 = await readJson3(req);
-        if (!body2)
+        const rawBody = await readJson3(req);
+        if (!rawBody)
           return error(400, "invalid JSON body");
+        const validated = validateTaskPatchVocabulary(rawBody);
+        if (!validated.ok)
+          return error(400, validated.message);
+        const body2 = validated.patch;
         const current = await store.tasks.get(id);
         if (!current)
           return error(404, "task not found");
@@ -75035,12 +75261,20 @@ Blocked:`));
   program2.command("fail <id>").description("Mark a task as failed with optional reason and retry").option("--reason <text>", "Why it failed").option("--agent <id>", "Agent reporting the failure").option("--retry", "Auto-create a retry copy").option("-j, --json", "Output as JSON").action(async (id, opts) => {
     const globalOpts = program2.opts();
     const json6 = opts.json || globalOpts.json;
-    const db = getDatabase();
-    const resolvedId = resolvePartialId(db, "tasks", id);
-    if (!resolvedId) {
-      handleError(new Error(`Task not found: ${id}`));
-    }
-    const result = failTask(resolvedId, opts.agent, opts.reason, { retry: opts.retry }, db);
+    const agentId = opts.agent || globalOpts.agent;
+    const cloud = getTodosCloudClient();
+    const result = cloud ? await cloudFailTask(cloud, await resolveTaskIdForCommand(id, cloud), {
+      ...agentId ? { agent_id: agentId } : {},
+      ...opts.reason !== undefined ? { reason: opts.reason } : {},
+      ...opts.retry ? { retry: true } : {}
+    }) : (() => {
+      const db = getDatabase();
+      const resolvedId = resolvePartialId(db, "tasks", id);
+      if (!resolvedId) {
+        handleError(new Error(`Task not found: ${id}`));
+      }
+      return failTask(resolvedId, agentId, opts.reason, { retry: opts.retry }, db);
+    })();
     if (json6) {
       console.log(JSON.stringify(result, null, 2));
       return;
@@ -77512,6 +77746,207 @@ var init_query_commands = __esm(() => {
   init_types();
 });
 
+// src/lib/goal-workflow.ts
+var GOAL_COMMAND_RECIPES;
+var init_goal_workflow = __esm(() => {
+  init_plans();
+  init_tasks();
+  init_tasks();
+  init_comments();
+  init_handoffs();
+  init_database();
+  GOAL_COMMAND_RECIPES = [
+    {
+      host: "codex|claude-code|takumi|mcp",
+      command: "/goal execute <plan-name>",
+      description: "Claim and start the next ready step for a goal plan",
+      equivalent_cli: "todos goal execute <plan-name> --agent <name>"
+    },
+    {
+      host: "codex|claude-code|takumi|mcp",
+      command: '/goal create "<goal text>" --steps step1,step2,step3',
+      description: "Create a plan and decompose into sequential tasks",
+      equivalent_cli: 'todos goal create "<goal>" --step "step1" --step "step2"'
+    },
+    {
+      host: "codex|claude-code|takumi|mcp",
+      command: "/goal status <plan-name>",
+      description: "Show plan progress and current step",
+      equivalent_cli: "todos goal status <plan-name>"
+    },
+    {
+      host: "codex|claude-code|takumi|mcp",
+      command: "/goal handoff <plan-name>",
+      description: "Produce JSON/Markdown handoff packet for session transfer",
+      equivalent_cli: "todos goal handoff <plan-name> --format md"
+    }
+  ];
+});
+
+// src/lib/agent-adapter-docs.ts
+var ADAPTER_DOCS_SCHEMA_VERSION = "todos.agent_adapter_docs.v1", MCP_REGISTRABLE_CLI_AGENTS, SHARED_TASK_CONTRACT, SHARED_VERIFICATION, SHARED_HANDOFF, SHARED_WORKFLOW, AGENT_ADAPTER_DOCS;
+var init_agent_adapter_docs = __esm(() => {
+  init_goal_workflow();
+  MCP_REGISTRABLE_CLI_AGENTS = ["claude", "codex", "gemini", "cursor", "takumi"];
+  SHARED_TASK_CONTRACT = {
+    claim: "todos claim <agent-name>  # atomic: find + lock + start best pending task",
+    progress: 'todos log-progress <task-id> "Investigating..." [--pct 50]',
+    complete: 'todos done <task-id> --commit-hash <hash> --notes "All tests pass"',
+    fail: 'todos fail <task-id> --reason "..." [--retry]',
+    evidence_fields: ["commit_hash", "notes", "attach_ids", "verification_record_id"]
+  };
+  SHARED_VERIFICATION = {
+    run: "todos verify run --provider shell --task <id>",
+    attach: "todos verify attach --task <id> --path ./test-output.log",
+    mcp: "run_verification"
+  };
+  SHARED_HANDOFF = {
+    goal: "todos goal handoff <plan-name> --format md",
+    session: 'todos handoff --create --agent <name> --summary "..."',
+    mcp: "format_goal_handoff"
+  };
+  SHARED_WORKFLOW = [
+    { step: 1, title: "Install @hasna/todos", cli: "bun install -g @hasna/todos", notes: "Use bun, not npm, for @hasna packages" },
+    { step: 2, title: "Register MCP server", cli: "todos mcp --register <host>", mcp: "bootstrap" },
+    { step: 3, title: "Register agent identity", cli: "todos init <agent-name>", mcp: "register_agent" },
+    { step: 4, title: "Claim work", cli: "todos claim <agent-name>", mcp: "claim_next_task" },
+    { step: 5, title: "Log progress", cli: 'todos log-progress <id> "..."', mcp: "add_comment" },
+    { step: 6, title: "Attach verification evidence", cli: "todos verify run --task <id>", mcp: "run_verification" },
+    { step: 7, title: "Complete with evidence", cli: "todos done <id> --commit-hash HEAD", mcp: "complete_task" }
+  ];
+  AGENT_ADAPTER_DOCS = {
+    codex: {
+      schema_version: ADAPTER_DOCS_SCHEMA_VERSION,
+      host: "codex",
+      display_name: "OpenAI Codex CLI",
+      install: {
+        bun: "bun install -g @hasna/todos",
+        verify: "todos --version && which todos-mcp"
+      },
+      mcp: {
+        register_cli: "todos mcp --register codex",
+        unregister_cli: "todos mcp --unregister codex",
+        config_path: "~/.codex/config.toml",
+        recommended_profile: "minimal",
+        env: ["TODOS_PROFILE=minimal", "TODOS_DB_PATH=.todos/todos.db"]
+      },
+      goal_commands: GOAL_COMMAND_RECIPES,
+      workflow: SHARED_WORKFLOW.map((s) => s.step === 2 ? { ...s, cli: "todos mcp --register codex" } : s),
+      task_contract: { ...SHARED_TASK_CONTRACT },
+      verification: { ...SHARED_VERIFICATION },
+      handoff: { ...SHARED_HANDOFF },
+      failure_modes: [
+        {
+          symptom: "MCP tools not visible in Codex",
+          cause: "Missing [mcp_servers.todos] block in ~/.codex/config.toml",
+          recovery: "Run `todos mcp --register codex` and restart Codex"
+        },
+        {
+          symptom: "VersionConflictError on complete_task",
+          cause: "Passed stale version to update_task instead of complete_task",
+          recovery: "Use `complete_task` or CLI `todos done` \u2014 do not pass version manually"
+        },
+        {
+          symptom: "No claimable tasks",
+          cause: "Queue empty, dependencies blocking, or task locked by another agent",
+          recovery: "Run `todos status --explain-blocked` or MCP get_status with explain_blocked"
+        }
+      ],
+      examples: [
+        { title: "Session start", command: "todos claim codex-agent && todos status" },
+        { title: "Goal plan", command: 'todos goal create "Ship feature" --step "Implement" --step "Test"' },
+        { title: "Queue agent run", command: "todos runs queue --adapter codex --task <id>" }
+      ]
+    },
+    "claude-code": {
+      schema_version: ADAPTER_DOCS_SCHEMA_VERSION,
+      host: "claude-code",
+      display_name: "Claude Code",
+      install: {
+        bun: "bun install -g @hasna/todos",
+        verify: "todos --version && claude mcp list | grep todos"
+      },
+      mcp: {
+        register_cli: "todos mcp --register claude",
+        unregister_cli: "todos mcp --unregister claude",
+        config_path: "Managed via `claude mcp` (project or user scope)",
+        recommended_profile: "minimal",
+        env: ["TODOS_PROFILE=minimal", "TODOS_AUTO_PROJECT=true"]
+      },
+      goal_commands: GOAL_COMMAND_RECIPES,
+      workflow: SHARED_WORKFLOW.map((s) => s.step === 2 ? { ...s, cli: "todos mcp --register claude" } : s),
+      task_contract: { ...SHARED_TASK_CONTRACT },
+      verification: { ...SHARED_VERIFICATION },
+      handoff: { ...SHARED_HANDOFF },
+      failure_modes: [
+        {
+          symptom: "claude mcp add fails",
+          cause: "Claude Code CLI not installed or not on PATH",
+          recovery: "Install Claude Code, then run the printed `claude mcp add` command manually"
+        },
+        {
+          symptom: "LockError on start",
+          cause: "Task locked by another agent within 30-minute window",
+          recovery: "Use `todos stale` to find abandoned locks or wait for lock expiry"
+        },
+        {
+          symptom: "CompletionGuardError",
+          cause: "Required checklist or approval gate not satisfied",
+          recovery: "Run `todos approvals list --task <id>` and complete gates first"
+        }
+      ],
+      examples: [
+        { title: "Global MCP registration", command: "todos mcp --register claude --global" },
+        { title: "Execute goal step", command: "todos goal execute my-plan --agent claude-agent" },
+        { title: "Link git traceability", command: "todos trace link <task-id> --branch feature/x --commit abc123" }
+      ]
+    },
+    takumi: {
+      schema_version: ADAPTER_DOCS_SCHEMA_VERSION,
+      host: "takumi",
+      display_name: "Takumi",
+      install: {
+        bun: "bun install -g @hasna/todos",
+        verify: "todos --version && takumi mcp list 2>/dev/null | grep todos || true"
+      },
+      mcp: {
+        register_cli: "todos mcp --register takumi",
+        unregister_cli: "todos mcp --unregister takumi",
+        config_path: "~/.takumi.json (project-scoped mcpServers) or local Takumi MCP config",
+        recommended_profile: "minimal",
+        env: ["TODOS_PROFILE=minimal", "TODOS_DB_PATH=.todos/todos.db"]
+      },
+      goal_commands: GOAL_COMMAND_RECIPES,
+      workflow: SHARED_WORKFLOW.map((s) => s.step === 2 ? { ...s, cli: "todos mcp --register takumi" } : s),
+      task_contract: { ...SHARED_TASK_CONTRACT },
+      verification: { ...SHARED_VERIFICATION },
+      handoff: { ...SHARED_HANDOFF },
+      failure_modes: [
+        {
+          symptom: "todos MCP missing in Takumi",
+          cause: "MCP server not added to project or user scope",
+          recovery: "Run `takumi mcp add --scope project todos -- todos-mcp` or `todos mcp --register takumi`"
+        },
+        {
+          symptom: "Wrong database / empty task list",
+          cause: "TODOS_DB_PATH not set; cwd differs from git project root",
+          recovery: "Set TODOS_DB_PATH=.todos/todos.db or run `todos bootstrap` in project root"
+        },
+        {
+          symptom: "Agent run queue stuck",
+          cause: "Run claimed but never completed/failed",
+          recovery: "Run `todos runs list --status running` then complete or fail the run"
+        }
+      ],
+      examples: [
+        { title: "Manual Takumi MCP add", command: "takumi mcp add --scope project todos -- todos-mcp" },
+        { title: "Legacy tmux handoff", command: "todos dispatch agents:0 --tasks <id>" },
+        { title: "Handoff on session end", command: "todos goal handoff release-v2 --format md --agent takumi-agent" }
+      ]
+    }
+  };
+});
+
 // src/cli/commands/mcp-hooks-commands.ts
 var exports_mcp_hooks_commands = {};
 __export(exports_mcp_hooks_commands, {
@@ -77671,6 +78106,28 @@ function unregisterGemini() {
   writeJsonFile2(configPath, config);
   console.log(chalk10.green(`Gemini CLI: unregistered from ${configPath}`));
 }
+function registerTakumi(binPath, global) {
+  const scope = global ? "user" : "project";
+  const cmd = `takumi mcp add --scope ${scope} todos -- ${binPath} --stdio`;
+  try {
+    execSync3(cmd, { stdio: "pipe" });
+    console.log(chalk10.green(`Takumi (${scope}): registered via 'takumi mcp add'`));
+  } catch {
+    console.log(chalk10.yellow(`Takumi: could not auto-register. Run this command manually:`));
+    console.log(chalk10.cyan(`  ${cmd}`));
+  }
+}
+function unregisterTakumi(global) {
+  const scope = global ? "user" : "project";
+  const cmd = `takumi mcp remove --scope ${scope} todos`;
+  try {
+    execSync3(cmd, { stdio: "pipe" });
+    console.log(chalk10.green(`Takumi (${scope}): removed todos MCP server`));
+  } catch {
+    console.log(chalk10.yellow(`Takumi: could not auto-remove. Run manually:`));
+    console.log(chalk10.cyan(`  ${cmd}`));
+  }
+}
 function cursorConfigPath(global) {
   return global ? join27(HOME2, ".cursor", "mcp.json") : join27(process.cwd(), ".cursor", "mcp.json");
 }
@@ -77701,7 +78158,7 @@ function unregisterCursor(global) {
   console.log(chalk10.green(`Cursor (${global ? "user" : "project"}): unregistered from ${configPath}`));
 }
 function registerMcp(agent, global) {
-  const agents = agent === "all" ? ["claude", "codex", "gemini", "cursor"] : [agent];
+  const agents = agent === "all" ? [...MCP_REGISTRABLE_CLI_AGENTS] : [agent];
   const binPath = getMcpBinaryPath();
   for (const a of agents) {
     switch (a) {
@@ -77717,13 +78174,16 @@ function registerMcp(agent, global) {
       case "cursor":
         registerCursor(binPath, global);
         break;
+      case "takumi":
+        registerTakumi(binPath, global);
+        break;
       default:
-        console.error(chalk10.red(`Unknown agent: ${a}. Use: claude, codex, gemini, cursor, all`));
+        console.error(chalk10.red(`Unknown agent: ${a}. Use: ${MCP_AGENT_CHOICES}`));
     }
   }
 }
 function unregisterMcp(agent, global) {
-  const agents = agent === "all" ? ["claude", "codex", "gemini", "cursor"] : [agent];
+  const agents = agent === "all" ? [...MCP_REGISTRABLE_CLI_AGENTS] : [agent];
   for (const a of agents) {
     switch (a) {
       case "claude":
@@ -77738,8 +78198,11 @@ function unregisterMcp(agent, global) {
       case "cursor":
         unregisterCursor(global);
         break;
+      case "takumi":
+        unregisterTakumi(global);
+        break;
       default:
-        console.error(chalk10.red(`Unknown agent: ${a}. Use: claude, codex, gemini, cursor, all`));
+        console.error(chalk10.red(`Unknown agent: ${a}. Use: ${MCP_AGENT_CHOICES}`));
     }
   }
 }
@@ -77811,7 +78274,7 @@ exit 0
     console.log(chalk10.green(`Claude Code hooks configured in: ${settingsPath}`));
     console.log(chalk10.dim("Task list ID auto-detected from project."));
   });
-  program2.command("mcp").description("Start MCP server (stdio)").option("--register <agent>", "Register MCP server with an agent (claude, codex, gemini, cursor, all)").option("--unregister <agent>", "Unregister MCP server from an agent (claude, codex, gemini, cursor, all)").option("-g, --global", "Register/unregister globally (user-level) instead of project-level").action(async (opts) => {
+  program2.command("mcp").description("Start MCP server (stdio)").option("--register <agent>", `Register MCP server with an agent (${MCP_AGENT_CHOICES})`).option("--unregister <agent>", `Unregister MCP server from an agent (${MCP_AGENT_CHOICES})`).option("-g, --global", "Register/unregister globally (user-level) instead of project-level").action(async (opts) => {
     if (opts.register) {
       registerMcp(opts.register, opts.global);
       return;
@@ -78764,13 +79227,15 @@ $(dirname "$0")/../../scripts/post-commit-hook.sh
     }
   });
 }
-var HOME2;
+var HOME2, MCP_AGENT_CHOICES;
 var init_mcp_hooks_commands = __esm(() => {
   init_tasks();
   init_helpers();
   init_cloud_router();
   init_sync_utils();
+  init_agent_adapter_docs();
   HOME2 = getHomeDir();
+  MCP_AGENT_CHOICES = `${MCP_REGISTRABLE_CLI_AGENTS.join(", ")}, all`;
 });
 
 // src/cli/commands/dispatch.tsx