@teamscala/service-boot 0.23.334 → 0.23.336

package/src/auth-gate.ts

@@ -114,12 +114,11 @@ const PUBLIC_INFRA_PATHS = new Set([
 	// the other dev-host infra reads.
 	"/api/fleet/claude-sessions",
 	// /api/fleet/ingest-event receives parsed lane-action events
-	// (message.part.updated etc.) from the cli-session Claude transcript-tail — a
+	// (message.part.updated etc.) from the cli-session transcript-tail — a
 	// dev-host INTERNAL machine caller that POSTs with no session cookie, exactly
 	// like the lane-event hook. Without this exemption the page auth-gate 302s
 	// every POST and the lane's tool/text action stream never reaches the
-	// ingestEvent pipeline (fleet_run_events stays empty → the dashboard console
-	// shows only lifecycle lines, never the per-tab action feed). A first-class
+	// ingestEvent pipeline. A first-class
 	// api_route (sibling to lane-event); security is the handler's loopback gate
 	// on the platform's x-caller-remote-address (set by register-api-routes).
 	"/api/fleet/ingest-event",

package/src/build-client-assets.test.ts

@@ -167,7 +167,7 @@ describe("computeInputFingerprint", () => {
 	});
 
 	// Regression guard for the 2026-07-12 scala-agents stale-bundle bug. A boot
-	// that builds MID-INSTALL (package-poller restarts after writing the new
+	// that builds MID-INSTALL (dep-sync restarts after writing the new
 	// bun.lock but before node_modules extraction finishes) bakes OLD @teamscala/*
 	// JS while the lock-derived fingerprint records "current" — so every later
 	// restart recomputes the same fingerprint, skips the rebuild, and serves the

package/src/build-client-assets.ts

@@ -84,7 +84,7 @@ export async function readClientBuildStatus(
 
 // Single shared host lock serialising the heavy boot-time client build across
 // ALL kind:ui services (client-asset-builds-serialize-via-lock). A publish of a
-// widely-consumed package makes the package-poller restart every consumer at
+// widely-consumed package makes the dep-sync restart every consumer at
 // once; without this lock each one rebuilds its hydrate bundle + Tailwind CSS
 // simultaneously and N concurrent builds saturate the host (load 36, each ~15s
 // build starved to ~10min, services offline — 2026-06-13). The build sibling of

package/src/fn-routers/orchestrator-registration-router.d.ts

@@ -13,12 +13,24 @@ declare const input: v.ObjectSchema<{
     readonly runtime_slug: v.StringSchema<undefined>;
 }, undefined>;
 export type OrchestratorRegistrationRequest = v.InferOutput<typeof input>;
+export declare function buildOrchestratorSpawnPayload(input: {
+    workItemId: string;
+    launchCommentId: string;
+    cliSessionId: string;
+    slug: string;
+}): {
+    workItemId: string;
+    launchCommentId: string;
+    cliSessionId: string;
+    slug: string;
+};
 export declare function ensureOrchestratorRegistration(request: OrchestratorRegistrationRequest, context: Context): Promise<{
     projectId: string;
     taskId: string;
     sessionId: string;
+    launchCommentId: string;
     runtime: string;
-    pickerOptionSlug: string | undefined;
+    slug: string | undefined;
 }>;
 export declare const orchestratorRegistrationRouter: {
     ensure: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
@@ -33,14 +45,16 @@ export declare const orchestratorRegistrationRouter: {
         projectId: string;
         taskId: string;
         sessionId: string;
+        launchCommentId: string;
         runtime: string;
-        pickerOptionSlug: string | undefined;
+        slug: string | undefined;
     }, {
         projectId: string;
         taskId: string;
         sessionId: string;
+        launchCommentId: string;
         runtime: string;
-        pickerOptionSlug: string | undefined;
+        slug: string | undefined;
     }>, Record<never, never>, Record<never, never>>;
 };
 export {};

package/src/fn-routers/orchestrator-registration-router.ts

@@ -19,6 +19,20 @@ const registryConfig = v.looseObject({
 
 export type OrchestratorRegistrationRequest = v.InferOutput<typeof input>;
 
+export function buildOrchestratorSpawnPayload(input: {
+	workItemId: string;
+	launchCommentId: string;
+	cliSessionId: string;
+	slug: string;
+}) {
+	return {
+		workItemId: input.workItemId,
+		launchCommentId: input.launchCommentId,
+		cliSessionId: input.cliSessionId,
+		slug: input.slug,
+	};
+}
+
 export async function ensureOrchestratorRegistration(
 	request: OrchestratorRegistrationRequest,
 	context: Context,
@@ -49,10 +63,10 @@ export async function ensureOrchestratorRegistration(
 					update: { picker_option_slug: runtime.picker_option_slug, runtime_slug: request.runtime_slug, model: runtime.model, closed_at: null, lifecycle_state: "registering" },
 				});
 				const startupBrief = `You are the permanent Orchestrator for developer project “${project.title}” (${project.id}). Coordinate all work through the canonical work_items and comments surfaces. Every tab is a child task, every prompt and reply is a comment, and cli_sessions is runtime identity only. Dispatch implementation through the fleet and reconcile durable outcomes; never create a parallel task, message, or session source.`;
-				await tx.comments.upsert({ where: { work_item_id_system_key: { work_item_id: task.id, system_key: "orchestrator-startup" } }, update: {}, create: { work_item_id: task.id, content: startupBrief, system_key: "orchestrator-startup", user_id: user.id } });
+				const launchComment = await tx.comments.upsert({ where: { work_item_id_system_key: { work_item_id: task.id, system_key: "orchestrator-startup" } }, update: { source_cli_session_id: session.id, sender_role: "orchestrator", sender_name: "Orchestrator" }, create: { work_item_id: task.id, content: startupBrief, system_key: "orchestrator-startup", source_cli_session_id: session.id, sender_role: "orchestrator", sender_name: "Orchestrator" } });
 				await tx.cli_session_transitions.upsert({ where: { session_id_idempotency_key: { session_id: session.id, idempotency_key: `register:${project.id}` } }, create: { session_id: session.id, idempotency_key: `register:${project.id}`, from_state: null, to_state: "registering", trigger_event: "atomic-registration", metadata_json: { work_item_id: task.id } }, update: {} });
-				await tx.host_commands.upsert({ where: { command_idempotency_key: { command: "picker_spawn_tab", idempotency_key: `orchestrator-visible:${project.id}` } }, update: {}, create: { command: "picker_spawn_tab", idempotency_key: `orchestrator-visible:${project.id}`, payload: { workItemId: task.id, runtimeSlug: request.runtime_slug, pickerOptionSlug: runtime.picker_option_slug, visible: true }, originator: { role: "orchestrator", session_id: session.id } } });
-				return { projectId: project.id, taskId: task.id, sessionId: session.id, runtime: request.runtime_slug, pickerOptionSlug: runtime.picker_option_slug };
+				await tx.host_commands.upsert({ where: { command_idempotency_key: { command: "picker_spawn_tab", idempotency_key: `orchestrator-visible:${project.id}` } }, update: {}, create: { command: "picker_spawn_tab", idempotency_key: `orchestrator-visible:${project.id}`, payload: buildOrchestratorSpawnPayload({ workItemId: task.id, launchCommentId: launchComment.id, cliSessionId: session.id, slug: runtime.picker_option_slug }), originator: { role: "orchestrator", session_id: session.id } } });
+				return { projectId: project.id, taskId: task.id, sessionId: session.id, launchCommentId: launchComment.id, runtime: request.runtime_slug, slug: runtime.picker_option_slug };
 			});
 }
 

package/src/fn-routers/orchestrator-registration.live.test.ts

@@ -38,10 +38,31 @@ describe.skipIf(!live)("canonical Orchestrator registration — live database",
 			const sessionId = results[0]?.sessionId;
 			expect(await db.prisma.work_items.count({ where: { id: projectId, parent: { kind: "initiative", kind_data: { path: ["tree"], equals: "agent_work" } } } })).toBe(1);
 			expect(await db.prisma.work_items.count({ where: { id: taskId, parent_id: projectId, kind: "task", title: "Orchestrator" } })).toBe(1);
-			expect(await db.prisma.comments.count({ where: { work_item_id: taskId, system_key: "orchestrator-startup" } })).toBe(1);
+			const startupComments = await db.prisma.comments.findMany({
+				where: { work_item_id: taskId, system_key: "orchestrator-startup" },
+				select: { id: true, source_cli_session_id: true, sender_role: true, sender_name: true },
+			});
+			expect(startupComments).toHaveLength(1);
+			expect(startupComments[0]).toMatchObject({
+				id: results[0]?.launchCommentId,
+				source_cli_session_id: sessionId,
+				sender_role: "orchestrator",
+				sender_name: "Orchestrator",
+			});
 			expect(await db.prisma.cli_sessions.count({ where: { id: sessionId, work_item_id: taskId, role: "orchestrator", closed_at: null } })).toBe(1);
 			expect(await db.prisma.cli_session_transitions.count({ where: { session_id: sessionId, idempotency_key: `register:${projectId}` } })).toBe(1);
-			expect(await db.prisma.host_commands.count({ where: { command: "picker_spawn_tab", idempotency_key: `orchestrator-visible:${projectId}` } })).toBe(1);
+			const spawnIntents = await db.prisma.host_commands.findMany({
+				where: { command: "picker_spawn_tab", idempotency_key: `orchestrator-visible:${projectId}` },
+				select: { payload: true },
+			});
+			expect(spawnIntents).toHaveLength(1);
+				expect(spawnIntents[0]?.payload).toMatchObject({
+					workItemId: taskId,
+					launchCommentId: results[0]?.launchCommentId,
+					cliSessionId: sessionId,
+					slug: results[0]?.slug,
+				});
+				expect(Object.keys(spawnIntents[0]?.payload as Record<string, unknown>).sort()).toEqual(["cliSessionId", "launchCommentId", "slug", "workItemId"]);
 		} finally {
 			await db.disconnect();
 		}

package/src/fn-routers/orchestrator-registration.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "bun:test";
+import { buildOrchestratorSpawnPayload } from "./orchestrator-registration-router.ts";
+
+describe("orchestrator spawn intent", () => {
+	it("uses the generated Rust slug contract and carries no alternate launch input", () => {
+		const payload = buildOrchestratorSpawnPayload({
+			workItemId: "task-1",
+			launchCommentId: "comment-1",
+			cliSessionId: "session-1",
+			slug: "codex-sol-acp-client",
+		});
+		expect(payload).toEqual({
+			workItemId: "task-1",
+			launchCommentId: "comment-1",
+			cliSessionId: "session-1",
+			slug: "codex-sol-acp-client",
+		});
+		expect(payload).not.toHaveProperty("pickerOptionSlug");
+		expect(payload).not.toHaveProperty("initialPrompt");
+		expect(payload).not.toHaveProperty("windowName");
+		expect(Object.keys(payload).sort()).toEqual(["cliSessionId", "launchCommentId", "slug", "workItemId"]);
+	});
+});

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

@@ -397,6 +397,7 @@ describe("buildAssignmentSpawnPayload (no keystroke brief — row-based self-bri
 		const out = buildAssignmentSpawnPayload(task, { slug: "cc-glm52" });
 		expect("initialPrompt" in out.payload).toBe(false);
 		expect(out.payload).not.toHaveProperty("initialPrompt");
+		expect("cliSessionId" in out.payload).toBe(false);
 	});
 
 	it("omits optional spawn fields when not supplied (no undefined keys)", () => {

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

@@ -21,7 +21,7 @@ mock.module("@teamscala/db/registry/platform", () => ({
 	getPlatformOrgId: () => "platform-org-test",
 }));
 
-const { resolveBindOrg, discardApplied, untrackedRunForPane } = await import(
+const { resolveBindOrg, discardApplied } = await import(
 	"./task-sync-router.ts"
 );
 
@@ -86,25 +86,25 @@ describe("lane task binding is deterministic and race-proof (source contract)",
 		expect(text).toContain("const winner = await resolveLaneTask(prisma, session)");
 	});
 
-	test("bindLane only fills an untracked run and preserves dispatched task identity", () => {
-		expect(untrackedRunForPane("tmux:%77")).toEqual({
-			pane: "tmux:%77",
-			state: { not: "closed" },
-			tracked_task_id: null,
-		});
+	test("bindLane leaves runtime identity to cli_sessions", async () => {
+		const text = await src.text();
+		const bindLane = text.slice(text.indexOf("bindLane:"), text.indexOf("upsertFromTaskList:"));
+		expect(bindLane).toContain("Runtime identity is owned by cli_sessions");
+		expect(bindLane).not.toContain("tracked_task_id");
+	});
+
+	test("task events resolve pane identity through cli_sessions", async () => {
+		const text = await src.text();
+		const resolver = text.slice(text.indexOf("async function resolveSessionFromPane"), text.indexOf("/** Resolve the task"));
+		expect(resolver).toContain("prisma.cli_sessions.findFirst");
+		expect(resolver).toContain('path: ["pane_id"]');
 	});
 
-	test("bindLane STEALS tracked_task_id before claiming (no two live runs share a task)", async () => {
+	test("readTaskList returns the checklist with evidence-derived progress", async () => {
 		const text = await src.text();
-		// The partial unique index fleet_agent_runs_one_active_run_per_task means a
-		// task is tracked by at most one LIVE run. Re-adoption on a new pane left the
-		// old run holding the task; claiming without first releasing it made the next
-		// state->active transition (upsertLaneRun's UPDATE) violate the index
-		// (P2002 -> the lane-event 500 + the lost run-link join). Release-then-claim
-		// steals it: only this lane's untracked run ends up with it.
-		expect(text).toContain("STEAL before CLAIM");
-		expect(text).toContain(
-			"tracked_task_id: taskId, state: { not: \"closed\" }",
-		);
+		const reader = text.slice(text.indexOf("readTaskList:"), text.indexOf("/**\n\t * DB→AGENT self-brief"));
+		expect(reader).toContain("deriveEvidenceProgress(rows, evidence)");
+		expect(reader).toContain("subtasks");
+		expect(reader).not.toContain("percentage from");
 	});
 });

package/src/fn-routers/task-sync-brief.d.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 LATEST comment.
+ * assigned to that session, and reads the brief from that task's FIRST 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;
@@ -34,7 +34,7 @@ import { type Context } from "./auth-router.ts";
  */
 export type BriefReadStatus = "ready" | "empty_brief" | "no_comment" | "unbound";
 /**
- * Shape the readAssignedBrief response from a resolved task + its latest
+ * Shape the readAssignedBrief response from a resolved task + its first
  * 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.
  *
@@ -64,13 +64,12 @@ export declare function shapeBriefResponse(task: {
     status: BriefReadStatus;
 };
 /**
- * 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".
+ * 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.
  */
-export declare function readLatestTaskComment(prisma: Prisma, workItemId: string): Promise<CommentRow | null>;
+export declare function readFirstTaskComment(prisma: Prisma, workItemId: string): Promise<CommentRow | null>;
 /**
  * readAssignedBrief ORPC handler. A lane's CLI extension calls this with its
  * own session id to pull its brief. Same transport as bindLane/readTaskList: the

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

@@ -5,11 +5,11 @@
  *
  * Unit tests for the self-brief leg: shapeBriefResponse (the pure
  * no-task/no-comment ⇒ nulls decision) + source-contract assertions that
- * readLatestTaskComment reads the LATEST comment and the handler resolves by
+ * readFirstTaskComment reads the FIRST launch comment and the handler resolves by
  * session. Covers `what-must-have-a-test` for the new procedure.
  */
 import { describe, it, expect } from "bun:test";
-import { shapeBriefResponse, readLatestTaskComment } from "./task-sync-brief.ts";
+import { shapeBriefResponse, readFirstTaskComment } from "./task-sync-brief.ts";
 
 describe("shapeBriefResponse (no verdict from no data)", () => {
 	it("classifies a missing task as unbound (work_item_id null)", () => {
@@ -76,14 +76,13 @@ describe("shapeBriefResponse (no verdict from no data)", () => {
 	});
 });
 
-describe("readAssignedBrief reads the LATEST comment (source contract)", () => {
+describe("readAssignedBrief reads the FIRST launch comment (source contract)", () => {
 	const briefSrc = Bun.file(new URL("./task-sync-brief.ts", import.meta.url).pathname);
 
-	it("queries comments newest-first by created_at on work_item_id", async () => {
-		// The comment IS the brief for a run; ordering by created_at desc makes the
-		// LATEST comment (this run's) the answer, never a stale prior-run comment.
+	it("queries comments oldest-first with an id tie-breaker", async () => {
+		// The first comment is immutable launch identity; later comments are dialogue.
 		const text = await briefSrc.text();
-		expect(text).toContain('orderBy: { created_at: "desc" }');
+		expect(text).toContain('orderBy: [{ created_at: "asc" }, { id: "asc" }]');
 		expect(text).toContain("work_item_id: workItemId");
 	});
 
@@ -111,12 +110,11 @@ describe("readAssignedBrief reads the LATEST comment (source contract)", () => {
 	});
 });
 
-describe("readLatestTaskComment is a single latest-comment read", () => {
+describe("readFirstTaskComment is a single deterministic launch-comment read", () => {
 	it("returns null when the prisma client has no comments model (feature-detect)", async () => {
-		// `comments` is a universal shared model, but the access is feature-detected
-		// like the fleet_agent_runs reads so a client without it degrades to "no
-		// brief" rather than throwing.
-		const out = await readLatestTaskComment({} as never, "task-1");
+		// `comments` is a universal shared model; a client without it degrades to
+		// "no brief" rather than throwing.
+		const out = await readFirstTaskComment({} as never, "task-1");
 		expect(out).toBe(null);
 	});
 });

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 LATEST comment.
+ * assigned to that session, and reads the brief from that task's FIRST 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 latest
+ * Shape the readAssignedBrief response from a resolved task + its first
  * 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.
  *
@@ -90,13 +90,12 @@ export function shapeBriefResponse(
 }
 
 /**
- * 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".
+ * 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.
  */
-export async function readLatestTaskComment(
+export async function readFirstTaskComment(
 	prisma: Prisma,
 	workItemId: string,
 ): Promise<CommentRow | null> {
@@ -110,7 +109,7 @@ export async function readLatestTaskComment(
 	if (!comments?.findFirst) return null;
 	return comments.findFirst({
 		where: { work_item_id: workItemId },
-		orderBy: { created_at: "desc" },
+		orderBy: [{ created_at: "asc" }, { id: "asc" }],
 	});
 }
 
@@ -147,6 +146,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 readLatestTaskComment(prisma, task.id);
+	const comment = await readFirstTaskComment(prisma, task.id);
 	return shapeBriefResponse(task, comment);
 });

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

@@ -3,59 +3,45 @@
  * @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).
+ * DB→AGENT task projection emission. A work_items change is delivered by one
+ * canonical comments row addressed to the active cli_sessions runtime; the
+ * database emission wakes that runtime adapter, which re-reads readTaskList.
+ * This module owns no pane transport, terminal fallback, or second message
+ * queue.
  */
-export interface TaskChangedEvent {
-    type: "orchestrator.message";
-    message: string;
-    fromOrchestratorId: string;
-    runId: string;
-    slotName: "cross-pane";
-    ts: number;
-    orchestratorSessionId: string;
+export interface TaskChangeComment {
+    work_item_id: string;
+    content: string;
+    system_key: string;
+    source_cli_session_id: string;
+    sender_role: "system";
+    sender_name: "TaskSync";
 }
-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>;
+export declare function buildTaskChangeComment(taskId: string, sessionId: string, eventKey?: string): TaskChangeComment;
+export interface TaskDispatchPrisma {
+    cli_sessions: {
+        findFirst(args: unknown): Promise<{
+            id: string;
+        } | null>;
+    };
+    comments: {
+        upsert(args: {
+            where: {
+                work_item_id_system_key: {
+                    work_item_id: string;
+                    system_key: string;
+                };
+            };
+            create: TaskChangeComment;
+            update: Record<string, never>;
+        }): Promise<{
+            id: string;
+        }>;
+    };
+}
+/** Write the durable task-change comment for the active runtime, if present. */
+export declare function notifyLaneOfTaskChange(prisma: TaskDispatchPrisma, taskId: string, eventKey?: string): Promise<{
+    delivered: boolean;
+    sessionId: string | null;
+    commentId: string | null;
+}>;

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

@@ -3,42 +3,60 @@
  * @status handwritten
  * @edit edit directly
  *
- * 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.
+ * Unit tests for the pure durable comment-payload builder in task-sync-dispatch.
+ * The runtime path writes this payload through the canonical comments model.
  */
 import { describe, it, expect } from "bun:test";
-import { buildTaskChangedEvent } from "./task-sync-dispatch.ts";
+import { buildTaskChangeComment, notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
 
-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");
-	});
+	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");
+		});
 
-	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("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("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);
+		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);
+		});
 	});
-});