@vibelet/cli 0.1.37 → 1.0.0

package/src/session-manager.ts

@@ -1,1775 +0,0 @@
-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));
-  }
-}