@hasna/todos 0.11.58 → 0.11.60

package/dist/contracts.js

@@ -1139,6 +1139,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);
   `
   ];
 });
@@ -1576,6 +1619,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,
@@ -3576,6 +3660,7 @@ var MCP_TOOL_GROUPS = {
     "add_task_run_event",
     "add_task_run_file",
     "acknowledge_handoff",
+    "begin_task_run_transaction",
     "build_local_report",
     "cancel_agent_run_dispatch",
     "finish_task_run",
@@ -3623,6 +3708,7 @@ var MCP_TOOL_GROUPS = {
     "list_local_snapshots",
     "list_retrospectives",
     "list_risks",
+    "list_task_findings",
     "list_task_runs",
     "list_verification_providers",
     "merge_duplicate_task",
@@ -3631,6 +3717,7 @@ var MCP_TOOL_GROUPS = {
     "remove_review_routing_rule",
     "restore_local_backup",
     "retry_agent_run_dispatch",
+    "resolve_missing_task_findings",
     "resolve_mentions",
     "run_next_agent_dispatch",
     "search_knowledge_records",
@@ -3673,9 +3760,17 @@ var MCP_TOOL_GROUPS = {
     "unlock_file",
     "unwatch_task",
     "update_comment",
+    "upsert_task_finding",
     "update_risk",
     "watch_task"
   ],
+  loops: [
+    "begin_task_run_transaction",
+    "finish_task_run",
+    "list_task_findings",
+    "resolve_missing_task_findings",
+    "upsert_task_finding"
+  ],
   agents: [
     "auto_assign_task",
     "delete_agent",
@@ -3757,7 +3852,7 @@ var MCP_TOOL_GROUPS = {
   maintenance: ["extract_todos", "get_sla_breaches", "notify_upcoming_deadlines", "run_doctor", "score_task", "watch_source_todos"]
 };
 var MCP_PROFILE_GROUPS = {
-  minimal: ["core"],
+  minimal: ["core", "loops"],
   core: ["core"],
   standard: ["core", "tasks", "projects", "resources", "agents", "metadata"],
   agent: ["core", "tasks", "projects", "resources"],
@@ -4830,6 +4925,92 @@ var TODOS_JSON_CONTRACTS = [
     },
     optional: {}
   }),
+  contract({
+    id: "loop_run_transaction",
+    name: "Loop Run Transaction",
+    description: "Compact local result for idempotent loop run begin/finish transactions.",
+    surfaces: ["cli", "mcp", "sdk"],
+    stability: "stable",
+    required: {
+      schema_version: field("string", "Result schema version."),
+      local_only: field("boolean", "Always true; loop run transactions use local state."),
+      dry_run: field("boolean", "True when no run ledger mutation was applied."),
+      processed_at: isoDateField,
+      action: field("string", "preview, created, matched, finished, or conflict."),
+      key: field("string", "Stable idempotency key used to dedupe the transaction."),
+      run: field(["object", "null"], "Compact run summary or null for create previews.", true),
+      warnings: field("array", "Non-fatal warnings such as terminal-status conflicts."),
+      commands: field("array", "Follow-up CLI commands for agents and operators.")
+    },
+    optional: {}
+  }),
+  contract({
+    id: "task_finding",
+    name: "Task Finding",
+    description: "Compact local finding record deduped by task and fingerprint.",
+    surfaces: ["cli", "mcp", "sdk"],
+    stability: "stable",
+    required: {
+      schema_version: field("string", "Finding schema version."),
+      id: idField,
+      task_id: idField,
+      run_id: field(["string", "null"], "Optional run ledger ID.", true),
+      fingerprint: field("string", "Stable finding fingerprint scoped to the task."),
+      title: field("string", "Short redacted finding title."),
+      severity: field("string", "low, medium, high, or critical."),
+      status: field("string", "open, resolved, or ignored."),
+      source: field(["string", "null"], "Optional loop/tool source.", true),
+      summary: field(["string", "null"], "Bounded redacted finding summary.", true),
+      artifact_path: field(["string", "null"], "Local artifact path/reference; raw content is not included.", true),
+      first_seen_at: isoDateField,
+      last_seen_at: isoDateField,
+      resolved_at: field(["string", "null"], "Resolution timestamp when closed.", true),
+      metadata_keys: field("array", "Sorted metadata keys; metadata values are intentionally omitted in compact output.")
+    },
+    optional: {}
+  }),
+  contract({
+    id: "task_finding_upsert",
+    name: "Task Finding Upsert Result",
+    description: "Local-only dry-run or applied result from idempotently upserting a task finding.",
+    surfaces: ["cli", "mcp", "sdk"],
+    stability: "stable",
+    required: {
+      schema_version: field("string", "Result schema version."),
+      local_only: field("boolean", "Always true; finding upserts use local state."),
+      dry_run: field("boolean", "True when no finding row was created or updated."),
+      processed_at: isoDateField,
+      action: field("string", "preview, created, matched, updated, or reopened."),
+      fingerprint: field("string", "Normalized finding fingerprint."),
+      finding: field(["object", "null"], "Compact finding summary or null for create previews.", true),
+      warnings: field("array", "Non-fatal warnings.")
+    },
+    optional: {}
+  }),
+  contract({
+    id: "task_finding_resolve_missing",
+    name: "Task Finding Resolve Missing Result",
+    description: "Local-only dry-run or applied result from resolving open findings absent from the latest loop finding set.",
+    surfaces: ["cli", "mcp", "sdk"],
+    stability: "stable",
+    required: {
+      schema_version: field("string", "Result schema version."),
+      local_only: field("boolean", "Always true; finding resolution uses local state."),
+      dry_run: field("boolean", "True when no finding rows were changed."),
+      processed_at: isoDateField,
+      action: field("string", "preview, resolved, ignored, or noop."),
+      task_id: idField,
+      source: field(["string", "null"], "Optional source scope.", true),
+      run_id: field(["string", "null"], "Optional run ledger ID used for audit metadata.", true),
+      present_fingerprint_count: field("integer", "Number of fingerprints supplied as still present."),
+      candidate_count: field("integer", "Open findings missing from the supplied set."),
+      changed_count: field("integer", "Rows resolved or ignored by the applied transaction."),
+      omitted_count: field("integer", "Matching findings omitted from bounded output."),
+      findings: field("array", "Bounded compact finding summaries."),
+      warnings: field("array", "Non-fatal warnings.")
+    },
+    optional: {}
+  }),
   contract({
     id: "verification_provider",
     name: "Verification Provider",
@@ -6535,6 +6716,7 @@ var LOCAL_EVENT_TYPES = [
   "task.blocked",
   "task.started",
   "task.completed",
+  "task.updated",
   "task.due",
   "task.due_soon",
   "task.failed",
@@ -6773,7 +6955,7 @@ async function testLocalEventHook(name, input) {
   return emitLocalEventHooks({ ...input, hooks: [hook] });
 }
 
-// node_modules/.bun/@hasna+events@0.1.9/node_modules/@hasna/events/dist/index.js
+// node_modules/.bun/@hasna+events@0.1.10/node_modules/@hasna/events/dist/index.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { existsSync as existsSync6 } from "fs";
 import { homedir } from "os";
@@ -6820,14 +7002,40 @@ function matchRecord(input, matcher) {
     return true;
   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, {
-        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
-      });
-    }
-    return actual === expected;
+    return matchField(actual, expected, path);
   });
 }
+function matchField(actual, expected, path) {
+  if (isNegativeMatcher(expected)) {
+    return !matchPositiveField(actual, expected.not, path);
+  }
+  return matchPositiveField(actual, expected, path);
+}
+function matchPositiveField(actual, expected, path) {
+  if (typeof expected === "string" || Array.isArray(expected)) {
+    return stringCandidates(actual).some((candidate) => matchString(candidate, expected, {
+      segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+    }));
+  }
+  if (Array.isArray(actual)) {
+    return actual.some((item) => item === expected);
+  }
+  return actual === expected;
+}
+function stringCandidates(actual) {
+  if (actual === undefined)
+    return [];
+  if (Array.isArray(actual)) {
+    return actual.flatMap((item) => isPrimitiveFieldValue(item) ? [String(item)] : []);
+  }
+  return [String(actual)];
+}
+function isPrimitiveFieldValue(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isNegativeMatcher(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && "not" in value);
+}
 function eventMatchesFilter(event, filter) {
   return matchString(event.source, filter.source) && matchString(event.type, filter.type) && matchString(event.subject, filter.subject) && matchString(event.severity, filter.severity) && matchRecord(event.data, filter.data) && matchRecord(event.metadata, filter.metadata);
 }
@@ -7434,9 +7642,66 @@ function taskEventData(task, extra = {}) {
     started_at: task.started_at,
     completed_at: task.completed_at,
     due_at: task.due_at,
+    requires_approval: task.requires_approval,
+    approved_by: task.approved_by,
+    approved_at: task.approved_at,
     ...extra
   };
 }
+function booleanField(value) {
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "number") {
+    if (value === 1)
+      return true;
+    if (value === 0)
+      return false;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "on"].includes(normalized))
+      return true;
+    if (["false", "0", "no", "off"].includes(normalized))
+      return false;
+  }
+  return;
+}
+function objectField(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function firstBoolean(records, keys) {
+  for (const record of records) {
+    for (const key of keys) {
+      const value = booleanField(record[key]);
+      if (value !== undefined)
+        return value;
+    }
+  }
+  return;
+}
+function routingAutomationMetadata(task) {
+  const automation = objectField(task.metadata.automation);
+  const records = [task.metadata];
+  if (automation)
+    records.push(automation);
+  const result = {};
+  const aliases = [
+    ["allowed", ["allowed", "automation_allowed", "automationAllowed"]],
+    ["no_auto", ["no_auto", "noAuto"]],
+    ["manual", ["manual"]],
+    ["manual_required", ["manual_required", "manualRequired"]],
+    ["requires_approval", ["requires_approval", "requiresApproval"]],
+    ["approval_required", ["approval_required", "approvalRequired"]]
+  ];
+  for (const [canonical, keys] of aliases) {
+    const value = firstBoolean(records, keys);
+    if (value !== undefined)
+      result[canonical] = value;
+  }
+  if (task.requires_approval)
+    result.requires_approval = true;
+  return Object.keys(result).length > 0 ? result : undefined;
+}
 function taskEventMetadata(task) {
   const metadata = {
     package: "@hasna/todos",
@@ -7447,6 +7712,14 @@ function taskEventMetadata(task) {
     task_list_id: task.task_list_id,
     working_dir: task.working_dir
   };
+  const routeEnabled = booleanField(task.metadata.route_enabled);
+  if (routeEnabled !== undefined) {
+    metadata.route_enabled = routeEnabled;
+  }
+  const automation = routingAutomationMetadata(task);
+  if (automation) {
+    metadata.automation = automation;
+  }
   try {
     const project = task.project_id ? getProject(task.project_id) : null;
     const projectPath = project ? readMachineLocalPath(project) ?? project.path : task.working_dir;
@@ -7464,9 +7737,6 @@ function taskEventMetadata(task) {
     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;
@@ -7873,6 +8143,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();
@@ -8055,6 +8336,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 {
@@ -8079,6 +8361,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 = [];
@@ -8142,6 +8472,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");
   }
@@ -8192,6 +8523,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));
@@ -8280,6 +8615,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 = {
@@ -8315,6 +8652,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) {
@@ -11010,6 +11351,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 {};
@@ -11032,6 +11374,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}%`);
@@ -11050,7 +11458,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);
@@ -11088,6 +11496,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);
@@ -11267,6 +11766,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();
@@ -17447,7 +18006,7 @@ function countMovedStandaloneVerifications(db, duplicateId) {
   const rows = db.query("SELECT command FROM task_verifications WHERE task_id = ?").all(duplicateId);
   return rows.filter((row) => !generatedCommands.has(row.command)).length;
 }
-function mergeTaskMetadata(primary, duplicate, input, mergedAt) {
+function mergeTaskMetadata2(primary, duplicate, input, mergedAt) {
   const mergedDuplicates = Array.isArray(primary.metadata["merged_duplicates"]) ? [...primary.metadata["merged_duplicates"]] : [];
   mergedDuplicates.push({
     id: duplicate.id,
@@ -17508,7 +18067,7 @@ function mergeDuplicateTask(input, db) {
     updateTask(primary.id, {
       version: primary.version,
       tags: mergedTags,
-      metadata: mergeTaskMetadata(primary, duplicate, input, mergedAt),
+      metadata: mergeTaskMetadata2(primary, duplicate, input, mergedAt),
       description: mergeTaskDescription(primary, duplicate) ?? undefined
     }, d);
     moved.comments = updateRows(d, "task_comments", "task_id", duplicate.id, primary.id);
@@ -19979,6 +20538,33 @@ var TODOS_API_ROUTES = [
     tags: ["tasks", "mutation"],
     stability: "stable"
   },
+  {
+    id: "tasks.upsert",
+    method: "POST",
+    path: "/api/tasks/upsert",
+    description: "Create or update a task by stable metadata fingerprint, merging metadata on updates.",
+    auth: "optional-api-key",
+    requestSchema: {
+      type: "object",
+      properties: {
+        fingerprint: { type: "string" },
+        title: { type: "string" },
+        description: { type: "string" },
+        priority: { type: "string", enum: TASK_PRIORITIES },
+        status: { type: "string", enum: TASK_STATUSES },
+        project_id: { type: "string" },
+        task_list_id: { type: "string" },
+        working_dir: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+        metadata: objectSchema
+      },
+      required: ["fingerprint", "title"],
+      additionalProperties: true
+    },
+    responseSchema: objectSchema,
+    tags: ["tasks", "mutation", "dedupe"],
+    stability: "stable"
+  },
   {
     id: "tasks.read",
     method: "GET",