@teamscala/service-boot 0.23.284

package/src/fn-routers/task-sync-router.ts

@@ -0,0 +1,1036 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * CLI-AGNOSTIC task-sync CORE — the bridge between a lane's native task list
+ * (Claude Code TodoWrite, OpenCode todowrite, future CLIs) and the `work_items`
+ * table, which is the single source of truth for "what work does this lane
+ * have." Detailed contract + the per-CLI adapter split: apps/agent-fleet.md
+ * (task-sync section).
+ *
+ * Design (operator requirement): work_items is the source; each CLI's task list
+ * is a WRITE-THROUGH PROJECTION, never a peer. One source + write-through
+ * projection cannot diverge by construction — no two-way sync, no conflict
+ * resolution. The lane↔task binding is SYMMETRIC: a lane is a lane whether the
+ * pane is an orchestrator or a supervised agent (both have tasks).
+ *
+ * Mapping: an operator request = a kind='task' work_item; the lane's todo items
+ * = kind='subtask' rows under it via parent_id. The task carries the lane
+ * identity in kind_data.lane = { pane, session, cli_kind, role } so any surface
+ * (fleet UI, another lane) can resolve "who owns this work" and push changes
+ * back. Binding is by pane identity (the stable $TMUX_PANE), not by fleet run —
+ * so it works before/without the fleet_agent_runs.work_item_id join (that column
+ * is a UI convenience for the unified lane+task+subtask view, not a dependency).
+ *
+ * These procedures are the ONLY CLI-agnostic surface an adapter calls:
+ *   bindLane           — bind (create-or-confirm) a lane's task. SessionStart.
+ *   upsertFromTaskList — write a lane's current task list through to subtasks (AGENT→DB leg, OpenCode whole-list).
+ *   upsertFromTaskHook — apply a per-item Claude Code PostToolUse:TaskCreate/Update/Delete (AGENT→DB leg, Claude per-item).
+ *   readTaskList       — read a lane's current subtasks as a normalized list (DB→AGENT backstop).
+ *   applyExternalChange — record an out-of-band subtask change + notify the owning lane (DB→AGENT realtime leg).
+ * A CLI with no native task surface (Codex today — upstream_issue openai-codex-2966)
+ * has NO adapter: it degrades to work_items-only. The work is still tracked and
+ * visible in the projects UI; the lane simply has no live projection. That is a
+ * legitimate end state, not a gap to paper over with a fake adapter.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { recordEvent } from "@teamscala/event-log/record-event";
+import { getPlatformOrgId } from "@teamscala/db/registry/platform";
+import { authed, type Context } from "./auth-router.ts";
+import { notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
+
+/** A lane's native task-list item, normalized. Every CLI adapter maps to this. */
+export interface TaskListItem {
+	content: string;
+	status: "pending" | "in_progress" | "completed";
+	/** CLI-native stable id when the CLI provides one (TodoWrite has none; opencode todo row id). */
+	mark?: string;
+}
+
+/** Who a lane IS — symmetric across orchestrator/agent roles and across CLIs. */
+export interface LaneIdentity {
+	/** "tmux:%42" — authoritative pane identity ($TMUX_PANE). */
+	pane: string;
+	session?: string;
+	/** pane-inventory inferCliKind: claude-code | opencode | codex | unknown. */
+	cli_kind?: string;
+	/** agent | orchestrator — both have tasks; the model does not assume a supervised agent. */
+	role?: string;
+	/**
+	 * Optional. work_items.organisation_id is NOT NULL; when the caller omits it
+	 * (auto-bind at SessionStart — an adopted or channel-dispatched lane has no
+	 * client org), bindLane defaults to the platform org via resolveBindOrg.
+	 */
+	organisation_id?: string;
+}
+
+interface WorkItem {
+	id: string;
+	kind: string;
+	parent_id: string | null;
+	organisation_id: string;
+	title: string;
+	status: string | null;
+	position: string | null;
+	completed: boolean | null;
+	kind_data: Record<string, unknown>;
+}
+
+type Prisma = {
+	work_items: {
+		findFirst: (a: unknown) => Promise<WorkItem | null>;
+		findMany: (a: unknown) => Promise<WorkItem[]>;
+		create: (a: unknown) => Promise<WorkItem>;
+		update: (a: unknown) => Promise<WorkItem>;
+		deleteMany: (a: unknown) => Promise<{ count: number }>;
+	};
+};
+
+/**
+ * A dispatched run already points at its fleet_tasks row. Task-sync may fill
+ * the convenience join for an adopted lane, but must never replace that
+ * dispatch identity with the lane's work_items projection id.
+ */
+export function untrackedRunForPane(pane: string) {
+	return {
+		pane,
+		state: { not: "closed" },
+		tracked_task_id: null,
+	};
+}
+
+// TodoWrite-style status (the normalized form) → work_items.status (DB enum).
+// The DB enum uses a hyphen for the active state ("in-progress"); see
+// COLUMN_ENUMS["work_items.status"] in db-validation.
+export const STATUS_TO_WORK_ITEM: Record<TaskListItem["status"], string> = {
+	pending: "todo",
+	in_progress: "in-progress",
+	completed: "done",
+};
+// work_items.status → normalized. Unknown/internal statuses collapse to pending.
+const WORK_ITEM_TO_STATUS: Record<string, TaskListItem["status"]> = {
+	todo: "pending",
+	"in-progress": "in_progress",
+	active: "in_progress",
+	done: "completed",
+	completed: "completed",
+};
+
+export function normalizeStatus(s: string | null): TaskListItem["status"] {
+	return (s && WORK_ITEM_TO_STATUS[s]) || "pending";
+}
+
+/**
+ * Resolve the org a lane's task is created under. Explicit when the lane knows
+ * its org (a dispatched fleet lane carries one); defaults to the platform org
+ * otherwise — an adopted or channel-dispatched pane has no client org, and the
+ * platform org is the home for fleet/internal lane tasks (where the operator's
+ * PM view reads), so auto-bind at SessionStart seeds the task there.
+ */
+export function resolveBindOrg(explicit?: string): string {
+	return explicit ?? getPlatformOrgId();
+}
+
+/**
+ * Record a task-sync hook DISCARD to event_log so it is observable + queryable,
+ * not silently swallowed by the hook command's `>/dev/null 2>&1 || true`. The
+ * endpoint records it server-side regardless of what the hook does with stdout.
+ * Fire-and-forget per event-log-is-the-only-durable-event-log. The headline
+ * discard is "no-task-bound" (lane has no bound parent task — exactly the gap
+ * that SessionStart auto-bind closes; once binding is automatic this becomes a
+ * rare safety signal rather than the default outcome).
+ */
+export function recordTaskSyncDiscard(
+	reason: string,
+	pane: string | null,
+	extra: Record<string, unknown> = {},
+): void {
+	recordEvent({
+		kind: "tasksync.hook.discarded",
+		payload: { reason, pane: pane ?? null, ...extra },
+	});
+}
+
+/**
+ * Record a discard AND return the soft {applied:false} body in one step — every
+ * no-op path in upsertFromTaskHook goes through here so none can silently drop
+ * an event. The returned shape matches the prior `{applied:false, reason,...}`.
+ */
+export function discardApplied(
+	reason: string,
+	pane: string | null,
+	extra: Record<string, unknown> = {},
+): { applied: false; reason: string } & Record<string, unknown> {
+	recordTaskSyncDiscard(reason, pane, extra);
+	return { applied: false as const, reason, ...extra };
+}
+
+/**
+ * The lane's human work name, read from its live fleet run (slot_name carries the
+ * tmux window label per lanes-named-by-the-spawner). Returns null when no run
+ * carries this pane yet — adoption and bind race at SessionStart, and a missing
+ * name must not block the bind. Feature-detected like the run-link below, because
+ * fleet_agent_runs lives only in the fleet service's schema.
+ */
+async function resolveLaneWorkName(prisma: Prisma, pane: string): Promise<string | null> {
+	try {
+		const runs = (
+			prisma as unknown as {
+				fleet_agent_runs?: {
+					findFirst: (a: unknown) => Promise<{ slot_name?: string | null } | null>;
+				};
+			}
+		).fleet_agent_runs;
+		if (!runs?.findFirst) return null;
+		const run = await runs.findFirst({
+			where: { pane, state: { not: "closed" } },
+			select: { slot_name: true },
+		});
+		const name = run?.slot_name?.trim();
+		return name ? name : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve a lane's CLI-native session id from its live run row by pane. Used by
+ * the task-event handlers (upsertFromTaskHook) whose payloads lack session_id —
+ * the run row's opencode_session_id IS the same CLI-native id the bind stamped
+ * on kind_data.lane.session, so this recovers it for session-keyed matching.
+ * Feature-detected (fleet_agent_runs lives only in the fleet service's schema).
+ */
+async function resolveSessionFromPane(prisma: Prisma, pane: string): Promise<string | null> {
+	try {
+		const runs = (
+			prisma as unknown as {
+				fleet_agent_runs?: {
+					findFirst: (a: unknown) => Promise<{ opencode_session_id?: string | null } | null>;
+				};
+			}
+		).fleet_agent_runs;
+		if (!runs?.findFirst) return null;
+		const run = await runs.findFirst({
+			where: { pane, state: { not: "closed" } },
+			select: { opencode_session_id: true },
+		});
+		return run?.opencode_session_id ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/** Resolve the task a lane owns, by SESSION IDENTITY (kind_data.lane.session).
+ *
+ * The CLI-native session id is the durable, unique-per-session key (Claude
+ * Code's UUIDv7 = transcript filename; OpenCode's ses-prefixed id). A pane id
+ * is NOT the key — it outlives the CLI session, so a fresh session in the same
+ * pane would inherit the prior session's tasks (the exact bug this re-keys).
+ * The pane stays on kind_data.lane.pane as a diagnostic field only. */
+/**
+ * The lane's parent task, CREATING the binding when it does not exist yet.
+ *
+ * Every lane must be able to comply with `lane-labels-and-task-lists` — operator
+ * ruling 2026-07-27: "ALL lanes can comply, there is no reason why a tab cant
+ * comply." The task hooks previously resolved the parent and, finding none,
+ * DISCARDED the lane's task ("no-task-bound"). A lane whose SessionStart bindLane
+ * never ran, or ran while the endpoint was failing, therefore lost every task it
+ * created, silently, forever — it was told to keep a task list and structurally
+ * could not. Measured 2026-07-27: live active lanes with no binding at all, each
+ * throwing away its own list.
+ *
+ * Binding on demand removes the failure mode instead of reporting it: the first
+ * task a lane records creates the parent it needs. SessionStart binding still
+ * runs and is still preferred (it names the task from the lane's work name); this
+ * is the backstop that makes the discard impossible.
+ *
+ * The create races SessionStart and a sibling hook exactly as bindLane does, so
+ * it loses the race the same way — re-read and carry on, never surface an error
+ * for a row that now exists.
+ */
+async function ensureLaneTask(
+	prisma: Prisma,
+	session: string,
+	pane: string | null,
+): Promise<WorkItem | null> {
+	const existing = await resolveLaneTask(prisma, session);
+	if (existing) return existing;
+	const lane: LaneIdentity = { pane: pane ?? "", session, cli_kind: "claude-code", role: "agent" };
+	try {
+		return await prisma.work_items.create({
+			data: {
+				kind: "task",
+				parent_id: null,
+				organisation_id: resolveBindOrg(),
+				title: (pane ? await resolveLaneWorkName(prisma, pane) : null) ?? "Lane",
+				status: "active",
+				kind_data: { lane },
+			},
+		});
+	} catch {
+		return resolveLaneTask(prisma, session);
+	}
+}
+
+async function resolveLaneTask(prisma: Prisma, session: string): Promise<WorkItem | null> {
+	return prisma.work_items.findFirst({
+		where: {
+			kind: "task",
+			status: "active",
+			kind_data: { path: ["lane", "session"], equals: session },
+		},
+		// Deterministic by oldest. An unordered findFirst returns whichever row
+		// Postgres happens to hand back, so with two parents for one lane (the
+		// bindLane race, below) one turn wrote the lane's todos under parent A
+		// and the next read parent B and found nothing — the lane's task list
+		// appeared to empty itself, and the watchdog accused lanes that were
+		// holding a populated list. Migration 109 makes the duplicate
+		// unwritable; this makes the read stable regardless.
+		orderBy: { created_at: "asc" },
+	});
+}
+
+/** Match key for a subtask: stable mark when the CLI provides one, else content, else title. Uses || (not ??) so an empty-string content (passed for existing rows that key by title) falls through. */
+/**
+ * Which lifecycle leg a Claude task-hook payload represents.
+ *
+ * The dedicated events `TaskCreated` and `TaskCompleted` BOTH carry
+ * `task_subject`, so "has a subject" cannot distinguish them — a completion
+ * classified as a creation mints a duplicate subtask instead of closing one,
+ * which is precisely the "list only grows, nothing ever completes" symptom
+ * (`task-projection-converges`). `hook_event_name` is a common field on every
+ * hook event and is the only reliable discriminator, so the decision is made
+ * here, once, rather than by branch ordering in the handler.
+ */
+/**
+ * Markers that can only appear in a task subject when the CLI's tool-call text
+ * leaked into the field. `</subject>` is the closing tag of the parameter
+ * itself, and `<parameter name=` is the START of the NEXT parameter — either
+ * one means the extraction ran past the end of the value it was reading.
+ */
+const SUBJECT_LEAK_MARKERS = ["</subject>", "<parameter name=", "</antml"];
+
+/**
+ * Trim a task subject at the first tool-call marker.
+ *
+ * A subject arriving as `Cut judge false positives</subject>\n<parameter
+ * name="description">Live gate blocks ~half...` is not a title with odd
+ * punctuation — it is the raw tool call, and it renders on the dashboard as a
+ * wall of XML where the operator expects a task name (observed live 2026-07-25,
+ * 3 rows). The malformation happens upstream in the CLI's hook payload, which
+ * this service does not control, so the defence belongs at the WRITE boundary:
+ * `work_items` is the single source of truth for every surface, and once a
+ * corrupted title lands there every reader shows it.
+ *
+ * Truncating rather than rejecting is deliberate: the text BEFORE the marker is
+ * the real subject and is worth keeping. Dropping the row instead would lose a
+ * task the lane genuinely created.
+ */
+export function sanitizeTaskSubject(raw: string): string {
+	let out = raw;
+	for (const marker of SUBJECT_LEAK_MARKERS) {
+		const i = out.indexOf(marker);
+		if (i !== -1) out = out.slice(0, i);
+	}
+	return out.trim();
+}
+
+export function classifyTaskHookEvent(evt: {
+	hook_event_name?: unknown;
+	task_subject?: unknown;
+}): "completed" | "created" | "tool" {
+	if (evt.hook_event_name === "TaskCompleted") return "completed";
+	if (typeof evt.task_subject === "string") return "created";
+	return "tool";
+}
+
+export function subtaskKey(item: { mark?: string; content: string; title: string }): string {
+	return item.mark || item.content || item.title;
+}
+
+/**
+ * Pure decision for a TaskUpdate/TaskDelete: which existing subtask does this
+ * event address, and what should happen when none does. Extracted for the same
+ * reason planReconcile was — the handler should only EXECUTE, so the matching
+ * rule is unit-testable.
+ *
+ * Three resolutions:
+ *  - `update` — matched by mark, or (mark absent/unstamped) by exact title.
+ *  - `heal`   — nothing matched but the event carries a subject, so the row can
+ *               be reconstructed. Covers a TaskCreate that silently produced no
+ *               subtask, which previously orphaned the task forever.
+ *  - `discard` — nothing matched and there is no subject to rebuild a title from.
+ *
+ * Measured 2026-07-28: marks "1" and "3" were stamped for one lane while mark
+ * "2" was never written at all, and every later update for it was dropped as
+ * `no-matching-subtask` — 26 of 30 tasksync discards in six hours, across seven
+ * distinct lane sessions, were that one reason.
+ */
+export function resolveTaskUpdateTarget(
+	existing: Array<{ id: string; title: string; kind_data?: Record<string, unknown> | null }>,
+	evt: { taskId: string; subject?: string },
+): { op: "update"; id: string } | { op: "heal"; title: string } | { op: "discard" } {
+	const byMark = existing.find(
+		(s) =>
+			evt.taskId &&
+			(s.kind_data as { task_sync?: { mark?: string } } | null)?.task_sync?.mark === evt.taskId,
+	);
+	if (byMark) return { op: "update", id: byMark.id };
+	const subject = (evt.subject ?? "").trim();
+	if (subject) {
+		const byTitle = existing.find((s) => s.title === subject);
+		if (byTitle) return { op: "update", id: byTitle.id };
+		return { op: "heal", title: subject };
+	}
+	return { op: "discard" };
+}
+
+/**
+ * Pure reconciliation plan: given the lane's EXISTING subtasks and its INCOMING
+ * (current) task list, compute the create/update/delete ops that make the
+ * subtask set match the list — WITHOUT touching prisma. Extracted so the
+ * matching/status/positioning logic is unit-testable (the handler only executes
+ * the plan). Matching is by stable mark when the CLI provides one, else by
+ * content. Position follows incoming index, so a reorder is an update.
+ */
+export interface ReconcilePlan {
+	toCreate: Array<{
+		content: string;
+		status: string;
+		completed: boolean;
+		position: string;
+		kind_data: Record<string, unknown>;
+	}>;
+	toUpdate: Array<{
+		id: string;
+		content: string;
+		status: string;
+		completed: boolean;
+		position: string;
+		kind_data: Record<string, unknown>;
+	}>;
+	toDelete: string[];
+}
+
+export function planReconcile(
+	existing: WorkItem[],
+	incoming: TaskListItem[],
+	source?: string,
+): ReconcilePlan {
+	const byKey = new Map<string, WorkItem>();
+	for (const s of existing) {
+		const mark = (s.kind_data?.task_sync as { mark?: string } | undefined)?.mark;
+		byKey.set(subtaskKey({ mark, content: "", title: s.title }), s);
+	}
+	const toCreate: ReconcilePlan["toCreate"] = [];
+	const toUpdate: ReconcilePlan["toUpdate"] = [];
+	const seen = new Set<string>();
+	for (let i = 0; i < incoming.length; i++) {
+		const item = incoming[i];
+		const content = (item.content ?? "").trim();
+		if (!content) continue;
+		const key = subtaskKey({ mark: item.mark, content, title: content });
+		const status = STATUS_TO_WORK_ITEM[item.status] ?? "todo";
+		const completed = item.status === "completed";
+		const position = String(i);
+		const taskSync = { task_sync: { mark: item.mark, source } };
+		const match = byKey.get(key);
+		if (match) {
+			seen.add(match.id);
+			const changed =
+				match.title !== content ||
+				match.status !== status ||
+				(match.completed ?? false) !== completed ||
+				match.position !== position;
+			if (changed) {
+				toUpdate.push({
+					id: match.id,
+					content,
+					status,
+					completed,
+					position,
+					kind_data: { ...match.kind_data, ...taskSync },
+				});
+			}
+		} else {
+			toCreate.push({ content, status, completed, position, kind_data: taskSync });
+		}
+	}
+	const toDelete = existing.filter((s) => !seen.has(s.id)).map((s) => s.id);
+	return { toCreate, toUpdate, toDelete };
+}
+
+/**
+ * Execute a reconcile against prisma for a lane's task — the shared write path
+ * for upsertFromTaskList (normalized input) and upsertFromTodoWriteHook (raw
+ * Claude hook event). Throws an Error ("No task bound to pane …") when the lane
+ * has no task; callers map that to their preferred response (ORPC NOT_FOUND or a
+ * soft {synced:0}). Does NOT dispatch a change notification — the lane that
+ * authored the list already has it.
+ */
+async function reconcileTaskList(
+	prisma: Prisma,
+	laneSession: string,
+	list: TaskListItem[],
+	source?: string,
+): Promise<{ task_id: string; created: number; updated: number; deleted: number; total: number }> {
+	const task = await resolveLaneTask(prisma, laneSession);
+	if (!task) {
+		throw new Error(`No task bound to session ${laneSession}. Call taskSync.bindLane first (SessionStart adapter).`);
+	}
+	const existing = await prisma.work_items.findMany({
+		where: { parent_id: task.id, kind: "subtask" },
+	});
+	const plan = planReconcile(existing, list, source);
+	for (const c of plan.toCreate) {
+		await prisma.work_items.create({
+			data: {
+				kind: "subtask",
+				parent_id: task.id,
+				organisation_id: task.organisation_id,
+				title: c.content,
+				status: c.status,
+				completed: c.completed,
+				position: c.position,
+				kind_data: c.kind_data,
+			},
+		});
+	}
+	for (const u of plan.toUpdate) {
+		await prisma.work_items.update({
+			where: { id: u.id },
+			data: { title: u.content, status: u.status, completed: u.completed, position: u.position, kind_data: u.kind_data },
+		});
+	}
+	let deleted = 0;
+	if (plan.toDelete.length > 0) {
+		const res = await prisma.work_items.deleteMany({ where: { id: { in: plan.toDelete } } });
+		deleted = res.count;
+	}
+	return { task_id: task.id, created: plan.toCreate.length, updated: plan.toUpdate.length, deleted, total: list.length };
+}
+
+export const taskSyncRouter = {
+	/**
+	 * Bind (create-or-confirm) the task a lane owns. Called from a SessionStart
+	 * adapter so the lane has a durable task row before its first todo write.
+	 * Idempotent: re-binding updates the identity (role/cli_kind can change) but
+	 * never orphans existing subtasks. After binding, links the lane's
+	 * fleet_agent_runs row (matched by pane) to the task via tracked_task_id —
+	 * the join the operator's lane-labels monitor + the unified fleet view read.
+	 */
+	bindLane: authed.handler(async ({ input, context }) => {
+		const ctx = context as Context;
+		const prisma = ctx.prisma as Prisma;
+		const log = getAppLogger();
+		// The SessionStart hook sends the pane + the CLI's native session id.
+		// SESSION is the match key (kind_data.lane.session) — it is unique per
+		// CLI session and re-minted each session, so a fresh session cannot find
+		// the prior session's tasks. PANE stays as a diagnostic field only
+		// (kind_data.lane.pane) — it outlives the CLI session, so matching on it
+		// is exactly the inheritance bug this re-keys. Without an .input()
+		// valibot schema ORPC does not parse the JSON body into `input`, so the
+		// headers (x-lane-session, x-lane-pane) are the reliable transport.
+		const raw = (input ?? {}) as {
+			lane?: Partial<LaneIdentity>;
+			title?: string;
+			parent_id?: string;
+		};
+		const headerPane = ctx.headers?.get("x-lane-pane") ?? null;
+		const pane = raw.lane?.pane ?? headerPane;
+		const headerSession = ctx.headers?.get("x-lane-session") ?? null;
+		const session = raw.lane?.session ?? headerSession;
+		if (!session) {
+			const { ORPCError } = await import("@orpc/server");
+			throw new ORPCError("BAD_REQUEST", {
+				message: "bindLane requires lane.session (the CLI's native session id)",
+			});
+		}
+		const lane: LaneIdentity = {
+			pane,
+			session,
+			cli_kind: raw.lane?.cli_kind ?? "claude-code",
+			role: raw.lane?.role ?? "agent",
+			organisation_id: raw.lane?.organisation_id,
+		};
+		// organisation_id optional: defaults to the platform org (resolveBindOrg)
+		// so auto-bind at SessionStart works with no client org on the lane.
+		const organisation_id = resolveBindOrg(lane.organisation_id);
+		const existing = await resolveLaneTask(prisma, session);
+		// A human-readable title, resolved from the lane's OWN work name. NEVER a
+		// pane id in user-facing text (agent-not-identity): `%9` is a machine
+		// address, it renumbers, and it tells the operator nothing about what the
+		// lane is doing. The run's slot_name IS the work name
+		// (lanes-named-by-the-spawner); fall back to a bare "Lane" rather than
+		// leak the pane id when no run resolves a name.
+		const laneTitle = raw.title ?? (await resolveLaneWorkName(prisma, pane)) ?? "Lane";
+		let taskId: string;
+		let created: boolean;
+		if (existing) {
+			const kindData = { ...existing.kind_data, lane };
+			const updated = await prisma.work_items.update({
+				where: { id: existing.id },
+				data: { kind_data: kindData },
+			});
+			taskId = updated.id;
+			created = false;
+			log.info("[task-sync] bindLane: re-bound existing task", { taskId, session });
+		} else {
+			// Read-then-create is a race: SessionStart and the lane's first
+			// TaskCreate arrive seconds apart, both read nothing, and both create.
+			// Measured 2026-07-25: 9 lanes with two active parents each, every twin
+			// 2-3 seconds behind its sibling. Migration 109's partial unique index
+			// makes the second write fail instead of succeed, and losing the race
+			// is not an error — the winner's row is exactly what this call wanted,
+			// so re-read it and carry on.
+			let row: WorkItem;
+			try {
+				row = await prisma.work_items.create({
+					data: {
+						kind: "task",
+						parent_id: raw.parent_id ?? null,
+						organisation_id,
+						title: laneTitle,
+						status: "active",
+						kind_data: { lane },
+					},
+				});
+				log.info("[task-sync] bindLane: created task", { taskId: row.id, session });
+			} catch (err) {
+				const winner = await resolveLaneTask(prisma, session);
+				if (!winner) throw err;
+				row = winner;
+				log.info("[task-sync] bindLane: lost the create race, using existing task", {
+					taskId: row.id,
+					session,
+				});
+			}
+			taskId = row.id;
+			created = true;
+		}
+		// Link the fleet run carrying this pane to the bound task — sets
+		// fleet_agent_runs.tracked_task_id. Best-effort by design: fleet_agent_runs
+		// is only in the fleet service's schema, so feature-detect the model; and a
+		// run not yet carrying its pane (adoption race at SessionStart — adoption
+		// fires first, but its pane resolve can come up empty on a tmux hiccup) is
+		// simply not matched, converging on re-bind / next adoption. The work_items
+		// task is the source of truth; this column is the UI convenience join.
+		try {
+			const runs = (
+				prisma as unknown as {
+					fleet_agent_runs?: {
+						updateMany: (a: unknown) => Promise<{ count: number }>;
+					};
+				}
+			).fleet_agent_runs;
+			if (runs?.updateMany) {
+				// STEAL before CLAIM. A task is tracked by at most one LIVE run — the
+				// partial unique index fleet_agent_runs_one_active_run_per_task
+				// (UNIQUE(tracked_task_id) WHERE state IN active/committing/waiting)
+				// enforces it. Assigning tracked_task_id without first releasing it
+				// from any OTHER run holding it leaves two runs sharing the task, and
+				// the next state→active transition on either one (upsertLaneRun's
+				// UPDATE) violates the index → P2002 → the lane-event 500s and the
+				// run-link join is lost. The common trigger is re-adoption: a lane
+				// moves to a new pane, bindLane claims the task for the new run while
+				// the OLD pane's run still holds it. A task is session-scoped, so every
+				// run holding this taskId is this lane's own (or a stale duplicate) —
+				// releasing from all non-closed runs is correct, then only this lane's
+				// untracked run re-claims it.
+				await runs.updateMany({
+					where: { tracked_task_id: taskId, state: { not: "closed" } },
+					data: { tracked_task_id: null },
+				});
+				await runs.updateMany({
+					where: untrackedRunForPane(pane),
+					data: { tracked_task_id: taskId },
+				});
+			}
+		} catch (err) {
+			log.warn("[task-sync] bindLane: run-link by pane failed", {
+				pane,
+				taskId,
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+		return { task_id: taskId, created };
+	}),
+
+	/**
+	 * AGENT→DB leg. Write a lane's CURRENT task list through to subtasks. The
+	 * list is authoritative for this lane (it's what the CLI just rendered), so
+	 * this is a full reconcile: create/update/delete to match. Matching is by
+	 * stable mark when the CLI provides one, else by content. Does NOT dispatch
+	 * a change notification — the lane that authored the list already has it.
+	 */
+	upsertFromTaskList: authed.handler(async ({ input, context }) => {
+		const body = input as { lane_session: string; task_list: TaskListItem[]; source?: string };
+		const prisma = (context as Context).prisma as Prisma;
+		const log = getAppLogger();
+		const session = body?.lane_session;
+		const list = Array.isArray(body?.task_list) ? body.task_list : [];
+		if (!session) {
+			const { ORPCError } = await import("@orpc/server");
+			throw new ORPCError("BAD_REQUEST", { message: "upsertFromTaskList requires lane_session" });
+		}
+		try {
+			const res = await reconcileTaskList(prisma, session, list, body.source);
+			log.info("[task-sync] upsertFromTaskList reconciled", { session, ...res });
+			return res;
+		} catch (err) {
+			if (err instanceof Error && err.message.includes("No task bound")) {
+				const { ORPCError } = await import("@orpc/server");
+				throw new ORPCError("NOT_FOUND", { message: err.message });
+			}
+			throw err;
+		}
+	}),
+	/**
+	 * Claude Code PostToolUse:TaskCreate/TaskUpdate hook entry. Claude Code's
+	 * todo tool is the per-item Task* family (TaskCreate/TaskUpdate) — TodoWrite
+	 * was REMOVED in recent Claude Code; the hook matcher keys on
+	 * TaskCreate/TaskUpdate, never TodoWrite. The hook command posts the RAW hook
+	 * event (stdin) + an x-lane-pane header (tmux:$TMUX_PANE). Fired as a
+	 * PostToolUse:TaskCreate/Update hook (NOT a "TaskCreated" event — that is
+	 * not a real Claude Code hook event + never fired); this procedure
+	 * applies the per-item change (TaskCreate → new subtask keyed by the harness
+	 * task id; TaskUpdate → status/title flip on the matching subtask). Server-
+	 * side extraction keeps the hook command a trivial jq|curl. Accepts the event
+	 * raw (input.tool_name) OR oRPC-enveloped (input.json.tool_name). Session-
+	 * less: fn.taskSync is page-gate-exempt; localhost pane shell authenticates
+	 * as super-admin via resolveUser. Soft-returns on any no-op (never throws).
+	 */
+	upsertFromTaskHook: authed.handler(async ({ input, context }) => {
+		const raw = (input ?? {}) as {
+			tool_name?: string;
+			tool_input?: Record<string, unknown>;
+			tool_response?: Record<string, unknown>;
+			json?: { tool_name?: string; tool_input?: Record<string, unknown>; tool_response?: Record<string, unknown> };
+		};
+		const evt = raw.tool_name ? raw : (raw.json ?? raw);
+		const toolName = typeof evt.tool_name === "string" ? evt.tool_name : "";
+		const toolInput = (evt.tool_input ?? {}) as Record<string, unknown>;
+		const toolResponse = (evt.tool_response ?? {}) as Record<string, unknown>;
+		const headerSession = (context as Context).headers?.get("x-lane-session") ?? null;
+		const headerPane = (context as Context).headers?.get("x-lane-pane") ?? null;
+		const prisma = (context as Context).prisma as Prisma;
+		// TaskCreated/TaskCompleted event payloads do NOT carry session_id (only
+		// SessionStart does), so the task hooks cannot populate x-lane-session —
+		// the extraction in the hook command yields an empty string. Resolve the
+		// session from the lane's run row by pane instead: the bind (at
+		// session_start) already stamped kind_data.lane.session, and the run row's
+		// opencode_session_id is the same CLI-native id. This keeps matching
+		// session-keyed (resolveLaneTask still filters kind_data.lane.session)
+		// without requiring every task-event payload to carry the session id.
+		const session = headerSession || (headerPane ? await resolveSessionFromPane(prisma, headerPane) : null);
+		if (!session) return discardApplied("no-session", null);
+		const log = getAppLogger();
+		// Claude Code fires the dedicated `TaskCreated` EVENT for the Task* tools,
+		// NOT PostToolUse — a PostToolUse:TaskCreate matcher never fired (the prior
+		// hook shape silently produced zero subtasks, so Claude lanes showed an
+		// empty task panel). The TaskCreated payload carries task_subject + task_id
+		// on the event object (evt — already unwrapped from the {json:...} wire
+		// envelope by the raw.json ?? raw fallback above). Handle it before the
+		// toolName guard so the dedicated event path creates the subtask.
+		const createdEvt = evt as {
+			task_subject?: unknown;
+			task_id?: unknown;
+			hook_event_name?: unknown;
+		};
+		// TaskCompleted BEFORE the TaskCreated branch. Both dedicated events carry
+		// `task_subject`, so the subject-presence test below cannot tell them apart
+		// — an unguarded TaskCompleted would fall into the create path and mint a
+		// DUPLICATE subtask instead of completing the existing one, which reads as
+		// "the list only ever grows and nothing is ever done"
+		// (`task-projection-converges`). `hook_event_name` is a common input field
+		// on every hook event, so it is the reliable discriminator.
+		const leg = classifyTaskHookEvent(createdEvt);
+		if (leg === "completed") {
+			const task3 = await resolveLaneTask(prisma, session);
+			if (!task3) return discardApplied("no-task-bound", session, { source: "TaskCompleted" });
+			const completedId = String(createdEvt.task_id ?? "");
+			const subject =
+				typeof createdEvt.task_subject === "string"
+					? sanitizeTaskSubject(createdEvt.task_subject)
+					: "";
+			// Match on the mark stamped at creation; fall back to the title so a
+			// subtask created before marks were recorded still closes.
+			const siblings = await prisma.work_items.findMany({
+				where: { parent_id: task3.id, kind: "subtask" },
+			});
+			const target =
+				siblings.find(
+					(s) =>
+						completedId &&
+						(s.kind_data as { task_sync?: { mark?: string } } | null)?.task_sync?.mark ===
+							completedId,
+				) ?? siblings.find((s) => subject && s.title === subject);
+			if (!target) {
+				return discardApplied("no-matching-subtask", session, {
+					source: "TaskCompleted",
+					taskId: completedId,
+				});
+			}
+			await prisma.work_items.update({
+				where: { id: target.id },
+				data: { status: "done", completed: true },
+			});
+			log.info("[task-sync] TaskCompleted: closed subtask", {
+				session,
+				taskId: completedId,
+				subject,
+			});
+			return { applied: true, op: "complete", taskId: completedId };
+		}
+		if (leg === "created") {
+			// Sanitized on BOTH legs: the completion leg matches by title, so a
+			// raw subject here and a sanitized one at creation would never match.
+			const subject = sanitizeTaskSubject(String(createdEvt.task_subject ?? ""));
+			if (!subject) return discardApplied("no-subject", session, { source: "TaskCreated" });
+			// Bind on demand rather than discard: a lane must always be able to
+			// record the task it was just told to create.
+			const task2 = await ensureLaneTask(prisma, session, headerPane);
+			if (!task2) return discardApplied("no-task-bound", session, { source: "TaskCreated" });
+			const createdId = String(createdEvt.task_id ?? "");
+			const existing = await prisma.work_items.findMany({ where: { parent_id: task2.id, kind: "subtask" } });
+			// IDEMPOTENT on the CLI's own task id. The hook curls with `--retry 2
+			// --retry-connrefused`, so one TaskCreate can arrive twice (observed
+			// 2026-07-25: four tasks each duplicated ~4s apart), and this path used
+			// `existing` only to compute a position — never to check whether the
+			// subtask was already written. A projection that duplicates on retry is
+			// not a projection (task-projection-converges); the operator sees a list
+			// that only grows. Match on the stored mark, falling back to title for
+			// rows written before marks were recorded.
+			const already = existing.find((e) => {
+				const mark = (e.kind_data as { task_sync?: { mark?: string } } | null)?.task_sync?.mark;
+				return createdId && mark ? mark === createdId : e.title === subject;
+			});
+			if (already) {
+				return discardApplied("duplicate-create", session, {
+					source: "TaskCreated",
+					taskId: createdId,
+					subtaskId: already.id,
+				});
+			}
+			try {
+				await prisma.work_items.create({
+					data: {
+						kind: "subtask",
+						parent_id: task2.id,
+						organisation_id: task2.organisation_id,
+						title: subject,
+						status: "todo",
+						completed: false,
+						position: String(existing.length),
+						kind_data: { task_sync: { mark: createdId || undefined, source: "claude-code" } },
+					},
+				});
+			} catch (err) {
+				// P2002 = unique violation on work_items_subtask_task_sync_mark_uniq.
+				// The `already` check above is a READ-THEN-WRITE and therefore loses
+				// a race by construction: two retries of one TaskCreate both read
+				// `existing` before either writes, both see nothing, and both insert.
+				// That is why cleaning duplicates by hand kept "fixing" a class that
+				// came straight back (31 rows cleaned earlier on 2026-07-25, 13 more
+				// by that evening). The index is what makes the second insert
+				// impossible; this catch turns losing the race into the CORRECT
+				// idempotent outcome instead of a 500 back to the hook.
+				if ((err as { code?: string })?.code !== "P2002") throw err;
+				return discardApplied("duplicate-create-race", session, {
+					source: "TaskCreated",
+					taskId: createdId,
+				});
+			}
+			log.info("[task-sync] TaskCreated: created subtask", { session, taskId: createdId, subject });
+			return { applied: true, op: "create", taskId: createdId };
+		}
+		if (toolName !== "TaskCreate" && toolName !== "TaskUpdate" && toolName !== "TaskDelete") {
+			return discardApplied("unhandled-tool", session, { toolName });
+		}
+		const task = await ensureLaneTask(prisma, session, headerPane);
+		if (!task) return discardApplied("no-task-bound", session, { toolName });
+
+		if (toolName === "TaskCreate") {
+			const subject = typeof toolInput.subject === "string" ? toolInput.subject.trim() : "";
+			if (!subject) return discardApplied("no-subject", session, { toolName });
+			const taskResp = toolResponse.task as Record<string, unknown> | undefined;
+			const taskId = String(toolResponse.id ?? toolResponse.taskId ?? taskResp?.id ?? toolInput.taskId ?? "");
+			const existing = await prisma.work_items.findMany({ where: { parent_id: task.id, kind: "subtask" } });
+			await prisma.work_items.create({
+				data: {
+					kind: "subtask",
+					parent_id: task.id,
+					organisation_id: task.organisation_id,
+					title: subject,
+					status: "todo",
+					completed: false,
+					position: String(existing.length),
+					kind_data: { task_sync: { mark: taskId || undefined, source: "claude-code" } },
+				},
+			});
+			log.info("[task-sync] upsertFromTaskHook: created subtask", { session, taskId, subject });
+			return { applied: true, op: "create", taskId };
+		}
+
+		const taskId = String(toolInput.taskId ?? toolInput.id ?? "");
+		if (!taskId) return discardApplied("no-taskId", session, { toolName });
+		// The handler only EXECUTES; the matching rule lives in the pure
+		// resolveTaskUpdateTarget so it is unit-testable (same split as planReconcile).
+		const siblings = await prisma.work_items.findMany({
+			where: { parent_id: task.id, kind: "subtask" },
+		});
+		const subjectRaw = typeof toolInput.subject === "string" ? toolInput.subject : undefined;
+		const decision = resolveTaskUpdateTarget(siblings, { taskId, subject: subjectRaw });
+		if (decision.op === "heal" && toolName === "TaskUpdate") {
+			await prisma.work_items.create({
+				data: {
+					kind: "subtask",
+					parent_id: task.id,
+					organisation_id: task.organisation_id,
+					title: decision.title,
+					status: STATUS_TO_WORK_ITEM[toolInput.status as TaskListItem["status"]] ?? "todo",
+					completed: toolInput.status === "completed",
+					position: String(siblings.length),
+					kind_data: { task_sync: { mark: taskId || undefined, source: "claude-code" } },
+				},
+			});
+			log.warn("[task-sync] TaskUpdate healed a missing subtask", {
+				session,
+				taskId,
+				subject: decision.title,
+			});
+			return { applied: true, op: "create", taskId };
+		}
+		const subtask = decision.op === "update" ? siblings.find((s) => s.id === decision.id) : null;
+		if (!subtask) return discardApplied("no-matching-subtask", session, { taskId });
+		if (toolName === "TaskDelete") {
+			await prisma.work_items.deleteMany({ where: { id: [subtask.id] } });
+			return { applied: true, op: "delete", taskId };
+		}
+		// TaskUpdate
+		const data: {
+			status?: string;
+			completed?: boolean;
+			title?: string;
+			kind_data?: Record<string, unknown>;
+		} = {};
+		const statusRaw = typeof toolInput.status === "string" ? toolInput.status : "";
+		if (statusRaw) {
+			data.status = STATUS_TO_WORK_ITEM[statusRaw as TaskListItem["status"]] ?? "todo";
+			data.completed = statusRaw === "completed";
+		}
+		if (typeof toolInput.subject === "string") data.title = toolInput.subject;
+		// STAMP THE MARK WHEN A ROW IS MATCHED BY TITLE.
+		//
+		// Matching is mark-first, then EXACT TITLE. A row that has never been
+		// stamped can therefore only ever be found by its title — so the moment a
+		// task is RENAMED, neither match succeeds, the event heals into a NEW row,
+		// and the pre-rename row is orphaned at whatever status it held. Forever:
+		// nothing else in the single-event path will ever look at it again.
+		//
+		// Observed 2026-07-28 on this lane — three subtasks stranded at `todo` and
+		// `in-progress` under their OLD titles while the CLI's own list read empty,
+		// which is what made the stop gate refuse a lane that had genuinely
+		// finished. `task-projection-converges` requires the projection to express
+		// every state a task reaches; a row it can no longer address expresses
+		// nothing.
+		//
+		// Stamping here closes the class rather than the instance: the FIRST
+		// title-match a row ever gets makes it mark-addressable, so every later
+		// rename updates it in place. The heal path already stamps on create; this
+		// is the half that was missing, and without it an unmarked row stays
+		// unmarked no matter how many times it is touched.
+		const alreadyMarked =
+			(subtask.kind_data as { task_sync?: { mark?: string } } | null)?.task_sync?.mark;
+		if (taskId && !alreadyMarked) {
+			const priorKindData = (subtask.kind_data ?? {}) as Record<string, unknown>;
+			const priorSync = (priorKindData.task_sync ?? {}) as Record<string, unknown>;
+			data.kind_data = {
+				...priorKindData,
+				task_sync: { ...priorSync, mark: taskId, source: "claude-code" },
+			};
+		}
+		if (Object.keys(data).length === 0) return discardApplied("no-change", session, { taskId });
+		await prisma.work_items.update({ where: { id: subtask.id }, data });
+		log.info("[task-sync] upsertFromTaskHook: updated subtask", { session, taskId, ...data });
+		return { applied: true, op: "update", taskId };
+	}),
+
+	/**
+	 * DB→AGENT backstop read. Returns the lane's current subtasks in the
+	 * normalized shape every CLI adapter maps to its native list. Called by the
+	 * SessionStart/UserPromptSubmit adapters so a pane never opens or continues
+	 * on stale tasks, and by a lane after it receives a "your tasks changed"
+	 * channel notification.
+	 */
+	readTaskList: authed.handler(async ({ input, context }) => {
+		const ctx = context as Context;
+		const prisma = ctx.prisma as Prisma;
+		const body = (input ?? {}) as { lane_session?: string };
+		// Same transport as bindLane/upsertFromTaskHook: the session id arrives
+		// on the x-lane-session header (and body.lane_session as fallback).
+		const session = body.lane_session ?? ctx.headers?.get("x-lane-session") ?? null;
+		if (!session) {
+			const { ORPCError } = await import("@orpc/server");
+			throw new ORPCError("BAD_REQUEST", { message: "readTaskList requires lane_session" });
+		}
+		const task = await resolveLaneTask(prisma, session);
+		if (!task) return { task_id: null, task_title: null, subtasks: [] };
+		const rows = await prisma.work_items.findMany({
+			where: { parent_id: task.id, kind: "subtask" },
+		});
+		rows.sort((a, b) => (a.position ?? "").localeCompare(b.position ?? "", undefined, { numeric: true }));
+		const subtasks: TaskListItem[] = rows.map((r) => ({
+			content: r.title,
+			status: normalizeStatus(r.status),
+			mark: (r.kind_data?.task_sync as { mark?: string } | undefined)?.mark,
+		}));
+		return { task_id: task.id, task_title: task.title, subtasks };
+	}),
+
+	/**
+	 * DB→AGENT realtime leg (explicit dispatch path). Record an out-of-band
+	 * change to a subtask's status (operator toggles it in the projects UI,
+	 * another lane edits a shared task) and notify the OWNING lane's pane that
+	 * its projection is stale. The pane's adapter re-reads (readTaskList) and
+	 * updates its native list. Symmetric counterpart to upsertFromTaskList:
+	 * there the lane is the originator (no self-echo); here the lane is the
+	 * recipient.
+	 *
+	 * COMPLETION STEP (not MVP): this procedure is the explicit trigger. For
+	 * FULL coverage — every work_items subtask write, including the projects
+	 * UI's generated CRUD — a Postgres trigger + LISTEN subscriber on
+	 * scala-channel fires the same publish, so an operator edit reaches the
+	 * lane with no explicit call. Tracked in apps/agent-fleet.md task-sync.
+	 */
+	applyExternalChange: authed.handler(async ({ input, context }) => {
+		const body = input as { task_id: string; subtask_id?: string; status?: TaskListItem["status"] };
+		const prisma = (context as Context).prisma as Prisma;
+		const log = getAppLogger();
+		const { task_id, subtask_id, status } = body ?? {};
+		if (!task_id) {
+			const { ORPCError } = await import("@orpc/server");
+			throw new ORPCError("BAD_REQUEST", { message: "applyExternalChange requires task_id" });
+		}
+		if (subtask_id && status) {
+			await prisma.work_items.update({
+				where: { id: subtask_id },
+				data: { status: STATUS_TO_WORK_ITEM[status], completed: status === "completed" },
+			});
+		}
+		const task = await prisma.work_items.findFirst({ where: { id: task_id } });
+		const lanePane = (task?.kind_data?.lane as { pane?: string } | undefined)?.pane;
+		// Fire-and-forget: a dispatch failure must never block the work_items write.
+		if (lanePane) {
+			notifyLaneOfTaskChange(lanePane, task_id).catch((err) => {
+				log.warn("[task-sync] applyExternalChange: lane notify failed", {
+					taskId: task_id,
+					error: err instanceof Error ? err.message : String(err),
+				});
+			});
+		}
+		return { task_id, lane_pane: lanePane ?? null, notified: !!lanePane };
+	}),
+};