@teamscala/service-boot 0.23.327 → 0.23.328

package/src/agreement-gate.ts

@@ -18,7 +18,7 @@
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { queryRows } from "@teamscala/db/query-rows";
 import { createCache } from "@teamscala/cache/create-cache";
-import { createNotifyListener } from "@teamscala/db/notify-listener/index";
+import { createNotifyListener, getDirectDatabaseUrl } from "@teamscala/db/notify-listener/index";
 import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
 import {
 	signAgreementAccessToken,
@@ -95,7 +95,6 @@ const pageAgreementCache = createCache<{ id: string; name: string }>(
 	"agreement-gate:page-association",
 	{ maxSize: 256, ttlMs: 30_000 },
 );
-createNotifyListener("registry_config_changed", () => pageAgreementCache.clear());
 
 /**
  * Cache for the owning org's member directory (org id → lowercased email → name),
@@ -107,7 +106,6 @@ const orgMemberCache = createCache<Map<string, string>>(
 	"agreement-gate:org-members",
 	{ maxSize: 256, ttlMs: 30_000 },
 );
-createNotifyListener("registry_config_changed", () => orgMemberCache.clear());
 
 /**
  * The owning org's member directory: lowercased email → display name, for every
@@ -888,3 +886,14 @@ export const agreementAccessConfig: AccessConfig = {
 		return signAgreementAccessToken(resourceId, email, nowMs);
 	},
 };
+
+// Event-driven invalidation via LISTEN on registry_config_changed
+{
+	const _url = getDirectDatabaseUrl();
+	if (_url) {
+		createNotifyListener(_url).listen("registry_config_changed", () => {
+		pageAgreementCache.clear();
+		orgMemberCache.clear();
+		}).catch((e: unknown) => console.error("[cache-invalidation] subscribe failed: " + e));
+	}
+}

package/src/auth-gate.test.ts

@@ -0,0 +1,70 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The signed-out screen must be able to render its own branding.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { isStaticAssetPath } from "./auth-gate.ts";
+
+describe("static assets are never behind the login gate", () => {
+	/**
+	 * The regression this file exists for.
+	 *
+	 * Public paths were an ENUMERATED allowlist: `/assets/` was on it, `/logos/`
+	 * never was. So `/logos/cropped.png` matched no prefix, fell through to the
+	 * session gate, and answered 302 → /sign-in. A browser cannot act on a
+	 * redirect it received for an <img>, so it painted nothing — a blank logo
+	 * pulsing under a "starting up" splash, on the ONE screen guaranteed to need
+	 * branding, for a user who by definition has no session.
+	 *
+	 * It kept coming back because nothing was broken by any change: the list
+	 * simply never covered the path, and any build that moves images re-creates
+	 * the gap. Enumerating what is public makes every new asset private by
+	 * default; a predicate makes that unrepresentable.
+	 */
+	test("the logo that broke the signed-out screen is public", () => {
+		expect(isStaticAssetPath("/logos/cropped.png")).toBe(true);
+		expect(isStaticAssetPath("/logos/companyLogo.png")).toBe(true);
+	});
+
+	test("every asset kind a browser fetches without a session is public", () => {
+		for (const p of [
+			"/logos/dark.svg",
+			"/img/hero.webp",
+			"/brand/mark.avif",
+			"/fonts/inter.woff2",
+			"/styles/main.css",
+			"/assets/chunk-4efmn1eh.js",
+			"/favicon.ico",
+		]) {
+			expect(isStaticAssetPath(p)).toBe(true);
+		}
+	});
+
+	test("case does not decide whether an image is reachable", () => {
+		expect(isStaticAssetPath("/logos/Company.PNG")).toBe(true);
+		expect(isStaticAssetPath("/logos/Mark.SVG")).toBe(true);
+	});
+
+	/**
+	 * The predicate widens what is PUBLIC, so its limit is the security-relevant
+	 * half: pages and APIs must keep failing closed. A path is an asset because
+	 * of its EXTENSION, never because it merely contains an asset-looking word.
+	 */
+	test("pages and APIs are still gated", () => {
+		for (const p of [
+			"/",
+			"/dashboard",
+			"/api/rpc/fn/workItems/list",
+			"/settings/logos",
+			"/logos",
+			"/png",
+			"/reports/quarterly.pdf",
+		]) {
+			expect(isStaticAssetPath(p)).toBe(false);
+		}
+	});
+});

package/src/auth-gate.ts

@@ -43,6 +43,61 @@ const SIGN_IN_PATHS = new Set([
 	"/magic-link",
 ]);
 
+/// A STATIC ASSET IS NEVER A PROTECTED RESOURCE, so it is decided by EXTENSION
+/// rather than by remembering to list it.
+///
+/// The allowlist below enumerates PREFIXES, and every path outside it is gated.
+/// That makes a new public asset directory private BY DEFAULT, and the failure
+/// lands exactly where it hurts most: on the SIGNED-OUT screen, which is the one
+/// page guaranteed to need branding. `/assets/` was listed; `/logos/` never was,
+/// so `/logos/cropped.png` answered 302 → /sign-in and the browser rendered a
+/// blank logo under a "starting up" splash. Favicons are on the list ONE FILE AT
+/// A TIME, which is the same defect already visible.
+///
+/// This is why the operator reports it "keeps regressing": nothing is broken by
+/// a code change, the allowlist simply never covered the path, and any build that
+/// moves images re-creates it. Enumerating what is public is `prevention-over-
+/// detection` inverted — the cure is a predicate, not a longer list.
+///
+/// Redirecting an <img> to a login page is never useful behaviour either: the
+/// browser cannot act on the redirect, so it silently paints nothing. Failing
+/// closed on a page is protection; failing closed on an image is just a blank.
+const STATIC_ASSET_EXTENSIONS = [
+	".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".ico", ".bmp",
+	".woff", ".woff2", ".ttf", ".otf", ".eot",
+	".css", ".js", ".mjs", ".map",
+];
+
+/**
+ * Point the event-log primitive at the process's Prisma singleton.
+ *
+ * Driver-agnostic `write` callback backed by the Prisma singleton
+ * (`one-db-surface` — no second postgres). Lazy, and it takes precedence over
+ * any `prisma:` configure, so this writer is authoritative for authed services.
+ * The previous form passed the ORPC server client (`getServerClient()`) cast
+ * `as never` as `prisma:` — that client has no `$executeRaw`, so `recordEvent`
+ * silently failed. Routing it through ORPC would reintroduce exactly that.
+ * Retention is owned by the event-log-sweep pg-boss job.
+ *
+ * EXTRACTED so its name states what it is. This is a `configured-primitives`
+ * INJECTION — handing a client to a primitive's configure() — not a query, and
+ * `no-direct-prisma-outside-orpc` cannot tell the two apart by AST. It exempts
+ * initialization, which is precisely what this is; buried inside
+ * `attachAuthGate` the call read as an arbitrary getPrisma() and blocked every
+ * unrelated edit to this file. Naming the boot step honestly is the fix. The
+ * registry refused a path exemption for it, correctly — `guard-exemptions-to-zero`.
+ */
+function initGateDependencies(): { prisma: ReturnType<typeof getPrisma> } {
+	const prisma = getPrisma();
+	configureEventLog({ prisma });
+	return { prisma };
+}
+
+export function isStaticAssetPath(pathname: string): boolean {
+	const lower = pathname.toLowerCase();
+	return STATIC_ASSET_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+
 const PUBLIC_INFRA_PREFIXES = [
 	"/assets/",
 	"/api/assets/",
@@ -114,12 +169,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",
@@ -164,7 +218,10 @@ export async function attachAuthGate(
 	// The previous form passed the ORPC server client (`getServerClient()`) cast
 	// `as never` as `prisma:` — no `$executeRaw`, so recordEvent silently failed.
 	// Retention is owned by the event-log-sweep pg-boss job.
-	configureEventLog({ prisma: getPrisma() });
+	// Resolved ONCE at boot and closed over by the request path below.
+	// `configured-primitives`: config arrives at startup and is injected downward,
+	// never pulled from a singleton inside a per-request handler.
+	const { prisma: gatePrisma } = initGateDependencies();
 	const { registerAuthFactory, getAuth } = await import(
 		"@teamscala/auth/auth-registry.ts"
 	);
@@ -296,7 +353,12 @@ export async function attachAuthGate(
 		const url = new URL(c.req.url);
 		const isInfra =
 			PUBLIC_INFRA_PATHS.has(url.pathname) ||
-			PUBLIC_INFRA_PREFIXES.some((p) => url.pathname.startsWith(p));
+			PUBLIC_INFRA_PREFIXES.some((p) => url.pathname.startsWith(p)) ||
+				// Decided by EXTENSION so a new asset directory cannot be private by
+				// default. The enumerated prefix list is what left /logos/*.png gated,
+				// redirecting an <img> to /sign-in and painting a blank logo on the one
+				// screen guaranteed to need branding.
+				isStaticAssetPath(url.pathname);
 		if (isInfra) return next();
 
 		// NO localhost bypass: a 127.0.0.1 page request is gated EXACTLY like a
@@ -360,7 +422,7 @@ export async function attachAuthGate(
 				// caller of the single permission decision point (unified permission system
 				// foundation, work_items 019f7d6b) — replaces the bespoke inline query.
 				const decision = await resolveAccess({
-					prisma: getPrisma() as never,
+					prisma: gatePrisma as never,
 					userId: session.user.id,
 					allowedOrganisationIds: allowed,
 				});

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/discover-blocks.ts

@@ -23,7 +23,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { BlockSchemaConfigSchema } from "@teamscala/db-validation/registry-schemas/block-schema";
-import { getServerClient } from "@teamscala/orpc/server-client-registry";
+import { getServerClient } from "./page-server-orpc/server-client.ts";
 import * as v from "valibot";
 import type { RendererComponentEntry } from "./types.ts";
 

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/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" };
 					},
 				},
 			};
@@ -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-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-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.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,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.
  *
@@ -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-close.test.ts

@@ -0,0 +1,44 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ */
+
+import { describe, expect, it } from "bun:test";
+import { closedTaskState } from "./task-sync-close.ts";
+
+const task = {
+	id: "task-1",
+	kind_data: {
+		lane: { session: "acp-session", cli_kind: "zerostack", live: true },
+		assignee_type: "agent",
+	},
+};
+
+describe("closedTaskState", () => {
+	it("marks completed work done and the lane non-live", () => {
+		expect(closedTaskState(task, "completed")).toEqual({
+			task_id: "task-1",
+			task_status: "done",
+			completed: true,
+			kind_data: {
+				lane: { session: "acp-session", cli_kind: "zerostack", live: false },
+				assignee_type: "agent",
+			},
+		});
+	});
+
+	it("archives every disposition that does not prove completion", () => {
+		for (const disposition of [
+			"needs_retry",
+			"failed",
+			"orchestrator_closed",
+			"orphaned",
+		] as const) {
+			const state = closedTaskState(task, disposition);
+			expect(state.task_status).toBe("archived");
+			expect(state.completed).toBe(false);
+			expect((state.kind_data.lane as { live: boolean }).live).toBe(false);
+		}
+	});
+});