spexcode 0.2.8 → 0.3.0

package/spec-cli/src/client.ts

@@ -1,5 +1,5 @@
 import { apiBase, assertProjectMatch, resolveSession, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
-import type { SessionEvals } from '../../spec-yatsu/src/proof.js'
+import type { SessionEvals } from '../../spec-eval/src/sessioneval.js'
 
 export class BackendError extends Error {
   constructor(message: string, readonly status?: number) {
@@ -25,7 +25,7 @@ const guarded = (verb: string) => assertProjectMatch(`spex ${verb}`)
 const post = (body: unknown): RequestInit => ({ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
 const seg = (id: string) => encodeURIComponent(id)
 
-// GET /api/sessions — the board, used by `spex ls`, and by `spex watch`/`wait` as their poll source.
+// GET /api/sessions — the board, used by `spex session ls`, and by `spex session watch`/`wait` as their poll source.
 export async function clientListSessions(): Promise<Session[]> {
   const r = await apiFetch('/api/sessions')
   if (!r.ok) throw new BackendError(`backend error ${r.status} listing sessions`, r.status)
@@ -46,13 +46,13 @@ export async function clientCapture(id: string): Promise<CaptureResult> {
   return { ok: false, status: r.status, reason: (await r.text().catch(() => '')) || `status ${r.status}` }
 }
 
-// POST /api/sessions/:id/keys — prompt dispatch (the backend routes it through the rendezvous socket,
-// socket-only + fail-loud; a non-accepted prompt comes back ok:false / HTTP 502).
+// POST /api/sessions/:id/input {kind:"text"} — prompt dispatch (the backend routes it through the rendezvous
+// socket, socket-only + fail-loud; a non-accepted prompt comes back ok:false / HTTP 502).
 export async function clientSend(id: string, text: string, from?: string): Promise<DispatchResult> {
   await guarded('session send')
   // `from` = the sending agent's own session id; the backend logs the comms edge ([[comms-edge]]) only when
   // it's present (an agent send), so a human-shell send stays unrecorded.
-  const r = await apiFetch(`/api/sessions/${seg(id)}/keys`, post({ text, ...(from ? { from } : {}) }))
+  const r = await apiFetch(`/api/sessions/${seg(id)}/input`, post({ kind: 'text', text, ...(from ? { from } : {}) }))
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` })) as DispatchResult
 }
 
@@ -64,18 +64,18 @@ export async function clientReview(id: string): Promise<ReviewPayload | null> {
   return await r.json() as ReviewPayload
 }
 
-// GET /api/sessions/:id/proof — the rendered proof EXPORT artifact ([[review-proof]]): the self-contained
-// HTML the backend builds (default), or the model JSON (`json:true` → ?format=json). The engine runs on the
-// backend, so the CLI is a thin fetcher that writes/opens these bytes — works against a remote backend
-// unchanged. 404 → no such session.
-export type ProofResult = { ok: true; body: string } | { ok: false; status: number }
-export async function clientProof(id: string, json = false): Promise<ProofResult> {
-  const r = await apiFetch(`/api/sessions/${seg(id)}/proof${json ? '?format=json' : ''}`)
+// GET /api/sessions/:id/evals?format=html — the rendered EXPORT artifact ([[session-eval]]): the
+// self-contained HTML the backend builds. The engine runs on the backend, so the CLI is a thin fetcher
+// that writes/opens these bytes — works against a remote backend unchanged. 404 → no such session.
+export type ExportResult = { ok: true; body: string } | { ok: false; status: number }
+export async function clientEvalExport(id: string): Promise<ExportResult> {
+  const r = await apiFetch(`/api/sessions/${seg(id)}/evals?format=html`)
   if (r.ok) return { ok: true, body: await r.text() }
   return { ok: false, status: r.status }
 }
 
-// GET /api/sessions/:id/evals — the session EVAL model ([[review-proof]]'s interactive face): the changed
+// GET /api/sessions/:id/evals — the session EVAL model ([[session-eval]]'s interactive face, the same
+// route's default JSON representation): the changed
 // nodes' worktree-rooted reading rows (each carrying `inSession`), no diff enrichment, no inlined evidence
 // bytes — what `spex eval` renders, the dashboard Eval tab's source. 404 → no such session.
 export type EvalsResult = { ok: true; model: SessionEvals } | { ok: false; status: number }
@@ -95,17 +95,17 @@ export async function clientMerge(id: string): Promise<{ dispatched: boolean; re
 // POST /api/sessions/:id/resume — bring the agent back (relaunch ONLY if confirmed offline); demotes
 // working→idle, keeps any declaration. The RESUME GUARD REFUSES (409 {refused:true}) on a live/unproven agent;
 // `force` overrides for a wedged-but-alive process. {ok:false} otherwise = no such session (404).
-export async function clientReopen(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean }> {
-  await guarded('session reopen')
+export async function clientResume(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean }> {
+  await guarded('session resume')
   const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({ force }))
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }))
 }
 
-// POST /api/sessions/:id/exit — the soft stop: kill tmux + socket, KEEP the worktree (session goes offline,
+// POST /api/sessions/:id/stop — the soft stop: kill tmux + socket, KEEP the worktree (session goes offline,
 // resumable). Distinct from close. {ok:false} = no such session.
-export async function clientExit(id: string): Promise<boolean> {
-  await guarded('session exit')
-  const r = await apiFetch(`/api/sessions/${seg(id)}/exit`, post({}))
+export async function clientStop(id: string): Promise<boolean> {
+  await guarded('session stop')
+  const r = await apiFetch(`/api/sessions/${seg(id)}/stop`, post({}))
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
@@ -124,19 +124,20 @@ export async function clientRename(id: string, name: string): Promise<boolean> {
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
-// POST /api/sessions/:id/rawkey — the raw nav-key channel (tmux send-keys, NEVER the prompt socket): an
-// ordered token batch drives an interactive TUI menu ([[nav-mode-key-ordering]]). {ok:false} = unknown
-// session, no live pane, or no valid token delivered.
-export async function clientRawkey(id: string, keys: string[]): Promise<boolean> {
-  await guarded('session rawkey')
-  const r = await apiFetch(`/api/sessions/${seg(id)}/rawkey`, post({ keys }))
+// POST /api/sessions/:id/input {kind:"keys"} — the LAST-RESORT raw nav-key face of send (tmux send-keys,
+// NEVER the prompt socket): an ordered token batch drives an interactive TUI menu
+// ([[nav-mode-key-ordering]]). {ok:false} = unknown session, no live pane, or no valid token delivered.
+export async function clientSendRawKeys(id: string, keys: string[]): Promise<boolean> {
+  await guarded('session send')
+  const r = await apiFetch(`/api/sessions/${seg(id)}/input`, post({ kind: 'keys', keys }))
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
-// GET /api/sessions/:id/prompt — the session's originating prompt (404 if none recorded).
-export type PromptResult = { ok: true; prompt: string } | { ok: false; status: number }
-export async function clientPrompt(id: string): Promise<PromptResult> {
-  const r = await apiFetch(`/api/sessions/${seg(id)}/prompt`)
-  if (r.ok) return { ok: true, prompt: await r.text() }
+// GET /api/sessions/:id — the session RECORD detail (`spex session show`): the board row plus the full
+// originating prompt. 404 → no such session.
+export type ShowResult = { ok: true; session: Session & { prompt: string | null } } | { ok: false; status: number }
+export async function clientShow(id: string): Promise<ShowResult> {
+  const r = await apiFetch(`/api/sessions/${seg(id)}`)
+  if (r.ok) return { ok: true, session: await r.json() as Session & { prompt: string | null } }
   return { ok: false, status: r.status }
 }

package/spec-cli/src/contract-filter.ts

@@ -138,7 +138,7 @@ export function settleIndexStat(proj: string, files: string[]): void {
 
 // the full inverse (edge ③ — call AFTER the managed blocks left the working files): attribute lines out,
 // config keys unset, shim + block content removed. `<common>/spexcode/` may host other spexcode data
-// (yatsu blobs), so only OUR two files go, never the dir.
+// (evidence blobs), so only OUR two files go, never the dir.
 export function removeContractFilter(proj: string): void {
   let common: string
   try { common = commonDirOf(proj) } catch { return }   // not a git repo → nothing was ever planted

package/spec-cli/src/doctor.ts

@@ -13,7 +13,7 @@ import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { homedir } from 'node:os'
 import { loadSystemConfig, loadSkillConfig } from './specs.js'
-import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord } from './layout.js'
+import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout } from './layout.js'
 
 // this file lives at <pkgRoot>/src/self.ts, so `..` is the package root — the same derivation init.ts/
 // materialize.ts use (never a hardcoded repo path), so the git-hook template lookup survives a relocated install.
@@ -219,6 +219,21 @@ async function doctor(): Promise<number> {
   line('spex-adopted', adopted ? 'yes (.spec/ + spexcode.json)' : root ? 'no — run `spex init`' : 'not a git repo')
   line('root', base)
   line('mode', managed ? 'managed worktree (backend-launched session)' : 'standalone repo (bring-your-own-agent)')
+  // the issues-workflow switch ([[local-issues]]): its only home is the `issues.enabled` settings key
+  // (v0.3.0 — the on|off|status CLI verbs are gone), so doctor is where its state is READ. A legacy
+  // pre-rename `proposals.enabled` key is no longer consulted at runtime (no fallback) — flag it here so
+  // an old settings file gets repaired instead of silently drifting from what its author believes.
+  if (adopted) {
+    const { issuesEnabled } = await import('./localIssues.js')
+    // probe the SAME files the switch actually reads — the trunk checkout's settings pair, not this
+    // worktree's (readConfig resolves to mainCheckout, so a legacy key only matters there).
+    const cfgHome = (() => { try { return mainCheckout() } catch { return base } })()
+    const legacy = ['spexcode.json', 'spexcode.local.json'].filter((f) => {
+      try { return 'proposals' in JSON.parse(readFileSync(join(cfgHome, f), 'utf8')) } catch { return false }
+    })
+    line('issues workflow', `${issuesEnabled() ? 'ON' : 'OFF'} (spexcode.json issues.enabled)`)
+    if (legacy.length) line('  LEGACY key', `\`proposals\` found in ${legacy.map((f) => join(cfgHome, f)).join(', ')} — no longer read; rename it to "issues": { "enabled": … }`)
+  }
 
   // --- preconditions: nothing downstream fires without these ---
   L.push('\nPreconditions (without these nothing downstream fires)')
@@ -247,7 +262,7 @@ async function doctor(): Promise<number> {
     const present = h.contractFiles(base).every((f) => /<!--\s*spexcode:start\s*-->/.test(read(f)))
     line(`in ${h.id}`, present ? `block present (${h.contractFiles(base).map((f) => f.replace(base + '/', '')).join(', ')})` : 'NOT landed — run `spex doctor contract` / materialize')
   }
-  line('view', 'spex doctor contract')
+  line('view', 'spex doctor --contract')
 
   // --- hooks: the shim → dispatch, the manifest, and EVERY handler readable in the worktree ---
   L.push('\nLayer 3 — hooks (shim → dispatch · manifest · handler-existence)')
@@ -293,7 +308,7 @@ async function doctor(): Promise<number> {
   line('layer 2', body.length === 0 ? 'ABSENT (no contract)' : 'see per-harness above')
   line('layer 3', manifestText ? 'see handler-existence above' : 'ABSENT (no manifest — agent ungoverned)')
   line('layer 4', up ? 'present' : managed ? 'EXPECTED but backend down' : 'absent (normal for bring-your-own-agent)')
-  line('layer 5', dd.conflict ? 'CONFLICT (double-delivery — see Layer 5; `spex doctor conflicts`)' : 'clean (single channel)')
+  line('layer 5', dd.conflict ? 'CONFLICT (double-delivery — see Layer 5; `spex doctor --conflicts`)' : 'clean (single channel)')
 
   // --- footprint: every artifact Spex wrote here, + any slot held by something not ours ---
   L.push('\nFootprint (what Spex wrote into this environment)')
@@ -323,12 +338,12 @@ function contract(): number {
 }
 
 // the focused double-delivery check: JUST Layer 5, exit non-zero when a conflict is live so it gates a script
-// / yatsu. Anchors at the repo root like doctor (the shims + contract + skills live there).
+// / eval. Anchors at the repo root like doctor (the shims + contract + skills live there).
 async function conflicts(): Promise<number> {
   const cwd = process.cwd()
   const base = repoRoot(cwd) ?? cwd
   const { lines, conflict } = await doubleDeliveryReport(base)
-  console.log(['spex doctor conflicts — does SpexCode reach this agent through more than one discovery channel?\n', ...lines].join('\n'))
+  console.log(['spex doctor --conflicts — does SpexCode reach this agent through more than one discovery channel?\n', ...lines].join('\n'))
   return conflict ? 1 : 0
 }
 
@@ -338,26 +353,38 @@ async function conflicts(): Promise<number> {
 function noteStaged(verb: string): number {
   console.error(`spex doctor ${verb} is not available yet — it is staged behind the hook-degradation prerequisite
 (the live hooks must detect a missing managed session and degrade before they can be safely wired into your
-own agent's config). Meanwhile: \`spex doctor\` reports your coverage, and \`spex doctor contract\` prints
+own agent's config). Meanwhile: \`spex doctor\` reports your coverage, and \`spex doctor --contract\` prints
 the workflow text you can hand any agent.`)
   return 2
 }
 
 function usage(): number {
   console.error(`spex doctor — diagnose how the SpexCode workflow reaches your agent
-  (bare)       per-layer report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
-  contract     print the surface:system contract text (hand it to any agent)
-  conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)
-  install      [staged] wire the materialized contract + hooks into your agent  (--agent claude, --minimal)
-  uninstall    [staged] reverse exactly what install wrote`)
+  (bare)         per-layer report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
+  --contract     print the surface:system contract text (hand it to any agent)
+  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)
+  --migrate      one-shot 0.2.x → 0.3.0 vocabulary migration for an adopter repo (renames + hook-asset
+                 upgrade + body rewrites; refuses on a dirty tree / undrained sessions / an already-migrated
+                 tree; stages everything, commits nothing; removed in 0.4.0)
+  install        [staged] wire the materialized contract + hooks into your agent  (--agent claude, --minimal)
+  uninstall      [staged] reverse exactly what install wrote`)
   return 0
 }
 
 export async function runDoctor(args: string[]): Promise<number> {
+  // contract/conflicts are FLAGS, not subcommands ([[cli-surface]] §4: another representation of the same
+  // diagnosis read, not a distinct action). The old positional spellings signpost — report, never run.
+  // --migrate is the one MUTATING flag: the term-limited 0.2.x→0.3.0 adopter migrator ([[migrate]],
+  // ships with 0.3.0, deleted in 0.4.0) — dispatched first so its refusal/summary is never diluted
+  // by the diagnosis report.
+  if (args.includes('--migrate')) return await (await import('./migrate.js')).runMigrate()
+  if (args.includes('--contract')) return contract()
+  if (args.includes('--conflicts')) return await conflicts()
   switch (args[0]) {
     case undefined: return await doctor()
-    case 'contract': return contract()
-    case 'conflicts': return await conflicts()
+    case 'contract': case 'conflicts':
+      console.error(`spex: \`spex doctor ${args[0]}\` was removed in v0.3.0 — use: spex doctor --${args[0]}`)
+      return 2
     case 'install': return noteStaged('install')
     case 'uninstall': return noteStaged('uninstall')
     case 'help': case '--help': case '-h': return usage()

package/spec-cli/src/gateway.ts

@@ -15,6 +15,7 @@ import { fileURLToPath } from 'node:url'
 import { homedir } from 'node:os'
 import { loginPage } from './login-page.js'
 import { listenOrExit } from './listen.js'
+import { installConnectionReaper } from './reaper.js'
 
 // @@@ resolvePublicConfig - the cert/gate is a RESOLVED value, never hardcoded. Reads the same precedence
 // chain the spec promises: flag > env > spexcode.json > self-signed default. Returns null when public mode
@@ -150,14 +151,17 @@ export function startGateway(opts: GatewayOpts): void {
   }
 
   // server-side connection reaping ([[spec-cli]] / [[public-mode]]) - the internet-facing gateway is the
-  // public server in public mode, so it carries the SAME reaping as the child: an abandoned/slow connection
-  // dies here instead of piling up. Idle keep-alive / slow-header / never-completing request only; the gated
-  // WS upgrade (handled below) is an active connection, not reaped by these. Set AT CONSTRUCTION so the
-  // connection-checking sweep is armed with our cadence (a post-hoc set leaves it under-effective).
+  // public server in public mode, so it carries the SAME reaping as the child. The `reap` HTTP timeouts are
+  // kept (harmless) but are NOT the mechanism — MEASURED (eval server-reaps-abandoned-connections), Node's
+  // headersTimeout/requestTimeout don't reap an INCOMPLETE request; the real reaper is the socket-level
+  // `installConnectionReaper` (reaper.ts), applied below at every http server the serving path creates.
+  // Idle keep-alive / slow-loris / never-completing request only; the gated WS upgrade (handled below) is an
+  // active stream and exempt for its lifetime.
   const reap = { keepAliveTimeout: 10000, headersTimeout: 20000, requestTimeout: 60000, connectionsCheckingInterval: 10000 }
   const server = secure
     ? https.createServer({ cert: opts.tls!.cert, key: opts.tls!.key, ...reap }, handler)
     : http.createServer(reap, handler)
+  installConnectionReaper(server)
 
   // @@@ WS gate - the terminal socket rides an HTTP upgrade. Gate it by the SAME cookie (the browser sends
   // it on the same-origin handshake), then raw-pipe to the loopback supervisor, replaying the buffered
@@ -173,7 +177,7 @@ export function startGateway(opts: GatewayOpts): void {
     socket.on('error', bail); up.on('error', bail)
   })
 
-  // `spex dashboard` passes an explicit host (loopback by default, --host to widen); `--public` passes
+  // `spex serve ui` passes an explicit host (loopback by default, --host to widen); `--public` passes
   // none → bind ALL interfaces (the original behaviour, IPv4+IPv6), so adding the local path never
   // narrows the public gateway's reach. The gate note keys on LOOPBACK, not on host-being-explicit:
   // an ungated loopback bind is normal, an ungated wide bind is announced — never silent.
@@ -186,7 +190,7 @@ export function startGateway(opts: GatewayOpts): void {
     if (!secure && !isLoopback && !opts.host) console.log('[gateway] (TLS off — --http)')
   }
   // a busy public port is a hard, loud, non-zero exit — the SAME contract as the supervisor's proxy
-  // (see [[spec-cli]] / listen.ts), so `spex serve` and `spex dashboard` fail a port clash identically.
+  // (see [[spec-cli]] / listen.ts), so `spex serve` and `spex serve ui` fail a port clash identically.
   listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, onListen })
 }
 
@@ -271,7 +275,7 @@ export function ensureDashboardBuilt(repoRoot: string, distDir: string): void {
   }
 }
 
-// @@@ serveDashboardLocal - the engine behind `spex dashboard`: the SAME gateway as public mode, bound to
+// @@@ serveDashboardLocal - the engine behind `spex serve ui`: the SAME gateway as public mode, bound to
 // loopback by default with no TLS and no password — `--host` widens the bind to a chosen interface
 // (LAN/tailnet viewing) while staying plain HTTP; the internet face remains `spex serve --public`.
 // It serves the bundled dist and proxies /api + the terminal socket to a separately-run `spex serve`.

package/spec-cli/src/git.ts

@@ -6,7 +6,7 @@ import { join, isAbsolute, resolve } from 'node:path'
 const US = '\x1f', RS = '\x1e'
 
 // @@@ bounded git children - a git child that never exits (wedged fs, a hijacked PATH git, a dead network
-// mount) must not pin its awaiter forever: [[board-cache]]'s settle guarantee starts at this seam. Every
+// mount) must not pin its awaiter forever: [[graph-cache]]'s settle guarantee starts at this seam. Every
 // shared helper passes a generous timeout (an order of magnitude above the slowest legitimate full-history
 // walk) with SIGKILL — same pattern sessions.ts's tmux/ps probes already use — so a hung child dies and the
 // call fails like any other git failure instead of hanging its caller's promise. The kill is warned loudly:
@@ -154,7 +154,7 @@ function parseStatPath(token: string): { from: string; to: string } {
 }
 
 // Both bulk indices are pure functions of a checkout's HEAD, and they are read for SEVERAL roots at
-// once — the backend checkout (board, loadSpecs) plus every session worktree ([[review-proof]]'s eval
+// once — the backend checkout (board, loadSpecs) plus every session worktree ([[session-eval]]'s eval
 // tab roots its readings at the session's branch). A single-slot cache thrashes between those roots:
 // each eval-tab request evicts the board's entry and vice versa, so every request re-runs a full-history
 // `git log` and re-parses it on the event loop — which is what starves every other request (the board,

package/spec-cli/src/{board.ts → graph.ts}

@@ -6,8 +6,8 @@ import { repoRoot, driftIndex, historyIndex } from './git.js'
 import { residentForgeState } from '../../spec-forge/src/resident.js'
 import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { mergedIssues } from './issues.js'
-import { evalContext, evalTimeline } from '../../spec-yatsu/src/evaltab.js'
-import { yatsuNodesAsync } from '../../spec-yatsu/src/yatsu.js'
+import { evalContext, evalTimeline } from '../../spec-eval/src/evaltab.js'
+import { evalNodesAsync } from '../../spec-eval/src/scenarios.js'
 
 // a ghost (added) node's parent: the existing node whose directory is the longest prefix of the new one.
 function resolveParent(path: string, byDir: Record<string, string>): string | null {
@@ -20,7 +20,7 @@ function resolveParent(path: string, byDir: Record<string, string>): string | nu
   return null
 }
 
-// the board's eval summary ([[board-lean]]): the LATEST reading per scenario, each kept as the VERBATIM
+// the board's eval summary ([[graph-lean]]): the LATEST reading per scenario, each kept as the VERBATIM
 // reading object — a filter, never a projection. Consumers hang optional fields off a reading (the
 // annotator's timelineBlob rides only video readings), so dropping a field here is a SILENT downstream
 // degradation no error would surface; the field-preservation unit test pins this contract.
@@ -29,7 +29,7 @@ export function latestPerScenario<T extends { scenario: string }>(readings: T[])
   return readings.filter((r) => !seen.has(r.scenario) && (seen.add(r.scenario), true))
 }
 
-// the board's scenario fold ([[board-lean]]): the declared set rides SLIM — {name, tags} is everything an
+// the board's scenario fold ([[graph-lean]]): the declared set rides SLIM — {name, tags} is everything an
 // overview surface joins state onto (badge, stats, focus rows, search rows); the prose (description/
 // expected) and per-scenario code stay off the hot poll, carried by `/api/specs/lite` and `/api/specs/:id/evals`.
 export function slimScenarios(scenarios: { name: string; tags?: string[] }[]): { name: string; tags?: string[] }[] {
@@ -44,7 +44,7 @@ export async function buildBoard() {
   const root = repoRoot()
   const [layout, sessions, specs] = await Promise.all([resolveLayout(), listSessions(), loadSpecs()])
   // the eval fold's freshness axes: WARM hits — loadSpecs already computed this HEAD's drift + history
-  // indices, so these are the same cached walks, fetched once and reused for every yatsu node (the history
+  // indices, so these are the same cached walks, fetched once and reused for every measurable node (the history
   // index drives the rename-safe scenario axis, mirroring a spec node's own freshness).
   const idx = await driftIndex(root)
   const hidx = await historyIndex(root)
@@ -96,7 +96,7 @@ export async function buildBoard() {
   const nodes = [
     ...specs.map((n: any) => {
       const overlays = overlaysByNode[n.id] || []
-      // `body` and its derivation `parts` are DROPPED from the board payload ([[board-lean]]): together ~56% of
+      // `body` and its derivation `parts` are DROPPED from the board payload ([[graph-lean]]): together ~56% of
       // the bytes, and detail the graph overview never renders. The detail view fetches them per node from
       // `/api/specs/:id/content` on open, and the search palette fetches the body corpus from `/api/specs/lite`
       // once on open — both off this hot poll. `undefined` makes JSON.stringify omit the keys.
@@ -109,8 +109,21 @@ export async function buildBoard() {
   // openIssues, attached only when non-empty). Non-blocking: residentForgeState never waits on `gh` and is
   // empty absent a forge, so the fold then carries the local slice alone. Sorted open-first, newest first.
   const isOpen = (i: { status: string }) => i.status === 'open'
+  const merged = mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, nodes.map((n) => n.id))
+  // ONE board-level freshness stamp over EVERY issue thread (noded or nodeless, both stores):
+  // open-count : thread-count : reply-count : latest-activity. Every thread write — open, reply, remark,
+  // resolve, retract, close — moves at least one component, so a store write ALWAYS moves board bytes:
+  // [[graph-delta]] suppresses no-change broadcasts, and without a moving byte an external write would
+  // stay invisible to viewers until the fallback poll ([[remark-substrate]] write-visibility). The per-node
+  // fold below stays [[graph-lean]]-slim (no reply payloads); this stamp is the freshness carrier.
+  const issuesStamp = [
+    merged.filter(isOpen).length,
+    merged.length,
+    merged.reduce((n, i) => n + i.replies.length, 0),
+    merged.flatMap((i) => [i.created, ...i.replies.flatMap((r) => [r.at, r.resolvedAt ?? ''])]).reduce((a, b) => (b > a ? b : a), ''),
+  ].join(':')
   const issuesByNode: Record<string, ReturnType<typeof mergedIssues>> = {}
-  for (const issue of mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, nodes.map((n) => n.id)))
+  for (const issue of merged)
     for (const nid of issue.nodes) (issuesByNode[nid] ??= []).push(issue)
   for (const n of nodes) {
     const issues = issuesByNode[n.id]
@@ -122,20 +135,20 @@ export async function buildBoard() {
     if (open.length) n.openIssues = open
   }
 
-  // fold each yatsu node's eval state onto it — as the LEAN summary ([[board-lean]]): `evals` carries only
+  // fold each measurable node's eval state onto it — as the LEAN summary ([[graph-lean]]): `evals` carries only
   // the LATEST reading per scenario (newest-first), which is all any overview surface consumes (the score
   // badge, stats, search all reduce to latest-per-scenario anyway); the full timeline stays off the board
   // and is lazy-loaded by the eval tab from `/api/specs/:id/evals`. `scenarios` (the declared set) rides
   // SLIM — {name, tags} only, the fields every overview surface joins state onto — with its prose
   // (description/expected) and per-scenario code off the hot poll: they ride the `/api/specs/lite` corpus
   // (search palette, focus-panel preview) and the `/api/specs/:id/evals` timeline (eval tab).
-  // evalContext reuses the specs + driftIndex above; evalTimeline short-circuits non-yatsu nodes. The
-  // yatsu walk rides fs/promises ([[board-cache]]) so it yields the event loop instead of stalling /health.
-  const ynodes = await yatsuNodesAsync(root)
+  // evalContext reuses the specs + driftIndex above; evalTimeline short-circuits non-measurable nodes. The
+  // eval-file walk rides fs/promises ([[graph-cache]]) so it yields the event loop instead of stalling /health.
+  const ynodes = await evalNodesAsync(root)
   const ectx = await evalContext(root, specs, idx, hidx, undefined, ynodes)
   await Promise.all(nodes.map(async (n) => {
     const tl = await evalTimeline(n.id, ectx)
-    if (tl.hasYatsu) { n.evals = latestPerScenario(tl.readings); n.scenarios = slimScenarios(tl.scenarios) }
+    if (tl.hasEvalFile) { n.evals = latestPerScenario(tl.readings); n.scenarios = slimScenarios(tl.scenarios) }
   }))
 
   const opsByPath: Record<string, any[]> = {}
@@ -144,6 +157,23 @@ export async function buildBoard() {
 
   const dash = readConfig(root).dashboard
   // project names the tab ([[tab-title]]); projectIcon is the tab favicon ([[tab-icon]]) — both ride the
-  // /api/board poll so they re-derive from whichever backend the viewer reached. Empty icon → frontend default.
-  return { nodes, sessions: sess, project: dash?.title || basename(root), projectIcon: dash?.icon || '' }
+  // /api/graph poll so they re-derive from whichever backend the viewer reached. Empty icon → frontend default.
+  return { nodes, sessions: sess, project: dash?.title || basename(root), projectIcon: dash?.icon || '', issuesStamp }
+}
+
+// @@@ spliceSessions — the SESSIONS-ONLY producer ([[graph-cache]]). A session-scoped change (a lifecycle
+// write, a liveness/activity poll flip) reshapes only the board's `sessions` rows — the node/meta units are
+// untouched — so the cache re-derives ONLY the sessions and splices them onto the previous board verbatim,
+// skipping the whole loadSpecs/layout/eval assembly a full buildBoard() pays. Pure aside from listSessions:
+// each row is decorated EXACTLY as buildBoard's sess mapping (`{...s, source: s.path, ops}`), and every
+// path's `ops` is REUSED from the previous board (a path→ops map). A session path absent in `prev` gets []
+// — a brand-new worktree has no pending spec ops yet, and any later ops-CHANGING event (a commit, a
+// worktree `.spec` edit) is refs/worktree-scoped, i.e. a FULL rebuild, never a sessions splice. So the
+// splice is byte-indistinguishable from a full rebuild whenever only session state moved.
+export async function spliceSessions(prev: Awaited<ReturnType<typeof buildBoard>>): Promise<Awaited<ReturnType<typeof buildBoard>>> {
+  const sessions = await listSessions()
+  const opsByPath: Record<string, any[]> = {}
+  for (const s of prev.sessions) opsByPath[s.source] = s.ops
+  const sess = sessions.map((s) => ({ ...s, source: s.path, ops: opsByPath[s.path] || [] }))
+  return { ...prev, sessions: sess }
 }

package/spec-cli/src/{boardCache.ts → graphCache.ts}

@@ -1,13 +1,13 @@
-import { buildBoard } from './board.js'
+import { buildBoard, spliceSessions } from './graph.js'
 
-// @@@ board-cache — single-flight + cache for the hot /api/board build ([[board-lean]]). Assembling the
+// @@@ graph-cache — single-flight + cache for the hot /api/graph build ([[graph-lean]]). Assembling the
 // board is expensive (two full-history git-log walks cold, a full `.spec` fs walk every build), so the
 // route MUST NOT rebuild per request: index.ts once ran `buildBoard()` inline on EVERY poll, so a normal
 // dashboard's overlapping polls (+ SSE-triggered refetches) multiplied into N simultaneous builds and
 // starved the event loop — one real user could wedge the backend. Here ONE build is shared by all
 // concurrent callers (a promise memo — this IS the max-concurrent-builds cap: at most one runs) and its
 // result is cached until a REAL change invalidates it. The cache is invalidated by the SAME freshness
-// signals [[board-stream]] already watches (session-store writes, git-ref moves, the cold tick), via
+// signals [[graph-stream]] already watches (session-store writes, git-ref moves, the cold tick), via
 // invalidateBoard(). So a poll storm costs ONE build, a quiet stretch costs ZERO, and the SSE rebuild and
 // the route share the very same in-flight build.
 
@@ -22,7 +22,7 @@ const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
 // below, so a never-settling buildBoard() would pin the single-flight forever — every later read (even of a
 // perfectly good cached board) short-circuits into the pinned promise before `valid` is consulted,
 // invalidation can't help, no log ever fires, and only a restart cures it (the live wedge: hung git
-// children → /api/board 503 forever, silently). So the build races a generous watchdog that REJECTS loudly;
+// children → /api/graph 503 forever, silently). So the build races a generous watchdog that REJECTS loudly;
 // the rejection flows through the SAME finally → inflight clears → the next read retries fresh. Sitting at
 // the single-flight boundary, this one wall bounds every never-settle cause — including ones with no child
 // process at all (fs/promises under libuv threadpool starvation); git.ts's per-child timeouts merely make
@@ -30,53 +30,73 @@ const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
 // fires on a genuine wedge.
 const BUILD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_BUILD_TIMEOUT_MS || 120000)
 
-let cached: Board | null = null   // last completed build; served while `valid`
+// the cache's staleness has a DOMAIN, not just a bit: a 'sessions' change (a lifecycle write, a
+// liveness/activity poll flip) touches only the session rows, so the next read can SPLICE fresh sessions
+// onto the still-valid node/meta units instead of re-walking git+`.spec`; a 'full' change (a ref move, a
+// worktree `.spec` edit, the cold-tick patrol) can reshape anything, so the next read does the whole
+// buildBoard(). 'none' = clean.
+type Scope = 'sessions' | 'full'
+let cached: Board | null = null   // last completed build; served while `dirty === 'none'`
 let cachedJson: string | null = null   // JSON.stringify(cached), serialized ONCE per build (see getBoardJson)
-let valid = false
+let dirty: Scope | 'none' = 'full'   // no cached board yet → the first read builds fully
 let inflight: Promise<Board> | null = null
 let gen = 0                       // bumped on every invalidation — detects a change that landed MID-build
 
-// mark the cache stale. Called by every board-stream freshness source (see boardStream.fireChanged), so a
-// real change forces the next getBoard() to rebuild while a quiet poll storm keeps hitting the cache.
-export function invalidateBoard(): void {
+// mark the cache stale at a SCOPE. Called by every board-stream freshness source (see
+// boardStream.fireChanged), so a real change forces the next getBoard() to rebuild while a quiet poll storm
+// keeps hitting the cache. The scope only ESCALATES within a dirty window: none→sessions→full, and a
+// 'sessions' signal arriving while 'full' is already pending stays 'full' (a full rebuild subsumes a
+// sessions splice). cachedJson is dropped either way — a splice replaces the board object, so its old
+// serialization is stale regardless of scope.
+export function invalidateBoard(scope: Scope = 'full'): void {
   gen++
-  valid = false
+  if (scope === 'full' || dirty === 'full') dirty = 'full'
+  else dirty = 'sessions'
+  cachedJson = null
 }
 
 // the coalesced board read the route and the SSE rebuild both go through. A concurrent caller during a
 // build shares the in-flight promise; a caller after a completed build gets the cached value until the
-// next invalidation. A change that lands WHILE a build runs (gen moved) leaves the cache invalid so the
-// NEXT read rebuilds — the just-finished build still returns to its waiters (freshest available when they
-// asked), never cached as current. Mirrors [[board-stream]]'s building/dirty loop.
+// next invalidation. A 'sessions'-scoped dirty with a cached board takes the SPLICE path (spliceSessions —
+// fresh session rows onto the cached node/meta units) under the SAME single-flight promise + watchdog +
+// generation rules; anything else (dirty 'full', or no cache to splice onto) does a full buildBoard(). A
+// change that lands WHILE a build runs (gen moved) leaves the cache dirty so the NEXT read rebuilds — a
+// 'full' invalidation landing mid-splice leaves it dirty 'full' for the next read. The just-finished build
+// still returns to its waiters (freshest available when they asked), never cached as current. Mirrors
+// [[graph-stream]]'s building/dirty loop.
 export function getBoard(): Promise<Board> {
   if (inflight) return inflight
-  if (valid && cached) return Promise.resolve(cached)
+  if (dirty === 'none' && cached) return Promise.resolve(cached)
   const startGen = gen
+  const sessionsOnly = dirty === 'sessions' && cached !== null
+  const prev = cached
   const p = (async () => {
     const t0 = Date.now()
     let watchdog: ReturnType<typeof setTimeout> | undefined
     try {
       const board = await Promise.race([
-        buildBoard(),
+        sessionsOnly ? spliceSessions(prev!) : buildBoard(),
         // the race consumes the loser's eventual settlement, so an abandoned build that fails later
         // can't surface as an unhandled rejection; unref'd so a pending watchdog never holds a one-shot
         // CLI process open.
         new Promise<never>((_, reject) => {
           watchdog = setTimeout(() => {
-            console.warn(`spec-cli: /api/board build did not settle within ${BUILD_TIMEOUT_MS}ms — wedged build abandoned so the next read can retry`)
-            reject(new Error(`board build did not settle within ${BUILD_TIMEOUT_MS}ms`))
+            console.warn(`spec-cli: /api/graph build did not settle within ${BUILD_TIMEOUT_MS}ms — wedged build abandoned so the next read can retry`)
+            reject(new Error(`graph build did not settle within ${BUILD_TIMEOUT_MS}ms`))
           }, BUILD_TIMEOUT_MS)
           watchdog.unref?.()
         }),
       ])
       cached = board
       cachedJson = null   // invalidate the memoized serialization; re-serialized lazily on first read
-      valid = gen === startGen
+      // clean ONLY if no invalidation landed during the build; otherwise leave `dirty` at whatever scope
+      // those in-build invalidations escalated it to (a mid-splice 'full' stays 'full' for the next read).
+      if (gen === startGen) dirty = 'none'
       return board
     } finally {
       clearTimeout(watchdog)
       const ms = Date.now() - t0
-      if (ms > BUDGET_MS) console.warn(`spec-cli: /api/board build took ${ms}ms (budget ${BUDGET_MS}ms) — hot path is slow`)
+      if (ms > BUDGET_MS) console.warn(`spec-cli: /api/graph build took ${ms}ms (budget ${BUDGET_MS}ms) — hot path is slow`)
       inflight = null
     }
   })()
@@ -84,9 +104,9 @@ export function getBoard(): Promise<Board> {
   return p
 }
 
-// the SERIALIZED board for the /api/board route — JSON.stringify runs ONCE per build, not once per poll,
+// the SERIALIZED board for the /api/graph route — JSON.stringify runs ONCE per build, not once per poll,
 // so a poll storm of cache hits costs zero serialization CPU (only the etag hash for the 304 path). The SSE
-// path still takes the object (getBoard) because it decomposes it into delta units ([[board-delta]]).
+// path still takes the object (getBoard) because it decomposes it into delta units ([[graph-delta]]).
 export async function getBoardJson(): Promise<string> {
   const board = await getBoard()
   if (board === cached && cachedJson !== null) return cachedJson

package/spec-cli/src/{boardDelta.ts → graphDelta.ts}

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 
 // @@@ board-delta — the pure core of the board's incremental push: decompose a board snapshot into a keyed
-// UNIT MAP, tag it, and diff two unit maps into a minimal {set, del} patch. The transport ([[board-stream]])
+// UNIT MAP, tag it, and diff two unit maps into a minimal {set, del} patch. The transport ([[graph-stream]])
 // chains these patches over SSE (`from`/`to` tags) so a subscribed dashboard applies a few KB per change
 // instead of refetching the full ~600KB snapshot; the client-side mirror of apply/reconstruct lives in the
 // dashboard's data layer. Everything here is pure and synchronous — no fs, no git, no stream — so the