@hasna/todos 0.11.58 → 0.11.59

package/dist/cli/index.js

@@ -3223,6 +3223,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);
   `
   ];
 });
@@ -3660,6 +3703,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,
@@ -6134,6 +6218,7 @@ var init_event_hooks = __esm(() => {
     "task.blocked",
     "task.started",
     "task.completed",
+    "task.updated",
     "task.due",
     "task.due_soon",
     "task.failed",
@@ -7463,6 +7548,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();
@@ -7645,6 +7741,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 {
@@ -7669,6 +7766,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 = [];
@@ -7732,6 +7877,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");
   }
@@ -7782,6 +7928,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));
@@ -7870,6 +8020,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 = {
@@ -7905,6 +8057,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) {
@@ -10903,17 +11059,22 @@ var init_task_commits = __esm(() => {
 var exports_task_runs = {};
 __export(exports_task_runs, {
   verifyTaskRunArtifacts: () => verifyTaskRunArtifacts,
+  summarizeTaskRun: () => summarizeTaskRun,
   startTaskRun: () => startTaskRun,
   resolveTaskRunId: () => resolveTaskRunId,
   redactEvidenceText: () => redactEvidenceText,
   listTaskRuns: () => listTaskRuns,
   getTaskRunLedger: () => getTaskRunLedger,
   getTaskRun: () => getTaskRun,
+  finishTaskRunTransaction: () => finishTaskRunTransaction,
   finishTaskRun: () => finishTaskRun,
+  findTaskRunByTransactionKey: () => findTaskRunByTransactionKey,
+  beginTaskRunTransaction: () => beginTaskRunTransaction,
   addTaskRunFile: () => addTaskRunFile,
   addTaskRunEvent: () => addTaskRunEvent,
   addTaskRunCommand: () => addTaskRunCommand,
-  addTaskRunArtifact: () => addTaskRunArtifact
+  addTaskRunArtifact: () => addTaskRunArtifact,
+  LOOP_RUN_TRANSACTION_SCHEMA_VERSION: () => LOOP_RUN_TRANSACTION_SCHEMA_VERSION
 });
 function parseObject(value) {
   if (!value)
@@ -10937,6 +11098,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}%`);
@@ -10955,7 +11182,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);
@@ -10993,6 +11220,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);
@@ -11172,6 +11490,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();
@@ -11189,6 +11567,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();
@@ -11577,6 +11956,7 @@ var init_calendar = __esm(() => {
 var exports_tasks = {};
 __export(exports_tasks, {
   watchTask: () => watchTask,
+  upsertTaskByFingerprint: () => upsertTaskByFingerprint,
   updateTaskBoard: () => updateTaskBoard,
   updateTask: () => updateTask,
   unwatchTask: () => unwatchTask,
@@ -11620,6 +12000,7 @@ __export(exports_tasks, {
   getTaskGraph: () => getTaskGraph,
   getTaskDependents: () => getTaskDependents,
   getTaskDependencies: () => getTaskDependencies,
+  getTaskByFingerprint: () => getTaskByFingerprint,
   getTaskBoard: () => getTaskBoard,
   getTask: () => getTask,
   getStatus: () => getStatus,
@@ -11860,6 +12241,62 @@ function parsePriority(value) {
   }
   return value;
 }
+function parseJsonObject3(value, flag) {
+  if (!value)
+    return;
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    console.error(chalk2.red(`${flag} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`));
+    process.exit(1);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    console.error(chalk2.red(`${flag} must be a JSON object`));
+    process.exit(1);
+  }
+  return parsed;
+}
+function parseJsonValue(value) {
+  if (value === undefined)
+    return;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function parseTags(value) {
+  return value ? value.split(",").map((tag) => tag.trim()).filter(Boolean) : undefined;
+}
+function buildExpectationMetadata(opts) {
+  const metadata = parseJsonObject3(opts["metadataJson"], "--metadata-json") ?? {};
+  const expectationId = opts["expectationId"];
+  const expectationFingerprint = opts["expectationFingerprint"];
+  const evidencePaths = opts["evidencePaths"];
+  const originLoopId = opts["originLoopId"];
+  const originRunId = opts["originRunId"];
+  const expected = opts["expected"];
+  const observed = opts["observed"];
+  const acceptance = opts["acceptance"];
+  if (expectationId !== undefined)
+    metadata["expectation_id"] = expectationId;
+  if (expectationFingerprint !== undefined)
+    metadata["expectation_fingerprint"] = expectationFingerprint;
+  if (evidencePaths !== undefined)
+    metadata["evidence_paths"] = String(evidencePaths).split(",").map((path) => path.trim()).filter(Boolean);
+  if (originLoopId !== undefined)
+    metadata["origin_loop_id"] = originLoopId;
+  if (originRunId !== undefined)
+    metadata["origin_run_id"] = originRunId;
+  if (expected !== undefined)
+    metadata["expected"] = parseJsonValue(String(expected));
+  if (observed !== undefined)
+    metadata["observed"] = parseJsonValue(String(observed));
+  if (acceptance !== undefined)
+    metadata["acceptance"] = parseJsonValue(String(acceptance));
+  return metadata;
+}
 function registerTaskCommands(program2) {
   program2.command("add <title>").description("Create a new task").option("-d, --description <text>", "Task description").option("-p, --priority <level>", "Priority: low, medium, high, critical").option("--parent <id>", "Parent task ID").option("-t, --tags <tags>", "Comma-separated tags").option("--tag <tags>", "Comma-separated tags (alias for --tags)").option("--plan <id>", "Assign to a plan").option("--assign <agent>", "Assign to agent").option("--status <status>", "Initial status").option("--list <id>", "Task list ID").option("--task-list <id>", "Task list ID (alias for --list)").option("--estimated <minutes>", "Estimated time in minutes").option("--sla-minutes <minutes>", "SLA minutes before unfinished work is escalated").option("--sla <minutes>", "Alias for --sla-minutes").option("--approval", "Require approval before completion").option("--recurrence <rule>", "Recurrence rule, e.g. 'every day', 'every weekday', 'every 2 weeks'").option("--due <date>", "Due date (ISO string or YYYY-MM-DD)").option("--reason <text>", "Why this task exists").option("--project <id>", "Assign to project by ID or slug (overrides auto-detect)").action((title, opts) => {
     const globalOpts = program2.opts();
@@ -11876,7 +12313,7 @@ function registerTaskCommands(program2) {
       }
       return id;
     })() : undefined;
-    const task = createTask({
+    const task2 = createTask({
       title,
       description: opts.description,
       priority: parsePriority(opts.priority),
@@ -11898,10 +12335,53 @@ function registerTaskCommands(program2) {
       reason: opts.reason
     });
     if (globalOpts.json) {
-      output(task, true);
+      output(task2, true);
     } else {
       console.log(chalk2.green("Task created:"));
-      console.log(formatTaskLine(task));
+      console.log(formatTaskLine(task2));
+    }
+  });
+  const task = program2.command("task").description("Task subcommands for deterministic automation");
+  task.command("upsert").description("Create or update a task by stable metadata fingerprint").requiredOption("--fingerprint <key>", "Stable dedupe fingerprint").requiredOption("--title <text>", "Task title").option("-d, --description <text>", "Task description").option("-p, --priority <level>", "Priority: low, medium, high, critical").option("-s, --status <status>", "Task status").option("--list <id>", "Task list ID").option("--task-list <id>", "Task list ID (alias for --list)").option("-t, --tags <tags>", "Comma-separated tags").option("--tag <tags>", "Comma-separated tags (alias for --tags)").option("--metadata-json <json>", "JSON object merged into task metadata").option("--working-dir <path>", "Working directory to store on create/update").option("--project <id>", "Assign to project by ID, slug, or path").option("--assign <agent>", "Assign to agent").option("--expectation-id <id>", "Expectation metadata ID").option("--expectation-fingerprint <key>", "Expectation metadata fingerprint").option("--evidence-paths <paths>", "Comma-separated evidence paths").option("--origin-loop-id <id>", "Origin loop ID").option("--origin-run-id <id>", "Origin run ID").option("--expected <json-or-text>", "Expected value metadata").option("--observed <json-or-text>", "Observed value metadata").option("--acceptance <json-or-text>", "Acceptance metadata").action((opts) => {
+    const globalOpts = program2.opts();
+    opts.tags = opts.tags || opts.tag;
+    opts.list = opts.list || opts.taskList;
+    const explicitProject = opts.project || globalOpts.project;
+    const projectId = explicitProject ? resolveProjectIdOrSlug(explicitProject) : autoProject(globalOpts);
+    const taskListId = opts.list ? (() => {
+      const db = getDatabase();
+      const id = resolvePartialId(db, "task_lists", opts.list);
+      if (!id) {
+        console.error(chalk2.red(`Could not resolve task list ID: ${opts.list}`));
+        process.exit(1);
+      }
+      return id;
+    })() : undefined;
+    let result;
+    try {
+      result = upsertTaskByFingerprint({
+        fingerprint: opts.fingerprint,
+        title: opts.title,
+        description: opts.description,
+        priority: parsePriority(opts.priority),
+        status: opts.status ? normalizeStatus(opts.status) : undefined,
+        task_list_id: taskListId,
+        tags: parseTags(opts.tags),
+        metadata: buildExpectationMetadata(opts),
+        working_dir: opts.workingDir ? resolve8(opts.workingDir) : process.cwd(),
+        project_id: projectId,
+        assigned_to: opts.assign,
+        agent_id: globalOpts.agent,
+        session_id: globalOpts.session
+      });
+    } catch (e) {
+      handleError(e);
+    }
+    if (globalOpts.json) {
+      output(result, true);
+    } else {
+      console.log(chalk2.green(result.created ? "Task created:" : "Task updated:"));
+      console.log(formatTaskLine(result.task));
     }
   });
   program2.command("list").description("List tasks").option("-s, --status <status>", "Filter by status").option("-p, --priority <priority>", "Filter by priority").option("--assigned <agent>", "Filter by assigned agent").option("--tags <tags>", "Filter by tags (comma-separated)").option("--tag <tags>", "Filter by tags (alias for --tags)").option("-a, --all", "Show all tasks (including completed/cancelled)").option("--list <id>", "Filter by task list ID").option("--task-list <id>", "Filter by task list ID (alias for --list)").option("--project-name <name>", "Filter by project name").option("--agent-name <name>", "Filter by agent name/assigned").option("--sort <field>", "Sort by: updated, created, priority, status").option("--format <fmt>", "Output format: table (default), compact, csv, json").option("--due-today", "Only tasks due today or earlier").option("--overdue", "Only overdue tasks (past due_at)").option("--recurring", "Only recurring tasks").option("--limit <n>", "Max tasks to return").action((opts) => {
@@ -12059,89 +12539,89 @@ function registerTaskCommands(program2) {
   program2.command("show <id>").description("Show full task details").action((id) => {
     const globalOpts = program2.opts();
     const resolvedId = resolveTaskId(id);
-    const task = getTaskWithRelations(resolvedId);
-    if (!task) {
+    const task2 = getTaskWithRelations(resolvedId);
+    if (!task2) {
       console.error(chalk2.red(`Task not found: ${id}`));
       process.exit(1);
     }
     if (globalOpts.json) {
-      output(task, true);
+      output(task2, true);
       return;
     }
     console.log(chalk2.bold(`Task Details:
 `));
-    console.log(`  ${chalk2.dim("ID:")}       ${task.id}`);
-    console.log(`  ${chalk2.dim("Title:")}    ${task.title}`);
-    console.log(`  ${chalk2.dim("Status:")}   ${(statusColors[task.status] || chalk2.white)(task.status)}`);
-    console.log(`  ${chalk2.dim("Priority:")} ${(priorityColors[task.priority] || chalk2.white)(task.priority)}`);
-    if (task.description)
-      console.log(`  ${chalk2.dim("Desc:")}     ${task.description}`);
-    if (task.assigned_to)
-      console.log(`  ${chalk2.dim("Assigned:")} ${task.assigned_to}`);
-    if (task.agent_id)
-      console.log(`  ${chalk2.dim("Agent:")}    ${task.agent_id}`);
-    if (task.session_id)
-      console.log(`  ${chalk2.dim("Session:")}  ${task.session_id}`);
-    if (task.locked_by)
-      console.log(`  ${chalk2.dim("Locked:")}   ${task.locked_by} (at ${task.locked_at})`);
-    if (task.requires_approval) {
-      const approvalStatus = task.approved_by ? chalk2.green(`approved by ${task.approved_by}`) : chalk2.yellow("pending approval");
+    console.log(`  ${chalk2.dim("ID:")}       ${task2.id}`);
+    console.log(`  ${chalk2.dim("Title:")}    ${task2.title}`);
+    console.log(`  ${chalk2.dim("Status:")}   ${(statusColors[task2.status] || chalk2.white)(task2.status)}`);
+    console.log(`  ${chalk2.dim("Priority:")} ${(priorityColors[task2.priority] || chalk2.white)(task2.priority)}`);
+    if (task2.description)
+      console.log(`  ${chalk2.dim("Desc:")}     ${task2.description}`);
+    if (task2.assigned_to)
+      console.log(`  ${chalk2.dim("Assigned:")} ${task2.assigned_to}`);
+    if (task2.agent_id)
+      console.log(`  ${chalk2.dim("Agent:")}    ${task2.agent_id}`);
+    if (task2.session_id)
+      console.log(`  ${chalk2.dim("Session:")}  ${task2.session_id}`);
+    if (task2.locked_by)
+      console.log(`  ${chalk2.dim("Locked:")}   ${task2.locked_by} (at ${task2.locked_at})`);
+    if (task2.requires_approval) {
+      const approvalStatus = task2.approved_by ? chalk2.green(`approved by ${task2.approved_by}`) : chalk2.yellow("pending approval");
       console.log(`  ${chalk2.dim("Approval:")} ${approvalStatus}`);
     }
-    if (task.estimated_minutes)
-      console.log(`  ${chalk2.dim("Estimate:")} ${task.estimated_minutes} minutes`);
-    if (task.sla_minutes)
-      console.log(`  ${chalk2.dim("SLA:")}      ${task.sla_minutes} minutes`);
-    if (task.due_at)
-      console.log(`  ${chalk2.dim("Due:")}      ${task.due_at}`);
-    if (task.recurrence_rule)
-      console.log(`  ${chalk2.dim("Repeats:")}  ${task.recurrence_rule}`);
-    if (task.project_id)
-      console.log(`  ${chalk2.dim("Project:")}  ${task.project_id}`);
-    if (task.plan_id)
-      console.log(`  ${chalk2.dim("Plan:")}     ${task.plan_id}`);
-    if (task.working_dir)
-      console.log(`  ${chalk2.dim("WorkDir:")}  ${task.working_dir}`);
-    if (task.parent)
-      console.log(`  ${chalk2.dim("Parent:")}   ${task.parent.id.slice(0, 8)} | ${task.parent.title}`);
-    if (task.tags.length > 0)
-      console.log(`  ${chalk2.dim("Tags:")}     ${task.tags.join(", ")}`);
-    console.log(`  ${chalk2.dim("Version:")}  ${task.version}`);
-    console.log(`  ${chalk2.dim("Created:")}  ${task.created_at}`);
-    if (task.started_at)
-      console.log(`  ${chalk2.dim("Started:")}  ${task.started_at}`);
-    if (task.completed_at) {
-      console.log(`  ${chalk2.dim("Done:")}     ${task.completed_at}`);
-      if (task.started_at) {
-        const dur = Math.round((new Date(task.completed_at).getTime() - new Date(task.started_at).getTime()) / 60000);
+    if (task2.estimated_minutes)
+      console.log(`  ${chalk2.dim("Estimate:")} ${task2.estimated_minutes} minutes`);
+    if (task2.sla_minutes)
+      console.log(`  ${chalk2.dim("SLA:")}      ${task2.sla_minutes} minutes`);
+    if (task2.due_at)
+      console.log(`  ${chalk2.dim("Due:")}      ${task2.due_at}`);
+    if (task2.recurrence_rule)
+      console.log(`  ${chalk2.dim("Repeats:")}  ${task2.recurrence_rule}`);
+    if (task2.project_id)
+      console.log(`  ${chalk2.dim("Project:")}  ${task2.project_id}`);
+    if (task2.plan_id)
+      console.log(`  ${chalk2.dim("Plan:")}     ${task2.plan_id}`);
+    if (task2.working_dir)
+      console.log(`  ${chalk2.dim("WorkDir:")}  ${task2.working_dir}`);
+    if (task2.parent)
+      console.log(`  ${chalk2.dim("Parent:")}   ${task2.parent.id.slice(0, 8)} | ${task2.parent.title}`);
+    if (task2.tags.length > 0)
+      console.log(`  ${chalk2.dim("Tags:")}     ${task2.tags.join(", ")}`);
+    console.log(`  ${chalk2.dim("Version:")}  ${task2.version}`);
+    console.log(`  ${chalk2.dim("Created:")}  ${task2.created_at}`);
+    if (task2.started_at)
+      console.log(`  ${chalk2.dim("Started:")}  ${task2.started_at}`);
+    if (task2.completed_at) {
+      console.log(`  ${chalk2.dim("Done:")}     ${task2.completed_at}`);
+      if (task2.started_at) {
+        const dur = Math.round((new Date(task2.completed_at).getTime() - new Date(task2.started_at).getTime()) / 60000);
         console.log(`  ${chalk2.dim("Duration:")} ${dur}m`);
       }
     }
-    if (task.subtasks.length > 0) {
+    if (task2.subtasks.length > 0) {
       console.log(chalk2.bold(`
-  Subtasks (${task.subtasks.length}):`));
-      for (const st of task.subtasks) {
+  Subtasks (${task2.subtasks.length}):`));
+      for (const st of task2.subtasks) {
         console.log(`    ${formatTaskLine(st)}`);
       }
     }
-    if (task.dependencies.length > 0) {
+    if (task2.dependencies.length > 0) {
       console.log(chalk2.bold(`
-  Depends on (${task.dependencies.length}):`));
-      for (const dep of task.dependencies) {
+  Depends on (${task2.dependencies.length}):`));
+      for (const dep of task2.dependencies) {
         console.log(`    ${formatTaskLine(dep)}`);
       }
     }
-    if (task.blocked_by.length > 0) {
+    if (task2.blocked_by.length > 0) {
       console.log(chalk2.bold(`
-  Blocks (${task.blocked_by.length}):`));
-      for (const b of task.blocked_by) {
+  Blocks (${task2.blocked_by.length}):`));
+      for (const b of task2.blocked_by) {
         console.log(`    ${formatTaskLine(b)}`);
       }
     }
-    if (task.comments.length > 0) {
+    if (task2.comments.length > 0) {
       console.log(chalk2.bold(`
-  Comments (${task.comments.length}):`));
-      for (const c of task.comments) {
+  Comments (${task2.comments.length}):`));
+      for (const c of task2.comments) {
         const agent = c.agent_id ? chalk2.cyan(`[${c.agent_id}] `) : "";
         console.log(`    ${agent}${chalk2.dim(c.created_at)}: ${c.content}`);
       }
@@ -12160,8 +12640,8 @@ function registerTaskCommands(program2) {
       console.error(chalk2.red("No task ID given and no active task found. Pass an ID or use --agent."));
       process.exit(1);
     }
-    const task = getTaskWithRelations(resolvedId);
-    if (!task) {
+    const task2 = getTaskWithRelations(resolvedId);
+    if (!task2) {
       console.error(chalk2.red(`Task not found: ${id || resolvedId}`));
       process.exit(1);
     }
@@ -12169,55 +12649,55 @@ function registerTaskCommands(program2) {
       const { listTaskFiles: listTaskFiles2 } = await Promise.resolve().then(() => (init_task_files(), exports_task_files));
       const { getTaskCommits: getTaskCommits2 } = await Promise.resolve().then(() => (init_task_commits(), exports_task_commits));
       try {
-        task.files = listTaskFiles2(task.id);
+        task2.files = listTaskFiles2(task2.id);
       } catch (e) {
         console.error(chalk2.dim(`Warning: could not load task files: ${e instanceof Error ? e.message : String(e)}`));
       }
       try {
-        task.commits = getTaskCommits2(task.id);
+        task2.commits = getTaskCommits2(task2.id);
       } catch (e) {
         console.error(chalk2.dim(`Warning: could not load task commits: ${e instanceof Error ? e.message : String(e)}`));
       }
-      output(task, true);
+      output(task2, true);
       return;
     }
-    const sid = task.short_id || task.id.slice(0, 8);
-    const statusColor = statusColors[task.status] || chalk2.white;
-    const prioColor = priorityColors[task.priority] || chalk2.white;
+    const sid = task2.short_id || task2.id.slice(0, 8);
+    const statusColor = statusColors[task2.status] || chalk2.white;
+    const prioColor = priorityColors[task2.priority] || chalk2.white;
     console.log(chalk2.bold(`
-${chalk2.cyan(sid)} ${statusColor(task.status)} ${prioColor(task.priority)} ${task.title}
+${chalk2.cyan(sid)} ${statusColor(task2.status)} ${prioColor(task2.priority)} ${task2.title}
 `));
-    if (task.description) {
+    if (task2.description) {
       console.log(chalk2.dim("Description:"));
-      console.log(`  ${task.description}
+      console.log(`  ${task2.description}
 `);
     }
-    if (task.assigned_to)
-      console.log(`  ${chalk2.dim("Assigned:")}  ${task.assigned_to}`);
-    if (task.locked_by)
-      console.log(`  ${chalk2.dim("Locked by:")} ${task.locked_by}`);
-    if (task.project_id)
-      console.log(`  ${chalk2.dim("Project:")}   ${task.project_id}`);
-    if (task.plan_id)
-      console.log(`  ${chalk2.dim("Plan:")}      ${task.plan_id}`);
-    if (task.started_at)
-      console.log(`  ${chalk2.dim("Started:")}   ${task.started_at}`);
-    if (task.completed_at) {
-      console.log(`  ${chalk2.dim("Completed:")} ${task.completed_at}`);
-      if (task.started_at) {
-        const dur = Math.round((new Date(task.completed_at).getTime() - new Date(task.started_at).getTime()) / 60000);
+    if (task2.assigned_to)
+      console.log(`  ${chalk2.dim("Assigned:")}  ${task2.assigned_to}`);
+    if (task2.locked_by)
+      console.log(`  ${chalk2.dim("Locked by:")} ${task2.locked_by}`);
+    if (task2.project_id)
+      console.log(`  ${chalk2.dim("Project:")}   ${task2.project_id}`);
+    if (task2.plan_id)
+      console.log(`  ${chalk2.dim("Plan:")}      ${task2.plan_id}`);
+    if (task2.started_at)
+      console.log(`  ${chalk2.dim("Started:")}   ${task2.started_at}`);
+    if (task2.completed_at) {
+      console.log(`  ${chalk2.dim("Completed:")} ${task2.completed_at}`);
+      if (task2.started_at) {
+        const dur = Math.round((new Date(task2.completed_at).getTime() - new Date(task2.started_at).getTime()) / 60000);
         console.log(`  ${chalk2.dim("Duration:")}  ${dur}m`);
       }
     }
-    if (task.estimated_minutes)
-      console.log(`  ${chalk2.dim("Estimate:")}  ${task.estimated_minutes}m`);
-    if (task.tags.length > 0)
-      console.log(`  ${chalk2.dim("Tags:")}      ${task.tags.join(", ")}`);
-    const unfinishedDeps = task.dependencies.filter((d) => d.status !== "completed" && d.status !== "cancelled");
-    if (task.dependencies.length > 0) {
+    if (task2.estimated_minutes)
+      console.log(`  ${chalk2.dim("Estimate:")}  ${task2.estimated_minutes}m`);
+    if (task2.tags.length > 0)
+      console.log(`  ${chalk2.dim("Tags:")}      ${task2.tags.join(", ")}`);
+    const unfinishedDeps = task2.dependencies.filter((d) => d.status !== "completed" && d.status !== "cancelled");
+    if (task2.dependencies.length > 0) {
       console.log(chalk2.bold(`
-  Depends on (${task.dependencies.length}):`));
-      for (const dep of task.dependencies) {
+  Depends on (${task2.dependencies.length}):`));
+      for (const dep of task2.dependencies) {
         const blocked = dep.status !== "completed" && dep.status !== "cancelled";
         const icon = blocked ? chalk2.red("\u2717") : chalk2.green("\u2713");
         console.log(`    ${icon} ${formatTaskLine(dep)}`);
@@ -12227,21 +12707,21 @@ ${chalk2.cyan(sid)} ${statusColor(task.status)} ${prioColor(task.priority)} ${ta
       console.log(chalk2.red(`
   BLOCKED by ${unfinishedDeps.length} unfinished dep(s)`));
     }
-    if (task.blocked_by.length > 0) {
+    if (task2.blocked_by.length > 0) {
       console.log(chalk2.bold(`
-  Blocks (${task.blocked_by.length}):`));
-      for (const b of task.blocked_by)
+  Blocks (${task2.blocked_by.length}):`));
+      for (const b of task2.blocked_by)
         console.log(`    ${formatTaskLine(b)}`);
     }
-    if (task.subtasks.length > 0) {
+    if (task2.subtasks.length > 0) {
       console.log(chalk2.bold(`
-  Subtasks (${task.subtasks.length}):`));
-      for (const st of task.subtasks)
+  Subtasks (${task2.subtasks.length}):`));
+      for (const st of task2.subtasks)
         console.log(`    ${formatTaskLine(st)}`);
     }
     try {
       const { listTaskFiles: listTaskFiles2 } = await Promise.resolve().then(() => (init_task_files(), exports_task_files));
-      const files = listTaskFiles2(task.id);
+      const files = listTaskFiles2(task2.id);
       if (files.length > 0) {
         console.log(chalk2.bold(`
   Files (${files.length}):`));
@@ -12253,7 +12733,7 @@ ${chalk2.cyan(sid)} ${statusColor(task.status)} ${prioColor(task.priority)} ${ta
     }
     try {
       const { getTaskCommits: getTaskCommits2 } = await Promise.resolve().then(() => (init_task_commits(), exports_task_commits));
-      const commits = getTaskCommits2(task.id);
+      const commits = getTaskCommits2(task2.id);
       if (commits.length > 0) {
         console.log(chalk2.bold(`
   Commits (${commits.length}):`));
@@ -12263,19 +12743,19 @@ ${chalk2.cyan(sid)} ${statusColor(task.status)} ${prioColor(task.priority)} ${ta
     } catch (e) {
       console.error(chalk2.dim(`Warning: could not load task commits: ${e instanceof Error ? e.message : String(e)}`));
     }
-    if (task.comments.length > 0) {
+    if (task2.comments.length > 0) {
       console.log(chalk2.bold(`
-  Comments (${task.comments.length}):`));
-      for (const c of task.comments) {
+  Comments (${task2.comments.length}):`));
+      for (const c of task2.comments) {
         const agent = c.agent_id ? chalk2.cyan(`[${c.agent_id}] `) : "";
         console.log(`    ${agent}${chalk2.dim(c.created_at)}: ${c.content}`);
       }
     }
-    if (task.checklist && task.checklist.length > 0) {
-      const done = task.checklist.filter((c) => c.checked).length;
+    if (task2.checklist && task2.checklist.length > 0) {
+      const done = task2.checklist.filter((c) => c.checked).length;
       console.log(chalk2.bold(`
-  Checklist (${done}/${task.checklist.length}):`));
-      for (const item of task.checklist) {
+  Checklist (${done}/${task2.checklist.length}):`));
+      for (const item of task2.checklist) {
         const icon = item.checked ? chalk2.green("\u2611") : chalk2.dim("\u2610");
         console.log(`    ${icon} ${item.text || item.title}`);
       }
@@ -12328,9 +12808,9 @@ ${chalk2.cyan(sid)} ${statusColor(task.status)} ${prioColor(task.priority)} ${ta
       return resolved;
     })() : undefined;
     const planId = opts.plan ? resolvePlanId(opts.plan) : opts.clearPlan ? null : undefined;
-    let task;
+    let task2;
     try {
-      task = updateTask(resolvedId, {
+      task2 = updateTask(resolvedId, {
         version: current.version,
         title: opts.title,
         description: opts.description,
@@ -12350,10 +12830,10 @@ ${chalk2.cyan(sid)} ${statusColor(task.status)} ${prioColor(task.priority)} ${ta
       handleError(e);
     }
     if (globalOpts.json) {
-      output(task, true);
+      output(task2, true);
     } else {
       console.log(chalk2.green("Task updated:"));
-      console.log(formatTaskLine(task));
+      console.log(formatTaskLine(task2));
     }
   });
   program2.command("done <id>").description("Mark a task as completed").option("--attach-ids <ids>", "Comma-separated @hasna/attachments IDs to link as evidence").option("--files-changed <files>", "Comma-separated list of files changed").option("--test-results <results>", "Test results summary").option("--commit-hash <hash>", "Git commit hash").option("--notes <notes>", "Completion notes").option("--confidence <0-1>", "Agent's confidence 0.0-1.0 that the task is fully complete (default: 1.0, <0.7 flagged for review)").action((id, opts) => {
@@ -12363,37 +12843,37 @@ ${chalk2.cyan(sid)} ${statusColor(task.status)} ${prioColor(task.priority)} ${ta
     const filesChanged = opts.filesChanged ? opts.filesChanged.split(",").map((s) => s.trim()) : undefined;
     const confidence = opts.confidence !== undefined ? parseFloat(opts.confidence) : undefined;
     const evidence = attachmentIds || filesChanged || opts.testResults || opts.commitHash || opts.notes ? { attachment_ids: attachmentIds, files_changed: filesChanged, test_results: opts.testResults, commit_hash: opts.commitHash, notes: opts.notes } : undefined;
-    let task;
+    let task2;
     try {
-      task = completeTask(resolvedId, globalOpts.agent, undefined, { ...evidence, confidence });
+      task2 = completeTask(resolvedId, globalOpts.agent, undefined, { ...evidence, confidence });
     } catch (e) {
       handleError(e);
     }
     if (globalOpts.json) {
-      output(task, true);
+      output(task2, true);
     } else {
       console.log(chalk2.green("Task completed:"));
-      console.log(formatTaskLine(task));
+      console.log(formatTaskLine(task2));
     }
   });
   program2.command("approve <id>").description("Approve a task that requires approval").action((id) => {
     const globalOpts = program2.opts();
     const resolvedId = resolveTaskId(id);
-    const task = getTask(resolvedId);
-    if (!task) {
+    const task2 = getTask(resolvedId);
+    if (!task2) {
       console.error(chalk2.red(`Task not found: ${id}`));
       process.exit(1);
     }
-    if (!task.requires_approval) {
+    if (!task2.requires_approval) {
       console.log(chalk2.yellow("This task does not require approval."));
       return;
     }
-    if (task.approved_by) {
-      console.log(chalk2.yellow(`Already approved by ${task.approved_by}.`));
+    if (task2.approved_by) {
+      console.log(chalk2.yellow(`Already approved by ${task2.approved_by}.`));
       return;
     }
     try {
-      const updated = updateTask(resolvedId, { approved_by: globalOpts.agent || "cli", version: task.version });
+      const updated = updateTask(resolvedId, { approved_by: globalOpts.agent || "cli", version: task2.version });
       if (globalOpts.json) {
         output(updated, true);
       } else {
@@ -12408,17 +12888,17 @@ ${chalk2.cyan(sid)} ${statusColor(task.status)} ${prioColor(task.priority)} ${ta
     const globalOpts = program2.opts();
     const agentId = globalOpts.agent || "cli";
     const resolvedId = resolveTaskId(id);
-    let task;
+    let task2;
     try {
-      task = startTask(resolvedId, agentId);
+      task2 = startTask(resolvedId, agentId);
     } catch (e) {
       handleError(e);
     }
     if (globalOpts.json) {
-      output(task, true);
+      output(task2, true);
     } else {
       console.log(chalk2.green(`Task started by ${agentId}:`));
-      console.log(formatTaskLine(task));
+      console.log(formatTaskLine(task2));
     }
   });
   program2.command("lock <id>").description("Acquire exclusive lock on a task").action((id) => {
@@ -13591,7 +14071,7 @@ function likePattern(query) {
     return null;
   return `%${trimmed}%`;
 }
-function parseJsonObject3(value) {
+function parseJsonObject4(value) {
   if (!value)
     return {};
   if (typeof value === "object" && !Array.isArray(value))
@@ -13606,7 +14086,7 @@ function parseJsonObject3(value) {
   }
 }
 function rowToTaskRun(row) {
-  return { ...row, metadata: parseJsonObject3(row.metadata) };
+  return { ...row, metadata: parseJsonObject4(row.metadata) };
 }
 function taskMatchesSavedFilters(task, filters, db) {
   if (filters.plan_id && task.plan_id !== filters.plan_id)
@@ -14969,7 +15449,7 @@ function packageSource(version) {
 function emptyCounts() {
   return Object.fromEntries(dataKeys.map((key) => [key, 0]));
 }
-function parseJsonObject4(value) {
+function parseJsonObject5(value) {
   if (!value)
     return {};
   if (typeof value === "object" && !Array.isArray(value))
@@ -15015,34 +15495,34 @@ function rowToTask3(row) {
   return {
     ...row,
     tags: parseJsonArray2(row.tags),
-    metadata: parseJsonObject4(row.metadata),
+    metadata: parseJsonObject5(row.metadata),
     requires_approval: Boolean(row.requires_approval)
   };
 }
 function rowToTaskList2(row) {
-  return { ...row, metadata: parseJsonObject4(row.metadata) };
+  return { ...row, metadata: parseJsonObject5(row.metadata) };
 }
 function rowWithMetadata(row) {
-  return { ...row, metadata: parseJsonObject4(row.metadata) };
+  return { ...row, metadata: parseJsonObject5(row.metadata) };
 }
 function rowToRunEvent(row) {
-  return { ...row, data: parseJsonObject4(row.data) };
+  return { ...row, data: parseJsonObject5(row.data) };
 }
 function rowToCommit2(row) {
   return { ...row, files_changed: row.files_changed ? parseJsonArray2(row.files_changed) : null };
 }
 function rowToSavedView(row) {
-  return { ...row, filters: parseJsonObject4(row.filters) };
+  return { ...row, filters: parseJsonObject5(row.filters) };
 }
 function rowToTaskBoard2(row) {
   return {
     ...row,
     lanes: parseJsonArray2(row.lanes),
-    filters: parseJsonObject4(row.filters)
+    filters: parseJsonObject5(row.filters)
   };
 }
 function rowToCalendarItem2(row) {
-  return { ...row, metadata: parseJsonObject4(row.metadata) };
+  return { ...row, metadata: parseJsonObject5(row.metadata) };
 }
 function bridgeStats(data) {
   return Object.fromEntries(dataKeys.map((key) => [key, data[key].length]));
@@ -18389,6 +18869,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",
@@ -18436,6 +18917,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",
@@ -18444,6 +18926,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",
@@ -18486,9 +18969,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",
@@ -18570,7 +19061,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"],
@@ -20863,6 +21354,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;
@@ -26005,6 +26529,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"),
@@ -26016,7 +26595,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 };
@@ -27604,7 +28184,7 @@ function parseAssignee(line) {
     return mention;
   return line.match(/\bassign(?:ed)?\s+(?:to\s+)?([a-zA-Z0-9._-]+)/i)?.[1] || null;
 }
-function parseTags(line) {
+function parseTags2(line) {
   return Array.from(new Set(Array.from(line.matchAll(/#([a-zA-Z0-9._-]+)/g)).map((match) => match[1].toLowerCase()))).slice(0, 10);
 }
 function parseDependencies(line) {
@@ -27676,7 +28256,7 @@ function previewNaturalLanguageIntake(input, db) {
       description: `Parsed from local natural-language intake:
 ${line}`,
       priority: parsePriority2(line, fallbackPriority),
-      tags: parseTags(line),
+      tags: parseTags2(line),
       assigned_to: parseAssignee(line),
       due_at: parseDue(line, referenceDate),
       depends_on: parseDependencies(line),
@@ -28184,7 +28764,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,
@@ -28245,7 +28825,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);
@@ -34239,6 +34819,366 @@ var init_task_meta_tools = __esm(() => {
   init_zod();
 });
 
+// src/db/findings.ts
+var exports_findings = {};
+__export(exports_findings, {
+  upsertTaskFinding: () => upsertTaskFinding,
+  resolveMissingTaskFindings: () => resolveMissingTaskFindings,
+  listTaskFindings: () => listTaskFindings,
+  listCompactTaskFindings: () => listCompactTaskFindings,
+  TASK_FINDING_UPSERT_SCHEMA_VERSION: () => TASK_FINDING_UPSERT_SCHEMA_VERSION,
+  TASK_FINDING_SCHEMA_VERSION: () => TASK_FINDING_SCHEMA_VERSION,
+  TASK_FINDING_RESOLVE_MISSING_SCHEMA_VERSION: () => TASK_FINDING_RESOLVE_MISSING_SCHEMA_VERSION
+});
+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 normalizeStatus2(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 = normalizeStatus2(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: normalizeStatus2(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: normalizeStatus2(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(normalizeStatus2(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
 var exports_agent_run_dispatcher = {};
 __export(exports_agent_run_dispatcher, {
@@ -35167,7 +36107,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 : {};
@@ -35208,7 +36148,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
   };
@@ -35427,7 +36367,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 : {};
@@ -35476,7 +36416,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
@@ -36327,7 +37267,7 @@ function extractUsage(value) {
   }
   return own;
 }
-function parseJsonObject5(value) {
+function parseJsonObject6(value) {
   if (!value)
     return {};
   try {
@@ -36499,7 +37439,7 @@ function createLocalUsageLedger(options = {}, db) {
       completedRunMs += millisBetween(run.started_at, run.completed_at);
     else
       openRunMs += millisBetween(run.started_at, generatedAt);
-    const usage = extractUsage(parseJsonObject5(run.metadata));
+    const usage = extractUsage(parseJsonObject6(run.metadata));
     metadataUsage.tokens += usage.tokens;
     metadataUsage.cost_usd += usage.cost_usd;
     metadataUsage.duration_ms += usage.duration_ms;
@@ -36511,7 +37451,7 @@ function createLocalUsageLedger(options = {}, db) {
        JOIN tasks t ON t.id = e.task_id
        ${runClause}`, runParams);
   for (const event of eventRows) {
-    const usage = extractUsage(parseJsonObject5(event.data));
+    const usage = extractUsage(parseJsonObject6(event.data));
     metadataUsage.tokens += usage.tokens;
     metadataUsage.cost_usd += usage.cost_usd;
     metadataUsage.duration_ms += usage.duration_ms;
@@ -40312,6 +41252,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 {
@@ -40409,15 +41381,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 {
-        const run = finishTaskRun({ run_id, status, summary, agent_id });
-        return { content: [{ type: "text", text: JSON.stringify(run, null, 2) }] };
+        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 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 };
       }
@@ -40753,6 +41827,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();
@@ -44493,8 +45568,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,
@@ -44636,6 +45713,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);
       }
@@ -44831,7 +45911,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();
@@ -44856,6 +45936,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/cli/components/Header.tsx
@@ -47509,9 +48590,9 @@ function normalizeKind(value) {
   const raw = cleanKey(asString4(value) || "unknown").replace(/-/g, "_");
   return KINDS.has(raw) ? raw : raw || "unknown";
 }
-function normalizeSeverity(value, fallback) {
+function normalizeSeverity2(value, fallback) {
   const raw = cleanKey(asString4(value) || fallback);
-  if (SEVERITIES.has(raw))
+  if (SEVERITIES2.has(raw))
     return raw;
   if (/^(p0|blocker|urgent|highest)$/.test(raw))
     return "critical";
@@ -47606,7 +48687,7 @@ function normalizeTesterIssueReport(value, fallbackPriority = "medium") {
     title,
     summary: truncate3(asString4(input["summary"]), 1000) ?? null,
     kind: normalizeKind(input["kind"] ?? input["type"]),
-    severity: normalizeSeverity(input["severity"] ?? input["priority"], fallbackPriority),
+    severity: normalizeSeverity2(input["severity"] ?? input["priority"], fallbackPriority),
     source: source3,
     target,
     failure,
@@ -47904,13 +48985,13 @@ function readTesterIssueReportsPayload(value) {
     return record["issues"];
   return [value];
 }
-var TESTERS_ISSUE_REPORT_SCHEMA_VERSION = "testers.issue_report.v1", TESTERS_ISSUE_REPORT_RESULT_SCHEMA_VERSION = "todos.tester_issue_report_result.v1", TESTERS_ISSUE_REPORT_BATCH_RESULT_SCHEMA_VERSION = "todos.tester_issue_report_batch_result.v1", PRIORITIES5, SEVERITIES, KINDS;
+var TESTERS_ISSUE_REPORT_SCHEMA_VERSION = "testers.issue_report.v1", TESTERS_ISSUE_REPORT_RESULT_SCHEMA_VERSION = "todos.tester_issue_report_result.v1", TESTERS_ISSUE_REPORT_BATCH_RESULT_SCHEMA_VERSION = "todos.tester_issue_report_batch_result.v1", PRIORITIES5, SEVERITIES2, KINDS;
 var init_tester_issue_reports = __esm(() => {
   init_database();
   init_tasks();
   init_redaction();
   PRIORITIES5 = ["low", "medium", "high", "critical"];
-  SEVERITIES = new Set(PRIORITIES5);
+  SEVERITIES2 = new Set(PRIORITIES5);
   KINDS = new Set([
     "assertion_failure",
     "runtime_error",
@@ -51092,6 +52173,23 @@ Verifications:`));
     console.log(`${result.status} ${result.provider}: ${result.output_summary || ""}`);
   });
   const runs = program2.command("runs").description("Manage the local run ledger and evidence capture");
+  runs.command("begin <task-id>").description("Preview or apply an idempotent loop run transaction").option("--key <key>", "Stable idempotency key for this loop transaction").option("--loop-id <id>", "Loop identifier; used as the key when --key/--loop-run-id are omitted").option("--loop-run-id <id>", "Loop run identifier; used as the key when --key is omitted").option("--agent <name>", "Agent starting the run").option("--title <text>", "Run title").option("--summary <text>", "Run summary").option("--metadata <json>", "Additional JSON metadata").option("--claim", "Claim/start the task for the agent before recording the run").option("--apply", "Apply the transaction; omitted means dry-run").action(async (taskId, opts) => {
+    const globalOpts = program2.opts();
+    const { beginTaskRunTransaction: beginTaskRunTransaction2 } = await Promise.resolve().then(() => (init_task_runs(), exports_task_runs));
+    const result = beginTaskRunTransaction2({
+      task_id: resolveTaskId(taskId),
+      key: opts.key,
+      loop_id: opts.loopId,
+      loop_run_id: opts.loopRunId,
+      agent_id: opts.agent || globalOpts.agent,
+      title: opts.title,
+      summary: opts.summary,
+      metadata: parseJsonOption(opts.metadata, "--metadata"),
+      claim: opts.claim,
+      apply: opts.apply
+    });
+    output(result, true);
+  });
   runs.command("start <task-id>").description("Start a local run ledger entry for a task").option("--agent <name>", "Agent starting the run").option("--title <text>", "Run title").option("--summary <text>", "Run summary").option("--metadata <json>", "Additional JSON metadata").option("--claim", "Claim/start the task for the agent before recording the run").action(async (taskId, opts) => {
     const globalOpts = program2.opts();
     const { startTaskRun: startTaskRun2 } = await Promise.resolve().then(() => (init_task_runs(), exports_task_runs));
@@ -51303,19 +52401,68 @@ Artifacts:`));
       process.exit(1);
     }
   });
-  runs.command("finish <run-id>").description("Finish a run ledger entry").option("--status <status>", "completed, failed, or cancelled", "completed").option("--summary <text>", "Final summary").option("--agent <name>", "Agent finishing the run").action(async (runId, opts) => {
+  runs.command("finish [run-id]").description("Finish a run ledger entry idempotently").option("--key <key>", "Resolve run by idempotency key when run-id is omitted").option("--task <task-id>", "Task scope for --key lookup").option("--status <status>", "completed, failed, or cancelled", "completed").option("--summary <text>", "Final summary").option("--agent <name>", "Agent finishing the run").option("--dry-run", "Preview without mutating").action(async (runId, opts) => {
     const globalOpts = program2.opts();
     if (opts.status !== "completed" && opts.status !== "failed" && opts.status !== "cancelled") {
       console.error(chalk8.red("--status must be completed, failed, or cancelled"));
       process.exit(1);
     }
-    const { finishTaskRun: finishTaskRun2 } = await Promise.resolve().then(() => (init_task_runs(), exports_task_runs));
-    const run = finishTaskRun2({ run_id: runId, status: opts.status, summary: opts.summary, agent_id: opts.agent || globalOpts.agent });
-    if (globalOpts.json) {
-      output(run, true);
-      return;
-    }
-    console.log(chalk8.green(`Finished run ${run.id.slice(0, 8)} as ${run.status}`));
+    const { finishTaskRunTransaction: finishTaskRunTransaction2 } = await Promise.resolve().then(() => (init_task_runs(), exports_task_runs));
+    const result = finishTaskRunTransaction2({
+      run_id: runId,
+      key: opts.key,
+      task_id: opts.task ? resolveTaskId(opts.task) : undefined,
+      status: opts.status,
+      summary: opts.summary,
+      agent_id: opts.agent || globalOpts.agent,
+      apply: !opts.dryRun
+    });
+    output(result, true);
+  });
+  const findings = program2.command("findings").description("Manage local task findings for loop dedupe and resolution");
+  findings.command("upsert").description("Preview or apply an idempotent finding upsert").requiredOption("--task <task-id>", "Task ID").requiredOption("--fingerprint <value>", "Stable finding fingerprint").requiredOption("--title <text>", "Finding title").option("--severity <severity>", "low, medium, high, or critical", "medium").option("--status <status>", "open, resolved, or ignored", "open").option("--source <source>", "Loop/tool source name").option("--summary <text>", "Bounded finding summary").option("--artifact <path>", "Local artifact path/reference; content is not read").option("--run <run-id>", "Run ledger ID or prefix").option("--metadata <json>", "Additional JSON metadata").option("--apply", "Apply the upsert; omitted means dry-run").action(async (opts) => {
+    const { upsertTaskFinding: upsertTaskFinding2 } = await Promise.resolve().then(() => (init_findings(), exports_findings));
+    const result = upsertTaskFinding2({
+      task_id: resolveTaskId(opts.task),
+      fingerprint: opts.fingerprint,
+      title: opts.title,
+      severity: opts.severity,
+      status: opts.status,
+      source: opts.source,
+      summary: opts.summary,
+      artifact_path: opts.artifact,
+      run_id: opts.run,
+      metadata: parseJsonOption(opts.metadata, "--metadata"),
+      apply: opts.apply
+    });
+    output(result, true);
+  });
+  findings.command("resolve-missing").description("Resolve open findings absent from the latest loop finding set").requiredOption("--task <task-id>", "Task ID").option("--fingerprints <list>", "Comma-separated fingerprints still present").option("--source <source>", "Only resolve findings from this source").option("--run <run-id>", "Run ledger ID or prefix for audit metadata").option("--status <status>", "resolved or ignored", "resolved").option("--agent <name>", "Agent resolving findings").option("--reason <text>", "Resolution reason").option("--limit <n>", "Maximum findings returned", "50").option("--apply", "Apply resolution; omitted means dry-run").action(async (opts) => {
+    const globalOpts = program2.opts();
+    const { resolveMissingTaskFindings: resolveMissingTaskFindings2 } = await Promise.resolve().then(() => (init_findings(), exports_findings));
+    const result = resolveMissingTaskFindings2({
+      task_id: resolveTaskId(opts.task),
+      fingerprints: listOption(opts.fingerprints) || [],
+      source: opts.source,
+      run_id: opts.run,
+      status: opts.status,
+      agent_id: opts.agent || globalOpts.agent,
+      reason: opts.reason,
+      limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined,
+      apply: opts.apply
+    });
+    output(result, true);
+  });
+  findings.command("list").description("List compact local findings").option("--task <task-id>", "Filter by task").option("--run <run-id>", "Filter by run").option("--status <status>", "Filter by open, resolved, or ignored").option("--source <source>", "Filter by source").option("--limit <n>", "Maximum findings returned", "50").action(async (opts) => {
+    const { listCompactTaskFindings: listCompactTaskFindings2 } = await Promise.resolve().then(() => (init_findings(), exports_findings));
+    const findings2 = listCompactTaskFindings2({
+      task_id: opts.task ? resolveTaskId(opts.task) : undefined,
+      run_id: opts.run,
+      status: opts.status,
+      source: opts.source,
+      limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined
+    });
+    output(findings2, true);
   });
   const agentRuns = program2.command("agent-runs").description("Queue and dispatch local agent runs");
   agentRuns.command("adapter-set <name>").description("Create or update a local agent run adapter").option("--command <command>", "Local command template. Supports {task_id}, {run_id}, and {agent_id}").option("--sandbox <name>", "Runner sandbox profile to check before launch").option("--cwd <path>", "Command working directory").option("--env <json>", "Static adapter environment as a JSON object").action(async (name, opts) => {
@@ -52229,7 +53376,7 @@ function parseRecordType(value) {
   console.error(chalk13.red(`type must be one of: ${RECORD_TYPES.join(", ")}`));
   process.exit(1);
 }
-function parseJsonObject6(value, label) {
+function parseJsonObject7(value, label) {
   if (!value)
     return;
   try {
@@ -52289,7 +53436,7 @@ function registerKnowledgeCommands(program2) {
         plan_id: opts.plan,
         agent_id: opts.agent || globalOpts.agent,
         tags: tagsFromOption(opts.tag),
-        metadata: parseJsonObject6(opts.metadataJson, "--metadata-json")
+        metadata: parseJsonObject7(opts.metadataJson, "--metadata-json")
       }, getDatabase());
       if (opts.json || globalOpts.json)
         output(record, true);
@@ -52314,7 +53461,7 @@ function registerKnowledgeCommands(program2) {
         blockers: opts.blocker,
         next_steps: opts.next,
         tags: tagsFromOption(opts.tag),
-        metadata: parseJsonObject6(opts.metadataJson, "--metadata-json")
+        metadata: parseJsonObject7(opts.metadataJson, "--metadata-json")
       }, getDatabase());
       if (opts.json || globalOpts.json)
         output(result, true);
@@ -52400,7 +53547,7 @@ function parseChoice(value, choices, label) {
   console.error(chalk14.red(`${label} must be one of: ${choices.join(", ")}`));
   process.exit(1);
 }
-function parseJsonObject7(value, label) {
+function parseJsonObject8(value, label) {
   if (!value)
     return;
   try {
@@ -52421,8 +53568,8 @@ function tagsFromOption2(value) {
 }
 function commonFilters2(opts) {
   return {
-    status: opts.status ? parseChoice(opts.status, STATUSES, "--status") : undefined,
-    severity: opts.severity ? parseChoice(opts.severity, SEVERITIES2, "--severity") : undefined,
+    status: opts.status ? parseChoice(opts.status, STATUSES2, "--status") : undefined,
+    severity: opts.severity ? parseChoice(opts.severity, SEVERITIES3, "--severity") : undefined,
     probability: opts.probability ? parseChoice(opts.probability, PROBABILITIES, "--probability") : undefined,
     owner: opts.owner,
     project_id: opts.project,
@@ -52455,8 +53602,8 @@ function registerRiskCommands(program2) {
       const risk = createRisk({
         title,
         description: opts.description,
-        status: parseChoice(opts.status, STATUSES, "--status"),
-        severity: parseChoice(opts.severity, SEVERITIES2, "--severity"),
+        status: parseChoice(opts.status, STATUSES2, "--status"),
+        severity: parseChoice(opts.severity, SEVERITIES3, "--severity"),
         probability: parseChoice(opts.probability, PROBABILITIES, "--probability"),
         owner: opts.owner,
         mitigation: opts.mitigation,
@@ -52465,7 +53612,7 @@ function registerRiskCommands(program2) {
         plan_id: opts.plan,
         task_id: opts.task,
         tags: tagsFromOption2(opts.tag),
-        metadata: parseJsonObject7(opts.metadataJson, "--metadata-json")
+        metadata: parseJsonObject8(opts.metadataJson, "--metadata-json")
       }, getDatabase());
       if (opts.json || globalOpts.json)
         output(risk, true);
@@ -52507,8 +53654,8 @@ function registerRiskCommands(program2) {
       const risk = updateRisk(id, {
         title: opts.title,
         description: opts.description,
-        status: opts.status ? parseChoice(opts.status, STATUSES, "--status") : undefined,
-        severity: opts.severity ? parseChoice(opts.severity, SEVERITIES2, "--severity") : undefined,
+        status: opts.status ? parseChoice(opts.status, STATUSES2, "--status") : undefined,
+        severity: opts.severity ? parseChoice(opts.severity, SEVERITIES3, "--severity") : undefined,
         probability: opts.probability ? parseChoice(opts.probability, PROBABILITIES, "--probability") : undefined,
         owner: opts.owner,
         mitigation: opts.mitigation,
@@ -52517,7 +53664,7 @@ function registerRiskCommands(program2) {
         plan_id: opts.plan,
         task_id: opts.task,
         tags: opts.tag.length > 0 ? tagsFromOption2(opts.tag) : undefined,
-        metadata: parseJsonObject7(opts.metadataJson, "--metadata-json")
+        metadata: parseJsonObject8(opts.metadataJson, "--metadata-json")
       }, getDatabase());
       if (opts.json || globalOpts.json)
         output(risk, true);
@@ -52575,13 +53722,13 @@ function registerRiskCommands(program2) {
     }
   });
 }
-var STATUSES, SEVERITIES2, PROBABILITIES;
+var STATUSES2, SEVERITIES3, PROBABILITIES;
 var init_risk_commands = __esm(() => {
   init_database();
   init_project_risks();
   init_helpers();
-  STATUSES = ["open", "mitigating", "resolved", "accepted"];
-  SEVERITIES2 = ["low", "medium", "high", "critical"];
+  STATUSES2 = ["open", "mitigating", "resolved", "accepted"];
+  SEVERITIES3 = ["low", "medium", "high", "critical"];
   PROBABILITIES = ["low", "medium", "high"];
 });
 
@@ -55166,6 +56313,92 @@ var init_json_contracts = __esm(() => {
       },
       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",