@teamscala/service-boot 0.23.329 → 0.23.331

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

@@ -0,0 +1,444 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ * @indivisible-unit
+ *
+ * CLI-AGNOSTIC task-sync CORE — the bridge between a lane's native task list
+ * (Claude Code TodoWrite, OpenCode todowrite, future CLIs) and the `work_items`
+ * table, which is the single source of truth for "what work does this lane
+ * have." Detailed contract + the per-CLI adapter split: apps/agent-fleet.md
+ * (task-sync section).
+ *
+ * Design (operator requirement): work_items is the source; each CLI's task list
+ * is a WRITE-THROUGH PROJECTION, never a peer. One source + write-through
+ * projection cannot diverge by construction — no two-way sync, no conflict
+ * resolution. The lane↔task binding is SYMMETRIC: a lane is a lane whether the
+ * pane is an orchestrator or a supervised agent (both have tasks).
+ *
+ * Mapping: an operator request = a kind='task' work_item; the lane's todo items
+ * = kind='subtask' rows under it via parent_id. The task carries the lane
+ * 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).
+ *
+ * These procedures are the ONLY CLI-agnostic surface an adapter calls:
+ *   bindLane           — bind (create-or-confirm) a lane's task. SessionStart.
+ *   closeLane          — reconcile a session-owned lane before its runtime releases it.
+ *   upsertFromTaskList — write a lane's current task list through to subtasks (AGENT→DB leg, OpenCode whole-list).
+ *   upsertFromTaskHook — apply a per-item Claude Code PostToolUse:TaskCreate/Update/Delete (AGENT→DB leg, Claude per-item).
+ *   readTaskList       — read a lane's current subtasks as a normalized list (DB→AGENT backstop).
+ *   applyExternalChange — record an out-of-band subtask change + notify the owning lane (DB→AGENT realtime leg).
+ * A CLI with no native task surface (Codex today — upstream_issue openai-codex-2966)
+ * has NO adapter: it degrades to work_items-only. The work is still tracked and
+ * visible in the projects UI; the lane simply has no live projection. That is a
+ * legitimate end state, not a gap to paper over with a fake adapter.
+ */
+import { type Context } from "./auth-router.ts";
+import * as v from "valibot";
+/** A lane's native task-list item, normalized. Every CLI adapter maps to this. */
+export interface TaskListItem {
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    /** CLI-native stable id when the CLI provides one (TodoWrite has none; opencode todo row id). */
+    mark?: string;
+}
+/**
+ * Input contract for upsertFromTaskList. oRPC does NOT parse the JSON body into
+ * `input` for a schema-less procedure (see the bindLane comment in this file) —
+ * so without an explicit `.input()` schema, `input.lane_session` is ALWAYS
+ * undefined and the procedure throws "requires lane_session" unconditionally.
+ * Measured 2026-07-29: every pi/opencode whole-list `task_list` publish 400'd
+ * for exactly this reason (the per-item upsertFromTaskHook path worked because
+ * it unwraps `raw.json ?? raw`). Declaring the schema is the documented remedy
+ * and the pattern every other `authed.input(...)` procedure in service-boot
+ * already follows. The pi adapter (scala-hooks.ts syncTaskList) already sends
+ * `{ lane_session, task_list, source }` — it was always valid; the server never
+ * read it.
+ */
+export declare const upsertFromTaskListInput: v.ObjectSchema<{
+    readonly lane_session: v.StringSchema<undefined>;
+    readonly task_list: v.ArraySchema<v.ObjectSchema<{
+        readonly content: v.StringSchema<undefined>;
+        readonly status: v.PicklistSchema<["pending", "in_progress", "completed"], undefined>;
+        readonly mark: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+/** Who a lane IS — symmetric across orchestrator/agent roles and across CLIs. */
+export interface LaneIdentity {
+    /** "tmux:%42" — authoritative pane identity ($TMUX_PANE). */
+    pane: string;
+    session?: string;
+    /** pane-inventory inferCliKind: claude-code | opencode | codex | unknown. */
+    cli_kind?: string;
+    /** agent | orchestrator — both have tasks; the model does not assume a supervised agent. */
+    role?: string;
+    /**
+     * Optional. work_items.organisation_id is NOT NULL; when the caller omits it
+     * (auto-bind at SessionStart — an adopted or channel-dispatched lane has no
+     * client org), bindLane defaults to the platform org via resolveBindOrg.
+     */
+    organisation_id?: string;
+}
+export interface WorkItem {
+    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>;
+}
+export type Prisma = {
+    work_items: {
+        findFirst: (a: unknown) => Promise<WorkItem | null>;
+        findMany: (a: unknown) => Promise<WorkItem[]>;
+        create: (a: unknown) => Promise<WorkItem>;
+        update: (a: unknown) => Promise<WorkItem>;
+        deleteMany: (a: unknown) => Promise<{
+            count: number;
+        }>;
+    };
+    comments?: {
+        findFirst: (a: unknown) => Promise<CommentRow | null>;
+    };
+};
+/** A `comments` row — only the fields readAssignedBrief touches. */
+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
+ * otherwise — an adopted or channel-dispatched pane has no client org, and the
+ * platform org is the home for fleet/internal lane tasks (where the operator's
+ * PM view reads), so auto-bind at SessionStart seeds the task there.
+ */
+export declare function resolveBindOrg(explicit?: string): string;
+/**
+ * Record a task-sync hook DISCARD to event_log so it is observable + queryable,
+ * not silently swallowed by the hook command's `>/dev/null 2>&1 || true`. The
+ * endpoint records it server-side regardless of what the hook does with stdout.
+ * Fire-and-forget per event-log-is-the-only-durable-event-log. The headline
+ * discard is "no-task-bound" (lane has no bound parent task — exactly the gap
+ * that SessionStart auto-bind closes; once binding is automatic this becomes a
+ * rare safety signal rather than the default outcome).
+ */
+export declare function recordTaskSyncDiscard(reason: string, pane: string | null, extra?: Record<string, unknown>): void;
+/**
+ * Record a discard AND return the soft {applied:false} body in one step — every
+ * no-op path in upsertFromTaskHook goes through here so none can silently drop
+ * an event. The returned shape matches the prior `{applied:false, reason,...}`.
+ */
+export declare function discardApplied(reason: string, pane: string | null, extra?: Record<string, unknown>): {
+    applied: false;
+    reason: string;
+} & Record<string, unknown>;
+/**
+ * Trim a task subject at the first tool-call marker.
+ *
+ * A subject arriving as `Cut judge false positives</subject>\n<parameter
+ * name="description">Live gate blocks ~half...` is not a title with odd
+ * punctuation — it is the raw tool call, and it renders on the dashboard as a
+ * wall of XML where the operator expects a task name (observed live 2026-07-25,
+ * 3 rows). The malformation happens upstream in the CLI's hook payload, which
+ * this service does not control, so the defence belongs at the WRITE boundary:
+ * `work_items` is the single source of truth for every surface, and once a
+ * corrupted title lands there every reader shows it.
+ *
+ * Truncating rather than rejecting is deliberate: the text BEFORE the marker is
+ * the real subject and is worth keeping. Dropping the row instead would lose a
+ * task the lane genuinely created.
+ */
+export declare function sanitizeTaskSubject(raw: string): string;
+export declare function classifyTaskHookEvent(evt: {
+    hook_event_name?: unknown;
+    task_subject?: unknown;
+}): "completed" | "created" | "tool";
+export declare const taskSyncRouter: {
+    /**
+     * Bind (create-or-confirm) the task a lane owns. Called from a SessionStart
+     * 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.
+     */
+    bindLane: 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.OptionalSchema<v.ObjectSchema<{
+        readonly lane: v.OptionalSchema<v.ObjectSchema<{
+            readonly pane: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly session: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly cli_kind: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly role: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly organisation_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        readonly title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly parent_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>, import("@orpc/contract").Schema<{
+        task_id: string;
+        created: boolean;
+    }, {
+        task_id: string;
+        created: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * AGENT→DB leg. Write a lane's CURRENT task list through to subtasks. The
+     * list is authoritative for this lane (it's what the CLI just rendered), so
+     * this is a full reconcile: create/update/delete to match. Matching is by
+     * stable mark when the CLI provides one, else by content. Does NOT dispatch
+     * a change notification — the lane that authored the list already has it.
+     */
+    upsertFromTaskList: 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.StringSchema<undefined>;
+        readonly task_list: v.ArraySchema<v.ObjectSchema<{
+            readonly content: v.StringSchema<undefined>;
+            readonly status: v.PicklistSchema<["pending", "in_progress", "completed"], undefined>;
+            readonly mark: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        task_id: string;
+        created: number;
+        updated: number;
+        deleted: number;
+        total: number;
+    }, {
+        task_id: string;
+        created: number;
+        updated: number;
+        deleted: number;
+        total: number;
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * Claude Code PostToolUse:TaskCreate/TaskUpdate hook entry. Claude Code's
+     * todo tool is the per-item Task* family (TaskCreate/TaskUpdate) — TodoWrite
+     * was REMOVED in recent Claude Code; the hook matcher keys on
+     * TaskCreate/TaskUpdate, never TodoWrite. The hook command posts the RAW hook
+     * event (stdin) + an x-lane-pane header (tmux:$TMUX_PANE). Fired as a
+     * PostToolUse:TaskCreate/Update hook (NOT a "TaskCreated" event — that is
+     * not a real Claude Code hook event + never fired); this procedure
+     * applies the per-item change (TaskCreate → new subtask keyed by the harness
+     * task id; TaskUpdate → status/title flip on the matching subtask). Server-
+     * side extraction keeps the hook command a trivial jq|curl. Accepts the event
+     * raw (input.tool_name) OR oRPC-enveloped (input.json.tool_name). Session-
+     * less: fn.taskSync is page-gate-exempt; localhost pane shell authenticates
+     * as super-admin via resolveUser. Soft-returns on any no-op (never throws).
+     */
+    upsertFromTaskHook: 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;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        applied: boolean;
+        op: string;
+        taskId: string;
+    } | ({
+        applied: false;
+        reason: string;
+    } & Record<string, unknown>), {
+        applied: boolean;
+        op: string;
+        taskId: string;
+    } | ({
+        applied: false;
+        reason: string;
+    } & Record<string, unknown>)>, Record<never, never>, Record<never, never>>;
+    /**
+     * DB→AGENT backstop read. Returns the lane's current subtasks in the
+     * normalized shape every CLI adapter maps to its native list. Called by the
+     * SessionStart/UserPromptSubmit adapters so a pane never opens or continues
+     * on stale tasks, and by a lane after it receives a "your tasks changed"
+     * channel notification.
+     */
+    readTaskList: 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;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        task_id: null;
+        task_title: null;
+        subtasks: never[];
+    } | {
+        task_id: string;
+        task_title: string;
+        subtasks: TaskListItem[];
+    }, {
+        task_id: null;
+        task_title: null;
+        subtasks: never[];
+    } | {
+        task_id: string;
+        task_title: string;
+        subtasks: TaskListItem[];
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * DB→AGENT self-brief leg. A spawned lane PULLS its own brief — nothing is
+     * pasted, typed, passed as an argument or sent over a channel
+     * (`action-emission-architecture.md` "The lane PULLS its brief"). The lane's
+     * CLI extension reads its own session id on load, calls this procedure, and
+     * reads the brief from the task's LATEST comment. The comment — not the
+     * description, not a stale comment — is the brief for THIS run: every spawn
+     * writes a NEW comment, so "what was this lane told" always has exactly one
+     * answer (`assignment-as-dispatch`). Handler lives in task-sync-brief.ts
+     * (router is at its line budget); mounted here so fn.taskSync surfaces it.
+     */
+    readAssignedBrief: 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;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        work_item_id: string | null;
+        brief: string | null;
+        comment_created_at: string | null;
+        status: import("./task-sync-brief.ts").BriefReadStatus;
+    }, {
+        work_item_id: string | null;
+        brief: string | null;
+        comment_created_at: string | null;
+        status: import("./task-sync-brief.ts").BriefReadStatus;
+    }>, Record<never, never>, Record<never, never>>;
+    /** SPAWNER→DB brief mint: `spawn_agent_tab` turns an initialPrompt into the task row (brief = first comment) the lane self-briefs from; returns the work_item_id that rides the spawn payload. Handler in task-sync-assign.ts. */
+    createBriefTask: 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;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        work_item_id: string;
+    }, {
+        work_item_id: string;
+    }>, Record<never, never>, Record<never, never>>;
+    /** RUNTIME→DB lifecycle close: mark lane.live=false and reconcile task status before the ACP owner releases the session. */
+    closeLane: 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 disposition: v.PicklistSchema<["completed", "needs_retry", "failed", "orchestrator_closed", "orphaned"], undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        task_id: string;
+        task_status: "archived" | "done";
+        reconciled: boolean;
+    }, {
+        task_id: string;
+        task_status: "archived" | "done";
+        reconciled: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * TAB→DB rename back-write: the session-picker `/rpc/rename` calls this after
+     * renaming a tmux window to update the bound task's title BY SESSION (never
+     * pane), so the tab bar and the project board never diverge
+     * (`tab-rename-emits-back-to-task-title`). Handler in task-sync-rename.ts.
+     */
+    renameLaneTask: 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>>;
+    /**
+     * DB→AGENT realtime leg (explicit dispatch path). Record an out-of-band
+     * change to a subtask's status (operator toggles it in the projects UI,
+     * another lane edits a shared task) and notify the OWNING lane's pane that
+     * its projection is stale. The pane's adapter re-reads (readTaskList) and
+     * updates its native list. Symmetric counterpart to upsertFromTaskList:
+     * 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.
+     */
+    applyExternalChange: 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;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        task_id: string;
+        lane_pane: string | null;
+        notified: boolean;
+    }, {
+        task_id: string;
+        lane_pane: string | null;
+        notified: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+};
+/**
+ * The Claude Code per-item task lifecycle applied to a lane's work_items
+ * subtasks — the AGENT→DB leg for the Task* tool family (TaskCreate /
+ * TaskUpdate / TaskDelete) and the dedicated TaskCreated / TaskCompleted events.
+ *
+ * Extracted verbatim from the upsertFromTaskHook ORPC handler so the FULL
+ * lifecycle — created, in_progress, completed, deleted — is unit-testable with a
+ * mock prisma (same testability split as claim-orchestrator-session, and the
+ * router-handlers-only-execute half of planReconcile). The ORPC handler is now a
+ * thin `authed` wrapper that delegates here; this function takes the exact
+ * `(input, context)` the handler would have bound, so behaviour is unchanged.
+ *
+ * `task-projection-converges`: every state a task reaches must write through, or
+ * the projection is an append-only log and the operator cannot see what a lane is
+ * doing. The matcher covering TaskCreate|TaskUpdate|TaskDelete is what makes all
+ * four states reach this handler; this body is what applies them.
+ */
+export declare function upsertFromTaskHookHandler(input: unknown, context: Context): Promise<{
+    applied: boolean;
+    op: string;
+    taskId: string;
+} | ({
+    applied: false;
+    reason: string;
+} & Record<string, unknown>)>;

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

@@ -337,20 +337,8 @@ 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(
-			[
-				{
-					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" }],
+			[{ 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,
 			"claude-code",
 		);
 		const update = plan.toUpdate.find((u) => u.id === "row-1");