agent-relay-server 0.107.0 → 0.109.0

package/src/db/migrations.ts

@@ -165,7 +165,7 @@ export function applyMigrations(): void {
   getDb().run(`
     CREATE TABLE IF NOT EXISTS issue_associations (
       issue_ref_id TEXT NOT NULL REFERENCES issue_refs(id) ON DELETE CASCADE,
-      entity_type TEXT NOT NULL CHECK (entity_type IN ('team', 'plan-node', 'epic')),
+      entity_type TEXT NOT NULL CHECK (entity_type IN ('team', 'plan-node', 'epic', 'task')),
       entity_id TEXT NOT NULL,
       created_at INTEGER NOT NULL,
       PRIMARY KEY (issue_ref_id, entity_type, entity_id)
@@ -265,7 +265,10 @@ export function applyMigrations(): void {
   getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_thread ON messages(thread_id)");
   getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_msg_idempotency ON messages(from_agent, idempotency_key) WHERE idempotency_key IS NOT NULL");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_delivery_status ON messages(delivery_status)");
-  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_resolved_to_agent ON messages(resolved_to_agent)");
+  // (#846) composite replaces the old single-column idx_msg_resolved_to_agent; created
+  // here — AFTER the resolved_to_agent ALTER above — so existing DBs without the column
+  // don't crash (same hazard as idx_msg_from_kind_id / #483/#559).
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_resolved_to_id ON messages(resolved_to_agent, id)");
 
   getDb().run(`
     CREATE TABLE IF NOT EXISTS agent_continuations (
@@ -294,6 +297,20 @@ export function applyMigrations(): void {
     ON continuation_archives(agent_id, generation, created_at DESC)
   `);
   ensureContinuationArchiveSearchSchema();
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS task_memories (
+      task_id INTEGER PRIMARY KEY REFERENCES tasks(id) ON DELETE CASCADE,
+      objective TEXT NOT NULL,
+      generation INTEGER NOT NULL DEFAULT 0,
+      ledger TEXT NOT NULL DEFAULT '[]',
+      decisions TEXT NOT NULL DEFAULT '[]',
+      working_state TEXT NOT NULL DEFAULT '',
+      archive_refs TEXT NOT NULL DEFAULT '[]',
+      budget TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
 
   const tokenCols = getDb().query("PRAGMA table_info(tokens)").all() as any[];
   const tokenColNames = tokenCols.map((c: any) => c.name);
@@ -1013,4 +1030,97 @@ export function applyMigrations(): void {
   getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_creator ON scheduled_timers(created_by, enabled, next_run_at)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_correlation ON scheduled_timers(correlation_id)");
 
+  // #834 — grow `tasks` into the durable Task entity. Additive, kind-fenced columns:
+  // existing rows default to kind='claim'/deliverable_stage='none', so every legacy
+  // claim path is byte-for-byte unaffected. The claim-lease machinery filters kind='claim'.
+  const durableTaskCols = (getDb().query("PRAGMA table_info(tasks)").all() as any[]).map((c: any) => c.name);
+  const addTaskCol = (name: string, ddl: string) => {
+    if (!durableTaskCols.includes(name)) getDb().run(`ALTER TABLE tasks ADD COLUMN ${ddl}`);
+  };
+  addTaskCol("kind", "kind TEXT NOT NULL DEFAULT 'claim'");
+  addTaskCol("intent", "intent TEXT");
+  addTaskCol("latest_steer", "latest_steer TEXT");
+  addTaskCol("deliverable_stage", "deliverable_stage TEXT NOT NULL DEFAULT 'none'");
+  addTaskCol("blocked_by", "blocked_by TEXT");
+  addTaskCol("branch", "branch TEXT");
+  addTaskCol("commits", "commits TEXT");
+  addTaskCol("done_when", "done_when TEXT");
+  addTaskCol("team_id", "team_id TEXT");
+  addTaskCol("created_by", "created_by TEXT");
+  addTaskCol("owner_agent_id", "owner_agent_id TEXT");
+  addTaskCol("dispatch", "dispatch TEXT");
+  addTaskCol("reaped_at", "reaped_at INTEGER");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_kind ON tasks(kind, status, updated_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_branch ON tasks(branch) WHERE branch IS NOT NULL");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_team ON tasks(team_id) WHERE team_id IS NOT NULL");
+
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS task_dependencies (
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      depends_on_task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (task_id, depends_on_task_id)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_task_dependencies_depended ON task_dependencies(depends_on_task_id)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_task_events_task_type ON task_events(task_id, type, id DESC)");
+
+  // #833 — comment-through idempotency outbox (reserve→post→finalize). Existing DBs gain
+  // the table here; the UNIQUE claim is what makes the write-through concurrency/crash-safe.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS task_comment_throughs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      kind TEXT NOT NULL,
+      idempotency_key TEXT NOT NULL,
+      status TEXT NOT NULL,
+      event_id INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE (task_id, kind, idempotency_key)
+    )
+  `);
+
+  // #834 — issue_associations.entity_type gained 'task'. The CHECK constraint is baked into
+  // the table SQL, so a TS-only enum change would fail at runtime; rebuild the table (SQLite
+  // can't ALTER a CHECK). Guarded on the absence of 'task' in the stored DDL so it runs once.
+  const issueAssocSql = (getDb().query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'issue_associations'").get() as { sql?: string } | undefined)?.sql;
+  if (issueAssocSql && !issueAssocSql.includes("'task'")) {
+    getDb().transaction(() => {
+      getDb().run("ALTER TABLE issue_associations RENAME TO issue_associations_old");
+      getDb().run(`
+        CREATE TABLE issue_associations (
+          issue_ref_id TEXT NOT NULL REFERENCES issue_refs(id) ON DELETE CASCADE,
+          entity_type TEXT NOT NULL CHECK (entity_type IN ('team', 'plan-node', 'epic', 'task')),
+          entity_id TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          PRIMARY KEY (issue_ref_id, entity_type, entity_id)
+        )
+      `);
+      getDb().run(`
+        INSERT INTO issue_associations (issue_ref_id, entity_type, entity_id, created_at)
+        SELECT issue_ref_id, entity_type, entity_id, created_at FROM issue_associations_old
+      `);
+      getDb().run("DROP TABLE issue_associations_old");
+    })();
+    getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_associations_entity ON issue_associations(entity_type, entity_id, created_at DESC)");
+    getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_associations_issue ON issue_associations(issue_ref_id, created_at DESC)");
+  }
+
+  // #846 — drop the superseded single-column indexes so the planner is forced to
+  // choose the composite replacements (idx_msg_to_id / idx_msg_resolved_to_id).
+  // When both old and new exist the planner may prefer the old single-column index,
+  // silently defeating the ORDER BY id optimisation.  DROP INDEX IF EXISTS is
+  // idempotent and safe on any populated DB.  Guard ANALYZE on the presence of the
+  // old idx_msg_to: it exists on pre-#846 DBs and is absent once this block has run,
+  // so ANALYZE executes exactly once per DB (on first boot with the new code).
+  // Fresh DBs never create idx_msg_to (removed from base schema), so the guard is
+  // false and ANALYZE is skipped (the first-boot `if (!hasStats)` path in initDb
+  // covers fresh DBs instead).
+  const hasOldToIdx = !!getDb()
+    .query("SELECT 1 FROM sqlite_master WHERE type='index' AND name='idx_msg_to'")
+    .get();
+  getDb().run("DROP INDEX IF EXISTS idx_msg_to");
+  getDb().run("DROP INDEX IF EXISTS idx_msg_resolved_to_agent");
+  if (hasOldToIdx) getDb().run("ANALYZE messages");
 }

package/src/db/notification-subscriptions.ts

@@ -48,7 +48,7 @@ interface NotificationSubscriptionRow {
   created_at: number;
 }
 
-const SCOPE_KEYS = ["author", "agentId", "parent", "teamId", "planId", "repoRoot", "workspaceId", "paths"] as const;
+const SCOPE_KEYS = ["author", "agentId", "parent", "teamId", "planId", "taskId", "transition", "landKey", "repoRoot", "workspaceId", "paths"] as const;
 
 export function addSubscription(input: {
   agentId: string;

package/src/db/prompt-templates.ts

@@ -67,6 +67,12 @@ export function seedTemplates(templates: SeedTemplate[]): void {
       slug, category, title, description, template, default_template, variables, updated_at, created_at
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
+  const current = getDb().query("SELECT * FROM prompt_templates WHERE slug = ?");
+  const update = getDb().query(`
+    UPDATE prompt_templates
+    SET category = ?, title = ?, description = ?, template = ?, default_template = ?, variables = ?, updated_at = ?
+    WHERE slug = ?
+  `);
   const tx = getDb().transaction((items: SeedTemplate[]) => {
     for (const item of items) {
       insert.run(
@@ -80,6 +86,19 @@ export function seedTemplates(templates: SeedTemplate[]): void {
         now,
         now,
       );
+      const row = current.get(item.slug) as PromptTemplateRow | null;
+      if (!row) continue;
+      const template = row.template === row.default_template ? item.template : row.template;
+      update.run(
+        item.category,
+        item.title,
+        item.description ?? null,
+        template,
+        item.defaultTemplate,
+        JSON.stringify(item.variables),
+        now,
+        item.slug,
+      );
     }
   });
   tx(templates);

package/src/db/schema.ts

@@ -157,7 +157,13 @@ export function initDb(path: string = "agent-relay.db"): Database {
       occurred_at INTEGER
     );
 
-    CREATE INDEX IF NOT EXISTS idx_msg_to ON messages(to_target);
+    -- (#846) composite covers ORDER BY id DESC for the to_target branch of
+    -- listAgentChatHistory without a filesort.  The composite is a leftmost-prefix
+    -- superset of the old idx_msg_to single-column index, so all WHERE to_target=?
+    -- queries (delivery, polling, etc.) are served identically.
+    -- idx_msg_resolved_to_id is created in applyMigrations() AFTER the
+    -- resolved_to_agent ALTER — never inline here (same hazard as #483/#559).
+    CREATE INDEX IF NOT EXISTS idx_msg_to_id ON messages(to_target, id);
     CREATE INDEX IF NOT EXISTS idx_msg_created ON messages(created_at);
     CREATE INDEX IF NOT EXISTS idx_msg_channel ON messages(channel);
     -- (reply_to, from_agent) powers the reply-obligation NOT EXISTS subquery in
@@ -395,6 +401,23 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_continuation_archives_agent_generation
       ON continuation_archives(agent_id, generation, created_at DESC);
 
+    -- #832 — Task-bound memory is the task-local slice of the #815 scoped-knowledge
+    -- chain. It mirrors the self-resume continuation envelope shape now; when #815
+    -- lands, this table becomes the task/session scope adapter instead of a parallel
+    -- memory system.
+    CREATE TABLE IF NOT EXISTS task_memories (
+      task_id INTEGER PRIMARY KEY REFERENCES tasks(id) ON DELETE CASCADE,
+      objective TEXT NOT NULL,
+      generation INTEGER NOT NULL DEFAULT 0,
+      ledger TEXT NOT NULL DEFAULT '[]',
+      decisions TEXT NOT NULL DEFAULT '[]',
+      working_state TEXT NOT NULL DEFAULT '',
+      archive_refs TEXT NOT NULL DEFAULT '[]',
+      budget TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS memories (
       id TEXT PRIMARY KEY,
       type TEXT NOT NULL,
@@ -619,13 +642,58 @@ export function initDb(path: string = "agent-relay.db"): Database {
       metadata TEXT NOT NULL DEFAULT '{}',
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL,
-      last_seen_at INTEGER NOT NULL
+      last_seen_at INTEGER NOT NULL,
+      -- #834 durable-Task facet. kind='claim' (default) is the historical claimable
+      -- work-item lane; kind='deliverable' is the durable coordination Task. The claim-
+      -- lease machinery is fenced to kind='claim' (see claimTaskWhere in task-core.ts).
+      kind TEXT NOT NULL DEFAULT 'claim',
+      intent TEXT,
+      latest_steer TEXT,
+      deliverable_stage TEXT NOT NULL DEFAULT 'none',
+      blocked_by TEXT,
+      branch TEXT,
+      commits TEXT,
+      done_when TEXT,
+      team_id TEXT,
+      created_by TEXT,
+      owner_agent_id TEXT,
+      dispatch TEXT,
+      reaped_at INTEGER
     );
 
     CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_source_dedupe ON tasks(source, dedupe_key) WHERE dedupe_key IS NOT NULL AND status NOT IN ('done', 'failed', 'canceled');
     CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
     CREATE INDEX IF NOT EXISTS idx_tasks_target ON tasks(target);
     CREATE INDEX IF NOT EXISTS idx_tasks_updated ON tasks(updated_at);
+    -- idx_tasks_kind / idx_tasks_branch / idx_tasks_team reference the #834 columns and are
+    -- created in applyMigrations() AFTER the ALTERs — never inline here: an existing pre-#834
+    -- tasks table makes CREATE TABLE IF NOT EXISTS a no-op, so an inline index over a column
+    -- it doesn't yet have crashes initDb (same hazard as idx_projects_scope_anchor above).
+
+    -- #834 task→task dependency DAG (the edges the plan DAG collapses into; #835).
+    -- Cycle-rejected transactionally on insert (src/db/task-entity.ts).
+    CREATE TABLE IF NOT EXISTS task_dependencies (
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      depends_on_task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (task_id, depends_on_task_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_task_dependencies_depended ON task_dependencies(depends_on_task_id);
+
+    -- #833 comment-through idempotency outbox: reserve→post→finalize so a Task comment
+    -- written THROUGH to GitHub is concurrency- and crash-safe (UNIQUE claim before the
+    -- adapter append; receipt only after it succeeds). Logic in src/db/task-comment-through.ts.
+    CREATE TABLE IF NOT EXISTS task_comment_throughs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      kind TEXT NOT NULL,
+      idempotency_key TEXT NOT NULL,
+      status TEXT NOT NULL,
+      event_id INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE (task_id, kind, idempotency_key)
+    );
 
     CREATE TABLE IF NOT EXISTS automations (
       id TEXT PRIMARY KEY,
@@ -682,6 +750,10 @@ export function initDb(path: string = "agent-relay.db"): Database {
       created_at INTEGER NOT NULL
     );
 
+    -- #834 — supports the deterministic latest-per-gate projection (type LIKE 'gate:%')
+    -- and append-history reads. The audit ledger stays append-only; this is just the index.
+    CREATE INDEX IF NOT EXISTS idx_task_events_task_type ON task_events(task_id, type, id DESC);
+
     CREATE TABLE IF NOT EXISTS task_callback_deliveries (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,

package/src/db/stats.ts

@@ -18,6 +18,7 @@ import { listAgents } from "./agents.ts";
 import { listChannels } from "./channels.ts";
 import { countExpiredUndeliveredMessages } from "./delivery.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
+import { claimTaskWhere } from "./task-core.ts";
 import { getDb } from "./connection.ts";
 import type {
   AgentCard,
@@ -428,7 +429,7 @@ export function getHealth(now: number = Date.now()): HealthReport {
   });
 
   const expiredTaskClaims = (getDb()
-    .query("SELECT COUNT(*) as c FROM tasks WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')")
+    .query(`SELECT COUNT(*) as c FROM tasks WHERE ${claimTaskWhere()} AND claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')`)
     .get(now) as any).c as number;
   checks.push({
     name: "expired-task-claims",
@@ -442,7 +443,7 @@ export function getHealth(now: number = Date.now()): HealthReport {
       SELECT COUNT(*) as c
       FROM tasks t
       JOIN agents a ON a.id = t.claimed_by
-      WHERE t.status IN ('claimed', 'in_progress', 'blocked') AND a.status = 'offline'
+      WHERE ${claimTaskWhere("t.")} AND t.status IN ('claimed', 'in_progress', 'blocked') AND a.status = 'offline'
     `)
     .get() as any).c as number;
   checks.push({

package/src/db/task-comment-through.ts

@@ -0,0 +1,112 @@
+// #833 — the comment-through idempotency outbox. The Task↔issue weave writes discussion
+// THROUGH to GitHub (the backing store); to keep "Task is a lens, GitHub is the store"
+// honest, a write-through must be reserve→post→finalize, never scan→post→insert:
+//   - a UNIQUE(task_id, kind, idempotency_key) claim is taken TRANSACTIONALLY before the
+//     awaited GitHub append, so two concurrent same-key requests can't both post.
+//   - a receipt (status='posted') is only written AFTER the adapter succeeds, so a failed
+//     GitHub post never leaves a local "posted" record that a retry would dedupe against.
+// A caught failure flips the row to 'failed' (reclaimable — a retry re-posts). A reservation
+// abandoned past RESERVATION_TTL_MS (crash mid-flight) is reclaimable too; within the TTL a
+// concurrent attempt sees 'in_flight' and stands down (at-most-once in the ambiguous window).
+import { getDb, ValidationError } from "./connection.ts";
+
+// A crashed reservation older than this is treated as abandoned and reclaimable. Inside the
+// window, a same-key attempt stands down rather than risk a duplicate GitHub comment.
+export const RESERVATION_TTL_MS = 120_000;
+
+export type TaskCommentThroughKind = "discussion" | "milestone";
+export type TaskCommentThroughStatus = "reserved" | "posted" | "failed";
+
+export interface TaskCommentThroughRecord {
+  id: number;
+  taskId: number;
+  kind: TaskCommentThroughKind;
+  idempotencyKey: string;
+  status: TaskCommentThroughStatus;
+  eventId?: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+interface TaskCommentThroughRow {
+  id: number;
+  task_id: number;
+  kind: TaskCommentThroughKind;
+  idempotency_key: string;
+  status: TaskCommentThroughStatus;
+  event_id: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+function rowTo(row: TaskCommentThroughRow): TaskCommentThroughRecord {
+  return {
+    id: row.id,
+    taskId: row.task_id,
+    kind: row.kind,
+    idempotencyKey: row.idempotency_key,
+    status: row.status,
+    ...(row.event_id !== null ? { eventId: row.event_id } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function getRow(taskId: number, kind: TaskCommentThroughKind, key: string): TaskCommentThroughRow | undefined {
+  return getDb()
+    .query("SELECT * FROM task_comment_throughs WHERE task_id = ? AND kind = ? AND idempotency_key = ?")
+    .get(taskId, kind, key) as TaskCommentThroughRow | undefined;
+}
+
+// reserved   → caller holds the claim; proceed to post, then finalize/fail. `reconcileNeeded`
+//              is true ONLY when a stale `reserved` row was reclaimed — that case is ambiguous
+//              (the prior attempt may have posted to GitHub then crashed before finalize), so
+//              the caller MUST reconcile against the issue's comments before re-posting. A
+//              `failed` reclaim or a fresh reservation is unambiguous (reconcileNeeded=false).
+// in_flight  → another attempt holds a fresh claim; caller must NOT post (dedupe).
+// duplicate  → already posted; caller returns the prior receipt.
+export type ReserveOutcome =
+  | { outcome: "reserved"; record: TaskCommentThroughRecord; reconcileNeeded: boolean }
+  | { outcome: "in_flight"; record: TaskCommentThroughRecord }
+  | { outcome: "duplicate"; record: TaskCommentThroughRecord };
+
+// Transactional claim. Runs check+insert/update inside a single SQLite write transaction
+// (single-writer ⇒ serialized), so concurrent callers can never both come back 'reserved'.
+export function reserveCommentThrough(
+  taskId: number,
+  kind: TaskCommentThroughKind,
+  idempotencyKey: string,
+  now: number,
+): ReserveOutcome {
+  const key = idempotencyKey.trim();
+  if (!key) throw new ValidationError("idempotencyKey required to reserve a comment-through");
+  return getDb().transaction((): ReserveOutcome => {
+    const existing = getRow(taskId, kind, key);
+    if (existing) {
+      if (existing.status === "posted") return { outcome: "duplicate", record: rowTo(existing) };
+      const staleReserved = existing.status === "reserved" && now - existing.updated_at >= RESERVATION_TTL_MS;
+      const reclaimable = existing.status === "failed" || staleReserved;
+      if (!reclaimable) return { outcome: "in_flight", record: rowTo(existing) };
+      getDb().query("UPDATE task_comment_throughs SET status = 'reserved', event_id = NULL, updated_at = ? WHERE id = ?").run(now, existing.id);
+      // Only a stale-`reserved` reclaim is ambiguous about whether GitHub already got the post.
+      return { outcome: "reserved", record: rowTo(getRow(taskId, kind, key)!), reconcileNeeded: staleReserved };
+    }
+    getDb()
+      .query("INSERT INTO task_comment_throughs (task_id, kind, idempotency_key, status, created_at, updated_at) VALUES (?, ?, ?, 'reserved', ?, ?)")
+      .run(taskId, kind, key, now, now);
+    return { outcome: "reserved", record: rowTo(getRow(taskId, kind, key)!), reconcileNeeded: false };
+  })();
+}
+
+export function finalizeCommentThrough(id: number, eventId: number, now: number): void {
+  getDb().query("UPDATE task_comment_throughs SET status = 'posted', event_id = ?, updated_at = ? WHERE id = ?").run(eventId, now, id);
+}
+
+export function failCommentThrough(id: number, now: number): void {
+  getDb().query("UPDATE task_comment_throughs SET status = 'failed', event_id = NULL, updated_at = ? WHERE id = ?").run(now, id);
+}
+
+export function getCommentThrough(taskId: number, kind: TaskCommentThroughKind, key: string): TaskCommentThroughRecord | null {
+  const row = getRow(taskId, kind, key.trim());
+  return row ? rowTo(row) : null;
+}

package/src/db/task-core.ts

@@ -4,6 +4,19 @@ import type { TaskEvent } from "../types";
 
 export const TASK_SELECT = "SELECT * FROM tasks";
 
+// #834 — the claim/deliverable partition is a REAL fence, not a convention. Every claim,
+// lease, orphan, on-demand-settle and health query that touches `claimed_by` MUST be scoped
+// to kind='claim' so the claim-lease machinery can never mutate a durable deliverable Task
+// (e.g. release/orphan one whose owner_agent_id is set). Route ALL such SQL through this.
+export const CLAIM_TASK_KIND = "claim";
+export const DELIVERABLE_TASK_KIND = "deliverable";
+
+/** SQL predicate fencing a query to claim-lane tasks. `prefix` is an optional table
+ * alias with trailing dot (e.g. `claimTaskWhere("t.")` → `t.kind = 'claim'`). */
+export function claimTaskWhere(prefix = ""): string {
+  return `${prefix}kind = '${CLAIM_TASK_KIND}'`;
+}
+
 export function insertTaskEvent(taskId: number, event: Required<Omit<TaskEvent, "id" | "taskId" | "createdAt">>, now: number): TaskEvent {
   const result = getDb().query(`
     INSERT INTO task_events (task_id, source, type, severity, title, body, metadata, created_at)
@@ -12,7 +25,7 @@ export function insertTaskEvent(taskId: number, event: Required<Omit<TaskEvent,
   return getTaskEvent(Number(result.lastInsertRowid))!;
 }
 
-function getTaskEvent(id: number): TaskEvent | null {
+export function getTaskEvent(id: number): TaskEvent | null {
   const row = getDb().query("SELECT * FROM task_events WHERE id = ?").get(id) as any;
   return row ? rowToTaskEvent(row) : null;
 }