@teamscala/service-boot 0.23.284

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

@@ -0,0 +1,109 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Tests for classifyTaskHookEvent — the discriminator between the Claude task
+ * lifecycle legs.
+ *
+ * The regression this locks: `TaskCreated` and `TaskCompleted` BOTH carry
+ * `task_subject`, so the handler's original "has a subject → it's a creation"
+ * test could not tell them apart. Only `TaskCreated` was ever wired, so nothing
+ * exercised the ambiguity — but the moment completion is wired, a completion
+ * classified as a creation mints a DUPLICATE subtask instead of closing one.
+ * That is the operator-visible symptom exactly: a task list that only ever
+ * grows, with everything reading incomplete (`task-projection-converges`).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { classifyTaskHookEvent, sanitizeTaskSubject } from "./task-sync-router.ts";
+
+describe("classifyTaskHookEvent", () => {
+	test("a completion carrying a subject is COMPLETED, not a creation", () => {
+		// The exact shape the TaskCompleted hook delivers: subject present.
+		expect(
+			classifyTaskHookEvent({
+				hook_event_name: "TaskCompleted",
+				task_subject: "Verify bindLane populates Task",
+			}),
+		).toBe("completed");
+	});
+
+	test("a creation carrying a subject is CREATED", () => {
+		expect(
+			classifyTaskHookEvent({
+				hook_event_name: "TaskCreated",
+				task_subject: "Verify bindLane populates Task",
+			}),
+		).toBe("created");
+	});
+
+	test("subject alone still classifies as created (payloads predating hook_event_name)", () => {
+		expect(classifyTaskHookEvent({ task_subject: "Some task" })).toBe("created");
+	});
+
+	test("a PostToolUse-shaped payload with no subject falls through to the tool leg", () => {
+		expect(classifyTaskHookEvent({})).toBe("tool");
+		expect(classifyTaskHookEvent({ hook_event_name: "PostToolUse" })).toBe("tool");
+	});
+
+	test("event name WINS over subject presence — the whole point", () => {
+		// If this ever inverts, completions silently become duplicate creations.
+		const completed = classifyTaskHookEvent({
+			hook_event_name: "TaskCompleted",
+			task_subject: "x",
+		});
+		const created = classifyTaskHookEvent({
+			hook_event_name: "TaskCreated",
+			task_subject: "x",
+		});
+		expect(completed).not.toBe(created);
+	});
+});
+
+// The subjects below are the REAL corrupted values found in work_items on
+// 2026-07-25 — three rows whose titles rendered on the fleet dashboard as a
+// wall of XML where the operator expects a task name. The malformation happens
+// upstream in the CLI's hook payload, so the write boundary is the only place
+// that can stop it reaching the single source of truth every surface reads.
+describe("sanitizeTaskSubject", () => {
+	test("cuts the leaked tool call, keeping the real subject", () => {
+		expect(
+			sanitizeTaskSubject(
+				'Cut judge false positives on clean work</subject>\n<parameter name="description">Live gate blocks ~half of clean drafts (7 of 7 failures were clean).',
+			),
+		).toBe("Cut judge false positives on clean work");
+
+		expect(
+			sanitizeTaskSubject(
+				'Give benchmark drafts synthetic tool activity</subject>\n<parameter name="description">The labelled suite sends drafts with no tool activity.',
+			),
+		).toBe("Give benchmark drafts synthetic tool activity");
+	});
+
+	test("cuts on a bare next-parameter marker with no closing tag", () => {
+		expect(sanitizeTaskSubject('Do the thing<parameter name="description">blah')).toBe(
+			"Do the thing",
+		);
+	});
+
+	test("leaves an ordinary subject untouched", () => {
+		// Including ones with punctuation that merely LOOKS structural — angle
+		// brackets alone are not a leak, only the tool-call markers are.
+		expect(sanitizeTaskSubject("Bound the pg-boss pool")).toBe("Bound the pg-boss pool");
+		expect(sanitizeTaskSubject("  Fix a < b comparison  ")).toBe("Fix a < b comparison");
+		expect(sanitizeTaskSubject("Rename foo -> bar")).toBe("Rename foo -> bar");
+	});
+
+	test("truncates rather than discards, so the task is not lost", () => {
+		// Dropping the row would lose a task the lane genuinely created; the text
+		// before the marker is the real subject and is worth keeping.
+		expect(sanitizeTaskSubject("Real subject</subject>junk").length).toBeGreaterThan(0);
+	});
+
+	test("an entirely-markup subject collapses to empty so the caller discards it", () => {
+		// The create leg treats "" as no-subject and records a discard — correct,
+		// because there is no real title to keep here.
+		expect(sanitizeTaskSubject('</subject><parameter name="description">x')).toBe("");
+	});
+});

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

@@ -0,0 +1,44 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Unit tests for the pure event-payload builder in task-sync-dispatch. The HTTP
+ * POST + registry resolution are side-effectful (covered end-to-end by the
+ * DB->AGENT direction demo — a published orchestrator.message with slotName
+ * cross-pane delivers to the target pane's <channel> tag); buildTaskChangedEvent
+ * is pure and tested here. Satisfies what-must-have-a-test / primitive-api-has-test.
+ */
+import { describe, it, expect } from "bun:test";
+import { buildTaskChangedEvent } from "./task-sync-dispatch.ts";
+
+describe("task-sync buildTaskChangedEvent", () => {
+	it("is an orchestrator.message addressed to the owning lane pane", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.type).toBe("orchestrator.message");
+		expect(e.orchestratorSessionId).toBe("tmux:%5");
+	});
+
+	it("uses slotName cross-pane so watchEvents bypasses the fleet-run-existence check", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.slotName).toBe("cross-pane");
+	});
+
+	it("carries the task id in the message so the recipient can re-read just it", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.message).toContain("task-7");
+		expect(e.message).toContain("readTaskList");
+	});
+
+	it("produces a single-line message (the <channel> tag renders it inline)", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.message.includes("\n")).toBe(false);
+	});
+
+	it("stamps the system sender + a deterministic runId + the provided epoch-ms ts", () => {
+		const e = buildTaskChangedEvent("tmux:%5", "task-7", 1700000000000);
+		expect(e.fromOrchestratorId).toBe("task-sync");
+		expect(e.runId).toBe("task-sync-task-7-1700000000000");
+		expect(e.ts).toBe(1700000000000);
+	});
+});

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

@@ -0,0 +1,124 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * DB→AGENT dispatch for task-sync — notifies a lane's live pane that its
+ * work_items task list changed out-of-band (operator toggled a subtask in the
+ * projects UI, another lane edited a shared task). The pane's adapter then
+ * re-reads (fn.taskSync.readTaskList) and updates its native list.
+ *
+ * MECHANISM — reuses the existing CLI-agnostic channel delivery, no new
+ * transport: a POST to scala-channel's fleet-events publish entry
+ * (POST /api/fleet/events — @teamscala/channel/fleet-events-publish) carrying an
+ * `orchestrator.message` FleetEvent with slotName "cross-pane". That slot is
+ * the watchEvents bypass for events NOT tied to a fleet_agent_runs row
+ * (FleetEventOrchestratorMessageSchema comment) — exactly the system-originated
+ * case. scala-channel re-emits onto its eventBus and streamFleetEvents delivers
+ * to the subscriber filtered by orchestratorSessionId (the target lane pane).
+ * Both the Claude Code relay and the OpenCode scala-hooks plugin subscribe to
+ * that SSE stream for their own pane identity and inject each event natively —
+ * so ONE publish reaches every CLI that has a live projection, no per-CLI
+ * dispatch code here.
+ *
+ * NOT the dispatch entry (POST /api/channel/send): that path requires a real
+ * sender pane identity (channel-sender-identity-validated anti-spoof) and so
+ * cannot carry a system-originated notification. The publish path is
+ * internal-trusted (localhost super-admin) and accepts a synthetic
+ * fromOrchestratorId — the correct path for a system→pane message.
+ *
+ * scala-channel's address is resolved from its service_routing row (local_port)
+ * — never hardcoded (service-ports-from-registry). Fire-and-forget: a dispatch
+ * failure (scala-channel down, port unresolvable) is logged and swallowed; it
+ * must never block the work_items write that triggered it, and the lane's
+ * SessionStart/UserPromptSubmit backstop picks up the change on its next turn
+ * regardless.
+ */
+
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { ServiceRoutingConfigSchema } from "@teamscala/db-validation/registry-schemas/service-routing";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+let cachedChannelBaseUrl: string | null | undefined;
+
+async function resolveChannelBaseUrl(): Promise<string | null> {
+	if (cachedChannelBaseUrl !== undefined) return cachedChannelBaseUrl;
+	try {
+		const row = await loadRegistryConfig("service_routing", "scala-channel", ServiceRoutingConfigSchema);
+		const port = row?.local_port;
+		cachedChannelBaseUrl = port ? `http://127.0.0.1:${port}` : null;
+	} catch {
+		cachedChannelBaseUrl = null;
+	}
+	return cachedChannelBaseUrl;
+}
+
+/** The system sender identity stamped on fromOrchestratorId. */
+const FROM_ORCHESTRATOR_ID = "task-sync";
+
+/**
+ * The `orchestrator.message` FleetEvent payload that notifies a lane its task
+ * list changed. Pure (no I/O) so it is unit-testable; notifyLaneOfTaskChange
+ * posts it. slotName "cross-pane" is REQUIRED — it is the watchEvents bypass for
+ * events not tied to a fleet_agent_runs row. orchestratorSessionId is the TARGET
+ * lane pane (the SSE subscriber filter). The message is single-line (the
+ * <channel> tag renders it inline).
+ */
+export interface TaskChangedEvent {
+	type: "orchestrator.message";
+	message: string;
+	fromOrchestratorId: string;
+	runId: string;
+	slotName: "cross-pane";
+	ts: number;
+	orchestratorSessionId: string;
+}
+
+export function buildTaskChangedEvent(lanePane: string, taskId: string, now: number = Date.now()): TaskChangedEvent {
+	return {
+		type: "orchestrator.message",
+		message: `TaskSync: your work_items task list changed externally (task ${taskId}). Re-read via fn.taskSync.readTaskList and update your todo list.`,
+		fromOrchestratorId: FROM_ORCHESTRATOR_ID,
+		runId: `task-sync-${taskId}-${now}`,
+		slotName: "cross-pane",
+		ts: now,
+		orchestratorSessionId: lanePane,
+	};
+}
+
+/**
+ * Publish a "your task list changed" notification to the owning lane's pane.
+ * The pane identity is the stable tmux id ("tmux:%42") every CLI relay/plugin
+ * receives for. `taskId` is carried in the message so the recipient can re-read
+ * just that task. Fire-and-forget.
+ */
+export async function notifyLaneOfTaskChange(
+	lanePane: string,
+	taskId: string,
+): Promise<void> {
+	const log = getAppLogger();
+	if (!lanePane) return;
+	const base = await resolveChannelBaseUrl();
+	if (!base) {
+		log.warn("[task-sync] notifyLaneOfTaskChange: scala-channel address unresolvable", { taskId });
+		return;
+	}
+	const payload = buildTaskChangedEvent(lanePane, taskId);
+	try {
+		const res = await fetch(`${base}/api/fleet/events`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(3000),
+		});
+		if (!res.ok) {
+			log.warn("[task-sync] notifyLaneOfTaskChange: non-2xx from scala-channel", {
+				taskId, status: res.status,
+			});
+		}
+	} catch (err) {
+		log.warn("[task-sync] notifyLaneOfTaskChange: POST failed", {
+			taskId, error: err instanceof Error ? err.message : String(err),
+		});
+	}
+}

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

@@ -0,0 +1,279 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Unit tests for the pure task-sync reconciliation logic (planReconcile +
+ * status mapping). The ORPC handlers only EXECUTE the plan against prisma; the
+ * matching / status / positioning decisions live here so they are unit-testable
+ * without a DB. Covers `what-must-have-a-test` for the public API.
+ */
+import { describe, it, expect } from "bun:test";
+import {
+	resolveTaskUpdateTarget,
+	planReconcile,
+	normalizeStatus,
+	subtaskKey,
+	STATUS_TO_WORK_ITEM,
+	type TaskListItem,
+} from "./task-sync-router.ts";
+
+interface WorkItemLike {
+	id: string;
+	kind: string;
+	parent_id: string | null;
+	organisation_id: string;
+	title: string;
+	status: string | null;
+	position: string | null;
+	completed: boolean | null;
+	kind_data: Record<string, unknown>;
+}
+
+function subtask(opts: Partial<WorkItemLike> & { id: string; title: string }): WorkItemLike {
+	return {
+		kind: "subtask",
+		parent_id: "task-1",
+		organisation_id: "org-1",
+		status: "todo",
+		position: null,
+		completed: false,
+		kind_data: {},
+		...opts,
+	};
+}
+
+const item = (content: string, status: TaskListItem["status"] = "pending", mark?: string): TaskListItem => ({
+	content,
+	status,
+	...(mark !== undefined ? { mark } : {}),
+});
+
+describe("task-sync status mapping", () => {
+	it("maps normalized status to the work_items DB enum (hyphenated in-progress)", () => {
+		expect(STATUS_TO_WORK_ITEM.pending).toBe("todo");
+		expect(STATUS_TO_WORK_ITEM.in_progress).toBe("in-progress");
+		expect(STATUS_TO_WORK_ITEM.completed).toBe("done");
+	});
+
+	it("normalizes work_items status back to the CLI form", () => {
+		expect(normalizeStatus("todo")).toBe("pending");
+		expect(normalizeStatus("in-progress")).toBe("in_progress");
+		expect(normalizeStatus("done")).toBe("completed");
+		expect(normalizeStatus("active")).toBe("in_progress");
+		expect(normalizeStatus(null)).toBe("pending");
+		expect(normalizeStatus("unknown-state")).toBe("pending");
+	});
+});
+
+describe("task-sync subtaskKey", () => {
+	it("prefers a stable mark over content when present", () => {
+		expect(subtaskKey({ mark: "m1", content: "ignored", title: "ignored" })).toBe("m1");
+	});
+	it("falls back to content when no mark", () => {
+		expect(subtaskKey({ content: "Build it", title: "Build it" })).toBe("Build it");
+	});
+});
+
+describe("task-sync planReconcile", () => {
+	it("creates every incoming item when there are no existing subtasks", () => {
+		const plan = planReconcile([], [item("A"), item("B", "in_progress")]);
+		expect(plan.toCreate).toHaveLength(2);
+		expect(plan.toCreate[0]).toMatchObject({ content: "A", status: "todo", position: "0", completed: false });
+		expect(plan.toCreate[1]).toMatchObject({ content: "B", status: "in-progress", position: "1", completed: false });
+		expect(plan.toUpdate).toHaveLength(0);
+		expect(plan.toDelete).toHaveLength(0);
+	});
+
+	it("emits no ops when existing already matches incoming (idempotent)", () => {
+		const existing = [
+			subtask({ id: "1", title: "A", status: "todo", position: "0", completed: false }),
+		];
+		const plan = planReconcile(existing, [item("A")]);
+		expect(plan.toCreate).toHaveLength(0);
+		expect(plan.toUpdate).toHaveLength(0);
+		expect(plan.toDelete).toHaveLength(0);
+	});
+
+	it("updates status + completed when a matched item changed", () => {
+		const existing = [subtask({ id: "1", title: "A", status: "todo", position: "0", completed: false })];
+		const plan = planReconcile(existing, [item("A", "completed")]);
+		expect(plan.toUpdate).toEqual([
+			expect.objectContaining({ id: "1", status: "done", completed: true, position: "0" }),
+		]);
+		expect(plan.toCreate).toHaveLength(0);
+		expect(plan.toDelete).toHaveLength(0);
+	});
+
+	it("updates position on reorder (same content, different index)", () => {
+		const existing = [
+			subtask({ id: "1", title: "A", status: "todo", position: "0" }),
+			subtask({ id: "2", title: "B", status: "todo", position: "1" }),
+		];
+		const plan = planReconcile(existing, [item("B"), item("A")]);
+		expect(plan.toUpdate.map((u) => [u.id, u.position])).toEqual([
+			["2", "0"],
+			["1", "1"],
+		]);
+	});
+
+	it("deletes existing subtasks absent from the incoming list", () => {
+		const existing = [
+			subtask({ id: "1", title: "A", position: "0" }),
+			subtask({ id: "2", title: "B", position: "1" }),
+		];
+		const plan = planReconcile(existing, [item("A")]);
+		expect(plan.toDelete).toEqual(["2"]);
+		expect(plan.toUpdate).toHaveLength(0);
+	});
+
+	it("matches by stable mark across a content rename, updating content", () => {
+		const existing = [
+			subtask({ id: "1", title: "Old text", status: "todo", position: "0", kind_data: { task_sync: { mark: "m1" } } }),
+		];
+		const plan = planReconcile(existing, [item("New text", "pending", "m1")]);
+		expect(plan.toUpdate).toEqual([
+			expect.objectContaining({ id: "1", content: "New text" }),
+		]);
+		expect(plan.toCreate).toHaveLength(0);
+		expect(plan.toDelete).toHaveLength(0);
+	});
+
+	it("ignores blank incoming content", () => {
+		const plan = planReconcile([], [item("   "), item("Real")]);
+		expect(plan.toCreate).toHaveLength(1);
+		expect(plan.toCreate[0].content).toBe("Real");
+	});
+
+	it("carries source into kind_data.task_sync for traceability", () => {
+		const plan = planReconcile([], [item("A")], "claude-code");
+		expect(plan.toCreate[0].kind_data).toEqual({ task_sync: { mark: undefined, source: "claude-code" } });
+	});
+});
+
+// --- resolveTaskUpdateTarget (added 2026-07-28) ----------------------------
+// The gap these close: the update path matched ONLY on kind_data.task_sync.mark,
+// so a subtask whose mark was never stamped — or a TaskCreate that silently
+// produced no row at all — was unaddressable forever. Every later update for it
+// was dropped as `no-matching-subtask`: 26 of 30 tasksync discards in six hours,
+// across seven distinct lane sessions, all one reason. One lane had marks "1"
+// and "3" stamped correctly while "2" was missing entirely, so a whole work item
+// left no trace in the fleet's record.
+describe("task-sync resolveTaskUpdateTarget", () => {
+	const marked = (id: string, title: string, mark?: string) => ({
+		id,
+		title,
+		kind_data: mark ? { task_sync: { mark } } : {},
+	});
+
+	it("matches by mark when stamped", () => {
+		const r = resolveTaskUpdateTarget([marked("a", "Alpha", "1")], { taskId: "1" });
+		expect(r).toEqual({ op: "update", id: "a" });
+	});
+
+	it("falls back to exact title when the mark was never stamped", () => {
+		// The unmarked-row case: mark lookup misses, title still identifies it.
+		const r = resolveTaskUpdateTarget([marked("a", "Alpha")], {
+			taskId: "1",
+			subject: "Alpha",
+		});
+		expect(r).toEqual({ op: "update", id: "a" });
+	});
+
+	it("does not cross-match a different task's mark", () => {
+		const r = resolveTaskUpdateTarget([marked("a", "Alpha", "1")], { taskId: "2" });
+		expect(r).toEqual({ op: "discard" });
+	});
+
+	it("heals a missed create when the event carries a subject", () => {
+		// The mark-"2"-never-written case: nothing to match, but the subject is
+		// enough to rebuild the row instead of orphaning the task forever.
+		const r = resolveTaskUpdateTarget([marked("a", "Alpha", "1")], {
+			taskId: "2",
+			subject: "Bravo",
+		});
+		expect(r).toEqual({ op: "heal", title: "Bravo" });
+	});
+
+	it("discards only when there is no subject to rebuild a title from", () => {
+		const r = resolveTaskUpdateTarget([marked("a", "Alpha", "1")], { taskId: "2" });
+		expect(r).toEqual({ op: "discard" });
+	});
+
+	it("prefers the mark over a same-subject title collision", () => {
+		const r = resolveTaskUpdateTarget(
+			[marked("a", "Same", "1"), marked("b", "Same", "2")],
+			{ taskId: "2", subject: "Same" },
+		);
+		expect(r).toEqual({ op: "update", id: "b" });
+	});
+
+	it("ignores a blank subject rather than healing a titleless row", () => {
+		const r = resolveTaskUpdateTarget([], { taskId: "9", subject: "   " });
+		expect(r).toEqual({ op: "discard" });
+	});
+});
+
+// --- rename must not orphan an unmarked row (added 2026-07-28) --------------
+describe("a rename cannot orphan an unmarked subtask", () => {
+	// Matching is mark-first, then EXACT TITLE. A row that has never been stamped
+	// can therefore only ever be found by its title — so the moment a task is
+	// RENAMED, neither match succeeds, the event heals into a NEW row, and the
+	// pre-rename row is orphaned at whatever status it held. Nothing in the
+	// single-event path will ever address it again.
+	//
+	// Observed on this lane 2026-07-28: three subtasks stranded at `todo` and
+	// `in-progress` under their OLD titles while the CLI's own list read empty,
+	// which is what made the stop gate refuse a lane that had genuinely finished.
+	// `task-projection-converges` requires the projection to express every state a
+	// task reaches; a row it can no longer address expresses nothing.
+
+	it("an unmarked row is still reachable by exact title", () => {
+		// The pre-condition for the whole failure: without a mark, TITLE is the
+		// only handle, so it works right up until the title changes.
+		const existing = [{ id: "row-1", title: "Original title", kind_data: null }];
+		expect(resolveTaskUpdateTarget(existing, { taskId: "7", subject: "Original title" })).toEqual({
+			op: "update",
+			id: "row-1",
+		});
+	});
+
+	it("renaming an UNMARKED row heals into a new one — the orphan", () => {
+		// This is the defect, asserted so the cost of NOT stamping is explicit: the
+		// update does not reach row-1, which stays at its old status forever.
+		const existing = [{ id: "row-1", title: "Original title", kind_data: null }];
+		expect(resolveTaskUpdateTarget(existing, { taskId: "7", subject: "Renamed title" })).toEqual({
+			op: "heal",
+			title: "Renamed title",
+		});
+	});
+
+	it("once marked, a rename updates the SAME row", () => {
+		// The fix: the first title-match stamps the mark, so every later rename is
+		// mark-addressable and lands on the original row. The heal path already
+		// stamped on create; the update path was the missing half.
+		const existing = [
+			{ id: "row-1", title: "Original title", kind_data: { task_sync: { mark: "7" } } },
+		];
+		expect(resolveTaskUpdateTarget(existing, { taskId: "7", subject: "Renamed title" })).toEqual({
+			op: "update",
+			id: "row-1",
+		});
+	});
+
+	it("the update path stamps the mark when the row has none", async () => {
+		// Asserted against the source because the write is inside an ORPC handler
+		// that needs a live prisma context. The regression is the absence of a
+		// stamp, which no pure test on resolveTaskUpdateTarget can observe.
+		const src = await Bun.file(
+			new URL("./task-sync-router.ts", import.meta.url).pathname,
+		).text();
+		expect(src).toContain("const alreadyMarked");
+		expect(src).toContain("if (taskId && !alreadyMarked)");
+		// Prior kind_data must be preserved — the lane binding and any other
+		// sibling keys live there, and clobbering them would trade this bug for a
+		// worse one.
+		expect(src).toContain("...priorKindData");
+		expect(src).toContain("...priorSync");
+	});
+});