@wrongstack/webui-server 0.301.0 → 0.302.2

package/dist/server/index.d.ts

@@ -42,7 +42,7 @@ export { type HostRouteHandlers, handleHostRoute } from './host-routes.js';
 export { clearAnalyticsBuffer, getAnalyticsBuffer, handleApiAnalyticsGet, handleApiAnalyticsPost, handleApiAnalyticsSummary, } from './http-server/analytics-handler.js';
 export type { CreateHttpServerOptions } from './http-server.js';
 export { buildCspHeader, createHttpServer, decodeSessionId, injectWsConfig, isInsideDist, } from './http-server.js';
-export { defaultBaseDir, formatInstances, isPidAlive, listInstances, registerInstance, registryPath, unregisterInstance, type WebUIInstanceRecord, } from './instance-registry.js';
+export { defaultBaseDir, formatInstances, isPidAlive, joinSessionRegistryWithWebUIInstances, listInstances, registerInstance, registryPath, unregisterInstance, type WebUIInstanceAuthInfo, type WebUIInstanceRecord, type WebUIInstanceRole, type WebUISessionAttachCandidate, type WebUISessionAttachDegradedReason, type WebUISessionAttachEndpoint, } from './instance-registry.js';
 export { handleIntrospectionRoute, type IntrospectionRouteContext, } from './introspection-routes.js';
 export { handleKanbanTaskDispatch, type KanbanDispatchContext, type KanbanDispatchResult, type KanbanTaskDispatcher, parseResolvedDispatchRoute, type ResolvedDispatchRoute, } from './kanban-dispatch.js';
 export { handleKanbanHostRoute, type KanbanHostRouteHandlers } from './kanban-host-routes.js';

package/dist/server/instance-registry.d.ts

@@ -18,12 +18,20 @@
  * - **Best-effort**: a failure to read/write the registry must NEVER take the
  *   server down. Callers wrap these in `.catch()`.
  */
+import type { SessionRegistryEntry, SessionLiveStatus } from '@wrongstack/core/storage';
+export type WebUIInstanceRole = 'standalone' | 'parent-shell' | 'session-child';
+export interface WebUIInstanceAuthInfo {
+    /** How a same-user parent/sibling process can authenticate to this endpoint. */
+    scheme: 'registry-token' | 'cookie-bootstrap' | 'none';
+    /** Whether the record has a usable token in `authToken`. */
+    tokenPresent: boolean;
+}
 /** One running WebUI / SimpleUI process. */
 export interface WebUIInstanceRecord {
     /** OS process id — also the liveness key. */
     pid: number;
-    /** Surface kind — 'webui' or 'simpleui'. */
-    surface: 'webui' | 'simpleui';
+    /** Surface kind — 'webui' or 'simpleui'. Additional strings are tolerated for new surfaces. */
+    surface: 'webui' | 'simpleui' | string;
     /** Port serving both HTTP and WebSocket. */
     httpPort: number;
     /** Bind host (e.g. 127.0.0.1 or 0.0.0.0). */
@@ -57,7 +65,48 @@ export interface WebUIInstanceRecord {
      * Optional so an older record (or a surface that has no token) still parses.
      */
     authToken?: string | undefined;
+    /** Runtime role. Missing means the legacy standalone WebUI/SimpleUI role. */
+    role?: WebUIInstanceRole | undefined;
+    /** Live session owned by this endpoint when `role === 'session-child'`. */
+    sessionId?: string | undefined;
+    /** Parent shell process identity, when this endpoint was spawned by a parent. */
+    parentPid?: number | undefined;
+    parentShellId?: string | undefined;
+    /** Stable child runtime id, distinct from the session id. */
+    runtimeId?: string | undefined;
+    /** Whether a parent shell should treat this endpoint as attachable. */
+    attachable?: boolean | undefined;
+    /** Descriptive auth metadata; the same-user token remains in `authToken`. */
+    auth?: WebUIInstanceAuthInfo | undefined;
+    /** Health/protocol hints for future parent shells. */
+    lastReadyAt?: string | undefined;
+    protocolVersion?: number | undefined;
+    capabilities?: string[] | undefined;
+}
+export interface WebUISessionAttachEndpoint {
+    host: string;
+    httpPort: number;
+    url: string;
+    authToken?: string | undefined;
+}
+export type WebUISessionAttachDegradedReason = 'live-session-no-webui-endpoint' | 'endpoint-owner-mismatch' | 'endpoint-missing-session-id' | 'endpoint-session-mismatch' | 'endpoint-not-session-child' | 'endpoint-not-attachable' | 'session-not-live';
+export interface WebUISessionAttachCandidate {
+    sessionId: string;
+    projectRoot: string;
+    workingDir: string;
+    sessionPid: number;
+    status: SessionLiveStatus;
+    instance?: WebUIInstanceRecord | undefined;
+    endpoint?: WebUISessionAttachEndpoint | undefined;
+    attachable: boolean;
+    degradedReason?: WebUISessionAttachDegradedReason | undefined;
 }
+export declare function joinSessionRegistryWithWebUIInstances(input: {
+    sessions: SessionRegistryEntry[];
+    instances: WebUIInstanceRecord[];
+    projectRoot?: string | undefined;
+    projectSlug?: string | undefined;
+}): WebUISessionAttachCandidate[];
 /** Default wstack home dir (`~/.wrongstack`). Callers may override the base. */
 export declare function defaultBaseDir(): string;
 /** Resolve the registry file path for a given base dir. */

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

@@ -2,6 +2,7 @@ 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';
 export { KANBAN_CLIENT_MESSAGE_TYPES } from './kanban-route-protocol.js';
 export { paginateKanbanBoards, type KanbanBoardPage } from './kanban-route-pagination.js';
 export interface KanbanRouteContext {
@@ -9,6 +10,13 @@ export interface KanbanRouteContext {
     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

@@ -110,8 +110,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.301.0",
+  "version": "0.302.2",
   "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.301.0",
-    "@wrongstack/kanban": "0.301.0",
-    "@wrongstack/mcp": "0.301.0",
-    "@wrongstack/requirement-intake": "0.301.0",
-    "@wrongstack/techstack": "0.301.0",
-    "@wrongstack/sage": "0.301.0",
-    "@wrongstack/providers": "0.301.0",
-    "@wrongstack/runtime": "0.301.0",
-    "@wrongstack/sdd": "0.301.0",
-    "@wrongstack/tools": "0.301.0"
+    "@wrongstack/core": "0.302.2",
+    "@wrongstack/sdd": "0.302.2",
+    "@wrongstack/mcp": "0.302.2",
+    "@wrongstack/providers": "0.302.2",
+    "@wrongstack/kanban": "0.302.2",
+    "@wrongstack/sage": "0.302.2",
+    "@wrongstack/requirement-intake": "0.302.2",
+    "@wrongstack/runtime": "0.302.2",
+    "@wrongstack/techstack": "0.302.2",
+    "@wrongstack/tools": "0.302.2"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",