@vibelet/cli 0.1.35 → 0.1.37

package/src/session-manager.ts

@@ -0,0 +1,1775 @@
+import type { WebSocket } from 'ws';
+import { randomUUID } from 'crypto';
+import { stat } from 'fs/promises';
+import type {
+  AgentType,
+  ApprovalRequestPayload,
+  ApprovalMode,
+  ApprovalModeOverride,
+  ClientMessage,
+  PendingApprovalSnapshot,
+  ReconnectSnapshotSession,
+  ServerMessage,
+  SessionListChangeReason,
+  SessionListPage,
+  SessionListCursor,
+} from '@vibelet/shared';
+import type { Driver } from './drivers/types.js';
+import { ClaudeDriver, isClaudeSyntheticApprovalRequestId } from './drivers/claude.js';
+import { CodexDriver } from './drivers/codex.js';
+import {
+  listSessions,
+  readSessionHistory,
+  readSessionRuntimeHints,
+  invalidateScannerCache,
+} from './scanner.js';
+import { invalidateProcessScanCache } from './process-scanner.js';
+import {
+  listSessionPage,
+  onExternalInventoryBackfill,
+  type ActiveSessionSnapshot,
+} from './session-inventory.js';
+import { SessionStore, type SessionRecord } from './session-store.js';
+import { expandPath } from './utils.js';
+import { isFallbackSessionTitle, titleFromFirstSentence } from './session-title.js';
+import { logger as rootLogger } from './logger.js';
+import { metrics } from './metrics.js';
+import { audit } from './audit.js';
+import { sendPush } from './push.js';
+import { config } from './config.js';
+import {
+  CLAUDE_HOOK_APPROVAL_PREFIX,
+  DEFAULT_CLAUDE_PERMISSION_HOOK_RESPONSE,
+  type ClaudePermissionHookData,
+  type ClaudePermissionHookResponse,
+  type ClaudeSessionHookData,
+} from './claude-hooks.js';
+
+const log = rootLogger.child({ module: 'manager' });
+const DEFAULT_PUSH_BODY = 'Done.';
+const APPROVAL_PUSH_TITLE = 'Approval required';
+const MAX_PUSH_BODY_LENGTH = 180;
+const MAX_ACCEPTED_CLIENT_MESSAGE_IDS = 200;
+
+type PushSender = (title: string, body: string, data?: Record<string, unknown>) => Promise<void> | void;
+type SyntheticApprovalRetry = {
+  message: string;
+  toolName: string;
+};
+
+type PendingApproval = ApprovalRequestPayload;
+
+type PendingClaudeHookApproval = {
+  requestId: string;
+  promise: Promise<ClaudePermissionHookResponse>;
+  resolve: (response: ClaudePermissionHookResponse) => void;
+};
+
+interface ActiveSession {
+  sessionId: string;
+  agent: AgentType;
+  cwd: string;
+  approvalMode?: ApprovalMode;
+  driver: Driver | null;
+  clients: Set<WebSocket>;
+  title: string;
+  createdAt: string;
+  lastActivityAt: string;
+  active: boolean;
+  /** Monotonic timestamp (Date.now()) of last activity, for idle timeout checks. */
+  lastActivityTs: number;
+  /** True while the driver is processing a prompt (between sendPrompt and session.done/exit). */
+  isResponding: boolean;
+  /** Accumulates the current assistant turn so push notifications can include a reply preview. */
+  currentReplyText: string;
+  /** Recently accepted client message ids so reconnect replays stay idempotent. */
+  acceptedClientMessageIds: string[];
+  /** Last prompt sent to the agent, used to recover from Claude's post-hoc permission denials. */
+  lastUserMessage?: string;
+  /** Synthetic approval requests awaiting a one-shot retry. */
+  syntheticApprovalRetries: Record<string, SyntheticApprovalRetry>;
+  /** Current pending approval request, re-sent to reconnecting clients. */
+  pendingApproval?: PendingApproval;
+  /** True while a newly created session is still completing async startup. */
+  startupInProgress: boolean;
+  /** Prompts accepted before the driver is ready to receive them. */
+  bufferedPrompts: string[];
+  /** Monotonic token used to ignore stale async startup completion. */
+  startupToken: number;
+  /** True for sessions created from the Vibelet app. */
+  managed?: boolean;
+  /** Shared secret for Claude hook bridge requests targeting this session. */
+  claudeHookSecret?: string;
+  /** Pending Claude hook approval requests waiting for user action. */
+  pendingClaudeHookApprovals: Map<string, PendingClaudeHookApproval>;
+}
+
+interface ResolvedReconnectSession {
+  agent: AgentType;
+  cwd: string;
+  approvalMode?: ApprovalMode;
+  pendingApproval?: PendingApproval;
+  title: string;
+  createdAt: string;
+  lastActivityAt: string;
+  acceptedClientMessageIds: string[];
+  source: 'memory' | 'record' | 'scanner' | 'client';
+  managed?: boolean;
+  isResponding?: boolean;
+}
+
+function mergeAcceptedClientMessageIds(...groups: Array<string[] | undefined>): string[] {
+  const merged: string[] = [];
+  for (const group of groups) {
+    if (!group?.length) continue;
+    for (const value of group) {
+      if (!value || merged.includes(value)) continue;
+      merged.push(value);
+      if (merged.length > MAX_ACCEPTED_CLIENT_MESSAGE_IDS) {
+        merged.splice(0, merged.length - MAX_ACCEPTED_CLIENT_MESSAGE_IDS);
+      }
+    }
+  }
+  return merged;
+}
+
+function acceptedClientMessageIdsPayload(acceptedClientMessageIds?: string[]): {
+  acceptedClientMessageIds?: string[];
+} {
+  return acceptedClientMessageIds?.length
+    ? { acceptedClientMessageIds: mergeAcceptedClientMessageIds(acceptedClientMessageIds) }
+    : {};
+}
+
+function buildRecord(session: ActiveSession): SessionRecord {
+  return {
+    sessionId: session.sessionId,
+    agent: session.agent,
+    cwd: session.cwd,
+    approvalMode: session.approvalMode,
+    acceptedClientMessageIds: mergeAcceptedClientMessageIds(session.acceptedClientMessageIds),
+    pendingApproval: session.agent === 'codex' ? session.pendingApproval : undefined,
+    title: session.title,
+    createdAt: session.createdAt,
+    lastActivityAt: session.lastActivityAt,
+    managed: session.managed,
+    isResponding: session.isResponding || undefined,
+  };
+}
+
+function hasSyntheticPendingApproval(session: Pick<ActiveSession, 'pendingApproval'>): boolean {
+  const requestId = session.pendingApproval?.requestId;
+  return typeof requestId === 'string' && isClaudeSyntheticApprovalRequestId(requestId);
+}
+
+function buildPendingApprovalSnapshot(
+  sessionId: string,
+  agent: AgentType,
+  pendingApproval: PendingApproval,
+): PendingApprovalSnapshot {
+  return {
+    sessionId,
+    agent,
+    ...pendingApproval,
+  };
+}
+
+function isClaudeHookApprovalRequestId(requestId: string): boolean {
+  return requestId.startsWith(CLAUDE_HOOK_APPROVAL_PREFIX);
+}
+
+function buildClaudeHookDecisionResponse(approved: boolean): ClaudePermissionHookResponse {
+  return approved
+    ? {
+        continue: true,
+        suppressOutput: true,
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'allow',
+        },
+      }
+    : {
+        continue: true,
+        suppressOutput: true,
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: 'Denied from Vibelet',
+        },
+      };
+}
+
+export class SessionManager {
+  private sessions = new Map<string, ActiveSession>();
+  private claudeHookSessions = new Map<string, ActiveSession>();
+  private store = new SessionStore();
+  private idleSweepInterval: ReturnType<typeof setInterval> | null = null;
+  /** All authenticated WebSocket clients, used for global broadcasts (e.g. approval requests). */
+  private globalClients = new Set<WebSocket>();
+  private inventoryVersion = 0;
+  private readonly removeInventoryBackfillListener: () => void;
+
+  constructor(private readonly pushSender: PushSender = sendPush) {
+    this.removeInventoryBackfillListener = onExternalInventoryBackfill(() => {
+      this.noteInventoryChanged('inventory_backfilled');
+    });
+    this.startIdleSweep();
+  }
+
+  /** Start the periodic idle-session sweep (every 60s). */
+  private startIdleSweep(): void {
+    if (config.idleTimeoutMs <= 0 && config.turnStallTimeoutMs <= 0) return;
+    this.idleSweepInterval = setInterval(() => this.sweepIdleSessions(), 60_000);
+    this.idleSweepInterval.unref();
+  }
+
+  /** Stop the idle sweep interval. */
+  private stopIdleSweep(): void {
+    if (this.idleSweepInterval) {
+      clearInterval(this.idleSweepInterval);
+      this.idleSweepInterval = null;
+    }
+  }
+
+  /** Check all active sessions and stop drivers that have been idle too long. */
+  private sweepIdleSessions(): void {
+    const now = Date.now();
+    const idleTimeoutMs = config.idleTimeoutMs;
+    const turnStallTimeoutMs = config.turnStallTimeoutMs;
+    if (idleTimeoutMs <= 0 && turnStallTimeoutMs <= 0) return;
+
+    const INACTIVE_CLEANUP_MS = 60 * 60 * 1000; // 1 hour
+
+    for (const [id, session] of this.sessions) {
+      // Clean up inactive sessions (no driver, no clients) after 1 hour
+      if (!session.active && !session.driver) {
+        if (session.clients.size === 0) {
+          const inactiveMs = now - session.lastActivityTs;
+          if (inactiveMs >= INACTIVE_CLEANUP_MS) {
+            log.info(
+              { sessionId: session.sessionId, inactiveMs },
+              'removing inactive session from memory',
+            );
+            metrics.increment('session.cleanup', { reason: 'inactive' });
+            this.unregisterClaudeHookSession(session);
+            this.sessions.delete(id);
+          }
+        }
+        continue;
+      }
+
+      if (!session.active || !session.driver) continue;
+
+      const inactiveMs = now - session.lastActivityTs;
+      if (session.isResponding) {
+        if (turnStallTimeoutMs <= 0 || session.pendingApproval) continue;
+        if (inactiveMs < turnStallTimeoutMs) continue;
+
+        log.warn(
+          {
+            sessionId: session.sessionId,
+            agent: session.agent,
+            inactiveMs,
+            turnStallTimeoutMs,
+          },
+          'stopping stalled driver',
+        );
+        metrics.increment('driver.stall_timeout', { agent: session.agent });
+        audit.emit('driver.stall_timeout', {
+          sessionId: session.sessionId,
+          agent: session.agent,
+          idleMs: inactiveMs,
+        });
+
+        // Kill the stalled driver; user's next message will auto-reconnect
+        this.resolvePendingClaudeHookApprovals(session);
+        session.driver.stop();
+        session.active = false;
+        session.driver = null;
+        session.isResponding = false;
+        session.currentReplyText = '';
+        this.updateGauges();
+        this.broadcast(session.sessionId, {
+          type: 'error',
+          sessionId: session.sessionId,
+          message: `Agent stopped responding for over ${Math.ceil(turnStallTimeoutMs / 1000)}s. Send a new message to continue.`,
+        });
+        this.touchSession(session.sessionId);
+        this.noteInventoryChanged('session_updated');
+        continue;
+      }
+
+      if (session.pendingApproval) continue;
+
+      if (idleTimeoutMs <= 0 || inactiveMs < idleTimeoutMs) continue;
+
+      log.info(
+        { sessionId: session.sessionId, agent: session.agent, idleMs: inactiveMs, timeoutMs: idleTimeoutMs },
+        'stopping idle driver',
+      );
+      metrics.increment('driver.idle_timeout', { agent: session.agent });
+      audit.emit('driver.idle_timeout', {
+        sessionId: session.sessionId,
+        agent: session.agent,
+        idleMs: inactiveMs,
+      });
+
+      session.driver.stop();
+      session.active = false;
+      session.driver = null;
+      this.updateGauges();
+      this.touchSession(session.sessionId);
+      this.noteInventoryChanged('session_updated');
+    }
+  }
+
+  private bindDriverLifecycle(session: ActiveSession, agent: AgentType, context: string, ws?: WebSocket): void {
+    session.driver?.onMessage((msg) => {
+      log.debug({ agent, context, msgType: msg.type, sessionId: session.sessionId }, 'driver message received');
+      if (
+        msg.type !== 'response'
+        && 'sessionId' in msg
+        && msg.sessionId
+        && msg.sessionId !== session.sessionId
+        && !this.sessions.has(msg.sessionId)
+      ) {
+        this.remapSessionId(session, msg.sessionId, ws);
+      }
+      if (msg.type === 'session.done' || msg.type === 'session.interrupted') {
+        session.isResponding = false;
+        if (msg.type === 'session.interrupted' || !hasSyntheticPendingApproval(session)) {
+          session.pendingApproval = undefined;
+        }
+      }
+      if (msg.type === 'approval.request') {
+        if (agent === 'codex' && session.approvalMode === 'autoApprove') {
+          const sent = session.driver?.respondApproval(msg.requestId, true) ?? false;
+          if (sent) {
+            audit.emit('approval.response', { sessionId: session.sessionId, requestId: msg.requestId, approved: true });
+            session.pendingApproval = undefined;
+            session.isResponding = true;
+            this.touchSession(session.sessionId);
+            this.noteInventoryChanged('session_updated');
+            return;
+          }
+          log.warn({ sessionId: session.sessionId, requestId: msg.requestId }, 'failed to auto-approve codex request; falling back to pending approval flow');
+        }
+        session.isResponding = false;
+        session.pendingApproval = {
+          requestId: msg.requestId,
+          toolName: msg.toolName,
+          input: msg.input,
+          description: msg.description,
+          ...(msg.approvalContext ? { approvalContext: msg.approvalContext } : {}),
+        };
+        void this.pushSender(
+          APPROVAL_PUSH_TITLE,
+          this.buildPushBody(`${session.title || session.sessionId}: ${msg.description || msg.toolName}`),
+          {
+            sessionId: session.sessionId,
+            agent: session.agent,
+            requestId: msg.requestId,
+            eventType: 'approval_request',
+          },
+        );
+      }
+      if (agent === 'claude' && msg.type === 'approval.request' && isClaudeSyntheticApprovalRequestId(msg.requestId)) {
+        if (session.lastUserMessage) {
+          session.syntheticApprovalRetries[msg.requestId] = {
+            message: session.lastUserMessage,
+            toolName: msg.toolName,
+          };
+        } else {
+          log.warn({ sessionId: session.sessionId, requestId: msg.requestId }, 'missing lastUserMessage for synthetic approval retry');
+        }
+      }
+      this.touchSession(session.sessionId, msg.type !== 'text.delta');
+      if (msg.type === 'approval.request' || msg.type === 'session.done' || msg.type === 'session.interrupted') {
+        this.noteInventoryChanged('session_updated');
+      }
+      this.broadcast(session.sessionId, msg);
+      if ((msg.type === 'session.done' || msg.type === 'session.interrupted') && session.bufferedPrompts.length > 0) {
+        this.flushBufferedPrompt(session);
+      }
+    });
+
+    session.driver?.onExit?.((code) => {
+      log.info({ agent, context, exitCode: code, sessionId: session.sessionId }, 'driver exited');
+      audit.emit('driver.exit', { sessionId: session.sessionId, agent, exitCode: code });
+      metrics.increment('driver.exit', { agent, abnormal: code && code !== 0 ? 'true' : 'false' });
+      const preservePendingApproval = Boolean(session.pendingApproval && (
+        session.agent === 'codex' || (code === 0 && hasSyntheticPendingApproval(session))
+      ));
+      this.resolvePendingClaudeHookApprovals(session);
+      session.active = false;
+      session.driver = null;
+      session.isResponding = false;
+      session.currentReplyText = '';
+      if (!preservePendingApproval) {
+        session.pendingApproval = undefined;
+      }
+      this.updateGauges();
+      this.touchSession(session.sessionId);
+      this.noteInventoryChanged('session_updated');
+    });
+  }
+
+  private remapSessionId(session: ActiveSession, newSessionId: string, ws?: WebSocket): void {
+    if (!newSessionId || newSessionId === session.sessionId) return;
+    const existing = this.sessions.get(newSessionId);
+    if (existing && existing !== session) {
+      log.warn({ oldSessionId: session.sessionId, newSessionId }, 'skipping session ID remap because target already exists');
+      return;
+    }
+    const oldId = session.sessionId;
+    log.info({ oldSessionId: oldId, newSessionId }, 'session ID updated');
+    this.store.remove(oldId);
+    this.sessions.delete(oldId);
+    session.sessionId = newSessionId;
+    this.sessions.set(newSessionId, session);
+    this.store.upsert(buildRecord(session));
+    this.noteInventoryChanged('session_remapped');
+    if (ws) {
+      this.reply(ws, `id_update_${Date.now()}`, true, { sessionId: newSessionId, oldSessionId: oldId });
+    }
+  }
+
+  private flushBufferedPrompt(session: ActiveSession, force = false): boolean {
+    if (!session.driver || !session.active || session.startupInProgress || session.pendingApproval) {
+      return false;
+    }
+    if (!force && session.isResponding) {
+      return false;
+    }
+    const nextPrompt = session.bufferedPrompts.shift();
+    if (!nextPrompt) {
+      return false;
+    }
+    session.isResponding = true;
+    session.currentReplyText = '';
+    session.lastUserMessage = nextPrompt;
+    this.touchSession(session.sessionId);
+    this.noteInventoryChanged('session_updated');
+    session.driver.sendPrompt(nextPrompt);
+    return true;
+  }
+
+  private startPendingCodexSession(session: ActiveSession, ws: WebSocket): void {
+    if (session.agent !== 'codex' || !session.driver) {
+      return;
+    }
+    const driver = session.driver;
+    const pendingSessionId = session.sessionId;
+    const startToken = session.startupToken;
+    const endTimer = metrics.startTimer('driver.spawn');
+    void (async () => {
+      try {
+        const actualSessionId = await driver.start(session.cwd, undefined, session.approvalMode);
+        const spawnMs = endTimer();
+        const current = this.sessions.get(pendingSessionId);
+        if (current !== session || session.startupToken !== startToken || session.driver !== driver) {
+          log.info({ pendingSessionId, actualSessionId }, 'discarding stale codex startup result');
+          return;
+        }
+        session.startupInProgress = false;
+        log.info({ pendingSessionId, sessionId: actualSessionId, spawnMs }, 'codex session ready');
+        if (actualSessionId && actualSessionId !== pendingSessionId) {
+          this.remapSessionId(session, actualSessionId, ws);
+        }
+        this.flushBufferedPrompt(session, true);
+      } catch (e) {
+        endTimer();
+        const current = this.sessions.get(pendingSessionId);
+        if (current !== session || session.startupToken !== startToken) {
+          log.info({ pendingSessionId, error: String(e) }, 'ignoring stale codex startup failure');
+          return;
+        }
+        session.startupInProgress = false;
+        session.bufferedPrompts = [];
+        session.active = false;
+        session.driver = null;
+        session.isResponding = false;
+        session.currentReplyText = '';
+        this.updateGauges();
+        this.touchSession(session.sessionId);
+        this.noteInventoryChanged('session_updated');
+        log.error({ sessionId: pendingSessionId, cwd: session.cwd, error: String(e) }, 'async codex createSession error');
+        this.broadcast(session.sessionId, {
+          type: 'error',
+          sessionId: session.sessionId,
+          message: `Failed to start Codex session: ${String(e)}`,
+        });
+      }
+    })();
+  }
+
+  private configureDriverBeforeStart(agent: AgentType, driver: Driver, existingSecret?: string): string | undefined {
+    if (agent !== 'claude' || !(driver instanceof ClaudeDriver)) return undefined;
+    const secret = existingSecret ?? randomUUID().replace(/-/g, '');
+    driver.configureHookBridge(config.port, secret);
+    return secret;
+  }
+
+  private registerClaudeHookSession(session: ActiveSession): void {
+    if (session.agent !== 'claude' || !session.claudeHookSecret) return;
+    this.claudeHookSessions.set(session.claudeHookSecret, session);
+  }
+
+  private unregisterClaudeHookSession(session: ActiveSession): void {
+    if (session.agent !== 'claude' || !session.claudeHookSecret) return;
+    const current = this.claudeHookSessions.get(session.claudeHookSecret);
+    if (current === session) {
+      this.claudeHookSessions.delete(session.claudeHookSecret);
+    }
+  }
+
+  private resolvePendingClaudeHookApprovals(
+    session: ActiveSession,
+    response: ClaudePermissionHookResponse = DEFAULT_CLAUDE_PERMISSION_HOOK_RESPONSE,
+  ): void {
+    for (const pending of session.pendingClaudeHookApprovals.values()) {
+      pending.resolve(response);
+    }
+    session.pendingClaudeHookApprovals.clear();
+    if (session.pendingApproval && isClaudeHookApprovalRequestId(session.pendingApproval.requestId)) {
+      session.pendingApproval = undefined;
+    }
+  }
+
+  private resolveClaudeHookSession(secret?: string | null): ActiveSession | undefined {
+    if (!secret) return undefined;
+    const normalized = secret.trim();
+    if (!normalized) return undefined;
+    return this.claudeHookSessions.get(normalized);
+  }
+
+  handleClaudeSessionStartHook(secret: string | null | undefined, _data: ClaudeSessionHookData): boolean {
+    const session = this.resolveClaudeHookSession(secret);
+    if (!session) {
+      log.warn({ secretPresent: Boolean(secret) }, 'received Claude session-start hook for unknown session');
+      return false;
+    }
+    this.touchSession(session.sessionId);
+    return true;
+  }
+
+  async handleClaudePermissionHook(
+    secret: string | null | undefined,
+    data: ClaudePermissionHookData,
+  ): Promise<ClaudePermissionHookResponse> {
+    const session = this.resolveClaudeHookSession(secret);
+    if (!session || session.agent !== 'claude' || !session.active) {
+      log.warn({ secretPresent: Boolean(secret) }, 'received Claude permission hook for unknown or inactive session');
+      return DEFAULT_CLAUDE_PERMISSION_HOOK_RESPONSE;
+    }
+
+    if (session.approvalMode === 'autoApprove') {
+      return buildClaudeHookDecisionResponse(true);
+    }
+
+    const rawToolName = typeof data.tool_name === 'string'
+      ? data.tool_name
+      : typeof data.toolName === 'string'
+        ? data.toolName
+        : '';
+    const toolName = rawToolName.trim();
+    if (!toolName) {
+      return DEFAULT_CLAUDE_PERMISSION_HOOK_RESPONSE;
+    }
+
+    const toolInput = data.tool_input ?? data.toolInput;
+    const input = toolInput && typeof toolInput === 'object' && !Array.isArray(toolInput)
+      ? toolInput as Record<string, unknown>
+      : {};
+    const rawToolUseId = typeof data.tool_use_id === 'string'
+      ? data.tool_use_id
+      : typeof data.toolUseId === 'string'
+        ? data.toolUseId
+        : '';
+    const requestId = `${CLAUDE_HOOK_APPROVAL_PREFIX}${rawToolUseId.trim() || randomUUID()}`;
+    const existing = session.pendingClaudeHookApprovals.get(requestId);
+    if (existing) {
+      return existing.promise;
+    }
+
+    const description = `Claude requested permissions to use ${toolName}.`;
+    let resolvePending!: (response: ClaudePermissionHookResponse) => void;
+    const promise = new Promise<ClaudePermissionHookResponse>((resolve) => {
+      resolvePending = resolve;
+    });
+    session.pendingClaudeHookApprovals.set(requestId, {
+      requestId,
+      promise,
+      resolve: (response) => {
+        session.pendingClaudeHookApprovals.delete(requestId);
+        resolvePending(response);
+      },
+    });
+
+    session.pendingApproval = {
+      requestId,
+      toolName,
+      input,
+      description,
+    };
+    audit.emit('approval.request', { agent: 'claude', sessionId: session.sessionId, toolName });
+    this.touchSession(session.sessionId);
+    this.noteInventoryChanged('session_updated');
+    this.broadcast(session.sessionId, {
+      type: 'approval.request',
+      sessionId: session.sessionId,
+      requestId,
+      toolName,
+      input,
+      description,
+    });
+
+    return promise;
+  }
+
+  private async resolveReconnectSession(
+    sessionId: string,
+    fallbackAgent?: AgentType,
+    existingSession?: ActiveSession,
+  ): Promise<ResolvedReconnectSession | undefined> {
+    if (this.isDeletedSession(sessionId)) {
+      return undefined;
+    }
+
+    const now = new Date().toISOString();
+    let resolvedAgent = existingSession?.agent;
+    let resolvedCwd = existingSession?.cwd ?? '';
+    let resolvedApprovalMode = existingSession?.approvalMode;
+    let resolvedPendingApproval = existingSession?.pendingApproval;
+    let resolvedTitle = existingSession?.title ?? '';
+    let resolvedCreatedAt = existingSession?.createdAt ?? now;
+    let resolvedLastActivityAt = existingSession?.lastActivityAt ?? now;
+    let resolvedAcceptedClientMessageIds = mergeAcceptedClientMessageIds(existingSession?.acceptedClientMessageIds);
+    let resolvedIsResponding = existingSession?.isResponding;
+    let source: ResolvedReconnectSession['source'] = existingSession ? 'memory' : 'client';
+
+    const record = this.store.find(sessionId);
+    if (record) {
+      resolvedAgent = record.agent;
+      resolvedCwd = record.cwd || resolvedCwd;
+      resolvedApprovalMode = record.approvalMode ?? resolvedApprovalMode;
+      resolvedPendingApproval = record.pendingApproval ?? resolvedPendingApproval;
+      resolvedTitle = record.title || resolvedTitle;
+      resolvedCreatedAt = record.createdAt || resolvedCreatedAt;
+      resolvedLastActivityAt = record.lastActivityAt || resolvedLastActivityAt;
+      resolvedAcceptedClientMessageIds = mergeAcceptedClientMessageIds(
+        record.acceptedClientMessageIds,
+        resolvedAcceptedClientMessageIds,
+      );
+      source = 'record';
+    } else if (!existingSession) {
+      const scanned = await listSessions(fallbackAgent ?? resolvedAgent);
+      const found = scanned.find((candidate) => candidate.sessionId === sessionId);
+      if (found) {
+        resolvedAgent = found.agent;
+        resolvedCwd = found.cwd || resolvedCwd;
+        resolvedTitle = found.title ?? resolvedTitle;
+        resolvedCreatedAt = found.createdAt;
+        resolvedLastActivityAt = found.lastActivityAt;
+        resolvedIsResponding = found.runtime.isResponding ?? resolvedIsResponding;
+        source = 'scanner';
+      }
+    }
+
+    if (!resolvedAgent && fallbackAgent) {
+      resolvedAgent = fallbackAgent;
+      source = existingSession ? 'memory' : 'client';
+    }
+
+    if (!resolvedAgent) {
+      return undefined;
+    }
+
+    return {
+      agent: resolvedAgent,
+      cwd: resolvedCwd,
+      approvalMode: resolvedApprovalMode,
+      pendingApproval: resolvedPendingApproval,
+      title: resolvedTitle,
+      createdAt: resolvedCreatedAt,
+      lastActivityAt: resolvedLastActivityAt,
+      acceptedClientMessageIds: resolvedAcceptedClientMessageIds,
+      source,
+      managed: existingSession?.managed ?? record?.managed,
+      isResponding: resolvedIsResponding || undefined,
+    };
+  }
+
+  private collectReconnectPendingApprovals(): PendingApprovalSnapshot[] {
+    const approvals: PendingApprovalSnapshot[] = [];
+    const seen = new Set<string>();
+
+    for (const session of this.sessions.values()) {
+      if (!session.pendingApproval) continue;
+      const key = `${session.agent}:${session.sessionId}:${session.pendingApproval.requestId}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      approvals.push(buildPendingApprovalSnapshot(session.sessionId, session.agent, session.pendingApproval));
+    }
+
+    for (const record of this.store.getAll()) {
+      if (!record.pendingApproval) continue;
+      const key = `${record.agent}:${record.sessionId}:${record.pendingApproval.requestId}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      approvals.push(buildPendingApprovalSnapshot(record.sessionId, record.agent, record.pendingApproval));
+    }
+
+    return approvals;
+  }
+
+  private restoreDriverPendingApproval(driver: Driver, pendingApproval: PendingApproval | undefined): void {
+    if (!pendingApproval) return;
+    driver.restorePendingApproval?.(pendingApproval);
+  }
+
+  private async reviveSessionForApproval(session: ActiveSession): Promise<boolean> {
+    if (session.driver) return true;
+    if (!session.pendingApproval || session.agent !== 'codex') return false;
+
+    const driver = this.createDriver(session.agent);
+    const claudeHookSecret = this.configureDriverBeforeStart(session.agent, driver, session.claudeHookSecret);
+    await driver.start(session.cwd, session.sessionId, session.approvalMode);
+    this.restoreDriverPendingApproval(driver, session.pendingApproval);
+
+    session.driver = driver;
+    session.active = true;
+    session.isResponding = false;
+    session.currentReplyText = '';
+    session.startupInProgress = false;
+    session.bufferedPrompts = session.bufferedPrompts ?? [];
+    session.startupToken = session.startupToken ?? 0;
+    session.claudeHookSecret = claudeHookSecret ?? session.claudeHookSecret;
+    session.pendingClaudeHookApprovals = session.pendingClaudeHookApprovals ?? new Map();
+
+    this.registerClaudeHookSession(session);
+    this.bindDriverLifecycle(session, session.agent, ' (approval resumed)');
+    this.store.upsert(buildRecord(session));
+    this.updateGauges();
+    this.touchSession(session.sessionId);
+    this.noteInventoryChanged('session_updated');
+    return true;
+  }
+
+  private buildPushBody(replyText: string): string {
+    const collapsed = replyText.replace(/\s+/g, ' ').trim();
+    if (!collapsed) return DEFAULT_PUSH_BODY;
+    if (collapsed.length <= MAX_PUSH_BODY_LENGTH) return collapsed;
+    return `${collapsed.slice(0, Math.max(1, MAX_PUSH_BODY_LENGTH - 3)).trimEnd()}...`;
+  }
+
+  private currentPartialReplyText(session?: Pick<ActiveSession, 'isResponding' | 'currentReplyText'>): string | undefined {
+    if (!session?.isResponding) return undefined;
+    const partial = session.currentReplyText.trim();
+    return partial ? session.currentReplyText : undefined;
+  }
+
+  private touchSession(sessionId: string, persist = true): void {
+    const now = new Date().toISOString();
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.lastActivityAt = now;
+      session.lastActivityTs = Date.now();
+      if (persist) {
+        this.store.upsert(buildRecord(session));
+      }
+      return;
+    }
+
+    const record = this.store.find(sessionId);
+    if (record) {
+      this.store.upsert({ ...record, lastActivityAt: now });
+    }
+  }
+
+  private updateGauges(): void {
+    let active = 0;
+    for (const s of this.sessions.values()) {
+      if (s.active) active++;
+    }
+    metrics.gauge('session.active', active);
+  }
+
+  private activeSessionSnapshots(): ActiveSessionSnapshot[] {
+    const snapshots: ActiveSessionSnapshot[] = [];
+    for (const session of this.sessions.values()) {
+      if (session.sessionId.startsWith('pending_')) continue;
+      if (!session.active) continue;
+      snapshots.push({
+        sessionId: session.sessionId,
+        agent: session.agent,
+        cwd: session.cwd,
+        approvalMode: session.approvalMode,
+        title: session.title,
+        createdAt: session.createdAt,
+        lastActivityAt: session.lastActivityAt,
+        ...(session.pendingApproval ? { needsAttention: true } : {}),
+        ...(session.isResponding ? { isResponding: true } : {}),
+        managed: session.managed,
+      });
+    }
+    return snapshots;
+  }
+
+  private getDeletedSessionIds(): Set<string> {
+    return new Set(this.store.getDeletedSessionIds());
+  }
+
+  private isDeletedSession(sessionId: string): boolean {
+    return this.store.isDeleted(sessionId);
+  }
+
+  private async listRecentSessionsForContinue(agent: AgentType, cwd: string) {
+    return listSessions(agent, cwd);
+  }
+
+  async handle(ws: WebSocket, msg: ClientMessage): Promise<void> {
+    log.debug({ action: msg.action }, 'handling client message');
+    switch (msg.action) {
+      case 'session.create':
+        await this.createSession(ws, msg.id, msg.agent, msg.cwd, msg.approvalMode, msg.continueSession);
+        break;
+      case 'session.resume':
+        await this.resumeSession(ws, msg.id, msg.sessionId, msg.agent);
+        break;
+      case 'session.send':
+        await this.sendMessage(ws, msg.id, msg.sessionId, msg.message, msg.agent, msg.clientMessageId, msg.images);
+        break;
+      case 'session.approve':
+        await this.approve(ws, msg.id, msg.sessionId, msg.requestId, msg.approved);
+        break;
+      case 'session.setApprovalMode':
+        await this.setApprovalMode(ws, msg.id, msg.sessionId, msg.approvalMode);
+        break;
+      case 'session.interrupt':
+        this.interrupt(ws, msg.id, msg.sessionId);
+        break;
+      case 'session.stop':
+        this.stopSession(ws, msg.id, msg.sessionId);
+        break;
+      case 'session.delete':
+        this.deleteSession(ws, msg.id, msg.sessionId);
+        break;
+      case 'session.history':
+        await this.sendHistory(ws, msg.id, msg.sessionId, msg.agent);
+        break;
+      case 'reconnect.snapshot':
+        await this.sendReconnectSnapshot(ws, msg.id, msg.agent, msg.cwd, msg.search, msg.activeSessionId, msg.activeAgent);
+        break;
+      case 'sessions.list':
+        await this.listSessions(ws, msg.id, msg.agent, msg.cwd, msg.search, msg.limit, msg.cursor);
+        break;
+    }
+  }
+
+  addGlobalClient(ws: WebSocket): void {
+    this.globalClients.add(ws);
+  }
+
+  removeClient(ws: WebSocket): void {
+    this.globalClients.delete(ws);
+    for (const session of this.sessions.values()) {
+      session.clients.delete(ws);
+    }
+  }
+
+  shutdown(): void {
+    this.stopIdleSweep();
+    this.removeInventoryBackfillListener();
+    this.globalClients.clear();
+    for (const session of this.sessions.values()) {
+      try {
+        this.resolvePendingClaudeHookApprovals(session);
+        session.driver?.stop();
+      } catch (e) {
+        log.error({ sessionId: session.sessionId, agent: session.agent, error: String(e) }, 'failed to stop session on shutdown');
+      }
+      session.active = false;
+      session.driver = null;
+      session.clients.clear();
+      this.unregisterClaudeHookSession(session);
+    }
+    this.claudeHookSessions.clear();
+    this.store.flushSync();
+  }
+
+  /** Expose active session count for health endpoint. */
+  getActiveSessionCount(): number {
+    let count = 0;
+    for (const s of this.sessions.values()) {
+      if (s.active) count++;
+    }
+    return count;
+  }
+
+  /** Fire-and-forget cache warm so the next reconnect.snapshot is fast. */
+  prewarmCaches(): void {
+    void listSessionPage({
+      limit: 50,
+      activeSessions: this.activeSessionSnapshots(),
+      sessionRecords: this.store.getAll(),
+      deletedSessionIds: this.getDeletedSessionIds(),
+    }).catch(() => {});
+  }
+
+  /** Expose driver breakdown for health endpoint. */
+  getDriverCounts(): Record<string, number> {
+    const counts: Record<string, number> = {};
+    for (const s of this.sessions.values()) {
+      if (s.active) {
+        counts[s.agent] = (counts[s.agent] ?? 0) + 1;
+      }
+    }
+    return counts;
+  }
+
+  private noteInventoryChanged(reason: SessionListChangeReason): void {
+    this.inventoryVersion += 1;
+    if (this.globalClients.size === 0) {
+      return;
+    }
+
+    const msg: ServerMessage = {
+      type: 'sessions.changed',
+      version: this.inventoryVersion,
+      reason,
+    };
+    const data = JSON.stringify(msg);
+    for (const client of this.globalClients) {
+      if (client.readyState === 1) {
+        client.send(data);
+      }
+    }
+  }
+
+  private async createSession(ws: WebSocket, reqId: string, agent: AgentType, cwd: string, approvalMode?: ApprovalMode, continueSession?: boolean): Promise<void> {
+    cwd = expandPath(cwd);
+    log.info({ agent, cwd, approvalMode, continueSession }, 'creating session');
+
+    // Validate that the working directory exists and is a directory
+    try {
+      const cwdStat = await stat(cwd);
+      if (!cwdStat.isDirectory()) {
+        this.reply(ws, reqId, false, undefined, `Path is not a directory: ${cwd}`);
+        return;
+      }
+    } catch {
+      this.reply(ws, reqId, false, undefined, `Directory does not exist: ${cwd}`);
+      return;
+    }
+
+    // For "continue last" mode, find the most recent session and resume it
+    if (continueSession) {
+      try {
+        const recentSessions = await this.listRecentSessionsForContinue(agent, cwd);
+        const lastSession = recentSessions.find((session) => !this.isDeletedSession(session.sessionId));
+        if (lastSession) {
+          log.info({ sessionId: lastSession.sessionId, cwd }, 'continue mode: resuming last session');
+          return this.resumeSession(ws, reqId, lastSession.sessionId, agent, cwd, approvalMode);
+        }
+        log.info('continue mode: no previous sessions found, creating new');
+      } catch (e) {
+        log.warn({ error: String(e) }, 'continue mode: error finding sessions, creating new');
+      }
+    }
+
+    try {
+      const driver = this.createDriver(agent);
+      const claudeHookSecret = this.configureDriverBeforeStart(agent, driver);
+      if (agent === 'codex') {
+        const sessionId = `pending_${Date.now()}`;
+        log.info({ sessionId, agent, cwd }, 'session created (pending codex startup)');
+        metrics.increment('session.create', { agent });
+        audit.emit('session.create', { sessionId, agent, cwd, approvalMode });
+
+        const session: ActiveSession = {
+          sessionId,
+          agent,
+          cwd,
+          approvalMode,
+          driver,
+          clients: new Set([ws]),
+          title: 'New session',
+          createdAt: new Date().toISOString(),
+          lastActivityAt: new Date().toISOString(),
+          active: true,
+          lastActivityTs: Date.now(),
+          isResponding: false,
+          currentReplyText: '',
+          acceptedClientMessageIds: [],
+          syntheticApprovalRetries: {},
+          startupInProgress: true,
+          bufferedPrompts: [],
+          startupToken: 1,
+          managed: true,
+          claudeHookSecret,
+          pendingClaudeHookApprovals: new Map(),
+        };
+        this.sessions.set(sessionId, session);
+        this.registerClaudeHookSession(session);
+        this.store.upsert(buildRecord(session));
+        this.updateGauges();
+        invalidateScannerCache();
+        invalidateProcessScanCache();
+        this.noteInventoryChanged('session_created');
+
+        this.bindDriverLifecycle(session, agent, '', ws);
+
+        this.reply(ws, reqId, true, { sessionId });
+        this.startPendingCodexSession(session, ws);
+        return;
+      }
+
+      const endTimer = metrics.startTimer('driver.spawn');
+      const sessionId = await driver.start(cwd, undefined, approvalMode);
+      const spawnMs = endTimer();
+      log.info({ sessionId, agent, spawnMs }, 'session created');
+
+      metrics.increment('session.create', { agent });
+      audit.emit('session.create', { sessionId, agent, cwd, approvalMode });
+
+      const session: ActiveSession = {
+        sessionId,
+        agent,
+        cwd,
+        approvalMode,
+        driver,
+        clients: new Set([ws]),
+        title: 'New session',
+        createdAt: new Date().toISOString(),
+        lastActivityAt: new Date().toISOString(),
+        active: true,
+        lastActivityTs: Date.now(),
+        isResponding: false,
+        currentReplyText: '',
+        acceptedClientMessageIds: [],
+        syntheticApprovalRetries: {},
+        startupInProgress: false,
+        bufferedPrompts: [],
+        startupToken: 0,
+        managed: true,
+        claudeHookSecret,
+        pendingClaudeHookApprovals: new Map(),
+      };
+      this.sessions.set(sessionId, session);
+      this.registerClaudeHookSession(session);
+      this.store.upsert(buildRecord(session));
+      this.updateGauges();
+      invalidateScannerCache();
+      invalidateProcessScanCache();
+      this.noteInventoryChanged('session_created');
+
+      this.bindDriverLifecycle(session, agent, '', ws);
+
+      this.reply(ws, reqId, true, { sessionId });
+    } catch (e) {
+      log.error({ agent, cwd, error: String(e) }, 'createSession error');
+      this.reply(ws, reqId, false, undefined, String(e));
+    }
+  }
+
+  private async resumeSession(
+    ws: WebSocket,
+    reqId: string,
+    sessionId: string,
+    agent: AgentType,
+    cwdOverride?: string,
+    approvalMode?: ApprovalMode,
+  ): Promise<void> {
+    if (this.isDeletedSession(sessionId)) {
+      this.reply(ws, reqId, false, undefined, 'Session not found');
+      return;
+    }
+
+    // If already active, just attach client
+    const existing = this.sessions.get(sessionId);
+    if (existing && existing.active) {
+      existing.clients.add(ws);
+      this.touchSession(existing.sessionId);
+      this.noteInventoryChanged('session_updated');
+      // Send history
+      const history = await readSessionHistory(sessionId, agent, existing.cwd);
+      const partialReplyText = this.currentPartialReplyText(existing);
+      if (history.length > 0 || partialReplyText || existing.approvalMode || existing.pendingApproval) {
+        const historyMsg: ServerMessage = {
+          type: 'session.history',
+          sessionId,
+          messages: history,
+          ...acceptedClientMessageIdsPayload(existing.acceptedClientMessageIds),
+          isResponding: existing.isResponding || undefined,
+          partialReplyText,
+          approvalMode: existing.approvalMode,
+          pendingApproval: existing.pendingApproval,
+        };
+        if (ws.readyState === 1) {
+          ws.send(JSON.stringify(historyMsg));
+        }
+      }
+      this.reply(ws, reqId, true, { sessionId });
+      return;
+    }
+
+    // Find persisted record for cwd/title
+    const record = this.store.find(sessionId);
+    const cwd = cwdOverride || record?.cwd || '';
+    const sessionApprovalMode = approvalMode ?? record?.approvalMode;
+    const title = record?.title ?? 'Resumed session';
+
+    try {
+      const endTimer = metrics.startTimer('driver.spawn');
+      const driver = this.createDriver(agent);
+      const claudeHookSecret = this.configureDriverBeforeStart(agent, driver);
+      const actualSessionId = await driver.start(cwd, sessionId, sessionApprovalMode);
+      const spawnMs = endTimer();
+      log.info({ sessionId: actualSessionId, agent, spawnMs }, 'session resumed');
+
+      metrics.increment('session.resume', { agent });
+      audit.emit('session.resume', { sessionId: actualSessionId, agent, cwd });
+
+      const session: ActiveSession = {
+        sessionId: actualSessionId, agent, cwd, approvalMode: sessionApprovalMode, driver,
+        clients: new Set([ws]),
+        title,
+        createdAt: record?.createdAt ?? new Date().toISOString(),
+        lastActivityAt: new Date().toISOString(),
+        active: true,
+        lastActivityTs: Date.now(),
+        isResponding: false,
+        currentReplyText: '',
+        acceptedClientMessageIds: record?.acceptedClientMessageIds ?? [],
+        syntheticApprovalRetries: {},
+        startupInProgress: false,
+        bufferedPrompts: [],
+        startupToken: 0,
+        managed: record?.managed,
+        pendingApproval: record?.pendingApproval,
+        claudeHookSecret,
+        pendingClaudeHookApprovals: new Map(),
+      };
+      this.sessions.set(actualSessionId, session);
+      this.registerClaudeHookSession(session);
+      this.store.upsert(buildRecord(session));
+      this.updateGauges();
+      this.noteInventoryChanged('session_updated');
+
+      this.bindDriverLifecycle(session, agent, ' (resumed)', ws);
+      this.restoreDriverPendingApproval(driver, session.pendingApproval);
+
+      // Send history from session file
+      const history = await readSessionHistory(sessionId, agent, cwd);
+      if (history.length > 0 || session.pendingApproval) {
+        log.info({ sessionId, historyCount: history.length }, 'sending history messages');
+        const historyMsg: ServerMessage = {
+          type: 'session.history',
+          sessionId: actualSessionId,
+          messages: history,
+          ...acceptedClientMessageIdsPayload(session.acceptedClientMessageIds),
+          approvalMode: sessionApprovalMode,
+          pendingApproval: session.pendingApproval,
+        };
+        if (ws.readyState === 1) {
+          ws.send(JSON.stringify(historyMsg));
+        }
+      }
+
+      this.reply(ws, reqId, true, { sessionId: actualSessionId });
+    } catch (e) {
+      this.reply(ws, reqId, false, undefined, String(e));
+    }
+  }
+
+  private hasAcceptedClientMessage(session: ActiveSession, clientMessageId: string): boolean {
+    return session.acceptedClientMessageIds.includes(clientMessageId);
+  }
+
+  private rememberAcceptedClientMessage(session: ActiveSession, clientMessageId: string): void {
+    if (this.hasAcceptedClientMessage(session, clientMessageId)) return;
+    session.acceptedClientMessageIds.push(clientMessageId);
+    if (session.acceptedClientMessageIds.length > MAX_ACCEPTED_CLIENT_MESSAGE_IDS) {
+      session.acceptedClientMessageIds.splice(
+        0,
+        session.acceptedClientMessageIds.length - MAX_ACCEPTED_CLIENT_MESSAGE_IDS,
+      );
+    }
+  }
+
+  private async sendMessage(
+    ws: WebSocket,
+    reqId: string,
+    sessionId: string,
+    message: string,
+    agent?: AgentType,
+    clientMessageId?: string,
+    images?: string[],
+  ): Promise<void> {
+    if (this.isDeletedSession(sessionId)) {
+      this.reply(ws, reqId, false, undefined, 'Session not found');
+      return;
+    }
+
+    let session = this.sessions.get(sessionId);
+
+    // Auto-reconnect: if session not found or inactive, try to resume it
+    if (!session || !session.driver) {
+      const reconnect = await this.resolveReconnectSession(sessionId, agent, session);
+      if (!reconnect) {
+        log.warn({ sessionId }, 'session not found in records or scanner');
+        this.reply(ws, reqId, false, undefined, 'Session not found');
+        return;
+      }
+
+      log.info({ sessionId, agent: reconnect.agent, source: reconnect.source }, 'auto-reconnecting session');
+      metrics.increment('session.reconnect', { agent: reconnect.agent, source: reconnect.source });
+      audit.emit('session.reconnect', { sessionId, agent: reconnect.agent, source: reconnect.source });
+
+      try {
+        const driver = this.createDriver(reconnect.agent);
+        const claudeHookSecret = this.configureDriverBeforeStart(reconnect.agent, driver, session?.claudeHookSecret);
+        await driver.start(reconnect.cwd, sessionId, reconnect.approvalMode);
+        this.restoreDriverPendingApproval(driver, reconnect.pendingApproval);
+
+        if (session) {
+          session.approvalMode = reconnect.approvalMode;
+          session.pendingApproval = reconnect.pendingApproval;
+          session.driver = driver;
+          session.active = true;
+          session.clients.add(ws);
+          session.lastActivityAt = reconnect.lastActivityAt;
+          session.lastActivityTs = Date.now();
+          session.isResponding = false;
+          session.currentReplyText = '';
+          session.acceptedClientMessageIds = mergeAcceptedClientMessageIds(
+            session.acceptedClientMessageIds,
+            reconnect.acceptedClientMessageIds,
+          );
+          session.syntheticApprovalRetries = session.syntheticApprovalRetries ?? {};
+          session.startupInProgress = false;
+          session.bufferedPrompts = session.bufferedPrompts ?? [];
+          session.startupToken = session.startupToken ?? 0;
+          session.claudeHookSecret = claudeHookSecret ?? session.claudeHookSecret;
+          session.pendingClaudeHookApprovals = session.pendingClaudeHookApprovals ?? new Map();
+        } else {
+          session = {
+            sessionId,
+            agent: reconnect.agent,
+            cwd: reconnect.cwd,
+            approvalMode: reconnect.approvalMode,
+            driver,
+            clients: new Set([ws]),
+            title: reconnect.title,
+            createdAt: reconnect.createdAt,
+            lastActivityAt: reconnect.lastActivityAt,
+            active: true,
+            lastActivityTs: Date.now(),
+            isResponding: false,
+            currentReplyText: '',
+            acceptedClientMessageIds: reconnect.acceptedClientMessageIds,
+            syntheticApprovalRetries: {},
+            startupInProgress: false,
+            bufferedPrompts: [],
+            startupToken: 0,
+            managed: reconnect.managed,
+            pendingApproval: reconnect.pendingApproval,
+            claudeHookSecret,
+            pendingClaudeHookApprovals: new Map(),
+          };
+          this.sessions.set(sessionId, session);
+        }
+
+        this.registerClaudeHookSession(session);
+        this.bindDriverLifecycle(session, reconnect.agent, ' (reconnected)');
+        this.store.upsert(buildRecord(session));
+        this.updateGauges();
+        this.noteInventoryChanged('session_updated');
+      } catch (e) {
+        this.reply(ws, reqId, false, undefined, `Failed to reconnect: ${e}`);
+        return;
+      }
+    }
+
+    session.clients.add(ws);
+    if (session.pendingApproval) {
+      this.reply(ws, reqId, false, undefined, 'Resolve the pending approval before sending another message.');
+      return;
+    }
+    if (clientMessageId && this.hasAcceptedClientMessage(session, clientMessageId)) {
+      this.reply(ws, reqId, true, { sessionId, clientMessageId, duplicate: true });
+      return;
+    }
+    log.info({
+      sessionId,
+      clients: session.clients.size,
+      hasDriver: !!session.driver,
+      active: session.active,
+      imageCount: images?.length ?? 0,
+    }, 'sending message');
+    audit.emit('session.send', {
+      sessionId,
+      agent: session.agent,
+      messagePreview: message.slice(0, 100),
+      imageCount: images?.length ?? 0,
+    });
+
+    if (isFallbackSessionTitle(session.title)) {
+      const derivedTitle = titleFromFirstSentence(message, 50);
+      if (derivedTitle && derivedTitle !== session.title) {
+        session.title = derivedTitle;
+      }
+      this.store.upsert(buildRecord(session));
+    }
+    if (clientMessageId) {
+      this.rememberAcceptedClientMessage(session, clientMessageId);
+    }
+    this.touchSession(session.sessionId);
+    const attachmentBlock = images?.length
+      ? images.map((path) => `[Attached image: ${path}]`).join('\n')
+      : '';
+    const prompt = attachmentBlock
+      ? message
+        ? `${message}\n\n${attachmentBlock}`
+        : attachmentBlock
+      : message;
+    if (session.startupInProgress) {
+      session.isResponding = true;
+      session.currentReplyText = '';
+      session.lastUserMessage = message;
+      session.bufferedPrompts.push(prompt);
+      this.noteInventoryChanged('session_updated');
+      this.reply(ws, reqId, true, clientMessageId ? { sessionId, clientMessageId } : undefined);
+      return;
+    }
+    if (session.isResponding) {
+      session.bufferedPrompts.push(prompt);
+      this.reply(ws, reqId, true, clientMessageId ? { sessionId, clientMessageId } : undefined);
+      return;
+    }
+    session.isResponding = true;
+    session.currentReplyText = '';
+    session.lastUserMessage = message;
+    this.noteInventoryChanged('session_updated');
+    session.driver!.sendPrompt(prompt);
+    this.reply(ws, reqId, true, clientMessageId ? { sessionId, clientMessageId } : undefined);
+  }
+
+  private async sendReconnectSnapshot(
+    ws: WebSocket,
+    reqId: string,
+    agent?: AgentType,
+    cwd?: string,
+    search?: string,
+    activeSessionId?: string,
+    activeAgent?: AgentType,
+  ): Promise<void> {
+    try {
+      const deletedSessionIds = this.getDeletedSessionIds();
+      let page: SessionListPage;
+      try {
+        page = await listSessionPage({
+          agent,
+          cwd,
+          search,
+          limit: 50,
+          activeSessions: this.activeSessionSnapshots(),
+          sessionRecords: this.store.getAll(),
+          deletedSessionIds,
+        });
+      } catch (error) {
+        log.warn({ error: String(error) }, 'failed to build reconnect snapshot session list');
+        page = { sessions: [], nextCursor: undefined };
+      }
+      page = { ...page, inventoryVersion: this.inventoryVersion };
+      let activeSession: ReconnectSnapshotSession | undefined;
+      if (activeSessionId && !deletedSessionIds.has(activeSessionId)) {
+        const inferredAgent = activeAgent
+          ?? page.sessions.find((session) => session.sessionId === activeSessionId)?.agent;
+        const liveSession = this.sessions.get(activeSessionId);
+        // Subscribe this ws to session broadcasts so streaming updates reach reconnected clients
+        if (liveSession) {
+          liveSession.clients.add(ws);
+        }
+        const resolved = await this.resolveReconnectSession(activeSessionId, inferredAgent, liveSession);
+        if (resolved) {
+          const history = await readSessionHistory(activeSessionId, resolved.agent, liveSession?.cwd ?? resolved.cwd);
+          const runtimeHints = liveSession
+            ? {}
+            : await readSessionRuntimeHints(activeSessionId, resolved.agent, resolved.cwd);
+          activeSession = {
+            sessionId: activeSessionId,
+            agent: resolved.agent,
+            messages: history,
+            ...acceptedClientMessageIdsPayload(
+              liveSession?.acceptedClientMessageIds ?? resolved.acceptedClientMessageIds,
+            ),
+            isResponding: liveSession?.isResponding ?? runtimeHints.isResponding ?? resolved.isResponding,
+            partialReplyText: liveSession
+              ? this.currentPartialReplyText(liveSession)
+              : runtimeHints.partialReplyText,
+            approvalMode: liveSession?.approvalMode ?? resolved.approvalMode,
+            ...(liveSession?.pendingApproval ? { pendingApproval: liveSession.pendingApproval } : {}),
+          };
+        }
+      }
+      const pendingApprovals = this.collectReconnectPendingApprovals();
+
+      metrics.increment('reconnect.snapshot', { activeSession: activeSession ? 'true' : 'false' });
+      this.reply(ws, reqId, true, {
+        snapshot: {
+          sessions: page.sessions,
+          nextCursor: page.nextCursor,
+          inventoryVersion: page.inventoryVersion,
+          ...(activeSession ? { activeSession } : {}),
+          ...(pendingApprovals.length > 0 ? { pendingApprovals } : {}),
+        },
+      });
+    } catch (error) {
+      this.reply(ws, reqId, false, undefined, `Failed to build reconnect snapshot: ${String(error)}`);
+    }
+  }
+
+  private async approve(ws: WebSocket, reqId: string, sessionId: string, requestId: string, approved: boolean): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    const pendingApproval = session?.pendingApproval;
+    const pendingClaudeHookApproval = session?.pendingClaudeHookApprovals.get(requestId);
+    if (session && pendingClaudeHookApproval) {
+      session.pendingApproval = undefined;
+      audit.emit('approval.response', { sessionId, requestId, approved });
+      this.touchSession(session.sessionId);
+      this.noteInventoryChanged('session_updated');
+      pendingClaudeHookApproval.resolve(buildClaudeHookDecisionResponse(approved));
+      session.isResponding = true;
+      this.reply(ws, reqId, true);
+      return;
+    }
+
+    const syntheticRetry = session?.syntheticApprovalRetries[requestId];
+    if (session && syntheticRetry && isClaudeSyntheticApprovalRequestId(requestId)) {
+      delete session.syntheticApprovalRetries[requestId];
+      session.pendingApproval = undefined;
+      audit.emit('approval.response', { sessionId, requestId, approved });
+      this.touchSession(session.sessionId);
+      this.noteInventoryChanged('session_updated');
+      this.reply(ws, reqId, true);
+      if (approved) {
+        await this.retrySyntheticClaudeApproval(session, syntheticRetry);
+      }
+      return;
+    }
+    if (session && !session.driver && pendingApproval) {
+      try {
+        await this.reviveSessionForApproval(session);
+      } catch (error) {
+        this.reply(ws, reqId, false, undefined, `Failed to restore approval session: ${String(error)}`);
+        return;
+      }
+    }
+    if (!session?.driver) {
+      this.reply(ws, reqId, false, undefined, 'Session not found or inactive');
+      return;
+    }
+    audit.emit('approval.response', { sessionId, requestId, approved });
+    const sent = session.driver.respondApproval(requestId, approved);
+    if (!sent) {
+      this.reply(ws, reqId, false, undefined, 'Agent process is not running. Send a new message to continue.');
+      return;
+    }
+    session.pendingApproval = undefined;
+    this.touchSession(session.sessionId);
+    session.isResponding = true;
+    this.noteInventoryChanged('session_updated');
+    this.reply(ws, reqId, true);
+  }
+
+  private async retrySyntheticClaudeApproval(session: ActiveSession, retry: SyntheticApprovalRetry): Promise<void> {
+    if (session.agent !== 'claude') return;
+
+    try {
+      if (session.driver) {
+        session.driver.stop();
+      }
+
+      const retryApprovalMode: ApprovalMode = ['Write', 'Edit', 'NotebookEdit'].includes(retry.toolName)
+        ? 'acceptEdits'
+        : 'autoApprove';
+      const driver = this.createDriver(session.agent);
+      const claudeHookSecret = this.configureDriverBeforeStart(session.agent, driver, session.claudeHookSecret);
+      await driver.start(session.cwd, session.sessionId, retryApprovalMode);
+
+      session.driver = driver;
+      session.active = true;
+      session.isResponding = true;
+      session.currentReplyText = '';
+      session.lastUserMessage = retry.message;
+      session.startupInProgress = false;
+      session.bufferedPrompts = [];
+      session.startupToken = 0;
+      session.claudeHookSecret = claudeHookSecret ?? session.claudeHookSecret;
+      session.pendingClaudeHookApprovals = session.pendingClaudeHookApprovals ?? new Map();
+
+      this.registerClaudeHookSession(session);
+      this.bindDriverLifecycle(session, session.agent, ' (approval retry)');
+      this.store.upsert(buildRecord(session));
+      this.updateGauges();
+      this.touchSession(session.sessionId);
+      this.noteInventoryChanged('session_updated');
+
+      log.info({ sessionId: session.sessionId, toolName: retry.toolName, retryApprovalMode }, 'retrying Claude turn after synthetic approval');
+      driver.sendPrompt(retry.message);
+    } catch (error) {
+      session.driver = null;
+      session.active = false;
+      session.isResponding = false;
+      session.startupInProgress = false;
+      session.bufferedPrompts = [];
+      session.startupToken += 1;
+      this.updateGauges();
+      this.touchSession(session.sessionId);
+      this.noteInventoryChanged('session_updated');
+      log.error({ sessionId: session.sessionId, error: String(error) }, 'failed to retry Claude turn after approval');
+      this.broadcast(session.sessionId, {
+        type: 'error',
+        sessionId: session.sessionId,
+        message: `Failed to continue after approval: ${String(error)}`,
+      });
+    }
+  }
+
+  private async setApprovalMode(ws: WebSocket, reqId: string, sessionId: string, approvalMode: ApprovalModeOverride): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      // Session not active in memory — update persisted record or create one
+      const record = this.store.find(sessionId);
+      if (record) {
+        if (approvalMode === null) {
+          delete record.approvalMode;
+        } else {
+          record.approvalMode = approvalMode;
+        }
+        this.store.upsert(record);
+        this.noteInventoryChanged('session_updated');
+        log.info({ sessionId, agent: record.agent, newMode: approvalMode }, 'approval mode changed (inactive session)');
+      } else {
+        log.info({ sessionId, newMode: approvalMode }, 'approval mode changed (untracked session)');
+      }
+      this.reply(ws, reqId, true, { approvalMode });
+      return;
+    }
+    if (approvalMode === null) {
+      this.reply(ws, reqId, false, undefined, 'Follow Remote is only available for external sessions');
+      return;
+    }
+    const oldMode = session.approvalMode;
+    session.approvalMode = approvalMode;
+    this.store.upsert(buildRecord(session));
+    this.noteInventoryChanged('session_updated');
+    log.info({ sessionId, agent: session.agent, oldMode, newMode: approvalMode }, 'approval mode changed');
+
+    if (session.driver) {
+      session.driver.setApprovalMode(approvalMode);
+    }
+
+    this.reply(ws, reqId, true, { approvalMode });
+  }
+
+  private interrupt(ws: WebSocket, reqId: string, sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session?.driver) {
+      this.reply(ws, reqId, false, undefined, 'Session not found or inactive');
+      return;
+    }
+    audit.emit('session.interrupt', { sessionId, agent: session.agent });
+    if (session.startupInProgress) {
+      const hadBufferedTurn = session.isResponding || session.bufferedPrompts.length > 0;
+      log.info({ sessionId, agent: session.agent, hadBufferedTurn }, 'interrupting pending startup session');
+      session.bufferedPrompts = [];
+      session.isResponding = false;
+      session.currentReplyText = '';
+      session.lastUserMessage = undefined;
+      session.pendingApproval = undefined;
+      this.touchSession(session.sessionId);
+      this.noteInventoryChanged('session_updated');
+      this.reply(ws, reqId, true);
+      if (hadBufferedTurn) {
+        this.broadcast(session.sessionId, { type: 'session.interrupted', sessionId: session.sessionId });
+      }
+      return;
+    }
+    session.driver.interrupt();
+    this.reply(ws, reqId, true);
+  }
+
+  private stopSession(ws: WebSocket, reqId: string, sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      this.reply(ws, reqId, false, undefined, 'Session not found');
+      return;
+    }
+    log.info({ sessionId, agent: session.agent }, 'stopping session');
+    audit.emit('session.stop', { sessionId, agent: session.agent });
+    this.resolvePendingClaudeHookApprovals(session);
+    session.driver?.stop();
+    session.active = false;
+    session.driver = null;
+    session.pendingApproval = undefined;
+    session.startupInProgress = false;
+    session.bufferedPrompts = [];
+    session.startupToken += 1;
+    this.updateGauges();
+    this.touchSession(session.sessionId);
+    this.noteInventoryChanged('session_updated');
+    this.reply(ws, reqId, true);
+  }
+
+  private deleteSession(ws: WebSocket, reqId: string, sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      log.info({ sessionId, agent: session.agent }, 'deleting session');
+      this.resolvePendingClaudeHookApprovals(session);
+      session.driver?.stop();
+      session.startupInProgress = false;
+      session.bufferedPrompts = [];
+      session.startupToken += 1;
+      this.unregisterClaudeHookSession(session);
+      this.sessions.delete(sessionId);
+    }
+    audit.emit('session.delete', { sessionId });
+    this.store.remove(sessionId);
+    this.updateGauges();
+    invalidateScannerCache();
+    invalidateProcessScanCache();
+    this.noteInventoryChanged('session_deleted');
+    this.reply(ws, reqId, true);
+  }
+
+  private async sendHistory(ws: WebSocket, reqId: string, sessionId: string, agent: AgentType): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session && this.isDeletedSession(sessionId)) {
+      this.reply(ws, reqId, false, undefined, 'Session not found');
+      return;
+    }
+    // Subscribe this ws to session broadcasts so streaming updates reach reconnected clients
+    if (session) {
+      session.clients.add(ws);
+    }
+    const cwd = session?.cwd ?? this.store.find(sessionId)?.cwd ?? '';
+    const record = this.store.find(sessionId);
+    const history = await readSessionHistory(sessionId, agent, cwd);
+    const runtimeHints = session ? {} : await readSessionRuntimeHints(sessionId, agent, cwd);
+    const isResponding = session?.isResponding ?? runtimeHints.isResponding;
+    const partialReplyText = session
+      ? this.currentPartialReplyText(session)
+      : runtimeHints.partialReplyText;
+    log.info({ sessionId, historyCount: history.length, isResponding, approvalMode: session?.approvalMode ?? record?.approvalMode }, 'sending history');
+    const historyMsg: ServerMessage = {
+      type: 'session.history',
+      sessionId,
+      messages: history,
+      ...acceptedClientMessageIdsPayload(session?.acceptedClientMessageIds ?? record?.acceptedClientMessageIds),
+      isResponding,
+      partialReplyText,
+      approvalMode: session?.approvalMode ?? record?.approvalMode,
+      pendingApproval: session?.pendingApproval ?? record?.pendingApproval,
+    };
+    if (ws.readyState === 1) {
+      ws.send(JSON.stringify(historyMsg));
+    }
+    this.reply(ws, reqId, true);
+  }
+
+  private async listSessions(
+    ws: WebSocket,
+    reqId: string,
+    agent?: AgentType,
+    cwd?: string,
+    search?: string,
+    limit = 50,
+    cursor?: SessionListCursor,
+  ): Promise<void> {
+    try {
+      const page = await listSessionPage({
+        agent,
+        cwd,
+        search,
+        limit,
+        cursor,
+        activeSessions: this.activeSessionSnapshots(),
+        sessionRecords: this.store.getAll(),
+        deletedSessionIds: this.getDeletedSessionIds(),
+      });
+      this.reply(ws, reqId, true, { ...page, inventoryVersion: this.inventoryVersion });
+    } catch (e) {
+      this.reply(ws, reqId, false, undefined, String(e));
+    }
+  }
+
+  private createDriver(agent: AgentType): Driver {
+    switch (agent) {
+      case 'claude': return new ClaudeDriver();
+      case 'codex': return new CodexDriver();
+      default: throw new Error(`Unknown agent: ${agent}`);
+    }
+  }
+
+  private broadcast(sessionId: string, msg: ServerMessage): void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      log.warn({ sessionId, msgType: msg.type }, 'broadcast target session not found');
+      return;
+    }
+    const data = JSON.stringify(msg);
+
+    // Approval requests must reach all connected clients, not just those
+    // subscribed to this session, so the app can show the approval sheet
+    // even when the user is viewing a different session.
+    const targets = msg.type === 'approval.request' ? this.globalClients : session.clients;
+
+    const total = targets.size;
+    let sent = 0;
+    let failed = 0;
+    for (const client of targets) {
+      if (client.readyState === 1) { // WebSocket.OPEN
+        client.send(data);
+        sent++;
+      } else {
+        failed++;
+      }
+    }
+    if (failed > 0) {
+      metrics.increment('broadcast.fail');
+    }
+    if (msg.type !== 'text.delta') {
+      log.debug({ sessionId, msgType: msg.type, sent, total }, 'broadcast');
+    }
+
+    if (msg.type === 'text.delta') {
+      session.currentReplyText += msg.content;
+      return;
+    }
+
+    if (msg.type === 'session.done') {
+      const title = session.title || sessionId;
+      const body = this.buildPushBody(session.currentReplyText);
+      session.currentReplyText = '';
+      void this.pushSender(title, body, {
+        sessionId,
+        agent: session.agent,
+        eventType: 'reply_ready',
+      });
+      return;
+    }
+
+    if (msg.type === 'session.interrupted') {
+      session.currentReplyText = '';
+    }
+  }
+
+  private reply(ws: WebSocket, id: string, ok: boolean, data?: unknown, error?: string): void {
+    if (ws.readyState !== 1) return;
+    const msg: ServerMessage = { type: 'response', id, ok, data, error };
+    ws.send(JSON.stringify(msg));
+  }
+}