@teamscala/service-boot 0.23.329 → 0.23.331

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

@@ -0,0 +1,125 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Lane RESOLUTION for task-sync: given a session or a pane, which work_items
+ * task IS this lane, and what is it called.
+ *
+ * Split out of task-sync-router.ts, which had reached 998 of its 1000-line
+ * budget — two lines from frozen. That is not tidiness: the budget is a commit
+ * gate, so at 998 lines ANY change to task-sync was blocked for every lane, and
+ * the four-line fix that needed to land could not. The router header records
+ * being split once before for exactly this reason; it grew back.
+ *
+ * The seam matches the one that split the projection. Everything here answers
+ * "which lane, called what" from an identity, and none of it touches the ORPC
+ * surface or decides what a task list should become — which is why these move
+ * together rather than one at a time: resolveLaneTask alone has seven callers.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Checked against the 14 platform singletons and the package
+ * catalogue; the doctrine test fails plainly, because every export is bound to
+ * the work_items schema and to task-sync own kind_data.lane convention, so no
+ * unrelated app could install this unmodified.
+ */
+
+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 },
+			orderBy: { created_at: "desc" },
+			select: { slot_name: true },
+		});
+		const name = run?.slot_name?.trim();
+		return name ? name : null;
+	} catch {
+		return null;
+	}
+}
+
+export async function resolveLaneTask(prisma: Prisma, session: string): Promise<WorkItem | null> {
+	const active = await prisma.work_items.findFirst({
+		where: {
+			kind: "task",
+			status: "active",
+			kind_data: { path: ["lane", "session"], equals: session },
+		},
+		// Deterministic by oldest. An unordered findFirst returns whichever row
+		// Postgres happens to hand back, so with two parents for one lane (the
+		// bindLane race, below) one turn wrote the lane's todos under parent A
+		// and the next read parent B and found nothing — the lane's task list
+		// appeared to empty itself, and the watchdog accused lanes that were
+		// holding a populated list. Migration 109 makes the duplicate
+		// unwritable; this makes the read stable regardless.
+		orderBy: { created_at: "asc" },
+	});
+	if (active) return active;
+
+	// FALL BACK TO AN ARCHIVED PARENT FOR THE SAME SESSION.
+	//
+	// Closing a run archives the lane's parent (close-run.ts) specifically to
+	// drop it from the active match set above. That is correct when the LANE is
+	// gone, and wrong whenever the run record closes while the lane keeps
+	// running — which happens on a tmux-server restart (runs are reaped, panes
+	// are restored) and whenever an orchestrator closes a run on a stale read.
+	// The lane then has a full task list that this function cannot see, so
+	// callers mint a FRESH parent, the old list is orphaned, and the compliance
+	// watchdog reports "working with NO task list" at a lane holding 85 tasks.
+	// That is the "KNOWN ADJACENT DEFECT" recorded on the lane-working-has-task-list
+	// guard row, observed live 2026-07-31.
+	//
+	// Safe because a session id is minted per lane spawn and never reused, so an
+	// archived parent under this session belongs to THIS lane. Newest-first.
+	return prisma.work_items.findFirst({
+		where: {
+			kind: "task",
+			status: "archived",
+			kind_data: { path: ["lane", "session"], equals: session },
+		},
+		orderBy: { created_at: "desc" },
+	});
+}
+
+/**
+ * Resolve a lane's task by its AUTHORITATIVE work_item id — the id the spawn
+ * minted (createBriefTask) and exported into the pane as SCALA_LANE_WORK_ITEM.
+ *
+ * WHY this exists alongside the session resolution: readAssignedBrief used to
+ * resolve ONLY by kind_data.lane.session, which is written by the lane's OWN
+ * bindLane hook at boot. That bind is a fire-and-forget POST racing the brief
+ * read, so a fleet lane whose bind had not yet commit read "no task" and the
+ * self-brief hook silently exited 0 — absent-input-reads-as-success at the
+ * dispatch boundary (a lane booted, was told its brief was loaded, had none,
+ * ran nothing, and was archived having done nothing — measured 2026-08-02).
+ *
+ * The work_item id is known to the spawn before the lane even starts
+ * (mintBriefTask returns it; the spawn REFUSES if minting fails for a capture
+ * CLI), so resolving by it CANNOT race: the row exists because the spawn
+ * created it. The session bind stays for task-list writes (upsertFromTaskList)
+ * — it is no longer load-bearing for brief delivery. Any status is matched
+ * (active OR archived) because the brief is the brief regardless of the run's
+ * state — closing a run archives the task, not the brief.
+ */
+export async function resolveTaskById(prisma: Prisma, workItemId: string): Promise<WorkItem | null> {
+	return prisma.work_items.findFirst({
+		where: { id: workItemId, kind: "task" },
+	});
+}

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

@@ -0,0 +1,121 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The task-sync PROJECTION: how a CLI's task list maps onto `work_items` rows,
+ * and what reconciling one against the other should do.
+ *
+ * Split out of `task-sync-router.ts`, which had grown past the 1000-line budget
+ * and so could not be committed by anyone touching it. The seam is real rather
+ * than arbitrary: everything here is PURE and decides WHAT should change, while
+ * the router owns the ORPC surface and performs the writes. That is exactly why
+ * this half is directly testable with no database.
+ *
+ * CAPABILITY HARVEST (capability-harvest-on-split): APP-LOCAL, not a capability
+ * candidate. Checked against the 14 platform singletons and the package catalog
+ * — nothing generic to fold into, and the doctrine test fails: no unrelated app
+ * could install this unmodified, because every export is bound to the
+ * `work_items` schema and task-sync's own contract (STATUS_TO_WORK_ITEM encodes
+ * the work_items status enum, subtaskKey is this projection's key convention,
+ * planReconcile diffs against work_items subtask rows).
+ *
+ * The near-miss is worth naming so the next reader does not re-derive it: the
+ * SHAPE — diff a desired list against existing rows into create/update/delete —
+ * is generic, and `document-signing` is precedent for lifting a pure domain half
+ * out of service-boot into a package. It stays here because it has exactly one
+ * consumer; extracting it now would be speculative packaging, which
+ * platform-capabilities treats as drift. Revisit if a SECOND surface needs
+ * list-against-rows reconciliation — then the generic diff core (not the
+ * work_items-specific mapping) is what earns a package.
+ */
+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"];
+/**
+ * Decide the status to WRITE for an existing row, given what the CLI list says.
+ *
+ * The CLI task list has no `blocked` state, so a blocked row round-trips as
+ * `pending` (via `normalizeStatus`, which collapses unknown/internal statuses)
+ * and then maps back to `todo` — silently destroying the block. That is not a
+ * cosmetic drift: the stop gate reads these rows, so un-blocking one re-blocks
+ * the LANE from stopping, and the lane's only apparent fix is to touch the list
+ * again, which destroys it again.
+ *
+ * A `todo` arriving from the CLI therefore carries NO information: it is what
+ * the projection emits for every status it cannot represent, not an assertion
+ * that the work became un-blocked. `in-progress` and `done` are different —
+ * those are real transitions the CLI CAN express, so they win normally.
+ *
+ * Measured 2026-07-30: a lane set a row to `blocked` with a named blocker, the
+ * next TaskUpdate reset it to `todo`, and the stop gate reported the lane
+ * unfinished again — three turns of ping-pong before the cause was found.
+ */
+export declare function resolveProjectedStatus(currentStatus: string | null | undefined, incomingStatus: string): string;
+export declare function subtaskKey(item: {
+    mark?: string;
+    content: string;
+    title: string;
+}): string;
+/**
+ * Pure decision for a TaskUpdate/TaskDelete: which existing subtask does this
+ * event address, and what should happen when none does. Extracted for the same
+ * reason planReconcile was — the handler should only EXECUTE, so the matching
+ * rule is unit-testable.
+ *
+ * Three resolutions:
+ *  - `update` — matched by mark, or (mark absent/unstamped) by exact title.
+ *  - `heal`   — nothing matched but the event carries a subject, so the row can
+ *               be reconstructed. Covers a TaskCreate that silently produced no
+ *               subtask, which previously orphaned the task forever.
+ *  - `discard` — nothing matched and there is no subject to rebuild a title from.
+ *
+ * Measured 2026-07-28: marks "1" and "3" were stamped for one lane while mark
+ * "2" was never written at all, and every later update for it was dropped as
+ * `no-matching-subtask` — 26 of 30 tasksync discards in six hours, across seven
+ * distinct lane sessions, were that one reason.
+ */
+export declare function resolveTaskUpdateTarget(existing: Array<{
+    id: string;
+    title: string;
+    kind_data?: Record<string, unknown> | null;
+}>, evt: {
+    taskId: string;
+    subject?: string;
+}): {
+    op: "update";
+    id: string;
+} | {
+    op: "heal";
+    title: string;
+} | {
+    op: "discard";
+};
+/**
+ * Pure reconciliation plan: given the lane's EXISTING subtasks and its INCOMING
+ * (current) task list, compute the create/update/delete ops that make the
+ * subtask set match the list — WITHOUT touching prisma. Extracted so the
+ * matching/status/positioning logic is unit-testable (the handler only executes
+ * the plan). Matching is by stable mark when the CLI provides one, else by
+ * content. Position follows incoming index, so a reorder is an update.
+ */
+export interface ReconcilePlan {
+    toCreate: Array<{
+        content: string;
+        status: string;
+        completed: boolean;
+        position: string;
+        kind_data: Record<string, unknown>;
+    }>;
+    toUpdate: Array<{
+        id: string;
+        content: string;
+        status: string;
+        completed: boolean;
+        position: string;
+        kind_data: Record<string, unknown>;
+    }>;
+    toDelete: string[];
+}
+export declare function planReconcile(existing: WorkItem[], incoming: TaskListItem[], source?: string): ReconcilePlan;

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

@@ -12,7 +12,6 @@
 import { describe, expect, it } from "bun:test";
 import {
 	STATUS_TO_WORK_ITEM,
-	deriveEvidenceProgress,
 	normalizeStatus,
 	planReconcile,
 	resolveProjectedStatus,
@@ -30,31 +29,6 @@ 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,57 +74,6 @@ 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.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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 Context } from "./auth-router.ts";
+/**
+ * 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 declare const renameLaneTaskInput: v.ObjectSchema<{
+    readonly lane_session: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "lane_session is required">]>;
+    readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "title is required">]>;
+}, undefined>;
+/**
+ * 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 declare function renameOutcome(task: {
+    id: string;
+} | null): {
+    task_id: string | null;
+    updated: boolean;
+};
+/**
+ * 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 declare const renameLaneTaskHandler: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+    headers: Headers;
+    resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+    prisma: any;
+    user: import("./auth-router.ts").User;
+    orgId: string | null | undefined;
+}>, v.ObjectSchema<{
+    readonly lane_session: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "lane_session is required">]>;
+    readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "title is required">]>;
+}, undefined>, import("@orpc/contract").Schema<{
+    task_id: string | null;
+    updated: boolean;
+}, {
+    task_id: string | null;
+    updated: boolean;
+}>, Record<never, never>, Record<never, never>>;