@hasna/todos 0.11.58 → 0.11.59

package/dist/index.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,
@@ -3681,6 +3765,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",
@@ -3728,6 +3813,7 @@ var MCP_TOOL_GROUPS = {
     "list_local_snapshots",
     "list_retrospectives",
     "list_risks",
+    "list_task_findings",
     "list_task_runs",
     "list_verification_providers",
     "merge_duplicate_task",
@@ -3736,6 +3822,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",
@@ -3778,9 +3865,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",
@@ -3862,7 +3957,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"],
@@ -4935,6 +5030,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",
@@ -6640,6 +6821,7 @@ var LOCAL_EVENT_TYPES = [
   "task.blocked",
   "task.started",
   "task.completed",
+  "task.updated",
   "task.due",
   "task.due_soon",
   "task.failed",
@@ -7978,6 +8160,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();
@@ -8160,6 +8353,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 {
@@ -8184,6 +8378,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 = [];
@@ -8247,6 +8489,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");
   }
@@ -8297,6 +8540,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));
@@ -8385,6 +8632,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 = {
@@ -8420,6 +8669,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) {
@@ -11115,6 +11368,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 {};
@@ -11137,6 +11391,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}%`);
@@ -11155,7 +11475,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);
@@ -11193,6 +11513,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);
@@ -11372,6 +11783,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();
@@ -17552,7 +18023,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,
@@ -17613,7 +18084,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);
@@ -20084,6 +20555,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",
@@ -28962,6 +29460,7 @@ var READ_ONLY_TOOLS = new Set([
   "describe_tools",
   "search_tools",
   "inspect_git_commit",
+  "list_task_findings",
   "scan_text_for_secrets",
   "check_workspace_permission",
   "check_sandbox_command",
@@ -28987,7 +29486,12 @@ var MINIMAL_TOOLS = new Set([
   "bootstrap",
   "get_tasks_changed_since",
   "heartbeat",
-  "release_agent"
+  "release_agent",
+  "begin_task_run_transaction",
+  "finish_task_run",
+  "upsert_task_finding",
+  "list_task_findings",
+  "resolve_missing_task_findings"
 ]);
 var AGENT_SAFE_TOOLS = new Set([
   ...READ_ONLY_TOOLS,
@@ -41825,6 +42329,353 @@ async function dispatchToMultiple(input, opts = {}, db) {
   }
   return dispatches;
 }
+// src/db/findings.ts
+init_redaction();
+init_types();
+init_database();
+var TASK_FINDING_SCHEMA_VERSION = "todos.task_finding.v1";
+var TASK_FINDING_UPSERT_SCHEMA_VERSION = "todos.task_finding_upsert.v1";
+var TASK_FINDING_RESOLVE_MISSING_SCHEMA_VERSION = "todos.task_finding_resolve_missing.v1";
+var SEVERITIES2 = new Set(["low", "medium", "high", "critical"]);
+var STATUSES = new Set(["open", "resolved", "ignored"]);
+function parseObject4(value) {
+  if (!value)
+    return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function normalizeKey(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9._:/-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function normalizeFingerprint(value) {
+  const normalized = normalizeKey(value);
+  if (!normalized)
+    throw new Error("finding fingerprint is required");
+  return normalized.slice(0, 240);
+}
+function normalizeSeverity2(value) {
+  const normalized = normalizeKey(value || "medium");
+  if (SEVERITIES2.has(normalized))
+    return normalized;
+  if (/^(p0|blocker|urgent|highest)$/.test(normalized))
+    return "critical";
+  if (/^(p1|major)$/.test(normalized))
+    return "high";
+  if (/^(p3|minor|info)$/.test(normalized))
+    return "low";
+  return "medium";
+}
+function normalizeStatus(value) {
+  const normalized = normalizeKey(value || "open");
+  if (STATUSES.has(normalized))
+    return normalized;
+  if (normalized === "closed" || normalized === "fixed")
+    return "resolved";
+  return "open";
+}
+function normalizeResolutionStatus(value) {
+  const status = normalizeStatus(value || "resolved");
+  if (status === "open")
+    throw new Error("resolve-missing status must be resolved or ignored");
+  return status;
+}
+function redactOptional(value, max = 2000) {
+  if (!value)
+    return null;
+  const redacted = redactEvidenceText(value).trim();
+  if (!redacted)
+    return null;
+  return redacted.length > max ? `${redacted.slice(0, max - 3)}...` : redacted;
+}
+function rowToFinding(row) {
+  return {
+    schema_version: TASK_FINDING_SCHEMA_VERSION,
+    ...row,
+    severity: normalizeSeverity2(row.severity),
+    status: normalizeStatus(row.status),
+    metadata: parseObject4(row.metadata)
+  };
+}
+function compactFinding(finding2) {
+  return {
+    schema_version: TASK_FINDING_SCHEMA_VERSION,
+    id: finding2.id,
+    task_id: finding2.task_id,
+    run_id: finding2.run_id,
+    fingerprint: finding2.fingerprint,
+    title: finding2.title,
+    severity: finding2.severity,
+    status: finding2.status,
+    source: finding2.source,
+    summary: finding2.summary,
+    artifact_path: finding2.artifact_path,
+    first_seen_at: finding2.first_seen_at,
+    last_seen_at: finding2.last_seen_at,
+    resolved_at: finding2.resolved_at,
+    metadata_keys: Object.keys(finding2.metadata).sort()
+  };
+}
+function previewFinding(existing, next, timestamp2) {
+  return {
+    ...existing,
+    run_id: next.run_id,
+    title: next.title,
+    severity: next.severity,
+    status: next.status,
+    source: next.source,
+    summary: next.summary,
+    artifact_path: next.artifact_path,
+    metadata: next.metadata,
+    last_seen_at: timestamp2,
+    resolved_at: next.status === "open" ? null : existing.resolved_at || timestamp2,
+    updated_at: timestamp2
+  };
+}
+function upsertAction(existing, next) {
+  if (sameFinding(existing, next))
+    return "matched";
+  return existing.status !== "open" && next.status === "open" ? "reopened" : "updated";
+}
+function resolveRunForTask(runId, taskId, db) {
+  if (!runId)
+    return null;
+  const resolved = resolveTaskRunId(runId, db);
+  const run = getTaskRun(resolved, db);
+  if (!run)
+    throw new Error(`Run not found: ${runId}`);
+  if (run.task_id !== taskId)
+    throw new Error(`Run ${resolved} belongs to task ${run.task_id}, not ${taskId}`);
+  return resolved;
+}
+function getFindingByFingerprint(taskId, fingerprint4, db) {
+  const row = db.query("SELECT * FROM task_findings WHERE task_id = ? AND fingerprint = ?").get(taskId, fingerprint4);
+  return row ? rowToFinding(row) : null;
+}
+function assertTask(taskId, db) {
+  if (!getTask(taskId, db))
+    throw new TaskNotFoundError(taskId);
+}
+function nextFinding(input, db) {
+  const fingerprint4 = normalizeFingerprint(input.fingerprint);
+  const title = redactOptional(input.title, 300);
+  if (!title)
+    throw new Error("finding title is required");
+  return {
+    fingerprint: fingerprint4,
+    run_id: resolveRunForTask(input.run_id, input.task_id, db),
+    title,
+    severity: normalizeSeverity2(input.severity),
+    status: normalizeStatus(input.status),
+    source: redactOptional(input.source, 120),
+    summary: redactOptional(input.summary, 2000),
+    artifact_path: redactOptional(input.artifact_path, 1000),
+    metadata: redactValue(input.metadata || {})
+  };
+}
+function sameFinding(left, right) {
+  return left.run_id === right.run_id && left.title === right.title && left.severity === right.severity && left.status === right.status && left.source === right.source && left.summary === right.summary && left.artifact_path === right.artifact_path && JSON.stringify(left.metadata) === JSON.stringify(right.metadata);
+}
+function upsertTaskFinding(input, db) {
+  const d = db || getDatabase();
+  assertTask(input.task_id, d);
+  const timestamp2 = input.observed_at || now();
+  const warnings = [];
+  const next = nextFinding(input, d);
+  const existing = getFindingByFingerprint(input.task_id, next.fingerprint, d);
+  const dryRun = !input.apply;
+  if (dryRun) {
+    const action2 = existing ? upsertAction(existing, next) : "preview";
+    return {
+      schema_version: TASK_FINDING_UPSERT_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: true,
+      processed_at: timestamp2,
+      action: action2,
+      fingerprint: next.fingerprint,
+      finding: existing ? compactFinding(previewFinding(existing, next, timestamp2)) : null,
+      warnings
+    };
+  }
+  if (!existing) {
+    const id = uuid();
+    d.run(`INSERT INTO task_findings (
+        id, task_id, run_id, fingerprint, title, severity, status, source, summary, artifact_path,
+        metadata, first_seen_at, last_seen_at, resolved_at, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      input.task_id,
+      next.run_id,
+      next.fingerprint,
+      next.title,
+      next.severity,
+      next.status,
+      next.source,
+      next.summary,
+      next.artifact_path,
+      JSON.stringify(next.metadata),
+      timestamp2,
+      timestamp2,
+      next.status === "open" ? null : timestamp2,
+      timestamp2,
+      timestamp2
+    ]);
+    return {
+      schema_version: TASK_FINDING_UPSERT_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: false,
+      processed_at: timestamp2,
+      action: "created",
+      fingerprint: next.fingerprint,
+      finding: compactFinding(getFindingByFingerprint(input.task_id, next.fingerprint, d)),
+      warnings
+    };
+  }
+  if (sameFinding(existing, next)) {
+    return {
+      schema_version: TASK_FINDING_UPSERT_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: false,
+      processed_at: timestamp2,
+      action: "matched",
+      fingerprint: next.fingerprint,
+      finding: compactFinding(existing),
+      warnings
+    };
+  }
+  const action = upsertAction(existing, next);
+  d.run(`UPDATE task_findings SET
+      run_id = ?, title = ?, severity = ?, status = ?, source = ?, summary = ?, artifact_path = ?,
+      metadata = ?, last_seen_at = ?, resolved_at = ?, updated_at = ?
+     WHERE id = ?`, [
+    next.run_id,
+    next.title,
+    next.severity,
+    next.status,
+    next.source,
+    next.summary,
+    next.artifact_path,
+    JSON.stringify(next.metadata),
+    timestamp2,
+    next.status === "open" ? null : existing.resolved_at || timestamp2,
+    timestamp2,
+    existing.id
+  ]);
+  return {
+    schema_version: TASK_FINDING_UPSERT_SCHEMA_VERSION,
+    local_only: true,
+    dry_run: false,
+    processed_at: timestamp2,
+    action,
+    fingerprint: next.fingerprint,
+    finding: compactFinding(getFindingByFingerprint(input.task_id, next.fingerprint, d)),
+    warnings
+  };
+}
+function listTaskFindings(filter = {}, db) {
+  const d = db || getDatabase();
+  const conditions = ["1=1"];
+  const params = [];
+  if (filter.task_id) {
+    conditions.push("task_id = ?");
+    params.push(filter.task_id);
+  }
+  if (filter.run_id) {
+    conditions.push("run_id = ?");
+    params.push(resolveTaskRunId(filter.run_id, d));
+  }
+  if (filter.status) {
+    conditions.push("status = ?");
+    params.push(normalizeStatus(filter.status));
+  }
+  if (filter.source) {
+    conditions.push("source = ?");
+    params.push(redactOptional(filter.source, 120));
+  }
+  const limit = Math.min(Math.max(Math.floor(filter.limit ?? 50), 1), 500);
+  const rows = d.query(`SELECT * FROM task_findings WHERE ${conditions.join(" AND ")} ORDER BY updated_at DESC, created_at DESC LIMIT ?`).all(...[...params, limit]);
+  return rows.map(rowToFinding);
+}
+function listCompactTaskFindings(filter = {}, db) {
+  return listTaskFindings(filter, db).map(compactFinding);
+}
+function resolveMissingTaskFindings(input, db) {
+  const d = db || getDatabase();
+  assertTask(input.task_id, d);
+  const timestamp2 = input.resolved_at || now();
+  const status = normalizeResolutionStatus(input.status);
+  const runId = resolveRunForTask(input.run_id, input.task_id, d);
+  const present = new Set(input.fingerprints.map(normalizeFingerprint));
+  const warnings = [];
+  const conditions = ["task_id = ?", "status = 'open'"];
+  const params = [input.task_id];
+  if (input.source) {
+    conditions.push("source = ?");
+    params.push(redactOptional(input.source, 120));
+  }
+  const candidates = d.query(`SELECT * FROM task_findings WHERE ${conditions.join(" AND ")} ORDER BY updated_at DESC, created_at DESC`).all(...params).map(rowToFinding).filter((finding2) => !present.has(finding2.fingerprint));
+  const limit = Math.min(Math.max(Math.floor(input.limit ?? 50), 1), 200);
+  const display = candidates.slice(0, limit);
+  const omittedCount = Math.max(0, candidates.length - display.length);
+  if (!input.apply) {
+    return {
+      schema_version: TASK_FINDING_RESOLVE_MISSING_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: true,
+      processed_at: timestamp2,
+      action: candidates.length > 0 ? "preview" : "noop",
+      task_id: input.task_id,
+      source: input.source ? redactOptional(input.source, 120) : null,
+      run_id: runId,
+      present_fingerprint_count: present.size,
+      candidate_count: candidates.length,
+      changed_count: 0,
+      omitted_count: omittedCount,
+      findings: display.map(compactFinding),
+      warnings
+    };
+  }
+  const metadataPatch = redactValue({
+    resolved_by: {
+      agent_id: input.agent_id ?? null,
+      run_id: runId,
+      reason: input.reason ? redactEvidenceText(input.reason) : "missing from latest loop finding set"
+    }
+  });
+  const tx = d.transaction(() => {
+    for (const finding2 of candidates) {
+      d.run("UPDATE task_findings SET status = ?, resolved_at = ?, metadata = ?, updated_at = ? WHERE id = ? AND status = 'open'", [
+        status,
+        timestamp2,
+        JSON.stringify({ ...finding2.metadata, ...metadataPatch }),
+        timestamp2,
+        finding2.id
+      ]);
+    }
+  });
+  tx();
+  const updated = candidates.map((finding2) => d.query("SELECT * FROM task_findings WHERE id = ?").get(finding2.id)).filter((row) => Boolean(row)).map(rowToFinding);
+  const visibleUpdated = updated.slice(0, limit);
+  return {
+    schema_version: TASK_FINDING_RESOLVE_MISSING_SCHEMA_VERSION,
+    local_only: true,
+    dry_run: false,
+    processed_at: timestamp2,
+    action: updated.length > 0 ? status : "noop",
+    task_id: input.task_id,
+    source: input.source ? redactOptional(input.source, 120) : null,
+    run_id: runId,
+    present_fingerprint_count: present.size,
+    candidate_count: candidates.length,
+    changed_count: updated.length,
+    omitted_count: omittedCount,
+    findings: visibleUpdated.map(compactFinding),
+    warnings
+  };
+}
 
 // src/index.ts
 init_redaction();
@@ -43155,6 +44006,8 @@ export {
   upsertTesterIssueReports,
   upsertTesterIssueReport,
   upsertTerminalNotificationRule,
+  upsertTaskFinding,
+  upsertTaskByFingerprint,
   upsertSecretSafetyConfig,
   upsertRunnerSandboxProfile,
   upsertReviewRoutingRule,
@@ -43204,6 +44057,7 @@ export {
   syncWithAgent,
   syncKgEdges,
   supersedeDecisionRecord,
+  summarizeTaskRun,
   summarizeRoadmap,
   summarizeMilestone,
   suggestAgentNames,
@@ -43281,6 +44135,7 @@ export {
   resolvePlanRef,
   resolvePlanId,
   resolvePartialId,
+  resolveMissingTaskFindings,
   resolveMentions,
   resolveGitRoot,
   resolveCommandQuery,
@@ -43455,6 +44310,7 @@ export {
   listTasks,
   listTaskRuns,
   listTaskLists,
+  listTaskFindings,
   listTaskFiles,
   listTaskBoards,
   listSubscriptions,
@@ -43507,6 +44363,7 @@ export {
   listCyclesWithStats,
   listCycles,
   listCustomFieldDefinitions,
+  listCompactTaskFindings,
   listComments,
   listCommandAliases,
   listCapacityProfiles,
@@ -43613,6 +44470,7 @@ export {
   getTaskCustomFields,
   getTaskContract,
   getTaskCommits,
+  getTaskByFingerprint,
   getTaskBoard,
   getTask,
   getStoredHandoffAsPacket,
@@ -43792,10 +44650,12 @@ export {
   formatDecisionRecordMarkdown,
   formatAgentWorkflowDemoReport,
   formatActivityRecordText,
+  finishTaskRunTransaction,
   finishTaskRun,
   fingerprintTesterIssueReport,
   fingerprintInboxInput,
   findTasksByFile,
+  findTaskRunByTransactionKey,
   findTaskByCommit,
   findRelatedTaskIds,
   findPath,
@@ -44017,6 +44877,7 @@ export {
   buildCodebaseIndex,
   buildArtifactExportManifest,
   bootstrapProject,
+  beginTaskRunTransaction,
   backupDatabase,
   autoReleaseStaleAgents,
   autoDetectFileRelationships,
@@ -44102,6 +44963,9 @@ export {
   TASK_STATUSES,
   TASK_SCHEDULING_SCHEMA,
   TASK_PRIORITIES,
+  TASK_FINDING_UPSERT_SCHEMA_VERSION,
+  TASK_FINDING_SCHEMA_VERSION,
+  TASK_FINDING_RESOLVE_MISSING_SCHEMA_VERSION,
   STORAGE_TABLES,
   SECRET_REDACTION_SCHEMA,
   SCHEMA_SEMVER,
@@ -44138,6 +45002,7 @@ export {
   MANPAGE_SCHEMA,
   MACHINE_TOPOLOGY_SCHEMA,
   LockError,
+  LOOP_RUN_TRANSACTION_SCHEMA_VERSION,
   LOCAL_USAGE_LEDGER_SCHEMA_VERSION,
   LOCAL_ROADMAP_SCHEMA_VERSION,
   LOCAL_REPORT_TYPES,