@teamscala/service-boot 0.23.319 → 0.23.321

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

@@ -5,7 +5,7 @@
  *
  * Lane BRIEF resolution for task-sync: a spawned lane PULLS its own brief. The
  * lane's CLI extension reads its own session id on load, resolves the task
- * assigned to that session, and reads the brief from that task's FIRST comment.
+ * assigned to that session, and reads the brief from that task's LATEST comment.
  * Nothing is pasted, typed, passed as an argument or sent over a channel
  * (`scala-docs/reference/action-emission-architecture.md` "The lane PULLS its
  * brief"). This file owns the readAssignedBrief ORPC handler + its pure helper;
@@ -39,7 +39,7 @@ import { resolveLaneTask, resolveTaskById } from "./task-sync-lane.ts";
 export type BriefReadStatus = "ready" | "empty_brief" | "no_comment" | "unbound";
 
 /**
- * Shape the readAssignedBrief response from a resolved task + its first
+ * Shape the readAssignedBrief response from a resolved task + its latest
  * comment. Pure (no prisma) so the decision — "no task/comment ⇒ nulls, never a
  * verdict from no data" (`no-verdict-from-no-data`) — is unit-testable.
  *
@@ -61,27 +61,25 @@ export type BriefReadStatus = "ready" | "empty_brief" | "no_comment" | "unbound"
  */
 export function shapeBriefResponse(
 	task: { id: string } | null,
-	comment: Pick<CommentRow, "id" | "content" | "created_at"> | null,
+	comment: Pick<CommentRow, "content" | "created_at"> | null,
 ): {
 	work_item_id: string | null;
-	comment_id: string | null;
 	brief: string | null;
 	comment_created_at: string | null;
 	status: BriefReadStatus;
 } {
 	if (!task) {
-		return { work_item_id: null, comment_id: null, brief: null, comment_created_at: null, status: "unbound" };
+		return { work_item_id: null, brief: null, comment_created_at: null, status: "unbound" };
 	}
 	if (!comment) {
-		return { work_item_id: task.id, comment_id: null, brief: null, comment_created_at: null, status: "no_comment" };
+		return { work_item_id: task.id, brief: null, comment_created_at: null, status: "no_comment" };
 	}
 	const text = typeof comment.content === "string" ? comment.content : String(comment.content);
 	if (text.trim() === "") {
-		return { work_item_id: task.id, comment_id: comment.id, brief: null, comment_created_at: null, status: "empty_brief" };
+		return { work_item_id: task.id, brief: null, comment_created_at: null, status: "empty_brief" };
 	}
 	return {
 		work_item_id: task.id,
-		comment_id: comment.id,
 		brief: text,
 		comment_created_at:
 			comment.created_at instanceof Date ? comment.created_at.toISOString() : String(comment.created_at),
@@ -90,12 +88,13 @@ export function shapeBriefResponse(
 }
 
 /**
- * Read the immutable FIRST comment on a work_items task. It is the launch brief;
- * later comments are conversation and must never change the launch identity.
- * Oldest-first by created_at with id as a deterministic tie-breaker. Returns null
- * when the task has no comment yet.
+ * Read the LATEST comment on a work_items task. The comment IS the brief for a
+ * run: every spawn writes a NEW comment, and the description is never the brief,
+ * so "what was this lane told" always has exactly one answer
+ * (`assignment-as-dispatch`). Newest-first by created_at. Returns null when the
+ * task has no comment yet — the extension treats that as "no brief to inject".
  */
-export async function readFirstTaskComment(
+export async function readLatestTaskComment(
 	prisma: Prisma,
 	workItemId: string,
 ): Promise<CommentRow | null> {
@@ -109,7 +108,7 @@ export async function readFirstTaskComment(
 	if (!comments?.findFirst) return null;
 	return comments.findFirst({
 		where: { work_item_id: workItemId },
-		orderBy: [{ created_at: "asc" }, { id: "asc" }],
+		orderBy: { created_at: "desc" },
 	});
 }
 
@@ -146,6 +145,6 @@ export const readAssignedBriefHandler = authed.handler(async ({ input, context }
 		task = (await resolveLaneTask(prisma, session)) as (WorkItem & { id: string }) | null;
 	}
 	if (!task) return shapeBriefResponse(null, null);
-	const comment = await readFirstTaskComment(prisma, task.id);
+	const comment = await readLatestTaskComment(prisma, task.id);
 	return shapeBriefResponse(task, comment);
 });

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

@@ -0,0 +1,61 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * DB→AGENT dispatch for task-sync — notifies a lane's live pane that its
+ * work_items task list changed out-of-band (operator toggled a subtask in the
+ * projects UI, another lane edited a shared task). The pane's adapter then
+ * re-reads (fn.taskSync.readTaskList) and updates its native list.
+ *
+ * MECHANISM — reuses the existing CLI-agnostic channel delivery, no new
+ * transport: a POST to scala-channel's fleet-events publish entry
+ * (POST /api/fleet/events — @teamscala/channel/fleet-events-publish) carrying an
+ * `orchestrator.message` FleetEvent with slotName "cross-pane". That slot is
+ * the watchEvents bypass for events NOT tied to a fleet_agent_runs row
+ * (FleetEventOrchestratorMessageSchema comment) — exactly the system-originated
+ * case. scala-channel re-emits onto its eventBus and streamFleetEvents delivers
+ * to the subscriber filtered by orchestratorSessionId (the target lane pane).
+ * Both the Claude Code relay and the OpenCode scala-hooks plugin subscribe to
+ * that SSE stream for their own pane identity and inject each event natively —
+ * so ONE publish reaches every CLI that has a live projection, no per-CLI
+ * dispatch code here.
+ *
+ * NOT the dispatch entry (POST /api/channel/send): that path requires a real
+ * sender pane identity (channel-sender-identity-validated anti-spoof) and so
+ * cannot carry a system-originated notification. The publish path is
+ * internal-trusted (localhost super-admin) and accepts a synthetic
+ * fromOrchestratorId — the correct path for a system→pane message.
+ *
+ * scala-channel's address is resolved from its service_routing row (local_port)
+ * — never hardcoded (service-ports-from-registry). Fire-and-forget: a dispatch
+ * failure (scala-channel down, port unresolvable) is logged and swallowed; it
+ * must never block the work_items write that triggered it, and the lane's
+ * SessionStart/UserPromptSubmit backstop picks up the change on its next turn
+ * regardless.
+ */
+/**
+ * The `orchestrator.message` FleetEvent payload that notifies a lane its task
+ * list changed. Pure (no I/O) so it is unit-testable; notifyLaneOfTaskChange
+ * posts it. slotName "cross-pane" is REQUIRED — it is the watchEvents bypass for
+ * events not tied to a fleet_agent_runs row. orchestratorSessionId is the TARGET
+ * lane pane (the SSE subscriber filter). The message is single-line (the
+ * <channel> tag renders it inline).
+ */
+export interface TaskChangedEvent {
+    type: "orchestrator.message";
+    message: string;
+    fromOrchestratorId: string;
+    runId: string;
+    slotName: "cross-pane";
+    ts: number;
+    orchestratorSessionId: string;
+}
+export declare function buildTaskChangedEvent(lanePane: string, taskId: string, now?: number): TaskChangedEvent;
+/**
+ * Publish a "your task list changed" notification to the owning lane's pane.
+ * The pane identity is the stable tmux id ("tmux:%42") every CLI relay/plugin
+ * receives for. `taskId` is carried in the message so the recipient can re-read
+ * just that task. Fire-and-forget.
+ */
+export declare function notifyLaneOfTaskChange(lanePane: string, taskId: string): Promise<void>;

package/src/fn-routers/task-sync-dispatch.test.ts

@@ -3,60 +3,42 @@
  * @status handwritten
  * @edit edit directly
  *
- * Unit tests for the pure durable comment-payload builder in task-sync-dispatch.
- * The runtime path writes this payload through the canonical comments model.
+ * Unit tests for the pure event-payload builder in task-sync-dispatch. The HTTP
+ * POST + registry resolution are side-effectful (covered end-to-end by the
+ * DB->AGENT direction demo — a published orchestrator.message with slotName
+ * cross-pane delivers to the target pane's <channel> tag); buildTaskChangedEvent
+ * is pure and tested here. Satisfies what-must-have-a-test / primitive-api-has-test.
  */
 import { describe, it, expect } from "bun:test";
-import { buildTaskChangeComment, notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
+import { buildTaskChangedEvent } from "./task-sync-dispatch.ts";
 
-	describe("task-sync buildTaskChangeComment", () => {
-		it("addresses the canonical task and runtime with no pane transport", () => {
-			const comment = buildTaskChangeComment("task-7", "session-5", "subtask-1:completed");
-			expect(comment).toMatchObject({
-				work_item_id: "task-7",
-				source_cli_session_id: "session-5",
-				sender_role: "system",
-				sender_name: "TaskSync",
-			});
-			expect(comment.system_key).toBe("task-sync:task-7:session-5:subtask-1:completed");
-			expect(comment.content).toContain("readTaskList");
-			expect(comment).not.toHaveProperty("pane");
-		});
+describe("task-sync buildTaskChangedEvent", () => {
+	it("is an orchestrator.message addressed to the owning lane pane", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.type).toBe("orchestrator.message");
+		expect(e.orchestratorSessionId).toBe("tmux:%5");
+	});
+
+	it("uses slotName cross-pane so watchEvents bypasses the fleet-run-existence check", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.slotName).toBe("cross-pane");
+	});
 
-		it("writes one durable comment addressed by the active cli_session", async () => {
-			const calls: unknown[] = [];
-			const result = await notifyLaneOfTaskChange(
-				{
-					cli_sessions: { findFirst: async () => ({ id: "session-5" }) },
-					comments: {
-						upsert: async (args) => {
-							calls.push(args);
-							return { id: "comment-1" };
-						},
-					},
-				},
-				"task-7",
-				"subtask-1:completed",
-			);
-			expect(result).toMatchObject({ delivered: true, sessionId: "session-5", commentId: "comment-1" });
-			expect(calls[0]).toMatchObject({ create: { work_item_id: "task-7", source_cli_session_id: "session-5" } });
-		});
+	it("carries the task id in the message so the recipient can re-read just it", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.message).toContain("task-7");
+		expect(e.message).toContain("readTaskList");
+	});
+
+	it("produces a single-line message (the <channel> tag renders it inline)", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.message.includes("\n")).toBe(false);
+	});
 
-		it("does not fabricate a pre-launch session or comment", async () => {
-			let writes = 0;
-			const result = await notifyLaneOfTaskChange(
-				{
-					cli_sessions: { findFirst: async () => null },
-					comments: {
-						upsert: async () => {
-							writes++;
-							return { id: "unexpected" };
-						},
-					},
-				},
-				"task-7",
-			);
-			expect(result).toEqual({ delivered: false, sessionId: null, commentId: null });
-			expect(writes).toBe(0);
-		});
+	it("stamps the system sender + a deterministic runId + the provided epoch-ms ts", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.fromOrchestratorId).toBe("task-sync");
+		expect(e.runId).toBe("task-sync-task-7-1700000000000");
+		expect(e.ts).toBe(1700000000000);
 	});
+});

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

@@ -0,0 +1,124 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * DB→AGENT dispatch for task-sync — notifies a lane's live pane that its
+ * work_items task list changed out-of-band (operator toggled a subtask in the
+ * projects UI, another lane edited a shared task). The pane's adapter then
+ * re-reads (fn.taskSync.readTaskList) and updates its native list.
+ *
+ * MECHANISM — reuses the existing CLI-agnostic channel delivery, no new
+ * transport: a POST to scala-channel's fleet-events publish entry
+ * (POST /api/fleet/events — @teamscala/channel/fleet-events-publish) carrying an
+ * `orchestrator.message` FleetEvent with slotName "cross-pane". That slot is
+ * the watchEvents bypass for events NOT tied to a fleet_agent_runs row
+ * (FleetEventOrchestratorMessageSchema comment) — exactly the system-originated
+ * case. scala-channel re-emits onto its eventBus and streamFleetEvents delivers
+ * to the subscriber filtered by orchestratorSessionId (the target lane pane).
+ * Both the Claude Code relay and the OpenCode scala-hooks plugin subscribe to
+ * that SSE stream for their own pane identity and inject each event natively —
+ * so ONE publish reaches every CLI that has a live projection, no per-CLI
+ * dispatch code here.
+ *
+ * NOT the dispatch entry (POST /api/channel/send): that path requires a real
+ * sender pane identity (channel-sender-identity-validated anti-spoof) and so
+ * cannot carry a system-originated notification. The publish path is
+ * internal-trusted (localhost super-admin) and accepts a synthetic
+ * fromOrchestratorId — the correct path for a system→pane message.
+ *
+ * scala-channel's address is resolved from its service_routing row (local_port)
+ * — never hardcoded (service-ports-from-registry). Fire-and-forget: a dispatch
+ * failure (scala-channel down, port unresolvable) is logged and swallowed; it
+ * must never block the work_items write that triggered it, and the lane's
+ * SessionStart/UserPromptSubmit backstop picks up the change on its next turn
+ * regardless.
+ */
+
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { ServiceRoutingConfigSchema } from "@teamscala/db-validation/registry-schemas/service-routing";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+let cachedChannelBaseUrl: string | null | undefined;
+
+async function resolveChannelBaseUrl(): Promise<string | null> {
+	if (cachedChannelBaseUrl !== undefined) return cachedChannelBaseUrl;
+	try {
+		const row = await loadRegistryConfig("service_routing", "scala-channel", ServiceRoutingConfigSchema);
+		const port = row?.local_port;
+		cachedChannelBaseUrl = port ? `http://127.0.0.1:${port}` : null;
+	} catch {
+		cachedChannelBaseUrl = null;
+	}
+	return cachedChannelBaseUrl;
+}
+
+/** The system sender identity stamped on fromOrchestratorId. */
+const FROM_ORCHESTRATOR_ID = "task-sync";
+
+/**
+ * The `orchestrator.message` FleetEvent payload that notifies a lane its task
+ * list changed. Pure (no I/O) so it is unit-testable; notifyLaneOfTaskChange
+ * posts it. slotName "cross-pane" is REQUIRED — it is the watchEvents bypass for
+ * events not tied to a fleet_agent_runs row. orchestratorSessionId is the TARGET
+ * lane pane (the SSE subscriber filter). The message is single-line (the
+ * <channel> tag renders it inline).
+ */
+export interface TaskChangedEvent {
+	type: "orchestrator.message";
+	message: string;
+	fromOrchestratorId: string;
+	runId: string;
+	slotName: "cross-pane";
+	ts: number;
+	orchestratorSessionId: string;
+}
+
+export function buildTaskChangedEvent(lanePane: string, taskId: string, now: number = Date.now()): TaskChangedEvent {
+	return {
+		type: "orchestrator.message",
+		message: `TaskSync: your work_items task list changed externally (task ${taskId}). Re-read via fn.taskSync.readTaskList and update your todo list.`,
+		fromOrchestratorId: FROM_ORCHESTRATOR_ID,
+		runId: `task-sync-${taskId}-${now}`,
+		slotName: "cross-pane",
+		ts: now,
+		orchestratorSessionId: lanePane,
+	};
+}
+
+/**
+ * Publish a "your task list changed" notification to the owning lane's pane.
+ * The pane identity is the stable tmux id ("tmux:%42") every CLI relay/plugin
+ * receives for. `taskId` is carried in the message so the recipient can re-read
+ * just that task. Fire-and-forget.
+ */
+export async function notifyLaneOfTaskChange(
+	lanePane: string,
+	taskId: string,
+): Promise<void> {
+	const log = getAppLogger();
+	if (!lanePane) return;
+	const base = await resolveChannelBaseUrl();
+	if (!base) {
+		log.warn("[task-sync] notifyLaneOfTaskChange: scala-channel address unresolvable", { taskId });
+		return;
+	}
+	const payload = buildTaskChangedEvent(lanePane, taskId);
+	try {
+		const res = await fetch(`${base}/api/fleet/events`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(3000),
+		});
+		if (!res.ok) {
+			log.warn("[task-sync] notifyLaneOfTaskChange: non-2xx from scala-channel", {
+				taskId, status: res.status,
+			});
+		}
+	} catch (err) {
+		log.warn("[task-sync] notifyLaneOfTaskChange: POST failed", {
+			taskId, error: err instanceof Error ? err.message : String(err),
+		});
+	}
+}

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

@@ -0,0 +1,49 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane RESOLUTION for task-sync: given a session or a pane, which work_items
+ * task IS this lane, and what is it called.
+ *
+ * Split out of task-sync-router.ts, which had reached 998 of its 1000-line
+ * budget — two lines from frozen. That is not tidiness: the budget is a commit
+ * gate, so at 998 lines ANY change to task-sync was blocked for every lane, and
+ * the four-line fix that needed to land could not. The router header records
+ * being split once before for exactly this reason; it grew back.
+ *
+ * The seam matches the one that split the projection. Everything here answers
+ * "which lane, called what" from an identity, and none of it touches the ORPC
+ * surface or decides what a task list should become — which is why these move
+ * together rather than one at a time: resolveLaneTask alone has seven callers.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Checked against the 14 platform singletons and the package
+ * catalogue; the doctrine test fails plainly, because every export is bound to
+ * the work_items schema and to task-sync own kind_data.lane convention, so no
+ * unrelated app could install this unmodified.
+ */
+import type { Prisma, WorkItem } from "./task-sync-router.ts";
+export declare function resolveLaneWorkName(prisma: Prisma, pane: string): Promise<string | null>;
+export declare function resolveLaneTask(prisma: Prisma, session: string): Promise<WorkItem | null>;
+/**
+ * Resolve a lane's task by its AUTHORITATIVE work_item id — the id the spawn
+ * minted (createBriefTask) and exported into the pane as SCALA_LANE_WORK_ITEM.
+ *
+ * WHY this exists alongside the session resolution: readAssignedBrief used to
+ * resolve ONLY by kind_data.lane.session, which is written by the lane's OWN
+ * bindLane hook at boot. That bind is a fire-and-forget POST racing the brief
+ * read, so a fleet lane whose bind had not yet commit read "no task" and the
+ * self-brief hook silently exited 0 — absent-input-reads-as-success at the
+ * dispatch boundary (a lane booted, was told its brief was loaded, had none,
+ * ran nothing, and was archived having done nothing — measured 2026-08-02).
+ *
+ * The work_item id is known to the spawn before the lane even starts
+ * (mintBriefTask returns it; the spawn REFUSES if minting fails for a capture
+ * CLI), so resolving by it CANNOT race: the row exists because the spawn
+ * created it. The session bind stays for task-list writes (upsertFromTaskList)
+ * — it is no longer load-bearing for brief delivery. Any status is matched
+ * (active OR archived) because the brief is the brief regardless of the run's
+ * state — closing a run archives the task, not the brief.
+ */
+export declare function resolveTaskById(prisma: Prisma, workItemId: string): Promise<WorkItem | null>;

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

@@ -0,0 +1,125 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane RESOLUTION for task-sync: given a session or a pane, which work_items
+ * task IS this lane, and what is it called.
+ *
+ * Split out of task-sync-router.ts, which had reached 998 of its 1000-line
+ * budget — two lines from frozen. That is not tidiness: the budget is a commit
+ * gate, so at 998 lines ANY change to task-sync was blocked for every lane, and
+ * the four-line fix that needed to land could not. The router header records
+ * being split once before for exactly this reason; it grew back.
+ *
+ * The seam matches the one that split the projection. Everything here answers
+ * "which lane, called what" from an identity, and none of it touches the ORPC
+ * surface or decides what a task list should become — which is why these move
+ * together rather than one at a time: resolveLaneTask alone has seven callers.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Checked against the 14 platform singletons and the package
+ * catalogue; the doctrine test fails plainly, because every export is bound to
+ * the work_items schema and to task-sync own kind_data.lane convention, so no
+ * unrelated app could install this unmodified.
+ */
+
+import type { Prisma, WorkItem } from "./task-sync-router.ts";
+
+export async function resolveLaneWorkName(prisma: Prisma, pane: string): Promise<string | null> {
+	try {
+		const runs = (
+			prisma as unknown as {
+				fleet_agent_runs?: {
+					findFirst: (a: unknown) => Promise<{ slot_name?: string | null } | null>;
+				};
+			}
+		).fleet_agent_runs;
+		if (!runs?.findFirst) return null;
+		// Most recent run for the pane, REGARDLESS of state. A lane's work name does
+		// not vanish when its run closes, and filtering `state != closed` here is
+		// exactly why task rows were titled "Lane": a task-list write (ensureLaneTask)
+		// that fires after the run closed resolved no name and fell back to the
+		// generic sentinel — spawn debris an orchestrator cannot attribute
+		// (measured 2026-08-01: 207 "Lane" rows). Newest-first so a reused pane
+		// resolves its CURRENT lane, not a prior one.
+		const run = await runs.findFirst({
+			where: { pane },
+			orderBy: { created_at: "desc" },
+			select: { slot_name: true },
+		});
+		const name = run?.slot_name?.trim();
+		return name ? name : null;
+	} catch {
+		return null;
+	}
+}
+
+export async function resolveLaneTask(prisma: Prisma, session: string): Promise<WorkItem | null> {
+	const active = await prisma.work_items.findFirst({
+		where: {
+			kind: "task",
+			status: "active",
+			kind_data: { path: ["lane", "session"], equals: session },
+		},
+		// Deterministic by oldest. An unordered findFirst returns whichever row
+		// Postgres happens to hand back, so with two parents for one lane (the
+		// bindLane race, below) one turn wrote the lane's todos under parent A
+		// and the next read parent B and found nothing — the lane's task list
+		// appeared to empty itself, and the watchdog accused lanes that were
+		// holding a populated list. Migration 109 makes the duplicate
+		// unwritable; this makes the read stable regardless.
+		orderBy: { created_at: "asc" },
+	});
+	if (active) return active;
+
+	// FALL BACK TO AN ARCHIVED PARENT FOR THE SAME SESSION.
+	//
+	// Closing a run archives the lane's parent (close-run.ts) specifically to
+	// drop it from the active match set above. That is correct when the LANE is
+	// gone, and wrong whenever the run record closes while the lane keeps
+	// running — which happens on a tmux-server restart (runs are reaped, panes
+	// are restored) and whenever an orchestrator closes a run on a stale read.
+	// The lane then has a full task list that this function cannot see, so
+	// callers mint a FRESH parent, the old list is orphaned, and the compliance
+	// watchdog reports "working with NO task list" at a lane holding 85 tasks.
+	// That is the "KNOWN ADJACENT DEFECT" recorded on the lane-working-has-task-list
+	// guard row, observed live 2026-07-31.
+	//
+	// Safe because a session id is minted per lane spawn and never reused, so an
+	// archived parent under this session belongs to THIS lane. Newest-first.
+	return prisma.work_items.findFirst({
+		where: {
+			kind: "task",
+			status: "archived",
+			kind_data: { path: ["lane", "session"], equals: session },
+		},
+		orderBy: { created_at: "desc" },
+	});
+}
+
+/**
+ * Resolve a lane's task by its AUTHORITATIVE work_item id — the id the spawn
+ * minted (createBriefTask) and exported into the pane as SCALA_LANE_WORK_ITEM.
+ *
+ * WHY this exists alongside the session resolution: readAssignedBrief used to
+ * resolve ONLY by kind_data.lane.session, which is written by the lane's OWN
+ * bindLane hook at boot. That bind is a fire-and-forget POST racing the brief
+ * read, so a fleet lane whose bind had not yet commit read "no task" and the
+ * self-brief hook silently exited 0 — absent-input-reads-as-success at the
+ * dispatch boundary (a lane booted, was told its brief was loaded, had none,
+ * ran nothing, and was archived having done nothing — measured 2026-08-02).
+ *
+ * The work_item id is known to the spawn before the lane even starts
+ * (mintBriefTask returns it; the spawn REFUSES if minting fails for a capture
+ * CLI), so resolving by it CANNOT race: the row exists because the spawn
+ * created it. The session bind stays for task-list writes (upsertFromTaskList)
+ * — it is no longer load-bearing for brief delivery. Any status is matched
+ * (active OR archived) because the brief is the brief regardless of the run's
+ * state — closing a run archives the task, not the brief.
+ */
+export async function resolveTaskById(prisma: Prisma, workItemId: string): Promise<WorkItem | null> {
+	return prisma.work_items.findFirst({
+		where: { id: workItemId, kind: "task" },
+	});
+}

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

@@ -0,0 +1,121 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The task-sync PROJECTION: how a CLI's task list maps onto `work_items` rows,
+ * and what reconciling one against the other should do.
+ *
+ * Split out of `task-sync-router.ts`, which had grown past the 1000-line budget
+ * and so could not be committed by anyone touching it. The seam is real rather
+ * than arbitrary: everything here is PURE and decides WHAT should change, while
+ * the router owns the ORPC surface and performs the writes. That is exactly why
+ * this half is directly testable with no database.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Checked against the 14 platform singletons and the package catalog
+ * — nothing generic to fold into, and the doctrine test fails: no unrelated app
+ * could install this unmodified, because every export is bound to the
+ * `work_items` schema and task-sync's own contract (STATUS_TO_WORK_ITEM encodes
+ * the work_items status enum, subtaskKey is this projection's key convention,
+ * planReconcile diffs against work_items subtask rows).
+ *
+ * The near-miss is worth naming so the next reader does not re-derive it: the
+ * SHAPE — diff a desired list against existing rows into create/update/delete —
+ * is generic, and `document-signing` is precedent for lifting a pure domain half
+ * out of service-boot into a package. It stays here because it has exactly one
+ * consumer; extracting it now would be speculative packaging, which
+ * platform-capabilities treats as drift. Revisit if a SECOND surface needs
+ * list-against-rows reconciliation — then the generic diff core (not the
+ * work_items-specific mapping) is what earns a package.
+ */
+import type { TaskListItem, WorkItem } from "./task-sync-router.ts";
+/** CLI task-list status → work_items.status. The canonical forward direction. */
+export declare const STATUS_TO_WORK_ITEM: Record<"completed" | "in_progress" | "pending", string>;
+export declare function normalizeStatus(s: string | null): TaskListItem["status"];
+/**
+ * Decide the status to WRITE for an existing row, given what the CLI list says.
+ *
+ * The CLI task list has no `blocked` state, so a blocked row round-trips as
+ * `pending` (via `normalizeStatus`, which collapses unknown/internal statuses)
+ * and then maps back to `todo` — silently destroying the block. That is not a
+ * cosmetic drift: the stop gate reads these rows, so un-blocking one re-blocks
+ * the LANE from stopping, and the lane's only apparent fix is to touch the list
+ * again, which destroys it again.
+ *
+ * A `todo` arriving from the CLI therefore carries NO information: it is what
+ * the projection emits for every status it cannot represent, not an assertion
+ * that the work became un-blocked. `in-progress` and `done` are different —
+ * those are real transitions the CLI CAN express, so they win normally.
+ *
+ * Measured 2026-07-30: a lane set a row to `blocked` with a named blocker, the
+ * next TaskUpdate reset it to `todo`, and the stop gate reported the lane
+ * unfinished again — three turns of ping-pong before the cause was found.
+ */
+export declare function resolveProjectedStatus(currentStatus: string | null | undefined, incomingStatus: string): string;
+export declare function subtaskKey(item: {
+    mark?: string;
+    content: string;
+    title: string;
+}): string;
+/**
+ * Pure decision for a TaskUpdate/TaskDelete: which existing subtask does this
+ * event address, and what should happen when none does. Extracted for the same
+ * reason planReconcile was — the handler should only EXECUTE, so the matching
+ * rule is unit-testable.
+ *
+ * Three resolutions:
+ *  - `update` — matched by mark, or (mark absent/unstamped) by exact title.
+ *  - `heal`   — nothing matched but the event carries a subject, so the row can
+ *               be reconstructed. Covers a TaskCreate that silently produced no
+ *               subtask, which previously orphaned the task forever.
+ *  - `discard` — nothing matched and there is no subject to rebuild a title from.
+ *
+ * Measured 2026-07-28: marks "1" and "3" were stamped for one lane while mark
+ * "2" was never written at all, and every later update for it was dropped as
+ * `no-matching-subtask` — 26 of 30 tasksync discards in six hours, across seven
+ * distinct lane sessions, were that one reason.
+ */
+export declare function resolveTaskUpdateTarget(existing: Array<{
+    id: string;
+    title: string;
+    kind_data?: Record<string, unknown> | null;
+}>, evt: {
+    taskId: string;
+    subject?: string;
+}): {
+    op: "update";
+    id: string;
+} | {
+    op: "heal";
+    title: string;
+} | {
+    op: "discard";
+};
+/**
+ * Pure reconciliation plan: given the lane's EXISTING subtasks and its INCOMING
+ * (current) task list, compute the create/update/delete ops that make the
+ * subtask set match the list — WITHOUT touching prisma. Extracted so the
+ * matching/status/positioning logic is unit-testable (the handler only executes
+ * the plan). Matching is by stable mark when the CLI provides one, else by
+ * content. Position follows incoming index, so a reorder is an update.
+ */
+export interface ReconcilePlan {
+    toCreate: Array<{
+        content: string;
+        status: string;
+        completed: boolean;
+        position: string;
+        kind_data: Record<string, unknown>;
+    }>;
+    toUpdate: Array<{
+        id: string;
+        content: string;
+        status: string;
+        completed: boolean;
+        position: string;
+        kind_data: Record<string, unknown>;
+    }>;
+    toDelete: string[];
+}
+export declare function planReconcile(existing: WorkItem[], incoming: TaskListItem[], source?: string): ReconcilePlan;