spexcode 0.4.1 → 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

@@ -13,20 +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.
@@ -34,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
@@ -53,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)
@@ -64,23 +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, test}), so a measurable
-// node's row here carries its declared scenarios' description/expected (+ test reference and 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.test ? { test: s.test } : {}),
-          ...(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) => {
@@ -136,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' }
@@ -163,17 +175,23 @@ 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.
 // `?surface=review` lists the review-track presets instead ([[review-commands]] — the eval detail's
@@ -183,12 +201,24 @@ app.get('/api/plugins', (c) => c.json(c.req.query('surface') === 'review' ? load
 // (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).
@@ -330,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) => {
@@ -370,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]].
@@ -389,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.
@@ -445,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.
@@ -530,23 +591,21 @@ 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}`)

package/spec-cli/src/init.ts

@@ -3,7 +3,7 @@ import { join, resolve, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
-import { resolveHarnessTargets } from './harness-select.js'
+import { resolveHarnessTargets, parseHarnessFlag, NATIVE_HARNESS_IDS } from './harness-select.js'
 
 // this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
 // launch paths use, never a hardcoded repo path (so a relocated/installed package still finds its data).
@@ -54,7 +54,7 @@ function resolveHooksDir(dir: string): string | null {
   }
 }
 
-export async function specInit(targetArg: string | undefined, presetArg?: string): Promise<void> {
+export async function specInit(targetArg: string | undefined, presetArg?: string, harnessArg?: string): Promise<void> {
   const targetDir = resolve(targetArg ?? process.cwd())
 
   // the preset the NEW adopter gets — `--preset <name>` wins, else an existing target spexcode.json's
@@ -78,6 +78,24 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     process.exit(1)
   }
 
+  // the harness DELIVERY TARGET set ([[harness-select]]) is a REQUIRED, explicit choice — `--harness <ids>`
+  // stamps it into spexcode.json; absent the flag, a pre-existing explicit `harnesses` field IS the choice.
+  // Neither → abort BEFORE writing anything: with many harnesses, a silent "deliver to all" would litter the
+  // adopter's tree (and global tool configs) with artifacts for harnesses they never installed. Legality
+  // (unknown ids, plugin exclusivity, empty set) fails loud here too, not as a soft materialize warning.
+  const flagRaw = (harnessArg ?? '').trim() ? parseHarnessFlag(harnessArg!.trim()) : null
+  const chosenHarnesses = flagRaw ?? readConfig(targetDir).harnesses ?? null
+  if (chosenHarnesses === null) {
+    console.error(`spex init: --harness is required — name the harness(es) this repo delivers into, e.g. \`spex init --harness claude\`. Known native ids: ${NATIVE_HARNESS_IDS.join(', ')} (comma-separate several; a plugin bundle: --harness plugin:<folder>). A pre-existing spexcode.json "harnesses" field also satisfies this.`)
+    process.exit(1)
+  }
+  try {
+    resolveHarnessTargets(chosenHarnesses)
+  } catch (e) {
+    console.error(`spex init: ${(e as Error).message}`)
+    process.exit(1)
+  }
+
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true })
   console.log(`spex init → ${targetDir}`)
 
@@ -100,27 +118,35 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     }
   }
 
-  // 1b. plant a starter spexcode.json (the lint/layout knob). The success message reports the value the
-  // template ACTUALLY ships (read from the planted file, never restated as a string literal here — the two
-  // once drifted: the message claimed ["src"] while the template seeded ["."]).
+  // 1b. plant a starter spexcode.json (the lint/layout knob) carrying the CHOSEN `harnesses` set. The
+  // template ships launchers for every native harness; seeding keeps only the SELECTED ones (a launcher for
+  // a tool the adopter didn't pick is exactly the litter --harness exists to prevent) — a plugin-only
+  // selection keeps them all, since the bundle serves the HOST agent while dispatched sessions still need a
+  // launcher. The success message reports values read back from the planted file, never restated literals.
   const cfgDest = join(targetDir, 'spexcode.json')
+  const nativeChosen = (chosenHarnesses as unknown[]).filter((m): m is string => typeof m === 'string')
   if (existsSync(cfgDest)) {
-    console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched.`)
+    if (flagRaw) {
+      // an explicit --harness on a re-init is a deliberate command: restamp THAT field, touch nothing else.
+      const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
+      cfg.harnesses = flagRaw
+      writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
+      console.log(`✓ stamped "harnesses": ${JSON.stringify(flagRaw)} into the existing spexcode.json (other fields untouched)`)
+    } else {
+      console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched (harnesses: ${JSON.stringify(chosenHarnesses)}).`)
+    }
   } else {
-    copyFileSync(join(TEMPLATES, 'spexcode.json'), cfgDest)
+    const cfg = (readJsonConfig(join(TEMPLATES, 'spexcode.json')) ?? {}) as Record<string, any>
+    cfg.harnesses = chosenHarnesses
+    if (nativeChosen.length && cfg.sessions?.launchers) {
+      cfg.sessions.launchers = Object.fromEntries(
+        Object.entries(cfg.sessions.launchers as Record<string, { harness?: string }>).filter(([, l]) => nativeChosen.includes(l.harness ?? 'claude')))
+      const names = Object.keys(cfg.sessions.launchers)
+      if (names.length) cfg.sessions.defaultLauncher = names[0]
+    }
+    writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
     const roots = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
-    console.log(`✓ planted spexcode.json — lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded); curate explicit roots later if you want a narrower graph`)
-  }
-
-  // validate the harness DELIVERY TARGET set ([[harness-select]]) up front: a bad `harnesses` set (plugin +
-  // native, or a plugin with no folder) must fail LOUD here, not be silently swallowed by the materialize
-  // try/catch below. A fresh starter spexcode.json omits the field (defaults to all natives), so this only
-  // bites a hand-edited or re-init'd config — exactly where a clear error belongs.
-  try {
-    resolveHarnessTargets(readConfig(targetDir).harnesses)
-  } catch (e) {
-    console.error(`spex init: ${(e as Error).message}`)
-    process.exit(1)
+    console.log(`✓ planted spexcode.json — harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
   }
 
   // 2. install the git hooks: templates/hooks/* -> <repo>/<common-git-dir>/hooks/* (skip any that exist).
@@ -145,18 +171,20 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     if (installed.length) console.log(`✓ installed git hooks (${installed.join(', ')}) → ${hooksDir}`)
   }
 
-  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched claude/codex works with zero further
-  // steps: the hook manifest (in the GLOBAL per-project store, not the worktree), the AGENTS.md/CLAUDE.md
-  // <spexcode> contract block (user content preserved), the .claude/.codex shims, and the Codex trust (global,
-  // scoped) so codex self-launch is prompt-free. Runs with cwd = the target so the loaders read the just-seeded
+  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched harness works with zero further
+  // steps. Runs with cwd = the target so the loaders read the just-seeded
   // .plugins. Idempotent — the planted git hooks (pre-commit/post-checkout/post-merge) keep it fresh
   // thereafter on the git-native anchors ([[commit-surgery]]); no harness event ever triggers a materialize.
   const prevCwd = process.cwd()
   try {
     process.chdir(targetDir)
     const { materialize } = await import('./materialize.js')
-    materialize(targetDir)
-    console.log('✓ materialized harness artifacts (global hook manifest, AGENTS.md/CLAUDE.md block, harness shims, Codex trust)')
+    const result = materialize(targetDir)
+    const display = (path: string) => {
+      const local = relative(targetDir, path)
+      return local && local !== '..' && !local.startsWith('../') && !local.startsWith('..\\') ? local : path
+    }
+    console.log(`✓ materialized harness artifacts (${result.planted.map((a) => `${a.kind}: ${display(a.path)}`).join(', ')})`)
   } catch (e) {
     console.warn(`• materialize skipped (${(e as Error).message}) — run \`spex materialize\` once the packages are installed.`)
   } finally {