@wrongstack/webui-server 0.302.0 → 0.303.0

package/dist/server/handlers/worklist-handlers.d.ts

@@ -12,22 +12,41 @@ export interface WorklistContext {
     send: (ws: WebSocket, msg: WSServerMessage) => void;
     broadcast: (msg: WSServerMessage) => void;
     replaceTodos?: ((todos: TodoItem[]) => void) | undefined;
+    mutateTodos?: ((todos: TodoItem[]) => Promise<{
+        todos: TodoItem[];
+        warnings?: string[] | undefined;
+    }>) | undefined;
+    mutateTaskStatus?: ((id: string, status: 'pending' | 'in_progress' | 'blocked' | 'failed' | 'review' | 'completed') => Promise<{
+        ok: boolean;
+        message: string;
+    }>) | undefined;
+    mutatePlan?: ((operation: {
+        action: 'template_use';
+        template: string;
+    } | {
+        action: 'status';
+        target: string;
+        status: 'open' | 'in_progress' | 'done';
+    }) => Promise<{
+        ok: boolean;
+        message: string;
+    }>) | undefined;
 }
 export interface WorklistMessage {
     type: string;
     payload?: unknown;
 }
 export declare function handleTodosGet(ctx: WorklistContext, ws: WebSocket): void;
-export declare function handleTodosClear(ctx: WorklistContext, ws: WebSocket): void;
+export declare function handleTodosClear(ctx: WorklistContext, ws: WebSocket): Promise<void>;
 export declare function handleTodosRemove(ctx: WorklistContext, ws: WebSocket, payload: {
     id?: string | undefined;
     index?: number | undefined;
-} | undefined): void;
+} | undefined): Promise<void>;
 export declare function handleTodoUpdate(ctx: WorklistContext, ws: WebSocket, payload: {
-    id: string;
+    id?: string | undefined;
     status?: TodoItem['status'] | undefined;
     activeForm?: string | undefined;
-}): void;
+} | undefined): Promise<void>;
 export declare function handleTasksGet(ctx: WorklistContext, ws: WebSocket): Promise<void>;
 export declare function handleTaskUpdate(ctx: WorklistContext, ws: WebSocket, payload: {
     id: string;

package/dist/server/handlers.js

@@ -55,12 +55,34 @@ function handleTodosGet(ctx, ws) {
     payload: sessionPayload(ctx, { todos: [...ctx.context.todos] })
   });
 }
-function handleTodosClear(ctx, ws) {
-  ctx.replaceTodos?.([]);
-  sendResult(ctx, ws, true, "Todos cleared");
-  ctx.broadcast({ type: "todos.updated", payload: sessionPayload(ctx, { todos: [] }) });
+async function commitTodos(ctx, todos) {
+  if (ctx.mutateTodos) {
+    const result = await ctx.mutateTodos(todos);
+    return { todos: result.todos, warnings: result.warnings ?? [] };
+  }
+  ctx.replaceTodos?.(todos);
+  return { todos: [...todos], warnings: [] };
+}
+function managedProjectionMessage() {
+  return "Kanban-bound todos are task projections. Change or remove the task from Kanban.";
 }
-function handleTodosRemove(ctx, ws, payload) {
+async function handleTodosClear(ctx, ws) {
+  if (ctx.context.todos.some((todo) => todo.kanbanBoardId && todo.kanbanTaskId)) {
+    sendResult(ctx, ws, false, managedProjectionMessage());
+    return;
+  }
+  try {
+    const result = await commitTodos(ctx, []);
+    sendResult(ctx, ws, true, "Todos cleared");
+    ctx.broadcast({
+      type: "todos.updated",
+      payload: sessionPayload(ctx, { todos: result.todos })
+    });
+  } catch (error) {
+    sendResult(ctx, ws, false, error instanceof Error ? error.message : String(error));
+  }
+}
+async function handleTodosRemove(ctx, ws, payload) {
   if (!payload) {
     sendResult(ctx, ws, false, "Missing id or index");
     return;
@@ -77,12 +99,27 @@ function handleTodosRemove(ctx, ws, payload) {
     sendResult(ctx, ws, false, "Todo not found");
     return;
   }
+  if (removed.kanbanBoardId && removed.kanbanTaskId) {
+    sendResult(ctx, ws, false, managedProjectionMessage());
+    return;
+  }
   const next = [...todos.slice(0, targetIndex), ...todos.slice(targetIndex + 1)];
-  ctx.replaceTodos?.(next);
-  sendResult(ctx, ws, true, `Removed: ${removed.content}`);
-  ctx.broadcast({ type: "todos.updated", payload: sessionPayload(ctx, { todos: next }) });
+  try {
+    const result = await commitTodos(ctx, next);
+    sendResult(ctx, ws, true, `Removed: ${removed.content}`);
+    ctx.broadcast({
+      type: "todos.updated",
+      payload: sessionPayload(ctx, { todos: result.todos })
+    });
+  } catch (error) {
+    sendResult(ctx, ws, false, error instanceof Error ? error.message : String(error));
+  }
 }
-function handleTodoUpdate(ctx, ws, payload) {
+async function handleTodoUpdate(ctx, ws, payload) {
+  if (!payload || typeof payload.id !== "string" || payload.status !== void 0 && payload.status !== "pending" && payload.status !== "in_progress" && payload.status !== "completed" || payload.activeForm !== void 0 && typeof payload.activeForm !== "string") {
+    sendResult(ctx, ws, false, "Invalid todo update payload");
+    return;
+  }
   const index = ctx.context.todos.findIndex((todo) => todo.id === payload.id);
   const existing = ctx.context.todos[index];
   if (index === -1 || !existing) {
@@ -95,9 +132,25 @@ function handleTodoUpdate(ctx, ws, payload) {
     status: payload.status ?? existing.status,
     activeForm: payload.activeForm !== void 0 ? payload.activeForm : existing.activeForm
   };
-  ctx.replaceTodos?.(next);
-  sendResult(ctx, ws, true, `Todo "${existing.content}" updated`);
-  ctx.broadcast({ type: "todos.updated", payload: sessionPayload(ctx, { todos: next }) });
+  try {
+    const result = await commitTodos(ctx, next);
+    const projected = result.todos.find((todo) => todo.id === existing.id);
+    const requestedStatus = payload.status ?? existing.status;
+    const projectionRejected = Boolean(existing.kanbanBoardId && existing.kanbanTaskId) && projected?.status !== requestedStatus;
+    const warning = result.warnings[0];
+    sendResult(
+      ctx,
+      ws,
+      !projectionRejected,
+      projectionRejected ? warning ?? `Kanban kept "${existing.content}" at ${projected?.status ?? "its current state"}.` : warning ? `Todo "${existing.content}" updated. ${warning}` : `Todo "${existing.content}" updated`
+    );
+    ctx.broadcast({
+      type: "todos.updated",
+      payload: sessionPayload(ctx, { todos: result.todos })
+    });
+  } catch (error) {
+    sendResult(ctx, ws, false, error instanceof Error ? error.message : String(error));
+  }
 }
 async function handleTasksGet(ctx, ws) {
   const taskPath = taskPathOf(ctx);
@@ -125,14 +178,32 @@ async function handleTaskUpdate(ctx, ws, payload) {
     return;
   }
   try {
-    const file = await mutateTasks(taskPath, currentSessionId(ctx), async (tasks) => {
-      const task = tasks.tasks.find((candidate) => candidate.id === payload.id);
-      if (!task) return tasks;
-      task.status = payload.status;
-      task.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-      return tasks;
-    });
-    sendResult(ctx, ws, true, `Task status updated to "${payload.status}".`);
+    let file;
+    if (ctx.mutateTaskStatus) {
+      const result = await ctx.mutateTaskStatus(payload.id, payload.status);
+      if (!result.ok) {
+        sendResult(ctx, ws, false, result.message);
+        return;
+      }
+      file = await loadTasks(taskPath);
+      if (!file) throw new Error("Task mutation succeeded but its persisted snapshot is missing.");
+      sendResult(ctx, ws, true, result.message);
+    } else {
+      let matched = false;
+      file = await mutateTasks(taskPath, currentSessionId(ctx), async (tasks) => {
+        const task = tasks.tasks.find((candidate) => candidate.id === payload.id);
+        if (!task) return tasks;
+        matched = true;
+        task.status = payload.status;
+        task.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+        return tasks;
+      });
+      if (!matched) {
+        sendResult(ctx, ws, false, `Task "${payload.id}" not found.`);
+        return;
+      }
+      sendResult(ctx, ws, true, `Task status updated to "${payload.status}".`);
+    }
     ctx.broadcast({
       type: "tasks.updated",
       payload: sessionPayload(ctx, { tasks: file.tasks })
@@ -179,6 +250,18 @@ async function handlePlanTemplateUse(ctx, ws, template) {
     return;
   }
   try {
+    if (ctx.mutatePlan) {
+      const result = await ctx.mutatePlan({ action: "template_use", template });
+      if (!result.ok) {
+        sendResult(ctx, ws, false, result.message);
+        return;
+      }
+      const plan2 = await loadPlan(planPath);
+      if (!plan2) throw new Error("Plan mutation succeeded but its persisted snapshot is missing.");
+      sendResult(ctx, ws, true, result.message);
+      ctx.broadcast({ type: "plan.updated", payload: sessionPayload(ctx, { plan: plan2 }) });
+      return;
+    }
     const templateDefinition = getPlanTemplate(template);
     if (!templateDefinition) {
       sendResult(ctx, ws, false, `Unknown template "${template}".`);
@@ -207,6 +290,22 @@ async function handlePlanItemUpdate(ctx, ws, payload) {
     return;
   }
   try {
+    if (ctx.mutatePlan) {
+      const result = await ctx.mutatePlan({
+        action: "status",
+        target: payload.target,
+        status: payload.status
+      });
+      if (!result.ok) {
+        sendResult(ctx, ws, false, result.message);
+        return;
+      }
+      const plan2 = await loadPlan(planPath);
+      if (!plan2) throw new Error("Plan mutation succeeded but its persisted snapshot is missing.");
+      sendResult(ctx, ws, true, result.message);
+      ctx.broadcast({ type: "plan.updated", payload: sessionPayload(ctx, { plan: plan2 }) });
+      return;
+    }
     let changed = false;
     const plan = await mutatePlan(planPath, currentSessionId(ctx), async (currentPlan) => {
       const before = currentPlan.updatedAt;
@@ -230,13 +329,17 @@ async function handleWorklistMessage(ctx, ws, message) {
       handleTodosGet(ctx, ws);
       return;
     case "todos.clear":
-      handleTodosClear(ctx, ws);
+      await handleTodosClear(ctx, ws);
       return;
     case "todos.remove":
-      handleTodosRemove(ctx, ws, message.payload);
+      await handleTodosRemove(
+        ctx,
+        ws,
+        message.payload
+      );
       return;
     case "todo.update":
-      handleTodoUpdate(
+      await handleTodoUpdate(
         ctx,
         ws,
         message.payload

package/dist/server/kanban-route-protocol.d.ts

@@ -1,2 +1,2 @@
-export declare const KANBAN_CLIENT_MESSAGE_TYPES: readonly ['kanban.capabilities', 'kanban.column.add', 'kanban.column.remove', 'kanban.create', 'kanban.decomposition.approve', 'kanban.decomposition.reject', 'kanban.delete', 'kanban.duplicate', 'kanban.generate', 'kanban.get', 'kanban.health', 'kanban.list', 'kanban.snapshot', 'kanban.supervisor.audit', 'kanban.supervisor.status', 'kanban.task.activity', 'kanban.task.activity.add', 'kanban.task.add', 'kanban.task.assign', 'kanban.task.chain', 'kanban.task.chain.get', 'kanban.task.check.add', 'kanban.task.check.update', 'kanban.task.claim', 'kanban.task.copy', 'kanban.task.dispatch', 'kanban.task.get', 'kanban.task.merge', 'kanban.task.metric.add', 'kanban.task.metric.update', 'kanban.task.move', 'kanban.task.note.add', 'kanban.task.ready', 'kanban.task.release', 'kanban.task.remove', 'kanban.task.split', 'kanban.task.transfer', 'kanban.task.transition', 'kanban.task.update', 'kanban.task.verify', 'kanban.taskgraph.export', 'kanban.taskgraph.sync', 'kanban.update'];
+export declare const KANBAN_CLIENT_MESSAGE_TYPES: readonly ['kanban.capabilities', 'kanban.column.add', 'kanban.column.remove', 'kanban.create', 'kanban.decomposition.approve', 'kanban.decomposition.reject', 'kanban.delete', 'kanban.duplicate', 'kanban.generate', 'kanban.get', 'kanban.health', 'kanban.list', 'kanban.snapshot', 'kanban.supervisor.audit', 'kanban.supervisor.status', 'kanban.task.activity', 'kanban.task.activity.add', 'kanban.task.add', 'kanban.task.assign', 'kanban.task.chain', 'kanban.task.chain.get', 'kanban.task.check.add', 'kanban.task.check.update', 'kanban.task.claim', 'kanban.task.copy', 'kanban.task.dispatch', 'kanban.task.get', 'kanban.task.merge', 'kanban.task.metric.add', 'kanban.task.metric.update', 'kanban.task.move', 'kanban.task.note.add', 'kanban.task.ready', 'kanban.task.release', 'kanban.task.remove', 'kanban.task.split', 'kanban.task.transfer', 'kanban.task.transition', 'kanban.task.update', 'kanban.task.verify', 'kanban.taskgraph.export', 'kanban.taskgraph.sync', 'kanban.update', 'kanban.workbench'];
 //# sourceMappingURL=kanban-route-protocol.d.ts.map

package/dist/server/kanban-routes.d.ts

@@ -1,14 +1,22 @@
 import type { Context } from '@wrongstack/core/agent';
 import type { WebSocket } from 'ws';
-import type { WSClientMessage, WSServerMessage } from './types.js';
 import { type KanbanTaskDispatcher } from './kanban-dispatch.js';
+import type { KanbanSupervisor } from './kanban-supervisor.js';
+import type { WSClientMessage, WSServerMessage } from './types.js';
+export { type KanbanBoardPage, paginateKanbanBoards } from './kanban-route-pagination.js';
 export { KANBAN_CLIENT_MESSAGE_TYPES } from './kanban-route-protocol.js';
-export { paginateKanbanBoards, type KanbanBoardPage } from './kanban-route-pagination.js';
 export interface KanbanRouteContext {
     projectRoot: string;
     context?: Context | undefined;
     broadcast?: ((msg: WSServerMessage) => void) | undefined;
     dispatchTask?: KanbanTaskDispatcher | undefined;
+    /**
+     * Background supervisor (if enabled). When present, the `kanban.supervisor.audit`
+     * and `kanban.supervisor.status` routes delegate to its in-process audit cycle
+     * instead of running a second reconcile/health/recover chain — preventing the
+     * double-audit that happens when both paths refresh the same board concurrently.
+     */
+    supervisor?: KanbanSupervisor | undefined;
 }
 export declare function handleKanbanRoute(ws: WebSocket, msg: WSClientMessage, ctx: KanbanRouteContext): Promise<boolean>;
 //# sourceMappingURL=kanban-routes.d.ts.map

package/dist/server/kanban-supervisor.d.ts

@@ -25,7 +25,7 @@ export interface KanbanSupervisorDispatchOptions {
     }) => void | Promise<void>) | undefined;
 }
 export interface KanbanSupervisorDeps {
-    projectRoot: string;
+    projectRoot: string | (() => string);
     broadcast: (message: {
         type: string;
         payload: unknown;

package/dist/server/lifecycle.d.ts

@@ -38,6 +38,13 @@ export interface LifecycleResources {
      * logged, never thrown — cleanup must not block a clean shutdown.
      */
     onShutdown?: (() => Promise<void> | void) | undefined;
+    /**
+     * Fires **before** any HTTP/WS servers close. Use this for cleanup that must
+     * finish while the network is still up — e.g. telling a Kanban supervisor
+     * to flush its periodic tick so no in-flight `kanban.*` broadcast races a
+     * `WebSocketServer.close()`.
+     */
+    onPreShutdown?: (() => Promise<void> | void) | undefined;
     /** Output sink. Defaults to `console.log`. */
     log?: ((msg: string) => void) | undefined;
     /** Process exit. Defaults to `process.exit`. Injectable for tests. */

package/dist/server/message-dispatcher.d.ts

@@ -29,6 +29,9 @@ import type { ConnectedClient, WSClientMessage } from './types.js';
 interface RunLockControl {
     get(): AbortController | null;
     set(ctrl: AbortController | null): void;
+    /** Session ID that owns the active run, or null when idle. */
+    getSession(): string | null;
+    setSession(id: string | null): void;
 }
 interface MessageDispatcherOptions {
     state: WebuiMutableState;
@@ -47,6 +50,13 @@ interface MessageDispatcherOptions {
     runLock: RunLockControl;
     /** Pending permission confirmations — tool.confirm_result resolves one. */
     pendingConfirms: Map<string, PendingConfirm>;
+    /**
+     * Caller-supplied register hook. The dispatcher calls this **once** during
+     * construction to hand its disposer to the caller. The caller is
+     * responsible for invoking the registered disposer during its own shutdown
+     * — the dispatcher itself never invokes the disposer.
+     */
+    onDispose?: ((disposer: () => void) => void) | undefined;
 }
 /**
  * Build the inbound message dispatcher. Mirrors the `handleMessage` closure

package/dist/server/server-runtime.d.ts

@@ -1,6 +1,18 @@
+/**
+ * Server lifecycle helpers for the standalone WebUI server.
+ *
+ * Phase 1e of the god-module split: the port resolution, WS auth/server
+ * creation, event arming, session-start payload builder, HTTP server
+ * startup, and graceful shutdown registration all moved here from
+ * `start-webui.ts` so the orchestrator reads as connect-the-dots.
+ *
+ * Each function is a pure construction step — no behaviour change. The
+ * WS/HTTP/shutdown wiring that used to be inline (~370 lines) now lives
+ * behind four focused entry points.
+ */
 import type { Config, ModelsRegistry } from '@wrongstack/core/types';
-import { WebSocketServer, type WebSocket } from 'ws';
-import { setupEvents, type FileWatcherMetrics } from './setup-events.js';
+import { type WebSocket, WebSocketServer } from 'ws';
+import { type FileWatcherMetrics, setupEvents } from './setup-events.js';
 import type { ConnectedClient } from './types.js';
 interface ResolvedPorts {
     wsHost: string;
@@ -110,8 +122,15 @@ interface ShutdownDeps {
     flushSession: () => Promise<void>;
     clients: () => IterableIterator<WebSocket>;
     servers: Array<import('node:http').Server | WebSocketServer>;
+    /**
+     * Fires **before** any HTTP/WS servers close. Use this for cleanup that must
+     * finish while the network is still up — e.g. telling a Kanban supervisor
+     * to flush its periodic tick so no in-flight `kanban.*` broadcast races a
+     * `WebSocketServer.close()`.
+     */
+    onPreShutdown?: () => Promise<void> | void;
     onShutdown: () => Promise<void> | void;
 }
-export declare function registerShutdown(deps: ShutdownDeps): void;
+export declare function registerShutdown(deps: ShutdownDeps): () => void;
 export {};
 //# sourceMappingURL=server-runtime.d.ts.map

package/dist/server/session-handlers.d.ts

@@ -80,8 +80,9 @@ export interface SessionHandlersContext {
      * swapped. Without this, a run started in the previous session keeps
      * streaming/tool-calling in the background after session.new/resume.
      */
-    abortActiveRun?: (() => void) | undefined;
-    isRunActive?: (() => boolean) | undefined;
+    /** When sessionId is provided, abort only that session's run; otherwise abort all. */
+    abortActiveRun?: ((sessionId?: string) => void) | undefined;
+    isRunActive?: ((sessionId?: string) => boolean) | undefined;
     sessionStartPayload: (overrides?: Record<string, unknown>) => Promise<SessionStartPayload>;
 }
 export declare function createSessionHandlers(ctx: SessionHandlersContext): SessionRouteHandlers;

package/dist/server/standalone-session-identity.d.ts

@@ -1,5 +1,5 @@
 import type { EventBus } from '@wrongstack/core/kernel';
-import { AgentStatusTracker, type SessionRegistry } from '@wrongstack/core/storage';
+import { AgentStatusTracker, getSessionRegistry } from '@wrongstack/core/storage';
 import type { Config, Logger } from '@wrongstack/core/types';
 export interface StandaloneSessionIdentityPaths {
     globalRoot: string;
@@ -13,10 +13,17 @@ export interface StandaloneSessionIdentityOptions {
     paths: StandaloneSessionIdentityPaths;
     workingDir: string;
     initialSessionId: string;
-    sessionRegistry?: SessionRegistry | undefined;
+    sessionRegistry?: SessionIdentityRegistry | undefined;
     /** Test/embedding escape hatch; production defaults to enabled. */
     enableHqTelemetry?: boolean | undefined;
 }
+interface SessionIdentityRegistry {
+    register(entry: Parameters<ReturnType<typeof getSessionRegistry>['register']>[0]): Promise<void>;
+    updateAgents(agents: Parameters<ReturnType<typeof getSessionRegistry>['updateAgents']>[0]): Promise<void>;
+    markClosing(): Promise<void>;
+    unregister(): Promise<void>;
+    reserveResume?: ReturnType<typeof getSessionRegistry>['reserveResume'] | undefined;
+}
 export interface SessionIdentityTarget {
     projectSlug: string;
     projectRoot: string;
@@ -37,4 +44,5 @@ export interface StandaloneSessionIdentityLifecycle {
  * external surface is fail-soft, while identity selection itself stays live.
  */
 export declare function createStandaloneSessionIdentityLifecycle(opts: StandaloneSessionIdentityOptions): Promise<StandaloneSessionIdentityLifecycle>;
+export {};
 //# sourceMappingURL=standalone-session-identity.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/webui-server",
-  "version": "0.302.0",
+  "version": "0.303.0",
   "license": "MIT",
   "description": "WrongStack WebUI HTTP/WebSocket server module — extracted from @wrongstack/webui in PR #243/244 to remove the CLI -> @wrongstack/webui/server cross-package edge (audit §3.1.1). Pure backend: HTTP routes, WebSocket handlers, MCP tool wrappers, HTML serving. The web frontend lives in @wrongstack/webui; this package is the standalone server it can run on.",
   "keywords": [
@@ -40,16 +40,16 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@wrongstack/core": "0.302.0",
-    "@wrongstack/mcp": "0.302.0",
-    "@wrongstack/techstack": "0.302.0",
-    "@wrongstack/kanban": "0.302.0",
-    "@wrongstack/runtime": "0.302.0",
-    "@wrongstack/sage": "0.302.0",
-    "@wrongstack/providers": "0.302.0",
-    "@wrongstack/requirement-intake": "0.302.0",
-    "@wrongstack/tools": "0.302.0",
-    "@wrongstack/sdd": "0.302.0"
+    "@wrongstack/core": "0.303.0",
+    "@wrongstack/kanban": "0.303.0",
+    "@wrongstack/requirement-intake": "0.303.0",
+    "@wrongstack/runtime": "0.303.0",
+    "@wrongstack/mcp": "0.303.0",
+    "@wrongstack/sage": "0.303.0",
+    "@wrongstack/providers": "0.303.0",
+    "@wrongstack/sdd": "0.303.0",
+    "@wrongstack/techstack": "0.303.0",
+    "@wrongstack/tools": "0.303.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",