@hasna/todos 0.11.57 → 0.11.59

package/dist/storage.js

@@ -1269,6 +1269,49 @@ var init_migrations = __esm(() => {
   CREATE INDEX IF NOT EXISTS idx_local_retrospectives_plan ON local_retrospectives(plan_id);
   CREATE INDEX IF NOT EXISTS idx_local_retrospectives_agent ON local_retrospectives(agent_id);
   INSERT OR IGNORE INTO _migrations (id) VALUES (61);
+  `,
+    `
+  CREATE TABLE IF NOT EXISTS task_run_transactions (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+    run_id TEXT REFERENCES task_runs(id) ON DELETE SET NULL,
+    key TEXT NOT NULL,
+    loop_id TEXT,
+    loop_run_id TEXT,
+    metadata TEXT DEFAULT '{}',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(task_id, key)
+  );
+  CREATE INDEX IF NOT EXISTS idx_task_run_transactions_task_key ON task_run_transactions(task_id, key);
+  CREATE INDEX IF NOT EXISTS idx_task_run_transactions_key ON task_run_transactions(key);
+  CREATE INDEX IF NOT EXISTS idx_task_run_transactions_run ON task_run_transactions(run_id);
+
+  CREATE TABLE IF NOT EXISTS task_findings (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+    run_id TEXT REFERENCES task_runs(id) ON DELETE SET NULL,
+    fingerprint TEXT NOT NULL,
+    title TEXT NOT NULL,
+    severity TEXT NOT NULL DEFAULT 'medium' CHECK(severity IN ('low', 'medium', 'high', 'critical')),
+    status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open', 'resolved', 'ignored')),
+    source TEXT,
+    summary TEXT,
+    artifact_path TEXT,
+    metadata TEXT DEFAULT '{}',
+    first_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+    last_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+    resolved_at TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(task_id, fingerprint)
+  );
+  CREATE INDEX IF NOT EXISTS idx_task_findings_task ON task_findings(task_id);
+  CREATE INDEX IF NOT EXISTS idx_task_findings_run ON task_findings(run_id);
+  CREATE INDEX IF NOT EXISTS idx_task_findings_status ON task_findings(status);
+  CREATE INDEX IF NOT EXISTS idx_task_findings_source ON task_findings(source);
+  CREATE INDEX IF NOT EXISTS idx_task_findings_fingerprint ON task_findings(fingerprint);
+  INSERT OR IGNORE INTO _migrations (id) VALUES (62);
   `
   ];
 });
@@ -1706,6 +1749,47 @@ function ensureSchema(db) {
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_artifacts_run ON task_run_artifacts(run_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_artifacts_task ON task_run_artifacts(task_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_artifacts_path ON task_run_artifacts(path)");
+  ensureTable("task_run_transactions", `
+    CREATE TABLE task_run_transactions (
+      id TEXT PRIMARY KEY,
+      task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      run_id TEXT REFERENCES task_runs(id) ON DELETE SET NULL,
+      key TEXT NOT NULL,
+      loop_id TEXT,
+      loop_run_id TEXT,
+      metadata TEXT DEFAULT '{}',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(task_id, key)
+    )`);
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_transactions_task_key ON task_run_transactions(task_id, key)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_transactions_key ON task_run_transactions(key)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_transactions_run ON task_run_transactions(run_id)");
+  ensureTable("task_findings", `
+    CREATE TABLE task_findings (
+      id TEXT PRIMARY KEY,
+      task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      run_id TEXT REFERENCES task_runs(id) ON DELETE SET NULL,
+      fingerprint TEXT NOT NULL,
+      title TEXT NOT NULL,
+      severity TEXT NOT NULL DEFAULT 'medium' CHECK(severity IN ('low', 'medium', 'high', 'critical')),
+      status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open', 'resolved', 'ignored')),
+      source TEXT,
+      summary TEXT,
+      artifact_path TEXT,
+      metadata TEXT DEFAULT '{}',
+      first_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+      last_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+      resolved_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(task_id, fingerprint)
+    )`);
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_task ON task_findings(task_id)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_run ON task_findings(run_id)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_status ON task_findings(status)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_source ON task_findings(source)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_fingerprint ON task_findings(fingerprint)");
   ensureTable("inbox_items", `
     CREATE TABLE inbox_items (
       id TEXT PRIMARY KEY,
@@ -4180,6 +4264,7 @@ var LOCAL_EVENT_TYPES = [
   "task.blocked",
   "task.started",
   "task.completed",
+  "task.updated",
   "task.due",
   "task.due_soon",
   "task.failed",
@@ -4418,7 +4503,7 @@ async function testLocalEventHook(name, input) {
   return emitLocalEventHooks({ ...input, hooks: [hook] });
 }
 
-// node_modules/.bun/@hasna+events@0.1.7/node_modules/@hasna/events/dist/index.js
+// node_modules/.bun/@hasna+events@0.1.9/node_modules/@hasna/events/dist/index.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { existsSync as existsSync5 } from "fs";
 import { homedir } from "os";
@@ -4435,17 +4520,30 @@ function getPathValue(input, path) {
     return;
   }, input);
 }
-function wildcardToRegExp(pattern) {
-  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`);
+function wildcardToRegExp(pattern, options = {}) {
+  let body = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        body += ".*";
+        index += 1;
+      } else {
+        body += options.segmentSafe ? "[^/]*" : ".*";
+      }
+    } else {
+      body += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${body}$`);
 }
-function matchString(value, matcher) {
+function matchString(value, matcher, options = {}) {
   if (matcher === undefined)
     return true;
   if (value === undefined)
     return false;
   const matchers = Array.isArray(matcher) ? matcher : [matcher];
-  return matchers.some((item) => wildcardToRegExp(item).test(value));
+  return matchers.some((item) => wildcardToRegExp(item, options).test(value));
 }
 function matchRecord(input, matcher) {
   if (!matcher)
@@ -4453,7 +4551,9 @@ function matchRecord(input, matcher) {
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
     if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected);
+      return matchString(actual === undefined ? undefined : String(actual), expected, {
+        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+      });
     }
     return actual === expected;
   });
@@ -4473,7 +4573,6 @@ var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join4(homedir(), ".hasna", "events");
 }
-
 class JsonEventsStore {
   dataDir;
   channelsPath;
@@ -4810,7 +4909,7 @@ class EventsClient {
     }
     return deliveries;
   }
-  async testChannel(id, input = {}) {
+  async matchChannel(id, input = {}) {
     const channel = await this.store.getChannel(id);
     if (!channel)
       throw new Error(`Channel not found: ${id}`);
@@ -4827,6 +4926,34 @@ class EventsClient {
       time: input.time,
       id: input.id
     });
+    const matched = channelMatchesEvent(channel, event);
+    return {
+      channelId: channel.id,
+      matched,
+      event,
+      filters: channel.filters,
+      reason: matched ? undefined : channel.enabled ? "event did not match channel filters" : "channel is disabled"
+    };
+  }
+  async testChannel(id, input = {}, options = {}) {
+    const channel = await this.store.getChannel(id);
+    if (!channel)
+      throw new Error(`Channel not found: ${id}`);
+    const match = await this.matchChannel(id, input);
+    const event = match.event;
+    if (options.honorFilters && !match.matched) {
+      const timestamp = new Date().toISOString();
+      const result2 = createDeliveryResult(event, channel, [{
+        attempt: 1,
+        status: "skipped",
+        startedAt: timestamp,
+        completedAt: timestamp,
+        error: match.reason
+      }]);
+      result2.metadata = { reason: "filter_mismatch" };
+      await this.store.appendDelivery(result2);
+      return result2;
+    }
     const eventForChannel = await this.applyRedaction(event, channel);
     const result = await this.deliverWithRetry(eventForChannel, channel);
     await this.store.appendDelivery(result);
@@ -4926,6 +5053,90 @@ function normalizeRetryPolicy(policy) {
   };
 }
 
+// src/lib/shared-events.ts
+init_database();
+
+// src/db/task-lists.ts
+init_types();
+init_database();
+function rowToTaskList(row) {
+  return {
+    ...row,
+    metadata: JSON.parse(row.metadata || "{}")
+  };
+}
+function createTaskList(input, db) {
+  const d = db || getDatabase();
+  const id = uuid();
+  const timestamp = now();
+  const slug = input.slug || slugify(input.name);
+  if (!input.project_id) {
+    const existing = d.query("SELECT id FROM task_lists WHERE project_id IS NULL AND slug = ?").get(slug);
+    if (existing) {
+      throw new Error(`Standalone task list with slug "${slug}" already exists`);
+    }
+  }
+  d.run(`INSERT INTO task_lists (id, project_id, slug, name, description, metadata, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [id, input.project_id || null, slug, input.name, input.description || null, JSON.stringify(input.metadata || {}), timestamp, timestamp]);
+  return getTaskList(id, d);
+}
+function getTaskList(id, db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT * FROM task_lists WHERE id = ?").get(id);
+  return row ? rowToTaskList(row) : null;
+}
+function getTaskListBySlug(slug, projectId, db) {
+  const d = db || getDatabase();
+  let row;
+  if (projectId) {
+    row = d.query("SELECT * FROM task_lists WHERE slug = ? AND project_id = ?").get(slug, projectId);
+  } else {
+    row = d.query("SELECT * FROM task_lists WHERE slug = ? AND project_id IS NULL").get(slug);
+  }
+  return row ? rowToTaskList(row) : null;
+}
+function listTaskLists(projectId, db) {
+  const d = db || getDatabase();
+  if (projectId) {
+    return d.query("SELECT * FROM task_lists WHERE project_id = ? ORDER BY name").all(projectId).map(rowToTaskList);
+  }
+  return d.query("SELECT * FROM task_lists ORDER BY name").all().map(rowToTaskList);
+}
+function updateTaskList(id, input, db) {
+  const d = db || getDatabase();
+  const existing = getTaskList(id, d);
+  if (!existing)
+    throw new TaskListNotFoundError(id);
+  const sets = ["updated_at = ?"];
+  const params = [now()];
+  if (input.name !== undefined) {
+    sets.push("name = ?");
+    params.push(input.name);
+  }
+  if (input.description !== undefined) {
+    sets.push("description = ?");
+    params.push(input.description);
+  }
+  if (input.metadata !== undefined) {
+    sets.push("metadata = ?");
+    params.push(JSON.stringify(input.metadata));
+  }
+  params.push(id);
+  d.run(`UPDATE task_lists SET ${sets.join(", ")} WHERE id = ?`, params);
+  return getTaskList(id, d);
+}
+function deleteTaskList(id, db) {
+  const d = db || getDatabase();
+  return d.run("DELETE FROM task_lists WHERE id = ?", [id]).changes > 0;
+}
+function ensureTaskList(name, slug, projectId, db) {
+  const d = db || getDatabase();
+  const existing = getTaskListBySlug(slug, projectId, d);
+  if (existing)
+    return existing;
+  return createTaskList({ name, slug, project_id: projectId }, d);
+}
+
 // src/lib/shared-events.ts
 var SOURCE = "todos";
 function taskEventData(task, extra = {}) {
@@ -4956,6 +5167,69 @@ function taskEventData(task, extra = {}) {
     ...extra
   };
 }
+function taskEventMetadata(task) {
+  const metadata = {
+    package: "@hasna/todos",
+    todos_event_schema_version: 1,
+    task_id: task.id,
+    task_short_id: task.short_id,
+    project_id: task.project_id,
+    task_list_id: task.task_list_id,
+    working_dir: task.working_dir
+  };
+  try {
+    const project = task.project_id ? getProject(task.project_id) : null;
+    const projectPath = project ? readMachineLocalPath(project) ?? project.path : task.working_dir;
+    if (project) {
+      metadata.project_id = project.id;
+      metadata.project_name = project.name;
+      metadata.project_path = projectPath;
+      metadata.project_canonical_path = project.path;
+      metadata.project_default_task_list_slug = project.task_list_id;
+      metadata.root_project_id = inferRootProjectId(project);
+    } else if (projectPath) {
+      metadata.project_path = projectPath;
+      metadata.project_canonical_path = projectPath;
+    }
+    if (projectPath) {
+      metadata.project_kind = classifyProjectKind(projectPath);
+      metadata.project_is_worktree = isWorktreePath(projectPath);
+      if (typeof task.metadata.route_enabled === "boolean") {
+        metadata.route_enabled = task.metadata.route_enabled;
+      }
+      metadata.working_dir = task.working_dir ?? projectPath;
+    }
+    const taskList = task.task_list_id ? getTaskList(task.task_list_id) ?? (project ? getTaskListBySlug(task.task_list_id, project.id) : null) : project?.task_list_id ? getTaskListBySlug(project.task_list_id, project.id) : null;
+    if (taskList) {
+      metadata.task_list_id = taskList.id;
+      metadata.task_list_slug = taskList.slug;
+      metadata.task_list_name = taskList.name;
+      metadata.task_list_project_id = taskList.project_id;
+      metadata.task_list_is_project_default = Boolean(project?.task_list_id && taskList.slug === project.task_list_id);
+    }
+  } catch {}
+  return metadata;
+}
+function classifyProjectKind(path) {
+  return path.includes("/hasna/opensource/") ? "open-source" : "unknown";
+}
+function isWorktreePath(path) {
+  return path.includes("/.codewith/worktrees/") || path.includes("/.worktrees/");
+}
+function inferRootProjectId(project) {
+  return isWorktreePath(project.path) ? null : project.id;
+}
+function readMachineLocalPath(project) {
+  const machineId = process.env["TODOS_MACHINE_ID"];
+  if (!machineId)
+    return null;
+  try {
+    const row = getDatabase().query("SELECT path FROM project_machine_paths WHERE project_id = ? AND machine_id = ?").get(project.id, machineId);
+    return row?.path ?? null;
+  } catch {
+    return null;
+  }
+}
 async function emitSharedTaskEvent(input) {
   const data = taskEventData(input.task, input.data);
   await new EventsClient().emit({
@@ -4966,12 +5240,7 @@ async function emitSharedTaskEvent(input) {
     message: input.message ?? `${input.type}: ${input.task.title}`,
     data,
     dedupeKey: input.dedupeKey ?? `${input.type}:${input.task.id}:${input.task.version}`,
-    metadata: {
-      package: "@hasna/todos",
-      task_id: input.task.id,
-      project_id: input.task.project_id,
-      task_list_id: input.task.task_list_id
-    }
+    metadata: taskEventMetadata(input.task)
   }, { deliver: true, dedupe: true });
 }
 function emitSharedTaskEventQuiet(input) {
@@ -5334,6 +5603,17 @@ function replaceTaskTags(taskId, tags, db) {
   db.run("DELETE FROM task_tags WHERE task_id = ?", [taskId]);
   insertTaskTags(taskId, tags, db);
 }
+function addMetadataConditions(metadata, conditions, params) {
+  if (!metadata)
+    return;
+  for (const [key, value] of Object.entries(metadata)) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(key)) {
+      throw new Error(`Invalid metadata filter key: ${key}`);
+    }
+    conditions.push(`json_extract(metadata, '$."${key}"') = ?`);
+    params.push(value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value));
+  }
+}
 function createTask(input, db) {
   const d = db || getDatabase();
   const timestamp = now();
@@ -5516,6 +5796,7 @@ function listTasks(filter = {}, db) {
       params.push(filter.task_type);
     }
   }
+  addMetadataConditions(filter.metadata, conditions, params);
   const PRIORITY_RANK = `CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END`;
   if (filter.cursor) {
     try {
@@ -5540,6 +5821,54 @@ function listTasks(filter = {}, db) {
   const rows = d.query(`SELECT * FROM tasks ${where} ORDER BY ${PRIORITY_RANK}, created_at DESC${limitClause}`).all(...params);
   return rows.map(rowToTask);
 }
+function getTaskByFingerprint(fingerprint, db) {
+  const tasks = listTasks({ metadata: { fingerprint }, limit: 1 }, db);
+  return tasks[0] ?? null;
+}
+function mergeTaskMetadata(current, next, fingerprint) {
+  return {
+    ...current,
+    ...next ?? {},
+    fingerprint
+  };
+}
+function upsertTaskByFingerprint(input, db) {
+  const d = db || getDatabase();
+  const fingerprint = input.fingerprint.trim();
+  if (!fingerprint)
+    throw new Error("fingerprint is required");
+  const existing = getTaskByFingerprint(fingerprint, d);
+  const metadata = mergeTaskMetadata(existing?.metadata ?? {}, input.metadata, fingerprint);
+  if (!existing) {
+    const task2 = createTask({ ...input, metadata }, d);
+    return { task: task2, created: true };
+  }
+  const task = updateTask(existing.id, {
+    version: existing.version,
+    title: input.title,
+    description: input.description,
+    status: input.status,
+    priority: input.priority,
+    project_id: input.project_id,
+    assigned_to: input.assigned_to,
+    working_dir: input.working_dir,
+    plan_id: input.plan_id,
+    task_list_id: input.task_list_id,
+    tags: input.tags,
+    metadata,
+    due_at: input.due_at,
+    estimated_minutes: input.estimated_minutes,
+    sla_minutes: input.sla_minutes,
+    confidence: input.confidence,
+    retry_count: input.retry_count,
+    max_retries: input.max_retries,
+    retry_after: input.retry_after,
+    requires_approval: input.requires_approval,
+    recurrence_rule: input.recurrence_rule,
+    task_type: input.task_type
+  }, d);
+  return { task, created: false };
+}
 function countTasks(filter = {}, db) {
   const d = db || getDatabase();
   const conditions = [];
@@ -5603,6 +5932,7 @@ function countTasks(filter = {}, db) {
     conditions.push("task_list_id = ?");
     params.push(filter.task_list_id);
   }
+  addMetadataConditions(filter.metadata, conditions, params);
   if (!filter.include_archived) {
     conditions.push("archived_at IS NULL");
   }
@@ -5653,6 +5983,10 @@ function updateTask(id, input, db) {
     sets.push("assigned_to = ?");
     params.push(input.assigned_to);
   }
+  if (input.working_dir !== undefined) {
+    sets.push("working_dir = ?");
+    params.push(input.working_dir);
+  }
   if (input.tags !== undefined) {
     sets.push("tags = ?");
     params.push(JSON.stringify(input.tags));
@@ -5741,6 +6075,8 @@ function updateTask(id, input, db) {
     logTaskChange(id, "update", "title", task.title, input.title, agentId, d);
   if (input.assigned_to !== undefined && input.assigned_to !== task.assigned_to)
     logTaskChange(id, "update", "assigned_to", task.assigned_to, input.assigned_to, agentId, d);
+  if (input.working_dir !== undefined && input.working_dir !== task.working_dir)
+    logTaskChange(id, "update", "working_dir", task.working_dir, input.working_dir, agentId, d);
   if (input.approved_by !== undefined)
     logTaskChange(id, "approve", "approved_by", null, input.approved_by, agentId, d);
   const updatedTask = {
@@ -5776,6 +6112,10 @@ function updateTask(id, input, db) {
   if (input.approved_by !== undefined) {
     emitLocalEventHooksQuiet({ type: "approval.decided", payload: { id, approved_by: input.approved_by, title: task.title } });
   }
+  const updatePayload = taskEventData(updatedTask);
+  dispatchWebhook2("task.updated", updatePayload, d).catch(() => {});
+  emitLocalEventHooksQuiet({ type: "task.updated", payload: updatePayload });
+  emitSharedTaskEventQuiet({ type: "task.updated", task: updatedTask });
   return updatedTask;
 }
 function deleteTask(id, db) {
@@ -8471,6 +8811,7 @@ function getTaskTraceability(taskId, db) {
 
 // src/db/task-runs.ts
 init_redaction();
+var LOOP_RUN_TRANSACTION_SCHEMA_VERSION = "todos.loop_run_transaction.v1";
 function parseObject(value) {
   if (!value)
     return {};
@@ -8493,6 +8834,72 @@ function rowToArtifact(row) {
 function getRunRow(runId, db) {
   return db.query("SELECT * FROM task_runs WHERE id = ?").get(runId);
 }
+function normalizeTransactionKey(input) {
+  const key = (input.key || input.loop_run_id || input.loop_id || "").trim();
+  if (!key)
+    throw new Error("idempotent run transactions require --key, --loop-run-id, or --loop-id");
+  return key.toLowerCase().replace(/[^a-z0-9._:/-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 240);
+}
+function loopTransactionMetadata(record) {
+  const value = record.metadata["loop_transaction"];
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function runKey(record) {
+  const tx = loopTransactionMetadata(record);
+  const key = tx["idempotency_key"] ?? record.metadata["idempotency_key"];
+  return typeof key === "string" ? key : null;
+}
+function loopId(record) {
+  const tx = loopTransactionMetadata(record);
+  const value = tx["loop_id"] ?? record.metadata["loop_id"];
+  return typeof value === "string" ? value : null;
+}
+function loopRunId(record) {
+  const tx = loopTransactionMetadata(record);
+  const value = tx["loop_run_id"] ?? record.metadata["loop_run_id"];
+  return typeof value === "string" ? value : null;
+}
+function getTaskRunTransactionByKey(key, taskId, db) {
+  if (taskId) {
+    return db.query("SELECT * FROM task_run_transactions WHERE task_id = ? AND key = ?").get(taskId, key);
+  }
+  const rows = db.query("SELECT * FROM task_run_transactions WHERE key = ? ORDER BY created_at DESC LIMIT 2").all(key);
+  if (rows.length > 1)
+    throw new Error(`Run transaction key is ambiguous across tasks: ${key}. Pass task_id.`);
+  return rows[0] ?? null;
+}
+function summarizeTaskRun(run) {
+  return {
+    id: run.id,
+    task_id: run.task_id,
+    agent_id: run.agent_id,
+    title: run.title,
+    status: run.status,
+    summary: run.summary,
+    idempotency_key: runKey(run),
+    loop_id: loopId(run),
+    loop_run_id: loopRunId(run),
+    metadata_keys: Object.keys(run.metadata).sort(),
+    started_at: run.started_at,
+    completed_at: run.completed_at,
+    updated_at: run.updated_at
+  };
+}
+function findTaskRunByTransactionKey(key, taskId, db) {
+  const d = db || getDatabase();
+  const normalized = normalizeTransactionKey({ key });
+  const transaction = getTaskRunTransactionByKey(normalized, taskId, d);
+  if (transaction?.run_id)
+    return getTaskRun(transaction.run_id, d);
+  return null;
+}
+function loopRunCommands(run, key) {
+  return [
+    run ? `todos runs show ${run.id.slice(0, 8)}` : "todos runs list",
+    run ? `todos findings list --task ${run.task_id.slice(0, 8)} --json` : "todos findings list --json",
+    `todos runs begin <task-id> --key ${key} --apply --json`
+  ];
+}
 function resolveTaskRunId(idOrPrefix, db) {
   const d = db || getDatabase();
   const rows = d.query("SELECT id FROM task_runs WHERE id = ? OR id LIKE ? ORDER BY created_at DESC LIMIT 2").all(idOrPrefix, `${idOrPrefix}%`);
@@ -8511,7 +8918,7 @@ function startTaskRun(input, db) {
   const d = db || getDatabase();
   if (!getTask(input.task_id, d))
     throw new TaskNotFoundError(input.task_id);
-  const id = uuid();
+  const id = input.id ?? uuid();
   const timestamp = input.started_at || now();
   if (input.claim && input.agent_id) {
     startTask(input.task_id, input.agent_id, d);
@@ -8549,6 +8956,97 @@ function startTaskRun(input, db) {
   emitLocalEventHooksQuiet({ type: "run.started", payload: { id: run.id, task_id: run.task_id, agent_id: run.agent_id, title: run.title } });
   return run;
 }
+function beginTaskRunTransaction(input, db) {
+  const d = db || getDatabase();
+  if (!getTask(input.task_id, d))
+    throw new TaskNotFoundError(input.task_id);
+  const timestamp = input.started_at || now();
+  const key = normalizeTransactionKey(input);
+  const existing = findTaskRunByTransactionKey(key, input.task_id, d);
+  const dryRun = !input.apply;
+  if (existing) {
+    return {
+      schema_version: LOOP_RUN_TRANSACTION_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: dryRun,
+      processed_at: timestamp,
+      action: "matched",
+      key,
+      run: summarizeTaskRun(existing),
+      warnings: existing.status === "running" ? [] : [`matched ${existing.status} run`],
+      commands: loopRunCommands(existing, key)
+    };
+  }
+  if (dryRun) {
+    return {
+      schema_version: LOOP_RUN_TRANSACTION_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: true,
+      processed_at: timestamp,
+      action: "preview",
+      key,
+      run: null,
+      warnings: [],
+      commands: loopRunCommands(null, key)
+    };
+  }
+  const metadata = redactValue({
+    ...input.metadata || {},
+    loop_transaction: {
+      schema_version: LOOP_RUN_TRANSACTION_SCHEMA_VERSION,
+      idempotency_key: key,
+      loop_id: input.loop_id ?? null,
+      loop_run_id: input.loop_run_id ?? null,
+      first_seen_at: timestamp
+    },
+    idempotency_key: key
+  });
+  const created = d.transaction(() => {
+    d.run(`INSERT OR IGNORE INTO task_run_transactions (
+        id, task_id, run_id, key, loop_id, loop_run_id, metadata, created_at, updated_at
+      ) VALUES (?, ?, NULL, ?, ?, ?, ?, ?, ?)`, [
+      uuid(),
+      input.task_id,
+      key,
+      input.loop_id ?? null,
+      input.loop_run_id ?? null,
+      JSON.stringify(metadata),
+      timestamp,
+      timestamp
+    ]);
+    const transaction = getTaskRunTransactionByKey(key, input.task_id, d);
+    if (!transaction)
+      throw new Error(`Could not create run transaction for key: ${key}`);
+    if (transaction.run_id) {
+      const existingRun = getTaskRun(transaction.run_id, d);
+      if (existingRun)
+        return { run: existingRun, action: "matched" };
+    }
+    const run = startTaskRun({
+      id: uuid(),
+      task_id: input.task_id,
+      agent_id: input.agent_id,
+      title: input.title,
+      summary: input.summary,
+      metadata,
+      claim: input.claim,
+      started_at: timestamp
+    }, d);
+    d.run("UPDATE task_run_transactions SET run_id = ?, loop_id = COALESCE(?, loop_id), loop_run_id = COALESCE(?, loop_run_id), metadata = ?, updated_at = ? WHERE id = ?", [run.id, input.loop_id ?? null, input.loop_run_id ?? null, JSON.stringify(metadata), timestamp, transaction.id]);
+    return { run, action: "created" };
+  })();
+  return {
+    schema_version: LOOP_RUN_TRANSACTION_SCHEMA_VERSION,
+    local_only: true,
+    dry_run: false,
+    processed_at: timestamp,
+    action: created.action,
+    key,
+    run: summarizeTaskRun(created.run),
+    warnings: [],
+    commands: loopRunCommands(created.run, key)
+  };
+}
 function addTaskRunEvent(input, db) {
   const d = db || getDatabase();
   const runId = resolveTaskRunId(input.run_id, d);
@@ -8728,6 +9226,66 @@ function finishTaskRun(input, db) {
   });
   return updated;
 }
+function finishTaskRunTransaction(input, db) {
+  const d = db || getDatabase();
+  const timestamp = input.completed_at || now();
+  const status = input.status || "completed";
+  const key = input.key ? normalizeTransactionKey({ key: input.key }) : "";
+  const run = input.run_id ? getTaskRun(resolveTaskRunId(input.run_id, d), d) : key ? findTaskRunByTransactionKey(key, input.task_id, d) : null;
+  if (!run) {
+    throw new Error(input.run_id ? `Run not found: ${input.run_id}` : "runs finish requires a run id or --key");
+  }
+  if (input.task_id && run.task_id !== input.task_id) {
+    throw new Error(`Run ${run.id} belongs to task ${run.task_id}, not ${input.task_id}`);
+  }
+  const resolvedKey = key || runKey(run) || run.id;
+  const dryRun = input.apply === false;
+  if (run.status !== "running") {
+    const conflict = run.status !== status;
+    return {
+      schema_version: LOOP_RUN_TRANSACTION_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: dryRun,
+      processed_at: timestamp,
+      action: conflict ? "conflict" : "matched",
+      key: resolvedKey,
+      run: summarizeTaskRun(run),
+      warnings: conflict ? [`run is already ${run.status}; requested ${status}`] : [],
+      commands: loopRunCommands(run, resolvedKey)
+    };
+  }
+  if (dryRun) {
+    return {
+      schema_version: LOOP_RUN_TRANSACTION_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: true,
+      processed_at: timestamp,
+      action: "preview",
+      key: resolvedKey,
+      run: summarizeTaskRun({ ...run, status, summary: input.summary ?? run.summary, completed_at: timestamp, updated_at: timestamp }),
+      warnings: [],
+      commands: loopRunCommands(run, resolvedKey)
+    };
+  }
+  const finished = finishTaskRun({
+    run_id: run.id,
+    status,
+    summary: input.summary,
+    agent_id: input.agent_id,
+    completed_at: timestamp
+  }, d);
+  return {
+    schema_version: LOOP_RUN_TRANSACTION_SCHEMA_VERSION,
+    local_only: true,
+    dry_run: false,
+    processed_at: timestamp,
+    action: "finished",
+    key: resolvedKey,
+    run: summarizeTaskRun(finished),
+    warnings: [],
+    commands: loopRunCommands(finished, resolvedKey)
+  };
+}
 function listTaskRuns(taskId, db) {
   const d = db || getDatabase();
   const rows = taskId ? d.query("SELECT * FROM task_runs WHERE task_id = ? ORDER BY started_at DESC, created_at DESC").all(taskId) : d.query("SELECT * FROM task_runs ORDER BY started_at DESC, created_at DESC LIMIT 100").all();
@@ -9741,87 +10299,6 @@ function getCapableAgents(capabilities, opts, db) {
   return opts?.limit ? scored.slice(0, opts.limit) : scored;
 }
 
-// src/db/task-lists.ts
-init_types();
-init_database();
-function rowToTaskList(row) {
-  return {
-    ...row,
-    metadata: JSON.parse(row.metadata || "{}")
-  };
-}
-function createTaskList(input, db) {
-  const d = db || getDatabase();
-  const id = uuid();
-  const timestamp = now();
-  const slug = input.slug || slugify(input.name);
-  if (!input.project_id) {
-    const existing = d.query("SELECT id FROM task_lists WHERE project_id IS NULL AND slug = ?").get(slug);
-    if (existing) {
-      throw new Error(`Standalone task list with slug "${slug}" already exists`);
-    }
-  }
-  d.run(`INSERT INTO task_lists (id, project_id, slug, name, description, metadata, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [id, input.project_id || null, slug, input.name, input.description || null, JSON.stringify(input.metadata || {}), timestamp, timestamp]);
-  return getTaskList(id, d);
-}
-function getTaskList(id, db) {
-  const d = db || getDatabase();
-  const row = d.query("SELECT * FROM task_lists WHERE id = ?").get(id);
-  return row ? rowToTaskList(row) : null;
-}
-function getTaskListBySlug(slug, projectId, db) {
-  const d = db || getDatabase();
-  let row;
-  if (projectId) {
-    row = d.query("SELECT * FROM task_lists WHERE slug = ? AND project_id = ?").get(slug, projectId);
-  } else {
-    row = d.query("SELECT * FROM task_lists WHERE slug = ? AND project_id IS NULL").get(slug);
-  }
-  return row ? rowToTaskList(row) : null;
-}
-function listTaskLists(projectId, db) {
-  const d = db || getDatabase();
-  if (projectId) {
-    return d.query("SELECT * FROM task_lists WHERE project_id = ? ORDER BY name").all(projectId).map(rowToTaskList);
-  }
-  return d.query("SELECT * FROM task_lists ORDER BY name").all().map(rowToTaskList);
-}
-function updateTaskList(id, input, db) {
-  const d = db || getDatabase();
-  const existing = getTaskList(id, d);
-  if (!existing)
-    throw new TaskListNotFoundError(id);
-  const sets = ["updated_at = ?"];
-  const params = [now()];
-  if (input.name !== undefined) {
-    sets.push("name = ?");
-    params.push(input.name);
-  }
-  if (input.description !== undefined) {
-    sets.push("description = ?");
-    params.push(input.description);
-  }
-  if (input.metadata !== undefined) {
-    sets.push("metadata = ?");
-    params.push(JSON.stringify(input.metadata));
-  }
-  params.push(id);
-  d.run(`UPDATE task_lists SET ${sets.join(", ")} WHERE id = ?`, params);
-  return getTaskList(id, d);
-}
-function deleteTaskList(id, db) {
-  const d = db || getDatabase();
-  return d.run("DELETE FROM task_lists WHERE id = ?", [id]).changes > 0;
-}
-function ensureTaskList(name, slug, projectId, db) {
-  const d = db || getDatabase();
-  const existing = getTaskListBySlug(slug, projectId, d);
-  if (existing)
-    return existing;
-  return createTaskList({ name, slug, project_id: projectId }, d);
-}
-
 // src/storage/local-sqlite.ts
 init_database();