@grackle-ai/server 0.74.1 → 0.75.0

package/dist/ws-bridge.js

@@ -1,37 +1,22 @@
 import { WebSocketServer, WebSocket } from "ws";
 import { create } from "@bufbuild/protobuf";
-import { grackle, powerline } from "@grackle-ai/common";
-import { envRegistry, sessionStore, tokenStore, credentialProviders, workspaceStore, taskStore, findingStore, personaStore, settingsStore, isAllowedSettingKey, grackleHome, safeParseJsonArray, slugify } from "@grackle-ai/database";
+import { powerline } from "@grackle-ai/common";
+import { envRegistry, sessionStore, workspaceStore, taskStore, grackleHome } from "@grackle-ai/database";
 import * as adapterManager from "./adapter-manager.js";
 import { reconnectOrProvision, } from "@grackle-ai/adapter-sdk";
 import * as streamHub from "./stream-hub.js";
 import * as tokenPush from "./token-push.js";
 import { v4 as uuid } from "uuid";
 import { join } from "node:path";
-import { LOGS_DIR, SESSION_STATUS, TERMINAL_SESSION_STATUSES, END_REASON, TASK_STATUS, DEFAULT_MCP_PORT, ROOT_TASK_ID, eventTypeToString, } from "@grackle-ai/common";
+import { LOGS_DIR, DEFAULT_MCP_PORT, ROOT_TASK_ID, eventTypeToString, } from "@grackle-ai/common";
 import { resolvePersona, fetchOrchestratorContext, SystemPromptBuilder, buildTaskPrompt } from "@grackle-ai/prompt";
-import * as logWriter from "./log-writer.js";
 import { logger } from "./logger.js";
 import { processEventStream } from "./event-processor.js";
-import * as processorRegistry from "./processor-registry.js";
-import { setWssInstance, envRowToWs } from "./ws-broadcast.js";
+import { setWssInstance } from "./ws-broadcast.js";
 import { emit } from "./event-bus.js";
 import { recoverSuspendedSessions } from "./session-recovery.js";
-import { clearReconnectState } from "./auto-reconnect.js";
 import { buildMcpServersJson, toDialableHost } from "./grpc-service.js";
 import { createScopedToken, loadOrCreateApiKey } from "@grackle-ai/auth";
-import { getKnowledgeEmbedder, isKnowledgeEnabled } from "./knowledge-init.js";
-import { knowledgeSearch, getNode as getKnowledgeNodeById, expandNode, listRecentNodes, } from "@grackle-ai/knowledge";
-import { cleanupLifecycleStream } from "./lifecycle.js";
-import * as streamRegistry from "./stream-registry.js";
-import { reanimateAgent } from "./reanimate-agent.js";
-import { ConnectError } from "@connectrpc/connect";
-import { computeTaskStatus } from "./compute-task-status.js";
-import { exec } from "./utils/exec.js";
-import { formatGhError } from "./utils/format-gh-error.js";
-const GH_CODESPACE_LIST_TIMEOUT_MS = 30_000;
-const GH_CODESPACE_CREATE_TIMEOUT_MS = 300_000;
-const GH_CODESPACE_LIST_LIMIT = 50;
 const WS_PING_INTERVAL_MS = 30_000;
 const WS_CLOSE_UNAUTHORIZED = 4001;
 const WS_CLOSE_FORBIDDEN_ORIGIN = 4003;
@@ -39,15 +24,17 @@ const WS_CLOSE_FORBIDDEN_ORIGIN = 4003;
 const LOOPBACK_HOSTNAMES = new Set([
     "localhost",
     "127.0.0.1",
+    "::1",
     "[::1]",
 ]);
 /**
- * Check whether a WebSocket connection's Origin header is acceptable.
+ * Check whether a WebSocket Origin header is allowed.
  *
- * - If no Origin is present (CLI/SDK clients), the connection is allowed.
- * - If Origin is present, it must target the expected web port.
- * - In local mode the Origin hostname must be a loopback address.
- * - In network mode (`--allow-network`) any hostname on the correct port is accepted.
+ * Rules:
+ * - Missing origin (non-browser clients, extensions) → always allowed
+ * - Origin port must match the web server port
+ * - In local mode (`allowNetwork === false`), hostname must be loopback
+ * - In network mode (`allowNetwork === true`), any hostname on the right port is allowed
  */
 export function isAllowedOrigin(origin, webPort, allowNetwork) {
     if (origin === undefined) {
@@ -71,13 +58,13 @@ export function isAllowedOrigin(origin, webPort, allowNetwork) {
     }
     return LOOPBACK_HOSTNAMES.has(parsed.hostname);
 }
-/** Create a WebSocket server on top of an HTTP server that bridges JSON messages to gRPC operations. */
+/** Create a WebSocket server on top of an HTTP server for real-time event streaming. */
 export function createWsBridge(httpServer, options) {
     const wss = new WebSocketServer({ server: httpServer });
     setWssInstance(wss);
     wss.on("connection", (ws, req) => {
         const origin = req.headers.origin;
-        if (!isAllowedOrigin(origin, options.webPort, options.allowNetwork)) {
+        if (!isAllowedOrigin(origin, options.webPort ?? 0, options.allowNetwork ?? false)) {
             logger.warn({ origin }, "Rejected WebSocket connection from disallowed origin");
             ws.close(WS_CLOSE_FORBIDDEN_ORIGIN, "Forbidden origin");
             return;
@@ -313,99 +300,8 @@ export async function startTaskSession(ws, task, options) {
     });
     return undefined;
 }
-/**
- * Terminate a session: set STOPPED+killed, then close lifecycle FDs.
- *
- * Sets the session to STOPPED+killed first, then deletes the lifecycle
- * stream. The orphan callback still sends the PowerLine kill request
- * (even for already-terminal sessions) to ensure the process is stopped.
- */
-async function terminateSession(sessionId) {
-    const session = sessionStore.getSession(sessionId);
-    if (!session) {
-        return;
-    }
-    // 1. Set STOPPED + killed BEFORE closing the lifecycle FD so the orphan
-    //    callback sees the session is already terminal and skips.
-    if (!TERMINAL_SESSION_STATUSES.has(session.status)) {
-        sessionStore.updateSession(sessionId, SESSION_STATUS.STOPPED, undefined, undefined, END_REASON.KILLED);
-        streamHub.publish(create(grackle.SessionEventSchema, {
-            sessionId,
-            type: grackle.EventType.STATUS,
-            timestamp: new Date().toISOString(),
-            content: END_REASON.KILLED,
-            raw: "",
-        }));
-        if (session.taskId) {
-            const task = taskStore.getTask(session.taskId);
-            if (task) {
-                emit("task.updated", { taskId: task.id, workspaceId: task.workspaceId || "" });
-            }
-        }
-    }
-    // 2. Delete lifecycle stream — orphan callback sees session is already
-    //    STOPPED and skips status change, but still kills the PowerLine process.
-    cleanupLifecycleStream(sessionId);
-    // 3. Close other subscriptions (pipe streams etc.)
-    const subs = streamRegistry.getSubscriptionsForSession(sessionId);
-    for (const sub of subs) {
-        streamRegistry.unsubscribe(sub.id);
-    }
-}
 async function handleMessage(ws, msg, subscriptions) {
     switch (msg.type) {
-        case "list_environments": {
-            const rows = envRegistry.listEnvironments();
-            sendWs(ws, {
-                type: "environments",
-                payload: { environments: rows.map(envRowToWs) },
-            });
-            break;
-        }
-        case "list_sessions": {
-            const environmentId = msg.payload?.environmentId || "";
-            const status = msg.payload?.status || "";
-            const rows = sessionStore.listSessions(environmentId, status);
-            sendWs(ws, {
-                type: "sessions",
-                payload: {
-                    sessions: rows.map((r) => ({
-                        id: r.id,
-                        environmentId: r.environmentId,
-                        runtime: r.runtime,
-                        status: r.status,
-                        prompt: r.prompt,
-                        startedAt: r.startedAt,
-                        personaId: r.personaId,
-                        inputTokens: r.inputTokens,
-                        outputTokens: r.outputTokens,
-                        costUsd: r.costUsd,
-                        endReason: r.endReason || undefined,
-                    })),
-                },
-            });
-            break;
-        }
-        case "get_session_events": {
-            const sessionId = msg.payload?.sessionId;
-            if (!sessionId) {
-                return;
-            }
-            const session = sessionStore.getSession(sessionId);
-            if (!session?.logPath) {
-                return;
-            }
-            const entries = logWriter.readLog(session.logPath);
-            const events = entries.map((e) => ({
-                sessionId: e.session_id,
-                eventType: e.type,
-                timestamp: e.timestamp,
-                content: e.content,
-                raw: e.raw || undefined,
-            }));
-            sendWs(ws, { type: "session_events", payload: { sessionId, events } });
-            break;
-        }
         case "subscribe": {
             const sessionId = msg.payload?.sessionId;
             if (!sessionId) {
@@ -463,1429 +359,10 @@ async function handleMessage(ws, msg, subscriptions) {
             })();
             break;
         }
-        case "spawn": {
-            const environmentId = msg.payload?.environmentId;
-            const prompt = msg.payload?.prompt;
-            const branch = msg.payload?.branch || "";
-            const systemContext = msg.payload?.systemContext || "";
-            const spawnPersonaId = msg.payload?.personaId || "";
-            if (!environmentId || !prompt) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "environmentId and prompt required" },
-                });
-                return;
-            }
-            // Resolve persona via cascade (request → app default)
-            let resolved;
-            try {
-                resolved = resolvePersona(spawnPersonaId);
-            }
-            catch (err) {
-                sendWs(ws, { type: "error", payload: { message: err.message } });
-                return;
-            }
-            const env = envRegistry.getEnvironment(environmentId);
-            if (!env) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Environment not found: ${environmentId}` },
-                });
-                return;
-            }
-            // Auto-provision the environment if not already connected
-            const conn = await autoProvisionEnvironment(ws, environmentId, env, {});
-            if (!conn) {
-                return;
-            }
-            const sessionId = uuid();
-            const { runtime: sessionRuntime, model: sessionModel, maxTurns, systemPrompt: spawnSystemPrompt } = resolved;
-            const logPath = join(grackleHome, LOGS_DIR, sessionId);
-            const builderPrompt = new SystemPromptBuilder({
-                personaPrompt: spawnSystemPrompt,
-            }).build();
-            const finalSystemContext = systemContext
-                ? builderPrompt + "\n\n" + systemContext
-                : builderPrompt;
-            sessionStore.createSession(sessionId, environmentId, sessionRuntime, prompt, sessionModel, logPath);
-            sendWs(ws, { type: "spawned", payload: { sessionId } });
-            const powerlineReq = create(powerline.SpawnRequestSchema, {
-                sessionId,
-                runtime: sessionRuntime,
-                prompt,
-                model: sessionModel,
-                maxTurns,
-                branch,
-                worktreeBasePath: branch
-                    ? ((typeof msg.payload?.worktreeBasePath === "string" ? msg.payload.worktreeBasePath.trim() : "") || process.env.GRACKLE_WORKTREE_BASE || "/workspace")
-                    : "",
-                systemContext: finalSystemContext,
-            });
-            processEventStream(conn.client.spawn(powerlineReq), {
-                sessionId,
-                logPath,
-                systemContext: finalSystemContext,
-                prompt,
-            });
-            break;
-        }
-        case "send_input": {
-            const sessionId = msg.payload?.sessionId;
-            const text = msg.payload?.text;
-            if (!sessionId || !text) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "sessionId and text required" },
-                });
-                return;
-            }
-            const session = sessionStore.getSession(sessionId);
-            if (!session) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Session not found: ${sessionId}` },
-                });
-                return;
-            }
-            if (TERMINAL_SESSION_STATUSES.has(session.status)) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: {
-                        message: `Session ${sessionId} has ended (status: ${session.status})`,
-                    },
-                });
-                return;
-            }
-            const conn = adapterManager.getConnection(session.environmentId);
-            if (!conn) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: {
-                        message: `Environment ${session.environmentId} is not connected`,
-                    },
-                });
-                return;
-            }
-            // Record the user's input as a session event before forwarding to the agent
-            const userInputEvent = create(grackle.SessionEventSchema, {
-                sessionId,
-                type: grackle.EventType.USER_INPUT,
-                timestamp: new Date().toISOString(),
-                content: text,
-            });
-            if (session.logPath) {
-                logWriter.writeEvent(session.logPath, userInputEvent);
-            }
-            streamHub.publish(userInputEvent);
-            try {
-                await conn.client.sendInput(create(powerline.InputMessageSchema, { sessionId, text }));
-            }
-            catch (err) {
-                const errMessage = err instanceof Error ? err.message : String(err);
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Failed to send input: ${errMessage}` },
-                });
-            }
-            break;
-        }
-        case "kill": {
-            const sessionId = msg.payload?.sessionId;
-            if (!sessionId) {
-                return;
-            }
-            await terminateSession(sessionId);
-            break;
-        }
-        case "stop_task": {
-            const taskId = msg.payload?.taskId;
-            if (!taskId)
-                return;
-            if (taskId === ROOT_TASK_ID) {
-                sendWs(ws, { type: "error", payload: { message: "Cannot stop the system task" } });
-                return;
-            }
-            // Terminate all active sessions for this task via fd closure
-            const activeSessions = sessionStore.getActiveSessionsForTask(taskId);
-            for (const session of activeSessions) {
-                await terminateSession(session.id);
-            }
-            // Mark task complete (same as "complete_task" handler)
-            taskStore.markTaskComplete(taskId, TASK_STATUS.COMPLETE);
-            const stoppedTask = taskStore.getTask(taskId);
-            const unblocked = stoppedTask?.workspaceId ? taskStore.checkAndUnblock(stoppedTask.workspaceId) : [];
-            sendWs(ws, {
-                type: "task_completed",
-                payload: {
-                    taskId,
-                    unblockedTaskIds: unblocked.map((t) => t.id),
-                },
-            });
-            if (stoppedTask) {
-                emit("task.completed", { taskId, workspaceId: stoppedTask.workspaceId || "" });
-            }
-            break;
-        }
-        case "resume_agent": {
-            const resumeSessionId = msg.payload?.sessionId;
-            if (!resumeSessionId) {
-                sendWs(ws, { type: "error", payload: { message: "sessionId required" } });
-                return;
-            }
-            try {
-                reanimateAgent(resumeSessionId);
-                sendWs(ws, { type: "agent_resumed", payload: { sessionId: resumeSessionId } });
-            }
-            catch (err) {
-                const message = err instanceof ConnectError ? err.message : String(err);
-                sendWs(ws, { type: "error", payload: { message } });
-            }
-            break;
-        }
-        // ─── Workspaces ────────────────────────────────────────
-        case "list_workspaces": {
-            const filterEnvironmentId = msg.payload?.environmentId || undefined;
-            const rows = workspaceStore.listWorkspaces(filterEnvironmentId);
-            sendWs(ws, {
-                type: "workspaces",
-                payload: {
-                    workspaces: rows.map((r) => ({
-                        id: r.id,
-                        name: r.name,
-                        description: r.description,
-                        repoUrl: r.repoUrl,
-                        environmentId: r.environmentId,
-                        defaultPersonaId: r.defaultPersonaId,
-                        status: r.status,
-                        useWorktrees: r.useWorktrees,
-                        worktreeBasePath: r.worktreeBasePath,
-                        createdAt: r.createdAt,
-                        updatedAt: r.updatedAt,
-                    })),
-                },
-            });
-            break;
-        }
-        case "create_workspace": {
-            const name = msg.payload?.name;
-            const requestId = typeof msg.payload?.requestId === "string"
-                ? msg.payload.requestId
-                : "";
-            if (!name) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "name required", requestId },
-                });
-                return;
-            }
-            const createEnvironmentId = msg.payload?.environmentId || "";
-            if (!createEnvironmentId) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "environmentId required", requestId },
-                });
-                return;
-            }
-            if (!envRegistry.getEnvironment(createEnvironmentId)) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Environment not found: ${createEnvironmentId}`, requestId },
-                });
-                return;
-            }
-            const baseWorkspaceId = slugify(name) || uuid().slice(0, 8);
-            let id = baseWorkspaceId;
-            for (let attempt = 0; attempt < 10 && workspaceStore.getWorkspace(id); attempt++) {
-                id = `${baseWorkspaceId}-${uuid().slice(0, 4)}`;
-            }
-            if (workspaceStore.getWorkspace(id)) {
-                id = uuid();
-            }
-            // useWorktrees defaults to true when not specified
-            const createUseWorktrees = msg.payload?.useWorktrees ?? true;
-            try {
-                workspaceStore.createWorkspace(id, name, msg.payload?.description || "", msg.payload?.repoUrl || "", createEnvironmentId, createUseWorktrees, typeof msg.payload?.worktreeBasePath === "string" ? msg.payload.worktreeBasePath.trim() : "", msg.payload?.defaultPersonaId || "");
-                emit("workspace.created", { workspaceId: id, requestId });
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : "Failed to create workspace";
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message, requestId },
-                });
-            }
-            break;
-        }
-        case "archive_workspace": {
-            const workspaceId = msg.payload?.workspaceId;
-            if (workspaceId) {
-                workspaceStore.archiveWorkspace(workspaceId);
-            }
-            emit("workspace.archived", { workspaceId });
-            break;
-        }
-        case "update_workspace": {
-            const workspaceId = msg.payload?.workspaceId;
-            if (!workspaceId) {
-                sendWs(ws, { type: "error", payload: { message: "workspaceId required" } });
-                return;
-            }
-            const existing = workspaceStore.getWorkspace(workspaceId);
-            if (!existing) {
-                sendWs(ws, { type: "error", payload: { message: `Workspace not found: ${workspaceId}` } });
-                return;
-            }
-            const nameVal = typeof msg.payload?.name === "string" ? msg.payload.name : undefined;
-            if (nameVal?.trim() === "") {
-                sendWs(ws, { type: "error", payload: { message: "Workspace name cannot be empty" } });
-                return;
-            }
-            const descVal = typeof msg.payload?.description === "string" ? msg.payload.description : undefined;
-            const repoVal = typeof msg.payload?.repoUrl === "string" ? msg.payload.repoUrl : undefined;
-            const envVal = typeof msg.payload?.environmentId === "string" ? msg.payload.environmentId : undefined;
-            if (repoVal !== undefined && repoVal !== "" && !/^https?:\/\//i.test(repoVal)) {
-                sendWs(ws, { type: "error", payload: { message: "Repository URL must use http or https scheme" } });
-                return;
-            }
-            if (envVal !== undefined && !envRegistry.getEnvironment(envVal)) {
-                sendWs(ws, { type: "error", payload: { message: `Environment not found: ${envVal}` } });
-                return;
-            }
-            const worktreesVal = typeof msg.payload?.useWorktrees === "boolean" ? msg.payload.useWorktrees : undefined;
-            const worktreeBasePathVal = typeof msg.payload?.worktreeBasePath === "string" ? msg.payload.worktreeBasePath : undefined;
-            const defaultPersonaIdVal = typeof msg.payload?.defaultPersonaId === "string" ? msg.payload.defaultPersonaId : undefined;
-            workspaceStore.updateWorkspace(workspaceId, {
-                name: nameVal !== undefined ? nameVal.trim() : undefined,
-                description: descVal,
-                repoUrl: repoVal,
-                environmentId: envVal,
-                useWorktrees: worktreesVal,
-                worktreeBasePath: worktreeBasePathVal,
-                defaultPersonaId: defaultPersonaIdVal,
-            });
-            emit("workspace.updated", { workspaceId });
-            break;
-        }
-        // ─── Personas ──────────────────────────────────────────
-        case "list_personas": {
-            const rows = personaStore.listPersonas();
-            sendWs(ws, {
-                type: "personas",
-                payload: {
-                    personas: rows.map((r) => ({
-                        id: r.id,
-                        name: r.name,
-                        description: r.description,
-                        systemPrompt: r.systemPrompt,
-                        toolConfig: r.toolConfig,
-                        runtime: r.runtime,
-                        model: r.model,
-                        maxTurns: r.maxTurns,
-                        mcpServers: r.mcpServers,
-                        createdAt: r.createdAt,
-                        updatedAt: r.updatedAt,
-                        type: r.type || "agent",
-                        script: r.script || "",
-                    })),
-                },
-            });
-            break;
-        }
-        case "create_persona": {
-            const personaName = msg.payload?.name;
-            if (!personaName) {
-                sendWs(ws, { type: "error", payload: { message: "name required" } });
-                return;
-            }
-            const personaType = msg.payload?.type || "agent";
-            if (personaType !== "agent" && personaType !== "script") {
-                sendWs(ws, { type: "error", payload: { message: `Invalid persona type: "${personaType}". Must be "agent" or "script".` } });
-                return;
-            }
-            const personaSystemPrompt = msg.payload?.systemPrompt || "";
-            const personaScript = msg.payload?.script || "";
-            if (personaType === "script") {
-                if (!personaScript) {
-                    sendWs(ws, { type: "error", payload: { message: "script required for script personas" } });
-                    return;
-                }
-            }
-            else {
-                if (!personaSystemPrompt) {
-                    sendWs(ws, { type: "error", payload: { message: "systemPrompt required" } });
-                    return;
-                }
-            }
-            let personaId = slugify(personaName) || uuid().slice(0, 8);
-            const MAX_ID_RETRIES = 10;
-            for (let i = 0; i < MAX_ID_RETRIES && personaStore.getPersona(personaId); i++) {
-                personaId = `${slugify(personaName) || "persona"}-${uuid().slice(0, 4)}`;
-            }
-            personaStore.createPersona(personaId, personaName, msg.payload?.description || "", personaSystemPrompt, msg.payload?.toolConfig || "{}", msg.payload?.runtime || "", msg.payload?.model || "", msg.payload?.maxTurns || 0, msg.payload?.mcpServers || "[]", personaType, personaScript);
-            emit("persona.created", { personaId });
-            break;
-        }
-        case "get_persona": {
-            const getPersonaId = msg.payload?.personaId;
-            if (!getPersonaId)
-                return;
-            const personaRow = personaStore.getPersona(getPersonaId);
-            if (!personaRow) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Persona not found: ${getPersonaId}` },
-                });
-                return;
-            }
-            sendWs(ws, { type: "persona", payload: { persona: personaRow } });
-            break;
-        }
-        case "update_persona": {
-            const updatePersonaId = msg.payload?.personaId;
-            if (!updatePersonaId) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "personaId required" },
-                });
-                return;
-            }
-            const existingPersona = personaStore.getPersona(updatePersonaId);
-            if (!existingPersona) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Persona not found: ${updatePersonaId}` },
-                });
-                return;
-            }
-            personaStore.updatePersona(updatePersonaId, msg.payload?.name ?? existingPersona.name, msg.payload?.description ?? existingPersona.description, msg.payload?.systemPrompt ?? existingPersona.systemPrompt, msg.payload?.toolConfig ?? existingPersona.toolConfig, msg.payload?.runtime ?? existingPersona.runtime, msg.payload?.model ?? existingPersona.model, msg.payload?.maxTurns ?? existingPersona.maxTurns, msg.payload?.mcpServers ?? existingPersona.mcpServers, msg.payload?.type ?? existingPersona.type, msg.payload?.script ?? existingPersona.script);
-            emit("persona.updated", { personaId: updatePersonaId });
-            break;
-        }
-        case "delete_persona": {
-            const deletePersonaId = msg.payload?.personaId;
-            if (!deletePersonaId)
-                return;
-            personaStore.deletePersona(deletePersonaId);
-            emit("persona.deleted", { personaId: deletePersonaId });
-            break;
-        }
-        // ─── Settings ────────────────────────────────────────────
-        case "get_setting": {
-            const key = msg.payload?.key;
-            if (typeof key !== "string" || !key)
-                return;
-            if (!isAllowedSettingKey(key)) {
-                sendWs(ws, { type: "error", payload: { message: `Setting key not allowed: ${key}` } });
-                return;
-            }
-            const value = settingsStore.getSetting(key) ?? "";
-            sendWs(ws, { type: "setting", payload: { key, value } });
-            break;
-        }
-        case "set_setting": {
-            const key = msg.payload?.key;
-            const value = msg.payload?.value || "";
-            if (typeof key !== "string" || !key)
-                return;
-            if (!isAllowedSettingKey(key)) {
-                sendWs(ws, { type: "error", payload: { message: `Setting key not allowed: ${key}` } });
-                return;
-            }
-            // Validate persona exists and has required fields when setting default_persona_id
-            if (key === "default_persona_id" && value) {
-                const persona = personaStore.getPersona(value);
-                if (!persona) {
-                    sendWs(ws, { type: "error", payload: { message: `Persona not found: ${value}` } });
-                    return;
-                }
-                if (!persona.runtime || !persona.model) {
-                    sendWs(ws, { type: "error", payload: { message: `Persona "${persona.name}" must have runtime and model configured` } });
-                    return;
-                }
-            }
-            settingsStore.setSetting(key, value);
-            emit("setting.changed", { key, value });
-            break;
-        }
-        // ─── Tasks ─────────────────────────────────────────────
-        case "list_tasks": {
-            const workspaceId = msg.payload?.workspaceId || undefined;
-            const rows = taskStore.listTasks(workspaceId, {
-                search: msg.payload?.search || undefined,
-                status: msg.payload?.status || undefined,
-            });
-            const childIdsMap = taskStore.buildChildIdsMap(rows);
-            // Batch-fetch sessions for all tasks and group by taskId
-            const taskIds = rows.map((r) => r.id);
-            const allSessions = sessionStore.listSessionsByTaskIds(taskIds);
-            const sessionsByTask = new Map();
-            for (const s of allSessions) {
-                const arr = sessionsByTask.get(s.taskId) ?? [];
-                arr.push(s);
-                sessionsByTask.set(s.taskId, arr);
-            }
-            sendWs(ws, {
-                type: "tasks",
-                payload: {
-                    workspaceId,
-                    tasks: rows.map((r) => {
-                        const taskSessions = sessionsByTask.get(r.id) ?? [];
-                        const computed = computeTaskStatus(r.status, taskSessions);
-                        return {
-                            id: r.id,
-                            workspaceId: r.workspaceId ?? undefined,
-                            title: r.title,
-                            description: r.description,
-                            status: computed.status,
-                            branch: r.branch,
-                            latestSessionId: computed.latestSessionId,
-                            dependsOn: safeParseJsonArray(r.dependsOn),
-                            sortOrder: r.sortOrder,
-                            createdAt: r.createdAt,
-                            parentTaskId: r.parentTaskId,
-                            depth: r.depth,
-                            childTaskIds: childIdsMap.get(r.id) ?? [],
-                            canDecompose: r.canDecompose,
-                            defaultPersonaId: r.defaultPersonaId,
-                        };
-                    }),
-                },
-            });
-            break;
-        }
-        case "create_task": {
-            const workspaceId = msg.payload?.workspaceId || undefined;
-            const title = msg.payload?.title;
-            const requestId = typeof msg.payload?.requestId === "string"
-                ? msg.payload.requestId
-                : "";
-            if (!title) {
-                sendWs(ws, {
-                    type: "create_task_error",
-                    payload: { message: "title required", requestId },
-                });
-                return;
-            }
-            let workspace;
-            if (workspaceId) {
-                workspace = workspaceStore.getWorkspace(workspaceId);
-                if (!workspace) {
-                    sendWs(ws, {
-                        type: "create_task_error",
-                        payload: { message: `Workspace not found: ${workspaceId}`, requestId },
-                    });
-                    return;
-                }
-            }
-            const parentTaskId = msg.payload?.parentTaskId || "";
-            const rawCanDecompose = msg.payload?.canDecompose;
-            // Default to false (no decomposition rights) unless explicitly granted.
-            // Orchestrator/root processes that need fork() must opt in via canDecompose: true.
-            const canDecompose = typeof rawCanDecompose === "boolean" ? rawCanDecompose : false;
-            try {
-                const id = uuid().slice(0, 8);
-                taskStore.createTask(id, workspaceId, title, msg.payload?.description || "", msg.payload?.dependsOn || [], workspace ? slugify(workspace.name) : "", parentTaskId, canDecompose, msg.payload?.defaultPersonaId || "");
-                emit("task.created", { taskId: id, workspaceId, requestId });
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : "Failed to create task";
-                sendWs(ws, {
-                    type: "create_task_error",
-                    payload: { message, requestId },
-                });
-            }
-            break;
-        }
-        case "update_task": {
-            const updateTaskId = msg.payload?.taskId;
-            if (!updateTaskId) {
-                sendWs(ws, { type: "error", payload: { message: "taskId required" } });
-                return;
-            }
-            const existingTask = taskStore.getTask(updateTaskId);
-            if (!existingTask) {
-                sendWs(ws, { type: "error", payload: { message: `Task not found: ${updateTaskId}` } });
-                return;
-            }
-            // Late-bind: associate a running session with this task
-            const lateBindSessionId = typeof msg.payload?.sessionId === "string" ? msg.payload.sessionId : "";
-            if (lateBindSessionId) {
-                const session = sessionStore.getSession(lateBindSessionId);
-                if (!session) {
-                    sendWs(ws, { type: "error", payload: { message: `Session not found: ${lateBindSessionId}` } });
-                    return;
-                }
-                if (TERMINAL_SESSION_STATUSES.has(session.status)) {
-                    sendWs(ws, {
-                        type: "error",
-                        payload: { message: `Cannot bind terminal session ${lateBindSessionId} (status: ${session.status})` },
-                    });
-                    return;
-                }
-                // Verify the processor exists before mutating DB state to avoid partial updates
-                if (!processorRegistry.get(lateBindSessionId)) {
-                    sendWs(ws, {
-                        type: "error",
-                        payload: { message: `No active event processor for session ${lateBindSessionId}` },
-                    });
-                    return;
-                }
-                sessionStore.setSessionTask(lateBindSessionId, updateTaskId);
-                try {
-                    processorRegistry.lateBind(lateBindSessionId, updateTaskId, existingTask.workspaceId || undefined);
-                }
-                catch (err) {
-                    sendWs(ws, { type: "error", payload: { message: String(err) } });
-                    return;
-                }
-                emit("task.started", { taskId: updateTaskId, sessionId: lateBindSessionId, workspaceId: existingTask.workspaceId || "" });
-                break;
-            }
-            // Only allow editing not_started tasks (non-late-bind path)
-            if (existingTask.status !== TASK_STATUS.NOT_STARTED) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Task ${updateTaskId} cannot be edited (status: ${existingTask.status})` },
-                });
-                return;
-            }
-            const updatedTitle = typeof msg.payload?.title === "string" && msg.payload.title.trim()
-                ? msg.payload.title.trim()
-                : existingTask.title;
-            const updatedDescription = typeof msg.payload?.description === "string"
-                ? msg.payload.description
-                : existingTask.description;
-            const updatedDependsOn = Array.isArray(msg.payload?.dependsOn)
-                ? [
-                    // Normalise: keep only non-empty strings, remove self-references and duplicates.
-                    ...new Set(msg.payload.dependsOn
-                        .filter((d) => typeof d === "string" && d.trim() !== "")
-                        .filter((d) => d !== updateTaskId)),
-                ]
-                : safeParseJsonArray(existingTask.dependsOn);
-            const updatedDefaultPersonaId = typeof msg.payload?.defaultPersonaId === "string"
-                ? msg.payload.defaultPersonaId
-                : undefined;
-            taskStore.updateTask(updateTaskId, updatedTitle, updatedDescription, existingTask.status, updatedDependsOn, updatedDefaultPersonaId);
-            emit("task.updated", { taskId: updateTaskId, workspaceId: existingTask.workspaceId || "" });
-            break;
-        }
-        case "start_task": {
-            const taskId = msg.payload?.taskId;
-            if (!taskId)
-                return;
-            const task = taskStore.getTask(taskId);
-            if (!task) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Task not found: ${taskId}` },
-                });
-                return;
-            }
-            {
-                const taskSessions = sessionStore.listSessionsForTask(taskId);
-                const { status: effectiveStatus } = computeTaskStatus(task.status, taskSessions);
-                if (taskId === ROOT_TASK_ID) {
-                    // Root task is always re-startable unless actively working
-                    if (effectiveStatus === TASK_STATUS.WORKING) {
-                        sendWs(ws, {
-                            type: "error",
-                            payload: { message: "System is already running" },
-                        });
-                        return;
-                    }
-                }
-                else if (![TASK_STATUS.NOT_STARTED, TASK_STATUS.FAILED].includes(effectiveStatus)) {
-                    sendWs(ws, {
-                        type: "error",
-                        payload: {
-                            message: `Task cannot be started (status: ${effectiveStatus})`,
-                        },
-                    });
-                    return;
-                }
-            }
-            if (!taskStore.areDependenciesMet(taskId)) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "Task has unmet dependencies" },
-                });
-                return;
-            }
-            const startError = await startTaskSession(ws, task, {
-                personaId: msg.payload?.personaId || undefined,
-                environmentId: msg.payload?.environmentId || undefined,
-                notes: msg.payload?.notes || undefined,
-            });
-            if (startError) {
-                sendWs(ws, { type: "error", payload: { message: startError } });
-            }
+        default:
+            // ignore unknown messages
             break;
-        }
-        case "complete_task": {
-            const taskId = msg.payload?.taskId;
-            if (!taskId)
-                return;
-            if (taskId === ROOT_TASK_ID) {
-                sendWs(ws, { type: "error", payload: { message: "Cannot complete the system task" } });
-                return;
-            }
-            taskStore.markTaskComplete(taskId, TASK_STATUS.COMPLETE);
-            const task = taskStore.getTask(taskId);
-            const unblocked = task?.workspaceId ? taskStore.checkAndUnblock(task.workspaceId) : [];
-            sendWs(ws, {
-                type: "task_completed",
-                payload: {
-                    taskId,
-                    unblockedTaskIds: unblocked.map((t) => t.id),
-                },
-            });
-            if (task) {
-                emit("task.completed", { taskId, workspaceId: task.workspaceId || "" });
-            }
-            break;
-        }
-        case "resume_task": {
-            const taskId = msg.payload?.taskId;
-            if (!taskId)
-                return;
-            const task = taskStore.getTask(taskId);
-            if (!task) {
-                sendWs(ws, { type: "error", payload: { message: `Task not found: ${taskId}` } });
-                return;
-            }
-            const latestSession = sessionStore.getLatestSessionForTask(taskId);
-            if (!latestSession) {
-                sendWs(ws, { type: "error", payload: { message: `Task ${taskId} has no sessions to resume` } });
-                return;
-            }
-            if (![SESSION_STATUS.STOPPED, SESSION_STATUS.SUSPENDED].includes(latestSession.status)) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Latest session ${latestSession.id} is not resumable (status: ${latestSession.status})` },
-                });
-                return;
-            }
-            if (!latestSession.runtimeSessionId) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Latest session ${latestSession.id} has no runtime session ID — cannot resume` },
-                });
-                return;
-            }
-            const env = envRegistry.getEnvironment(latestSession.environmentId);
-            if (!env) {
-                sendWs(ws, { type: "error", payload: { message: `Environment not found: ${latestSession.environmentId}` } });
-                return;
-            }
-            const conn = await autoProvisionEnvironment(ws, latestSession.environmentId, env, { taskId });
-            if (!conn) {
-                return;
-            }
-            const powerlineReq = create(powerline.ResumeRequestSchema, {
-                sessionId: latestSession.id,
-                runtimeSessionId: latestSession.runtimeSessionId,
-                runtime: latestSession.runtime,
-            });
-            const logPath = latestSession.logPath || join(grackleHome, LOGS_DIR, latestSession.id);
-            processEventStream(conn.client.resume(powerlineReq), {
-                sessionId: latestSession.id,
-                logPath,
-                workspaceId: task.workspaceId ?? undefined,
-                taskId: task.id,
-            });
-            emit("task.started", { taskId: task.id, sessionId: latestSession.id, workspaceId: task.workspaceId || "" });
-            break;
-        }
-        case "delete_task": {
-            const taskId = msg.payload?.taskId;
-            if (!taskId)
-                return;
-            if (taskId === ROOT_TASK_ID) {
-                sendWs(ws, { type: "error", payload: { message: "Cannot delete the system task" } });
-                return;
-            }
-            const deletedTask = taskStore.getTask(taskId);
-            if (!deletedTask) {
-                sendWs(ws, { type: "error", payload: { message: `Task not found: ${taskId}` } });
-                return;
-            }
-            const children = taskStore.getChildren(taskId);
-            if (children.length > 0) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: {
-                        message: "Cannot delete task with children. Delete children first.",
-                    },
-                });
-                return;
-            }
-            // Terminate all active sessions via fd closure before deleting the task
-            const deleteTaskSessions = sessionStore.getActiveSessionsForTask(taskId);
-            for (const activeSession of deleteTaskSessions) {
-                await terminateSession(activeSession.id);
-            }
-            const changes = taskStore.deleteTask(taskId);
-            if (changes === 0) {
-                logger.error({ taskId }, "deleteTask returned 0 changes despite task existing");
-                sendWs(ws, { type: "error", payload: { message: `Failed to delete task ${taskId}: no rows affected` } });
-                return;
-            }
-            emit("task.deleted", { taskId, workspaceId: deletedTask.workspaceId || "" });
-            break;
-        }
-        // ─── Task Sessions ─────────────────────────────────────
-        case "get_task_sessions": {
-            const taskId = msg.payload?.taskId;
-            if (typeof taskId !== "string" || taskId.length === 0) {
-                return;
-            }
-            const taskSessions = sessionStore.listSessionsForTask(taskId);
-            sendWs(ws, {
-                type: "task_sessions",
-                payload: {
-                    taskId,
-                    sessions: taskSessions.map((r) => ({
-                        id: r.id,
-                        environmentId: r.environmentId,
-                        runtime: r.runtime,
-                        status: r.status,
-                        prompt: r.prompt,
-                        startedAt: r.startedAt,
-                        endedAt: r.endedAt ?? "",
-                        error: r.error ?? "",
-                        personaId: r.personaId,
-                        inputTokens: r.inputTokens,
-                        outputTokens: r.outputTokens,
-                        costUsd: r.costUsd,
-                        endReason: r.endReason || undefined,
-                    })),
-                },
-            });
-            break;
-        }
-        // ─── Usage ────────────────────────────────────────────
-        case "get_usage": {
-            const scope = msg.payload?.scope || "";
-            const id = msg.payload?.id || "";
-            if (!id || !scope) {
-                return;
-            }
-            let usage = { inputTokens: 0, outputTokens: 0, costUsd: 0, sessionCount: 0 };
-            if (scope === "session") {
-                const s = sessionStore.getSession(id);
-                if (s) {
-                    usage = { inputTokens: s.inputTokens, outputTokens: s.outputTokens, costUsd: s.costUsd, sessionCount: 1 };
-                }
-            }
-            else if (scope === "task") {
-                usage = sessionStore.aggregateUsage({ taskId: id });
-            }
-            else if (scope === "task_tree") {
-                const descendants = taskStore.getDescendants(id);
-                usage = sessionStore.aggregateUsage({ taskIds: [id, ...descendants.map((d) => d.id)] });
-            }
-            else if (scope === "workspace") {
-                const wsTasks = taskStore.listTasks(id);
-                if (wsTasks.length > 0) {
-                    usage = sessionStore.aggregateUsage({ taskIds: wsTasks.map((t) => t.id) });
-                }
-            }
-            else if (scope === "environment") {
-                usage = sessionStore.aggregateUsage({ environmentId: id });
-            }
-            sendWs(ws, { type: "usage_stats", payload: { scope, id, ...usage } });
-            break;
-        }
-        // ─── Findings ──────────────────────────────────────────
-        case "list_findings": {
-            const workspaceId = msg.payload?.workspaceId;
-            if (!workspaceId)
-                return;
-            const rows = findingStore.queryFindings(workspaceId, msg.payload?.categories || undefined, msg.payload?.tags || undefined, msg.payload?.limit || undefined);
-            sendWs(ws, {
-                type: "findings",
-                payload: {
-                    workspaceId,
-                    findings: rows.map((r) => ({
-                        id: r.id,
-                        workspaceId: r.workspaceId,
-                        taskId: r.taskId,
-                        sessionId: r.sessionId,
-                        category: r.category,
-                        title: r.title,
-                        content: r.content,
-                        tags: safeParseJsonArray(r.tags),
-                        createdAt: r.createdAt,
-                    })),
-                },
-            });
-            break;
-        }
-        case "post_finding": {
-            const workspaceId = msg.payload?.workspaceId;
-            const title = msg.payload?.title;
-            if (!workspaceId || !title) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "workspaceId and title required" },
-                });
-                return;
-            }
-            const id = uuid().slice(0, 8);
-            findingStore.postFinding(id, workspaceId, msg.payload?.taskId || "", msg.payload?.sessionId || "", msg.payload?.category || "general", title, msg.payload?.content || "", msg.payload?.tags || []);
-            sendWs(ws, { type: "finding_posted", payload: { id, workspaceId } });
-            break;
-        }
-        case "provision_environment": {
-            const environmentId = msg.payload?.environmentId;
-            if (!environmentId) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "environmentId required" },
-                });
-                return;
-            }
-            // Manual provision overrides auto-reconnect
-            clearReconnectState(environmentId);
-            const env = envRegistry.getEnvironment(environmentId);
-            if (!env) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Environment not found: ${environmentId}` },
-                });
-                return;
-            }
-            const adapter = adapterManager.getAdapter(env.adapterType);
-            if (!adapter) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `No adapter for type: ${env.adapterType}` },
-                });
-                return;
-            }
-            logger.info({ environmentId, adapterType: env.adapterType }, "Provisioning environment");
-            envRegistry.updateEnvironmentStatus(environmentId, "connecting");
-            emit("environment.changed", {});
-            // Run provision in background, broadcasting progress to all connected clients
-            // eslint-disable-next-line @typescript-eslint/no-floating-promises
-            (async () => {
-                try {
-                    const config = safeParseAdapterConfig(env.adapterConfig, environmentId);
-                    config.defaultRuntime = env.defaultRuntime;
-                    const powerlineToken = env.powerlineToken || "";
-                    for await (const event of reconnectOrProvision(environmentId, adapter, config, powerlineToken, !!env.bootstrapped)) {
-                        logger.info({ environmentId, stage: event.stage, message: event.message }, "Provision progress");
-                        emit("environment.provision_progress", {
-                            environmentId,
-                            stage: event.stage,
-                            message: event.message,
-                            progress: event.progress,
-                        });
-                    }
-                    logger.info({ environmentId }, "Provision complete, calling adapter.connect");
-                    const conn = await adapter.connect(environmentId, config, powerlineToken);
-                    adapterManager.setConnection(environmentId, conn);
-                    // Push stored tokens to newly connected environment
-                    await tokenPush.pushToEnv(environmentId);
-                    envRegistry.updateEnvironmentStatus(environmentId, "connected");
-                    envRegistry.markBootstrapped(environmentId);
-                    // Auto-recover suspended sessions (fire-and-forget)
-                    recoverSuspendedSessions(environmentId, conn).catch((err) => {
-                        logger.error({ environmentId, err }, "Session recovery failed");
-                    });
-                    logger.info({ environmentId }, "Environment connected");
-                    emit("environment.provision_progress", {
-                        environmentId,
-                        stage: "ready",
-                        message: "Environment connected",
-                        progress: 1,
-                    });
-                }
-                catch (err) {
-                    logger.error({ environmentId, err }, "Provision failed");
-                    envRegistry.updateEnvironmentStatus(environmentId, "error");
-                    const errorMessage = err instanceof Error ? err.message : String(err);
-                    emit("environment.provision_progress", {
-                        environmentId,
-                        stage: "error",
-                        message: `Connection failed: ${errorMessage}`,
-                        progress: 0,
-                    });
-                }
-                emit("environment.changed", {});
-            })();
-            break;
-        }
-        case "stop_environment": {
-            const environmentId = msg.payload?.environmentId;
-            if (!environmentId) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "environmentId required" },
-                });
-                return;
-            }
-            const env = envRegistry.getEnvironment(environmentId);
-            if (!env) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Environment not found: ${environmentId}` },
-                });
-                return;
-            }
-            const adapter = adapterManager.getAdapter(env.adapterType);
-            if (adapter) {
-                const config = safeParseAdapterConfig(env.adapterConfig, environmentId);
-                await adapter.stop(environmentId, config);
-            }
-            adapterManager.removeConnection(environmentId);
-            envRegistry.updateEnvironmentStatus(environmentId, "disconnected");
-            logger.info({ environmentId }, "Environment stopped");
-            emit("environment.changed", {});
-            break;
-        }
-        case "add_environment": {
-            const displayName = msg.payload?.displayName || "";
-            const adapterType = msg.payload?.adapterType || "";
-            if (!displayName || !adapterType) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "displayName and adapterType required" },
-                });
-                return;
-            }
-            if (!adapterManager.getAdapter(adapterType)) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: `Unknown adapter type: ${adapterType}` },
-                });
-                return;
-            }
-            const baseEnvId = slugify(displayName) || uuid().slice(0, 8);
-            let id = baseEnvId;
-            for (let attempt = 0; attempt < 10 && envRegistry.getEnvironment(id); attempt++) {
-                id = `${baseEnvId}-${uuid().slice(0, 4)}`;
-            }
-            if (envRegistry.getEnvironment(id)) {
-                id = uuid();
-            }
-            const rawAdapterConfig = msg.payload?.adapterConfig;
-            let adapterConfig;
-            if (rawAdapterConfig === undefined || rawAdapterConfig === null) {
-                adapterConfig = "{}";
-            }
-            else if (typeof rawAdapterConfig === "string") {
-                const normalized = rawAdapterConfig.trim() === "" ? "{}" : rawAdapterConfig;
-                try {
-                    JSON.parse(normalized);
-                }
-                catch {
-                    sendWs(ws, {
-                        type: "error",
-                        payload: { message: "adapterConfig string is not valid JSON" },
-                    });
-                    return;
-                }
-                adapterConfig = normalized;
-            }
-            else if (typeof rawAdapterConfig === "object") {
-                adapterConfig = JSON.stringify(rawAdapterConfig);
-            }
-            else {
-                sendWs(ws, {
-                    type: "error",
-                    payload: {
-                        message: "adapterConfig must be an object or JSON string",
-                    },
-                });
-                return;
-            }
-            envRegistry.addEnvironment(id, displayName, adapterType, adapterConfig);
-            logger.info({ id, displayName, adapterType }, "Environment added via WebSocket");
-            emit("environment.added", { environmentId: id });
-            emit("environment.changed", {});
-            break;
-        }
-        case "update_environment": {
-            const environmentId = msg.payload?.environmentId;
-            if (!environmentId) {
-                sendWs(ws, { type: "error", payload: { message: "environmentId required" } });
-                return;
-            }
-            const existing = envRegistry.getEnvironment(environmentId);
-            if (!existing) {
-                sendWs(ws, { type: "error", payload: { message: `Environment not found: ${environmentId}` } });
-                return;
-            }
-            const nameVal = typeof msg.payload?.displayName === "string" ? msg.payload.displayName : undefined;
-            if (nameVal?.trim() === "") {
-                sendWs(ws, { type: "error", payload: { message: "Environment name cannot be empty" } });
-                return;
-            }
-            let configVal;
-            const rawConfig = msg.payload?.adapterConfig;
-            if (rawConfig !== undefined) {
-                if (rawConfig === null) {
-                    configVal = "{}";
-                }
-                else if (typeof rawConfig === "string") {
-                    const normalized = rawConfig.trim() === "" ? "{}" : rawConfig;
-                    let parsed;
-                    try {
-                        parsed = JSON.parse(normalized);
-                    }
-                    catch {
-                        sendWs(ws, { type: "error", payload: { message: "adapterConfig string is not valid JSON" } });
-                        return;
-                    }
-                    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-                        sendWs(ws, { type: "error", payload: { message: "adapterConfig must be a JSON object" } });
-                        return;
-                    }
-                    configVal = normalized;
-                }
-                else if (typeof rawConfig === "object") {
-                    if (Array.isArray(rawConfig)) {
-                        sendWs(ws, { type: "error", payload: { message: "adapterConfig must be a JSON object" } });
-                        return;
-                    }
-                    configVal = JSON.stringify(rawConfig);
-                }
-                else {
-                    sendWs(ws, { type: "error", payload: { message: "adapterConfig must be a JSON object" } });
-                    return;
-                }
-            }
-            const trimmedName = nameVal !== undefined ? nameVal.trim() : undefined;
-            if (trimmedName === undefined && configVal === undefined) {
-                sendWs(ws, { type: "error", payload: { message: "No updatable fields provided" } });
-                return;
-            }
-            envRegistry.updateEnvironment(environmentId, {
-                displayName: trimmedName,
-                adapterConfig: configVal,
-            });
-            logger.info({ environmentId, displayName: trimmedName }, "Environment updated via WebSocket");
-            emit("environment.changed", {});
-            break;
-        }
-        case "remove_environment": {
-            const environmentId = msg.payload?.environmentId;
-            if (!environmentId) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "environmentId required" },
-                });
-                return;
-            }
-            clearReconnectState(environmentId);
-            // Block deletion if workspaces still reference this environment
-            const wsCount = workspaceStore.countWorkspacesByEnvironment(environmentId);
-            if (wsCount > 0) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: {
-                        message: `Cannot remove environment: ${wsCount} active workspace(s) still reference it. Archive or reparent them first.`,
-                    },
-                });
-                return;
-            }
-            const env = envRegistry.getEnvironment(environmentId);
-            if (env) {
-                const adapter = adapterManager.getAdapter(env.adapterType);
-                if (adapter) {
-                    const config = safeParseAdapterConfig(env.adapterConfig, environmentId);
-                    try {
-                        await adapter.destroy(environmentId, config);
-                    }
-                    catch {
-                        /* best-effort */
-                    }
-                    try {
-                        await adapter.disconnect(environmentId);
-                    }
-                    catch {
-                        /* best-effort */
-                    }
-                }
-            }
-            adapterManager.removeConnection(environmentId);
-            sessionStore.deleteByEnvironment(environmentId);
-            envRegistry.removeEnvironment(environmentId);
-            logger.info({ environmentId }, "Environment removed");
-            emit("environment.removed", { environmentId });
-            emit("environment.changed", {});
-            break;
-        }
-        // ─── Codespaces ─────────────────────────────────────
-        case "list_codespaces": {
-            try {
-                const result = await exec("gh", [
-                    "codespace",
-                    "list",
-                    "--json",
-                    "name,repository,state,gitStatus",
-                    "--limit",
-                    String(GH_CODESPACE_LIST_LIMIT),
-                ], { timeout: GH_CODESPACE_LIST_TIMEOUT_MS });
-                const codespaces = JSON.parse(result.stdout || "[]");
-                sendWs(ws, { type: "codespaces_list", payload: { codespaces } });
-            }
-            catch (err) {
-                logger.warn({ err }, "Failed to list codespaces");
-                sendWs(ws, {
-                    type: "codespaces_list",
-                    payload: {
-                        codespaces: [],
-                        error: formatGhError(err, "list codespaces"),
-                    },
-                });
-            }
-            break;
-        }
-        case "create_codespace": {
-            const repo = msg.payload?.repo;
-            if (typeof repo !== "string" || repo.trim().length === 0) {
-                sendWs(ws, {
-                    type: "codespace_create_error",
-                    payload: { message: "repo required" },
-                });
-                return;
-            }
-            const trimmedRepo = repo.trim();
-            const machine = typeof msg.payload?.machine === "string"
-                ? msg.payload.machine.trim()
-                : "";
-            const createArgs = ["codespace", "create", "--repo", trimmedRepo];
-            if (machine) {
-                createArgs.push("--machine", machine);
-            }
-            try {
-                const result = await exec("gh", createArgs, {
-                    timeout: GH_CODESPACE_CREATE_TIMEOUT_MS,
-                });
-                const codespaceName = result.stdout.trim();
-                sendWs(ws, {
-                    type: "codespace_created",
-                    payload: { name: codespaceName, repository: trimmedRepo },
-                });
-            }
-            catch (err) {
-                logger.error({ err, repo }, "Failed to create codespace");
-                sendWs(ws, {
-                    type: "codespace_create_error",
-                    payload: { message: formatGhError(err, "create codespace") },
-                });
-            }
-            break;
-        }
-        // ─── Tokens ───────────────────────────────────────────
-        case "list_tokens": {
-            const items = tokenStore.listTokens();
-            sendWs(ws, {
-                type: "tokens",
-                payload: {
-                    tokens: items.map((t) => ({
-                        name: t.name,
-                        tokenType: t.type,
-                        envVar: t.envVar || "",
-                        filePath: t.filePath || "",
-                        expiresAt: t.expiresAt || "",
-                    })),
-                },
-            });
-            break;
-        }
-        case "set_token": {
-            const name = msg.payload?.name;
-            const value = msg.payload?.value;
-            if (!name || !value) {
-                sendWs(ws, {
-                    type: "error",
-                    payload: { message: "name and value required" },
-                });
-                return;
-            }
-            tokenStore.setToken({
-                name,
-                type: msg.payload?.tokenType || "env_var",
-                envVar: msg.payload?.envVar || "",
-                filePath: msg.payload?.filePath || "",
-                value,
-                expiresAt: msg.payload?.expiresAt || "",
-            });
-            await tokenPush.pushToAll();
-            emit("token.changed", {});
-            break;
-        }
-        case "delete_token": {
-            const tokenName = msg.payload?.name;
-            if (!tokenName) {
-                sendWs(ws, { type: "error", payload: { message: "name required" } });
-                return;
-            }
-            tokenStore.deleteToken(tokenName);
-            await tokenPush.pushToAll();
-            emit("token.changed", {});
-            break;
-        }
-        case "get_credential_providers": {
-            const config = credentialProviders.getCredentialProviders();
-            sendWs(ws, {
-                type: "credential_providers",
-                payload: config,
-            });
-            break;
-        }
-        case "set_credential_providers": {
-            if (!credentialProviders.isValidCredentialProviderConfig(msg.payload)) {
-                sendWs(ws, { type: "error", payload: { message: "invalid credential provider config" } });
-                return;
-            }
-            credentialProviders.setCredentialProviders(msg.payload);
-            emit("credential.providers_changed", credentialProviders.getCredentialProviders());
-            break;
-        }
-        // ── Knowledge Graph ─────────────────────────────────────────
-        case "knowledge.search": {
-            const embedder = getKnowledgeEmbedder();
-            if (!embedder) {
-                sendWs(ws, { type: "knowledge.search.result", payload: { error: "Knowledge graph not available", results: [] } });
-                return;
-            }
-            try {
-                const query = msg.payload?.query || "";
-                const rawLimit = Number(msg.payload?.limit) || 10;
-                const limit = Math.max(1, Math.min(50, Math.floor(rawLimit)));
-                const workspaceId = msg.payload?.workspaceId !== undefined ? msg.payload.workspaceId : undefined;
-                const results = await knowledgeSearch(query, embedder, { limit, workspaceId });
-                sendWs(ws, {
-                    type: "knowledge.search.result",
-                    payload: {
-                        results: results.map((r) => ({
-                            score: r.score,
-                            node: formatKnowledgeNode(r.node),
-                            edges: r.edges.map(formatKnowledgeEdge),
-                        })),
-                    },
-                });
-            }
-            catch (err) {
-                logger.error({ err }, "Knowledge search failed");
-                sendWs(ws, { type: "knowledge.search.result", payload: { error: "Search failed", results: [] } });
-            }
-            break;
-        }
-        case "knowledge.getNode": {
-            if (!isKnowledgeEnabled()) {
-                sendWs(ws, { type: "knowledge.getNode.result", payload: { error: "Knowledge graph not available" } });
-                return;
-            }
-            try {
-                const id = msg.payload?.id || "";
-                const result = await getKnowledgeNodeById(id);
-                if (!result) {
-                    sendWs(ws, { type: "knowledge.getNode.result", payload: { error: `Node not found: ${id}` } });
-                    return;
-                }
-                sendWs(ws, {
-                    type: "knowledge.getNode.result",
-                    payload: {
-                        node: formatKnowledgeNode(result.node),
-                        edges: result.edges.map(formatKnowledgeEdge),
-                    },
-                });
-            }
-            catch (err) {
-                logger.error({ err }, "Knowledge getNode failed");
-                sendWs(ws, { type: "knowledge.getNode.result", payload: { error: "Failed to get node" } });
-            }
-            break;
-        }
-        case "knowledge.expand": {
-            if (!isKnowledgeEnabled()) {
-                sendWs(ws, { type: "knowledge.expand.result", payload: { error: "Knowledge graph not available", nodes: [], edges: [] } });
-                return;
-            }
-            try {
-                const id = msg.payload?.id || "";
-                const rawDepth = Number(msg.payload?.depth) || 1;
-                const depth = Math.max(1, Math.min(5, Math.floor(rawDepth)));
-                const rawEdgeTypes = msg.payload?.edgeTypes;
-                const edgeTypes = rawEdgeTypes?.length ? rawEdgeTypes : undefined;
-                const result = await expandNode(id, { depth, edgeTypes });
-                sendWs(ws, {
-                    type: "knowledge.expand.result",
-                    payload: {
-                        nodes: result.nodes.map(formatKnowledgeNode),
-                        edges: result.edges.map(formatKnowledgeEdge),
-                    },
-                });
-            }
-            catch (err) {
-                logger.error({ err }, "Knowledge expand failed");
-                sendWs(ws, { type: "knowledge.expand.result", payload: { error: "Expand failed", nodes: [], edges: [] } });
-            }
-            break;
-        }
-        case "knowledge.listRecent": {
-            if (!isKnowledgeEnabled()) {
-                sendWs(ws, { type: "knowledge.listRecent.result", payload: { error: "Knowledge graph not available", nodes: [], edges: [] } });
-                return;
-            }
-            try {
-                const rawLimit = Number(msg.payload?.limit) || 20;
-                const limit = Math.max(1, Math.min(100, Math.floor(rawLimit)));
-                const workspaceId = msg.payload?.workspaceId !== undefined ? msg.payload.workspaceId : undefined;
-                const result = await listRecentNodes(limit, workspaceId);
-                sendWs(ws, {
-                    type: "knowledge.listRecent.result",
-                    payload: {
-                        nodes: result.nodes.map(formatKnowledgeNode),
-                        edges: result.edges.map(formatKnowledgeEdge),
-                    },
-                });
-            }
-            catch (err) {
-                logger.error({ err }, "Knowledge listRecent failed");
-                sendWs(ws, { type: "knowledge.listRecent.result", payload: { error: "Failed to list recent", nodes: [], edges: [] } });
-            }
-            break;
-        }
-    }
-}
-/** Format a KnowledgeNode for WS transport (omit embedding). */
-function formatKnowledgeNode(node) {
-    const base = {
-        id: node.id,
-        kind: node.kind,
-        workspaceId: node.workspaceId,
-        createdAt: node.createdAt,
-        updatedAt: node.updatedAt,
-    };
-    if (node.kind === "reference") {
-        base.sourceType = node.sourceType;
-        base.sourceId = node.sourceId;
-        base.label = node.label;
     }
-    else {
-        base.category = node.category;
-        base.title = node.title;
-        base.content = node.content;
-        base.tags = node.tags;
-    }
-    return base;
-}
-/** Format a KnowledgeEdge for WS transport. */
-function formatKnowledgeEdge(edge) {
-    return {
-        fromId: edge.fromId,
-        toId: edge.toId,
-        type: edge.type,
-        ...(edge.metadata ? { metadata: edge.metadata } : {}),
-        createdAt: edge.createdAt,
-    };
 }
 function sendWs(ws, msg) {
     if (ws.readyState === WebSocket.OPEN) {