@clauderecallhq/cli 0.0.1 → 0.11.0

package/dist/daemon/server.js

@@ -0,0 +1,2010 @@
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { getLicenseStatus } from '../license/manager.js';
+import { serveStatic } from '@hono/node-server/serve-static';
+import { existsSync, readFileSync } from 'node:fs';
+import { stat, readFile, realpath } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getDb } from '../db/client.js';
+import { placeholderHtml } from './ui.js';
+import { formatSessionAsContext, } from '../context/formatter.js';
+import { setAlias, clearAlias, getAlias } from '../utils/aliases.js';
+import { deriveAgentNote, getNote, setAutoSynopsis, setNote } from '../utils/notes.js';
+import { addTag, removeTag, tagsForSession, allTagsWithCounts, normalizeTag, } from '../utils/tags.js';
+import { listCollections, getCollection, createCollection, patchCollection, archiveCollection, restoreCollection, addSessionToCollection, removeSessionFromCollection, sessionsInCollection, collectionsForSession, descendantIds, } from '../utils/collections.js';
+import { listRules as listAutoRules, createRule as createAutoRule, patchRule as patchAutoRule, deleteRule as deleteAutoRule, listSuggestions as listAutoSuggestions, acceptSuggestion as acceptAutoSuggestion, dismissSuggestion as dismissAutoSuggestion, detectSuggestions as detectAutoSuggestions, previewMatches as previewAutoSuggestion, autoCollectionIdSet, } from '../utils/autoCollections.js';
+import { createThread, listThreads, getThread, threadsForSession, addSessionToThread, removeSessionFromThread, setParent, renameThread, closeThread, reopenThread, archiveThread, mergeThreads, splitThread, } from '../utils/threads.js';
+import { startBulkTitleJob, subscribeJob, cancelJob, getJobSnapshot, } from './bulk-title-jobs.js';
+import { terminalRegistry, looksLikeClaudeAutoTitle, stripAutoTitlePrefix, } from './terminal-registry.js';
+import { isGenericShellName, tryAutoAlias } from './correlator.js';
+/**
+ * Propagate a terminal rename to the alias of every session that started in
+ * that shell. Returns the number of sessions whose alias was updated.
+ *
+ * Name resolution mirrors the correlator's:
+ *   - Claude Code auto-titles ("⠐ Exploratory coding session", "✳ Claude
+ *     Code", etc.) get the spinner / busy / version prefix stripped. The
+ *     clean remainder (e.g. "Exploratory coding session") propagates.
+ *   - Pure spinner ("✳") or version-only strings ("2.1.119") strip to null
+ *     and are dropped — no usable content.
+ *   - Generic shell names ("zsh", "bash", "/bin/zsh") are dropped.
+ *   - Anything else propagates as-is.
+ *
+ * Idempotency: if the resolved name equals the session's current alias, we
+ * skip the SQLite write. So Claude oscillating its spinner glyph (⠐ ⠂ ⠐ …)
+ * produces zero churn — every tick strips to the same name and short-circuits.
+ */
+function propagateRenameToSessions(shell_pid, tab_name) {
+    let trimmed = tab_name.trim();
+    if (!trimmed)
+        return 0;
+    if (looksLikeClaudeAutoTitle(trimmed)) {
+        const stripped = stripAutoTitlePrefix(trimmed);
+        if (!stripped)
+            return 0;
+        trimmed = stripped;
+    }
+    if (isGenericShellName(trimmed))
+        return 0;
+    const sessions = terminalRegistry.sessionsFor(shell_pid);
+    let updated = 0;
+    for (const sid of sessions) {
+        try {
+            const current = getAlias(sid);
+            if (current === trimmed)
+                continue;
+            setAlias(sid, trimmed);
+            updated++;
+        }
+        catch {
+            /* non-fatal */
+        }
+    }
+    if (updated > 0) {
+        // eslint-disable-next-line no-console
+        console.log(`[terminal] rename of pid ${shell_pid} → "${trimmed}" propagated to ${updated} session(s)`);
+    }
+    return updated;
+}
+import { readAutoTagConfig, writeAutoTagConfig, redactForApi, AutoTagConfigSchema, } from './auto-tag-config.js';
+import { readAutoTitleConfig, writeAutoTitleConfig, AutoTitleConfigSchema, } from './auto-title-config.js';
+import { backfillHeuristicTitles, deriveAgentTitle, getAutoTitle, setAutoTitle, } from '../utils/autoTitle.js';
+import { streamSSE } from 'hono/streaming';
+import { z } from 'zod';
+import { listSessionsForScan } from './tag-scanner/session-fetcher.js';
+import { createScan, getScan, subscribe, cancelScan, deleteScan, } from './tag-scanner/scan-state.js';
+import { runScan, applyScanSelection } from './tag-scanner/orchestrator.js';
+import { kickAutopilot, getAutopilotSnapshot, subscribeAutopilot } from './tag-scanner/autopilot.js';
+import { getMcpInstallStatus, installMcp, uninstallMcp } from './mcp-installer.js';
+import { readOnboardingState, writeOnboardingState, resetOnboardingState, OnboardingStateSchema, } from './onboarding-state.js';
+import { isClaudeCliAvailable, runClaudeCliScan, spawnClaudePrompt, } from './tag-scanner/claude-cli-driver.js';
+import { publish as publishScanProgress, subscribe as subscribeScanProgress, } from './scanProgressRegistry.js';
+import { RECALL_PROMPTS, findPrompt } from '../mcp/prompts.js';
+import { readSemanticConfig, writeSemanticConfig, SemanticConfigSchema } from '../semantic/config.js';
+import { backfill as semanticBackfill, getSemanticStatus, processSession as processSemanticSession } from '../semantic/pipeline.js';
+import { getOverviewStats, getProjectStats, getSessionStats, } from '../stats/query.js';
+import { computeAllHealthScores, computeHealthScore } from '../stats/health.js';
+import { getLastBackfillRun, isBackfillRunning, runBackfill, startBackgroundBackfill, } from '../stats/backfill.js';
+import { correlateSession, findSessionsByCommit, getCommitsForSession, } from './git-correlator.js';
+import { discoverToday } from './discover.js';
+import { getEmbedderStatus, loadEmbedder } from '../semantic/embedder.js';
+import { vectorSearch, findSimilarSessions } from '../semantic/query.js';
+import { fuseResults } from '../semantic/fusion.js';
+import { startWorker, getWorkerStatus } from '../semantic/worker.js';
+import { isModelInstalled, downloadModel } from '../semantic/model-download.js';
+import { getOrCompute as getOrComputeVerification } from '../verification/compute.js';
+import { isVerificationEnabled, setVerificationEnabled } from '../verification/config.js';
+const VERSION = '0.11.0';
+const here = dirname(fileURLToPath(import.meta.url));
+const DIST_WEB = join(here, '..', 'web');
+const INDEX_HTML = join(DIST_WEB, 'index.html');
+const HAS_BUNDLED_UI = existsSync(INDEX_HTML);
+function readStats() {
+    const db = getDb();
+    return db
+        .prepare(`SELECT
+         (SELECT COUNT(*) FROM projects)                                       AS projects,
+         (SELECT COUNT(*) FROM sessions)                                       AS sessions,
+         (SELECT COUNT(*) FROM messages)                                       AS messages,
+         (SELECT MIN(started_at) FROM sessions WHERE started_at IS NOT NULL)   AS earliest,
+         (SELECT MAX(started_at) FROM sessions WHERE started_at IS NOT NULL)   AS latest`)
+        .get();
+}
+/**
+ * Tier-1 localhost hardening. The daemon binds to 127.0.0.1, but a loopback
+ * socket alone is not enough — a malicious website the user visits could
+ * otherwise reach us via DNS rebinding (attacker domain re-resolves to
+ * 127.0.0.1; browser's same-origin policy is bypassed because the hostname
+ * "matches"). We defend with three layered checks:
+ *
+ *   1. Host header must be 127.0.0.1|localhost (optionally with port).
+ *      DNS-rebinding attacks send the attacker's hostname; we reject those.
+ *   2. Origin header, when present, must be a loopback origin. Cross-origin
+ *      browser requests always carry Origin; non-browser tools (curl, the
+ *      CLI) omit it and are allowed.
+ *   3. Every response carries a strict CSP and related hardening headers so
+ *      that even if some future bug lets attacker content render, it cannot
+ *      phone home or execute inline scripts.
+ */
+const HOST_ALLOWED_RE = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i;
+const ORIGIN_ALLOWED_RE = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i;
+async function requireProMiddleware(c, next) {
+    const status = await getLicenseStatus();
+    if (status.tier !== 'pro') {
+        return c.json({
+            error: 'pro_required',
+            message: 'This feature requires a Claude Recall Pro license.',
+            upgrade_url: 'https://clauderecall.com/pricing',
+            activate_command: 'recall activate <license-key>',
+        }, 402);
+    }
+    await next();
+}
+export function buildApp() {
+    const app = new Hono();
+    // Layer 1+2: Host and Origin validation. Runs before any route.
+    app.use('*', async (c, next) => {
+        const host = c.req.raw.headers.get('host') ?? '';
+        if (!HOST_ALLOWED_RE.test(host)) {
+            return c.text('Forbidden: invalid Host header', 403);
+        }
+        const origin = c.req.raw.headers.get('origin');
+        if (origin && !ORIGIN_ALLOWED_RE.test(origin)) {
+            return c.text('Forbidden: cross-origin request rejected', 403);
+        }
+        await next();
+    });
+    // Layer 3: security headers on every response.
+    app.use('*', async (c, next) => {
+        await next();
+        // CSP scoped for a local React SPA. 'unsafe-inline' on style is required
+        // by Tailwind's injected styles; scripts stay strict.
+        c.res.headers.set('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'");
+        c.res.headers.set('X-Content-Type-Options', 'nosniff');
+        c.res.headers.set('X-Frame-Options', 'DENY');
+        c.res.headers.set('Referrer-Policy', 'no-referrer');
+        c.res.headers.set('Cross-Origin-Resource-Policy', 'same-origin');
+    });
+    app.get('/api/health', (c) => c.json({
+        status: 'ok',
+        version: VERSION,
+        pid: process.pid,
+        uptimeSeconds: Math.round(process.uptime()),
+    }));
+    app.get('/api/stats', (c) => c.json(readStats()));
+    // v0.10a — cost / token analytics.
+    //
+    // All three endpoints derive dollar amounts at render time from the
+    // static pricing table in src/utils/pricing.ts — only raw token counts
+    // are persisted in message_usage + session rollups. Prices change; the
+    // source of truth shouldn't.
+    app.get('/api/stats/session/:id', (c) => {
+        const stats = getSessionStats(c.req.param('id'));
+        if (!stats)
+            return c.json({ error: 'session not found' }, 404);
+        return c.json(stats);
+    });
+    app.get('/api/stats/project/:name', (c) => {
+        const stats = getProjectStats(c.req.param('name'));
+        if (!stats)
+            return c.json({ error: 'project not found' }, 404);
+        return c.json(stats);
+    });
+    app.get('/api/stats/overview', (c) => {
+        const raw = c.req.query('range');
+        const range = raw === '7d' ? '7d' : raw === '30d' ? '30d' : 'all';
+        return c.json(getOverviewStats(range));
+    });
+    // Run a backfill pass. Synchronous up to ~5k messages so the UI gets
+    // accurate stats back in the same response (chunked txns keep locks
+    // short). Larger requests fall back to the background queue.
+    app.post('/api/stats/backfill', async (c) => {
+        const body = (await c.req.json().catch(() => ({})));
+        const limit = body.limit
+            ? Math.max(1, Math.min(100_000, Number(body.limit)))
+            : 5_000;
+        if (limit > 5_000) {
+            const started = startBackgroundBackfill({ limit });
+            return c.json({
+                mode: 'background',
+                started,
+                alreadyRunning: !started && isBackfillRunning(),
+                limit,
+                lastRun: getLastBackfillRun(),
+            });
+        }
+        const result = runBackfill({ limit });
+        return c.json({
+            mode: 'sync',
+            started: false,
+            alreadyRunning: false,
+            limit,
+            result,
+            lastRun: getLastBackfillRun(),
+        });
+    });
+    // v0.16 — Memory health score
+    app.get('/api/stats/health', (c) => {
+        return c.json(computeAllHealthScores());
+    });
+    app.get('/api/stats/health/:projectId', (c) => {
+        const id = Number(c.req.param('projectId'));
+        const result = computeHealthScore(id);
+        if (!result)
+            return c.json({ error: 'project not found' }, 404);
+        return c.json(result);
+    });
+    // v0.16 — Verification badges
+    app.get('/api/config/verification', (c) => {
+        return c.json({ enabled: isVerificationEnabled() });
+    });
+    app.put('/api/config/verification', async (c) => {
+        const body = (await c.req.json());
+        if (typeof body.enabled === 'boolean') {
+            setVerificationEnabled(body.enabled);
+        }
+        return c.json({ enabled: isVerificationEnabled() });
+    });
+    app.get('/api/sessions/:id/verification', (c) => {
+        const id = c.req.param('id');
+        const result = getOrComputeVerification(id);
+        return c.json(result);
+    });
+    // v0.10b — git correlation endpoints.
+    //
+    // Both are read-only. The write-path (running `git log`) is triggered by
+    // the daemon's own watcher + the explicit `recall correlate` CLI; we do
+    // not expose a POST here that lets arbitrary HTTP callers fire scoped
+    // subprocesses. If a session hasn't been correlated yet, the GET returns
+    // an empty list and the transcript header quietly shows nothing.
+    app.get('/api/sessions/:id/commits', async (c) => {
+        const id = c.req.param('id');
+        const existing = getCommitsForSession(id);
+        if (existing.length > 0 || c.req.query('refresh') !== '1') {
+            return c.json({ commits: existing });
+        }
+        // Lazy first-view correlation. Only runs when explicitly asked via
+        // ?refresh=1 to keep pageload cheap on repeat visits.
+        const res = await correlateSession(id);
+        return c.json({ commits: getCommitsForSession(id), status: res.status });
+    });
+    app.get('/api/commits/:sha/session', (c) => {
+        const sha = c.req.param('sha');
+        if (!/^[0-9a-fA-F]{4,40}$/.test(sha)) {
+            return c.json({ error: 'invalid sha format' }, 400);
+        }
+        return c.json({ sessions: findSessionsByCommit(sha) });
+    });
+    // v0.12b — Rediscovery "For you" picks. Three independent cards (rediscovered,
+    // expensive, authored) plus the availability bitmap so the UI can distinguish
+    // "feature off" from "feature on but no pick today". Each card is null when
+    // its backing data stream isn't producing yet (v0.11 semantic, v0.10a cost,
+    // v0.10b git respectively) — the response shape is stable so the client can
+    // render each slot independently.
+    app.get('/api/license/status', async (c) => {
+        const status = await getLicenseStatus();
+        return c.json(status);
+    });
+    app.get('/api/discover/today', requireProMiddleware, async (c) => {
+        try {
+            return c.json(await discoverToday());
+        }
+        catch (err) {
+            console.error('[discover.today]', err);
+            return c.json({
+                rediscovered: null,
+                expensive: null,
+                authored: null,
+                availability: { semantic: false, cost: false, git: false },
+                generatedAt: new Date().toISOString(),
+                error: err.message,
+            }, 500);
+        }
+    });
+    app.get('/api/projects', (c) => {
+        const db = getDb();
+        const rows = db
+            .prepare(`SELECT p.id, p.name, p.decoded_path,
+                COUNT(s.id)                     AS session_count,
+                COALESCE(SUM(s.message_count), 0) AS message_count,
+                MAX(COALESCE(s.ended_at, s.started_at)) AS latest
+         FROM projects p
+         LEFT JOIN sessions s ON s.project_id = p.id
+         GROUP BY p.id
+         ORDER BY MAX(COALESCE(s.ended_at, s.started_at, '')) DESC`)
+            .all();
+        return c.json(rows);
+    });
+    app.get('/api/sessions', (c) => {
+        const db = getDb();
+        const project = c.req.query('project');
+        const since = c.req.query('since');
+        const until = c.req.query('until');
+        const tagsFilter = c.req.queries('tag') ?? [];
+        const collection = c.req.query('collection');
+        const limit = Math.max(1, Math.min(500, Number(c.req.query('limit') ?? 100)));
+        const params = { limit };
+        let where = 's.message_count > 2';
+        if (project) {
+            where += ' AND (p.name LIKE @proj OR p.decoded_path LIKE @proj)';
+            params.proj = `%${project}%`;
+        }
+        if (since) {
+            where += ' AND s.started_at >= @since';
+            params.since = since;
+        }
+        if (until) {
+            where += ' AND s.started_at <= @until';
+            if (/^\d{4}-\d{2}-\d{2}$/.test(until))
+                params.until = `${until}T23:59:59.999Z`;
+            else
+                params.until = until;
+        }
+        if (tagsFilter.length > 0) {
+            const normalized = tagsFilter.map((t) => normalizeTag(t)).filter(Boolean);
+            normalized.forEach((tag, i) => {
+                where += ` AND s.id IN (SELECT session_id FROM session_tags WHERE tag = @tag_${i})`;
+                params[`tag_${i}`] = tag;
+            });
+        }
+        if (collection) {
+            // Collections are hierarchical; filtering by a parent includes every
+            // child collection's sessions too (matches the UX spec: "recursively
+            // include child collections when the collection has children").
+            const ids = descendantIds(collection);
+            if (ids.length === 0) {
+                return c.json([]);
+            }
+            const placeholders = ids.map((_, i) => `@col_${i}`).join(',');
+            where += ` AND s.id IN (SELECT session_id FROM collection_sessions WHERE collection_id IN (${placeholders}))`;
+            ids.forEach((cid, i) => {
+                params[`col_${i}`] = cid;
+            });
+        }
+        const rows = db
+            .prepare(`SELECT s.id, p.name AS project, s.started_at, s.ended_at,
+                s.message_count, s.first_user_message, s.git_branch,
+                s.auto_title, s.auto_title_source, s.verification_status,
+                NULLIF(sa.alias, '') AS alias,
+                CASE
+                  WHEN (sn.content IS NOT NULL AND sn.content != '')
+                    OR (sn.auto_synopsis IS NOT NULL AND sn.auto_synopsis != '')
+                  THEN 1 ELSE 0
+                END AS has_notes,
+                COALESCE(
+                  (SELECT GROUP_CONCAT(tag, ',')
+                   FROM (SELECT tag FROM session_tags WHERE session_id = s.id ORDER BY tag)),
+                  ''
+                ) AS tags_csv
+         FROM sessions s
+         JOIN projects p ON p.id = s.project_id
+         LEFT JOIN session_aliases sa ON sa.session_id = s.id
+         LEFT JOIN session_notes   sn ON sn.session_id = s.id
+         WHERE ${where}
+         ORDER BY COALESCE(s.ended_at, s.started_at, '') DESC
+         LIMIT @limit`)
+            .all(params);
+        // Expand tags_csv into a real array for the client, then decorate each
+        // row with the editor/terminal origin (in-memory, v0.15 T4). Origin is
+        // a separate lookup because we deliberately don't persist it to SQLite.
+        const expanded = rows.map(({ tags_csv, ...rest }) => {
+            const sessionId = rest.id;
+            const detected = terminalRegistry.getOrigin(sessionId);
+            // 'auto' = correlator-set from a terminal tab name or origin fallback.
+            // 'manual' = user typed it via PUT /api/sessions/:id/alias. Mirrors
+            // the same logic in the detail endpoint so the list view can apply
+            // the same display precedence (auto_title beats auto-alias).
+            const aliasValue = rest.alias;
+            const aliasSource = aliasValue == null
+                ? null
+                : terminalRegistry.isSessionAutoLinked(sessionId)
+                    ? 'auto'
+                    : 'manual';
+            return {
+                ...rest,
+                tags: tags_csv ? tags_csv.split(',') : [],
+                origin: detected ? { editor: detected.editor, label: detected.label } : null,
+                alias_source: aliasSource,
+            };
+        });
+        return c.json(expanded);
+    });
+    app.get('/api/sessions/:id', (c) => {
+        const db = getDb();
+        const id = c.req.param('id');
+        const session = db
+            .prepare(`SELECT s.*, p.name AS project_name, p.decoded_path,
+                NULLIF(sa.alias, '') AS alias
+         FROM sessions s
+         JOIN projects p ON p.id = s.project_id
+         LEFT JOIN session_aliases sa ON sa.session_id = s.id
+         WHERE s.id = ?`)
+            .get(id);
+        if (!session)
+            return c.json({ error: 'not found' }, 404);
+        const tags = tagsForSession(id);
+        const detected = terminalRegistry.getOrigin(id);
+        const origin = detected
+            ? { editor: detected.editor, label: detected.label }
+            : null;
+        // 'auto' = alias set by the correlator from a terminal tab name or origin
+        // fallback. 'manual' = user typed it via PUT /api/sessions/:id/alias.
+        // The client uses this to decide whether an ✨ agent title should beat
+        // the alias on display (auto → yes, manual → no).
+        const aliasSource = session.alias == null
+            ? null
+            : terminalRegistry.isSessionAutoLinked(id)
+                ? 'auto'
+                : 'manual';
+        const messages = db
+            .prepare(`SELECT uuid, type, role, timestamp, is_sidechain, content_text, tool_names
+         FROM messages
+         WHERE session_id = ?
+         ORDER BY COALESCE(timestamp, ''), rowid`)
+            .all(id);
+        return c.json({
+            session: { ...session, tags, origin, alias_source: aliasSource },
+            messages,
+        });
+    });
+    // Tag endpoints
+    app.get('/api/tags', (c) => c.json(allTagsWithCounts()));
+    app.get('/api/sessions/:id/tags', (c) => {
+        return c.json({ tags: tagsForSession(c.req.param('id')) });
+    });
+    app.post('/api/sessions/:id/tags', async (c) => {
+        const id = c.req.param('id');
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.tag !== 'string') {
+            return c.json({ error: 'tag required' }, 400);
+        }
+        try {
+            const result = addTag(id, body.tag);
+            return c.json(result);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.delete('/api/sessions/:id/tags/:tag', (c) => {
+        const id = c.req.param('id');
+        const tag = c.req.param('tag');
+        return c.json(removeTag(id, tag));
+    });
+    // Auto-tag config. GET redacts the apiKey over the wire (returns a marker
+    // + `hasApiKey` bool). PUT merges the submitted patch with existing values,
+    // preserving a stored apiKey when the PUT body omits one.
+    app.get('/api/config/auto-tag', (c) => {
+        return c.json(redactForApi(readAutoTagConfig()));
+    });
+    app.put('/api/config/auto-tag', async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = AutoTagConfigSchema.partial().safeParse(body);
+        if (!parsed.success) {
+            return c.json({ error: 'invalid config', issues: parsed.error.issues }, 400);
+        }
+        const patch = parsed.data;
+        // If caller did not send an apiKey field, preserve the existing one.
+        if (patch.apiKey === undefined) {
+            delete patch.apiKey;
+        }
+        const merged = writeAutoTagConfig(patch);
+        // Autopilot depends on config — kick it so it picks up flag changes.
+        if (merged.autopilot && merged.enabled && merged.backend === 'api' && merged.apiKey) {
+            void kickAutopilot();
+        }
+        return c.json(redactForApi(merged));
+    });
+    // v0.14a — first-run onboarding state. The web UI hits this on boot; if
+    // `completed` and `skipped` are both false the 3-step tour fires. Writes
+    // are additive (history-preserving); reset wipes the terminal flags so
+    // the "Replay onboarding" button in the Command Center can fire again.
+    app.get('/api/onboarding', (c) => {
+        const db = getDb();
+        const latest = db
+            .prepare(`SELECT s.id,
+                p.name AS project,
+                s.started_at,
+                s.ended_at,
+                s.message_count,
+                s.first_user_message,
+                NULLIF(sa.alias, '') AS alias
+         FROM sessions s
+         JOIN projects p ON p.id = s.project_id
+         LEFT JOIN session_aliases sa ON sa.session_id = s.id
+         WHERE s.message_count > 2
+         ORDER BY COALESCE(s.ended_at, s.started_at, '') DESC
+         LIMIT 1`)
+            .get();
+        return c.json({ state: readOnboardingState(), mostRecentSession: latest ?? null });
+    });
+    app.put('/api/onboarding', async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = OnboardingStateSchema.partial().safeParse(body);
+        if (!parsed.success) {
+            return c.json({ error: 'invalid onboarding state', issues: parsed.error.issues }, 400);
+        }
+        return c.json(writeOnboardingState(parsed.data));
+    });
+    app.post('/api/onboarding/reset', (c) => c.json(resetOnboardingState()));
+    // One-click MCP install into ~/.claude.json. Merges surgically; never
+    // clobbers other MCP entries the user may already have.
+    app.get('/api/config/mcp-install', (c) => c.json({ ...getMcpInstallStatus(), claudeCliAvailable: isClaudeCliAvailable() }));
+    app.post('/api/config/mcp-install', (c) => c.json({ ...installMcp(), claudeCliAvailable: isClaudeCliAvailable() }));
+    app.delete('/api/config/mcp-install', (c) => c.json({ ...uninstallMcp(), claudeCliAvailable: isClaudeCliAvailable() }));
+    // Button-driven MCP scan: spawn `claude -p` in headless mode so the
+    // user's own Claude Code subscription does the work — no API key, no
+    // copy-paste. Claude picks up the Recall MCP server from ~/.claude.json
+    // and applies tags via mcp__recall__apply_tags. We block until the
+    // subprocess finishes (capped at 30 min by the driver) and report the
+    // tag-count delta so the UI can show a concrete result.
+    const ClaudeCliScanSchema = z.object({
+        scope: z
+            .object({
+            untaggedOnly: z.boolean().optional(),
+            project: z.string().optional(),
+            collectionId: z.string().optional(),
+            sessionIds: z.array(z.string()).optional(),
+            limit: z.number().int().min(1).max(500).optional(),
+        })
+            .default({}),
+        /** Optional per-run model override; falls back to config.model, then claude's default. */
+        model: z.string().optional(),
+        /**
+         * Optional client-generated scan id. When present the runner emits per-
+         * session progress events on scanProgressRegistry so an EventSource
+         * subscriber can render live "Tagging session X of N" feedback. Clients
+         * that don't care (e.g. the legacy settings dialog) can omit it.
+         */
+        scanId: z.string().min(1).max(100).optional(),
+    });
+    app.post('/api/tags/scan/claude-cli', async (c) => {
+        if (!isClaudeCliAvailable()) {
+            return c.json({
+                error: 'claude CLI not found on PATH. Install Claude Code locally, then reload.',
+            }, 400);
+        }
+        const mcp = getMcpInstallStatus();
+        if (!mcp.installed) {
+            return c.json({ error: 'Recall MCP is not installed in Claude Code yet — run the one-click install first.' }, 400);
+        }
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = ClaudeCliScanSchema.safeParse(body);
+        if (!parsed.success) {
+            return c.json({ error: 'invalid scope', issues: parsed.error.issues }, 400);
+        }
+        const scope = parsed.data.scope;
+        // Model precedence: per-run override → config.model → claude's default.
+        const cfg = readAutoTagConfig();
+        const model = parsed.data.model ?? cfg.model;
+        const db = getDb();
+        const tagCount = () => db
+            .prepare('SELECT COUNT(*) AS n FROM session_tags')
+            .get().n;
+        const before = tagCount();
+        const scanId = parsed.data.scanId;
+        const result = await runClaudeCliScan(scope, { model, scanId });
+        const after = tagCount();
+        const tagsAdded = Math.max(0, after - before);
+        // When the client passed a scanId, broadcast the terminal event so any
+        // open SSE subscriber can render the final success bubble and close.
+        if (scanId) {
+            publishScanProgress(scanId, {
+                type: 'done',
+                result: { success: result.success, exitCode: result.exitCode, tagsAdded },
+            });
+        }
+        return c.json({
+            success: result.success,
+            exitCode: result.exitCode,
+            tagsAdded,
+            model,
+            stdout: result.stdout.slice(0, 2000),
+            stderrTail: result.stderr.slice(-2000),
+        });
+    });
+    // Per-scan progress stream for the claude-cli auto-tag runner. Clients
+    // generate a scanId (UUID), open this EventSource first, then POST
+    // /api/tags/scan/claude-cli with the same id — the POST runs the scan
+    // and publishes progress on the registry while this route relays it.
+    // Heartbeats every 15s to keep intermediaries from closing the socket.
+    app.get('/api/claude-cli/scan/:scanId/progress', (c) => {
+        const scanId = c.req.param('scanId');
+        return streamSSE(c, async (stream) => {
+            const pending = [];
+            const wake = { resolve: () => { } };
+            let waiter = new Promise((r) => {
+                wake.resolve = r;
+            });
+            const unsubscribe = subscribeScanProgress(scanId, (ev) => {
+                pending.push(ev);
+                const prev = wake.resolve;
+                waiter = new Promise((r) => {
+                    wake.resolve = r;
+                });
+                prev();
+            });
+            // Heartbeat loop: every 15s, push a `: heartbeat` comment. Keeps
+            // proxies (if any) and browsers from considering the stream idle.
+            let closed = false;
+            const heartbeat = setInterval(() => {
+                if (closed)
+                    return;
+                stream.writeSSE({ event: 'heartbeat', data: '' }).catch(() => {
+                    closed = true;
+                });
+            }, 15_000);
+            try {
+                while (!closed) {
+                    if (pending.length === 0)
+                        await waiter;
+                    const ev = pending.shift();
+                    if (!ev)
+                        continue;
+                    await stream.writeSSE({ event: ev.type, data: JSON.stringify(ev) });
+                    if (ev.type === 'done')
+                        break;
+                }
+            }
+            finally {
+                closed = true;
+                clearInterval(heartbeat);
+                unsubscribe();
+            }
+        });
+    });
+    // Recall prompt library: list + run. Any Recall prompt registered in
+    // src/mcp/prompts.ts is automatically exposed here so the web UI (and
+    // any other HTTP consumer) can spawn the user's local claude CLI to
+    // execute it. Same prompts, same MCP tools, same one-source-of-truth.
+    app.get('/api/prompts', (c) => c.json({
+        prompts: RECALL_PROMPTS.map((p) => ({
+            name: p.name,
+            title: p.title,
+            description: p.description,
+        })),
+        claudeCliAvailable: isClaudeCliAvailable(),
+    }));
+    app.post('/api/prompts/run', async (c) => {
+        if (!isClaudeCliAvailable()) {
+            return c.json({ error: 'claude CLI not found on PATH. Install Claude Code locally, then reload.' }, 400);
+        }
+        const mcp = getMcpInstallStatus();
+        if (!mcp.installed) {
+            return c.json({ error: 'Recall MCP is not installed in Claude Code yet — run the one-click install first.' }, 400);
+        }
+        const body = await c.req.json().catch(() => ({}));
+        const PromptRunSchema = z.object({
+            name: z.string(),
+            args: z.record(z.string(), z.unknown()).optional(),
+            model: z.string().optional(),
+        });
+        const parsed = PromptRunSchema.safeParse(body);
+        if (!parsed.success) {
+            return c.json({ error: 'invalid request', issues: parsed.error.issues }, 400);
+        }
+        const def = findPrompt(parsed.data.name);
+        if (!def)
+            return c.json({ error: `unknown prompt: ${parsed.data.name}` }, 404);
+        const promptText = def.build((parsed.data.args ?? {}));
+        const cfg = readAutoTagConfig();
+        const model = parsed.data.model ?? cfg.model;
+        const result = await spawnClaudePrompt(promptText, def.allowedTools, { model });
+        return c.json({
+            success: result.success,
+            exitCode: result.exitCode,
+            promptName: def.name,
+            model,
+            stdout: result.stdout,
+            stderrTail: result.stderr.slice(-4000),
+        });
+    });
+    // Autopilot status: GET snapshot, SSE stream for live progress updates.
+    app.get('/api/autopilot/status', (c) => c.json(getAutopilotSnapshot()));
+    app.get('/api/autopilot/events', (c) => streamSSE(c, async (stream) => {
+        await stream.writeSSE({ event: 'state', data: JSON.stringify(getAutopilotSnapshot()) });
+        const pending = [];
+        let resolve = () => { };
+        let wait = new Promise((r) => (resolve = r));
+        const unsubscribe = subscribeAutopilot((snap) => {
+            pending.push(snap);
+            const prev = resolve;
+            wait = new Promise((r) => (resolve = r));
+            prev();
+        });
+        try {
+            // Heartbeat loop with 30s max idle to keep the stream warm.
+            while (true) {
+                if (pending.length === 0) {
+                    const heartbeat = new Promise((r) => setTimeout(() => r('tick'), 30000));
+                    const next = await Promise.race([wait.then(() => 'event'), heartbeat]);
+                    if (next === 'tick') {
+                        await stream.writeSSE({ event: 'heartbeat', data: '1' });
+                        continue;
+                    }
+                }
+                const snap = pending.shift();
+                if (!snap)
+                    continue;
+                await stream.writeSSE({ event: 'state', data: JSON.stringify(snap) });
+            }
+        }
+        finally {
+            unsubscribe();
+        }
+    }));
+    app.post('/api/autopilot/kick', (c) => {
+        void kickAutopilot();
+        return c.json({ ok: true, snapshot: getAutopilotSnapshot() });
+    });
+    // Auto-tag scan lifecycle.
+    // POST /api/tags/scan        — start a background scan, returns { scanId, total }
+    // GET  /api/tags/scan/:id    — snapshot of current state
+    // GET  /api/tags/scan/:id/events  — SSE stream of progress/result/status/done events
+    // POST /api/tags/scan/:id/apply   — persist selected suggestions as tags
+    // DELETE /api/tags/scan/:id       — cancel + forget
+    const StartScanSchema = z.object({
+        scope: z
+            .object({
+            untaggedOnly: z.boolean().optional(),
+            project: z.string().optional(),
+            collectionId: z.string().optional(),
+            sessionIds: z.array(z.string()).optional(),
+            limit: z.number().int().min(1).max(500).optional(),
+        })
+            .default({}),
+    });
+    app.post('/api/tags/scan', async (c) => {
+        const cfg = readAutoTagConfig();
+        if (!cfg.enabled)
+            return c.json({ error: 'auto-tagging is disabled' }, 403);
+        if (cfg.backend !== 'api') {
+            return c.json({ error: 'api-backend scan requires backend=api in config' }, 400);
+        }
+        if (!cfg.apiKey)
+            return c.json({ error: 'no api key configured' }, 400);
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = StartScanSchema.safeParse(body);
+        if (!parsed.success)
+            return c.json({ error: 'invalid scope', issues: parsed.error.issues }, 400);
+        const sessions = listSessionsForScan(parsed.data.scope);
+        if (sessions.length === 0)
+            return c.json({ error: 'no sessions match scope' }, 400);
+        const rec = createScan(sessions.length);
+        // fire-and-forget; client subscribes via SSE
+        void runScan(rec, {
+            apiKey: cfg.apiKey,
+            model: cfg.model,
+            minTags: cfg.minTagsPerSession,
+            maxTags: cfg.maxTagsPerSession,
+            sessions,
+        });
+        return c.json({ scanId: rec.id, total: rec.total });
+    });
+    app.get('/api/tags/scan/:id', (c) => {
+        const rec = getScan(c.req.param('id'));
+        if (!rec)
+            return c.json({ error: 'scan not found' }, 404);
+        // Strip non-serializable fields (AbortController, listener set) before
+        // emitting a snapshot over the wire.
+        const { controller: _controller, listeners: _listeners, ...safe } = rec;
+        void _controller;
+        void _listeners;
+        return c.json(safe);
+    });
+    app.get('/api/tags/scan/:id/events', (c) => {
+        const rec = getScan(c.req.param('id'));
+        if (!rec)
+            return c.json({ error: 'scan not found' }, 404);
+        return streamSSE(c, async (stream) => {
+            // Replay current state so late subscribers see what they missed.
+            await stream.writeSSE({
+                event: 'state',
+                data: JSON.stringify({
+                    completed: rec.completed,
+                    total: rec.total,
+                    status: rec.status,
+                }),
+            });
+            for (const r of rec.results) {
+                await stream.writeSSE({ event: 'result', data: JSON.stringify(r) });
+            }
+            // Subscribe for new events via a simple pending-queue + wake-promise.
+            const pending = [];
+            const wake = { resolve: () => { } };
+            let waiter = new Promise((r) => {
+                wake.resolve = r;
+            });
+            const unsubscribe = subscribe(rec, (ev) => {
+                pending.push(ev);
+                const prev = wake.resolve;
+                waiter = new Promise((r) => {
+                    wake.resolve = r;
+                });
+                prev();
+            });
+            try {
+                while (rec.status === 'running' || rec.status === 'pending') {
+                    if (pending.length === 0)
+                        await waiter;
+                    const ev = pending.shift();
+                    if (!ev)
+                        continue;
+                    await stream.writeSSE({ event: ev.type, data: JSON.stringify(ev) });
+                    if (ev.type === 'done')
+                        break;
+                    if (ev.type === 'status' && (ev.status === 'cancelled' || ev.status === 'failed'))
+                        break;
+                }
+            }
+            finally {
+                unsubscribe();
+            }
+        });
+    });
+    const ApplySchema = z.object({
+        selection: z.array(z.object({
+            sessionId: z.string(),
+            tags: z.array(z.string()).min(1),
+        })),
+    });
+    app.post('/api/tags/scan/:id/apply', async (c) => {
+        const rec = getScan(c.req.param('id'));
+        if (!rec)
+            return c.json({ error: 'scan not found' }, 404);
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = ApplySchema.safeParse(body);
+        if (!parsed.success)
+            return c.json({ error: 'invalid selection' }, 400);
+        const result = applyScanSelection(rec, parsed.data.selection);
+        return c.json(result);
+    });
+    app.delete('/api/tags/scan/:id', (c) => {
+        const id = c.req.param('id');
+        cancelScan(id);
+        deleteScan(id);
+        return c.json({ ok: true });
+    });
+    // Alias CRUD. Never deletes history — DELETE clears to empty with history preserved.
+    app.put('/api/sessions/:id/alias', async (c) => {
+        const id = c.req.param('id');
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.alias !== 'string') {
+            return c.json({ error: 'alias required' }, 400);
+        }
+        try {
+            const row = setAlias(id, body.alias);
+            // User explicitly typed an alias — from now on treat it as manual
+            // intent. The correlator MUST NOT clobber it on rename, and the client
+            // MUST render it over any agent title.
+            terminalRegistry.unlinkSession(id);
+            return c.json(row);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.delete('/api/sessions/:id/alias', (c) => {
+        const id = c.req.param('id');
+        clearAlias(id);
+        terminalRegistry.unlinkSession(id);
+        return c.json({ ok: true });
+    });
+    app.get('/api/sessions/:id/alias', (c) => {
+        const id = c.req.param('id');
+        return c.json({ alias: getAlias(id) });
+    });
+    // v0.14b (T5) — auto-title config.
+    app.get('/api/config/auto-title', (c) => c.json(readAutoTitleConfig()));
+    app.put('/api/config/auto-title', async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = AutoTitleConfigSchema.partial().safeParse(body);
+        if (!parsed.success) {
+            return c.json({ error: 'invalid config', issues: parsed.error.issues }, 400);
+        }
+        return c.json(writeAutoTitleConfig(parsed.data));
+    });
+    app.get('/api/sessions/:id/auto-title', (c) => {
+        const id = c.req.param('id');
+        const row = getAutoTitle(id);
+        if (!row)
+            return c.json({ error: 'session not found' }, 404);
+        return c.json(row);
+    });
+    /**
+     * Agent-generated title. 403 until the user has flipped
+     * `autoTitle.agentEnabled` in config — the endpoint shells out to `claude`
+     * and uses their subscription, so we only fire it on explicit opt-in.
+     */
+    app.post('/api/sessions/:id/auto-title', async (c) => {
+        const id = c.req.param('id');
+        const cfg = readAutoTitleConfig();
+        if (!cfg.agentEnabled) {
+            return c.json({ error: 'autoTitle.agentEnabled is false' }, 403);
+        }
+        const db = getDb();
+        const exists = db.prepare('SELECT 1 FROM sessions WHERE id = ?').get(id);
+        if (!exists)
+            return c.json({ error: 'session not found' }, 404);
+        try {
+            const title = await deriveAgentTitle(id);
+            setAutoTitle(id, title, 'agent');
+            return c.json(getAutoTitle(id));
+        }
+        catch (err) {
+            return c.json({ error: err.message, code: 'agent-title-failed' }, 500);
+        }
+    });
+    // Notes CRUD — never truly delete, PUT with empty string is the "clear" action.
+    app.get('/api/sessions/:id/notes', (c) => {
+        const id = c.req.param('id');
+        const note = getNote(id);
+        if (!note) {
+            // 204 No Content = no row yet; client treats as "empty, not-yet-created"
+            return c.body(null, 204);
+        }
+        return c.json(note);
+    });
+    app.put('/api/sessions/:id/notes', async (c) => {
+        const id = c.req.param('id');
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.content !== 'string') {
+            return c.json({ error: 'content required (string)' }, 400);
+        }
+        try {
+            const row = setNote(id, body.content);
+            return c.json(row);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 500);
+        }
+    });
+    /**
+     * ✨ Generate Note — runs claude -p over a sampled transcript and stores
+     * the resulting markdown synopsis in `session_notes.auto_synopsis`. Never
+     * overwrites the user-typed `content`. Returns the full notes row so the
+     * client can re-render manual + synopsis side by side.
+     *
+     * Gated behind the same agentEnabled config flag as ✨ Generate Title —
+     * shells out to the user's Claude subscription.
+     */
+    app.post('/api/sessions/:id/generate-note', async (c) => {
+        const id = c.req.param('id');
+        const cfg = readAutoTitleConfig();
+        if (!cfg.agentEnabled) {
+            return c.json({ error: 'autoTitle.agentEnabled is false' }, 403);
+        }
+        try {
+            const synopsis = await deriveAgentNote(id);
+            const row = setAutoSynopsis(id, synopsis);
+            return c.json(row);
+        }
+        catch (err) {
+            const msg = err.message;
+            // 404 for missing session/messages, 500 for CLI failure.
+            const status = /no messages available/i.test(msg) ? 404 : 500;
+            return c.json({ error: msg }, status);
+        }
+    });
+    // v0.11 — semantic search config + status. Off by default. Enabling sends
+    // condensed session summaries to Claude via the local `claude` CLI; the UI
+    // surfaces this disclosure before flipping the switch.
+    app.get('/api/semantic/status', (c) => c.json(getSemanticStatus()));
+    app.put('/api/semantic/config', async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = SemanticConfigSchema.partial().safeParse(body);
+        if (!parsed.success) {
+            return c.json({ error: 'invalid semantic config', issues: parsed.error.issues }, 400);
+        }
+        writeSemanticConfig(parsed.data);
+        return c.json(getSemanticStatus());
+    });
+    app.get('/api/semantic/config', (c) => c.json(readSemanticConfig()));
+    // Trigger a non-blocking backfill pass. Returns immediately; progress
+    // can be polled via /api/semantic/status.
+    app.post('/api/semantic/backfill', async (c) => {
+        const cfg = readSemanticConfig();
+        if (!cfg.enabled)
+            return c.json({ error: 'semantic search is disabled' }, 400);
+        const body = (await c.req.json().catch(() => ({})));
+        const limit = Math.max(1, Math.min(5000, Number(body.limit ?? 200)));
+        void semanticBackfill({ limit, force: !!body.force }).catch((err) => console.error('[semantic.backfill] error:', err));
+        return c.json({ ok: true, limit });
+    });
+    // One-shot summarize for a single session (e.g. from the transcript header).
+    app.post('/api/semantic/sessions/:id', async (c) => {
+        const cfg = readSemanticConfig();
+        if (!cfg.enabled)
+            return c.json({ error: 'semantic search is disabled' }, 400);
+        const id = c.req.param('id');
+        const result = await processSemanticSession(id);
+        return c.json(result);
+    });
+    // v0.7 — Vector tier endpoints (Pro-only)
+    app.get('/api/semantic/vector-status', (c) => {
+        const embedder = getEmbedderStatus();
+        const worker = getWorkerStatus();
+        const modelInstalled = isModelInstalled();
+        return c.json({ embedder, worker, modelInstalled });
+    });
+    app.post('/api/semantic/install', requireProMiddleware, async (c) => {
+        if (isModelInstalled())
+            return c.json({ ok: true, status: 'already_installed' });
+        try {
+            await downloadModel();
+            await loadEmbedder();
+            startWorker();
+            return c.json({ ok: true, status: 'installed' });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : 'unknown error';
+            return c.json({ ok: false, error: msg }, 500);
+        }
+    });
+    app.get('/api/sessions/:id/similar', requireProMiddleware, async (c) => {
+        if (!getEmbedderStatus().loaded) {
+            return c.json({ error: 'vector model not loaded' }, 503);
+        }
+        const id = c.req.param('id');
+        const limit = Math.max(1, Math.min(50, Number(c.req.query('limit') ?? 10)));
+        try {
+            const results = await findSimilarSessions(id, limit);
+            return c.json({ sessionId: id, similar: results });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : 'unknown error';
+            return c.json({ error: msg }, 500);
+        }
+    });
+    app.get('/api/search', requireProMiddleware, async (c) => {
+        const db = getDb();
+        const q = c.req.query('q')?.trim();
+        if (!q)
+            return c.json({ query: '', hits: [], tags: [] });
+        // Bound the query length — pathological inputs (thousands of tokens)
+        // would build huge SQL and an expensive FTS5 plan. 500 is 5× any sane
+        // search.
+        if (q.length > 500)
+            return c.json({ error: 'query too long (max 500 chars)' }, 400);
+        const project = c.req.query('project');
+        // Split query tokens: anything starting with '#' becomes a tag filter,
+        // everything else goes to FTS. `#auth-fix migration` = sessions tagged
+        // 'auth-fix' AND message text contains 'migration'.
+        const tokens = q.split(/\s+/).filter((t) => t.length > 0);
+        const tagTokens = tokens.filter((t) => t.startsWith('#')).map((t) => normalizeTag(t)).filter(Boolean);
+        const textTokens = tokens.filter((t) => !t.startsWith('#'));
+        const terms = textTokens.map((t) => `"${t.replace(/"/g, '')}"`);
+        const fts = terms.join(' ');
+        const limit = Math.max(1, Math.min(200, Number(c.req.query('limit') ?? 30)));
+        // Tag-only queries: no FTS at all, just list matching sessions' first
+        // user message as the snippet.
+        if (terms.length === 0 && tagTokens.length > 0) {
+            let sql = `
+        SELECT s.id            AS session_id,
+               s.id             AS message_uuid,
+               p.name           AS project,
+               s.started_at,
+               COALESCE(s.first_user_message, '')  AS snippet,
+               CAST(NULL AS TEXT) AS role,
+               CAST(NULL AS TEXT) AS timestamp,
+               NULLIF(sa.alias, '') AS alias
+        FROM sessions s
+        JOIN projects p ON p.id = s.project_id
+        LEFT JOIN session_aliases sa ON sa.session_id = s.id
+        WHERE 1=1
+      `;
+            const params = { limit };
+            if (project) {
+                sql += ' AND (p.name LIKE @proj OR p.decoded_path LIKE @proj)';
+                params.proj = `%${project}%`;
+            }
+            tagTokens.forEach((tag, i) => {
+                sql += ` AND s.id IN (SELECT session_id FROM session_tags WHERE tag = @tag_${i})`;
+                params[`tag_${i}`] = tag;
+            });
+            sql += ' ORDER BY COALESCE(s.started_at, \'\') DESC LIMIT @limit';
+            const rows = db.prepare(sql).all(params);
+            return c.json({ query: q, hits: rows, tags: tagTokens });
+        }
+        let sql = `
+      SELECT m.session_id AS session_id,
+             m.uuid        AS message_uuid,
+             p.name        AS project,
+             s.started_at,
+             snippet(messages_fts, 0, '<<', '>>', '…', 20) AS snippet,
+             m.role,
+             m.timestamp,
+             NULLIF(sa.alias, '') AS alias
+      FROM messages_fts
+      JOIN messages m ON m.rowid = messages_fts.rowid
+      JOIN sessions s ON s.id = m.session_id
+      JOIN projects p ON p.id = s.project_id
+      LEFT JOIN session_aliases sa ON sa.session_id = s.id
+      WHERE messages_fts MATCH @fts
+    `;
+        const params = { fts, limit };
+        if (project) {
+            sql += ' AND (p.name LIKE @proj OR p.decoded_path LIKE @proj)';
+            params.proj = `%${project}%`;
+        }
+        tagTokens.forEach((tag, i) => {
+            sql += ` AND s.id IN (SELECT session_id FROM session_tags WHERE tag = @tag_${i})`;
+            params[`tag_${i}`] = tag;
+        });
+        sql += ' ORDER BY bm25(messages_fts) LIMIT @limit';
+        const rows = db.prepare(sql).all(params);
+        const ftsHits = rows.map((r) => ({
+            ...r,
+            matched_via: 'fts',
+        }));
+        const mode = c.req.query('mode');
+        if (mode !== 'semantic') {
+            return c.json({ query: q, hits: ftsHits, tags: tagTokens });
+        }
+        // v0.11 — semantic mode: run sessions_fts over (summary, keywords).
+        let semanticRows = [];
+        try {
+            let semSql = `
+        SELECT s.id            AS session_id,
+               s.id             AS message_uuid,
+               p.name           AS project,
+               s.started_at,
+               COALESCE(NULLIF(ss.summary, ''), s.first_user_message, '') AS snippet,
+               CAST(NULL AS TEXT) AS role,
+               CAST(NULL AS TEXT) AS timestamp,
+               NULLIF(sa.alias, '') AS alias,
+               bm25(sessions_fts) AS rank
+        FROM sessions_fts
+        JOIN session_semantic ss ON ss.rowid = sessions_fts.rowid
+        JOIN sessions s ON s.id = ss.session_id
+        JOIN projects p ON p.id = s.project_id
+        LEFT JOIN session_aliases sa ON sa.session_id = s.id
+        WHERE sessions_fts MATCH @fts
+      `;
+            const semParams = { fts, limit };
+            if (project) {
+                semSql += ' AND (p.name LIKE @proj OR p.decoded_path LIKE @proj)';
+                semParams.proj = `%${project}%`;
+            }
+            tagTokens.forEach((tag, i) => {
+                semSql += ` AND s.id IN (SELECT session_id FROM session_tags WHERE tag = @tag_${i})`;
+                semParams[`tag_${i}`] = tag;
+            });
+            semSql += ' ORDER BY rank LIMIT @limit';
+            semanticRows = db.prepare(semSql).all(semParams);
+        }
+        catch (err) {
+            console.error('[search.semantic] failed:', err);
+        }
+        // v0.7 — vector lane via RRF fusion when embedder is loaded.
+        if (getEmbedderStatus().loaded) {
+            try {
+                const vectorHits = await vectorSearch(q, limit);
+                const bm25Lane = ftsHits.map((h) => ({
+                    id: String(h.session_id),
+                    data: h,
+                    lane: 'bm25',
+                }));
+                const summaryLane = semanticRows.map((r) => ({
+                    id: String(r.session_id),
+                    data: r,
+                    lane: 'summary',
+                }));
+                const vectorLane = vectorHits.map((vh) => ({
+                    id: vh.sessionId,
+                    data: { session_id: vh.sessionId, snippet: vh.text, matched_via: 'vector' },
+                    lane: 'vector',
+                }));
+                const fused = fuseResults([bm25Lane, summaryLane, vectorLane]).slice(0, limit);
+                const hits = fused.map((f) => ({
+                    ...f.data,
+                    session_id: f.id,
+                    rrf_score: f.score,
+                    lanes: f.lanes,
+                    matched_via: f.lanes.length > 1 ? 'fused' : f.lanes[0],
+                }));
+                return c.json({ query: q, hits, tags: tagTokens, mode: 'semantic', fusion: 'rrf' });
+            }
+            catch (err) {
+                console.error('[search.vector] failed, falling back:', err);
+            }
+        }
+        // Fallback: simple merge without vector lane.
+        const seenSessionIds = new Set(ftsHits.map((h) => String(h.session_id)));
+        const semHits = semanticRows
+            .filter((r) => !seenSessionIds.has(String(r.session_id)))
+            .map(({ rank: _rank, ...rest }) => ({
+            ...rest,
+            matched_via: 'semantic',
+        }));
+        const merged = [...ftsHits, ...semHits].slice(0, limit);
+        return c.json({ query: q, hits: merged, tags: tagTokens, mode: 'semantic' });
+    });
+    // Context export — returns markdown ready to paste into a new Claude conversation.
+    app.get('/api/sessions/:id/context', requireProMiddleware, (c) => {
+        const db = getDb();
+        const id = c.req.param('id');
+        const mode = c.req.query('mode') === 'full' ? 'full' : 'condensed';
+        const includeSidechain = c.req.query('subagents') === '1';
+        const prelude = c.req.query('prelude') ?? null;
+        const session = db
+            .prepare(`SELECT s.id, p.name AS project_name, p.decoded_path,
+                s.started_at, s.ended_at, s.message_count, s.git_branch
+         FROM sessions s JOIN projects p ON p.id = s.project_id
+         WHERE s.id = ?`)
+            .get(id);
+        if (!session)
+            return c.json({ error: 'not found' }, 404);
+        const messages = db
+            .prepare(`SELECT uuid, type, role, timestamp, is_sidechain, content_text, tool_names
+         FROM messages
+         WHERE session_id = ?
+         ORDER BY COALESCE(timestamp, ''), rowid`)
+            .all(id);
+        const markdown = formatSessionAsContext(session, messages, {
+            mode,
+            includeSidechain,
+            prelude,
+        });
+        return c.text(markdown);
+    });
+    /**
+     * v0.8 — Collections. User-curated, hierarchical groupings of sessions.
+     * Every mutation runs in a transaction inside `src/utils/collections.ts`,
+     * which also appends to the event log and rewrites the plain-text mirror
+     * at ~/.recall/collections.json. The server here is a thin wrapper.
+     */
+    app.get('/api/collections', (c) => {
+        const includeArchived = c.req.query('archived') === '1';
+        return c.json({ collections: listCollections(includeArchived) });
+    });
+    app.get('/api/collections/:id', (c) => {
+        const id = c.req.param('id');
+        const col = getCollection(id);
+        if (!col)
+            return c.json({ error: 'not found' }, 404);
+        const members = sessionsInCollection(id, /* includeDescendants */ true);
+        return c.json({ collection: col, members });
+    });
+    app.post('/api/collections', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.name !== 'string') {
+            return c.json({ error: 'name required' }, 400);
+        }
+        try {
+            const row = createCollection({
+                name: body.name,
+                description: body.description ?? null,
+                icon: body.icon ?? null,
+                color: body.color ?? null,
+                parent_id: body.parent_id ?? null,
+                sort_key: body.sort_key,
+            });
+            return c.json(row, 201);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.patch('/api/collections/:id', async (c) => {
+        const id = c.req.param('id');
+        const body = (await c.req.json().catch(() => null));
+        if (!body)
+            return c.json({ error: 'body required' }, 400);
+        try {
+            const row = patchCollection(id, body);
+            return c.json(row);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.post('/api/collections/:id/archive', (c) => {
+        const id = c.req.param('id');
+        try {
+            const row = archiveCollection(id);
+            return c.json(row);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 404);
+        }
+    });
+    app.post('/api/collections/:id/restore', (c) => {
+        const id = c.req.param('id');
+        try {
+            const row = restoreCollection(id);
+            return c.json(row);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 404);
+        }
+    });
+    app.post('/api/collections/:id/members', async (c) => {
+        const id = c.req.param('id');
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.session_id !== 'string') {
+            return c.json({ error: 'session_id required' }, 400);
+        }
+        try {
+            const result = addSessionToCollection(id, body.session_id, body.note ?? null);
+            return c.json(result);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.delete('/api/collections/:id/members/:sid', (c) => {
+        const id = c.req.param('id');
+        const sid = c.req.param('sid');
+        try {
+            const result = removeSessionFromCollection(id, sid);
+            return c.json(result);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.get('/api/sessions/:id/collections', (c) => {
+        const id = c.req.param('id');
+        return c.json({ collections: collectionsForSession(id) });
+    });
+    /**
+     * v0.15 T6 — Auto-collections. Rules bind (type, pattern) pairs to
+     * target collections; suggestions propose new rules for clusters the
+     * daemon spots in the corpus. Every mutation is wrapped by the util
+     * layer's transaction + JSON mirror, so the server is a thin shell.
+     */
+    const AUTO_RULE_TYPES = [
+        'cwd-prefix',
+        'project-id',
+        'tag',
+        'plan-file',
+        'git-branch-prefix',
+    ];
+    app.get('/api/auto-collections/rules', (c) => c.json({ rules: listAutoRules() }));
+    app.post('/api/auto-collections/rules', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (!body ||
+            typeof body.name !== 'string' ||
+            typeof body.pattern !== 'string' ||
+            !body.type ||
+            !AUTO_RULE_TYPES.includes(body.type)) {
+            return c.json({ error: 'name, type, pattern required (type must be a known matcher)' }, 400);
+        }
+        try {
+            const rule = createAutoRule({
+                name: body.name,
+                type: body.type,
+                pattern: body.pattern,
+                collection_id: body.collection_id,
+                parent_collection_id: body.parent_collection_id,
+                priority: body.priority,
+                enabled: body.enabled,
+            });
+            return c.json(rule, 201);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.patch('/api/auto-collections/rules/:id', async (c) => {
+        const id = c.req.param('id');
+        const body = (await c.req.json().catch(() => null));
+        if (!body)
+            return c.json({ error: 'body required' }, 400);
+        try {
+            const rule = patchAutoRule(id, body);
+            return c.json(rule);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.delete('/api/auto-collections/rules/:id', (c) => {
+        const id = c.req.param('id');
+        try {
+            const result = deleteAutoRule(id);
+            return c.json(result);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.get('/api/auto-collections/suggestions', (c) => {
+        const includeDismissed = c.req.query('dismissed') === '1';
+        return c.json({
+            suggestions: listAutoSuggestions({ includeDismissed }),
+        });
+    });
+    app.post('/api/auto-collections/suggestions/:id/accept', (c) => {
+        const id = c.req.param('id');
+        try {
+            const rule = acceptAutoSuggestion(id);
+            return c.json({ rule });
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.post('/api/auto-collections/suggestions/:id/dismiss', (c) => {
+        const id = c.req.param('id');
+        try {
+            dismissAutoSuggestion(id);
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.post('/api/auto-collections/detect', (c) => {
+        // Manual re-scan — surfaced in the UI for users who don't want to wait
+        // for the 6h background pass.
+        const suggestions = detectAutoSuggestions();
+        return c.json({ suggestions });
+    });
+    app.get('/api/auto-collections/suggestions/:id/preview', (c) => {
+        const id = c.req.param('id');
+        const limit = Math.max(1, Math.min(20, Number(c.req.query('limit')) || 3));
+        const all = listAutoSuggestions({ includeDismissed: false });
+        const match = all.find((s) => s.id === id);
+        if (!match)
+            return c.json({ error: 'suggestion not found' }, 404);
+        const sessions = previewAutoSuggestion(match.type, match.pattern, limit);
+        return c.json({ sessions });
+    });
+    app.get('/api/auto-collections/parents', (c) => {
+        // Lightweight helper for the UI: which collection ids are auto-managed?
+        const ids = Array.from(autoCollectionIdSet());
+        return c.json({ auto_collection_ids: ids });
+    });
+    // v0.15 Threads — intent-grouping DAG. See src/utils/threads.ts.
+    app.get('/api/threads', (c) => {
+        const includeArchived = c.req.query('archived') === '1';
+        return c.json({ threads: listThreads({ includeArchived }) });
+    });
+    app.get('/api/threads/:id', (c) => {
+        const id = c.req.param('id');
+        const detail = getThread(id);
+        if (!detail)
+            return c.json({ error: 'thread not found' }, 404);
+        // Enrich each edge with alias_source from the terminal registry. The DB
+        // doesn't persist this — it's derived at request time the same way as the
+        // sessions list endpoint, so the graph applies the same display precedence
+        // (agent ✨ title > manual alias > heuristic title > auto-alias).
+        const edges = detail.edges.map((e) => ({
+            ...e,
+            alias_source: e.alias == null
+                ? null
+                : terminalRegistry.isSessionAutoLinked(e.session_id)
+                    ? 'auto'
+                    : 'manual',
+        }));
+        return c.json({ thread: { ...detail, edges } });
+    });
+    app.post('/api/threads', async (c) => {
+        const body = (await c.req.json().catch(() => ({})));
+        if (!body.name)
+            return c.json({ error: 'name required' }, 400);
+        try {
+            const thread = createThread({
+                name: body.name,
+                summary: body.summary ?? null,
+                originSessionId: body.originSessionId,
+            });
+            return c.json({ thread });
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.patch('/api/threads/:id', async (c) => {
+        const id = c.req.param('id');
+        const body = (await c.req.json().catch(() => ({})));
+        try {
+            if (body.name)
+                renameThread(id, body.name);
+            if (body.close)
+                closeThread(id);
+            if (body.reopen)
+                reopenThread(id);
+            if (body.archive)
+                archiveThread(id);
+            const detail = getThread(id);
+            if (!detail)
+                return c.json({ error: 'thread not found' }, 404);
+            return c.json({ thread: detail });
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.post('/api/threads/:id/sessions', async (c) => {
+        const threadId = c.req.param('id');
+        const body = (await c.req.json().catch(() => ({})));
+        if (!body.sessionId)
+            return c.json({ error: 'sessionId required' }, 400);
+        try {
+            const edge = addSessionToThread({
+                threadId,
+                sessionId: body.sessionId,
+                parentSessionId: body.parentSessionId ?? null,
+                role: body.role,
+            });
+            return c.json({ edge });
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.delete('/api/threads/:id/sessions/:sessionId', (c) => {
+        const threadId = c.req.param('id');
+        const sessionId = c.req.param('sessionId');
+        const result = removeSessionFromThread(threadId, sessionId);
+        return c.json(result);
+    });
+    app.patch('/api/threads/:id/sessions/:sessionId', async (c) => {
+        const threadId = c.req.param('id');
+        const sessionId = c.req.param('sessionId');
+        const body = (await c.req.json().catch(() => ({})));
+        try {
+            const edge = setParent(threadId, sessionId, body.parentSessionId ?? null);
+            return c.json({ edge });
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.post('/api/threads/:id/merge', async (c) => {
+        const destId = c.req.param('id');
+        const body = (await c.req.json().catch(() => ({})));
+        if (!body.sourceId)
+            return c.json({ error: 'sourceId required' }, 400);
+        try {
+            const detail = mergeThreads(body.sourceId, destId);
+            return c.json({ thread: detail });
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.post('/api/threads/:id/split', async (c) => {
+        const threadId = c.req.param('id');
+        const body = (await c.req.json().catch(() => ({})));
+        if (!body.sessionIds?.length || !body.newThreadName) {
+            return c.json({ error: 'sessionIds and newThreadName required' }, 400);
+        }
+        try {
+            const detail = splitThread({
+                threadId,
+                sessionIds: body.sessionIds,
+                newThreadName: body.newThreadName,
+            });
+            return c.json({ thread: detail });
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.get('/api/sessions/:id/threads', (c) => {
+        const sessionId = c.req.param('id');
+        return c.json({ threads: threadsForSession(sessionId) });
+    });
+    /**
+     * v0.7 Bucket 5: bulk thread title generation.
+     *
+     * POST /api/threads/:id/titles/generate kicks off a detached walk and
+     * returns {jobId} immediately. The client then opens an SSE stream on
+     * /api/jobs/:jobId/stream to follow progress, or DELETEs the job to cancel.
+     *
+     * Pre-flight count: when the client asks for `?count=1` (or POST body
+     * { count: true }) we return the number of sessions in the thread that
+     * already have an agent-sourced title so the UI can render the
+     * "skip already-titled vs regenerate all" choice. No job is started.
+     */
+    app.get('/api/threads/:id/titles/preflight', (c) => {
+        const threadId = c.req.param('id');
+        const detail = getThread(threadId);
+        if (!detail)
+            return c.json({ error: 'thread not found' }, 404);
+        const db = getDb();
+        let alreadyTitled = 0;
+        for (const e of detail.edges) {
+            const row = db
+                .prepare(`SELECT auto_title_source FROM sessions WHERE id = ?`)
+                .get(e.session_id);
+            if (row?.auto_title_source === 'agent')
+                alreadyTitled += 1;
+        }
+        return c.json({
+            total: detail.edges.length,
+            alreadyTitled,
+            untitled: detail.edges.length - alreadyTitled,
+        });
+    });
+    app.post('/api/threads/:id/titles/generate', async (c) => {
+        const threadId = c.req.param('id');
+        const body = (await c.req.json().catch(() => ({})));
+        const detail = getThread(threadId);
+        if (!detail)
+            return c.json({ error: 'thread not found' }, 404);
+        if (detail.edges.length === 0) {
+            return c.json({ error: 'thread has no sessions' }, 400);
+        }
+        // BUCKET 6 INTEGRATION POINT: model resolution. Today we read the user's
+        // auto-tag model preference if no explicit override is supplied. Bucket 6
+        // will replace this with a richer engine-config lookup keyed off feature
+        // (autoTitle vs autoTag vs others) so different features can route to
+        // different models from a single source of truth.
+        const cfg = readAutoTagConfig();
+        const model = body.model ?? cfg.model;
+        const jobId = startBulkTitleJob({
+            threadId,
+            force: body.force ?? false,
+            model,
+        });
+        return c.json({ jobId });
+    });
+    app.get('/api/jobs/:jobId/stream', (c) => {
+        const jobId = c.req.param('jobId');
+        const snap = getJobSnapshot(jobId);
+        if (!snap)
+            return c.json({ error: 'job not found' }, 404);
+        // Standard SSE resume: client sends Last-Event-ID to pick up where it
+        // left off. Hono passes the header through; we coerce to a number so the
+        // generator can skip already-emitted events.
+        const lastEventId = Number(c.req.header('Last-Event-ID') ?? 0);
+        return streamSSE(c, async (stream) => {
+            let closed = false;
+            const heartbeat = setInterval(() => {
+                if (closed)
+                    return;
+                stream.writeSSE({ event: 'heartbeat', data: '' }).catch(() => {
+                    closed = true;
+                });
+            }, 15_000);
+            try {
+                for await (const ev of subscribeJob(jobId, lastEventId)) {
+                    if (closed)
+                        break;
+                    await stream.writeSSE({
+                        id: String(ev.id),
+                        event: ev.kind,
+                        data: JSON.stringify(ev.data),
+                    });
+                    if (ev.kind === 'done')
+                        break;
+                }
+            }
+            finally {
+                closed = true;
+                clearInterval(heartbeat);
+            }
+        });
+    });
+    app.get('/api/jobs/:jobId', (c) => {
+        const snap = getJobSnapshot(c.req.param('jobId'));
+        if (!snap)
+            return c.json({ error: 'job not found' }, 404);
+        return c.json(snap);
+    });
+    app.delete('/api/jobs/:jobId', (c) => {
+        const ok = cancelJob(c.req.param('jobId'));
+        if (!ok)
+            return c.json({ error: 'job not found or already done' }, 404);
+        return c.json({ ok: true });
+    });
+    /**
+     * v0.7 - Terminal registry endpoints for the VS Code extension.
+     *
+     * The extension POSTs these when the user's VS Code terminals open, get
+     * renamed, or close. We store the mapping shell_pid → tab_name in memory
+     * so the correlator (see watcher.ts — landing in v0.7.1) can auto-alias
+     * new Claude Code sessions with the tab name they were started in.
+     *
+     * All three endpoints accept small JSON bodies and return `{ ok: true,
+     * count }`. They never read or write anything outside the in-memory map.
+     */
+    app.post('/api/terminal/opened', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.shell_pid !== 'number' || typeof body.tab_name !== 'string') {
+            return c.json({ error: 'shell_pid and tab_name required' }, 400);
+        }
+        const entry = terminalRegistry.upsert({
+            shell_pid: body.shell_pid,
+            tab_name: body.tab_name,
+            cwd: body.cwd ?? null,
+            opened_at: body.opened_at ?? new Date().toISOString(),
+        });
+        return c.json({ ok: true, count: terminalRegistry.size(), entry });
+    });
+    app.post('/api/terminal/renamed', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.shell_pid !== 'number' || typeof body.tab_name !== 'string') {
+            return c.json({ error: 'shell_pid and tab_name required' }, 400);
+        }
+        const entry = terminalRegistry.rename(body.shell_pid, body.tab_name);
+        if (!entry)
+            return c.json({ error: 'unknown shell_pid' }, 404);
+        const propagated = propagateRenameToSessions(body.shell_pid, body.tab_name);
+        return c.json({ ok: true, entry, propagated });
+    });
+    app.post('/api/terminal/closed', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.shell_pid !== 'number') {
+            return c.json({ error: 'shell_pid required' }, 400);
+        }
+        const removed = terminalRegistry.remove(body.shell_pid);
+        return c.json({ ok: true, removed, count: terminalRegistry.size() });
+    });
+    /**
+     * Deterministic-link breadcrumb. The VS Code extension fires
+     * `onDidStartTerminalShellExecution` when the user runs `claude` and POSTs
+     * the (shell_pid, tab_name, cwd, started_at) tuple here. The correlator
+     * drains the most recent matching cwd within ~30s of the JSONL appearing
+     * on disk. This replaces the lsof + ppid-walk guesswork that previously
+     * mis-linked sessions to sibling terminals' shell_pids.
+     */
+    app.post('/api/terminal/claude-started', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (!body || typeof body.shell_pid !== 'number') {
+            return c.json({ error: 'shell_pid required' }, 400);
+        }
+        terminalRegistry.pushPending({
+            shell_pid: body.shell_pid,
+            tab_name: typeof body.tab_name === 'string' ? body.tab_name : '',
+            cwd: typeof body.cwd === 'string' ? body.cwd : null,
+            started_at: typeof body.started_at === 'string' ? body.started_at : new Date().toISOString(),
+        });
+        return c.json({ ok: true, pending: terminalRegistry.pendingSize() });
+    });
+    /**
+     * Full-snapshot reconcile. The extension sends the complete list of open
+     * terminals on a polling loop (every few seconds). The registry replaces
+     * itself with this list and, for any shell_pid whose tab_name changed,
+     * propagates the new name to every session that started in that shell —
+     * so a rename in VS Code shows up as the session alias in Claude Recall
+     * without any manual step.
+     */
+    app.post('/api/terminal/sync', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (!body || !Array.isArray(body.terminals)) {
+            return c.json({ error: 'terminals array required' }, 400);
+        }
+        // Capture previous tab names so we can detect renames post-reconcile.
+        const previous = new Map();
+        for (const t of terminalRegistry.all())
+            previous.set(t.shell_pid, t.tab_name);
+        const snapshot = body.terminals
+            .filter((t) => !!t && typeof t.shell_pid === 'number' && typeof t.tab_name === 'string')
+            .map((t) => ({
+            shell_pid: t.shell_pid,
+            tab_name: t.tab_name,
+            cwd: t.cwd ?? null,
+            opened_at: t.opened_at ?? new Date().toISOString(),
+        }));
+        const diff = terminalRegistry.sync(snapshot);
+        // Propagate any rename we see. The registry may reject a Claude Code
+        // auto-title for storage purposes (to keep a user-set name pinned), but
+        // for PROPAGATION we want to consider both: the registry's stored name
+        // (good when the user typed a real name) AND the raw incoming name
+        // (good when Claude generated a session title that strips to clean).
+        // propagateRenameToSessions handles the strip + clean check.
+        let propagatedTotal = 0;
+        for (const t of snapshot) {
+            const prev = previous.get(t.shell_pid);
+            const stored = terminalRegistry.get(t.shell_pid)?.tab_name ?? t.tab_name;
+            // Pick the candidate most likely to produce a useful alias: the stored
+            // name when it's a real user-typed name, otherwise the raw incoming
+            // (which propagation will strip if it's a Claude auto-title).
+            const storedLooksClean = !!stored && !isGenericShellName(stored) && !looksLikeClaudeAutoTitle(stored);
+            const candidate = storedLooksClean ? stored : t.tab_name;
+            if (prev !== undefined && prev !== candidate) {
+                propagatedTotal += propagateRenameToSessions(t.shell_pid, candidate);
+            }
+        }
+        return c.json({
+            ok: true,
+            count: terminalRegistry.size(),
+            diff,
+            propagated: propagatedTotal,
+        });
+    });
+    app.get('/api/terminal/registry', (c) => {
+        return c.json({
+            terminals: terminalRegistry.all(),
+            count: terminalRegistry.size(),
+        });
+    });
+    /**
+     * Force-rerun the correlator for a single session. Unlinks any existing
+     * shell-pid association, clears the auto alias, and calls tryAutoAlias
+     * again so the session picks up the current registry state. Intended for
+     * sessions that were aliased under an old correlator version, or when a
+     * user has opened a fresh terminal AFTER the session was indexed and
+     * wants the alias tied to that new terminal.
+     */
+    app.post('/api/sessions/:id/recorrelate', async (c) => {
+        const id = c.req.param('id');
+        const row = getDb()
+            .prepare('SELECT file_path FROM sessions WHERE id = ?')
+            .get(id);
+        if (!row?.file_path)
+            return c.json({ error: 'session not found' }, 404);
+        terminalRegistry.unlinkSession(id);
+        clearAlias(id);
+        await tryAutoAlias(row.file_path);
+        const newAlias = getAlias(id);
+        return c.json({
+            ok: true,
+            alias: newAlias,
+            linked_pid: terminalRegistry
+                .all()
+                .find((t) => terminalRegistry.sessionsFor(t.shell_pid).includes(id))
+                ?.shell_pid ?? null,
+        });
+    });
+    /**
+     * v0.4.5 — Paste expand.
+     * A message whose content is `[Pasted text #N +L lines] <path>` stores only
+     * a placeholder. This endpoint attempts two recoveries:
+     *   1. Scan the *next* ~10 messages in the same session for a Read tool
+     *      result that contains the path — if found, return that content.
+     *   2. Fall back to reading the file from disk.
+     *
+     * Security: we refuse any path that doesn't appear in an actual paste
+     * placeholder in an indexed message in this session. This is an
+     * "allowlist via observation" — we only serve files the user themselves
+     * already referenced in a prior session.
+     */
+    app.get('/api/paste-expand', async (c) => {
+        const sessionId = c.req.query('session');
+        const messageUuid = c.req.query('message');
+        const path = c.req.query('path');
+        if (!sessionId || !messageUuid || !path) {
+            return c.json({ error: 'session, message and path are required' }, 400);
+        }
+        const db = getDb();
+        const msg = db
+            .prepare('SELECT rowid, content_text FROM messages WHERE uuid = ? AND session_id = ?')
+            .get(messageUuid, sessionId);
+        if (!msg)
+            return c.json({ error: 'message not found in session' }, 404);
+        // The placeholder pattern. Path must be literally in the content.
+        const escaped = path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const allowlistRe = new RegExp(`\\[Pasted text #\\d+ \\+\\d+ lines\\]\\s*${escaped}`);
+        if (!allowlistRe.test(msg.content_text ?? '')) {
+            return c.json({ error: 'path not referenced by this message' }, 403);
+        }
+        // 1) search next messages for a Read tool result containing this file's content
+        const nearby = db
+            .prepare(`SELECT content_text FROM messages
+         WHERE session_id = ? AND rowid > ?
+         ORDER BY rowid ASC LIMIT 10`)
+            .all(sessionId, msg.rowid);
+        for (const m of nearby) {
+            const body = m.content_text ?? '';
+            // Tool results are rendered with a "**Tool result**\n```\n…\n```" wrapper.
+            if (body.includes('**Tool result**') && body.includes(path)) {
+                return c.json({ source: 'tool-result', content: body });
+            }
+            // Some Read results are numbered-line format; also accept heuristic match.
+            if (/^\s*1\t/.test(body) && body.length > 200) {
+                return c.json({ source: 'tool-result', content: body });
+            }
+        }
+        // 2) fall back to disk read, bounded at 2 MB.
+        //
+        // Path-traversal defense: even though the allowlist regex above ensures
+        // the path appears in an indexed paste placeholder, a crafted session
+        // message could contain `../../etc/passwd`. Resolve with realpath() (so
+        // symlinks are followed to their real target) then require the resolved
+        // path to live under $HOME. That contains the blast radius to the user's
+        // own files — never /etc, /var, another user's home, etc.
+        try {
+            const real = await realpath(path);
+            const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+            if (!home || (!real.startsWith(home + '/') && !real.startsWith(home + '\\'))) {
+                return c.json({ error: 'path outside allowed root' }, 403);
+            }
+            const st = await stat(real);
+            const MAX = 2 * 1024 * 1024;
+            if (st.size > MAX) {
+                return c.json({ error: 'file too large', size: st.size, max: MAX }, 413);
+            }
+            const content = await readFile(real, 'utf8');
+            return c.json({ source: 'disk', content });
+        }
+        catch (err) {
+            return c.json({ source: 'missing', error: err.message });
+        }
+    });
+    // Per-project stats — for the "project summary" card above the sessions list.
+    app.get('/api/projects/:name/stats', (c) => {
+        const db = getDb();
+        const name = c.req.param('name');
+        const summary = db
+            .prepare(`SELECT
+           (SELECT COUNT(*) FROM sessions s JOIN projects p ON p.id=s.project_id WHERE p.name=? AND s.message_count > 2) AS sessions,
+           (SELECT COALESCE(SUM(s.message_count), 0) FROM sessions s JOIN projects p ON p.id=s.project_id WHERE p.name=?) AS messages,
+           (SELECT MIN(s.started_at) FROM sessions s JOIN projects p ON p.id=s.project_id WHERE p.name=? AND s.started_at IS NOT NULL) AS earliest,
+           (SELECT MAX(COALESCE(s.ended_at, s.started_at)) FROM sessions s JOIN projects p ON p.id=s.project_id WHERE (s.ended_at IS NOT NULL OR s.started_at IS NOT NULL) AND p.name=?) AS latest`)
+            .get(name, name, name, name);
+        const branches = db
+            .prepare(`SELECT DISTINCT s.git_branch FROM sessions s
+         JOIN projects p ON p.id = s.project_id
+         WHERE p.name = ? AND s.git_branch IS NOT NULL
+         ORDER BY s.git_branch
+         LIMIT 20`)
+            .all(name)
+            .map((r) => r.git_branch);
+        return c.json({ ...summary, branches });
+    });
+    // --- Static UI ---
+    if (HAS_BUNDLED_UI) {
+        app.use('/assets/*', serveStatic({ root: DIST_WEB }));
+        app.get('/favicon.svg', serveStatic({ root: DIST_WEB }));
+        // The HTML itself must NEVER cache — it's what references the
+        // hashed JS/CSS bundles. If the HTML caches, the browser keeps
+        // asking for a stale bundle hash even after rebuilds.
+        app.get('/', (c) => {
+            c.header('cache-control', 'no-cache, no-store, must-revalidate');
+            c.header('pragma', 'no-cache');
+            c.header('expires', '0');
+            return c.html(readFileSync(INDEX_HTML, 'utf8'));
+        });
+        app.get('*', (c) => {
+            if (c.req.path.startsWith('/api/'))
+                return c.notFound();
+            c.header('cache-control', 'no-cache, no-store, must-revalidate');
+            c.header('pragma', 'no-cache');
+            c.header('expires', '0');
+            return c.html(readFileSync(INDEX_HTML, 'utf8'));
+        });
+    }
+    else {
+        app.get('/', (c) => {
+            const stats = readStats();
+            return c.html(placeholderHtml({
+                projects: stats.projects,
+                sessions: stats.sessions,
+                messages: stats.messages,
+                port: Number(c.req.raw.headers.get('host')?.split(':')[1] ?? 0),
+                version: VERSION,
+            }));
+        });
+    }
+    return app;
+}
+export async function startServer(port) {
+    const app = buildApp();
+    return new Promise((resolve, reject) => {
+        try {
+            const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, () => {
+                // Kick autopilot once on boot. No-op unless the user has already
+                // enabled it + set an API key. Idempotent — kickAutopilot guards
+                // against double-starts internally.
+                void kickAutopilot();
+                // v0.14b (T5) — one-time heuristic backfill. Cheap (SQL NULL check
+                // makes repeat boots a no-op after the first fill), so we just run
+                // it every startup instead of tracking a "has-run" flag.
+                if (readAutoTitleConfig().heuristicEnabled) {
+                    try {
+                        const { updated } = backfillHeuristicTitles();
+                        if (updated > 0) {
+                            console.log(`[auto-title] backfilled heuristic title on ${updated} sessions`);
+                        }
+                    }
+                    catch (err) {
+                        console.error('[auto-title] backfill failed:', err);
+                    }
+                }
+                resolve(server);
+            });
+        }
+        catch (err) {
+            reject(err);
+        }
+    });
+}
+//# sourceMappingURL=server.js.map