@teamscala/service-boot 0.23.305 → 0.23.306

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.305",
+  "version": "0.23.306",
   "sideEffects": false,
   "files": [
     "src"
@@ -386,6 +386,14 @@
       "types": "./src/fn-routers/sign-in-flow-router.d.ts",
       "default": "./src/fn-routers/sign-in-flow-router.ts"
     },
+    "./fn-routers/task-sync-assign": {
+      "types": "./src/fn-routers/task-sync-assign.d.ts",
+      "default": "./src/fn-routers/task-sync-assign.ts"
+    },
+    "./fn-routers/task-sync-assign.ts": {
+      "types": "./src/fn-routers/task-sync-assign.d.ts",
+      "default": "./src/fn-routers/task-sync-assign.ts"
+    },
     "./fn-routers/task-sync-brief": {
       "types": "./src/fn-routers/task-sync-brief.d.ts",
       "default": "./src/fn-routers/task-sync-brief.ts"

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

@@ -0,0 +1,196 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @indivisible-unit
+ * @edit edit directly
+ *
+ * Lane DISPATCH by assignment — the WRITE half of dispatch-by-assignment. The
+ * operator's contract (verbatim intent): you create a task (the NAME), you write
+ * the first COMMENT (which IS the prompt/brief), and THEN you assign it to an AI
+ * agent — and the assignment is the TRIGGER that spawns the lane. Assignment
+ * last, always, because by the time the agent exists every piece of information
+ * it needs is already in the row.
+ *
+ * This file owns the two pure halves of that flow, split out of task-sync-router
+ * (which sits at its 1000-line commit gate, so any new task-sync unit lands in a
+ * sibling — the same reason task-sync-brief/lane/dispatch exist):
+ *   createTaskWithBriefComment — create the task AND its first comment (the
+ *     description IS the first comment IS the brief) in one transaction. An
+ *     incomplete task is UNCONSTRUCTIBLE: the ORPC `.input()` schema
+ *     (`assignTaskInput`) requires name + description TOGETHER, so oRPC rejects
+ *     the call before the handler runs (`prevention-over-detection` — require at
+ *     the signature, never validate after the fact).
+ *   buildAssignmentSpawnPayload — shape the spawn emission that the assignment
+ *     emits. It carries the task id and NO initialPrompt, because the spawned
+ *     lane PULLS its brief from the DB by its own session id
+ *     (`task-sync-brief.ts` readAssignedBrief → latest comment). That deletes the
+ *     keystroke-brief failure class (a ~4400-char initialPrompt fails outright;
+ *     a ~2600-char one arrives intact and is never submitted, then the pane is
+ *     reaped for producing no turn): when the brief is a row, no keystroke can
+ *     lose it.
+ *
+ * THE EMISSION is a row write followed by an emission that triggers the spawn
+ * (`actions-are-rows-then-emissions`): the assignment writes the task + comment,
+ * then emits; the host-command bus consumer reacts by spawning. State lives in
+ * the row, never in a return value a caller may never receive. The exact bus
+ * surface this file emits through is INJECTED (AssignmentEmitter) rather than
+ * hard-coded, so it composes with whichever surface the host-command-bus cutover
+ * lands — one mechanism, not two (`no-silent-reverts` on the spawn path).
+ *
+ * BINDING (the gap this flow exposes). A lane resolves its task by its CLI-native
+ * session id (`kind_data.lane.session`, minted by the CLI at boot — never by us).
+ * Today `ensureLaneTask`/`bindLane` CREATE a fresh parent task at SessionStart.
+ * But assignment PRE-CREATES the task (with the brief as its first comment, no
+ * session yet), so SessionStart must ADOPT THAT EXISTING TASK BY ID — writing the
+ * freshly-minted session onto its `kind_data.lane.session` — instead of creating
+ * a new one, or the brief-task is orphaned and the lane self-briefs to nothing.
+ * The task is created `status:"active"` with no session, so `resolveLaneTask`
+ * (which filters `kind_data.lane.session`) cannot see it until bind writes the
+ * session — exactly right: the lane resolves it only after it is bound.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Bound to the work_items + comments schema and to task-sync's own
+ * kind_data.lane.session convention; no unrelated app could install this
+ * unmodified.
+ */
+import * as v from "valibot";
+import type { Prisma, WorkItem } from "./task-sync-router.ts";
+/**
+ * The assignment input. `name` + `description` are REQUIRED TOGETHER at the
+ * signature: oRPC parses this schema before the handler runs, so a call missing
+ * either is rejected with a 400 — an incomplete task is unconstructible, not
+ * caught after the fact. `description` becomes the task's first comment (the
+ * brief); it is never stored separately on the task, so "the brief" has exactly
+ * one home (`task-sync-brief.ts` readLatestTaskComment, newest-first).
+ *
+ * `name` → work_items.title; `description` → the first comment. `parent_id` is
+ * the project the dispatched task is scoped under (omit for an exploratory
+ * lane). `slug`/`windowName` shape the spawn; `organisation_id` defaults to the
+ * platform org (fleet/internal lane tasks live there).
+ */
+export declare const assignTaskInput: v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "name is required — an incomplete task is unconstructible">]>;
+    readonly description: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "description is required — it is the brief (first comment)">]>;
+    readonly parent_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly organisation_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly slug: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly windowName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly idempotencyKey: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+/** The resolved (post-schema) shape the handlers operate on. */
+export type AssignTaskInput = v.InferOutput<typeof assignTaskInput>;
+/**
+ * Resolve the org a dispatched task is created under. Pure: the platform org is
+ * INJECTED (resolved by the caller at the handler boundary, where a registry
+ * read is appropriate) rather than pulled from the registry inside this module,
+ * so the create logic is unit-testable with no DB (`configured-primitives`:
+ * config arrives from the caller, never pulled from DB/Env inside a primitive).
+ */
+export declare function resolveAssignOrg(explicit?: string, platformOrg?: string): string;
+/**
+ * Create a dispatched task AND its first comment (the description = the brief) in
+ * one transaction. The task is `kind:"task"`, `status:"active"`, with NO
+ * `kind_data.lane.session` yet — the session is minted by the CLI at spawn and
+ * written onto the row by SessionStart's adopt-existing bind. Until then the
+ * task is invisible to `resolveLaneTask` (which filters on the session), which is
+ * correct: the lane may only resolve its task once it is bound to it.
+ *
+ * Pure over an injected prisma (no module-level I/O) so the atomic create +
+ * first-comment decision is unit-testable with a fake transaction. `userId`
+ * stamps `created_by`/`updated_by` on the task and `user_id` on the comment.
+ */
+export declare function createTaskWithBriefComment(prisma: Prisma, input: {
+    name: string;
+    description: string;
+    parent_id?: string;
+    organisation_id: string;
+}, userId: string): Promise<WorkItem>;
+/**
+ * ADOPT a pre-created assignment task at SessionStart: write the lane's
+ * freshly-minted session onto an EXISTING task row instead of creating a new
+ * one. `bindLane` calls this when the spawn carried a `workItemId` that resolves
+ * to a `kind:"task"` row (the assignment task whose first comment IS the brief).
+ * Without this, bindLane would CREATE a new task and orphan the brief-task — the
+ * lane would `readAssignedBrief` to nothing.
+ *
+ * Realizes OWNERSHIP too: sets `assignee_id` to the lane's session (its stable
+ * identity, `lane-identity-is-cli-session-id`), so the compliance gate can
+ * distinguish a task the CALLER owes from one a dispatched lane owns (the
+ * orchestrator supervises, not implements — `anthropic-models-orchestrate-not-
+ * 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.
+ */
+export declare function adoptAssignmentTask(prisma: Prisma, maybeTaskId: string | null | undefined, lane: {
+    session: string;
+    pane: string | null;
+    cli_kind?: string;
+    role?: string;
+}): Promise<WorkItem | null>;
+/**
+ * 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
+ * lane knows its session id up front (`resumeId`). So the assignment binds the
+ * task to `resumeId` directly and writes a NEW comment as the continuation brief,
+ * before emitting the spawn with `resumeId`. `readAssignedBrief(resumeId)` then
+ * returns that continuation — so `DEFAULT_CONTINUATION_PROMPT`'s job (which rode
+ * the now-retired keystroke path) moves to a row write at assign time. Also sets
+ * `assignee_id` (ownership) for the same reason as the fresh-spawn adopt.
+ */
+export declare function bindTaskToKnownSession(prisma: Prisma, taskId: string, lane: {
+    session: string;
+    pane: string | null;
+    cli_kind?: string;
+    role?: string;
+}): Promise<WorkItem | null>;
+/**
+ * The spawn payload an assignment emits. Carries the task id (as `workItemId`,
+ * which the picker exports into the pane so SessionStart can ADOPT the existing
+ * task) and NEVER an `initialPrompt` — the lane pulls its brief from the DB by
+ * its own session id. This is the contract whatever host-command surface lands:
+ * command `spawn_agent_tab`, payload `{ workItemId, slug?, windowName?,
+ * idempotencyKey? }`.
+ *
+ * Pure (no I/O) so the "no keystroke brief, taskId-only" invariant is
+ * unit-testable and regression-locked: a test asserting `initialPrompt` is
+ * absent fails the moment someone re-adds keystroke delivery.
+ */
+export declare function buildAssignmentSpawnPayload(task: Pick<WorkItem, "id">, options: {
+    slug?: string;
+    windowName?: string;
+    idempotencyKey?: string;
+}): {
+    command: "spawn_agent_tab";
+    payload: {
+        workItemId: string;
+        slug?: string;
+        windowName?: string;
+        idempotencyKey?: string;
+    };
+};
+/**
+ * The emission surface an assignment writes the spawn intent to. Injected (not
+ * imported) so this file composes with whichever bus surface the host-command-bus
+ * cutover settles on, rather than hard-coding a second mechanism. Implementations
+ * write a durable row the consumer reacts to (`actions-are-rows-then-emissions`):
+ * fire-and-forget from the caller's perspective — the caller states intent and
+ * proceeds; the consumer spawns the lane and the lane self-briefs.
+ */
+export interface AssignmentEmitter {
+    /** Write the spawn intent as a durable row the host-command consumer reacts to. */
+    emitSpawn(payload: ReturnType<typeof buildAssignmentSpawnPayload>): Promise<void>;
+}
+/**
+ * The outcome of assigning a task: the created/confirmed task and confirmation
+ * that the spawn intent was emitted (not that the lane spawned — that is the
+ * consumer's reaction, observed separately). The caller proceeds on the row.
+ */
+export interface AssignmentResult {
+    task: WorkItem;
+    emitted: boolean;
+}

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

@@ -0,0 +1,290 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Unit tests for the dispatch-by-assignment WRITE core (task-sync-assign.ts):
+ * the "incomplete task is unconstructible" signature invariant, the atomic
+ * create-task + first-comment (= brief) write, and the no-initialPrompt spawn
+ * payload (regression-locks the row-based self-brief model — fails the moment
+ * someone re-adds keystroke delivery). Covers `what-must-have-a-test`.
+ */
+import { describe, it, expect } from "bun:test";
+import * as v from "valibot";
+import {
+	assignTaskInput,
+	createTaskWithBriefComment,
+	adoptAssignmentTask,
+	bindTaskToKnownSession,
+	buildAssignmentSpawnPayload,
+	resolveAssignOrg,
+} from "./task-sync-assign.ts";
+
+/** A minimal fake prisma exposing only $transaction + the two creates the fn uses. */
+function fakePrisma(overrides: { platformOrg?: string } = {}) {
+	const calls: {
+		workItem: Record<string, unknown> | null;
+		comment: Record<string, unknown> | null;
+	}[] = [];
+	let createdTask: Record<string, unknown> = {
+		id: "task-new-1",
+		kind: "task",
+		title: "unused",
+		status: "active",
+		kind_data: {},
+	};
+	const prisma = {
+		$transaction: async (fn: (tx: unknown) => Promise<unknown>) => {
+			const tx = {
+				work_items: {
+					create: async (a: { data: Record<string, unknown> }) => {
+						createdTask = { ...createdTask, ...a.data, id: "task-new-1" };
+						return createdTask;
+					},
+				},
+				comments: {
+					create: async (a: { data: Record<string, unknown> }) => {
+						calls.push({ workItem: null, comment: a.data });
+						return a.data;
+					},
+				},
+			};
+			const result = await fn(tx);
+			// Record the task create alongside the first comment for assertion.
+			calls[calls.length - 1] = { ...calls[calls.length - 1], workItem: { ...createdTask } };
+			return result;
+		},
+	};
+	return { prisma, calls, platformOrg: overrides.platformOrg ?? "org-platform" };
+}
+
+describe("assignTaskInput (incomplete task is unconstructible)", () => {
+	it("accepts name + description together", () => {
+		const out = v.safeParse(assignTaskInput, { name: "FleetTruth", description: "Do X" });
+		expect(out.success).toBe(true);
+	});
+
+	it("rejects a missing description — no brief, no task", () => {
+		// The description IS the brief (first comment); a task without it is exactly
+		// the incomplete state the operator said must be unconstructible.
+		const out = v.safeParse(assignTaskInput, { name: "FleetTruth" });
+		expect(out.success).toBe(false);
+	});
+
+	it("rejects a missing name", () => {
+		const out = v.safeParse(assignTaskInput, { description: "Do X" });
+		expect(out.success).toBe(false);
+	});
+
+	it("rejects an empty-string description (not just absent)", () => {
+		const out = v.safeParse(assignTaskInput, { name: "FleetTruth", description: "" });
+		expect(out.success).toBe(false);
+	});
+
+	it("treats parent_id/slug/windowName as optional", () => {
+		const out = v.safeParse(assignTaskInput, {
+			name: "Exploratory",
+			description: "Look around",
+		});
+		expect(out.success).toBe(true);
+	});
+});
+
+describe("createTaskWithBriefComment (atomic task + first comment = brief)", () => {
+	it("creates the task active with kind_data carrying NO session, and writes the description as the first comment in the SAME transaction", async () => {
+		const { prisma, calls } = fakePrisma();
+		const task = await createTaskWithBriefComment(
+			prisma as never,
+			{ name: "Dispatch test", description: "the brief text", organisation_id: "org-1" },
+			"user-1",
+		);
+
+		// The task is the active parent the lane will later bind its session to.
+		expect(task.kind).toBe("task");
+		expect(task.status).toBe("active");
+		expect(task.title).toBe("Dispatch test");
+		// CRITICAL: no session key yet — the CLI mints it at spawn and SessionStart
+		// writes it. Carrying one now would let resolveLaneTask race a half-bound row.
+		// assignee_type:"agent" marks it lane-owned from creation (ownership marker).
+		expect(task.kind_data).toEqual({ assignee_type: "agent" });
+		expect((task.kind_data as Record<string, unknown>).lane).toBeUndefined();
+
+		// Exactly one comment, content = the description (one source, not two).
+		expect(calls).toHaveLength(1);
+		expect(calls[0].comment).toMatchObject({
+			work_item_id: task.id,
+			content: "the brief text",
+			user_id: "user-1",
+		});
+		// The comment was written inside the same transaction as the task create
+		// (atomic — a task row without its brief comment can never exist).
+		expect(calls[0].workItem).toMatchObject({ id: task.id, kind: "task", status: "active" });
+	});
+
+	it("parents the task under parent_id when supplied, else null", async () => {
+		const withParent = fakePrisma();
+		await createTaskWithBriefComment(
+			withParent.prisma as never,
+			{ name: "T", description: "d", parent_id: "proj-9", organisation_id: "org-1" },
+			"u",
+		);
+		expect(withParent.calls[0].workItem?.parent_id).toBe("proj-9");
+
+		const noParent = fakePrisma();
+		await createTaskWithBriefComment(
+			noParent.prisma as never,
+			{ name: "T", description: "d", organisation_id: "org-1" },
+			"u",
+		);
+		expect(noParent.calls[0].workItem?.parent_id).toBe(null);
+	});
+
+	it("stamps created_by/updated_by + comment user_id from the caller", async () => {
+		const { prisma, calls } = fakePrisma();
+		await createTaskWithBriefComment(
+			prisma as never,
+			{ name: "T", description: "d", organisation_id: "org-1" },
+			"user-42",
+		);
+		expect(calls[0].workItem).toMatchObject({ created_by: "user-42", updated_by: "user-42" });
+		expect(calls[0].comment).toMatchObject({ user_id: "user-42" });
+	});
+});
+
+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 prisma = {
+			work_items: {
+				findFirst: async () => existing,
+				update: async (a: { where: { id: string }; data: Record<string, unknown> }) => {
+					const row = { ...(existing ?? {}), ...a.data, id: a.where.id };
+					updates.push(row);
+					return row;
+				},
+			},
+		};
+		return { prisma, updates };
+	}
+
+	it("writes the lane session onto the pre-created task AND sets assignee_id (ownership)", async () => {
+		const task = { id: "task-1", kind: "task", kind_data: { assignee_type: "agent" }, assignee_id: null };
+		const { prisma, updates } = fakeAdoptPrisma(task);
+		const out = await adoptAssignmentTask(prisma as never, "task-1", { session: "ses-9", pane: "tmux:%5" });
+		expect(out).not.toBeNull();
+		expect(updates).toHaveLength(1);
+		// OWNERSHIP: assignee_id = the lane session (so the gate can key caller==assignee).
+		expect(updates[0].assignee_id).toBe("ses-9");
+		// BINDING: kind_data.lane.session set (resolveLaneTask can now find it).
+		const kd = updates[0].kind_data as { lane: { session: string; pane: string }; assignee_type: string };
+		expect(kd.lane.session).toBe("ses-9");
+		expect(kd.lane.pane).toBe("tmux:%5");
+		expect(kd.assignee_type).toBe("agent");
+	});
+
+	it("preserves existing kind_data when merging the lane marker onto it", async () => {
+		const task = { id: "t", kind: "task", kind_data: { assignee_type: "agent", other: "keep" } };
+		const { prisma, updates } = fakeAdoptPrisma(task);
+		await adoptAssignmentTask(prisma as never, "t", { session: "s", pane: null });
+		const kd = updates[0].kind_data as { other: string; lane: { session: string } };
+		expect(kd.other).toBe("keep"); // not clobbered
+		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-adopts a task already bound to THIS session (idempotent re-bind)", async () => {
+		const task = { id: "t", kind: "task", kind_data: { lane: { session: "ses-9" } } };
+		const { prisma, updates } = fakeAdoptPrisma(task);
+		const out = await adoptAssignmentTask(prisma as never, "t", { session: "ses-9", pane: "tmux:%5" });
+		expect(out).not.toBeNull();
+		expect(updates).toHaveLength(1);
+	});
+
+	it("returns null when the id is absent (nothing to adopt — caller creates)", async () => {
+		const { prisma, updates } = fakeAdoptPrisma(null);
+		expect(await adoptAssignmentTask(prisma as never, null, { session: "s", pane: null })).toBeNull();
+		expect(await adoptAssignmentTask(prisma as never, undefined, { session: "s", pane: null })).toBeNull();
+		expect(updates).toHaveLength(0);
+	});
+
+	it("returns null when the id is a PROJECT, not a task (disambiguates by kind)", async () => {
+		// A project parent must NOT be adopted — bindLane creates a task UNDER it.
+		const { prisma, updates } = fakeAdoptPrisma({ id: "proj-1", kind: "project", kind_data: {} });
+		expect(await adoptAssignmentTask(prisma as never, "proj-1", { session: "s", pane: null })).toBeNull();
+		expect(updates).toHaveLength(0);
+	});
+});
+
+describe("bindTaskToKnownSession (resume path binds to a known session up front)", () => {
+	it("binds the task to the known resumeId session (ownership = resumeId)", async () => {
+		const task = { id: "t", kind: "task", kind_data: { assignee_type: "agent" }, assignee_id: null };
+		const prisma = {
+			work_items: {
+				findFirst: async () => task,
+				update: async (a: { where: { id: string }; data: Record<string, unknown> }) =>
+					({ ...task, ...a.data, id: a.where.id }) as Record<string, unknown>,
+			},
+		};
+		const out = (await bindTaskToKnownSession(prisma as never, "t", {
+			session: "resumeId-1",
+			pane: "tmux:%9",
+		})) as Record<string, unknown> | null;
+		expect(out).not.toBeNull();
+		expect(out?.assignee_id).toBe("resumeId-1");
+	});
+});
+
+describe("resolveAssignOrg", () => {
+	it("returns the explicit org when supplied", () => {
+		expect(resolveAssignOrg("org-explicit")).toBe("org-explicit");
+	});
+	it("falls back to the INJECTED platform org when explicit is omitted", () => {
+		// Pure: platform org arrives from the caller (resolved at the handler
+		// boundary), never pulled from the registry inside this module.
+		expect(resolveAssignOrg(undefined, "org-platform")).toBe("org-platform");
+	});
+	it("prefers explicit over the injected platform org", () => {
+		expect(resolveAssignOrg("org-explicit", "org-platform")).toBe("org-explicit");
+	});
+});
+
+describe("buildAssignmentSpawnPayload (no keystroke brief — row-based self-brief)", () => {
+	const task = { id: "task-99" };
+
+	it("emits command spawn_agent_tab carrying the taskId as workItemId", () => {
+		const out = buildAssignmentSpawnPayload(task, { slug: "cc-glm52", windowName: "FleetTruth" });
+		expect(out.command).toBe("spawn_agent_tab");
+		expect(out.payload.workItemId).toBe("task-99");
+		expect(out.payload.slug).toBe("cc-glm52");
+		expect(out.payload.windowName).toBe("FleetTruth");
+	});
+
+	it("NEVER carries initialPrompt — the lane pulls its brief from the DB by session id", () => {
+		// Regression-lock for the failure class this deletes: a 4400-char
+		// initialPrompt fails; a 2600-char one arrives but is never submitted.
+		// The moment someone re-adds keystroke delivery this assertion fails.
+		const out = buildAssignmentSpawnPayload(task, { slug: "cc-glm52" });
+		expect("initialPrompt" in out.payload).toBe(false);
+		expect(out.payload).not.toHaveProperty("initialPrompt");
+	});
+
+	it("omits optional spawn fields when not supplied (no undefined keys)", () => {
+		const out = buildAssignmentSpawnPayload(task, {});
+		expect(out.payload).toEqual({ workItemId: "task-99" });
+		expect("slug" in out.payload).toBe(false);
+		expect("windowName" in out.payload).toBe(false);
+		expect("idempotencyKey" in out.payload).toBe(false);
+	});
+
+	it("forwards idempotencyKey when supplied (retries reuse it, new spawns don't)", () => {
+		const out = buildAssignmentSpawnPayload(task, { idempotencyKey: "k-1" });
+		expect(out.payload.idempotencyKey).toBe("k-1");
+	});
+});

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

@@ -0,0 +1,290 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @indivisible-unit
+ * @edit edit directly
+ *
+ * Lane DISPATCH by assignment — the WRITE half of dispatch-by-assignment. The
+ * operator's contract (verbatim intent): you create a task (the NAME), you write
+ * the first COMMENT (which IS the prompt/brief), and THEN you assign it to an AI
+ * agent — and the assignment is the TRIGGER that spawns the lane. Assignment
+ * last, always, because by the time the agent exists every piece of information
+ * it needs is already in the row.
+ *
+ * This file owns the two pure halves of that flow, split out of task-sync-router
+ * (which sits at its 1000-line commit gate, so any new task-sync unit lands in a
+ * sibling — the same reason task-sync-brief/lane/dispatch exist):
+ *   createTaskWithBriefComment — create the task AND its first comment (the
+ *     description IS the first comment IS the brief) in one transaction. An
+ *     incomplete task is UNCONSTRUCTIBLE: the ORPC `.input()` schema
+ *     (`assignTaskInput`) requires name + description TOGETHER, so oRPC rejects
+ *     the call before the handler runs (`prevention-over-detection` — require at
+ *     the signature, never validate after the fact).
+ *   buildAssignmentSpawnPayload — shape the spawn emission that the assignment
+ *     emits. It carries the task id and NO initialPrompt, because the spawned
+ *     lane PULLS its brief from the DB by its own session id
+ *     (`task-sync-brief.ts` readAssignedBrief → latest comment). That deletes the
+ *     keystroke-brief failure class (a ~4400-char initialPrompt fails outright;
+ *     a ~2600-char one arrives intact and is never submitted, then the pane is
+ *     reaped for producing no turn): when the brief is a row, no keystroke can
+ *     lose it.
+ *
+ * THE EMISSION is a row write followed by an emission that triggers the spawn
+ * (`actions-are-rows-then-emissions`): the assignment writes the task + comment,
+ * then emits; the host-command bus consumer reacts by spawning. State lives in
+ * the row, never in a return value a caller may never receive. The exact bus
+ * surface this file emits through is INJECTED (AssignmentEmitter) rather than
+ * hard-coded, so it composes with whichever surface the host-command-bus cutover
+ * lands — one mechanism, not two (`no-silent-reverts` on the spawn path).
+ *
+ * BINDING (the gap this flow exposes). A lane resolves its task by its CLI-native
+ * session id (`kind_data.lane.session`, minted by the CLI at boot — never by us).
+ * Today `ensureLaneTask`/`bindLane` CREATE a fresh parent task at SessionStart.
+ * But assignment PRE-CREATES the task (with the brief as its first comment, no
+ * session yet), so SessionStart must ADOPT THAT EXISTING TASK BY ID — writing the
+ * freshly-minted session onto its `kind_data.lane.session` — instead of creating
+ * a new one, or the brief-task is orphaned and the lane self-briefs to nothing.
+ * The task is created `status:"active"` with no session, so `resolveLaneTask`
+ * (which filters `kind_data.lane.session`) cannot see it until bind writes the
+ * session — exactly right: the lane resolves it only after it is bound.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Bound to the work_items + comments schema and to task-sync's own
+ * kind_data.lane.session convention; no unrelated app could install this
+ * unmodified.
+ */
+
+import { getPlatformOrgId } from "@teamscala/db/registry/platform";
+import * as v from "valibot";
+import type { Prisma, WorkItem } from "./task-sync-router.ts";
+
+/**
+ * The assignment input. `name` + `description` are REQUIRED TOGETHER at the
+ * signature: oRPC parses this schema before the handler runs, so a call missing
+ * either is rejected with a 400 — an incomplete task is unconstructible, not
+ * caught after the fact. `description` becomes the task's first comment (the
+ * brief); it is never stored separately on the task, so "the brief" has exactly
+ * one home (`task-sync-brief.ts` readLatestTaskComment, newest-first).
+ *
+ * `name` → work_items.title; `description` → the first comment. `parent_id` is
+ * the project the dispatched task is scoped under (omit for an exploratory
+ * 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"),
+	),
+	description: v.pipe(
+		v.string(),
+		v.minLength(1, "description is required — it is the brief (first comment)"),
+	),
+	parent_id: v.optional(v.string()),
+	organisation_id: v.optional(v.string()),
+	slug: v.optional(v.string()),
+	windowName: v.optional(v.string()),
+	idempotencyKey: v.optional(v.string()),
+});
+
+/** The resolved (post-schema) shape the handlers operate on. */
+export type AssignTaskInput = v.InferOutput<typeof assignTaskInput>;
+
+/**
+ * Resolve the org a dispatched task is created under. Pure: the platform org is
+ * INJECTED (resolved by the caller at the handler boundary, where a registry
+ * read is appropriate) rather than pulled from the registry inside this module,
+ * so the create logic is unit-testable with no DB (`configured-primitives`:
+ * config arrives from the caller, never pulled from DB/Env inside a primitive).
+ */
+export function resolveAssignOrg(explicit?: string, platformOrg?: string): string {
+	return explicit ?? platformOrg ?? getPlatformOrgId();
+}
+
+/**
+ * Create a dispatched task AND its first comment (the description = the brief) in
+ * one transaction. The task is `kind:"task"`, `status:"active"`, with NO
+ * `kind_data.lane.session` yet — the session is minted by the CLI at spawn and
+ * written onto the row by SessionStart's adopt-existing bind. Until then the
+ * task is invisible to `resolveLaneTask` (which filters on the session), which is
+ * correct: the lane may only resolve its task once it is bound to it.
+ *
+ * Pure over an injected prisma (no module-level I/O) so the atomic create +
+ * first-comment decision is unit-testable with a fake transaction. `userId`
+ * stamps `created_by`/`updated_by` on the task and `user_id` on the comment.
+ */
+export async function createTaskWithBriefComment(
+	prisma: Prisma,
+	input: { name: string; description: string; parent_id?: string; organisation_id: string },
+	userId: string,
+): Promise<WorkItem> {
+	const organisation_id = input.organisation_id;
+	return (prisma as unknown as {
+		$transaction: (fn: (tx: unknown) => Promise<WorkItem>) => Promise<WorkItem>;
+	}).$transaction(async (tx) => {
+		const t = tx as {
+			work_items: { create: (a: unknown) => Promise<WorkItem> };
+			comments: { create: (a: unknown) => Promise<unknown> };
+		};
+		const task = await t.work_items.create({
+			data: {
+				kind: "task",
+				parent_id: input.parent_id ?? null,
+				organisation_id,
+				title: input.name,
+				status: "active",
+				// No kind_data.lane.session here: the CLI mints the session at spawn
+				// and SessionStart binds it. Carrying an empty lane marker would let
+				// resolveLaneTask race a half-bound row, so the key is absent until set.
+				// assignee_type:"agent" marks the task as OWNED BY A LANE from creation,
+				// so the compliance gate can tell a dispatched+supervised task (the
+				// orchestrator does NOT owe it) from the caller's own implementation work
+				// — even before SessionStart writes the session that finalises ownership.
+				kind_data: { assignee_type: "agent" },
+				created_by: userId,
+				updated_by: userId,
+			},
+		});
+		// The description IS the first comment IS the brief — one write, one source.
+		await t.comments.create({
+			data: {
+				work_item_id: task.id,
+				content: input.description,
+				user_id: userId,
+			},
+		});
+		return task;
+	});
+}
+
+/**
+ * ADOPT a pre-created assignment task at SessionStart: write the lane's
+ * freshly-minted session onto an EXISTING task row instead of creating a new
+ * one. `bindLane` calls this when the spawn carried a `workItemId` that resolves
+ * to a `kind:"task"` row (the assignment task whose first comment IS the brief).
+ * Without this, bindLane would CREATE a new task and orphan the brief-task — the
+ * lane would `readAssignedBrief` to nothing.
+ *
+ * Realizes OWNERSHIP too: sets `assignee_id` to the lane's session (its stable
+ * identity, `lane-identity-is-cli-session-id`), so the compliance gate can
+ * distinguish a task the CALLER owes from one a dispatched lane owns (the
+ * orchestrator supervises, not implements — `anthropic-models-orchestrate-not-
+ * 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.
+ */
+export async function adoptAssignmentTask(
+	prisma: Prisma,
+	maybeTaskId: string | null | undefined,
+	lane: { session: string; pane: string | null; cli_kind?: string; role?: string },
+): Promise<WorkItem | null> {
+	if (!maybeTaskId) return null;
+	const row = await prisma.work_items.findFirst({ where: { id: maybeTaskId, kind: "task" } });
+	if (!row) return null;
+	// Defense-in-depth: the findFirst filters kind:"task", but verify the kind on
+	// the read row too rather than trusting only the DB filter — a project parent
+	// (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,
+		cli_kind: lane.cli_kind ?? "claude-code",
+		role: lane.role ?? "agent",
+	};
+	const mergedKindData = {
+		...(row.kind_data ?? {}),
+		lane: laneData,
+		assignee_type: "agent",
+	};
+	try {
+		return await prisma.work_items.update({
+			where: { id: row.id },
+			data: { kind_data: mergedKindData, assignee_id: lane.session },
+		});
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * 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
+ * lane knows its session id up front (`resumeId`). So the assignment binds the
+ * task to `resumeId` directly and writes a NEW comment as the continuation brief,
+ * before emitting the spawn with `resumeId`. `readAssignedBrief(resumeId)` then
+ * returns that continuation — so `DEFAULT_CONTINUATION_PROMPT`'s job (which rode
+ * the now-retired keystroke path) moves to a row write at assign time. Also sets
+ * `assignee_id` (ownership) for the same reason as the fresh-spawn adopt.
+ */
+export async function bindTaskToKnownSession(
+	prisma: Prisma,
+	taskId: string,
+	lane: { session: string; pane: string | null; cli_kind?: string; role?: string },
+): Promise<WorkItem | null> {
+	return adoptAssignmentTask(prisma, taskId, lane);
+}
+
+/**
+ * The spawn payload an assignment emits. Carries the task id (as `workItemId`,
+ * which the picker exports into the pane so SessionStart can ADOPT the existing
+ * task) and NEVER an `initialPrompt` — the lane pulls its brief from the DB by
+ * its own session id. This is the contract whatever host-command surface lands:
+ * command `spawn_agent_tab`, payload `{ workItemId, slug?, windowName?,
+ * idempotencyKey? }`.
+ *
+ * Pure (no I/O) so the "no keystroke brief, taskId-only" invariant is
+ * unit-testable and regression-locked: a test asserting `initialPrompt` is
+ * absent fails the moment someone re-adds keystroke delivery.
+ */
+export function buildAssignmentSpawnPayload(
+	task: Pick<WorkItem, "id">,
+	options: { slug?: string; windowName?: string; idempotencyKey?: string },
+): {
+	command: "spawn_agent_tab";
+	payload: { workItemId: string; slug?: string; windowName?: string; idempotencyKey?: string };
+} {
+	return {
+		command: "spawn_agent_tab",
+		payload: {
+			workItemId: task.id,
+			...(options.slug ? { slug: options.slug } : {}),
+			...(options.windowName ? { windowName: options.windowName } : {}),
+			...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+		},
+	};
+}
+
+/**
+ * The emission surface an assignment writes the spawn intent to. Injected (not
+ * imported) so this file composes with whichever bus surface the host-command-bus
+ * cutover settles on, rather than hard-coding a second mechanism. Implementations
+ * write a durable row the consumer reacts to (`actions-are-rows-then-emissions`):
+ * fire-and-forget from the caller's perspective — the caller states intent and
+ * proceeds; the consumer spawns the lane and the lane self-briefs.
+ */
+export interface AssignmentEmitter {
+	/** Write the spawn intent as a durable row the host-command consumer reacts to. */
+	emitSpawn(
+		payload: ReturnType<typeof buildAssignmentSpawnPayload>,
+	): Promise<void>;
+}
+
+/**
+ * The outcome of assigning a task: the created/confirmed task and confirmation
+ * that the spawn intent was emitted (not that the lane spawned — that is the
+ * consumer's reaction, observed separately). The caller proceeds on the row.
+ */
+export interface AssignmentResult {
+	task: WorkItem;
+	emitted: boolean;
+}

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

@@ -30,7 +30,8 @@
  * work_items-specific mapping) is what earns a package.
  */
 import type { TaskListItem, WorkItem } from "./task-sync-router.ts";
-export declare const STATUS_TO_WORK_ITEM: Record<TaskListItem["status"], string>;
+/** CLI task-list status → work_items.status. The canonical forward direction. */
+export declare const STATUS_TO_WORK_ITEM: Record<"completed" | "in_progress" | "pending", string>;
 export declare function normalizeStatus(s: string | null): TaskListItem["status"];
 /**
  * Decide the status to WRITE for an existing row, given what the CLI list says.

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

@@ -29,6 +29,29 @@ describe("STATUS_TO_WORK_ITEM", () => {
 	});
 });
 
+describe("status translation is a single non-drifting source", () => {
+	// The forward map (CLI → work_items) is canonical; the reverse is DERIVED from
+	// it (+ a closed synonym set). This locks the structural fix: the two
+	// directions can never disagree, so adding a CLI status is one entry, not two
+	// maps to keep in sync — deletes the drift class (`prevention-over-detection`).
+
+	it("round-trips every CLI status through work_items and back unchanged", () => {
+		for (const cli of ["pending", "in_progress", "completed"] as TaskListItem["status"][]) {
+			expect(normalizeStatus(STATUS_TO_WORK_ITEM[cli])).toBe(cli);
+		}
+	});
+
+	it("the reverse map is the derived inverse of the forward map", () => {
+		// Every forward mapping is present reversed (the reverse may ADD synonyms
+		// like active/completed, but must never CONTRADICT the forward map).
+		for (const [cli, workItem] of Object.entries(STATUS_TO_WORK_ITEM) as Array<
+			[TaskListItem["status"], string]
+		>) {
+			expect(normalizeStatus(workItem)).toBe(cli);
+		}
+	});
+});
+
 describe("normalizeStatus", () => {
 	it("maps work_items statuses back to the normalized CLI form", () => {
 		expect(normalizeStatus("todo")).toBe("pending");

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

@@ -32,23 +32,44 @@
 
 import type { TaskListItem, WorkItem } from "./task-sync-router.ts";
 
-// TodoWrite-style status (the normalized form) → work_items.status (DB enum).
+// The status translation between a CLI's task list (pending/in_progress/completed)
+// and work_items.status (todo/in-progress/done/active/blocked/…). ONE source of
+// truth: the CLI→work_items map is canonical (each CLI state maps to exactly one
+// work_items status); the reverse direction is DERIVED from it, plus a closed set
+// of work_items-internal synonyms (active, completed) that have no distinct CLI
+// state. The two directions therefore cannot drift — adding a CLI state is one
+// entry in CLI_STATUS_TO_WORK_ITEM and the inverse updates with it — which deletes
+// the "two hand-maintained inverse maps" drift class (`prevention-over-detection`).
 // The DB enum uses a hyphen for the active state ("in-progress"); see
-// COLUMN_ENUMS["work_items.status"] in db-validation.
-export const STATUS_TO_WORK_ITEM: Record<TaskListItem["status"], string> = {
+// COLUMN_ENUMES["work_items.status"] in db-validation.
+const CLI_STATUS_TO_WORK_ITEM: Record<TaskListItem["status"], string> = {
 	pending: "todo",
 	in_progress: "in-progress",
 	completed: "done",
 };
-// work_items.status → normalized. Unknown/internal statuses collapse to pending.
-const WORK_ITEM_TO_STATUS: Record<string, TaskListItem["status"]> = {
-	todo: "pending",
-	"in-progress": "in_progress",
+
+// work_items-internal statuses that are SYNONYMS for a CLI state (no distinct CLI
+// representation). A closed, additive set — the only hand-maintained second source.
+const WORK_ITEM_STATUS_SYNONYMS: Record<string, TaskListItem["status"]> = {
 	active: "in_progress",
-	done: "completed",
 	completed: "completed",
 };
 
+// The reverse map, DERIVED: the canonical inverse of CLI_STATUS_TO_WORK_ITEM, plus
+// the synonyms. Generated at module load so it can never disagree with the forward
+// map. Unknown/internal statuses collapse to pending via normalizeStatus.
+const WORK_ITEM_TO_STATUS: Record<string, TaskListItem["status"]> = {
+	...Object.fromEntries(
+		(Object.entries(CLI_STATUS_TO_WORK_ITEM) as Array<[TaskListItem["status"], string]>).map(
+			([cli, workItem]) => [workItem, cli],
+		),
+	),
+	...WORK_ITEM_STATUS_SYNONYMS,
+};
+
+/** CLI task-list status → work_items.status. The canonical forward direction. */
+export const STATUS_TO_WORK_ITEM = CLI_STATUS_TO_WORK_ITEM;
+
 export function normalizeStatus(s: string | null): TaskListItem["status"] {
 	return (s && WORK_ITEM_TO_STATUS[s]) || "pending";
 }

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

@@ -42,6 +42,7 @@ import { authed, type Context } from "./auth-router.ts";
 import { notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
 import { resolveLaneTask, resolveLaneWorkName } from "./task-sync-lane.ts";
 import { readAssignedBriefHandler } from "./task-sync-brief.ts";
+import { adoptAssignmentTask } from "./task-sync-assign.ts";
 import * as v from "valibot";
 import {
 	STATUS_TO_WORK_ITEM,
@@ -486,37 +487,58 @@ export const taskSyncRouter = {
 			created = false;
 			log.info("[task-sync] bindLane: re-bound existing task", { taskId, session });
 		} else {
-			// Read-then-create is a race: SessionStart and the lane's first
-			// TaskCreate arrive seconds apart, both read nothing, and both create.
-			// Measured 2026-07-25: 9 lanes with two active parents each, every twin
-			// 2-3 seconds behind its sibling. Migration 109's partial unique index
-			// makes the second write fail instead of succeed, and losing the race
-			// is not an error — the winner's row is exactly what this call wanted,
-			// so re-read it and carry on.
-			let row: WorkItem;
-			try {
-				row = await prisma.work_items.create({
-					data: {
-						kind: "task",
-						parent_id: raw.parent_id ?? null,
-						organisation_id,
-						title: laneTitle,
-						status: "active",
-						kind_data: { lane },
-					},
-				});
-				log.info("[task-sync] bindLane: created task", { taskId: row.id, session });
-			} catch (err) {
-				const winner = await resolveLaneTask(prisma, session);
-				if (!winner) throw err;
-				row = winner;
-				log.info("[task-sync] bindLane: lost the create race, using existing task", {
-					taskId: row.id,
+			// DISPATCH-BY-ASSIGNMENT adopt. When the spawn carried a workItemId that
+			// points to an existing kind:"task" (the assignment task whose FIRST
+			// COMMENT is the brief), ADOPT it — write this lane's freshly-minted
+			// session onto it + set ownership (assignee_id) — instead of creating a
+			// new task that orphans the brief and leaves the lane self-briefing to
+			// nothing. Falls through to create for an exploratory lane (no
+			// workItemId) or a project parent (kind:"project"), so existing behaviour
+			// is unchanged on those paths.
+			const adopted = await adoptAssignmentTask(prisma, raw.parent_id, {
+				...lane,
+				session,
+			});
+			if (adopted) {
+				taskId = adopted.id;
+				created = false;
+				log.info("[task-sync] bindLane: adopted assigned task", {
+					taskId: adopted.id,
 					session,
 				});
+			} else {
+				// Read-then-create is a race: SessionStart and the lane's first
+				// TaskCreate arrive seconds apart, both read nothing, and both create.
+				// Measured 2026-07-25: 9 lanes with two active parents each, every twin
+				// 2-3 seconds behind its sibling. Migration 109's partial unique index
+				// makes the second write fail instead of succeed, and losing the race
+				// is not an error — the winner's row is exactly what this call wanted,
+				// so re-read it and carry on.
+				let row: WorkItem;
+				try {
+					row = await prisma.work_items.create({
+						data: {
+							kind: "task",
+							parent_id: raw.parent_id ?? null,
+							organisation_id,
+							title: laneTitle,
+							status: "active",
+							kind_data: { lane },
+						},
+					});
+					log.info("[task-sync] bindLane: created task", { taskId: row.id, session });
+				} catch (err) {
+					const winner = await resolveLaneTask(prisma, session);
+					if (!winner) throw err;
+					row = winner;
+					log.info("[task-sync] bindLane: lost the create race, using existing task", {
+						taskId: row.id,
+						session,
+					});
+				}
+				taskId = row.id;
+				created = true;
 			}
-			taskId = row.id;
-			created = true;
 		}
 		// Link the fleet run carrying this pane to the bound task — sets
 		// fleet_agent_runs.tracked_task_id. Best-effort by design: fleet_agent_runs

package/src/pg-boss-handler-registry.d.ts

@@ -16,6 +16,8 @@
 import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
 export type PgBossJobHandler = (ctx: {
     config: ScheduledJobConfig;
+    /** Per-job data payload from a one-shot `boss.send()` — absent for scheduled jobs. */
+    jobData?: unknown;
 }) => Promise<void> | void;
 export declare const pgBossHandlerRegistry: import("@teamscala/generic-registry/create-registry").Registry<PgBossJobHandler>;
 /**

package/src/pg-boss-mount.d.ts

@@ -21,6 +21,8 @@ import "./handlers/scala-tools-currency-watch.ts";
 import "./handlers/singleton-tools-currency-watch.ts";
 import "./handlers/registry-stale-inactive-sweep.ts";
 import "./handlers/pane-outbox-drain.ts";
+/** Returns the mounted PgBoss instance, or null if pg-boss is not running on this service. */
+export declare function getPgBoss(): PgBoss | null;
 export interface PgBossMountContext {
     databaseUrl: string;
     serviceSlug: string;