@wrongstack/webui-server 0.299.0 → 0.301.0

package/dist/server/fallback-choice.d.ts

@@ -0,0 +1,19 @@
+import type { EventBus } from '@wrongstack/core/kernel';
+import type { WSClientMessage } from './types.js';
+/**
+ * Bridge a `model.fallback_choice` client message to the
+ * `provider.fallback_choice` EventBus emission consumed by the fallback gate
+ * (`packages/cli/src/wiring/fallback-gate.ts`). Shared by the standalone route
+ * table (`routes.ts`) and the embedded message router so wire validation and
+ * the event contract live in exactly one place.
+ *
+ * Returns `true` when the payload was valid and forwarded, `false` when the
+ * payload failed validation (the caller may send an error frame).
+ */
+export declare function emitFallbackChoice(events: EventBus | undefined, msg: WSClientMessage): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+//# sourceMappingURL=fallback-choice.d.ts.map

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/http-server.d.ts

@@ -42,6 +42,19 @@ export interface CreateHttpServerOptions {
      * URL-token-only flow (e.g. in tests that don't want cookie state).
      */
     enableWsCookie?: boolean | undefined;
+    /**
+     * Mark the `ws_token` cookie `Secure` and give it the `__Host-` prefix.
+     *
+     * Inferred from a `wss://` {@link CreateHttpServerOptions.publicWsUrl} when
+     * omitted, which covers the tunnel deployments this server documents. Set it
+     * explicitly when TLS is terminated in front of the server by something that
+     * does not surface through `publicWsUrl` (e.g. an nginx `proxy_pass` with a
+     * separately configured WS origin).
+     *
+     * Must stay false on a plain-HTTP loopback bind: browsers do not send a
+     * `Secure` cookie over HTTP, so enabling it there breaks the WS handshake.
+     */
+    secureCookies?: boolean | undefined;
     /**
      * Optional file watcher metrics object. When provided, the
      * /debug/watcher-metrics endpoint will be enabled to expose these metrics.
@@ -85,6 +98,42 @@ export interface CreateHttpServerOptions {
 export declare function injectWsConfig(html: string, opts: {
     publicWsUrl?: string | undefined;
 }): string;
+/**
+ * WS-107: the auth cookie never carried `Secure`, on the stated grounds that
+ * "the dev server is plain HTTP on loopback". True for the default bind — and
+ * wrong for the deployment this server explicitly supports, where a tunnel
+ * terminates TLS in front of it (`publicWsUrl: wss://…`). There the browser is
+ * on HTTPS, so a cookie set without `Secure` is one the browser will also
+ * attach to a plaintext request to the same host: a downgrade or a stray
+ * `http://` link leaks the token that authenticates the whole control plane.
+ *
+ * So the flag follows the deployment. On an HTTPS-fronted server the cookie is
+ * additionally `__Host-`-prefixed, which browsers only accept when it is
+ * Secure, Path=/, and Domain-less — the same hardening the HQ server adopted.
+ * On loopback HTTP neither is usable (a `Secure` cookie would simply not be
+ * sent), so the plain name is kept there.
+ */
+export declare const WS_TOKEN_COOKIE = "ws_token";
+export declare const WS_TOKEN_COOKIE_SECURE = "__Host-ws_token";
+/**
+ * Resolve the access token presented on an HTTP request.
+ *
+ * WS-108: the `?token=` query source was accepted on EVERY route regardless of
+ * bind. On a tunnel that is the C-598 exposure the WS path already closed —
+ * the token reaches reverse-proxy access logs, browser history, and any
+ * `Referer` the page emits to a third-party origin. The header and cookie
+ * sources have none of those channels.
+ *
+ * `allowQuery` is therefore opt-in and reserved for the two places the token
+ * legitimately rides the URL: `/ws-auth`, whose entire job is to exchange it
+ * for the cookie, and the HTML page load the operator opens from the printed
+ * access URL. Everywhere else it is refused off-loopback — and when refused,
+ * resolution falls through to the header and cookie rather than returning
+ * early, so a client that sent both still authenticates.
+ */
+export declare function requestToken(req: http.IncomingMessage, url: URL, opts?: {
+    allowQuery?: boolean;
+}): string | undefined;
 /**
  * Build the Content-Security-Policy value for the WebUI.
  *

package/dist/server/index.d.ts

@@ -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

@@ -36,6 +36,27 @@ export interface WebUIInstanceRecord {
     startedAt: string;
     /** Convenience open-in-browser URL. */
     url: string;
+    /**
+     * Access token for this instance's HTTP API, so a same-project sibling
+     * process (TUI/REPL) can authenticate the `POST /api/fleet/ping`
+     * push-on-write nudge.
+     *
+     * Security scan 2026-08-04, finding H3: the API used to require no
+     * credential at all on a loopback bind. Closing that meant the one
+     * legitimate non-browser caller needed a way to obtain the token, and this
+     * registry — already `0o600`, already read by exactly those siblings — is
+     * where it belongs.
+     *
+     * Be precise about what this is worth. Storing the token here raises the bar
+     * against a *different-user* or sandboxed local process, which cannot read
+     * the file. It does nothing against a process running as the same user: that
+     * process can read this file, and could read `~/.wrongstack/projects/*` —
+     * the very transcripts the API exposes — without going near the API at all.
+     * The same reasoning already applies to HQ's `auth.json`.
+     *
+     * Optional so an older record (or a surface that has no token) still parses.
+     */
+    authToken?: string | undefined;
 }
 /** Default wstack home dir (`~/.wrongstack`). Callers may override the base. */
 export declare function defaultBaseDir(): string;

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/mcp-handlers.d.ts

@@ -9,6 +9,7 @@
  * there; here we only map structured results to WS events the browser expects.
  */
 import { type MCPRegistry, type MCPServerOperationalHealth, type McpServerInfo } from '@wrongstack/mcp';
+import type { TrustBoundary } from '@wrongstack/core/security';
 import type { WebSocket } from 'ws';
 import type { WSClientMessage } from './types.js';
 /** Wire view of a server as the browser MCP panel consumes it. */
@@ -33,9 +34,9 @@ export declare function toView(info: McpServerInfo, health?: MCPServerOperationa
 /** mcp.list — configured servers merged with live registry status + tools. */
 export declare function handleMcpList(ws: WebSocket, _msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
 /** mcp.add — persist a new server (incl. url/headers) and start it if enabled. */
-export declare function handleMcpAdd(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
+export declare function handleMcpAdd(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry, trustBoundary?: TrustBoundary): Promise<void>;
 /** mcp.update — re-persist config (incl. url/headers) and re-apply to registry. */
-export declare function handleMcpUpdate(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
+export declare function handleMcpUpdate(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry, trustBoundary?: TrustBoundary): Promise<void>;
 /** mcp.remove — stop the server and delete it from config. */
 export declare function handleMcpRemove(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
 /** mcp.enable — flip enabled:true in config and start the server. */

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', '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/dist/server/provider-handlers.d.ts

@@ -95,7 +95,7 @@ export declare function createProviderOperations(deps: ProviderOperationsDeps):
         apiKey?: string | undefined;
         models?: string[] | undefined;
         customModels?: ProviderConfig['customModels'] | undefined;
-    }) => Promise<void>;
+    }) => Promise<boolean>;
     handleProviderRemove: (ws: WebSocket, providerId: string) => Promise<void>;
     handleProviderClearModels: (ws: WebSocket, providerId: string) => Promise<void>;
     handleCustomModelSet: (ws: WebSocket, providerId: string, modelId: string, definition: NonNullable<ProviderConfig['customModels']>[string]) => Promise<void>;
@@ -137,7 +137,7 @@ export declare function createProviderHandlers(deps: ProviderHandlerDeps): {
         apiKey?: string | undefined;
         models?: string[] | undefined;
         customModels?: ProviderConfig['customModels'] | undefined;
-    }) => Promise<void>;
+    }) => Promise<boolean>;
     handleProviderRemove: (ws: WebSocket, providerId: string) => Promise<void>;
     handleProviderClearModels: (ws: WebSocket, providerId: string) => Promise<void>;
     handleCustomModelSet: (ws: WebSocket, providerId: string, modelId: string, definition: NonNullable<ProviderConfig['customModels']>[string]) => Promise<void>;

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

@@ -14,7 +14,7 @@ export interface ProviderMutationHandlers {
         apiKey?: string | undefined;
         models?: string[] | undefined;
         customModels?: ProviderConfig['customModels'] | undefined;
-    }) => Promise<void>;
+    }) => Promise<boolean>;
     handleProviderRemove: (ws: WebSocket, providerId: string) => Promise<void>;
     handleProviderClearModels: (ws: WebSocket, providerId: string) => Promise<void>;
     handleCustomModelSet: (ws: WebSocket, providerId: string, modelId: string, definition: NonNullable<ProviderConfig['customModels']>[string]) => Promise<void>;
@@ -40,6 +40,8 @@ export interface ProviderRouteHandlers {
     searchProviderModels: (ws: WebSocket, query: string, limit?: number | undefined) => Promise<void>;
     switchModel: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
     refineModel: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
+    /** Forward a model.fallback_choice client message to the EventBus. */
+    fallbackChoice: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
     /** Adopt a just-added provider as the live default when no model is active. */
     adoptDefaultProviderIfUnset: (providerId: string) => Promise<void>;
     providerHandlers: ProviderMutationHandlers;

package/dist/server/ws-auth.d.ts

@@ -88,6 +88,24 @@ export interface VerifyClientInput {
     allowedHostnames?: readonly string[] | undefined;
     /** Allow browser WS URL tokens for explicit public WS URLs where cookies cannot cross hostnames. */
     allowBrowserUrlToken?: boolean | undefined;
+    /**
+     * Let a valid `ws_token` cookie authenticate a loopback origin whose **port**
+     * differs from this server's (WS-003 opt-out). **Development only.**
+     *
+     * The Vite dev server and the WS server necessarily occupy different ports
+     * (`packages/webui/vite.config.ts` asks for 3456 and auto-advances when the
+     * WS server already holds it), so the dev loop cannot satisfy the port check.
+     *
+     * It must stay opt-in because the cookie proves nothing across ports: cookies
+     * are keyed by host, not port, and SameSite computes *site* without the port,
+     * so the browser attaches `ws_token` to a socket opened from **any** other
+     * localhost origin automatically. Enabling this in a shipped build re-opens
+     * exactly the hole WS-003 closed — a second dev server, a local app's UI, or
+     * an XSS in either can drive the agent.
+     *
+     * Wired from `WRONGSTACK_WEBUI_DEV_CROSS_PORT_WS=1`; never defaulted on.
+     */
+    allowCrossPortLoopbackCookie?: boolean | undefined;
 }
 /**
  * Decide whether to accept an incoming WebSocket handshake. Pure mirror of the

package/dist/server/ws-payload-validation.d.ts

@@ -12,6 +12,13 @@ interface ModelSwitchPayload {
     requestId?: string | undefined;
 }
 export declare function validateModelSwitchPayload(payload: unknown): PayloadValidationResult<ModelSwitchPayload>;
+export interface ModelFallbackChoicePayload {
+    requestId: string;
+    providerId?: string | undefined;
+    model?: string | undefined;
+    autoSwitch?: boolean | undefined;
+}
+export declare function validateModelFallbackChoicePayload(payload: unknown): PayloadValidationResult<ModelFallbackChoicePayload>;
 interface MailboxMessagesPayload {
     limit?: number;
     agentId?: string;

package/package.json

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