@teamscala/service-boot 0.23.317 → 0.23.319

package/src/fn-routers/task-sync-hook-lifecycle.test.ts

@@ -0,0 +1,204 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lifecycle round-trip for the Claude Code per-item task projection:
+ * `upsertFromTaskHookHandler` (the extracted body of the upsertFromTaskHook
+ * ORPC handler) must carry a task through created -> in_progress -> completed ->
+ * deleted against an in-memory mock prisma, so `work_items` sees every state a
+ * task reaches (`task-projection-converges`). A projection that cannot express
+ * completion — or deletion — is an append-only log, and the operator cannot see
+ * what a lane is doing. The matcher covering TaskCreate|TaskUpdate|TaskDelete is
+ * what routes all three tool events here; these tests assert the body applies
+ * each one. Same mock-prisma shape as claim-orchestrator-session.test.ts.
+ */
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+
+const recordEventMock = mock((_event: unknown) => {});
+mock.module("@teamscala/event-log/record-event", () => ({ recordEvent: recordEventMock }));
+mock.module("@teamscala/logger/app-loggers", () => ({
+	getAppLogger: () => ({
+		info: () => {},
+		warn: () => {},
+		error: () => {},
+	}),
+}));
+
+const { upsertFromTaskHookHandler } = await import("./task-sync-router.ts");
+
+/** A lane's parent task, returned by the mocked resolveLaneTask findFirst. */
+const LANE_TASK = {
+	id: "task-1",
+	kind: "task",
+	parent_id: null,
+	organisation_id: "org-1",
+	title: "Test Lane",
+	status: "active",
+	completed: false,
+	position: null,
+	kind_data: { lane: { session: "ses-1", pane: "tmux:%1" } },
+};
+
+function makePrisma() {
+	// In-memory subtask store, so the four states act on ONE evolving row.
+	const subtasks: Array<Record<string, unknown>> = [];
+	const findFirst = mock(async (args: { where: Record<string, unknown> }) => {
+		// resolveLaneTask asks for kind='task' + status active/archived; everything
+		// else (subtask lookups) returns null.
+		if (args.where?.kind === "task") return { ...LANE_TASK };
+		return null;
+	});
+	const findMany = mock(async (args: { where: Record<string, unknown> }) => {
+		const pid = args.where?.parent_id;
+		return subtasks.filter((s) => s.parent_id === pid);
+	});
+	const create = mock(async (args: { data: Record<string, unknown> }) => {
+		const row = { id: `s-${subtasks.length + 1}`, ...args.data };
+		subtasks.push(row);
+		return row;
+	});
+	const update = mock(async (args: { where: { id: string }; data: Record<string, unknown> }) => {
+		const row = subtasks.find((s) => s.id === args.where.id);
+		if (row) Object.assign(row, args.data);
+		return row ?? null;
+	});
+	const deleteMany = mock(async (args: { where: { id: { in: string[] } } }) => {
+		// Real Prisma form: where.id.in (a bare array on the scalar id is a
+		// validation error). Mirrors the canonical deleteMany in reconcileTaskList.
+		const ids = args.where?.id?.in ?? [];
+		let count = 0;
+		for (let i = subtasks.length - 1; i >= 0; i--) {
+			if (ids.includes(String(subtasks[i]?.id))) {
+				subtasks.splice(i, 1);
+				count++;
+			}
+		}
+		return { count };
+	});
+	return {
+		store: subtasks,
+		prisma: { work_items: { findFirst, findMany, create, update, deleteMany } },
+		mocks: { findFirst, findMany, create, update, deleteMany },
+	};
+}
+
+/** A lane context bound to a mock prisma, so each call site passes only the event. */
+function bindCtx(prisma: unknown, session = "ses-1") {
+	const headers = new Headers();
+	headers.set("x-lane-session", session);
+	headers.set("x-lane-pane", "tmux:%1");
+	return { headers, prisma, user: undefined };
+}
+
+/** makePrisma + a `hook(evt)` convenience bound to that prisma's session. */
+function makeFixture() {
+	const fixture = makePrisma();
+	const hook = (evt: unknown) => upsertFromTaskHookHandler(evt, bindCtx(fixture.prisma));
+	return { ...fixture, hook };
+}
+
+describe("upsertFromTaskHookHandler — full lifecycle round-trip", () => {
+	beforeEach(() => recordEventMock.mockClear());
+
+	it("created -> in_progress -> completed -> deleted all write through to one subtask", async () => {
+		const { hook, store, mocks } = makeFixture();
+
+		// 1. CREATED — PostToolUse:TaskCreate. The harness assigns the task id in
+		//    tool_response.task.id; the projection must stamp it as the mark so every
+		//    later state is mark-addressable.
+		const created = await hook({
+			tool_name: "TaskCreate",
+			hook_event_name: "PostToolUse",
+			tool_input: { subject: "Ship the fix" },
+			tool_response: { task: { id: "42" } },
+		});
+		expect(created).toEqual({ applied: true, op: "create", taskId: "42" });
+		expect(mocks.create).toHaveBeenCalledTimes(1);
+		const row = store[0];
+		expect(row.title).toBe("Ship the fix");
+		expect(row.status).toBe("todo");
+		expect((row.kind_data as { task_sync: { mark: string } }).task_sync.mark).toBe("42");
+
+		// 2. IN_PROGRESS — PostToolUse:TaskUpdate with status in_progress. Matched
+		//    by the mark stamped at creation; the projection expresses it, it does
+		//    not append a new row.
+		mocks.create.mockClear();
+		const inProgress = await hook({
+			tool_name: "TaskUpdate",
+			hook_event_name: "PostToolUse",
+			tool_input: { taskId: "42", status: "in_progress" },
+		});
+		expect(inProgress).toEqual({ applied: true, op: "update", taskId: "42" });
+		expect(mocks.create).not.toHaveBeenCalled();
+		expect(mocks.update).toHaveBeenCalledTimes(1);
+		expect(row.status).toBe("in-progress");
+		expect(row.completed).toBe(false);
+		expect(store).toHaveLength(1);
+
+		// 3. COMPLETED — PostToolUse:TaskUpdate with status completed. A projection
+		//    that cannot express completion is an append-only log.
+		mocks.update.mockClear();
+		const done = await hook({
+			tool_name: "TaskUpdate",
+			hook_event_name: "PostToolUse",
+			tool_input: { taskId: "42", status: "completed" },
+		});
+		expect(done).toEqual({ applied: true, op: "update", taskId: "42" });
+		expect(mocks.update).toHaveBeenCalledTimes(1);
+		expect(row.status).toBe("done");
+		expect(row.completed).toBe(true);
+		expect(store).toHaveLength(1);
+
+		// 4. DELETED — PostToolUse:TaskDelete. The row leaves the projection; the
+		//    list empties, which is the half a create-only projection can never do.
+		const deleted = await hook({
+			tool_name: "TaskDelete",
+			hook_event_name: "PostToolUse",
+			tool_input: { taskId: "42" },
+		});
+		expect(deleted).toEqual({ applied: true, op: "delete", taskId: "42" });
+		expect(mocks.deleteMany).toHaveBeenCalledTimes(1);
+		expect(store).toHaveLength(0);
+	});
+
+	it("stamps the mark on a title-matched update so a later rename is mark-addressable", async () => {
+		// A row written with NO mark (pre-mark history, or a healed row) is only
+		// reachable by title. The first title-match must stamp the mark so the row
+		// never orphans on a later rename (the 2026-07-28 stranded-subtask class).
+		const { hook, store } = makeFixture();
+		store.push({
+			id: "legacy-1",
+			parent_id: "task-1",
+			title: "Old title",
+			status: "todo",
+			completed: false,
+			kind_data: {},
+		});
+
+		await hook({
+			tool_name: "TaskUpdate",
+			hook_event_name: "PostToolUse",
+			tool_input: { taskId: "99", subject: "Old title", status: "in_progress" },
+		});
+		expect((store[0].kind_data as { task_sync: { mark: string } }).task_sync.mark).toBe("99");
+		expect(store[0].status).toBe("in-progress");
+	});
+
+	it("is idempotent on a retried TaskCreate (no duplicate subtask)", async () => {
+		// The hook curls with --retry, so one TaskCreate can arrive twice. A
+		// projection that duplicates on retry is not a projection.
+		const { hook, store } = makeFixture();
+		const evt = {
+			tool_name: "TaskCreate",
+			hook_event_name: "PostToolUse",
+			tool_input: { subject: "Once only" },
+			tool_response: { task: { id: "7" } },
+		};
+		await hook(evt);
+		const second = await hook(evt);
+		// The retried create matches the stored mark and is discarded, not doubled.
+		expect(second.applied).toBe(false);
+		expect(store.filter((s) => s.title === "Once only")).toHaveLength(1);
+	});
+});

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

@@ -0,0 +1,36 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Behavioral tests for canonical CLI-session lane resolution.
+ */
+import { describe, expect, it } from "bun:test";
+import { resolveLaneWorkName } from "./task-sync-lane.ts";
+
+describe("resolveLaneWorkName", () => {
+	it("reads the visible label from the active cli_sessions route", async () => {
+		let query: unknown;
+		const name = await resolveLaneWorkName(
+			{
+				cli_sessions: {
+					findFirst: async (args: unknown) => {
+						query = args;
+						return { id: "session-1", label: "ZeroStack" };
+					},
+				},
+			} as never,
+			"tmux:%7",
+		);
+		expect(name).toBe("ZeroStack");
+		expect(query).toMatchObject({ where: { host_route: { path: ["pane_id"], equals: "tmux:%7" } } });
+	});
+
+	it("returns no unverified title when no active session owns the pane", async () => {
+		const name = await resolveLaneWorkName(
+			{ cli_sessions: { findFirst: async () => null } } as never,
+			"tmux:%8",
+		);
+		expect(name).toBeNull();
+	});
+});

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

@@ -12,6 +12,7 @@
 import { describe, expect, it } from "bun:test";
 import {
 	STATUS_TO_WORK_ITEM,
+	deriveEvidenceProgress,
 	normalizeStatus,
 	planReconcile,
 	resolveProjectedStatus,
@@ -29,6 +30,31 @@ describe("STATUS_TO_WORK_ITEM", () => {
 	});
 });
 
+describe("evidence-derived task progress", () => {
+	it("counts only required subtasks with independent Orchestrator acceptance", () => {
+		const out = deriveEvidenceProgress(
+			[
+				{ id: "a", status: "done" },
+				{ id: "b", status: "done" },
+				{ id: "c", status: "todo", kind_data: { pm_progress: { required: false } } },
+			],
+			[
+				{ work_item_id: "a", sender_role: "orchestrator", system_key: "acceptance:a" },
+				{ work_item_id: "b", sender_role: "worker", system_key: "acceptance:b" },
+			],
+		);
+		expect(out).toEqual({ total: 2, accepted: 1, percentage: 50 });
+	});
+
+	it("does not treat prose, context, or done alone as evidence", () => {
+		expect(
+			deriveEvidenceProgress([{ id: "a", status: "done" }], [
+				{ work_item_id: "a", sender_role: "orchestrator", system_key: "progress:100" },
+			]),
+		).toEqual({ total: 1, accepted: 0, percentage: 0 });
+	});
+});
+
 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

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

@@ -74,6 +74,57 @@ export function normalizeStatus(s: string | null): TaskListItem["status"] {
 	return (s && WORK_ITEM_TO_STATUS[s]) || "pending";
 }
 
+export interface ProgressSubtask {
+	id: string;
+	status: string | null;
+	kind_data?: Record<string, unknown> | null;
+}
+
+export interface ProgressAcceptanceEvidence {
+	work_item_id: string | null;
+	sender_role: string | null;
+	system_key: string | null;
+}
+
+export interface EvidenceProgress {
+	total: number;
+	accepted: number;
+	percentage: number;
+}
+
+/**
+ * Derive progress from the canonical checklist and independent acceptance
+ * comments. A done status without an Orchestrator acceptance comment is not
+ * evidence of completion; prose percentages and context gauges never enter
+ * this calculation. Subtasks are required by default, with an explicit
+ * `kind_data.pm_progress.required: false` opt-out for non-gating notes.
+ */
+export function deriveEvidenceProgress(
+	subtasks: ProgressSubtask[],
+	evidence: ProgressAcceptanceEvidence[],
+): EvidenceProgress {
+	const required = subtasks.filter(
+		(s) => (s.kind_data?.pm_progress as { required?: boolean } | undefined)?.required !== false,
+	);
+	const accepted = new Set(
+		evidence
+			.filter(
+				(e) =>
+					e.sender_role === "orchestrator" &&
+					typeof e.system_key === "string" &&
+					e.system_key.startsWith("acceptance:") &&
+					e.work_item_id,
+			)
+			.map((e) => e.work_item_id as string),
+	);
+	const acceptedCount = required.filter((s) => s.status === "done" && accepted.has(s.id)).length;
+	return {
+		total: required.length,
+		accepted: acceptedCount,
+		percentage: required.length === 0 ? 0 : Math.round((acceptedCount / required.length) * 100),
+	};
+}
+
 /**
  * Decide the status to WRITE for an existing row, given what the CLI list says.
  *

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

@@ -0,0 +1,53 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit directly
+ *
+ * Unit tests for the rename back-write leg: renameOutcome (the pure
+ * no-task ⇒ not-updated decision) + source-contract assertions that the handler
+ * resolves the lane task BY SESSION (never pane) and updates its title. Covers
+ * `what-must-have-a-test` for the new procedure + the `lane-identity-is-cli-
+ * session-id` invariant it rides on.
+ */
+import { describe, it, expect } from "bun:test";
+import { renameOutcome } from "./task-sync-rename.ts";
+
+describe("renameOutcome (no verdict from no data)", () => {
+	it("returns not-updated with a null task_id when no task is bound to the session", () => {
+		// A rename of a tab whose lane has no resolvable task updates nothing —
+		// never an error, never a fake id. updated:false is the signal the caller
+		// treats as best-effort (the window was already renamed; this only missed
+		// the DB echo, which is the rare archived-and-pruned case).
+		expect(renameOutcome(null)).toEqual({ task_id: null, updated: false });
+	});
+
+	it("returns the bound task id + updated:true when a task resolves", () => {
+		expect(renameOutcome({ id: "task-9" })).toEqual({ task_id: "task-9", updated: true });
+	});
+});
+
+describe("renameLaneTask resolves BY SESSION and writes the title (source contract)", () => {
+	const renameSrc = Bun.file(new URL("./task-sync-rename.ts", import.meta.url).pathname);
+
+	it("resolves the lane task by lane_session (the CLI session id), never by pane", async () => {
+		// `lane-identity-is-cli-session-id`: binding is by session because a pane
+		// outlives the session inside it. A pane-keyed rename would let a dead
+		// session's task answer for a live lane.
+		const text = await renameSrc.text();
+		expect(text).toContain("resolveLaneTask(prisma, lane_session)");
+		// No pane matching anywhere in the resolution path.
+		expect(text).not.toContain("lane.pane");
+	});
+
+	it("updates the resolved task's title by id", async () => {
+		const text = await renameSrc.text();
+		expect(text).toContain('where: { id: task.id }');
+		expect(text).toContain("data: { title }");
+	});
+
+	it("requires lane_session + title at the signature (incomplete rename unconstructible)", async () => {
+		const text = await renameSrc.text();
+		expect(text).toContain('lane_session: v.pipe(v.string()');
+		expect(text).toContain('title: v.pipe(v.string()');
+	});
+});

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

@@ -0,0 +1,111 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane RENAME back-write for task-sync: a tab rename EMITS to update the bound
+ * work_items task's title in the DB, by CLI session id. This is the DB half of
+ * `tab-rename-emits-back-to-task-title`: the operator's tab bar is how they see
+ * what is being worked on (`lane-labels-and-task-lists`), so the tmux window
+ * name and the task title must never diverge silently. Renaming a tab from
+ * `scala-tools session rename` (or the lane renaming itself through the same
+ * surface) updates the task title so the project board agrees with the tab bar.
+ *
+ * THE EMISSION, not a poll (`actions-are-rows-then-emissions`): a caller renames
+ * the window (a row/state change) and that change emits the title update — the
+ * task-sync owner reacts by updating the row. State lives in the row, never in a
+ * return value a caller may never receive.
+ *
+ * Bound by CLI SESSION ID, never pane id (`lane-identity-is-cli-session-id`): a
+ * pane OUTLIVES the session inside it, so matching on a pane would let a dead
+ * session's task answer for a live lane. The session is the stable identity a
+ * rename resolves to (the daemon resolves the pane's tab → its stored session id
+ * and passes that here), so the rename lands on the lane that owns the tab.
+ *
+ * Split out of task-sync-router.ts for the same reason task-sync-brief/lane/
+ * assign exist: the router sits at its 1000-line commit gate, so every cohesive
+ * task-sync unit that can live in a sibling does. This owns the rename handler +
+ * its pure outcome decision.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Bound to the work_items 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 } from "./task-sync-router.ts";
+import { authed, type Context } from "./auth-router.ts";
+import { resolveLaneTask } from "./task-sync-lane.ts";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+/**
+ * renameLaneTask ORPC input. `lane_session` is the lane's CLI-native session id
+ * (kind_data.lane.session) — the stable identity a pane rename resolves to.
+ * `title` is the new task title (the renamed tab's label). Both required:
+ * oRPC rejects a call missing either at the signature
+ * (`prevention-over-detection`), so a malformed rename is a 400, never a silent
+ * no-op that leaves the title stale.
+ */
+export const renameLaneTaskInput = v.object({
+	lane_session: v.pipe(v.string(), v.minLength(1, "lane_session is required")),
+	title: v.pipe(v.string(), v.minLength(1, "title is required")),
+});
+
+/**
+ * The rename outcome from a resolved lane task — pure so the "no task bound ⇒
+ * not updated, never an error" decision is unit-testable with no DB. A rename
+ * whose lane has no task is best-effort (returns updated:false): every spawn
+ * now mints a task, so this is the rare case (a tab whose task was archived and
+ * pruned), not a path the operator hits. Failing loudly here would refuse a
+ * rename of the WINDOW for a DB miss, which couples two surfaces that must not
+ * be — the tmux rename already succeeded before this is called.
+ */
+export function renameOutcome(task: { id: string } | null): {
+	task_id: string | null;
+	updated: boolean;
+} {
+	if (!task) return { task_id: null, updated: false };
+	return { task_id: task.id, updated: true };
+}
+
+/**
+ * renameLaneTask ORPC handler. The session-picker daemon calls this from
+ * `/rpc/rename` after it renames the tmux window: it resolves the pane's tab to
+ * its session id and posts it here. Same transport as bindLane/readTaskList:
+ * page-gate-exempt (fn.taskSync), localhost super-admin. Resolves the lane's
+ * task BY SESSION (never pane) and updates its title. Idempotent: renaming to
+ * the same title writes the same row.
+ *
+ * An archived parent is matched too (resolveLaneTask falls back to the archived
+ * lane task for the session), so a rename of a tab whose run closed still lands
+ * on its task — the title is the title regardless of run state.
+ */
+export const renameLaneTaskHandler = authed
+	.input(renameLaneTaskInput)
+	.handler(async ({ input, context }) => {
+		const ctx = context as Context;
+		const prisma = ctx.prisma as Prisma;
+		const { lane_session, title } = input;
+		const task = await resolveLaneTask(prisma, lane_session);
+		const outcome = renameOutcome(task);
+		if (!task) return outcome;
+		try {
+			await prisma.work_items.update({
+				where: { id: task.id },
+				data: { title },
+				select: { id: true },
+			});
+		} catch (err) {
+			// The window was already renamed by the caller; a DB update failure must
+			// not surface as an error that implies the rename failed. Report
+			// not-updated + log, so the two surfaces stay decoupled
+			// (`a-component-may-not-report-a-state-it-has-not-verified`).
+			getAppLogger().warn("[task-sync] renameLaneTask: title update failed", {
+				taskId: task.id,
+				error: err instanceof Error ? err.message : String(err),
+			});
+			return { task_id: task.id, updated: false };
+		}
+		return outcome;
+	});

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

@@ -337,8 +337,20 @@ describe("a blocked row survives a CLI list that cannot express it", () => {
 	it("planReconcile leaves a blocked subtask blocked when the list says pending", () => {
 		// The end-to-end shape: this is what re-blocked the lane three times.
 		const plan = planReconcile(
-			[{ mark: "1", content: "Deploy the fix", status: "pending" }],
-			[{ id: "row-1", title: "Deploy the fix", status: "blocked", completed: false, position: "0", kind_data: { task_sync: { mark: "1" } } }] as never,
+			[
+				{
+					id: "row-1",
+					kind: "subtask",
+					parent_id: "task-1",
+					organisation_id: "org-1",
+					title: "Deploy the fix",
+					status: "blocked",
+					position: "0",
+					completed: false,
+					kind_data: { task_sync: { mark: "1" } },
+				},
+			],
+			[{ content: "Deploy the fix", status: "pending" }],
 			"claude-code",
 		);
 		const update = plan.toUpdate.find((u) => u.id === "row-1");