relay-ide 0.1.0

package/dist/server/index.js

@@ -0,0 +1,1549 @@
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import readline from 'node:readline';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import express from 'express';
+import cookieParser from 'cookie-parser';
+import { loadConfig, saveConfig, DEFAULTS, readMeta, writeMeta, deleteMeta, ensureMetaDir, getConfigDir, resolveSessionSettings, } from './config.js';
+import * as auth from './auth.js';
+import * as sessions from './sessions.js';
+import { AGENT_CONTINUE_ARGS, AGENT_YOLO_ARGS, serializeAll, restoreFromDisk, activeTmuxSessionNames, populateMetaCache, } from './sessions.js';
+import { getTmuxPrefix } from './pty-handler.js';
+import { setupWebSocket } from './ws.js';
+import { WorktreeWatcher, BranchWatcher, RefWatcher, GitWatcher, parseAllWorktrees, } from './watcher.js';
+import { isInstalled as serviceIsInstalled } from './service.js';
+import { extensionForMime, setClipboardImage } from './clipboard.js';
+import { createGitRouter } from './git-routes.js';
+import { createGhRouter } from './gh-routes.js';
+import * as push from './push.js';
+import { initAnalytics, closeAnalytics, createAnalyticsRouter, createSessionAnalyticsRouter, flushEventBuffer, computeEngagementMetrics, upsertSessionRollup, getSessionRollup, startEventBatching, stopEventBatching, runRetentionCleanup, recoverOrphanedSessions, recordRateLimitSnapshot, } from './analytics.js';
+import { createWorkspaceRouter, clearPrCache, clearFilesListCache, } from './workspaces.js';
+import { createWorkspaceGroupsRouter } from './workspace-groups.js';
+import { createOrgDashboardRouter } from './org-dashboard.js';
+import { createIntegrationGitHubRouter } from './integration-github.js';
+import { createBranchLinkerRouter, invalidateBranchLinkerCache, } from './branch-linker.js';
+import { createHooksRouter } from './hooks.js';
+import { createTicketTransitionsRouter } from './ticket-transitions.js';
+import { createIntegrationJiraRouter } from './integration-jira.js';
+import { startPolling, stopPolling } from './review-poller.js';
+import { createGitHubAppRouter } from './github-app.js';
+import { createWebhookRouter } from './webhooks.js';
+import { createWebhookManagerRouter, reloadSmee, startSmartPolling, } from './webhook-manager.js';
+import { fetchPrsGraphQL } from './github-graphql.js';
+import { createTelemetryRouter, startTelemetry, stopTelemetry, getTelemetryForSession, getAccountTelemetry, } from './telemetry.js';
+import { BUILTIN_FRAMEWORKS } from './types.js';
+import { semverLessThan } from './utils.js';
+import { createBrowserContentRouter, generateScopedToken, cleanExpiredTokens, } from './browser-content.js';
+import { createLogger } from './logger.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const execFileAsync = promisify(execFile);
+const logger = createLogger('index');
+// When run via CLI bin, config lives in ~/.config/relay-ide/
+// When run directly (development), fall back to local config.json
+const CONFIG_PATH = process.env.RELAY_IDE_CONFIG ||
+    path.join(__dirname, '..', '..', 'config.json');
+const DEFAULT_GITHUB_CLIENT_ID = 'Ov23lilheF3LelYSo0bu';
+const VERSION_CACHE_TTL = 5 * 60 * 1000;
+const versionCache = new Map();
+function getCurrentVersion() {
+    const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return pkg.version;
+}
+async function getLatestVersion(channel = 'stable') {
+    const now = Date.now();
+    const cached = versionCache.get(channel);
+    if (cached && now - cached.fetchedAt < VERSION_CACHE_TTL) {
+        return cached.latest;
+    }
+    try {
+        const tag = channel === 'nightly' ? 'nightly' : 'latest';
+        const res = await fetch(`https://registry.npmjs.org/relay-ide/${tag}`);
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        if (!data.version)
+            return null;
+        versionCache.set(channel, { latest: data.version, fetchedAt: now });
+        return data.version;
+    }
+    catch (_) {
+        return null;
+    }
+}
+function execErrorMessage(err, fallback) {
+    const e = err;
+    return (e.stderr || e.message || fallback).trim();
+}
+function scanReposInRoot(rootDir) {
+    const repos = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(rootDir, { withFileTypes: true });
+    }
+    catch (_) {
+        return repos;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const fullPath = path.join(rootDir, entry.name);
+        const dotGit = path.join(fullPath, '.git');
+        try {
+            if (fs.statSync(dotGit).isDirectory()) {
+                repos.push({ name: entry.name, path: fullPath, root: rootDir });
+            }
+        }
+        catch (_) {
+            // .git doesn't exist — not a repo
+        }
+    }
+    return repos;
+}
+function scanAllRepos(rootDirs) {
+    const repos = [];
+    for (const rootDir of rootDirs) {
+        repos.push(...scanReposInRoot(rootDir));
+    }
+    return repos;
+}
+function parseTTL(ttl) {
+    if (typeof ttl !== 'string')
+        return 24 * 60 * 60 * 1000;
+    const match = ttl.match(/^(\d+)([smhd])$/);
+    if (!match)
+        return 24 * 60 * 60 * 1000;
+    const value = parseInt(match[1], 10);
+    switch (match[2]) {
+        case 's':
+            return value * 1000;
+        case 'm':
+            return value * 60 * 1000;
+        case 'h':
+            return value * 60 * 60 * 1000;
+        case 'd':
+            return value * 24 * 60 * 60 * 1000;
+        default:
+            return 24 * 60 * 60 * 1000;
+    }
+}
+function promptPin(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function main() {
+    // Ignore SIGPIPE: node-pty can propagate pipe breaks causing unexpected session exits
+    process.on('SIGPIPE', () => { });
+    // Ignore SIGHUP: keep server alive if controlling terminal disconnects
+    process.on('SIGHUP', () => { });
+    ensureMetaDir(CONFIG_PATH);
+    // Runtime config — always reads fresh from disk.
+    // Use this for ALL config access in route handlers, pollers, and event callbacks.
+    let lastGoodConfig = null;
+    function getConfig() {
+        try {
+            const fresh = loadConfig(CONFIG_PATH);
+            lastGoodConfig = fresh;
+            return structuredClone(fresh);
+        }
+        catch (err) {
+            logger.warn('[config] Failed to load config, using last good config:', err);
+            const fallback = lastGoodConfig ?? { ...DEFAULTS };
+            return structuredClone(fallback);
+        }
+    }
+    // Startup-only config — captured once at boot.
+    // Use ONLY for values wired into the listening socket or long-lived connections
+    // (port, host, webhookSecret, smeeUrl, githubToken, forceOutputParser).
+    let startupConfig;
+    try {
+        startupConfig = loadConfig(CONFIG_PATH);
+    }
+    catch (_) {
+        startupConfig = { ...DEFAULTS };
+        saveConfig(CONFIG_PATH, startupConfig);
+    }
+    // CLI flag overrides
+    if (process.env.RELAY_IDE_PORT)
+        startupConfig.port = parseInt(process.env.RELAY_IDE_PORT, 10);
+    if (process.env.RELAY_IDE_HOST)
+        startupConfig.host = process.env.RELAY_IDE_HOST;
+    push.ensureVapidKeys(startupConfig, CONFIG_PATH, saveConfig);
+    const configDir = getConfigDir(CONFIG_PATH);
+    fs.mkdirSync(path.join(configDir, 'telemetry'), { recursive: true });
+    try {
+        initAnalytics(configDir);
+    }
+    catch (err) {
+        logger.warn('Analytics disabled: failed to initialize:', err instanceof Error ? err.message : err);
+    }
+    if (startupConfig.pinHash && auth.isLegacyHash(startupConfig.pinHash)) {
+        logger.info('Migrating legacy PIN hash to scrypt. You will need to set a new PIN.');
+        delete startupConfig.pinHash;
+        saveConfig(CONFIG_PATH, startupConfig);
+    }
+    if (process.env.NO_PIN === '1') {
+        logger.info('PIN disabled (NO_PIN=1).');
+        startupConfig.pinHash = startupConfig.pinHash || 'disabled';
+    }
+    else if (!startupConfig.pinHash) {
+        if (process.stdin.isTTY) {
+            const pin = await promptPin('Set up a PIN for relay-ide:');
+            startupConfig.pinHash = await auth.hashPin(pin);
+            saveConfig(CONFIG_PATH, startupConfig);
+            logger.info('PIN set successfully.');
+        }
+        else {
+            logger.info(`No PIN configured. Open http://localhost:${startupConfig.port} to set one.`);
+        }
+    }
+    const authenticatedTokens = new Set();
+    // Build frontend if missing (e.g. fresh clone in development)
+    const frontendDir = path.join(__dirname, '..', 'frontend');
+    if (!fs.existsSync(path.join(frontendDir, 'index.html'))) {
+        const packageRoot = path.join(__dirname, '..', '..');
+        const viteConfig = path.join(packageRoot, 'frontend', 'vite.config.ts');
+        if (fs.existsSync(viteConfig)) {
+            logger.info('Frontend not built — building now...');
+            try {
+                await execFileAsync('npx', ['vite', 'build', '--config', 'frontend/vite.config.ts'], { cwd: packageRoot });
+                logger.info('Frontend build complete.');
+            }
+            catch (err) {
+                logger.error('Frontend build failed:', err instanceof Error ? err.message : err);
+            }
+        }
+        else {
+            logger.warn('Frontend assets missing and source not available — UI will not be served.');
+        }
+    }
+    const app = express();
+    // Mount webhooks BEFORE global express.json() — unconditionally.
+    // Secret is validated at request time (returns 401 if not configured).
+    let broadcastEventDelegate = null;
+    const webhookRouter = createWebhookRouter({
+        secret: () => loadConfig(CONFIG_PATH).github?.webhookSecret,
+        broadcastEvent: (type, data) => {
+            broadcastEventDelegate?.(type, data);
+        },
+    });
+    app.use('/webhooks', webhookRouter);
+    app.use(express.json({ limit: '15mb' }));
+    app.use(cookieParser());
+    app.use(express.static(frontendDir));
+    const requireAuth = (req, res, next) => {
+        const token = req.cookies && req.cookies.token;
+        if (!token || !authenticatedTokens.has(token)) {
+            res.status(401).json({ error: 'Unauthorized' });
+            return;
+        }
+        next();
+    };
+    const webhookManagerRouter = createWebhookManagerRouter({
+        configPath: CONFIG_PATH,
+        broadcastEvent: (type, data) => {
+            broadcastEventDelegate?.(type, data);
+        },
+        requireAuth,
+    });
+    app.use('/webhooks/manage', webhookManagerRouter);
+    function boolConfigEndpoints(name, defaultValue, onEnable) {
+        app.get(`/config/${name}`, requireAuth, (_req, res) => {
+            res.json({
+                [name]: getConfig()[name] ??
+                    defaultValue,
+            });
+        });
+        app.patch(`/config/${name}`, requireAuth, async (req, res) => {
+            const value = req.body[name];
+            if (typeof value !== 'boolean') {
+                res.status(400).json({ error: `${name} must be a boolean` });
+                return;
+            }
+            if (value && onEnable) {
+                try {
+                    await onEnable();
+                }
+                catch {
+                    res.status(400).json({ error: `Validation failed for ${name}` });
+                    return;
+                }
+            }
+            const c = getConfig();
+            c[name] = value;
+            saveConfig(CONFIG_PATH, c);
+            res.json({ [name]: value });
+        });
+    }
+    const watcher = new WorktreeWatcher();
+    watcher.rebuild(getConfig().repos || []);
+    const gitWatcher = new GitWatcher();
+    const server = http.createServer(app);
+    const { broadcastEvent, broadcastBranchChanged } = setupWebSocket(server, authenticatedTokens, watcher, CONFIG_PATH);
+    const browserScopedToken = generateScopedToken();
+    process.env['RELAY_IDE_BROWSER'] = '1';
+    process.env['RELAY_IDE_BROWSER_CMD'] = 'relay-ide browser';
+    process.env['RELAY_IDE_BROWSER_TOKEN'] = browserScopedToken;
+    if (!process.env['RELAY_IDE_PORT']) {
+        process.env['RELAY_IDE_PORT'] = String(startupConfig.port);
+    }
+    // Wire up the delegate used by the webhook router (mounted before broadcastEvent was available)
+    // Also clear the PR cache on real webhook events — these indicate actual PR state changes
+    broadcastEventDelegate = (type, data) => {
+        if (type === 'pr-updated')
+            clearPrCache();
+        broadcastEvent(type, data);
+    };
+    gitWatcher.on('files-changed', (data) => {
+        broadcastEvent('files-changed', {
+            workspacePath: data.workspacePath,
+            changedFiles: data.changedFiles,
+        });
+        clearFilesListCache(data.workspacePath);
+    });
+    // Watch .git/HEAD files for branch changes and update active sessions
+    const branchWatcher = new BranchWatcher((cwdPath, newBranch) => {
+        for (const session of sessions.list()) {
+            // Match by worktreePath or repoPath — session.cwd can drift to subdirectories
+            const groupPath = session.worktreePath ?? session.repoPath;
+            if (groupPath === cwdPath) {
+                const raw = sessions.get(session.id);
+                if (raw) {
+                    raw.branchName = newBranch;
+                    broadcastEvent('session-renamed', {
+                        sessionId: session.id,
+                        branchName: newBranch,
+                        displayName: raw.displayName,
+                    });
+                }
+            }
+        }
+        broadcastBranchChanged(cwdPath, newBranch);
+        // Rebuild ref watchers when branches change (new upstream to watch)
+        rebuildRefWatcher();
+    });
+    branchWatcher.rebuild(getConfig().repos || []);
+    watcher.on('worktrees-changed', () => {
+        branchWatcher.rebuild(getConfig().repos || []);
+    });
+    // Watch upstream tracking refs for push/fetch and broadcast ref-changed events
+    const refWatcher = new RefWatcher((cwdPath, branch) => {
+        broadcastEvent('ref-changed', { cwdPath, branch });
+        // Clear all PR cache — cwdPath may be a worktree path that doesn't match workspace cache keys
+        clearPrCache();
+    });
+    let refWatcherRebuildPending = false;
+    let refWatcherNeedsRebuild = false;
+    function rebuildRefWatcher() {
+        if (refWatcherRebuildPending) {
+            refWatcherNeedsRebuild = true;
+            return;
+        }
+        refWatcherRebuildPending = true;
+        refWatcherNeedsRebuild = false;
+        const entries = sessions
+            .list()
+            .filter((s) => s.branchName)
+            .map((s) => ({ cwdPath: s.cwd, branch: s.branchName }));
+        refWatcher.rebuild(entries).finally(() => {
+            refWatcherRebuildPending = false;
+            if (refWatcherNeedsRebuild)
+                rebuildRefWatcher();
+        });
+    }
+    rebuildRefWatcher();
+    sessions.onSessionCreate(() => rebuildRefWatcher());
+    sessions.onSessionEnd(() => rebuildRefWatcher());
+    // Configure session defaults for hooks injection (startup-only — changing these requires restart)
+    sessions.configure({
+        port: startupConfig.port,
+        forceOutputParser: startupConfig.forceOutputParser ?? false,
+        configDir,
+    });
+    // Mount hooks router BEFORE auth middleware — hook callbacks come from localhost Claude Code
+    const hooksRouter = createHooksRouter({
+        getSession: sessions.get,
+        broadcastEvent,
+        fireBackendStateIfChanged: sessions.fireBackendStateIfChanged,
+        notifySessionAttention: push.notifySessionAttention,
+        configPath: CONFIG_PATH,
+    });
+    app.use('/hooks', hooksRouter);
+    // Mount workspace router — rebuild watchers when workspaces are added or removed
+    const workspaceRouter = createWorkspaceRouter({
+        configPath: CONFIG_PATH,
+        onWorkspacesChanged: () => {
+            setImmediate(() => {
+                try {
+                    const repoPaths = getConfig().repos || [];
+                    watcher.rebuild(repoPaths);
+                    branchWatcher.rebuild(repoPaths);
+                }
+                catch (err) {
+                    logger.error('Failed to rebuild workspace watchers:', err);
+                }
+            });
+        },
+    });
+    app.use('/workspaces', requireAuth, workspaceRouter);
+    // Mount git (local/fast) and gh (network/slow) routers
+    app.use('/git', requireAuth, createGitRouter({
+        configPath: CONFIG_PATH,
+        getConfig,
+        getSessions: () => sessions.list().map((s) => ({
+            id: s.id,
+            worktreePath: s.worktreePath ?? s.repoPath,
+        })),
+    }));
+    app.use('/gh', requireAuth, createGhRouter());
+    // Mount workspace-groups CRUD router
+    app.use('/workspace-groups', createWorkspaceGroupsRouter(CONFIG_PATH, requireAuth, {
+        sessions,
+        gitWatcher,
+        configPath: CONFIG_PATH,
+    }));
+    // Mount GitHub integration router
+    const integrationGitHubRouter = createIntegrationGitHubRouter({
+        configPath: CONFIG_PATH,
+    });
+    app.use('/integration-github', requireAuth, integrationGitHubRouter);
+    // Mount Jira integration router
+    const integrationJiraRouter = createIntegrationJiraRouter({
+        configPath: CONFIG_PATH,
+    });
+    app.use('/integration-jira', requireAuth, integrationJiraRouter);
+    // Mount branch linker router
+    const branchLinkerRouter = createBranchLinkerRouter({
+        configPath: CONFIG_PATH,
+        getActiveBranchNames: () => {
+            const map = new Map();
+            for (const s of sessions.list()) {
+                if (!s.branchName)
+                    continue;
+                // Use repoPath so all sessions (main worktree and sub-worktrees) group correctly
+                const wsRoot = s.repoPath || s.cwd;
+                const existing = map.get(wsRoot);
+                if (existing) {
+                    existing.add(s.branchName);
+                }
+                else {
+                    map.set(wsRoot, new Set([s.branchName]));
+                }
+            }
+            return map;
+        },
+    });
+    app.use('/branch-linker', requireAuth, branchLinkerRouter);
+    // Mount ticket transitions router
+    const { router: ticketTransitionsRouter, transitionOnSessionCreate, checkPrTransitions, } = createTicketTransitionsRouter({ configPath: CONFIG_PATH });
+    app.use('/ticket-transitions', requireAuth, ticketTransitionsRouter);
+    // Mount GitHub device flow auth
+    // onConnected is called after token save; reload smee so it picks up any new config.
+    const githubAppRouter = createGitHubAppRouter({
+        configPath: CONFIG_PATH,
+        clientId: process.env.GITHUB_CLIENT_ID || DEFAULT_GITHUB_CLIENT_ID,
+        onConnected: () => {
+            reloadSmee(CONFIG_PATH, startupConfig.port);
+        },
+    });
+    app.use('/auth/github', requireAuth, githubAppRouter);
+    // Mount org dashboard router — use GraphQL when token available, fall back to gh CLI
+    const orgDashboardRouter = createOrgDashboardRouter({
+        configPath: CONFIG_PATH,
+        checkPrTransitions,
+        getBranchLinks: () => branchLinkerRouter.fetchLinks(),
+        fetchGraphQL: fetchPrsGraphQL,
+    });
+    app.use('/org-dashboard', requireAuth, orgDashboardRouter);
+    // Mount analytics router
+    app.use('/analytics', requireAuth, createAnalyticsRouter(configDir));
+    app.use('/api/analytics', requireAuth, createSessionAnalyticsRouter());
+    app.use('/telemetry', requireAuth, createTelemetryRouter());
+    // GET /api/frameworks — returns available agent frameworks with capabilities
+    app.get('/api/frameworks', requireAuth, (_req, res) => {
+        const frameworks = Object.values(BUILTIN_FRAMEWORKS).map((f) => ({
+            id: f.id,
+            displayName: f.displayName,
+            command: f.command,
+            capabilities: f.capabilities,
+            eventSource: f.eventSource,
+        }));
+        res.json({ frameworks });
+    });
+    // Restore sessions from a previous update restart
+    const restoredCount = await restoreFromDisk(configDir, getConfig().repos ?? [], getConfig().frameworks);
+    if (restoredCount > 0) {
+        logger.info(`Restored ${restoredCount} session(s) from previous update.`);
+        // Start git watching for restored sessions
+        for (const session of sessions.list()) {
+            gitWatcher.watch(session.cwd);
+        }
+    }
+    startTelemetry({
+        getActiveSessions: sessions.list,
+        broadcastEvent,
+        configDir,
+    });
+    startEventBatching();
+    // Run retention cleanup and orphan recovery at startup
+    try {
+        const recovered = recoverOrphanedSessions();
+        if (recovered > 0)
+            logger.info(`[analytics] Recovered ${recovered} orphaned session(s).`);
+        runRetentionCleanup();
+    }
+    catch (err) {
+        logger.warn('[analytics] Retention/recovery error:', err);
+    }
+    // Periodic rate limit snapshot recording (every 5 minutes)
+    let lastRateLimitSnapshot = 0;
+    const RATE_LIMIT_SNAPSHOT_INTERVAL = 5 * 60 * 1000;
+    setInterval(() => {
+        const now = Date.now();
+        if (now - lastRateLimitSnapshot < RATE_LIMIT_SNAPSHOT_INTERVAL)
+            return;
+        const account = getAccountTelemetry();
+        if (!account || account.fiveHourUsedPercent < 0)
+            return;
+        lastRateLimitSnapshot = now;
+        recordRateLimitSnapshot({
+            fiveHourPercent: account.fiveHourUsedPercent,
+            fiveHourResetsAt: account.fiveHourResetsAt,
+            sevenDayPercent: account.sevenDayUsedPercent,
+            sevenDayResetsAt: account.sevenDayResetsAt,
+            timestamp: new Date().toISOString(),
+        });
+    }, 60_000);
+    // Schedule daily retention cleanup
+    setInterval(() => {
+        try {
+            runRetentionCleanup();
+        }
+        catch {
+            /* non-fatal */
+        }
+    }, 24 * 60 * 60 * 1000);
+    // Populate session metadata cache in background (non-blocking)
+    populateMetaCache().catch(() => { });
+    // Build shared deps for review poller
+    function buildPollerDeps() {
+        return {
+            configPath: CONFIG_PATH,
+            getWorkspacePaths: () => getConfig().repos ?? [],
+            getRepoSettings: (wsPath) => getConfig().repoSettings?.[wsPath],
+            createSession: async (opts) => {
+                const resolved = resolveSessionSettings(getConfig(), opts.repoPath, {});
+                const repoName = opts.repoPath.split('/').filter(Boolean).pop() || 'session';
+                const displayName = sessions.nextAgentName();
+                sessions.create({
+                    type: 'agent',
+                    agent: resolved.agent,
+                    repoName,
+                    repoPath: opts.repoPath,
+                    worktreePath: opts.worktreePath,
+                    cwd: opts.worktreePath,
+                    branchName: opts.branchName,
+                    displayName,
+                    args: [
+                        ...resolved.claudeArgs,
+                        ...(resolved.yolo ? (AGENT_YOLO_ARGS[resolved.agent] ?? []) : []),
+                    ],
+                    configPath: CONFIG_PATH,
+                    useTmux: resolved.useTmux,
+                    yolo: resolved.yolo,
+                    claudeArgs: resolved.claudeArgs,
+                    ...(opts.initialPrompt != null && {
+                        initialPrompt: opts.initialPrompt,
+                    }),
+                });
+            },
+            broadcastEvent,
+        };
+    }
+    // Start review request poller if enabled
+    if (getConfig().automations?.autoCheckoutReviewRequests) {
+        startPolling(buildPollerDeps());
+    }
+    // Start smee-client via webhook-manager
+    reloadSmee(CONFIG_PATH, startupConfig.port);
+    // Start smart polling — broadcasts pr-updated/ci-updated only for repos without webhooks
+    startSmartPolling(CONFIG_PATH, broadcastEvent);
+    // Invalidate branch linker cache on session lifecycle changes
+    sessions.onSessionCreate(() => {
+        invalidateBranchLinkerCache();
+    });
+    sessions.onSessionEnd((sessionId) => {
+        invalidateBranchLinkerCache();
+        lastPushState.delete(sessionId);
+    });
+    sessions.onSessionEnd((sessionId) => {
+        // 1-second grace period for in-flight hooks before computing final metrics
+        setTimeout(() => {
+            // Capture final telemetry snapshot
+            const telemetry = getTelemetryForSession(sessionId);
+            if (telemetry) {
+                upsertSessionRollup({
+                    sessionId,
+                    ...(telemetry.model !== null ? { model: telemetry.model } : {}),
+                    totalInputTokens: telemetry.totalInputTokens,
+                    totalOutputTokens: telemetry.totalOutputTokens,
+                    totalCacheRead: telemetry.totalCacheRead,
+                    totalCacheWrite: telemetry.totalCacheWrite,
+                });
+            }
+            flushEventBuffer(sessionId);
+            const metrics = computeEngagementMetrics(sessionId);
+            const endedAt = new Date().toISOString();
+            const existingRollup = getSessionRollup(sessionId);
+            const durationSeconds = existingRollup?.startedAt
+                ? Math.round((new Date(endedAt).getTime() -
+                    new Date(existingRollup.startedAt).getTime()) /
+                    1000)
+                : undefined;
+            upsertSessionRollup({
+                sessionId,
+                endedAt,
+                ...(durationSeconds !== undefined ? { durationSeconds } : {}),
+                ...(metrics
+                    ? {
+                        ...(metrics.humanResponseLatencyAvgMs !== null
+                            ? {
+                                humanResponseLatencyAvgMs: metrics.humanResponseLatencyAvgMs,
+                            }
+                            : {}),
+                        ...(metrics.humanResponseLatencyP50Ms !== null
+                            ? {
+                                humanResponseLatencyP50Ms: metrics.humanResponseLatencyP50Ms,
+                            }
+                            : {}),
+                        ...(metrics.humanResponseLatencyP95Ms !== null
+                            ? {
+                                humanResponseLatencyP95Ms: metrics.humanResponseLatencyP95Ms,
+                            }
+                            : {}),
+                        ...(metrics.agentIdlePercent !== null
+                            ? { agentIdlePercent: metrics.agentIdlePercent }
+                            : {}),
+                        rateLimitEncounters: metrics.rateLimitEncounters,
+                        toolUseCounts: metrics.toolUseCounts,
+                    }
+                    : {}),
+            });
+        }, 1000);
+    });
+    // Push notifications on meaningful state transitions (skip when hooks already sent attention notification)
+    const lastPushState = new Map();
+    sessions.onBackendStateChange((sessionId, state) => {
+        const prevState = lastPushState.get(sessionId);
+        lastPushState.set(sessionId, state);
+        // Only notify on meaningful transitions: running → idle or running → permission
+        if (prevState === 'running' &&
+            (state === 'idle' || state === 'permission')) {
+            const session = sessions.get(sessionId);
+            if (session && session.type !== 'terminal') {
+                // Dedup: if hooks fired an attention notification within last 10s, skip
+                if (session.hooksActive &&
+                    session.lastAttentionNotifiedAt &&
+                    Date.now() - session.lastAttentionNotifiedAt < 10000) {
+                    return;
+                }
+                push.notifySessionAttention(sessionId, session);
+            }
+        }
+    });
+    // GET /auth/status — no auth required, tells frontend if PIN is configured
+    app.get('/auth/status', (_req, res) => {
+        const config = getConfig();
+        res.json({ hasPIN: !!config.pinHash });
+    });
+    // POST /auth/setup — set initial PIN (only works when no PIN is configured)
+    app.post('/auth/setup', async (req, res) => {
+        try {
+            const ip = (req.ip || req.connection.remoteAddress);
+            if (auth.isRateLimited(ip)) {
+                res.status(429).json({ error: 'Too many attempts. Try again later.' });
+                return;
+            }
+            const { pin, confirm } = req.body;
+            if (!pin || !confirm) {
+                res.status(400).json({ error: 'PIN and confirmation required' });
+                return;
+            }
+            if (pin !== confirm) {
+                auth.recordFailedAttempt(ip);
+                res.status(400).json({ error: 'PINs do not match' });
+                return;
+            }
+            if (pin.length < 4) {
+                res.status(400).json({ error: 'PIN must be at least 4 characters' });
+                return;
+            }
+            // Single read — check + write atomically to avoid TOCTOU race
+            const freshConfig = loadConfig(CONFIG_PATH);
+            if (freshConfig.pinHash) {
+                res
+                    .status(403)
+                    .json({ error: 'PIN is already configured. Use CLI to reset.' });
+                return;
+            }
+            freshConfig.pinHash = await auth.hashPin(pin);
+            saveConfig(CONFIG_PATH, freshConfig);
+            // Auto-login: generate token and set cookie
+            auth.clearRateLimit(ip);
+            const token = auth.generateCookieToken();
+            authenticatedTokens.add(token);
+            const ttlMs = parseTTL(freshConfig.cookieTTL);
+            setTimeout(() => authenticatedTokens.delete(token), ttlMs);
+            res.cookie('token', token, {
+                httpOnly: true,
+                sameSite: 'strict',
+                maxAge: ttlMs,
+            });
+            res.json({ ok: true });
+        }
+        catch (err) {
+            logger.error('[auth] Unhandled error in POST /auth/setup:', err);
+            res.status(500).json({ error: 'Failed to set PIN' });
+        }
+    });
+    // POST /auth
+    app.post('/auth', async (req, res) => {
+        try {
+            const ip = (req.ip || req.connection.remoteAddress);
+            if (auth.isRateLimited(ip)) {
+                res.status(429).json({ error: 'Too many attempts. Try again later.' });
+                return;
+            }
+            const { pin } = req.body;
+            if (!pin) {
+                res.status(400).json({ error: 'PIN required' });
+                return;
+            }
+            const authConfig = getConfig();
+            if (!authConfig.pinHash) {
+                res.status(412).json({ error: 'No PIN configured', needsSetup: true });
+                return;
+            }
+            const valid = process.env.NO_PIN === '1' ||
+                (await auth.verifyPin(pin, authConfig.pinHash));
+            if (!valid) {
+                auth.recordFailedAttempt(ip);
+                res.status(401).json({ error: 'Invalid PIN' });
+                return;
+            }
+            auth.clearRateLimit(ip);
+            const token = auth.generateCookieToken();
+            authenticatedTokens.add(token);
+            const ttlMs = parseTTL(authConfig.cookieTTL);
+            setTimeout(() => authenticatedTokens.delete(token), ttlMs);
+            res.cookie('token', token, {
+                httpOnly: true,
+                sameSite: 'strict',
+                maxAge: ttlMs,
+            });
+            res.json({ ok: true });
+        }
+        catch (err) {
+            logger.error('[auth] Unhandled error in POST /auth:', err);
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // GET /sessions — enrich with live branch from git (rate-limited to avoid spawning git on every poll)
+    const branchRefreshCache = new Map(); // sessionId -> last refresh timestamp
+    const BRANCH_REFRESH_INTERVAL_MS = 10_000;
+    app.get('/sessions', requireAuth, async (_req, res) => {
+        const allSessions = sessions.list();
+        const now = Date.now();
+        // Prune cache entries for sessions that no longer exist
+        const activeIds = new Set(allSessions.map((s) => s.id));
+        for (const sessionId of branchRefreshCache.keys()) {
+            if (!activeIds.has(sessionId))
+                branchRefreshCache.delete(sessionId);
+        }
+        await Promise.all(allSessions.map(async (s) => {
+            if (s.type !== 'agent')
+                return;
+            if (!s.cwd)
+                return;
+            const lastRefresh = branchRefreshCache.get(s.id) ?? 0;
+            if (now - lastRefresh < BRANCH_REFRESH_INTERVAL_MS)
+                return;
+            const cwd = s.cwd;
+            branchRefreshCache.set(s.id, now);
+            try {
+                const { stdout } = await execFileAsync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd });
+                const liveBranch = stdout.trim();
+                if (liveBranch && liveBranch !== s.branchName) {
+                    s.branchName = liveBranch;
+                    const raw = sessions.get(s.id);
+                    if (raw)
+                        raw.branchName = liveBranch;
+                }
+            }
+            catch {
+                /* non-fatal */
+            }
+        }));
+        res.json(allSessions);
+    });
+    // GET /repos — scan root dirs for repos
+    app.get('/repos', requireAuth, async (_req, res) => {
+        const freshConfig = getConfig();
+        const repos = scanAllRepos(freshConfig.rootDirs || []);
+        // Also include legacy manually-added repos
+        if (freshConfig.repos) {
+            for (const repo of freshConfig.repos) {
+                if (!repos.some((r) => r.path === repo.path)) {
+                    repos.push(repo);
+                }
+            }
+        }
+        // Enrich with current branch (best-effort, parallel)
+        const enriched = await Promise.all(repos.map(async (repo) => {
+            try {
+                const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: repo.path });
+                return { ...repo, defaultBranch: stdout.trim() };
+            }
+            catch {
+                return { ...repo, defaultBranch: null };
+            }
+        }));
+        res.json(enriched);
+    });
+    // GET /worktrees/status — pre-cleanup checks for a worktree
+    app.get('/worktrees/status', requireAuth, async (req, res) => {
+        const worktreePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        if (!worktreePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const resolved = path.resolve(worktreePath);
+        // Validate the path is a recognized git worktree via git worktree list (trust boundary first)
+        const allRoots = getConfig().rootDirs || [];
+        const allRepos = [...(getConfig().repos ?? [])];
+        for (const rootDir of allRoots) {
+            try {
+                for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+                    if (!entry.isDirectory() || entry.name.startsWith('.'))
+                        continue;
+                    const fullPath = path.join(rootDir, entry.name);
+                    if (fs.existsSync(path.join(fullPath, '.git')))
+                        allRepos.push(fullPath);
+                }
+            }
+            catch {
+                /* skip unreadable rootDirs */
+            }
+        }
+        let isKnownWorktree = false;
+        for (const repoPath of [...new Set(allRepos)]) {
+            try {
+                const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], { cwd: repoPath, timeout: 5000 });
+                const allWt = parseAllWorktrees(stdout, repoPath);
+                if (allWt.some((wt) => wt.path === resolved && !wt.isMain)) {
+                    isKnownWorktree = true;
+                    break;
+                }
+            }
+            catch {
+                /* skip repos where git fails */
+            }
+        }
+        if (!isKnownWorktree) {
+            res.status(400).json({ error: 'Path is not a recognized git worktree' });
+            return;
+        }
+        if (!fs.existsSync(resolved)) {
+            res.status(404).json({ error: 'Worktree not found' });
+            return;
+        }
+        // Check for active sessions in this worktree
+        const allSessions = sessions.list();
+        const activeSessions = allSessions
+            .filter((s) => s.worktreePath === resolved || s.cwd === resolved)
+            .map((s) => s.id);
+        // Check for uncommitted changes — default to true (safe: assume changes exist if check fails)
+        let hasUncommittedChanges = true;
+        try {
+            const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
+                cwd: resolved,
+                timeout: 5000,
+            });
+            hasUncommittedChanges = stdout.trim().length > 0;
+        }
+        catch (err) {
+            logger.warn('[worktrees/status] git status failed for', resolved, err instanceof Error ? err.message : err);
+        }
+        res.json({ activeSessions, hasUncommittedChanges });
+    });
+    // GET /config/defaultAgent — get default coding agent
+    app.get('/config/defaultAgent', requireAuth, (_req, res) => {
+        res.json({ defaultAgent: getConfig().defaultAgent || 'claude' });
+    });
+    // PATCH /config/defaultAgent — set default coding agent
+    app.patch('/config/defaultAgent', requireAuth, (req, res) => {
+        const { defaultAgent } = req.body;
+        if (!defaultAgent ||
+            (defaultAgent !== 'claude' && defaultAgent !== 'codex')) {
+            res
+                .status(400)
+                .json({ error: 'defaultAgent must be "claude" or "codex"' });
+            return;
+        }
+        const c = getConfig();
+        c.defaultAgent = defaultAgent;
+        saveConfig(CONFIG_PATH, c);
+        res.json({ defaultAgent: c.defaultAgent });
+    });
+    boolConfigEndpoints('defaultContinue', true);
+    boolConfigEndpoints('defaultYolo', false);
+    boolConfigEndpoints('launchInTmux', false, async () => {
+        await execFileAsync('tmux', ['-V']);
+    });
+    boolConfigEndpoints('defaultNotifications', true);
+    boolConfigEndpoints('autoProvision', false);
+    // GET /config/automations — get automation settings
+    app.get('/config/automations', requireAuth, (_req, res) => {
+        res.json(getConfig().automations ?? {});
+    });
+    // PATCH /config/automations — update automation settings and start/stop poller
+    app.patch('/config/automations', requireAuth, (req, res) => {
+        const body = req.body;
+        const c = getConfig();
+        const prev = c.automations ?? {};
+        const next = { ...prev };
+        if (typeof body.autoCheckoutReviewRequests === 'boolean') {
+            next.autoCheckoutReviewRequests = body.autoCheckoutReviewRequests;
+        }
+        if (typeof body.autoReviewOnCheckout === 'boolean') {
+            next.autoReviewOnCheckout = body.autoReviewOnCheckout;
+        }
+        if (typeof body.pollIntervalMs === 'number' &&
+            body.pollIntervalMs >= 60000) {
+            next.pollIntervalMs = body.pollIntervalMs;
+        }
+        // Enforce: auto-review requires auto-checkout
+        if (!next.autoCheckoutReviewRequests) {
+            next.autoReviewOnCheckout = false;
+        }
+        c.automations = next;
+        try {
+            saveConfig(CONFIG_PATH, c);
+        }
+        catch (err) {
+            logger.error('[config] Failed to save automation settings:', err);
+            res.status(500).json({ error: 'Failed to save settings' });
+            return;
+        }
+        // Start or stop poller based on new setting
+        void stopPolling().then(() => {
+            if (next.autoCheckoutReviewRequests) {
+                startPolling(buildPollerDeps());
+            }
+        });
+        res.json(next);
+    });
+    // GET /config/workspace-groups — return workspace group configuration
+    app.get('/config/workspace-groups', requireAuth, (_req, res) => {
+        res.json({ groups: getConfig().workspaceGroups ?? {} });
+    });
+    // GET /presets — return all filter presets (built-in merged with user presets)
+    app.get('/presets', requireAuth, (_req, res) => {
+        res.json(getConfig().filterPresets ?? []);
+    });
+    // POST /presets — add a new user filter preset
+    app.post('/presets', requireAuth, (req, res) => {
+        const { name, filters, sort } = req.body;
+        if (!name || typeof name !== 'string' || !name.trim()) {
+            res.status(400).json({ error: 'name is required' });
+            return;
+        }
+        if (sort && typeof sort === 'object') {
+            const dir = sort.direction;
+            if (dir !== 'asc' && dir !== 'desc') {
+                res
+                    .status(400)
+                    .json({ error: 'sort.direction must be "asc" or "desc"' });
+                return;
+            }
+            const col = sort.column;
+            if (!col || typeof col !== 'string' || !col.trim()) {
+                res
+                    .status(400)
+                    .json({ error: 'sort.column must be a non-empty string' });
+                return;
+            }
+        }
+        const trimmedName = name.trim();
+        const c = getConfig();
+        const existingPresets = c.filterPresets ?? [];
+        const duplicate = existingPresets.some((p) => p.name.toLowerCase() === trimmedName.toLowerCase());
+        if (duplicate) {
+            res
+                .status(409)
+                .json({ error: `A preset named "${trimmedName}" already exists` });
+            return;
+        }
+        const preset = {
+            name: trimmedName,
+            filters: filters ?? {},
+            sort: sort ?? {
+                column: 'role',
+                direction: 'asc',
+            },
+        };
+        if (!c.filterPresets)
+            c.filterPresets = [];
+        c.filterPresets.push(preset);
+        saveConfig(CONFIG_PATH, c);
+        res.json(preset);
+    });
+    // DELETE /presets/:name — remove a user preset (built-in presets cannot be deleted)
+    app.delete('/presets/:name', requireAuth, (req, res) => {
+        const name = decodeURIComponent(req.params['name'] ?? '');
+        const c = getConfig();
+        const presets = c.filterPresets ?? [];
+        const target = presets.find((p) => p.name === name);
+        if (!target) {
+            res.status(404).json({ error: 'Preset not found' });
+            return;
+        }
+        if (target.builtIn) {
+            res.status(400).json({ error: 'Cannot delete a built-in preset' });
+            return;
+        }
+        c.filterPresets = presets.filter((p) => p.name !== name);
+        saveConfig(CONFIG_PATH, c);
+        res.json({ ok: true });
+    });
+    // GET /push/vapid-key
+    app.get('/push/vapid-key', requireAuth, (_req, res) => {
+        const key = push.getVapidPublicKey();
+        if (!key) {
+            res.status(501).json({ error: 'Push not available' });
+            return;
+        }
+        res.json({ vapidPublicKey: key });
+    });
+    // POST /push/subscribe
+    app.post('/push/subscribe', requireAuth, (req, res) => {
+        const { subscription, sessionIds } = req.body;
+        if (!subscription?.endpoint) {
+            res.status(400).json({ error: 'subscription required' });
+            return;
+        }
+        push.subscribe(subscription, sessionIds || []);
+        res.json({ ok: true });
+    });
+    // POST /push/unsubscribe
+    app.post('/push/unsubscribe', requireAuth, (req, res) => {
+        const { endpoint } = req.body;
+        if (!endpoint) {
+            res.status(400).json({ error: 'endpoint required' });
+            return;
+        }
+        push.unsubscribe(endpoint);
+        res.json({ ok: true });
+    });
+    // DELETE /worktrees — remove a worktree, prune, and delete its branch
+    app.delete('/worktrees', requireAuth, async (req, res) => {
+        const { worktreePath, repoPath, force } = req.body;
+        if (!worktreePath || !repoPath) {
+            res.status(400).json({ error: 'worktreePath and repoPath are required' });
+            return;
+        }
+        // Validate the path is a real git worktree (not the main worktree)
+        try {
+            const { stdout: wtListOut } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], { cwd: repoPath });
+            const allWorktrees = parseAllWorktrees(wtListOut, repoPath);
+            const isKnownWorktree = allWorktrees.some((wt) => wt.path === path.resolve(worktreePath) && !wt.isMain);
+            if (!isKnownWorktree) {
+                // Check if the path simply doesn't exist anymore (already cleaned up)
+                if (!fs.existsSync(worktreePath)) {
+                    res.status(404).json({
+                        error: 'Worktree not found — may have been already cleaned up',
+                    });
+                    return;
+                }
+                res
+                    .status(400)
+                    .json({ error: 'Path is not a recognized git worktree' });
+                return;
+            }
+        }
+        catch (err) {
+            logger.warn('[worktrees/delete] git worktree list failed for', repoPath, err instanceof Error ? err.message : err);
+            // Allow force-delete when git is broken (user explicitly wants cleanup)
+            if (!force) {
+                res.status(500).json({
+                    error: 'Cannot verify worktree — git worktree list failed. Use force: true to delete anyway.',
+                });
+                return;
+            }
+        }
+        // Check for active sessions in this worktree
+        const allSessions = sessions.list();
+        const resolvedPath = path.resolve(worktreePath);
+        const worktreeSessions = allSessions.filter((s) => s.worktreePath === resolvedPath || s.cwd === resolvedPath);
+        if (worktreeSessions.length > 0 && !force) {
+            // Non-force delete with active sessions: reject to prevent killing PTYs unexpectedly
+            res.status(409).json({
+                error: 'active_sessions',
+                sessionIds: worktreeSessions.map((s) => s.id),
+            });
+            return;
+        }
+        // Force: kill active sessions in this worktree first
+        if (force) {
+            for (const s of worktreeSessions) {
+                try {
+                    sessions.kill(s.id);
+                }
+                catch (err) {
+                    logger.warn(`[worktrees] failed to kill session ${s.id}:`, err instanceof Error ? err.message : err);
+                }
+            }
+        }
+        // Derive branch name from metadata or worktree directory name
+        const meta = readMeta(CONFIG_PATH, worktreePath);
+        const branchName = (meta && meta.branchName) || worktreePath.split('/').pop() || '';
+        try {
+            // Use --force when the user has confirmed via the cascade dialog
+            const removeArgs = force
+                ? ['worktree', 'remove', '--force', worktreePath]
+                : ['worktree', 'remove', worktreePath];
+            await execFileAsync('git', removeArgs, { cwd: repoPath });
+        }
+        catch (err) {
+            // If git worktree remove fails, the directory may be an orphaned worktree
+            // that git no longer tracks. Try to remove the directory directly.
+            if (fs.existsSync(worktreePath)) {
+                try {
+                    fs.rmSync(worktreePath, { recursive: true });
+                }
+                catch (rmErr) {
+                    res.status(500).json({
+                        error: execErrorMessage(rmErr, 'Failed to remove worktree directory'),
+                    });
+                    return;
+                }
+            }
+            // If directory doesn't exist, the worktree is already gone — continue to cleanup
+        }
+        try {
+            // Prune stale worktree refs
+            await execFileAsync('git', ['worktree', 'prune'], { cwd: repoPath });
+        }
+        catch (_) {
+            // Non-fatal: prune failure doesn't block success
+        }
+        if (branchName) {
+            try {
+                // Delete the branch
+                await execFileAsync('git', ['branch', '-D', branchName], {
+                    cwd: repoPath,
+                });
+            }
+            catch (_) {
+                // Non-fatal: branch may not exist or may be checked out elsewhere
+            }
+        }
+        // Clean up metadata file
+        deleteMeta(CONFIG_PATH, worktreePath);
+        // Broadcast worktrees-changed so all clients refresh
+        broadcastEvent('worktrees-changed');
+        res.json({ ok: true });
+    });
+    // POST /sessions — unified endpoint for agent and terminal sessions
+    app.post('/sessions', requireAuth, async (req, res) => {
+        const { repoPath, worktreePath, type = 'agent', agent, yolo, useTmux, claudeArgs, cols, rows, branchName: requestBranchName, needsBranchRename, branchRenamePrompt, initialPrompt, continue: explicitContinue, continuePolicy: explicitContinuePolicy, ticketContext, } = req.body;
+        if (!repoPath) {
+            res.status(400).json({ error: 'repoPath is required' });
+            return;
+        }
+        // Read config once for the lifetime of this request
+        const freshConfig = getConfig();
+        // Validate repoPath is a configured workspace
+        const configuredWorkspaces = freshConfig.repos ?? [];
+        if (!configuredWorkspaces.includes(repoPath)) {
+            res.status(400).json({ error: 'repoPath is not a configured workspace' });
+            return;
+        }
+        const cwd = worktreePath ?? repoPath;
+        // Validate cwd directory exists
+        if (!fs.existsSync(cwd)) {
+            res.status(400).json({ error: `Directory does not exist: ${cwd}` });
+            return;
+        }
+        const safeCols = typeof cols === 'number' &&
+            Number.isFinite(cols) &&
+            cols >= 1 &&
+            cols <= 500
+            ? Math.round(cols)
+            : undefined;
+        const safeRows = typeof rows === 'number' &&
+            Number.isFinite(rows) &&
+            rows >= 1 &&
+            rows <= 200
+            ? Math.round(rows)
+            : undefined;
+        const name = repoPath.split('/').filter(Boolean).pop() || 'session';
+        if (type === 'terminal') {
+            // Terminal session — bare shell
+            const shell = process.env.SHELL || '/bin/sh';
+            const displayName = sessions.nextTerminalName();
+            const session = sessions.create({
+                type: 'terminal',
+                agent: 'claude',
+                repoName: name,
+                repoPath,
+                worktreePath: worktreePath ?? null,
+                cwd,
+                displayName,
+                branchName: '',
+                command: shell,
+                args: [],
+                ...(safeCols != null && { cols: safeCols }),
+                ...(safeRows != null && { rows: safeRows }),
+            });
+            gitWatcher.watch(session.cwd);
+            res.status(201).json(session);
+            return;
+        }
+        // Agent session
+        // Map legacy boolean continue → continuePolicy for backward compat
+        const policyOverride = explicitContinuePolicy ??
+            (explicitContinue !== undefined
+                ? explicitContinue
+                    ? 'always'
+                    : 'never'
+                : undefined);
+        // For new worktrees, always use 'never' regardless of config
+        const effectivePolicy = needsBranchRename
+            ? 'never'
+            : policyOverride;
+        const resolved = resolveSessionSettings(freshConfig, repoPath, {
+            agent,
+            yolo,
+            useTmux,
+            claudeArgs,
+            continuePolicy: effectivePolicy,
+        });
+        const resolvedAgent = resolved.agent;
+        const baseArgs = [
+            ...resolved.claudeArgs,
+            ...(resolved.yolo ? (AGENT_YOLO_ARGS[resolvedAgent] ?? []) : []),
+        ];
+        // Determine --continue from policy (no .claude directory heuristic)
+        const useContinue = resolved.continuePolicy === 'always';
+        const args = useContinue
+            ? [...(AGENT_CONTINUE_ARGS[resolvedAgent] ?? []), ...baseArgs]
+            : [...baseArgs];
+        // Ticket context validation and initial prompt
+        let computedInitialPrompt = initialPrompt;
+        if (ticketContext) {
+            if (typeof ticketContext.ticketId !== 'string' ||
+                typeof ticketContext.title !== 'string' ||
+                typeof ticketContext.url !== 'string') {
+                res.status(400).json({
+                    error: 'ticketContext requires string ticketId, title, and url',
+                });
+                return;
+            }
+            if (ticketContext.source !== 'github' &&
+                ticketContext.source !== 'jira') {
+                res
+                    .status(400)
+                    .json({ error: "ticketContext.source must be 'github' or 'jira'" });
+                return;
+            }
+            if (!configuredWorkspaces.includes(ticketContext.repoPath)) {
+                res.status(400).json({
+                    error: 'ticketContext.repoPath is not a configured workspace',
+                });
+                return;
+            }
+            if (ticketContext.source === 'github' &&
+                !/^GH-\d+$/.test(ticketContext.ticketId)) {
+                res.status(400).json({
+                    error: 'ticketContext.ticketId for github must match GH-<number>',
+                });
+                return;
+            }
+            if (ticketContext.source === 'jira' &&
+                !/^[A-Z][A-Z0-9]*-\d+$/.test(ticketContext.ticketId)) {
+                res.status(400).json({
+                    error: 'ticketContext.ticketId must match <PROJECT>-<number>',
+                });
+                return;
+            }
+            const settings = freshConfig.repoSettings?.[ticketContext.repoPath];
+            const template = settings?.promptStartWork ??
+                'You are working on ticket {ticketId}: {title}\n\nTicket URL: {ticketUrl}\n\nPlease start by understanding the issue and proposing an approach.';
+            computedInitialPrompt = template
+                .replace(/\{ticketId\}/g, ticketContext.ticketId)
+                .replace(/\{title\}/g, ticketContext.title)
+                .replace(/\{ticketUrl\}/g, ticketContext.url)
+                .replace(/\{description\}/g, ticketContext.description ?? '');
+        }
+        const displayName = sessions.nextAgentName();
+        // Compute tmux-specific display name from repo + branch for identifiable tmux ls output
+        // UI displayName stays as "Agent N" — tmux name and UI name are independent
+        // generateTmuxSessionName handles all sanitization and truncation
+        const tmuxDisplayName = requestBranchName
+            ? `${name}-${requestBranchName}`
+            : name;
+        const session = sessions.create({
+            type: 'agent',
+            agent: resolvedAgent,
+            repoName: name,
+            repoPath,
+            worktreePath: worktreePath ?? null,
+            cwd,
+            branchName: requestBranchName || '', // caller may provide; branch watcher enriches later
+            displayName,
+            tmuxDisplayName,
+            args,
+            configPath: CONFIG_PATH,
+            useTmux: resolved.useTmux,
+            yolo: resolved.yolo,
+            claudeArgs: resolved.claudeArgs,
+            continuePolicy: resolved.continuePolicy,
+            ...(safeCols != null && { cols: safeCols }),
+            ...(safeRows != null && { rows: safeRows }),
+            needsBranchRename: needsBranchRename ?? false,
+            branchRenamePrompt: branchRenamePrompt ?? '',
+            ...(computedInitialPrompt != null && {
+                initialPrompt: computedInitialPrompt,
+            }),
+        });
+        // Write worktree metadata if in a worktree
+        if (worktreePath) {
+            writeMeta(CONFIG_PATH, {
+                worktreePath: cwd,
+                displayName,
+                lastActivity: new Date().toISOString(),
+                branchName: requestBranchName || '',
+            });
+        }
+        gitWatcher.watch(session.cwd);
+        if (ticketContext) {
+            transitionOnSessionCreate(ticketContext).catch((err) => {
+                logger.error('[index] transition on session create failed:', err);
+            });
+        }
+        res.status(201).json(session);
+    });
+    // DELETE /sessions/:id
+    app.delete('/sessions/:id', requireAuth, (req, res) => {
+        const id = req.params['id'];
+        try {
+            const sessionToDelete = sessions.get(id);
+            sessions.kill(id);
+            push.removeSession(id);
+            if (sessionToDelete)
+                gitWatcher.unwatch(sessionToDelete.cwd);
+            res.json({ ok: true });
+        }
+        catch (_) {
+            res.status(404).json({ error: 'Session not found' });
+        }
+    });
+    // PATCH /sessions/:id — update displayName and persist to metadata
+    app.patch('/sessions/:id', requireAuth, (req, res) => {
+        const { displayName } = req.body;
+        if (!displayName) {
+            res.status(400).json({ error: 'displayName is required' });
+            return;
+        }
+        try {
+            const id = req.params['id'];
+            const updated = sessions.updateDisplayName(id, displayName);
+            const session = sessions.get(id);
+            if (session) {
+                writeMeta(CONFIG_PATH, {
+                    worktreePath: session.cwd,
+                    displayName,
+                    lastActivity: session.lastActivity,
+                });
+            }
+            res.json(updated);
+        }
+        catch (_) {
+            res.status(404).json({ error: 'Session not found' });
+        }
+    });
+    // POST /sessions/:id/image — upload clipboard image, proxy to system clipboard
+    const ALLOWED_IMAGE_TYPES = [
+        'image/png',
+        'image/jpeg',
+        'image/gif',
+        'image/webp',
+    ];
+    app.post('/sessions/:id/image', requireAuth, async (req, res) => {
+        const { data, mimeType } = req.body;
+        if (!data || !mimeType) {
+            res.status(400).json({ error: 'data and mimeType are required' });
+            return;
+        }
+        if (!ALLOWED_IMAGE_TYPES.includes(mimeType)) {
+            res.status(400).json({ error: 'Unsupported image type: ' + mimeType });
+            return;
+        }
+        // base64 is ~33% larger than binary; 10MB binary ≈ 13.3MB base64
+        if (data.length > 14 * 1024 * 1024) {
+            res.status(413).json({ error: 'Image too large (max 10MB)' });
+            return;
+        }
+        const sessionId = req.params['id'];
+        if (!sessions.get(sessionId)) {
+            res.status(404).json({ error: 'Session not found' });
+            return;
+        }
+        try {
+            const ext = extensionForMime(mimeType);
+            const dir = path.join(os.tmpdir(), 'relay-ide', sessionId);
+            fs.mkdirSync(dir, { recursive: true });
+            const filePath = path.join(dir, 'paste-' + Date.now() + ext);
+            fs.writeFileSync(filePath, Buffer.from(data, 'base64'));
+            let clipboardSet = false;
+            try {
+                clipboardSet = await setClipboardImage(filePath, mimeType);
+            }
+            catch {
+                // Clipboard tools failed — fall back to path
+            }
+            if (clipboardSet) {
+                sessions.write(sessionId, '\x16');
+            }
+            res.json({ path: filePath, clipboardSet });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Image upload failed';
+            res.status(500).json({ error: message });
+        }
+    });
+    // GET /version — check current vs latest
+    app.get('/version', requireAuth, async (_req, res) => {
+        const current = getCurrentVersion();
+        const channel = startupConfig.updateChannel ?? 'stable';
+        const latest = await getLatestVersion(channel);
+        const updateAvailable = latest !== null && semverLessThan(current, latest);
+        res.json({ current, latest, updateAvailable, channel });
+    });
+    // POST /update — install latest version from npm
+    app.post('/update', requireAuth, async (_req, res) => {
+        try {
+            const channel = startupConfig.updateChannel ?? 'stable';
+            const tag = channel === 'nightly' ? 'nightly' : 'latest';
+            await execFileAsync('npm', ['install', '-g', `relay-ide@${tag}`]);
+            const restarting = serviceIsInstalled();
+            if (restarting) {
+                stopEventBatching();
+                stopTelemetry();
+                serializeAll(configDir);
+            }
+            res.json({ ok: true, restarting });
+            if (restarting) {
+                setTimeout(() => process.exit(0), 1000);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Update failed';
+            res.status(500).json({ ok: false, error: message });
+        }
+    });
+    app.get('/update-channel', requireAuth, (_req, res) => {
+        res.json({ channel: startupConfig.updateChannel ?? 'stable' });
+    });
+    app.put('/update-channel', requireAuth, (req, res) => {
+        const { channel } = req.body;
+        if (channel !== 'stable' && channel !== 'nightly') {
+            res
+                .status(400)
+                .json({ error: 'Invalid channel. Must be "stable" or "nightly".' });
+            return;
+        }
+        startupConfig.updateChannel = channel;
+        saveConfig(CONFIG_PATH, startupConfig);
+        versionCache.clear();
+        res.json({ channel });
+    });
+    // Browser content viewer (token-based auth, not cookie auth)
+    const browserContentRouter = createBrowserContentRouter(broadcastEvent);
+    app.use(browserContentRouter);
+    // Clean expired browser content tokens every hour
+    const BROWSER_TOKEN_TTL = 24 * 60 * 60 * 1000;
+    setInterval(() => cleanExpiredTokens(BROWSER_TOKEN_TTL), 60 * 60 * 1000);
+    // Clean up orphaned tmux sessions from previous runs (skip any adopted by restore)
+    // Skip in dev mode — another server instance owns these sessions
+    if (process.env.NO_PIN === '1') {
+        logger.info('Dev mode: skipping orphaned tmux session cleanup.');
+    }
+    else
+        try {
+            const adoptedNames = activeTmuxSessionNames();
+            const { stdout } = await execFileAsync('tmux', [
+                'list-sessions',
+                '-F',
+                '#{session_name}',
+            ]);
+            const tmuxPrefix = getTmuxPrefix();
+            const orphanedSessions = stdout
+                .trim()
+                .split('\n')
+                .filter((name) => name.startsWith(tmuxPrefix) && !adoptedNames.has(name));
+            for (const name of orphanedSessions) {
+                execFileAsync('tmux', ['kill-session', '-t', name]).catch(() => { });
+            }
+            if (orphanedSessions.length > 0) {
+                logger.info(`Cleaned up ${orphanedSessions.length} orphaned tmux session(s).`);
+            }
+        }
+        catch {
+            // tmux not installed or no sessions — ignore
+        }
+    async function gracefulShutdown() {
+        await stopPolling();
+        stopEventBatching();
+        stopTelemetry();
+        closeAnalytics();
+        branchWatcher.close();
+        refWatcher.close();
+        gitWatcher.close();
+        server.close();
+        // Serialize sessions to disk BEFORE killing them
+        serializeAll(configDir);
+        // Kill all active sessions (PTY + tmux)
+        for (const s of sessions.list()) {
+            try {
+                sessions.kill(s.id);
+            }
+            catch {
+                /* already exiting */
+            }
+        }
+        // Brief delay to let async tmux kill-session calls fire
+        setTimeout(() => process.exit(0), 200);
+    }
+    process.on('SIGTERM', gracefulShutdown);
+    process.on('SIGINT', gracefulShutdown);
+    server.listen(startupConfig.port, startupConfig.host, () => {
+        const addr = server.address();
+        logger.info(`relay-ide listening on ${startupConfig.host}:${addr.port}`);
+    });
+}
+main().catch((err) => logger.error('Unhandled fatal error:', err));