@hasna/todos 0.11.58 → 0.11.60

package/dist/mcp/index.js

@@ -1140,6 +1140,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);
   `
   ];
 });
@@ -1577,6 +1620,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,
@@ -8633,6 +8717,7 @@ var init_event_hooks = __esm(() => {
     "task.blocked",
     "task.started",
     "task.completed",
+    "task.updated",
     "task.due",
     "task.due_soon",
     "task.failed",
@@ -8653,7 +8738,7 @@ var init_event_hooks = __esm(() => {
   VALID_TARGETS = new Set(["stdout", "file", "socket", "script"]);
 });
 
-// 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 existsSync5 } from "fs";
 import { homedir } from "os";
@@ -8700,14 +8785,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);
 }
@@ -9315,9 +9426,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",
@@ -9328,6 +9496,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;
@@ -9345,9 +9521,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;
@@ -9929,6 +10102,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();
@@ -10111,6 +10295,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 {
@@ -10135,6 +10320,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 = [];
@@ -10198,6 +10431,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");
   }
@@ -10248,6 +10482,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));
@@ -10336,6 +10574,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 = {
@@ -10371,6 +10611,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) {
@@ -13388,6 +13632,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}%`);
@@ -13406,7 +13716,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);
@@ -13444,6 +13754,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);
@@ -13623,6 +14024,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();
@@ -13640,6 +14101,7 @@ function getTaskRunLedger(runId, db) {
   const files = d.query("SELECT * FROM task_files WHERE task_id = ? ORDER BY updated_at DESC, path").all(run.task_id);
   return { run, events, commands, artifacts, files };
 }
+var LOOP_RUN_TRANSACTION_SCHEMA_VERSION = "todos.loop_run_transaction.v1";
 var init_task_runs = __esm(() => {
   init_artifact_store();
   init_event_hooks();
@@ -14028,6 +14490,7 @@ var init_calendar = __esm(() => {
 var exports_tasks = {};
 __export(exports_tasks, {
   watchTask: () => watchTask,
+  upsertTaskByFingerprint: () => upsertTaskByFingerprint,
   updateTaskBoard: () => updateTaskBoard,
   updateTask: () => updateTask,
   unwatchTask: () => unwatchTask,
@@ -14071,6 +14534,7 @@ __export(exports_tasks, {
   getTaskGraph: () => getTaskGraph,
   getTaskDependents: () => getTaskDependents,
   getTaskDependencies: () => getTaskDependencies,
+  getTaskByFingerprint: () => getTaskByFingerprint,
   getTaskBoard: () => getTaskBoard,
   getTask: () => getTask,
   getStatus: () => getStatus,
@@ -14917,6 +15381,7 @@ var init_token_utils = __esm(() => {
       "add_task_run_event",
       "add_task_run_file",
       "acknowledge_handoff",
+      "begin_task_run_transaction",
       "build_local_report",
       "cancel_agent_run_dispatch",
       "finish_task_run",
@@ -14964,6 +15429,7 @@ var init_token_utils = __esm(() => {
       "list_local_snapshots",
       "list_retrospectives",
       "list_risks",
+      "list_task_findings",
       "list_task_runs",
       "list_verification_providers",
       "merge_duplicate_task",
@@ -14972,6 +15438,7 @@ var init_token_utils = __esm(() => {
       "remove_review_routing_rule",
       "restore_local_backup",
       "retry_agent_run_dispatch",
+      "resolve_missing_task_findings",
       "resolve_mentions",
       "run_next_agent_dispatch",
       "search_knowledge_records",
@@ -15014,9 +15481,17 @@ var init_token_utils = __esm(() => {
       "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",
@@ -15098,7 +15573,7 @@ var init_token_utils = __esm(() => {
     maintenance: ["extract_todos", "get_sla_breaches", "notify_upcoming_deadlines", "run_doctor", "score_task", "watch_source_todos"]
   };
   MCP_PROFILE_GROUPS = {
-    minimal: ["core"],
+    minimal: ["core", "loops"],
     core: ["core"],
     standard: ["core", "tasks", "projects", "resources", "agents", "metadata"],
     agent: ["core", "tasks", "projects", "resources"],
@@ -15178,6 +15653,61 @@ function registerTaskCrudTools(server, ctx) {
       }
     });
   }
+  if (shouldRegisterTool("upsert_task")) {
+    server.tool("upsert_task", "Create or update a task by stable metadata fingerprint. Metadata is shallow-merged on updates.", {
+      fingerprint: exports_external.string().describe("Stable dedupe fingerprint stored as metadata.fingerprint"),
+      title: exports_external.string().describe("Task title"),
+      description: exports_external.string().optional().describe("Task description"),
+      status: exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]).optional(),
+      priority: exports_external.enum(["low", "medium", "high", "critical"]).optional(),
+      project_id: exports_external.string().optional().describe("Project ID"),
+      task_list_id: exports_external.string().optional().describe("Task list ID"),
+      assigned_to: exports_external.string().optional().describe("Agent ID or name to assign to"),
+      tags: exports_external.array(exports_external.string()).optional().describe("Tags for the task"),
+      working_dir: exports_external.string().optional().describe("Working directory associated with the task"),
+      metadata: exports_external.record(exports_external.unknown()).optional().describe("Metadata object to shallow-merge"),
+      expectation_id: exports_external.string().optional(),
+      expectation_fingerprint: exports_external.string().optional(),
+      evidence_paths: exports_external.array(exports_external.string()).optional(),
+      origin_loop_id: exports_external.string().optional(),
+      origin_run_id: exports_external.string().optional(),
+      expected: exports_external.unknown().optional(),
+      observed: exports_external.unknown().optional(),
+      acceptance: exports_external.unknown().optional()
+    }, async (params) => {
+      try {
+        const { assigned_to, project_id, task_list_id, metadata, expectation_id, expectation_fingerprint, evidence_paths, origin_loop_id, origin_run_id, expected, observed, acceptance, ...rest } = params;
+        const mergedMetadata = { ...metadata ?? {} };
+        if (expectation_id !== undefined)
+          mergedMetadata["expectation_id"] = expectation_id;
+        if (expectation_fingerprint !== undefined)
+          mergedMetadata["expectation_fingerprint"] = expectation_fingerprint;
+        if (evidence_paths !== undefined)
+          mergedMetadata["evidence_paths"] = evidence_paths;
+        if (origin_loop_id !== undefined)
+          mergedMetadata["origin_loop_id"] = origin_loop_id;
+        if (origin_run_id !== undefined)
+          mergedMetadata["origin_run_id"] = origin_run_id;
+        if (expected !== undefined)
+          mergedMetadata["expected"] = expected;
+        if (observed !== undefined)
+          mergedMetadata["observed"] = observed;
+        if (acceptance !== undefined)
+          mergedMetadata["acceptance"] = acceptance;
+        const resolved = { ...rest, metadata: mergedMetadata };
+        if (assigned_to)
+          resolved.assigned_to = resolveAssignee(assigned_to);
+        if (project_id)
+          resolved.project_id = resolveId(project_id, "projects");
+        if (task_list_id)
+          resolved.task_list_id = resolveId(task_list_id, "task_lists");
+        const result = upsertTaskByFingerprint(resolved);
+        return { content: [{ type: "text", text: compactJson({ created: result.created, task: JSON.parse(mutationTaskResponse(result.task)) }) }] };
+      } catch (e) {
+        return { content: [{ type: "text", text: formatError(e) }], isError: true };
+      }
+    });
+  }
   if (shouldRegisterTool("list_tasks")) {
     server.tool("list_tasks", "List tasks with optional filters. Pass empty arrays for multi-value filters (e.g. status=[] shows all).", {
       status: exports_external.union([exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]), exports_external.array(exports_external.enum(["pending", "in_progress", "completed", "failed", "cancelled"]))]).optional().describe("Filter by status"),
@@ -15189,7 +15719,8 @@ function registerTaskCrudTools(server, ctx) {
       created_after: exports_external.string().optional().describe("ISO date \u2014 tasks created after this date"),
       created_before: exports_external.string().optional().describe("ISO date \u2014 tasks created before this date"),
       limit: exports_external.number().optional().describe("Max results (default: 50, max 500)"),
-      offset: exports_external.number().optional().describe("Pagination offset")
+      offset: exports_external.number().optional().describe("Pagination offset"),
+      metadata: exports_external.record(exports_external.unknown()).optional().describe("Exact top-level metadata filters")
     }, async (params) => {
       try {
         const resolved = { ...params };
@@ -18730,7 +19261,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,
@@ -18791,7 +19322,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);
@@ -25588,6 +26119,356 @@ var init_task_meta_tools = __esm(() => {
   init_zod();
 });
 
+// src/db/findings.ts
+function parseObject2(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 normalizeSeverity(value) {
+  const normalized = normalizeKey(value || "medium");
+  if (SEVERITIES.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: normalizeSeverity(row.severity),
+    status: normalizeStatus(row.status),
+    metadata: parseObject2(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, timestamp3) {
+  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: timestamp3,
+    resolved_at: next.status === "open" ? null : existing.resolved_at || timestamp3,
+    updated_at: timestamp3
+  };
+}
+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, fingerprint2, db) {
+  const row = db.query("SELECT * FROM task_findings WHERE task_id = ? AND fingerprint = ?").get(taskId, fingerprint2);
+  return row ? rowToFinding(row) : null;
+}
+function assertTask(taskId, db) {
+  if (!getTask(taskId, db))
+    throw new TaskNotFoundError(taskId);
+}
+function nextFinding(input, db) {
+  const fingerprint2 = normalizeFingerprint(input.fingerprint);
+  const title = redactOptional(input.title, 300);
+  if (!title)
+    throw new Error("finding title is required");
+  return {
+    fingerprint: fingerprint2,
+    run_id: resolveRunForTask(input.run_id, input.task_id, db),
+    title,
+    severity: normalizeSeverity(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 timestamp3 = 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: timestamp3,
+      action: action2,
+      fingerprint: next.fingerprint,
+      finding: existing ? compactFinding(previewFinding(existing, next, timestamp3)) : 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),
+      timestamp3,
+      timestamp3,
+      next.status === "open" ? null : timestamp3,
+      timestamp3,
+      timestamp3
+    ]);
+    return {
+      schema_version: TASK_FINDING_UPSERT_SCHEMA_VERSION,
+      local_only: true,
+      dry_run: false,
+      processed_at: timestamp3,
+      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: timestamp3,
+      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),
+    timestamp3,
+    next.status === "open" ? null : existing.resolved_at || timestamp3,
+    timestamp3,
+    existing.id
+  ]);
+  return {
+    schema_version: TASK_FINDING_UPSERT_SCHEMA_VERSION,
+    local_only: true,
+    dry_run: false,
+    processed_at: timestamp3,
+    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 timestamp3 = 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: timestamp3,
+      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,
+        timestamp3,
+        JSON.stringify({ ...finding2.metadata, ...metadataPatch }),
+        timestamp3,
+        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: timestamp3,
+    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
+  };
+}
+var TASK_FINDING_SCHEMA_VERSION = "todos.task_finding.v1", TASK_FINDING_UPSERT_SCHEMA_VERSION = "todos.task_finding_upsert.v1", TASK_FINDING_RESOLVE_MISSING_SCHEMA_VERSION = "todos.task_finding_resolve_missing.v1", SEVERITIES, STATUSES;
+var init_findings = __esm(() => {
+  init_redaction();
+  init_types();
+  init_database();
+  init_tasks();
+  init_task_runs();
+  SEVERITIES = new Set(["low", "medium", "high", "critical"]);
+  STATUSES = new Set(["open", "resolved", "ignored"]);
+});
+
 // src/lib/agent-run-dispatcher.ts
 function dispatcherFromRun(run) {
   const value = run.metadata["agent_run_dispatcher"];
@@ -26248,7 +27129,7 @@ function parseArray2(value) {
     return [];
   }
 }
-function parseObject2(value) {
+function parseObject3(value) {
   try {
     const parsed = JSON.parse(value || "{}");
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
@@ -26289,7 +27170,7 @@ function rowToKnowledgeRecord(row) {
     agent_id: row.agent_id,
     snapshot_id: row.snapshot_id,
     tags: parseArray2(row.tags),
-    metadata: redactValue(parseObject2(row.metadata)),
+    metadata: redactValue(parseObject3(row.metadata)),
     created_at: row.created_at,
     updated_at: row.updated_at
   };
@@ -26508,7 +27389,7 @@ function parseArray3(value) {
     return [];
   }
 }
-function parseObject3(value) {
+function parseObject4(value) {
   try {
     const parsed = JSON.parse(value || "{}");
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
@@ -26557,7 +27438,7 @@ function rowToRisk(row) {
     plan_id: row.plan_id,
     task_id: row.task_id,
     tags: parseArray3(row.tags),
-    metadata: redactValue(parseObject3(row.metadata)),
+    metadata: redactValue(parseObject4(row.metadata)),
     created_at: row.created_at,
     updated_at: row.updated_at,
     closed_at: row.closed_at
@@ -32399,6 +33280,38 @@ ${lines.join(`
       }
     });
   }
+  if (shouldRegisterTool("begin_task_run_transaction")) {
+    server.tool("begin_task_run_transaction", "Preview or apply an idempotent local loop run transaction keyed by a stable loop/run id.", {
+      task_id: exports_external.string().describe("Task ID"),
+      key: exports_external.string().optional().describe("Stable idempotency key"),
+      loop_id: exports_external.string().optional().describe("Loop identifier; used as key fallback"),
+      loop_run_id: exports_external.string().optional().describe("Loop run identifier; used as key fallback"),
+      agent_id: exports_external.string().optional().describe("Agent starting the run"),
+      title: exports_external.string().optional().describe("Run title"),
+      summary: exports_external.string().optional().describe("Run summary"),
+      metadata: exports_external.record(exports_external.unknown()).optional().describe("Additional local metadata"),
+      claim: exports_external.boolean().optional().describe("Claim/start the task before recording the run"),
+      apply: exports_external.boolean().optional().describe("Apply the transaction; false or omitted is dry-run")
+    }, async ({ task_id, key, loop_id, loop_run_id, agent_id, title, summary, metadata, claim, apply }) => {
+      try {
+        const result = beginTaskRunTransaction({
+          task_id: resolveId(task_id),
+          key,
+          loop_id,
+          loop_run_id,
+          agent_id,
+          title,
+          summary,
+          metadata,
+          claim,
+          apply
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (e) {
+        return { content: [{ type: "text", text: formatError(e) }], isError: true };
+      }
+    });
+  }
   if (shouldRegisterTool("list_task_runs")) {
     server.tool("list_task_runs", "List local run ledger entries, optionally scoped to a task.", { task_id: exports_external.string().optional().describe("Optional task ID") }, async ({ task_id }) => {
       try {
@@ -32496,15 +33409,117 @@ ${lines.join(`
     });
   }
   if (shouldRegisterTool("finish_task_run")) {
-    server.tool("finish_task_run", "Finish a local run ledger entry as completed, failed, or cancelled.", {
-      run_id: exports_external.string().describe("Run ID or prefix"),
-      status: exports_external.enum(["completed", "failed", "cancelled"]).describe("Final run status"),
+    server.tool("finish_task_run", "Finish a local run ledger entry as completed, failed, or cancelled. Supports idempotent lookup by key.", {
+      run_id: exports_external.string().optional().describe("Run ID or prefix"),
+      key: exports_external.string().optional().describe("Idempotency key when run_id is omitted"),
+      task_id: exports_external.string().optional().describe("Task scope for key lookup"),
+      status: exports_external.enum(["completed", "failed", "cancelled"]).optional().describe("Final run status"),
       summary: exports_external.string().optional().describe("Final summary"),
-      agent_id: exports_external.string().optional().describe("Agent finishing the run")
-    }, async ({ run_id, status, summary, agent_id }) => {
+      agent_id: exports_external.string().optional().describe("Agent finishing the run"),
+      apply: exports_external.boolean().optional().describe("Apply the transaction; false previews without mutating")
+    }, async ({ run_id, key, task_id, status, summary, agent_id, apply }) => {
+      try {
+        if (run_id && !key && apply === undefined) {
+          const result2 = finishTaskRunTransaction({ run_id, status: status || "completed", summary, agent_id, apply: true });
+          const run = result2.run ? getTaskRunLedger(result2.run.id).run : null;
+          return { content: [{ type: "text", text: JSON.stringify(run, null, 2) }] };
+        }
+        const result = finishTaskRunTransaction({
+          run_id,
+          key,
+          task_id: task_id ? resolveId(task_id) : undefined,
+          status: status || "completed",
+          summary,
+          agent_id,
+          apply: apply !== false
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (e) {
+        return { content: [{ type: "text", text: formatError(e) }], isError: true };
+      }
+    });
+  }
+  if (shouldRegisterTool("upsert_task_finding")) {
+    server.tool("upsert_task_finding", "Preview or apply an idempotent local finding upsert scoped by task and fingerprint.", {
+      task_id: exports_external.string().describe("Task ID"),
+      fingerprint: exports_external.string().describe("Stable finding fingerprint"),
+      title: exports_external.string().describe("Finding title"),
+      severity: exports_external.enum(["low", "medium", "high", "critical"]).optional().describe("Finding severity"),
+      status: exports_external.enum(["open", "resolved", "ignored"]).optional().describe("Finding status"),
+      source: exports_external.string().optional().describe("Loop/tool source name"),
+      summary: exports_external.string().optional().describe("Bounded finding summary"),
+      artifact_path: exports_external.string().optional().describe("Local artifact path/reference; content is not read"),
+      run_id: exports_external.string().optional().describe("Run ledger ID or prefix"),
+      metadata: exports_external.record(exports_external.unknown()).optional().describe("Additional local metadata"),
+      apply: exports_external.boolean().optional().describe("Apply the upsert; false or omitted is dry-run")
+    }, async ({ task_id, fingerprint: fingerprint3, title, severity, status, source: source3, summary, artifact_path, run_id, metadata, apply }) => {
       try {
-        const run = finishTaskRun({ run_id, status, summary, agent_id });
-        return { content: [{ type: "text", text: JSON.stringify(run, null, 2) }] };
+        const result = upsertTaskFinding({
+          task_id: resolveId(task_id),
+          fingerprint: fingerprint3,
+          title,
+          severity,
+          status,
+          source: source3,
+          summary,
+          artifact_path,
+          run_id,
+          metadata,
+          apply
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (e) {
+        return { content: [{ type: "text", text: formatError(e) }], isError: true };
+      }
+    });
+  }
+  if (shouldRegisterTool("list_task_findings")) {
+    server.tool("list_task_findings", "List compact local findings with bounded output.", {
+      task_id: exports_external.string().optional().describe("Filter by task"),
+      run_id: exports_external.string().optional().describe("Filter by run"),
+      status: exports_external.enum(["open", "resolved", "ignored"]).optional().describe("Filter by status"),
+      source: exports_external.string().optional().describe("Filter by source"),
+      limit: exports_external.number().optional().describe("Maximum findings to return")
+    }, async ({ task_id, run_id, status, source: source3, limit }) => {
+      try {
+        const findings = listCompactTaskFindings({
+          task_id: task_id ? resolveId(task_id) : undefined,
+          run_id,
+          status,
+          source: source3,
+          limit
+        });
+        return { content: [{ type: "text", text: JSON.stringify(findings) }] };
+      } catch (e) {
+        return { content: [{ type: "text", text: formatError(e) }], isError: true };
+      }
+    });
+  }
+  if (shouldRegisterTool("resolve_missing_task_findings")) {
+    server.tool("resolve_missing_task_findings", "Resolve open findings absent from the latest loop finding set.", {
+      task_id: exports_external.string().describe("Task ID"),
+      fingerprints: exports_external.array(exports_external.string()).optional().describe("Fingerprints still present in the latest run"),
+      source: exports_external.string().optional().describe("Only resolve findings from this source"),
+      run_id: exports_external.string().optional().describe("Run ledger ID or prefix for audit metadata"),
+      status: exports_external.enum(["resolved", "ignored"]).optional().describe("Resolution status"),
+      agent_id: exports_external.string().optional().describe("Agent resolving findings"),
+      reason: exports_external.string().optional().describe("Resolution reason"),
+      limit: exports_external.number().optional().describe("Maximum findings returned"),
+      apply: exports_external.boolean().optional().describe("Apply resolution; false or omitted is dry-run")
+    }, async ({ task_id, fingerprints, source: source3, run_id, status, agent_id, reason, limit, apply }) => {
+      try {
+        const result = resolveMissingTaskFindings({
+          task_id: resolveId(task_id),
+          fingerprints: fingerprints || [],
+          source: source3,
+          run_id,
+          status,
+          agent_id,
+          reason,
+          limit,
+          apply
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
       } catch (e) {
         return { content: [{ type: "text", text: formatError(e) }], isError: true };
       }
@@ -32840,6 +33855,7 @@ var init_task_resources = __esm(() => {
   init_agents();
   init_task_commits();
   init_task_runs();
+  init_findings();
   init_agent_run_dispatcher();
   init_verification_providers();
   init_release_notes();
@@ -37384,6 +38400,39 @@ async function handleCreateTask(req, ctx, json2, taskToSummary2) {
     return json2({ error: e instanceof Error ? e.message : "Failed to create task" }, 500);
   }
 }
+async function handleUpsertTask(req, ctx, json2, taskToSummary2) {
+  try {
+    const body = await req.json();
+    if (typeof body["fingerprint"] !== "string" || body["fingerprint"].trim() === "") {
+      return json2({ error: "Missing 'fingerprint'" }, 400);
+    }
+    if (typeof body["title"] !== "string" || body["title"].trim() === "") {
+      return json2({ error: "Missing 'title'" }, 400);
+    }
+    const metadata = body["metadata"] && typeof body["metadata"] === "object" && !Array.isArray(body["metadata"]) ? { ...body["metadata"] } : {};
+    for (const key of ["expectation_id", "expectation_fingerprint", "evidence_paths", "origin_loop_id", "origin_run_id", "expected", "observed", "acceptance"]) {
+      if (body[key] !== undefined)
+        metadata[key] = body[key];
+    }
+    const result = upsertTaskByFingerprint({
+      fingerprint: body["fingerprint"],
+      title: body["title"],
+      description: typeof body["description"] === "string" ? body["description"] : undefined,
+      status: body["status"],
+      priority: body["priority"],
+      project_id: typeof body["project_id"] === "string" ? body["project_id"] : undefined,
+      task_list_id: typeof body["task_list_id"] === "string" ? body["task_list_id"] : undefined,
+      assigned_to: typeof body["assigned_to"] === "string" ? body["assigned_to"] : undefined,
+      working_dir: typeof body["working_dir"] === "string" ? body["working_dir"] : undefined,
+      tags: Array.isArray(body["tags"]) ? body["tags"].filter((tag) => typeof tag === "string") : undefined,
+      metadata
+    });
+    ctx.broadcastEvent({ type: "task", task_id: result.task.id, action: result.created ? "created" : "updated", agent_id: result.task.agent_id, project_id: result.task.project_id });
+    return json2({ created: result.created, task: taskToSummary2(result.task) }, result.created ? 201 : 200);
+  } catch (e) {
+    return json2({ error: e instanceof Error ? e.message : "Failed to upsert task" }, 500);
+  }
+}
 function handleTasksExport(_req, url, _ctx, _json, taskToSummary2) {
   const format = url.searchParams.get("format") || "json";
   const status = url.searchParams.get("status") || undefined;
@@ -38064,8 +39113,10 @@ function taskToSummary(task2, fields) {
     task_list_id: task2.task_list_id,
     agent_id: task2.agent_id,
     assigned_to: task2.assigned_to,
+    working_dir: task2.working_dir,
     locked_by: task2.locked_by,
     tags: task2.tags,
+    metadata: task2.metadata,
     version: task2.version,
     created_at: task2.created_at,
     updated_at: task2.updated_at,
@@ -38207,6 +39258,9 @@ Dashboard not found at: ${dashboardDir}`);
       if (path === "/api/tasks" && method === "POST") {
         return handleCreateTask(req, ctx, jsonWithCors, taskToSummary);
       }
+      if (path === "/api/tasks/upsert" && method === "POST") {
+        return handleUpsertTask(req, ctx, jsonWithCors, taskToSummary);
+      }
       if (path === "/api/tasks/export" && method === "GET") {
         return handleTasksExport(req, url, ctx, jsonWithCors, taskToSummary);
       }
@@ -38402,7 +39456,7 @@ Dashboard not found at: ${dashboardDir}`);
     } catch {}
   }
 }
-var MIME_TYPES, SECURITY_HEADERS, rateLimitMap, RATE_LIMIT_WINDOW_MS = 60000, RATE_LIMIT_MAX = 120;
+var MIME_TYPES, SECURITY_HEADERS, rateLimitMap, RATE_LIMIT_WINDOW_MS = 60000, RATE_LIMIT_MAX;
 var init_serve = __esm(() => {
   init_database();
   init_api_keys();
@@ -38427,6 +39481,7 @@ var init_serve = __esm(() => {
     "Permissions-Policy": "camera=, microphone=, geolocation="
   };
   rateLimitMap = new Map;
+  RATE_LIMIT_MAX = Number.parseInt(process.env["TODOS_RATE_LIMIT_MAX"] || "120", 10);
 });
 
 // src/mcp/index.ts