agent-relay-server 0.106.0 → 0.108.0

package/src/services/task-lifecycle.ts

@@ -0,0 +1,465 @@
+// #831 — Task lifecycle automation ON LAND. The land event already knows the branch, commit,
+// backlink, and (worker-reported) gate ledger; this service turns that authoritative land into
+// the Task drive the coordinator otherwise hand-does (~40% of its tool calls): advance the
+// deliverable axis, attach the deliverable, project the issue-close, notify stakeholders, and
+// reap a one-shot worker.
+//
+// LAND-PIPELINE SAFETY (the #823/#824 strand lane lives next door): this is OBSERVE-ONLY. It is
+// invoked best-effort + non-blocking from `notifyBranchLanded` AFTER the merge already completed,
+// so a throw here can never fail or alter a merge. It never touches merge/branch state.
+//
+// TWO DECOUPLED EVENTS (Edin's refinement on #830):
+//   - reap-signal  = deliverable landed + gates passed → dispose the bound one-shot worker NOW
+//                    (frees the live-children slot + quota immediately; the worker's contribution
+//                    is verifiably complete the moment its branch lands green).
+//   - task-done    = the Task's own `doneWhen` field → reaching it CLOSES the Task (execution
+//                    status → done). A Task can sit at `landed-on-main` with its worker already
+//                    gone, advancing to `deployed` on the deliverable-position axis without it.
+// So: landed+gates frees the AGENT; doneWhen closes the TASK. Both are wired below.
+//
+// FIELD-OWNERSHIP BOUNDARY (#830/#833): GitHub owns intent/spec/acceptance/discussion; the Task
+// owns execution telemetry. Issue CLOSE is the canonical #482/#474 path (which runs just before
+// this in `notifyBranchLanded`) — we do NOT re-close; we PROJECT it via #833's `taskCloseBridge`.
+// The one write-through we make is the single milestone summary (#833's milestone exception).
+import { errMessage, TASK_DELIVERABLE_STAGES } from "agent-relay-sdk";
+import {
+  deliverableTaskIdsByBranch,
+  deliverableTaskIdsByOwnerAgent,
+  deliverableTaskIdsBySpawnRequestId,
+  getAgent,
+  getTaskDetail,
+  markTaskAgentReaped,
+} from "../db";
+import { setTaskEntityStage, setTaskEntityStatus } from "./task-entity";
+import { postTaskMilestoneComment, taskCloseBridge, type TaskCloseBridgeEntry } from "./task-issue-weave";
+import { requestTransientAgentShutdown } from "./transient-agent-reaper";
+import { emitRelayEvent } from "../events";
+import { routeNotification } from "../notification-router";
+import { resolveCoordinatorAgentId } from "../steward-identity";
+import { emitTaskSemanticNotification } from "./task-semantic-events";
+import type { IssueRef, TaskDeliverableStage, TaskGateState, WorkspaceRecord } from "../types";
+import type { IssueTrackerAdapter } from "../issue-tracker";
+
+type LifecycleWorkspace = Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "baseSha" | "ownerAgentId">;
+type LogFn = (message: string) => void;
+
+export interface LandedTaskLifecycleInput {
+  workspace: LifecycleWorkspace;
+  mergedSha?: string;
+  subject?: string;
+  commitSubjects?: string[];
+  /** The land arrived via a PR (subject's trailing `(#N)` is the PR number) — forwarded for parity
+   *  with the issue-lifecycle hook; the Task drive itself doesn't parse backlinks. */
+  prLand?: boolean;
+}
+
+export interface TaskLifecycleOptions {
+  log?: LogFn;
+  /** Injected for tests so the milestone write-through never hits a live tracker. */
+  adapterResolver?: (ref: IssueRef) => IssueTrackerAdapter;
+}
+
+// One Task's land outcome — the structured payload the coordinator receipt + relay event carry.
+export interface TaskLandOutcome {
+  taskId: number;
+  error?: string;
+  deliverableStage?: TaskDeliverableStage;
+  gatesPassed?: boolean;
+  /** Why gates were not passed (empty/missing/partial/failed), for the receipt + green-report guard. */
+  gateReason?: string;
+  doneWhen?: string;
+  doneWhenSatisfied?: boolean;
+  /** Execution status was advanced to `done` because doneWhen was reached. */
+  statusAdvanced?: boolean;
+  /** Linked issues the canonical #482 path has closed (projection, not a re-close). */
+  issuesClosed?: number;
+  issuesLinked?: number;
+  milestonePosted?: boolean;
+  reaped?: boolean;
+  reapedAgentId?: string;
+  reapSkipReason?: string;
+}
+
+export interface LandedTaskLifecycleResult {
+  handled: boolean;
+  reason?: string;
+  tasks: TaskLandOutcome[];
+}
+
+// --- diff summary (injectable for tests; best-effort git, never throws into the land) ----------
+type DiffSummaryResolver = (input: LandedTaskLifecycleInput) => string | undefined;
+let diffSummaryResolverForTests: DiffSummaryResolver | undefined;
+type DriveTaskResolver = typeof driveTaskOnLand;
+let driveTaskOnLandForTests: DriveTaskResolver | undefined;
+export function __setLandedDiffSummaryResolverForTests(resolver: DiffSummaryResolver | undefined): void {
+  diffSummaryResolverForTests = resolver;
+}
+
+export function __setDriveTaskOnLandForTests(resolver: DriveTaskResolver | undefined): void {
+  driveTaskOnLandForTests = resolver;
+}
+
+function landedDiffSummary(input: LandedTaskLifecycleInput, log: LogFn): string | undefined {
+  if (diffSummaryResolverForTests) return diffSummaryResolverForTests(input);
+  const repoRoot = input.workspace.repoRoot?.trim();
+  const baseSha = input.workspace.baseSha?.trim();
+  const tipSha = input.mergedSha?.trim();
+  if (!repoRoot || !baseSha || !tipSha || baseSha === tipSha) return undefined;
+  try {
+    const proc = Bun.spawnSync(["git", "-C", repoRoot, "diff", "--shortstat", `${baseSha}..${tipSha}`], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (proc.exitCode !== 0) return undefined;
+    const out = Buffer.from(proc.stdout).toString("utf8").trim();
+    return out || undefined;
+  } catch (error) {
+    log(`task lifecycle diff summary failed for ${input.workspace.id}: ${errMessage(error)}`);
+    return undefined;
+  }
+}
+
+// --- doneWhen → deliverable-stage mapping -------------------------------------------------------
+const STAGE_INDEX = new Map<string, number>(TASK_DELIVERABLE_STAGES.map((stage, i) => [stage, i]));
+
+// Which deliverable stage satisfies a Task's `doneWhen`. `doneWhen` is free text (#834): we map
+// the small known vocabulary (`landed` | `deployed` | `deliverable-attached`, with synonyms) and
+// default an UNSET doneWhen to `landed-on-main` — the common case where a Task is done when it
+// lands. An unrecognized value falls back to the landed default rather than blocking forever.
+function doneWhenTargetStage(doneWhen: string | undefined): TaskDeliverableStage {
+  const value = doneWhen?.trim().toLowerCase();
+  if (!value) return "landed-on-main";
+  if (value.includes("deploying")) return "deploying";
+  if (value.includes("deploy")) return "deployed";
+  return "landed-on-main";
+}
+
+function stageSatisfiesDoneWhen(stage: TaskDeliverableStage, doneWhen: string | undefined): boolean {
+  const current = STAGE_INDEX.get(stage) ?? 0;
+  const target = STAGE_INDEX.get(doneWhenTargetStage(doneWhen)) ?? STAGE_INDEX.get("landed-on-main")!;
+  return current >= target;
+}
+
+// --- gate verdict ------------------------------------------------------------------------------
+// "Gates passed" is the signal that frees the agent (reap) AND closes the Task (doneWhen). The
+// merge landing green is necessary but NOT sufficient (Codex #831 review): a worker that crashed
+// before reporting gates, or reported only a subset, must NOT read as green on a vacuous `[]`.
+// So a pass REQUIRES the expected gates present-and-passing AND no recorded gate failing. An
+// empty / missing / partial / failed ledger is NOT passed → no reap, no close, no green report.
+export const EXPECTED_GATES = ["typecheck", "test"] as const;
+
+interface GateVerdict {
+  passed: boolean;
+  reason?: string;
+}
+
+function evaluateGates(gates: TaskGateState[]): GateVerdict {
+  if (gates.length === 0) return { passed: false, reason: "no-gates-reported" };
+  const reported = new Map(gates.map((gate) => [gate.gate, gate.status]));
+  const missing = EXPECTED_GATES.filter((name) => !reported.has(name));
+  if (missing.length > 0) return { passed: false, reason: `missing-gates:${missing.join("+")}` };
+  const failed = gates.filter((gate) => gate.status !== "pass").map((gate) => gate.gate);
+  if (failed.length > 0) return { passed: false, reason: `failed-gates:${failed.join("+")}` };
+  return { passed: true };
+}
+
+// Stable land identity — shared shape with the issue-lifecycle landKey so the milestone summary
+// is idempotent per land (a re-fired land posts at most one summary).
+function landKeyFor(input: LandedTaskLifecycleInput): string {
+  const base = input.workspace.baseRef ?? "main";
+  const sha = input.mergedSha?.trim();
+  if (sha) return `land:${base}:${sha}`;
+  return `land:${base}:${input.workspace.id}:${input.workspace.branch ?? "unknown"}`.slice(0, 240);
+}
+
+// --- land → Task linkage (#838 attribution) ----------------------------------------------------
+// Resolve the bound Task(s) for a landed workspace. The robust key is the spawned WORKER, not the
+// branch (a worker cuts its own branch). Union of: owner_agent_id (assignTaskAgent #838), the
+// `agent.spawn_requested` attribution keyed on the worker's meta.spawnRequestId (fire-and-forget,
+// owner not yet backfilled), and the Task's recorded branch column. Deduped + ordered. Returns []
+// for an ordinary non-task branch → the land is a strict no-op (behavior byte-identical).
+function resolveBoundTaskIds(workspace: LifecycleWorkspace): number[] {
+  const ids = new Set<number>();
+  const owner = workspace.ownerAgentId?.trim();
+  if (owner) {
+    for (const id of deliverableTaskIdsByOwnerAgent(owner)) ids.add(id);
+    const spawnRequestId = getAgent(owner)?.meta?.spawnRequestId;
+    if (typeof spawnRequestId === "string" && spawnRequestId.trim()) {
+      for (const id of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) ids.add(id);
+    }
+  }
+  if (workspace.branch) {
+    for (const id of deliverableTaskIdsByBranch(workspace.branch)) ids.add(id);
+  }
+  return [...ids].sort((a, b) => a - b);
+}
+
+// --- reap signal (decoupled from task-done) ----------------------------------------------------
+interface ReapResult {
+  reaped: boolean;
+  agentId?: string;
+  reason?: string;
+}
+
+// Dispose the LANDING one-shot worker — but only when EVERY Task this land bound to it is
+// satisfied (landed + gates-passed), never as soon as a single task goes green (Codex #831).
+// A shared transient owning multiple deliverable Tasks keeps running until all of them clear, so
+// it can't be killed out from under another bound task with missing/failed gates or open work.
+// Owner-level (run once after all tasks are driven), not per-task. Guards: the agent must still
+// exist (already gone → nothing to reap) and be `transient` (one-shot); a `persistent` worker
+// keeps running (land-and-continue). Idempotent: any bound Task already stamped `reapedAt` short-
+// circuits, so a re-land never re-reaps. Reuses the reaper's canonical shutdown path.
+function maybeReapOwnerWorker(workspace: LifecycleWorkspace, outcomes: TaskLandOutcome[]): ReapResult {
+  const driven = outcomes.filter((outcome) => !outcome.error);
+  if (driven.length === 0) return { reaped: false, reason: "no-task-driven" };
+  const agentId = workspace.ownerAgentId?.trim();
+  if (!agentId) return { reaped: false, reason: "no-owner-agent" };
+  if (driven.some((outcome) => getTaskDetail(outcome.taskId)?.reapedAt)) return { reaped: false, agentId, reason: "already-reaped" };
+  const unsatisfied = driven.filter((outcome) => outcome.gatesPassed !== true);
+  if (unsatisfied.length > 0) return { reaped: false, agentId, reason: `tasks-not-all-passed:${unsatisfied.map((o) => o.taskId).join("+")}` };
+  const agent = getAgent(agentId);
+  if (!agent) return { reaped: false, agentId, reason: "agent-gone" };
+  if (agent.lifecycle !== "transient") return { reaped: false, agentId, reason: "persistent-worker" };
+  requestTransientAgentShutdown(agent, {
+    reason: "deliverable-landed",
+    requestedBy: "task-lifecycle",
+    workspaceId: workspace.id,
+    workspaceStatus: "merged",
+    activityTitle: "One-shot worker reaped on land",
+    activityBody: `All ${driven.length} bound deliverable(s) landed green; disposing one-shot worker ${agentId} to free its slot + quota`,
+    landReason: "deliverable-landed",
+  });
+  return { reaped: true, agentId };
+}
+
+// Stamp the reap marker on every bound Task + annotate the outcomes (the reap is decided ONCE at
+// owner level, then applied across the owner's tasks).
+function finalizeReap(outcomes: TaskLandOutcome[], reap: ReapResult, log: LogFn): void {
+  for (const outcome of outcomes) {
+    if (outcome.error) continue;
+    outcome.reaped = reap.reaped;
+    if (reap.agentId) outcome.reapedAgentId = reap.agentId;
+    if (reap.reason) outcome.reapSkipReason = reap.reason;
+    if (reap.reaped && reap.agentId) {
+      try {
+        markTaskAgentReaped(outcome.taskId, { agentId: reap.agentId, reason: "deliverable-landed" });
+      } catch (error) {
+        log(`task reap marker failed for task ${outcome.taskId}: ${errMessage(error)}`);
+      }
+    }
+  }
+}
+
+// --- per-Task drive ----------------------------------------------------------------------------
+async function driveTaskOnLand(
+  taskId: number,
+  input: LandedTaskLifecycleInput,
+  diffSummary: string | undefined,
+  opts: TaskLifecycleOptions,
+  log: LogFn,
+): Promise<TaskLandOutcome> {
+  const before = getTaskDetail(taskId);
+  if (!before) return { taskId, error: "task not found" };
+  const landKey = landKeyFor(input);
+
+  // 1 + 2 (deliverable-position axis) — advance the stage to `landed-on-main` and ATTACH the
+  // landed commit (idempotent append). The execution `status` axis is handled separately below.
+  const commit = input.mergedSha ? { sha: input.mergedSha, ...(input.subject ? { subject: input.subject } : {}) } : undefined;
+  let detail = setTaskEntityStage(taskId, {
+    deliverableStage: "landed-on-main",
+    ...(input.workspace.branch ? { branch: input.workspace.branch } : {}),
+    ...(commit ? { commit } : {}),
+    actor: "task-lifecycle",
+  });
+
+  // 2 (gate ledger) — READ the worker-reported gates and VERIFY them (see evaluateGates): the
+  // source of truth for "gates passed". We never fabricate gate runs; the worker records
+  // typecheck/test via recordGate before landing. Empty/missing/partial/failed ⇒ NOT passed.
+  const gates = detail.gates;
+  const gateVerdict = evaluateGates(gates);
+  const gatesPassed = gateVerdict.passed;
+
+  // 3 (doneWhen axis) — reaching the Task's doneWhen target CLOSES the Task (execution status →
+  // done) — but ONLY with verified gates (Codex #831): a failed/incomplete gate keeps the Task
+  // open, never `done`, even at/after the doneWhen stage. Otherwise it stays where it was ("landed
+  // but not done", e.g. doneWhen=deployed waits on deploy). Idempotent: an already-done Task isn't
+  // re-written.
+  const doneWhenSatisfied = stageSatisfiesDoneWhen("landed-on-main", before.doneWhen);
+  let statusAdvanced = false;
+  if (doneWhenSatisfied && gatesPassed && before.status !== "done") {
+    detail = setTaskEntityStatus(taskId, {
+      status: "done",
+      note: `doneWhen reached on land (${input.mergedSha?.slice(0, 12) ?? input.workspace.branch ?? "merged"})`,
+      actor: "task-lifecycle",
+    });
+    statusAdvanced = true;
+  }
+
+  // 3b (close projection) — the linked issue is closed by the canonical #482/#474 path (which ran
+  // immediately before this in notifyBranchLanded). We PROJECT that ledger via #833, never re-close.
+  let closeBridge: TaskCloseBridgeEntry[] = [];
+  try {
+    closeBridge = taskCloseBridge(taskId);
+  } catch (error) {
+    log(`task close-bridge projection failed for task ${taskId}: ${errMessage(error)}`);
+  }
+  const issuesClosed = closeBridge.filter((entry) => entry.closed).length;
+
+  // 4 (notify) — the single milestone write-through (#833 exception), idempotent by landKey.
+  let milestonePosted = false;
+  try {
+    const summaryBits = [`Landed to \`${input.workspace.baseRef ?? "main"}\``];
+    if (diffSummary) summaryBits.push(diffSummary);
+    if (!gatesPassed) summaryBits.push(`gates not verified (${gateVerdict.reason ?? "incomplete"})`);
+    summaryBits.push(statusAdvanced ? "Task done (doneWhen reached)" : `Task at \`landed-on-main\` (doneWhen \`${before.doneWhen ?? "landed"}\` not yet reached)`);
+    const milestone = await postTaskMilestoneComment(
+      {
+        taskId,
+        milestone: "landed",
+        summary: summaryBits.join(" — "),
+        idempotencyKey: landKey,
+        ...(input.mergedSha ? { commitSha: input.mergedSha } : {}),
+        gates,
+        author: "task-lifecycle",
+      },
+      { ...(opts.adapterResolver ? { adapterResolver: opts.adapterResolver } : {}), log },
+    );
+    milestonePosted = milestone.posted.length > 0 || milestone.deduped;
+  } catch (error) {
+    log(`task milestone comment failed for task ${taskId} on ${landKey}: ${errMessage(error)}`);
+  }
+
+  // NOTE: the one-shot reap (step 5) is decided ONCE at OWNER level AFTER every bound Task is
+  // driven (maybeReapOwnerWorker), never per-task — a shared transient must not be killed the
+  // instant one of its tasks goes green while another still has open/red gates (Codex #831).
+  return {
+    taskId,
+    deliverableStage: "landed-on-main",
+    gatesPassed,
+    ...(gateVerdict.reason ? { gateReason: gateVerdict.reason } : {}),
+    doneWhen: before.doneWhen,
+    doneWhenSatisfied,
+    statusAdvanced,
+    issuesClosed,
+    issuesLinked: closeBridge.length,
+    milestonePosted,
+  };
+}
+
+// 4b (basic deliverable event) — SEAM for #835's rich semantic-event subscriptions. Emitted AFTER
+// the owner-level reap decision so `reaped` is accurate. A deliverable-LEVEL event ("task
+// deliverable landed", not "commit X merged") through the existing bus; #835 enriches the
+// audience/subscription layer on top of this same event.
+function emitDeliverableLandedEvent(input: LandedTaskLifecycleInput, outcome: TaskLandOutcome): void {
+  const landKey = landKeyFor(input);
+  if (outcome.error) {
+    emitDeliverableErrorReceipt(input, outcome, landKey);
+    return;
+  }
+  emitRelayEvent({
+    type: "task.deliverable_landed",
+    source: "server",
+    subject: String(outcome.taskId),
+    data: {
+      taskId: outcome.taskId,
+      workspaceId: input.workspace.id,
+      branch: input.workspace.branch,
+      base: input.workspace.baseRef ?? "main",
+      sha: input.mergedSha,
+      deliverableStage: "landed-on-main",
+      gatesPassed: outcome.gatesPassed ?? false,
+      statusAdvanced: outcome.statusAdvanced ?? false,
+      issuesClosed: outcome.issuesClosed ?? 0,
+      reaped: outcome.reaped ?? false,
+      landKey,
+      // #835 seam: the enriched semantic-subscription fan-out reads off this same event.
+      semanticEvent: "deliverable.landed",
+    },
+  });
+  const task = getTaskDetail(outcome.taskId);
+  if (!task) return;
+  const coordinator = resolveCoordinatorAgentId(input.workspace.ownerAgentId ?? undefined);
+  emitTaskSemanticNotification({
+    task,
+    transition: "landed",
+    actor: "task-lifecycle",
+    recipients: coordinator ? [coordinator] : [],
+    workspaceId: input.workspace.id,
+    branch: input.workspace.branch,
+    sha: input.mergedSha,
+    landKey,
+    outcome: outcome as unknown as Record<string, unknown>,
+  });
+}
+
+function emitDeliverableErrorReceipt(input: LandedTaskLifecycleInput, outcome: TaskLandOutcome, landKey: string): void {
+  const coordinator = resolveCoordinatorAgentId(input.workspace.ownerAgentId ?? undefined);
+  if (!coordinator) return;
+  const task = getTaskDetail(outcome.taskId);
+  routeNotification({
+    type: "task.landed",
+    scope: {
+      taskId: String(outcome.taskId),
+      transition: "landed",
+      landKey,
+      ...(input.workspace.ownerAgentId ? { agentId: input.workspace.ownerAgentId, author: input.workspace.ownerAgentId } : {}),
+      ...(task?.createdBy ? { parent: task.createdBy } : {}),
+      ...(task?.teamId ? { teamId: task.teamId } : {}),
+      workspaceId: input.workspace.id,
+    },
+    recipients: [{ agentId: coordinator, matchedRule: "task-stakeholder" }],
+    ttlMs: null,
+    message: {
+      subject: `Task #${outcome.taskId} land lifecycle failed`,
+      body: `Task #${outcome.taskId} landed, but Relay could not complete the task lifecycle automation: ${outcome.error}`,
+      payload: {
+        kind: "task.lifecycle-error",
+        notification: "task-lifecycle-error",
+        taskId: outcome.taskId,
+        transition: "landed",
+        semanticEvent: "task.landed",
+        workspaceId: input.workspace.id,
+        branch: input.workspace.branch,
+        ...(input.mergedSha ? { sha: input.mergedSha } : {}),
+        outcome: outcome as unknown as Record<string, unknown>,
+      },
+      idempotencyKey: `task:${outcome.taskId}:land-error:${landKey}`,
+      replyExpected: false,
+    },
+  });
+}
+
+/**
+ * Drive the bound Task(s) off a confirmed land. Best-effort + non-blocking: the caller invokes this
+ * AFTER the merge completed and isolates its throws, so nothing here can fail a merge. A non-task
+ * branch (no bound Task) is a strict no-op. See the module header for the reap-vs-done decoupling.
+ */
+export async function handleLandedTaskLifecycle(
+  input: LandedTaskLifecycleInput,
+  opts: TaskLifecycleOptions = {},
+): Promise<LandedTaskLifecycleResult> {
+  const log = opts.log ?? ((message: string) => console.warn(message));
+  // Non-default-base lands never drive a deliverable (mirror the issue-lifecycle guard).
+  if ((input.workspace.baseRef ?? "main") !== "main") return { handled: false, reason: "non-default-branch", tasks: [] };
+  const taskIds = resolveBoundTaskIds(input.workspace);
+  if (taskIds.length === 0) return { handled: false, reason: "no-bound-task", tasks: [] };
+
+  const diffSummary = landedDiffSummary(input, log);
+  const outcomes: TaskLandOutcome[] = [];
+  for (const taskId of taskIds) {
+    try {
+      const drive = driveTaskOnLandForTests ?? driveTaskOnLand;
+      outcomes.push(await drive(taskId, input, diffSummary, opts, log));
+    } catch (error) {
+      log(`task lifecycle drive failed for task ${taskId} on ${input.workspace.id}: ${errMessage(error)}`);
+      outcomes.push({ taskId, error: errMessage(error) });
+    }
+  }
+  // Reap (step 5) is decided ONCE at owner level, only when ALL bound tasks are satisfied — then
+  // applied/annotated across the outcomes. The deliverable event is emitted after, with the
+  // accurate `reaped`.
+  finalizeReap(outcomes, maybeReapOwnerWorker(input.workspace, outcomes), log);
+  for (const outcome of outcomes) emitDeliverableLandedEvent(input, outcome);
+  return { handled: true, tasks: outcomes };
+}

package/src/services/task-plan-view.ts

@@ -0,0 +1,178 @@
+// #836 — the plan DAG as a VIEW over Tasks. The keystone #834 made `task_dependencies`
+// the durable, cycle-checked edge store and added `PlanNode.refs.taskId` as the binding
+// seam. This module collapses the plan DAG onto that spine: one primitive (the Task), two
+// views. It holds only PURE projections (db reads → Plan shape) so it stays a leaf module —
+// plan-graph.ts imports from here, never the reverse, which keeps the binding/mutation
+// machinery (bindPlanNodeToTask, edge canonicalization) in plan-graph without an import cycle.
+//
+// Two projections live here:
+//   1. projectPlanOverTasks(plan): overlay an EXISTING plan row's bound nodes with their
+//      Task's title/intent/status (single source of truth — no double-bookkeeping) and merge
+//      in the task_dependencies edges among bound nodes. This is the coexistence path: legacy
+//      unbound plans pass through untouched.
+//   2. buildTaskGraphView({teamId}): synthesize a whole Plan-shaped DAG from a team's
+//      deliverable Tasks + their task_dependencies, with NO plan row at all. This is the
+//      endgame view — the queue IS the task list, the DAG IS the task→task edges.
+import { getTaskDetail, listDeliverableTasks, listTaskDependencies } from "../db";
+import type { Plan, PlanEdge, PlanNode, PlanStatus, Task, TaskStatus } from "../types";
+
+// Synthetic node id for a Task in the pure task-backed view. Stable per Task so the view is
+// idempotent and a dashboard can diff it across refreshes.
+export function taskNodeId(taskId: number): string {
+  return `task_${taskId}`;
+}
+
+// Parse a stored refs.taskId (always a numeric string once cleanRefs has validated it) back
+// to a positive integer, or undefined for an unbound node.
+export function parseTaskId(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isSafeInteger(n) && n >= 1 ? n : undefined;
+}
+
+// Task execution status (+ deliverable stage) → the 4-state plan status. The deliverable
+// stage wins for terminal success: a Task that has landed/deployed reads as "landed" on the
+// board even while its execution status is still settling.
+export function taskStatusToPlanStatus(task: Pick<Task, "status" | "deliverableStage">): PlanStatus {
+  if (task.deliverableStage === "landed-on-main" || task.deliverableStage === "deploying" || task.deliverableStage === "deployed") {
+    return "landed";
+  }
+  switch (task.status) {
+    case "done":
+      return "landed";
+    case "in_progress":
+    case "claimed":
+      return "in-progress";
+    case "blocked":
+    case "failed":
+    case "canceled":
+    case "orphaned":
+      return "blocked";
+    default:
+      return "pending";
+  }
+}
+
+// Reverse map for the migration path (plan node → freshly-created Task). The plan's coarse
+// status seeds the Task's execution status; the richer deliverable axis is filled in later by
+// the land pipeline, not guessed here.
+export function planStatusToTaskStatus(status: PlanStatus): TaskStatus {
+  switch (status) {
+    case "in-progress":
+      return "in_progress";
+    case "landed":
+      return "done";
+    case "blocked":
+      return "blocked";
+    default:
+      return "open";
+  }
+}
+
+function dedupePlanEdges(edges: PlanEdge[]): PlanEdge[] {
+  const seen = new Set<string>();
+  const out: PlanEdge[] = [];
+  for (const edge of edges) {
+    const key = `${edge.from}\0${edge.to}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(edge);
+  }
+  return out;
+}
+
+// Overlay a stored plan with its Task bindings. Bound nodes take their label/scopeBlurb/status
+// from the Task (the Task is the source of truth); edges among bound nodes are projected from
+// the canonical task_dependencies store and merged with the plan's own (legacy/unbound) edges.
+// An unbound plan — the common legacy case — is returned unchanged.
+export function projectPlanOverTasks(plan: Plan): Plan {
+  const taskByNode = new Map<string, number>();
+  const nodeByTask = new Map<number, string>();
+  for (const node of plan.nodes) {
+    const taskId = parseTaskId(node.refs?.taskId);
+    if (taskId !== undefined) {
+      taskByNode.set(node.id, taskId);
+      nodeByTask.set(taskId, node.id);
+    }
+  }
+  if (taskByNode.size === 0) return plan;
+
+  const nodes = plan.nodes.map((node) => {
+    const taskId = taskByNode.get(node.id);
+    if (taskId === undefined) return node;
+    const task = getTaskDetail(taskId);
+    // A deleted/non-deliverable Task leaves the stored node as-is — stale but safe; the
+    // binding can be repaired by re-binding rather than crashing the whole plan read.
+    if (!task) return node;
+    const projected: PlanNode = {
+      ...node,
+      label: task.title,
+      status: taskStatusToPlanStatus(task),
+      ...(task.ownerAgentId ? { ownerRef: { ...(node.ownerRef ?? {}), agentId: task.ownerAgentId } } : {}),
+    };
+    // scopeBlurb mirrors the Task's intent EXACTLY — including clearing it when the Task's
+    // intent was removed. Preserving the stored node field would leave a stale blurb visible
+    // after intent is cleared (#836 review). The Task is the single source of truth.
+    if (task.intent) projected.scopeBlurb = task.intent;
+    else delete projected.scopeBlurb;
+    return projected;
+  });
+
+  // task_dependencies edge `T depends on D` projects to plan edge {from: D, to: T} — the
+  // prerequisite points at the dependent, matching the existing plan-edge direction.
+  const projected: PlanEdge[] = [];
+  for (const [nodeId, taskId] of taskByNode) {
+    for (const dependsOn of listTaskDependencies(taskId)) {
+      const fromNode = nodeByTask.get(dependsOn);
+      if (fromNode) projected.push({ from: fromNode, to: nodeId });
+    }
+  }
+  return { ...plan, nodes, edges: dedupePlanEdges([...plan.edges, ...projected]) };
+}
+
+function taskToPlanNode(task: Task): PlanNode {
+  return {
+    id: taskNodeId(task.id),
+    label: task.title,
+    ...(task.intent ? { scopeBlurb: task.intent } : {}),
+    ...(task.ownerAgentId ? { ownerRef: { agentId: task.ownerAgentId } } : {}),
+    status: taskStatusToPlanStatus(task),
+    statusSource: "bound",
+    refs: { taskId: String(task.id) },
+  };
+}
+
+// Synthesize a Plan-shaped DAG entirely from a team's deliverable Tasks — no plan row exists.
+// Every Task is a node; every task_dependency is an edge. This is the canonical forward view:
+// a coordinator expresses "B depends on A" via relay_task_add_dependency and reads the ordering
+// here without ever creating a plan. Returns a virtual Plan (id `taskgraph_<teamId>`); the
+// thread/version fields are placeholders since there is no persisted row.
+export function buildTaskGraphView(input: { teamId: string; status?: string; limit?: number }): Plan {
+  const teamId = input.teamId.trim();
+  if (!teamId) throw new Error("teamId required for the task-backed plan view");
+  const tasks = listDeliverableTasks({ teamId, ...(input.status ? { status: input.status } : {}), ...(input.limit ? { limit: input.limit } : {}) });
+  const present = new Set(tasks.map((t) => t.id));
+  const nodes = tasks.map(taskToPlanNode);
+  const edges: PlanEdge[] = [];
+  for (const task of tasks) {
+    for (const dependsOn of listTaskDependencies(task.id)) {
+      // Only edges whose BOTH endpoints are in the rendered set become view edges; a
+      // dependency on a Task outside this team/filter is silently dropped (it's not a node).
+      if (present.has(dependsOn)) edges.push({ from: taskNodeId(dependsOn), to: taskNodeId(task.id) });
+    }
+  }
+  const now = tasks.reduce((max, t) => Math.max(max, t.updatedAt), 0);
+  return {
+    id: `taskgraph_${teamId}`,
+    threadId: "0",
+    teamId,
+    version: 1,
+    title: "Task graph",
+    objective: `Deliverable tasks for ${teamId}`,
+    nodes,
+    edges: dedupePlanEdges(edges),
+    createdBy: "agent-relay",
+    createdAt: now,
+    updatedAt: now,
+  };
+}