@wrongstack/webui-server 0.306.4 → 0.307.1

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

@@ -27,6 +27,11 @@ export declare function handleFilesTree(ws: WebSocket, msg: unknown, projectRoot
  * `{ type: 'files.read', payload: { filePath, content } }`.
  */
 export declare function handleFilesRead(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
+/**
+ * Extract an AST-based skeleton for a file.
+ * Responds with `{ type: 'files.skeleton_result', payload: { filePath, lang, skeleton, stats } }`.
+ */
+export declare function handleFilesSkeleton(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
 /**
  * Write file content back to disk (atomic write via tmp + rename).
  *
@@ -42,4 +47,36 @@ export declare function handleFilesWrite(ws: WebSocket, msg: unknown, projectRoo
  * `{ type: 'files.list', payload: { files } }`.
  */
 export declare function handleFilesList(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
+/**
+ * Create a new file or directory inside the project root.
+ *
+ * Guards against path traversal via `resolveFileInsideProject`. Rejects
+ * if the target already exists. Responds with
+ * `{ type: 'files.created', payload: { filePath, success } }`.
+ */
+export declare function handleFilesCreate(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
+/**
+ * Delete a file or directory inside the project root.
+ *
+ * Guards against path traversal via `resolveFileInsideProject`. Directories
+ * require `recursive: true` to delete non-empty contents. Responds with
+ * `{ type: 'files.deleted', payload: { filePath, success } }`.
+ */
+export declare function handleFilesDelete(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
+/**
+ * Rename or move a file/directory within the project root.
+ *
+ * Guards both source and destination via `resolveFileInsideProject`.
+ * Rejects if the destination already exists or the source doesn't.
+ * Responds with `{ type: 'files.renamed', payload: { oldPath, newPath, success } }`.
+ */
+export declare function handleFilesRename(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
+/**
+ * Move a file/directory into a destination directory within the project root.
+ *
+ * Guards both source and destination via `resolveFileInsideProject`.
+ * The file keeps its basename — it is placed inside `destDir`.
+ * Responds with `{ type: 'files.moved', payload: { srcPath, destPath, success } }`.
+ */
+export declare function handleFilesMove(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
 //# sourceMappingURL=file-handlers.d.ts.map

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

@@ -37,6 +37,14 @@ export declare class GoalWebSocketHandler {
     private store;
     private clients;
     private broadcastInterval;
+    /**
+     * Change-detection state for the 2s broadcast tick: a cheap content
+     * fingerprint of the graph and the last serialized progress payload, so an
+     * idle run costs one small string build per tick instead of a full
+     * buildState + serialize + fan-out every 2 seconds.
+     */
+    private lastGraphFingerprint;
+    private lastProgressJson;
     /** Aborts in-flight task agents AND the planning turn when the run is stopped. */
     private abort;
     /** Per-assessment AbortController so a newer assessment can abort the prior
@@ -129,6 +137,14 @@ export declare class GoalWebSocketHandler {
     private startBroadcast;
     private stopBroadcast;
     private broadcastState;
+    /**
+     * Cheap content fingerprint covering exactly what `buildState` renders:
+     * graph identity/flags plus per-phase status, timestamps, assignees, and
+     * task status counts with the newest task update. Any mutation that would
+     * change the projection changes this string, so the 2s tick can skip the
+     * full buildState + serialize + fan-out while the graph is idle.
+     */
+    private graphFingerprint;
     private buildState;
     private sendState;
     private broadcast;

package/dist/server/http-server/api-router.d.ts

@@ -0,0 +1,22 @@
+import type * as http from 'node:http';
+import { type TechStackEvent } from '../techstack-handlers.js';
+export interface ApiRouterDeps {
+    globalRoot?: string | undefined;
+    projectRoot?: string | undefined;
+    indexDir?: string | undefined;
+    intakeService?: import('@wrongstack/requirement-intake').RequirementIntakeService | undefined;
+    onFleetPing?: (() => void) | undefined;
+    watcherMetrics?: import('../setup-events.js').FileWatcherMetrics | undefined;
+    onTechStackEvent?: ((event: TechStackEvent) => void) | undefined;
+    getLlm?: (() => {
+        provider: import('@wrongstack/core/types').Provider;
+        model: string;
+    } | undefined) | undefined;
+    executePackageOperation?: import('../techstack-handlers.js').TechStackHandlerDeps['executePackageOperation'];
+}
+export declare function handleApiRoutes(req: http.IncomingMessage, res: http.ServerResponse, url: URL, deps: ApiRouterDeps, requireAccessToken: boolean, accessTokenOk: boolean, getTechStackRuntime: () => Promise<{
+    store: import('@wrongstack/techstack').TechStackStore;
+    engine: import('@wrongstack/techstack').TechStackEngine;
+    runningJobs: Map<string, AbortController>;
+}>): Promise<boolean>;
+//# sourceMappingURL=api-router.d.ts.map

package/dist/server/http-server/index.d.ts

@@ -0,0 +1,6 @@
+export * from './security-helpers.js';
+export * from './static-file-handler.js';
+export * from './analytics-handler.js';
+export * from './api-handlers.js';
+export * from './api-router.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/http-server/security-helpers.d.ts

@@ -0,0 +1,24 @@
+import type * as http from 'node:http';
+export declare const MIME_TYPES: Record<string, string>;
+export declare function escapeHtmlAttr(value: string): string;
+export declare function injectWsConfig(html: string, opts: {
+    publicWsUrl?: string | undefined;
+}): string;
+export declare function firstHeader(value: string | string[] | undefined): string | undefined;
+export declare const WS_TOKEN_COOKIE = "ws_token";
+export declare const WS_TOKEN_COOKIE_SECURE = "__Host-ws_token";
+export declare function wsTokenCookie(token: string, secure: boolean): string;
+export declare function setAuthCookieHeaders(res: http.ServerResponse, token: string, secure: boolean): void;
+export declare function setStaticSecurityHeaders(res: http.ServerResponse): void;
+export declare function requestToken(req: http.IncomingMessage, url: URL, opts?: {
+    allowQuery?: boolean;
+}): string | undefined;
+export declare function isLoopbackPeer(req: http.IncomingMessage): boolean;
+export declare function formatCspHostname(hostname: string): string;
+export declare function cspSourceFromUrl(rawUrl: string): string | undefined;
+export declare const EXTRA_SCRIPT_SOURCES: readonly string[];
+export declare function buildCspHeader(publicWsUrl?: string | undefined, host?: string, port?: number): string;
+export declare function isInsideDist(candidate: string, distDir: string): boolean;
+export declare function decodeSessionId(segment: string): string;
+export declare function strictDecodeParam(segment: string, res: http.ServerResponse): string | null;
+//# sourceMappingURL=security-helpers.d.ts.map

package/dist/server/http-server/static-file-handler.d.ts

@@ -0,0 +1,10 @@
+import type * as http from 'node:http';
+export declare function handleStaticFileRequest(_req: http.IncomingMessage, res: http.ServerResponse, distDir: string, url: URL, opts: {
+    publicWsUrl?: string | undefined;
+    host: string;
+}, port: number, shouldSetAuthCookie: boolean): Promise<void>;
+export declare function handleSpaFallback(res: http.ServerResponse, distDir: string, opts: {
+    publicWsUrl?: string | undefined;
+    host: string;
+}, port: number): Promise<void>;
+//# sourceMappingURL=static-file-handler.d.ts.map

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

@@ -1,6 +1,33 @@
+/**
+ * Static-file HTTP server for the WebUI / SimpleUI React frontends.
+ *
+ * Design:
+ * - **Single port — shared HTTP + WebSocket.** A single port serves both the
+ *   static frontend and the WebSocket protocol. See the port-utils module.
+ * - **CSP**: `connect-src 'self'` covers the core same-origin case. For loopback
+ *   binds (127.0.0.1 / localhost) we also add explicit `ws://`/`wss://` entries
+ *   so browsers that strictly separate `ws:` from `http:` in CSP `connect-src`
+ *   matching still allow WS upgrades. These loopback entries are safe because
+ *   they only open connections to the local machine. Tunnel/proxy setups use
+ *   `publicWsUrl` for the single external origin.
+ * - **Path-traversal guard**: `path.join` alone does NOT prevent
+ *   `%2e%2e%2f` escapes (the `URL` constructor decodes percent-encoding
+ *   before we see the path). We re-`resolve` the candidate and verify it
+ *   stays under `distDir`.
+ * - **Access auth**: on non-loopback binds, all HTTP routes require the same
+ *   shared token as the WS upgrade, accepted via `?token=...`, `X-WS-Token`,
+ *   or the `ws_token` HttpOnly cookie. This protects the React UI and the
+ *   `/api/*` control/read endpoints when `WS_HOST=0.0.0.0`.
+ *
+ * Extracted from `index.ts` so the static-serve concern can be tested
+ * with a tiny fake `distDir` and asserted on path-traversal, MIME
+ * matching, and CSP header presence.
+ */
 import * as http from 'node:http';
 import type { FileWatcherMetrics } from './setup-events.js';
-import { type TechStackEvent } from './techstack-handlers.js';
+import type { TechStackEvent } from './techstack-handlers.js';
+import { buildCspHeader, decodeSessionId, injectWsConfig, isInsideDist, requestToken, WS_TOKEN_COOKIE, WS_TOKEN_COOKIE_SECURE } from './http-server/security-helpers.js';
+export { buildCspHeader, decodeSessionId, injectWsConfig, isInsideDist, requestToken, WS_TOKEN_COOKIE, WS_TOKEN_COOKIE_SECURE, };
 export interface CreateHttpServerOptions {
     /** Port to listen on. Defaults to 3456 (or the `PORT` env var). */
     port?: number | undefined;
@@ -95,92 +122,6 @@ export interface CreateHttpServerOptions {
      */
     intakeService?: import('@wrongstack/requirement-intake').RequirementIntakeService | undefined;
 }
-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.
- *
- * Adds explicit `ws://`/`wss://` entries for loopback addresses (`127.0.0.1`,
- * `localhost`) so `connect-src` covers WebSocket even in strict CSP
- * implementations that distinguish `ws:` from `http:` origins.
- *
- * @param publicWsUrl - Optional public-facing WS URL (tunnel/reverse-proxy).
- *   When set, this origin is added to `connect-src` as a `ws://`/`wss://` entry.
- * @param host - The server bind host. When it matches a known loopback address
- *   (`127.0.0.1`, `::1`, `[::1]`, or `localhost`), explicit `ws://`/`wss://`
- *   entries for `127.0.0.1` and `localhost` are added to `connect-src`.
- *   IPv6 loopback (`[::1]`) is excluded — it produces an invalid CSP source
- *   and is covered by `'self'` (CSP maps ws:→http:, wss:→https:).
- * @param port - The server listen port. Defaults to `3456`. Unnecessary when
- *   only publicWsUrl is used (no loopback branch).
- */
-export declare function buildCspHeader(publicWsUrl?: string | undefined, host?: string, port?: number): string;
-/**
- * Returns true when `candidate` (a fully-resolved absolute path) lies
- * strictly inside `distDir` (or equals it). Used to reject path-traversal
- * attempts after `path.resolve` has normalised any `..` segments.
- *
- * Exported so tests can assert the guard's contract without having to
- * also defeat the WHATWG URL normaliser (which strips `..` from the
- * path string *before* the request even reaches the server, making a
- * black-box test via fetch impossible).
- */
-export declare function isInsideDist(candidate: string, distDir: string): boolean;
-/**
- * Decode a `:id` path segment captured by the `/api/sessions/:id/*` routes.
- *
- * Session ids are `YYYY-MM-DD/sess_<ULID>` — they contain a literal
- * `/`. The frontend builds the URL with `encodeURIComponent(sessionId)`, so
- * that slash arrives as `%2F`. The route regex `([^/]+)` correctly captures
- * the whole percent-encoded segment (there is no real `/` in `%2F`), but the
- * SessionRegistry is keyed by the *decoded* id — so the capture must be
- * `decodeURIComponent`d before lookup. Without this, every
- * `/api/sessions/:id/{events,message,agents}` request 404s (the registry has
- * `2026-…/…` but we looked up `2026-…%2F…`), which broke the Fleet HQ
- * watch-stream and the steer-message composer.
- *
- * Malformed percent-encoding (a lone `%`) makes `decodeURIComponent` throw;
- * fall back to the raw segment so the caller still gets a clean 404 rather
- * than a 500.
- */
-export declare function decodeSessionId(segment: string): string;
 /**
  * Create the static-file HTTP server. Returns the `http.Server` (not
  * listening yet) so the caller can attach to a `shutdown()` hook and

package/dist/server/index.d.ts

@@ -30,7 +30,7 @@ export { collectConnectionsHealth, type ConnectionHealthService, type Connection
 export { type CustomContextMode, type CustomModeStore, createCustomModeStore, } from './custom-context-modes.js';
 export { type DesignContext, handleDesignList, handleDesignMaterialize, handleDesignSet, handleDesignState, handleDesignSwap, handleDesignTune, handleDesignUse, handleDesignVerify, } from './design-handlers.js';
 export { createEternalSubscription, type EternalBroadcast, type EternalSubscribe, type EternalSubscription, } from './eternal-iteration-broadcast.js';
-export { handleFilesList, handleFilesRead, handleFilesTree, handleFilesWrite, } from './file-handlers.js';
+export { handleFilesCreate, handleFilesDelete, handleFilesList, handleFilesMove, handleFilesRead, handleFilesRename, handleFilesSkeleton, handleFilesTree, handleFilesWrite, } from './file-handlers.js';
 export { isHiddenEntry, rankFiles, SKIP_DIRS } from './file-picker.js';
 export { handleGitChanges, handleGitDiff, handleGitInfo } from './git-handlers.js';
 export { handleGoalGet } from './goal-handlers.js';
@@ -90,7 +90,7 @@ export type { ProjectRouteHandlers } from './project-routes.js';
 export { handleProjectRoute } from './project-routes.js';
 export { createProjectHandlers, type ProjectHandlersContext } from './project-handlers.js';
 export { ensureProjectDataDir, loadManifest, projectsJsonPath, saveManifest, touchProjectInManifest, } from './projects-manifest.js';
-export { handlePromptsContent, handlePromptsCreate, handlePromptsFavorite, handlePromptsList, handlePromptsRecent, handlePromptsSearch, handlePromptsUsed, type PromptsContext, } from './prompts-handlers.js';
+export { handlePromptsContent, handlePromptsCreate, handlePromptsFavorite, handlePromptsJournal, handlePromptsList, handlePromptsRecent, handlePromptsSearch, handlePromptsUsed, type PromptsContext, } from './prompts-handlers.js';
 export { loadSavedProviders, saveProviders } from './provider-config-io.js';
 export { createProviderConfigIO } from './provider-config-standalone.js';
 export { createProviderHandlers, createProviderOperations, type ProviderOperationsDeps, type ProviderPersistence, probeModelDescriptors, projectSavedProviders, type SavedProviderView, } from './provider-handlers.js';
@@ -115,6 +115,7 @@ export { handleShellOpen, type ShellOpenOptions, type ShellOpenRequest, type She
 export { handleSkillsContent, handleSkillsCreate, handleSkillsEdit, handleSkillsExport, handleSkillsInstall, handleSkillsList, handleSkillsUninstall, handleSkillsUpdate, type SkillsContext, } from './skills-handlers.js';
 export { handleSpecsRoute, type SpecsRouteHandlers } from './specs-routes.js';
 export { SpecsWebSocketHandler } from './specs-ws-handler.js';
+export { startProjectWatcher } from './project-watcher.js';
 export { startWebUI } from './start-webui.js';
 export { TerminalWebSocketHandler } from './terminal-ws-handler.js';
 export { type ContextBreakdown, estimateContextBreakdown, estimateTokens, type MessageTokenEntry, messagePreview, messageTokens, stringifyContent, type ToolTokenEntry, } from './token-estimator.js';

package/dist/server/network-info.d.ts

@@ -37,13 +37,12 @@ export declare function getExternalAddresses(getInterfaces?: () => NodeJS.Dict<o
  * Format the extra access-URL lines for a wildcard bind.
  *
  * Returns a list of indented, ready-to-print lines showing the external
- * IPs and their full access URLs (including token). Returns an empty
- * array for non-wildcard binds or when no external addresses are found.
+ * IPs and their access URLs. Authentication tokens are deliberately excluded
+ * because these lines are written to terminal and session logs.
  */
 export declare function formatExternalAccessUrls(opts: {
     bindHost: string;
     port: number;
-    token?: string | undefined;
     publicUrl?: string | undefined;
     getInterfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>;
 }): string[];

package/dist/server/project-watcher.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Project source-tree watcher — broadcasts `files.tree.changed` when
+ * files are created, modified, or deleted inside the project root, so
+ * the WebUI file explorer refreshes its tree without manual navigation.
+ *
+ * Uses Node's native `fs.watch` with `recursive: true` (supported on
+ * Windows and macOS; Linux support landed in Node 22). Events are
+ * debounced (400ms) to coalesce bursts from build tools, git
+ * checkouts, and agent writes. Heavyweight directories
+ * (`node_modules`, `.git`, `dist`, …) are ignored to avoid event
+ * storms — the same `SKIP_DIRS` set the tree builder uses.
+ *
+ * The watcher is `persistent: false` and `unref`'d on each handle so
+ * it does not keep the process alive. The returned disposer closes
+ * all native handles.
+ */
+import type { ConnectedClient, WSServerMessage } from './types.js';
+export interface ProjectWatcherDeps {
+    /** Absolute project root to watch. */
+    projectRoot: string;
+    /** Broadcast a message to all connected WS clients. */
+    broadcast: (clients: Map<import('ws').WebSocket, ConnectedClient>, msg: WSServerMessage) => void;
+    /** Live client map (same reference the rest of setupEvents uses). */
+    clients: Map<import('ws').WebSocket, ConnectedClient>;
+}
+/**
+ * Start watching `projectRoot` for filesystem changes. Returns a
+ * disposer that closes all native watch handles.
+ */
+export declare function startProjectWatcher(deps: ProjectWatcherDeps): () => void;
+//# sourceMappingURL=project-watcher.d.ts.map

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

@@ -33,6 +33,8 @@ export declare function handlePromptsCreate(ws: WSLike, ctx: PromptsContext, msg
 export declare function handlePromptsUsed(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
 /** Return recently-inserted prompt slugs (most-recent first) for the modal's Recent view. */
 export declare function handlePromptsRecent(ws: WSLike, ctx: PromptsContext): Promise<void>;
+/** Read the project's hierarchical prompt journal (`<projectRoot>/.wrongstack/prompts/`). */
+export declare function handlePromptsJournal(ws: WSLike, msg: unknown, projectRoot: string): Promise<void>;
 /** Minimal structural type for the ws.send sink (matches `ws` WebSocket). */
 type WSLike = Parameters<typeof send>[0];
 export {};

package/dist/server/sdd-board-ws-handler.d.ts

@@ -61,6 +61,15 @@ export declare class SddBoardWebSocketHandler {
     private applyLifecycle;
     dispose(): void;
     private pollLatest;
+    /**
+     * Cheap freshness probe used before the full snapshot load. In kanban mode
+     * the workflow-state listing IS the snapshot payload (no cheaper probe
+     * exists), so fall through to the load — the post-load `updatedAt` guard
+     * still dedups the broadcast. In legacy-file mode the store index carries
+     * per-run `updatedAt`, letting an unchanged board skip the snapshot file
+     * entirely. Probe failures fall through to the load path.
+     */
+    private hasNewerSnapshot;
     private startPolling;
     private stopPolling;
     private sendCurrent;

package/dist/server/sdd-wizard-ws-handler.d.ts

@@ -98,6 +98,7 @@ export declare class SddWizardWebSocketHandler {
     private onDiscard;
     private onMessage;
     private onApprove;
+    private onRewind;
     private onRunStart;
     private onRunFromGraph;
     private onRunFromSpec;

package/dist/server/setup-events-pattern-handlers.d.ts

@@ -0,0 +1,10 @@
+import type { EventBus } from '@wrongstack/core/kernel';
+import type { WebSocket } from 'ws';
+import type { ConnectedClient, WSServerMessage } from './types.js';
+export declare function registerSetupEventsPatternHandlers(options: {
+    events: EventBus;
+    broadcast: (clients: Map<WebSocket, ConnectedClient>, msg: WSServerMessage) => void;
+    clients: Map<WebSocket, ConnectedClient>;
+    sessionPayload: <T extends Record<string, unknown>>(payload: T) => T;
+}): Array<() => void>;
+//# sourceMappingURL=setup-events-pattern-handlers.d.ts.map

package/dist/server/setup-events-status-watcher.d.ts

@@ -8,7 +8,7 @@ export interface SetupEventsStatusWatcherDeps {
     watcherMetrics?: FileWatcherMetrics | undefined;
     clients: Map<WebSocket, ConnectedClient>;
     broadcast: (clients: Map<WebSocket, ConnectedClient>, msg: WSServerMessage) => void;
-    on: <E extends EventName>(event: E, listener: Listener<E>) => void;
+    on: <E extends EventName>(event: E, listener: Listener<E>) => (() => void) | void;
     isDisposed: () => boolean;
 }
 export declare function registerSetupEventsStatusWatcher(deps: SetupEventsStatusWatcherDeps): (() => void) | undefined;

package/dist/server/setup-events-subagent-handlers.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@wrongstack/core/agent';
+import type { EventName, Listener } from '@wrongstack/core/kernel';
+import type { WebSocket } from 'ws';
+import type { SetupEventProjection } from './setup-event-projection.js';
+import type { ConnectedClient, WSServerMessage } from './types.js';
+export declare function registerSetupEventsSubagentHandlers(options: {
+    on: <E extends EventName>(event: E, listener: Listener<E>) => void;
+    broadcast: (clients: Map<WebSocket, ConnectedClient>, msg: WSServerMessage) => void;
+    clients: Map<WebSocket, ConnectedClient>;
+    context: Context;
+    projection?: SetupEventProjection | undefined;
+    sessionPayload: <T extends Record<string, unknown>>(payload: T) => T;
+}): void;
+//# sourceMappingURL=setup-events-subagent-handlers.d.ts.map

package/dist/server/setup-events-tool-handlers.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from '@wrongstack/core/agent';
+import type { EventName, Listener } from '@wrongstack/core/kernel';
+import type { SessionEventBridge } from '@wrongstack/core/storage';
+import type { WebSocket } from 'ws';
+import type { PendingConfirm } from './pending-confirms.js';
+import type { SetupEventProjection } from './setup-event-projection.js';
+import type { ConnectedClient, WSServerMessage } from './types.js';
+export declare function registerSetupEventsToolHandlers(options: {
+    on: <E extends EventName>(event: E, listener: Listener<E>) => void;
+    broadcast: (clients: Map<WebSocket, ConnectedClient>, msg: WSServerMessage) => void;
+    clients: Map<WebSocket, ConnectedClient>;
+    context: Context;
+    pendingConfirms: Map<string, PendingConfirm>;
+    projection?: SetupEventProjection | undefined;
+    sessionPayload: <T extends Record<string, unknown>>(payload: T) => T;
+    appendForCurrentSession: (sessionId: string | undefined, event: Parameters<SessionEventBridge['append']>[0]) => void;
+}): void;
+//# sourceMappingURL=setup-events-tool-handlers.d.ts.map

package/dist/server/setup-events.d.ts

@@ -50,8 +50,7 @@ export { statusProjectHashFromWatchFilename } from './setup-events-watcher.js';
  * intervals, and flushes pending debounce timers. Callers MUST invoke it on
  * shutdown — the watcher is `persistent: true` and the metrics interval is not
  * `unref`'d, so without disposal they keep the process alive and leak across
- * server restarts. (Previously this was hung off a non-existent
- * `process.on('cleanup')` event that never fired.)
+ * server restarts.
  */
 export declare function setupEvents(deps: SetupEventsDeps): () => void;
 //# sourceMappingURL=setup-events.d.ts.map

package/dist/server/shell-open.d.ts

@@ -17,20 +17,21 @@ export interface ShellOpenRequest {
  */
 export declare function normalizeShellOpenTarget(target: string | undefined): ShellOpenTarget;
 /**
- * Optional security options for `handleShellOpen`.
+ * Security options for `handleShellOpen`.
  *
- * `projectRoot`, when provided, confines the resolved path to the project
- * directory — the OS file manager / terminal will never be launched at a
- * location outside the project. This is defense-in-depth: the TrustBoundary
- * authorization may use a permissive compatibility policy, so the path
- * containment must be enforced at the executor as well.
+ * `projectRoot` is **required** — it confines the resolved path to the
+ * project directory. Without it a WebSocket client could open the OS
+ * file manager or terminal at ANY existing path on the system
+ * (/etc, ~/.ssh, C:\Windows). The TrustBoundary authorization may use
+ * a permissive compatibility policy, so path containment is enforced
+ * here as defense-in-depth.
  */
 export interface ShellOpenOptions {
-    projectRoot?: string;
+    projectRoot: string;
 }
 export interface ShellOpenResult {
     success: boolean;
     message: string;
 }
-export declare function handleShellOpen(req: ShellOpenRequest, logger: Logger, options?: ShellOpenOptions): Promise<ShellOpenResult>;
+export declare function handleShellOpen(req: ShellOpenRequest, logger: Logger, options: ShellOpenOptions): Promise<ShellOpenResult>;
 //# sourceMappingURL=shell-open.d.ts.map

package/dist/server/start-webui-companion.d.ts

@@ -0,0 +1,16 @@
+import * as http from 'node:http';
+/**
+ * Dual-stack / IPv6 companion listener.
+ *
+ * When the primary bind is IPv4-only, also try the IPv6 equivalent so
+ * peers using IPv6 can connect. Tailscale assigns both v4 (100.x.x.x)
+ * and v6 (fd7a:…) addresses; Chrome/Edge on Windows resolve `localhost`
+ * to [::1] before 127.0.0.1. Without the companion listener, a v4-only
+ * bind causes ECONNREFUSED for all IPv6 peers.
+ *
+ * When the primary bind is IPv6-only (::), try the IPv4 companion as a
+ * fallback for systems where `::` does not accept IPv4-mapped
+ * connections (net.ipv6.bindv6only=1, some Windows configs).
+ */
+export declare function setupCompanionServer(httpServer: http.Server, wsHost: string | undefined, httpPort: number): http.Server | null;
+//# sourceMappingURL=start-webui-companion.d.ts.map

package/dist/server/start-webui-credential-watcher.d.ts

@@ -0,0 +1,13 @@
+import type { WebSocket } from 'ws';
+import type { WebuiDeps, WebuiMutableState } from './routes.js';
+import type { ConnectedClient } from './types.js';
+export declare function setupWebuiCredentialWatcher(options: {
+    watchConfigPath: string;
+    vault: WebuiDeps['vault'];
+    logger: WebuiDeps['logger'];
+    state: WebuiMutableState;
+    deps: WebuiDeps;
+    clients: Map<WebSocket, ConnectedClient>;
+    updateAutoCompactionMaxContext: (provider: any) => Promise<void>;
+}): (() => void) | undefined;
+//# sourceMappingURL=start-webui-credential-watcher.d.ts.map

package/dist/server/start-webui-remediation.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@wrongstack/core/agent';
+import type { ToolExecutor } from '@wrongstack/core/execution';
+import type { EventBus } from '@wrongstack/core/kernel';
+import type { PermissionPolicy } from '@wrongstack/core/types';
+import { type PackageOperation } from '@wrongstack/techstack';
+export declare function createPackageOperationExecutor(options: {
+    toolExecutor: ToolExecutor;
+    context: Context;
+    events: EventBus;
+    permissionPolicy: PermissionPolicy;
+}): (operation: PackageOperation, workspace?: string) => Promise<{
+    detail: string;
+}>;
+//# sourceMappingURL=start-webui-remediation.d.ts.map

package/dist/server/start-webui-shutdown.d.ts

@@ -0,0 +1,43 @@
+import type * as http from 'node:http';
+import type { WebSocket, WebSocketServer } from 'ws';
+import type { ConnectedClient } from './types.js';
+export declare function setupWebuiShutdown(options: {
+    session: any;
+    tokenCounter: any;
+    clients: Map<WebSocket, ConnectedClient>;
+    httpServer: http.Server;
+    companionServer: http.Server | null;
+    wssPrimary: WebSocketServer;
+    wssSecondary?: WebSocketServer | null | undefined;
+    stopEmptySessionCleanup: {
+        dispose: () => Promise<void>;
+    };
+    getKanbanSupervisorDispose: () => (() => void) | null;
+    todosCheckpoint: {
+        detach: () => Promise<void>;
+    };
+    stopHeapWatchdog: () => Promise<void>;
+    getCredentialWatcherClose: () => (() => void) | undefined;
+    disposeRealtimeHandlers: () => void;
+    governanceHandle?: {
+        close: () => Promise<{
+            ok: boolean;
+            action?: string;
+            message?: string;
+        } | undefined>;
+    } | undefined;
+    logger: any;
+    brainMonitor: any;
+    agentServices: any;
+    mcpRegistry: any;
+    sessionIdentity: any;
+    eventArming: any;
+    getEternalSubscription: () => {
+        dispose: () => void;
+    } | null;
+    clearEternalSubscription: () => void;
+    codebaseIndexing: any;
+    memoryStore: any;
+    globalConfigPath: string;
+}): () => void;
+//# sourceMappingURL=start-webui-shutdown.d.ts.map

package/dist/server/start-webui-todos.d.ts

@@ -0,0 +1,13 @@
+import { attachTodosCheckpoint } from '@wrongstack/core/storage';
+export declare function createStandaloneTodosCheckpointLifecycle(input: {
+    state: Parameters<typeof attachTodosCheckpoint>[0];
+    sessionsDir: string;
+    sessionId: string;
+    events?: Parameters<typeof attachTodosCheckpoint>[3];
+    traceId?: string | undefined;
+    warn?: ((message: string) => void) | undefined;
+}): {
+    rebind: (sessionId: string, sessionsDir: string) => Promise<void>;
+    detach: () => Promise<void>;
+};
+//# sourceMappingURL=start-webui-todos.d.ts.map

package/dist/server/start-webui.d.ts

@@ -7,19 +7,9 @@
  * service construction (Phase 1c), route/dispatcher/connection wiring
  * (Phase 1b/1a), WS + HTTP server creation, and graceful shutdown.
  */
-import { attachTodosCheckpoint } from '@wrongstack/core/storage';
+import { createStandaloneTodosCheckpointLifecycle } from './start-webui-todos.js';
 import type { WebUIOptions } from './types.js';
-export declare function createStandaloneTodosCheckpointLifecycle(input: {
-    state: Parameters<typeof attachTodosCheckpoint>[0];
-    sessionsDir: string;
-    sessionId: string;
-    events?: Parameters<typeof attachTodosCheckpoint>[3];
-    traceId?: string | undefined;
-    warn?: ((message: string) => void) | undefined;
-}): {
-    rebind: (sessionId: string, sessionsDir: string) => Promise<void>;
-    detach: () => Promise<void>;
-};
+export { createStandaloneTodosCheckpointLifecycle };
 export declare function startWebUI(opts?: WebUIOptions & {
     wsHost?: string | undefined;
     httpPort?: number | undefined;
@@ -29,21 +19,4 @@ export declare function startWebUI(opts?: WebUIOptions & {
     requireToken?: boolean | undefined;
     open?: boolean | undefined;
 }): Promise<void>;
-/**
- * Webui-side mailbox bridge discovery.
- *
- * The webui doesn't spawn a bridge — the bridge (`wstack mailbox serve`)
- * is spawned by any CLI surface via the auto-bootstrap wiring. We just
- * probe the per-project lock for an already-running instance and stash
- * the discovered handle on `ctx.meta['mailboxBridge']` so any later
- * code (the `/mailbox` HTTP surface, agent-status broadcasters,
- * external-agent proxy) can find it without re-running discovery.
- *
- * If no bridge is running, we log a breadcrumb so the user knows
- * to start one (`wstack --repl`, `wstack --webui`, or
- * `wstack mailbox serve` standalone).
- *
- * Best-effort: never throws. A failure (missing lock dir, ENOENT,
- * etc.) logs at warn level and returns — the webui keeps running.
- */
 //# sourceMappingURL=start-webui.d.ts.map