spexcode 0.5.2 → 0.5.4

package/spec-cli/src/index.ts

@@ -13,11 +13,10 @@ import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { summarize } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './graphCache.js'
-import { boardStream, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
+import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
-import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, TMUX_SOCK } from './sessions.js'
+import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, archiveSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
 import { superviseTimeline, readTimeline } from './session-timeline.js'
-import { readSessionMessages, sessionMessageStream } from './message-stream.js'
 import { defaultHarness, HARNESSES, dashboardLauncherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
 import { putBlob } from '../../spec-eval/src/cache.js'
@@ -29,6 +28,9 @@ import { attachViewer, detachViewer, resizeBridge, hideViewer, forwardInput, sup
 import { installProcessGuards } from './resilience.js'
 import { resolveProjectIdentity } from './project-identity.js'
 import { evalDetailReview, evalsReview, issuesReview } from './reviews.js'
+import { collectResourceReport, ResourceConflict } from './host-resources.js'
+import { exactProcessIdentity, maintenanceErrorPayload, sessionMaintenance, SessionMaintenanceError, type Authorization } from './session-maintenance.js'
+import { readBackendInstanceRecords } from './runtime-ownership.js'
 
 // last-resort net: an unforeseen async throw (e.g. a worktree vanishing mid-read during a worker
 // self-merge) is logged and the server KEEPS SERVING instead of exiting and dropping the public port.
@@ -38,12 +40,18 @@ const app = new Hono()
 app.use('/api/*', cors())
 app.onError((error, c) => {
   if (error instanceof SessionEvalUnavailableError) return c.json({ error: error.message }, 503)
+  // a record that cannot carry state is a CONFLICT with the caller's request, not a server fault: the refusal
+  // is deliberate and already carries its own diagnosis + repair ([[sessions-core]]). Answering 500 with a
+  // stack would hide exactly the sentence the human needs.
+  if (error instanceof SessionRecordUnusable) return c.json({ error: error.message, code: error.code }, 409)
+  if (error instanceof ResourceConflict) return c.json({ error: error.message, code: error.code }, 409)
+  if (error instanceof SessionMaintenanceError) return c.json(maintenanceErrorPayload(error)!, 409)
   console.error(error)
   return c.text('Internal Server Error', 500)
 })
 const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app })
 
-app.get('/', (c) => c.text('spec-cli — GET /api/graph · /api/specs · /api/specs/:id/history · /api/settings · /api/sessions · /api/slash-commands'))
+app.get('/', (c) => c.text('spec-cli — GET /api/graph · /api/specs · /api/specs/:id/history · /api/settings · /api/sessions · /api/resources · /api/slash-commands'))
 // the supervisor's readiness gate (supervise.ts): a bare git-free 200 so a booting child reports ready the
 // instant Hono is listening. Not under /api/* — loopback-only (supervisor→child), no CORS needed.
 app.get('/health', (c) => c.text('ok'))
@@ -77,11 +85,21 @@ app.get('/api/instance', (c) => {
 // is bounded by [[graph-cache]]'s own build watchdog, so the next poll retries a fresh build.
 const BOARD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_TIMEOUT_MS || 20000)
 app.get('/api/graph', etag(), async (c) => {
-  ensureBoardFileWatchers()
+  await ensureBoardFileWatchers()
   const timeout = Symbol('timeout')
-  const json = await Promise.race([getBoardJson(), new Promise<typeof timeout>((r) => setTimeout(() => r(timeout), BOARD_TIMEOUT_MS))])
-  if (json === timeout) return c.json({ error: 'graph build timed out' }, 503)
-  return c.body(json as string, 200, { 'content-type': 'application/json; charset=UTF-8' })
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const result = await Promise.race([
+    getBoardJson('stale-ok'),
+    new Promise<typeof timeout>((resolve) => {
+      timer = setTimeout(() => resolve(timeout), BOARD_TIMEOUT_MS)
+      timer.unref?.()
+    }),
+  ])
+  clearTimeout(timer)
+  if (result === timeout) return c.json({ error: 'graph build timed out' }, 503)
+  const freshness = result.refreshing ? `${result.freshness}, refreshing` : result.freshness
+  c.header('x-spexcode-graph', freshness)
+  return c.body(result.json, 200, { 'content-type': 'application/json; charset=UTF-8' })
 })
 // the graph'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 ([[graph-stream]]).
@@ -206,14 +224,15 @@ app.get('/api/issues', etag(), async (c) => c.json(await issuesReview(c.req.quer
 // Evals uses the identical paged-review response. `scope:` inside q selects the worktree source; without
 // it the source is the current cached board. Filtering/counts always precede the one 25-row slice.
 app.get('/api/evals', etag(), async (c) => {
-  ensureBoardFileWatchers()
+  const scope = c.req.query('q')?.match(/(?:^|\s)scope:([^\s]+)/)?.[1]
+  await ensureBoardFileWatchers(scope)
   const page = await evalsReview(c.req.query('q'), c.req.query('page'), { view: c.req.query('view') })
   return page ? c.json(page) : c.json({ error: 'no such review source' }, 404)
 })
 // ONE bounded detail response for both source roots: the selected scenario's complete A/B history and at
 // most five lightweight neighbors. It never serializes another scenario's history or the scoped model.
 app.get('/api/evals/detail', etag(), async (c) => {
-  ensureBoardFileWatchers()
+  await ensureBoardFileWatchers(c.req.query('scope')?.trim() || undefined)
   const node = c.req.query('node')?.trim()
   const scenario = c.req.query('scenario')?.trim()
   if (!node || !scenario) return c.json({ error: 'node and scenario are required' }, 400)
@@ -385,7 +404,48 @@ app.post('/api/uploads', async (c) => {
 
 // sessions: real tmux-backed Claude Code sessions. List + spawn, stream the live pane (WebSocket),
 // forward keystrokes, and close.
-app.get('/api/sessions', async (c) => c.json(await listSessions()))
+app.get('/api/sessions', async (c) => c.json(await listSessions(c.req.query('all') === '1' || c.req.query('all') === 'true')))
+app.get('/api/resources', async (c) => c.json(await collectResourceReport()))
+const maintenance = sessionMaintenance()
+const maintenanceToken = (header: (name: string) => string | undefined) => header('x-spexcode-session-maintenance')?.trim() || ''
+const maintenanceLeaseOwner = () => {
+  const instanceId = process.env.SPEXCODE_INSTANCE_ID?.trim()
+  const record = instanceId ? readBackendInstanceRecords(repoRoot()).find((candidate) => candidate.instanceId === instanceId) : null
+  const exact = record ? exactProcessIdentity(record.pid) : null
+  if (!instanceId || !record || !exact || exact.startToken !== record.startToken)
+    throw new SessionMaintenanceError('maintenance_identity_unknown', 'cannot prove the exact live backend supervisor generation')
+  return { instanceId, pid: record.pid, startToken: record.startToken }
+}
+const operationAuthorization = async (
+  header: (name: string) => string | undefined,
+  operation: { op: 'stop'; sessionId: string } | { op: 'resume'; sessionId: string; force: boolean },
+): Promise<Authorization | undefined> => maintenance.authorizeHttpOperation({
+  authenticated: true,
+  projectMatches: true,
+  headers: { [maintenance.headerName]: maintenanceToken(header) },
+  operation,
+})
+app.get('/api/session-maintenance', (c) => c.json(maintenance.readState()))
+app.post('/api/session-maintenance/acquire', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  const lease = await maintenance.acquireLease({
+    capabilities: Array.isArray(body?.capabilities) ? body.capabilities : body?.capabilities,
+    owner: maintenanceLeaseOwner(),
+    ttlMs: Number(body?.ttlMs),
+    waitMs: Number(body?.waitMs),
+  })
+  return c.json(lease, lease.state === 'active' ? 201 : 202)
+})
+app.post('/api/session-maintenance/heartbeat', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  await maintenance.heartbeatLease({ token: maintenanceToken(c.req.header.bind(c.req)), epoch: Number(body?.epoch), ttlMs: Number(body?.ttlMs) })
+  return c.json({ ok: true, ...maintenance.readState() })
+})
+app.post('/api/session-maintenance/release', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  await maintenance.releaseLease({ token: maintenanceToken(c.req.header.bind(c.req)), epoch: Number(body?.epoch) })
+  return c.json({ ok: true })
+})
 // edges derived live from `spex session watch` monitors (A→B = agent A is watching B), not a stored subscription;
 // watch/unwatch register + heartbeat. A literal `edges` segment so it never collides with the `:id` routes.
 app.get('/api/sessions/edges', async (c) => c.json(await sessionGraph()))
@@ -437,19 +497,12 @@ app.get('/api/sessions/:id/timeline', (c) => {
   const r = readTimeline(c.req.param('id'), Number.isFinite(limit) && limit > 0 ? limit : undefined)
   return r ? c.json(r) : c.json({ error: 'no such session' }, 404)
 })
-// An adapter may expose its native event log as the console's optional full-process drill-down. REST establishes
-// the complete ordered snapshot + byte cursor; SSE follows appends from that cursor (or Last-Event-ID on reconnect).
-app.get('/api/sessions/:id/messages', (c) => {
-  const r = readSessionMessages(c.req.param('id'))
-  return r ? c.json(r) : c.json({ error: 'no such session' }, 404)
-})
-app.get('/api/sessions/:id/messages/stream', (c) => sessionMessageStream(c))
 // the session RECORD detail (`spex session show`): the board row (status · node · branch · launcher · …)
 // plus the full originating prompt (the row itself carries only the preview). One id-addressed read backs
 // the CLI's show; 404 for an unknown id.
 app.get('/api/sessions/:id', async (c) => {
   const id = c.req.param('id')
-  const row = (await listSessions()).find((s) => s.id === id)
+  const row = (await listSessions(true)).find((s) => s.id === id)
   if (!row) return c.json({ error: 'no such session' }, 404)
   return c.json({ ...row, prompt: await sessionPrompt(id) })
 })
@@ -460,7 +513,9 @@ app.get('/api/sessions/:id', async (c) => {
 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 resumeSession(c.req.param('id'), { force })
+  const sessionId = c.req.param('id')
+  const authorization = await operationAuthorization(c.req.header.bind(c.req), { op: 'resume', sessionId, force })
+  const r = await resumeSession(sessionId, { force, authorization })
   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
@@ -574,12 +629,22 @@ app.post('/api/sessions/:id/input', async (c) => {
 })
 // soft stop: kill the agent's tmux + socket but KEEP the worktree (resumable). Distinct from close, which
 // removes the worktree. {ok:false} = no such session.
-app.post('/api/sessions/:id/stop', async (c) => c.json({ ok: await stopSession(c.req.param('id')) }))
+app.post('/api/sessions/:id/stop', async (c) => {
+  const sessionId = c.req.param('id')
+  const authorization = await operationAuthorization(c.req.header.bind(c.req), { op: 'stop', sessionId })
+  return c.json({ ok: await stopSession(sessionId, { authorization }) })
+})
 app.post('/api/sessions/:id/interrupt', async (c) => {
   const result = await interruptSession(c.req.param('id'))
   return c.json(result, result.ok ? 200 : 502)
 })
 app.post('/api/sessions/:id/close', async (c) => c.json({ ok: await closeSession(c.req.param('id')) }))
+// archive / legacy unarchive signpost ([[archive]]) — archive proves exact cold/offline ownership before filing;
+// `{on:false}` enters the same resume transition and recreates the preserved conversation. {ok:false}=no such session.
+app.post('/api/sessions/:id/archive', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  return c.json({ ok: await archiveSession(c.req.param('id'), body?.on !== false) })
+})
 // set (or clear, with a blank) a session's display-name override; persists to the session's global record
 // (`session.json`) so it survives a restart. Unknown id → 404. That record sits INSIDE the watched store, but
 // the store watch is best-effort (it can fail to attach), so the route still nudges the stream explicitly
@@ -622,10 +687,19 @@ superviseQueue()     // launch queued sessions as slots free (catches agent-auth
 superviseTimeline()  // record authored-lifecycle transitions to each session's durable timeline ([[session-timeline]])
 console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`)
 
+let graphWatchersClosed = false
+const closeGraphWatchers = (): void => {
+  if (graphWatchersClosed) return
+  graphWatchersClosed = true
+  closeBoardFileWatchers()
+}
+process.once('exit', closeGraphWatchers)
+
 // graceful drain (the other half of zero-downtime reload, supervise.ts): on SIGTERM stop accepting new
 // connections, let in-flight requests finish, and sweep now-idle keep-alive sockets so close() fires the
 // instant the last request drains. A hard cap still forces exit if a connection won't close.
 process.on('SIGTERM', () => {
+  closeGraphWatchers()
   const srv = server as unknown as { close(cb?: () => void): void; closeIdleConnections?(): void }
   const sweep = setInterval(() => srv.closeIdleConnections?.(), 200)
   srv.close(() => { clearInterval(sweep); process.exit(0) })

package/spec-cli/src/init.ts

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, chmodSync, writeFileSync } from 'node:fs'
-import { join, resolve, relative } from 'node:path'
+import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, renameSync, rmSync, statSync, chmodSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join, resolve, relative, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
@@ -9,6 +10,32 @@ import { resolveHarnessTargets, parseHarnessFlag, NATIVE_HARNESS_IDS } from './h
 // 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')
+const MANAGED_HOOK_HEADER = '# spexcode-managed-hook-v1'
+const LEGACY_MANAGED_HOOKS: Record<string, Set<string>> = {
+  'pre-commit': new Set(['fc33a6ff2b444fa47210a2594b6a714613d9c62fd8ec77a9a13aec81143de8a7']),
+  'prepare-commit-msg': new Set(['08b26ad8ffb305a64b7cddc868231854c84d539b8e5e9324702bd2c293044183']),
+}
+
+function hookDigest(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex')
+}
+
+function isManagedHook(path: string, name: string): boolean {
+  const source = readFileSync(path, 'utf8')
+  return source.split('\n').slice(0, 4).includes(MANAGED_HOOK_HEADER)
+    || LEGACY_MANAGED_HOOKS[name]?.has(createHash('sha256').update(source).digest('hex')) === true
+}
+
+function replaceHook(source: string, dest: string): void {
+  const temp = `${dest}.spexcode-${process.pid}`
+  try {
+    copyFileSync(source, temp)
+    chmodSync(temp, 0o755)
+    renameSync(temp, dest)
+  } finally {
+    rmSync(temp, { force: true })
+  }
+}
 
 // the cumulative preset chain, lean → cautious (see [[init-preset]]). `default` is the live `.plugins`
 // instance set (planted from templates/spec); a higher tier would be a SEPARATE package under
@@ -54,6 +81,20 @@ function resolveHooksDir(dir: string): string | null {
   }
 }
 
+// Detect once, at adoption, while the root checkout still names the branch being adopted. Steady-state
+// layout never re-derives trunk identity from a mutable checkout (an ordinary `git switch node/x` must not
+// turn that feature branch into trunk).
+function adoptionMainBranch(dir: string): string {
+  try {
+    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
+    const branch = execFileSync('git', ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
+    if (branch) return branch
+  } catch { /* render the one product-level repair below */ }
+  const error = new Error('cannot determine the source-of-truth branch at adoption — check out the trunk in the root checkout, or set "mainBranch" in spexcode.json before re-running `spex init`')
+  error.name = 'ConfigError'
+  throw error
+}
+
 export async function specInit(targetArg: string | undefined, presetArg?: string, harnessArg?: string): Promise<void> {
   const targetDir = resolve(targetArg ?? process.cwd())
 
@@ -126,18 +167,23 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
   const cfgDest = join(targetDir, 'spexcode.json')
   const nativeChosen = (chosenHarnesses as unknown[]).filter((m): m is string => typeof m === 'string')
   if (existsSync(cfgDest)) {
-    if (flagRaw) {
-      // an explicit --harness on a re-init is a deliberate command: restamp THAT field, touch nothing else.
-      const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
-      cfg.harnesses = flagRaw
+    const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
+    const stampedBranch = typeof cfg.mainBranch !== 'string' || !cfg.mainBranch.trim()
+    if (stampedBranch) cfg.mainBranch = adoptionMainBranch(targetDir)
+    if (flagRaw) cfg.harnesses = flagRaw
+    if (flagRaw || stampedBranch) {
       writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
-      console.log(`✓ stamped "harnesses": ${JSON.stringify(flagRaw)} into the existing spexcode.json (other fields untouched)`)
+      console.log(`✓ stamped ${[
+        flagRaw ? `"harnesses": ${JSON.stringify(flagRaw)}` : '',
+        stampedBranch ? `"mainBranch": ${JSON.stringify(cfg.mainBranch)}` : '',
+      ].filter(Boolean).join(' and ')} into the existing spexcode.json (other fields untouched)`)
     } else {
       console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched (harnesses: ${JSON.stringify(chosenHarnesses)}).`)
     }
   } else {
     const cfg = (readJsonConfig(join(TEMPLATES, 'spexcode.json')) ?? {}) as Record<string, any>
     cfg.harnesses = chosenHarnesses
+    cfg.mainBranch = adoptionMainBranch(targetDir)
     if (nativeChosen.length && cfg.sessions?.launchers) {
       cfg.sessions.launchers = Object.fromEntries(
         Object.entries(cfg.sessions.launchers as Record<string, { harness?: string }>).filter(([, l]) => nativeChosen.includes(l.harness ?? 'claude')))
@@ -146,10 +192,11 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     }
     writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
     const roots = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
-    console.log(`✓ planted spexcode.json — harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
+    console.log(`✓ planted spexcode.json — mainBranch ${JSON.stringify(cfg.mainBranch)}, harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
   }
 
-  // 2. install the git hooks: templates/hooks/* -> <repo>/<common-git-dir>/hooks/* (skip any that exist).
+  // 2. install the git hooks. Unknown existing hooks are user-owned and stay byte-identical. An exact
+  // SpexCode snapshot is refreshed because a multi-hook protocol cannot mix old and new generations.
   const hooksDir = resolveHooksDir(targetDir)
   if (!hooksDir) {
     console.warn(`• ${targetDir} is not a git repository — skipped hook install. Run \`git init\` there, then \`spex init\` again (or \`npm run hooks\`).`)
@@ -157,18 +204,27 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     mkdirSync(hooksDir, { recursive: true })
     const hooksSrc = join(TEMPLATES, 'hooks')
     const installed: string[] = []
+    const refreshed: string[] = []
     for (const e of readdirSync(hooksSrc, { withFileTypes: true })) {
       if (!e.isFile()) continue
+      const source = join(hooksSrc, e.name)
       const dest = join(hooksDir, e.name)
       if (existsSync(dest)) {
-        console.warn(`• hook ${e.name} already exists in ${hooksDir} — left untouched.`)
+        if (hookDigest(dest) === hookDigest(source)) continue
+        if (isManagedHook(dest, e.name)) {
+          replaceHook(source, dest)
+          refreshed.push(e.name)
+        } else {
+          console.warn(`• user hook ${e.name} already exists in ${hooksDir} — left untouched.`)
+        }
         continue
       }
-      copyFileSync(join(hooksSrc, e.name), dest)
+      copyFileSync(source, dest)
       chmodSync(dest, 0o755)
       installed.push(e.name)
     }
     if (installed.length) console.log(`✓ installed git hooks (${installed.join(', ')}) → ${hooksDir}`)
+    if (refreshed.length) console.log(`✓ refreshed SpexCode hook snapshots (${refreshed.join(', ')}) → ${hooksDir}`)
   }
 
   // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched harness works with zero further
@@ -196,13 +252,15 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
   const rootsNow = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
   console.log(`
 Next steps:
-  1. Edit .spec/project/spec.md to describe YOUR project, then grow child nodes beneath it.
-  2. lint.governedRoots in spexcode.json (currently ${rootsNow}) names what \`spex spec lint\` governs —
+  1. The seeded .spec/ tree and spexcode.json are project source of truth: add and commit them. Generated
+     harness artifacts are machine-local and can stay untracked.
+  2. Edit .spec/project/spec.md to describe YOUR project, then grow child nodes beneath it.
+  3. lint.governedRoots in spexcode.json (currently ${rootsNow}) names what \`spex spec lint\` governs —
      ["."] governs the whole git-tracked tree (tests excluded); narrow it to explicit source roots
      when you want a curated graph.
-  3. Start the backend and open the dashboard:
+  4. Start the backend and open the dashboard:
        spex serve                       # http://localhost:8787
-  4. \`spex spec lint\` should report 0 errors. Coverage warnings are your adoption TODO (source files no
+  5. \`spex spec lint\` should report 0 errors. Coverage warnings are your adoption TODO (source files no
      spec node claims yet). You're adopting SpexCode — the spec tree is now ground truth.
   (On a fresh CLONE, re-run \`spex init\` — git never clones .git/hooks/, and the harness shims are
    gitignored machine-local files that regenerate per-machine.)`)

package/spec-cli/src/issues.ts

@@ -140,10 +140,43 @@ export function fromForge(slice: ForgeSlice, nodeIds: string[]): Issue[] {
 // board issue badge, the `spex issue ls` drain — is free of them by construction (they reach the EVAL side
 // through loadEvalRemarkTracks / the reading overlay instead).
 export function mergedIssues(forge: ForgeSlice | null, nodeIds: string[]): Issue[] {
+  return allThreads(forge, nodeIds).filter((i) => !isEvalConcern(i.concern))
+}
+
+// the same one merged read BEFORE the read-time split: every thread in the store, both halves, one walk.
+// Deliberately NOT exported — the split above is what every SURFACE read owes ([[eval-issue-split]]), and
+// an unsplit set escaping to a surface would put eval remarks back in the issue drain. The one consumer
+// whose question is about the STORE ITSELF reaches it through boardThreads below.
+function allThreads(forge: ForgeSlice | null, nodeIds: string[]): Issue[] {
   const remote = forge ? fromForge(forge, nodeIds) : []
-  return [...loadLocalIssues(), ...remote]
-    .filter((i) => !isEvalConcern(i.concern))
-    .sort((a, b) => b.created.localeCompare(a.created))
+  return [...loadLocalIssues(), ...remote].sort((a, b) => b.created.localeCompare(a.created))
+}
+
+// @@@ boardThreads - the board's ONE store read ([[graph-lean]]'s fold and [[remark-substrate]]'s carrier
+// from one walk). It hands back the SPLIT issue population every issue surface consumes and the freshness
+// stamp folded over the WHOLE store, together, because the two answer different questions and must not be
+// derived from each other: the split is a SURFACE question (which page renders this thread), the stamp is a
+// STORE question (was anything written at all). Folding the stamp from whatever the surface read returned
+// is exactly the confusion that left an open reading blind to every remark on it — a scenario-hosted remark
+// moved no board byte, so no push ever fired. Pairing them here means no caller can pick the wrong set.
+export function boardThreads(forge: ForgeSlice | null, nodeIds: string[]): { issues: Issue[]; stamp: string } {
+  const threads = allThreads(forge, nodeIds)
+  return { issues: threads.filter((i) => !isEvalConcern(i.concern)), stamp: threadStamp(threads) }
+}
+
+// @@@ threadStamp - the board's freshness carrier over a thread set ([[remark-substrate]] write-visibility):
+// 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 and
+// [[graph-delta]]'s no-change suppression can never swallow the push. Pure over the set it is handed, which
+// is what makes "does THIS write move it" a test rather than a claim; the caller owes it the WHOLE store
+// (allThreads), because a set missing a half is a carrier blind to that half.
+export function threadStamp(threads: Issue[]): string {
+  return [
+    threads.filter((i) => i.status === 'open').length,
+    threads.length,
+    threads.reduce((n, i) => n + i.replies.length, 0),
+    threads.flatMap((i) => [i.created, ...i.replies.flatMap((r) => [r.at, r.resolvedAt ?? ''])]).reduce((a, b) => (b > a ? b : a), ''),
+  ].join(':')
 }
 
 // @@@ createIssue - the ONE creation port, store-routed ([[issues]]): the dashboard's New form