spexcode 0.2.8 → 0.4.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,
@@ -366,28 +366,36 @@ export function inAncestors(idx: DriftIndex, bits: Uint8Array, sha: string): boo
   return o !== undefined && (bits[o >> 3] & (1 << (o & 7))) !== 0
 }
 
-// pure lookup, no git: a commit to `path` is drift iff it is NOT an ancestor of `sinceHash` — it lies
-// in `sinceHash..HEAD` by true DAG reachability, wherever a date-ordered log happens to place it.
-//
-// `sinceHash` is the node's OWN latest version commit, so the node(s) it's a version of
-// (specNodes[sinceHash]) name the node being measured; an ack counts only if its `Spec-OK:` set names
-// one of those — `Spec-OK: A` quiets A's drift, never B's. An ack that is itself an ancestor of the
-// version can't speak for it (a re-version invalidates older acks); a valid ack quiets exactly the
-// commits reachable from it. An off-history `sinceHash` → 0: no basis on HEAD to measure from.
-export function driftFor(idx: DriftIndex, sinceHash: string, path: string): number {
-  if (!sinceHash) return 0
+// the valid Spec-OK coverage for a node's version commit: `sinceHash` is the node's OWN latest version,
+// so the node(s) it's a version of (specNodes[sinceHash]) name the node being measured; an ack counts
+// only if its `Spec-OK:` set names one of those — `Spec-OK: A` quiets A's drift, never B's. An ack that
+// is itself an ancestor of the version can't speak for it (a re-version invalidates older acks); a valid
+// ack quiets exactly the commits reachable from it. Shared by driftFor (the count) and the anchor
+// engine's windowCommits (the commit set) so both read ONE ack rule.
+export function ackCoverFor(idx: DriftIndex, sinceHash: string): Uint8Array[] {
   const base = ancestorsOf(idx, sinceHash)
-  if (!base) return 0
+  if (!base) return []
   const targets = idx.specNodes.get(sinceHash)
-  const ackCover: Uint8Array[] = []
+  const cover: Uint8Array[] = []
   if (targets) {
     for (const [h, ackSet] of idx.acks) {
       if (inAncestors(idx, base, h)) continue
       if (![...targets].some((t) => ackSet.has(t))) continue
       const a = ancestorsOf(idx, h)
-      if (a) ackCover.push(a)
+      if (a) cover.push(a)
     }
   }
+  return cover
+}
+
+// pure lookup, no git: a commit to `path` is drift iff it is NOT an ancestor of `sinceHash` — it lies
+// in `sinceHash..HEAD` by true DAG reachability, wherever a date-ordered log happens to place it.
+// An off-history `sinceHash` → 0: no basis on HEAD to measure from.
+export function driftFor(idx: DriftIndex, sinceHash: string, path: string): number {
+  if (!sinceHash) return 0
+  const base = ancestorsOf(idx, sinceHash)
+  if (!base) return 0
+  const ackCover = ackCoverFor(idx, sinceHash)
   let n = 0
   for (const h of idx.fileCommits.get(path) ?? []) {
     if (inAncestors(idx, base, h)) continue           // reachable from the version → not drift

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 }
 }