@wrongstack/webui 0.275.0 → 0.276.2

package/dist/server/index.d.ts

@@ -1,9 +1,214 @@
 import { WebSocket } from 'ws';
-import { Agent, EventBus, SessionStore, ToolRegistry, ModelsRegistry, ConfigStore, SecretVault, JournalEntry, Logger, Provider, Tool, Context, MemoryStore, ProviderConfig, ProviderApiKey, SddInterviewDriver, AgentFactory, BrainArbiter, SkillLoader, PromptLoader, PromptUsageStore } from '@wrongstack/core';
+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;
@@ -92,53 +297,144 @@ interface ConnectedClient {
     connId: string;
 }
 
-/** Metrics for the file watcher that watches status.json files. */
-interface FileWatcherMetrics {
-    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;
+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;
 
-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
+/**
+ * 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 {
+    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
@@ -180,231 +476,163 @@ declare function buildCspHeader(wsPort: number, requestHost?: string | undefined
 declare function createHttpServer(opts: CreateHttpServerOptions): http.Server;
 
 /**
- * Free-port discovery for the standalone WebUI server.
+ * Running-instance registry 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.
+ * 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.
  *
- * 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.
+ * 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()`.
  */
-/** 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;
+/** 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;
 /**
- * Find the first free port at or above `startPort` on `host`, skipping any in
- * `exclude`. Throws if nothing is free within `maxTries` steps.
+ * 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 findFreePort(host: string, startPort: number, opts?: FindFreePortOptions): Promise<number>;
+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;
 
 /**
- * Best-effort "open this URL in the default browser" for `--webui --open`.
+ * MCP management handlers for the WebUI server (both the standalone
+ * `wstackui` server and the CLI's embedded `--webui` server).
  *
- * 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.
+ * 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.
  */
-/** 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;
 
-interface WorktreeManagementDeps {
-    projectRoot: string;
-    /** Board snapshot dir — powers the cross-process liveness guard on cleanup. */
-    boardsDir: string;
-}
+/** 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>;
+
 /**
- * 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)
+ * 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);
  */
-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;
-}
 
 /**
- * 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.
+ * 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`.
  *
- * Extracted from `index.ts` as a pure function so the breakdown maths can be
- * unit tested without standing up a Context/ToolRegistry.
+ * 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.
  */
-/** 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;
+/** 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;
 
 /**
- * Running-instance registry for the standalone WebUI server.
+ * Free-port discovery 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.
+ * 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.
  *
- * 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()`.
+ * 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.
  */
-/** 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;
+/** 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;
 }
-/** 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.
+ * 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 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;
-
-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;
-
-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>;
+declare function findFreePort(host: string, startPort: number, opts?: FindFreePortOptions): Promise<number>;
 
 /**
  * Send a JSON message to a single WebSocket client.
@@ -443,290 +671,65 @@ declare function buildWebUIAccessUrl(opts: {
 declare function envFlag(name: string): boolean;
 
 /**
- * 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>;
-
-/**
- * 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;
-
-/**
- * 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>;
-
-/**
- * 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>;
-
-/**
- * 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>;
-
-/**
- * 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[];
+ * 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 createCustomModeStore(wrongstackDir: string): CustomModeStore;
+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];
 
-/** 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.
+ * 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 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;
+declare function loadSavedProviders(configPath: string, vault: SecretVault): Promise<Record<string, ProviderConfig>>;
 /**
- * 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.
+ * 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 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;
-}
+declare function saveProviders(configPath: string, vault: SecretVault, providers: Record<string, ProviderConfig>): Promise<void>;
 /**
- * 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.
+ * 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 verifyClient(input: VerifyClientInput): boolean;
+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
@@ -781,147 +784,6 @@ declare function addProvider(providers: ProvidersRecord, payload: {
 /** Remove an entire provider and all its keys. */
 declare function removeProvider(providers: ProvidersRecord, providerId: string): KeyOpResult;
 
-/**
- * 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>;
-};
-
-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;
-}
-
-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;
-}
-
 interface SddBoardWSMessage {
     type: string;
     payload?: Record<string, unknown>;
@@ -1061,7 +923,18 @@ interface SddWizardWiringOptions {
         projectDir: string;
     };
 }
-declare function buildSddWizardDeps(opts: SddWizardWiringOptions): SddWizardDeps;
+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
@@ -1128,81 +1001,208 @@ declare function handleSkillsEdit(ws: WebSocket, ctx: SkillsContext, msg: unknow
  */
 declare function handleSkillsExport(ws: WebSocket, ctx: SkillsContext): Promise<void>;
 
+interface SpecsWSMessage {
+    type: string;
+    payload?: Record<string, unknown>;
+}
 /**
- * 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);
+ * 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.
  *
- * 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.
+ * Message types:
+ *   specs.list                       → all specs + progress
+ *   specs.get { specId }             → one spec's dependency board
+ *   specs.taskStatus { graphId, taskId, status } → update + rebroadcast
  */
-
-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 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;
 }
-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];
 
 /**
- * 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).
+ * Per-section context-window token estimate for the `context.debug` command.
  *
- *   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);
+ * 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.
  *
- * 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.
+ * 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 DesignContext {
+interface WorktreeManagementDeps {
     projectRoot: string;
-    /** Live agent context whose `meta.designStudio` we read/pin. Optional. */
-    agentMeta?: {
-        meta: Record<string, unknown>;
-    } | undefined;
+    /** Board snapshot dir — powers the cross-process liveness guard on cleanup. */
+    boardsDir: string;
 }
-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>;
+/**
+ * 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;