@teamscala/service-boot 0.23.320 → 0.23.322

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.320",
+  "version": "0.23.322",
   "sideEffects": false,
   "files": [
     "src"

package/src/fn-routers/task-sync-hook-lifecycle.test.ts

@@ -0,0 +1,204 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lifecycle round-trip for the Claude Code per-item task projection:
+ * `upsertFromTaskHookHandler` (the extracted body of the upsertFromTaskHook
+ * ORPC handler) must carry a task through created -> in_progress -> completed ->
+ * deleted against an in-memory mock prisma, so `work_items` sees every state a
+ * task reaches (`task-projection-converges`). A projection that cannot express
+ * completion — or deletion — is an append-only log, and the operator cannot see
+ * what a lane is doing. The matcher covering TaskCreate|TaskUpdate|TaskDelete is
+ * what routes all three tool events here; these tests assert the body applies
+ * each one. Same mock-prisma shape as claim-orchestrator-session.test.ts.
+ */
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+
+const recordEventMock = mock((_event: unknown) => {});
+mock.module("@teamscala/event-log/record-event", () => ({ recordEvent: recordEventMock }));
+mock.module("@teamscala/logger/app-loggers", () => ({
+	getAppLogger: () => ({
+		info: () => {},
+		warn: () => {},
+		error: () => {},
+	}),
+}));
+
+const { upsertFromTaskHookHandler } = await import("./task-sync-router.ts");
+
+/** A lane's parent task, returned by the mocked resolveLaneTask findFirst. */
+const LANE_TASK = {
+	id: "task-1",
+	kind: "task",
+	parent_id: null,
+	organisation_id: "org-1",
+	title: "Test Lane",
+	status: "active",
+	completed: false,
+	position: null,
+	kind_data: { lane: { session: "ses-1", pane: "tmux:%1" } },
+};
+
+function makePrisma() {
+	// In-memory subtask store, so the four states act on ONE evolving row.
+	const subtasks: Array<Record<string, unknown>> = [];
+	const findFirst = mock(async (args: { where: Record<string, unknown> }) => {
+		// resolveLaneTask asks for kind='task' + status active/archived; everything
+		// else (subtask lookups) returns null.
+		if (args.where?.kind === "task") return { ...LANE_TASK };
+		return null;
+	});
+	const findMany = mock(async (args: { where: Record<string, unknown> }) => {
+		const pid = args.where?.parent_id;
+		return subtasks.filter((s) => s.parent_id === pid);
+	});
+	const create = mock(async (args: { data: Record<string, unknown> }) => {
+		const row = { id: `s-${subtasks.length + 1}`, ...args.data };
+		subtasks.push(row);
+		return row;
+	});
+	const update = mock(async (args: { where: { id: string }; data: Record<string, unknown> }) => {
+		const row = subtasks.find((s) => s.id === args.where.id);
+		if (row) Object.assign(row, args.data);
+		return row ?? null;
+	});
+	const deleteMany = mock(async (args: { where: { id: { in: string[] } } }) => {
+		// Real Prisma form: where.id.in (a bare array on the scalar id is a
+		// validation error). Mirrors the canonical deleteMany in reconcileTaskList.
+		const ids = args.where?.id?.in ?? [];
+		let count = 0;
+		for (let i = subtasks.length - 1; i >= 0; i--) {
+			if (ids.includes(String(subtasks[i]?.id))) {
+				subtasks.splice(i, 1);
+				count++;
+			}
+		}
+		return { count };
+	});
+	return {
+		store: subtasks,
+		prisma: { work_items: { findFirst, findMany, create, update, deleteMany } },
+		mocks: { findFirst, findMany, create, update, deleteMany },
+	};
+}
+
+/** A lane context bound to a mock prisma, so each call site passes only the event. */
+function bindCtx(prisma: unknown, session = "ses-1") {
+	const headers = new Headers();
+	headers.set("x-lane-session", session);
+	headers.set("x-lane-pane", "tmux:%1");
+	return { headers, prisma, user: undefined };
+}
+
+/** makePrisma + a `hook(evt)` convenience bound to that prisma's session. */
+function makeFixture() {
+	const fixture = makePrisma();
+	const hook = (evt: unknown) => upsertFromTaskHookHandler(evt, bindCtx(fixture.prisma));
+	return { ...fixture, hook };
+}
+
+describe("upsertFromTaskHookHandler — full lifecycle round-trip", () => {
+	beforeEach(() => recordEventMock.mockClear());
+
+	it("created -> in_progress -> completed -> deleted all write through to one subtask", async () => {
+		const { hook, store, mocks } = makeFixture();
+
+		// 1. CREATED — PostToolUse:TaskCreate. The harness assigns the task id in
+		//    tool_response.task.id; the projection must stamp it as the mark so every
+		//    later state is mark-addressable.
+		const created = await hook({
+			tool_name: "TaskCreate",
+			hook_event_name: "PostToolUse",
+			tool_input: { subject: "Ship the fix" },
+			tool_response: { task: { id: "42" } },
+		});
+		expect(created).toEqual({ applied: true, op: "create", taskId: "42" });
+		expect(mocks.create).toHaveBeenCalledTimes(1);
+		const row = store[0];
+		expect(row.title).toBe("Ship the fix");
+		expect(row.status).toBe("todo");
+		expect((row.kind_data as { task_sync: { mark: string } }).task_sync.mark).toBe("42");
+
+		// 2. IN_PROGRESS — PostToolUse:TaskUpdate with status in_progress. Matched
+		//    by the mark stamped at creation; the projection expresses it, it does
+		//    not append a new row.
+		mocks.create.mockClear();
+		const inProgress = await hook({
+			tool_name: "TaskUpdate",
+			hook_event_name: "PostToolUse",
+			tool_input: { taskId: "42", status: "in_progress" },
+		});
+		expect(inProgress).toEqual({ applied: true, op: "update", taskId: "42" });
+		expect(mocks.create).not.toHaveBeenCalled();
+		expect(mocks.update).toHaveBeenCalledTimes(1);
+		expect(row.status).toBe("in-progress");
+		expect(row.completed).toBe(false);
+		expect(store).toHaveLength(1);
+
+		// 3. COMPLETED — PostToolUse:TaskUpdate with status completed. A projection
+		//    that cannot express completion is an append-only log.
+		mocks.update.mockClear();
+		const done = await hook({
+			tool_name: "TaskUpdate",
+			hook_event_name: "PostToolUse",
+			tool_input: { taskId: "42", status: "completed" },
+		});
+		expect(done).toEqual({ applied: true, op: "update", taskId: "42" });
+		expect(mocks.update).toHaveBeenCalledTimes(1);
+		expect(row.status).toBe("done");
+		expect(row.completed).toBe(true);
+		expect(store).toHaveLength(1);
+
+		// 4. DELETED — PostToolUse:TaskDelete. The row leaves the projection; the
+		//    list empties, which is the half a create-only projection can never do.
+		const deleted = await hook({
+			tool_name: "TaskDelete",
+			hook_event_name: "PostToolUse",
+			tool_input: { taskId: "42" },
+		});
+		expect(deleted).toEqual({ applied: true, op: "delete", taskId: "42" });
+		expect(mocks.deleteMany).toHaveBeenCalledTimes(1);
+		expect(store).toHaveLength(0);
+	});
+
+	it("stamps the mark on a title-matched update so a later rename is mark-addressable", async () => {
+		// A row written with NO mark (pre-mark history, or a healed row) is only
+		// reachable by title. The first title-match must stamp the mark so the row
+		// never orphans on a later rename (the 2026-07-28 stranded-subtask class).
+		const { hook, store } = makeFixture();
+		store.push({
+			id: "legacy-1",
+			parent_id: "task-1",
+			title: "Old title",
+			status: "todo",
+			completed: false,
+			kind_data: {},
+		});
+
+		await hook({
+			tool_name: "TaskUpdate",
+			hook_event_name: "PostToolUse",
+			tool_input: { taskId: "99", subject: "Old title", status: "in_progress" },
+		});
+		expect((store[0].kind_data as { task_sync: { mark: string } }).task_sync.mark).toBe("99");
+		expect(store[0].status).toBe("in-progress");
+	});
+
+	it("is idempotent on a retried TaskCreate (no duplicate subtask)", async () => {
+		// The hook curls with --retry, so one TaskCreate can arrive twice. A
+		// projection that duplicates on retry is not a projection.
+		const { hook, store } = makeFixture();
+		const evt = {
+			tool_name: "TaskCreate",
+			hook_event_name: "PostToolUse",
+			tool_input: { subject: "Once only" },
+			tool_response: { task: { id: "7" } },
+		};
+		await hook(evt);
+		const second = await hook(evt);
+		// The retried create matches the stored mark and is discarded, not doubled.
+		expect(second.applied).toBe(false);
+		expect(store.filter((s) => s.title === "Once only")).toHaveLength(1);
+	});
+});

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

@@ -375,3 +375,28 @@ export declare const taskSyncRouter: {
         notified: boolean;
     }>, Record<never, never>, Record<never, never>>;
 };
+/**
+ * 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 declare function upsertFromTaskHookHandler(input: unknown, context: Context): Promise<{
+    applied: boolean;
+    op: string;
+    taskId: string;
+} | ({
+    applied: false;
+    reason: string;
+} & Record<string, unknown>)>;

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

@@ -721,265 +721,8 @@ export const taskSyncRouter = {
 	 * 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;
-			// Created-already-done must not project OPEN. Absent -> old behaviour.
-			status?: 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 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" } });
-			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 };
-	}),
+	upsertFromTaskHook: authed.handler(async ({ input, context }) =>
+		upsertFromTaskHookHandler(input, context)),
 
 	/**
 	 * DB→AGENT backstop read. Returns the lane's current subtasks in the
@@ -1073,3 +816,282 @@ export const taskSyncRouter = {
 		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 };
+}

package/src/register-api-routes.ts

@@ -19,14 +19,20 @@ import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
 import type { Context, Hono } from "hono";
 import { getConnInfo } from "hono/bun";
+import { CALLER_HEADERS } from "@teamscala/os/contracts/mcp";
 
-const REMOTE_PORT_HEADER = "x-caller-remote-port";
+// From CALLER_HEADERS, never a literal: this name is one end of a contract the
+// gateway's caller-resolution reads, and a literal stores it twice. The
+// 2026-08-02 outage was that exact drift on a sibling header (reader on
+// `x-user-id`, writer on `x-caller-user-id`), and it took every tool on the
+// cloud MCP down once the branch masking it was closed.
+const REMOTE_PORT_HEADER = CALLER_HEADERS.REMOTE_PORT;
 // Verified socket-peer address (unforgeable transport origin). Sanitized
 // (client-supplied value deleted) then set from getConnInfo so handlers that
 // receive only a Request (e.g. mcp-tool-runtime/mount.ts) can gate on the
 // genuine transport origin per no-client-controlled-trust-signals — an external
 // attacker cannot make their TCP connection appear on the server's loopback.
-const REMOTE_ADDR_HEADER = "x-caller-remote-address";
+const REMOTE_ADDR_HEADER = CALLER_HEADERS.REMOTE_ADDRESS;
 
 export function registerApiRoutes(
 	app: Hono,

package/src/serve/stamp-transport-identity.ts

@@ -26,6 +26,7 @@
  * identity — a clone can never upgrade).
  */
 
+import { CALLER_HEADERS } from "@teamscala/os/contracts/mcp";
 import { resolveSocketPeer } from "@teamscala/proc-walker/socket-peer";
 
 const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
@@ -53,15 +54,15 @@ export function stampTransportIdentity(
 		const port = peer?.port;
 		const address = peer?.address ?? null;
 		const needsPort =
-			typeof port === "number" && port > 0 && !req.headers.has("x-caller-remote-port");
+			typeof port === "number" && port > 0 && !req.headers.has(CALLER_HEADERS.REMOTE_PORT);
 		// Nothing to stamp when there is no peer address and no port to add.
 		if (!needsPort && address === null) return req;
 
 		const headers = new Headers(req.headers);
-		if (needsPort) headers.set("x-caller-remote-port", String(port));
+		if (needsPort) headers.set(CALLER_HEADERS.REMOTE_PORT, String(port));
 		if (address) {
-			headers.delete("x-caller-remote-address");
-			headers.set("x-caller-remote-address", String(address));
+			headers.delete(CALLER_HEADERS.REMOTE_ADDRESS);
+			headers.set(CALLER_HEADERS.REMOTE_ADDRESS, String(address));
 		}
 		// Local-caller attribution: loopback peer + no forwarding header => a
 		// direct local fetch whose owning process we can name via /proc.
@@ -75,9 +76,9 @@ export function stampTransportIdentity(
 		) {
 			const owner = resolveSocketPeer(port);
 			if (owner) {
-				headers.set("x-caller-local-comm", owner.comm);
+				headers.set(CALLER_HEADERS.LOCAL_COMM, owner.comm);
 				const cmd = owner.cmdline.join(" ").trim();
-				if (cmd) headers.set("x-caller-local-cmd", cmd.slice(0, 160));
+				if (cmd) headers.set(CALLER_HEADERS.LOCAL_CMD, cmd.slice(0, 160));
 			}
 		}
 		return new Request(req.url, {