@teamscala/service-boot 0.23.335 → 0.23.336

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

@@ -3,122 +3,79 @@
  * @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.
+ * DB→AGENT task projection emission. A work_items change is delivered by one
+ * canonical comments row addressed to the active cli_sessions runtime; the
+ * database emission wakes that runtime adapter, which re-reads readTaskList.
+ * This module owns no pane transport, terminal fallback, or second message
+ * queue.
  */
 
-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;
+export interface TaskChangeComment {
+	work_item_id: string;
+	content: string;
+	system_key: string;
+	source_cli_session_id: string;
+	sender_role: "system";
+	sender_name: "TaskSync";
 }
 
-/** 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 buildTaskChangeComment(
+	taskId: string,
+	sessionId: string,
+	eventKey: string = "refresh",
+): TaskChangeComment {
+	return {
+		work_item_id: taskId,
+		content: `TaskSync: work_items task ${taskId} changed; re-read fn.taskSync.readTaskList.`,
+		system_key: `task-sync:${taskId}:${sessionId}:${eventKey}`,
+		source_cli_session_id: sessionId,
+		sender_role: "system",
+		sender_name: "TaskSync",
+	};
 }
 
-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,
+export interface TaskDispatchPrisma {
+	cli_sessions: {
+		findFirst(args: unknown): Promise<{ id: string } | null>;
+	};
+	comments: {
+		upsert(args: {
+			where: { work_item_id_system_key: { work_item_id: string; system_key: string } };
+			create: TaskChangeComment;
+			update: Record<string, never>;
+		}): Promise<{ id: string }>;
 	};
 }
 
-/**
- * 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.
- */
+/** Write the durable task-change comment for the active runtime, if present. */
 export async function notifyLaneOfTaskChange(
-	lanePane: string,
+	prisma: TaskDispatchPrisma,
 	taskId: string,
-): Promise<void> {
+	eventKey: string = "refresh",
+): Promise<{ delivered: boolean; sessionId: string | null; commentId: string | null }> {
 	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);
+	const session = await prisma.cli_sessions.findFirst({
+		where: { work_item_id: taskId, closed_at: null, lifecycle_state: { not: "closed" } },
+		orderBy: { created_at: "desc" },
+		select: { id: true },
+	});
+	if (!session) return { delivered: false, sessionId: null, commentId: null };
 	try {
-		const res = await fetch(`${base}/api/fleet/events`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify(payload),
-			signal: AbortSignal.timeout(3000),
+		const data = buildTaskChangeComment(taskId, session.id, eventKey);
+		const comment = await prisma.comments.upsert({
+			where: { work_item_id_system_key: { work_item_id: taskId, system_key: data.system_key } },
+			create: data,
+			update: {},
 		});
-		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),
+		return { delivered: true, sessionId: session.id, commentId: comment.id };
+	} catch (error) {
+		log.warn("[task-sync] durable task comment emission failed", {
+			taskId,
+			sessionId: session.id,
+			error: error instanceof Error ? error.message : String(error),
 		});
+		return { delivered: false, sessionId: session.id, commentId: null };
 	}
 }

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-lane.ts

@@ -28,27 +28,16 @@ import type { Prisma, WorkItem } from "./task-sync-router.ts";
 
 export async function resolveLaneWorkName(prisma: Prisma, pane: string): Promise<string | null> {
 	try {
-		const runs = (
-			prisma as unknown as {
-				fleet_agent_runs?: {
-					findFirst: (a: unknown) => Promise<{ slot_name?: string | null } | null>;
-				};
-			}
-		).fleet_agent_runs;
-		if (!runs?.findFirst) return null;
-		// Most recent run for the pane, REGARDLESS of state. A lane's work name does
-		// not vanish when its run closes, and filtering `state != closed` here is
-		// exactly why task rows were titled "Lane": a task-list write (ensureLaneTask)
-		// that fires after the run closed resolved no name and fell back to the
-		// generic sentinel — spawn debris an orchestrator cannot attribute
-		// (measured 2026-08-01: 207 "Lane" rows). Newest-first so a reused pane
-		// resolves its CURRENT lane, not a prior one.
-		const run = await runs.findFirst({
-			where: { pane },
+		const session = await prisma.cli_sessions.findFirst({
+			where: {
+				closed_at: null,
+				lifecycle_state: { not: "closed" },
+				host_route: { path: ["pane_id"], equals: pane },
+			},
 			orderBy: { created_at: "desc" },
-			select: { slot_name: true },
+			select: { id: true, label: true },
 		});
-		const name = run?.slot_name?.trim();
+		const name = session?.label?.trim();
 		return name ? name : null;
 	} catch {
 		return null;

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

@@ -33,6 +33,29 @@ import type { TaskListItem, WorkItem } from "./task-sync-router.ts";
 /** 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"];
+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 declare function deriveEvidenceProgress(subtasks: ProgressSubtask[], evidence: ProgressAcceptanceEvidence[]): EvidenceProgress;
 /**
  * Decide the status to WRITE for an existing row, given what the CLI list says.
  *

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-router.d.ts

@@ -21,8 +21,8 @@
  * identity in kind_data.lane = { pane, session, cli_kind, role } so any surface
  * (fleet UI, another lane) can resolve "who owns this work" and push changes
  * back. Binding is by pane identity (the stable $TMUX_PANE), not by fleet run —
- * so it works before/without the fleet_agent_runs.work_item_id join (that column
- * is a UI convenience for the unified lane+task+subtask view, not a dependency).
+ * so it works without any second runtime-assignment join; the canonical runtime
+ * identity remains cli_sessions and the assignment remains work_items.
  *
  * These procedures are the ONLY CLI-agnostic surface an adapter calls:
  *   bindLane           — bind (create-or-confirm) a lane's task. SessionStart.
@@ -38,6 +38,7 @@
  */
 import { type Context } from "./auth-router.ts";
 import * as v from "valibot";
+import { type ProgressAcceptanceEvidence } from "./task-sync-projection.ts";
 /** A lane's native task-list item, normalized. Every CLI adapter maps to this. */
 export interface TaskListItem {
     content: string;
@@ -104,8 +105,15 @@ export type Prisma = {
             count: number;
         }>;
     };
+    cli_sessions: {
+        findFirst: (a: unknown) => Promise<{
+            id: string;
+            label?: string | null;
+        } | null>;
+    };
     comments?: {
         findFirst: (a: unknown) => Promise<CommentRow | null>;
+        findMany: (a: unknown) => Promise<Array<ProgressAcceptanceEvidence>>;
     };
 };
 /** A `comments` row — only the fields readAssignedBrief touches. */
@@ -113,18 +121,6 @@ export interface CommentRow {
     content: string;
     created_at: Date;
 }
-/**
- * A dispatched run already points at its fleet_tasks row. Task-sync may fill
- * the convenience join for an adopted lane, but must never replace that
- * dispatch identity with the lane's work_items projection id.
- */
-export declare function untrackedRunForPane(pane: string): {
-    pane: string;
-    state: {
-        not: string;
-    };
-    tracked_task_id: null;
-};
 /**
  * Resolve the org a lane's task is created under. Explicit when the lane knows
  * its org (a dispatched fleet lane carries one); defaults to the platform org
@@ -179,8 +175,7 @@ export declare const taskSyncRouter: {
      * adapter so the lane has a durable task row before its first todo write.
      * Idempotent: re-binding updates the identity (role/cli_kind can change) but
      * never orphans existing subtasks. After binding, links the lane's
-     * fleet_agent_runs row (matched by pane) to the task via tracked_task_id —
-     * the join the operator's lane-labels monitor + the unified fleet view read.
+     * cli_sessions is the runtime identity and work_items is the assignment.
      */
     bindLane: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
         headers: Headers;
@@ -292,18 +287,30 @@ export declare const taskSyncRouter: {
         task_id: null;
         task_title: null;
         subtasks: never[];
+        progress: {
+            total: number;
+            accepted: number;
+            percentage: number;
+        };
     } | {
         task_id: string;
         task_title: string;
         subtasks: TaskListItem[];
+        progress: import("./task-sync-projection.ts").EvidenceProgress;
     }, {
         task_id: null;
         task_title: null;
         subtasks: never[];
+        progress: {
+            total: number;
+            accepted: number;
+            percentage: number;
+        };
     } | {
         task_id: string;
         task_title: string;
         subtasks: TaskListItem[];
+        progress: import("./task-sync-projection.ts").EvidenceProgress;
     }>, Record<never, never>, Record<never, never>>;
     /**
      * DB→AGENT self-brief leg. A spawned lane PULLS its own brief — nothing is
@@ -399,11 +406,9 @@ export declare const taskSyncRouter: {
      * there the lane is the originator (no self-echo); here the lane is the
      * recipient.
      *
-     * COMPLETION STEP (not MVP): this procedure is the explicit trigger. For
-     * FULL coverage — every work_items subtask write, including the projects
-     * UI's generated CRUD — a Postgres trigger + LISTEN subscriber on
-     * scala-channel fires the same publish, so an operator edit reaches the
-     * lane with no explicit call. Tracked in apps/agent-fleet.md task-sync.
+     * Every call writes the canonical task-change comment for the active
+     * cli_sessions row; the database comment emission is the delivery trigger.
+     * There is no pane transport or secondary channel publisher here.
      */
     applyExternalChange: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
         headers: Headers;
@@ -413,11 +418,13 @@ export declare const taskSyncRouter: {
         orgId: string | null | undefined;
     }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
         task_id: string;
-        lane_pane: string | null;
+        cli_session_id: string | null;
+        comment_id: string | null;
         notified: boolean;
     }, {
         task_id: string;
-        lane_pane: string | null;
+        cli_session_id: string | null;
+        comment_id: string | null;
         notified: boolean;
     }>, Record<never, never>, Record<never, never>>;
 };

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");