spexcode 0.1.5 → 0.2.0

package/spec-cli/src/index.ts

@@ -1,17 +1,26 @@
 import { serve } from '@hono/node-server'
 import { Hono } from 'hono'
 import { cors } from 'hono/cors'
+import { etag } from 'hono/etag'
 import { createNodeWebSocket } from '@hono/node-ws'
-import { loadSpecs, specHistory, specDiffAt, loadConfig } from './specs.js'
+import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig } from './specs.js'
+import { issuesEnabled, postLocalIssue, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
+import { closeIssue, mergedIssues, replyIssue } from './issues.js'
+import { residentForgeState, refreshForgeNow } from '../../spec-forge/src/resident.js'
+import { summarize } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
-import { buildBoard } from './board.js'
-import { gitA, gitTry } from './git.js'
-import { newSession, listSessions, sendKeys, rawKey, exitSession, closeSession, reopen, propose, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, superviseQueue } from './sessions.js'
-import { defaultHarness, HARNESSES } from './harness.js'
+import { getBoardJson } from './boardCache.js'
+import { boardStream, notifyBoardChanged } from './boardStream.js'
+import { gitA, gitTry, repoRoot } from './git.js'
+import { newSession, listSessions, sendKeys, rawKey, exitSession, closeSession, reopen, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, superviseQueue } from './sessions.js'
+import { defaultHarness, HARNESSES, launcherList, defaultLauncher } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-yatsu/src/evaltab.js'
-import { buildProofModel, renderProofHtml } from '../../spec-yatsu/src/proof.js'
+import { putBlob } from '../../spec-yatsu/src/cache.js'
+import { yatsuNodes } from '../../spec-yatsu/src/yatsu.js'
+import { fileHumanReading } from '../../spec-yatsu/src/filing.js'
+import { buildProofModel, renderProofHtml, buildSessionEvals } from '../../spec-yatsu/src/proof.js'
 import { saveUpload, MAX_UPLOAD_BYTES } from './uploads.js'
-import { attachViewer, detachViewer, writeViewer, resizeBridge, superviseBridges, type Viewer } from './pty-bridge.js'
+import { attachViewer, detachViewer, resizeBridge, forwardWheel, superviseBridges, type Viewer } from './pty-bridge.js'
 import { installProcessGuards } from './resilience.js'
 
 // last-resort net: an unforeseen async throw (e.g. a worktree vanishing mid-read during a worker
@@ -27,9 +36,47 @@ app.get('/', (c) => c.text('spec-cli — GET /api/board · /api/specs · /api/sp
 // instant Hono is listening. Not under /api/* — loopback-only (supervisor→child), no CORS needed.
 app.get('/health', (c) => c.text('ok'))
 // the assembled board (merged tree + overlay + sessions) — the dashboard's single source. Same data
-// as `spex board`; the frontend only adds x/y pixels on top.
-app.get('/api/board', async (c) => c.json(await buildBoard()))
+// as `spex board`; the frontend only adds x/y pixels on top. Freshness is PUSH-first ([[board-stream]]): the
+// dashboard reloads on a `/api/board/stream` event, not a tight poll, so the route is a conditional-request
+// endpoint: `etag()` hashes the serialized body, and a reload whose `If-None-Match` matches gets a bodyless 304
+// instead of the full transfer (~1 MB on the dogfood board — it scales with the node count). The 304 saves the
+// WIRE only; the COMPUTE is saved by [[board-cache]]: getBoard() is single-flight + cached, so a poll storm
+// shares ONE build instead of each running its own — the poll-frequency cut (push channel) and the
+// build-coalescing cut compound. A hard timeout bounds a wedged build to a loud 503 rather than an
+// unboundedly-held connection (the wall sits well above the legitimately-several-seconds cold first build);
+// the underlying single-flight build keeps running and caches for the next poll.
+const BOARD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_TIMEOUT_MS || 20000)
+app.get('/api/board', etag(), async (c) => {
+  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: 'board build timed out' }, 503)
+  return c.body(json as string, 200, { 'content-type': 'application/json; charset=UTF-8' })
+})
+// the board's push channel: an SSE that fires `board-changed` on any session-store write, so the dashboard
+// reloads the instant status moves instead of waiting for its slow fallback poll ([[board-stream]]).
+app.get('/api/board/stream', (c) => boardStream(c))
 app.get('/api/specs', async (c) => c.json(await loadSpecs()))
+// the search corpus ([[board-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 yatsu
+// 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(yatsuNodes(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
+  }))
+})
+// one node's body + parsed parts ([[board-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) => {
+  const x = specContent(c.req.param('id'))
+  return x ? c.json(x) : c.json({ body: '', parts: null }, 404)
+})
 app.get('/api/specs/:id/history', async (c) => c.json(await specHistory(c.req.param('id'))))
 // the spec.md line diff one version introduced — the history tab's per-version proof-of-change, fetched
 // lazily when an older version's item expands (the latest version's diff ships with the board as node.lastDiff).
@@ -53,18 +100,162 @@ app.get('/api/edit', async (c) => {
 // a node's eval timeline (read half of `spex yatsu`): yatsu-sidecar readings joined with a live freshness
 // flag, newest-first; `hasYatsu:false` when none declared. Contract belongs to [[spec-yatsu]].
 app.get('/api/specs/:id/evals', async (c) => c.json(await evalTimeline(c.req.param('id'))))
+// the eval seam's WRITE half over HTTP ([[spec-yatsu]] filing.ts): a programmatic caller files a manual@1
+// reading (verdict + optional transcript) through the SAME append the CLI uses. The dashboard does not
+// call this — [[event-detail]] reads readings and hosts remarks, never files.
+app.post('/api/specs/:id/yatsu/eval', async (c) => {
+  const b = await c.req.json().catch(() => null)
+  if (!b || typeof b.scenario !== 'string') return c.json({ error: 'body needs { scenario, status, note?, transcript? }' }, 400)
+  const r = fileHumanReading(c.req.param('id'), b)
+  return r.ok ? c.json({ ok: true, reading: r.reading }) : c.json({ error: r.error }, 400)
+})
 // serve a reading's evidence blob by content hash (bytes never enter git): bad hash → 400, missing → 404,
 // 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.
 app.get('/api/yatsu/blob/:hash', (c) => {
   const r = readBlobByHash(c.req.param('hash'))
   if (!r.ok) return c.text(r.message, r.reason === 'invalid' ? 400 : 404)
-  return c.body(new Uint8Array(r.bytes), 200, { 'Content-Type': r.mime, 'Cache-Control': 'public, max-age=31536000, immutable' })
+  const total = r.bytes.length
+  const base = { 'Content-Type': r.mime, 'Cache-Control': 'public, max-age=31536000, immutable', 'Accept-Ranges': 'bytes' }
+  const m = /^bytes=(\d*)-(\d*)$/.exec(c.req.header('range') ?? '')
+  if (m && (m[1] || m[2])) {
+    const start = m[1] ? parseInt(m[1], 10) : total - parseInt(m[2], 10)
+    const end = m[1] && m[2] ? Math.min(parseInt(m[2], 10), total - 1) : total - 1
+    if (!(start >= 0 && start <= end && end < total)) return c.body(null, 416, { 'Content-Range': `bytes */${total}` })
+    return c.body(new Uint8Array(r.bytes.subarray(start, end + 1)), 206, { ...base, 'Content-Range': `bytes ${start}-${end}/${total}` })
+  }
+  return c.body(new Uint8Array(r.bytes), 200, base)
+})
+// the WRITE half of the blob store ([[annotator]]): the annotator captures a circled video frame to a PNG
+// and stashes the bytes here, content-addressed (same putBlob the yatsu cache uses). The returned hash is
+// what an anchored comment references (image link in the body, and the typed evidence[] on its thread) —
+// bytes never enter git. Raw body, sniffed by the same content-addressed name. Empty → 400, over cap → 413.
+app.post('/api/yatsu/blob', async (c) => {
+  const buf = Buffer.from(await c.req.arrayBuffer())
+  if (buf.length === 0) return c.json({ error: 'empty blob' }, 400)
+  if (buf.length > MAX_UPLOAD_BYTES) return c.json({ error: 'blob too large' }, 413)
+  return c.json({ hash: putBlob(buf) }, 201)
 })
 app.get('/api/layout', async (c) => c.json(await resolveLayout()))
-// the `surface: slash` config-root plugins (built/active only) for the new-session `/` dropdown — each with
+// the `surface: command` config-root plugins (built/active only) for the new-session `/` dropdown — 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/config', (c) => c.json(loadConfig()))
+// 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 new` uses (the CLI/config default), instead of the
+// alphabetically-first one. `launchers` is empty (and `default` '') when a project configured none, so the form
+// falls back to the plain harness picker.
+app.get('/api/launchers', (c) => c.json({
+  launchers: launcherList().map(({ name, harness }) => ({ name, harness })),
+  default: defaultLauncher(),
+}))
+// 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(),
+    issues: mergedIssues({ host: 'github', state: residentForgeState() }, loadSpecsLite().map((s) => s.id)),
+  }))
+// the WRITE surface ([[local-issues]] / [[issues-view]]) — the human reply path, STORE-ROUTED through the one
+// reply verb ([[issues]] replyIssue): a local id git-commits to the trunk store, a forge id ('github#N')
+// posts a REAL comment through the driver; either way the text's @-mentions dispatch (a human summons an
+// agent from the issues page). `outcomes` is the one-line @-dispatch summary the dashboard echoes. The
+// server owns its freshness: a forge write forces the resident slice's read-back before answering, so the
+// reload that follows shows the comment. Honor the on/off switch: 403 when the feature is OFF; an unknown
+// local thread → 404; a failed forge write → 502 with the driver's own message (fail loud, never queued).
+app.post('/api/issues/:id/reply', async (c) => {
+  if (!issuesEnabled()) return c.json({ error: 'issues workflow is off' }, 403)
+  const body = await c.req.json().catch(() => ({}))
+  const text = typeof body?.body === 'string' ? body.body : ''
+  if (!text.trim()) return c.json({ error: 'empty reply' }, 400)
+  // typed evidence[] — an anchored annotation's frame-blob hashes accrue onto the local thread (same shape
+  // as the create route); a forge reply ignores them (its frame rides the comment body's image link).
+  const evidence = Array.isArray(body?.evidence) ? (body.evidence as unknown[]).filter((h): h is string => typeof h === 'string' && /^[0-9a-f]{64}$/.test(h)) : []
+  const id = c.req.param('id')
+  try {
+    // the mention prompt's node context, from the same resident merge the GET serves
+    const node = id.includes('#')
+      ? mergedIssues({ host: 'github', state: residentForgeState() }, loadSpecsLite().map((s) => s.id)).find((i) => i.id === id)?.nodes[0] ?? null
+      : null
+    const r = await replyIssue(id, text, { author: 'human', node, evidence })
+    if (r.store !== 'local') await refreshForgeNow()
+    return c.json({ ok: true, replies: r.replies, url: r.url, outcomes: summarize(r.outcomes, r.loopIn) })
+  } catch (e) {
+    const msg = String((e as Error).message || e)
+    return c.json({ error: msg }, id.includes('#') ? 502 : 404)
+  }
+})
+// store-routed lifecycle close ([[issues]]): local resolves the local thread, forge closes the remote
+// issue through the driver. A forge close forces read-back before the dashboard reloads the resident list.
+app.post('/api/issues/:id/close', async (c) => {
+  if (!issuesEnabled()) return c.json({ error: 'issues workflow is off' }, 403)
+  const id = c.req.param('id')
+  try {
+    const r = await closeIssue(id)
+    if (r.store !== 'local') await refreshForgeNow()
+    return c.json({ ok: true, ...r })
+  } catch (e) {
+    const msg = String((e as Error).message || e)
+    return c.json({ error: msg }, id.includes('#') ? 502 : 404)
+  }
+})
+app.post('/api/issues', async (c) => {
+  if (!issuesEnabled()) return c.json({ error: 'issues workflow is off' }, 403)
+  const body = await c.req.json().catch(() => ({}))
+  const concern = typeof body?.concern === 'string' ? body.concern.trim() : ''
+  if (!concern) return c.json({ error: 'empty concern' }, 400)
+  const nodes = Array.isArray(body?.nodes) ? (body.nodes as unknown[]).filter((n): n is string => typeof n === 'string') : []
+  const postBody = typeof body?.body === 'string' ? body.body : undefined
+  // typed evidence[] — yatsu content-addressed hashes (the annotator's clip reference rides here, not prose)
+  const evidence = Array.isArray(body?.evidence) ? (body.evidence as unknown[]).filter((h): h is string => typeof h === 'string' && /^[0-9a-f]{64}$/.test(h)) : []
+  const { thread, outcomes } = await postLocalIssue(concern, { nodes, body: postBody, evidence, author: 'human' })
+  return c.json({ ok: true, id: thread.id, outcomes: summarize(outcomes) }, 201)
+})
+
+// the REMARK write surface ([[remark-substrate]]) — server PARITY with the CLI: the dashboard can author /
+// resolve / retract a remark through the SAME functions `spex remark|resolve|retract` call, adding no
+// capability. A ref (`<thread-id>#<rid>`) rides the request BODY, not the path (a '#' in a URL is a
+// fragment). Identity is derived SERVER-SIDE — this is the dashboard's human surface, so the actor is
+// `'human'`, the SAME sentinel /api/issues stamps; it is NEVER read from the request body. That keeps R3's
+// teeth structural (identity is not spoofable over the wire) and honest on both surfaces: resolve rejects
+// `'human'` (agent-only — an agent resolves through the CLI, never the dashboard), and retract binds to the
+// human who authored (only their own `'human'` remarks). Who-may-resolve/retract cannot depend on transport.
+app.post('/api/remarks', async (c) => {
+  if (!issuesEnabled()) return c.json({ error: 'issues workflow is off' }, 403)
+  const body = await c.req.json().catch(() => ({}))
+  const text = typeof body?.body === 'string' ? body.body : ''
+  if (!text.trim()) return c.json({ error: 'empty remark' }, 400)
+  const evidence = Array.isArray(body?.evidence) ? (body.evidence as unknown[]).filter((h): h is string => typeof h === 'string' && /^[0-9a-f]{64}$/.test(h)) : []
+  const host = typeof body?.scenario === 'string' && body.scenario
+    ? { node: typeof body?.node === 'string' ? body.node : undefined, scenario: body.scenario as string }
+    : { issue: typeof body?.issue === 'string' ? body.issue : undefined }
+  const codeSha = typeof body?.codeSha === 'string' ? body.codeSha : undefined
+  try {
+    const r = await remarkOnHost(host, text, { codeSha, author: 'human', evidence })
+    return c.json({ ok: true, ref: r.ref, rid: r.rid, codeSha: r.codeSha, outcomes: summarize(r.outcomes, r.loopIn) }, 201)
+  } catch (e) {
+    return c.json({ error: String((e as Error).message || e) }, 400)
+  }
+})
+app.post('/api/remarks/:action{resolve|retract}', async (c) => {
+  if (!issuesEnabled()) return c.json({ error: 'issues workflow is off' }, 403)
+  const body = await c.req.json().catch(() => ({}))
+  const ref = typeof body?.ref === 'string' ? body.ref : ''
+  if (!ref) return c.json({ error: 'missing remark ref' }, 400)
+  const by = 'human'   // server-derived identity — never the request body (see /api/remarks above)
+  try {
+    if (c.req.param('action') === 'resolve') resolveRemark(ref, by)
+    else retractRemark(ref, by)
+    return c.json({ ok: true, ref })
+  } catch (e) {
+    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
 // 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.
@@ -109,9 +300,14 @@ app.post('/api/sessions', async (c) => {
   const prompt = typeof body?.prompt === 'string' ? body.prompt : ''
   if (!prompt.trim()) return c.json({ error: 'empty prompt' }, 400)
   const harness = typeof body?.harness === 'string' ? body.harness : undefined
+  // 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, harness), 201)
-  } catch (e) { return c.json({ error: String((e as Error).message || e) }, 400) }   // unknown harness id → 400, not a 500
+    return c.json(await newSession(typeof body?.node === 'string' ? body.node : null, prompt, harness, parent, launcher), 201)
+  } catch (e) { return c.json({ error: String((e as Error).message || e) }, 400) }   // unknown harness/launcher id → 400, not a 500
 })
 // one server-side merge bundle (ahead/dirty/diff(merge-base)/gates/proposal) for the manager cockpit;
 // dashboard and `spex review` are thin callers. 404 for an unknown id. See [[manager-cockpit]].
@@ -119,14 +315,22 @@ 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 [[review-proof]] HTML: the diff grouped by node, each node's measured yatsu loss with evidence inlined
-// as data-URIs, and the merge gates. `?format=json` returns the model; default = rendered HTML. 404 unknown id.
+// the [[review-proof]] EXPORT artifact: one self-contained HTML (diff + gates + evidence inlined as
+// data-URIs) for CI/share/bare-browser. `?format=json` returns the model; default = rendered HTML. The
+// dashboard's interactive face is the lean route below, never this. 404 unknown id.
 app.get('/api/sessions/:id/proof', async (c) => {
   const m = await buildProofModel(c.req.param('id'))
   if (!m) return c.text('no such session', 404)
   if (c.req.query('format') === 'json') return c.json(m)
   return c.html(renderProofHtml(m))
 })
+// the session EVAL model ([[review-proof]]'s interactive face): worktree-rooted rows only — no diff
+// enrichment, no inlined bytes; evidence streams lazily from /api/yatsu/blob. Each reading carries
+// `inSession` so the tab leads with what THIS session measured.
+app.get('/api/sessions/:id/evals', async (c) => {
+  const m = await buildSessionEvals(c.req.param('id'))
+  return m ? c.json(m) : c.json({ error: 'no such session' }, 404)
+})
 // the session's live pane as text (one-shot snapshot) for a backend client (`spex capture`). Empty and fail
 // stay distinct: an empty pane is 200 with empty body; unknown id → 404, offline (no live pane) → 409, error → 502.
 app.get('/api/sessions/:id/capture', async (c) => {
@@ -142,8 +346,15 @@ app.get('/api/sessions/:id/prompt', async (c) => {
   return p == null ? c.text('no prompt recorded', 404) : c.text(p)
 })
 // lifecycle transitions (thin callers of the session state machine)
-app.post('/api/sessions/:id/resume', async (c) => c.json({ ok: await reopen(c.req.param('id')) }))   // back-to-working / relaunch
-app.post('/api/sessions/:id/review', async (c) => c.json({ ok: await propose(c.req.param('id'), 'merge') }))
+// relaunch ONLY if confirmed offline; demotes working→idle, keeps any declaration. The RESUME GUARD refuses
+// (409) when the agent is alive or its liveness is unproven — restore-on-alive was the incident's kill-shot.
+// `force` (query ?force=1 or JSON {force:true}) overrides for a wedged-but-alive process.
+app.post('/api/sessions/:id/resume', async (c) => {
+  const body = await c.req.json().catch(() => ({} as { force?: boolean }))
+  const force = body?.force === true || c.req.query('force') === '1'
+  const r = await reopen(c.req.param('id'), { force })
+  return c.json(r, r.ok ? 200 : (r.refused ? 409 : 404))
+})
 // a dispatch to the session's own agent (it runs the merge), never a server merge — the server never touches
 // main's tree. 200 {dispatched:true} once the prompt is accepted, 409 {dispatched:false} if the agent is unreachable.
 app.post('/api/sessions/:id/merge', async (c) => {
@@ -151,27 +362,34 @@ app.post('/api/sessions/:id/merge', async (c) => {
   return c.json(r, r.dispatched ? 200 : 409)
 })
 
-// one bidirectional WS over a shared tmux client (pty-bridge): server→client = raw pane bytes (binary);
-// client→server = raw terminal input (binary) + a text control frame {t:'resize',cols,rows}. A real tmux
-// client, so scrollback is tmux's own and the first paint is one coherent repaint.
+// 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.
 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
   return {
     onOpen(_evt, ws) {
       viewer = { send: (buf) => { try { ws.send(Uint8Array.from(buf)) } catch { /* viewer gone */ } } }
-      if (!attachViewer(id, viewer)) { try { ws.close() } catch { /* already closed */ } }
+      if (!attachViewer(id, viewer, initialSize)) { try { ws.close() } catch { /* already closed */ } }
     },
     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.
       if (typeof data === 'string') {
-        // text frame = control. Only resize today.
-        try { const m = JSON.parse(data); if (m?.t === 'resize') resizeBridge(id, Number(m.cols), Number(m.rows)) } catch { /* ignore */ }
-      } else if (data instanceof ArrayBuffer) {
-        writeViewer(id, Buffer.from(data))                              // binary: raw terminal input
-      } else if (ArrayBuffer.isView(data)) {
-        writeViewer(id, Buffer.from(data.buffer, data.byteOffset, data.byteLength))  // (keystrokes / mouse)
+        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))
+        } catch { /* ignore */ }
       }
     },
     onClose() { if (viewer) detachViewer(id, viewer) },
@@ -187,11 +405,14 @@ app.post('/api/sessions/:id/keys', async (c) => {
   const r = await sendKeys(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined)
   return c.json(r, r.ok ? 200 : 502)
 })
-// the preserved tmux send-keys path (distinct from the ❯ prompt socket): one key per keydown so a human can
-// drive the agent's interactive TUI menus in real time. Forwards keystrokes only.
+// the preserved tmux send-keys path (distinct from the ❯ prompt socket): the human drives the agent's
+// interactive TUI menus in real time. Accepts an ORDERED BATCH (`keys`, the client coalesces fast typing) or a
+// single `key`; rawKey delivers them in array order so tap order is preserved ([[nav-mode-key-ordering]]).
 app.post('/api/sessions/:id/rawkey', async (c) => {
   const body = await c.req.json().catch(() => ({}))
-  const ok = await rawKey(c.req.param('id'), typeof body?.key === 'string' ? body.key : '')
+  const keys = Array.isArray(body?.keys) ? body.keys.filter((k: unknown) => typeof k === 'string')
+    : typeof body?.key === 'string' ? [body.key] : []
+  const ok = await rawKey(c.req.param('id'), keys)
   return c.json({ ok }, ok ? 200 : 404)
 })
 // soft stop: kill the agent's tmux + socket but KEEP the worktree (relaunchable). Distinct from close, which
@@ -199,10 +420,12 @@ app.post('/api/sessions/:id/rawkey', async (c) => {
 app.post('/api/sessions/:id/exit', async (c) => c.json({ ok: await exitSession(c.req.param('id')) }))
 app.post('/api/sessions/:id/close', async (c) => c.json({ ok: await closeSession(c.req.param('id')) }))
 // set (or clear, with a blank) a session's display-name override; persists to the worktree's `.session` so
-// it survives a restart. Unknown id → 404.
+// it survives a restart. Unknown id → 404. The worktree file is OUTSIDE the store the board watchers see,
+// so the route nudges the stream explicitly ([[board-stream]]) — the rename shows in ~150ms, not a cold tick.
 app.post('/api/sessions/:id/rename', async (c) => {
   const body = await c.req.json().catch(() => ({}))
   const ok = await renameSession(c.req.param('id'), typeof body?.name === 'string' ? body.name : '')
+  if (ok) notifyBoardChanged()
   return c.json({ ok }, ok ? 200 : 404)
 })
 
@@ -216,7 +439,24 @@ app.post('/api/sessions/:id/sort', async (c) => {
 })
 
 const port = Number(process.env.PORT || 8787)
-const server = serve({ fetch: app.fetch, port })
+// @@@ 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). keepAliveTimeout
+// reaps an idle keep-alive socket; headersTimeout a slow-header/slow-loris; requestTimeout a request whose
+// body never completes. These reap IDLE/STALLED sockets only — an ACTIVE WS/SSE response is not "keep-alive
+// idle", so the board-stream SSE and the terminal socket are untouched. requestTimeout bounds RECEIVING a
+// request only (not the response), so a slow board build or a streaming SSE/WS response is never cut. Node
+// enforces these on a periodic sweep whose cadence (connectionsCheckingInterval) is armed AT CONSTRUCTION —
+// so they MUST ride `serverOptions` (setting them post-`serve()` leaves the sweep on its 30s default and the
+// change under-effective); a 10s sweep makes reaping land within timeout+10s, well under the multi-minute
+// defaults (requestTimeout 300s) that let the conns accumulate. headersTimeout > keepAliveTimeout (Node's rule).
+// @@@ 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: yatsu auth-boundary).
+const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1', serverOptions: {
+  keepAliveTimeout: 10000, headersTimeout: 20000, requestTimeout: 60000, connectionsCheckingInterval: 10000,
+} })
 injectWebSocket(server)
 superviseBridges()   // keep a warm tmux client per live session, so opening a tab is instant
 superviseQueue()     // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)

package/spec-cli/src/init.ts

@@ -2,12 +2,22 @@ import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, chmodSync }
 import { join, resolve, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
+import { readConfig } from './layout.js'
+import { resolveHarnessTargets } 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).
 const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
 const TEMPLATES = join(pkgRoot, 'templates')
 
+// the cumulative preset chain, lean → cautious (see [[init-preset]]). `default` is the live `.config`
+// instance set (planted from templates/spec); every higher tier is a SEPARATE package under
+// templates/presets/<tier>/ that seeding stacks ON TOP — a superset, so selecting `careful` seeds the
+// default set PLUS the careful package. Selection matters ONLY here at seed time; the running repo just
+// walks whatever `.config` ended up planted, so there is no launcher-side preset gate.
+const PRESET_TIERS = ['default', 'careful'] as const
+const presetRank = (name: string): number => (PRESET_TIERS as readonly string[]).indexOf(name)
+
 // recursively copy srcDir -> destDir, NEVER overwriting an existing file. Returns the repo-relative
 // paths of files actually written (so the caller can report exactly what was planted vs already there).
 function copyTreeNoClobber(srcDir: string, destDir: string, base: string): string[] {
@@ -43,9 +53,18 @@ function resolveHooksDir(dir: string): string | null {
   }
 }
 
-export async function specInit(targetArg: string | undefined): Promise<void> {
+export async function specInit(targetArg: string | undefined, presetArg?: 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
+  // `preset` field, else the lean `default`. Validated loudly against the chain (an unknown name would
+  // otherwise seed silently). A non-default tier stacks its template package on top of the default set below.
+  const selected = (presetArg ?? '').trim() || (readConfig(targetDir).preset ?? '').trim() || 'default'
+  if (!(PRESET_TIERS as readonly string[]).includes(selected)) {
+    console.error(`spex init: unknown preset '${selected}'. Valid presets (cumulative, lean→cautious): ${PRESET_TIERS.join(', ')}.`)
+    process.exit(1)
+  }
+
   // SpexCode is git-backed: git IS the version database and the hooks live in `.git`. A non-git target
   // would leave a HALF-STATE — specs on disk but no version history, no hooks, no harness shims, no
   // sessions. So fail LOUD before writing anything, rather than seeding debris and warning past it. We do
@@ -68,6 +87,16 @@ export async function specInit(targetArg: string | undefined): Promise<void> {
   } else {
     const planted = copyTreeNoClobber(join(TEMPLATES, 'spec'), specDest, targetDir)
     console.log(`✓ seeded ${planted.length} spec file(s) under .spec/ (root 'project' node + default .config)`)
+    // 1a. stack the selected preset's package(s) ON TOP of the default set — cumulative, so every tier from
+    // just above `default` up to the selection is planted. Each lives under templates/presets/<tier>/ mirroring
+    // the default layout (its `.config/<plugin>` lands in the seeded project node's `.config`). See [[init-preset]].
+    for (let r = 1; r <= presetRank(selected); r++) {
+      const tier = PRESET_TIERS[r]
+      const pkg = join(TEMPLATES, 'presets', tier)
+      if (!existsSync(pkg)) { console.warn(`• preset '${tier}' has no package at ${pkg} — skipped.`); continue }
+      const added = copyTreeNoClobber(pkg, join(specDest, 'project'), targetDir)
+      console.log(`✓ seeded preset '${tier}' (${added.length} file(s)) into .config`)
+    }
   }
 
   // 1b. plant a starter spexcode.json (the lint/layout knob), pointing governedRoots at `src/`.
@@ -79,6 +108,17 @@ export async function specInit(targetArg: string | undefined): Promise<void> {
     console.log(`✓ planted spexcode.json — set lint.governedRoots to YOUR source dirs (starter: ["src"])`)
   }
 
+  // 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)
+  }
+
   // 2. install the git hooks: templates/hooks/* -> <repo>/<common-git-dir>/hooks/* (skip any that exist).
   const hooksDir = resolveHooksDir(targetDir)
   if (!hooksDir) {