main.js

const { app, BrowserWindow, clipboard, dialog, ipcMain, Menu, powerMonitor, screen, session, shell } = require('electron');
const { Worker } = require('worker_threads');
const { execFile } = require('child_process');
const path = require('path');
const fs = require('fs');
const os = require('os');
const pty = require('node-pty');
const log = require('electron-log');

// Dev builds default to a separate SQLite DB so they don't race on
// session_cache with a running installed AppImage. Honors an explicit
// SWITCHBOARD_DATA_DIR env var if set (test sandboxes, agent runs). This MUST
// happen before db.js is required — db.js resolves DATA_DIR at module load.
if (!app.isPackaged && !process.env.SWITCHBOARD_DATA_DIR) {
  process.env.SWITCHBOARD_DATA_DIR = path.join(os.homedir(), '.switchboard-dev');
}

// getFolderIndexMtimeMs moved to session-cache.js
const { appendToOutputBuffer, MAX_BUFFER_SIZE } = require('./output-buffer');
const { startMcpServer, shutdownMcpServer, shutdownAll: shutdownAllMcp, resolvePendingDiff, rekeyMcpServer, cleanStaleLockFiles } = require('./mcp-bridge');
const { fetchAndTransformUsage } = require('./claude-auth');

// SWITCHBOARD_DATA_DIR isolates a dev/test instance from the installed app:
// db.js puts switchboard.db under it, and pointing userData there gives the
// instance its own single-instance lock (requestSingleInstanceLock keys on
// userData), so both can run side by side.
if (process.env.SWITCHBOARD_DATA_DIR) {
  app.setPath('userData', path.resolve(process.env.SWITCHBOARD_DATA_DIR, 'electron'));
}

log.transports.file.level = app.isPackaged ? 'info' : 'debug';
log.transports.console.level = app.isPackaged ? 'info' : 'debug';
const LOG_DEBUG_ON = log.transports.file.level === 'debug' || log.transports.console.level === 'debug';

// Opt-in activity trace — see docs/activity-trace.md.
const activityTrace = require('./activity-trace');
const { state: TRACE, trace, codePoints, controlOffset, busyDecision, progressDecision } = activityTrace;

const { classifyTitleActivity } = require('./classify-title-activity');
const { windowFrameOptions, applicationMenuTemplate, zoomKey, nextZoomLevel, menuPopupPoint } = require('./window-frame');

try { require('electron-reloader')(module, { watchRenderer: true }); } catch {};

// Clean env for child processes — strip Electron internals that cause nested
// Electron apps (or node-pty inside them) to malfunction.
const cleanPtyEnv = Object.fromEntries(
  Object.entries(process.env).filter(([k]) =>
    !k.startsWith('ELECTRON_') &&
    !k.startsWith('GOOGLE_API_KEY') &&
    k !== 'NODE_OPTIONS' &&
    k !== 'ORIGINAL_XDG_CURRENT_DESKTOP' &&
    k !== 'WT_SESSION'
  )
);

// Windows: prefer node-pty's bundled ConPTY (conpty.dll + OpenConsole.exe)
// over the OS inbox one. The inbox ConPTY re-renders TUI frames itself and is a
// known source of ghost/duplicated lines and torn rows during Claude Code
// redraws — artifacts that end up in the xterm buffer, so no renderer-side
// repaint can remove them. VS Code ships the same flag for the same reason.
// SWITCHBOARD_NO_CONPTY_DLL=1 reverts to the inbox ConPTY without a rebuild.
function spawnPty(file, args, opts) {
  if (process.platform === 'win32' && !process.env.SWITCHBOARD_NO_CONPTY_DLL) {
    try {
      return pty.spawn(file, args, { ...opts, useConptyDll: true });
    } catch (err) {
      // e.g. conpty.dll not found next to the binding — inbox ConPTY still works
      log.warn(`[pty] useConptyDll spawn failed, falling back to inbox ConPTY: ${err.message}`);
    }
  }
  return pty.spawn(file, args, opts);
}

// Shell profiles → shell-profiles.js
const { discoverShellProfiles, getShellProfiles, resolveShell, isWindows, isWslShell, windowsToWslPath, shellArgs, quoteArgvForShell } = require('./shell-profiles');
const { startScheduler } = require('./schedule-runner');
const { encodeProjectPath } = require('./encode-project-path');
const { SETTING_DEFAULTS } = require('./public/setting-defaults');
const { scanMdFiles, acceptMdFile } = require('./scan-md-files');
const { isSensitivePath, isAllowedMemoryPath: _isAllowedMemoryPath, resolveAllowedMemoryPath: _resolveAllowedMemoryPath, isKnownProjectRoot: _isKnownProjectRoot } = require('./ipc-path-validator');
const { validatePreLaunchCmd } = require('./pre-launch-cmd-guard');
const { normalizePtySize } = require('./pty-size');
const { setPtyOpLogger, resizePty, killPty } = require('./pty-ops');
const { createComposerState } = require('./composer-state');
const { handleTerminalInput } = require('./terminal-input');
const { createTriggerContext } = require('./trigger-context');
const { createTmuxAttachAdapter } = require('./remote-attach');
const { createRemoteStopAdapter } = require('./remote-stop');
const { createGitChangesRunner } = require('./git-changes-runner');
const gitChangesTarget = require('./git-changes-target');
const terminalPathTarget = require('./terminal-path-target');
const { resolvePanelTerminalCwd, isPanelShellSession } = require('./panel-terminal-target');
const gitChangesFile = require('./git-changes-file');
const { createChangesWatchRegistry } = require('./git-changes-watch');
const { createActivityWatchClient, DEFAULT_BASE_URL: ACTIVITYWATCH_URL } = require('./activitywatch-client');
const { createActivityWatchReporter } = require('./activitywatch-reporter');

setPtyOpLogger(log);


// --- Auto-updater (only in packaged builds) ---
let autoUpdater = null;
if (app.isPackaged || process.env.FORCE_UPDATER) {
  autoUpdater = require('electron-updater').autoUpdater;
  autoUpdater.logger = log;
  autoUpdater.autoDownload = true;
  autoUpdater.autoInstallOnAppQuit = true;
  if (!app.isPackaged) autoUpdater.forceDevUpdateConfig = true;

  function sendUpdaterEvent(type, data) {
    log.info(`[updater] ${type}`, data || '');
    if (mainWindow && !mainWindow.isDestroyed()) {
      mainWindow.webContents.send('updater-event', type, data);
    }
  }
  autoUpdater.on('checking-for-update', () => sendUpdaterEvent('checking'));
  autoUpdater.on('update-available', (info) => {
    sendUpdaterEvent('update-available', info);
    // With Automatic Updates off there are no scheduled checks, so this event
    // can only come from the user pressing "Check for Updates". electron-updater
    // does not fetch in that case — AppUpdater's downloadPromise is null unless
    // autoDownload — and nothing else calls downloadUpdate(), so a deliberate
    // check would otherwise stall at "found, never downloaded". Install still
    // waits for the user, since autoInstallOnAppQuit is off too.
    if (!autoUpdater.autoDownload) {
      autoUpdater.downloadUpdate().catch(err =>
        log.error('[updater] manual download failed:', err?.message || String(err)));
    }
  });
  autoUpdater.on('update-not-available', (info) => sendUpdaterEvent('update-not-available', info));
  autoUpdater.on('download-progress', (progress) => sendUpdaterEvent('download-progress', progress));
  autoUpdater.on('update-downloaded', (info) => sendUpdaterEvent('update-downloaded', info));
  autoUpdater.on('error', (err) => {
    log.error('[updater] Error:', err?.message || String(err));
    activityFlushedForQuit = false; // see .ai/contexts/activitywatch.md ("Quitting")
    if (mainWindow && !mainWindow.isDestroyed()) {
      mainWindow.webContents.send('updater-event', 'error', { message: err?.message || String(err) });
    }
  });
}
const {
  getMeta, getAllMeta, toggleStar, setName, setArchived,
  isCachePopulated, getAllCached, getCachedByFolder, getCachedByParent, getCachedFolder, getCachedSession, upsertCachedSessions,
  deleteCachedSession, deleteCachedFolder, replaceSessionMetrics, touchCachedModified,
  getFolderMeta, getAllFolderMeta, setFolderMeta,
  upsertSearchEntries, updateSearchTitle, deleteSearchSession, deleteSearchFolder, deleteSearchType,
  searchByType, isSearchIndexPopulated, searchFtsRecreated,
  getSetting, setSetting, deleteSetting,
  isInitialScanComplete, setInitialScanComplete,
  getDailyMetrics, getDailyModelTokens, getModelUsage, getTotalCounts,
  closeDb,
  DB_PATH,
} = require('./db');

// The trace file sits next to switchboard.db — DB_PATH is the one resolution
// of SWITCHBOARD_DATA_DIR, never re-derived here.
const TRACE_DIR = path.dirname(DB_PATH);
activityTrace.init(TRACE_DIR);
activityTrace.setEnabled(
  activityTrace.initialEnabled(process.env, (getSetting('global') || {}).activityTrace)
);
if (TRACE.on) {
  log.info(`[activity-trace] enabled → ${activityTrace.currentFile() || '(failed to open)'}`);
}

// see .ai/contexts/activitywatch.md
const activityWatchClient = createActivityWatchClient({ fetchFn: fetch, hostname: os.hostname(), log });
const activityReporter = createActivityWatchReporter({
  client: activityWatchClient,
  hostname: os.hostname(),
  idleSeconds: () => { try { return powerMonitor.getSystemIdleTime(); } catch { return 0; } },
});
let activityFlushedForQuit = false; // see .ai/contexts/activitywatch.md ("Quitting")
activityReporter.setEnabled(
  (getSetting('global') || {}).activityReporting ?? SETTING_DEFAULTS.activityReporting
);

// One-shot cleanup: the Plans tab was removed, so nothing indexes or clears
// FTS rows of type 'plan' anymore. Purge any left behind by earlier versions.
try { deleteSearchType('plan'); } catch {}

// --- Search query worker ---
// Routes 'search' IPC off the main thread so that a slow FTS5 phrase query
// (e.g. a 60-char pasted URL) never blocks the Electron event loop.
// better-sqlite3 is synchronous; on the main thread a slow query stalls ALL
// IPC (terminal data, OSC, sidebar) → visible UI freeze. The worker opens a
// read-only WAL connection which coexists safely with the main thread's writer.
//
// A dedicated worker is used instead of the existing scan-projects worker because
// that worker is used for cold-start indexing and may be occupied with a long
// sequential scan when the user types a query.
//
// Protocol logic (correlation IDs, pending map, drain, backoff, circuit-breaker)
// lives in search-worker-client.js so it can be unit-tested without Electron.
const { createSearchWorkerClient } = require('./search-worker-client');

const searchClient = createSearchWorkerClient({
  workerFactory: (dbPath) => new Worker(
    path.join(__dirname, 'workers', 'search-query.js'),
    { workerData: { dbPath } }
  ),
  searchByType,
  log,
  dbPath: DB_PATH,
});

searchClient.startWorker();

/**
 * Send a search query to the worker and return a Promise<results[]>.
 * Falls back to the synchronous searchByType on the main thread if the
 * worker is not yet ready (first-launch race or circuit-breaker open).
 */
const searchViaWorker = searchClient.searchViaWorker;

const PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
// Ceiling for a file opened in the viewer panel, mirroring read-work-file.
const PANEL_FILE_MAX_BYTES = 2 * 1024 * 1024;
const TERMINAL_PATH_BATCH_MAX = 64;
const CLAUDE_DIR = path.join(os.homedir(), '.claude');
const STATS_CACHE_PATH = path.join(CLAUDE_DIR, 'stats-cache.json');
// MAX_BUFFER_SIZE imported from output-buffer.js (single source of truth)

// Active PTY sessions
const activeSessions = new Map();
let mainWindow = null;

// Every project root Switchboard currently knows about: live sessions plus
// every indexed project (same enumeration as the get-memories handler).
// Shared by every guard that needs to bound a renderer-supplied path to "a
// project this install actually knows about" — the memory allowlist below,
// and the worktree-path containment check next to WORKTREE_PATH_RE.
function getKnownProjectPaths() {
  const projectPaths = new Set();
  for (const [, s] of activeSessions) {
    if (s.projectPath) projectPaths.add(s.projectPath);
  }
  try {
    const { deriveProjectPath } = require('./derive-project-path');
    if (fs.existsSync(PROJECTS_DIR)) {
      for (const d of fs.readdirSync(PROJECTS_DIR, { withFileTypes: true })) {
        if (!d.isDirectory() || d.name === '.git') continue;
        const folderPath = path.join(PROJECTS_DIR, d.name);
        const p = deriveProjectPath(folderPath, d.name);
        if (p) projectPaths.add(p);
      }
    }
  } catch {}
  return projectPaths;
}

// Wrapper that plumbs the set of known project roots into isAllowedMemoryPath.
// The Memory panel (get-memories) surfaces CLAUDE.md / agents.md and
// .claude/*.md from EVERY indexed project — not just ones with a live session —
// so the allowlist must cover every known project root, otherwise reading a
// memory file for a project without an open session would be rejected.
function isAllowedMemoryPath(filePath) {
  return _isAllowedMemoryPath(filePath, [...getKnownProjectPaths()]);
}

// Same allowlist, but returns the resolved path to read/write instead of a
// boolean — callers with a filesystem operation to perform must use this and
// operate on the returned value, not on their own path.resolve(filePath).
// See ipc-path-validator.js and resolve-path-on-disk.js.
function resolveAllowedMemoryPath(filePath) {
  return _resolveAllowedMemoryPath(filePath, [...getKnownProjectPaths()]);
}

// Subagent live-tail watchers (watchId → { filePath, parentSessionId, agentId, teardown })
const subagentWatchers = new Map();
let subagentWatcherSeq = 0;

function createWindow() {
  // Restore saved window bounds
  const savedBounds = getSetting('global')?.windowBounds;
  let bounds = { width: 1400, height: 900 };

  let restorePosition = null;
  if (savedBounds && savedBounds.width && savedBounds.height) {
    bounds.width = savedBounds.width;
    bounds.height = savedBounds.height;

    // Only restore position if it's on a visible display
    if (savedBounds.x != null && savedBounds.y != null) {
      const displays = screen.getAllDisplays();
      const onScreen = displays.some(d => {
        const b = d.bounds;
        return savedBounds.x >= b.x - 100 && savedBounds.x < b.x + b.width &&
               savedBounds.y >= b.y - 100 && savedBounds.y < b.y + b.height;
      });
      if (onScreen) {
        restorePosition = { x: savedBounds.x, y: savedBounds.y };
      }
    }
  }

  const appTitle = app.isPackaged ? 'Switchboard' : 'Switchboard (dev)';
  mainWindow = new BrowserWindow({
    ...bounds,
    minWidth: 800,
    minHeight: 500,
    title: appTitle,
    ...windowFrameOptions(process.platform),
    icon: path.join(__dirname, 'build', 'icon.png'),
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      nodeIntegration: false,
      contextIsolation: true,
      // The sandboxed preload cannot require activity-trace.js, so main's
      // resolution of the flag is handed to it instead of parsed twice.
      additionalArguments: TRACE.on ? ['--switchboard-activity-trace'] : [],
    },
  });

  // Set position after creation to prevent macOS from clamping size
  if (restorePosition) {
    mainWindow.setBounds({ ...restorePosition, width: bounds.width, height: bounds.height });
  }

  mainWindow.loadFile(path.join(__dirname, 'public', 'index.html'));
  mainWindow.webContents.on('console-message', (_e, level, message, line, sourceId) => {
    if (level >= 2) log.error(`[renderer:${level}] ${sourceId}:${line} ${message}`);
  });

  // Open external links in the system browser instead of a child BrowserWindow
  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
    if (/^https?:\/\//i.test(url)) shell.openExternal(url).catch(() => {});
    return { action: 'deny' };
  });
  mainWindow.webContents.on('will-navigate', (event, url) => {
    if (url !== mainWindow.webContents.getURL()) {
      event.preventDefault();
      if (/^https?:\/\//i.test(url)) shell.openExternal(url).catch(() => {});
    }
  });
  // Override window.open so xterm WebLinksAddon's default handler (which does
  // window.open() then sets location.href) routes through our IPC instead of
  // creating a child BrowserWindow.
  mainWindow.webContents.on('did-finish-load', () => {
    mainWindow.webContents.executeJavaScript(`
      window.open = function(url) {
        if (url && /^https?:\\/\\//i.test(url)) { window.api.openExternal(url); return null; }
        const proxy = {};
        Object.defineProperty(proxy, 'location', { get() {
          const loc = {};
          Object.defineProperty(loc, 'href', {
            set(u) { if (/^https?:\\/\\//i.test(u)) window.api.openExternal(u); }
          });
          return loc;
        }});
        return proxy;
      };
      void 0;
    `);
  });

  // Prevent Cmd+R / Ctrl+Shift+R from reloading the page (Chromium built-in).
  // Ctrl+R alone on macOS is NOT a reload shortcut and must pass through to xterm
  // for reverse-i-search.
  mainWindow.webContents.on('before-input-event', (event, input) => {
    if (input.type !== 'keyDown') return;
    const key = input.key.toLowerCase();
    if (key === 'r' && input.meta) event.preventDefault();
    if (key === 'r' && input.control && input.shift) event.preventDefault();
    const zoom = zoomKey(input, process.platform);
    if (zoom) {
      event.preventDefault();
      mainWindow.webContents.setZoomLevel(nextZoomLevel(mainWindow.webContents.getZoomLevel(), zoom));
    }
  });

  // Renderer-driven fullscreen toggle (F11 lands in xterm, which consumes the
  // keydown before the menu accelerator can fire — the terminal forwards it
  // here instead). Notify the renderer on every change, whatever triggered it
  // (menu click, IPC, OS shortcut), so it can refocus the active terminal —
  // otherwise the focus is lost on the transition and typing goes nowhere.
  const sendFullScreenChanged = () => {
    if (!mainWindow || mainWindow.isDestroyed()) return;
    mainWindow.webContents.send('full-screen-changed', mainWindow.isFullScreen());
  };
  mainWindow.on('enter-full-screen', sendFullScreenChanged);
  mainWindow.on('leave-full-screen', sendFullScreenChanged);

  // Save window bounds on move/resize (debounced)
  let boundsTimer = null;
  const saveBounds = () => {
    if (boundsTimer) clearTimeout(boundsTimer);
    boundsTimer = setTimeout(() => {
      if (!mainWindow || mainWindow.isDestroyed() || mainWindow.isMinimized()) return;
      const b = mainWindow.getBounds();
      const global = getSetting('global') || {};
      global.windowBounds = { x: b.x, y: b.y, width: b.width, height: b.height };
      setSetting('global', global);
    }, 500);
  };
  mainWindow.on('resize', saveBounds);
  mainWindow.on('move', saveBounds);

  // Also save immediately before close (debounce may not have flushed)
  mainWindow.on('close', () => {
    if (boundsTimer) clearTimeout(boundsTimer);
    if (!mainWindow.isMinimized()) {
      const b = mainWindow.getBounds();
      const global = getSetting('global') || {};
      global.windowBounds = { x: b.x, y: b.y, width: b.width, height: b.height };
      setSetting('global', global);
    }
  });

  mainWindow.on('closed', () => {
    // On macOS the app stays alive in the dock after the last window closes.
    // Kill all running PTY processes so orphaned `claude` processes don't
    // accumulate in the background with no way for the user to interact.
    for (const [id, session] of activeSessions) {
      if (!session.exited) killPty(session, id);
      activeSessions.delete(id);
    }
    changesWatchers.closeAll();
    closeAllFileWatchers();
    // Release all subagent file watchers (closes fs.watch handles + clears any
    // debounce timers / polling fallbacks via the stored teardown closure)
    for (const [, entry] of subagentWatchers) {
      try { entry.teardown(); } catch {}
    }
    subagentWatchers.clear();
    mainWindow = null;
  });
}

function buildMenu() {
  Menu.setApplicationMenu(Menu.buildFromTemplate(applicationMenuTemplate(app.name)));
}

// --- Session cache helpers ---

const { deriveProjectPath, resolveSessionRealCwd, sessionTranscriptExists, isGitRepo } = require('./derive-project-path');
const { resolveDeletionTargets } = require('./delete-session-target');

// Session cache → session-cache.js
const sessionCache = require('./session-cache');
sessionCache.init({
  PROJECTS_DIR,
  activeSessions,
  getMainWindow: () => mainWindow,
  log,
  db: {
    deleteCachedFolder, getCachedByFolder, upsertCachedSessions, deleteCachedSession, replaceSessionMetrics, touchCachedModified,
    deleteSearchFolder, deleteSearchSession, upsertSearchEntries,
    setFolderMeta, getFolderMeta, getAllFolderMeta, getAllMeta, getAllCached, getSetting, getMeta, setName,
    isInitialScanComplete, setInitialScanComplete,
  },
});
const { readSessionFile, readFolderFromFilesystem, refreshFolder, reconcileCacheFromFilesystem,
        buildProjectsFromCache, notifyRendererProjectsChanged, sendStatus, populateCacheViaWorker,
        scanFoldersViaWorker, setRemoteRoots, resolveFolderDir } = sessionCache;
const { resolveJsonlPath, enumerateSessionFiles } = require('./read-session-file');

// --- Remote SSH hosts (observation only) — see .ai/contexts/session-cache.md ---
const { isRemoteFolder, parseFolderKey, joinFolderKey, enabledHosts } = require('./remote-hosts');
const REMOTE_READ_ONLY = 'remote sessions are read-only — this build observes them, it does not attach to them';
const { createSshTransport } = require('./remote-transport');
const { createRemoteIndexer } = require('./remote-index');
const { createRemoteWatcher } = require('./remote-watch');
const { createRemoteActivityTracker } = require('./remote-activity');
const { createLocalTranscriptTracker } = require('./local-transcript-activity');

const remoteTransport = createSshTransport({ log });
const remoteIndexer = createRemoteIndexer({
  getHosts: () => (getSetting('global') || {}).remoteHosts,
  getRefreshMs: () => (getSetting('global') || {}).remoteRefreshMs,
  dataDir: path.dirname(DB_PATH),
  transport: remoteTransport,
  scanFolders: scanFoldersViaWorker,
  listIndexedFolderKeys: () => [...getAllFolderMeta().keys()],
  dropFolder: (folderKey) => { deleteCachedFolder(folderKey); deleteSearchFolder(folderKey); },
  setRemoteRoots,
  notify: notifyRendererProjectsChanged,
  log,
});

// see .ai/contexts/session-cache.md ("Remote hosts — watch channel")
const remoteWatcher = createRemoteWatcher({ log });
let watchedAliases = new Set();
function onRemoteWatchEvent(alias) { remoteIndexer.refreshHostNow(alias).catch(() => {}); }

// see .ai/contexts/session-cache.md ("Remote hosts — busy spinner (issue #242)")
const remoteActivityTracker = createRemoteActivityTracker({});

function onRemoteWatchActivity(alias, rel) {
  const result = remoteActivityTracker.record(alias, rel);
  if (!result) return;
  if (mainWindow && !mainWindow.isDestroyed()) {
    mainWindow.webContents.send('remote-activity', result);
  }
}

function startWatcherForHost(host) {
  remoteWatcher.start(host.alias, onRemoteWatchEvent, onRemoteWatchActivity);
}

function syncRemoteWatchers() {
  const declared = enabledHosts((getSetting('global') || {}).remoteHosts);
  const wanted = new Set(declared.map(h => h.alias));
  for (const alias of watchedAliases) {
    if (!wanted.has(alias)) remoteWatcher.stop(alias);
  }
  for (const host of declared) {
    if (!remoteWatcher.isRunning(host.alias)) startWatcherForHost(host);
  }
  watchedAliases = wanted;
}

// see .ai/contexts/session-cache.md ("Remote hosts backoff" — manual reconnect, issue #252)
function restartWatcherForAlias(alias) {
  const declared = enabledHosts((getSetting('global') || {}).remoteHosts);
  const host = declared.find(h => h.alias === alias);
  if (!host) return;
  remoteWatcher.stop(alias);
  startWatcherForHost(host);
  watchedAliases.add(alias);
}

// see .ai/contexts/session-cache.md ("Remote hosts — tmux attach")
const remoteAttachAdapter = createTmuxAttachAdapter({
  spawnPty: (file, args, ptyOpts) => spawnPty(file, args, { ...ptyOpts, cwd: os.homedir(), env: cleanPtyEnv }),
  log,
});

// see .ai/contexts/session-state.md ("The two lifecycle verbs: detach and stop")
const remoteStopAdapter = createRemoteStopAdapter({ log });

// Joins the sidebar's remote sessions to the indexer's live descriptors so the
// renderer can route a click without ever naming an attach mechanism itself
// — see .ai/contexts/session-cache.md ("Remote hosts — tmux attach").
function annotateRemoteAttachable(projects) {
  const hostInfoByAlias = new Map();
  function hostInfo(alias) {
    if (!hostInfoByAlias.has(alias)) {
      const { sessions, at, error } = remoteIndexer.getRemoteSessions(alias);
      const { nextAttemptAt } = remoteIndexer.getRemoteHostState(alias);
      hostInfoByAlias.set(alias, { at, error, nextAttemptAt, byId: new Map(sessions.map(d => [d.sessionId, d])) });
    }
    return hostInfoByAlias.get(alias);
  }
  for (const project of projects) {
    if (project.remoteAlias) {
      const info = hostInfo(project.remoteAlias);
      project.remoteHostAt = info.at;
      project.remoteHostError = info.error;
      project.remoteHostNextAttemptAt = info.nextAttemptAt || null;
    }
    for (const session of project.sessions) {
      if (session.remoteAlias) {
        const descriptor = hostInfo(session.remoteAlias).byId.get(session.sessionId);
        session.remoteAttachable = !!(descriptor && remoteAttachAdapter.supports(descriptor));
        session.status = descriptor ? (descriptor.status || null) : null;
        session.statusUpdatedAt = descriptor ? (descriptor.statusUpdatedAt || null) : null;
        session.remoteActiveAt = remoteActivityTracker.activeAt(session.remoteAlias, session.sessionId);
        // listed descriptor = live process (ALIVE filter) — see .ai/contexts/session-state.md
        session.remoteDescriptorSeen = !!descriptor;
      } else {
        // Same descriptor vocabulary, read from the local ~/.claude/sessions/<pid>.json
        // instead of a remote host's mirror -- see .ai/contexts/cli-session-state.md
        const local = cliSessionState.getStatus(session.sessionId);
        session.status = local ? local.status : undefined;
        session.statusUpdatedAt = local ? local.statusUpdatedAt : undefined;
      }
    }
  }
  return projects;
}

// see .ai/contexts/session-cache.md ("Remote hosts — descriptor-only sessions")
function toSidebarPlaceholderSession(ph) {
  return {
    sessionId: ph.sessionId,
    summary: ph.summary,
    firstPrompt: null,
    created: null,
    modified: ph.modified,
    messageCount: 0,
    projectPath: ph.projectPath,
    slug: null,
    aiTitle: null,
    parentSessionId: null,
    agentId: null,
    subagentType: null,
    description: null,
    name: null,
    starred: 0,
    archived: 0,
    remoteAlias: ph.remoteAlias,
    remoteDescriptorSeen: ph.remoteDescriptorSeen,
    status: ph.status,
    statusUpdatedAt: ph.statusUpdatedAt,
    placeholder: true,
  };
}

function mergePlaceholderSessions(projects) {
  const placeholders = remoteIndexer.getAllPlaceholderSessions();
  for (const ph of placeholders) {
    const project = projects.find(p => p.remoteAlias === ph.remoteAlias && p.projectPath === ph.projectPath);
    if (project) {
      if (project.sessions.some(s => s.sessionId === ph.sessionId)) continue;
      project.sessions.push(toSidebarPlaceholderSession(ph));
    } else {
      projects.push({
        folder: joinFolderKey(ph.remoteAlias, ph.folder),
        projectPath: ph.projectPath,
        remoteAlias: ph.remoteAlias,
        sessions: [toSidebarPlaceholderSession(ph)],
        missing: false,
      });
    }
  }
  return projects;
}

/** Directory holding a folder key's transcripts, local or mirrored. */
function projectsDirForFolder(folder) {
  return resolveFolderDir(folder);
}

/** resolveJsonlPath for a cache row whose `folder` may carry an alias prefix. */
function resolveSessionJsonlPath(row) {
  const dir = projectsDirForFolder(row && row.folder);
  if (!dir) return null;
  return resolveJsonlPath(dir, { ...row, folder: '.' });
}

// --- IPC: browse-folder ---
ipcMain.handle('browse-folder', async () => {
  const result = await dialog.showOpenDialog(mainWindow, {
    properties: ['openDirectory', 'createDirectory'],
    title: 'Select Project Folder',
  });
  if (result.canceled || !result.filePaths.length) return null;
  return result.filePaths[0];
});

// --- IPC: add-project ---
ipcMain.handle('add-project', (_event, projectPath) => {
  try {
    // Validate the path exists and is a directory
    const stat = fs.statSync(projectPath);
    if (!stat.isDirectory()) return { error: 'Path is not a directory' };

    // Unhide if previously hidden
    const global = getSetting('global') || {};
    if (global.hiddenProjects && global.hiddenProjects.includes(projectPath)) {
      global.hiddenProjects = global.hiddenProjects.filter(p => p !== projectPath);
      setSetting('global', global);
    }

    // Create the corresponding folder in ~/.claude/projects/ so it persists
    const folder = encodeProjectPath(projectPath);
    const folderPath = path.join(PROJECTS_DIR, folder);
    if (!fs.existsSync(folderPath)) {
      fs.mkdirSync(folderPath, { recursive: true });
    }

    // Seed a minimal .jsonl so deriveProjectPath can read the cwd
    if (!fs.readdirSync(folderPath).some(f => f.endsWith('.jsonl'))) {
      const seedId = require('crypto').randomUUID();
      const seedFile = path.join(folderPath, seedId + '.jsonl');
      const now = new Date().toISOString();
      const line = JSON.stringify({ type: 'user', cwd: projectPath, sessionId: seedId, uuid: require('crypto').randomUUID(), timestamp: now, message: { role: 'user', content: 'New project' } });
      fs.writeFileSync(seedFile, line + '\n');
    }

    // Immediately index the new folder so it's in cache before frontend renders
    refreshFolder(folder);
    notifyRendererProjectsChanged();

    return { ok: true, folder, projectPath };
  } catch (err) {
    return { error: err.message };
  }
});

// --- IPC: remove-project ---
ipcMain.handle('remove-project', (_event, projectPath, folderKey) => {
  try {
    // Add to hidden projects list
    const global = getSetting('global') || {};
    const hidden = global.hiddenProjects || [];
    const { alias } = folderKey ? parseFolderKey(folderKey) : { alias: null };
    const hiddenEntry = alias === null ? projectPath : joinFolderKey(alias, projectPath);
    if (!hidden.includes(hiddenEntry)) hidden.push(hiddenEntry);
    global.hiddenProjects = hidden;
    setSetting('global', global);

    // Clean up DB cache and search index for this folder
    const folder = folderKey || encodeProjectPath(projectPath);
    deleteCachedFolder(folder);
    deleteSearchFolder(folder);
    deleteSetting('project:' + projectPath);

    notifyRendererProjectsChanged();
    return { ok: true };
  } catch (err) {
    return { error: err.message };
  }
});

// --- IPC: remap-project ---

/**
 * Atomically rewrite cwd occurrences of oldPath → newPath in a single JSONL
 * file. Uses a .tmp sibling + rename for crash safety. On any failure the .tmp
 * orphan is cleaned up so it cannot block a future remap attempt.
 */
function rewriteJsonlAtomic(filePath, oldPath, newPath) {
  const tmp = filePath + '.tmp';
  try {
    const content = fs.readFileSync(filePath, 'utf8');
    const updated = content.split('\n').map(line => {
      if (!line) return line;
      try {
        const parsed = JSON.parse(line);
        if (parsed.cwd === oldPath) {
          parsed.cwd = newPath;
          return JSON.stringify(parsed);
        }
      } catch {}
      return line;
    }).join('\n');
    fs.writeFileSync(tmp, updated);
    fs.renameSync(tmp, filePath);
  } catch (err) {
    try { fs.unlinkSync(tmp); } catch {}
    throw err;
  }
}

ipcMain.handle('remap-project', (_event, oldPath, newPath) => {
  try {
    // Validate oldPath/newPath are strings (basic sanitisation)
    if (typeof oldPath !== 'string' || typeof newPath !== 'string') {
      return { error: 'Invalid arguments' };
    }

    // Re-check at handler entry: if oldPath came back, no remap is needed
    if (fs.existsSync(oldPath)) {
      return { error: 'Project path now exists — remap no longer needed' };
    }

    // Validate the new path exists and is a directory
    let stat;
    try { stat = fs.lstatSync(newPath); } catch { return { error: 'Path does not exist' }; }
    if (!stat.isDirectory()) return { error: 'Path is not a directory' };

    // Find the session folder for the old project path using the same encoding the CLI uses
    const folder = encodeProjectPath(oldPath);
    const folderPath = path.join(PROJECTS_DIR, folder);
    if (!fs.existsSync(folderPath)) return { error: 'No session data found for this project' };

    // Refuse if any active PTY session is running for this folder — rewriting
    // files while a live claude process is appending them risks data loss
    // (our snapshot + rename would silently drop lines appended between read
    // and rename). The user must stop all sessions for this project first.
    for (const [, session] of activeSessions) {
      // A panel shell appends to no transcript and has no row to stop it from
      // — see .ai/contexts/panel-terminal.md
      if (isPanelShellSession(session)) continue;
      if (!session.exited && encodeProjectPath(session.projectPath) === folder) {
        return { error: 'Active sessions for this project — stop them first' };
      }
    }

    // Rewrite cwd in all session JSONL files (top-level + subagents) so
    // `claude --resume` from CLI also picks up the new path.
    const sessionFiles = enumerateSessionFiles(folderPath);
    for (const { filePath } of sessionFiles) {
      rewriteJsonlAtomic(filePath, oldPath, newPath);
    }

    // Refresh the folder cache so the new path takes effect in the UI
    refreshFolder(folder);
    notifyRendererProjectsChanged();
    return { ok: true };
  } catch (err) {
    return { error: err.message };
  }
});

// --- IPC: delete-worktree ---
// Validated path pattern: <project>/.<segment>/[worktrees/]<name>
// Matches .claude/worktrees/<n>, .claude-worktrees/<n>, .worktrees/<n>
const WORKTREE_PATH_RE = /^(.+?)\/\.(?:claude\/worktrees|claude-worktrees|worktrees)\/([^/]+)\/?$/;

// WORKTREE_PATH_RE only checks *shape* (a string that looks like
// <something>/.claude/worktrees/<name>) — match[1] can be any string with
// that suffix stripped, including a directory this install has never heard
// of. Bind it to a project root Switchboard actually knows about before
// letting `git -C <parentRepo> worktree remove` run against it.
function isKnownProjectRoot(candidatePath) {
  return _isKnownProjectRoot(candidatePath, [...getKnownProjectPaths()]);
}

ipcMain.handle('delete-worktree', (_event, worktreePath) => {
  return new Promise((resolve) => {
    // Normalize trailing slash
    const normalizedPath = worktreePath.replace(/\/$/, '');

    // Validate path matches a known worktree layout
    const match = normalizedPath.match(WORKTREE_PATH_RE);
    if (!match) {
      return resolve({ ok: false, error: 'Path does not match a recognized worktree layout' });
    }
    const parentRepo = match[1];
    if (!isKnownProjectRoot(parentRepo)) {
      return resolve({ ok: false, error: 'Parent repository is not a known project' });
    }

    // Helper: run git worktree remove, optionally double-force
    function runRemove(doubleForce, callback) {
      const args = ['-C', parentRepo, 'worktree', 'remove', '-f'];
      if (doubleForce) args.push('-f');
      args.push('--', normalizedPath);
      execFile('git', args, (err, _stdout, stderr) => callback(err, stderr));
    }

    runRemove(false, (err, stderr) => {
      if (err && /locked/i.test(stderr || err.message || '')) {
        // Retry with double force for locked worktrees
        runRemove(true, (err2, stderr2) => {
          if (err2) return resolve({ ok: false, error: (stderr2 || err2.message || String(err2)).trim() });
          afterRemove();
        });
      } else if (err) {
        return resolve({ ok: false, error: (stderr || err.message || String(err)).trim() });
      } else {
        afterRemove();
      }
    });

    function afterRemove() {
      // Clean up DB cache: delete all sessions whose projectPath matches worktreePath
      let removed = 0;
      try {
        const allRows = getAllCached();
        for (const row of allRows) {
          if (row.projectPath === normalizedPath) {
            deleteCachedSession(row.sessionId);
            deleteSearchSession(row.sessionId);
            removed++;
          }
        }
      } catch (dbErr) {
        log.warn('[delete-worktree] DB cleanup error:', dbErr.message);
      }

      // Remove from hiddenProjects if present
      try {
        const global = getSetting('global') || {};
        if (Array.isArray(global.hiddenProjects) && global.hiddenProjects.includes(normalizedPath)) {
          global.hiddenProjects = global.hiddenProjects.filter(p => p !== normalizedPath);
          setSetting('global', global);
        }
      } catch {}

      // Also clean up folder meta
      try {
        const folder = encodeProjectPath(normalizedPath);
        deleteCachedFolder(folder);
        deleteSearchFolder(folder);
      } catch {}

      log.info(`[delete-worktree] removed=${normalizedPath} sessions=${removed}`);
      notifyRendererProjectsChanged();
      resolve({ ok: true, removed });
    }
  });
});

// --- IPC: worktree-status ---
ipcMain.handle('worktree-status', (_event, worktreePath) => {
  return new Promise((resolve) => {
    const normalizedPath = worktreePath.replace(/\/$/, '');
    const match = normalizedPath.match(WORKTREE_PATH_RE);
    if (!match) {
      return resolve({ ok: false, error: 'Path does not match a recognized worktree layout' });
    }
    const parentRepo = match[1];
    if (!isKnownProjectRoot(parentRepo)) {
      return resolve({ ok: false, error: 'Parent repository is not a known project' });
    }

    execFile('git', ['-C', parentRepo, '-C', normalizedPath, 'status', '--porcelain'], (err, stdout, stderr) => {
      if (err) {
        return resolve({ ok: false, error: (stderr || err.message || String(err)).trim() });
      }
      const dirty = stdout.split('\n').map(l => l.trimEnd()).filter(Boolean);
      resolve({ ok: true, dirty, total: dirty.length });
    });
  });
});

// --- IPC: get-projects ---
ipcMain.handle('open-external', (_event, url) => {
  log.info('[open-external IPC]', url);
  if (/^https?:\/\//i.test(url)) return shell.openExternal(url);
});

// --- IPC: open a local file in the OS default app (terminal right-click menu) ---
ipcMain.handle('open-path', (_event, filePath) => {
  if (typeof filePath !== 'string' || !filePath) return;
  const resolved = path.resolve(filePath);
  // Mirror the read/save-file-for-panel guard: never hand a sensitive path
  // (~/.ssh, credentials, etc.) to the OS default opener.
  if (isSensitivePath(resolved)) return;
  return shell.openPath(resolved);
});

// --- IPC: read clipboard (terminal right-click paste; see clipboard-write-text) ---
ipcMain.handle('read-clipboard', () => clipboard.readText());

// --- IPC: clipboard write ---
// The renderer's navigator.clipboard.writeText is gated on focus/user-activation and
// is flaky-to-dead on Linux/Wayland (Ozone). The main-process clipboard has no such
// strings attached, so all terminal copies go through here.
ipcMain.handle('clipboard-write-text', (_event, text) => {
  if (typeof text === 'string') clipboard.writeText(text);
});

ipcMain.handle('popup-app-menu', (_event, position) => {
  const menu = Menu.getApplicationMenu();
  if (!menu || !mainWindow || mainWindow.isDestroyed()) return false;
  const { x, y } = menuPopupPoint(position, mainWindow.webContents.getZoomFactor());
  menu.popup({ window: mainWindow, x, y });
  return true;
});

ipcMain.handle('toggle-full-screen', () => {
  if (!mainWindow || mainWindow.isDestroyed()) return false;
  mainWindow.setFullScreen(!mainWindow.isFullScreen());
  return mainWindow.isFullScreen();
});

// --- IPC: does the clipboard hold an image? ---
// A terminal is a text stream, so an image can't ride a text paste. When one is on
// the clipboard the renderer forwards Ctrl+V (0x16) to the PTY instead of doing a
// text paste, so the child — e.g. Claude Code — runs its own native clipboard paste
// and reads the image straight off the system clipboard (the same thing a regular
// terminal does). This just reports whether to take that path.
ipcMain.handle('clipboard-has-image', () => !clipboard.readImage().isEmpty());

// --- IPC: MCP bridge ---
ipcMain.on('mcp-diff-response', (_event, sessionId, diffId, action, editedContent) => {
  resolvePendingDiff(sessionId, diffId, action, editedContent);
});

ipcMain.handle('read-file-for-panel', async (_event, filePath) => {
  try {
    const resolved = path.resolve(filePath);
    if (isSensitivePath(resolved)) return { ok: false, error: 'access to sensitive path denied' };
    // A file link in terminal output decides this path, so the size is not
    // ours -- see .ai/contexts/viewer-panel.md, "Bounds".
    const stat = fs.statSync(resolved);
    if (!stat.isFile()) return { ok: false, error: 'not a regular file' };
    if (stat.size > PANEL_FILE_MAX_BYTES) {
      return { ok: false, error: 'file too large to display' };
    }
    const buf = fs.readFileSync(resolved);
    if (buf.includes(0)) return { ok: false, error: 'binary file' };
    return { ok: true, content: buf.toString('utf8') };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

ipcMain.handle('save-file-for-panel', async (_event, filePath, content) => {
  try {
    const resolved = path.resolve(filePath);
    if (isSensitivePath(resolved)) return { ok: false, error: 'access to sensitive path denied' };
    if (!fs.existsSync(resolved)) return { ok: false, error: 'File does not exist' };
    fs.writeFileSync(resolved, content, 'utf8');
    // Close the sub-second window between save and search: if the saved file
    // belongs to a type that the FTS index tracks, invalidate its signature so
    // the next get-work-files / get-memories call triggers a full reindex
    // (matching the explicit invalidation in save-memory / delete-work-file).
    if (resolved.includes('/.work-files/')) invalidateFtsSignature('work-file');
    if (resolved.endsWith('.md')) invalidateFtsSignature('memory');
    return { ok: true };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

// ── File Watching (for viewer panels) ────────────────────────────────
const fileWatchers = new Map(); // filePath → FSWatcher

function closeAllFileWatchers() {
  for (const watcher of fileWatchers.values()) {
    try { watcher.close(); } catch {}
  }
  fileWatchers.clear();
}

ipcMain.handle('watch-file', (_event, filePath) => {
  const resolved = path.resolve(filePath);
  if (isSensitivePath(resolved)) return { ok: false, error: 'access to sensitive path denied' };
  if (fileWatchers.has(resolved)) return { ok: true };
  try {
    let debounce = null;
    const watcher = fs.watch(resolved, (eventType) => {
      if (eventType !== 'change') return;
      if (debounce) clearTimeout(debounce);
      debounce = setTimeout(() => {
        if (mainWindow && !mainWindow.isDestroyed()) {
          mainWindow.webContents.send('file-changed', resolved);
        }
      }, 300);
    });
    fileWatchers.set(resolved, watcher);
    return { ok: true };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

ipcMain.handle('unwatch-file', (_event, filePath) => {
  const resolved = path.resolve(filePath);
  const watcher = fileWatchers.get(resolved);
  if (watcher) {
    watcher.close();
    fileWatchers.delete(resolved);
  }
  return { ok: true };
});

// Full re-scan triggered from the UI. Re-reads every jsonl file in the worker
// thread, which is the only path that rebuilds search_fts with the live tail
// of active sessions (refreshFolder uses a header-only read by design — see
// session-cache.js). Concurrent callers share the same in-flight worker via
// populateCacheViaWorker's internal Promise.
ipcMain.handle('rebuild-cache', async () => {
  try {
    await populateCacheViaWorker();
    return { ok: true };
  } catch (err) {
    console.error('Error rebuilding cache:', err);
    return { ok: false, error: err.message };
  }
});

ipcMain.handle('get-projects', async (_event, showArchived) => {
  try {
    // "Cache has rows" is NOT enough to call the start warm: the scan worker
    // streams one DB write per folder, so killing the app mid-scan leaves
    // session_cache partially populated. Only the completeness marker —
    // written when the worker's final done message arrives — proves the
    // initial scan actually finished. Without it, a partial cache must take
    // the cold branch below: the warm branch's reconcileCacheFromFilesystem()
    // would find every still-missing folder stat-dirty and re-parse them all
    // synchronously on the main thread — the original multi-minute freeze,
    // reachable by simply relaunching after an interrupted first scan.
    const needsPopulate = !isCachePopulated() || !isSearchIndexPopulated() || !isInitialScanComplete();

    if (needsPopulate) {
      // First call after a migration that clears session_cache (e.g. v4), or a
      // genuine first launch, finds an empty cache. Used to `await` the full
      // scan here so the response carried the freshly-populated cache — but on
      // a large ~/.claude/projects/ (1GB+, witnessed live) that scan takes many
      // minutes, and awaiting it left the renderer's very first get-projects
      // call — and therefore the whole sidebar — blocked the entire time with
      // nothing but a "Loading…" label (the user force-quit believing the app
      // had hung). Kick the scan off in the background instead: it now writes
      // each folder to the DB and pushes `projects-changed` as it completes
      // (see populateCacheViaWorker in session-cache.js), and emits
      // `indexing-progress` events the renderer turns into a one-time banner.
      // This immediate response returns whatever's cached right now (empty
      // session rows on a true first run, but buildProjectsFromCache still
      // lists every on-disk project directory synchronously below).
      populateCacheViaWorker();
    } else {
      // Cache already populated: pick up folders changed while the app was
      // closed, or never indexed by an older build, so sessions/worktrees don't
      // silently go missing. Stat-gated, so it's cheap when nothing has changed.
      //
      // Deliberately NOT called in the needsPopulate branch above: on a truly
      // cold cache, cache_meta is still empty at this point (the background
      // worker hasn't written a single folder yet), so this stat-gate would be
      // true for every folder and reconcileCacheFromFilesystem would run a full
      // synchronous refreshFolder() sweep -- a full JSONL parse of the entire
      // tree, on the main thread, before this handler could return. That
      // reintroduces the exact multi-minute blocking hang the fire-and-forget
      // populateCacheViaWorker() call above exists to avoid (PR #124 review
      // finding F1 -- see test/get-projects-cold-start-reconcile.test.js).
      reconcileCacheFromFilesystem();
    }

    return annotateRemoteAttachable(mergePlaceholderSessions(buildProjectsFromCache(showArchived)));
  } catch (err) {
    console.error('Error listing projects:', err);
    return [];
  }
});

// --- IPC: get-stats ---
ipcMain.handle('get-stats', () => {
  try {
    if (!fs.existsSync(STATS_CACHE_PATH)) return null;
    const raw = fs.readFileSync(STATS_CACHE_PATH, 'utf8');
    return JSON.parse(raw);
  } catch (err) {
    console.error('Error reading stats cache:', err);
    return null;
  }
});

// --- IPC: get-stats-from-db ---
// Builds a stats object from session_cache so the heatmap reflects real usage
// including subagent sessions (which claude /stats silently ignores) and
// periods where Claude already rotated the parent JSONL files off disk.
ipcMain.handle('get-stats-from-db', () => {
  try {
    return buildStatsFromDb();
  } catch (err) {
    log.error('Error building stats from DB:', err);
    return null;
  }
});

// Build the full stats object the renderer consumes. Sourced from
// session_metrics (per-(session,date,model) tokens/tool-calls/messages bucketed
// by message timestamp) so tokens, tool calls, and per-model usage are all real
// data — not the hardcoded {} the heatmap-only path used to return.
function buildStatsFromDb() {
  const daily = getDailyMetrics();       // [{date, messageCount, toolCallCount, tokens, sessionCount}]
  const totals = getTotalCounts();
  const lastComputedDate = new Date().toISOString().slice(0, 10);
  return {
    dailyActivity: daily,
    dailyModelTokens: getDailyModelTokens(),
    modelUsage: getModelUsage(),
    totalMessages: totals.totalMessages,
    totalSessions: totals.totalSessions,
    totalToolCalls: totals.totalToolCalls,
    totalTokens: totals.totalTokens,
    firstSessionDate: daily[0]?.date || lastComputedDate,
    lastComputedDate,
  };
}

// --- IPC: refresh-stats (fetch /usage + build stats from DB; /stats PTY removed) ---
ipcMain.handle('refresh-stats', async () => {
  try {
    // /stats PTY call removed — heatmap is now sourced from session_cache via
    // get-stats-from-db. Only /usage is fetched here (rate-limits panel).
    const usage = await fetchAndTransformUsage().catch(() => ({}));

    // Build stats from DB (same as get-stats-from-db) so the caller gets both
    // at once and the renderer can update heatmap + usage in a single round-trip.
    let stats = null;
    try {
      stats = buildStatsFromDb();
    } catch (dbErr) {
      log.error('Error building stats from DB in refresh-stats:', dbErr);
    }

    return { stats, usage: usage || {} };
  } catch (err) {
    log.error('Error refreshing stats:', err);
    return { stats: null, usage: {} };
  }
});

// --- IPC: get-usage (lightweight, API-only, no PTY) ---
ipcMain.handle('get-usage', async () => {
  try {
    return await fetchAndTransformUsage() || {};
  } catch (err) {
    log.error('Error fetching usage:', err);
    return {};
  }
});

// ---------------------------------------------------------------------------
// FTS dirty-flag: skip full reindex when file set hasn't changed.
// Each tab handler (get-memories, get-work-files) computes a cheap signature
// from the collected file list (sorted filePath + mtimeMs + size) and compares
// it to the last-indexed signature stored here. If equal, the expensive
// deleteSearchType + upsertSearchEntries block is skipped entirely — including
// the full-file readFileSync calls on every file.
//
// Invariant: the result payload (file tree returned to the UI) is built and
// returned unconditionally; only the FTS side-effect is gated.
//
// Invalidation: save-memory and delete-work-file mutations clear the stored
// signature for their respective type, forcing a fresh reindex on the next
// tab open (even if mtime precision rounds to the same second on some FSes).
// ---------------------------------------------------------------------------

/** @type {Map<string, string>} type → last-indexed signature */
const _ftsIndexSignature = new Map();

/**
 * Compute a cheap stable signature for an array of indexed file descriptors.
 * @param {Array<{filePath: string, mtimeMs: number, size: number}>} files
 * @returns {string}
 */
function computeIndexSignature(files) {
  // Sort by filePath for determinism regardless of scan order.
  const sorted = [...files].sort((a, b) => a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0);
  return sorted.map(f => `${f.filePath}\x00${f.mtimeMs}\x00${f.size}`).join('\n');
}

/**
 * Returns true when the file set for the given FTS type has changed since
 * the last reindex (or was never indexed), and updates the stored signature.
 * @param {string} type - FTS type key ('memory' | 'work-file')
 * @param {string} sig  - result of computeIndexSignature()
 * @returns {boolean}
 */
function shouldReindex(type, sig) {
  if (_ftsIndexSignature.get(type) === sig) return false;
  _ftsIndexSignature.set(type, sig);
  return true;
}

/**
 * Invalidate the stored signature for a given FTS type, forcing a full
 * reindex on the next get-memories / get-work-files call.
 * @param {string} type
 */
function invalidateFtsSignature(type) {
  _ftsIndexSignature.delete(type);
}

// --- IPC: get-memories ---
function folderToShortPath(folder) {
  // Convert "-Users-home-dev-MyClaude" → "dev/MyClaude"
  const parts = folder.replace(/^-/, '').split('-');
  const meaningful = parts.filter(Boolean);
  return meaningful.slice(-2).join('/');
}

ipcMain.handle('get-memories', () => {
  const global = getSetting('global') || {};
  const hiddenProjects = new Set(global.hiddenProjects || []);

  // The known-project set is rebuilt from disk on every isAllowedMemoryPath
  // call, so binding it once per handler call keeps this off a per-file path.
  const knownRoots = [...getKnownProjectPaths()];
  const isAllowed = (filePath) => _isAllowedMemoryPath(filePath, knownRoots);

  // Bodies of the files accepted below, kept for the FTS index at the end of
  // this handler. They travel here rather than on the entries themselves: the
  // entries go to the renderer, the bodies have no business going with them.
  const bodies = new Map();
  const listed = ({ content, ...entry }) => {
    bodies.set(entry.filePath, content);
    return entry;
  };

  // --- Global files ---
  const globalFiles = scanMdFiles(CLAUDE_DIR, isAllowed).map(f => ({ ...listed(f), displayPath: '~/.claude' }));

  // --- Per-project files ---
  const projects = [];
  try {
    if (fs.existsSync(PROJECTS_DIR)) {
      const folders = fs.readdirSync(PROJECTS_DIR, { withFileTypes: true })
        .filter(d => d.isDirectory() && d.name !== '.git')
        .map(d => d.name);

      for (const folder of folders) {
        const folderPath = path.join(PROJECTS_DIR, folder);
        const projectPath = deriveProjectPath(folderPath, folder);
        if (projectPath && hiddenProjects.has(projectPath)) continue;

        // Use same 2-deep short path as Sessions tab (e.g. "dev/MyClaude")
        // Splits on both separators — `cwd` is backslash-separated on Windows,
        // where splitting on '/' alone left the whole path as one segment.
        const shortName = projectPath
          ? projectPath.split(/[\\/]/).filter(Boolean).slice(-2).join('/')
          : folderToShortPath(folder);
        const files = [];
        const seenPaths = new Set();

        // 1. ~/.claude/projects/{folder}/ — claude-home .md files
        const claudeHomeFiles = scanMdFiles(folderPath, isAllowed);
        for (const f of claudeHomeFiles) {
          files.push({ ...listed(f), displayPath: '~/.claude', source: 'claude-home' });
          seenPaths.add(f.filePath);
        }
        // memory/MEMORY.md
        const memoryDir = path.join(folderPath, 'memory');
        const memoryFiles = scanMdFiles(memoryDir, isAllowed);
        for (const f of memoryFiles) {
          files.push({ ...listed(f), displayPath: '~/.claude', source: 'claude-home' });
          seenPaths.add(f.filePath);
        }

        // 2. {projectPath}/ — project root CLAUDE.md, agents.md
        if (projectPath) {
          for (const name of ['CLAUDE.md', 'GEMINI.md', 'agents.md']) {
            const fp = path.join(projectPath, name);
            const accepted = acceptMdFile(fp, isAllowed);
            if (accepted && !seenPaths.has(fp)) {
              files.push({ ...listed(accepted), displayPath: shortName + '/', source: 'project' });
              seenPaths.add(fp);
            }
          }

          // 3. {projectPath}/.claude/ — commands/*.md and other .md files
          const dotClaudeDir = path.join(projectPath, '.claude');
          const dotClaudeFiles = scanMdFiles(dotClaudeDir, isAllowed);
          for (const f of dotClaudeFiles) {
            if (!seenPaths.has(f.filePath)) {
              files.push({ ...listed(f), displayPath: shortName + '/.claude/', source: 'project' });
              seenPaths.add(f.filePath);
            }
          }
          // commands/*.md
          const commandsDir = path.join(dotClaudeDir, 'commands');
          const commandFiles = scanMdFiles(commandsDir, isAllowed);
          for (const f of commandFiles) {
            if (!seenPaths.has(f.filePath)) {
              files.push({ ...listed(f), displayPath: shortName + '/.claude/commands/', source: 'project' });
              seenPaths.add(f.filePath);
            }
          }
        }

        if (files.length > 0) {
          projects.push({ folder, projectPath: projectPath || '', shortName, files });
        }
      }
    }
  } catch (err) {
    console.error('Error scanning memories:', err);
  }

  // Sort projects by most recent file modified date
  projects.sort((a, b) => {
    const aMax = Math.max(...a.files.map(f => new Date(f.modified).getTime()));
    const bMax = Math.max(...b.files.map(f => new Date(f.modified).getTime()));
    return bMax - aMax;
  });

  const result = { global: { files: globalFiles }, projects };

  // Index all files for FTS — skipped when the file set is unchanged (dirty-flag).
  try {
    const allFiles = [
      ...globalFiles.map(f => ({ ...f, label: 'Global' })),
      ...projects.flatMap(p => p.files.map(f => ({ ...f, label: p.shortName }))),
    ];
    const sig = computeIndexSignature(allFiles.map(f => ({
      filePath: f.filePath,
      mtimeMs: new Date(f.modified).getTime(),
      size: 0, // .md files don't carry size in scanMdFiles; mtime + path is sufficient
    })));
    if (shouldReindex('memory', sig)) {
      deleteSearchType('memory');
      upsertSearchEntries(allFiles.map(f => ({
        id: f.filePath, type: 'memory', folder: null,
        title: f.label + ' ' + f.filename,
        body: bodies.get(f.filePath) ?? '',
      })));
    }
  } catch {}

  return result;
});

// --- IPC: read-memory ---
ipcMain.handle('read-memory', (_event, filePath) => {
  try {
    const literal = path.resolve(filePath);
    if (!literal.endsWith('.md')) return '';
    // Read on the guard's own resolved path, not on `literal` again — see
    // resolveAllowedMemoryPath's contract.
    const resolved = resolveAllowedMemoryPath(literal);
    if (!resolved) return '';
    return fs.readFileSync(resolved, 'utf8');
  } catch (err) {
    console.error('Error reading memory file:', err);
    return '';
  }
});

// --- IPC: save-memory ---
ipcMain.handle('save-memory', (_event, filePath, content) => {
  try {
    const literal = path.resolve(filePath);
    if (!literal.endsWith('.md')) return { ok: false, error: 'not a .md file' };
    // Same requirement as read-memory: existsSync/writeFileSync below must
    // target the guard's resolved path, not `literal` again.
    const resolved = resolveAllowedMemoryPath(literal);
    if (!resolved) return { ok: false, error: 'path not allowed' };
    if (!fs.existsSync(resolved)) return { ok: false, error: 'file does not exist' };
    fs.writeFileSync(resolved, content, 'utf8');
    // Invalidate the FTS signature so the next get-memories call reindexes
    // (mtime change is caught by the signature, but an explicit invalidation
    // guards against sub-second writes where the mtime might not advance).
    invalidateFtsSignature('memory');
    return { ok: true };
  } catch (err) {
    console.error('Error saving memory file:', err);
    return { ok: false, error: err.message };
  }
});

// --- IPC: get-work-files ---
// Walks <projectPath>/.work-files/ recursively for all known projects.
// Returns { projects: WorkFilesProject[] } — empty projects are skipped.
// Caps at WORK_FILES_CAP files per project (most recent by mtime) to guard
// against huge .work-files trees (e.g. tagpay has ~39k files).
const WORK_FILES_CAP = 200;

function walkWorkFiles(dir, baseDir, results) {
  let entries;
  try {
    entries = fs.readdirSync(dir, { withFileTypes: true });
  } catch {
    return;
  }
  for (const e of entries) {
    const fullPath = path.join(dir, e.name);
    if (e.isDirectory()) {
      walkWorkFiles(fullPath, baseDir, results);
    } else if (e.isFile()) {
      try {
        const stat = fs.statSync(fullPath);
        const relativePath = path.relative(baseDir, fullPath);
        results.push({
          filename: e.name,
          filePath: fullPath,
          relativePath,
          modified: stat.mtime.toISOString(),
          size: stat.size,
        });
      } catch {}
    }
  }
}

ipcMain.handle('get-work-files', () => {
  const global = getSetting('global') || {};
  const hiddenProjects = new Set(global.hiddenProjects || []);
  // Dedupe by projectPath: multiple ~/.claude/projects/ folders (e.g. worktrees
  // of the same repo) can derive to the same projectPath via
  // resolveWorktreePath, which would otherwise produce N copies of the same
  // header+file list in the UI.
  const seen = new Set();
  const projects = [];

  try {
    if (fs.existsSync(PROJECTS_DIR)) {
      const folders = fs.readdirSync(PROJECTS_DIR, { withFileTypes: true })
        .filter(d => d.isDirectory() && d.name !== '.git')
        .map(d => d.name);

      for (const folder of folders) {
        const folderPath = path.join(PROJECTS_DIR, folder);
        const projectPath = deriveProjectPath(folderPath, folder);
        if (!projectPath) continue;
        if (hiddenProjects.has(projectPath)) continue;
        if (seen.has(projectPath)) continue;
        seen.add(projectPath);

        const workFilesDir = path.join(projectPath, '.work-files');
        if (!fs.existsSync(workFilesDir)) continue;

        const shortName = projectPath.split('/').filter(Boolean).slice(-2).join('/');

        const allFiles = [];
        walkWorkFiles(workFilesDir, workFilesDir, allFiles);

        // Sort by modified desc
        allFiles.sort((a, b) => new Date(b.modified) - new Date(a.modified));

        const totalCount = allFiles.length;
        const files = allFiles.slice(0, WORK_FILES_CAP);

        if (files.length > 0) {
          projects.push({ projectPath, shortName, files, totalCount });
        }
      }
    }
  } catch (err) {
    console.error('Error scanning work-files:', err);
  }

  // Sort projects by most recent file modified date
  projects.sort((a, b) => {
    const aMax = a.files.length > 0 ? new Date(a.files[0].modified).getTime() : 0;
    const bMax = b.files.length > 0 ? new Date(b.files[0].modified).getTime() : 0;
    return bMax - aMax;
  });

  // Index for FTS — text files ≤ 64KB, skip .jsonl — skipped when file set is unchanged.
  try {
    const allFiles = projects.flatMap(proj => proj.files.map(f => ({ ...f, proj })));
    const sig = computeIndexSignature(allFiles.map(f => ({
      filePath: f.filePath,
      mtimeMs: new Date(f.modified).getTime(),
      size: f.size,
    })));
    if (shouldReindex('work-file', sig)) {
      deleteSearchType('work-file');
      const TEXT_MAX = 64 * 1024;
      const entries = allFiles.map(f => {
        let body = '';
        if (!f.relativePath.endsWith('.jsonl') && f.size <= TEXT_MAX) {
          try { body = fs.readFileSync(f.filePath, 'utf8'); } catch {}
        }
        return {
          id: f.filePath, type: 'work-file', folder: null,
          title: f.proj.shortName + ' ' + f.relativePath,
          body,
        };
      });
      upsertSearchEntries(entries);
    }
  } catch {}

  return { projects };
});

// --- IPC: read-work-file ---
ipcMain.handle('read-work-file', (_event, filePath) => {
  try {
    const resolved = path.resolve(filePath);
    // Security: path must contain /.work-files/ segment
    if (!resolved.includes('/.work-files/') && !resolved.includes('\\.work-files\\')) {
      return '[access denied]';
    }
    if (!fs.existsSync(resolved)) return '';
    const stat = fs.statSync(resolved);
    if (stat.size > 2 * 1024 * 1024) return '[file too large to display]';
    // Detect binary: try reading as utf8; if it fails or contains null bytes, treat as binary
    const buf = fs.readFileSync(resolved);
    if (buf.includes(0)) return '[binary file]';
    return buf.toString('utf8');
  } catch (err) {
    console.error('Error reading work file:', err);
    return '';
  }
});

// --- IPC: delete-work-file ---
ipcMain.handle('delete-work-file', (_event, filePath) => {
  try {
    const resolved = path.resolve(filePath);
    if (!resolved.includes('/.work-files/') && !resolved.includes('\\.work-files\\')) {
      return { ok: false, error: 'access denied' };
    }
    if (!fs.existsSync(resolved)) return { ok: false, error: 'not found' };
    fs.unlinkSync(resolved);
    // Invalidate the FTS signature so the next get-work-files call reindexes.
    // Deletion changes the path set, which the signature would catch; the explicit
    // invalidation is a belt-and-braces guard for path-set mutations.
    invalidateFtsSignature('work-file');
    return { ok: true };
  } catch (err) {
    console.error('Error deleting work file:', err);
    return { ok: false, error: err.message };
  }
});

// --- IPC: search ---
// Routed through the search-query worker so that slow FTS5 phrase queries
// (e.g. a 60-char pasted URL) do not block the Electron main event loop.
// The renderer already awaits window.api.search(...) — this change is transparent.
ipcMain.handle('search', (_event, type, query, titleOnly) => {
  return searchViaWorker(type, query, titleOnly);
});

// --- IPC: settings ---
ipcMain.handle('get-setting', (_event, key) => {
  return getSetting(key);
});

ipcMain.handle('set-setting', (_event, key, value) => {
  setSetting(key, value);
  return { ok: true };
});

// --- IPC: remote hosts ---
// Re-reads the declared hosts and pulls straight away, so a host added in
// Settings shows up without waiting a full refresh interval.
ipcMain.handle('remote-hosts-apply', () => {
  try {
    const running = remoteIndexer.restart();
    syncRemoteWatchers();
    return { ok: true, running };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

// see .ai/contexts/session-cache.md ("Remote hosts backoff" — manual reconnect, issue #252)
ipcMain.handle('remote-hosts-refresh', async () => {
  try {
    const result = await remoteIndexer.refreshNow({ force: true });
    for (const host of enabledHosts((getSetting('global') || {}).remoteHosts)) {
      restartWatcherForAlias(host.alias);
    }
    return { ok: true, ...result };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

ipcMain.handle('remote-host-refresh', async (_event, alias) => {
  try {
    const result = await remoteIndexer.refreshHostNow(alias, { force: true });
    restartWatcherForAlias(alias);
    return { ok: true, ...result };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

ipcMain.handle('delete-setting', (_event, key) => {
  deleteSetting(key);
  return { ok: true };
});

// --- Scheduled tasks ---
const scheduleIpc = require('./schedule-ipc');

ipcMain.handle('get-shell-profiles', () => {
  // TODO(lint): `_shellProfiles` is scoped inside shell-profiles.js and not
  // reachable from here — this line is a no-op left over from a refactor.
  // Kept as-is for now; tracked separately. See tests/eslint-and-renderer-coverage.
  // eslint-disable-next-line no-undef
  _shellProfiles = null; // refresh on each request
  return getShellProfiles();
});

ipcMain.handle('get-effective-settings', (_event, projectPath) => {
  const global = getSetting('global') || {};
  const project = projectPath ? (getSetting('project:' + projectPath) || {}) : {};
  const effective = { ...SETTING_DEFAULTS };
  for (const key of Object.keys(SETTING_DEFAULTS)) {
    // Only `undefined` (key never saved at this scope) falls through to the
    // next-broader scope. An explicit `null` — e.g. permissionMode's "Default"
    // choice, which settings-panel.js persists as `value || null` — is a real,
    // deliberate value and must win.
    //
    // This previously also skipped on `!== null`, which made an explicitly
    // saved "Default" indistinguishable from "never configured". Two
    // consequences: a project that narrowed permissionMode back to Default
    // silently kept inheriting the global mode, and any SETTING_DEFAULTS value
    // other than null was unreachable at project scope.
    if (global[key] !== undefined) {
      effective[key] = global[key];
    }
    if (project[key] !== undefined) {
      effective[key] = project[key];
    }
  }
  return effective;
});

// --- IPC: get-active-sessions ---
// see .ai/contexts/ipc-bridge.md "Busy-state reconciliation"
ipcMain.handle('get-active-sessions', () => {
  const active = [];
  for (const [sessionId, session] of activeSessions) {
    if (!session.exited) active.push({ sessionId, busy: !!session._cliBusy });
  }
  if (TRACE.on) trace('poll.snapshot', null, { count: active.length, entries: active });
  return active;
});

// --- IPC: get-active-terminals --- (plain terminal sessions for renderer restore)
ipcMain.handle('get-active-terminals', () => {
  const terminals = [];
  for (const [sessionId, session] of activeSessions) {
    // see .ai/contexts/panel-terminal.md
    if (!session.exited && session.isPlainTerminal && !isPanelShellSession(session)) {
      terminals.push({ sessionId, projectPath: session.projectPath });
    }
  }
  return terminals;
});

// --- IPC: stop-session ---
ipcMain.handle('stop-session', (_event, sessionId) => {
  const session = activeSessions.get(sessionId);
  if (!session || session.exited) return { ok: false, error: 'not running' };
  killPty(session, sessionId);
  return { ok: true };
});

// --- IPC: remote-stop-session ---
// see .ai/contexts/session-state.md ("The two lifecycle verbs: detach and stop")
ipcMain.handle('remote-stop-session', async (_event, payload) => {
  const alias = payload && payload.alias;
  const sessionId = payload && payload.sessionId;
  if (typeof alias !== 'string' || !alias || typeof sessionId !== 'string' || !sessionId) {
    return { ok: false, error: 'invalid request' };
  }
  const descriptor = remoteIndexer.getRemoteSessions(alias).sessions.find(s => s.sessionId === sessionId);
  if (!descriptor) return { ok: false, error: 'session not found on that host' };

  const result = await remoteStopAdapter.stop(alias, descriptor);
  if (result.ok) {
    remoteIndexer.dropRemoteSession(alias, sessionId);
    // see .ai/contexts/session-state.md ("The two lifecycle verbs: detach and stop")
    notifyRendererProjectsChanged();
    remoteIndexer.refreshHostNow(alias, { force: true }).catch(() => {});
    const attachedSession = activeSessions.get(sessionId);
    if (attachedSession && attachedSession.kind === 'remote-attach' && !attachedSession.exited) {
      killPty(attachedSession, sessionId);
    }
  }
  return result;
});

// --- IPC: git-changes-status / git-changes-diff — see .ai/contexts/changes-view.md ---
function resolveGitChangesTarget(sessionId) {
  return gitChangesTarget.resolveGitChangesTarget(sessionId, {
    getCachedFolder,
    isRemoteFolder,
    parseFolderKey,
    getRemoteSessions: (alias) => remoteIndexer.getRemoteSessions(alias),
    activeSessions,
    resolveSessionRealCwd,
    existsSync: (p) => fs.existsSync(p),
    projectsDir: PROJECTS_DIR,
  });
}

function gitChangesRunnerFor(target) {
  return target.kind === 'remote'
    ? createGitChangesRunner({ kind: 'remote', cwd: target.cwd, alias: target.alias })
    : createGitChangesRunner({ kind: 'local', cwd: target.cwd });
}

ipcMain.handle('git-changes-status', async (_event, sessionId) => {
  const target = resolveGitChangesTarget(sessionId);
  if (!target.ok) return target;
  try {
    const result = await gitChangesRunnerFor(target).status();
    return result.ok === false ? result : { ...result, kind: target.kind };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

// filePath is a git pathspec, or an untracked file's --no-index operand — see .ai/contexts/changes-view.md
ipcMain.handle('git-changes-diff', async (_event, sessionId, filePath, staged, untracked) => {
  if (typeof filePath !== 'string' || !filePath) return { ok: false, error: 'invalid path' };
  const target = resolveGitChangesTarget(sessionId);
  if (!target.ok) return target;
  try {
    return await gitChangesRunnerFor(target).diff(filePath, { staged: !!staged, untracked: !!untracked });
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

// filePath is a repo-relative path, resolved and contained main-side — see .ai/contexts/changes-view.md ("Editing a changed file")
ipcMain.handle('git-changes-file', async (_event, sessionId, filePath, opts) => {
  if (typeof filePath !== 'string' || !filePath) return { ok: false, error: 'invalid path', reason: 'invalid-path' };
  const target = gitChangesFile.requireLocalTarget(resolveGitChangesTarget(sessionId));
  if (!target.ok) return target;
  try {
    return await gitChangesFile.readChangesFile({
      cwd: target.cwd,
      relPath: filePath,
      staged: !!(opts && opts.staged),
      maxBytes: PANEL_FILE_MAX_BYTES,
    });
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

ipcMain.handle('git-changes-save', async (_event, sessionId, filePath, content, version) => {
  if (typeof filePath !== 'string' || !filePath) return { ok: false, error: 'invalid path', reason: 'invalid-path' };
  const target = gitChangesFile.requireLocalTarget(resolveGitChangesTarget(sessionId));
  if (!target.ok) return target;
  try {
    const result = await gitChangesFile.writeChangesFile({
      cwd: target.cwd,
      relPath: filePath,
      content,
      version,
      maxBytes: PANEL_FILE_MAX_BYTES,
    });
    if (!result.ok) return result;
    if (result.savedPath.split(/[\\/]/).includes('.work-files')) invalidateFtsSignature('work-file');
    if (result.savedPath.endsWith('.md')) invalidateFtsSignature('memory');
    return { ok: true, version: result.version };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

// see .ai/contexts/changes-view.md ("Saving over a file that moved")
const changesWatchers = createChangesWatchRegistry({
  watchFn: (filePath, handler) => fs.watch(filePath, handler),
  send: (sessionId, relPath) => {
    if (mainWindow && !mainWindow.isDestroyed()) {
      mainWindow.webContents.send('git-changes-file-changed', sessionId, relPath);
    }
  },
});

// A path from terminal output is untrusted input — see .ai/contexts/terminal-path-links.md
ipcMain.handle('resolve-terminal-paths', (_event, sessionId, texts) => {
  if (!Array.isArray(texts)) return [];
  const wanted = texts.slice(0, TERMINAL_PATH_BATCH_MAX);
  const where = terminalPathTarget.resolveTerminalPathsCwd(sessionId, {
    getSession: (id) => activeSessions.get(id),
    resolveTarget: resolveGitChangesTarget,
    resolvePanelCwd: resolvePanelTerminalCwd,
  });
  if (!where.ok) return wanted.map(() => ({ ok: false, reason: where.reason }));
  const deps = {
    isSensitivePath,
    statSync: (p) => fs.statSync(p),
    hasNullByte: terminalPathTarget.fileHasNullByte,
    homedir: () => os.homedir(),
    maxBytes: PANEL_FILE_MAX_BYTES,
  };
  return wanted.map((text) => terminalPathTarget.resolveTerminalPathTarget(text, where.cwd, deps));
});

// filePath is absolute here — the only Changes IPC that takes one, and it
// gives back a repo-relative row — see .ai/contexts/changes-view.md
ipcMain.handle('git-changes-locate', async (_event, sessionId, filePath) => {
  if (typeof filePath !== 'string' || !filePath) return { ok: false, error: 'invalid path', reason: 'invalid-path' };
  const target = gitChangesFile.requireLocalTarget(resolveGitChangesTarget(sessionId));
  if (!target.ok) return target;
  try {
    return await gitChangesFile.locateChangesFile({ cwd: target.cwd, absolutePath: filePath });
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

ipcMain.handle('git-changes-watch', async (_event, sessionId, filePath) => {
  if (typeof filePath !== 'string' || !filePath) return { ok: false, error: 'invalid path', reason: 'invalid-path' };
  const target = gitChangesFile.requireLocalTarget(resolveGitChangesTarget(sessionId));
  if (!target.ok) return target;

  const repo = await gitChangesFile.resolveRepoDirs(target.cwd, {});
  if (!repo) return { ok: false, error: 'not a git repository', reason: 'repo' };
  const resolved = gitChangesFile.resolveTargetInsideRepo(repo, filePath, {});
  if (!resolved.ok) return resolved;

  return changesWatchers.watch(sessionId, filePath, resolved.path);
});

ipcMain.handle('git-changes-unwatch', (_event, sessionId, filePath) => {
  if (typeof filePath !== 'string' || !filePath) return { ok: true };
  return changesWatchers.unwatch(sessionId, filePath);
});

// --- IPC: toggle-star ---
ipcMain.handle('toggle-star', (_event, sessionId) => {
  const starred = toggleStar(sessionId);
  return { starred };
});

// --- IPC: rename-session ---
ipcMain.handle('rename-session', (_event, sessionId, name) => {
  setName(sessionId, name || null);
  // Update search index title to include the new name
  const cached = getCachedSession(sessionId);
  const summary = cached?.summary || '';
  updateSearchTitle(sessionId, 'session', (name ? name + ' ' : '') + summary);
  return { name: name || null };
});

// --- IPC: archive-session ---
ipcMain.handle('read-session-jsonl', (_event, sessionId) => {
  const folder = getCachedFolder(sessionId);
  if (!folder) return { error: 'Session not found in cache' };
  const folderDir = projectsDirForFolder(folder);
  if (!folderDir) return { error: 'Session belongs to a host that is no longer declared' };
  const jsonlPath = path.join(folderDir, sessionId + '.jsonl');
  try {
    const content = fs.readFileSync(jsonlPath, 'utf-8');
    const entries = [];
    for (const line of content.split('\n')) {
      if (!line.trim()) continue;
      try { entries.push(JSON.parse(line)); } catch {}
    }
    return { entries };
  } catch (err) {
    return { error: err.message };
  }
});

ipcMain.handle('read-subagent-jsonl', (_event, parentSessionId, agentId) => {
  const row = getCachedSession('sub:' + parentSessionId + ':' + agentId);
  if (!row) return { error: 'Subagent session not found in cache' };
  const jsonlPath = resolveSessionJsonlPath(row);
  if (!jsonlPath) return { error: 'Subagent belongs to a host that is no longer declared' };
  try {
    const content = fs.readFileSync(jsonlPath, 'utf-8');
    const entries = [];
    for (const line of content.split('\n')) {
      if (!line.trim()) continue;
      try { entries.push(JSON.parse(line)); } catch {}
    }
    return { entries };
  } catch (err) {
    return { error: err.message };
  }
});

ipcMain.handle('list-subagents', (_event, parentSessionId) => {
  return getCachedByParent(parentSessionId).map(r => ({
    sessionId: r.sessionId,
    agentId: r.agentId,
    subagentType: r.subagentType,
    description: r.description,
    modified: r.modified,
    messageCount: r.messageCount,
  }));
});

// ── Subagent live-tail watchers ──────────────────────────────────────────────

ipcMain.handle('start-subagent-watch', (_event, parentSessionId, agentId) => {
  const row = getCachedSession('sub:' + parentSessionId + ':' + agentId);
  if (!row) return { error: 'Subagent not found in cache' };
  const filePath = resolveSessionJsonlPath(row);
  if (!filePath) return { error: 'Subagent belongs to a host that is no longer declared' };

  const watchId = ++subagentWatcherSeq;
  let offset = 0;
  // Seek to EOF so we only deliver *new* lines
  try { offset = fs.statSync(filePath).size; } catch {}

  function readNewEntries() {
    try {
      const stat = fs.statSync(filePath);
      if (stat.size <= offset) return;
      const buf = Buffer.alloc(stat.size - offset);
      const fd = fs.openSync(filePath, 'r');
      const bytesRead = fs.readSync(fd, buf, 0, buf.length, offset);
      fs.closeSync(fd);
      if (bytesRead <= 0) return;
      offset += bytesRead;
      const text = buf.toString('utf8', 0, bytesRead);
      const entries = [];
      for (const line of text.split('\n')) {
        if (!line.trim()) continue;
        try { entries.push(JSON.parse(line)); } catch {}
      }
      if (entries.length > 0 && mainWindow && !mainWindow.isDestroyed()) {
        mainWindow.webContents.send('subagent-watch-event', { parentSessionId, agentId, entries });
      }
    } catch {}
  }

  // Coalesce rapid JSONL appends into a single incremental read. Mirrors the
  // debounce used by the projects watcher (see startProjectsWatcher) instead of
  // polling stat() once per second per watcher, which pegged the main process at
  // idle when watchers accumulated.
  let debounceTimer = null;
  function scheduleRead() {
    if (debounceTimer) clearTimeout(debounceTimer);
    debounceTimer = setTimeout(() => {
      debounceTimer = null;
      readNewEntries();
    }, 300);
  }

  let watcher = null;
  let pollInterval = null;
  try {
    watcher = fs.watch(filePath, { persistent: false }, (eventType) => {
      if (eventType === 'rename') return; // file replaced/removed — ignore
      scheduleRead();
    });
    watcher.on('error', (err) => {
      log.warn(`[subagent-watch] fs.watch error watchId=${watchId}: ${err.message}`);
    });
  } catch (err) {
    // Robustness fallback only when fs.watch can't attach: poll on a long
    // interval (10s) so a failed inotify registration never busy-stats the file.
    log.warn(`[subagent-watch] fs.watch failed watchId=${watchId}, polling fallback: ${err.message}`);
    pollInterval = setInterval(readNewEntries, 10000);
  }

  function teardown() {
    if (debounceTimer) { clearTimeout(debounceTimer); debounceTimer = null; }
    if (watcher) { try { watcher.close(); } catch {} watcher = null; }
    if (pollInterval) { clearInterval(pollInterval); pollInterval = null; }
  }

  subagentWatchers.set(watchId, { filePath, parentSessionId, agentId, teardown });
  log.info(`[subagent-watch] start watchId=${watchId} parent=${parentSessionId} agentId=${agentId}`);
  return { watchId };
});

ipcMain.handle('stop-subagent-watch', (_event, watchId) => {
  const entry = subagentWatchers.get(watchId);
  if (!entry) return { ok: false };
  entry.teardown();
  subagentWatchers.delete(watchId);
  log.info(`[subagent-watch] stop watchId=${watchId}`);
  return { ok: true };
});

// --- IPC: delete-session ---
// Permanently removes a session's transcript from disk. This is the one action
// in the app that destroys user history, so it is deliberately narrow:
//
//  - the id must look like a session id, and is used only as a filename
//    component under PROJECTS_DIR — never joined with caller-supplied paths
//  - the resolved file must still sit inside PROJECTS_DIR after realpath, so a
//    symlinked transcript cannot be used to delete something elsewhere
//  - a session with a live PTY is refused; killing the process and deleting its
//    transcript underneath itself is not something to do implicitly
//
// Subagent transcripts live in a sibling <sessionId>/ directory and are part of
// the same conversation, so they go too — leaving them orphans the tree.
// --- IPC: delete-session-preview ---
// What deleting `sessionId` would remove, so the confirmation dialog can state
// it rather than asking the user to trust a generic warning.
ipcMain.handle('delete-session-preview', (_event, sessionId) => {
  const id = String(sessionId || '');
  let folder = null;
  try { folder = getCachedFolder(id); } catch {}
  if (isRemoteFolder(folder)) return { ok: false, error: REMOTE_READ_ONLY };
  const resolved = resolveDeletionTargets(PROJECTS_DIR, id, folder);
  if (!resolved.ok) return { ok: false, error: resolved.error };
  let subagents = 0;
  try {
    subagents = (getCachedByParent(id) || []).filter(r => r.sessionId && r.sessionId !== id).length;
  } catch {}
  const running = activeSessions.has(id) && !activeSessions.get(id).exited;
  return { ok: true, transcripts: resolved.targets.length, subagents, running };
});

ipcMain.handle('delete-session', (_event, sessionId) => {
  const id = String(sessionId || '');
  if (activeSessions.has(id) && !activeSessions.get(id).exited) {
    return { ok: false, error: 'session is still running — close it first' };
  }

  // Validation, symlink resolution and containment live in
  // delete-session-target.js so they can be executed by tests against real
  // paths and symlinks. getCachedFolder makes the common case an O(1) lookup
  // instead of a readdir of every project; fall back to the scan when the row
  // is missing (a placeholder session that was never indexed).
  let folder = null;
  try { folder = getCachedFolder(id); } catch {}
  // A mirrored transcript is a copy; the next refresh would fetch it back.
  if (isRemoteFolder(folder)) return { ok: false, error: REMOTE_READ_ONLY };
  const resolved = resolveDeletionTargets(PROJECTS_DIR, id, folder);
  if (!resolved.ok) return { ok: false, error: resolved.error };
  for (const r of resolved.refused) {
    log.warn(`[delete-session] refusing ${r.path} — ${r.reason} (${r.real})`);
  }

  // Collect the subagents BEFORE removing anything: their transcripts sit inside
  // the parent's directory and go with it, but they are indexed under their own
  // composite `sub:<parent>:<agent>` ids, which nothing else here would clear.
  // Left behind, the sidebar renders them as a phantom "Orphan subagents" group
  // and search keeps returning hits pointing at deleted files.
  let subagentIds = [];
  try {
    subagentIds = (getCachedByParent(id) || [])
      .map(row => row.sessionId)
      .filter(sid => sid && sid !== id);
  } catch {}

  const removed = [];
  for (const target of resolved.targets) {
    try {
      fs.rmSync(target, { recursive: true, force: true });
      removed.push(target);
    } catch (err) {
      log.error(`[delete-session] failed to remove ${target}: ${err.message}`);
      return { ok: false, error: `could not delete: ${err.message}` };
    }
  }

  for (const sid of [id, ...subagentIds]) {
    try { deleteCachedSession(sid); } catch {}
    try { deleteSearchSession(sid); } catch {}
  }

  // A session with no transcript on disk is not an error case: launchNewSession
  // shows a card before claude starts, so a launch that died leaves one with
  // nothing behind it — and those are precisely the cards a user wants gone.
  if (!removed.length) {
    log.info(`[delete-session] ${id} had no transcript — cleared caches only`);
    return { ok: true, removed: [], subagents: subagentIds.length, placeholder: true };
  }

  log.info(`[delete-session] ${id} removed ${removed.length} path(s), ${subagentIds.length} subagent row(s)`);
  return { ok: true, removed, subagents: subagentIds.length };
});

ipcMain.handle('archive-session', (_event, sessionId, archived) => {
  const val = archived ? 1 : 0;
  setArchived(sessionId, val);
  return { archived: val };
});

// --- Sandbox launch helpers (Linux / bubblewrap) ---
// In the packaged app main.js lives inside app.asar, which bash cannot read
// from — the script is asarUnpacked (see package.json build config). The
// separator-anchored pattern rewrites only the real app.asar path segment,
// not an install directory whose name merely contains "app.asar".
function sandboxScriptPath() {
  return path.join(__dirname, 'scripts', 'claude-sandbox.sh')
    .replace(/app\.asar([\\/])/, 'app.asar.unpacked$1');
}

// "Additional Directories" is a comma-separated free-text field. Single parse
// point so the claude `--add-dir` args and the sandbox bind list can never
// disagree about what the user typed.
function parseAddDirs(value) {
  if (!value) return [];
  return String(value).split(',').map(d => d.trim()).filter(Boolean);
}

// SWITCHBOARD_SANDBOX_BINDS is colon-separated (env vars cannot carry NUL), so
// a path that itself contains ':' cannot be transported — the script would
// split it into fragments and never bind the real directory. Newlines are
// rejected for the same reason: they survive the env var but not every shell
// splitter downstream. Drop such paths loudly instead of half-binding them.
function sandboxBindEnv(dirs) {
  const usable = dirs.filter(d => {
    if (d.includes(':')) {
      log.warn(`[sandbox] skipping extra bind — ':' in path is unsupported: ${JSON.stringify(d)}`);
      return false;
    }
    if (/[\r\n]/.test(d)) {
      log.warn(`[sandbox] skipping extra bind — newline in path is unsupported: ${JSON.stringify(d)}`);
      return false;
    }
    return true;
  });
  return usable.length ? usable.join(':') : undefined;
}

// see .ai/contexts/session-cache.md ("Remote hosts — tmux attach")
function wireSessionPty(session, sessionId, ptyProcess) {
  ptyProcess.onData(data => {
    const currentId = session.realSessionId || sessionId;

    // Parse OSC sequences (title changes, progress, notifications, etc.)
    if (data.includes('\x1b]')) {
      const oscMatches = data.matchAll(/\x1b\](\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/g);
      for (const m of oscMatches) {
        const code = m[1];
        const payload = m[2].slice(0, 120);
        // Detect Claude CLI busy state from the OSC 0 title — see .ai/contexts/ipc-bridge.md
        if (code === '0') {
          const { busy: isBusy, idle: isIdle, via } = classifyTitleActivity(payload, { allowFallback: !session.isPlainTerminal });
          if (LOG_DEBUG_ON) log.debug(`[OSC 0] session=${currentId} cp=${codePoints(payload, 1)} rule=${via} busy=${isBusy} idle=${isIdle} wasBusy=${!!session._cliBusy}`);
          if (TRACE.on) trace('osc.title', currentId, { cp: codePoints(payload, 3), title: payload.slice(0, 60), busy: isBusy, idle: isIdle, rule: via, was: !!session._cliBusy, decision: busyDecision(isBusy, isIdle, !!session._cliBusy) });
          if (isBusy && !session._cliBusy) {
            session._cliBusy = true;
            session._oscIdle = false;
            if (LOG_DEBUG_ON) log.debug(`[OSC 0] session=${currentId} → BUSY`);
            if (TRACE.on) trace('busy.emit', currentId, { busy: true, via: 'osc0', sent: !!(mainWindow && !mainWindow.isDestroyed()) });
            if (mainWindow && !mainWindow.isDestroyed()) {
              mainWindow.webContents.send('cli-busy-state', currentId, true);
            }
          } else if (isIdle && session._cliBusy) {
            session._cliBusy = false;
            session._oscIdle = true;
            if (LOG_DEBUG_ON) log.debug(`[OSC 0] session=${currentId} → IDLE`);
            if (TRACE.on) trace('busy.emit', currentId, { busy: false, via: 'osc0', sent: !!(mainWindow && !mainWindow.isDestroyed()) });
            if (mainWindow && !mainWindow.isDestroyed()) {
              mainWindow.webContents.send('cli-busy-state', currentId, false);
            }
          }
        }
      }
      // Parse iTerm2 OSC 9 sequences (terminated by BEL \x07 or ST \x1b\\)
      const osc9Matches = data.matchAll(/\x1b\]9;([^\x07\x1b]*)(?:\x07|\x1b\\)/g);
      for (const osc9 of osc9Matches) {
        const payload = osc9[1];
        // OSC 9;4 progress: 4;0; = clear/done, 4;1;N = running at N%, 4;2;N = error, 4;3; = indeterminate
        if (payload.startsWith('4;')) {
          const level = payload.split(';')[1];
          if (level === '0') continue; // 4;0 is also used for clearing, making it unreliable as an idle signal
          if (LOG_DEBUG_ON) log.debug(`[OSC 9;4] session=${currentId} level=${level} payload="${payload}" wasBusy=${!!session._cliBusy}`);
          if (TRACE.on) trace('osc.progress', currentId, { level, payload: payload.slice(0, 60), was: !!session._cliBusy, decision: progressDecision(level, !!session._cliBusy) });
          if ((level === '1' || level === '2' || level === '3') && !session._cliBusy) {
            session._cliBusy = true;
            session._oscIdle = false;
            if (LOG_DEBUG_ON) log.debug(`[OSC 9;4] session=${currentId} → BUSY`);
            if (TRACE.on) trace('busy.emit', currentId, { busy: true, via: 'osc9.4', sent: !!(mainWindow && !mainWindow.isDestroyed()) });
            if (mainWindow && !mainWindow.isDestroyed()) {
              mainWindow.webContents.send('cli-busy-state', currentId, true);
            }
          }
        } else {
          // Regular notification (attention, permission, etc.)
          log.info(`[OSC 9] session=${currentId} message="${payload}"`);
          if (TRACE.on) trace('osc.notify', currentId, { message: payload.slice(0, 120), sent: !!(mainWindow && !mainWindow.isDestroyed()) });
          if (mainWindow && !mainWindow.isDestroyed()) {
            mainWindow.webContents.send('terminal-notification', currentId, payload);
          }
        }
      }
    }

    // Standalone BEL (not part of an OSC sequence)
    if (data.includes('\x07') && !data.includes('\x1b]')) {
      log.info(`[BEL] session=${currentId}`);
    }

    // Track alternate screen mode (only if data contains the marker)
    if (data.includes('\x1b[?')) {
      if (data.includes('\x1b[?1049h') || data.includes('\x1b[?47h')) {
        session.altScreen = true;
        log.info(`[altscreen] session=${currentId} ON`);
      }
      if (data.includes('\x1b[?1049l') || data.includes('\x1b[?47l')) {
        session.altScreen = false;
        log.info(`[altscreen] session=${currentId} OFF`);
      }
    }

    // Buffer output (skip resize-triggered redraws for plain terminals)
    if (!session._suppressBuffer) {
      appendToOutputBuffer(session, data, MAX_BUFFER_SIZE);
    }

    if (mainWindow && !mainWindow.isDestroyed()) {
      mainWindow.webContents.send('terminal-data', currentId, data);
    }
  });

  ptyProcess.onExit(({ exitCode }) => {
    session.exited = true;
    // Clean up MCP server
    const mcpId = session.realSessionId || sessionId;
    shutdownMcpServer(mcpId);
    session.mcpServer = null;

    const realId = session.realSessionId || sessionId;
    if (TRACE.on) trace('pty.exit', realId, { exitCode, alsoUnder: realId !== sessionId ? sessionId : null, wasBusy: !!session._cliBusy, sent: !!(mainWindow && !mainWindow.isDestroyed()) });
    if (mainWindow && !mainWindow.isDestroyed()) {
      mainWindow.webContents.send('process-exited', realId, exitCode);
      // If a fork transition re-keyed this session under realId but the PTY
      // exited before transition detection ran, also notify the renderer for
      // the original sessionId so it doesn't stay stuck as "Running".
      if (realId !== sessionId && activeSessions.has(sessionId)) {
        mainWindow.webContents.send('process-exited', sessionId, exitCode);
      }
    }
    activeSessions.delete(realId);
    // Clean up the original key too in case transition detection hasn't run yet
    activeSessions.delete(sessionId);
    activityReporter.sessionEnded(realId);
    activityReporter.sessionEnded(sessionId);
  });
}

// --- IPC: open-terminal ---
ipcMain.handle('open-terminal', async (_event, sessionId, projectPath, isNew, sessionOptions, initialSize) => {
  if (!mainWindow) return { ok: false, error: 'no window' };

  // Reattach to existing session
  if (activeSessions.has(sessionId)) {
    const session = activeSessions.get(sessionId);
    session.rendererAttached = true;
    session.firstResize = !session.isPlainTerminal;

    // If TUI is in alternate screen mode, send escape to switch into it
    if (session.altScreen && !session.isPlainTerminal) {
      mainWindow.webContents.send('terminal-data', sessionId, '\x1b[?1049h');
    }

    // Send buffered output for reattach
    for (const chunk of session.outputBuffer) {
      mainWindow.webContents.send('terminal-data', sessionId, chunk);
    }

    if (!session.isPlainTerminal) {
      // Hide cursor after buffer replay — the live PTY stream or resize nudge
      // will re-show it at the correct position, avoiding a stale cursor artifact
      mainWindow.webContents.send('terminal-data', sessionId, '\x1b[?25l');
    }

    return { ok: true, reattached: true, mcpActive: !!session.mcpServer, sandbox: !!session.sandbox };
  }

  // see .ai/contexts/session-cache.md ("Remote hosts — tmux attach")
  if (!isNew) {
    let cachedFolder = null;
    try { cachedFolder = getCachedFolder(sessionId); } catch {}
    // see .ai/contexts/session-cache.md ("Remote hosts — descriptor-only sessions")
    const alias = isRemoteFolder(cachedFolder)
      ? parseFolderKey(cachedFolder).alias
      : (cachedFolder ? null : remoteIndexer.findSessionAlias(sessionId));
    if (alias) {
      const descriptor = remoteIndexer.getRemoteSessions(alias).sessions.find(s => s.sessionId === sessionId);
      const localPtySize = normalizePtySize(initialSize);
      const attachResult = descriptor
        ? await remoteAttachAdapter.attach(alias, descriptor, localPtySize)
        : { ok: false, error: REMOTE_READ_ONLY };
      if (!attachResult.ok) return { ok: false, error: attachResult.error || REMOTE_READ_ONLY };

      const remoteCwd = (descriptor && typeof descriptor.cwd === 'string') ? descriptor.cwd : null;
      const remoteSession = {
        pty: attachResult.ptyProcess,
        // handle: {write, isAlive} — see .ai/contexts/trigger-watcher.md, "Session handle"
        handle: attachResult.ptyProcess,
        host: alias, kind: 'remote-attach',
        rendererAttached: true, exited: false,
        outputBuffer: [], outputBufferSize: 0, altScreen: false,
        projectPath, firstResize: true,
        cwd: remoteCwd,
        isPlainTerminal: false,
        _openedAt: Date.now(),
      };
      activeSessions.set(sessionId, remoteSession);
      wireSessionPty(remoteSession, sessionId, attachResult.ptyProcess);
      return { ok: true, reattached: false, remote: true, sandbox: false };
    }
  }

  // For a Claude resume, spawn in the session's real recorded cwd (e.g. its
  // worktree) rather than the possibly-collapsed projectPath — otherwise
  // `claude --resume` can't find the conversation. Forks resume too (they run
  // `claude --resume <forkFrom> --fork-session` despite isNew being true), so
  // they need the fork source's real cwd. Only the spawn side moves:
  // project-level settings stay keyed on the collapsed projectPath, which is
  // also what the renderer header uses to display the shell profile. Genuinely
  // new sessions and plain terminals keep the requested projectPath.
  let spawnCwd = projectPath;
  const resumeSourceId = sessionOptions?.forkFrom
    ? String(sessionOptions.forkFrom)
    : (!isNew ? sessionId : null);
  if (resumeSourceId && sessionOptions?.type !== 'terminal') {
    const realCwd = resolveSessionRealCwd(
      PROJECTS_DIR, resumeSourceId, projectPath ? encodeProjectPath(projectPath) : null
    );
    if (realCwd && fs.existsSync(realCwd)) spawnCwd = realCwd;
  }

  // see .ai/contexts/panel-terminal.md ("Main process")
  const panelOwnerId = sessionOptions?.type === 'terminal' && sessionOptions.panelFor
    ? String(sessionOptions.panelFor)
    : null;
  if (panelOwnerId) {
    const panelTarget = resolvePanelTerminalCwd(panelOwnerId, resolveGitChangesTarget);
    if (!panelTarget.ok) return { ok: false, error: panelTarget.error };
    spawnCwd = panelTarget.cwd;
  }

  // Spawn new PTY
  if (!fs.existsSync(spawnCwd)) {
    return { ok: false, error: `project directory no longer exists: ${spawnCwd}` };
  }

  // Spawn at the size the renderer actually measured for the terminal
  // container. Spawning at a fixed 120x30 and only correcting on the first
  // terminal-resize left every session running against a wrong width until
  // then — the shell wrapped its output for 120 columns while xterm displayed
  // another, and TUI cursor moves landed a line off. normalizePtySize falls
  // back to the historical 120x30 when the renderer could not measure.
  const { cols: spawnCols, rows: spawnRows } = normalizePtySize(initialSize);

  const isPlainTerminal = sessionOptions?.type === 'terminal';

  // Resolve shell profile from effective settings
  const effectiveProfileId = (() => {
    const global = getSetting('global') || {};
    const project = projectPath ? (getSetting('project:' + projectPath) || {}) : {};
    let profileId = SETTING_DEFAULTS.shellProfile;
    if (global.shellProfile !== undefined && global.shellProfile !== null) profileId = global.shellProfile;
    if (project.shellProfile !== undefined && project.shellProfile !== null) profileId = project.shellProfile;
    return profileId;
  })();
  // WSL profiles only work for plain terminals — Claude CLI sessions need the
  // Windows shell because session data lives on the Windows filesystem.
  const requestedProfile = resolveShell(effectiveProfileId);
  const useWslProfile = isWslShell(requestedProfile.path) && isPlainTerminal;
  const shellProfile = (isWslShell(requestedProfile.path) && !isPlainTerminal)
    ? resolveShell('auto')
    : requestedProfile;
  const shell = shellProfile.path;
  const shellExtraArgs = [...(shellProfile.args || [])];
  const isWsl = isWslShell(shell);
  // For WSL, convert Windows path to /mnt/ path and pass via --cd;
  // the spawn cwd must remain a valid Windows path for wsl.exe itself.
  if (isWsl) {
    const wslCwd = windowsToWslPath(spawnCwd);
    shellExtraArgs.unshift('--cd', wslCwd);
  }
  log.info(`[shell] profile=${shellProfile.id} shell=${shell} args=${JSON.stringify(shellExtraArgs)}`);

  let knownJsonlFiles = new Set();
  let projectFolder = null;

  if (!isPlainTerminal) {
    // Snapshot existing .jsonl files before spawning (for new session + fork detection)
    projectFolder = encodeProjectPath(spawnCwd);
    const claudeProjectDir = path.join(PROJECTS_DIR, projectFolder);
    if (fs.existsSync(claudeProjectDir)) {
      try {
        knownJsonlFiles = new Set(
          fs.readdirSync(claudeProjectDir).filter(f => f.endsWith('.jsonl'))
        );
      } catch {}
    }
  }

  let ptyProcess;
  let mcpServer = null;
  try {
    if (isPlainTerminal) {
      // Plain terminal: interactive login shell, no claude command
      // Inject a shell function to override `claude` with a helpful message
      const claudeShim = 'claude() { echo "\\033[33mTo start a Claude session, use the + button in the sidebar.\\033[0m"; return 1; }; export -f claude 2>/dev/null;';
      ptyProcess = spawnPty(shell, shellArgs(shell, undefined, shellExtraArgs), {
        name: 'xterm-256color',
        cols: spawnCols,
        rows: spawnRows,
        cwd: isWsl ? os.homedir() : spawnCwd,
        env: {
          ...cleanPtyEnv,
          TERM: 'xterm-256color', COLORTERM: 'truecolor', TERM_PROGRAM: 'iTerm.app', TERM_PROGRAM_VERSION: '3.6.6', FORCE_COLOR: '3', ITERM_SESSION_ID: '1',
          CLAUDECODE: '1',
          // ZDOTDIR trick won't work reliably; instead inject via ENV (sh/bash) or precmd
          ENV: claudeShim,
          BASH_ENV: claudeShim,
        },
      });
      // For zsh, ENV/BASH_ENV don't apply — write the function after shell starts
      setTimeout(() => {
        if (!ptyProcess._isDisposed) {
          try {
            ptyProcess.write(claudeShim + ' clear\n');
          } catch {}
        }
      }, 300);
    } else {
      // Build claude command, using array to prevent accidental shell injection
      const claudeArgs = [];
      // A sidebar card is not proof the session exists on disk: launchNewSession
      // shows one before claude starts, so a launch that fails immediately (bad
      // flag, missing directory) leaves a card whose transcript was never
      // written. Resuming that id makes claude exit with "No conversation found
      // with session ID", and the banner's advice — re-click to relaunch — could
      // never work because every retry resumed the same missing id. Start it
      // instead, reusing the id the sidebar already shows.
      const startsFresh = isNew
        || (!sessionOptions?.forkFrom && !sessionTranscriptExists(PROJECTS_DIR, sessionId));
      if (!isNew && startsFresh && !sessionOptions?.forkFrom) {
        log.info(`[open-terminal] ${sessionId} has no transcript — starting it instead of resuming`);
      }
      if (sessionOptions?.forkFrom) {
        claudeArgs.push('--resume', String(sessionOptions.forkFrom), '--fork-session');
      } else if (startsFresh) {
        claudeArgs.push('--session-id', String(sessionId));
      } else {
        claudeArgs.push('--resume', String(sessionId));
      }

      if (sessionOptions) {
        if (sessionOptions.dangerouslySkipPermissions) {
          claudeArgs.push('--dangerously-skip-permissions');
        } else if (sessionOptions.permissionMode) {
          claudeArgs.push('--permission-mode', String(sessionOptions.permissionMode));
        }
        // --worktree only applies when STARTING a session — it creates a fresh
        // isolated git worktree. Resuming (isNew === false) must reuse the
        // session's existing directory, so ignore the worktree option on resume
        // regardless of which call site supplied it (sidebar click, schedule
        // creator, fork, …). Otherwise a resume tries to spin up a new worktree
        // and fails to attach.
        if (startsFresh && sessionOptions.worktree && !isGitRepo(spawnCwd)) {
          // Worktree is commonly enabled globally, but plenty of projects are
          // not git repos. Passing --worktree there makes claude refuse to start
          // at all ("Can only use --worktree in a git repository"), which turns
          // one global convenience toggle into a broken project. Drop the flag
          // and run unisolated rather than fail the launch.
          log.warn(`[open-terminal] ${spawnCwd} is not a git repository — launching without --worktree`);
        } else if (startsFresh && sessionOptions.worktree) {
          claudeArgs.push('--worktree');
          if (sessionOptions.worktreeName) {
            claudeArgs.push(String(sessionOptions.worktreeName));
          }
        }
        if (sessionOptions.chrome) {
          claudeArgs.push('--chrome');
        }
        for (const dir of parseAddDirs(sessionOptions.addDirs)) {
          claudeArgs.push('--add-dir', dir);
        }
      }

      if (sessionOptions?.appendSystemPrompt) {
        claudeArgs.push('--append-system-prompt', String(sessionOptions.appendSystemPrompt));
      }

      let claudeCmd = 'claude ' + quoteArgvForShell(shell, claudeArgs);

      // Sandbox: run claude inside a bubblewrap sandbox that only exposes the
      // project directory and Claude's own config/state dirs. Linux only —
      // bwrap has no macOS/Windows equivalent wired up here.
      if (sessionOptions?.sandbox) {
        if (process.platform !== 'linux') {
          return { ok: false, error: 'Sandbox mode requires Linux (bubblewrap)' };
        }
        claudeCmd = quoteArgvForShell(shell, ['bash', sandboxScriptPath()]) + ' ' + quoteArgvForShell(shell, claudeArgs);
      }

      // preLaunchCmd is raw shell by design (e.g. "aws-vault exec profile --")
      // — see pre-launch-cmd-guard.js for what is and isn't blocked and why.
      if (sessionOptions?.preLaunchCmd) {
        const pre = String(sessionOptions.preLaunchCmd);
        const preCheck = validatePreLaunchCmd(pre);
        if (!preCheck.ok) {
          return { ok: false, error: preCheck.error };
        }
        claudeCmd = pre + ' ' + claudeCmd;
      }

      // Start MCP server for this session so Claude CLI sends diffs/file opens to Switchboard
      // (skip if user disabled IDE emulation in global settings)
      if (sessionOptions?.mcpEmulation !== false) {
        try {
          mcpServer = await startMcpServer(sessionId, [spawnCwd], mainWindow, log);
          claudeCmd += ' --ide';
        } catch (err) {
          log.error(`[mcp] Failed to start MCP server for ${sessionId}: ${err.message}`);
        }
      }

      // Anchor the working directory in the command itself. pty.spawn's `cwd`
      // is set below, but it does not survive in practice: the login+interactive
      // shell (`bash -l -i -c`) sources the user's profile first, and anything
      // there that changes directory — or any environment that hands the PTY
      // the app's own cwd — silently relocates claude. It then derives its
      // project folder from the wrong directory and reports "No conversation
      // found with session ID", and with Sandbox on it binds the wrong tree.
      // `&&` so a failed cd aborts rather than running claude somewhere random.
      if (!isWsl && spawnCwd) {
        const base = path.basename(shell).toLowerCase();
        const posixish = base.includes('bash') || base.includes('zsh')
          || base === 'sh' || base === 'dash' || base === 'ksh';
        if (posixish) {
          claudeCmd = quoteArgvForShell(shell, ['cd', spawnCwd]) + ' && ' + claudeCmd;
        }
      }

      const ptyEnv = {
        ...cleanPtyEnv,
        TERM: 'xterm-256color', COLORTERM: 'truecolor',
        TERM_PROGRAM: 'iTerm.app', TERM_PROGRAM_VERSION: '3.6.6', FORCE_COLOR: '3', ITERM_SESSION_ID: '1',
      };
      if (mcpServer) {
        ptyEnv.CLAUDE_CODE_SSE_PORT = String(mcpServer.port);
      }
      if (sessionOptions?.sandbox) {
        // Directories the sandboxed claude must still reach beyond the cwd:
        // the project root when resuming inside a worktree (git metadata lives
        // there), and any user-configured Additional Directories.
        const extraBinds = [];
        if (projectPath && projectPath !== spawnCwd) extraBinds.push(projectPath);
        extraBinds.push(...parseAddDirs(sessionOptions.addDirs));
        const bindEnv = sandboxBindEnv(extraBinds);
        if (bindEnv) ptyEnv.SWITCHBOARD_SANDBOX_BINDS = bindEnv;
      }

      ptyProcess = spawnPty(shell, shellArgs(shell, claudeCmd, shellExtraArgs), {
        name: 'xterm-256color',
        cols: spawnCols,
        rows: spawnRows,
        cwd: isWsl ? os.homedir() : spawnCwd,
        // TERM_PROGRAM=iTerm.app: Claude Code checks this to decide whether to emit
        // OSC 9 notifications (e.g. "needs your attention"). Without it, the packaged
        // app's minimal Electron environment won't trigger those sequences.
        env: ptyEnv,
      });

    }
  } catch (err) {
    return { ok: false, error: `Error spawning PTY: ${err.message}` };
  }

  const session = {
    pty: ptyProcess, rendererAttached: true, exited: false,
    outputBuffer: [], outputBufferSize: 0, altScreen: false,
    projectPath, firstResize: true,
    // see .ai/contexts/trigger-watcher.md, "Target guard"
    cwd: spawnCwd,
    projectFolder, knownJsonlFiles,
    isPlainTerminal, panelFor: panelOwnerId, forkFrom: sessionOptions?.forkFrom || null,
    // Recorded so a reattach can report it too — the renderer badges sandboxed
    // sessions, and a reattached session is still inside the same sandbox.
    sandbox: !!sessionOptions?.sandbox,
    mcpServer, _openedAt: Date.now(),
    // see docs/automation.md — the trigger watcher's politeness guard
    composerState: createComposerState(),
    // see .ai/contexts/trigger-watcher.md, "Session handle"
    host: null, kind: 'local-pty',
  };
  activeSessions.set(sessionId, session);
  if (!isPlainTerminal && !panelOwnerId) activityReporter.sessionStarted({ sessionId, project: projectPath });

  // see .ai/contexts/cli-session-state.md
  if (!isPlainTerminal && !cliSessionState.ensureWatching()) {
    const retry = setTimeout(() => cliSessionState.ensureWatching(), 15000);
    if (typeof retry.unref === 'function') retry.unref();
  }

  wireSessionPty(session, sessionId, ptyProcess);

  if (sessionOptions?.forkFrom) {
    log.info(`[fork-spawn] tempId=${sessionId} forkFrom=${sessionOptions.forkFrom} folder=${projectFolder} knownFiles=${knownJsonlFiles.size}`);
  }

  return { ok: true, reattached: false, mcpActive: !!mcpServer, sandbox: !!sessionOptions?.sandbox };
});

// --- IPC: activity-trace (fire-and-forget, opt-in) ---
// Registered unconditionally — see .ai/contexts/ipc-bridge.md "Activity trace".
ipcMain.on('activity-trace', (_event, cat, sid, fields) => {
  trace(typeof cat === 'string' ? cat : 'renderer', sid, fields, 'renderer');
});

// --- IPC: activity-trace control (the Diagnostics panel) ---
// see docs/activity-trace.md "Toggling it at runtime"
const TRACE_FILE_RE = activityTrace.TRACE_FILE_RE;
const TRACE_READ_CAP = 4 * 1024 * 1024;

function listActivityTraceFiles() {
  let names;
  try { names = fs.readdirSync(TRACE_DIR); } catch { return []; }
  const current = activityTrace.currentFile();
  const files = [];
  for (const name of names) {
    if (!TRACE_FILE_RE.test(name)) continue;
    const filePath = path.join(TRACE_DIR, name);
    try {
      const stat = fs.statSync(filePath);
      if (!stat.isFile()) continue;
      files.push({ name, filePath, size: stat.size, modified: stat.mtime.toISOString(), current: filePath === current });
    } catch {}
  }
  files.sort((a, b) => (a.modified < b.modified ? 1 : a.modified > b.modified ? -1 : 0));
  return files;
}

function resolveTraceFile(filePath) {
  return activityTrace.resolveTraceFilePath(TRACE_DIR, filePath);
}

function activityTraceState() {
  return {
    enabled: TRACE.on,
    dir: TRACE_DIR,
    currentFile: activityTrace.currentFile(),
    fromEnv: activityTrace.envState(process.env) !== null,
  };
}

ipcMain.handle('get-activity-trace-state', () => activityTraceState());

// see .ai/contexts/activitywatch.md ("The IPC surface")
async function activityReportingState() {
  const reachable = activityReporter.enabled ? await activityWatchClient.probe() : null;
  return {
    enabled: activityReporter.enabled,
    destination: 'ActivityWatch',
    url: ACTIVITYWATCH_URL,
    reachable,
    buckets: activityReporter.buckets,
  };
}

ipcMain.handle('get-activity-reporting-state', () => activityReportingState());

ipcMain.handle('set-activity-reporting-enabled', (_event, enabled) => {
  const on = !!enabled;
  activityReporter.setEnabled(on);
  const global = getSetting('global') || {};
  global.activityReporting = on;
  setSetting('global', global);
  log.info(`[activitywatch] reporting ${on ? 'enabled' : 'disabled'} from the UI`);
  return activityReportingState();
});

// see .ai/contexts/activitywatch.md ("The IPC surface")
ipcMain.on('activity-focus', (_event, focus) => {
  if (!focus || typeof focus.sessionId !== 'string' || !focus.sessionId || focus.sessionId.length > 200) {
    activityReporter.focus(null);
    return;
  }
  activityReporter.focus({
    sessionId: focus.sessionId,
    name: typeof focus.name === 'string' ? focus.name.slice(0, 200) : '',
    project: typeof focus.project === 'string' ? focus.project.slice(0, 1024) : '',
  });
});

ipcMain.on('activity-titles', (_event, list) => {
  if (!Array.isArray(list)) return;
  activityReporter.titles(list.slice(0, 500)
    .filter(t => t && typeof t.sessionId === 'string' && t.sessionId && t.sessionId.length <= 200 && typeof t.name === 'string')
    .map(t => ({ sessionId: t.sessionId, name: t.name.slice(0, 200) })));
});

ipcMain.handle('set-activity-trace-enabled', async (_event, enabled) => {
  const on = !!enabled;
  // activityTrace.setEnabled has its own bounded fallback (see
  // docs/activity-trace.md), but this toggle must never hang on it either —
  // belt and suspenders against a stream close that never comes.
  await new Promise((resolve) => {
    let settled = false;
    const timer = setTimeout(() => {
      if (settled) return;
      settled = true;
      log.warn('[activity-trace] setEnabled did not call back in time; unblocking the Diagnostics toggle anyway');
      resolve();
    }, 8000);
    activityTrace.setEnabled(on, () => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      resolve();
    });
  });
  const global = getSetting('global') || {};
  global.activityTrace = on;
  setSetting('global', global);
  if (mainWindow && !mainWindow.isDestroyed()) mainWindow.webContents.send('activity-trace-state', on);
  log.info(`[activity-trace] ${on ? 'enabled' : 'disabled'} from the UI → ${activityTrace.currentFile() || '(closed)'}`);
  return activityTraceState();
});

ipcMain.handle('list-activity-trace-files', () => listActivityTraceFiles());

ipcMain.handle('read-activity-trace-file', (_event, filePath) => {
  const resolved = resolveTraceFile(filePath);
  if (!resolved) return { ok: false, error: 'not an activity-trace file' };
  try {
    return { ok: true, ...activityTrace.readTraceTail(resolved, TRACE_READ_CAP) };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

ipcMain.handle('delete-activity-trace-file', (_event, filePath) => {
  const resolved = resolveTraceFile(filePath);
  if (!resolved) return { ok: false, error: 'not an activity-trace file' };
  if (resolved === activityTrace.currentFile()) return { ok: false, error: 'the trace is writing to this file — turn debug mode off first' };
  try {
    fs.unlinkSync(resolved);
    return { ok: true };
  } catch (err) {
    return { ok: false, error: err.message };
  }
});

// --- IPC: terminal-input (fire-and-forget) ---
ipcMain.on('terminal-input', (_event, sessionId, data) => {
  if (TRACE.on) {
    const chunk = typeof data === 'string' ? data : String(data ?? '');
    const at = controlOffset(chunk);
    trace('pty.input', sessionId, at === -1
      ? { len: chunk.length }
      : { at, cp: codePoints(chunk.slice(at), 10), len: chunk.length });
  }
  handleTerminalInput(activeSessions, sessionId, data, Date.now());
});

// --- IPC: terminal-resize (fire-and-forget) ---
ipcMain.on('terminal-resize', (_event, sessionId, cols, rows) => {
  const session = activeSessions.get(sessionId);
  if (session && !session.exited) {
    // For plain terminals, suppress buffering during resize to avoid
    // accumulating prompt redraws that pollute reattach replay
    if (session.isPlainTerminal) session._suppressBuffer = true;

    resizePty(session, cols, rows, sessionId);

    if (session.isPlainTerminal) {
      setTimeout(() => { session._suppressBuffer = false; }, 200);
    }

    // First resize: nudge to force TUI redraw on reattach (skip for plain terminals — causes duplicate prompts)
    if (session.firstResize && !session.isPlainTerminal) {
      session.firstResize = false;
      setTimeout(() => {
        if (!resizePty(session, cols + 1, rows, sessionId)) return;
        setTimeout(() => resizePty(session, cols, rows, sessionId), 50);
      }, 50);
    }
  }
});

// --- IPC: close-terminal ---
ipcMain.on('close-terminal', (_event, sessionId) => {
  const session = activeSessions.get(sessionId);
  if (session) {
    session.rendererAttached = false;
    if (session.exited) {
      activeSessions.delete(sessionId);
    }
  }
});

// Session transitions → session-transitions.js
const sessionTransitions = require('./session-transitions');
sessionTransitions.init({
  PROJECTS_DIR, activeSessions, getMainWindow: () => mainWindow, log, rekeyMcpServer,
  rekeyActivity: (fromId, toId) => activityReporter.rekey(fromId, toId),
});
const { detectSessionTransitions } = sessionTransitions;

// see .ai/contexts/cli-session-state.md
const cliSessionState = require('./cli-session-state');
cliSessionState.init({
  activeSessions,
  log,
  onIdle: (sessionId, session) => {
    sessionTransitions.detectSubagentTransitions(
      sessionId, session, path.join(PROJECTS_DIR, session.projectFolder)
    );
  },
});

// a session with a live PTY is owned by the OSC path — see .ai/contexts/session-state.md
function ptyPids() {
  const pids = [];
  for (const session of activeSessions.values()) {
    if (session && !session.exited && session.pty && Number.isInteger(session.pty.pid)) pids.push(session.pty.pid);
  }
  return pids;
}

function sessionHasPty(sessionId) {
  for (const [key, session] of activeSessions) {
    if (!session || session.exited) continue;
    if ((session.realSessionId || key) === sessionId) return true;
  }
  return false;
}
const localTranscriptTracker = createLocalTranscriptTracker({ hasPty: sessionHasPty });

// see .ai/contexts/cli-session-state.md ("Live elsewhere")
ipcMain.handle('session-live-elsewhere', (_event, sessionId) => cliSessionState.liveElsewhere(sessionId, sessionHasPty, ptyPids));
ipcMain.handle('sessions-live-elsewhere', (_event, sessionIds) => cliSessionState.liveElsewhereMany(sessionIds, sessionHasPty, ptyPids));

// --- fs.watch on projects directory ---
let projectsWatcher = null;

function startProjectsWatcher() {
  if (!fs.existsSync(PROJECTS_DIR)) return;

  // pendingChanges: folder → Set<relativePath> | true.
  //   Set<string>  — only the listed files changed (targeted refresh, fast path)
  //   true         — folder-level event or unknown scope, do a full walk
  // The watcher reports the specific filename, so for the common case of a
  // subagent appending JSONL we can stat one file instead of thousands.
  const pendingChanges = new Map();
  let debounceTimer = null;

  function flushChanges() {
    debounceTimer = null;
    // Drain pendingChanges into a local copy so events arriving during the
    // synchronous flush land in a fresh batch for the next tick.
    const work = new Map(pendingChanges);
    pendingChanges.clear();

    let changed = false;
    for (const [folder, scope] of work) {
      const folderPath = path.join(PROJECTS_DIR, folder);
      if (fs.existsSync(folderPath)) {
        detectSessionTransitions(folder);
        if (scope === true) {
          refreshFolder(folder);
        } else {
          refreshFolder(folder, { files: scope });
        }
      } else {
        deleteCachedFolder(folder);
      }
      changed = true;
    }

    if (changed) {
      notifyRendererProjectsChanged();
    }
  }

  function recordChange(folder, relPath) {
    const existing = pendingChanges.get(folder);
    if (existing === true) return;
    if (relPath === null) {
      pendingChanges.set(folder, true);
      return;
    }
    if (existing instanceof Set) {
      existing.add(relPath);
    } else {
      pendingChanges.set(folder, new Set([relPath]));
    }
  }

  try {
    projectsWatcher = fs.watch(PROJECTS_DIR, { recursive: true }, (_eventType, filename) => {
      if (!filename) return;

      // filename is relative, e.g. "folder-name/sessions-index.json" or "folder-name/abc.jsonl"
      const parts = filename.split(path.sep);
      const folder = parts[0];
      if (!folder || folder === '.git') return;

      const basename = parts[parts.length - 1];
      if (parts.length === 1) {
        // Top-level folder add/remove — must re-scan the whole folder
        recordChange(folder, null);
      } else if (basename.endsWith('.jsonl')) {
        // Specific .jsonl changed — targeted refresh on just this file
        const rel = parts.slice(1).join(path.sep);
        recordChange(folder, rel);
        // out-of-band signal for the local-transcript adapter — see .ai/contexts/session-state.md
        const activity = localTranscriptTracker.record(parts);
        if (activity && mainWindow && !mainWindow.isDestroyed()) {
          mainWindow.webContents.send('session-transcript-activity', activity);
        }
      } else {
        return;
      }

      if (debounceTimer) clearTimeout(debounceTimer);
      debounceTimer = setTimeout(flushChanges, 500);
    });

    projectsWatcher.on('error', (err) => {
      console.error('Projects watcher error:', err);
    });
  } catch (err) {
    console.error('Failed to start projects watcher:', err);
  }
}

// --- IPC: app version ---
ipcMain.handle('get-app-version', () => app.getVersion());

// --- IPC: auto-updater ---
ipcMain.handle('updater-check', () => {
  if (!autoUpdater) return { available: false, dev: true };
  return autoUpdater.checkForUpdates();
});
ipcMain.handle('updater-download', () => {
  if (!autoUpdater) return;
  return autoUpdater.downloadUpdate();
});
ipcMain.handle('updater-install', () => {
  activityFlushedForQuit = true; // see .ai/contexts/activitywatch.md ("Quitting")
  if (!autoUpdater) return;
  autoUpdater.quitAndInstall();
});

// --- App lifecycle ---
// Differentiate the dev build from the released binary in the OS task switcher,
// dock, and About menu by suffixing the app name. No-op in packaged builds.
if (!app.isPackaged) {
  app.setName('Switchboard (dev)');
}

// Prevent a second Electron instance from killing active PTY sessions.
// This happens when the user replaces the AppImage while Switchboard is running:
// the OS spawns the new binary, which would otherwise initialise a second process
// and leave the first one's node-pty sessions orphaned or killed.
// requestSingleInstanceLock ensures only one instance runs at a time. The second
// launch quits immediately; the first brings its window to the front.
const gotSingleInstanceLock = app.requestSingleInstanceLock();
if (!gotSingleInstanceLock) {
  app.quit();
} else {
  // Focus the existing window when a second launch is attempted.
  app.on('second-instance', () => {
    if (mainWindow) {
      if (mainWindow.isMinimized()) mainWindow.restore();
      mainWindow.focus();
    }
  });

  app.whenReady().then(() => {
    // Content Security Policy — restrict what the renderer can load or execute.
    // 'unsafe-inline' for style-src is required because the app sets .style.*
    // properties via JavaScript and style.css uses data: URIs in background-image.
    session.defaultSession.webRequest.onHeadersReceived((details, callback) => {
      callback({
        responseHeaders: {
          ...details.responseHeaders,
          'Content-Security-Policy': [
            "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; font-src 'self'",
          ],
        },
      });
    });

    buildMenu();
    createWindow();
    startProjectsWatcher();
    // No declared host => no timer and no ssh call. see .ai/contexts/session-cache.md ("Remote SSH hosts")
    remoteIndexer.start();
    syncRemoteWatchers();
    cliSessionState.ensureWatching();
    // Remove IDE lock files left behind by a crashed instance whose PID was
    // reused (the function only unlinks locks matching our own pid).
    cleanStaleLockFiles(log);
    scheduleIpc.ensureScheduleCreatorCommand();

    // Shared runCommand for cron scheduler and "run now" — takes argv, not a shell string
    const { spawn: cpSpawn } = require('child_process');
    function runScheduleCommand(claudeArgv, cwd, name, onDone) {
      const globalSettings = getSetting('global') || {};
      const profileId = globalSettings.shellProfile || SETTING_DEFAULTS.shellProfile;
      const profile = resolveShell(profileId);
      const shell = profile.path;
      // Re-serialise the safe argv into a shell string so the user's login shell
      // can initialise its profile (PATH, version managers, etc.) before running claude.
      let cmd = 'claude ' + quoteArgvForShell(shell, claudeArgv);
      const env = { ...cleanPtyEnv, FORCE_COLOR: '0' };

      // Scheduled runs honor the effective sandbox setting like interactive
      // sessions do — an unattended headless run is exactly where the
      // isolation matters most. Same global → project override chain as
      // get-effective-settings.
      const projectSettings = getSetting('project:' + cwd) || {};
      let sandbox = SETTING_DEFAULTS.sandbox;
      if (globalSettings.sandbox !== undefined) sandbox = globalSettings.sandbox;
      if (projectSettings.sandbox !== undefined) sandbox = projectSettings.sandbox;
      if (sandbox && process.platform !== 'linux') {
        // Fail closed, exactly like the interactive path: the whole point of
        // asking for a sandbox is not running unconfined. Silently downgrading
        // an unattended run to "no isolation" is the one outcome the user
        // cannot notice, so skip the run and surface the error instead.
        log.error(`[schedule] ${name}: skipped — sandbox is enabled but requires Linux (bubblewrap)`);
        if (onDone) onDone();
        return;
      }
      if (sandbox) {
        cmd = quoteArgvForShell(shell, ['bash', sandboxScriptPath()]) + ' ' + quoteArgvForShell(shell, claudeArgv);
        // A schedule's `cli: add-dirs:` paths surface in the argv as
        // --add-dir pairs — bind them like interactive sessions bind
        // Additional Directories.
        const addDirs = [];
        for (let i = 0; i < claudeArgv.length - 1; i++) {
          if (claudeArgv[i] === '--add-dir') addDirs.push(claudeArgv[i + 1]);
        }
        const bindEnv = sandboxBindEnv(addDirs);
        if (bindEnv) env.SWITCHBOARD_SANDBOX_BINDS = bindEnv;
      }
      const args = shellArgs(shell, cmd, profile.args || []);

      log.info(`[schedule] Running: ${shell} ${args.join(' ')}`);
      const child = cpSpawn(shell, args, {
        cwd,
        stdio: ['ignore', 'ignore', 'pipe'],
        env,
      });
      // see .ai/contexts/activitywatch.md ("Running")
      const activityId = `schedule:${name}:${Date.now()}`;
      activityReporter.sessionStarted({ sessionId: activityId, project: cwd, name: `Scheduled: ${name}` });

      let stderr = '';
      child.stderr.on('data', (data) => { stderr += data.toString(); });

      child.on('exit', (code) => {
        if (stderr.trim()) log.error(`[schedule] ${name} stderr:\n${stderr.trim()}`);
        log.info(`[schedule] ${name} finished (exit ${code})`);
        activityReporter.sessionEnded(activityId);
        if (onDone) onDone();
      });

      child.on('error', (err) => {
        log.error(`[schedule] ${name} error:`, err.message);
        activityReporter.sessionEnded(activityId);
        if (onDone) onDone();
      });
    }

    scheduleIpc.init(log, runScheduleCommand, isAllowedMemoryPath);
    startScheduler(log, runScheduleCommand);

    // File-trigger watcher — allows harness scripts to inject input into open
    // PTY sessions by dropping a JSON file in ~/.switchboard/triggers/.
    // I3: wrapped in try/catch so a boot failure here doesn't abort
    // app.whenReady (auto-updater, etc. would otherwise be silently lost).
    try {
      require('./trigger-watcher').start(createTriggerContext({ activeSessions, log }));
    } catch (err) {
      log.error('[trigger-watcher] Failed to start trigger watcher:', err.message);
    }

    // Full cache rebuild on every startup — prunes stale rows for deleted
    // transcripts (sub-agent/workflow runs cleaned up between sessions leave
    // ghost rows in session_cache that show in the sidebar but are
    // inaccessible on open). populateCacheViaWorker runs in a Worker thread
    // and is non-blocking; concurrent callers share the same in-flight
    // Promise so the FTS-recreated path below (if also triggered) is free.
    populateCacheViaWorker();

    // Re-index search if FTS table was recreated (e.g. tokenizer config change).
    // populateCacheViaWorker is already running above; the guard inside it
    // (populatePromise !== null) means this is a no-op on the same tick and
    // returns the shared Promise — no double scan.
    if (searchFtsRecreated) populateCacheViaWorker();

    // Check for updates after launch
    if (autoUpdater) {
      // Read the setting here rather than at the updater's construction: that
      // block runs before db.js is required, so getSetting isn't available yet.
      // Nothing checks for updates before this point, so overriding the flags
      // now is early enough.
      const autoUpdate = (getSetting('global') || {}).autoUpdate !== false;
      autoUpdater.autoDownload = autoUpdate;
      autoUpdater.autoInstallOnAppQuit = autoUpdate;
      if (!autoUpdate) {
        log.info('[updater] automatic updates disabled by setting — not checking');
      } else {
        setTimeout(() => autoUpdater.checkForUpdates().catch(e => log.error('[updater] check failed:', e?.message || String(e))), 5000);
        // Re-check every 4 hours for long-running sessions
        setInterval(() => autoUpdater.checkForUpdates().catch(e => log.error('[updater] check failed:', e?.message || String(e))), 4 * 60 * 60 * 1000);
      }
    }

    app.on('activate', () => {
      if (BrowserWindow.getAllWindows().length === 0) createWindow();
    });
  }); // end app.whenReady
} // end gotSingleInstanceLock else-branch

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit();
});

// see .ai/contexts/activitywatch.md ("Quitting")
app.on('before-quit', (event) => {
  if (!activityFlushedForQuit && activityReporter.hasPendingWork) {
    event.preventDefault();
    activityFlushedForQuit = true;
    const bound = new Promise((resolve) => setTimeout(resolve, 1500));
    Promise.race([activityReporter.flush().catch(() => {}), bound]).finally(() => app.quit());
    return;
  }
  activityReporter.stop();
  if (TRACE.on) trace('app.quit', null, {});
  activityTrace.close();

  // Shut down all MCP servers
  shutdownAllMcp();

  // Close filesystem watcher
  if (projectsWatcher) {
    projectsWatcher.close();
    projectsWatcher = null;
  }
  cliSessionState.stop();
  // Stops the timer and SIGKILLs any ssh/scp still in flight.
  remoteIndexer.dispose();
  remoteWatcher.stopAll();

  // Kill all PTY processes on quit
  for (const [id, session] of activeSessions) {
    if (!session.exited) killPty(session, id);
  }
});

// Close SQLite after all windows are closed to avoid "connection is not open" errors
app.on('will-quit', () => {
  // Terminate the search worker gracefully before closing the DB, so the
  // worker's read-only connection is released before the WAL checkpoint.
  // shutdown() suppresses the restart logic before calling terminate().
  searchClient.shutdown();
  closeDb();
});