trekoon 0.4.4 → 0.4.6

package/src/commands/epic.ts

@@ -462,10 +462,10 @@ function parseExpandTaskSpecs(rawSpecs: readonly string[]): { specs: CompactTask
       };
     }
 
-    if (parsed.fields.length !== 4) {
+    if (parsed.fields.length !== 3 && parsed.fields.length !== 4) {
       return {
         specs: [],
-        error: failBatchSpec("epic.expand", `Task specs must use <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}.`, {
+        error: failBatchSpec("epic.expand", `Task specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}.`, {
           option: "task",
           index,
           rawSpec,
@@ -558,10 +558,10 @@ function parseExpandSubtaskSpecs(rawSpecs: readonly string[]): { specs: CompactS
       };
     }
 
-    if (parsed.fields.length !== 5) {
+    if (parsed.fields.length !== 4 && parsed.fields.length !== 5) {
       return {
         specs: [],
-        error: failBatchSpec("epic.expand", `Subtask specs must use <parent-ref>|<temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}.`, {
+        error: failBatchSpec("epic.expand", `Subtask specs must use <parent-ref>|<temp-key>|<title>|<description> or <parent-ref>|<temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}.`, {
           option: "subtask",
           index,
           rawSpec,

package/src/commands/help.ts

@@ -59,7 +59,8 @@ const QUICKSTART_HELP = [
   "  1. trekoon --toon session",
   "  2. Stop if diagnostics report recoveryRequired or a tracked/ignored mismatch",
   "  3. If behind: trekoon --toon sync pull --from main",
-  "  4. Claim work: trekoon --toon task update <task-id> --status in_progress",
+  "  4. Claim work: trekoon --toon task claim <task-id> --owner <TODO_OWNER>",
+  "     (atomic CAS; safe for parallel agents. Check data.claimed.)",
   "  5. Finish: trekoon --toon task done <task-id>",
   "",
   "Manual bootstrap (if you need step-by-step):",
@@ -121,8 +122,10 @@ const EPIC_HELP = [
   "",
   "Expand:",
   "  trekoon --toon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
-  "  --task <temp-key>|<title>|<description>|<status>",
-  `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>  (${"@"}<temp-key> for new parents)`,
+  "  --task <temp-key>|<title>|<description>            (status defaults to todo)",
+  "  --task <temp-key>|<title>|<description>|<status>   (explicit status)",
+  `  --subtask <parent-ref>|<temp-key>|<title>|<description>            (status defaults to todo) (${"@"}<temp-key> for new parents)`,
+  `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>   (explicit status)`,
   `  --dep <source-ref>|<depends-on-ref>  (refs can be IDs or ${"@"}<temp-key>)`,
   "  Escapes in compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
@@ -182,7 +185,8 @@ const TASK_HELP = [
   "",
   "Create-many:",
   "  trekoon task create-many --epic <epic-id> --task <spec> [--task <spec> ...]",
-  "  --task <temp-key>|<title>|<description>|<status>",
+  "  --task <temp-key>|<title>|<description>            (status defaults to todo)",
+  "  --task <temp-key>|<title>|<description>|<status>   (explicit status)",
   "  Multiple --task flags are applied in order.",
   "  Escapes in compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
@@ -239,7 +243,8 @@ const SUBTASK_HELP = [
   "",
   "Create-many:",
   "  trekoon subtask create-many [<task-id>] [--task <task-id>] --subtask <spec> [--subtask <spec> ...]",
-  "  --subtask <temp-key>|<title>|<description>|<status>",
+  "  --subtask <temp-key>|<title>|<description>            (status defaults to todo)",
+  "  --subtask <temp-key>|<title>|<description>|<status>   (explicit status)",
   "  Positional <task-id> and --task can be combined only when equal.",
   "  Multiple --subtask flags are applied in order.",
   "  Escapes in compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
@@ -328,6 +333,8 @@ const MIGRATE_HELP = [
   "",
   "Notes:",
   "  Migrations 0004, 0005, and 0006 are irreversible (ALTER TABLE / data cleanup).",
+  "  Migration 0012 drops only its new indexes on rollback; the deduplicated dependency",
+  "  edges it removed cannot be restored without a backup.",
   "  Rolling back below those versions errors with code migration_down_unsupported.",
   "  Take a backup first; restore by copying the backup over .trekoon/trekoon.db.",
   "",
@@ -391,7 +398,7 @@ const SYNC_HELP = [
 ].join("\n");
 
 const SESSION_HELP = [
-  "Usage: trekoon session [--epic <epic-id>] [--json|--toon]",
+  "Usage: trekoon session [--epic <epic-id>] [--item <id>] [--json|--toon]",
   "",
   "One-call agent orientation. Opens the DB once and returns:",
   "  - diagnostics: storageMode, recoveryRequired, recoveryStatus",
@@ -402,6 +409,10 @@ const SESSION_HELP = [
   "",
   "Options:",
   "  --epic <epic-id>  Scope readiness to a specific epic.",
+  "  --item <id>       Resolve any epic/task/subtask id in one call. Returns",
+  "                    item: { kind, parentEpicId, entity, readiness, suggestedNext }.",
+  "                    Replaces the legacy epic-show || task-show || subtask-show cascade.",
+  "                    Mutually exclusive with --epic; passing both yields invalid_input.",
   "",
   "Output modes:",
   "  human  Multi-section summary (default in TTY)",
@@ -412,6 +423,7 @@ const SESSION_HELP = [
   "  trekoon session",
   "  trekoon --toon session",
   "  trekoon --toon session --epic <epic-id>",
+  "  trekoon --toon session --item <id>",
   "  trekoon --json session",
 ].join("\n");
 

package/src/commands/quickstart.ts

@@ -38,11 +38,14 @@ const QUICKSTART_TEXT = [
   "",
   "3) Execution loop",
   "  1. Start session:  trekoon --toon session [--epic <epic-id>]",
-  "  2. Claim work:     trekoon --toon task update <task-id> --status in_progress",
+  "  2. Claim work:     trekoon --toon task claim <task-id> --owner <TODO_OWNER>",
+  "     (atomic CAS; safe for parallel agents. Check data.claimed.)",
   "  3. Log progress:   trekoon --toon task update <task-id> --append \"Done with implementation\"",
   "  4. Finish:         trekoon --toon task done <task-id>",
   "     Returns the next ready task, its deps, and full payload.",
   "  5. Or report block: trekoon --toon task update <task-id> --append \"Blocked: <reason>\" --status blocked",
+  "  Non-claim path (mark progress without taking ownership):",
+  "     trekoon --toon task update <task-id> --status in_progress",
   "",
   "4) Orientation and suggestions",
   "  Next-action suggestions:  trekoon --toon suggest [--epic <epic-id>]",
@@ -130,7 +133,7 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
       ],
       executionLoop: [
         "trekoon --toon session",
-        "trekoon --toon task update <task-id> --status in_progress",
+        "trekoon --toon task claim <task-id> --owner <TODO_OWNER>",
         "trekoon --toon task update <task-id> --append \"Completed implementation\"",
         "trekoon --toon task done <task-id>",
       ],

package/src/commands/session.ts

@@ -4,7 +4,7 @@ import { DEFAULT_SOURCE_BRANCH, resolveSyncStatus } from "./sync-helpers";
 import { buildTaskReadiness, type DependencyBlocker } from "./task-readiness";
 
 import { TrackerDomain } from "../domain/tracker-domain";
-import { okResult } from "../io/output";
+import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 import { type GitContextSnapshot } from "../sync/types";
@@ -46,6 +46,23 @@ interface SessionResult {
   readonly readiness: SessionReadiness;
 }
 
+type ItemKind = "epic" | "task" | "subtask";
+
+interface ItemEnvelope {
+  readonly id: string;
+  readonly kind: ItemKind;
+  readonly parentEpicId: string;
+  readonly entity: unknown;
+  readonly readiness: SessionReadiness;
+  readonly suggestedNext: string;
+}
+
+interface ItemSessionResult {
+  readonly diagnostics: SessionResult["diagnostics"];
+  readonly sync: SessionResult["sync"];
+  readonly item: ItemEnvelope;
+}
+
 
 function formatSessionHuman(result: SessionResult): string {
   const lines: string[] = [];
@@ -98,18 +115,161 @@ function formatSessionHuman(result: SessionResult): string {
   return lines.join("\n");
 }
 
+function formatItemHuman(result: ItemSessionResult): string {
+  const lines: string[] = [];
+
+  lines.push("=== Session ===");
+  lines.push(`Storage mode: ${result.diagnostics.storageMode}`);
+  lines.push(`Recovery required: ${result.diagnostics.recoveryRequired}`);
+  lines.push(`Recovery status: ${result.diagnostics.recoveryStatus}`);
+
+  lines.push("");
+  lines.push("=== Sync ===");
+  lines.push(`Source branch: ${DEFAULT_SOURCE_BRANCH}`);
+  lines.push(`Ahead: ${result.sync.ahead}`);
+  lines.push(`Behind: ${result.sync.behind}`);
+  lines.push(`Pending conflicts: ${result.sync.pendingConflicts}`);
+  lines.push(`Branch: ${result.sync.git.branchName ?? "(detached)"}`);
+
+  lines.push("");
+  lines.push("=== Item ===");
+  lines.push(`${result.item.id} | kind=${result.item.kind} | epic=${result.item.parentEpicId}`);
+
+  lines.push("");
+  lines.push("=== Readiness (epic-scoped) ===");
+  lines.push(`Ready: ${result.item.readiness.readyCount}`);
+  lines.push(`Blocked: ${result.item.readiness.blockedCount}`);
+
+  lines.push("");
+  lines.push("=== Suggested Next ===");
+  lines.push(result.item.suggestedNext);
+
+  return lines.join("\n");
+}
+
+function resolveItem(
+  domain: TrackerDomain,
+  id: string,
+): { kind: ItemKind; parentEpicId: string; entity: unknown } | null {
+  const epic = domain.getEpic(id);
+  if (epic !== null) {
+    return {
+      kind: "epic",
+      parentEpicId: epic.id,
+      entity: domain.buildEpicTreeDetailed(epic.id),
+    };
+  }
+
+  const task = domain.getTask(id);
+  if (task !== null) {
+    return {
+      kind: "task",
+      parentEpicId: task.epicId,
+      entity: domain.buildTaskTreeDetailed(task.id),
+    };
+  }
+
+  const subtask = domain.getSubtask(id);
+  if (subtask !== null) {
+    const parentTask = domain.getTask(subtask.taskId);
+    const parentEpicId = parentTask?.epicId ?? "";
+    return {
+      kind: "subtask",
+      parentEpicId,
+      entity: subtask,
+    };
+  }
+
+  return null;
+}
+
+function suggestNextCommand(kind: ItemKind, id: string, parentEpicId: string): string {
+  switch (kind) {
+    case "epic":
+      return `trekoon --toon epic progress ${id}`;
+    case "task":
+      return `trekoon --toon task claim ${id} --owner <TODO_OWNER>`;
+    case "subtask":
+      return `trekoon --toon session --epic ${parentEpicId}`;
+  }
+}
+
 export async function runSession(context: CliContext): Promise<CliResult> {
   let database: TrekoonDatabase | undefined;
 
   try {
     const parsed = parseArgs(context.args);
     const epicId: string | undefined = readOption(parsed.options, "epic");
+    const itemId: string | undefined = readOption(parsed.options, "item");
+
+    if (epicId !== undefined && itemId !== undefined) {
+      return failResult({
+        command: "session",
+        human: "--epic and --item are mutually exclusive. Pass --epic to scope readiness by epic, or --item to resolve a specific entity.",
+        data: { code: "invalid_input", providedFlags: ["--epic", "--item"] },
+        error: {
+          code: "invalid_input",
+          message: "--epic and --item are mutually exclusive. Pass --epic to scope readiness by epic, or --item to resolve a specific entity.",
+        },
+      });
+    }
 
     database = openTrekoonDatabase(context.cwd);
     const diagnostics = database.diagnostics;
 
     const syncSummary = resolveSyncStatus(database, context.cwd, DEFAULT_SOURCE_BRANCH);
     const domain = new TrackerDomain(database.db);
+
+    if (itemId !== undefined) {
+      const resolved = resolveItem(domain, itemId);
+      if (resolved === null) {
+        return failResult({
+          command: "session",
+          human: `No epic, task, or subtask matches id ${itemId}`,
+          data: { code: "not_found", id: itemId },
+          error: {
+            code: "not_found",
+            message: `No epic, task, or subtask matches id ${itemId}`,
+          },
+        });
+      }
+
+      const scopedReadiness = resolved.parentEpicId.length > 0
+        ? buildTaskReadiness(domain, resolved.parentEpicId)
+        : buildTaskReadiness(domain, undefined);
+
+      const result: ItemSessionResult = {
+        diagnostics: {
+          storageMode: diagnostics.storageMode,
+          recoveryRequired: diagnostics.recoveryRequired,
+          recoveryStatus: diagnostics.recoveryStatus,
+        },
+        sync: {
+          ahead: syncSummary.ahead,
+          behind: syncSummary.behind,
+          pendingConflicts: syncSummary.pendingConflicts,
+          git: syncSummary.git,
+        },
+        item: {
+          id: itemId,
+          kind: resolved.kind,
+          parentEpicId: resolved.parentEpicId,
+          entity: resolved.entity,
+          readiness: {
+            readyCount: scopedReadiness.summary.readyCount,
+            blockedCount: scopedReadiness.summary.blockedCount,
+          },
+          suggestedNext: suggestNextCommand(resolved.kind, itemId, resolved.parentEpicId),
+        },
+      };
+
+      return okResult({
+        command: "session",
+        human: formatItemHuman(result),
+        data: result,
+      });
+    }
+
     const readiness = buildTaskReadiness(domain, epicId);
     const topCandidate = readiness.candidates[0] ?? null;
 

package/src/commands/subtask.ts

@@ -286,10 +286,10 @@ function parseSubtaskCreateManySpecs(parentTaskId: string, rawSpecs: readonly st
       };
     }
 
-    if (parsed.fields.length !== 4) {
+    if (parsed.fields.length !== 3 && parsed.fields.length !== 4) {
       return {
         specs: [],
-        error: failBatchSpec("subtask.create-many", `Subtask specs must use <temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}.`, {
+        error: failBatchSpec("subtask.create-many", `Subtask specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}.`, {
           option: "subtask",
           index,
           rawSpec,

package/src/commands/suggest.ts

@@ -125,7 +125,7 @@ function buildSuggestions(
     suggestions.push({
       priority: suggestions.length + 1,
       action: `claim task ${topReady.task.id}`,
-      command: `trekoon --toon task update ${topReady.task.id} --status in_progress`,
+      command: `trekoon --toon task claim ${topReady.task.id} --owner <TODO_OWNER>`,
       reason: `Highest priority ready task: ${topReady.task.title}`,
       category: "execution",
     });

package/src/commands/task.ts

@@ -375,10 +375,10 @@ function parseTaskCreateManySpecs(rawSpecs: readonly string[]): { specs: Compact
       };
     }
 
-    if (parsed.fields.length !== 4) {
+    if (parsed.fields.length !== 3 && parsed.fields.length !== 4) {
       return {
         specs: [],
-        error: failBatchSpec("task.create-many", `Task specs must use <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}.`, {
+        error: failBatchSpec("task.create-many", `Task specs must use <temp-key>|<title>|<description> or <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}.`, {
           option: "task",
           index,
           rawSpec,

package/src/domain/mutation-service.ts

@@ -434,7 +434,32 @@ export class MutationService {
         ? this.#domain.listSubtasksByTaskIds(taskIds)
         : new Map<string, readonly SubtaskRecord[]>();
 
+      // Collect every dependency touching the cascaded tasks/subtasks BEFORE
+      // the epic delete fires. The dependencies table has no FK to
+      // tasks/subtasks so SQLite ON DELETE CASCADE leaves these rows
+      // orphaned — we must clean them up here AND emit canonical
+      // `dependency.removed` events so the WAL watcher's event-cursor path
+      // can surface deletedDependencyIds to peer boards without falling
+      // back to a full-snapshot rebuild.
+      const cascadeNodeIds: string[] = [];
+      for (const task of tasks) {
+        cascadeNodeIds.push(task.id);
+        const subtasks = subtasksByTaskId.get(task.id) ?? [];
+        for (const subtask of subtasks) {
+          cascadeNodeIds.push(subtask.id);
+        }
+      }
+      const cascadedDependencies = cascadeNodeIds.length > 0
+        ? this.#domain.listDependenciesTouchingNodes(cascadeNodeIds)
+        : [];
+
       this.#domain.deleteEpic(id);
+      // Explicitly delete the dependency rows that touched the cascaded
+      // nodes. domain.deleteEpic relies on SQLite CASCADE for tasks/subtasks
+      // but does not (and cannot) reach the dependencies table.
+      if (cascadedDependencies.length > 0) {
+        this.#domain.removeDependenciesByIds(cascadedDependencies.map((dependency) => dependency.id));
+      }
 
       const epicDeleteEventId = this.#emitEpicDeleted(id);
 
@@ -450,6 +475,26 @@ export class MutationService {
           this.#emitSubtaskDeleted(subtask.id, { taskId: task.id, sourceEventId: taskDeleteEventId });
         }
       }
+
+      // Emit dependency.removed for each cascaded dep. Stamp them with the
+      // epic-delete event id so peer worktrees can suppress the per-dep
+      // conflict the same way cascaded task.deleted events are suppressed
+      // behind a pending epic-level conflict.
+      for (const dependency of cascadedDependencies) {
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.removed,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+            sourceEventId: epicDeleteEventId,
+          }),
+        );
+      }
     });
   }
 
@@ -955,8 +1000,15 @@ export class MutationService {
   deleteTask(id: string): { deletedSubtaskIds: string[]; deletedDependencyIds: string[] } {
     return this.#writeTransaction((): { deletedSubtaskIds: string[]; deletedDependencyIds: string[] } => {
       const plan = this.#domain.planTaskDeletion(id);
+      // Capture the parent epic id BEFORE delete so the canonical task.deleted
+      // event can fan-in to the parent epic in the WAL watcher event-cursor
+      // path. Without this the watcher cannot reconstruct the parent epic
+      // change (taskIds / counts / searchText) from the event stream alone
+      // for non-cascade deletes.
+      const existing = this.#domain.getTaskOrThrow(id);
+      const parentEpicId = existing.epicId;
       this.#domain.deleteTask(id);
-      const taskDeleteEventId = this.#emitTaskDeleted(id);
+      const taskDeleteEventId = this.#emitTaskDeleted(id, { epicId: parentEpicId });
 
       for (const subtaskId of plan.subtaskIds) {
         this.#emitSubtaskDeleted(subtaskId, { taskId: id, sourceEventId: taskDeleteEventId });
@@ -1104,8 +1156,16 @@ export class MutationService {
   deleteSubtask(id: string): { deletedDependencyIds: string[] } {
     return this.#writeTransaction((): { deletedDependencyIds: string[] } => {
       const touchingDependencies = this.#domain.listDependenciesTouchingNode(id);
+      // Capture the parent task id BEFORE delete so the canonical
+      // subtask.deleted event can fan-in to the parent task in the WAL
+      // watcher event-cursor path. Without this the watcher cannot
+      // reconstruct the parent task change (subtasks list / searchText /
+      // counts) from the event stream — domain.getSubtask(id) returns null
+      // post-delete.
+      const existing = this.#domain.getSubtaskOrThrow(id);
+      const parentTaskId = existing.taskId;
       this.#domain.deleteSubtask(id);
-      const subtaskDeleteEventId = this.#emitSubtaskDeleted(id);
+      const subtaskDeleteEventId = this.#emitSubtaskDeleted(id, { taskId: parentTaskId });
       for (const dependency of touchingDependencies) {
         this.#appendEntityEvent(
           "dependency",
@@ -1143,7 +1203,11 @@ export class MutationService {
       const task = this.#domain.getTaskOrThrow(existingSubtask.taskId);
       const touchingDependencies = this.#domain.listDependenciesTouchingNode(input.id);
       this.#domain.deleteSubtask(input.id);
-      const subtaskDeleteEventId = this.#emitSubtaskDeleted(input.id);
+      // Emit task_id on the canonical subtask.deleted event so the WAL
+      // watcher's event-cursor path can fan-in the parent task without a
+      // post-delete domain lookup (which returns null). Same field shape as
+      // the cascade path's emitter call, minus source_event_id.
+      const subtaskDeleteEventId = this.#emitSubtaskDeleted(input.id, { taskId: existingSubtask.taskId });
       for (const dependency of touchingDependencies) {
         this.#appendEntityEvent(
           "dependency",
@@ -1480,9 +1544,15 @@ export class MutationService {
 
   #emitTaskDeleted(
     taskId: string,
-    cascade?: { sourceEventId: string } | undefined,
+    options?: { epicId?: string | undefined; sourceEventId?: string | undefined } | undefined,
   ): string {
-    const fields: Record<string, unknown> = cascade ? { source_event_id: cascade.sourceEventId } : {};
+    const fields: Record<string, unknown> = {};
+    if (options?.epicId) {
+      fields.epic_id = options.epicId;
+    }
+    if (options?.sourceEventId) {
+      fields.source_event_id = options.sourceEventId;
+    }
     return this.#appendEntityEvent("task", taskId, ENTITY_OPERATIONS.task.deleted, fields);
   }
 
@@ -1507,11 +1577,15 @@ export class MutationService {
 
   #emitSubtaskDeleted(
     subtaskId: string,
-    cascade?: { taskId: string; sourceEventId: string } | undefined,
+    options?: { taskId?: string | undefined; sourceEventId?: string | undefined } | undefined,
   ): string {
-    const fields: Record<string, unknown> = cascade
-      ? { task_id: cascade.taskId, source_event_id: cascade.sourceEventId }
-      : {};
+    const fields: Record<string, unknown> = {};
+    if (options?.taskId) {
+      fields.task_id = options.taskId;
+    }
+    if (options?.sourceEventId) {
+      fields.source_event_id = options.sourceEventId;
+    }
     return this.#appendEntityEvent("subtask", subtaskId, ENTITY_OPERATIONS.subtask.deleted, fields);
   }
 

package/src/domain/tracker-domain.ts

@@ -826,6 +826,44 @@ export class TrackerDomain {
     return rows.map(mapDependency);
   }
 
+  /**
+   * Multi-node variant of {@link listDependenciesTouchingNode}. Returns every
+   * dependency row whose `source_id` OR `depends_on_id` is in the supplied
+   * set, deduped and ordered by (created_at, id).
+   *
+   * Used by epic-cascade delete to gather touching dependencies for the
+   * union of an epic's tasks and subtasks in a single chunked query rather
+   * than N per-node calls. Mirrors `planTaskDeletion`'s SQL shape.
+   *
+   * Callers do NOT need to pre-validate node existence — orphaned dep rows
+   * are surfaced as-is so the caller can clean them up. An empty input
+   * returns an empty array without touching the database.
+   */
+  listDependenciesTouchingNodes(nodeIds: readonly string[]): readonly DependencyRecord[] {
+    if (nodeIds.length === 0) {
+      return [];
+    }
+    const normalizedIds: string[] = nodeIds.map((nodeId) => assertNonEmpty("nodeId", nodeId));
+    const dependencyRows: DependencyRow[] = [];
+    const nodeIdChunks = chunkValues(normalizedIds, Math.floor(SQLITE_MAX_VARIABLES / 2));
+    for (const nodeIdChunk of nodeIdChunks) {
+      const placeholders = nodeIdChunk.map(() => "?").join(", ");
+      const rows = this.#db
+        .query(
+          `SELECT id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at
+           FROM dependencies
+           WHERE source_id IN (${placeholders}) OR depends_on_id IN (${placeholders})
+           ORDER BY created_at ASC, id ASC;`,
+        )
+        .all(...nodeIdChunk, ...nodeIdChunk) as DependencyRow[];
+      dependencyRows.push(...rows);
+    }
+
+    return [...new Map(dependencyRows.map((row) => [row.id, row])).values()]
+      .sort((left, right) => left.created_at - right.created_at || left.id.localeCompare(right.id))
+      .map(mapDependency);
+  }
+
   planTaskDeletion(taskId: string): TaskDeletionPlan {
     const normalizedTaskId: string = assertNonEmpty("taskId", taskId);
     this.getTaskOrThrow(normalizedTaskId);
@@ -1146,7 +1184,13 @@ export class TrackerDomain {
     }
 
     const dependencies: DependencyRecord[] = [];
-    const newIds: string[] = [];
+    const newRows: Array<{
+      id: string;
+      sourceId: string;
+      sourceKind: string;
+      dependsOnId: string;
+      dependsOnKind: string;
+    }> = [];
     const batchNow: number = Date.now();
 
     for (const spec of resolvedSpecs) {
@@ -1157,15 +1201,38 @@ export class TrackerDomain {
         continue;
       }
 
-      const id: string = randomUUID();
+      newRows.push({
+        id: randomUUID(),
+        sourceId: spec.sourceId,
+        sourceKind: spec.sourceKind,
+        dependsOnId: spec.dependsOnId,
+        dependsOnKind: spec.dependsOnKind,
+      });
+    }
 
+    // Chunked multi-row INSERT. Each row binds 7 parameters (the trailing
+    // `version` literal stays in the VALUES tuple to mirror the createTaskBatch
+    // shape). Cap the chunk size by the global SQLite bound-parameter limit so
+    // a 200-edge batch produces ~ceil(200/142) = 2 statements rather than 200.
+    // Per-edge canonical `dependency.added` events are still emitted upstream
+    // (mutation-service) — this only collapses the SQL writes, never the
+    // event-row contract.
+    const DEP_COLS_PER_ROW = 7; // id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at (version is literal 1)
+    const WRITE_CHUNK_SIZE: number = Math.floor(SQLITE_MAX_VARIABLES / DEP_COLS_PER_ROW);
+    const newIds: string[] = newRows.map((row) => row.id);
+
+    for (let offset = 0; offset < newRows.length; offset += WRITE_CHUNK_SIZE) {
+      const chunk = newRows.slice(offset, offset + WRITE_CHUNK_SIZE);
+      const placeholders: string = chunk.map(() => "(?, ?, ?, ?, ?, ?, ?, 1)").join(", ");
+      const params: Array<string | number> = [];
+      for (const row of chunk) {
+        params.push(row.id, row.sourceId, row.sourceKind, row.dependsOnId, row.dependsOnKind, batchNow, batchNow);
+      }
       this.#db
         .query(
-          "INSERT INTO dependencies (id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at, version) VALUES (?, ?, ?, ?, ?, ?, ?, 1);",
+          `INSERT INTO dependencies (id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at, version) VALUES ${placeholders};`,
         )
-        .run(id, spec.sourceId, spec.sourceKind, spec.dependsOnId, spec.dependsOnKind, batchNow, batchNow);
-
-      newIds.push(id);
+        .run(...params);
     }
 
     // Batch-fetch all newly inserted dependencies instead of one getDependencyOrThrow per row.
@@ -1204,6 +1271,42 @@ export class TrackerDomain {
     return result.changes;
   }
 
+  /**
+   * Bulk delete dependency rows by primary key, chunked to respect
+   * {@link SQLITE_MAX_VARIABLES}. Used by the epic-cascade deletion path:
+   * SQLite ON DELETE CASCADE covers tasks/subtasks but NOT the dependencies
+   * table (no FK exists) — without this, dep rows touching cascaded
+   * tasks/subtasks are left orphaned after `deleteEpic`.
+   *
+   * Returns the total number of rows actually deleted across all chunks.
+   * Empty input is a no-op and returns 0 without touching the database.
+   */
+  removeDependenciesByIds(ids: readonly string[]): number {
+    if (ids.length === 0) {
+      return 0;
+    }
+    this.#assertInTransaction("removeDependenciesByIds");
+    const normalized: string[] = ids.map((id) => assertNonEmpty("id", id));
+    let totalChanges = 0;
+    for (const chunk of chunkValues(normalized, SQLITE_MAX_VARIABLES)) {
+      const placeholders = chunk.map(() => "?").join(", ");
+      const result = this.#db
+        .query(`DELETE FROM dependencies WHERE id IN (${placeholders});`)
+        .run(...chunk);
+      totalChanges += result.changes;
+    }
+    return totalChanges;
+  }
+
+  getDependency(id: string): DependencyRecord | null {
+    const row = this.#db
+      .query(
+        "SELECT id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at FROM dependencies WHERE id = ?;",
+      )
+      .get(id) as DependencyRow | null;
+    return row ? mapDependency(row) : null;
+  }
+
   listDependencies(sourceId: string): readonly DependencyRecord[] {
     const normalizedSourceId: string = assertNonEmpty("sourceId", sourceId);
     this.resolveNodeKind(normalizedSourceId);

package/src/io/output.ts

@@ -144,7 +144,7 @@ export function toToonEnvelope(result: CliResult, options: RenderOptions = {}):
     ok: result.ok,
     command,
     data: result.data,
-    ...(compact ? {} : { metadata: createContractMetadata(result, compatibilityMode) }),
+    ...(!compact ? { metadata: createContractMetadata(result, compatibilityMode) } : {}),
     ...(result.error ? { error: result.error } : {}),
     ...(result.meta ? { meta: result.meta } : {}),
   };