@teamscala/service-boot 0.23.333 → 0.23.335

package/src/fn-routers/index.ts

@@ -37,6 +37,7 @@ import { tasksRouter } from "./tasks-router.ts";
 import { userPreferencesRouter } from "./user-preferences-router.ts";
 import { userPreferencesRouter as portalPreferencesRouter } from "../page-server-orpc/user-preferences-router.ts";
 import { workItemsRouter } from "./work-items-router.ts";
+import { orchestratorRegistrationRouter } from "./orchestrator-registration-router.ts";
 
 export function registerFnRouters(): void {
 	registerCustomRouter("fn", {
@@ -53,6 +54,7 @@ export function registerFnRouters(): void {
 		tasks: tasksRouter,
 		taskSync: taskSyncRouter,
 		workItems: workItemsRouter,
+		orchestratorRegistration: orchestratorRegistrationRouter,
 		userPreferences: userPreferencesRouter,
 		portalPreferences: portalPreferencesRouter,
 		plans: plansRouter,

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

@@ -0,0 +1,46 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * One transaction for the permanent Orchestrator registration. Database
+ * uniqueness is the correctness boundary; every identity row is upserted
+ * inside one transaction and callers cannot supply a project/session id.
+ */
+import { type Context } from "./auth-router.ts";
+import * as v from "valibot";
+declare const input: v.ObjectSchema<{
+    readonly runtime_slug: v.StringSchema<undefined>;
+}, undefined>;
+export type OrchestratorRegistrationRequest = v.InferOutput<typeof input>;
+export declare function ensureOrchestratorRegistration(request: OrchestratorRegistrationRequest, context: Context): Promise<{
+    projectId: string;
+    taskId: string;
+    sessionId: string;
+    runtime: string;
+    pickerOptionSlug: 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, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, v.ObjectSchema<{
+        readonly runtime_slug: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        projectId: string;
+        taskId: string;
+        sessionId: string;
+        runtime: string;
+        pickerOptionSlug: string | undefined;
+    }, {
+        projectId: string;
+        taskId: string;
+        sessionId: string;
+        runtime: string;
+        pickerOptionSlug: string | undefined;
+    }>, Record<never, never>, Record<never, never>>;
+};
+export {};

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

@@ -0,0 +1,63 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * One transaction for the permanent Orchestrator registration. Database
+ * uniqueness is the correctness boundary; every identity row is upserted
+ * inside one transaction and callers cannot supply a project/session id.
+ */
+import { authed, type Context } from "./auth-router.ts";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import type { PrismaClient } from "@teamscala/db/client";
+import * as v from "valibot";
+
+const input = v.object({ runtime_slug: v.string() });
+const registryConfig = v.looseObject({
+	enabled: v.optional(v.boolean()), model: v.optional(v.string()), reasoning_effort: v.optional(v.string()), picker_option_slug: v.optional(v.string()),
+});
+
+export type OrchestratorRegistrationRequest = v.InferOutput<typeof input>;
+
+export async function ensureOrchestratorRegistration(
+	request: OrchestratorRegistrationRequest,
+	context: Context,
+) {
+	const runtime = await loadRegistryConfig("agent_runtime", request.runtime_slug, registryConfig);
+	if (runtime.enabled === false || runtime.model !== "gpt-5.6-sol" || runtime.reasoning_effort !== "high" || !runtime.picker_option_slug) throw new Error("requested runtime is not the registry-backed Sol High Orchestrator runtime");
+	const user = context.user as { id: string; name?: string | null; displayName?: string | null; organisationId?: string | null };
+	const organisationId = context.orgId || user.organisationId;
+	if (!organisationId) throw new Error("Orchestrator registration requires an organisation");
+	return await (context.prisma as PrismaClient).$transaction(async (tx) => {
+				const initiative = await tx.work_items.findFirst({ where: { organisation_id: organisationId, kind: "initiative", kind_data: { path: ["tree"], equals: "agent_work" } } });
+				if (!initiative) throw new Error("agent-work initiative is not registered");
+				const developerName = user.displayName?.trim() || user.name?.trim() || "Developer";
+				const project = await tx.work_items.upsert({
+					where: { organisation_id_parent_id_assignee_id: { organisation_id: organisationId, parent_id: initiative.id, assignee_id: user.id } },
+					create: { kind: "project", parent_id: initiative.id, organisation_id: organisationId, title: `Developer session — ${developerName}`, owner_id: user.id, assignee_id: user.id, created_by: user.id, kind_data: { project_type: "developer_session" } },
+					update: { title: `Developer session — ${developerName}`, owner_id: user.id, assignee_id: user.id },
+				});
+				await tx.work_item_roles.upsert({ where: { work_item_id_user_id_role: { work_item_id: project.id, user_id: user.id, role: "assignee" } }, create: { work_item_id: project.id, user_id: user.id, role: "assignee", organisation_id: organisationId, created_by: user.id }, update: {} });
+				const task = await tx.work_items.upsert({
+					where: { parent_id_title: { parent_id: project.id, title: "Orchestrator" } },
+					create: { kind: "task", parent_id: project.id, organisation_id: organisationId, title: "Orchestrator", owner_id: user.id, assignee_id: user.id, created_by: user.id },
+					update: { owner_id: user.id, assignee_id: user.id },
+				});
+				const session = await tx.cli_sessions.upsert({
+					where: { work_item_id: task.id },
+					create: { authority: "operator", role: "orchestrator", cli_kind: "codex", picker_option_slug: runtime.picker_option_slug, runtime_slug: request.runtime_slug, provider: "codex", model: runtime.model, source_adapter: "orchestrator", label: "Orchestrator", lifecycle_state: "registering", host_route: {}, restore_metadata: {}, adapter_metadata: { project_id: project.id, work_item_id: task.id }, work_item_id: task.id },
+					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 } });
+				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 };
+			});
+}
+
+export const orchestratorRegistrationRouter = {
+	ensure: authed.input(input).handler(async ({ input: request, context }) => {
+		return ensureOrchestratorRegistration(request, context);
+	}),
+};

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

@@ -0,0 +1,49 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Real database concurrency acceptance for the canonical developer-session
+ * registration. Run with PM_FLEET_LIVE_TEST=1 and a PM_FLEET_TEST_USER_ID
+ * (plus PM_FLEET_TEST_ORG_ID when the user has more than one membership).
+ */
+import { describe, expect, it } from "bun:test";
+import { createDbClient } from "@teamscala/db/create-db-client";
+import { registerPrismaClient } from "@teamscala/db/prisma-registry";
+import { ensureOrchestratorRegistration } from "./orchestrator-registration-router.ts";
+import type { Context } from "./auth-router.ts";
+
+const live = process.env.PM_FLEET_LIVE_TEST === "1";
+
+describe.skipIf(!live)("canonical Orchestrator registration — live database", () => {
+	it("concurrent callers converge on one project, task, comment, runtime, transition, and spawn intent", async () => {
+		const userId = process.env.PM_FLEET_TEST_USER_ID;
+		if (!userId) throw new Error("PM_FLEET_TEST_USER_ID is required for the live concurrency acceptance");
+		const db = await createDbClient({ serviceName: "service-boot-pm-fleet-live", maxConnections: 10 });
+		try {
+			registerPrismaClient(db.prisma as never);
+			const user = await db.prisma.user.findUniqueOrThrow({ where: { id: userId }, select: { id: true, name: true } });
+			const organisationId = process.env.PM_FLEET_TEST_ORG_ID;
+			if (!organisationId) throw new Error("PM_FLEET_TEST_ORG_ID is required for the live concurrency acceptance");
+			const context: Context = { user: { id: user.id, name: user.name, organisationId }, orgId: organisationId, prisma: db.prisma, headers: new Headers() };
+			const results = await Promise.all(Array.from({ length: 8 }, () => ensureOrchestratorRegistration({ runtime_slug: "codex-acp" }, context)));
+			const projectIds = new Set(results.map((result) => result.projectId));
+			const taskIds = new Set(results.map((result) => result.taskId));
+			const sessionIds = new Set(results.map((result) => result.sessionId));
+			expect(projectIds.size).toBe(1);
+			expect(taskIds.size).toBe(1);
+			expect(sessionIds.size).toBe(1);
+			const projectId = results[0]?.projectId;
+			const taskId = results[0]?.taskId;
+			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);
+			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);
+		} finally {
+			await db.disconnect();
+		}
+	});
+});

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

@@ -300,6 +300,8 @@ export declare const createBriefTaskHandler: import("@orpc/server").DecoratedPro
     orgId: string | null | undefined;
 }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
     work_item_id: string;
+    comment_id: string;
 }, {
     work_item_id: string;
+    comment_id: string;
 }>, Record<never, never>, Record<never, never>>;

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

@@ -49,7 +49,7 @@ function fakePrisma(overrides: { platformOrg?: string } = {}) {
 				comments: {
 					create: async (a: { data: Record<string, unknown> }) => {
 						calls.push({ workItem: null, comment: a.data });
-						return a.data;
+						return { ...a.data, id: "comment-new-1" };
 					},
 				},
 			};

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

@@ -181,7 +181,7 @@ export async function createTaskWithBriefComment(
 	}).$transaction(async (tx) => {
 		const t = tx as {
 			work_items: { create: (a: unknown) => Promise<WorkItem> };
-			comments: { create: (a: unknown) => Promise<unknown> };
+			comments: { create: (a: unknown) => Promise<{ id: string }> };
 		};
 		const task = await t.work_items.create({
 			data: {
@@ -203,14 +203,14 @@ export async function createTaskWithBriefComment(
 			},
 		});
 		// The description IS the first comment IS the brief — one write, one source.
-		await t.comments.create({
+		const firstComment = await t.comments.create({
 			data: {
 				work_item_id: task.id,
 				content: input.description,
 				user_id: userId,
 			},
 		});
-		return task;
+		return { ...task, first_comment_id: firstComment.id } as WorkItem & { first_comment_id: string };
 	});
 }
 
@@ -471,7 +471,7 @@ export const createBriefTaskHandler = authed.handler(async ({ input, context })
 			},
 			userId,
 		);
-		return { work_item_id: task.id };
+		return { work_item_id: task.id, comment_id: (task as WorkItem & { first_comment_id: string }).first_comment_id };
 	} catch (err) {
 		// oRPC's default swallows a handler throw into a generic 500 with no stack;
 		// emit it so a mint failure is diagnosable, not a black box

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.
  *
@@ -56,20 +56,20 @@ export type BriefReadStatus = "ready" | "empty_brief" | "no_comment" | "unbound"
  */
 export declare function shapeBriefResponse(task: {
     id: string;
-} | null, comment: Pick<CommentRow, "content" | "created_at"> | null): {
+} | null, comment: Pick<CommentRow, "id" | "content" | "created_at"> | null): {
     work_item_id: string | null;
+    comment_id: string | null;
     brief: string | null;
     comment_created_at: string | null;
     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
@@ -85,11 +85,13 @@ export declare const readAssignedBriefHandler: import("@orpc/server").DecoratedP
     orgId: string | null | undefined;
 }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
     work_item_id: string | null;
+    comment_id: string | null;
     brief: string | null;
     comment_created_at: string | null;
     status: BriefReadStatus;
 }, {
     work_item_id: string | null;
+    comment_id: string | null;
     brief: string | null;
     comment_created_at: string | null;
     status: BriefReadStatus;

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

@@ -5,19 +5,20 @@
  *
  * 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)", () => {
 		// A lane with no resolvable task has no brief — null, never an empty fake.
 		// status:"unbound" is the signal a non-fleet lane no-ops on and a fleet
 		// lane (which resolves by work_item_id, so cannot reach this) never sees.
-		expect(shapeBriefResponse(null, { content: "x", created_at: new Date() })).toEqual({
+		expect(shapeBriefResponse(null, { id: "c-0", content: "x", created_at: new Date() })).toEqual({
 			work_item_id: null,
+			comment_id: null,
 			brief: null,
 			comment_created_at: null,
 			status: "unbound",
@@ -30,6 +31,7 @@ describe("shapeBriefResponse (no verdict from no data)", () => {
 		// is the broken state a fleet lane halts on rather than reading as success.
 		expect(shapeBriefResponse({ id: "task-1" }, null)).toEqual({
 			work_item_id: "task-1",
+			comment_id: null,
 			brief: null,
 			comment_created_at: null,
 			status: "no_comment",
@@ -40,14 +42,16 @@ describe("shapeBriefResponse (no verdict from no data)", () => {
 		// The comment exists but its content is empty/whitespace — "loads it
 		// empty". A fleet lane whose spawn minted a task MUST have a non-empty
 		// brief, so a blank comment is a defect the hook halts on, not a success.
-		expect(shapeBriefResponse({ id: "task-2" }, { content: "   ", created_at: new Date() })).toEqual({
+		expect(shapeBriefResponse({ id: "task-2" }, { id: "c-2", content: "   ", created_at: new Date() })).toEqual({
 			work_item_id: "task-2",
+			comment_id: "c-2",
 			brief: null,
 			comment_created_at: null,
 			status: "empty_brief",
 		});
-		expect(shapeBriefResponse({ id: "task-2b" }, { content: "", created_at: new Date() })).toEqual({
+		expect(shapeBriefResponse({ id: "task-2b" }, { id: "c-2b", content: "", created_at: new Date() })).toEqual({
 			work_item_id: "task-2b",
+			comment_id: "c-2b",
 			brief: null,
 			comment_created_at: null,
 			status: "empty_brief",
@@ -56,8 +60,9 @@ describe("shapeBriefResponse (no verdict from no data)", () => {
 
 	it("returns the comment content + ISO created_at + status ready for a resolved task+comment", () => {
 		const ts = new Date("2026-08-01T03:24:00.000Z");
-		expect(shapeBriefResponse({ id: "task-7" }, { content: "Do the thing", created_at: ts })).toEqual({
+		expect(shapeBriefResponse({ id: "task-7" }, { id: "c-7", content: "Do the thing", created_at: ts })).toEqual({
 			work_item_id: "task-7",
+			comment_id: "c-7",
 			brief: "Do the thing",
 			comment_created_at: "2026-08-01T03:24:00.000Z",
 			status: "ready",
@@ -66,19 +71,18 @@ describe("shapeBriefResponse (no verdict from no data)", () => {
 
 	it("serializes the comment created_at deterministically (Date → ISO)", () => {
 		const ts = new Date(0);
-		const out = shapeBriefResponse({ id: "t" }, { content: "c", created_at: ts });
+		const out = shapeBriefResponse({ id: "t" }, { id: "c", content: "c", created_at: ts });
 		expect(out.comment_created_at).toBe("1970-01-01T00:00:00.000Z");
 	});
 });
 
-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");
 	});
 
@@ -106,12 +110,12 @@ 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");
+		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.
  *
@@ -61,25 +61,27 @@ export type BriefReadStatus = "ready" | "empty_brief" | "no_comment" | "unbound"
  */
 export function shapeBriefResponse(
 	task: { id: string } | null,
-	comment: Pick<CommentRow, "content" | "created_at"> | null,
+	comment: Pick<CommentRow, "id" | "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, brief: null, comment_created_at: null, status: "unbound" };
+		return { work_item_id: null, comment_id: null, brief: null, comment_created_at: null, status: "unbound" };
 	}
 	if (!comment) {
-		return { work_item_id: task.id, brief: null, comment_created_at: null, status: "no_comment" };
+		return { work_item_id: task.id, comment_id: null, 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, brief: null, comment_created_at: null, status: "empty_brief" };
+		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,
+		comment_id: comment.id,
 		brief: text,
 		comment_created_at:
 			comment.created_at instanceof Date ? comment.created_at.toISOString() : String(comment.created_at),
@@ -88,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> {
@@ -108,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" }],
 	});
 }
 
@@ -145,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-router.d.ts

@@ -324,11 +324,13 @@ export declare const taskSyncRouter: {
         orgId: string | null | undefined;
     }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
         work_item_id: string | null;
+        comment_id: string | null;
         brief: string | null;
         comment_created_at: string | null;
         status: import("./task-sync-brief.ts").BriefReadStatus;
     }, {
         work_item_id: string | null;
+        comment_id: string | null;
         brief: string | null;
         comment_created_at: string | null;
         status: import("./task-sync-brief.ts").BriefReadStatus;
@@ -342,8 +344,10 @@ export declare const taskSyncRouter: {
         orgId: string | null | undefined;
     }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
         work_item_id: string;
+        comment_id: string;
     }, {
         work_item_id: string;
+        comment_id: string;
     }>, Record<never, never>, Record<never, never>>;
     /** RUNTIME→DB lifecycle close: mark lane.live=false and reconcile task status before the ACP owner releases the session. */
     closeLane: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {