chainlesschain 0.45.70 → 0.45.74

package/src/lib/ws-session-manager.js

@@ -1,1421 +1,12 @@
 /**
- * WebSocket Session Manager
+ * @deprecated — canonical implementation lives in
+ * `../gateways/ws/ws-session-gateway.js` as of the CLI Runtime
+ * Convergence roadmap (Phase 6a, 2026-04-09). This file is retained
+ * as a re-export shim for backwards compatibility and will be
+ * removed once all external consumers have migrated.
  *
- * Registry and lifecycle management for stateful agent/chat sessions
- * accessed over WebSocket. Each session maintains its own message history,
- * context engine, permanent memory, plan manager, and LLM configuration.
+ * Please import `WSSessionManager` directly from
+ * `packages/cli/src/gateways/ws/ws-session-gateway.js` in new code.
  */
 
-import { createHash } from "crypto";
-import fs from "fs";
-import path from "path";
-import { ExecutionPlan, PlanModeManager, PlanState } from "./plan-mode.js";
-import { CLIContextEngineering } from "./cli-context-engineering.js";
-import { CLIPermanentMemory } from "./permanent-memory.js";
-import {
-  createTrustedMcpServerMap,
-  resolveMcpServerPolicy,
-  normalizeRiskLevel,
-  normalizeBoolean,
-  selectHigherRiskLevel,
-} from "../runtime/coding-agent-managed-tool-policy.cjs";
-import {
-  createSession as dbCreateSession,
-  saveMessages as dbSaveMessages,
-  getSession as dbGetSession,
-  listSessions as dbListSessions,
-  updateSession as dbUpdateSession,
-} from "./session-manager.js";
-import { buildSystemPrompt } from "./agent-core.js";
-import { SubAgentRegistry } from "./sub-agent-registry.js";
-import { createWorktree, removeWorktree } from "./worktree-isolator.js";
-import { isGitRepo } from "./git-integration.js";
-import {
-  CODING_AGENT_MVP_TOOL_NAMES,
-  listCodingAgentToolNames,
-} from "../runtime/coding-agent-contract.js";
-
-/**
- * @typedef {object} Session
- * @property {string} id
- * @property {"agent"|"chat"} type
- * @property {"active"|"closed"} status
- * @property {Array} messages
- * @property {string} provider
- * @property {string} model
- * @property {string|null} apiKey
- * @property {string|null} baseUrl
- * @property {string} projectRoot
- * @property {string} baseProjectRoot
- * @property {string|null} rulesContent
- * @property {string[]} enabledToolNames
- * @property {object|null} hostManagedToolPolicy
- * @property {Array<object>} externalToolDefinitions
- * @property {object} externalToolDescriptors
- * @property {object} externalToolExecutors
- * @property {boolean} worktreeIsolation
- * @property {object|null} worktree
- * @property {PlanModeManager} planManager
- * @property {CLIContextEngineering|null} contextEngine
- * @property {CLIPermanentMemory|null} permanentMemory
- * @property {import("./interaction-adapter.js").WebSocketInteractionAdapter|null} interaction
- * @property {string} createdAt
- * @property {string} lastActivity
- */
-
-export class WSSessionManager {
-  /**
-   * @param {object} options
-   * @param {object} [options.db] - Database instance
-   * @param {object} [options.config] - Config object
-   * @param {string} [options.defaultProjectRoot] - Default project root
-   */
-  constructor(options = {}) {
-    this.db = options.db || null;
-    this.config = options.config || {};
-    this.defaultProjectRoot = options.defaultProjectRoot || process.cwd();
-    this.mcpClient = options.mcpClient || null;
-    this.allowedMcpServerNames = Array.isArray(options.allowedMcpServerNames)
-      ? options.allowedMcpServerNames
-      : null;
-    this.allowHighRiskMcpServers = options.allowHighRiskMcpServers === true;
-    this.trustedMcpServers = createTrustedMcpServerMap(
-      options.mcpServerRegistry || null,
-    );
-
-    /** @type {Map<string, Session>} */
-    this.sessions = new Map();
-  }
-
-  _normalizeEnabledToolNames(enabledToolNames) {
-    const knownToolNames = new Set(listCodingAgentToolNames());
-    const requested = Array.isArray(enabledToolNames)
-      ? enabledToolNames
-          .map((name) => String(name || "").trim())
-          .filter(Boolean)
-      : [];
-
-    const filtered = requested.filter((name) => knownToolNames.has(name));
-    if (filtered.length > 0) {
-      return [...new Set(filtered)];
-    }
-
-    return [...CODING_AGENT_MVP_TOOL_NAMES];
-  }
-
-  _buildSessionExternalTools() {
-    if (
-      !this.mcpClient ||
-      !(this.mcpClient.servers instanceof Map) ||
-      typeof this.mcpClient.listTools !== "function"
-    ) {
-      return {
-        definitions: [],
-        descriptors: {},
-        executors: {},
-      };
-    }
-
-    const definitions = [];
-    const descriptors = {};
-    const executors = {};
-    const seenNames = new Set();
-
-    for (const [serverName, serverState] of this.mcpClient.servers.entries()) {
-      const serverPolicy = resolveMcpServerPolicy(serverName, serverState, {
-        allowedMcpServerNames: this.allowedMcpServerNames,
-        trustedMcpServers: this.trustedMcpServers,
-        allowHighRiskMcpServers: this.allowHighRiskMcpServers,
-      });
-
-      if (!serverPolicy.allowed) {
-        continue;
-      }
-
-      const serverTools = Array.isArray(serverState?.tools)
-        ? serverState.tools
-        : this.mcpClient.listTools(serverName);
-
-      for (const mcpTool of Array.isArray(serverTools) ? serverTools : []) {
-        const parsedSchema = this._parseToolSchema(mcpTool?.inputSchema) ||
-          this._parseToolSchema(mcpTool?.input_schema) ||
-          this._parseToolSchema(mcpTool?.parameters_schema) || {
-            type: "object",
-            properties: {},
-          };
-        const riskLevel = selectHigherRiskLevel(
-          serverPolicy.securityLevel,
-          normalizeRiskLevel(mcpTool?.risk_level, null),
-        );
-        const isReadOnly =
-          normalizeBoolean(mcpTool?.isReadOnly, false) ||
-          normalizeBoolean(mcpTool?.is_read_only, false) ||
-          riskLevel === "low";
-
-        let toolName = `mcp_${serverName}_${mcpTool?.name || "tool"}`;
-        if (seenNames.has(toolName)) {
-          let index = 2;
-          let candidate = `${toolName}_${index}`;
-          while (seenNames.has(candidate)) {
-            index += 1;
-            candidate = `${toolName}_${index}`;
-          }
-          toolName = candidate;
-        }
-        seenNames.add(toolName);
-
-        const descriptor = {
-          name: toolName,
-          description: mcpTool?.description || `MCP tool from ${serverName}.`,
-          inputSchema: parsedSchema,
-          isReadOnly,
-          riskLevel,
-          source: `mcp:${serverName}`,
-          mcpMetadata: {
-            serverName,
-            trusted: serverPolicy.trusted === true,
-            securityLevel: serverPolicy.securityLevel,
-            requiredPermissions: serverPolicy.requiredPermissions || [],
-            capabilities: serverPolicy.capabilities || [],
-            originalToolName: mcpTool?.name || null,
-            tool: mcpTool || null,
-          },
-        };
-
-        definitions.push({
-          type: "function",
-          function: {
-            name: descriptor.name,
-            description: descriptor.description,
-            parameters: JSON.parse(JSON.stringify(descriptor.inputSchema)),
-          },
-        });
-        descriptors[descriptor.name] = descriptor;
-        executors[descriptor.name] = {
-          kind: "mcp",
-          serverName,
-          toolName: mcpTool?.name || null,
-        };
-      }
-    }
-
-    return {
-      definitions,
-      descriptors,
-      executors,
-    };
-  }
-
-  _parseToolSchema(value) {
-    if (!value) {
-      return null;
-    }
-
-    if (typeof value === "object") {
-      return value;
-    }
-
-    if (typeof value !== "string") {
-      return null;
-    }
-
-    try {
-      return JSON.parse(value);
-    } catch (_err) {
-      return null;
-    }
-  }
-
-  /**
-   * Generate a unique session ID
-   */
-  _generateId() {
-    const hash = createHash("sha256")
-      .update(Math.random().toString() + Date.now().toString())
-      .digest("hex")
-      .slice(0, 8);
-    return `ws-session-${Date.now()}-${hash}`;
-  }
-
-  /**
-   * Create a new session.
-   *
-   * @param {object} options
-   * @param {"agent"|"chat"} [options.type="agent"]
-   * @param {string} [options.projectRoot]
-   * @param {string} [options.provider="ollama"]
-   * @param {string} [options.model]
-   * @param {string} [options.apiKey]
-   * @param {string} [options.baseUrl]
-   * @param {object} [options.hostManagedToolPolicy]
-   * @returns {{ sessionId: string }}
-   */
-  createSession(options = {}) {
-    const sessionId = this._generateId();
-    const type = options.type || "agent";
-    const baseProjectRoot = options.projectRoot || this.defaultProjectRoot;
-    const cfgLlm = this.config?.llm || {};
-    const provider = options.provider || cfgLlm.provider || "ollama";
-    const model =
-      options.model ||
-      cfgLlm.model ||
-      (provider === "ollama" ? "qwen2.5:7b" : null);
-    const baseUrl =
-      options.baseUrl || cfgLlm.baseUrl || "http://localhost:11434";
-    const apiKey = options.apiKey || cfgLlm.apiKey || null;
-    const worktreeIsolationRequested = options.worktreeIsolation === true;
-    const enabledToolNames = this._normalizeEnabledToolNames(
-      options.enabledToolNames,
-    );
-    const externalTools = this._buildSessionExternalTools();
-    const isolatedWorkspace = this._prepareSessionWorkspace(
-      baseProjectRoot,
-      sessionId,
-      {
-        worktreeIsolation: worktreeIsolationRequested,
-      },
-    );
-    const projectRoot = isolatedWorkspace.projectRoot;
-    const worktree = isolatedWorkspace.worktree;
-
-    // Project context (rules.md, persona) is now loaded by buildSystemPrompt()
-
-    // Create plan manager (non-singleton, per-session)
-    const planManager = new PlanModeManager();
-
-    // Create context engine
-    let contextEngine = null;
-    let permanentMemory = null;
-    try {
-      const memoryDir = path.join(projectRoot, "memory");
-      permanentMemory = new CLIPermanentMemory({
-        db: this.db,
-        memoryDir,
-      });
-      permanentMemory.initialize();
-    } catch (_err) {
-      // Non-critical
-    }
-
-    try {
-      contextEngine = new CLIContextEngineering({
-        db: this.db,
-        permanentMemory,
-      });
-    } catch (_err) {
-      // Non-critical
-    }
-
-    // Build initial system prompt (includes persona + rules.md)
-    const systemPrompt = buildSystemPrompt(projectRoot);
-
-    const messages = [{ role: "system", content: systemPrompt }];
-
-    // Persist to DB
-    if (this.db) {
-      try {
-        dbCreateSession(this.db, {
-          id: sessionId,
-          title: `WS ${type} ${new Date().toISOString().slice(0, 10)}`,
-          provider,
-          model: model || "",
-          messages,
-        });
-      } catch (_err) {
-        // Non-critical
-      }
-    }
-
-    const session = {
-      id: sessionId,
-      type,
-      status: "active",
-      messages,
-      provider,
-      model,
-      apiKey,
-      baseUrl,
-      mcpClient: this.mcpClient,
-      enabledToolNames,
-      hostManagedToolPolicy: options.hostManagedToolPolicy || null,
-      externalToolDefinitions: externalTools.definitions,
-      externalToolDescriptors: externalTools.descriptors,
-      externalToolExecutors: externalTools.executors,
-      projectRoot,
-      baseProjectRoot,
-      rulesContent: null,
-      worktreeIsolation: worktreeIsolationRequested,
-      worktree,
-      planManager,
-      contextEngine,
-      permanentMemory,
-      reviewState: null,
-      pendingPatches: new Map(),
-      patchHistory: [],
-      taskGraph: null,
-      interaction: null, // Set by ws-server after creation
-      createdAt: new Date().toISOString(),
-      lastActivity: new Date().toISOString(),
-    };
-
-    if (this.db) {
-      try {
-        dbUpdateSession(this.db, sessionId, {
-          metadata: this._serializeSessionMetadata(session),
-        });
-      } catch (_err) {
-        // Non-critical
-      }
-    }
-
-    this._bindPlanManagerPersistence(session);
-    this.sessions.set(sessionId, session);
-
-    return { sessionId };
-  }
-
-  /**
-   * Resume an existing session from DB.
-   *
-   * @param {string} sessionId
-   * @returns {Session|null}
-   */
-  resumeSession(sessionId) {
-    // Check in-memory first
-    if (this.sessions.has(sessionId)) {
-      const session = this.sessions.get(sessionId);
-      session.status = "active";
-      session.lastActivity = new Date().toISOString();
-      return session;
-    }
-
-    // Try loading from DB
-    if (!this.db) return null;
-
-    try {
-      const dbSession = dbGetSession(this.db, sessionId);
-      if (!dbSession) return null;
-
-      const messages =
-        typeof dbSession.messages === "string"
-          ? JSON.parse(dbSession.messages)
-          : dbSession.messages || [];
-      const metadata = this._normalizeSessionMetadata(dbSession.metadata);
-      const baseProjectRoot =
-        metadata.baseProjectRoot ||
-        metadata.projectRoot ||
-        this.defaultProjectRoot;
-      const workspace = this._restoreSessionWorkspace(
-        dbSession.id,
-        baseProjectRoot,
-        metadata,
-      );
-      const planManager = this._hydratePlanManager(metadata.planSnapshot);
-      const externalTools = this._buildSessionExternalTools();
-      let contextEngine = null;
-      let permanentMemory = null;
-
-      try {
-        const memoryDir = path.join(workspace.projectRoot, "memory");
-        permanentMemory = new CLIPermanentMemory({
-          db: this.db,
-          memoryDir,
-        });
-        permanentMemory.initialize();
-      } catch (_err) {
-        // Non-critical
-      }
-
-      try {
-        contextEngine = new CLIContextEngineering({
-          db: this.db,
-          permanentMemory,
-        });
-      } catch (_err) {
-        // Non-critical
-      }
-
-      const session = {
-        id: dbSession.id,
-        type: metadata.sessionType || "agent",
-        status: "active",
-        messages,
-        provider: dbSession.provider || "ollama",
-        model: dbSession.model || null,
-        apiKey: null,
-        baseUrl: metadata.baseUrl || "http://localhost:11434",
-        mcpClient: this.mcpClient,
-        enabledToolNames: this._normalizeEnabledToolNames(
-          metadata.enabledToolNames,
-        ),
-        hostManagedToolPolicy: metadata.hostManagedToolPolicy || null,
-        externalToolDefinitions: externalTools.definitions,
-        externalToolDescriptors: externalTools.descriptors,
-        externalToolExecutors: externalTools.executors,
-        projectRoot: workspace.projectRoot,
-        baseProjectRoot,
-        rulesContent: null,
-        worktreeIsolation: metadata.worktreeIsolation === true,
-        worktree: workspace.worktree,
-        planManager,
-        contextEngine,
-        permanentMemory,
-        reviewState: metadata.reviewState || null,
-        pendingPatches: this._hydratePendingPatches(metadata.pendingPatches),
-        patchHistory: Array.isArray(metadata.patchHistory)
-          ? metadata.patchHistory
-          : [],
-        taskGraph: this._hydrateTaskGraph(metadata.taskGraph),
-        interaction: null,
-        createdAt: dbSession.created_at,
-        lastActivity: new Date().toISOString(),
-      };
-
-      this._bindPlanManagerPersistence(session);
-      this.sessions.set(session.id, session);
-      return session;
-    } catch (_err) {
-      return null;
-    }
-  }
-
-  /**
-   * Close a session and persist final state.
-   *
-   * @param {string} sessionId
-   */
-  closeSession(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session) return;
-
-    session.status = "closed";
-
-    // Persist messages to DB
-    this._persistSessionState(sessionId);
-
-    // Auto-summarize into permanent memory
-    if (session.permanentMemory && session.messages.length > 4) {
-      try {
-        session.permanentMemory.autoSummarize(session.messages);
-      } catch (_err) {
-        // Non-critical
-      }
-    }
-
-    // Force-complete any active sub-agents for this session
-    try {
-      SubAgentRegistry.getInstance().forceCompleteAll(sessionId);
-    } catch (_err) {
-      // Non-critical
-    }
-
-    // Clean up plan manager listeners
-    if (session.planManager) {
-      if (typeof session._planPersistenceCleanup === "function") {
-        try {
-          session._planPersistenceCleanup();
-        } catch (_err) {
-          // Non-critical.
-        }
-      }
-      session.planManager.removeAllListeners();
-    }
-
-    if (session.worktree?.path && session.baseProjectRoot) {
-      try {
-        removeWorktree(session.baseProjectRoot, session.worktree.path, {
-          deleteBranch: true,
-        });
-      } catch (_err) {
-        // Best-effort cleanup.
-      }
-    }
-
-    this.sessions.delete(sessionId);
-  }
-
-  /**
-   * List all sessions (in-memory + DB).
-   *
-   * @returns {Array<{id, type, status, createdAt, lastActivity}>}
-   */
-  listSessions() {
-    const results = [];
-
-    // In-memory active sessions
-    for (const [, session] of this.sessions) {
-      results.push({
-        id: session.id,
-        type: session.type,
-        status: session.status,
-        provider: session.provider,
-        model: session.model,
-        messageCount: session.messages.length,
-        enabledToolNames: session.enabledToolNames || [],
-        baseProjectRoot: session.baseProjectRoot,
-        worktreeIsolation: session.worktreeIsolation === true,
-        worktree: session.worktree || null,
-        createdAt: session.createdAt,
-        lastActivity: session.lastActivity,
-      });
-    }
-
-    // DB sessions (exclude already-listed in-memory ones)
-    if (this.db) {
-      try {
-        const dbSessions = dbListSessions(this.db, { limit: 20 });
-        const inMemoryIds = new Set(this.sessions.keys());
-        for (const dbs of dbSessions) {
-          const metadata = this._normalizeSessionMetadata(dbs.metadata);
-          if (!inMemoryIds.has(dbs.id)) {
-            results.push({
-              id: dbs.id,
-              type: metadata.sessionType || "unknown",
-              status: "persisted",
-              provider: dbs.provider,
-              model: dbs.model,
-              messageCount: dbs.message_count,
-              enabledToolNames: Array.isArray(metadata.enabledToolNames)
-                ? metadata.enabledToolNames
-                : [],
-              baseProjectRoot: metadata.baseProjectRoot || null,
-              worktreeIsolation: metadata.worktreeIsolation === true,
-              worktree: metadata.worktree || null,
-              createdAt: dbs.created_at,
-              lastActivity: dbs.updated_at,
-            });
-          }
-        }
-      } catch (_err) {
-        // Non-critical
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * Get a session by ID.
-   *
-   * @param {string} sessionId
-   * @returns {Session|null}
-   */
-  getSession(sessionId) {
-    return this.sessions.get(sessionId) || null;
-  }
-
-  /**
-   * Update host-managed tool policy for an active session.
-   *
-   * @param {string} sessionId
-   * @param {object|null} hostManagedToolPolicy
-   * @returns {Session|null}
-   */
-  updateSessionPolicy(sessionId, hostManagedToolPolicy) {
-    const session = this.sessions.get(sessionId);
-    if (!session) return null;
-
-    session.hostManagedToolPolicy = hostManagedToolPolicy || null;
-    session.lastActivity = new Date().toISOString();
-    this._persistSessionState(sessionId);
-    return session;
-  }
-
-  /**
-   * Enter explicit review mode for a session. While in review, handlers
-   * MUST gate new sendMessage calls until the review is resolved. Reviewer
-   * sub-agents and human reviewers both feed into the same `comments` /
-   * `checklist` arrays.
-   *
-   * @param {string} sessionId
-   * @param {{
-   *   reason?: string,
-   *   requestedBy?: string,
-   *   checklist?: Array<{ id?: string, title: string, note?: string }>,
-   *   blocking?: boolean,
-   * }} [options]
-   */
-  enterReview(sessionId, options = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session) return null;
-
-    // If already in pending review, return the existing state unchanged so
-    // callers can retry safely.
-    if (session.reviewState && session.reviewState.status === "pending") {
-      return session.reviewState;
-    }
-
-    const reviewId = `review-${this._generateId()}`;
-    const now = new Date().toISOString();
-    const checklist = Array.isArray(options.checklist)
-      ? options.checklist.map((item, index) => ({
-          id: item.id || `chk-${index}-${Date.now()}`,
-          title: item.title || `Item ${index + 1}`,
-          note: item.note || null,
-          done: false,
-        }))
-      : [];
-
-    session.reviewState = {
-      reviewId,
-      status: "pending",
-      reason: options.reason || null,
-      requestedBy: options.requestedBy || "user",
-      requestedAt: now,
-      resolvedAt: null,
-      resolvedBy: null,
-      decision: null,
-      blocking: options.blocking !== false,
-      comments: [],
-      checklist,
-    };
-    session.lastActivity = now;
-    this._persistSessionState(sessionId);
-    return session.reviewState;
-  }
-
-  /**
-   * Submit an incremental update to the active review — append a comment
-   * and/or toggle a checklist item. Returns the updated reviewState, or null
-   * if the session has no active review.
-   *
-   * @param {string} sessionId
-   * @param {{
-   *   comment?: { author?: string, content: string },
-   *   checklistItemId?: string,
-   *   checklistItemDone?: boolean,
-   *   checklistItemNote?: string,
-   * }} update
-   */
-  submitReviewComment(sessionId, update = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !session.reviewState) return null;
-    if (session.reviewState.status !== "pending") return null;
-
-    const now = new Date().toISOString();
-
-    if (update.comment && update.comment.content) {
-      session.reviewState.comments.push({
-        id: `cmt-${session.reviewState.comments.length}-${Date.now()}`,
-        author: update.comment.author || "user",
-        content: String(update.comment.content),
-        timestamp: now,
-      });
-    }
-
-    if (update.checklistItemId) {
-      const item = session.reviewState.checklist.find(
-        (c) => c.id === update.checklistItemId,
-      );
-      if (item) {
-        if (typeof update.checklistItemDone === "boolean") {
-          item.done = update.checklistItemDone;
-        }
-        if (typeof update.checklistItemNote === "string") {
-          item.note = update.checklistItemNote;
-        }
-      }
-    }
-
-    session.lastActivity = now;
-    this._persistSessionState(sessionId);
-    return session.reviewState;
-  }
-
-  /**
-   * Resolve the active review with an approved/rejected decision. After
-   * resolve the session can accept new messages again (reviewState becomes
-   * non-blocking but is retained for audit).
-   *
-   * @param {string} sessionId
-   * @param {{ decision: "approved"|"rejected", resolvedBy?: string, summary?: string }} payload
-   */
-  resolveReview(sessionId, payload = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !session.reviewState) return null;
-    if (session.reviewState.status !== "pending") {
-      return session.reviewState;
-    }
-
-    const decision =
-      payload.decision === "approved" || payload.decision === "rejected"
-        ? payload.decision
-        : "approved";
-
-    session.reviewState.status = decision;
-    session.reviewState.decision = decision;
-    session.reviewState.resolvedAt = new Date().toISOString();
-    session.reviewState.resolvedBy = payload.resolvedBy || "user";
-    session.reviewState.blocking = false;
-    if (payload.summary) {
-      session.reviewState.summary = String(payload.summary);
-    }
-
-    session.lastActivity = session.reviewState.resolvedAt;
-    this._persistSessionState(sessionId);
-    return session.reviewState;
-  }
-
-  /**
-   * Returns true when the session currently has a blocking review gate
-   * open. Callers (e.g. handleSessionMessage) should short-circuit with a
-   * REVIEW_BLOCKING error instead of running the agent turn.
-   */
-  isReviewBlocking(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !session.reviewState) return false;
-    return (
-      session.reviewState.status === "pending" &&
-      session.reviewState.blocking === true
-    );
-  }
-
-  getReviewState(sessionId) {
-    const session = this.sessions.get(sessionId);
-    return session ? session.reviewState || null : null;
-  }
-
-  /**
-   * Record a proposed patch on the session. Accepts one or more file hunks
-   * that a tool wanted to write but should be previewed before they land.
-   *
-   * @param {string} sessionId
-   * @param {{
-   *   files: Array<{
-   *     path: string,
-   *     op?: "create"|"modify"|"delete",
-   *     before?: string|null,
-   *     after?: string|null,
-   *     diff?: string|null,
-   *     stats?: { added?: number, removed?: number }
-   *   }>,
-   *   origin?: string,
-   *   reason?: string,
-   *   requestId?: string|null
-   * }} payload
-   * @returns {object|null} patch record, or null if the session is missing
-   */
-  proposePatch(sessionId, payload = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session) return null;
-
-    const files = Array.isArray(payload.files) ? payload.files : [];
-    if (files.length === 0) return null;
-
-    const patchId = `patch-${this._generateId()}`;
-    const now = new Date().toISOString();
-    const normalizedFiles = files.map((file, index) => {
-      const op = file.op || (file.before == null ? "create" : "modify");
-      const stats = this._computePatchStats(file);
-      return {
-        index,
-        path: file.path || `unknown-${index}`,
-        op,
-        before: file.before == null ? null : String(file.before),
-        after: file.after == null ? null : String(file.after),
-        diff: file.diff == null ? null : String(file.diff),
-        stats,
-      };
-    });
-
-    const totalStats = normalizedFiles.reduce(
-      (acc, file) => ({
-        added: acc.added + (file.stats.added || 0),
-        removed: acc.removed + (file.stats.removed || 0),
-      }),
-      { added: 0, removed: 0 },
-    );
-
-    const patch = {
-      patchId,
-      status: "pending",
-      origin: payload.origin || "tool",
-      reason: payload.reason || null,
-      requestId: payload.requestId || null,
-      proposedAt: now,
-      resolvedAt: null,
-      resolvedBy: null,
-      files: normalizedFiles,
-      stats: {
-        fileCount: normalizedFiles.length,
-        added: totalStats.added,
-        removed: totalStats.removed,
-      },
-    };
-
-    if (!(session.pendingPatches instanceof Map)) {
-      session.pendingPatches = new Map();
-    }
-    session.pendingPatches.set(patchId, patch);
-    session.lastActivity = now;
-    this._persistSessionState(sessionId);
-    return patch;
-  }
-
-  /**
-   * Mark a pending patch as applied. Moves the record to patchHistory so it
-   * is still visible in the summary view but no longer counts as pending.
-   */
-  applyPatch(sessionId, patchId, options = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !(session.pendingPatches instanceof Map)) return null;
-    const patch = session.pendingPatches.get(patchId);
-    if (!patch) return null;
-
-    patch.status = "applied";
-    patch.resolvedAt = new Date().toISOString();
-    patch.resolvedBy = options.resolvedBy || "user";
-    if (options.note) {
-      patch.note = String(options.note);
-    }
-
-    session.pendingPatches.delete(patchId);
-    if (!Array.isArray(session.patchHistory)) {
-      session.patchHistory = [];
-    }
-    session.patchHistory.push(patch);
-    session.lastActivity = patch.resolvedAt;
-    this._persistSessionState(sessionId);
-    return patch;
-  }
-
-  /**
-   * Discard a pending patch. Same bookkeeping as applyPatch but records a
-   * "rejected" decision instead.
-   */
-  rejectPatch(sessionId, patchId, options = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !(session.pendingPatches instanceof Map)) return null;
-    const patch = session.pendingPatches.get(patchId);
-    if (!patch) return null;
-
-    patch.status = "rejected";
-    patch.resolvedAt = new Date().toISOString();
-    patch.resolvedBy = options.resolvedBy || "user";
-    if (options.reason) {
-      patch.rejectionReason = String(options.reason);
-    }
-
-    session.pendingPatches.delete(patchId);
-    if (!Array.isArray(session.patchHistory)) {
-      session.patchHistory = [];
-    }
-    session.patchHistory.push(patch);
-    session.lastActivity = patch.resolvedAt;
-    this._persistSessionState(sessionId);
-    return patch;
-  }
-
-  /**
-   * Return a flattened summary of all pending + resolved patches on the
-   * session. Shape matches what the renderer strip consumes:
-   *   { pending: [...], history: [...], totals: { added, removed, fileCount } }
-   */
-  getPatchSummary(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session) return null;
-
-    const pending =
-      session.pendingPatches instanceof Map
-        ? Array.from(session.pendingPatches.values())
-        : [];
-    const history = Array.isArray(session.patchHistory)
-      ? session.patchHistory
-      : [];
-
-    const totals = [...pending, ...history].reduce(
-      (acc, patch) => ({
-        fileCount: acc.fileCount + (patch.stats?.fileCount || 0),
-        added: acc.added + (patch.stats?.added || 0),
-        removed: acc.removed + (patch.stats?.removed || 0),
-      }),
-      { fileCount: 0, added: 0, removed: 0 },
-    );
-
-    return { pending, history, totals };
-  }
-
-  hasPendingPatches(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !(session.pendingPatches instanceof Map)) return false;
-    return session.pendingPatches.size > 0;
-  }
-
-  _computePatchStats(file) {
-    if (file && file.stats && typeof file.stats === "object") {
-      return {
-        added: Number(file.stats.added) || 0,
-        removed: Number(file.stats.removed) || 0,
-      };
-    }
-    const before = file && typeof file.before === "string" ? file.before : "";
-    const after = file && typeof file.after === "string" ? file.after : "";
-    const beforeLines = before ? before.split(/\r?\n/).length : 0;
-    const afterLines = after ? after.split(/\r?\n/).length : 0;
-    // Rough heuristic when no explicit diff is provided: full replace counts
-    // the entire file as added/removed.
-    if (!before && after) return { added: afterLines, removed: 0 };
-    if (before && !after) return { added: 0, removed: beforeLines };
-    return {
-      added: Math.max(0, afterLines - beforeLines),
-      removed: Math.max(0, beforeLines - afterLines),
-    };
-  }
-
-  /**
-   * Create or replace the task graph for a session. A graph is a DAG of
-   * `nodes` keyed by id; each node has `{ id, title, status, dependsOn[],
-   * metadata }`. Returns the serialized graph.
-   */
-  createTaskGraph(sessionId, payload = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session) return null;
-
-    const graphId = payload.graphId || `graph-${this._generateId()}`;
-    const now = new Date().toISOString();
-    const nodes = {};
-    const incomingNodes = Array.isArray(payload.nodes) ? payload.nodes : [];
-    for (const raw of incomingNodes) {
-      if (!raw || !raw.id) continue;
-      nodes[raw.id] = this._normalizeTaskNode(raw, now);
-    }
-
-    const graph = {
-      graphId,
-      title: payload.title || null,
-      description: payload.description || null,
-      status: "active",
-      createdAt: now,
-      updatedAt: now,
-      completedAt: null,
-      nodes,
-      order: Object.keys(nodes),
-    };
-
-    session.taskGraph = graph;
-    session.lastActivity = now;
-    this._persistSessionState(sessionId);
-    return this._cloneTaskGraph(graph);
-  }
-
-  /**
-   * Add a node to the existing task graph. Fails if no graph exists or if
-   * the node id already exists.
-   */
-  addTaskNode(sessionId, payload = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !session.taskGraph) return null;
-    if (!payload || !payload.id) return null;
-    const graph = session.taskGraph;
-    if (graph.nodes[payload.id]) return null;
-
-    const now = new Date().toISOString();
-    graph.nodes[payload.id] = this._normalizeTaskNode(payload, now);
-    graph.order = [...(graph.order || []), payload.id];
-    graph.updatedAt = now;
-    session.lastActivity = now;
-    this._persistSessionState(sessionId);
-    return this._cloneTaskGraph(graph);
-  }
-
-  /**
-   * Update a node's status / metadata. Valid statuses: pending, ready,
-   * running, completed, failed, skipped.
-   */
-  updateTaskNode(sessionId, nodeId, updates = {}) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !session.taskGraph) return null;
-    const graph = session.taskGraph;
-    const node = graph.nodes[nodeId];
-    if (!node) return null;
-
-    const now = new Date().toISOString();
-    if (updates.status) {
-      node.status = String(updates.status);
-      if (node.status === "running" && !node.startedAt) {
-        node.startedAt = now;
-      }
-      if (
-        node.status === "completed" ||
-        node.status === "failed" ||
-        node.status === "skipped"
-      ) {
-        node.completedAt = now;
-      }
-    }
-    if (updates.title !== undefined) node.title = updates.title;
-    if (updates.result !== undefined) node.result = updates.result;
-    if (updates.error !== undefined) node.error = updates.error;
-    if (updates.metadata !== undefined) {
-      node.metadata = { ...(node.metadata || {}), ...(updates.metadata || {}) };
-    }
-    node.updatedAt = now;
-    graph.updatedAt = now;
-
-    // Check graph completion
-    const allDone = Object.values(graph.nodes).every((n) =>
-      ["completed", "failed", "skipped"].includes(n.status),
-    );
-    if (allDone) {
-      graph.status = Object.values(graph.nodes).some(
-        (n) => n.status === "failed",
-      )
-        ? "failed"
-        : "completed";
-      graph.completedAt = now;
-    }
-
-    session.lastActivity = now;
-    this._persistSessionState(sessionId);
-    return this._cloneTaskGraph(graph);
-  }
-
-  /**
-   * Advance the task graph: mark any `pending` node whose dependencies are
-   * all `completed` (or `skipped`) as `ready`. Returns the list of node ids
-   * that became ready and the updated graph snapshot.
-   */
-  advanceTaskGraph(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !session.taskGraph) return null;
-    const graph = session.taskGraph;
-
-    const becameReady = [];
-    for (const node of Object.values(graph.nodes)) {
-      if (node.status !== "pending") continue;
-      const deps = Array.isArray(node.dependsOn) ? node.dependsOn : [];
-      const blocked = deps.some((depId) => {
-        const dep = graph.nodes[depId];
-        if (!dep) return true;
-        return dep.status !== "completed" && dep.status !== "skipped";
-      });
-      if (!blocked) {
-        node.status = "ready";
-        node.updatedAt = new Date().toISOString();
-        becameReady.push(node.id);
-      }
-    }
-
-    if (becameReady.length > 0) {
-      graph.updatedAt = new Date().toISOString();
-      session.lastActivity = graph.updatedAt;
-      this._persistSessionState(sessionId);
-    }
-
-    return {
-      graph: this._cloneTaskGraph(graph),
-      becameReady,
-    };
-  }
-
-  getTaskGraph(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !session.taskGraph) return null;
-    return this._cloneTaskGraph(session.taskGraph);
-  }
-
-  clearTaskGraph(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session) return false;
-    session.taskGraph = null;
-    session.lastActivity = new Date().toISOString();
-    this._persistSessionState(sessionId);
-    return true;
-  }
-
-  _normalizeTaskNode(raw, now) {
-    const status = raw.status || "pending";
-    return {
-      id: raw.id,
-      title: raw.title || raw.id,
-      description: raw.description || null,
-      status,
-      dependsOn: Array.isArray(raw.dependsOn)
-        ? raw.dependsOn.filter((x) => typeof x === "string")
-        : [],
-      metadata:
-        raw.metadata && typeof raw.metadata === "object" ? raw.metadata : {},
-      createdAt: raw.createdAt || now,
-      updatedAt: raw.updatedAt || now,
-      startedAt: raw.startedAt || null,
-      completedAt: raw.completedAt || null,
-      result: raw.result || null,
-      error: raw.error || null,
-    };
-  }
-
-  _cloneTaskGraph(graph) {
-    if (!graph) return null;
-    return {
-      graphId: graph.graphId,
-      title: graph.title,
-      description: graph.description,
-      status: graph.status,
-      createdAt: graph.createdAt,
-      updatedAt: graph.updatedAt,
-      completedAt: graph.completedAt,
-      order: Array.isArray(graph.order)
-        ? [...graph.order]
-        : Object.keys(graph.nodes || {}),
-      nodes: Object.fromEntries(
-        Object.entries(graph.nodes || {}).map(([id, node]) => [
-          id,
-          {
-            ...node,
-            dependsOn: [...(node.dependsOn || [])],
-            metadata: { ...(node.metadata || {}) },
-          },
-        ]),
-      ),
-    };
-  }
-
-  _hydrateTaskGraph(data) {
-    if (!data || typeof data !== "object") return null;
-    if (!data.graphId || !data.nodes) return null;
-    const nodes = {};
-    for (const [id, node] of Object.entries(data.nodes)) {
-      nodes[id] = this._normalizeTaskNode(
-        { ...node, id },
-        node.createdAt || new Date().toISOString(),
-      );
-    }
-    return {
-      graphId: data.graphId,
-      title: data.title || null,
-      description: data.description || null,
-      status: data.status || "active",
-      createdAt: data.createdAt || new Date().toISOString(),
-      updatedAt: data.updatedAt || new Date().toISOString(),
-      completedAt: data.completedAt || null,
-      order: Array.isArray(data.order) ? data.order : Object.keys(nodes),
-      nodes,
-    };
-  }
-
-  _serializeTaskGraph(graph) {
-    if (!graph) return null;
-    return this._cloneTaskGraph(graph);
-  }
-
-  /**
-   * Persist current messages for a session.
-   */
-  persistMessages(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !this.db) return;
-
-    try {
-      dbSaveMessages(
-        this.db,
-        sessionId,
-        session.messages,
-        this._serializeSessionMetadata(session),
-      );
-    } catch (_err) {
-      // Non-critical
-    }
-
-    session.lastActivity = new Date().toISOString();
-  }
-
-  _prepareSessionWorkspace(projectRoot, sessionId, options = {}) {
-    if (options.worktreeIsolation !== true) {
-      return {
-        projectRoot,
-        worktree: null,
-      };
-    }
-
-    if (!isGitRepo(projectRoot)) {
-      throw new Error(
-        `Worktree isolation requires a git repository: ${projectRoot}`,
-      );
-    }
-
-    const branchName = `coding-agent/${sessionId}`;
-    const worktree = createWorktree(projectRoot, branchName);
-
-    return {
-      projectRoot: worktree.path,
-      worktree: {
-        branch: worktree.branch,
-        path: worktree.path,
-        baseProjectRoot: projectRoot,
-      },
-    };
-  }
-
-  _persistSessionState(sessionId) {
-    const session = this.sessions.get(sessionId);
-    if (!session || !this.db) return;
-
-    try {
-      dbSaveMessages(
-        this.db,
-        sessionId,
-        session.messages,
-        this._serializeSessionMetadata(session),
-      );
-    } catch (_err) {
-      // Non-critical
-    }
-
-    session.lastActivity = new Date().toISOString();
-  }
-
-  _serializeSessionMetadata(session) {
-    return {
-      version: 1,
-      sessionType: session.type || "agent",
-      projectRoot: session.projectRoot || null,
-      baseProjectRoot: session.baseProjectRoot || session.projectRoot || null,
-      baseUrl: session.baseUrl || null,
-      hostManagedToolPolicy: session.hostManagedToolPolicy || null,
-      enabledToolNames: session.enabledToolNames || [],
-      worktreeIsolation: session.worktreeIsolation === true,
-      worktree: session.worktree || null,
-      planSnapshot: this._serializePlanManager(session.planManager),
-      reviewState: session.reviewState || null,
-      pendingPatches:
-        session.pendingPatches instanceof Map
-          ? Array.from(session.pendingPatches.values())
-          : [],
-      patchHistory: Array.isArray(session.patchHistory)
-        ? session.patchHistory
-        : [],
-      taskGraph: this._serializeTaskGraph(session.taskGraph),
-    };
-  }
-
-  _hydratePendingPatches(list) {
-    const map = new Map();
-    if (Array.isArray(list)) {
-      for (const patch of list) {
-        if (patch && patch.patchId) {
-          map.set(patch.patchId, patch);
-        }
-      }
-    }
-    return map;
-  }
-
-  _serializePlanManager(planManager) {
-    if (!planManager) {
-      return null;
-    }
-
-    return {
-      state: planManager.state || PlanState.INACTIVE,
-      currentPlan: planManager.currentPlan || null,
-      history: Array.isArray(planManager.history) ? planManager.history : [],
-      blockedToolLog: Array.isArray(planManager.blockedToolLog)
-        ? planManager.blockedToolLog
-        : [],
-    };
-  }
-
-  _normalizeSessionMetadata(metadata) {
-    if (!metadata) {
-      return {};
-    }
-
-    if (typeof metadata === "string") {
-      try {
-        return JSON.parse(metadata);
-      } catch (_err) {
-        return {};
-      }
-    }
-
-    return typeof metadata === "object" ? metadata : {};
-  }
-
-  _hydratePlanManager(snapshot) {
-    const planManager = new PlanModeManager();
-    if (!snapshot || typeof snapshot !== "object") {
-      return planManager;
-    }
-
-    planManager.state = snapshot.state || PlanState.INACTIVE;
-    planManager.currentPlan = snapshot.currentPlan
-      ? new ExecutionPlan(snapshot.currentPlan)
-      : null;
-    planManager.history = Array.isArray(snapshot.history)
-      ? snapshot.history.map((plan) => new ExecutionPlan(plan))
-      : [];
-    planManager.blockedToolLog = Array.isArray(snapshot.blockedToolLog)
-      ? [...snapshot.blockedToolLog]
-      : [];
-    return planManager;
-  }
-
-  _restoreSessionWorkspace(sessionId, baseProjectRoot, metadata = {}) {
-    const requestedWorktreeIsolation = metadata.worktreeIsolation === true;
-    const persistedWorktreePath = metadata.worktree?.path || null;
-
-    if (!requestedWorktreeIsolation) {
-      return {
-        projectRoot: metadata.projectRoot || baseProjectRoot,
-        worktree: null,
-      };
-    }
-
-    if (persistedWorktreePath && fs.existsSync(persistedWorktreePath)) {
-      return {
-        projectRoot: persistedWorktreePath,
-        worktree: {
-          ...(metadata.worktree || {}),
-          baseProjectRoot,
-        },
-      };
-    }
-
-    try {
-      return this._prepareSessionWorkspace(baseProjectRoot, sessionId, {
-        worktreeIsolation: true,
-      });
-    } catch (_err) {
-      return {
-        projectRoot: baseProjectRoot,
-        worktree: null,
-      };
-    }
-  }
-
-  _bindPlanManagerPersistence(session) {
-    if (
-      !session?.id ||
-      !session.planManager ||
-      typeof session.planManager.on !== "function"
-    ) {
-      return;
-    }
-
-    if (typeof session._planPersistenceCleanup === "function") {
-      session._planPersistenceCleanup();
-    }
-
-    const persist = () => this._persistSessionState(session.id);
-    const events = [
-      "enter",
-      "exit",
-      "item-added",
-      "plan-ready",
-      "plan-approved",
-      "tool-blocked",
-    ];
-
-    for (const eventName of events) {
-      session.planManager.on(eventName, persist);
-    }
-
-    session._planPersistenceCleanup = () => {
-      if (typeof session.planManager.off === "function") {
-        for (const eventName of events) {
-          session.planManager.off(eventName, persist);
-        }
-      }
-    };
-  }
-}
+export { WSSessionManager } from "../gateways/ws/ws-session-gateway.js";