@hasna/todos 0.11.57 → 0.11.59

package/dist/registry.js

@@ -1139,6 +1139,49 @@ var init_migrations = __esm(() => {
   CREATE INDEX IF NOT EXISTS idx_local_retrospectives_plan ON local_retrospectives(plan_id);
   CREATE INDEX IF NOT EXISTS idx_local_retrospectives_agent ON local_retrospectives(agent_id);
   INSERT OR IGNORE INTO _migrations (id) VALUES (61);
+  `,
+    `
+  CREATE TABLE IF NOT EXISTS task_run_transactions (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+    run_id TEXT REFERENCES task_runs(id) ON DELETE SET NULL,
+    key TEXT NOT NULL,
+    loop_id TEXT,
+    loop_run_id TEXT,
+    metadata TEXT DEFAULT '{}',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(task_id, key)
+  );
+  CREATE INDEX IF NOT EXISTS idx_task_run_transactions_task_key ON task_run_transactions(task_id, key);
+  CREATE INDEX IF NOT EXISTS idx_task_run_transactions_key ON task_run_transactions(key);
+  CREATE INDEX IF NOT EXISTS idx_task_run_transactions_run ON task_run_transactions(run_id);
+
+  CREATE TABLE IF NOT EXISTS task_findings (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+    run_id TEXT REFERENCES task_runs(id) ON DELETE SET NULL,
+    fingerprint TEXT NOT NULL,
+    title TEXT NOT NULL,
+    severity TEXT NOT NULL DEFAULT 'medium' CHECK(severity IN ('low', 'medium', 'high', 'critical')),
+    status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open', 'resolved', 'ignored')),
+    source TEXT,
+    summary TEXT,
+    artifact_path TEXT,
+    metadata TEXT DEFAULT '{}',
+    first_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+    last_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+    resolved_at TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(task_id, fingerprint)
+  );
+  CREATE INDEX IF NOT EXISTS idx_task_findings_task ON task_findings(task_id);
+  CREATE INDEX IF NOT EXISTS idx_task_findings_run ON task_findings(run_id);
+  CREATE INDEX IF NOT EXISTS idx_task_findings_status ON task_findings(status);
+  CREATE INDEX IF NOT EXISTS idx_task_findings_source ON task_findings(source);
+  CREATE INDEX IF NOT EXISTS idx_task_findings_fingerprint ON task_findings(fingerprint);
+  INSERT OR IGNORE INTO _migrations (id) VALUES (62);
   `
   ];
 });
@@ -1576,6 +1619,47 @@ function ensureSchema(db) {
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_artifacts_run ON task_run_artifacts(run_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_artifacts_task ON task_run_artifacts(task_id)");
   ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_artifacts_path ON task_run_artifacts(path)");
+  ensureTable("task_run_transactions", `
+    CREATE TABLE task_run_transactions (
+      id TEXT PRIMARY KEY,
+      task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      run_id TEXT REFERENCES task_runs(id) ON DELETE SET NULL,
+      key TEXT NOT NULL,
+      loop_id TEXT,
+      loop_run_id TEXT,
+      metadata TEXT DEFAULT '{}',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(task_id, key)
+    )`);
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_transactions_task_key ON task_run_transactions(task_id, key)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_transactions_key ON task_run_transactions(key)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_run_transactions_run ON task_run_transactions(run_id)");
+  ensureTable("task_findings", `
+    CREATE TABLE task_findings (
+      id TEXT PRIMARY KEY,
+      task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      run_id TEXT REFERENCES task_runs(id) ON DELETE SET NULL,
+      fingerprint TEXT NOT NULL,
+      title TEXT NOT NULL,
+      severity TEXT NOT NULL DEFAULT 'medium' CHECK(severity IN ('low', 'medium', 'high', 'critical')),
+      status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open', 'resolved', 'ignored')),
+      source TEXT,
+      summary TEXT,
+      artifact_path TEXT,
+      metadata TEXT DEFAULT '{}',
+      first_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+      last_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+      resolved_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(task_id, fingerprint)
+    )`);
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_task ON task_findings(task_id)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_run ON task_findings(run_id)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_status ON task_findings(status)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_source ON task_findings(source)");
+  ensureIndex("CREATE INDEX IF NOT EXISTS idx_task_findings_fingerprint ON task_findings(fingerprint)");
   ensureTable("inbox_items", `
     CREATE TABLE inbox_items (
       id TEXT PRIMARY KEY,
@@ -3576,6 +3660,7 @@ var MCP_TOOL_GROUPS = {
     "add_task_run_event",
     "add_task_run_file",
     "acknowledge_handoff",
+    "begin_task_run_transaction",
     "build_local_report",
     "cancel_agent_run_dispatch",
     "finish_task_run",
@@ -3623,6 +3708,7 @@ var MCP_TOOL_GROUPS = {
     "list_local_snapshots",
     "list_retrospectives",
     "list_risks",
+    "list_task_findings",
     "list_task_runs",
     "list_verification_providers",
     "merge_duplicate_task",
@@ -3631,6 +3717,7 @@ var MCP_TOOL_GROUPS = {
     "remove_review_routing_rule",
     "restore_local_backup",
     "retry_agent_run_dispatch",
+    "resolve_missing_task_findings",
     "resolve_mentions",
     "run_next_agent_dispatch",
     "search_knowledge_records",
@@ -3673,9 +3760,17 @@ var MCP_TOOL_GROUPS = {
     "unlock_file",
     "unwatch_task",
     "update_comment",
+    "upsert_task_finding",
     "update_risk",
     "watch_task"
   ],
+  loops: [
+    "begin_task_run_transaction",
+    "finish_task_run",
+    "list_task_findings",
+    "resolve_missing_task_findings",
+    "upsert_task_finding"
+  ],
   agents: [
     "auto_assign_task",
     "delete_agent",
@@ -3757,7 +3852,7 @@ var MCP_TOOL_GROUPS = {
   maintenance: ["extract_todos", "get_sla_breaches", "notify_upcoming_deadlines", "run_doctor", "score_task", "watch_source_todos"]
 };
 var MCP_PROFILE_GROUPS = {
-  minimal: ["core"],
+  minimal: ["core", "loops"],
   core: ["core"],
   standard: ["core", "tasks", "projects", "resources", "agents", "metadata"],
   agent: ["core", "tasks", "projects", "resources"],
@@ -4830,6 +4925,92 @@ var TODOS_JSON_CONTRACTS = [
     },
     optional: {}
   }),
+  contract({
+    id: "loop_run_transaction",
+    name: "Loop Run Transaction",
+    description: "Compact local result for idempotent loop run begin/finish transactions.",
+    surfaces: ["cli", "mcp", "sdk"],
+    stability: "stable",
+    required: {
+      schema_version: field("string", "Result schema version."),
+      local_only: field("boolean", "Always true; loop run transactions use local state."),
+      dry_run: field("boolean", "True when no run ledger mutation was applied."),
+      processed_at: isoDateField,
+      action: field("string", "preview, created, matched, finished, or conflict."),
+      key: field("string", "Stable idempotency key used to dedupe the transaction."),
+      run: field(["object", "null"], "Compact run summary or null for create previews.", true),
+      warnings: field("array", "Non-fatal warnings such as terminal-status conflicts."),
+      commands: field("array", "Follow-up CLI commands for agents and operators.")
+    },
+    optional: {}
+  }),
+  contract({
+    id: "task_finding",
+    name: "Task Finding",
+    description: "Compact local finding record deduped by task and fingerprint.",
+    surfaces: ["cli", "mcp", "sdk"],
+    stability: "stable",
+    required: {
+      schema_version: field("string", "Finding schema version."),
+      id: idField,
+      task_id: idField,
+      run_id: field(["string", "null"], "Optional run ledger ID.", true),
+      fingerprint: field("string", "Stable finding fingerprint scoped to the task."),
+      title: field("string", "Short redacted finding title."),
+      severity: field("string", "low, medium, high, or critical."),
+      status: field("string", "open, resolved, or ignored."),
+      source: field(["string", "null"], "Optional loop/tool source.", true),
+      summary: field(["string", "null"], "Bounded redacted finding summary.", true),
+      artifact_path: field(["string", "null"], "Local artifact path/reference; raw content is not included.", true),
+      first_seen_at: isoDateField,
+      last_seen_at: isoDateField,
+      resolved_at: field(["string", "null"], "Resolution timestamp when closed.", true),
+      metadata_keys: field("array", "Sorted metadata keys; metadata values are intentionally omitted in compact output.")
+    },
+    optional: {}
+  }),
+  contract({
+    id: "task_finding_upsert",
+    name: "Task Finding Upsert Result",
+    description: "Local-only dry-run or applied result from idempotently upserting a task finding.",
+    surfaces: ["cli", "mcp", "sdk"],
+    stability: "stable",
+    required: {
+      schema_version: field("string", "Result schema version."),
+      local_only: field("boolean", "Always true; finding upserts use local state."),
+      dry_run: field("boolean", "True when no finding row was created or updated."),
+      processed_at: isoDateField,
+      action: field("string", "preview, created, matched, updated, or reopened."),
+      fingerprint: field("string", "Normalized finding fingerprint."),
+      finding: field(["object", "null"], "Compact finding summary or null for create previews.", true),
+      warnings: field("array", "Non-fatal warnings.")
+    },
+    optional: {}
+  }),
+  contract({
+    id: "task_finding_resolve_missing",
+    name: "Task Finding Resolve Missing Result",
+    description: "Local-only dry-run or applied result from resolving open findings absent from the latest loop finding set.",
+    surfaces: ["cli", "mcp", "sdk"],
+    stability: "stable",
+    required: {
+      schema_version: field("string", "Result schema version."),
+      local_only: field("boolean", "Always true; finding resolution uses local state."),
+      dry_run: field("boolean", "True when no finding rows were changed."),
+      processed_at: isoDateField,
+      action: field("string", "preview, resolved, ignored, or noop."),
+      task_id: idField,
+      source: field(["string", "null"], "Optional source scope.", true),
+      run_id: field(["string", "null"], "Optional run ledger ID used for audit metadata.", true),
+      present_fingerprint_count: field("integer", "Number of fingerprints supplied as still present."),
+      candidate_count: field("integer", "Open findings missing from the supplied set."),
+      changed_count: field("integer", "Rows resolved or ignored by the applied transaction."),
+      omitted_count: field("integer", "Matching findings omitted from bounded output."),
+      findings: field("array", "Bounded compact finding summaries."),
+      warnings: field("array", "Non-fatal warnings.")
+    },
+    optional: {}
+  }),
   contract({
     id: "verification_provider",
     name: "Verification Provider",
@@ -6535,6 +6716,7 @@ var LOCAL_EVENT_TYPES = [
   "task.blocked",
   "task.started",
   "task.completed",
+  "task.updated",
   "task.due",
   "task.due_soon",
   "task.failed",
@@ -6773,7 +6955,7 @@ async function testLocalEventHook(name, input) {
   return emitLocalEventHooks({ ...input, hooks: [hook] });
 }
 
-// node_modules/.bun/@hasna+events@0.1.7/node_modules/@hasna/events/dist/index.js
+// node_modules/.bun/@hasna+events@0.1.9/node_modules/@hasna/events/dist/index.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { existsSync as existsSync6 } from "fs";
 import { homedir } from "os";
@@ -6790,17 +6972,30 @@ function getPathValue(input, path) {
     return;
   }, input);
 }
-function wildcardToRegExp(pattern) {
-  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`);
+function wildcardToRegExp(pattern, options = {}) {
+  let body = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        body += ".*";
+        index += 1;
+      } else {
+        body += options.segmentSafe ? "[^/]*" : ".*";
+      }
+    } else {
+      body += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${body}$`);
 }
-function matchString(value, matcher) {
+function matchString(value, matcher, options = {}) {
   if (matcher === undefined)
     return true;
   if (value === undefined)
     return false;
   const matchers = Array.isArray(matcher) ? matcher : [matcher];
-  return matchers.some((item) => wildcardToRegExp(item).test(value));
+  return matchers.some((item) => wildcardToRegExp(item, options).test(value));
 }
 function matchRecord(input, matcher) {
   if (!matcher)
@@ -6808,7 +7003,9 @@ function matchRecord(input, matcher) {
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
     if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected);
+      return matchString(actual === undefined ? undefined : String(actual), expected, {
+        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+      });
     }
     return actual === expected;
   });
@@ -6828,7 +7025,6 @@ var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join5(homedir(), ".hasna", "events");
 }
-
 class JsonEventsStore {
   dataDir;
   channelsPath;
@@ -7165,7 +7361,7 @@ class EventsClient {
     }
     return deliveries;
   }
-  async testChannel(id, input = {}) {
+  async matchChannel(id, input = {}) {
     const channel = await this.store.getChannel(id);
     if (!channel)
       throw new Error(`Channel not found: ${id}`);
@@ -7182,6 +7378,34 @@ class EventsClient {
       time: input.time,
       id: input.id
     });
+    const matched = channelMatchesEvent(channel, event);
+    return {
+      channelId: channel.id,
+      matched,
+      event,
+      filters: channel.filters,
+      reason: matched ? undefined : channel.enabled ? "event did not match channel filters" : "channel is disabled"
+    };
+  }
+  async testChannel(id, input = {}, options = {}) {
+    const channel = await this.store.getChannel(id);
+    if (!channel)
+      throw new Error(`Channel not found: ${id}`);
+    const match = await this.matchChannel(id, input);
+    const event = match.event;
+    if (options.honorFilters && !match.matched) {
+      const timestamp = new Date().toISOString();
+      const result2 = createDeliveryResult(event, channel, [{
+        attempt: 1,
+        status: "skipped",
+        startedAt: timestamp,
+        completedAt: timestamp,
+        error: match.reason
+      }]);
+      result2.metadata = { reason: "filter_mismatch" };
+      await this.store.appendDelivery(result2);
+      return result2;
+    }
     const eventForChannel = await this.applyRedaction(event, channel);
     const result = await this.deliverWithRetry(eventForChannel, channel);
     await this.store.appendDelivery(result);
@@ -7281,6 +7505,90 @@ function normalizeRetryPolicy(policy) {
   };
 }
 
+// src/lib/shared-events.ts
+init_database();
+
+// src/db/task-lists.ts
+init_types();
+init_database();
+function rowToTaskList(row) {
+  return {
+    ...row,
+    metadata: JSON.parse(row.metadata || "{}")
+  };
+}
+function createTaskList(input, db) {
+  const d = db || getDatabase();
+  const id = uuid();
+  const timestamp = now();
+  const slug = input.slug || slugify(input.name);
+  if (!input.project_id) {
+    const existing = d.query("SELECT id FROM task_lists WHERE project_id IS NULL AND slug = ?").get(slug);
+    if (existing) {
+      throw new Error(`Standalone task list with slug "${slug}" already exists`);
+    }
+  }
+  d.run(`INSERT INTO task_lists (id, project_id, slug, name, description, metadata, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [id, input.project_id || null, slug, input.name, input.description || null, JSON.stringify(input.metadata || {}), timestamp, timestamp]);
+  return getTaskList(id, d);
+}
+function getTaskList(id, db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT * FROM task_lists WHERE id = ?").get(id);
+  return row ? rowToTaskList(row) : null;
+}
+function getTaskListBySlug(slug, projectId, db) {
+  const d = db || getDatabase();
+  let row;
+  if (projectId) {
+    row = d.query("SELECT * FROM task_lists WHERE slug = ? AND project_id = ?").get(slug, projectId);
+  } else {
+    row = d.query("SELECT * FROM task_lists WHERE slug = ? AND project_id IS NULL").get(slug);
+  }
+  return row ? rowToTaskList(row) : null;
+}
+function listTaskLists(projectId, db) {
+  const d = db || getDatabase();
+  if (projectId) {
+    return d.query("SELECT * FROM task_lists WHERE project_id = ? ORDER BY name").all(projectId).map(rowToTaskList);
+  }
+  return d.query("SELECT * FROM task_lists ORDER BY name").all().map(rowToTaskList);
+}
+function updateTaskList(id, input, db) {
+  const d = db || getDatabase();
+  const existing = getTaskList(id, d);
+  if (!existing)
+    throw new TaskListNotFoundError(id);
+  const sets = ["updated_at = ?"];
+  const params = [now()];
+  if (input.name !== undefined) {
+    sets.push("name = ?");
+    params.push(input.name);
+  }
+  if (input.description !== undefined) {
+    sets.push("description = ?");
+    params.push(input.description);
+  }
+  if (input.metadata !== undefined) {
+    sets.push("metadata = ?");
+    params.push(JSON.stringify(input.metadata));
+  }
+  params.push(id);
+  d.run(`UPDATE task_lists SET ${sets.join(", ")} WHERE id = ?`, params);
+  return getTaskList(id, d);
+}
+function deleteTaskList(id, db) {
+  const d = db || getDatabase();
+  return d.run("DELETE FROM task_lists WHERE id = ?", [id]).changes > 0;
+}
+function ensureTaskList(name, slug, projectId, db) {
+  const d = db || getDatabase();
+  const existing = getTaskListBySlug(slug, projectId, d);
+  if (existing)
+    return existing;
+  return createTaskList({ name, slug, project_id: projectId }, d);
+}
+
 // src/lib/shared-events.ts
 var SOURCE = "todos";
 function taskEventData(task, extra = {}) {
@@ -7311,6 +7619,69 @@ function taskEventData(task, extra = {}) {
     ...extra
   };
 }
+function taskEventMetadata(task) {
+  const metadata = {
+    package: "@hasna/todos",
+    todos_event_schema_version: 1,
+    task_id: task.id,
+    task_short_id: task.short_id,
+    project_id: task.project_id,
+    task_list_id: task.task_list_id,
+    working_dir: task.working_dir
+  };
+  try {
+    const project = task.project_id ? getProject(task.project_id) : null;
+    const projectPath = project ? readMachineLocalPath(project) ?? project.path : task.working_dir;
+    if (project) {
+      metadata.project_id = project.id;
+      metadata.project_name = project.name;
+      metadata.project_path = projectPath;
+      metadata.project_canonical_path = project.path;
+      metadata.project_default_task_list_slug = project.task_list_id;
+      metadata.root_project_id = inferRootProjectId(project);
+    } else if (projectPath) {
+      metadata.project_path = projectPath;
+      metadata.project_canonical_path = projectPath;
+    }
+    if (projectPath) {
+      metadata.project_kind = classifyProjectKind(projectPath);
+      metadata.project_is_worktree = isWorktreePath(projectPath);
+      if (typeof task.metadata.route_enabled === "boolean") {
+        metadata.route_enabled = task.metadata.route_enabled;
+      }
+      metadata.working_dir = task.working_dir ?? projectPath;
+    }
+    const taskList = task.task_list_id ? getTaskList(task.task_list_id) ?? (project ? getTaskListBySlug(task.task_list_id, project.id) : null) : project?.task_list_id ? getTaskListBySlug(project.task_list_id, project.id) : null;
+    if (taskList) {
+      metadata.task_list_id = taskList.id;
+      metadata.task_list_slug = taskList.slug;
+      metadata.task_list_name = taskList.name;
+      metadata.task_list_project_id = taskList.project_id;
+      metadata.task_list_is_project_default = Boolean(project?.task_list_id && taskList.slug === project.task_list_id);
+    }
+  } catch {}
+  return metadata;
+}
+function classifyProjectKind(path) {
+  return path.includes("/hasna/opensource/") ? "open-source" : "unknown";
+}
+function isWorktreePath(path) {
+  return path.includes("/.codewith/worktrees/") || path.includes("/.worktrees/");
+}
+function inferRootProjectId(project) {
+  return isWorktreePath(project.path) ? null : project.id;
+}
+function readMachineLocalPath(project) {
+  const machineId = process.env["TODOS_MACHINE_ID"];
+  if (!machineId)
+    return null;
+  try {
+    const row = getDatabase().query("SELECT path FROM project_machine_paths WHERE project_id = ? AND machine_id = ?").get(project.id, machineId);
+    return row?.path ?? null;
+  } catch {
+    return null;
+  }
+}
 async function emitSharedTaskEvent(input) {
   const data = taskEventData(input.task, input.data);
   await new EventsClient().emit({
@@ -7321,12 +7692,7 @@ async function emitSharedTaskEvent(input) {
     message: input.message ?? `${input.type}: ${input.task.title}`,
     data,
     dedupeKey: input.dedupeKey ?? `${input.type}:${input.task.id}:${input.task.version}`,
-    metadata: {
-      package: "@hasna/todos",
-      task_id: input.task.id,
-      project_id: input.task.project_id,
-      task_list_id: input.task.task_list_id
-    }
+    metadata: taskEventMetadata(input.task)
   }, { deliver: true, dedupe: true });
 }
 function emitSharedTaskEventQuiet(input) {
@@ -7689,6 +8055,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();
@@ -7871,6 +8248,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 {
@@ -7895,6 +8273,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 = [];
@@ -7958,6 +8384,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");
   }
@@ -8008,6 +8435,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));
@@ -8096,6 +8527,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 = {
@@ -8131,6 +8564,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) {
@@ -10826,6 +11263,7 @@ function getTaskTraceability(taskId, db) {
 
 // src/db/task-runs.ts
 init_redaction();
+var LOOP_RUN_TRANSACTION_SCHEMA_VERSION = "todos.loop_run_transaction.v1";
 function parseObject(value) {
   if (!value)
     return {};
@@ -10848,6 +11286,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}%`);
@@ -10866,7 +11370,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);
@@ -10904,6 +11408,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);
@@ -11083,6 +11678,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();
@@ -11644,7 +12299,7 @@ function rowToTask2(row) {
     requires_approval: Boolean(row.requires_approval)
   };
 }
-function rowToTaskList(row) {
+function rowToTaskList2(row) {
   return { ...row, metadata: parseJsonObject3(row.metadata) };
 }
 function rowWithMetadata(row) {
@@ -11680,7 +12335,7 @@ function createLocalBridgeBundle(options = {}, db) {
   const project = options.project_id ? d.query("SELECT * FROM projects WHERE id = ?").get(options.project_id) : null;
   const data = redactValue({
     projects: options.project_id ? project ? [project] : [] : d.query("SELECT * FROM projects ORDER BY name").all(),
-    task_lists: (options.project_id ? d.query("SELECT * FROM task_lists WHERE project_id = ? ORDER BY name").all(options.project_id) : d.query("SELECT * FROM task_lists ORDER BY name").all()).map(rowToTaskList),
+    task_lists: (options.project_id ? d.query("SELECT * FROM task_lists WHERE project_id = ? ORDER BY name").all(options.project_id) : d.query("SELECT * FROM task_lists ORDER BY name").all()).map(rowToTaskList2),
     plans: options.project_id ? d.query("SELECT * FROM plans WHERE project_id = ? ORDER BY created_at").all(options.project_id) : d.query("SELECT * FROM plans ORDER BY created_at").all(),
     tasks: queryByTaskIds(d, "SELECT * FROM tasks WHERE id IN (__TASK_IDS__) ORDER BY created_at", taskIds).map(rowToTask2),
     task_dependencies: queryByTaskIds(d, "SELECT task_id, depends_on, external_project_id, external_task_id FROM task_dependencies WHERE task_id IN (__TASK_IDS__) ORDER BY task_id, depends_on", taskIds),
@@ -17263,7 +17918,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,
@@ -17324,7 +17979,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);
@@ -19795,6 +20450,33 @@ var TODOS_API_ROUTES = [
     tags: ["tasks", "mutation"],
     stability: "stable"
   },
+  {
+    id: "tasks.upsert",
+    method: "POST",
+    path: "/api/tasks/upsert",
+    description: "Create or update a task by stable metadata fingerprint, merging metadata on updates.",
+    auth: "optional-api-key",
+    requestSchema: {
+      type: "object",
+      properties: {
+        fingerprint: { type: "string" },
+        title: { type: "string" },
+        description: { type: "string" },
+        priority: { type: "string", enum: TASK_PRIORITIES },
+        status: { type: "string", enum: TASK_STATUSES },
+        project_id: { type: "string" },
+        task_list_id: { type: "string" },
+        working_dir: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+        metadata: objectSchema
+      },
+      required: ["fingerprint", "title"],
+      additionalProperties: true
+    },
+    responseSchema: objectSchema,
+    tags: ["tasks", "mutation", "dedupe"],
+    stability: "stable"
+  },
   {
     id: "tasks.read",
     method: "GET",