@wrongstack/webui 0.283.0 → 0.284.0

package/dist/server/index.d.ts

@@ -1,1223 +1 @@
-import { WebSocket } from 'ws';
-import { Agent, Context, Logger, EventBus, Provider, Tool, SessionStore, ToolRegistry, ModelsRegistry, ConfigStore, SecretVault, JournalEntry, MemoryStore, PromptLoader, PromptUsageStore, ProviderConfig, ProviderApiKey, SddInterviewDriver, AgentFactory, BrainArbiter, SkillLoader } from '@wrongstack/core';
-import * as http from 'node:http';
-import { MCPRegistry } from '@wrongstack/mcp';
-import { SkillInstaller } from '@wrongstack/core/skills';
-
-interface AutoPhaseWSMessage {
-    type: string;
-    payload?: Record<string, unknown>;
-}
-/**
- * AutoPhaseWebSocketHandler — WebSocket-based AutoPhase control.
- *
- * Message types:
- *   autophase.start   → { title, phases?, autonomous? }
- *   autophase.pause   → {}
- *   autophase.resume  → {}
- *   autophase.stop    → {}
- *   autophase.status  → {}
- *   autophase.selectPhase → { phaseId }
- *   autophase.taskStatus  → { taskId, status }
- */
-declare class AutoPhaseWebSocketHandler {
-    private agent;
-    private context;
-    private logger;
-    private events?;
-    private projectRoot?;
-    private orchestrator;
-    private graph;
-    private store;
-    private clients;
-    private broadcastInterval;
-    /** Aborts in-flight task agents AND the planning turn when the run is stopped. */
-    private abort;
-    /** Set the instant a stop/clear/revert is requested, so a planning turn that
-     *  resolves afterwards never launches the orchestrator (the abort alone can't
-     *  cover the window between the LLM call resolving and the orchestrator start). */
-    private stopping;
-    /** Optional per-phase git-worktree isolation (lazily created at start). */
-    private worktrees;
-    /** Base branch + tip SHA captured at run start so a revert can git-revert the
-     *  run's squash commits (history-preserving) instead of a destructive reset. */
-    private runBase;
-    /** Per-run worker identities so the board can show "who is on what". */
-    private usedNicknames;
-    constructor(agent: Agent, context: Context, logger: Logger, storeDir: string, events?: EventBus | undefined, projectRoot?: string | undefined);
-    addClient(ws: WebSocket): void;
-    handleMessage(msg: AutoPhaseWSMessage): Promise<void>;
-    private handleStart;
-    /**
-     * Halt the run NOW — at any phase. Sets `stopping` (so a planning turn that
-     * resolves afterwards bails), aborts in-flight agents, stops the orchestrator
-     * tick, and ends the live broadcast. The board is kept for review; use
-     * `autophase.clear` to reset or `autophase.revert` to undo the changes.
-     */
-    private handleStop;
-    /**
-     * Stop + wipe: tear down phase worktrees and reset to an empty board so the UI
-     * returns to the start screen ("new one"). Does NOT touch already-merged commits
-     * on the base branch — that is `autophase.revert`.
-     */
-    private handleClear;
-    /**
-     * Stop + undo: remove phase worktrees, then history-preservingly `git revert`
-     * every commit this run landed on the base branch (captured `runBase`..HEAD),
-     * then reset to an empty board. Refuses (reports a reason) on a dirty tree or a
-     * conflicting revert rather than leaving the tree half-reverted.
-     */
-    private handleRevert;
-    /** Generic fallback phases when the LLM planner produces nothing usable. */
-    private defaultPhases;
-    /** Plan phases+todos for the goal via the LLM; fall back to defaults on failure.
-     *  The caller passes the run's abort signal so a stop during planning cancels
-     *  the LLM turn (the previous fresh, never-aborted controller made planning
-     *  uninterruptible). */
-    private planPhases;
-    private executeTaskWithAgent;
-    /** Persist + broadcast after an interactive board mutation. */
-    private afterBoardMutation;
-    private handleTaskStatusChange;
-    private startBroadcast;
-    private stopBroadcast;
-    private broadcastState;
-    private buildState;
-    private sendState;
-    private broadcast;
-    private send;
-}
-
-/**
- * Context-aware editor completion for the WebUI Monaco surface.
- *
- * The handler combines fast symbol-index hits with a short, JSON-only LLM call.
- * It is intentionally side-effect free: it never writes files and only reads the
- * existing codebase index when available.
- */
-
-type CompletionItemKind = 'text' | 'method' | 'function' | 'constructor' | 'field' | 'variable' | 'class' | 'interface' | 'module' | 'property' | 'unit' | 'value' | 'enum' | 'keyword' | 'snippet' | 'file' | 'reference';
-interface CompletionSuggestion {
-    label: string;
-    insertText: string;
-    kind?: CompletionItemKind | undefined;
-    detail?: string | undefined;
-    documentation?: string | undefined;
-    sortText?: string | undefined;
-    source?: 'llm' | 'index' | 'lsp' | undefined;
-}
-interface CompletionHandlerOptions {
-    projectRoot: string;
-    provider?: Provider | undefined;
-    model?: string | undefined;
-    indexDir?: string | undefined;
-    lspCompletion?: LspCompletionSource | undefined;
-    timeoutMs?: number | undefined;
-}
-interface LspCompletionSourceRequest {
-    filePath: string;
-    lineNumber: number;
-    column: number;
-    content?: string | undefined;
-    triggerCharacter?: string | undefined;
-    signal: AbortSignal;
-}
-type LspCompletionSource = (request: LspCompletionSourceRequest) => Promise<CompletionSuggestion[]>;
-declare function handleCompletionRequest(ws: WebSocket, msg: unknown, opts: CompletionHandlerOptions): Promise<void>;
-declare function createToolLspCompletionSource(tool: Tool | undefined, ctx: Context): LspCompletionSource | undefined;
-
-/**
- * Custom context modes — user-defined presets that are loaded from disk,
- * merged with the built-in modes, and managed via WebSocket CRUD handlers.
- *
- * Stored in: ~/.wrongstack/custom-context-modes.json
- * Format: { "modes": ContextWindowMode[] }
- */
-interface CustomContextMode {
-    id: string;
-    name: string;
-    description: string;
-    thresholds: {
-        warn: number;
-        soft: number;
-        hard: number;
-    };
-    aggressiveOn: string;
-    preserveK: number;
-    eliseThreshold: number;
-    targetLoad: number;
-    /** Whether this is a user-defined (custom) or built-in mode. */
-    custom: boolean;
-}
-interface CustomModeStore {
-    modes: Map<string, CustomContextMode>;
-    load: () => Promise<void>;
-    save: () => Promise<void>;
-    create: (mode: CustomContextMode) => {
-        ok: boolean;
-        error?: string | undefined;
-    };
-    update: (id: string, patch: Partial<CustomContextMode>) => {
-        ok: boolean;
-        error?: string | undefined;
-    };
-    remove: (id: string) => {
-        ok: boolean;
-        error?: string | undefined;
-    };
-    list: () => CustomContextMode[];
-}
-declare function createCustomModeStore(wrongstackDir: string): CustomModeStore;
-
-/**
- * Shared Design Studio WebSocket handlers for both the standalone WebUI server
- * (`packages/webui/src/server/index.ts`) and the CLI's `--webui` embedded
- * server (`packages/cli/src/webui-server.ts`). One source of truth keeps the two
- * servers at parity (enforced by ws-handler-parity.test.ts).
- *
- *   case 'design.list':        return handleDesignList(ws, designCtx);
- *   case 'design.use':         return handleDesignUse(ws, designCtx, msg);
- *   case 'design.state':       return handleDesignState(ws, designCtx);
- *   case 'design.set':         return handleDesignSet(ws, designCtx, msg);
- *   case 'design.materialize': return handleDesignMaterialize(ws, designCtx, msg);
- *
- * Browsing + customization of curated UI design kits; `design.use` pins the
- * active kit, `design.set` records color/token overrides, `design.materialize`
- * writes the (override-applied) tokens to a real theme file on disk.
- */
-
-interface DesignContext {
-    projectRoot: string;
-    /** Live agent context whose `meta.designStudio` we read/pin. Optional. */
-    agentMeta?: {
-        meta: Record<string, unknown>;
-    } | undefined;
-}
-declare function handleDesignList(ws: WebSocket, ctx: DesignContext): Promise<void>;
-declare function handleDesignState(ws: WebSocket, ctx: DesignContext): Promise<void>;
-declare function handleDesignUse(ws: WebSocket, ctx: DesignContext, msg: {
-    payload?: unknown;
-}): Promise<void>;
-/** Record structured color/token overrides without changing the pinned kit. */
-declare function handleDesignSet(ws: WebSocket, ctx: DesignContext, msg: {
-    payload?: unknown;
-}): Promise<void>;
-/** Write the active kit's (override-applied) tokens to a real theme file. */
-declare function handleDesignMaterialize(ws: WebSocket, ctx: DesignContext, msg: {
-    payload?: unknown;
-}): Promise<void>;
-/** Scan project UI files for off-palette colors against the active kit. */
-declare function handleDesignVerify(ws: WebSocket, ctx: DesignContext): Promise<void>;
-
-interface WSServerMessage {
-    type: string;
-    payload: unknown;
-}
-interface WSClientMessage {
-    type: string;
-    payload?: unknown | undefined;
-}
-interface WebUIOptions {
-    /** HTTP frontend port. Prefer `httpPort`; `port` is kept for compatibility. */
-    port?: number | undefined;
-    /** HTTP frontend port. */
-    httpPort?: number | undefined;
-    webuiPort?: number | undefined;
-    /** WebSocket backend port. */
-    wsPort?: number | undefined;
-    /** Host/interface to bind. */
-    wsHost?: string | undefined;
-    /** Fixed access token/password. Defaults to WEBUI_TOKEN or random per process. */
-    accessToken?: string | undefined;
-    /** Browser-facing HTTP URL, used in startup output and instance registry. */
-    publicUrl?: string | undefined;
-    /** Browser-facing WebSocket URL, injected into the frontend for tunnels/proxies. */
-    publicWsUrl?: string | undefined;
-    /** Force token/password protection even on loopback binds. */
-    requireToken?: boolean | undefined;
-    /**
-     * Pre-built backend services. When provided, `startWebUI` skips its
-     * default agent/event-bus/session/store construction and wires the
-     * supplied instances into the WS message router and HTTP API
-     * handlers instead.
-     *
-     * Intended for callers (most notably `cli/webui-server.ts`) that
-     * already own the agent lifecycle — the CLI's `runWebUI` constructs
-     * the Agent, EventBus, SessionStore, and friends so it can run an
-     * eternal iteration against them, then hands the lot to the webui
-     * for the human-facing surface.
-     *
-     * `session` is typed as `SessionStore` (read + write) rather than
-     * the narrower `SessionWriter` because `startWebUI` needs to
-     * `load()` existing session history to project the chat view, and
-     * `list()` past sessions to populate the sessions dashboard. A
-     * `SessionWriter`-only field would force `startWebUI` to take a
-     * separate `sessionStore` for reads, which is a worse API for the
-     * CLI caller (`runWebUI` already has one store, not two).
-     *
-     * When `services` is omitted, `startWebUI` retains its existing
-     * behavior (builds the defaults in-place). This keeps the standalone
-     * `node dist/index.js webui` flow fully back-compatible.
-     */
-    services?: BackendServices | undefined;
-    /**
-     * Subscribe to live per-iteration events from the eternal-autonomy
-     * engine. When provided, `startWebUI` wires a WS broadcast that
-     * pushes each `JournalEntry` to every connected client. Observability
-     * only — starting the loop still goes through REPL/TUI or `--eternal`,
-     * since the webui has no slash-command dispatch surface yet.
-     *
-     * The argument is a *function* the caller supplies that performs the
-     * actual subscription; the returned disposer is invoked on
-     * `shutdown()`. This indirection lets the caller (most commonly
-     * `cli/webui-server.ts`) own the engine lifecycle and merely hand the
-     * webui an observer slot.
-     */
-    subscribeEternalIteration?: ((fn: (entry: JournalEntry) => void) => () => void) | undefined;
-}
-interface BackendServices {
-    agent: Agent;
-    events: EventBus;
-    session: SessionStore;
-    toolRegistry: ToolRegistry;
-    modelsRegistry: ModelsRegistry;
-    configStore: ConfigStore;
-    vault: SecretVault;
-    globalConfigPath: string;
-    projectRoot: string;
-}
-interface ConnectedClient {
-    ws: WebSocket;
-    sessionId: string | null;
-    connectedAt: number;
-    /** Unique per-connection id — used to key per-connection state (e.g. the
-     *  rate-limit bucket) so distinct browser tabs that share the same
-     *  `sessionId` do not collide, and so the entry is reliably removable on
-     *  close (`String(ws)` is `"[object Object]"` for every socket). */
-    connId: string;
-}
-
-type EternalSubscribe = (fn: (entry: JournalEntry) => void) => () => void;
-type EternalBroadcast<C> = (clients: Map<WebSocket, C>, msg: WSServerMessage) => void;
-interface EternalSubscription {
-    /** Tear down the underlying engine subscription. Idempotent. */
-    dispose: () => void;
-}
-declare function createEternalSubscription<C>(subscribe: EternalSubscribe, broadcast: EternalBroadcast<C>, clientsRef: () => Map<WebSocket, C>): EternalSubscription;
-
-/**
- * Shared file-operation WebSocket handlers for both the standalone WebUI
- * server and the CLI's `--webui` embedded server. Extracted from the
- * duplicated switch cases in `index.ts` and `cli/src/webui-server.ts`.
- *
- * Each function handles the full request→response cycle for one message
- * type. Callers drop them into their switch statement:
- *
- *   case 'files.tree': return handleFilesTree(ws, msg, projectRoot);
- */
-
-interface FilesWriteOptions {
-    onWritten?: ((filePath: string) => void | Promise<void>) | undefined;
-}
-/**
- * Build and send a nested directory tree for the File Explorer.
- *
- * Walks `projectRoot` to depth 10 max, skipping heavyweight dirs
- * (node_modules, .git, dist, …) and dot-entries. Responds with
- * `{ type: 'files.tree', payload: { root, tree } }`.
- */
-declare function handleFilesTree(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
-/**
- * Read a file's content for the Monaco editor.
- *
- * Guards against path traversal (`../` escapes). Responds with
- * `{ type: 'files.read', payload: { filePath, content } }`.
- */
-declare function handleFilesRead(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
-/**
- * Write file content back to disk (atomic write via tmp + rename).
- *
- * Guards against path traversal. Responds with
- * `{ type: 'files.written', payload: { filePath, success } }`.
- */
-declare function handleFilesWrite(ws: WebSocket, msg: unknown, projectRoot: string, opts?: FilesWriteOptions): Promise<void>;
-/**
- * Lightweight project file picker for the chat `@` mention popup.
- *
- * Walks `projectRoot` (max depth 8), skipping hidden and heavyweight
- * dirs, then fuzzy-ranks results against `query`. Responds with
- * `{ type: 'files.list', payload: { files } }`.
- */
-declare function handleFilesList(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
-
-/**
- * Shared `git.info` WebSocket handler for both the standalone WebUI server and
- * the CLI's `--webui` embedded server. Extracted from the duplicated switch
- * cases in `index.ts` and `cli/src/webui-server.ts`, which had drifted (the
- * standalone copy transposed ahead/behind and never matched deletions). One
- * implementation here keeps both surfaces in lockstep.
- *
- *   case 'git.info': return handleGitInfo(ws, projectRoot);
- */
-
-/**
- * Read git branch, change stats, and upstream sync status from `projectRoot`
- * and broadcast a `git.info` message. Never throws — a non-repo / missing-git
- * directory yields an empty-but-valid payload.
- */
-declare function handleGitInfo(ws: WebSocket, projectRoot: string): Promise<void>;
-/**
- * Read the working-tree change set (everything that differs from HEAD:
- * staged, unstaged, and untracked) and broadcast a `git.changes` message.
- *
- * The file list comes from `git status --porcelain -z` (NUL-delimited so
- * paths with spaces/unicode survive intact, and renames are unambiguous).
- * Per-file line counts come from `--numstat` of both the unstaged and the
- * staged diff, summed. Untracked files intentionally report 0/0 here so the
- * list view does not read every untracked file; `git.diff` loads a selected
- * file lazily on demand.
- * Never throws — a non-repo yields an empty list.
- */
-declare function handleGitChanges(ws: WebSocket, projectRoot: string): Promise<void>;
-/**
- * Resolve the before/after text for a single file and broadcast a `git.diff`
- * message. `oldText` is the file at HEAD (`git show HEAD:<path>`), `newText`
- * is the current working-tree content. New/untracked files have empty
- * `oldText`; deleted files have empty `newText`. Binary or oversized files
- * are reported with a flag instead of content so the client can show a notice.
- */
-declare function handleGitDiff(ws: WebSocket, projectRoot: string, path: string): Promise<void>;
-
-/** Metrics for the file watcher that watches status.json files. */
-interface FileWatcherMetrics {
-    /** Number of status.json filesystem events detected after filename filtering. */
-    fileChangesDetected: number;
-    filesProcessed: number;
-    broadcastsSent: number;
-    debounceResets: number;
-    totalDebounceDelayMs: number;
-    activeProjects: number;
-    /** Average debounce delay in ms across all broadcasts. */
-    averageDebounceDelayMs: number;
-    /** Whether the file watcher is currently active. */
-    watcherActive: boolean;
-}
-
-interface CreateHttpServerOptions {
-    /** Port to listen on. Defaults to 3456 (or the `PORT` env var). */
-    port?: number | undefined;
-    /** Host/interface to bind. Typically the loopback for the WebUI. */
-    host: string;
-    /** Resolved path to the directory containing the built React assets. */
-    distDir: string;
-    /**
-     * WS port — appears in the CSP `connect-src` directive so the browser
-     * is allowed to open a WebSocket back to the local server.
-     */
-    wsPort: number;
-    /**
-     * Public WebSocket URL injected into the frontend. Use this behind tunnels or
-     * reverse proxies where the browser-facing WS URL differs from host:wsPort.
-     */
-    publicWsUrl?: string | undefined;
-    /**
-     * Path to the global WrongStack root (~/.wrongstack). Used by the
-     * /api/sessions and /api/sessions/:id/agents endpoints to read the
-     * cross-process SessionRegistry.
-     */
-    globalRoot?: string | undefined;
-    /**
-     * Shared auth token for HTTP and WS access. Required for non-loopback
-     * binds (LAN exposure). Loopback binds accept local browser access without
-     * a token (the WS path's loopback-bootstrap policy — see ws-auth.ts).
-     */
-    apiToken?: string | undefined;
-    /** Force HTTP token auth even on loopback binds, useful behind public tunnels. */
-    requireToken?: boolean | undefined;
-    /**
-     * If true, the `/ws-auth` endpoint exchanges a `?token=` query param (or
-     * `X-WS-Token` header) for an `HttpOnly` auth cookie. The cookie is then
-     * sent automatically on the WS upgrade, closing the C-598 query-string
-     * token exposure class. Default: true. Set to false to keep the legacy
-     * URL-token-only flow (e.g. in tests that don't want cookie state).
-     */
-    enableWsCookie?: boolean | undefined;
-    /**
-     * Optional file watcher metrics object. When provided, the
-     * /debug/watcher-metrics endpoint will be enabled to expose these metrics.
-     */
-    watcherMetrics?: FileWatcherMetrics | undefined;
-    /**
-     * Push-on-write hook. `POST /api/fleet/ping` (loopback only) invokes this to
-     * trigger an immediate fleet re-broadcast, so a TUI/REPL's registry write
-     * reaches the map without waiting on the file-watch/poll. Best-effort.
-     */
-    onFleetPing?: (() => void) | undefined;
-}
-/**
- * Inject the live WS port into the served HTML so the frontend connects to
- * THIS instance's backend instead of a hardcoded default. Enables running
- * several WebUI instances simultaneously on different PORT/WS_PORT pairs
- * (e.g. one per project) — each instance serves HTML stamped with its own
- * WS port.
- *
- * A `<meta>` tag is used deliberately rather than an inline `<script>`: the
- * CSP sets `script-src 'self'`, which would block an inline script, but meta
- * tags are not subject to script-src. The frontend reads
- * `meta[name="wrongstack-ws-port"]` (see ws-client.ts `defaultWsUrl`).
- */
-declare function injectWsPort(html: string, wsPort: number): string;
-/** Build the Content-Security-Policy value for the given WS port. */
-declare function buildCspHeader(wsPort: number, requestHost?: string | undefined, publicWsUrl?: string | undefined): string;
-/**
- * Create the static-file HTTP server. Returns the `http.Server` (not
- * listening yet) so the caller can attach to a `shutdown()` hook and
- * coordinate the listen() with the WebSocket bootstrap.
- */
-declare function createHttpServer(opts: CreateHttpServerOptions): http.Server;
-
-/**
- * Running-instance registry for the standalone WebUI server.
- *
- * Every live `wstackui` process records itself in a single JSON file under the
- * wstack home dir (`~/.wrongstack/webui-instances.json`) so a user running
- * several instances (one per project, or several per project on different
- * ports) can see at a glance which ports are open for which path.
- *
- * Design notes:
- * - **Self-healing**: every register/unregister/list prunes entries whose PID
- *   is no longer alive (`process.kill(pid, 0)`), so a crashed instance that
- *   never got to unregister doesn't leave a ghost behind.
- * - **Atomic writes**: the file is rewritten via `atomicWrite` (tmp + rename),
- *   so a concurrent reader never sees a half-written file. Two instances
- *   starting at the *exact* same millisecond could still race the
- *   read-modify-write — acceptable for a best-effort tracking file, and the
- *   next register() heals any dropped entry.
- * - **Best-effort**: a failure to read/write the registry must NEVER take the
- *   server down. Callers wrap these in `.catch()`.
- */
-/** One running WebUI process. */
-interface WebUIInstanceRecord {
-    /** OS process id — also the liveness key. */
-    pid: number;
-    /** HTTP port serving the React frontend. */
-    httpPort: number;
-    /** WebSocket port for the agent backend. */
-    wsPort: number;
-    /** Bind host (e.g. 127.0.0.1 or 0.0.0.0). */
-    host: string;
-    /** Absolute project root the instance booted against. */
-    projectRoot: string;
-    /** Display name (basename of projectRoot). */
-    projectName: string;
-    /** ISO timestamp when the instance registered. */
-    startedAt: string;
-    /** Convenience open-in-browser URL. */
-    url: string;
-}
-/** Default wstack home dir (`~/.wrongstack`). Callers may override the base. */
-declare function defaultBaseDir(): string;
-/** Resolve the registry file path for a given base dir. */
-declare function registryPath(baseDir?: string): string;
-/**
- * Register (or refresh) this instance. Prunes dead entries and any stale entry
- * for our own PID before adding the current record. Best-effort — rejects only
- * on a hard fs error, which callers swallow.
- */
-declare function registerInstance(record: WebUIInstanceRecord, baseDir?: string): Promise<void>;
-/** Remove this instance (called on graceful shutdown). Also prunes dead pids. */
-declare function unregisterInstance(pid: number, baseDir?: string): Promise<void>;
-/** List live instances, pruning any dead entries encountered. */
-declare function listInstances(baseDir?: string): Promise<WebUIInstanceRecord[]>;
-/** Human-readable table of running instances for `wstackui --list`. */
-declare function formatInstances(instances: WebUIInstanceRecord[]): string;
-
-/**
- * MCP management handlers for the WebUI server (both the standalone
- * `wstackui` server and the CLI's embedded `--webui` server).
- *
- * These are thin WebSocket translators over the shared, surface-agnostic
- * management core in `@wrongstack/mcp` (`manage.ts`) — the SAME core the REPL
- * `/mcp` command writes against (same config.json, same MCPRegistry). All the
- * config IO, url/header persistence, and live registry start/stop logic lives
- * there; here we only map structured results to WS events the browser expects.
- */
-
-/** mcp.list — configured servers merged with live registry status + tools. */
-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. */
-declare function handleMcpAdd(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.update — re-persist config (incl. url/headers) and re-apply to registry. */
-declare function handleMcpUpdate(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.remove — stop the server and delete it from config. */
-declare function handleMcpRemove(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.enable — flip enabled:true in config and start the server. */
-declare function handleMcpEnable(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.disable — stop the server and flip enabled:false in config. */
-declare function handleMcpDisable(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.sleep — stop a running server (config stays enabled). */
-declare function handleMcpSleep(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.wake — restart a sleeping/stopped server from config. */
-declare function handleMcpWake(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.restart — stop + start a server. */
-declare function handleMcpRestart(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.discover — ensure the server is running and report its live tools. */
-declare function handleMcpDiscover(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-
-/**
- * Shared memory-operation WebSocket handlers for both the standalone WebUI
- * server and the CLI's `--webui` embedded server. Extracted from the
- * duplicated switch cases in `index.ts` and `cli/src/webui-server.ts`.
- *
- * Each function handles the full request→response cycle for one message
- * type. Callers drop them into their switch statement:
- *
- *   case 'memory.list': return handleMemoryList(ws, memoryStore);
- */
-
-/**
- * List all memory entries across all scopes.
- * Responds with `{ type: 'memory.list', payload: { text } }`.
- */
-declare function handleMemoryList(ws: WebSocket, memoryStore: MemoryStore): Promise<void>;
-/**
- * Persist a new memory entry.
- * Responds with `{ type: 'key.operation_result', payload: { success, message } }`.
- */
-declare function handleMemoryRemember(ws: WebSocket, msg: unknown, memoryStore: MemoryStore): Promise<void>;
-/**
- * Remove memory entries matching the given text.
- * Responds with `{ type: 'key.operation_result', payload: { success, message } }`.
- */
-declare function handleMemoryForget(ws: WebSocket, msg: unknown, memoryStore: MemoryStore): Promise<void>;
-
-/**
- * Best-effort "open this URL in the default browser" for `--webui --open`.
- *
- * Cross-platform via the OS opener (`start` / `open` / `xdg-open`). Fully
- * fire-and-forget: a missing opener, a headless box, or a spawn failure must
- * NEVER take the server down — the URL is always also printed to the console.
- */
-/** Resolve the platform's URL-opener command + args. */
-declare function browserOpenCommand(url: string, platform?: NodeJS.Platform): {
-    command: string;
-    args: string[];
-};
-/** Spawn the OS browser-opener for `url` and register it as a protected
- *  process so it survives kill/killAll. Never throws. */
-declare function openBrowser(url: string, platform?: NodeJS.Platform): void;
-
-/**
- * Free-port discovery for the standalone WebUI server.
- *
- * When a user runs several instances, the default ports (HTTP 3456 / WS 3457)
- * are taken by the first one. Rather than make the user hand-pick `PORT` /
- * `WS_PORT` for every extra instance, the server probes upward from the
- * requested port and binds the first free one — then stamps that real port into
- * the served HTML and the instance registry so everything stays consistent.
- *
- * The probe binds a throwaway `net.Server`, then closes it, so there is a tiny
- * TOCTOU window between "found free" and "the real server binds it". For local
- * single-user multi-instance use that race is negligible; if it ever loses, the
- * real bind fails loudly with EADDRINUSE exactly as before.
- */
-/** Resolve true when `port` can be bound on `host`, false on EADDRINUSE/EACCES. */
-declare function isPortFree(host: string, port: number): Promise<boolean>;
-interface FindFreePortOptions {
-    /** Ports to skip even if free (e.g. one already chosen for the sibling server). */
-    exclude?: Set<number> | undefined;
-    /** How many consecutive ports to try before giving up. Default 200. */
-    maxTries?: number | undefined;
-}
-/**
- * Find the first free port at or above `startPort` on `host`, skipping any in
- * `exclude`. Throws if nothing is free within `maxTries` steps.
- */
-declare function findFreePort(host: string, startPort: number, opts?: FindFreePortOptions): Promise<number>;
-
-/**
- * Send a JSON message to a single WebSocket client.
- * No-op when the socket is not in OPEN state (disconnected / closing).
- */
-declare function send(ws: WebSocket, msg: object): void;
-/**
- * Broadcast a JSON message to every connected client.
- * Swallows per-socket send errors — a client that disconnected between the
- * readyState check and `ws.send()` is cleaned up by its own `close` handler.
- */
-declare function broadcast(clients: Map<WebSocket, ConnectedClient>, msg: object): void;
-/**
- * Send a success/failure result message (used by key.* and provider.* handlers).
- * The frontend expects `key.operation_result` with `{ success, message }`.
- */
-declare function sendResult(ws: WebSocket, success: boolean, message: string): void;
-/**
- * Extract a human-readable message from an unknown thrown value.
- */
-declare function errMessage(err: unknown): string;
-/**
- * Generate a cryptographically random WebSocket auth token (hex string).
- * Shared between standalone and CLI-embedded WebUI servers.
- */
-declare function generateAuthToken(): string;
-declare function resolveAuthToken(explicit?: string | undefined): string;
-declare function hostForBrowserUrl(bindHost: string): string;
-declare function buildWebUIAccessUrl(opts: {
-    host: string;
-    port: number;
-    token?: string | undefined;
-    protocol?: 'http' | 'https' | undefined;
-    publicUrl?: string | undefined;
-}): string;
-declare function envFlag(name: string): boolean;
-
-/**
- * Shared prompt-library WebSocket handlers for BOTH the standalone WebUI server
- * (`packages/webui/src/server/index.ts`) and the CLI's `--webui` embedded server
- * (`packages/cli/src/webui-server.ts`). One source of truth so the two servers
- * never drift (the lesson from skills-handlers).
- *
- * Each function handles one request→response cycle; callers drop them into their
- * switch:
- *
- *   case 'prompts.search': return handlePromptsSearch(ws, promptsCtx, msg);
- *
- * The prompt library is read across three layers (builtin + user + project) by
- * the injected `PromptLoader`; writes (create/favorite) go to the user layer
- * with copy-on-write for builtins. Treat synced/builtin content as DATA — these
- * handlers never execute it; the client inserts a chosen prompt into the chat
- * input as an ordinary user turn.
- */
-
-interface PromptsContext {
-    /** Backs all prompt ops. Absent ⇒ feature unavailable. */
-    promptLoader: PromptLoader | undefined;
-    /** Records per-slug insert counts (shared with CLI `/prompt recent`). */
-    promptUsage?: PromptUsageStore | undefined;
-}
-declare function handlePromptsList(ws: WSLike, ctx: PromptsContext): Promise<void>;
-declare function handlePromptsSearch(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-declare function handlePromptsContent(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-declare function handlePromptsFavorite(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-declare function handlePromptsCreate(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-/** Record that a prompt was inserted (best-effort; feeds CLI `/prompt recent`). */
-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. */
-declare function handlePromptsRecent(ws: WSLike, ctx: PromptsContext): Promise<void>;
-/** Minimal structural type for the ws.send sink (matches `ws` WebSocket). */
-type WSLike = Parameters<typeof send>[0];
-
-/**
- * Read the `providers` section from the global config, decrypting
- * secret-bearing fields. Returns an empty record when the config file
- * doesn't exist or has no `providers` key.
- */
-declare function loadSavedProviders(configPath: string, vault: SecretVault): Promise<Record<string, ProviderConfig>>;
-/**
- * Write `providers` back into the global config, encrypting secrets first.
- * Refuses to overwrite a corrupt-but-existing config file (the operator
- * should fix it manually). When the config file is missing (ENOENT), starts
- * from an empty object.
- */
-declare function saveProviders(configPath: string, vault: SecretVault, providers: Record<string, ProviderConfig>): Promise<void>;
-/**
- * Small helper for the standalone WebUI entry point: create a
- * `{ load, save }` pair from a config path alone (uses the
- * config-directory-relative `.key` file for the vault). The `--webui`
- * CLI mode and the standalone server both need to read/write the
- * `providers` map identically.
- */
-declare function createProviderConfigIO(configPath: string): {
-    load: () => Promise<Record<string, ProviderConfig>>;
-    save: (providers: Record<string, ProviderConfig>) => Promise<void>;
-};
-
-/**
- * Pure provider/API-key record transforms for the WebUI server's `key.*` and
- * `provider.*` WebSocket handlers.
- *
- * These operate on an in-memory `providers` record (the decrypted
- * `config.providers` map) and return a `{ ok, message }` result mirroring the
- * status string the handler sends back to the client. All persistence
- * (load/decrypt, encrypt/atomic-write) and WS messaging stays in `index.ts` —
- * keeping this layer pure means the security-sensitive key bookkeeping (which
- * key is active, when a provider is dropped, how legacy single-key configs are
- * normalized) is unit-testable without a vault or a socket.
- *
- * Extracted from `index.ts`; transforms mutate the passed record in place, the
- * same way the original handlers did before calling `saveProviders`.
- */
-
-type ProvidersRecord = Record<string, ProviderConfig>;
-interface KeyOpResult {
-    ok: boolean;
-    message: string;
-}
-/**
- * Normalize a provider's keys to the array form, upgrading a legacy single
- * `apiKey` string to a one-element `[{ label: 'default', ... }]` list. Returns
- * fresh copies so callers can mutate without aliasing the stored config.
- */
-declare function normalizeKeys(cfg: ProviderConfig): ProviderApiKey[];
-/**
- * Write a normalized key list back onto a provider config: drop all key fields
- * when empty, otherwise sync `apiKeys` and re-point `activeKey` if it no longer
- * names a present key. Does NOT mirror the plaintext key to the legacy `apiKey`
- * field — that would leak the secret on accidental serialization. Consumers
- * that need the real key should read from `apiKeys[]` directly.
- */
-declare function writeKeysBack(cfg: ProviderConfig, keys: ProviderApiKey[]): void;
-/** Mask a secret for display: `••••` for short keys, `abcd…wxyz` otherwise. */
-declare function maskedKey(key: string | undefined): string;
-/** Add or replace a labeled key for a provider, creating the provider if new. */
-declare function upsertKey(providers: ProvidersRecord, providerId: string, label: string, apiKey: string, nowIso: string): KeyOpResult;
-/** Remove a labeled key; drops the provider entirely when its last key goes. */
-declare function deleteKey(providers: ProvidersRecord, providerId: string, label: string): KeyOpResult;
-/** Point a provider's active key at the given label. */
-declare function setActiveKey(providers: ProvidersRecord, providerId: string, label: string): KeyOpResult;
-/** Register a brand-new provider (optionally with an initial `default` key). */
-declare function addProvider(providers: ProvidersRecord, payload: {
-    id: string;
-    family: string;
-    baseUrl?: string | undefined;
-    apiKey?: string | undefined;
-}, nowIso: string): KeyOpResult;
-/** Remove an entire provider and all its keys. */
-declare function removeProvider(providers: ProvidersRecord, providerId: string): KeyOpResult;
-
-interface SddBoardWSMessage {
-    type: string;
-    payload?: Record<string, unknown>;
-}
-/** Project paths the handler needs to apply lifecycle ops directly. */
-interface SddBoardLifecycleDeps {
-    projectRoot: string;
-    paths: {
-        projectSpecs: string;
-        projectTaskGraphs: string;
-        projectSddSession: string;
-        projectSddBoards: string;
-    };
-}
-/**
- * SddBoardWebSocketHandler — streams the live SDD multi-agent board to clients
- * and relays control commands back to the CLI-owned run.
- *
- * Two observe modes (one class, shared by both webui servers):
- *  • in-process (CLI-hosted): subscribe the shared EventBus `sdd.board.snapshot`
- *    for instant updates;
- *  • standalone (separate process): poll the on-disk snapshot store (the CLI
- *    run persists JSON every change).
- *
- * Control is uniform + cross-process: every command is appended to the run's
- * `<runId>.control.jsonl`, which the CLI run drains and applies — so the run
- * stays the single driver and nothing races on shared state.
- */
-declare class SddBoardWebSocketHandler {
-    private readonly store;
-    private readonly clients;
-    private readonly lifecycle?;
-    private latest;
-    private poll;
-    private unsub;
-    constructor(boardsDir: string, events?: EventBus, lifecycle?: SddBoardLifecycleDeps);
-    addClient(ws: WebSocket): void;
-    handleMessage(msg: SddBoardWSMessage): Promise<void>;
-    /**
-     * Apply a cleanup/rollback/destroy from disk and broadcast a structured
-     * `sdd.board.lifecycle_result`. Refuses (no-op) while a run is still active —
-     * the user must stop it first; the UI gates the buttons on `!active` and the
-     * Destroy flow auto-stops then waits before sending `destroy`.
-     */
-    private applyLifecycle;
-    dispose(): void;
-    private pollLatest;
-    private sendCurrent;
-    private broadcastCurrent;
-    private loadLatestFromDisk;
-    private broadcast;
-    private send;
-}
-
-interface WizardMessage {
-    type: string;
-    payload?: Record<string, unknown>;
-}
-/**
- * Dependencies each webui server supplies. The handler is deliberately
- * agent-agnostic: every surface decides how to build a driver, how to run an
- * interview turn (on an isolated agent, off the main chat bus), and how to
- * start the real multi-agent run (CLI's director-backed factory vs the runtime
- * light factory). This keeps the wizard protocol identical across both servers.
- */
-interface SddWizardDeps {
-    /** Build a fresh interview driver (disk spec/graph stores + session path). */
-    makeDriver: () => SddInterviewDriver;
-    /**
-     * Run one interview turn: feed the AI prompt to an isolated agent and return
-     * its final text. MUST NOT run on the main chat agent's bus — the wizard owns
-     * this conversation, separate from the user's chat.
-     */
-    runInterviewTurn: (prompt: string) => Promise<string>;
-    /**
-     * Start the real multi-agent SDD run for the driver's task graph. Returns the
-     * runId; the live board flows through the existing board handler.
-     */
-    startRun: (driver: SddInterviewDriver, opts: {
-        parallelSlots?: number | undefined;
-        defaultModel?: string | undefined;
-        defaultProvider?: string | undefined;
-        fallbackModels?: string[] | undefined;
-        /** Per-run worktree-isolation override; undefined → env default. */
-        worktrees?: boolean | undefined;
-    }) => Promise<{
-        runId: string;
-    }>;
-}
-/**
- * SddWizardWebSocketHandler — drives the interactive "New SDD Project" wizard
- * (goal → Q&A → spec → task graph → start run) over WebSocket. Shared by both
- * webui servers; server-specific construction (agent, factory) is injected via
- * {@link SddWizardDeps}.
- */
-declare class SddWizardWebSocketHandler {
-    private readonly deps;
-    private readonly clients;
-    private driver;
-    /** The agent's most recent question — paired with the next user answer. */
-    private lastAgentText;
-    /** Guards against overlapping interview turns (one in flight at a time). */
-    private busy;
-    constructor(deps: SddWizardDeps);
-    addClient(ws: WebSocket): void;
-    handleMessage(msg: WizardMessage): Promise<void>;
-    private onStart;
-    private onMessage;
-    private onApprove;
-    private onRunStart;
-    /** Run one interview turn against the isolated agent, then ingest + broadcast. */
-    private runTurn;
-    private snapshotMsg;
-    private broadcast;
-    private send;
-}
-
-interface SddWizardWiringOptions {
-    /** Leader agent — seeds the run's default factory + project context. */
-    agent: Agent;
-    /** Shared EventBus — the board projector emits sdd.board.snapshot on it. */
-    events: EventBus;
-    projectRoot: string;
-    /** Per-task agent factory: CLI's director-backed one, or the runtime light one. */
-    subagentFactory: AgentFactory;
-    /**
-     * Decision authority for the failure supervisor (the server's bound
-     * TOKENS.BrainArbiter). Omit to run without a supervisor (plain terminal-fail,
-     * matching a bare run) — but parity with the CLI wants it wired.
-     */
-    brain?: BrainArbiter | undefined;
-    /** Persisted-store directories (from resolveWstackPaths). */
-    paths: {
-        projectSpecs: string;
-        projectTaskGraphs: string;
-        projectSddBoards: string;
-        projectDir: string;
-    };
-}
-declare function buildSddWizardDeps(opts: SddWizardWiringOptions): SddWizardDeps;
-
-type ShellOpenTarget = 'terminal' | 'file-manager';
-interface ShellOpenRequest {
-    path: string;
-    target: ShellOpenTarget;
-}
-interface ShellOpenResult {
-    success: boolean;
-    message: string;
-}
-declare function handleShellOpen(req: ShellOpenRequest, logger: Logger): Promise<ShellOpenResult>;
-
-/**
- * Shared skills WebSocket handlers for both the standalone WebUI server
- * (`packages/webui/src/server/index.ts`) and the CLI's `--webui` embedded
- * server (`packages/cli/src/webui-server.ts`).
- *
- * These were previously inlined in BOTH servers, and the CLI copy had
- * drifted — it only wired `skills.list`, so `skills.content` /
- * `skills.export` / `skills.update` (and install/uninstall/create/edit)
- * fell through to the "Unhandled message type" warning even though the
- * SkillsPanel sends them. Extracting the full set here gives both servers
- * one source of truth. Each function handles the full request→response
- * cycle for one message type; callers drop them into their switch:
- *
- *   case 'skills.content': return handleSkillsContent(ws, skillsCtx, msg);
- *
- * The logic is a verbatim lift of the standalone's inline cases — only the
- * dependency references changed (`skillLoader`/`skillInstaller`/
- * `projectRoot` → `ctx.*`, local `send`/`errMessage` → imported helpers).
- */
-
-interface SkillsContext {
-    /** Backs skills.list/content/edit/export. Absent ⇒ feature disabled. */
-    skillLoader: SkillLoader | undefined;
-    /** Backs skills.install/uninstall/update. Absent ⇒ those ops disabled. */
-    skillInstaller: SkillInstaller | undefined;
-    /** Project root — used by skills.create to write `.wrongstack/skills/…`. */
-    projectRoot: string;
-    /** Project skills directory, normally `<project>/.wrongstack/skills`. */
-    projectSkillsDir?: string | undefined;
-    /** User-global skills directory, normally `~/.wrongstack/skills`. */
-    globalSkillsDir?: string | undefined;
-}
-/**
- * Read a single skill's body + its directory's related files + which other
- * skills reference it by name. Powers the skill detail/preview view.
- */
-declare function handleSkillsContent(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Install a skill from a git ref (`owner/repo` or URL). Optional `global`
- * installs into the user-wide skills dir instead of the project's.
- */
-declare function handleSkillsInstall(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Uninstall a skill by name. Optional `global` restricts/Targets the
- * user-wide install.
- */
-declare function handleSkillsUninstall(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Update one skill (`name`) or all installed skills (when `name` is
- * omitted). Reports per-skill updated/unchanged/error tallies.
- */
-declare function handleSkillsUpdate(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Scaffold a new project- or global-scoped skill from a name + description.
- * Writes a templated `SKILL.md` under `.wrongstack/skills/<name>/` (project)
- * or the user-wide skills dir (global).
- */
-declare function handleSkillsCreate(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Overwrite a skill's body. Refuses bundled skills (read-only) and unknown
- * names.
- */
-declare function handleSkillsEdit(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Export every readable skill as a base64-encoded zip (one folder per skill,
- * each with its `SKILL.md`). Powers the panel's "Export all" button.
- */
-declare function handleSkillsExport(ws: WebSocket, ctx: SkillsContext): Promise<void>;
-
-interface SpecsWSMessage {
-    type: string;
-    payload?: Record<string, unknown>;
-}
-/**
- * SpecsWebSocketHandler — read-only-ish browser of persisted SDD specs and their
- * task graphs, rendered as a FORGE-style dependency board (topological phase
- * columns + dependency refs). Shared by both webui servers via specs-routes.
- *
- * Message types:
- *   specs.list                       → all specs + progress
- *   specs.get { specId }             → one spec's dependency board
- *   specs.taskStatus { graphId, taskId, status } → update + rebroadcast
- */
-declare class SpecsWebSocketHandler {
-    private specStore;
-    private graphStore;
-    private clients;
-    constructor(specsDir: string, taskGraphsDir: string);
-    addClient(ws: WebSocket): void;
-    handleMessage(msg: SpecsWSMessage): Promise<void>;
-    private buildList;
-    private broadcastList;
-    private sendList;
-    private broadcastDetail;
-    private findGraphForSpec;
-    private buildDetail;
-    private updateTaskStatus;
-    private broadcast;
-    private send;
-}
-
-/**
- * Per-section context-window token estimate for the `context.debug` command.
- *
- * Uses the simple 4-chars-per-token heuristic — not exact, but close enough to
- * spot which section (system prompt, tool schemas, or message history) is
- * eating the context window. Tool schemas in particular are easy to overlook:
- * each tool ships its full JSON schema to the model every turn, so 20+ builtins
- * can cost 10-20k tokens on their own.
- *
- * Extracted from `index.ts` as a pure function so the breakdown maths can be
- * unit tested without standing up a Context/ToolRegistry.
- */
-/** 4-chars-per-token heuristic estimate for a string. */
-declare function estimateTokens(s: string): number;
-/** Stringify arbitrary content for length estimation (JSON, with fallbacks). */
-declare function stringifyContent(c: unknown): string;
-interface ToolTokenEntry {
-    name: string;
-    tokens: number;
-}
-interface MessageTokenEntry {
-    index: number;
-    role: string;
-    tokens: number;
-    preview: string;
-}
-interface ContextBreakdown {
-    total: number;
-    systemPrompt: number;
-    tools: {
-        total: number;
-        count: number;
-        breakdown: ToolTokenEntry[];
-    };
-    messages: {
-        total: number;
-        count: number;
-        breakdown: MessageTokenEntry[];
-    };
-}
-declare function messageTokens(content: unknown): number;
-declare function messagePreview(content: unknown): string;
-
-interface WorktreeManagementDeps {
-    projectRoot: string;
-    /** Board snapshot dir — powers the cross-process liveness guard on cleanup. */
-    boardsDir: string;
-}
-/**
- * WorktreeWebSocketHandler — mirrors AutoPhaseWebSocketHandler. Subscribes to
- * the shared EventBus `worktree.*` lifecycle events, keeps a live snapshot of
- * every worktree, and broadcasts:
- *   - `worktree.event` incrementally (drives the flowing activity strip)
- *   - `worktree.state`  on connect + on a 2s timer (drives swim-lanes/DAG)
- */
-declare class WorktreeWebSocketHandler {
-    private readonly events;
-    private readonly logger;
-    private readonly management?;
-    private readonly clients;
-    private readonly handles;
-    private baseBranch;
-    private broadcastInterval;
-    private readonly offs;
-    constructor(events: EventBus, logger: Logger, management?: WorktreeManagementDeps | undefined);
-    addClient(ws: WebSocket): void;
-    /** Handle worktree-panel control messages (scan / clean / per-row ops). */
-    handleMessage(msg: {
-        type: string;
-        payload?: Record<string, unknown>;
-    }): Promise<boolean>;
-    dispose(): void;
-    /** Absolute managed-worktrees root for this project. */
-    private worktreesRoot;
-    /** True iff `dir` resolves strictly inside the managed worktrees root. */
-    private underRoot;
-    /** Branches of worktrees a live in-session run currently owns. */
-    private liveActiveBranches;
-    /**
-     * Scan the disk for managed worktrees/branches NOT owned by a live in-session
-     * run and broadcast them as orphans, with whether it is safe to clean now.
-     * No-op (empty inventory) when management deps were not wired.
-     */
-    private scanAndBroadcast;
-    /**
-     * Force-remove every orphaned worktree + branch. Refused while a run is live —
-     * in this session (active handles) OR another process (the SDD board liveness
-     * guard inside cleanupStaleSddWorktrees). Best-effort; reports the outcome.
-     */
-    private cleanupOrphans;
-    /** Remove/discard ONE worktree + branch. Refused while a live run owns it. */
-    private removeOne;
-    /** Squash-merge ONE branch into base. Refused while a live run owns it. */
-    private mergeBranch;
-    /** Compact change summary for one worktree checkout. */
-    private diffOne;
-    private subscribe;
-    private upsert;
-    private patch;
-    private activity;
-    private stateMessage;
-    private broadcastState;
-    private ensureBroadcast;
-    private stopBroadcast;
-    private broadcast;
-    private send;
-}
-
-/** A hostname that refers to the local machine. */
-declare function isLoopbackHostname(hostname: string): boolean;
-/** True when the server is bound to a loopback interface (vs. LAN/0.0.0.0). */
-declare function isLoopbackBind(wsHost: string): boolean;
-/**
- * Constant-time comparison of a provided token against the expected one.
- * A length mismatch short-circuits (lengths aren't secret); equal-length
- * inputs are compared with `timingSafeEqual` so the token can't be recovered
- * byte-by-byte via response timing.
- */
-declare function tokenMatches(provided: string | undefined, expected: string): boolean;
-/** Pull the `token` query param out of a request URL (`/?token=…`). */
-declare function extractToken(url: string): string | undefined;
-/**
- * DNS-rebinding defense. On a loopback bind, the `Host` header must resolve to
- * a loopback name. When the operator deliberately exposes the socket (wsHost is
- * a LAN/0.0.0.0 address) the Host is legitimately non-loopback, so the guard is
- * skipped and connection auth falls to the token check.
- */
-declare function hostHeaderOk(input: {
-    hostHeader: string | undefined;
-    wsHost: string;
-    allowedHostnames?: readonly string[] | undefined;
-}): boolean;
-interface VerifyClientInput {
-    /** Browser `Origin` header, or undefined for non-browser clients. */
-    origin?: string | undefined;
-    /** Request URL (`req.url`) — carries the `?token=…` query param. */
-    url: string;
-    /** `Host` header (`req.headers.host`). */
-    hostHeader?: string | undefined;
-    /** Peer address (`req.socket.remoteAddress`). */
-    remoteAddress?: string | undefined;
-    /** `Cookie` header (`req.headers.cookie`). Carries `ws_token=…` when the
-     *  browser went through `/ws-auth` to set the HttpOnly auth cookie. */
-    cookieHeader?: string | string[] | undefined;
-    /** Host/interface the WS server is bound to. */
-    wsHost: string;
-    /** The server's generated auth token. */
-    expectedToken: string;
-    /** Force token auth even for loopback binds, useful behind public tunnels. */
-    requireToken?: boolean | undefined;
-    /** Extra Host header names allowed on loopback binds, e.g. a tunnel hostname. */
-    allowedHostnames?: readonly string[] | undefined;
-    /** Allow browser WS URL tokens for explicit public WS URLs where cookies cannot cross hostnames. */
-    allowBrowserUrlToken?: boolean | undefined;
-}
-/**
- * Decide whether to accept an incoming WebSocket handshake. Pure mirror of the
- * closure previously inlined in `index.ts`; see the module doc for the layered
- * policy. Returns `true` to accept, `false` to reject.
- *
- * Token sources, in priority order:
- *  1. `Cookie: ws_token=…` (browser clients that went through `/ws-auth`)
- *  2. `?token=…` URL query param (non-browser clients: curl, scripts)
- *
- * Browser clients (with an `Origin` header) are restricted to the cookie path —
- * URL token is rejected for them, closing the C-598 query-string token
- * exposure class. Non-browser clients keep the URL-token fallback so curl
- * and tests continue to work.
- */
-declare function verifyClient(input: VerifyClientInput): boolean;
-
-declare function startWebUI(opts?: WebUIOptions & {
-    wsPort?: number | undefined;
-    wsHost?: string | undefined;
-    httpPort?: number | undefined;
-    accessToken?: string | undefined;
-    publicUrl?: string | undefined;
-    publicWsUrl?: string | undefined;
-    requireToken?: boolean | undefined;
-    open?: boolean | undefined;
-}): Promise<void>;
-
-export { AutoPhaseWebSocketHandler, type BackendServices, type CompletionHandlerOptions, type CompletionItemKind, type CompletionSuggestion, type ConnectedClient, type ContextBreakdown, type CreateHttpServerOptions, type CustomContextMode, type CustomModeStore, type DesignContext, type EternalBroadcast, type EternalSubscribe, type EternalSubscription, type KeyOpResult, type LspCompletionSource, type LspCompletionSourceRequest, type MessageTokenEntry, type PromptsContext, type ProvidersRecord, SddBoardWebSocketHandler, type SddWizardDeps, SddWizardWebSocketHandler, type SddWizardWiringOptions, type ShellOpenRequest, type ShellOpenResult, type ShellOpenTarget, type SkillsContext, SpecsWebSocketHandler, type ToolTokenEntry, type VerifyClientInput, type WSClientMessage, type WSServerMessage, type WebUIInstanceRecord, type WebUIOptions, WorktreeWebSocketHandler, addProvider, broadcast, browserOpenCommand, buildCspHeader, buildSddWizardDeps, buildWebUIAccessUrl, createCustomModeStore, createEternalSubscription, createHttpServer, createProviderConfigIO, createToolLspCompletionSource, defaultBaseDir, deleteKey, envFlag, errMessage, estimateTokens, extractToken, findFreePort, formatInstances, generateAuthToken, handleCompletionRequest, handleDesignList, handleDesignMaterialize, handleDesignSet, handleDesignState, handleDesignUse, handleDesignVerify, handleFilesList, handleFilesRead, handleFilesTree, handleFilesWrite, handleGitChanges, handleGitDiff, handleGitInfo, handleMcpAdd, handleMcpDisable, handleMcpDiscover, handleMcpEnable, handleMcpList, handleMcpRemove, handleMcpRestart, handleMcpSleep, handleMcpUpdate, handleMcpWake, handleMemoryForget, handleMemoryList, handleMemoryRemember, handlePromptsContent, handlePromptsCreate, handlePromptsFavorite, handlePromptsList, handlePromptsRecent, handlePromptsSearch, handlePromptsUsed, handleShellOpen, handleSkillsContent, handleSkillsCreate, handleSkillsEdit, handleSkillsExport, handleSkillsInstall, handleSkillsUninstall, handleSkillsUpdate, hostForBrowserUrl, hostHeaderOk, injectWsPort, isLoopbackBind, isLoopbackHostname, isPortFree, listInstances, loadSavedProviders, maskedKey, messagePreview, messageTokens, normalizeKeys, openBrowser, registerInstance, registryPath, removeProvider, resolveAuthToken, saveProviders, send, sendResult, setActiveKey, startWebUI, stringifyContent, tokenMatches, unregisterInstance, upsertKey, verifyClient, writeKeysBack };
+export * from '@wrongstack/webui-server';