@wrongstack/webui-server 0.300.0 → 0.302.0

package/dist/server/goal-ws-handler.d.ts

@@ -111,6 +111,18 @@ export declare class GoalWebSocketHandler {
      * Fire-and-forget: runs in the background and logs the review summary.
      */
     private runChimeraReview;
+    /**
+     * Fire-and-forget persist.
+     *
+     * Every detached `store.save()` used to be a bare `void`, so a rejection
+     * became an unhandled rejection and — under Node 22's default
+     * `--unhandled-rejections=throw` — killed the process mid-run. On Windows an
+     * AV scanner or indexer holding the `.wrongstack/phases/<id>.json` rename
+     * target for a few hundred ms is enough (EPERM from `atomicWrite`), and in
+     * `--webui` mode that takes the CLI session down with it. `handleStop` at
+     * `:549` already had the `.catch`; these call sites did not.
+     */
+    private persistDetached;
     /** Persist + broadcast after an interactive board mutation. */
     private afterBoardMutation;
     private handleTaskStatusChange;

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';
@@ -123,7 +123,7 @@ export { handleWorktreeRoute, type WorktreeRouteHandlers } from './worktree-rout
 export { WorktreeWebSocketHandler } from './worktree-ws-handler.js';
 export { extractToken, extractTokenFromCookie, hostHeaderOk, isLoopbackBind, isLoopbackHostname, isWildcardBind, tokenMatches, type VerifyClientInput, verifyClient, } from './ws-auth.js';
 export { validateAutonomySwitchPayload, validateBrainAskPayload, validateBrainRiskPayload, validateContextModeCreatePayload, validateContextModeDeletePayload, validateContextModeSwitchPayload, validateContextModeUpdatePayload, validateGitDiffPayload, validateMailboxAgentsPayload, validateMailboxMessagesPayload, validateMailboxPurgePayload, validateModelSwitchPayload, validateModeSwitchPayload, validatePlanTemplateUsePayload, validatePrefsUpdatePayload, validateProcessKillPayload, validateProjectsAddPayload, validateProjectsSelectPayload, validateShellOpenPayload, validateSkillsCreatePayload, validateSkillsEditPayload, validateWorkingDirSetPayload, } from './ws-payload-validation.js';
-export { broadcast, buildWebUIAccessUrl, envFlag, errMessage, generateAuthToken, hostForBrowserUrl, resolveAuthToken, send, sendResult, } from './ws-utils.js';
+export { broadcast, buildWebUIAccessUrl, envFlag, errMessage, generateAuthToken, hostForBrowserUrl, resolveAuthToken, send, sendResult, sendSerialized, WEBUI_WS_MAX_BUFFERED_BYTES, } from './ws-utils.js';
 export { formatExternalAccessUrls, getExternalAddresses, type NetworkAddress } from './network-info.js';
 export { createZipBuffer, readZipEntries, type ZipEntryInput } from './zip.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,37 @@
+/**
+ * The one place a Kanban board becomes a WebSocket message.
+ *
+ * Six call sites built these envelopes by hand — the daemon subscriber,
+ * decomposition routes (twice), the task dispatcher (twice), the run mirror and
+ * the supervisor. `WSServerMessage` is `{ type: string; payload: unknown }`, so
+ * the type system checks none of it: a board sent bare instead of wrapped in
+ * `{ board }` compiles, ships, and leaves the client's `isBoard(data)` branch
+ * silently unmatched. That has already happened once
+ * (`hq-kanban-sync-best-effort`), and hand-copied envelopes are how it happens
+ * again.
+ *
+ * These builders are the shape. Prefer them over an inline literal even for a
+ * one-off broadcast — an inline literal is how the seventh site starts.
+ */
+import type { KanbanBoard, KanbanBoardSummary, KanbanTask } from '@wrongstack/kanban';
+import type { WSServerMessage } from './types.js';
+/** A full board, for `kanban.get`. The client keys on `data.board`. */
+export declare function kanbanBoardMessage(board: KanbanBoard): WSServerMessage;
+/** The board list, for `kanban.list`. `data` is the array itself, not `{ boards }`. */
+export declare function kanbanListMessage(boards: readonly KanbanBoardSummary[]): WSServerMessage;
+/** A single task, for `kanban.task.update`. */
+export declare function kanbanTaskMessage(boardId: string, task: KanbanTask): WSServerMessage;
+/** A removed board, for `kanban.delete`. */
+export declare function kanbanDeletedMessage(boardId: string): WSServerMessage;
+/**
+ * Broadcast a board, and optionally the refreshed list behind it.
+ *
+ * The list is opt-in because the client already derives a summary from the
+ * board it receives (`kanban-store.ts` calls `upsertSummary` on `kanban.get`),
+ * so a second round trip is only needed when the SET of boards changed —
+ * created, deleted, renamed. Sites that skipped it were not leaving the sidebar
+ * stale; sites that sent it unconditionally were paying for a list read on
+ * every task move.
+ */
+export declare function publishKanbanBoard(broadcast: (message: WSServerMessage) => void, board: KanbanBoard, listBoards?: () => Promise<readonly KanbanBoardSummary[]>): Promise<void>;
+//# sourceMappingURL=kanban-broadcast.d.ts.map

package/dist/server/lifecycle.d.ts

@@ -19,8 +19,14 @@ export interface LifecycleResources {
      * snapshot) so shutdown closes whoever is connected *at signal time*, not
      * whoever was connected when the handler was registered.
      */
+    /**
+     * Live client sockets. `terminate` is optional so a test double can supply
+     * `close` alone, but a real `ws` socket has it — and the shutdown path needs
+     * it: `close()` only starts a handshake the peer may never answer.
+     */
     clients: () => Iterable<{
         close: () => void;
+        terminate?: (() => void) | undefined;
     }>;
     /** Servers to stop (HTTP + WS). `null`/`undefined` entries are skipped. */
     servers: Array<{

package/dist/server/pref-helpers.d.ts

@@ -17,7 +17,7 @@
  */
 import type { SecretVault } from '@wrongstack/core/types';
 /** Pref keys exposed to the settings panel via prefs.get / prefs.updated. */
-export declare const PREF_KEYS: readonly ['autonomy', 'autonomyDelayMs', 'autoProceedMaxIterations', 'yolo', 'maxIterations', 'chime', 'confirmExit', 'nextPrediction', 'enhanceEnabled', 'enhanceDelayMs', 'enhanceLanguage', 'featureMcp', 'featurePlugins', 'featureMemory', 'featureSkills', 'featureModelsRegistry', 'indexOnStart', 'contextAutoCompact', 'contextStrategy', 'contextMode', 'tokenSavingTier', 'maxConcurrent', 'titleAnimation', 'uiLocale', 'logLevel', 'auditLevel', 'hqEnabled', 'hqUrl', 'hqToken', 'hqRawContent', 'tgConfigured', 'tgSessionEnd', 'tgDelegate', 'tgLongToolMs', 'reasoningMode', 'reasoningEffort', 'reasoningPreserve', 'cacheTtl', 'fallbackModels', 'fallbackProfiles', 'favoriteModels', 'favoriteModelsOnly', 'modelAvailabilitySchedule', 'modelMatrix', 'fallbackAuto', 'refinerProvider', 'refinerModel', 'refinerFallbackProfile', 'thinkingWord', 'statuslineMode', 'animationStyle', 'showModelReasoning', 'breakerEnabled', 'breakerAutoKillResetMs', 'fsAccess', 'debugStream', 'chimeraEnabled', 'chimeraProvider', 'chimeraModel', 'chimeraMaxFiles', 'chimeraAutoFix', 'autoReviewEnabled', 'autoReviewProvider', 'autoReviewModel', 'autoReviewFallbackProfile', 'autoReviewFallbackModels', 'autoReviewDebounceMs', 'autoReviewMaxFilesPerBatch', 'autoReviewMaxConcurrentReviews', 'autoReviewCascadeOn', 'groupToolCalls', 'showThinkingLogs', 'autoCollapseInput', 'pluginsEnabled', 'fleetChatVerbosity'];
+export declare const PREF_KEYS: readonly ['autonomy', 'autonomyDelayMs', 'autoProceedMaxIterations', 'yolo', 'maxIterations', 'chime', 'confirmExit', 'nextPrediction', 'nextStepsTool', 'enhanceEnabled', 'enhanceDelayMs', 'enhanceLanguage', 'featureMcp', 'featurePlugins', 'featureMemory', 'featureSkills', 'featureModelsRegistry', 'indexOnStart', 'contextAutoCompact', 'contextStrategy', 'contextMode', 'tokenSavingTier', 'maxConcurrent', 'titleAnimation', 'uiLocale', 'logLevel', 'auditLevel', 'hqEnabled', 'hqUrl', 'hqToken', 'hqRawContent', 'tgConfigured', 'tgSessionEnd', 'tgDelegate', 'tgLongToolMs', 'reasoningMode', 'reasoningEffort', 'reasoningPreserve', 'cacheTtl', 'fallbackModels', 'fallbackProfiles', 'favoriteModels', 'favoriteModelsOnly', 'modelAvailabilitySchedule', 'modelMatrix', 'fallbackAuto', 'refinerProvider', 'refinerModel', 'refinerFallbackProfile', 'thinkingWord', 'statuslineMode', 'animationStyle', 'showModelReasoning', 'breakerEnabled', 'breakerAutoKillResetMs', 'fsAccess', 'debugStream', 'chimeraEnabled', 'chimeraProvider', 'chimeraModel', 'chimeraMaxFiles', 'chimeraAutoFix', 'autoReviewEnabled', 'autoReviewProvider', 'autoReviewModel', 'autoReviewFallbackProfile', 'autoReviewModelSelection', 'autoReviewFallbackModels', 'autoReviewDebounceMs', 'autoReviewMaxFilesPerBatch', 'autoReviewMaxConcurrentReviews', 'autoReviewCascadeOn', 'groupToolCalls', 'showThinkingLogs', 'autoCollapseInput', 'pluginsEnabled', 'fleetChatVerbosity'];
 export interface PrefHelperDeps {
     /** Path to the active profile config; the sole settings mutation target. */
     profileConfigPath: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/webui-server",
-  "version": "0.300.0",
+  "version": "0.302.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.300.0",
-    "@wrongstack/providers": "0.300.0",
-    "@wrongstack/kanban": "0.300.0",
-    "@wrongstack/requirement-intake": "0.300.0",
-    "@wrongstack/runtime": "0.300.0",
-    "@wrongstack/techstack": "0.300.0",
-    "@wrongstack/sage": "0.300.0",
-    "@wrongstack/mcp": "0.300.0",
-    "@wrongstack/tools": "0.300.0",
-    "@wrongstack/sdd": "0.300.0"
+    "@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"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",