@humwick/server 0.0.0-stage → 0.130.0

package/src/db/task-entity.ts

@@ -0,0 +1,1143 @@
+// #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_DISPATCH_COMPLEXITIES,
+  TASK_DISPATCH_CRITICALITIES,
+  TASK_DISPATCH_FOOTPRINTS,
+  TASK_DISPATCH_TYPES,
+  TASK_GATE_STATUSES,
+  TASK_PRIORITIES,
+  BACKLOG_STATES,
+  type BacklogState,
+  type Task,
+  type TaskBlocker,
+  type TaskComplexity,
+  type TaskCommitRef,
+  type TaskDeliverableStage,
+  type TaskDependency,
+  type TaskTerminalStage,
+  type TaskDetail,
+  type TaskDispatch,
+  type TaskGateState,
+  type TaskGateStatus,
+  type TaskIssueLink,
+  type IssueRefRelation,
+  type TaskPriority,
+  type TaskStatus,
+} from "../types";
+import { parseJson } from "../utils";
+import { cleanEnum, cleanStringArray, optionalEnum } from "../validation";
+import { getDb, writeTransaction, ValidationError } from "./connection.ts";
+import { ownerForNewTask } from "./task-owner.ts";
+import { rowToTask } from "./mappers.ts";
+import { latestTaskDispatchDecision, taskBoundWorkerModel, taskDispatchWorkShape } from "./task-detail-projection.ts";
+import { taskPendingReviewDelivery } from "./task-review-hold.ts";
+import { getAgent } from "./agents.ts";
+import { statusWriteDropsCarryPending, CARRY_PENDING_GATED_STAGES } from "./carry-pending.ts";
+import { carryPendingHeadBlockingAdvance } from "./carry-pending-marker.ts";
+import { TASK_SELECT, insertTaskEvent, DELIVERABLE_TASK_KIND, deliverableTaskIdsByBranch } from "./task-core.ts";
+export { deliverableTaskIdsByBranch } from "./task-core.ts";
+import { associateIssue, listIssuesForEntity, removeAssociation } from "./issue-associations.ts";
+import { resolveIssueRefFromString } from "./issue-refs.ts";
+import { cleanIssueRefRelation, defaultTaskIssueRelation } from "./task-issue-relation";
+import { cleanTaskTerminalStage, reconciledTaskCompletionStatus, taskTerminalStage, validationCompletionStatus } from "../task-completion.ts";
+import { getProject } from "./projects.ts";
+import { taskExecutionField } from "./task-execution.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.
+// `orphaned` (#3051): the owner agent is gone and nothing was delivered — the Task needs a new owner.
+const DELIVERABLE_STATUSES: readonly TaskStatus[] = ["open", "claimed", "in_progress", "validating", "blocked", "orphaned", "done", "failed", "canceled"];
+const NOT_STARTED_STATUSES: readonly TaskStatus[] = ["open", "claimed", "orphaned"];
+
+// #3051 — a bound owner or a reached stage means the work started: a not-started Task becomes in_progress.
+function startTaskWorkBody(task: Pick<Task, "id" | "status">, actor: string | undefined, note: string, now: number): void {
+  if (NOT_STARTED_STATUSES.includes(task.status)) setTaskStatusBody(task.id, { status: "in_progress", actor, note }, now);
+}
+const GATE_EVENT_PREFIX = "gate:";
+export const DEFAULT_TASK_COMPLEXITY: TaskComplexity = "moderate";
+
+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 cleanTaskComplexity(value: unknown, field = "complexity"): TaskComplexity | undefined {
+  return optionalEnum(value, field, TASK_DISPATCH_COMPLEXITIES) as TaskComplexity | undefined;
+}
+
+// #1535 WS2 — priority is OPTIONAL (unlike complexity, it has no default), so a create-time
+// absent value stays undefined (optionalEnum) while an explicit clear on update is a distinct
+// `null` the caller must pass through (see updateDeliverableTask) — a present-but-invalid value
+// always throws (cleanEnum), never silently drops.
+function cleanTaskPriority(value: unknown, field = "priority"): TaskPriority | undefined {
+  return optionalEnum(value, field, TASK_PRIORITIES) as TaskPriority | undefined;
+}
+
+function requireTaskPriority(value: unknown, field = "priority"): TaskPriority {
+  return cleanEnum(value, field, TASK_PRIORITIES) as TaskPriority;
+}
+
+function cleanTags(value: unknown, field = "tags"): string[] | undefined {
+  return cleanStringArray(value, field, { itemMax: 60, maxItems: 30 });
+}
+
+// #1535 WS3 — backlog lifecycle state. Optional (like priority): absent stays undefined so a
+// non-backlog task's column is NULL; a present-but-invalid value throws rather than silently
+// dropping. The backlog→promoted flip is a distinct writer (setTaskBacklogState in db/backlog.ts).
+function cleanBacklogState(value: unknown, field = "backlogState"): BacklogState | undefined {
+  return optionalEnum(value, field, BACKLOG_STATES) as BacklogState | undefined;
+}
+
+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)! } : {}),
+    };
+  });
+}
+
+export function cleanTaskDispatch(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 = {};
+  const complexity = cleanTaskComplexity(d.complexity, "dispatch.complexity");
+  const type = optionalEnum(d.type, "dispatch.type", TASK_DISPATCH_TYPES);
+  const contextFootprint = optionalEnum(d.contextFootprint, "dispatch.contextFootprint", TASK_DISPATCH_FOOTPRINTS);
+  const criticality = optionalEnum(d.criticality, "dispatch.criticality", TASK_DISPATCH_CRITICALITIES);
+  if (complexity !== undefined) out.complexity = complexity;
+  if (type !== undefined) out.type = type as TaskDispatch["type"];
+  if (contextFootprint !== undefined) out.contextFootprint = contextFootprint as TaskDispatch["contextFootprint"];
+  if (criticality !== undefined) out.criticality = criticality as TaskDispatch["criticality"];
+  return out;
+}
+
+function projectForRepo(repo: string | undefined): string | undefined {
+  const cleaned = repo?.trim();
+  if (!cleaned) return undefined;
+  const row = getDb()
+    .query("SELECT id FROM projects WHERE scope = 'project' AND issue_repo = ? ORDER BY created_at ASC, id ASC LIMIT 1")
+    .get(cleaned) as { id: string } | undefined;
+  return row?.id;
+}
+
+function cleanTaskProject(input: { projectId?: unknown; repo?: unknown }): { projectId?: string; repo?: string } {
+  const projectId = optionalText(input.projectId, "projectId", 120);
+  const project = projectId ? getProject(projectId) : null;
+  const repo = optionalText(input.repo, "repo", 500) ?? project?.issueRepo;
+  return {
+    ...(projectId ? { projectId } : repo ? { projectId: projectForRepo(repo) } : {}),
+    ...(repo ? { repo } : {}),
+  };
+}
+
+function fillTaskProjectFromRepo(id: number, repo: string, now = Date.now()): void {
+  const cleaned = optionalText(repo, "repo", 500);
+  if (!cleaned) return;
+  const projectId = projectForRepo(cleaned);
+  getDb().query(`
+    UPDATE tasks
+    SET repo = COALESCE(NULLIF(trim(repo), ''), ?),
+        project_id = COALESCE(NULLIF(trim(project_id), ''), ?),
+        updated_at = ?
+    WHERE id = ?
+  `).run(cleaned, projectId ?? null, now, id);
+}
+
+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;
+  complexity?: TaskComplexity;
+  context?: string;
+  terminalStage?: Task["terminalStage"];
+  doneWhen?: string; branch?: string;
+  teamId?: string;
+  projectId?: string;
+  repo?: string;
+  createdBy: string;
+  source?: string;
+  target?: string;
+  latestSteer?: string;
+  dispatch?: TaskDispatch;
+  tags?: string[];
+  priority?: TaskPriority;
+  /** #1535 WS3 — seed the task directly into the backlog (`backlog`) so it shows up in the
+   * prioritized backlog query until promoted. Absent ⇒ not backlog-managed. */
+  backlogState?: BacklogState;
+}
+
+// The BODY of createDeliverableTask, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the
+// project-lookup READ (cleanTaskProject → projectForRepo) and the INSERT + event are one atomic unit —
+// the seam boundary is the whole logical op, not the statement (§3.1). Assumes a transaction is already
+// open (the `taskEntity.create` op executor's BEGIN IMMEDIATE); the sync wrapper below adds the tx for
+// ordinary callers. `now` is submission-time wall-clock (H6). NON-idempotent: a blind retry would insert
+// a SECOND task row, so the async facade supplies a per-submission idempotencyKey.
+export function createDeliverableTaskBody(input: CreateDeliverableTaskInput, now: number): TaskDetail {
+  if (input.terminalStage !== undefined) cleanTaskTerminalStage(input.terminalStage);
+  const title = requireText(input.title, "title", 500);
+  const createdBy = requireText(input.createdBy, "createdBy", 200);
+  const intent = requireText(input.intent, "intent", 1_000_000);
+  const dispatch = cleanTaskDispatch(input.dispatch);
+  const complexity = cleanTaskComplexity(input.complexity ?? dispatch?.complexity, "complexity") ?? DEFAULT_TASK_COMPLEXITY;
+  const context = optionalText(input.context, "context", 1_000_000);
+  const branch = optionalText(input.branch, "branch", 500);
+  const taskProject = cleanTaskProject(input);
+  const tags = cleanTags(input.tags) ?? [];
+  const priority = cleanTaskPriority(input.priority);
+  const backlogState = cleanBacklogState(input.backlogState);
+  const teamId = optionalText(input.teamId, "teamId", 200) ?? null;
+  // 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, complexity, context, latest_steer, deliverable_stage, done_when, branch, team_id, project_id, repo, created_by, dispatch, tags, priority, backlog_state, owner
+    ) VALUES (?, ?, ?, 'info', 'open', ?, 1, '{}', ?, ?, ?, '${DELIVERABLE_TASK_KIND}', ?, ?, ?, ?, 'none', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    optionalText(input.source, "source", 200) ?? "coordinator",
+    title,
+    intent,
+    optionalText(input.target, "target", 200) ?? createdBy,
+    now, now, now, intent, complexity, context ?? null,
+    optionalText(input.latestSteer, "latestSteer", 1_000_000) ?? null,
+    optionalText(input.doneWhen, "doneWhen", 1_000_000) ?? null,
+    branch ?? null,
+    teamId,
+    taskProject.projectId ?? null,
+    taskProject.repo ?? null,
+    createdBy,
+    dispatch ? JSON.stringify(dispatch) : null,
+    tags.length ? JSON.stringify(tags) : null,
+    priority ?? null,
+    backlogState ?? null,
+    ownerForNewTask(createdBy, teamId),
+  );
+  const id = Number(result.lastInsertRowid);
+  if (input.terminalStage) getDb().query("UPDATE tasks SET terminal_stage = ? WHERE id = ?").run(input.terminalStage, id);
+  insertTaskEvent(id, {
+    source: createdBy,
+    type: "task.created",
+    severity: "info",
+    title: `Task created: ${title}`,
+    body: intent,
+    metadata: { createdBy, complexity, ...(context ? { context } : {}), ...(branch ? { branch } : {}), ...(taskProject.projectId ? { projectId: taskProject.projectId } : {}), ...(taskProject.repo ? { repo: taskProject.repo } : {}), ...(dispatch ? { dispatch } : {}), ...(tags.length ? { tags } : {}), ...(priority ? { priority } : {}), ...(backlogState ? { backlogState } : {}) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export function createDeliverableTask(input: CreateDeliverableTaskInput): TaskDetail {
+  return writeTransaction(() => createDeliverableTaskBody(input, Date.now()));
+}
+
+export interface UpdateDeliverableTaskInput {
+  terminalStage?: Task["terminalStage"] | null;
+  title?: string;
+  intent?: string;
+  complexity?: TaskComplexity;
+  context?: string;
+  latestSteer?: string;
+  doneWhen?: string;
+  dispatch?: TaskDispatch;
+  teamId?: string;
+  projectId?: string;
+  repo?: string;
+  actor?: string;
+  /** Absent ⇒ untouched. `[]` (or `null`) ⇒ clear all tags. */
+  tags?: string[] | null;
+  /** Absent ⇒ untouched. `null` ⇒ clear (priority has no default, unlike complexity). */
+  priority?: TaskPriority | null;
+}
+
+// The BODY of updateDeliverableTask, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the
+// `requireDeliverable` existence/kind-guard READ and the UPDATE + event are one atomic unit — a
+// concurrent delete/kind-change between the guard and the write can never slip through a thread hop.
+// Assumes a transaction is already open; the sync wrapper below adds the tx for ordinary callers.
+// NON-idempotent (always appends a `task.updated` event) → the async facade supplies a per-submission key.
+export function updateDeliverableTaskBody(id: number, input: UpdateDeliverableTaskInput, now: number): 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.complexity !== undefined) push("complexity", cleanTaskComplexity(input.complexity) ?? null);
+  if (input.context !== undefined) push("context", optionalText(input.context, "context", 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.projectId !== undefined || input.repo !== undefined) {
+    const taskProject = cleanTaskProject(input);
+    if (input.projectId !== undefined) push("project_id", taskProject.projectId ?? null);
+    if (input.repo !== undefined) push("repo", taskProject.repo ?? null);
+  }
+  if (input.dispatch !== undefined) { const d = cleanTaskDispatch(input.dispatch); push("dispatch", d ? JSON.stringify(d) : null); }
+  if (input.tags !== undefined) {
+    const tags = input.tags === null ? [] : (cleanTags(input.tags) ?? []);
+    push("tags", tags.length ? JSON.stringify(tags) : null);
+  }
+  if (input.terminalStage !== undefined) push("terminal_stage", input.terminalStage === null ? null : cleanTaskTerminalStage(input.terminalStage));
+  if (input.priority !== undefined) push("priority", input.priority === null ? null : requireTaskPriority(input.priority));
+  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 function updateDeliverableTask(id: number, input: UpdateDeliverableTaskInput): TaskDetail {
+  return writeTransaction(() => updateDeliverableTaskBody(id, input, Date.now()));
+}
+
+export interface SetTaskStatusInput {
+  status: TaskStatus;
+  /** Coordinator-authorized override of open/failed validation items when closing. */
+  force?: boolean;
+  /** Explicit API/MCP transitions reject unmet validation; lifecycle writes reconcile it. */
+  strictValidation?: boolean;
+  blockedBy?: TaskBlocker[];
+  note?: string;
+  actor?: string;
+  /** #1456 — INTERNAL, never exposed by a transport. Authorizes removing a `carry-pending` blocker
+   * (set only by `confirmTaskCarry`). Without it, a carry-pending blocker is a hard latch that no
+   * ordinary status/blocked_by write may drop (round-4 BLOCKER 1). */
+  allowCarryPendingClear?: boolean;
+}
+
+// The BODY of setTaskStatus, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the
+// `requireDeliverable` guard READ + the #1456 carry-pending latch check (both reads of `current`) and
+// the UPDATE + event are one atomic unit — the latch can never be bypassed by a write that slips in
+// between the read and the write across a thread hop. 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. Assumes a transaction is already open; the sync wrapper below adds
+// the tx. NON-idempotent (always appends a status event) → the async facade supplies a per-submission key.
+export function setTaskStatusBody(id: number, input: SetTaskStatusInput, now: number): TaskDetail {
+  const current = requireDeliverable(id);
+  if (input.force !== undefined && typeof input.force !== "boolean") throw new ValidationError("force must be a boolean");
+  if (input.force && input.status !== "done") throw new ValidationError("force is only supported for status done");
+  if (input.status === "done" && !input.force) {
+    const status = validationCompletionStatus(current.validationItems);
+    if (input.strictValidation && status !== "done") throw new ValidationError("task has open or failed validation items; use validating while collecting proof, or coordinator force:true to override-close");
+    input = { ...input, status };
+  }
+  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'");
+  }
+  // #1456 (BLOCKER 1) — HARD LATCH at the lowest status writer (see statusWriteDropsCarryPending): no
+  // ordinary status/blocked_by write may drop a carry-pending blocker; only an authorized confirm does.
+  if (!input.allowCarryPendingClear && statusWriteDropsCarryPending(current, input.status, blockedBy)) {
+    throw new ValidationError(`cannot change task ${id} status/blockers while a #1456 carry-pending blocker is open — it can only be cleared by confirming the carry (relay_task_confirm_carry)`);
+  }
+  // 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 = ?, completed_at = ?, updated_at = ?, last_seen_at = ? WHERE id = ?")
+    .run(input.status, blockedJson, input.status === "done" ? current.completedAt ?? now : null, 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, ...(input.force ? { force: true } : {}), ...(blockedBy ? { blockedBy } : {}) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export function setTaskStatus(id: number, input: SetTaskStatusInput): TaskDetail {
+  return writeTransaction(() => setTaskStatusBody(id, input, Date.now()));
+}
+
+export interface SetTaskStageInput {
+  deliverableStage: TaskDeliverableStage;
+  branch?: string;
+  commit?: TaskCommitRef;
+  actor?: string;
+  /** Correlates a stage transition to a durable deploy or similar lifecycle run. */
+  metadata?: Record<string, unknown>;
+}
+
+// The BODY of setTaskStage, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the
+// `requireDeliverable` guard + the #1456 carry-pending landing-gate READ (`carryPendingHeadBlockingAdvance`,
+// both against `current`) and the UPDATE + event are one atomic unit — the un-bypassable landing gate can
+// never be raced by a write straddling a thread hop. 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. Assumes a transaction is already open; the sync wrapper below adds
+// the tx. NON-idempotent (always appends a stage event) → the async facade supplies a per-submission key.
+export function setTaskStageBody(id: number, input: SetTaskStageInput, now: number): TaskDetail {
+  const current = requireDeliverable(id);
+  if (!TASK_DELIVERABLE_STAGES.includes(input.deliverableStage)) {
+    throw new ValidationError(`deliverableStage must be one of: ${TASK_DELIVERABLE_STAGES.join(", ")}`);
+  }
+  // #1456 (BLOCKERs 2 & 3) — the un-bypassable landing gate lives HERE, in the lowest stage writer, so
+  // EVERY advance funnels through it (land pipeline, manual `relay_task_set_stage`, and the deploy path
+  // `stampDeployedTasks` which calls this primitive directly). See carryPendingHeadBlockingAdvance.
+  // TODO(#1456): this gate is a read-then-write and could race a concurrent clear/confirm across hosts;
+  // folding it into the UPDATE's WHERE is blocked by the workspace-marker leg (not a single-row
+  // predicate) — deferred; SQLite writer-serialization bounds the window to a single host.
+  if (CARRY_PENDING_GATED_STAGES.has(input.deliverableStage)) {
+    const head = carryPendingHeadBlockingAdvance(current);
+    if (head) {
+      throw new ValidationError(`cannot advance task ${id} to ${input.deliverableStage}: a #1456 carry-pending obligation is open (discarded head ${head}) — confirm the delivered change was carried onto the current base (relay_task_confirm_carry) before it can land`);
+    }
+  }
+  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, now);
+  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 } : {}), ...(input.metadata ?? {}) },
+  }, now);
+  if (input.deliverableStage !== "none") startTaskWorkBody(current, input.actor, `Deliverable stage reached: ${input.deliverableStage}`, now);
+  const detail = getTaskDetail(id)!;
+  const status = reconciledTaskCompletionStatus(detail);
+  if (detail.status !== "done" && status && detail.status !== status) {
+    return setTaskStatusBody(id, { status, actor: input.actor, note: `Terminal stage reached: ${input.deliverableStage}` }, now);
+  }
+  return detail;
+}
+
+export function setTaskStage(id: number, input: SetTaskStageInput): TaskDetail {
+  return writeTransaction(() => setTaskStageBody(id, input, Date.now()));
+}
+
+export interface RecordGateInput { gate: string; status: TaskGateStatus; detail?: string; count?: number; commitSha?: string; runId?: string; actor?: string; }
+
+// The BODY of recordGate, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the `requireDeliverable`
+// guard + the runId dedup READ and the event insert are one atomic unit, so a concurrent duplicate report
+// can never race past the dedup check across a thread hop. 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. A KEYLESS call (no runId) always inserts fresh — same "frequently keyless, dedups by
+// construction when a key IS given" classification as L1 `messages.send` (ADR §3.7.1) — so this op is
+// `idempotent: true` and needs no gateway ledger key. Assumes a transaction is already open; the sync
+// wrapper below adds the tx.
+export function recordGateBody(id: number, input: RecordGateInput, now: number): 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(", ")}`);
+  }
+  if (input.count !== undefined && (!Number.isSafeInteger(input.count) || input.count < 0)) throw new ValidationError("count must be a non-negative integer");
+  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 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 } : {}),
+      ...(typeof input.count === "number" ? { count: input.count } : {}),
+      ...(input.commitSha ? { commitSha: input.commitSha } : {}),
+      ...(runId ? { runId } : {}),
+    },
+  }, now);
+  return gateStateFromEvent({ type, created_at: event.createdAt, metadata: JSON.stringify(event.metadata) });
+}
+
+export function recordGate(id: number, input: RecordGateInput): TaskGateState {
+  return writeTransaction(() => recordGateBody(id, input, Date.now()));
+}
+
+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.count === "number" ? { count: meta.count } : {}),
+    ...(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).
+//
+// The BODY of addTaskDependency, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904, already the
+// pattern here pre-migration — #1432): the existence reads (getRawTask×2), the DAG-walk cycle-check
+// SELECTs, and the INSERT + event are one atomic unit. BEGIN IMMEDIATE (#1432): the benefit is
+// BUSY-avoidance + clean serialization, NOT cycle-prevention — under WAL the DEFERRED default does NOT
+// silently both-commit a cycle; the second of two concurrent adds hits instant SQLITE_BUSY on the
+// reader→writer upgrade (the #1428 class), so it errors rather than inserting. BEGIN IMMEDIATE takes the
+// write lock at BEGIN, so the loser instead WAITS on busy_timeout, then re-reads the winner's committed
+// edge under the lock and cleanly rejects the closing edge as a cycle — turning a spurious BUSY into
+// deterministic serialization. Assumes a transaction is already open; the sync wrapper below adds the tx.
+// The edge insert is `ON CONFLICT DO NOTHING` (dedups by construction) but the event append is
+// unconditional on every call, so this is classified `idempotent: false` — a blind retry after a
+// phantom failure would double-append the `dependency.added` event even though the edge itself dedups.
+export function addTaskDependencyBody(taskId: number, dependsOnTaskId: number, actor: string | undefined, now: number, requiredStage?: TaskTerminalStage): TaskDependency {
+  if (taskId === dependsOnTaskId) throw new ValidationError("a task cannot depend on itself");
+  const dependent = getRawTask(taskId);
+  if (!dependent) throw new ValidationError(`task ${taskId} not found`);
+  const prerequisite = getRawTask(dependsOnTaskId);
+  if (!prerequisite) throw new ValidationError(`task ${dependsOnTaskId} not found`);
+  // #3692 — never quietly downgrade: a deployed edge to a Task whose delivery ends at landed-on-main could not be met.
+  if (requiredStage === "deployed" && taskTerminalStage(prerequisite) !== "deployed") {
+    throw new ValidationError(`STAGE_UNREACHABLE: T${dependsOnTaskId}'s repo has no CD; require landed-on-main`);
+  }
+  // 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);
+  }
+  // The upsert reports one change for a stage update too, so "new edge" is read before it.
+  const added = !getDb().query("SELECT 1 FROM task_dependencies WHERE task_id = ? AND depends_on_task_id = ?").get(taskId, dependsOnTaskId);
+  // Re-adding an edge keeps its stage unless the caller names one (plan edge saves re-add bare edges).
+  getDb().query("INSERT INTO task_dependencies (task_id, depends_on_task_id, created_at, required_stage) VALUES (?, ?, ?, ?) ON CONFLICT DO UPDATE SET required_stage = COALESCE(excluded.required_stage, required_stage)")
+    .run(taskId, dependsOnTaskId, now, requiredStage ?? null);
+  // #3692: the prerequisite's owner sees who waits on it, once per new edge. A history line, never a wake.
+  if (added && (dependent.projectId !== prerequisite.projectId || dependent.teamId !== prerequisite.teamId)) {
+    insertTaskEvent(dependsOnTaskId, { source: "agent-relay", type: "dependency.dependent-added", severity: "info", title: `Task ${taskId} waits on this`, body: "", metadata: { dependentTaskId: taskId, ...(dependent.projectId ? { projectId: dependent.projectId } : {}), ...(dependent.teamId ? { teamId: dependent.teamId } : {}) } }, now);
+  }
+  insertTaskEvent(taskId, {
+    source: actor ?? "agent-relay",
+    type: "dependency.added",
+    severity: "info",
+    title: `Depends on task ${dependsOnTaskId}${requiredStage ? ` (requires ${requiredStage})` : ""}`,
+    body: "",
+    metadata: { dependsOnTaskId, ...(requiredStage ? { requiredStage } : {}) },
+  }, now);
+  return { taskId, dependsOnTaskId, ...(requiredStage ? { requiredStage } : {}), createdAt: now };
+}
+
+export function addTaskDependency(taskId: number, dependsOnTaskId: number, actor?: string, requiredStage?: TaskTerminalStage): TaskDependency {
+  return writeTransaction(() => addTaskDependencyBody(taskId, dependsOnTaskId, actor, Date.now(), requiredStage));
+}
+
+// The BODY of removeTaskDependency, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the DELETE
+// and the conditional event insert (guarded on `result.changes`, not a separate read) are one atomic
+// unit. Idempotent by construction: a retry after the edge is already gone finds `changes === 0` and
+// appends no second event — a genuine no-op re-application (ADR §3.7.1). Assumes a transaction is
+// already open; the sync wrapper below adds the tx.
+export function removeTaskDependencyBody(taskId: number, dependsOnTaskId: number, actor: string | undefined, now: number): 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 },
+    }, now);
+  }
+  return result.changes > 0;
+}
+
+export function removeTaskDependency(taskId: number, dependsOnTaskId: number, actor?: string): boolean {
+  return writeTransaction(() => removeTaskDependencyBody(taskId, dependsOnTaskId, actor, Date.now()));
+}
+
+function listTaskDependencyEdges(taskId: number) {
+  return getDb().query("SELECT depends_on_task_id, required_stage FROM task_dependencies WHERE task_id = ? ORDER BY depends_on_task_id ASC").all(taskId) as Array<{ depends_on_task_id: number; required_stage: TaskTerminalStage | null }>;
+}
+
+export function listTaskDependencies(taskId: number): number[] {
+  return listTaskDependencyEdges(taskId).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);
+}
+
+// --- Hierarchy (#1535 WS1): parent_task_id is a tree edge — a task has at most one
+// parent. Cycle-guarded the same way as the depends-on DAG above (#834 finding 7): walk
+// the CURRENT parent chain starting at the proposed parent; if it reaches taskId, adding
+// the edge would close a cycle.
+//
+// The BODY of setTaskParent, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904, already the pattern
+// here pre-migration): the existence/kind guard, the parent-chain cycle-walk SELECTs, and the UPDATE +
+// event are one atomic unit — same BEGIN IMMEDIATE concurrency rationale as addTaskDependencyBody.
+// Assumes a transaction is already open; the sync wrapper below adds the tx. The UPDATE itself guards
+// against an already-identical parent and the event follows `changes`, so a replay cannot append a
+// duplicate `parent.set` receipt even if it arrives with a different transport key.
+export function setTaskParentBody(taskId: number, parentTaskId: number, actor: string | undefined, now: number): TaskDetail {
+  if (taskId === parentTaskId) throw new ValidationError("a task cannot be its own parent");
+  requireDeliverable(taskId);
+  if (!getRawTask(parentTaskId)) throw new ValidationError(`task ${parentTaskId} not found`);
+  let cur: number | null = parentTaskId;
+  const visited = new Set<number>();
+  while (cur !== null) {
+    if (cur === taskId) throw new ValidationError("parent would create a cycle");
+    if (visited.has(cur)) break; // defensive; pre-existing data should never already cycle
+    visited.add(cur);
+    const row = getDb().query("SELECT parent_task_id FROM tasks WHERE id = ?").get(cur) as { parent_task_id: number | null } | undefined;
+    cur = row?.parent_task_id ?? null;
+  }
+  const result = getDb().query("UPDATE tasks SET parent_task_id = ?, updated_at = ? WHERE id = ? AND (parent_task_id IS NULL OR parent_task_id != ?)")
+    .run(parentTaskId, now, taskId, parentTaskId);
+  if (result.changes > 0) {
+    insertTaskEvent(taskId, {
+      source: actor ?? "agent-relay",
+      type: "parent.set",
+      severity: "info",
+      title: `Parent set to task ${parentTaskId}`,
+      body: "",
+      metadata: { parentTaskId },
+    }, now);
+  }
+  return getTaskDetail(taskId)!;
+}
+
+export function setTaskParent(taskId: number, parentTaskId: number, actor?: string): TaskDetail {
+  return writeTransaction(() => setTaskParentBody(taskId, parentTaskId, actor, Date.now()));
+}
+
+// The BODY of clearTaskParent, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the guard read +
+// the UPDATE (conditioned on `parent_task_id IS NOT NULL` in the WHERE, not a separate read) + the
+// conditional event (guarded on `result.changes`) are one atomic unit. Idempotent by construction: a
+// retry once the parent is already cleared finds `changes === 0` and appends no second event. Assumes a
+// transaction is already open; the sync wrapper below adds the tx.
+export function clearTaskParentBody(taskId: number, actor: string | undefined, now: number): TaskDetail {
+  requireDeliverable(taskId);
+  const result = getDb().query("UPDATE tasks SET parent_task_id = NULL, updated_at = ? WHERE id = ? AND parent_task_id IS NOT NULL").run(now, taskId);
+  if (result.changes > 0) {
+    insertTaskEvent(taskId, {
+      source: actor ?? "agent-relay",
+      type: "parent.cleared",
+      severity: "info",
+      title: "Parent cleared",
+      body: "",
+      metadata: {},
+    }, now);
+  }
+  return getTaskDetail(taskId)!;
+}
+
+export function clearTaskParent(taskId: number, actor?: string): TaskDetail {
+  return writeTransaction(() => clearTaskParentBody(taskId, actor, Date.now()));
+}
+
+export function listTaskChildren(taskId: number): number[] {
+  return (getDb().query(`SELECT id FROM tasks WHERE parent_task_id = ? AND kind = '${DELIVERABLE_TASK_KIND}' ORDER BY id ASC`).all(taskId) as Array<{ id: number }>)
+    .map((r) => r.id);
+}
+
+// --- Soft related-link (#1535 WS1): symmetric, non-blocking association — distinct from
+// the depends-on DAG (no ordering/gating semantics, no cycle concept). A single canonical
+// row (task_a_id < task_b_id) represents the undirected edge, so adding/removing from
+// either side of the pair is the same write and both directions read it back identically.
+function normalizedRelationPair(taskId: number, relatedTaskId: number): [number, number] {
+  if (taskId === relatedTaskId) throw new ValidationError("a task cannot be related to itself");
+  return taskId < relatedTaskId ? [taskId, relatedTaskId] : [relatedTaskId, taskId];
+}
+
+// The BODY of addTaskRelation, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the two existence
+// guard reads + the INSERT + event are one atomic unit. Same classification as addTaskDependencyBody:
+// the edge insert dedups via `ON CONFLICT DO NOTHING` but the event append is unconditional, so this is
+// `idempotent: false`. Assumes a transaction is already open; the sync wrapper below adds the tx.
+export function addTaskRelationBody(taskId: number, relatedTaskId: number, actor: string | undefined, now: number): TaskDetail {
+  requireDeliverable(taskId);
+  if (!getRawTask(relatedTaskId)) throw new ValidationError(`task ${relatedTaskId} not found`);
+  const [a, b] = normalizedRelationPair(taskId, relatedTaskId);
+  getDb().query("INSERT INTO task_relations (task_a_id, task_b_id, created_at) VALUES (?, ?, ?) ON CONFLICT DO NOTHING")
+    .run(a, b, now);
+  insertTaskEvent(taskId, {
+    source: actor ?? "agent-relay",
+    type: "related.added",
+    severity: "info",
+    title: `Related to task ${relatedTaskId}`,
+    body: "",
+    metadata: { relatedTaskId },
+  }, now);
+  return getTaskDetail(taskId)!;
+}
+
+export function addTaskRelation(taskId: number, relatedTaskId: number, actor?: string): TaskDetail {
+  return writeTransaction(() => addTaskRelationBody(taskId, relatedTaskId, actor, Date.now()));
+}
+
+// The BODY of removeTaskRelation, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the DELETE +
+// conditional event (guarded on `result.changes`) are one atomic unit — idempotent by construction
+// (same as removeTaskDependencyBody). Assumes a transaction is already open; the sync wrapper below
+// adds the tx.
+export function removeTaskRelationBody(taskId: number, relatedTaskId: number, actor: string | undefined, now: number): TaskDetail | null {
+  const [a, b] = normalizedRelationPair(taskId, relatedTaskId);
+  const result = getDb().query("DELETE FROM task_relations WHERE task_a_id = ? AND task_b_id = ?").run(a, b);
+  if (result.changes > 0) {
+    insertTaskEvent(taskId, {
+      source: actor ?? "agent-relay",
+      type: "related.removed",
+      severity: "info",
+      title: `Removed relation to task ${relatedTaskId}`,
+      body: "",
+      metadata: { relatedTaskId },
+    }, now);
+  }
+  return getTaskDetail(taskId);
+}
+
+export function removeTaskRelation(taskId: number, relatedTaskId: number, actor?: string): TaskDetail | null {
+  return writeTransaction(() => removeTaskRelationBody(taskId, relatedTaskId, actor, Date.now()));
+}
+
+export function listTaskRelated(taskId: number): number[] {
+  return (getDb().query(`
+    SELECT task_b_id AS id FROM task_relations WHERE task_a_id = ?
+    UNION
+    SELECT task_a_id AS id FROM task_relations WHERE task_b_id = ?
+    ORDER BY id ASC
+  `).all(taskId, taskId) as Array<{ id: number }>).map((r) => r.id);
+}
+
+// --- Refs: issue links (via issue_associations, the source of truth) + branch + commits.
+export interface AddTaskRefInput {
+  relation?: IssueRefRelation;
+  issue?: string;
+  defaultRepo?: string;
+  branch?: string;
+  commit?: TaskCommitRef;
+  actor?: string;
+}
+
+// The BODY of addTaskRef, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the guard read, the
+// issue resolve/associate + project-fill, the branch UPDATE, and the commit append (itself a read-guarded
+// write — see appendCommitRow) are one atomic unit, each with its own event append. `idempotent: false`:
+// every present field unconditionally appends its own event on each call. Assumes a transaction is
+// already open; the sync wrapper below adds the tx.
+export function addTaskRefBody(id: number, input: AddTaskRefInput, now: number): TaskDetail {
+  requireDeliverable(id);
+  const relation = cleanIssueRefRelation(input.relation);
+  if (input.issue) {
+    const ref = resolveIssueRefFromString({ ref: input.issue, defaultRepo: optionalText(input.defaultRepo, "defaultRepo", 500) });
+    associateIssue(ref.id, "task", taskEntityId(String(id)), relation);
+    fillTaskProjectFromRepo(id, ref.repo, now);
+    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, relation, 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, now);
+    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 function addTaskRef(id: number, input: AddTaskRefInput): TaskDetail {
+  return writeTransaction(() => addTaskRefBody(id, input, Date.now()));
+}
+
+export interface RemoveTaskRefInput {
+  issueRefId?: string;
+  branch?: boolean;
+  commitSha?: string;
+  actor?: string;
+}
+
+// The BODY of removeTaskRef, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the guard read + the
+// commit-filter read (getRawTask) that guards its own UPDATE are one atomic unit — no thread-hop between
+// the commit-list read and the write. Assumes a transaction is already open; the sync wrapper below adds
+// the tx.
+export function removeTaskRefBody(id: number, input: RemoveTaskRefInput, now: number): TaskDetail {
+  requireDeliverable(id);
+  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)!;
+}
+
+export function removeTaskRef(id: number, input: RemoveTaskRefInput): TaskDetail {
+  return writeTransaction(() => removeTaskRefBody(id, input, Date.now()));
+}
+
+// Read-guarded write (already a same-tx read+write before this migration): reads the current commits
+// array and appends only if the sha is not already present, so a duplicate append is a no-op. `now` is
+// threaded from the caller (H6) rather than re-read here.
+function appendCommitRow(id: number, commit: TaskCommitRef, now: number): 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), now, id);
+}
+
+// --- Attribution: who did what. Writes owner_agent_id + owner_agent_label (NOT claimed_by) + an attribution event.
+// label is stored at bind time so it survives agent reap and can be shown without a live roster lookup (#890).
+//
+// The BODY of assignTaskAgent, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the guard read +
+// the agent-record lookup (both guard the UPDATE) and the UPDATE + event are one atomic unit.
+// `idempotent: false`: unconditional UPDATE + event on every call. Assumes a transaction is already
+// open; the sync wrapper below adds the tx.
+export function assignTaskAgentBody(id: number, agentId: string, role: string | undefined, actor: string | undefined, now: number): TaskDetail {
+  const current = requireDeliverable(id);
+  const cleanAgent = requireText(agentId, "agentId", 200);
+  const agentRecord = getAgent(cleanAgent);
+  const agentLabel = agentRecord?.label || agentRecord?.name || null;
+  const cleanRole = optionalText(role, "role", 120);
+  getDb().query("UPDATE tasks SET owner_agent_id = ?, owner_agent_label = ?, updated_at = ? WHERE id = ?").run(cleanAgent, agentLabel, 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);
+  startTaskWorkBody(current, actor ?? cleanAgent, `owner ${cleanAgent} assigned`, now);
+  return getTaskDetail(id)!;
+}
+
+export function assignTaskAgent(id: number, agentId: string, role?: string, actor?: string): TaskDetail {
+  return writeTransaction(() => assignTaskAgentBody(id, agentId, role, actor, Date.now()));
+}
+
+// --- 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;
+}
+
+export interface RecordTaskDispatchDecisionInput {
+  decision: {
+    target?: unknown;
+    rationale?: string;
+    pinned?: boolean;
+    factors?: unknown;
+    warnings?: readonly unknown[];
+  };
+  source: string;
+  actor: 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.
+// The BODY of recordTaskSpawnRequested, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the
+// spawnRequestId dedup READ and the event insert are one atomic unit — dedups by construction on
+// spawnRequestId (a REQUIRED field, unlike recordGate's optional runId), so `idempotent: true` and no
+// gateway ledger key is needed. Assumes a transaction is already open; the sync wrapper below adds the tx.
+export function recordTaskSpawnRequestedBody(id: number, input: RecordTaskSpawnInput, now: number): 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 } : {}) },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export function recordTaskSpawnRequested(id: number, input: RecordTaskSpawnInput): TaskDetail {
+  return writeTransaction(() => recordTaskSpawnRequestedBody(id, input, Date.now()));
+}
+
+// The BODY of recordTaskDispatchDecision, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the
+// guard read and the event insert are one atomic unit. `idempotent: false`: unconditional event append
+// on every call, no dedup key. Assumes a transaction is already open; the sync wrapper below adds the tx.
+export function recordTaskDispatchDecisionBody(id: number, input: RecordTaskDispatchDecisionInput, now: number): TaskDetail {
+  requireDeliverable(id);
+  const source = requireText(input.source, "source", 120);
+  const actor = requireText(input.actor, "actor", 200);
+  const target = isObject(input.decision.target) ? input.decision.target : {};
+  const rationale = optionalText(input.decision.rationale, "rationale", 4000) ?? "No dispatch rationale recorded";
+  const warnings = Array.isArray(input.decision.warnings)
+    ? input.decision.warnings.filter((item): item is string => typeof item === "string")
+    : [];
+  insertTaskEvent(id, {
+    source: actor,
+    type: "dispatch.resolved",
+    severity: warnings.length ? "warning" : "info",
+    title: `Dispatch resolved: ${typeof target.provider === "string" ? target.provider : "provider"}`,
+    body: rationale,
+    metadata: {
+      source,
+      decision: {
+        target,
+        rationale,
+        pinned: input.decision.pinned === true,
+        ...(isObject(input.decision.factors) ? { factors: input.decision.factors } : {}),
+        warnings,
+      },
+    },
+  }, now);
+  return getTaskDetail(id)!;
+}
+
+export function recordTaskDispatchDecision(id: number, input: RecordTaskDispatchDecisionInput): TaskDetail {
+  return writeTransaction(() => recordTaskDispatchDecisionBody(id, input, Date.now()));
+}
+
+// --- Reads / projections.
+function issueLinks(id: number, task?: Pick<Task, "dispatch" | "ownerAgentId">): TaskIssueLink[] {
+  const defaultRelation = defaultTaskIssueRelation(task?.dispatch, task?.ownerAgentId);
+  return listIssuesForEntity("task", taskEntityId(String(id))).map((item) => ({
+    issueRefId: item.issueRef.id,
+    relation: item.association.relation ?? defaultRelation,
+    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,
+    ...(item.issueRef.closeReason ? { closeReason: item.issueRef.closeReason } : {}),
+  }));
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function getTaskDetail(id: number): TaskDetail | null {
+  const task = getRawTask(id);
+  if (!task || task.kind !== DELIVERABLE_TASK_KIND) return null;
+  const decision = latestTaskDispatchDecision(id);
+  const workerModel = taskBoundWorkerModel(task.ownerAgentId);
+  // #2518 — derived from the event ledger (db/task-review-hold.ts), never stored.
+  const pendingReviewDelivery = taskPendingReviewDelivery(id);
+  const edges = listTaskDependencyEdges(id);
+  const dependsOnStages = Object.fromEntries(edges.flatMap((edge) => edge.required_stage ? [[String(edge.depends_on_task_id), edge.required_stage] as const] : []));
+  return {
+    ...task,
+    issues: issueLinks(id, task),
+    dependsOn: edges.map((edge) => edge.depends_on_task_id),
+    ...(Object.keys(dependsOnStages).length ? { dependsOnStages } : {}),
+    dependents: listTaskDependents(id),
+    gates: latestGates(id),
+    dispatchWorkShape: taskDispatchWorkShape(task.dispatch),
+    ...(decision ? { dispatchDecision: decision } : {}),
+    ...(workerModel ? { boundWorkerModel: workerModel } : {}),
+    children: listTaskChildren(id),
+    related: listTaskRelated(id),
+    ...(pendingReviewDelivery ? { pendingReviewDelivery } : {}),
+    ...taskExecutionField(id),
+  };
+}
+
+export { listDeliverableTasks, countDeliverableTasks, listDeliverableTaskSummaries, type ListDeliverableTasksFilter } from "./task-list.ts";
+
+// 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);
+}
+
+// #910 — true once this deliverable task has recorded a `deliverable` event (any disposition). The
+// task-deliver path routes a structured `task.deliverable` notification to the spawner for that same
+// event, so the lineage report-up flush treats this as "the spawner was already told" and suppresses
+// its redundant narrative turn-final / reap-time re-flush (db/messages.ts flushWorkFinalReports).
+export function taskHasDeliverableEvent(taskId: number): boolean {
+  if (!Number.isSafeInteger(taskId) || taskId <= 0) return false;
+  return Boolean(getDb()
+    .query("SELECT 1 FROM task_events WHERE task_id = ? AND type = 'deliverable' LIMIT 1")
+    .get(taskId));
+}
+
+// #2125 — the `created_at` of this deliverable task's `deliverable` event (earliest, if somehow more
+// than one), or undefined if none. The #910 suppression above reads this to narrow its window: a held
+// lineage capture from BEFORE this timestamp was part of the delivery itself (already covered by the
+// structured `task.deliverable` notification); one from AFTER it is post-delivery work the spawner has
+// not otherwise heard about and must still report up.
+export function taskDeliverableEventCreatedAt(taskId: number): number | undefined {
+  if (!Number.isSafeInteger(taskId) || taskId <= 0) return undefined;
+  const row = getDb()
+    .query("SELECT created_at AS createdAt FROM task_events WHERE task_id = ? AND type = 'deliverable' ORDER BY created_at ASC LIMIT 1")
+    .get(taskId) as { createdAt: number } | undefined;
+  return row?.createdAt;
+}
+
+// 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).
+//
+// The BODY of markTaskAgentReaped, folded into ONE transaction (ADR §3.4, S3 L-D2 #1904): the guard read
+// and the UPDATE + event are one atomic unit. NOTE despite the doc-comment's "idempotent" framing above
+// (a same-land re-fire is expected to be a no-op in PRACTICE), the op has no STRUCTURAL dedup: it
+// unconditionally re-stamps `reaped_at` and re-appends an `agent.reaped` event on every call, so per the
+// ADR §3.7.1 STRUCTURAL gate this is `idempotent: false` and the async facade supplies a per-submission
+// key. Assumes a transaction is already open; the sync wrapper below adds the tx.
+export function markTaskAgentReapedBody(id: number, input: { agentId: string; reason?: string }, now: number): TaskDetail {
+  requireDeliverable(id);
+  const agentId = requireText(input.agentId, "agentId", 200);
+  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 markTaskAgentReaped(id: number, input: { agentId: string; reason?: string; at?: number }): TaskDetail {
+  return writeTransaction(() => markTaskAgentReapedBody(id, input, input.at ?? Date.now()));
+}
+
+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, getRawTask(id) ?? undefined)) {
+      if (seen.has(link.issueRefId)) continue;
+      seen.add(link.issueRefId);
+      out.push(link);
+    }
+  }
+  return out;
+}