spexcode 0.4.0 → 0.4.3

package/spec-cli/src/identity-presets.js

@@ -0,0 +1,128 @@
+// One browser-safe identity registry shared by backend validation and every dashboard projection.
+// Geometry is data so the React renderer and favicon serializer cannot drift into separate drawings.
+
+export const DEFAULT_PROJECT_ICON = 'spexcode'
+export const DEFAULT_GATEWAY_ICON = 'gateway'
+
+export const IDENTITY_PRESETS = Object.freeze([
+  {
+    id: 'spexcode', label: 'SpexCode', bg: '#166534', fg: '#f0fdf4',
+    shapes: [
+      { tag: 'circle', cx: 12, cy: 6.2, r: 2.2 },
+      { tag: 'circle', cx: 6.2, cy: 17.5, r: 2 },
+      { tag: 'circle', cx: 17.8, cy: 17.5, r: 2 },
+      { tag: 'path', d: 'M12 8.4v2.1c0 2.2-5.8 1.8-5.8 5' },
+      { tag: 'path', d: 'M12 10.5c0 2.2 5.8 1.8 5.8 5' },
+    ],
+  },
+  {
+    id: 'gateway', label: 'Gateway', bg: '#155e75', fg: '#ecfeff',
+    shapes: [
+      { tag: 'path', d: 'm12 3 8 4.2-8 4.2-8-4.2Z' },
+      { tag: 'path', d: 'm4 11.2 8 4.2 8-4.2' },
+      { tag: 'path', d: 'm4 15.2 8 4.2 8-4.2' },
+    ],
+  },
+  {
+    id: 'mdi:rocket-launch', label: 'Rocket', bg: '#9f1239', fg: '#fff1f2',
+    shapes: [
+      { tag: 'path', d: 'M14.5 5.2c2.2-2.2 4.8-2 5.3-1.8.2.5.4 3.1-1.8 5.3l-5.5 5.5-4.2-4.2Z' },
+      { tag: 'path', d: 'm11.2 6.8-4.1.6-2.5 2.5 4.1.7' },
+      { tag: 'path', d: 'm16.4 12-1 4.7-2.5 2.5-.7-4.1' },
+      { tag: 'circle', cx: 16.1, cy: 7.1, r: 1.2 },
+      { tag: 'path', d: 'M7.6 14.6c-2.2.4-3.4 1.6-3.6 3.8 2.2-.2 3.4-1.4 3.8-3.6' },
+    ],
+  },
+  {
+    id: 'compass', label: 'Compass', bg: '#1d4ed8', fg: '#eff6ff',
+    shapes: [
+      { tag: 'circle', cx: 12, cy: 12, r: 8.5 },
+      { tag: 'path', d: 'm15.2 8.8-1.8 4.6-4.6 1.8 1.8-4.6Z' },
+    ],
+  },
+  {
+    id: 'terminal', label: 'Terminal', bg: '#3f3f46', fg: '#fafafa',
+    shapes: [
+      { tag: 'rect', x: 3.5, y: 4.5, width: 17, height: 15, rx: 2 },
+      { tag: 'path', d: 'm7 9 3 3-3 3' },
+      { tag: 'path', d: 'M12.5 15H17' },
+    ],
+  },
+  {
+    id: 'package', label: 'Package', bg: '#6d28d9', fg: '#f5f3ff',
+    shapes: [
+      { tag: 'path', d: 'm12 3 8 4.5v9L12 21l-8-4.5v-9Z' },
+      { tag: 'path', d: 'm4.3 7.7 7.7 4.4 7.7-4.4' },
+      { tag: 'path', d: 'M12 12.1V21' },
+    ],
+  },
+  {
+    id: 'database', label: 'Database', bg: '#a16207', fg: '#fefce8',
+    shapes: [
+      { tag: 'ellipse', cx: 12, cy: 6, rx: 7.5, ry: 3 },
+      { tag: 'path', d: 'M4.5 6v6c0 1.7 3.4 3 7.5 3s7.5-1.3 7.5-3V6' },
+      { tag: 'path', d: 'M4.5 12v6c0 1.7 3.4 3 7.5 3s7.5-1.3 7.5-3v-6' },
+    ],
+  },
+  {
+    id: 'spark', label: 'Spark', bg: '#c2410c', fg: '#fff7ed',
+    shapes: [
+      { tag: 'path', d: 'm12 3 1.5 5.2L19 10l-5.5 1.8L12 17l-1.5-5.2L5 10l5.5-1.8Z' },
+      { tag: 'path', d: 'm18.5 15 .7 2.2 2.3.8-2.3.8-.7 2.2-.7-2.2-2.3-.8 2.3-.8Z' },
+    ],
+  },
+])
+
+const BY_ID = new Map(IDENTITY_PRESETS.map((preset) => [preset.id, preset]))
+const ICONIFY_ID = /^[a-z0-9-]+[:/][a-z0-9-]+$/i
+const ALIASES = new Map([
+  ['rocket', 'mdi:rocket-launch'],
+  ['mdi/rocket-launch', 'mdi:rocket-launch'],
+  ['layers', 'gateway'],
+  ['default', 'spexcode'],
+])
+
+export const IDENTITY_PRESET_IDS = Object.freeze(IDENTITY_PRESETS.map((preset) => preset.id))
+
+export function resolvedIdentityIcon(value, fallback = DEFAULT_PROJECT_ICON) {
+  const raw = typeof value === 'string' ? value.trim() : ''
+  const id = ALIASES.get(raw) || raw
+  return id || fallback
+}
+
+export function identityPreset(value) {
+  const raw = typeof value === 'string' ? value.trim() : ''
+  return BY_ID.get(ALIASES.get(raw) || raw) || null
+}
+
+export function isIconifyIcon(value) {
+  return ICONIFY_ID.test(typeof value === 'string' ? value.trim() : '')
+}
+
+export function requireIdentityChoice(value) {
+  const raw = typeof value === 'string' ? value.trim() : ''
+  const id = ALIASES.get(raw) || raw
+  if (BY_ID.has(id)) return id
+  if (isIconifyIcon(id)) return id.replace('/', ':')
+  throw new Error(`unknown identity icon '${raw}' (choose a preset or Iconify prefix:name)`)
+}
+
+function attrs(shape) {
+  return Object.entries(shape).filter(([key]) => key !== 'tag')
+    .map(([key, value]) => `${key === 'className' ? 'class' : key}="${String(value).replaceAll('&', '&').replaceAll('"', '"')}"`).join(' ')
+}
+
+export function identitySvg(value, fallback = DEFAULT_PROJECT_ICON) {
+  const preset = identityPreset(value) || identityPreset(fallback)
+  const geometry = preset.shapes.map((shape) => `<${shape.tag} ${attrs(shape)}/>`).join('')
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect x="1" y="1" width="22" height="22" rx="5" fill="${preset.bg}"/><g fill="none" stroke="${preset.fg}" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">${geometry}</g></svg>`
+}
+
+export function identityFaviconHref(value, fallback = DEFAULT_PROJECT_ICON) {
+  const resolved = resolvedIdentityIcon(value, fallback)
+  if (identityPreset(resolved)) return `data:image/svg+xml,${encodeURIComponent(identitySvg(resolved, fallback))}`
+  if (/^https?:\/\//.test(resolved)) return resolved
+  if (isIconifyIcon(resolved)) return `https://api.iconify.design/${resolved.replace(':', '/')}.svg`
+  const glyph = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text x="50" y=".86em" font-size="82" text-anchor="middle">${resolved.replaceAll('&', '&amp;').replaceAll('<', '&lt;')}</text></svg>`
+  return `data:image/svg+xml,${encodeURIComponent(glyph)}`
+}

package/spec-cli/src/index.ts

@@ -5,7 +5,7 @@ import { Hono } from 'hono'
 import { cors } from 'hono/cors'
 import { etag } from 'hono/etag'
 import { createNodeWebSocket } from '@hono/node-ws'
-import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig } from './specs.js'
+import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig, loadReviewConfig } from './specs.js'
 import { issuesEnabled, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
 import { closeIssue, createIssue, findIssue, issueStores, mergedIssues, promote, replyIssue } from './issues.js'
 import { residentForgeState, refreshForgeNow } from '../../spec-forge/src/resident.js'
@@ -13,19 +13,21 @@ import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { summarize } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './graphCache.js'
-import { boardStream, notifyBoardChanged } from './graphStream.js'
+import { boardStream, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
-import { newSession, listSessions, sendText, rawKey, stopSession, closeSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, superviseQueue } from './sessions.js'
+import { listSessions, sendText, rawKey, stopSession, closeSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, TMUX_SOCK } from './sessions.js'
+import { superviseTimeline, readTimeline } from './session-timeline.js'
 import { defaultHarness, HARNESSES, launcherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
 import { putBlob } from '../../spec-eval/src/cache.js'
-import { evalNodes } from '../../spec-eval/src/scenarios.js'
 import { fileHumanReading } from '../../spec-eval/src/filing.js'
 import { fileHumanOk } from '../../spec-eval/src/humanok.js'
-import { buildExportModel, renderExportHtml, buildSessionEvals } from '../../spec-eval/src/sessioneval.js'
+import { buildExportModel, renderExportHtml, SessionEvalUnavailableError } from '../../spec-eval/src/sessioneval.js'
 import { saveUpload, MAX_UPLOAD_BYTES } from './uploads.js'
-import { attachViewer, detachViewer, resizeBridge, forwardWheel, superviseBridges, type Viewer } from './pty-bridge.js'
+import { attachViewer, detachViewer, resizeBridge, hideViewer, forwardInput, superviseBridges, type Viewer } from './pty-bridge.js'
 import { installProcessGuards } from './resilience.js'
+import { resolveProjectIdentity } from './project-identity.js'
+import { evalDetailReview, evalsReview, issuesReview } from './reviews.js'
 
 // last-resort net: an unforeseen async throw (e.g. a worktree vanishing mid-read during a worker
 // self-merge) is logged and the server KEEPS SERVING instead of exiting and dropping the public port.
@@ -33,12 +35,34 @@ installProcessGuards()
 
 const app = new Hono()
 app.use('/api/*', cors())
+app.onError((error, c) => {
+  if (error instanceof SessionEvalUnavailableError) return c.json({ error: error.message }, 503)
+  console.error(error)
+  return c.text('Internal Server Error', 500)
+})
 const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app })
 
 app.get('/', (c) => c.text('spec-cli — GET /api/graph · /api/specs · /api/specs/:id/history · /api/settings · /api/sessions · /api/slash-commands'))
 // the supervisor's readiness gate (supervise.ts): a bare git-free 200 so a booting child reports ready the
 // instant Hono is listening. Not under /api/* — loopback-only (supervisor→child), no CORS needed.
 app.get('/health', (c) => c.text('ok'))
+// @@@ instance identity - who THIS backend is: the serve generation's instanceId (minted by the supervisor,
+// constant across zero-downtime reloads, handed down via env) and the project root it serves. This is the
+// answer the host gateway ([[host-gateway]]) compares an endpoint record against before proxying to it — a
+// recycled port serving another project or a stale record fails the match instead of being routed to. Git-free
+// after the first memoized resolution; a self-run child (no supervisor) answers instanceId:null, which no
+// record claims, so it is simply not hosted.
+const instanceStartedAt = new Date().toISOString()
+app.get('/api/instance', (c) => {
+  const root = repoRoot()
+  return c.json({
+    instanceId: process.env.SPEXCODE_INSTANCE_ID ?? null,
+    root,
+    identity: resolveProjectIdentity(root, root),
+    pid: process.pid,
+    startedAt: instanceStartedAt,
+  })
+})
 // the assembled graph (merged tree + overlay + sessions) — the dashboard's single source. Same data
 // as `spex graph --json`; the frontend only adds x/y pixels on top. Freshness is PUSH-first ([[graph-stream]]): the
 // dashboard reloads on a `/api/graph/stream` event, not a tight poll, so the route is a conditional-request
@@ -52,6 +76,7 @@ app.get('/health', (c) => c.text('ok'))
 // is bounded by [[graph-cache]]'s own build watchdog, so the next poll retries a fresh build.
 const BOARD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_TIMEOUT_MS || 20000)
 app.get('/api/graph', etag(), async (c) => {
+  ensureBoardFileWatchers()
   const timeout = Symbol('timeout')
   const json = await Promise.race([getBoardJson(), new Promise<typeof timeout>((r) => setTimeout(() => r(timeout), BOARD_TIMEOUT_MS))])
   if (json === timeout) return c.json({ error: 'graph build timed out' }, 503)
@@ -63,19 +88,9 @@ app.get('/api/graph/stream', (c) => boardStream(c))
 app.get('/api/specs', async (c) => c.json(await loadSpecs()))
 // the search corpus ([[graph-lean]]): a filesystem-only {id,title,path,desc,body} for every node, NO git. The
 // board omits `body` to stay lean, so the search palette fetches this ONCE when it opens (cached client-side)
-// to rank nodes over their prose — off the board's hot poll. A literal segment, before the `:id` routes.
-// Scenario prose rides the same corpus: the board's `scenarios` fold is slim ({name, tags}), so a measurable
-// node's row here carries its declared scenarios' description/expected (+ per-scenario code) — one fetch
-// serves both the palette's scenario plane and the focus-panel preview.
-app.get('/api/specs/lite', (c) => {
-  const scByNode = new Map(evalNodes(repoRoot()).map((y) => [y.id, y.scenarios]))
-  return c.json(loadSpecsLite().map((row) => {
-    const sc = scByNode.get(row.id)
-    return sc?.length
-      ? { ...row, scenarios: sc.map((s) => ({ name: s.name, description: s.description, expected: s.expected, ...(s.code?.length ? { code: s.code } : {}) })) }
-      : row
-  }))
-})
+// to rank nodes over their prose — off the board's hot poll. Review rows, including scenarios, come only
+// from their paged endpoints and cannot be reconstructed from this corpus.
+app.get('/api/specs/lite', (c) => c.json(loadSpecsLite()))
 // one node's body + parsed parts ([[graph-lean]]): the board no longer ships either, so the detail view
 // fetches this when a node opens. 404 for an unknown id.
 app.get('/api/specs/:id/content', (c) => {
@@ -131,9 +146,11 @@ app.post('/api/specs/:id/evals/ok', async (c) => {
 // else the bytes with a sniffed MIME and an immutable cache header (the name IS the content hash).
 // HTTP Range is honored — a <video> can only SEEK when the server answers byte ranges (a browser clamps
 // currentTime to the seekable window, which stays [0,0] without them); one general mechanism at the
-// transport, so every evidence kind streams the same way.
+// transport, so every evidence kind streams the same way. A trailing `.<ext>` on the hash is IGNORED
+// decoration for third-party markdown renderers (GitLab/GitHub only emit a <video> player when the URL
+// ends in a video extension); the served bytes and MIME stay the stored ones — a wrong suffix never lies.
 app.get('/api/evidence/:hash', (c) => {
-  const r = readBlobByHash(c.req.param('hash'))
+  const r = readBlobByHash(c.req.param('hash').replace(/\.[a-z0-9]+$/i, ''))
   if (!r.ok) return c.text(r.message, r.reason === 'invalid' ? 400 : 404)
   const total = r.bytes.length
   const base = { 'Content-Type': r.mime, 'Cache-Control': 'public, max-age=31536000, immutable', 'Accept-Ranges': 'bytes' }
@@ -158,30 +175,50 @@ app.post('/api/evidence', async (c) => {
 })
 // the SETTINGS read surface — one route for everything spexcode.json / spexcode.local.json resolves to:
 // `layout` (resolveLayout()'s main/worktrees/branch shape — the write-guard's project-identity probe reads
-// `.layout.main`) and the named launcher profiles ([[launcher-select]]) the New-Session form's dropdown
-// offers — `{ name, harness }` only (the `cmd` is a host secret, never shipped to the browser) — plus the
-// configured `default` NAME so the dropdown pre-selects the SAME launcher a bare `spex session new` uses
-// (the CLI/config default), instead of the alphabetically-first one. Missing defaultLauncher is returned
-// as an actionable config error, not hidden by falling through to the built-in `claude` launcher.
+// `.layout.main`) and the named launcher profiles ([[launcher-select]]) the New-Session picker
+// offers — `{ name, harness, cmd }`: the cmd is read-only display data for the picker (the dashboard sits
+// behind the gateway auth; the browser can read but never edit config) — plus the configured `default` NAME
+// so the picker pre-selects the SAME
+// launcher a bare `spex session new` uses (the CLI/config default), instead of the alphabetically-first one,
+// Missing defaultLauncher is returned as an actionable config error, not hidden by falling through to the
+// built-in `claude` launcher.
+// `tmuxSocket` is the `-L <name>` label our private tmux server runs under (a backend fact, env-overridable),
+// so the row's attach modal ([[attach-menu]]) can offer the RAW `tmux -L <socket> attach -t <id>` fallback
+// beside the blessed `spex session attach` command — the frontend never hardcodes the socket.
 app.get('/api/settings', async (c) => c.json({
   layout: await resolveLayout(),
-  launchers: launcherList().map(({ name, harness }) => ({ name, harness })),
+  launchers: launcherList(),
+  tmuxSocket: TMUX_SOCK,
   ...launcherDefault(),
 }))
-// the `surface: command` plugin-root nodes (built/active only) for the new-session `/` dropdown — each with
+// the `surface: command` plugin-root nodes (built/active only) for new-session and live-inbox `/` dropdowns — each with
 // its prompt `body` ({{targets}} placeholder), `kind`, and folder `dir` + co-located `files`. surface is a
 // frontmatter field, not a dir (specs.ts loadSurface); `surface: system` siblings are gathered elsewhere.
-app.get('/api/plugins', (c) => c.json(loadConfig()))
+// `?surface=review` lists the review-track presets instead ([[review-commands]] — the eval detail's
+// remark-composer `/` dropdown); the exposed surfaces stay this explicit whitelist, never a passthrough.
+app.get('/api/plugins', (c) => c.json(c.req.query('surface') === 'review' ? loadReviewConfig() : loadConfig()))
 // the ISSUES read surface ([[issues]]) for the dashboard's issues page — the merged list over every store
 // (local threads + the resident forge slice), the SAME mergedIssues() the CLI drain reads, verbatim
 // (the dashboard computes nothing over it: no re-sort, no salience ranking). The `enabled` flag mirrors
 // the issues-workflow on/off switch so the frontend hides the view when the feature is OFF.
-app.get('/api/issues', etag(), (c) =>
-  c.json({
-    enabled: issuesEnabled(),
-    stores: issueStores(),
-    issues: mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, loadSpecsLite().map((s) => s.id)),
-  }))
+app.get('/api/issues', etag(), async (c) => c.json(await issuesReview(c.req.query('q'), c.req.query('page'))))
+// Evals uses the identical paged-review response. `scope:` inside q selects the worktree source; without
+// it the source is the current cached board. Filtering/counts always precede the one 25-row slice.
+app.get('/api/evals', etag(), async (c) => {
+  ensureBoardFileWatchers()
+  const page = await evalsReview(c.req.query('q'), c.req.query('page'), { view: c.req.query('view') })
+  return page ? c.json(page) : c.json({ error: 'no such review source' }, 404)
+})
+// ONE bounded detail response for both source roots: the selected scenario's complete A/B history and at
+// most five lightweight neighbors. It never serializes another scenario's history or the scoped model.
+app.get('/api/evals/detail', etag(), async (c) => {
+  ensureBoardFileWatchers()
+  const node = c.req.query('node')?.trim()
+  const scenario = c.req.query('scenario')?.trim()
+  if (!node || !scenario) return c.json({ error: 'node and scenario are required' }, 400)
+  const detail = await evalDetailReview(node, scenario, c.req.query('scope')?.trim() || null)
+  return detail ? c.json(detail) : c.json({ error: 'no such review source' }, 404)
+})
 // the single-thread read ([[issues]]) behind `spex issue show <id>` — the SAME findIssue lookup, from the
 // resident forge slice (instant view, background reconcile — the list route's freshness contract). A local
 // id, or a forge id (`<host>#<n>`); unknown → 404 (eval-remark threads are not issues, so they 404 here too).
@@ -323,7 +360,7 @@ app.post('/api/remarks/:action{resolve|retract}', async (c) => {
     return c.json({ error: String((e as Error).message || e) }, 400)
   }
 })
-// the dashboard input's `/` dropdown — computed by the launcher's HARNESS adapter the same way that harness
+// the harness slice of the dashboard input's `/` dropdown — computed by the launcher's HARNESS adapter the same way that harness
 // computes its own `/` menu ([[harness-adapter]]). The client passes `?harness=<id>` for the ACTIVE session,
 // so a codex tab gets CODEX's menu, not the default's; unknown/absent → default. Insert-only on the client.
 app.get('/api/slash-commands', (c) => {
@@ -363,18 +400,9 @@ app.post('/api/sessions/edges/unwatch', async (c) => {
   return c.json({ ok }, ok ? 200 : 404)
 })
 app.post('/api/sessions', async (c) => {
-  const body = await c.req.json().catch(() => ({}))
-  const prompt = typeof body?.prompt === 'string' ? body.prompt : ''
-  if (!prompt.trim()) return c.json({ error: 'empty prompt' }, 400)
-  if (typeof body?.harness === 'string') return c.json({ error: 'harness is not a create-session input; use launcher' }, 400)
-  // the named launcher ([[launcher-select]]) — fixes the session's harness AND its persisted launch command.
-  const launcher = typeof body?.launcher === 'string' && body.launcher.trim() ? body.launcher.trim() : undefined
-  // parent = the spawning session's id, resolved by the CALLER (createSession) in its own process and passed
-  // through here ([[session-nesting]]); the browser's New Session omits it → a top-level session.
-  const parent = typeof body?.parent === 'string' && body.parent.trim() ? body.parent.trim() : null
-  try {
-    return c.json(await newSession(typeof body?.node === 'string' ? body.node : null, prompt, parent, launcher), 201)
-  } catch (e) { return c.json({ error: String((e as Error).message || e) }, 400) }   // unknown launcher id → 400, not a 500
+  const body = await c.req.json().catch(() => null)
+  const result = await sessionCreateRequest(body)
+  return result.status === 201 ? c.json(result.session, 201) : c.json({ error: result.error }, 400)
 })
 // one server-side merge bundle (ahead/dirty/diff(merge-base)/gates/proposal) for the manager cockpit;
 // dashboard and `spex session review` are thin callers. 404 for an unknown id. See [[manager-cockpit]].
@@ -382,18 +410,14 @@ app.get('/api/sessions/:id/review', async (c) => {
   const r = await reviewPayload(c.req.param('id'))
   return r ? c.json(r) : c.json({ error: 'no such session' }, 404)
 })
-// the ONE session eval read ([[session-eval]]): default = the lean interactive model — worktree-rooted
-// rows only, no diff enrichment, no inlined bytes (evidence streams lazily from /api/evidence), each
-// reading carrying `inSession` so the tab leads with what THIS session measured. `?format=html` = the
-// EXPORT artifact: one self-contained HTML (diff + gates + evidence inlined as data-URIs) for
-// CI/share/bare-browser — a heavier REPRESENTATION of the same read, not a second route. 404 unknown id.
+// The self-contained HTML is the sole full-model transport exception. Interactive rows, including the CLI,
+// use /api/evals pages; a bare request fails loudly rather than reopening a hidden full JSON path.
 app.get('/api/sessions/:id/evals', async (c) => {
   if (c.req.query('format') === 'html') {
     const m = await buildExportModel(c.req.param('id'))
     return m ? c.html(renderExportHtml(m)) : c.text('no such session', 404)
   }
-  const m = await buildSessionEvals(c.req.param('id'))
-  return m ? c.json(m) : c.json({ error: 'no such session' }, 404)
+  return c.json({ error: 'interactive eval rows use /api/evals pagination; use ?format=html only for export' }, 400)
 })
 // the session's live pane as text (one-shot snapshot) for a backend client (`spex session show --capture`). Empty and fail
 // stay distinct: an empty pane is 200 with empty body; unknown id → 404, offline (no live pane) → 409, error → 502.
@@ -404,6 +428,14 @@ app.get('/api/sessions/:id/capture', async (c) => {
   if (r.reason === 'offline') return c.text('session offline (no live pane)', 409)
   return c.text('capture failed', 502)
 })
+// the session's persisted interaction history ([[session-timeline]]): authored status transitions (with the
+// FULL note text) + delivered prompts, timestamped, oldest first — what a terminal-free surface renders as
+// the conversation. `?limit=<n>` caps the tail (default 500). 404 for an unknown/non-governed id.
+app.get('/api/sessions/:id/timeline', (c) => {
+  const limit = Number(c.req.query('limit'))
+  const r = readTimeline(c.req.param('id'), Number.isFinite(limit) && limit > 0 ? limit : undefined)
+  return r ? c.json(r) : c.json({ error: 'no such session' }, 404)
+})
 // the session RECORD detail (`spex session show`): the board row (status · node · branch · launcher · …)
 // plus the full originating prompt (the row itself carries only the preview). One id-addressed read backs
 // the CLI's show; 404 for an unknown id.
@@ -430,44 +462,88 @@ app.post('/api/sessions/:id/merge', async (c) => {
   return c.json(r, r.dispatched ? 200 : 409)
 })
 
-// one WS over a shared tmux control-mode client (pty-bridge): server→client = raw pane bytes (binary); the
-// view takes no keyboard input, so client→server is only a text control frame — {t:'resize',cols,rows} or
-// {t:'wheel',…}. The bridge resolves the wheel against tmux pane state: copy-mode repaint for normal panes,
-// SGR mouse report injection for mouse-owning TUIs. A real tmux client, so the first paint is one coherent
-// frame and live bytes arrive as events.
+// one WS owns one native tmux client (pty-bridge): server→client = that client's rendered PTY bytes (binary);
+// client→server text controls resize, visibility, and xterm-native input (which carries the mouse/wheel
+// SGR reports xterm produces natively in mouse-report mode). Server→client text commits a completed resize immediately before its binary tmux transaction;
+// hiding starts that viewer's bounded helper release without closing the warm socket. tmux itself resolves wheel input between
+// copy-mode and a mouse-owning TUI. The bridge never splices capture-pane state into this stream.
+// keep-alive ping cadence for the terminal socket — the server half of [[reconnect]]'s heartbeat contract,
+// and the contract's ONE primitive number: the client mirrors it (SERVER_PING_MS in the dashboard's
+// resilientSocket.js, pinned by its test) and DERIVES its silence deadline (2.5×) from it.
+// A healthy link is guaranteed inbound traffic every PING window, so the client may presume an OPEN socket
+// silent past its derived window dead. The same tick also sends a WebSocket protocol ping; browsers answer its
+// pong below JavaScript, so a backend reload stays compatible with a tab running the previous frontend bundle.
+// The server owns that mirror deadline and detaches the viewer itself when a half-open link never reports close.
+// Terminal pixels remain binary frames, so heartbeat controls never enter xterm.
+const TERM_PING_MS = 10000
+const TERM_DEAD_MS = 2.5 * TERM_PING_MS
 app.get('/api/sessions/:id/socket', upgradeWebSocket((c) => {
   const id = c.req.param('id') as string
-  // the size-first handshake: a client that already knows its pane size carries it as ?cols=&rows= so the
-  // first frame is drawn at the true size. Absent/garbage → undefined, and the bridge falls back to prewarm.
-  const qc = Number(c.req.query('cols')), qr = Number(c.req.query('rows'))
-  const initialSize = qc > 0 && qr > 0 ? { cols: qc, rows: qr } : undefined
   let viewer: Viewer | null = null
+  let ping: ReturnType<typeof setInterval> | undefined
+  let pongDeadline: ReturnType<typeof setTimeout> | undefined
+  let cleaned = false
+  const disarmPongDeadline = () => { if (pongDeadline) clearTimeout(pongDeadline); pongDeadline = undefined }
+  let armPongDeadline = () => {}
+  const cleanup = () => {
+    if (cleaned) return
+    cleaned = true
+    if (ping) clearInterval(ping)
+    disarmPongDeadline()
+    if (viewer) detachViewer(id, viewer)
+    viewer = null
+  }
   return {
     onOpen(_evt, ws) {
-      viewer = { send: (buf) => { try { ws.send(Uint8Array.from(buf)) } catch { /* viewer gone */ } } }
-      if (!attachViewer(id, viewer, initialSize)) { try { ws.close() } catch { /* already closed */ } }
+      viewer = {
+        send: (buf) => { try { ws.send(Uint8Array.from(buf)) } catch { /* viewer gone */ } },
+        commitSize: (cols, rows) => { try { ws.send(JSON.stringify({ t: 'resize-commit', cols, rows })) } catch { /* viewer gone */ } },
+      }
+      attachViewer(id, viewer)
+      armPongDeadline = () => {
+        if (cleaned) return
+        disarmPongDeadline()
+        pongDeadline = setTimeout(() => {
+          cleanup()
+          try { ws.close() } catch { /* cleanup already detached the dead viewer */ }
+        }, TERM_DEAD_MS)
+        pongDeadline.unref()
+      }
+      // `raw` is @hono/node-ws's real ws.WebSocket. Protocol pong is intentionally the server-side liveness
+      // signal: unlike an application text reply, every browser generation answers it automatically.
+      ws.raw.on('pong', armPongDeadline)
+      armPongDeadline()
+      ping = setInterval(() => {
+        try { ws.raw.ping() } catch { /* viewer gone; onClose reaps */ }
+        try { ws.send('ping') } catch { /* client dead-man still needs observable inbound traffic */ }
+      }, TERM_PING_MS)
     },
     onMessage(evt) {
       if (!viewer) return
       const data = evt.data
-      // no keyboard input: the only client→server messages are the resize frame and the wheel frame. Binary
-      // is ignored; pane navigation stays inside the tmux bridge instead of becoming browser scroll state.
+      // Binary input is ignored; JSON keeps terminal input distinct from binary pane output while preserving
+      // xterm's ordered string exactly. The bridge accepts input only from this viewer's visible claim.
       if (typeof data === 'string') {
+        if (data === 'pong') {
+          armPongDeadline()
+          return
+        }
         try {
           const m = JSON.parse(data)
-          if (m?.t === 'resize') resizeBridge(id, Number(m.cols), Number(m.rows), !!m.full)
-          else if (m?.t === 'wheel') forwardWheel(id, !!m.up, Number(m.col), Number(m.row), Number(m.ticks))
+          if (m?.t === 'resize') resizeBridge(id, viewer, Number(m.cols), Number(m.rows))
+          else if (m?.t === 'visible' && m.visible === false) hideViewer(id, viewer)
+          else if (m?.t === 'input' && typeof m.data === 'string') forwardInput(id, viewer, m.data)
         } catch { /* ignore */ }
       }
     },
-    onClose() { if (viewer) detachViewer(id, viewer) },
+    onClose() { cleanup() },
   }
 }))
 // ONE input route, `kind` the discriminator — the transport split is an implementation fact, not API surface.
-// kind:"text" (the docked ❯ line, `spex session send`, the server-side merge dispatch) injects a whole prompt
+// kind:"text" (Command Box, `spex session send`, the server-side merge dispatch) injects a whole prompt
 // through the rendezvous control socket — socket-only + fail-loud: a prompt the agent doesn't confirm
 // accepting returns 502 with the reason (never a silent 200), so a dead dispatch is seen, not a false success.
-// kind:"keys" is the LAST-RESORT raw face (`send --keys`, the dashboard's type mode): an ORDERED BATCH of
+// kind:"keys" is the LAST-RESORT raw face (`spex session send --keys`): an ORDERED BATCH of
 // nav-mode key tokens over tmux send-keys, delivered in array order so tap order survives
 // ([[nav-mode-key-ordering]]); unstable by nature — callers try a plain text send first. An unknown kind is a
 // loud 400, never a guessed channel.
@@ -475,8 +551,10 @@ app.post('/api/sessions/:id/input', async (c) => {
   const body = await c.req.json().catch(() => ({}))
   if (body?.kind === 'text') {
     // `from` (the sender's session id) rides only an agent-to-agent send → the backend records the comms
-    // edge ([[comms-edge]]); a raw human dispatch omits it and is not logged.
-    const r = await sendText(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined)
+    // edge ([[comms-edge]]); a raw human dispatch omits it and is not logged. `replyVia:"note"` marks a
+    // terminal-free sender ([[session-timeline]]): the server appends the note-reply insert to the delivery.
+    const r = await sendText(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined,
+      body?.replyVia === 'note' ? { replyVia: 'note' } : {})
     return c.json(r, r.ok ? 200 : 502)
   }
   if (body?.kind === 'keys') {
@@ -513,24 +591,23 @@ app.post('/api/sessions/:id/sort', async (c) => {
 const port = Number(process.env.PORT || 8787)
 // @@@ server-side connection reaping ([[spec-cli]]) - abandoned connections must die SERVER-SIDE, or they
 // pile up and wedge the backend (135 leaked conns once starved :8787 into looking dead — the cascade that
-// triggered the mass-restore incident, since every client-side timeout-kill leaks one). The `serverOptions`
-// timeouts below are kept (harmless), but they are NOT the mechanism: MEASURED (eval
-// server-reaps-abandoned-connections), Node's `headersTimeout`/`requestTimeout` do NOT reap an INCOMPLETE
-// request via the connectionsCheckingInterval sweep — a slow-loris survives indefinitely; only
-// keepAliveTimeout (idle-between-requests) ever fires. So the real reaper is the explicit socket-level
-// `installConnectionReaper` below (see reaper.ts): a per-socket deadline that reaps a slow-loris / idle
-// keep-alive but exempts an ACTIVE WS/SSE stream (board-stream, terminal socket) for as long as it streams.
+// triggered the mass-restore incident, since every client-side timeout-kill leaks one). The ONE mechanism is
+// the socket-level `installConnectionReaper` below (reaper.ts): a per-socket deadline that reaps a
+// slow-loris / idle keep-alive but exempts an ACTIVE WS/SSE stream (board-stream, terminal socket) for as
+// long as it streams. Deliberately NO `serverOptions` timeouts here: they were measured to be not harmless
+// but a second mechanism racing the reaper (issue #65 — a 20s headersTimeout won at default config and
+// silently capped SPEXCODE_REAP_HEADER_MS); the install disables Node's overlapping timeouts so the
+// deadlines have a single owner.
 // @@@ loopback bind ([[public-mode]]) - this child is NEVER the internet face: the supervisor (and in public
 // mode the gateway) fronts it, and dials it only via 127.0.0.1. Binding loopback is what makes "loopback is
 // the trust boundary" true — without a hostname Node binds all interfaces and the child is reachable from
 // the LAN with no password, bypassing the gate entirely (measured: eval auth-boundary).
-const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1', serverOptions: {
-  keepAliveTimeout: 10000, headersTimeout: 20000, requestTimeout: 60000, connectionsCheckingInterval: 10000,
-} })
+const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' })
 installConnectionReaper(server as unknown as HttpServer)
 injectWebSocket(server)
-superviseBridges()   // keep a warm tmux client per live session, so opening a tab is instant
+superviseBridges()   // restore visible helpers after failure; their viewer subscriptions survive replacement
 superviseQueue()     // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
+superviseTimeline()  // record authored-lifecycle transitions to each session's durable timeline ([[session-timeline]])
 console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`)
 
 // graceful drain (the other half of zero-downtime reload, supervise.ts): on SIGTERM stop accepting new