aihand 0.0.1 → 0.1.1

package/src/ui/server/plugin.ts

@@ -0,0 +1,1151 @@
+import type { Plugin, ViteDevServer } from 'vite'
+import type { ActionArgs, ActionResult } from '../core/action'
+import type { ActionEntry, ErrorEntry, LogEntry, NetworkRequest, PerformanceData, RawState, ScreenSnap, TabInfo } from '../core/types'
+import { Buffer } from 'node:buffer'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { transformSync } from 'esbuild'
+import { sourceLocPlugin } from '../babel/source-loc'
+import { viteBridge } from '../bridge/vite-bridge'
+import { misroutedAction, resolveAction, TYPES } from '../core/action'
+import { check } from '../core/check'
+import { compact } from '../core/compact'
+import { detail } from '../core/detail'
+import { diffScreen, diffState } from '../core/diff'
+import { emit, emitCheck, emitDiff, emitSummary } from '../core/emit'
+import { diffPerformance } from '../core/perf'
+import { appendAction, diagnose as diagnoseConn, formatActions, formatTabs, isLive } from '../core/util'
+import { argsFromQuery, dispatchAction, dispatchScreen, isDispatchAction, runChain } from './dispatch'
+import type { ChainStep } from './dispatch'
+import { helpText } from './help-text'
+
+function readBody(req: { on: (e: string, cb: (c: unknown) => void) => void }): Promise<string> {
+    return new Promise((resolve) => {
+        let s = ''
+        req.on('data', c => s += c)
+        req.on('end', () => resolve(s))
+    })
+}
+
+// 所有端点都回文本响应——writeHead(Content-Type) + end 二连写了 15 遍（且有 2 处漏 charset）。收敛成一处。
+function send(res: { writeHead: (s: number, h: Record<string, string>) => void, end: (b: string) => void }, status: number, body: string) {
+    res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' })
+    res.end(body)
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+// client/core sources are read at runtime (client.ts served via Vite transform,
+// client-patch.ts compiled by esbuild). aihand fuses ui under src/ui/, so:
+//   source consumption: __dirname=src/ui/server → ../client (= src/ui/client)
+//   published package:   __dirname=dist         → ../src/ui/client
+// First existing dir wins.
+const clientDir = [
+    resolve(__dirname, '../client'),
+    resolve(__dirname, '../src/ui/client'),
+].find(existsSync) ?? resolve(__dirname, '../src/ui/client')
+const clientPath = resolve(clientDir, 'client.ts')
+const patchPath = resolve(clientDir, 'client-patch.ts')
+
+// Compile patch code to JS at plugin init (synchronous, runs once)
+function compilePatch(): string {
+    const source = readFileSync(patchPath, 'utf-8')
+    const result = transformSync(source, {
+        loader: 'ts',
+        target: 'es2020',
+        format: 'iife',
+        minify: false,
+    })
+    return result.code
+}
+
+// The enriched /screen reply: rendered text for display + structured snap & buffers so the
+// server can diff one read against an earlier one for /screen?since=<token>.
+interface ScreenReply { screen: string, canvas: string, snap: ScreenSnap, console: LogEntry[], network: NetworkRequest[], errors: ErrorEntry[] }
+
+// Source-location injection: a `pre`-enforced transform that stamps `data-insp-path` onto
+// every host JSX element so the client can map a DOM node back to its source. Isolated in its own
+// plugin so it touches only .jsx/.tsx (and only at serve time) — the main aihand plugin's HTTP
+// /HMR machinery is untouched. babel is loaded lazily (it's external; a top-level import would
+// pull it into both bundle formats and break the dual-format contract).
+function sourceInjectPlugin(): Plugin {
+    let babel: typeof import('@babel/core') | null = null
+    let plugin: import('@babel/core').PluginObj | null = null
+    let root = ''
+    return {
+        name: 'aihand:source-loc',
+        apply: 'serve',
+        enforce: 'pre',
+        async configResolved(config) {
+            root = config.root
+        },
+        async transform(code, id) {
+            const file = id.split('?')[0]
+            if (!file.endsWith('.tsx') && !file.endsWith('.jsx'))
+                return
+            if (file.includes('node_modules') || file.includes('packages/aidev/'))
+                return
+            if (!babel) {
+                babel = await import('@babel/core')
+                plugin = sourceLocPlugin(babel.types)
+            }
+            const result = await babel.transformAsync(code, {
+                filename: file,
+                root,
+                plugins: [plugin!],
+                parserOpts: { plugins: ['jsx', 'typescript'] },
+                sourceMaps: true,
+                configFile: false,
+                babelrc: false,
+            })
+            if (!result?.code)
+                return
+            return { code: result.code, map: result.map }
+        },
+    }
+}
+
+export function aihandPlugin(): Plugin[] {
+    return [aihandMainPlugin(), sourceInjectPlugin()]
+}
+
+function aihandMainPlugin(): Plugin {
+    let pendingResolve: ((data: RawState) => void) | null = null
+    let server: ViteDevServer
+    let lastRaw: RawState | null = null
+    let perfBaseline: PerformanceData | null = null // /profile/diff before-snapshot
+    let pushTimer: ReturnType<typeof setTimeout> | undefined
+    const pendingActions = new Map<number, (r: ActionResult) => void>()
+    // An async flow (send a message → stream → done) legitimately keeps a mutating action open for
+    // seconds while the client samples the trajectory. The client pings `aihand:action-progress`
+    // each frame; we stamp the latest ping here so twoPhase's live-tab deadline counts from the last
+    // sign of life, not from dispatch — a real hung handler still rejects (no pings → deadline fires).
+    const actionProgressAt = new Map<number, number>()
+    let actionId = 0
+
+    // 融合反向态射的运行时半边:/source 把点中的 DOM 坐标缝回静态符号(FUSION §4)。
+    // CallGraph 全仓构建 ~1s,/source 是交互路径(人点一下等一下),故惰性建一次 + 文件变更失效,
+    // 不每次重建。运行时态不缓存(易腐,§3),但**静态调用图是 Log 类**——文件没改它不变,缓存安全。
+    let graphCache: import('../../read/graph.js').CallGraph | null = null
+    let graphBuilding: Promise<import('../../read/graph.js').CallGraph> | null = null
+    async function cachedGraph(): Promise<import('../../read/graph.js').CallGraph> {
+        if (graphCache)
+            return graphCache
+        if (!graphBuilding) {
+            graphBuilding = (async () => {
+                const { loadConfig, isTsFile } = await import('../../read/config.js')
+                const { scan } = await import('../../read/scan.js')
+                const { buildCallGraph } = await import('../../read/graph.js')
+                const config = await loadConfig(server.config.root)
+                const g = await buildCallGraph(scan(config).filter(isTsFile))
+                graphCache = g
+                graphBuilding = null
+                return g
+            })()
+        }
+        return graphBuilding
+    }
+
+    // Live-tab roster. Every reply carries the client's tab id; we upsert here so commands
+    // can address one tab (?tab=) and so a multi-tab session reports a "which tab?" list
+    // instead of racing N answers. lastSeen = server-side arrival time (Node clock).
+    const tabs = new Map<string, TabInfo>()
+    function seen(data: { tab?: string, url?: string, title?: string, visible?: boolean }) {
+        if (!data.tab)
+            return
+        const prev = tabs.get(data.tab)
+        tabs.set(data.tab, {
+            id: data.tab,
+            url: data.url ?? prev?.url ?? '',
+            title: data.title ?? prev?.title ?? '',
+            visible: data.visible ?? prev?.visible ?? false,
+            lastSeen: Date.now(),
+        })
+    }
+    const liveTabs = () => [...tabs.values()].filter(t => isLive(t, Date.now()))
+
+    // Bind the pure diagnose() (the single π, in core/util) to live server state. Every
+    // "didn't get an answer" path routes through here — twoPhase rejects, /tabs empty roster,
+    // /profile tab-absent — so the state→action split lives in exactly one tested function.
+    const diagnose = (tab?: string) =>
+        diagnoseConn(tab, [...tabs.values()], Date.now(), server.ws.clients.size, server.config.server.port || 5173)
+
+    // Cross-tab action timeline. Each tab already ships its full action ring inside every
+    // aihand:state reply (the same `actions` the single-tab `recent actions` tail reads); we
+    // merge those into a global ring keyed by tab on each collect — no separate fire-and-forget
+    // report path, no dependency on client-patch (which only reloads on server restart).
+    // GET /timeline interleaves all tabs by ts, so a multi-tab A/B comparison sees who did what.
+    const actionLog: ActionEntry[] = []
+
+    // Self-heal handshake: a process-level id, fresh on every server start. The injected
+    // client-patch polls GET /ping and reloads the page when this id changes — so a full
+    // server restart (which kills the HMR socket the whole action chain rides on) heals
+    // itself instead of stranding the page on "connection lost" until a human hits ⌘R.
+    const BOOT_ID = Date.now().toString(36)
+
+    // Per-tab head-eviction count, reported by the client (its 30-entry ring drops the oldest
+    // between collects — entries the server never saw). Monotonic, so the latest report wins.
+    // Summed at /timeline read so a clipped causal chain announces the clip (diagnostic-fiber law).
+    const droppedByTab = new Map<string, number>()
+    const mergeActions = (tab: string | undefined, actions?: ActionEntry[], dropped?: number) => {
+        if (!tab)
+            return
+        if (typeof dropped === 'number')
+            droppedByTab.set(tab, dropped)
+        if (!actions?.length)
+            return
+        for (const entry of actions) {
+            if (!actionLog.some(e => e.tab === tab && e.ts === entry.ts))
+                appendAction(actionLog, tab, entry, 200)
+        }
+    }
+
+    // Chrome real-input channel: synthetic events can't open a Radix ContextMenu, and the
+    // in-page script can't reach chrome.debugger. So for a plain browser tab, realclick is a
+    // two-step handshake — the page resolves the element to (x,y), then the server enqueues a
+    // CDP command here for the extension to execute with trusted input. The extension long-polls
+    // /cdp/poll for the next command and POSTs the verdict to /cdp/result. Electron never touches
+    // this (it fires sendInputEvent in-process from the page — see client.ts).
+    interface CdpCommand { id: number, x: number, y: number, button: 'left' | 'right' }
+    const cdpQueue: CdpCommand[] = []
+    let cdpWaiter: ((cmd: CdpCommand | null) => void) | null = null
+    const cdpResults = new Map<number, (r: { ok: boolean, error?: string }) => void>()
+    let cdpId = 0
+
+    function runCdpClick(x: number, y: number, button: 'left' | 'right'): Promise<{ ok: boolean, error?: string }> {
+        const id = ++cdpId
+        const cmd: CdpCommand = { id, x, y, button }
+        return new Promise((resolve, reject) => {
+            cdpResults.set(id, resolve)
+            // hand the command to a parked poller, else queue it for the next poll
+            if (cdpWaiter) {
+                cdpWaiter(cmd)
+                cdpWaiter = null
+            }
+            else {
+                cdpQueue.push(cmd)
+            }
+            setTimeout(() => {
+                if (cdpResults.delete(id))
+                    reject(new Error('cdp timeout: no extension result within 10s (is the aihand extension loaded and the debugger attached?)'))
+            }, 10000)
+        })
+    }
+
+    let pendingDom: ((dom: string) => void) | null = null
+    let pendingStatePath: ((reply: { ok: boolean, value?: unknown, error?: string }) => void) | null = null
+    let pendingScreen: ((reply: ScreenReply) => void) | null = null
+    const pendingEvals = new Map<number, (r: { ok: boolean, value?: string, error?: string, hint?: string }) => void>()
+    let evalId = 0
+
+    const pendingSemantic = new Map<number, (r: { ok: boolean, value?: string, error?: string }) => void>()
+    let semanticId = 0
+
+    const pendingKnob = new Map<number, (r: { ok: boolean, value?: string, error?: string }) => void>()
+    let knobId = 0
+    const knobProgressAt = new Map<number, number>()
+
+    // /screen?since=<token> diffs the current screen against an earlier one. We stash each
+    // /screen read's structured snap + buffers under a monotonic token; `since` looks the
+    // token up and renders only the transition (diffScreen). Ring-bounded so it can't grow.
+    interface Stash { snap: ScreenSnap, console: LogEntry[], network: NetworkRequest[], errors: ErrorEntry[] }
+    const screenStash = new Map<string, Stash>()
+    let screenToken = 0
+    function stashScreen(r: ScreenReply): string {
+        const token = `t${++screenToken}`
+        screenStash.set(token, { snap: r.snap, console: r.console, network: r.network, errors: r.errors })
+        if (screenStash.size > 32)
+            screenStash.delete(screenStash.keys().next().value!)
+        return token
+    }
+
+    // Multi-tab: round one asks only the visible tab (requireVisible). If no tab is
+    // visible (user reading the terminal), nobody answers within VISIBLE_MS, so round
+    // two drops the guard and any tab replies. `arm` installs the pending slot and
+    // returns a clearer; the slot's resolve settles the promise on either round.
+    const VISIBLE_MS = 400
+    function twoPhase<T>(
+        event: string,
+        payload: Record<string, unknown>,
+        arm: (resolve: (v: T) => void) => () => void,
+        fullMs = 3000,
+        tab?: string,
+        // Optional: latest sign-of-life timestamp for this call (an in-flight flow pings to extend
+        // its own deadline). When set, the live-tab deadline counts from max(startedAt, lastProgress).
+        lastProgress?: () => number | undefined,
+    ): Promise<T> {
+        return new Promise<T>((resolve, reject) => {
+            let settled = false
+            const clear = arm((v) => {
+                settled = true
+                resolve(v)
+            })
+            // Addressed at one tab: skip the requireVisible round entirely — only that tab
+            // answers (skip() matches on tab id), background or not. No visibility race.
+            //
+            // Shortest-path delivery: assume the tab always exists. TAB_ID is sessionStorage-backed
+            // and survives the self-heal location.reload(), so a tab keeps its id across a server
+            // restart — it's the same descendant. Two regimes, split on whether the tab is live now:
+            //   live   → present-but-silent past fullMs is a real miss (bad sel / hung handler) →
+            //            reject fast, exactly as before. Never re-send to a live tab (double-exec hazard).
+            //   absent → server just restarted / page mid self-heal. Keep re-delivering every RETRY_MS
+            //            until it re-registers (self-heal brings it back ~2-4s), bounded by ABSENT_CEILING_MS.
+            // Re-delivery is made idempotent client-side (__AIPEEK_DONE_ACTIONS__ de-dups by action id).
+            if (tab) {
+                const RETRY_MS = 500
+                const ABSENT_CEILING_MS = 10000
+                const startedAt = Date.now()
+                const deliver = () => server.hot.send(event, { ...payload, tab })
+                deliver()
+                const iv = setInterval(() => {
+                    if (settled) {
+                        clearInterval(iv)
+                        return
+                    }
+                    const t = tabs.get(tab)
+                    const live = !!t && isLive(t, Date.now())
+                    const progressAt = lastProgress?.()
+                    const sinceLife = Date.now() - Math.max(startedAt, progressAt ?? 0)
+                    const elapsed = Date.now() - startedAt
+                    if (live) {
+                        if (sinceLife > fullMs) {
+                            clearInterval(iv)
+                            clear()
+                            reject(new Error(diagnose(tab)))
+                        }
+                    }
+                    else if (elapsed > ABSENT_CEILING_MS) {
+                        clearInterval(iv)
+                        clear()
+                        reject(new Error(diagnose(tab)))
+                    }
+                    else {
+                        deliver()
+                    }
+                }, RETRY_MS)
+                return
+            }
+            server.hot.send(event, { ...payload, requireVisible: true })
+            setTimeout(() => {
+                if (settled)
+                    return
+                // no visible tab answered — ask everyone
+                server.hot.send(event, { ...payload, requireVisible: false })
+                setTimeout(() => {
+                    if (settled)
+                        return
+                    clear()
+                    reject(new Error(diagnose(tab)))
+                }, fullMs)
+            }, VISIBLE_MS)
+        })
+    }
+
+    function collectFromClient(tab?: string): Promise<RawState> {
+        return twoPhase<RawState>('aihand:collect', {}, (resolve) => {
+            pendingResolve = resolve
+            return () => {
+                pendingResolve = null
+            }
+        }, 3000, tab)
+    }
+
+    function collectDomFromClient(scope?: string, sel?: string, tab?: string): Promise<string> {
+        return twoPhase<string>('aihand:collect-dom', { scope, sel }, (resolve) => {
+            pendingDom = resolve
+            return () => {
+                pendingDom = null
+            }
+        }, 3000, tab)
+    }
+
+    function collectStatePathFromClient(path: string, tab?: string): Promise<{ ok: boolean, value?: unknown, error?: string }> {
+        return twoPhase('aihand:collect-state-path', { path }, (resolve) => {
+            pendingStatePath = resolve
+            return () => {
+                pendingStatePath = null
+            }
+        }, 3000, tab)
+    }
+
+    function collectScreenFromClient(tab?: string, form?: string): Promise<ScreenReply> {
+        return twoPhase<ScreenReply>('aihand:collect-screen', { form }, (resolve) => {
+            pendingScreen = resolve
+            return () => {
+                pendingScreen = null
+            }
+        }, 3000, tab)
+    }
+
+    function sendAction(type: string, args: ActionArgs, tab?: string): Promise<ActionResult> {
+        const id = ++actionId
+        // wait actions own their timeout; give the channel that long + slack
+        const fullMs = Math.max(args.timeout ?? 0, 3000) + 2000
+        return twoPhase<ActionResult>('aihand:action', { id, type, args }, (resolve) => {
+            pendingActions.set(id, resolve)
+            return () => {
+                pendingActions.delete(id)
+                actionProgressAt.delete(id)
+            }
+        }, fullMs, tab, () => actionProgressAt.get(id))
+    }
+
+    // sendAction + the Chrome realclick handshake, in one place so the single endpoint and
+    // /chain both get it. The page resolves realclick to (x,y): if result.fired, Electron
+    // already fired the trusted click in-process — done. Otherwise (plain Chrome tab) the page
+    // couldn't click, so drive the extension's CDP queue with the coords, then collect the
+    // settled screen. A CDP failure comes back as a normal ok:false result.
+    async function runAction(type: string, args: ActionArgs, tab?: string): Promise<ActionResult> {
+        const result = await sendAction(type, args, tab)
+        lastRaw = null // page mutated; force fresh collect next read
+        if (type === 'realclick' && result.ok && !result.fired) {
+            const cdp = await runCdpClick(result.x!, result.y!, args.button ?? 'left')
+            if (!cdp.ok)
+                return { ok: false, error: `cdp click failed: ${cdp.error ?? 'unknown'}` }
+            result.detail = `${result.detail} → clicked via extension`
+            result.screen = (await collectScreenFromClient(tab)).screen
+        }
+        return result
+    }
+
+    function evalInClient(code: string, tab?: string): Promise<{ ok: boolean, value?: string, error?: string, hint?: string }> {
+        const id = ++evalId
+        return twoPhase('aihand:eval', { id, code }, (resolve) => {
+            pendingEvals.set(id, resolve)
+            return () => {
+                pendingEvals.delete(id)
+            }
+        }, 8000, tab)
+    }
+
+    // The green channel: call a named semantic action the app mounted on __AIHAND_ACTIONS__.
+    // Same twoPhase shape as eval, but the page invokes a declared fn (not arbitrary code) and
+    // returns its delta. The action may kick off an async flow (sendPrompt → stream); give it
+    // the same generous window a streaming /click gets.
+    function semanticInClient(name: string, args: unknown[], tab?: string): Promise<{ ok: boolean, value?: string, error?: string }> {
+        const id = ++semanticId
+        return twoPhase('aihand:semantic-action', { id, name, args }, (resolve) => {
+            pendingSemantic.set(id, resolve)
+            return () => {
+                pendingSemantic.delete(id)
+            }
+        }, 15000, tab)
+    }
+
+    // The god-tier green channel: replay a statically-extracted knob morphism (no hand-mounting).
+    // Server stays dumb — it forwards label+file+value; the browser resolves knob→ops from the
+    // build-time schema (virtual:aihand-knobs) and writes the store directly, then samples the
+    // resulting trajectory (same waitForStable/diffScreen/traceFlow path as /click). The action
+    // may kick off an async flow; pings extend the deadline like a streaming click does.
+    function knobInClient(knob: string, file: string | undefined, value: string | undefined, tab?: string): Promise<{ ok: boolean, value?: string, error?: string }> {
+        const id = ++knobId
+        return twoPhase('aihand:knob-action', { id, knob, file, value }, (resolve) => {
+            pendingKnob.set(id, resolve)
+            return () => {
+                pendingKnob.delete(id)
+                knobProgressAt.delete(id)
+            }
+        }, 15000, tab, () => knobProgressAt.get(id))
+    }
+
+    return {
+        name: 'aihand',
+        apply: 'serve',
+
+        transformIndexHtml() {
+            const patchCode = compilePatch()
+            return [
+                // Synchronous inline script — patches console/fetch/XHR/errors
+                // BEFORE any ES modules execute
+                {
+                    tag: 'script',
+                    children: patchCode,
+                    injectTo: 'head-prepend',
+                },
+                // Module script — collectors + HMR channel (can be deferred)
+                {
+                    tag: 'script',
+                    attrs: { type: 'module' },
+                    children: `import '/@fs/${clientPath}'`,
+                    injectTo: 'body',
+                },
+            ]
+        },
+
+        configureServer(_server) {
+            server = _server
+
+            // 出口1 适配:把 Vite HMR WS 包成 ServerBridge,/screen 与动作端点经 dispatch 复用它
+            // ——出口2(CDP)走同一 dispatch、换 cdpBridge。bridge 自己持久监听 aihand:action-progress
+            // 盖时戳;下面的命名 pending 监听只管 seen/mergeActions 等副作用,resolve 让给 bridge 的
+            // 一次性监听(同一 event 多监听器都触发,bridge 路由的 id 在旧命名槽里查不到 → 旧监听无害空转)。
+            const bridge = viteBridge(server, { tabs, diagnose })
+
+            // 静态调用图随源码变更失效(只清不重建,下次 /source 惰性重建)。任一 .ts/.tsx 改/增/删即脏。
+            // 扩展名判定用 endsWith 词法比较(禁正则铁律),与 read/config.ts isTsFile 同口径。
+            const isTs = (f: string) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js') || f.endsWith('.jsx')
+            const invalidateGraph = (f: string) => { if (isTs(f)) graphCache = null }
+            server.watcher.on('change', invalidateGraph)
+            server.watcher.on('add', invalidateGraph)
+            server.watcher.on('unlink', invalidateGraph)
+
+            server.hot.on('aihand:state', (data: RawState) => {
+                seen(data)
+                mergeActions(data.tab, data.actions, data.actionsDropped)
+                if (pendingResolve) {
+                    pendingResolve(data)
+                    pendingResolve = null
+                }
+            })
+
+            // Client announces itself on connect (and on visibilitychange) — the registration
+            // edge the roster otherwise lacks, so /tabs is accurate without first being polled.
+            // Echo an ack so the client can stop its hello-retry loop. The client resends hello on
+            // a short interval (its first send often races the socket-open and is dropped); the ack
+            // is how it learns the roster finally has it. Keyed by tab so a client only stops once
+            // ITS registration landed.
+            server.hot.on('aihand:hello', (data: { tab?: string, url?: string, title?: string, visible?: boolean }) => {
+                seen(data)
+                if (data.tab)
+                    server.hot.send('aihand:hello-ack', { tab: data.tab })
+            })
+
+            server.hot.on('aihand:result', (data: ActionResult & { id: number, tab?: string }) => {
+                seen(data)
+                const resolve = pendingActions.get(data.id)
+                if (resolve) {
+                    pendingActions.delete(data.id)
+                    resolve(data)
+                }
+            })
+
+            // An in-flight flow pings each frame so its deadline counts from the last sign of life,
+            // not from dispatch — lets a legitimate multi-second stream finish without a false miss.
+            server.hot.on('aihand:action-progress', (data: { id: number, tab?: string, kind?: string }) => {
+                seen(data)
+                if (data.kind === 'knob') {
+                    if (pendingKnob.has(data.id))
+                        knobProgressAt.set(data.id, Date.now())
+                }
+                else if (pendingActions.has(data.id)) {
+                    actionProgressAt.set(data.id, Date.now())
+                }
+            })
+
+            server.hot.on('aihand:eval-result', (data: { id: number, ok: boolean, value?: string, error?: string, hint?: string, tab?: string }) => {
+                seen(data)
+                const resolve = pendingEvals.get(data.id)
+                if (resolve) {
+                    pendingEvals.delete(data.id)
+                    resolve(data)
+                }
+            })
+
+            server.hot.on('aihand:semantic-result', (data: { id: number, ok: boolean, value?: string, error?: string, tab?: string }) => {
+                seen(data)
+                const resolve = pendingSemantic.get(data.id)
+                if (resolve) {
+                    pendingSemantic.delete(data.id)
+                    resolve(data)
+                }
+            })
+
+            server.hot.on('aihand:knob-result', (data: { id: number, ok: boolean, value?: string, error?: string, tab?: string }) => {
+                seen(data)
+                const resolve = pendingKnob.get(data.id)
+                if (resolve) {
+                    pendingKnob.delete(data.id)
+                    resolve(data)
+                }
+            })
+
+            server.hot.on('aihand:dom', (data: { dom: string, tab?: string }) => {
+                seen(data)
+                if (pendingDom) {
+                    pendingDom(data.dom)
+                    pendingDom = null
+                }
+            })
+
+            server.hot.on('aihand:state-path', (data: { ok: boolean, value?: unknown, error?: string, tab?: string }) => {
+                seen(data)
+                if (pendingStatePath) {
+                    pendingStatePath(data)
+                    pendingStatePath = null
+                }
+            })
+
+            server.hot.on('aihand:screen', (data: ScreenReply & { tab?: string }) => {
+                seen(data)
+                if (pendingScreen) {
+                    pendingScreen(data)
+                    pendingScreen = null
+                }
+            })
+
+            // push mode: auto-detect errors after HMR
+            server.hot.on('vite:afterUpdate', () => {
+                clearTimeout(pushTimer)
+                pushTimer = setTimeout(async () => {
+                    try {
+                        const raw = await collectFromClient()
+                        const diff = diffState(lastRaw, raw)
+                        lastRaw = raw
+                        if (!diff.clean) {
+                            const msg = emitDiff(diff)
+                            if (msg)
+                                server.config.logger.warn(msg)
+                        }
+                    }
+                    catch {}
+                }, 500)
+            })
+
+            // /__aihand — summary
+            // /__aihand/{section}/{index} — detail
+            // /__aihand/check — health check
+            server.middlewares.use('/__aihand', async (req, res) => {
+                const url = new URL(req.url || '/', 'http://localhost')
+                const parts = url.pathname.split('/').filter(Boolean)
+                const full = url.searchParams.has('full')
+                // Resolve the target tab. Explicit ?tab= wins. Otherwise, when exactly one tab is
+                // live, adopt it: this routes the action through the tab-ADDRESSED path (skip() by id,
+                // answers regardless of visibility) instead of the no-tab broadcast path. The addressed
+                // path is the only one that honors per-action progress pings — a long async flow
+                // (send → stream → done) pings to extend its deadline, but the broadcast path rejects
+                // flat at fullMs and would cut a >5s stream short. One live tab is the common case, so
+                // without this default the flow trace is lost on every plain (no ?tab=) drive call.
+                // Ambiguity (>1 tab) still falls through to refuse() below — no silent wrong-tab pick.
+                const explicitTab = url.searchParams.get('tab') || undefined
+                const live = liveTabs()
+                const tab = explicitTab ?? (live.length === 1 ? live[0].id : undefined)
+
+                // Federation: ?host=<host:port> reverse-proxies this request to a *sibling*
+                // aihand (another dev server — micro-frontend, separate front/back servers, a
+                // teammate's machine). N peers, no registry, no discovery, no central router:
+                // each plugin is already an HTTP server, so any one of them proxies to a named
+                // peer via a server-side fetch (no browser, no CORS). The forwarded URL drops
+                // host= so the peer treats it as local — `host===self` and re-forwarding both
+                // collapse to the normal path. ?host= is a routing directive, not stored state.
+                const host = url.searchParams.get('host') || undefined
+                const selfPort = server.config.server.port || 5173
+                const selfHosts = new Set([`localhost:${selfPort}`, `127.0.0.1:${selfPort}`, `:${selfPort}`, `${selfPort}`])
+                if (host && !selfHosts.has(host)) {
+                    const fwd = new URL(url)
+                    fwd.searchParams.delete('host')
+                    const target = `http://${host}/__aihand/${parts.join('/')}${fwd.search}`
+                    try {
+                        const body = req.method === 'POST' ? await readBody(req) : undefined
+                        const r = await fetch(target, { method: req.method, body })
+                        send(res, r.status, await r.text())
+                    }
+                    catch (e) {
+                        // Split the failure fibers — each needs a different fix. node's fetch nests
+                        // the syscall error under .cause.code.
+                        const code = (e as { cause?: { code?: string } }).cause?.code
+                        const why = code === 'ECONNREFUSED'
+                            ? `nothing is listening on ${host} — its dev server isn't running (start it), or the port is wrong.`
+                            : code === 'ENOTFOUND'
+                                ? `host '${host}' doesn't resolve — check the hostname.`
+                                : code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT'
+                                    ? `connection to ${host} timed out — it's unreachable (firewall, or wrong host).`
+                                    : `${(e as Error).message} (code ${code ?? 'unknown'}).`
+                        send(res, 502, `cannot reach aihand peer at ${host}: ${why}`)
+                    }
+                    return
+                }
+
+                // /__aihand/ping — process-level BOOT_ID, polled by the injected client-patch
+                // to self-heal after a server restart (see BOOT_ID). Server-self health, no tab,
+                // highest frequency — short-circuit before everything else.
+                if (parts[0] === 'ping') {
+                    send(res, 200, BOOT_ID)
+                    return
+                }
+
+                // /__aihand/help — the full command reference. Static, tab-independent: this is
+                // the body that used to sit in CLAUDE.md every session. It moved here so the model
+                // pulls it on demand (it's already curling aihand when it needs a command) instead
+                // of paying for it resident. The injected snippet points here.
+                if (parts[0] === 'help') {
+                    send(res, 200, helpText(selfPort).trim())
+                    return
+                }
+
+                // /__aihand/open?file=…&line=…&column=… — open a source location in the editor.
+                // The page's Alt/Ctrl-click overlay (client.ts) hits this with the data-insp-path
+                // it read off the clicked element. Server-side only — no client round-trip, no tab.
+                // Guarded to files under the project root: this is a dev-only serve plugin, but
+                // launchIDE shells out to an editor, so we never open an arbitrary absolute path.
+                if (parts[0] === 'open') {
+                    const file = url.searchParams.get('file') || ''
+                    const line = Number(url.searchParams.get('line')) || 1
+                    const column = Number(url.searchParams.get('column')) || 1
+                    const root = server.config.root
+                    const abs = isAbsolute(file) ? file : resolve(root, file)
+                    const rel = relative(root, abs)
+                    if (!file || rel.startsWith('..') || isAbsolute(rel)) {
+                        send(res, 400, `refusing to open '${file}' — not under project root`)
+                        return
+                    }
+                    try {
+                        const { launchIDE } = await import('launch-ide')
+                        launchIDE({ file: abs, line, column })
+                        send(res, 200, `opening ${rel}:${line}:${column}`)
+                    }
+                    catch (err) {
+                        send(res, 500, `launch-ide failed: ${err instanceof Error ? err.message : 'unknown'}`)
+                    }
+                    return
+                }
+
+                // /__aihand/source?path=<data-insp-path> — 融合反向态射的静态孪生(FUSION §4)。
+                // /open 的运行时半边把点中坐标送进编辑器;这里送回**代码原因**:该行属于哪个符号 + callers/
+                // callees。?path 直接喂 /dom 吐的 data-insp-path(`rel:line:col:Name`),
+                // 也吃裸 `rel:line`。静态侧用现成 CallGraph(缓存),运行时侧不掺——点对点缝,无第四数据结构。
+                // 触发端是运行时(人/AI 在页面点了元素),故 join 挂在 ui 探针,不在 read CLI。AI 仍可走
+                // `curl /dom → aihand read source`;此 endpoint 闭的是**人**侧环(点击页面直接看代码原因)。
+                if (parts[0] === 'source') {
+                    const path = url.searchParams.get('path') || ''
+                    if (!path) {
+                        send(res, 400, 'usage: /__aihand/source?path=<file:line>  (path 可直接是 /dom 的 data-insp-path)')
+                        return
+                    }
+                    const { parseInspPath, locate, renderLocate } = await import('../../read/locate.js')
+                    const { file, line } = parseInspPath(path)
+                    if (!file || !Number.isFinite(line)) {
+                        send(res, 400, `bad path '${path}' — expected file:line (or data-insp-path)`)
+                        return
+                    }
+                    try {
+                        const graph = await cachedGraph()
+                        const result = locate(graph, file, line)
+                        if (!result) {
+                            send(res, 404, `no symbol covers ${file}:${line} — file not in scan scope, or line outside any symbol`)
+                            return
+                        }
+                        send(res, 200, renderLocate(result, url.searchParams.has('json')))
+                    }
+                    catch (err) {
+                        send(res, 500, `source lookup failed: ${err instanceof Error ? err.message : 'unknown'}`)
+                    }
+                    return
+                }
+
+                // Multi-tab guard: with >1 live tab and no ?tab=, a broadcast would race N
+                // answers and keep a random one. Refuse and show the roster so the caller
+                // picks. Single tab (or addressed) falls through to the normal path.
+                // /tabs, /timeline and /cdp/* are exempt (server-side aggregate reads / polling).
+                const ambiguous = () => !tab && !['tabs', 'timeline', 'cdp'].includes(parts[0]) && liveTabs().length > 1
+                const refuse = () => send(res, 409, `multiple live tabs — add ?tab=<id>:\n\n${formatTabs(liveTabs(), Date.now())}`)
+
+                try {
+                    // /__aihand/tabs — list live clients (tab id, visibility, title, url, age).
+                    // On an empty roster, defer to the single diagnose() projection so the
+                    // "page open but not injected" vs "no browser at all" split is never re-derived
+                    // here — one π, one place.
+                    if (parts[0] === 'tabs') {
+                        const roster = formatTabs(liveTabs(), Date.now())
+                        send(res, 200, roster === '(no live tabs)' ? `(${diagnose()})` : roster)
+                        return
+                    }
+
+                    // /__aihand/timeline — interleaved action stream across all tabs (server's
+                    // global ring), rendered by the same formatActions as the single-tab tail.
+                    // With >1 tab, lines are prefixed with the tab id; ?tab= filters to one.
+                    // Pull a fresh collect from each addressed tab first so the ring is current at
+                    // read time — actions flush into actionLog via the aihand:state merge, decoupled
+                    // from whichever read happened before (a /screen wouldn't have flushed them).
+                    if (parts[0] === 'timeline') {
+                        // Sequential, not parallel: collectFromClient shares one module-level
+                        // pendingResolve, so concurrent collects would clobber each other.
+                        const targets = tab ? [tab] : liveTabs().map(t => t.id)
+                        for (const id of targets)
+                            await collectFromClient(id).catch(() => {})
+                        const entries = tab ? actionLog.filter(e => e.tab === tab) : actionLog
+                        const dropped = targets.reduce((n, id) => n + (droppedByTab.get(id) ?? 0), 0)
+                        send(res, 200, formatActions(entries, undefined, dropped))
+                        return
+                    }
+
+                    if (ambiguous()) {
+                        refuse()
+                        return
+                    }
+
+                    // /__aihand/eval — run arbitrary JS in the page. POST body = code,
+                    // or ?code=. The page evaluates it and returns the result (or thrown
+                    // error). The escape hatch for anything the typed endpoints can't do:
+                    // install event listeners, read closures, probe real event flow.
+                    if (parts[0] === 'eval') {
+                        let code = url.searchParams.get('code') || ''
+                        if (!code && req.method === 'POST')
+                            code = await readBody(req)
+                        if (!code) {
+                            send(res, 400, 'eval needs ?code= or a POST body')
+                            return
+                        }
+                        const r = await evalInClient(code, tab)
+                        const body = r.ok ? (r.value ?? 'undefined') : `error: ${r.error}`
+                        // refine the eval fiber to the action fiber: when the code is a hand-rolled
+                        // /state or /query, or the error is an illegal selector, point at the typed twin.
+                        send(res, r.ok ? 200 : 422, r.hint ? `${body}\n\nhint: ${r.hint}` : body)
+                        return
+                    }
+
+                    // /__aihand/action?name=sendPrompt — the green channel. Calls a named semantic
+                    // action the app mounted on __AIHAND_ACTIONS__ (the store-write + real semantic fn
+                    // a button's onClick runs, minus the DOM). Returns its before/after delta directly
+                    // — operation IS observation, no /screen round-trip. args= is a JSON array (or POST
+                    // body); a name= the app didn't declare lists the ones it did.
+                    if (parts[0] === 'action') {
+                        // ?knob= — the god-tier path: replay a statically-extracted morphism with
+                        // zero hand-mounting. The browser resolves knob→ops from virtual:aihand-knobs
+                        // and writes the store directly. ?value= fills param knobs; ?file= disambiguates
+                        // a label that two components share. context-dependent knobs are refused (422).
+                        const knob = url.searchParams.get('knob') || ''
+                        if (knob) {
+                            lastRaw = null // page mutated; force fresh collect next read
+                            const r = await knobInClient(
+                                knob,
+                                url.searchParams.get('file') || undefined,
+                                url.searchParams.get('value') ?? undefined,
+                                tab,
+                            )
+                            send(res, r.ok ? 200 : 422, r.ok ? (r.value ?? 'undefined') : `error: ${r.error}`)
+                            return
+                        }
+                        const name = url.searchParams.get('name') || ''
+                        if (!name) {
+                            const hint = misroutedAction([...url.searchParams.keys()])
+                            const base = 'action needs ?knob= (a panel label) or ?name= (a __AIHAND_ACTIONS__ key)'
+                            send(res, 400, hint ? `${base}\n\nhint: ${hint}` : base)
+                            return
+                        }
+                        let args: unknown[] = []
+                        const rawArgs = url.searchParams.get('args') || (req.method === 'POST' ? await readBody(req) : '')
+                        if (rawArgs) {
+                            try {
+                                const parsed = JSON.parse(rawArgs)
+                                args = Array.isArray(parsed) ? parsed : [parsed]
+                            }
+                            catch {
+                                send(res, 400, `action args= must be a JSON array, got: ${rawArgs.slice(0, 80)}`)
+                                return
+                            }
+                        }
+                        lastRaw = null // page mutated; force fresh collect next read
+                        const r = await semanticInClient(name, args, tab)
+                        send(res, r.ok ? 200 : 422, r.ok ? (r.value ?? 'undefined') : `error: ${r.error}`)
+                        return
+                    }
+
+                    // /__aihand/dom[?scope=Component|?sel=CSS] — semantic DOM, scoped, on-demand
+                    if (parts[0] === 'dom') {
+                        const dom = await collectDomFromClient(
+                            url.searchParams.get('scope') || undefined,
+                            url.searchParams.get('sel') || undefined,
+                            tab,
+                        )
+                        send(res, 200, dom || '(empty)')
+                        return
+                    }
+
+                    // /__aihand/state?path=store.field.0 — the point-drill of the state axis, twin
+                    // of /dom?sel=. /state and /state/<store> both go through boundedSnapshot (every
+                    // array → "Array(N)", depth-3 cliff); ?path= walks the raw live store and expands
+                    // the leaf one bound deeper, so a nested list is reachable without a hand-rolled
+                    // /eval. (Domain drill /state/<store> still rides the generic detail() path below.)
+                    if (parts[0] === 'state' && url.searchParams.has('path')) {
+                        const path = url.searchParams.get('path') || ''
+                        const r = await collectStatePathFromClient(path, tab)
+                        if (!r.ok) {
+                            send(res, 404, `path not found: ${r.error}`)
+                            return
+                        }
+                        let body: string
+                        try {
+                            body = JSON.stringify(r.value, null, 2) ?? String(r.value)
+                        }
+                        catch {
+                            body = String(r.value)
+                        }
+                        send(res, 200, body)
+                        return
+                    }
+
+                    // /__aihand/screen — state-machine projection {view, modal, focus, knobs}.
+                    // Each read stashes its snap under a token and prints `token: tN`. With
+                    // ?since=<token> we diff this read against that stashed snap and return only
+                    // the transition (diffScreen) — what moved since you last looked, not a snapshot.
+                    if (parts[0] === 'screen') {
+                        // dispatch(viteBridge) 跑 collect-screen + 渲染——与出口2 同一份。?since= token
+                        // ring 是 HTTP 专属,留在这里:用 dispatchScreen 顺手拿回的结构化 reply 去 stash/diff。
+                        const { reply, result } = await dispatchScreen(bridge, { tab, form: url.searchParams.get('form') || undefined })
+                        const since = url.searchParams.get('since')
+                        const token = stashScreen(reply)
+                        if (since) {
+                            const prev = screenStash.get(since)
+                            if (!prev) {
+                                send(res, 422, `unknown since token "${since}" (expired or never issued) — read /screen first for a fresh token`)
+                                return
+                            }
+                            const d = diffState(
+                                { ui: '', console: prev.console, network: prev.network, errors: prev.errors, state: {}, url: '', timestamp: 0 },
+                                { ui: '', console: reply.console, network: reply.network, errors: reply.errors, state: {}, url: '', timestamp: 0 },
+                            )
+                            const changed = diffScreen(prev.snap, reply.snap, d.newErrors, d.newExceptions, d.newFailedRequests)
+                            send(res, 200, `token: ${token}\n${changed.length ? changed.join('\n') : '(no state change)'}`)
+                            return
+                        }
+                        send(res, 200, result.body === '(empty)' ? '(empty)' : `token: ${token}\n${result.body}`)
+                        return
+                    }
+
+                    // /__aihand/cdp/poll — the Chrome extension long-polls here for the next
+                    // trusted-input command. Returns the command as JSON, or 204 on timeout
+                    // (the extension simply re-polls). Only one poller is parked at a time.
+                    if (parts[0] === 'cdp' && parts[1] === 'poll') {
+                        const queued = cdpQueue.shift()
+                        if (queued) {
+                            send(res, 200, JSON.stringify(queued))
+                            return
+                        }
+                        const cmd = await new Promise<CdpCommand | null>((resolve) => {
+                            cdpWaiter = resolve
+                            setTimeout(() => {
+                                if (cdpWaiter === resolve) {
+                                    cdpWaiter = null
+                                    resolve(null)
+                                }
+                            }, 25000)
+                        })
+                        if (cmd)
+                            send(res, 200, JSON.stringify(cmd))
+                        else
+                            send(res, 204, '')
+                        return
+                    }
+
+                    // /__aihand/cdp/result — POST {id, ok, error?}; resolves the awaiting realclick.
+                    if (parts[0] === 'cdp' && parts[1] === 'result') {
+                        const body = await readBody(req)
+                        let data: { id: number, ok: boolean, error?: string }
+                        try {
+                            data = JSON.parse(body)
+                        }
+                        catch {
+                            send(res, 400, 'cdp/result needs a JSON body {id, ok, error?}')
+                            return
+                        }
+                        const resolveCdp = cdpResults.get(data.id)
+                        if (resolveCdp) {
+                            cdpResults.delete(data.id)
+                            resolveCdp({ ok: data.ok, error: data.error })
+                        }
+                        send(res, 200, 'ok')
+                        return
+                    }
+
+                    // /__aihand/chain — POST a JSON array of actions, run them in
+                    // sequence (each settles the DOM before the next), stop on first
+                    // failure. One round-trip for a whole interaction.
+                    if (parts[0] === 'chain') {
+                        const body = await readBody(req)
+                        let steps: ChainStep[]
+                        try {
+                            steps = JSON.parse(body)
+                            if (!Array.isArray(steps))
+                                throw new Error('body must be a JSON array')
+                        }
+                        catch (e) {
+                            send(res, 400, `invalid chain body: ${e instanceof Error ? e.message : String(e)}`)
+                            return
+                        }
+                        lastRaw = null
+                        // 循环/fail-fast/skipped 汇报走内核 runChain(与出口2 共用一份)。出口1 的单步执行器
+                        // 比出口2 多 knob 特例:knob 步骤经绿色通道 replay 一个 panel 态射(/action?knob= 的
+                        // store-direct 最优路,现在能进 batch,不被迫降级 click text=)。非 knob 走 runAction。
+                        const dr = await runChain(steps, async (type, args) => {
+                            if (type === 'knob') {
+                                const k = args as { knob?: string, file?: string, value?: string }
+                                if (!k.knob)
+                                    return { ok: false, label: 'knob', error: 'needs knob=<panel label>' }
+                                const kr = await knobInClient(k.knob, k.file, k.value, tab)
+                                return { ok: kr.ok, label: 'knob', detail: kr.ok ? `replayed ${k.knob}` : undefined, error: kr.ok ? undefined : kr.error, screen: kr.ok ? kr.value : undefined }
+                            }
+                            const check = resolveAction(type, args)
+                            if (!check.valid)
+                                return { ok: false, label: type, error: check.error }
+                            const r = await runAction(type, args, tab)
+                            return { ok: r.ok, label: type, detail: r.detail, error: r.error, screen: r.screen, actions: r.actions }
+                        })
+                        send(res, dr.status, dr.body)
+                        return
+                    }
+
+                    // action endpoints — the full TYPES source of truth (no hand-kept second list that
+                    // drifts; dblclick was missing here before). isDispatchAction ones go through the
+                    // shared kernel (dispatchAction), the SPECIAL_CONTRACT rest fall through to runAction.
+                    if (TYPES.includes(parts[0] as (typeof TYPES)[number])) {
+                        const args = argsFromQuery(url.searchParams)
+                        // 最小闭环动作(click|fill|press|hover|wait)经 dispatch(viteBridge)——与出口2 同一
+                        // 内核路径。dispatchAction 内部自校验 + 渲染,id 复用 plugin 的 actionId 计数器(与
+                        // runAction/chain 同空间不撞)。realclick/screenshot/query/assert/drag 等仍走 runAction
+                        // (CDP 握手、落盘等出口1 专属副作用),fall through。
+                        if (isDispatchAction(parts[0])) {
+                            const dr = await dispatchAction(bridge, parts[0], args, { nextId: () => ++actionId, tab })
+                            lastRaw = null // page mutated; force fresh collect next read (runAction parity)
+                            send(res, dr.status, dr.body)
+                            return
+                        }
+                        const check = resolveAction(parts[0], args)
+                        if (!check.valid) {
+                            send(res, 400, check.error ?? 'invalid action')
+                            return
+                        }
+                        const result = await runAction(parts[0], args, tab)
+                        if (parts[0] === 'screenshot' && result.dataUrl) {
+                            const dir = resolve(server.config.root, '.aidev')
+                            mkdirSync(dir, { recursive: true })
+                            const name = url.searchParams.get('out') || `shot-${result.dataUrl.length}.png`
+                            const file = resolve(dir, name)
+                            writeFileSync(file, Buffer.from(result.dataUrl.split(',')[1], 'base64'))
+                            send(res, 200, `saved: ${file}`)
+                            return
+                        }
+                        const head = result.ok ? (result.detail || 'ok') : `${result.error}${result.detail ? `\n\nclickable: ${result.detail}` : ''}`
+                        const actionsTail = result.actions ? `\n\n--- recent actions ---\n${result.actions}` : ''
+                        const changedTail = result.screen ? `\n\n--- changed ---\n${result.screen}` : ''
+                        const flowTail = result.flow ? `\n\n--- flow ---\n${result.flow}` : ''
+                        send(res, result.ok ? 200 : 422, `${head}${actionsTail}${changedTail}${flowTail}`)
+                        return
+                    }
+
+                    // check endpoint
+                    if (parts[0] === 'check') {
+                        const raw = await collectFromClient(tab)
+                        lastRaw = raw
+                        const result = check(raw)
+                        const output = emitCheck(result)
+                        send(res, result.pass ? 200 : 417, output)
+                        return
+                    }
+
+                    // /__aihand/profile — performance profiler (always-on, semantic-bucketed).
+                    // /profile reads the current window; /profile/reset clears it.
+                    // Hidden tabs throttle rAF to ~1fps, making each hidden frame look like a
+                    // 1000ms dropped frame — the profiler guards with document.hidden, but if
+                    // hiddenFrames is high the data is suspect. Mention it.
+                    if (parts[0] === 'profile') {
+                        // Empty perf data is a recoverable state, not a dead end: the tab DID answer
+                        // collectFromClient (so it's connected) — it's just backgrounded, where the
+                        // browser throttles rAF to ~1fps and there are no real frames to sample. The
+                        // bare "(no perf data)" reads to a model as "no browser, can't help", so it
+                        // gives up. Say the page is already running and a 2s foreground fixes it —
+                        // profiling is the only read that needs foreground (/screen, /dom work hidden).
+                        // Empty perf data after a SUCCESSFUL collect is its own fiber, disjoint from
+                        // diagnose() (which is the no-reply projection): the tab answered, so it's
+                        // connected — it's just backgrounded, where the browser throttles rAF to ~1fps
+                        // and there are no real frames to sample. Recoverable in 2s, not a dead end.
+                        // The tab-absent fallback defers to diagnose() so the socket logic lives once.
+                        const noPerfMsg = (t?: string) => {
+                            const info = t ? tabs.get(t) : liveTabs()[0]
+                            return info
+                                ? `tab '${info.id}' is connected but BACKGROUNDED — the browser throttles rAF to ~1fps for hidden tabs, so there are no real frames to profile. You don't need to open anything: the page is already running. Ask the user to click that browser tab to the foreground and keep it there ~2s, then re-run /profile. (Profiling is the only read needing foreground — /screen and /dom work backgrounded.)`
+                                : `(${diagnose(t)})`
+                        }
+                        // Clear the client-side perf window and wait for ack. Used by /profile/reset
+                        // and by /profile/diff when capturing a baseline — so "before" and "after"
+                        // each measure ONLY their own reproduce, not an ever-growing running sum.
+                        const resetPerfWindow = () => new Promise<void>((resolve, reject) => {
+                            const timeout = setTimeout(() => reject(new Error('timeout waiting for perf-reset-ack')), 3000)
+                            const handler = (data: { tab?: string }) => {
+                                if (tab && data.tab !== tab) return
+                                clearTimeout(timeout)
+                                server.hot.off('aihand:perf-reset-ack', handler)
+                                resolve()
+                            }
+                            server.hot.on('aihand:perf-reset-ack', handler)
+                            server.hot.send('aihand:perf-reset', { tab, requireVisible: false })
+                        })
+                        if (parts[1] === 'reset') {
+                            await resetPerfWindow()
+                            send(res, 200, 'perf window cleared — reproduce the interaction, then GET /profile')
+                            return
+                        }
+                        if (parts[1] === 'diff') {
+                            // Closed-loop verdict. First call captures a baseline; second diffs
+                            // current vs baseline and clears it. Workflow: /profile/diff (mark before)
+                            // → make a fix → reproduce → /profile/diff (get IMPROVED/REGRESSED verdict).
+                            const raw = await collectFromClient(tab)
+                            lastRaw = raw
+                            if (!raw.performance) {
+                                send(res, 200, noPerfMsg(tab))
+                                return
+                            }
+                            if (!perfBaseline) {
+                                perfBaseline = raw.performance
+                                // Clear the window so the NEXT collect measures only the post-fix
+                                // reproduce. Without this, "after" ⊇ "before" (samples append, total
+                                // is a running sum) → self-time can only grow → IMPROVED impossible.
+                                await resetPerfWindow()
+                                send(res, 200, 'baseline captured + window cleared — make your fix, reproduce the interaction, then GET /profile/diff again for the verdict')
+                                return
+                            }
+                            const report = diffPerformance(perfBaseline, raw.performance)
+                            perfBaseline = null // consumed; next call starts a fresh baseline
+                            send(res, 200, report)
+                            return
+                        }
+                        // /profile — fresh collect, render detail
+                        const raw = await collectFromClient(tab)
+                        lastRaw = raw
+                        if (!raw.performance) {
+                            send(res, 200, noPerfMsg(tab))
+                            return
+                        }
+                        const hiddenNote = raw.performance.hiddenFrames > 10
+                            ? `\n\n⚠ ${raw.performance.hiddenFrames} frames skipped while tab was hidden — bring it to foreground and /profile/reset for accurate data.`
+                            : ''
+                        send(res, 200, detail(raw, 'profile', undefined, false) + hiddenNote)
+                        return
+                    }
+
+                    // detail: /__aihand/{section}[/{index}][?full]
+                    if (parts.length >= 1) {
+                        if (!lastRaw)
+                            lastRaw = await collectFromClient(tab)
+                        const result = detail(lastRaw, parts[0], parts[1], full)
+                        if (result !== null) {
+                            send(res, 200, result)
+                            return
+                        }
+                        // null splits two fibers: an unknown section name (→ fix the path) vs a
+                        // known section that's simply empty (→ nothing to show, not an error). Name
+                        // the valid sections so the caller can tell which it hit.
+                        const SECTIONS = ['ui', 'console', 'network', 'errors', 'state', 'profile']
+                        send(res, 404, SECTIONS.includes(parts[0])
+                            ? `'${parts[0]}' is empty right now — nothing captured this window (not an error).`
+                            : `unknown section '${parts[0]}'. Valid: ${SECTIONS.join(', ')}. (Or /screen, /dom, /tabs, /timeline, /check.)`)
+                        return
+                    }
+
+                    // summary or full: /__aihand[?full]
+                    const raw = await collectFromClient(tab)
+                    lastRaw = raw
+                    if (full) {
+                        const compacted = compact(raw)
+                        send(res, 200, emit(compacted))
+                    }
+                    else {
+                        send(res, 200, emitSummary(raw))
+                    }
+                }
+                catch (err) {
+                    send(res, 504, err instanceof Error ? err.message : 'unknown error')
+                }
+            })
+        },
+    }
+}