@teamscala/service-boot 0.23.326 → 0.23.327

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

@@ -0,0 +1,1106 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ * @indivisible-unit
+ *
+ * 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";
+import { resolveLaneTask, resolveLaneWorkName } from "./task-sync-lane.ts";
+import { readAssignedBriefHandler } from "./task-sync-brief.ts";
+import { renameLaneTaskHandler } from "./task-sync-rename.ts";
+import {
+	adoptAssignmentTask,
+	bindLaneInput,
+	createBriefTaskHandler,
+	resolveBindAction,
+} from "./task-sync-assign.ts";
+import * as v from "valibot";
+import {
+	STATUS_TO_WORK_ITEM,
+	normalizeStatus,
+	resolveProjectedStatus,
+	subtaskKey,
+	resolveTaskUpdateTarget,
+	planReconcile,
+	type ReconcilePlan,
+} from "./task-sync-projection.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;
+}
+
+/**
+ * Input contract for upsertFromTaskList. oRPC does NOT parse the JSON body into
+ * `input` for a schema-less procedure (see the bindLane comment in this file) —
+ * so without an explicit `.input()` schema, `input.lane_session` is ALWAYS
+ * undefined and the procedure throws "requires lane_session" unconditionally.
+ * Measured 2026-07-29: every pi/opencode whole-list `task_list` publish 400'd
+ * for exactly this reason (the per-item upsertFromTaskHook path worked because
+ * it unwraps `raw.json ?? raw`). Declaring the schema is the documented remedy
+ * and the pattern every other `authed.input(...)` procedure in service-boot
+ * already follows. The pi adapter (scala-hooks.ts syncTaskList) already sends
+ * `{ lane_session, task_list, source }` — it was always valid; the server never
+ * read it.
+ */
+export const upsertFromTaskListInput = v.object({
+	lane_session: v.string(),
+	task_list: v.array(
+		v.object({
+			content: v.string(),
+			status: v.picklist(["pending", "in_progress", "completed"]),
+			mark: v.optional(v.string()),
+		}),
+	),
+	source: v.optional(v.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;
+}
+
+export 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>;
+}
+
+export 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 }>;
+	};
+	// `comments` is a universal shared model (owned by @teamgbg/db), so every
+	// service with the db client carries it. Declared here rather than
+	// feature-detected because, unlike fleet_agent_runs (fleet-service-only), it
+	// is part of the shared client every consumer installs.
+	comments?: {
+		findFirst: (a: unknown) => Promise<CommentRow | null>;
+	};
+};
+
+/** A `comments` row — only the fields readAssignedBrief touches. */
+export interface CommentRow {
+	content: string;
+	created_at: Date;
+}
+
+/**
+ * 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,
+	};
+}
+
+
+/**
+ * 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.
+ */
+
+/**
+ * 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;
+	// The lane's real work name — its fleet run's slot_name
+	// (lanes-named-by-the-spawner). resolveLaneWorkName reads the most recent run
+	// for the pane regardless of state, so a lane whose run closed still resolves.
+	// A task with NO resolvable name is NOT created: writing the generic "Lane"
+	// sentinel is exactly the unmakeable state this backstop must refuse (a row
+	// titled "Lane" tells the operator nothing and reads as spawn debris).
+	// Return null — reconcileTaskList throws, the TaskCreated hook discards
+	// (observably), so the lane never silently produces a "Lane" row.
+	const name = pane ? await resolveLaneWorkName(prisma, pane) : null;
+	if (!name || name.trim().toLowerCase() === "lane") return null;
+	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: name,
+				status: "active",
+				// assignee_id on every bind path (see bindLane): without it a bound
+				// task reads as unowned to an orchestrator steering by assignee_id.
+				assignee_id: session,
+				kind_data: { lane },
+			},
+		});
+	} catch {
+		return resolveLaneTask(prisma, session);
+	}
+}
+
+
+/** 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";
+}
+
+
+/**
+ * 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,
+	pane?: string | null,
+): Promise<{ task_id: string; created: number; updated: number; deleted: number; total: number }> {
+	// BIND ON DEMAND — this path used to `resolveLaneTask` and THROW, which is the
+	// exact failure `ensureLaneTask` was written to make impossible (see its
+	// comment above, and the operator ruling it cites: "ALL lanes can comply,
+	// there is no reason why a tab cant comply"). The backstop existed and this
+	// caller did not use it, so a lane whose SessionStart bindLane never ran — or
+	// ran while the endpoint was failing — could never sync a task list again.
+	// Not degraded: permanently, with a 404 on every attempt and no path to
+	// self-recover.
+	//
+	// Measured 2026-07-30: a live lane reported ~9 consecutive failures over
+	// hours and correctly diagnosed its own lane-compliance flag as a false
+	// positive it was structurally unable to clear. The gate was telling it to
+	// keep a task list while the only endpoint that records one refused it.
+	//
+	// A lane calling this HAS everything the bind needs — its session, its pane,
+	// its list — so requiring a prior call is a sequencing demand with no
+	// informational content. `friction-is-a-stop-condition`: the compliant path
+	// must exist, or the rule is unenforceable against the lane it binds.
+	const task = await ensureLaneTask(prisma, laneSession, pane ?? null);
+	if (!task) {
+		throw new Error(
+			`Could not bind a task for session ${laneSession} — the create failed and no existing task was found.`,
+		);
+	}
+	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.input(bindLaneInput).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;
+		// parent_id arrives EITHER as a body field (parsed now that bindLane has an
+		// `.input()` schema — bindLaneInput) OR on the x-lane-work-item header. Both
+		// are the assignment task id this lane ADOPTS (`adoptAssignmentTask`); the
+		// header stays as the redundant transport a header-only caller (zerostack)
+		// already sends. Before the schema, the body path silently never parsed, so a
+		// body-only caller (pi) dropped parent_id, never adopted, and self-briefed to
+		// nulls — the data-not-serving gap `bindLaneInput` exists to close.
+		const headerWorkItem = ctx.headers?.get("x-lane-work-item") ?? null;
+		// cli_kind via header is the fallback for callers that transport it there; a
+		// caller that puts cli_kind in the body lane object (parsed by bindLaneInput)
+		// is read from raw.lane.cli_kind first.
+		const headerWorkKind = ctx.headers?.get("x-lane-cli-kind") ?? null;
+		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 ?? headerWorkKind ?? "claude-code") as LaneIdentity["cli_kind"],
+			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.
+		// The lane's work name — NEVER the "Lane" sentinel (spawn debris an
+		// orchestrator cannot attribute). null when no run resolves a slot_name;
+		// the create path REFUSES rather than write "Lane" (lanes-named-by-the-
+		// spawner).
+		const laneTitle = raw.title ?? (await resolveLaneWorkName(prisma, pane)) ?? null;
+		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 },
+				// A supplied parent is an INSTRUCTION, not a default: the spawn named
+				// the project this lane is for, which is newer than whatever the row
+				// carried. Set only on create until now, so a re-bind — the common
+				// case, since this matches by session — silently dropped it.
+				// Omitted leaves the existing parent alone, so a re-bind without a
+				// project cannot orphan a lane that already has one.
+				data: {
+					kind_data: kindData,
+					// assignee_id on EVERY bind path, not only adopt: a re-bind that
+					// left assignee_id null read as "unowned" to an orchestrator
+					// steering by it (measured 2026-08-01: "Dev-mcp bus claim" — a
+					// live lane whose task had a session but null assignee_id).
+					assignee_id: session,
+					...(raw.parent_id ? { parent_id: raw.parent_id } : {}),
+				},
+			});
+			taskId = updated.id;
+			created = false;
+			log.info("[task-sync] bindLane: re-bound existing task", { taskId, session });
+		} else {
+			// DISPATCH-BY-ASSIGNMENT adopt, then a write-back that NEVER orphans.
+			// The spawn may have carried a workItemId the lane should adopt; adopt
+			// attempts it, then resolveBindAction decides from the outcome:
+			//   use     — adopt succeeded.
+			//   create  — exploratory lane (no workItemId) or the id is a PROJECT
+			//             the task is created under.
+			//   refuse  — the spawn named a task that does NOT exist. This is the
+			//             `absent-input-reads-as-success` failure: silently creating
+			//             a new task here would abandon the spawn's referenced brief
+			//             and bind the lane to an empty task it was never meant to
+			//             own, leaving an orphan an orchestrator cannot tell from
+			//             real unowned work. Failing loudly surfaces the bad spawn.
+			const workItemId = raw.parent_id ?? headerWorkItem;
+			const adopted = await adoptAssignmentTask(prisma, workItemId, { ...lane, session });
+			let referencedKind: string | null = null;
+			if (!adopted && workItemId) {
+				const ref = await prisma.work_items.findFirst({
+					where: { id: workItemId },
+					select: { kind: true },
+				});
+				referencedKind = ref?.kind ?? null;
+			}
+			const action = resolveBindAction({ adopted, workItemId, referencedKind });
+			if (action.action === "refuse") {
+				const { ORPCError } = await import("@orpc/server");
+				throw new ORPCError("NOT_FOUND", {
+					message:
+						`bindLane: the spawn referenced work item ${action.workItemId} to adopt, but no task ` +
+						"exists with that id — refusing rather than creating an orphan task and abandoning the spawn's brief.",
+				});
+			}
+			if (action.action === "use") {
+				taskId = adopted!.id;
+				created = false;
+				log.info("[task-sync] bindLane: adopted assigned task", {
+					taskId: adopted!.id,
+					session,
+				});
+			} else {
+				// A task's title must carry the lane's REAL work name — never the
+				// generic "Lane" sentinel (spawn debris an orchestrator cannot
+				// attribute). No resolvable name = refuse, so a "Lane" row is
+				// unmakeable on this path (lanes-named-by-the-spawner).
+				if (!laneTitle || laneTitle.trim().toLowerCase() === "lane") {
+					const { ORPCError } = await import("@orpc/server");
+					throw new ORPCError("BAD_REQUEST", {
+						message:
+							"bindLane: no real work name resolved for this lane (its fleet run has no slot_name). " +
+							"A task titled 'Lane' is spawn debris — name the lane at spawn (windowName) or ensure its fleet run resolves a slot_name.",
+					});
+				}
+				// 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",
+							// assignee_id = the lane's session on EVERY bind path, not only
+							// adopt. Without it a bound task reads as unowned (assignee_id
+							// null) — the signal the fleet steers by. Measured 2026-08-01:
+							// 207 task rows with kind_data.lane.session set but assignee_id
+							// null, every one reading as unowned.
+							assignee_id: session,
+							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.input(upsertFromTaskListInput).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" });
+		}
+		// The pane rides in the header the callers already send (`x-lane-pane`),
+		// and it is what lets the on-demand bind link the new task to the lane's
+		// run. Absent, the bind still succeeds — it just cannot link the run — so
+		// this is passed opportunistically rather than required.
+		const headerPane = (context as Context).headers?.get("x-lane-pane") ?? null;
+		try {
+			const res = await reconcileTaskList(prisma, session, list, body.source, headerPane);
+			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 });
+			}
+			// The 500 body is masked by oRPC (INTERNAL_SERVER_ERROR), so without
+			// this the cause is invisible — measured 2026-07-30:
+			// upsertFromTaskList 500ing consistently with no surfaced error,
+			// blocking task-list projection + the watchdog for every lane. Log
+			// the actual error before re-throwing (protective-layers-fail-
+			// explicitly: a failure with no observability is the worst shape).
+			log.error("[task-sync] upsertFromTaskList FAILED", { session, err: err instanceof Error ? `${err.name}: ${err.message}` : String(err) });
+			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 }) =>
+		upsertFromTaskHookHandler(input, context)),
+
+	/**
+	 * 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 self-brief leg. A spawned lane PULLS its own brief — nothing is
+	 * pasted, typed, passed as an argument or sent over a channel
+	 * (`action-emission-architecture.md` "The lane PULLS its brief"). The lane's
+	 * CLI extension reads its own session id on load, calls this procedure, and
+	 * reads the brief from the task's LATEST comment. The comment — not the
+	 * description, not a stale comment — is the brief for THIS run: every spawn
+	 * writes a NEW comment, so "what was this lane told" always has exactly one
+	 * answer (`assignment-as-dispatch`). Handler lives in task-sync-brief.ts
+	 * (router is at its line budget); mounted here so fn.taskSync surfaces it.
+	 */
+	readAssignedBrief: readAssignedBriefHandler,
+
+	/** SPAWNER→DB brief mint: `spawn_agent_tab` turns an initialPrompt into the task row (brief = first comment) the lane self-briefs from; returns the work_item_id that rides the spawn payload. Handler in task-sync-assign.ts. */
+	createBriefTask: createBriefTaskHandler,
+
+	/**
+	 * TAB→DB rename back-write: the session-picker `/rpc/rename` calls this after
+	 * renaming a tmux window to update the bound task's title BY SESSION (never
+	 * pane), so the tab bar and the project board never diverge
+	 * (`tab-rename-emits-back-to-task-title`). Handler in task-sync-rename.ts.
+	 */
+	renameLaneTask: renameLaneTaskHandler,
+
+	/**
+	 * 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 };
+	}),
+};
+
+/**
+ * The Claude Code per-item task lifecycle applied to a lane's work_items
+ * subtasks — the AGENT→DB leg for the Task* tool family (TaskCreate /
+ * TaskUpdate / TaskDelete) and the dedicated TaskCreated / TaskCompleted events.
+ *
+ * Extracted verbatim from the upsertFromTaskHook ORPC handler so the FULL
+ * lifecycle — created, in_progress, completed, deleted — is unit-testable with a
+ * mock prisma (same testability split as claim-orchestrator-session, and the
+ * router-handlers-only-execute half of planReconcile). The ORPC handler is now a
+ * thin `authed` wrapper that delegates here; this function takes the exact
+ * `(input, context)` the handler would have bound, so behaviour is unchanged.
+ *
+ * `task-projection-converges`: every state a task reaches must write through, or
+ * the projection is an append-only log and the operator cannot see what a lane is
+ * doing. The matcher covering TaskCreate|TaskUpdate|TaskDelete is what makes all
+ * four states reach this handler; this body is what applies them.
+ */
+export async function upsertFromTaskHookHandler(input: unknown, context: 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();
+	// PostToolUse is what Claude Code fires for the Task* tools (verified live:
+	// subtasks are created from PostToolUse:TaskCreate events). The dedicated
+	// TaskCreated/TaskCompleted EVENT legs below are kept as a defensive path —
+	// classifyTaskHookEvent discriminates them by hook_event_name — but the live
+	// matcher is PostToolUse:TaskCreate|TaskUpdate|TaskDelete, which lands in the
+	// `tool` leg. Handle the dedicated events first so a TaskCompleted cannot fall
+	// through to create a duplicate (task-projection-converges).
+	const createdEvt = evt as {
+		task_subject?: unknown;
+		task_id?: unknown;
+		hook_event_name?: unknown;
+		// Created-already-done must not project OPEN. Absent -> old behaviour.
+		status?: unknown;
+	};
+	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 createdStatus =
+			STATUS_TO_WORK_ITEM[createdEvt.status as TaskListItem["status"]] ?? "todo";
+		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: createdStatus,
+					completed: createdStatus === "done",
+					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" } });
+		// IDEMPOTENT on the CLI's own task id. The hook curls with --retry, so one
+		// TaskCreate can arrive twice, and this (the LIVE PostToolUse path) used to
+		// fetch `existing` only for position — never to check whether the subtask
+		// was already written — so every retry minted a duplicate
+		// (task-projection-converges: a projection that duplicates is not a
+		// projection). Same mark-then-title match as the TaskCreated event leg.
+		const already = existing.find((e) => {
+			const mark = (e.kind_data as { task_sync?: { mark?: string } } | null)?.task_sync?.mark;
+			return taskId && mark ? mark === taskId : e.title === subject;
+		});
+		if (already) {
+			return discardApplied("duplicate-create", session, { toolName, taskId, subtaskId: already.id });
+		}
+		try {
+			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" } },
+				},
+			});
+		} catch (err) {
+			// P2002 = unique violation on work_items_subtask_task_sync_mark_uniq
+			// (read-then-write race: two retries both read `existing` before either
+			// writes). Losing the race is the correct idempotent outcome, not a 500.
+			if ((err as { code?: string })?.code !== "P2002") throw err;
+			return discardApplied("duplicate-create-race", session, { toolName, taskId });
+		}
+		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") {
+		// Canonical Prisma form (the same as reconcileTaskList's deleteMany):
+		// `id: { in: [...] }`, NOT `id: [...]` — a bare array on the scalar id is a
+		// Prisma validation error that 500'd every TaskDelete, so deletion never
+		// projected even once the hook was wired.
+		await prisma.work_items.deleteMany({ where: { id: { in: [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. The first title-match a row
+	// ever gets makes it mark-addressable, so every later rename updates it in
+	// place (task-projection-converges — a row it can no longer address expresses
+	// nothing). The heal path stamps on create; this is the update half.
+	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 };
+}