agent-relay-server 0.106.0 → 0.108.0

package/src/db/task-entity.ts

@@ -0,0 +1,629 @@
+// #834 — the durable first-class Task entity (keystone of #830).
+//
+// This module owns the `kind='deliverable'` facet of the `tasks` table: the durable
+// coordination Task that threads issues / branch / commits / dependencies / quality gates.
+// The historical claim-lane lives in tasks.ts and is fenced off by `claimTaskWhere`
+// (see task-core.ts) — the two facets share a table but never each other's machinery.
+//
+// Source-of-truth boundary (#830/#833): GitHub owns intent/spec/acceptance/discussion;
+// the Task owns execution telemetry (status, deliverable stage, gate results, branch,
+// commits, deps, attribution). Issue links are a PROJECTION of issue_associations
+// (entity_type='task') — never a duplicated column — so they cannot drift.
+import {
+  TASK_DELIVERABLE_STAGES,
+  TASK_BLOCKER_TYPES,
+  TASK_GATE_STATUSES,
+  type Task,
+  type TaskBlocker,
+  type TaskCommitRef,
+  type TaskDeliverableStage,
+  type TaskDependency,
+  type TaskDetail,
+  type TaskDispatch,
+  type TaskGateState,
+  type TaskGateStatus,
+  type TaskIssueLink,
+  type TaskStatus,
+} from "../types";
+import { parseJson } from "../utils";
+import { getDb, ValidationError } from "./connection.ts";
+import { rowToTask } from "./mappers.ts";
+import { TASK_SELECT, insertTaskEvent, DELIVERABLE_TASK_KIND } from "./task-core.ts";
+import { associateIssue, listIssuesForEntity, removeAssociation } from "./issue-associations.ts";
+import { resolveIssueRefFromString } from "./issue-refs.ts";
+
+// Execution-status axis (#834): the existing claim FSM vocabulary, reused so there is no
+// enum break. not-started=open, working=in_progress, plus claimed/blocked/done/failed/canceled.
+const DELIVERABLE_STATUSES: readonly TaskStatus[] = ["open", "claimed", "in_progress", "blocked", "done", "failed", "canceled"];
+const GATE_EVENT_PREFIX = "gate:";
+
+function taskEntityId(id: string): string {
+  return String(id);
+}
+
+function requireText(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError(`${field} required`);
+  const cleaned = value.trim();
+  if (cleaned.length > max) throw new ValidationError(`${field} must be ${max} characters or fewer`);
+  return cleaned;
+}
+
+function optionalText(value: unknown, field: string, max: number): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
+  const cleaned = value.trim();
+  if (!cleaned) return undefined;
+  if (cleaned.length > max) throw new ValidationError(`${field} must be ${max} characters or fewer`);
+  return cleaned;
+}
+
+function cleanBlockedBy(value: unknown): TaskBlocker[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError("blockedBy must be an array");
+  return value.map((entry, i) => {
+    if (typeof entry !== "object" || entry === null) throw new ValidationError(`blockedBy[${i}] must be an object`);
+    const type = (entry as any).type;
+    if (!TASK_BLOCKER_TYPES.includes(type)) throw new ValidationError(`blockedBy[${i}].type must be one of: ${TASK_BLOCKER_TYPES.join(", ")}`);
+    return {
+      type,
+      ...(optionalText((entry as any).ref, "blockedBy.ref", 240) ? { ref: optionalText((entry as any).ref, "blockedBy.ref", 240)! } : {}),
+      ...(optionalText((entry as any).note, "blockedBy.note", 2000) ? { note: optionalText((entry as any).note, "blockedBy.note", 2000)! } : {}),
+    };
+  });
+}
+
+function cleanDispatch(value: unknown): TaskDispatch | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "object") throw new ValidationError("dispatch must be an object");
+  const d = value as Record<string, unknown>;
+  const out: TaskDispatch = {};
+  if (d.complexity !== undefined) out.complexity = d.complexity as TaskDispatch["complexity"];
+  if (d.type !== undefined) out.type = d.type as TaskDispatch["type"];
+  if (d.contextFootprint !== undefined) out.contextFootprint = d.contextFootprint as TaskDispatch["contextFootprint"];
+  if (d.criticality !== undefined) out.criticality = d.criticality as TaskDispatch["criticality"];
+  return out;
+}
+
+function getRawTask(id: number): Task | null {
+  const row = getDb().query(`${TASK_SELECT} WHERE id = ?`).get(id) as any;
+  return row ? rowToTask(row) : null;
+}
+
+function requireDeliverable(id: number): Task {
+  const task = getRawTask(id);
+  if (!task) throw new ValidationError(`task ${id} not found`);
+  if (task.kind !== DELIVERABLE_TASK_KIND) throw new ValidationError(`task ${id} is not a deliverable task`);
+  return task;
+}
+
+export interface CreateDeliverableTaskInput {
+  title: string;
+  intent?: string;
+  doneWhen?: string;
+  teamId?: string;
+  createdBy: string;
+  source?: string;
+  target?: string;
+  latestSteer?: string;
+  dispatch?: TaskDispatch;
+}
+
+export function createDeliverableTask(input: CreateDeliverableTaskInput): TaskDetail {
+  const title = requireText(input.title, "title", 500);
+  const createdBy = requireText(input.createdBy, "createdBy", 200);
+  const intent = optionalText(input.intent, "intent", 1_000_000);
+  const now = Date.now();
+  const dispatch = cleanDispatch(input.dispatch);
+  // Legacy NOT-NULL columns have no DB defaults (#834 finding 6) — set them explicitly.
+  const result = getDb().query(`
+    INSERT INTO tasks (
+      source, title, body, severity, status, target, occurrence_count, metadata,
+      created_at, updated_at, last_seen_at,
+      kind, intent, latest_steer, deliverable_stage, done_when, team_id, created_by, dispatch
+    ) VALUES (?, ?, ?, 'info', 'open', ?, 1, '{}', ?, ?, ?, '${DELIVERABLE_TASK_KIND}', ?, ?, 'none', ?, ?, ?, ?)
+  `).run(
+    optionalText(input.source, "source", 200) ?? "coordinator",
+    title,
+    intent ?? title,
+    optionalText(input.target, "target", 200) ?? createdBy,
+    now, now, now,
+    intent ?? null,
+    optionalText(input.latestSteer, "latestSteer", 1_000_000) ?? null,
+    optionalText(input.doneWhen, "doneWhen", 1_000_000) ?? null,
+    optionalText(input.teamId, "teamId", 200) ?? null,
+    createdBy,
+    dispatch ? JSON.stringify(dispatch) : null,
+  );
+  const id = Number(result.lastInsertRowid);
+  insertTaskEvent(id, {
+    source: createdBy,
+    type: "task.created",
+    severity: "info",
+    title: `Task created: ${title}`,
+    body: intent ?? "",
+    metadata: { createdBy, ...(dispatch ? { dispatch } : {}) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export interface UpdateDeliverableTaskInput {
+  title?: string;
+  intent?: string;
+  latestSteer?: string;
+  doneWhen?: string;
+  dispatch?: TaskDispatch;
+  teamId?: string;
+  actor?: string;
+}
+
+export function updateDeliverableTask(id: number, input: UpdateDeliverableTaskInput): TaskDetail {
+  requireDeliverable(id);
+  const sets: string[] = [];
+  const params: unknown[] = [];
+  const push = (col: string, val: unknown) => { sets.push(`${col} = ?`); params.push(val); };
+  if (input.title !== undefined) push("title", requireText(input.title, "title", 500));
+  if (input.intent !== undefined) push("intent", optionalText(input.intent, "intent", 1_000_000) ?? null);
+  if (input.latestSteer !== undefined) push("latest_steer", optionalText(input.latestSteer, "latestSteer", 1_000_000) ?? null);
+  if (input.doneWhen !== undefined) push("done_when", optionalText(input.doneWhen, "doneWhen", 1_000_000) ?? null);
+  if (input.teamId !== undefined) push("team_id", optionalText(input.teamId, "teamId", 200) ?? null);
+  if (input.dispatch !== undefined) { const d = cleanDispatch(input.dispatch); push("dispatch", d ? JSON.stringify(d) : null); }
+  const now = Date.now();
+  if (sets.length > 0) {
+    params.push(now, id);
+    getDb().query(`UPDATE tasks SET ${sets.join(", ")}, updated_at = ? WHERE id = ?`).run(...params as any[]);
+  }
+  insertTaskEvent(id, {
+    source: input.actor ?? "agent-relay",
+    type: "task.updated",
+    severity: "info",
+    title: "Task updated",
+    body: input.latestSteer ? `steer: ${input.latestSteer}` : "",
+    metadata: { fields: sets.map((s) => s.split(" = ")[0]) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export interface SetTaskStatusInput {
+  status: TaskStatus;
+  blockedBy?: TaskBlocker[];
+  note?: string;
+  actor?: string;
+}
+
+// Execution-status transition (#834). NEVER touches claimed_by — that column is exclusive to
+// the claim lane, so the claim-lease maintenance machinery can never act on a deliverable Task.
+export function setTaskStatus(id: number, input: SetTaskStatusInput): TaskDetail {
+  requireDeliverable(id);
+  if (!DELIVERABLE_STATUSES.includes(input.status)) {
+    throw new ValidationError(`status must be one of: ${DELIVERABLE_STATUSES.join(", ")}`);
+  }
+  const blockedBy = cleanBlockedBy(input.blockedBy);
+  if (input.status === "blocked" && (!blockedBy || blockedBy.length === 0)) {
+    throw new ValidationError("blockedBy is required (non-empty) when status is 'blocked'");
+  }
+  const now = Date.now();
+  // Clearing the blocker set when leaving 'blocked' keeps the row self-consistent.
+  const blockedJson = input.status === "blocked" ? JSON.stringify(blockedBy) : null;
+  getDb().query("UPDATE tasks SET status = ?, blocked_by = ?, updated_at = ?, last_seen_at = ? WHERE id = ?")
+    .run(input.status, blockedJson, now, now, id);
+  insertTaskEvent(id, {
+    source: input.actor ?? "agent-relay",
+    type: `status:${input.status}`,
+    severity: "info",
+    title: `Task ${input.status}`,
+    body: input.note ?? "",
+    metadata: { status: input.status, ...(blockedBy ? { blockedBy } : {}) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export interface SetTaskStageInput {
+  deliverableStage: TaskDeliverableStage;
+  branch?: string;
+  commit?: TaskCommitRef;
+  actor?: string;
+}
+
+// Deliverable-position transition (#834). Designed to be driven OBSERVABLY by the land/deploy
+// pipeline (#831 wires it); exposed here for manual/test use. Composes with status, never claims.
+export function setTaskStage(id: number, input: SetTaskStageInput): TaskDetail {
+  requireDeliverable(id);
+  if (!TASK_DELIVERABLE_STAGES.includes(input.deliverableStage)) {
+    throw new ValidationError(`deliverableStage must be one of: ${TASK_DELIVERABLE_STAGES.join(", ")}`);
+  }
+  const now = Date.now();
+  const sets = ["deliverable_stage = ?"];
+  const params: unknown[] = [input.deliverableStage];
+  const branch = optionalText(input.branch, "branch", 500);
+  if (branch) { sets.push("branch = ?"); params.push(branch); }
+  if (input.commit) appendCommitRow(id, input.commit);
+  params.push(now, now, id);
+  getDb().query(`UPDATE tasks SET ${sets.join(", ")}, updated_at = ?, last_seen_at = ? WHERE id = ?`).run(...params as any[]);
+  insertTaskEvent(id, {
+    source: input.actor ?? "agent-relay",
+    type: `stage:${input.deliverableStage}`,
+    severity: "info",
+    title: `Deliverable stage: ${input.deliverableStage}`,
+    body: branch ? `branch ${branch}` : "",
+    metadata: { deliverableStage: input.deliverableStage, ...(branch ? { branch } : {}), ...(input.commit ? { commit: input.commit } : {}) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export interface RecordGateInput {
+  gate: string;
+  status: TaskGateStatus;
+  detail?: string;
+  commitSha?: string;
+  runId?: string;
+  actor?: string;
+}
+
+// Quality-gate ledger write (#834). The append-only `task_events` IS the ledger (no second
+// system of record). Idempotent by runId: the SAME run reported twice does not double-append,
+// so a retried report cannot read as a duplicate pass. A genuine re-run (new runId) appends a
+// higher-id event, which `latestGates` deterministically surfaces as the current state.
+export function recordGate(id: number, input: RecordGateInput): TaskGateState {
+  requireDeliverable(id);
+  const gate = requireText(input.gate, "gate", 120);
+  if (!TASK_GATE_STATUSES.includes(input.status)) {
+    throw new ValidationError(`gate status must be one of: ${TASK_GATE_STATUSES.join(", ")}`);
+  }
+  const type = `${GATE_EVENT_PREFIX}${gate}`;
+  const runId = optionalText(input.runId, "runId", 240);
+  if (runId) {
+    const existing = getDb()
+      .query(`SELECT * FROM task_events WHERE task_id = ? AND type = ? AND json_extract(metadata, '$.runId') = ? LIMIT 1`)
+      .get(id, type, runId) as any;
+    if (existing) return gateStateFromEvent(existing);
+  }
+  const now = Date.now();
+  const event = insertTaskEvent(id, {
+    source: input.actor ?? "agent-relay",
+    type,
+    severity: input.status === "fail" ? "warning" : "info",
+    title: `Gate ${gate}: ${input.status}`,
+    body: input.detail ?? "",
+    metadata: {
+      gate,
+      status: input.status,
+      ...(input.detail ? { detail: input.detail } : {}),
+      ...(input.commitSha ? { commitSha: input.commitSha } : {}),
+      ...(runId ? { runId } : {}),
+    },
+  }, now);
+  return gateStateFromEvent({ type, created_at: event.createdAt, metadata: JSON.stringify(event.metadata) });
+}
+
+function gateStateFromEvent(row: { type: string; created_at: number; metadata: string }): TaskGateState {
+  const meta = parseJson<Record<string, unknown>>(row.metadata, {});
+  return {
+    gate: typeof meta.gate === "string" ? meta.gate : row.type.slice(GATE_EVENT_PREFIX.length),
+    status: (meta.status as TaskGateStatus) ?? "fail",
+    ...(typeof meta.detail === "string" ? { detail: meta.detail } : {}),
+    ...(typeof meta.commitSha === "string" ? { commitSha: meta.commitSha } : {}),
+    ...(typeof meta.runId === "string" ? { runId: meta.runId } : {}),
+    ranAt: row.created_at,
+  };
+}
+
+// Deterministic current-state projection over the append-only ledger: the highest-id event
+// per gate type. Re-runs always win; ties are impossible (autoincrement id).
+export function latestGates(id: number): TaskGateState[] {
+  const rows = getDb().query(`
+    SELECT te.type AS type, te.created_at AS created_at, te.metadata AS metadata
+    FROM task_events te
+    JOIN (
+      SELECT type, MAX(id) AS mid FROM task_events
+      WHERE task_id = ? AND type LIKE '${GATE_EVENT_PREFIX}%'
+      GROUP BY type
+    ) m ON te.id = m.mid
+    ORDER BY te.type ASC
+  `).all(id) as Array<{ type: string; created_at: number; metadata: string }>;
+  return rows.map(gateStateFromEvent);
+}
+
+// --- Dependency DAG (#834): task→task edges, cycle-rejected transactionally (#834 finding 7).
+// Edge semantics: `taskId` depends on `dependsOnTaskId` (the latter must complete first).
+export function addTaskDependency(taskId: number, dependsOnTaskId: number, actor?: string): TaskDependency {
+  if (taskId === dependsOnTaskId) throw new ValidationError("a task cannot depend on itself");
+  return getDb().transaction(() => {
+    if (!getRawTask(taskId)) throw new ValidationError(`task ${taskId} not found`);
+    if (!getRawTask(dependsOnTaskId)) throw new ValidationError(`task ${dependsOnTaskId} not found`);
+    // Cycle check inside the write transaction: if `dependsOnTaskId` can already reach
+    // `taskId` along dependency edges, adding this edge would close a cycle. Loading the
+    // reachable set here (not from a stale in-memory snapshot) makes concurrent inserts safe.
+    const visited = new Set<number>();
+    const stack = [dependsOnTaskId];
+    while (stack.length > 0) {
+      const cur = stack.pop()!;
+      if (cur === taskId) throw new ValidationError("dependency would create a cycle");
+      if (visited.has(cur)) continue;
+      visited.add(cur);
+      const next = getDb().query("SELECT depends_on_task_id FROM task_dependencies WHERE task_id = ?").all(cur) as Array<{ depends_on_task_id: number }>;
+      for (const n of next) stack.push(n.depends_on_task_id);
+    }
+    const now = Date.now();
+    getDb().query("INSERT INTO task_dependencies (task_id, depends_on_task_id, created_at) VALUES (?, ?, ?) ON CONFLICT DO NOTHING")
+      .run(taskId, dependsOnTaskId, now);
+    insertTaskEvent(taskId, {
+      source: actor ?? "agent-relay",
+      type: "dependency.added",
+      severity: "info",
+      title: `Depends on task ${dependsOnTaskId}`,
+      body: "",
+      metadata: { dependsOnTaskId },
+    }, now);
+    return { taskId, dependsOnTaskId, createdAt: now };
+  })();
+}
+
+export function removeTaskDependency(taskId: number, dependsOnTaskId: number, actor?: string): boolean {
+  const result = getDb().query("DELETE FROM task_dependencies WHERE task_id = ? AND depends_on_task_id = ?").run(taskId, dependsOnTaskId);
+  if (result.changes > 0) {
+    insertTaskEvent(taskId, {
+      source: actor ?? "agent-relay",
+      type: "dependency.removed",
+      severity: "info",
+      title: `Removed dependency on task ${dependsOnTaskId}`,
+      body: "",
+      metadata: { dependsOnTaskId },
+    }, Date.now());
+  }
+  return result.changes > 0;
+}
+
+export function listTaskDependencies(taskId: number): number[] {
+  return (getDb().query("SELECT depends_on_task_id FROM task_dependencies WHERE task_id = ? ORDER BY depends_on_task_id ASC").all(taskId) as Array<{ depends_on_task_id: number }>)
+    .map((r) => r.depends_on_task_id);
+}
+
+export function listTaskDependents(taskId: number): number[] {
+  return (getDb().query("SELECT task_id FROM task_dependencies WHERE depends_on_task_id = ? ORDER BY task_id ASC").all(taskId) as Array<{ task_id: number }>)
+    .map((r) => r.task_id);
+}
+
+// --- Refs: issue links (via issue_associations, the source of truth) + branch + commits.
+export interface AddTaskRefInput {
+  issue?: string;
+  defaultRepo?: string;
+  branch?: string;
+  commit?: TaskCommitRef;
+  actor?: string;
+}
+
+export function addTaskRef(id: number, input: AddTaskRefInput): TaskDetail {
+  requireDeliverable(id);
+  const now = Date.now();
+  if (input.issue) {
+    const ref = resolveIssueRefFromString({ ref: input.issue, defaultRepo: optionalText(input.defaultRepo, "defaultRepo", 500) });
+    associateIssue(ref.id, "task", taskEntityId(String(id)));
+    insertTaskEvent(id, {
+      source: input.actor ?? "agent-relay",
+      type: "ref.issue.added",
+      severity: "info",
+      title: `Linked issue ${ref.repo}#${ref.externalKey}`,
+      body: ref.url,
+      metadata: { issueRefId: ref.id, provider: ref.provider, repo: ref.repo, externalKey: ref.externalKey },
+    }, now);
+  }
+  const branch = optionalText(input.branch, "branch", 500);
+  if (branch) {
+    getDb().query("UPDATE tasks SET branch = ?, updated_at = ? WHERE id = ?").run(branch, now, id);
+    insertTaskEvent(id, { source: input.actor ?? "agent-relay", type: "ref.branch.set", severity: "info", title: `Branch ${branch}`, body: "", metadata: { branch } }, now);
+  }
+  if (input.commit) {
+    appendCommitRow(id, input.commit);
+    insertTaskEvent(id, { source: input.actor ?? "agent-relay", type: "ref.commit.added", severity: "info", title: `Commit ${input.commit.sha}`, body: input.commit.subject ?? "", metadata: { commit: input.commit } }, now);
+  }
+  return getTaskDetail(id)!;
+}
+
+export interface RemoveTaskRefInput {
+  issueRefId?: string;
+  branch?: boolean;
+  commitSha?: string;
+  actor?: string;
+}
+
+export function removeTaskRef(id: number, input: RemoveTaskRefInput): TaskDetail {
+  requireDeliverable(id);
+  const now = Date.now();
+  if (input.issueRefId) {
+    removeAssociation(requireText(input.issueRefId, "issueRefId", 120), "task", taskEntityId(String(id)));
+  }
+  if (input.branch) {
+    getDb().query("UPDATE tasks SET branch = NULL, updated_at = ? WHERE id = ?").run(now, id);
+  }
+  if (input.commitSha) {
+    const task = getRawTask(id)!;
+    const commits = (task.commits ?? []).filter((c) => c.sha !== input.commitSha);
+    getDb().query("UPDATE tasks SET commits = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(commits), now, id);
+  }
+  return getTaskDetail(id)!;
+}
+
+function appendCommitRow(id: number, commit: TaskCommitRef): void {
+  const sha = requireText(commit.sha, "commit.sha", 80);
+  const subject = optionalText(commit.subject, "commit.subject", 1000);
+  const task = getRawTask(id)!;
+  const commits = task.commits ?? [];
+  if (commits.some((c) => c.sha === sha)) return;
+  commits.push({ sha, ...(subject ? { subject } : {}) });
+  getDb().query("UPDATE tasks SET commits = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(commits), Date.now(), id);
+}
+
+// --- Attribution: who did what. Writes owner_agent_id (NOT claimed_by) + an attribution event.
+export function assignTaskAgent(id: number, agentId: string, role?: string, actor?: string): TaskDetail {
+  requireDeliverable(id);
+  const cleanAgent = requireText(agentId, "agentId", 200);
+  const cleanRole = optionalText(role, "role", 120);
+  const now = Date.now();
+  getDb().query("UPDATE tasks SET owner_agent_id = ?, updated_at = ? WHERE id = ?").run(cleanAgent, now, id);
+  insertTaskEvent(id, {
+    source: actor ?? cleanAgent,
+    type: "agent.assigned",
+    severity: "info",
+    title: `Assigned ${cleanAgent}${cleanRole ? ` (${cleanRole})` : ""}`,
+    body: "",
+    metadata: { agentId: cleanAgent, ...(cleanRole ? { role: cleanRole } : {}) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+// --- Attribution: spawn-with-task (#838). Records that a worker was spawned FOR this Task,
+// keyed on its spawnRequestId, BEFORE the child registers (fire-and-forget spawns resolve the
+// agent id later). The append-only event is the durable hook #831 reads to drive one-shot
+// reap (find the spawn by spawnRequestId → on land update status → reap). `agent.`-prefixed so
+// it stays Task-only telemetry and never write-throughs to the issue tracker (#833 boundary).
+export interface RecordTaskSpawnInput {
+  spawnRequestId: string;
+  provider: string;
+  requestedBy: string;
+  steer?: string;
+}
+
+// Idempotent by spawnRequestId: a retried spawn (orchestrator re-dispatch, client retry) reusing
+// the SAME spawnRequestId must NOT append a second attribution event. The append-only `task_events`
+// is the ledger, so we check-before-insert on the spawnRequestId stamped in metadata (mirrors the
+// runId idempotency in recordGate). NOTE (#838): this dedups the Task ATTRIBUTION only. The
+// command-bus layer is NOT idempotent — `createCommand` always inserts a fresh random-id row and
+// `commands.correlation_id` is indexed but not UNIQUE — so a retried spawnRequestId can still
+// dispatch a duplicate agent.spawn command. Making correlation_id unique ramifies into the broader
+// command/orchestrator-retry path beyond #838's lane; tracked as a separate follow-up.
+export function recordTaskSpawnRequested(id: number, input: RecordTaskSpawnInput): TaskDetail {
+  requireDeliverable(id);
+  const spawnRequestId = requireText(input.spawnRequestId, "spawnRequestId", 200);
+  const provider = requireText(input.provider, "provider", 120);
+  const requestedBy = requireText(input.requestedBy, "requestedBy", 200);
+  const steer = optionalText(input.steer, "steer", 1_000_000);
+  const existing = getDb()
+    .query(`SELECT id FROM task_events WHERE task_id = ? AND type = 'agent.spawn_requested' AND json_extract(metadata, '$.spawnRequestId') = ? LIMIT 1`)
+    .get(id, spawnRequestId);
+  if (existing) return getTaskDetail(id)!;
+  insertTaskEvent(id, {
+    source: requestedBy,
+    type: "agent.spawn_requested",
+    severity: "info",
+    title: `Worker spawn requested (${provider})`,
+    body: steer ?? "",
+    metadata: { spawnRequestId, provider, requestedBy, ...(steer ? { steer } : {}) },
+  }, Date.now());
+  return getTaskDetail(id)!;
+}
+
+// --- Reads / projections.
+function issueLinks(id: number): TaskIssueLink[] {
+  return listIssuesForEntity("task", taskEntityId(String(id))).map((item) => ({
+    issueRefId: item.issueRef.id,
+    provider: item.issueRef.provider,
+    repo: item.issueRef.repo,
+    externalKey: item.issueRef.externalKey,
+    url: item.issueRef.url,
+    ...(item.issueRef.title ? { title: item.issueRef.title } : {}),
+    status: item.issueRef.status,
+  }));
+}
+
+export function getTaskDetail(id: number): TaskDetail | null {
+  const task = getRawTask(id);
+  if (!task || task.kind !== DELIVERABLE_TASK_KIND) return null;
+  return {
+    ...task,
+    issues: issueLinks(id),
+    dependsOn: listTaskDependencies(id),
+    dependents: listTaskDependents(id),
+    gates: latestGates(id),
+  };
+}
+
+export interface ListDeliverableTasksFilter {
+  status?: string;
+  deliverableStage?: string;
+  teamId?: string;
+  limit?: number;
+}
+
+export function listDeliverableTasks(filter: ListDeliverableTasksFilter = {}): Task[] {
+  const conditions = [`kind = '${DELIVERABLE_TASK_KIND}'`];
+  const params: unknown[] = [];
+  if (filter.status) { conditions.push("status = ?"); params.push(filter.status); }
+  if (filter.deliverableStage) { conditions.push("deliverable_stage = ?"); params.push(filter.deliverableStage); }
+  if (filter.teamId) { conditions.push("team_id = ?"); params.push(filter.teamId); }
+  const limit = Math.min(Math.max(filter.limit ?? 100, 1), 500);
+  params.push(limit);
+  return (getDb().query(`${TASK_SELECT} WHERE ${conditions.join(" AND ")} ORDER BY updated_at DESC LIMIT ?`).all(...params as any[]) as any[]).map(rowToTask);
+}
+
+// Task-aware issue resolution for the land→close bridge (#833/#834 finding 4). Deliverable
+// Tasks own `branch`, so a landed branch resolves to its Task(s). The land WIRING is #831;
+// this is the resolution path + entity-type the bridge needs to be ABLE to fire. The issue
+// lifecycle service consumes these ids via listIssuesForEntity('task', id) — same shape as
+// the existing team/plan-node resolution.
+export function deliverableTaskIdsByBranch(branch: string): number[] {
+  const cleaned = branch?.trim();
+  if (!cleaned) return [];
+  return (getDb().query(`SELECT id FROM tasks WHERE kind = '${DELIVERABLE_TASK_KIND}' AND branch = ? ORDER BY id ASC`).all(cleaned) as Array<{ id: number }>)
+    .map((r) => r.id);
+}
+
+// Land→Task linkage by attribution (#831/#838). The robust key is the spawned WORKER, not the
+// branch column (a worker cuts its own branch; the Task's `branch` may never have been recorded).
+// `assignTaskAgent` (#838) stamps `owner_agent_id` once the child's id resolves, so the landing
+// workspace's ownerAgentId resolves straight to its bound Task(s).
+export function deliverableTaskIdsByOwnerAgent(agentId: string): number[] {
+  const cleaned = agentId?.trim();
+  if (!cleaned) return [];
+  return (getDb().query(`SELECT id FROM tasks WHERE kind = '${DELIVERABLE_TASK_KIND}' AND owner_agent_id = ? ORDER BY id ASC`).all(cleaned) as Array<{ id: number }>)
+    .map((r) => r.id);
+}
+
+// Fallback linkage for a fire-and-forget spawn whose `owner_agent_id` was never backfilled (the
+// child registered after the bounded poll window, #838): the `agent.spawn_requested` attribution
+// event (recorded BEFORE the child registers) carries the spawnRequestId. The landing worker's
+// `meta.spawnRequestId` resolves back through it to the Task. Returns every matching task id so a
+// reused spawnRequestId can't silently drop a link.
+export function deliverableTaskIdsBySpawnRequestId(spawnRequestId: string): number[] {
+  const cleaned = spawnRequestId?.trim();
+  if (!cleaned) return [];
+  return (getDb()
+    .query(`SELECT DISTINCT te.task_id AS id FROM task_events te
+            JOIN tasks t ON t.id = te.task_id AND t.kind = '${DELIVERABLE_TASK_KIND}'
+            WHERE te.type = 'agent.spawn_requested' AND json_extract(te.metadata, '$.spawnRequestId') = ?
+            ORDER BY te.task_id ASC`)
+    .all(cleaned) as Array<{ id: number }>)
+    .map((r) => r.id);
+}
+
+// Mark that the Task's one-shot worker was reaped on land (#831 reap-signal axis). Records the
+// timestamp on the durable row and appends an `agent.`-prefixed telemetry event (Task-only; never
+// writes through to the issue tracker — see the weave boundary). Idempotent: a second reap on the
+// same land is a no-op marker refresh, so a re-fired land can't double-stamp a different agent.
+export function markTaskAgentReaped(id: number, input: { agentId: string; reason?: string; at?: number }): TaskDetail {
+  requireDeliverable(id);
+  const agentId = requireText(input.agentId, "agentId", 200);
+  const now = input.at ?? Date.now();
+  getDb().query("UPDATE tasks SET reaped_at = ?, updated_at = ? WHERE id = ?").run(now, now, id);
+  insertTaskEvent(id, {
+    source: "agent-relay",
+    type: "agent.reaped",
+    severity: "info",
+    title: `Worker ${agentId} reaped`,
+    body: input.reason ?? "deliverable landed + gates passed",
+    metadata: { agentId, ...(input.reason ? { reason: input.reason } : {}) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export function listIssueRefsForLandedBranch(branch: string): TaskIssueLink[] {
+  const out: TaskIssueLink[] = [];
+  const seen = new Set<string>();
+  for (const id of deliverableTaskIdsByBranch(branch)) {
+    for (const link of issueLinks(id)) {
+      if (seen.has(link.issueRefId)) continue;
+      seen.add(link.issueRefId);
+      out.push(link);
+    }
+  }
+  return out;
+}

package/src/db/task-maintenance.ts

@@ -1,15 +1,16 @@
 import { getDb } from "./connection.ts";
-import { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
+import { TASK_SELECT, insertTaskEvent, claimTaskWhere } from "./task-core.ts";
 
 // On-demand automation tasks (targetMode=on_demand_agent) are bound to a single
 // ephemeral agent spawned just for that task. When that agent's claim is released,
 // the task must not return to a claimable pool that can never match it again.
 export function settleSingleTargetOnDemandTasks(condition: string, params: any[], now: number, reason: string): void {
-  const selectSql = `${TASK_SELECT} WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`;
+  // Fenced to the claim lane (#834): on-demand settle must never resolve a deliverable Task.
+  const selectSql = `${TASK_SELECT} WHERE ${claimTaskWhere()} AND (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`;
   const rows = getDb().query(selectSql).all(...params) as any[];
   if (rows.length === 0) return;
   getDb().query(
-    `UPDATE tasks SET status = 'done', claim_expires_at = NULL, updated_at = ?, last_seen_at = ? WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`
+    `UPDATE tasks SET status = 'done', claim_expires_at = NULL, updated_at = ?, last_seen_at = ? WHERE ${claimTaskWhere()} AND (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`
   ).run(now, now, ...params);
   for (const row of rows) {
     insertTaskEvent(row.id, {