@wrongstack/tools 1.0.8 → 1.0.10

package/dist/{chunk-2NTHMZV3.js → chunk-VMJY6FYJ.js}

@@ -3,9 +3,6 @@ import {
   taskFileToSerializedGraph
 } from "./chunk-YZECCW3F.js";
 
-// src/kanban.ts
-import { stripLifecycleIssues as stripLifecycleIssues2 } from "@wrongstack/kanban";
-
 // src/kanban-board-actions.ts
 import { loadTasks } from "@wrongstack/core/storage";
 import { deserializeTaskGraph, serializeTaskGraph } from "@wrongstack/core/tasking";
@@ -31,9 +28,163 @@ import {
   updateBoard
 } from "@wrongstack/kanban";
 
+// src/kanban-tool-results.ts
+import { ToolValidationError } from "@wrongstack/core/types";
+import {
+  decodeLifecycleIssues,
+  stripLifecycleIssues
+} from "@wrongstack/kanban";
+function atomicityNudge(task) {
+  if (task.atomicityAssessment?.verdict !== "needs_decomposition") return "";
+  const reasons = task.atomicityAssessment.criteria.filter((entry) => entry.score < 1).map((entry) => entry.reason).join(" | ");
+  return ` Atomicity: needs_decomposition (score ${task.atomicityAssessment.score}) \u2014 call propose_decomposition with 2+ subtasks before dispatch. Reasons: ${reasons}`;
+}
+function readEnvGateEnforcement() {
+  const raw = process.env["WRONGSTACK_KANBAN_GATE"]?.trim().toLowerCase();
+  return raw === "strict" || raw === "soft" || raw === "off" ? raw : void 0;
+}
+var CLASSIFIER_HINT = {
+  NOT_FOUND: "ENOENT",
+  CONFLICT: "EBUSY",
+  UNAVAILABLE: "ECONNREFUSED"
+};
+function formatKanbanErrorMessage(code, message, opts) {
+  let text = `[${code}] ${message}`;
+  if (opts.committed) text += ` Already committed: ${opts.committed}`;
+  const extra = (opts.issues ?? []).filter((issue) => issue.message.trim() !== message.trim());
+  if (extra.length > 0) {
+    text += ` Issues: ${extra.map((issue) => issue.field ? `${issue.field}: ${issue.message}` : issue.message).join(" | ")}`;
+  }
+  return text;
+}
+var KanbanToolError = class extends Error {
+  kanbanCode;
+  /** Classifier hint (see CLASSIFIER_HINT); not the Kanban code. */
+  code;
+  retryable;
+  issues;
+  committed;
+  /** The bare message, without the code prefix, committed note, or issues tail. */
+  detail;
+  constructor(code, message, opts = {}) {
+    super(
+      formatKanbanErrorMessage(code, message, opts),
+      opts.cause !== void 0 ? { cause: opts.cause } : void 0
+    );
+    this.detail = message;
+    this.name = code === "ABORTED" ? "AbortError" : "KanbanToolError";
+    this.kanbanCode = code;
+    this.retryable = opts.retryable ?? (code === "CONFLICT" || code === "UNAVAILABLE");
+    const hint = CLASSIFIER_HINT[code];
+    this.code = hint === "ENOENT" || this.retryable ? hint : void 0;
+    this.issues = opts.issues;
+    this.committed = opts.committed;
+  }
+};
+var KanbanInputError = class extends ToolValidationError {
+  kanbanCode = "INVALID_INPUT";
+  retryable = false;
+  issues = void 0;
+  constructor(message, field) {
+    super({ message: `[INVALID_INPUT] ${message}`, ...field !== void 0 ? { field } : {} });
+  }
+};
+function invalidInput(message, field) {
+  return new KanbanInputError(message, field);
+}
+function notFound(message, opts = {}) {
+  return new KanbanToolError("NOT_FOUND", message, opts);
+}
+function refused(message, opts = {}) {
+  return new KanbanToolError("REFUSED", message, opts);
+}
+function conflict(message, opts = {}) {
+  return new KanbanToolError("CONFLICT", message, opts);
+}
+function isKanbanToolFailure(err) {
+  return err instanceof Error && typeof err.kanbanCode === "string" && typeof err.retryable === "boolean";
+}
+function errorCode(err) {
+  const code = err.code;
+  return typeof code === "string" ? code : void 0;
+}
+function lifecycleIssuesOf(err) {
+  const own = err.issues;
+  if (Array.isArray(own)) return own;
+  return decodeLifecycleIssues(err);
+}
+var UNAVAILABLE_MESSAGE_PATTERNS = [
+  /^Kanban project server is disabled/,
+  /^Failed to connect to kanban project server/,
+  /^Kanban server .+: /,
+  /^Connection closed$/,
+  /^connect-timeout$/,
+  /^Request \S+ timed out$/
+];
+var UNAVAILABLE_ERRNO = /* @__PURE__ */ new Set(["ECONNREFUSED", "ECONNRESET", "EPIPE", "ETIMEDOUT"]);
+function toKanbanToolError(err, committed) {
+  if (!(err instanceof Error)) return err;
+  if (isKanbanToolFailure(err)) {
+    if (!committed) return err;
+    return err instanceof KanbanToolError ? new KanbanToolError(err.kanbanCode, err.detail, {
+      issues: err.issues,
+      retryable: err.retryable,
+      committed: err.committed ? `${err.committed} ${committed}` : committed,
+      cause: err
+    }) : err;
+  }
+  const code = errorCode(err);
+  if (err.name === "KanbanLifecycleError" || code === "LIFECYCLE") {
+    return refused(stripLifecycleIssues(err.message), {
+      issues: lifecycleIssuesOf(err),
+      committed,
+      cause: err
+    });
+  }
+  if (err.name === "StaleWriteError" || code === "STALE_WRITE") {
+    return conflict(err.message, { retryable: true, committed, cause: err });
+  }
+  if (code !== void 0 && UNAVAILABLE_ERRNO.has(code) || UNAVAILABLE_MESSAGE_PATTERNS.some((pattern) => pattern.test(err.message))) {
+    return new KanbanToolError("UNAVAILABLE", err.message, {
+      retryable: true,
+      committed,
+      cause: err
+    });
+  }
+  if (/^Ambiguous kanban (task|board) id /.test(err.message)) {
+    return invalidInput(err.message, "taskId");
+  }
+  return err;
+}
+function okBoard(board, message = "Board loaded.") {
+  return { ok: true, message, board };
+}
+function okTask(board, task, message) {
+  return { ok: true, message, board, task };
+}
+function resolveTaskRef(board, taskRef) {
+  if (!taskRef?.trim()) return void 0;
+  const exact = board.tasks.find((task) => task.id === taskRef);
+  if (exact) return exact;
+  const matches = board.tasks.filter((task) => task.id.startsWith(taskRef));
+  if (matches.length > 1) {
+    throw invalidInput(
+      `Ambiguous kanban task id "${taskRef}": ${matches.slice(0, 5).map((task) => task.id).join(", ")}`,
+      "taskId"
+    );
+  }
+  return matches[0];
+}
+
 // src/kanban-board-inputs.ts
 function agentSettableGate(enforcement) {
-  if (enforcement === void 0 || enforcement === "off") return {};
+  if (enforcement === void 0) return {};
+  if (enforcement !== "strict" && enforcement !== "soft") {
+    throw invalidInput(
+      `gateEnforcement "${String(enforcement)}" is not settable from the kanban tool; only "strict" or "soft" (switching the completion gate off is a human decision made through board config).`,
+      "gateEnforcement"
+    );
+  }
   return { completionGate: { enforcement } };
 }
 function boardCreateInput(input, title) {
@@ -77,34 +228,12 @@ function duplicateBoardOptions(input) {
 
 // src/kanban-split-task-handler.ts
 import { getBoard, splitTask } from "@wrongstack/kanban";
-
-// src/kanban-tool-results.ts
-function atomicityNudge(task) {
-  if (task.atomicityAssessment?.verdict !== "needs_decomposition") return "";
-  const reasons = task.atomicityAssessment.criteria.filter((entry) => entry.score < 1).map((entry) => entry.reason).join(" | ");
-  return ` Atomicity: needs_decomposition (score ${task.atomicityAssessment.score}) \u2014 call propose_decomposition with 2+ subtasks before dispatch. Reasons: ${reasons}`;
-}
-function readEnvGateEnforcement() {
-  const raw = process.env["WRONGSTACK_KANBAN_GATE"]?.trim().toLowerCase();
-  return raw === "strict" || raw === "soft" || raw === "off" ? raw : void 0;
-}
-function fail(message) {
-  return { ok: false, message };
-}
-function okBoard(board, message = "Board loaded.") {
-  return { ok: true, message, board };
-}
-function okTask(board, task, message) {
-  return { ok: true, message, board, task };
-}
-
-// src/kanban-split-task-handler.ts
 async function handleSplitTask(projectRoot, input, extraSplitOptions, eventContext) {
   const boardId = input.boardId;
   const taskId = input.taskId;
   const childTitles = input.childTitles;
   if (!boardId || !taskId || !childTitles?.length) {
-    return fail("split requires boardId, taskId, and at least one childTitles.");
+    throw invalidInput("split requires boardId, taskId, and at least one childTitles.");
   }
   const {
     targetColumnId,
@@ -134,12 +263,12 @@ async function handleSplitTask(projectRoot, input, extraSplitOptions, eventConte
     },
     eventContext
   );
-  if (!result) return fail("Task not found.");
-  const freshParent = result.board.tasks?.find((t) => t.id === taskId);
+  if (!result) throw notFound("Task not found.");
+  const freshParent = result.board.tasks?.find((t) => t.id === taskId) ?? result.board.tasks?.find((t) => t.id === result.parent?.id);
   if (!freshParent) {
-    return fail(
-      `Split succeeded but parent ${taskId} not found in returned board. Children: [${result.children.map((c) => c.id).join(", ")}].`
-    );
+    throw conflict(`Parent ${taskId} not found in the board returned by the split.`, {
+      committed: `the split was written \u2014 child task(s) [${result.children.map((c) => c.id).join(", ")}] were created. Re-read the board with get_board.`
+    });
   }
   return {
     ok: true,
@@ -165,11 +294,13 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
       return { ok: true, message: `${boards.length} board(s).`, boards };
     }
     case "get_board": {
+      if (!input.boardId) throw invalidInput("get_board requires boardId.", "boardId");
       const board = await requireBoard(projectRoot, input.boardId);
-      return board ? okBoard(board) : fail("Board not found.");
+      if (!board) throw notFound("Board not found.");
+      return okBoard(board);
     }
     case "create_board": {
-      if (!input.title) return fail("create_board requires title.");
+      if (!input.title) throw invalidInput("create_board requires title.", "title");
       const existing = (await listBoards(projectRoot)).filter(
         (candidate) => (candidate.kind ?? "project") === "project"
       );
@@ -180,52 +311,65 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
       return { ok: true, message: `Board created: ${board.title}.${note}`, board };
     }
     case "update_board": {
-      if (!input.boardId) return fail("update_board requires boardId.");
+      if (!input.boardId) throw invalidInput("update_board requires boardId.", "boardId");
       const board = await updateBoard(projectRoot, input.boardId, boardUpdatePatch(input));
-      return board ? okBoard(board, "Board updated.") : fail("Board not found.");
+      if (!board) throw notFound("Board not found.");
+      return okBoard(board, "Board updated.");
     }
     case "adopt_managed_lifecycle": {
       if (!input.boardId || !input.author || !input.transitionComment) {
-        return fail(
+        throw invalidInput(
           "adopt_managed_lifecycle requires boardId, author, transitionComment, and five ordered columns."
         );
       }
       if (input.columns?.length !== 5) {
-        return fail(
-          "adopt_managed_lifecycle columns must be ordered as backlog, todo, running, review, done."
+        throw invalidInput(
+          "adopt_managed_lifecycle columns must be ordered as backlog, todo, running, review, done.",
+          "columns"
         );
       }
       const [backlog, todo, running, review, done] = input.columns;
       if (!backlog || !todo || !running || !review || !done) {
-        return fail("adopt_managed_lifecycle columns must contain five nonblank ids.");
+        throw invalidInput(
+          "adopt_managed_lifecycle columns must contain five nonblank ids.",
+          "columns"
+        );
       }
       const board = await adoptManagedLifecycle(projectRoot, input.boardId, {
         columns: { backlog, todo, running, review, done },
         actor: input.author,
         comment: input.transitionComment
       });
-      return board ? okBoard(board, "Managed lifecycle adopted without moving existing cards.") : fail("Board not found.");
+      if (!board) throw notFound("Board not found.");
+      return okBoard(board, "Managed lifecycle adopted without moving existing cards.");
     }
     case "release_managed_lifecycle": {
-      if (!input.boardId) return fail("release_managed_lifecycle requires boardId.");
+      if (!input.boardId) {
+        throw invalidInput("release_managed_lifecycle requires boardId.", "boardId");
+      }
       const board = await updateBoard(projectRoot, input.boardId, { lifecycle: null });
-      return board ? okBoard(
+      if (!board) throw notFound("Board not found.");
+      return okBoard(
         board,
         "Managed lifecycle released; the board now tracks work without strict gates."
-      ) : fail("Board not found.");
+      );
     }
     case "duplicate_board": {
-      if (!input.boardId) return fail("duplicate_board requires boardId.");
+      if (!input.boardId) throw invalidInput("duplicate_board requires boardId.", "boardId");
       const board = await duplicateBoard(projectRoot, input.boardId, duplicateBoardOptions(input));
-      return board ? okBoard(board, "Board duplicated.") : fail("Board not found.");
+      if (!board) throw notFound("Board not found.");
+      return okBoard(board, "Board duplicated.");
     }
     case "delete_board": {
-      if (!input.boardId) return fail("delete_board requires boardId.");
+      if (!input.boardId) throw invalidInput("delete_board requires boardId.", "boardId");
       const removed = await removeBoard(projectRoot, input.boardId);
-      return { ok: removed, message: removed ? "Board deleted." : "Board not found." };
+      if (!removed) throw notFound("Board not found.");
+      return { ok: true, message: "Board deleted." };
     }
     case "generate_board": {
-      if (!input.description) return fail("generate_board requires description.");
+      if (!input.description) {
+        throw invalidInput("generate_board requires description.", "description");
+      }
       const boardInput = createBoardFromText({
         description: input.description,
         ...input.title !== void 0 ? { title: input.title } : {},
@@ -241,17 +385,17 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
       return okBoard(await getBoard2(projectRoot, board.id) ?? board, "Board generated.");
     }
     case "export_markdown": {
+      if (!input.boardId) throw invalidInput("export_markdown requires boardId.", "boardId");
       const board = await requireBoard(projectRoot, input.boardId);
-      if (!board) return fail("Board not found.");
+      if (!board) throw notFound("Board not found.");
       return {
         ok: true,
         message: "Board exported.",
-        board,
         markdown: exportBoardAsMarkdown(board)
       };
     }
     case "export_task_graph": {
-      if (!input.boardId) return fail("export_task_graph requires boardId.");
+      if (!input.boardId) throw invalidInput("export_task_graph requires boardId.", "boardId");
       const exported = await exportBoardToTaskGraph(projectRoot, input.boardId, {
         ...input.graphId !== void 0 ? { graphId: input.graphId } : {},
         ...input.specId !== void 0 ? { specId: input.specId } : {},
@@ -259,7 +403,7 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
         ...input.preserveOriginTaskIds !== void 0 ? { preserveOriginTaskIds: input.preserveOriginTaskIds } : {},
         ...input.includeArchived !== void 0 ? { includeArchived: input.includeArchived } : {}
       });
-      if (!exported) return fail("Board not found.");
+      if (!exported) throw notFound("Board not found.");
       return {
         ok: true,
         message: `Task graph exported with ${exported.graph.nodes.size} node(s).`,
@@ -269,7 +413,7 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
     }
     case "sync_task_graph": {
       if (!input.boardId || !input.taskGraph) {
-        return fail("sync_task_graph requires boardId and taskGraph.");
+        throw invalidInput("sync_task_graph requires boardId and taskGraph.");
       }
       const graph = deserializeTaskGraph(input.taskGraph);
       const result = await syncBoardFromTaskGraph(projectRoot, input.boardId, graph, {
@@ -283,14 +427,16 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
         ...input.archiveMissingTasks !== void 0 ? { archiveMissingTasks: input.archiveMissingTasks } : {},
         ...input.preserveManualDependencies !== void 0 ? { preserveManualDependencies: input.preserveManualDependencies } : {}
       });
-      return result ? {
+      if (!result) throw notFound("Board not found.");
+      return {
         ok: true,
         message: `Task graph synced: ${result.createdTaskIds.length} created, ${result.updatedTaskIds.length} updated, ${result.archivedTaskIds.length} archived.`,
         board: result.board
-      } : fail("Board not found.");
+      };
     }
     case "create_from_graph": {
-      if (!input.taskGraph) return fail("create_from_graph requires taskGraph.");
+      if (!input.taskGraph)
+        throw invalidInput("create_from_graph requires taskGraph.", "taskGraph");
       const graph = deserializeTaskGraph(input.taskGraph);
       const { board } = await createBoardFromTaskGraph(projectRoot, graph, {
         ...input.title !== void 0 ? { title: input.title } : {},
@@ -309,9 +455,13 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
     }
     case "import_session_tasks": {
       const taskPath = ctx.meta?.["task.path"];
-      if (!taskPath) return fail("No session task file for this session.");
+      if (!taskPath) {
+        return { ok: true, imported: 0, message: "No session task file for this session." };
+      }
       const file = await loadTasks(taskPath);
-      if (!file || file.tasks.length === 0) return fail("No session tasks to import.");
+      if (!file || file.tasks.length === 0) {
+        return { ok: true, imported: 0, message: "No session tasks to import." };
+      }
       const sessionId = ctx.session?.id ?? file.sessionId ?? "session";
       const graph = deserializeTaskGraph(taskFileToSerializedGraph(file.tasks, sessionId));
       const tags = ["session", `session:${sessionId}`];
@@ -325,11 +475,17 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
           archiveMissingTasks: true,
           includeCompletedTasks: true
         });
-        return result ? {
+        if (!result) {
+          throw conflict("Session board vanished mid-sync; nothing was imported. Retry.", {
+            retryable: true
+          });
+        }
+        return {
           ok: true,
+          imported: file.tasks.length,
           message: `Synced ${file.tasks.length} session tasks into board "${result.board.title}".`,
           board: result.board
-        } : fail("Session board vanished mid-sync.");
+        };
       }
       const { board } = await createBoardFromTaskGraph(projectRoot, graph, {
         title: `Session tasks (${sessionId.slice(0, 8)})`,
@@ -338,6 +494,7 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
       });
       return {
         ok: true,
+        imported: file.tasks.length,
         message: `Imported ${file.tasks.length} session tasks into new board "${board.title}".`,
         board
       };
@@ -383,12 +540,14 @@ async function handleKanbanBoardAction(projectRoot, input, ctx) {
       };
     }
     case "events": {
-      if (!input.boardId) return fail("events requires boardId.");
+      if (!input.boardId) throw invalidInput("events requires boardId.", "boardId");
       const eventList = await listKanbanEvents(projectRoot, input.boardId);
+      const limit = typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0 ? Math.floor(input.limit) : void 0;
+      const events = limit !== void 0 ? eventList.slice(-limit) : eventList;
       return {
         ok: true,
-        message: `${eventList.length} event(s).`,
-        events: eventList
+        message: events.length === eventList.length ? `${eventList.length} event(s).` : `${events.length} most recent of ${eventList.length} event(s).`,
+        events
       };
     }
     case "queue_health": {
@@ -420,11 +579,11 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
   const eventContext = { sessionId, ...actor !== void 0 ? { actor } : {} };
   switch (input.action) {
     case "get_contract_graph": {
-      if (!input.boardId) return fail("get_contract_graph requires boardId.");
+      if (!input.boardId) throw invalidInput("get_contract_graph requires boardId.");
       const found = await getContractGraph(projectRoot, input.boardId);
-      if (!found) return fail("Board not found.");
+      if (!found) throw notFound("Board not found.");
       const evaluated = input.taskId ? await evaluateTaskContractGraph(projectRoot, input.boardId, input.taskId) : null;
-      if (input.taskId && !evaluated) return fail("Task not found on this board.");
+      if (input.taskId && !evaluated) throw notFound("Task not found on this board.");
       return {
         ok: true,
         message: found.graph ? `Contract map: ${found.graph.nodes.length} node(s), ${found.graph.edges.length} edge(s), enforcement ${found.graph.enforcement}.` : "No contract map on this board yet. Call configure_contract_graph to start one.",
@@ -434,7 +593,7 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
       };
     }
     case "configure_contract_graph": {
-      if (!input.boardId) return fail("configure_contract_graph requires boardId.");
+      if (!input.boardId) throw invalidInput("configure_contract_graph requires boardId.");
       const enforcement = input.contractEnforcement ?? "advisory";
       const board = await configureContractGraph(
         projectRoot,
@@ -442,14 +601,15 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
         enforcement,
         eventContext
       );
-      return board ? okBoard(board, `Contract map enforcement set to ${enforcement}.`) : fail("Board not found.");
+      if (!board) throw notFound("Board not found.");
+      return okBoard(board, `Contract map enforcement set to ${enforcement}.`);
     }
     case "upsert_contract_node": {
       if (!input.boardId || !input.taskId) {
-        return fail("upsert_contract_node requires boardId and taskId.");
+        throw invalidInput("upsert_contract_node requires boardId and taskId.");
       }
       if (!input.contractNodeKind || !input.contractNodeTitle) {
-        return fail("upsert_contract_node requires contractNodeKind and contractNodeTitle.");
+        throw invalidInput("upsert_contract_node requires contractNodeKind and contractNodeTitle.");
       }
       const waiver = input.contractNodeState === "waived" ? {
         actor: actor ?? "agent",
@@ -457,7 +617,7 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
         at: (/* @__PURE__ */ new Date()).toISOString()
       } : void 0;
       if (waiver && !waiver.reason.trim()) {
-        return fail("A waived contract node requires contractWaiverReason.");
+        throw invalidInput("A waived contract node requires contractWaiverReason.");
       }
       const result = await upsertContractNode(
         projectRoot,
@@ -477,7 +637,7 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
         },
         eventContext
       );
-      if (!result) return fail("Board or task not found.");
+      if (!result) throw notFound("Board or task not found.");
       return {
         ok: true,
         message: `Contract node ${result.node.kind} "${result.node.title}" saved (${result.node.id}).`,
@@ -487,7 +647,7 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
     }
     case "remove_contract_node": {
       if (!input.boardId || !input.contractNodeId) {
-        return fail("remove_contract_node requires boardId and contractNodeId.");
+        throw invalidInput("remove_contract_node requires boardId and contractNodeId.");
       }
       const board = await removeContractNode(
         projectRoot,
@@ -495,13 +655,17 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
         input.contractNodeId,
         eventContext
       );
-      return board ? okBoard(board, "Contract node removed, along with every edge that touched it.") : fail("Contract node not found.");
+      if (!board) throw notFound("Contract node not found.");
+      return okBoard(board, "Contract node removed, along with every edge that touched it.");
     }
     case "add_contract_edge": {
       if (!input.boardId || !input.contractEdgeFrom || !input.contractEdgeTo) {
-        return fail("add_contract_edge requires boardId, contractEdgeFrom, and contractEdgeTo.");
+        throw invalidInput(
+          "add_contract_edge requires boardId, contractEdgeFrom, and contractEdgeTo."
+        );
       }
-      if (!input.contractEdgeType) return fail("add_contract_edge requires contractEdgeType.");
+      if (!input.contractEdgeType)
+        throw invalidInput("add_contract_edge requires contractEdgeType.");
       const result = await addContractEdge(
         projectRoot,
         input.boardId,
@@ -516,7 +680,7 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
         },
         eventContext
       );
-      if (!result) return fail("Board not found.");
+      if (!result) throw notFound("Board not found.");
       return {
         ok: true,
         message: `Contract edge ${result.edge.type}: ${result.edge.from} \u2192 ${result.edge.to}.`,
@@ -526,7 +690,7 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
     }
     case "remove_contract_edge": {
       if (!input.boardId || !input.contractEdgeId) {
-        return fail("remove_contract_edge requires boardId and contractEdgeId.");
+        throw invalidInput("remove_contract_edge requires boardId and contractEdgeId.");
       }
       const board = await removeContractEdge(
         projectRoot,
@@ -534,7 +698,8 @@ async function handleKanbanContractAction(projectRoot, input, actor, sessionId)
         input.contractEdgeId,
         eventContext
       );
-      return board ? okBoard(board, "Contract edge removed.") : fail("Contract edge not found.");
+      if (!board) throw notFound("Contract edge not found.");
+      return okBoard(board, "Contract edge removed.");
     }
     default:
       return void 0;
@@ -581,13 +746,13 @@ async function handleKanbanDecompositionAction(projectRoot, input, ctx) {
   switch (input.action) {
     case "assess_atomicity": {
       if (!input.boardId || !input.taskId) {
-        return fail("assess_atomicity requires boardId and taskId.");
+        throw invalidInput("assess_atomicity requires boardId and taskId.");
       }
       const result = await assessTaskAtomicity(projectRoot, input.boardId, input.taskId, {
         assessedBy: "agent",
         eventContext
       });
-      if (!result) return fail("Task not found.");
+      if (!result) throw notFound("Task not found.");
       const failing = result.assessment.criteria.filter((entry) => entry.score < 1).map((entry) => entry.reason);
       const guidance = result.assessment.verdict === "needs_decomposition" ? ` This task should be split before dispatch \u2014 call propose_decomposition with 2+ subtasks (each with one verifiable success criterion). Reasons: ${failing.join(" | ")}` : result.assessment.verdict === "composite" ? " Container task: work happens in its children; it is verified via subtask aggregation." : "";
       return okTask(
@@ -598,15 +763,16 @@ async function handleKanbanDecompositionAction(projectRoot, input, ctx) {
     }
     case "propose_decomposition": {
       if (!input.boardId || !input.taskId || !input.subtasks?.length) {
-        return fail("propose_decomposition requires boardId, taskId, and subtasks (2+).");
+        throw invalidInput("propose_decomposition requires boardId, taskId, and subtasks (2+).");
       }
       if (input.subtasks.length < 2) {
-        return fail("propose_decomposition requires at least two subtasks.");
+        throw invalidInput("propose_decomposition requires at least two subtasks.", "subtasks");
       }
       const invalid = input.subtasks.find(
         (subtask) => typeof subtask?.title !== "string" || !subtask.title.trim()
       );
-      if (invalid) return fail("Every proposed subtask needs a non-blank title.");
+      if (invalid)
+        throw invalidInput("Every proposed subtask needs a non-blank title.", "subtasks");
       const result = await proposeTaskDecomposition(
         projectRoot,
         input.boardId,
@@ -618,15 +784,25 @@ async function handleKanbanDecompositionAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      if (!result) return fail("Task not found.");
+      if (!result) throw notFound("Task not found.");
       const message = result.proposal.status === "applied" ? `Decomposition applied: ${result.proposal.appliedChildTaskIds?.length ?? 0} child tasks created (parent marked atomic).` : 'Decomposition proposal recorded \u2014 awaiting approval (board policy is "propose"). It can be approved from the WebUI or via update_task.';
       return okTask(result.board, result.task, message);
     }
     case "verify_completion": {
       if (!input.boardId || !input.taskId) {
-        return fail("verify_completion requires boardId and taskId.");
+        throw invalidInput("verify_completion requires boardId and taskId.");
+      }
+      let verResult;
+      try {
+        verResult = await verifyTaskCompletion(projectRoot, input.boardId, input.taskId, {
+          persist: false
+        });
+      } catch (err) {
+        if (err instanceof Error && /^(Board|Task) not found\b/.test(err.message)) {
+          throw notFound(err.message, { cause: err });
+        }
+        throw err;
       }
-      const verResult = await verifyTaskCompletion(projectRoot, input.boardId, input.taskId);
       const persistedBoard = await updateTask(
         projectRoot,
         input.boardId,
@@ -638,20 +814,15 @@ async function handleKanbanDecompositionAction(projectRoot, input, ctx) {
         eventContext
       );
       if (!persistedBoard) {
-        return {
-          ok: false,
-          verdict: verResult.report.verdict,
-          message: `Verification succeeded but persist failed: ${verResult.report.markdownSummary}. Board may be stale \u2014 re-run verify_completion.`,
-          board: verResult.board
-        };
+        throw conflict(
+          `Verification ran (verdict: ${verResult.report.verdict}) but its report could not be saved: the task is no longer on the board. Nothing was written; re-run verify_completion.`,
+          { retryable: true }
+        );
       }
       recordKanbanVerificationEvidence(ctx, verResult.report);
-      const freshTask = persistedBoard.tasks?.find((t) => t.id === input.taskId);
-      const deterministicVerdicts = ["passed", "failed", "needs_human", "incomplete"];
+      const freshTask = persistedBoard.tasks?.find((t) => t.id === verResult.task.id);
       return {
-        ok: deterministicVerdicts.includes(
-          verResult.report.verdict
-        ),
+        ok: true,
         verdict: verResult.report.verdict,
         message: verResult.report.markdownSummary,
         board: persistedBoard,
@@ -693,7 +864,7 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
     }
     case "add_dependency": {
       if (!input.boardId || !input.taskId || !input.dependencyTaskId) {
-        return fail("add_dependency requires boardId, taskId, and dependencyTaskId.");
+        throw invalidInput("add_dependency requires boardId, taskId, and dependencyTaskId.");
       }
       const board = await addDependency(
         projectRoot,
@@ -702,11 +873,12 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
         input.dependencyTaskId,
         eventContext
       );
-      return board ? okBoard(board, "Dependency added.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      return okBoard(board, "Dependency added.");
     }
     case "add_goal_metric": {
       if (!input.boardId || !input.taskId || !input.metricName) {
-        return fail("add_goal_metric requires boardId, taskId, and metricName.");
+        throw invalidInput("add_goal_metric requires boardId, taskId, and metricName.");
       }
       const board = await addGoalMetricToTask(
         projectRoot,
@@ -723,11 +895,12 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return board ? okBoard(board, "Goal metric added.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      return okBoard(board, "Goal metric added.");
     }
     case "update_goal_metric": {
       if (!input.boardId || !input.taskId || !input.metricId) {
-        return fail("update_goal_metric requires boardId, taskId, and metricId.");
+        throw invalidInput("update_goal_metric requires boardId, taskId, and metricId.");
       }
       const board = await updateGoalMetricOnTask(
         projectRoot,
@@ -745,11 +918,12 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return board ? okBoard(board, "Goal metric updated.") : fail("Metric not found.");
+      if (!board) throw notFound("Metric not found.");
+      return okBoard(board, "Goal metric updated.");
     }
     case "add_check": {
       if (!input.boardId || !input.taskId || !input.checkDescription) {
-        return fail("add_check requires boardId, taskId, and checkDescription.");
+        throw invalidInput("add_check requires boardId, taskId, and checkDescription.");
       }
       const board = await addCheckToTask(
         projectRoot,
@@ -763,11 +937,12 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return board ? okBoard(board, "Check added.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      return okBoard(board, "Check added.");
     }
     case "update_check": {
       if (!input.boardId || !input.taskId || !input.checkId) {
-        return fail("update_check requires boardId, taskId, and checkId.");
+        throw invalidInput("update_check requires boardId, taskId, and checkId.");
       }
       const board = await updateCheckOnTask(
         projectRoot,
@@ -784,11 +959,12 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return board ? okBoard(board, "Check updated.") : fail("Check not found.");
+      if (!board) throw notFound("Check not found.");
+      return okBoard(board, "Check updated.");
     }
     case "remove_check": {
       if (!input.boardId || !input.taskId || !input.checkId) {
-        return fail("remove_check requires boardId, taskId, and checkId.");
+        throw invalidInput("remove_check requires boardId, taskId, and checkId.");
       }
       const board = await removeCheckFromTask(
         projectRoot,
@@ -797,11 +973,12 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
         input.checkId,
         eventContext
       );
-      return board ? okBoard(board, "Acceptance criterion removed.") : fail("Check not found on this task.");
+      if (!board) throw notFound("Check not found on this task.");
+      return okBoard(board, "Acceptance criterion removed.");
     }
     case "add_note": {
       if (!input.boardId || !input.taskId || !input.note)
-        return fail("add_note requires boardId, taskId, and note.");
+        throw invalidInput("add_note requires boardId, taskId, and note.");
       const board = await addNoteToTask(
         projectRoot,
         input.boardId,
@@ -812,11 +989,12 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return board ? okBoard(board, "Note added.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      return okBoard(board, "Note added.");
     }
     case "add_link": {
       if (!input.boardId || !input.taskId || !input.url)
-        return fail("add_link requires boardId, taskId, and url.");
+        throw invalidInput("add_link requires boardId, taskId, and url.");
       const board = await addLinkToTask(
         projectRoot,
         input.boardId,
@@ -828,11 +1006,14 @@ async function handleKanbanDetailAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return board ? okBoard(board, "Link added.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      return okBoard(board, "Link added.");
     }
     case "split_atomic": {
       if (!input.boardId || !input.taskId || !input.childTitles?.length) {
-        return fail("split_atomic requires boardId, taskId, and childTitles (at least one).");
+        throw invalidInput(
+          "split_atomic requires boardId, taskId, and childTitles (at least one)."
+        );
       }
       return handleSplitTask(projectRoot, input, { atomic: true }, eventContext);
     }
@@ -862,7 +1043,7 @@ import {
   repairManagedTaskProjection,
   resolveAutoAccept,
   setTaskChain,
-  stripLifecycleIssues,
+  stripLifecycleIssues as stripLifecycleIssues2,
   transferTaskToBoard,
   transitionTask,
   updateTask as updateTask2,
@@ -898,7 +1079,12 @@ function taskInput(input) {
     // neither the create input nor the patch, so the instruction described a
     // capability that did not exist and the attempt was silently dropped.
     ...input.atomic !== void 0 ? { atomic: input.atomic } : {},
-    ...input.childTitles !== void 0 ? { childTaskIds: input.childTitles } : {},
+    // `childTitles` are TITLES of children to create, never ids. They used to
+    // be written straight into `childTaskIds`, recording dangling "ids" such as
+    // "Child 1". add_task creates those children after the parent exists (via
+    // splitTask, the one path that creates child cards); explicit ids of
+    // existing children go through `childTaskIds`.
+    ...input.childTaskIds !== void 0 ? { childTaskIds: input.childTaskIds } : {},
     ...input.checkDescription !== void 0 ? {
       successCriteria: [
         {
@@ -1053,6 +1239,37 @@ async function syncContextTask(ctx, task, options = {}) {
   } catch {
   }
 }
+async function rollbackStartedAssignment(projectRoot, boardId, taskId, prior, leaseId, eventContext) {
+  try {
+    const restored = prior ? await updateTaskAssignment(projectRoot, boardId, taskId, prior, {
+      ...eventContext,
+      expectedLeaseId: leaseId
+    }) : await releaseTaskClaim(
+      projectRoot,
+      boardId,
+      taskId,
+      { clearAssignee: false, expectedLeaseId: leaseId },
+      eventContext
+    );
+    if (restored) return void 0;
+    return `the running assignment (lease ${leaseId}) could not be rolled back \u2014 the lease changed or the task is gone; release it with release_task.`;
+  } catch (err) {
+    return `the running assignment (lease ${leaseId}) could not be rolled back (${err instanceof Error ? err.message : String(err)}); release it with release_task.`;
+  }
+}
+function joinCommitted(...notes) {
+  const present = notes.filter((note) => Boolean(note));
+  return present.length ? present.join(" ") : void 0;
+}
+async function missingOrFenced(projectRoot, boardId, taskId, expectedLeaseId, what) {
+  if (expectedLeaseId !== void 0 && await getTask(projectRoot, boardId, taskId)) {
+    throw conflict(
+      `${what}: the task's current lease no longer matches expectedLeaseId "${expectedLeaseId}" (it was recovered or reassigned). Nothing was written.`,
+      { retryable: false }
+    );
+  }
+  throw notFound(`${what}: task not found.`);
+}
 async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
   const eventContext = {
     sessionId: ctx.eventSessionId?.() ?? ctx.session?.id ?? "default-session",
@@ -1060,21 +1277,57 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
   };
   switch (input.action) {
     case "add_task": {
-      if (!input.boardId || !input.title) return fail("add_task requires boardId and title.");
+      if (!input.boardId || !input.title)
+        throw invalidInput("add_task requires boardId and title.");
+      const childTitles = input.childTitles;
+      if (childTitles !== void 0 && (!Array.isArray(childTitles) || childTitles.some((title) => typeof title !== "string" || !title.trim()))) {
+        throw invalidInput("add_task childTitles must be non-blank strings.", "childTitles");
+      }
       const result = await addTask2(projectRoot, input.boardId, taskInput(input), eventContext);
-      if (!result) return fail("Board not found.");
+      if (!result) throw notFound("Board not found.");
+      if (childTitles?.length) {
+        let split;
+        try {
+          split = await handleSplitTask(
+            projectRoot,
+            { action: "split_task", boardId: result.board.id, taskId: result.task.id, childTitles },
+            {},
+            eventContext
+          );
+        } catch (err) {
+          const removed = await removeTask(
+            projectRoot,
+            result.board.id,
+            result.task.id,
+            eventContext
+          ).catch(() => null);
+          throw toKanbanToolError(
+            err,
+            removed ? void 0 : `task ${result.task.id} was created but its children were not, and removing it failed; delete it with delete_task.`
+          );
+        }
+        const parent = split.task ?? result.task;
+        await syncContextTask(ctx, parent);
+        return {
+          ok: true,
+          message: `Task added with ${split.children?.length ?? 0} child task(s).${atomicityNudge(parent)}`,
+          board: split.board ?? result.board,
+          task: parent,
+          children: split.children
+        };
+      }
       await syncContextTask(ctx, result.task);
       return okTask(result.board, result.task, `Task added.${atomicityNudge(result.task)}`);
     }
     case "split_task": {
       if (!input.boardId || !input.taskId || !input.childTitles?.length) {
-        return fail("split_task requires boardId, taskId, and childTitles.");
+        throw invalidInput("split_task requires boardId, taskId, and childTitles.");
       }
       return handleSplitTask(projectRoot, input, {}, eventContext);
     }
     case "merge_tasks": {
       if (!input.boardId || !input.taskIds?.length || !input.title) {
-        return fail("merge_tasks requires boardId, taskIds, and title.");
+        throw invalidInput("merge_tasks requires boardId, taskIds, and title.");
       }
       const result = await mergeTasks(
         projectRoot,
@@ -1089,11 +1342,12 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return result ? okTask(result.board, result.task, "Tasks merged.") : fail("Board or task not found.");
+      if (!result) throw notFound("Board or task not found.");
+      return okTask(result.board, result.task, "Tasks merged.");
     }
     case "copy_task": {
       if (!input.boardId || !input.taskId || !input.targetBoardId) {
-        return fail("copy_task requires boardId, taskId, and targetBoardId.");
+        throw invalidInput("copy_task requires boardId, taskId, and targetBoardId.");
       }
       const result = await copyTaskToBoard(
         projectRoot,
@@ -1108,11 +1362,12 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
           eventContext
         }
       );
-      return result ? okTask(result.targetBoard, result.task, "Task copied to target board.") : fail("Board or task not found.");
+      if (!result) throw notFound("Board or task not found.");
+      return okTask(result.targetBoard, result.task, "Task copied to target board.");
     }
     case "transfer_task": {
       if (!input.boardId || !input.taskId || !input.targetBoardId) {
-        return fail("transfer_task requires boardId, taskId, and targetBoardId.");
+        throw invalidInput("transfer_task requires boardId, taskId, and targetBoardId.");
       }
       const result = await transferTaskToBoard(
         projectRoot,
@@ -1127,23 +1382,27 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
           eventContext
         }
       );
-      return result ? okTask(result.targetBoard, result.task, "Task transferred to target board.") : fail("Board or task not found.");
+      if (!result) throw notFound("Board or task not found.");
+      return okTask(result.targetBoard, result.task, "Task transferred to target board.");
     }
     case "get_task": {
-      if (!input.boardId || !input.taskId) return fail("get_task requires boardId and taskId.");
+      if (!input.boardId || !input.taskId)
+        throw invalidInput("get_task requires boardId and taskId.");
       const task = await getTask(projectRoot, input.boardId, input.taskId);
-      return task ? { ok: true, message: "Task loaded.", task } : fail("Task not found.");
+      if (!task) throw notFound("Task not found.");
+      return { ok: true, message: "Task loaded.", task };
     }
     case "start_task": {
       if (!input.boardId || !input.taskId || !input.author || !input.transitionComment) {
-        return fail("start_task requires boardId, taskId, author, and transitionComment.");
+        throw invalidInput("start_task requires boardId, taskId, author, and transitionComment.");
       }
       let board = await getBoard3(projectRoot, input.boardId);
-      let task = board?.tasks.find((candidate) => candidate.id === input.taskId);
-      if (!board || !task) return fail("Board or task not found.");
+      if (!board) throw notFound("Board not found.");
+      let task = resolveTaskRef(board, input.taskId);
+      if (!task) throw notFound("Task not found.");
       const readiness = evaluateContractGraphReadiness(board, task.id);
       if (!readiness.ready) {
-        return fail(
+        throw refused(
           `Task is not implementation-ready: ${readiness.issues.map((issue) => issue.message).join(" | ")}`
         );
       }
@@ -1165,7 +1424,7 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
           },
           eventContext
         );
-        if (!assigned) return fail("Task assignment could not be started.");
+        if (!assigned) throw notFound("Task assignment could not be started: task not found.");
         const started = await updateTask2(
           projectRoot,
           board.id,
@@ -1184,6 +1443,7 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         );
       }
       let stage = task.lifecycle?.currentStage;
+      let movedToTodo = false;
       if (stage === "backlog") {
         const moved = await transitionTask(projectRoot, board.id, task.id, {
           to: "todo",
@@ -1191,7 +1451,8 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
           actor: input.author,
           comment: input.transitionComment
         });
-        if (!moved) return fail("Task could not enter Todo.");
+        if (!moved) throw notFound("Task could not enter Todo: board or task not found.");
+        movedToTodo = true;
         board = moved.board;
         task = moved.task;
         stage = task.lifecycle?.currentStage;
@@ -1199,6 +1460,8 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
       if (stage === "todo" || stage === "review") {
         const now = /* @__PURE__ */ new Date();
         const leaseId = input.leaseId ?? randomUUID2();
+        const priorAssignment = task.assignment ? { ...task.assignment } : void 0;
+        const todoNote = movedToTodo ? "the card was moved Backlog \u2192 Todo." : void 0;
         const assigned = await updateTaskAssignment(
           projectRoot,
           board.id,
@@ -1215,24 +1478,56 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
           },
           eventContext
         );
-        if (!assigned) return fail("Task assignment could not be started.");
-        const moved = await transitionTask(projectRoot, board.id, task.id, {
-          to: "running",
-          sessionId: eventContext.sessionId,
-          actor: input.author,
-          comment: input.transitionComment
-        });
-        if (!moved) return fail("Task could not enter Running.");
+        if (!assigned) {
+          throw notFound("Task assignment could not be started: task not found.", {
+            committed: todoNote
+          });
+        }
+        const startedTaskId = task.id;
+        const startedBoardId = board.id;
+        let moved;
+        try {
+          moved = await transitionTask(projectRoot, startedBoardId, startedTaskId, {
+            to: "running",
+            sessionId: eventContext.sessionId,
+            actor: input.author,
+            comment: input.transitionComment
+          });
+        } catch (err) {
+          const rollback = await rollbackStartedAssignment(
+            projectRoot,
+            startedBoardId,
+            startedTaskId,
+            priorAssignment,
+            leaseId,
+            eventContext
+          );
+          throw toKanbanToolError(err, joinCommitted(todoNote, rollback));
+        }
+        if (!moved) {
+          const rollback = await rollbackStartedAssignment(
+            projectRoot,
+            startedBoardId,
+            startedTaskId,
+            priorAssignment,
+            leaseId,
+            eventContext
+          );
+          throw conflict("Task could not enter Running: the board or task disappeared.", {
+            committed: joinCommitted(todoNote, rollback)
+          });
+        }
         board = moved.board;
         task = moved.task;
         stage = task.lifecycle?.currentStage;
       }
       if (stage !== "running" || task.assignment?.status !== "running") {
-        return fail(
-          `start_task only accepts Backlog, Todo, Review repair, or live Running cards (current: ${stage ?? "unknown"}).`
+        throw refused(
+          `start_task only accepts Backlog, Todo, Review repair, or live Running cards (current: ${stage ?? "unknown"}).`,
+          { committed: movedToTodo ? "the card was moved Backlog \u2192 Todo." : void 0 }
         );
       }
-      ctx.setCurrentKanbanTask(task.id, board.id);
+      ctx.setCurrentKanbanTask?.(task.id, board.id);
       await syncContextTask(ctx, task);
       return okTask(
         board,
@@ -1241,7 +1536,8 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
       );
     }
     case "update_task": {
-      if (!input.boardId || !input.taskId) return fail("update_task requires boardId and taskId.");
+      if (!input.boardId || !input.taskId)
+        throw invalidInput("update_task requires boardId and taskId.");
       const board = await updateTask2(
         projectRoot,
         input.boardId,
@@ -1249,20 +1545,23 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         taskPatch(input),
         eventContext
       );
-      if (board) {
-        await syncContextTask(
-          ctx,
-          board.tasks.find((t) => t.id === input.taskId)
-        );
-      }
-      return board ? okBoard(board, "Task updated.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      await syncContextTask(ctx, resolveTaskRef(board, input.taskId));
+      return okBoard(board, "Task updated.");
     }
     case "transition_task": {
       if (!input.boardId || !input.taskId || !input.lifecycleStage || !input.author || !input.transitionComment) {
-        return fail(
+        throw invalidInput(
           "transition_task requires boardId, taskId, lifecycleStage, author, and transitionComment."
         );
       }
+      if (input.tickChecks?.length && input.lifecycleStage !== "done") {
+        throw invalidInput(
+          `tickChecks only applies to transition_task with lifecycleStage "done" (got "${input.lifecycleStage}"). Tick criteria with update_check instead.`,
+          "tickChecks"
+        );
+      }
+      let preGateSaved = false;
       if (input.lifecycleStage === "done") {
         const boardBefore = await getBoard3(projectRoot, input.boardId);
         const taskBefore = boardBefore ? await getTask(projectRoot, input.boardId, input.taskId) : null;
@@ -1270,45 +1569,52 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
           const preGate = await verifyTaskCompletion2(projectRoot, input.boardId, taskBefore.id, {
             persist: false
           });
-          await updateTask2(
-            projectRoot,
-            input.boardId,
-            taskBefore.id,
-            {
-              verificationReport: preGate.report,
-              successCriteria: preGate.task.successCriteria
-            },
-            eventContext
+          preGateSaved = Boolean(
+            await updateTask2(
+              projectRoot,
+              input.boardId,
+              taskBefore.id,
+              {
+                verificationReport: preGate.report,
+                successCriteria: preGate.task.successCriteria
+              },
+              eventContext
+            )
           );
         }
       }
-      const result = await transitionTask(projectRoot, input.boardId, input.taskId, {
-        to: input.lifecycleStage,
-        sessionId: eventContext.sessionId,
-        actor: input.author,
-        comment: input.transitionComment,
-        ...input.transitionAction !== void 0 ? { action: input.transitionAction } : {},
-        ...input.tickChecks !== void 0 ? { tickChecks: input.tickChecks } : {},
-        ...input.attachmentUrl !== void 0 ? {
-          attachment: {
-            url: input.attachmentUrl,
-            type: input.attachmentType ?? "url",
-            ...input.attachmentTitle !== void 0 ? { title: input.attachmentTitle } : {}
-          }
-        } : {},
-        patch: taskPatch(input)
-      });
-      if (result && input.lifecycleStage === "done" && result.task.verificationReport) {
-        recordKanbanVerificationEvidence(ctx, result.task.verificationReport);
+      const preGateNote = preGateSaved ? "the pre-gate verification report was saved on the card (evidence only; the card did not move)." : void 0;
+      let result;
+      try {
+        result = await transitionTask(projectRoot, input.boardId, input.taskId, {
+          to: input.lifecycleStage,
+          sessionId: eventContext.sessionId,
+          actor: input.author,
+          comment: input.transitionComment,
+          ...input.transitionAction !== void 0 ? { action: input.transitionAction } : {},
+          ...input.tickChecks !== void 0 ? { tickChecks: input.tickChecks } : {},
+          ...input.attachmentUrl !== void 0 ? {
+            attachment: {
+              url: input.attachmentUrl,
+              type: input.attachmentType ?? "url",
+              ...input.attachmentTitle !== void 0 ? { title: input.attachmentTitle } : {}
+            }
+          } : {},
+          patch: taskPatch(input)
+        });
+      } catch (err) {
+        throw toKanbanToolError(err, preGateNote);
       }
-      if (result?.task) {
-        await syncContextTask(ctx, result.task);
+      if (!result) throw notFound("Board or task not found.", { committed: preGateNote });
+      if (input.lifecycleStage === "done" && result.task.verificationReport) {
+        recordKanbanVerificationEvidence(ctx, result.task.verificationReport);
       }
-      return result ? okTask(result.board, result.task, `Task advanced to ${result.transition.to}.`) : fail("Board or task not found.");
+      await syncContextTask(ctx, result.task);
+      return okTask(result.board, result.task, `Task advanced to ${result.transition.to}.`);
     }
     case "repair_managed_projection": {
       if (!input.boardId || !input.taskId || !input.author || !input.transitionComment) {
-        return fail(
+        throw invalidInput(
           "repair_managed_projection requires boardId, taskId, author, and transitionComment."
         );
       }
@@ -1319,15 +1625,16 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
       if (result?.task) {
         await syncContextTask(ctx, result.task);
       }
-      return result ? okTask(
+      if (!result) throw notFound("Board or task not found.");
+      return okTask(
         result.board,
         result.task,
         "Managed card projection repaired from lifecycle history."
-      ) : fail("Board or task not found.");
+      );
     }
     case "move_task": {
       if (!input.boardId || !input.taskId || !input.targetColumnId) {
-        return fail("move_task requires boardId, taskId, and targetColumnId.");
+        throw invalidInput("move_task requires boardId, taskId, and targetColumnId.");
       }
       const board = await moveTask(
         projectRoot,
@@ -1337,30 +1644,28 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         input.order,
         eventContext
       );
-      if (board) {
-        await syncContextTask(
-          ctx,
-          board.tasks.find((t) => t.id === input.taskId)
-        );
-      }
-      return board ? okBoard(board, "Task moved.") : fail("Move failed.");
+      if (!board) throw notFound("Move failed: board or task not found.");
+      await syncContextTask(ctx, resolveTaskRef(board, input.taskId));
+      return okBoard(board, "Task moved.");
     }
     case "delete_task": {
-      if (!input.boardId || !input.taskId) return fail("delete_task requires boardId and taskId.");
+      if (!input.boardId || !input.taskId)
+        throw invalidInput("delete_task requires boardId and taskId.");
       const boardBefore = await getBoard3(projectRoot, input.boardId);
-      const taskToDelete = boardBefore?.tasks.find((t) => t.id === input.taskId);
+      const taskToDelete = boardBefore ? resolveTaskRef(boardBefore, input.taskId) : void 0;
       const board = await removeTask(projectRoot, input.boardId, input.taskId, eventContext);
-      if (board && ctx.currentKanbanTaskId === input.taskId) {
+      if (board && taskToDelete && ctx.currentKanbanTaskId === taskToDelete.id) {
         ctx.setCurrentKanbanTask?.(void 0, ctx.currentKanbanBoardId);
       }
       if (board && taskToDelete) {
         await syncContextTask(ctx, taskToDelete, { remove: true });
       }
-      return board ? okBoard(board, "Task deleted.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      return okBoard(board, "Task deleted.");
     }
     case "set_chain": {
       if (!input.boardId || !input.taskIds?.length) {
-        return fail("set_chain requires boardId and taskIds.");
+        throw invalidInput("set_chain requires boardId and taskIds.");
       }
       const result = await setTaskChain(
         projectRoot,
@@ -1372,28 +1677,30 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return result ? {
+      if (!result) throw notFound("Board or task not found.");
+      return {
         ok: true,
         message: `Chain set: ${result.chainId}`,
         board: result.board,
         chain: result.tasks
-      } : fail("Board or task not found.");
+      };
     }
     case "get_chain": {
       if (!input.boardId || !(input.taskId || input.chainId)) {
-        return fail("get_chain requires boardId and taskId or chainId.");
+        throw invalidInput("get_chain requires boardId and taskId or chainId.");
       }
       const result = await getTaskChain(
         projectRoot,
         input.boardId,
         input.taskId ?? input.chainId ?? ""
       );
-      return result ? {
+      if (!result) throw notFound("Chain not found.");
+      return {
         ok: true,
         message: `Chain loaded: ${result.chainId}`,
         board: result.board,
         chain: result.tasks
-      } : fail("Chain not found.");
+      };
     }
     case "claim_task": {
       const result = await claimReadyTask(
@@ -1406,11 +1713,14 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return result ? okTask(result.board, result.task, "Task claimed.") : fail("No ready kanban task matched the claim.");
+      if (!result) {
+        return { ok: true, claimed: false, message: "No ready kanban task matched the claim." };
+      }
+      return { ...okTask(result.board, result.task, "Task claimed."), claimed: true };
     }
     case "release_task": {
       if (!input.boardId || !input.taskId) {
-        return fail("release_task requires boardId and taskId.");
+        throw invalidInput("release_task requires boardId and taskId.");
       }
       const board = await releaseTaskClaim(
         projectRoot,
@@ -1423,10 +1733,12 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return board ? okBoard(board, "Task claim released.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      return okBoard(board, "Task claim released.");
     }
     case "assign_task": {
-      if (!input.boardId || !input.taskId) return fail("assign_task requires boardId and taskId.");
+      if (!input.boardId || !input.taskId)
+        throw invalidInput("assign_task requires boardId and taskId.");
       const board = await assignTask(
         projectRoot,
         input.boardId,
@@ -1434,11 +1746,12 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         assignmentInput(input),
         eventContext
       );
-      return board ? okBoard(board, "Task assigned.") : fail("Task not found.");
+      if (!board) throw notFound("Task not found.");
+      return okBoard(board, "Task assigned.");
     }
     case "mark_assignment": {
       if (!input.boardId || !input.taskId)
-        return fail("mark_assignment requires boardId and taskId.");
+        throw invalidInput("mark_assignment requires boardId and taskId.");
       const assignmentStatus = input.assignmentStatus ?? (input.status === "completed" ? "completed" : input.error ? "failed" : void 0);
       const board = await updateTaskAssignment(
         projectRoot,
@@ -1463,7 +1776,15 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
           ...input.expectedLeaseId !== void 0 ? { expectedLeaseId: input.expectedLeaseId } : {}
         }
       );
-      if (!board) return fail("Task not found.");
+      if (!board) {
+        return missingOrFenced(
+          projectRoot,
+          input.boardId,
+          input.taskId,
+          input.expectedLeaseId,
+          "Assignment not updated"
+        );
+      }
       if (assignmentStatus === "completed" && board.lifecycle?.mode !== "managed") {
         const envGate = readEnvGateEnforcement();
         const finalized = await finalizeTaskCompletion(projectRoot, board.id, input.taskId, {
@@ -1503,7 +1824,7 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
             });
           } catch (err) {
             lifecycleWarnings.push(
-              `Lifecycle transition to Running deferred: ${stripLifecycleIssues(err instanceof Error ? err.message : String(err))}`
+              `Lifecycle transition to Running deferred: ${stripLifecycleIssues2(err instanceof Error ? err.message : String(err))}`
             );
           }
         }
@@ -1526,14 +1847,16 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
             });
           } catch (err) {
             lifecycleWarnings.push(
-              `Lifecycle transition to Review failed: ${stripLifecycleIssues(err instanceof Error ? err.message : String(err))}`
+              `Lifecycle transition to Review failed: ${stripLifecycleIssues2(err instanceof Error ? err.message : String(err))}`
             );
           }
           if (transitionResult) {
             const hasCriteria = (transitionResult.task.successCriteria?.length ?? 0) > 0 || transitionResult.task.atomic === true;
             if (hasCriteria) {
               try {
-                const verResult = await verifyTaskCompletion2(projectRoot, board.id, input.taskId);
+                const verResult = await verifyTaskCompletion2(projectRoot, board.id, input.taskId, {
+                  persist: false
+                });
                 if (verResult.report) {
                   recordKanbanVerificationEvidence(ctx, verResult.report);
                 }
@@ -1603,7 +1926,7 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
     }
     case "heartbeat_assignment": {
       if (!input.boardId || !input.taskId) {
-        return fail("heartbeat_assignment requires boardId and taskId.");
+        throw invalidInput("heartbeat_assignment requires boardId and taskId.");
       }
       const board = await heartbeatTaskAssignment(
         projectRoot,
@@ -1616,10 +1939,19 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return board ? okBoard(board, "Assignment heartbeat updated.") : fail("Task assignment not found.");
+      if (!board) {
+        return missingOrFenced(
+          projectRoot,
+          input.boardId,
+          input.taskId,
+          input.expectedLeaseId,
+          "Heartbeat not recorded"
+        );
+      }
+      return okBoard(board, "Assignment heartbeat updated.");
     }
     case "recover_stale": {
-      if (!input.boardId) return fail("recover_stale requires boardId.");
+      if (!input.boardId) throw invalidInput("recover_stale requires boardId.");
       const policyFields = [
         input.recoveryPolicyFailOnCostCeiling !== void 0,
         input.recoveryPolicyReleaseOnFailureKinds !== void 0,
@@ -1651,12 +1983,16 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
         },
         eventContext
       );
-      return result ? {
+      if (!result) {
+        if (!await getBoard3(projectRoot, input.boardId)) throw notFound("Board not found.");
+        return { ok: true, message: "No stale assignment matched.", recoveredTasks: [] };
+      }
+      return {
         ok: true,
         message: `Recovered ${result.tasks.length} stale assignment(s).`,
         board: result.board,
         recoveredTasks: result.tasks
-      } : { ok: true, message: "No stale assignment matched.", recoveredTasks: [] };
+      };
     }
     default:
       return void 0;
@@ -1665,8 +2001,29 @@ async function handleKanbanLifecycleAction(projectRoot, input, ctx) {
 
 // src/kanban-presence.ts
 import { touchKanbanPresence } from "@wrongstack/kanban";
+
+// src/kanban-tool-types.ts
+var KANBAN_READ_ONLY_ACTIONS = [
+  "list_boards",
+  "get_board",
+  "export_markdown",
+  "export_task_graph",
+  "search_tasks",
+  "ready_tasks",
+  "snapshot",
+  "workbench",
+  "get_task",
+  "get_chain",
+  "events",
+  "queue_health",
+  "get_contract_graph"
+];
+
+// src/kanban-presence.ts
+var READ_ONLY = new Set(KANBAN_READ_ONLY_ACTIONS);
 function createKanbanPresenceWrapper(projectRoot, input, ctx) {
   return async (result) => {
+    if (READ_ONLY.has(input.action)) return result;
     const boardId = result.board?.id ?? input.boardId;
     if (!result.ok || !boardId || !ctx.session?.id || !ctx.agentId) return result;
     try {
@@ -1677,7 +2034,7 @@ function createKanbanPresenceWrapper(projectRoot, input, ctx) {
         taskId: input.taskId ?? result.task?.id,
         runTaskId: input.runTaskId
       });
-      return board ? { ...result, board } : result;
+      return board && result.board ? { ...result, board } : result;
     } catch {
       return result;
     }
@@ -1691,40 +2048,86 @@ var KANBAN_FULL_BOARD_ACTIONS = /* @__PURE__ */ new Set([
   "export_markdown",
   "export_task_graph"
 ]);
+var KANBAN_TRANSCRIPT_ITEM_CAP = 100;
+var KANBAN_LIST_FIELDS = [
+  { field: "events", tail: true },
+  { field: "tasks" },
+  { field: "boards" },
+  { field: "recoveredTasks" },
+  { field: "chain" },
+  { field: "children" }
+];
+var KANBAN_OBJECT_TRANSCRIPT_BYTE_CAP = 65536;
+var KANBAN_PRIMARY_OBJECT_TRANSCRIPT_BYTE_CAP = 262144;
+var KANBAN_OBJECT_FIELDS = [
+  { field: "snapshot", primaryFor: "snapshot" },
+  { field: "workbench", primaryFor: "workbench" },
+  { field: "taskGraph", primaryFor: "export_task_graph" }
+];
+function byteLength(value) {
+  try {
+    return Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+  } catch {
+    return 0;
+  }
+}
+function objectSummary(field, value) {
+  const summary = {};
+  if (value && typeof value === "object") {
+    for (const [key, entry] of Object.entries(value)) {
+      if (Array.isArray(entry)) summary[`${key}Count`] = entry.length;
+      else if (typeof entry === "number" || typeof entry === "string") summary[key] = entry;
+    }
+    if (field === "workbench") {
+      const totals = value.totals;
+      if (totals && typeof totals === "object") summary["totals"] = totals;
+    }
+  }
+  return summary;
+}
 function serializeKanbanOutput(output, input) {
   const action = input && typeof input === "object" ? input.action : void 0;
+  const actionName = typeof action === "string" ? action : "";
+  const compact = { ...output };
+  const truncated = { ...output.truncated };
   const board = output.board;
-  if (board) {
-    const keepFull = typeof action === "string" && KANBAN_FULL_BOARD_ACTIONS.has(action);
-    let boardBytes = 0;
-    if (!keepFull) {
-      try {
-        boardBytes = Buffer.byteLength(JSON.stringify(board), "utf8");
-      } catch {
-        boardBytes = 0;
-      }
-    }
-    if (!keepFull && boardBytes > KANBAN_BOARD_TRANSCRIPT_BYTE_CAP) {
+  if (board && !KANBAN_FULL_BOARD_ACTIONS.has(actionName)) {
+    const boardBytes = byteLength(board);
+    if (boardBytes > KANBAN_BOARD_TRANSCRIPT_BYTE_CAP) {
       const columns = {};
       for (const column of board.columns) {
         columns[column.title || column.id] = board.tasks.filter(
           (task) => task.columnId === column.id
         ).length;
       }
-      const compact = {
-        ...output,
-        board: {
-          id: board.id,
-          title: board.title,
-          columns,
-          totalTasks: board.tasks.length,
-          note: `Full board (${boardBytes} bytes) omitted from the transcript; use get_board to load it.`
-        }
+      compact["board"] = {
+        id: board.id,
+        title: board.title,
+        columns,
+        totalTasks: board.tasks.length,
+        note: `Full board (${boardBytes} bytes) omitted from the transcript; use get_board to load it.`
       };
-      return JSON.stringify(compact, null, 2);
     }
   }
-  return JSON.stringify(output, null, 2);
+  for (const { field, tail } of KANBAN_LIST_FIELDS) {
+    const list = output[field];
+    if (!Array.isArray(list) || list.length <= KANBAN_TRANSCRIPT_ITEM_CAP) continue;
+    compact[field] = tail ? list.slice(-KANBAN_TRANSCRIPT_ITEM_CAP) : list.slice(0, KANBAN_TRANSCRIPT_ITEM_CAP);
+    truncated[field] = { shown: KANBAN_TRANSCRIPT_ITEM_CAP, total: list.length };
+  }
+  for (const { field, primaryFor } of KANBAN_OBJECT_FIELDS) {
+    const value = output[field];
+    if (value === void 0 || value === null) continue;
+    const cap = actionName === primaryFor ? KANBAN_PRIMARY_OBJECT_TRANSCRIPT_BYTE_CAP : KANBAN_OBJECT_TRANSCRIPT_BYTE_CAP;
+    const bytes = byteLength(value);
+    if (bytes <= cap) continue;
+    compact[field] = {
+      ...objectSummary(field, value),
+      note: `${field} (${bytes} bytes) omitted from the transcript; narrow it with boardId, query, or limit.`
+    };
+  }
+  if (Object.keys(truncated).length > 0) compact["truncated"] = truncated;
+  return JSON.stringify(compact, null, 2);
 }
 
 // src/kanban-tool-schema.ts
@@ -1800,10 +2203,6 @@ var KANBAN_INPUT_SCHEMA = {
     taskId: { type: "string" },
     taskIds: { type: "array", items: { type: "string" } },
     chainId: { type: "string" },
-    fromNodeId: { type: "string" },
-    toNodeId: { type: "string" },
-    baseline: { oneOf: [{ type: "string" }, { type: "number" }] },
-    threshold: { oneOf: [{ type: "string" }, { type: "number" }] },
     columnId: { type: "string" },
     targetBoardId: { type: "string" },
     targetColumnId: { type: "string" },
@@ -1812,6 +2211,10 @@ var KANBAN_INPUT_SCHEMA = {
     dueDate: { type: "string" },
     tags: { type: "array", items: { type: "string" } },
     labels: { type: "array", items: { type: "string" } },
+    label: {
+      type: "string",
+      description: "search_tasks / ready_tasks / snapshot: filter by a single label (takes precedence over labels[0])."
+    },
     priority: { type: "string", enum: ["critical", "high", "medium", "low"] },
     taskType: {
       type: "string",
@@ -1832,7 +2235,10 @@ var KANBAN_INPUT_SCHEMA = {
     },
     order: { type: "number" },
     query: { type: "string" },
-    limit: { type: "number" },
+    limit: {
+      type: "number",
+      description: "ready_tasks: max results. workbench: per-lane and alert limit. events: return only the most recent N events."
+    },
     agentId: { type: "string" },
     name: { type: "string" },
     role: { type: "string" },
@@ -1873,7 +2279,7 @@ var KANBAN_INPUT_SCHEMA = {
         },
         required: ["checkId", "checkStatus"]
       },
-      description: "`transition_task` (to=done only): flip one or more manual criteria to `passed` before the gate fires. Read ids from kanban get_task. Non-manual criteria are refused."
+      description: '`transition_task` with lifecycleStage "done" only (rejected for any other stage): flip one or more manual criteria before the gate fires. Read ids from kanban get_task. Non-manual criteria are refused.'
     },
     attachmentUrl: { type: "string" },
     attachmentTitle: { type: "string" },
@@ -2028,7 +2434,6 @@ var KANBAN_INPUT_SCHEMA = {
     includeCompletedTasks: { type: "boolean" },
     preserveAssignment: { type: "boolean" },
     preserveDependencies: { type: "boolean" },
-    moveTasksToColumnId: { type: "string" },
     atomicityMode: { type: "string", enum: ["off", "assess", "enforce"] },
     atomicityDecomposition: { type: "string", enum: ["auto", "propose"] },
     gateEnforcement: {
@@ -2071,51 +2476,63 @@ var kanbanTool = {
   inputSchema: KANBAN_INPUT_SCHEMA,
   async execute(input, ctx, _opts) {
     const signal = _opts?.signal ?? ctx.signal ?? new AbortController().signal;
-    if (signal.aborted) return fail("Operation aborted.");
+    if (signal.aborted) {
+      throw new KanbanToolError("ABORTED", "Operation aborted before any Kanban work ran.");
+    }
     if (!input || typeof input !== "object" || typeof input.action !== "string" || !input.action.trim()) {
-      return fail("kanban: action is required and must be a non-empty string.");
+      throw invalidInput("kanban: action is required and must be a non-empty string.", "action");
     }
     const normalizedInput = {
       ...input,
       action: input.action.trim()
     };
     const projectRoot = ctx.projectRoot;
-    if (!projectRoot) return fail("No project root is available.");
+    if (!projectRoot) {
+      throw new KanbanToolError("UNAVAILABLE", "No project root is available.", {
+        retryable: false
+      });
+    }
     const withPresence = createKanbanPresenceWrapper(projectRoot, normalizedInput, ctx);
+    let result;
     try {
-      const result = await (async () => {
-        const decompositionResult = await handleKanbanDecompositionAction(projectRoot, normalizedInput, ctx);
-        if (decompositionResult !== void 0) return decompositionResult;
-        const boardResult = await handleKanbanBoardAction(projectRoot, normalizedInput, ctx);
-        if (boardResult !== void 0) return boardResult;
-        const lifecycleResult = await handleKanbanLifecycleAction(projectRoot, normalizedInput, ctx);
-        if (lifecycleResult !== void 0) return lifecycleResult;
-        const contractResult = await handleKanbanContractAction(
-          projectRoot,
-          normalizedInput,
-          normalizedInput.author ?? normalizedInput.agentId,
-          ctx.eventSessionId?.() ?? ctx.session?.id ?? "default-session"
-        );
-        if (contractResult !== void 0) return contractResult;
-        const detailResult = await handleKanbanDetailAction(projectRoot, normalizedInput, ctx);
-        if (detailResult !== void 0) return detailResult;
-        return fail(`Unknown kanban action: ${normalizedInput.action}`);
-      })();
-      if (signal.aborted) return fail("Operation aborted.");
-      return await withPresence(result);
+      result = await dispatchKanbanAction(projectRoot, normalizedInput, ctx);
     } catch (err) {
-      return fail(stripLifecycleIssues2(err instanceof Error ? err.message : String(err)));
+      throw toKanbanToolError(err);
     }
+    if (signal.aborted) return result;
+    return await withPresence(result);
   },
   serialize(output, input) {
     return serializeKanbanOutput(output, input);
   }
 };
+async function dispatchKanbanAction(projectRoot, input, ctx) {
+  const decompositionResult = await handleKanbanDecompositionAction(projectRoot, input, ctx);
+  if (decompositionResult !== void 0) return decompositionResult;
+  const boardResult = await handleKanbanBoardAction(projectRoot, input, ctx);
+  if (boardResult !== void 0) return boardResult;
+  const lifecycleResult = await handleKanbanLifecycleAction(projectRoot, input, ctx);
+  if (lifecycleResult !== void 0) return lifecycleResult;
+  const contractResult = await handleKanbanContractAction(
+    projectRoot,
+    input,
+    input.author ?? input.agentId,
+    ctx.eventSessionId?.() ?? ctx.session?.id ?? "default-session"
+  );
+  if (contractResult !== void 0) return contractResult;
+  const detailResult = await handleKanbanDetailAction(projectRoot, input, ctx);
+  if (detailResult !== void 0) return detailResult;
+  throw invalidInput(`Unknown kanban action: ${input.action}`, "action");
+}
 
 export {
+  KanbanToolError,
+  KanbanInputError,
+  isKanbanToolFailure,
   kanbanEvidenceKey,
   kanbanEvidencePointer,
   recordKanbanVerificationEvidence,
+  KANBAN_READ_ONLY_ACTIONS,
   kanbanTool
 };
-//# sourceMappingURL=chunk-2NTHMZV3.js.map
+//# sourceMappingURL=chunk-VMJY6FYJ.js.map