@teamscala/service-boot 0.23.317 → 0.23.319

package/src/agreement-gate.ts

@@ -18,6 +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, getDirectDatabaseUrl } from "@teamscala/db/notify-listener/index";
 import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
 import {
 	signAgreementAccessToken,
@@ -885,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

@@ -20,7 +20,9 @@ import {
 	bindTaskToKnownSession,
 	buildAssignmentSpawnPayload,
 	resolveAssignOrg,
+	resolveBindAction,
 } from "./task-sync-assign.ts";
+import type { WorkItem } from "./task-sync-router.ts";
 
 /** A minimal fake prisma exposing only $transaction + the two creates the fn uses. */
 function fakePrisma(overrides: { platformOrg?: string } = {}) {
@@ -47,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" };
 					},
 				},
 			};
@@ -90,6 +92,10 @@ describe("assignTaskInput (incomplete task is unconstructible)", () => {
 		});
 		expect(out.success).toBe(true);
 	});
+
+	it("REJECTS the generic 'Lane' title (assignment mint — same gate as createBriefTask)", () => {
+		expect(v.safeParse(assignTaskInput, { name: "Lane", description: "d" }).success).toBe(false);
+	});
 });
 
 describe("createBriefTaskInput (the spawner's mint entry — incomplete task is unconstructible)", () => {
@@ -121,6 +127,31 @@ describe("createBriefTaskInput (the spawner's mint entry — incomplete task is
 		const out = v.safeParse(createBriefTaskInput, { name: "Explore", description: "d" });
 		expect(out.success).toBe(true);
 	});
+
+	// "Lane" is the generic sentinel a spawn that forgot to name its lane falls
+	// back to. A row titled "Lane" is spawn debris an orchestrator cannot
+	// attribute — rejected at the mint chokepoint so the malformed spawn is
+	// refused, never written (lanes-named-by-the-spawner).
+	it("REJECTS the generic 'Lane' title — spawn debris is unconstructible", () => {
+		expect(
+			v.safeParse(createBriefTaskInput, { name: "Lane", description: "d" }).success,
+		).toBe(false);
+	});
+
+	it("rejects 'Lane' case- and whitespace-insensitively", () => {
+		expect(
+			v.safeParse(createBriefTaskInput, { name: "  lane  ", description: "d" }).success,
+		).toBe(false);
+		expect(
+			v.safeParse(createBriefTaskInput, { name: "LANE", description: "d" }).success,
+		).toBe(false);
+	});
+
+	it("accepts a real work name (e.g. the lane's slot_name)", () => {
+		expect(
+			v.safeParse(createBriefTaskInput, { name: "Bus handlers", description: "d" }).success,
+		).toBe(true);
+	});
 });
 
 describe("createTaskWithBriefComment (atomic task + first comment = brief)", () => {
@@ -187,6 +218,7 @@ describe("createTaskWithBriefComment (atomic task + first comment = brief)", ()
 describe("adoptAssignmentTask (SessionStart adopts the pre-created task + ownership)", () => {
 	function fakeAdoptPrisma(existing: Record<string, unknown> | null) {
 		const updates: Array<{ id: string } & Record<string, unknown>> = [];
+		const updateManyCalls: unknown[] = [];
 		const prisma = {
 			work_items: {
 				findFirst: async () => existing,
@@ -195,9 +227,13 @@ describe("adoptAssignmentTask (SessionStart adopts the pre-created task + owners
 					updates.push(row);
 					return row;
 				},
+				updateMany: async (a: unknown) => {
+					updateManyCalls.push(a);
+					return { count: 0 };
+				},
 			},
 		};
-		return { prisma, updates };
+		return { prisma, updates, updateManyCalls };
 	}
 
 	it("writes the lane session onto the pre-created task AND sets assignee_id (ownership)", async () => {
@@ -224,12 +260,22 @@ describe("adoptAssignmentTask (SessionStart adopts the pre-created task + owners
 		expect(kd.lane.session).toBe("s");
 	});
 
-	it("REFUSES to steal a task another live session already owns", async () => {
-		const task = { id: "t", kind: "task", kind_data: { lane: { session: "someone-else" } } };
-		const { prisma, updates } = fakeAdoptPrisma(task);
-		const out = await adoptAssignmentTask(prisma as never, "t", { session: "s", pane: null });
-		expect(out).toBeNull();
-		expect(updates).toHaveLength(0);
+	it("RE-BINDS a task a stale session owns to the fresh lane (pane slot recovery)", async () => {
+		// Migration 109 makes (kind_data->'lane'->>'pane') unique WHERE active, so a
+		// re-spawn on a pane whose prior task is still active under a dead session
+		// cannot create a new task (P2002). adopt re-binds the assignment task to
+		// the fresh session + releases the stale pane slot first. A stale session
+		// is by definition dead, so the task belongs to whichever lane was
+		// dispatched to it — re-binding is correct recovery, not theft.
+		const task = { id: "t", kind: "task", kind_data: { lane: { session: "someone-else", pane: "tmux:%9" } } };
+		const { prisma, updates, updateManyCalls } = fakeAdoptPrisma(task);
+		const out = await adoptAssignmentTask(prisma as never, "t", { session: "fresh", pane: "tmux:%9" });
+		expect(out).not.toBeNull();
+		expect(updates).toHaveLength(1);
+		expect((updates[0].kind_data as { lane: { session: string } }).lane.session).toBe("fresh");
+		expect(updates[0].assignee_id).toBe("fresh");
+		// The stale pane slot was released before the re-bind (STEAL-before-CLAIM).
+		expect(updateManyCalls).toHaveLength(1);
 	});
 
 	it("re-adopts a task already bound to THIS session (idempotent re-bind)", async () => {
@@ -351,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)", () => {
@@ -366,3 +413,71 @@ describe("buildAssignmentSpawnPayload (no keystroke brief — row-based self-bri
 		expect(out.payload.idempotencyKey).toBe("k-1");
 	});
 });
+
+describe("resolveBindAction (a spawn that cannot bind fails loudly, never orphans)", () => {
+	// The `absent-input-reads-as-success` failure this closes: a spawn carried a
+	// workItemId the lane should adopt, but no task with that id exists. The old
+	// path silently created a NEW task, abandoning the spawn's referenced brief
+	// and binding the lane to an empty task it was never meant to own — an orphan
+	// an orchestrator cannot tell from real unowned work. bindLane now REFUSES on
+	// this outcome; this is the pure, unit-testable decision behind that refusal.
+	function taskRow(id: string): WorkItem {
+		return {
+			id,
+			kind: "task",
+			parent_id: null,
+			organisation_id: "org",
+			title: "T",
+			status: "active",
+			position: null,
+			completed: null,
+			kind_data: {},
+		};
+	}
+
+	it("uses the adopted task when adopt succeeds", () => {
+		const t = taskRow("t1");
+		const out = resolveBindAction({ adopted: t, workItemId: "t1", referencedKind: "task" });
+		expect(out.action).toBe("use");
+		if (out.action === "use") expect(out.task.id).toBe("t1");
+	});
+
+	it("creates for an exploratory lane (no workItemId supplied)", () => {
+		const out = resolveBindAction({ adopted: null, workItemId: null, referencedKind: null });
+		expect(out.action).toBe("create");
+		if (out.action === "create") expect(out.scope).toBe("exploratory");
+	});
+
+	it("creates under a PROJECT parent (workItemId resolves to a project, not a task)", () => {
+		const out = resolveBindAction({
+			adopted: null,
+			workItemId: "proj-1",
+			referencedKind: "project",
+		});
+		expect(out.action).toBe("create");
+		if (out.action === "create") expect(out.scope).toBe("project-parent");
+	});
+
+	it("REFUSES when the spawn named a task that does not exist — no orphan created", () => {
+		// THE owed test: a spawn carrying a workItemId that resolves to NO task
+		// must fail (refuse) instead of silently creating a new orphan task.
+		const out = resolveBindAction({
+			adopted: null,
+			workItemId: "ghost-9",
+			referencedKind: null,
+		});
+		expect(out.action).toBe("refuse");
+		if (out.action === "refuse") {
+			expect(out.reason).toBe("missing-referenced-task");
+			expect(out.workItemId).toBe("ghost-9");
+		}
+	});
+
+	it("prefers a successful adopt even when a (stale) referenced kind is present", () => {
+		// adopt already writes the session + assignee_id; once it succeeds the
+		// referenced-kind probe is irrelevant.
+		const t = taskRow("t1");
+		const out = resolveBindAction({ adopted: t, workItemId: "t1", referencedKind: null });
+		expect(out.action).toBe("use");
+	});
+});

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

@@ -73,11 +73,25 @@ import { getAppLogger } from "@teamscala/logger/app-loggers";
  * lane). `slug`/`windowName` shape the spawn; `organisation_id` defaults to the
  * platform org (fleet/internal lane tasks live there).
  */
-export const assignTaskInput = v.object({
-	name: v.pipe(
-		v.string(),
-		v.minLength(1, "name is required — an incomplete task is unconstructible"),
+/**
+ * A lane task's NAME — the lane's real work label, never the generic "Lane"
+ * sentinel. A row titled "Lane" is spawn debris: it tells the operator nothing
+ * about the work, so an orchestrator cannot tell real unowned work from it (the
+ * signal the fleet steers by). Rejected at the ORPC input chokepoint so a spawn
+ * that forgot to name its lane is REFUSED at the mint, never written
+ * (lanes-named-by-the-spawner — the spawner sets the work name at creation).
+ */
+const laneWorkName = v.pipe(
+	v.string(),
+	v.minLength(1, "name is required — the lane's real work label"),
+	v.check(
+		(n) => n.trim().toLowerCase() !== "lane",
+		"name must carry the lane's real work name, not the generic sentinel 'Lane'",
 	),
+);
+
+export const assignTaskInput = v.object({
+	name: laneWorkName,
 	description: v.pipe(
 		v.string(),
 		v.minLength(1, "description is required — it is the brief (first comment)"),
@@ -167,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: {
@@ -189,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 };
 	});
 }
 
@@ -215,11 +229,18 @@ export async function createTaskWithBriefComment(
  * implement`). "Is the caller the assignee" becomes a simple equality on the
  * session.
  *
- * Refuses to STEAL a task another live session already owns — that is the
- * existing-session re-bind branch's job (matched by `kind_data.lane.session`).
- * Here we adopt only tasks with no session (or already this session). Returns
- * null when `maybeTaskId` is absent, not a task, or already owned by another
- * session — caller falls through to the normal create.
+ * RE-BINDS a task another session already owns. Migration 109
+ * (`work_items_one_active_task_per_lane`) makes `(kind_data->'lane'->>'pane')`
+ * unique WHERE active, so when a lane is re-spawned on a pane whose prior task is
+ * still active under a STALE session (the lane died, the row survived),
+ * `resolveLaneTask(newSession)` finds nothing and `create` P2002s — measured
+ * fleet-wide 2026-08-01: every real lane's bindLane 500'd on this constraint.
+ * Refusing to steal (the original design) routes every re-spawn into that
+ * dead-end. An assignment task belongs to whichever lane was dispatched to it,
+ * and a stale session is by definition dead, so re-binding to the fresh session
+ * is the correct recovery: the pane's unique slot moves to the live lane and
+ * the brief follows. Returns null only when `maybeTaskId` is absent or not a
+ * task — caller falls through to create for an exploratory lane (no workItemId).
  */
 export async function adoptAssignmentTask(
 	prisma: Prisma,
@@ -234,10 +255,6 @@ export async function adoptAssignmentTask(
 	// (which a spawn also carries as workItemId) must never be adopted, only
 	// created-under. Verified, not assumed (`a-component-may-not-report-a-state...`).
 	if (row.kind !== "task") return null;
-	const existingSession = (
-		(row.kind_data as { lane?: { session?: string } } | null) ?? {}
-	).lane?.session;
-	if (existingSession && existingSession !== lane.session) return null;
 	const laneData = {
 		pane: lane.pane,
 		session: lane.session,
@@ -249,6 +266,37 @@ export async function adoptAssignmentTask(
 		lane: laneData,
 		assignee_type: "agent",
 	};
+	// RELEASE any OTHER active task holding this pane's unique lane slot before
+	// writing — migration 109's unique index would otherwise P2002 on the update
+	// when a stale task (prior session, same pane) is still active. Same logic
+	// as the run-link STEAL-before-CLAIM: a pane's lane slot is singly-owned, so
+	// every other row holding it is this lane's own stale prior (or a duplicate the
+	// race created) and is released to null-pane so this update can land. The
+	// assignment task itself is then re-bound to the fresh session.
+	try {
+		if (lane.pane) {
+			const others = (
+				prisma as unknown as {
+					work_items?: {
+						updateMany: (a: unknown) => Promise<{ count: number }>;
+					};
+				}
+			).work_items;
+			await others?.updateMany({
+				where: {
+					kind: "task",
+					status: "active",
+					id: { not: row.id },
+					kind_data: { path: ["lane", "pane"], equals: lane.pane },
+				},
+				data: { kind_data: { lane: { pane: null } } },
+			});
+		}
+	} catch {
+		// Best-effort: a release failure does not block the adopt — the update below
+		// will throw its own P2002 and the handler falls through, converging on the
+		// next bind. Logged by the caller's run-link region, not here.
+	}
 	try {
 		return await prisma.work_items.update({
 			where: { id: row.id },
@@ -259,6 +307,45 @@ export async function adoptAssignmentTask(
 	}
 }
 
+/**
+ * The bind decision AFTER attempting to adopt the spawn's referenced task. PURE
+ * over the adopt result + whether the referenced row exists, so the
+ * "a spawn that cannot bind fails loudly rather than orphaning" invariant
+ * (`absent-input-reads-as-success`) is unit-testable without standing up the
+ * ORPC handler. `bindLane` calls `adoptAssignmentTask` then this, then acts.
+ *
+ *   `use`     — adopt succeeded; bind the lane to that task.
+ *   `create`  — no task to adopt: an exploratory lane (no workItemId) or the
+ *               referenced id is a PROJECT the task is created under.
+ *   `refuse`  — the spawn named a workItemId the lane should adopt, but NO task
+ *               exists with that id. Silently creating a NEW task here would
+ *               abandon the spawn's referenced brief and bind the lane to an
+ *               empty task it was never meant to own — exactly the orphan
+ *               `absent-input-reads-as-success` forbids (a caller that stated
+ *               adopt-intent reads "success" while the referenced row rots).
+ *               Failing loudly surfaces the malformed spawn instead.
+ */
+export type BindAction =
+	| { action: "use"; task: WorkItem }
+	| { action: "create"; scope: "exploratory" | "project-parent" }
+	| { action: "refuse"; reason: "missing-referenced-task"; workItemId: string };
+
+export function resolveBindAction(args: {
+	adopted: WorkItem | null;
+	workItemId: string | null;
+	/** The kind of the row at workItemId, or null when no such row exists. */
+	referencedKind: string | null;
+}): BindAction {
+	if (args.adopted) return { action: "use", task: args.adopted };
+	if (!args.workItemId) return { action: "create", scope: "exploratory" };
+	// A workItemId was provided but adopt returned null: either it resolves to a
+	// non-task (a PROJECT — create a task under it) or to nothing (refuse).
+	if (args.referencedKind === null) {
+		return { action: "refuse", reason: "missing-referenced-task", workItemId: args.workItemId };
+	}
+	return { action: "create", scope: "project-parent" };
+}
+
 /**
  * Bind a task to a KNOWN session — the RESUME path. Unlike a fresh spawn (the
  * CLI mints the session at boot, so SessionStart must adopt), a resumed/switched
@@ -342,7 +429,7 @@ export interface AssignmentResult {
  * idempotencyKey), which belong on the spawn emission, not the mint.
  */
 export const createBriefTaskInput = v.object({
-	name: v.pipe(v.string(), v.minLength(1, "name is required — the lane's work label")),
+	name: laneWorkName,
 	description: v.pipe(
 		v.string(),
 		v.minLength(1, "description is required — it is the brief (first comment)"),
@@ -384,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