spexcode 0.4.0 → 0.4.3

package/spec-cli/src/pty-helper.mjs

@@ -0,0 +1,86 @@
+import * as pty from 'node-pty'
+import { execFileSync } from 'node:child_process'
+
+const [id, colsArg, rowsArg] = process.argv.slice(2)
+const cols = Number(colsArg)
+const rows = Number(rowsArg)
+const socket = process.env.SPEXCODE_TMUX || 'spexcode'
+
+if (!id || !(cols > 0 && rows > 0)) {
+  process.stderr.write('ERROR invalid helper arguments\n')
+  process.exit(2)
+}
+
+// Establish the outer-terminal contract before this process owns a PTY. tmux must preserve hyperlinks and
+// wrap client updates in DEC 2026 for xterm 6; doing the setup before forkpty preserves helper isolation.
+try {
+  // The dashboard renders the pane, not tmux's client chrome. Keeping this as a tmux session option makes
+  // the requested PTY grid the pane grid too; filtering a coloured final row in xterm would corrupt real
+  // pane content. SpexCode owns these sessions, so a later foreground attach sees the same status-free pane.
+  execFileSync('tmux', ['-L', socket, 'set-option', '-t', id, 'status', 'off'])
+  // Control follows the person actually driving: `latest` sizes the window to the most recently
+  // active client, so a small screen takes the grid the moment its user interacts and sees the WHOLE
+  // pane, while an idle larger viewer letterboxes. `largest` optimized the big display's real estate
+  // but left a small concurrent viewer a cropped corner it could never take back.
+  execFileSync('tmux', ['-L', socket, 'set-window-option', '-t', id, 'window-size', 'latest'])
+  execFileSync('tmux', ['-L', socket, 'set-option', '-g', 'mouse', 'on'])
+  execFileSync('tmux', ['-L', socket, 'set-option', '-g', 'history-limit', '50000'])
+  // Wheel routing stays tmux-default: copy-mode history for a plain pane, pass-through to a
+  // mouse-owning TUI. Claude's TUI virtual-scrolls its own transcript on those reports (it lives on
+  // the alternate screen and repaints in place, so tmux history cannot substitute — an in-place
+  // renderer never scrolls lines off the top). Restore the default bindings idempotently in case an
+  // earlier release rebound them server-wide; the unbind may already be clean, so it fails quietly.
+  execFileSync('tmux', ['-L', socket, 'bind-key', '-n', 'WheelUpPane', 'if', '-F', '-t=', '#{||:#{pane_in_mode},#{mouse_any_flag}}', 'send-keys -M', 'copy-mode -et='])
+  try { execFileSync('tmux', ['-L', socket, 'unbind-key', '-n', 'WheelDownPane']) } catch { /* already unbound */ }
+  const features = execFileSync('tmux', ['-L', socket, 'show-options', '-gsv', 'terminal-features'], { encoding: 'utf8' })
+  const xtermFeatures = new Set(features.split('\n').filter((line) => line.startsWith('xterm*:')).flatMap((line) => line.split(':').slice(1)))
+  const missing = ['sync', 'hyperlinks'].filter((feature) => !xtermFeatures.has(feature))
+  if (missing.length) {
+    execFileSync('tmux', ['-L', socket, 'set-option', '-as', 'terminal-features', `,xterm*:${missing.join(':')}`])
+  }
+} catch { /* attach below fails loudly if the tmux server/session is unavailable */ }
+
+const terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
+  name: 'xterm-256color',
+  cols,
+  rows,
+  env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
+})
+
+terminal.onData((data) => process.stdout.write(Buffer.from(data, 'utf8')))
+terminal.onExit(({ exitCode }) => process.exit(exitCode === 0 ? 0 : 1))
+process.stderr.write(`READY ${terminal.pid}\n`)
+
+let input = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  input += chunk
+  let newline
+  while ((newline = input.indexOf('\n')) >= 0) {
+    const line = input.slice(0, newline)
+    input = input.slice(newline + 1)
+    if (!line) continue
+    try {
+      const message = JSON.parse(line)
+      if (message?.t === 'resize' && message.cols > 0 && message.rows > 0) {
+        const nextCols = Math.floor(message.cols)
+        const nextRows = Math.floor(message.rows)
+        terminal.resize(nextCols, nextRows)
+        process.stderr.write(`RESIZED ${nextCols} ${nextRows}\n`)
+      } else if (message?.t === 'input' && typeof message.data === 'string' && Buffer.byteLength(message.data, 'utf8') <= 64 * 1024) {
+        terminal.write(message.data)
+      }
+    } catch { /* malformed controls cannot become terminal input */ }
+  }
+})
+
+let closing = false
+function close() {
+  if (closing) return
+  closing = true
+  try { terminal.kill() } catch { /* already gone */ }
+  setTimeout(() => process.exit(0), 100).unref()
+}
+process.stdin.on('end', close)
+process.on('SIGTERM', close)
+process.on('SIGINT', close)

package/spec-cli/src/reaper.ts

@@ -1,11 +1,12 @@
-// @@@ socket-level connection reaper ([[spec-cli]]) - the ONE mechanism that actually reaps abandoned
-// sockets, because Node's own http.Server timeouts do not. MEASURED (eval server-reaps-abandoned-connections,
-// minimal http.createServer on Node 20/22/24): `headersTimeout` and `requestTimeout` DO NOT reap an
-// incomplete request — a slow-loris (TCP connect + partial headers, never completed) survives indefinitely
-// past the `connectionsCheckingInterval` sweep; only `keepAliveTimeout` (the idle-between-requests case) ever
-// fires. So the abandoned-connection pileup protection those options claim (the 135-conn starvation that
-// wedged the public port and triggered the mass-restore cascade) was NOT delivered. This helper is the real
-// mechanism: an explicit per-socket deadline at the server boundary, independent of the platform sweep.
+// @@@ socket-level connection reaper ([[spec-cli]]) - the ONE mechanism that reaps abandoned sockets (the
+// 135-conn starvation that wedged the public port and triggered the mass-restore cascade), and the SINGLE
+// OWNER of the deadlines it enforces. Node's own `headersTimeout`/`keepAliveTimeout` cover the same phases
+// (pre-request, idle-between-requests) and so are a second mechanism racing this one: MEASURED (eval
+// server-reaps-abandoned-connections, issue #65) a `headersTimeout: 20000` set beside the reaper won the
+// race on every reap at default config and silently capped SPEXCODE_REAP_HEADER_MS above 20s — the knob
+// went dead while the close still looked timely (Node's 408, not the reaper's destroy). So install()
+// DISABLES those overlapping Node timeouts on the server it guards; this helper is an explicit per-socket
+// deadline at the server boundary, with no platform machinery shadowing it.
 //
 // It keys on "no request has completed yet / idle between requests" — never on response DURATION — so a
 // long-lived ESTABLISHED stream (the /api/graph/stream SSE, a terminal WebSocket upgrade) is exempt for as
@@ -61,6 +62,13 @@ export function installConnectionReaper(server: HttpServer, opts: ReaperOptions
   const headerMs = resolveMs(opts.headerMs, process.env.SPEXCODE_REAP_HEADER_MS, 30000)
   const idleMs = resolveMs(opts.idleMs, process.env.SPEXCODE_REAP_IDLE_MS, 15000)
 
+  // claim single ownership of the phases the reaper covers (see header comment): Node's overlapping
+  // timeouts would otherwise race these deadlines and silently cap the env knobs. `requestTimeout` is
+  // deliberately LEFT at Node's default (~5 min): it bounds the in-flight request-body phase the reaper
+  // exempts (a silently-abandoned mid-body upload has no other reaper), and 5 min shadows no sane knob.
+  server.headersTimeout = 0
+  server.keepAliveTimeout = 0
+
   // per-socket tracking, on the SAME socket object 'request'/'upgrade' will report (see header comment).
   const track = (socket: Socket) => {
     const state: SocketState = {

package/spec-cli/src/reviewSnapshot.ts

@@ -0,0 +1,23 @@
+export type ReviewEvalNode = {
+  id: string
+  hue?: number
+  scenarios: any[]
+  evals: any[]
+  readings: any[]
+}
+
+export type ReviewSnapshot = {
+  issues: any[]
+  evalNodes: ReviewEvalNode[]
+}
+
+let current: ReviewSnapshot | null = null
+
+export function publishReviewSnapshot(snapshot: ReviewSnapshot): void {
+  current = snapshot
+}
+
+export function readReviewSnapshot(): ReviewSnapshot {
+  if (!current) throw new Error('review snapshot is unavailable before the first successful graph build')
+  return current
+}

package/spec-cli/src/reviews.ts

@@ -0,0 +1,347 @@
+import { createHash } from 'node:crypto'
+import { listSessions } from './sessions.js'
+import { getBoard } from './graphCache.js'
+import { buildSessionEvals, type SessionEvals } from '../../spec-eval/src/sessioneval.js'
+import { evalTimeline } from '../../spec-eval/src/evaltab.js'
+import { issuesEnabled as issuesEnabledForReview } from './localIssues.js'
+import { issueStores as issueStoresForReview } from './issues.js'
+import { readReviewSnapshot } from './reviewSnapshot.js'
+// @ts-expect-error The dashboard module is deliberately plain JS so the browser and server execute the
+// exact same tokenizer/matcher. It is shipped beside the built dashboard by the root package manifest.
+import { EVAL_FILTER_KIND, evalFilterModel, evalReviewState, issueFilterModel, tokenFilterState } from '../../spec-dashboard/src/reviewFilters.js'
+// @ts-expect-error See the shared-domain note above.
+import { EVAL_QUERY_DEFAULT, ISSUE_QUERY_DEFAULT, readToken } from '../../spec-dashboard/src/reviewQuery.js'
+
+export const REVIEW_PER_PAGE = 25
+
+type ReviewItem = Record<string, unknown>
+type ReviewOption = { value: string; label?: string; count?: number }
+type ReviewFacet = { key: string; label?: string; value: string; meaningful?: boolean; options: ReviewOption[] }
+type EvalNeighbor = { node: string; scenario: string; state: string }
+
+export type PagedReview<T extends ReviewItem = ReviewItem> = {
+  items: T[]
+  page: number
+  perPage: number
+  total: number
+  sourceTotal: number
+  pageCount: number
+  prev: number | null
+  next: number | null
+  revision: string
+  counts: Record<string, number>
+  facets: Record<string, ReviewFacet>
+  section: { key: string; value: string; options: ReviewOption[] } | null
+}
+
+export type EvalDetailReview = {
+  scope: string | null
+  selected: ReviewItem | null
+  history: ReviewItem[]
+  neighbors: {
+    prev: EvalNeighbor[]
+    next: EvalNeighbor[]
+    total: number
+    index: number | null
+    order: 'default'
+  }
+  revision: string
+  summary?: SessionEvals['summary']
+  evalRevision?: SessionEvals['evalRevision']
+}
+
+const revisionOf = (value: unknown): string => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+
+export function reviewPageNumber(value: unknown): number {
+  const raw = typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : Number.NaN
+  return Number.isSafeInteger(raw) && raw > 0 ? raw : 1
+}
+
+function responseModel(model: any): Pick<PagedReview, 'counts' | 'facets' | 'section'> {
+  const facets = Object.fromEntries(Object.entries(model.facets ?? {}).map(([key, raw]) => {
+    const facet = raw as any
+    return [key, {
+      key,
+      ...(facet.label != null ? { label: String(facet.label) } : {}),
+      value: String(facet.value ?? ''),
+      ...(facet.meaningful != null ? { meaningful: !!facet.meaningful } : {}),
+      options: (facet.options ?? []).map((option: any) => ({
+        value: String(option.value ?? ''),
+        ...(option.label != null ? { label: String(option.label) } : {}),
+        ...(Number.isFinite(option.count) ? { count: Number(option.count) } : {}),
+      })),
+    }]
+  })) as Record<string, ReviewFacet>
+  const section = model.section ? {
+    key: String(model.section.key),
+    ...(model.section.label != null ? { label: String(model.section.label) } : {}),
+    value: String(model.section.value ?? ''),
+    ...(model.section.meaningful != null ? { meaningful: !!model.section.meaningful } : {}),
+    options: (model.section.options ?? []).map((option: any) => ({
+      value: String(option.value ?? ''),
+      ...(option.label != null ? { label: String(option.label) } : {}),
+      ...(Number.isFinite(option.count) ? { count: Number(option.count) } : {}),
+    })),
+  } : null
+  return { counts: { ...(model.sections ?? {}) }, facets, section }
+}
+
+export function paginateReview<T extends ReviewItem>(
+  source: T[],
+  shown: T[],
+  model: any,
+  requestedPage: unknown,
+  revisionInputs: unknown,
+): PagedReview<T> {
+  const page = reviewPageNumber(requestedPage)
+  const total = shown.length
+  const pageCount = Math.ceil(total / REVIEW_PER_PAGE)
+  const start = (page - 1) * REVIEW_PER_PAGE
+  const overflow = pageCount > 0 ? page > pageCount : page > 1
+  return {
+    items: shown.slice(start, start + REVIEW_PER_PAGE),
+    page,
+    perPage: REVIEW_PER_PAGE,
+    total,
+    sourceTotal: source.length,
+    pageCount,
+    prev: page > 1 ? page - 1 : null,
+    next: page < pageCount || overflow ? page + 1 : null,
+    revision: revisionOf(revisionInputs),
+    ...responseModel(model),
+  }
+}
+
+const issueOrder = (a: any, b: any): number => String(b.created ?? '').localeCompare(String(a.created ?? ''))
+  || String(a.id ?? '').localeCompare(String(b.id ?? ''))
+
+export async function issuesReview(query: string | undefined, requestedPage: unknown) {
+  const [, sessions] = await Promise.all([getBoard(), listSessions()])
+  const issues = readReviewSnapshot().issues.slice().sort(issueOrder)
+  const text = String(query ?? '').trim() || ISSUE_QUERY_DEFAULT
+  const model = issueFilterModel(issues, tokenFilterState(text, 'issue'), { sessions, defaultSection: '' })
+  return {
+    enabled: issuesEnabledForReview(),
+    stores: issueStoresForReview(),
+    ...paginateReview(issues, model.shown, model, requestedPage, {
+      domain: 'issues', issues, sessions: sessions.map((session) => session.id),
+    }),
+  }
+}
+
+const byNewest = (a: any, b: any): number => String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
+  || String(a.node ?? '').localeCompare(String(b.node ?? ''))
+  || String(a.scenario ?? '').localeCompare(String(b.scenario ?? ''))
+
+export function trunkEvalReviewItems(nodes: any[]): ReviewItem[] {
+  const blind: any[] = []
+  const items: any[] = []
+  for (const node of nodes ?? []) {
+    const latest = new Map<string, any>()
+    for (const reading of node.evals ?? []) if (!latest.has(reading.scenario)) latest.set(reading.scenario, reading)
+    for (const scenario of node.scenarios ?? []) {
+      const reading = latest.get(scenario.name)
+      if (!reading) {
+        blind.push({
+          scenario: scenario.name,
+          expected: scenario.expected,
+          tags: scenario.tags,
+          node: node.id,
+          hue: node.hue,
+          filterKind: EVAL_FILTER_KIND.BLIND,
+        })
+        continue
+      }
+      items.push({
+        ...reading,
+        expected: scenario.expected ?? reading.expected,
+        tags: scenario.tags,
+        state: evalReviewState(reading),
+        node: node.id,
+        hue: node.hue,
+        filterKind: EVAL_FILTER_KIND.RESULT,
+      })
+    }
+  }
+  blind.sort((a, b) => String(a.node).localeCompare(String(b.node)) || String(a.scenario).localeCompare(String(b.scenario)))
+  return [...blind, ...items.sort(byNewest)]
+}
+
+export function scopedEvalReviewItems(model: SessionEvals): ReviewItem[] {
+  const blind: any[] = []
+  const own: any[] = []
+  const inherited: any[] = []
+  for (const node of model.nodes ?? []) {
+    const latest = new Map<string, any>()
+    for (const reading of node.evals ?? []) if (!latest.has(reading.scenario)) latest.set(reading.scenario, reading)
+    for (const scenario of node.scenarios ?? []) {
+      const reading = latest.get(scenario.name)
+      if (!reading) {
+        blind.push({
+          scenario: scenario.name,
+          expected: scenario.expected,
+          tags: scenario.tags,
+          impact: scenario.impact,
+          node: node.id,
+          hue: node.hue,
+          filterKind: EVAL_FILTER_KIND.BLIND,
+        })
+        continue
+      }
+      const item = {
+        ...reading,
+        expected: scenario.expected ?? reading.expected,
+        tags: scenario.tags,
+        state: evalReviewState(reading),
+        node: node.id,
+        hue: node.hue,
+        filterKind: EVAL_FILTER_KIND.RESULT,
+      }
+      ;(reading.inSession ? own : inherited).push(item)
+    }
+  }
+  return [...blind, ...own.sort(byNewest), ...inherited.sort(byNewest)]
+}
+
+const evalItemKey = (item: any): string => `${String(item?.node ?? '')}\0${String(item?.scenario ?? '')}`
+
+function evalNeighbor(item: any): EvalNeighbor {
+  return {
+    node: String(item.node),
+    scenario: String(item.scenario),
+    state: String(item.state ?? evalReviewState(item)),
+  }
+}
+
+export function boundedEvalNeighbors(items: ReviewItem[], node: string, scenario: string, want = 5) {
+  const key = `${node}\0${scenario}`
+  const index = items.findIndex((item) => evalItemKey(item) === key)
+  if (index < 0) return { prev: [], next: [], total: items.length, index: null, order: 'default' as const }
+  const before = index
+  const after = items.length - index - 1
+  const take = Math.min(want, before + after)
+  const nextN = Math.min(after, Math.max(Math.ceil(take / 2), take - before))
+  const prevN = Math.min(before, take - nextN)
+  return {
+    prev: items.slice(index - prevN, index).reverse().map(evalNeighbor),
+    next: items.slice(index + 1, index + 1 + nextN).map(evalNeighbor),
+    total: items.length,
+    index,
+    order: 'default' as const,
+  }
+}
+
+export function projectEvalDetail(
+  items: ReviewItem[],
+  historySource: ReviewItem[],
+  node: string,
+  scenario: string,
+  metadata: { scope?: string | null; summary?: SessionEvals['summary']; evalRevision?: SessionEvals['evalRevision'] } = {},
+): EvalDetailReview {
+  const results = items.filter((item: any) => item.filterKind === EVAL_FILTER_KIND.RESULT)
+  const selected = results.find((item) => evalItemKey(item) === `${node}\0${scenario}`) ?? null
+  const history = historySource.filter((reading: any) => String(reading.scenario) === scenario)
+  const neighbors = boundedEvalNeighbors(results, node, scenario)
+  const scope = metadata.scope ?? null
+  return {
+    scope,
+    selected,
+    history,
+    neighbors,
+    revision: revisionOf({ scope, selected, history, neighbors, summary: metadata.summary, evalRevision: metadata.evalRevision }),
+    ...(metadata.summary ? { summary: metadata.summary } : {}),
+    ...(metadata.evalRevision ? { evalRevision: metadata.evalRevision } : {}),
+  }
+}
+
+export async function evalDetailReview(node: string, scenario: string, scope?: string | null): Promise<EvalDetailReview | null> {
+  if (scope) {
+    const model = await buildSessionEvals(scope)
+    if (!model) return null
+    const sourceNode = model.nodes.find((candidate) => candidate.id === node)
+    return projectEvalDetail(scopedEvalReviewItems(model), sourceNode?.evals ?? [], node, scenario, {
+      scope,
+      summary: model.summary,
+      evalRevision: model.evalRevision,
+    })
+  }
+  await getBoard()
+  const snapshot = readReviewSnapshot()
+  const sourceNode = snapshot.evalNodes.find((candidate) => candidate.id === node)
+  return projectEvalDetail(trunkEvalReviewItems(snapshot.evalNodes), sourceNode?.readings ?? [], node, scenario)
+}
+
+async function timelineEvalReview(text: string, requestedPage: unknown) {
+  const node = readToken(text, 'node')
+  if (!node) return null
+  const [timeline, sessions] = await Promise.all([evalTimeline(node), listSessions()])
+  const measured = new Set(timeline.readings.map((reading) => reading.scenario))
+  const items = [
+    ...timeline.scenarios.filter((scenario) => !measured.has(scenario.name)).map((scenario) => ({
+      ...scenario,
+      scenario: scenario.name,
+      node,
+      filterKind: EVAL_FILTER_KIND.UNMEASURED,
+    })),
+    ...timeline.readings.map((reading, index) => ({
+      ...reading,
+      state: evalReviewState(reading),
+      node,
+      filterKind: EVAL_FILTER_KIND.RESULT,
+      filterKey: `${EVAL_FILTER_KIND.RESULT}:${index}`,
+    })),
+    ...(timeline.dangling ?? []).map((track) => ({
+      ...track,
+      node,
+      filterKind: EVAL_FILTER_KIND.DANGLING,
+      filterKey: `${EVAL_FILTER_KIND.DANGLING}:${track.threadId}`,
+    })),
+  ]
+  const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
+  return {
+    scope: null,
+    view: 'timeline',
+    node,
+    hasEvalFile: timeline.hasEvalFile,
+    gates: [],
+    unknown: 0,
+    ...paginateReview(items, filtered.shown, filtered, requestedPage, {
+      domain: 'evals', view: 'timeline', node, timeline, sessions: sessions.map((session) => session.id),
+    }),
+  }
+}
+
+export async function evalsReview(query: string | undefined, requestedPage: unknown, options: { view?: string } = {}) {
+  const text = String(query ?? '').trim() || EVAL_QUERY_DEFAULT
+  if (options.view === 'timeline') return timelineEvalReview(text, requestedPage)
+  const scope = readToken(text, 'scope') || null
+  if (scope) {
+    const model = await buildSessionEvals(scope)
+    if (!model) return null
+    const items = scopedEvalReviewItems(model)
+    const sessions = await listSessions()
+    const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
+    return {
+      scope,
+      gates: model.gates,
+      unknown: model.nodes.reduce((count, node) => count + (node.unknownCoverage?.length ?? 0), 0),
+      summary: model.summary,
+      evalRevision: model.evalRevision,
+      ...paginateReview(items, filtered.shown, filtered, requestedPage, {
+        domain: 'evals', scope, items, gates: model.gates, summary: model.summary,
+        evalRevision: model.evalRevision, sessions: sessions.map((session) => session.id),
+      }),
+    }
+  }
+  const board = await getBoard()
+  const items = trunkEvalReviewItems(readReviewSnapshot().evalNodes)
+  const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions: board.sessions, defaultKind: 'all', defaultSection: '' })
+  return {
+    scope: null,
+    gates: [],
+    unknown: 0,
+    ...paginateReview(items, filtered.shown, filtered, requestedPage, {
+      domain: 'evals', items, sessions: board.sessions.map((session) => session.id),
+    }),
+  }
+}

package/spec-cli/src/session-timeline.ts

@@ -0,0 +1,162 @@
+import { watch, existsSync, readFileSync, appendFileSync, mkdirSync, type FSWatcher } from 'node:fs'
+import { sessionsRoot, sessionStoreDir, sessionArtifactPath, listSessionIds, readAliasedRawRecord } from './layout.js'
+import type { Lifecycle, Proposal } from './sessions.js'
+
+// @@@ session-timeline - the PERSISTED interaction history of a session: every authored-lifecycle
+// transition (status + proposal + the FULL note text) and every delivered prompt, timestamped, appended to
+// `timeline.ndjson` in the session's global store dir. This is what a TERMINAL-FREE surface (the phone face,
+// [[mobile-ui]]) renders instead of a live pane: without the terminal, the declaration notes ARE the agent's
+// replies, and the timeline is the whole conversation.
+//
+// WHY an observer, not writer instrumentation: the lifecycle has a writer the TS layer never sees — the
+// mark-active hook value-replaces status/proposal/note in session.json with pure-shell sed ([[state]]).
+// Instrumenting every writer would always miss that one, so the recorder OBSERVES the store instead: one
+// fs.watch on the sessions root (debounced) plus a slow reconcile tick (the fs.watch is best-effort, same
+// stance as [[graph-stream]]'s source 1), and on each tick it diffs every governed record's
+// (status, proposal, note) against the last seen and appends what moved. One mechanism covers every writer
+// by construction. Granularity is the debounce window — a flap faster than ~100ms can collapse, exactly like
+// the board itself.
+//
+// The recorder runs ONLY in the serve process (superviseTimeline is called from index.ts) so exactly one
+// process appends; timestamps are observation times, honest to within the debounce. Only the AUTHORED axis
+// is recorded — liveness (offline/starting/unknown) is a present-tense derivation ([[state]]), re-derived
+// per probe and never history, so it stays off the durable log; a surface shows the CURRENT liveness from
+// the board row. The timeline lives and dies with the session record (close sweeps the store dir), like
+// comms.ndjson. `sent` events are appended by sendText on a CONFIRMED delivery (all prompt deliveries flow
+// through it: dashboard/phone input, `spex session send`, the merge dispatch); `from` is the sending
+// session's id, null = a human surface.
+
+export type TimelineEvent =
+  | { ts: string; kind: 'status'; status: Lifecycle; proposal: Proposal | null; note: string | null; display?: string }
+  | { ts: string; kind: 'sent'; text: string; from: string | null; replyVia?: 'note' }
+
+const timelinePath = (id: string): string => sessionArtifactPath(id, 'timeline.ndjson')
+
+function append(id: string, ev: TimelineEvent): void {
+  try {
+    mkdirSync(sessionStoreDir(id), { recursive: true })
+    appendFileSync(timelinePath(id), JSON.stringify(ev) + '\n')
+  } catch { /* best-effort: a failed history append must never break the state machine or a delivery */ }
+}
+
+function readEvents(id: string): TimelineEvent[] {
+  try {
+    const p = timelinePath(id)
+    if (!existsSync(p)) return []
+    return readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
+      try { return JSON.parse(l) as TimelineEvent } catch { return null }
+    }).filter((e): e is TimelineEvent => e != null && (e.kind === 'status' || e.kind === 'sent'))
+  } catch { return [] }
+}
+
+// the display word for an authored state — the SAME composition reconcile uses for the authored axis
+// (awaiting → its proposal's label, active → working), duplicated here as a tiny read-time map rather than
+// importing the state machine (sessions.ts imports THIS module for recordSent; a value import back would
+// be a cycle — the Lifecycle/Proposal imports above are type-only, erased at runtime).
+const PROPOSAL_DISPLAY: Record<string, string> = { merge: 'review', nothing: 'done', close: 'close-pending' }
+const displayOf = (e: { status: Lifecycle; proposal: Proposal | null }): string =>
+  e.status === 'awaiting' ? (PROPOSAL_DISPLAY[e.proposal ?? 'nothing'] ?? 'done')
+  : e.status === 'active' ? 'working' : e.status
+
+// ---- the recorder (serve-process only) ----
+
+// id → fingerprint of the last recorded (status, proposal, note); seeded per id from the persisted last
+// status line so a server restart appends nothing for a session that didn't move while the server was down —
+// and DOES append (with an honest observed-now timestamp) when it did.
+const lastSeen = new Map<string, string>()
+const fpOf = (status: string, proposal: string | null, note: string | null): string => JSON.stringify([status, proposal, note])
+
+function lastStatusEvent(id: string): { status: string; proposal: string | null; note: string | null } | null {
+  const evs = readEvents(id)
+  for (let i = evs.length - 1; i >= 0; i--) { const e = evs[i]; if (e.kind === 'status') return e }
+  return null
+}
+
+function scan(): void {
+  let ids: string[] = []
+  try { ids = listSessionIds() } catch { return }
+  for (const id of ids) {
+    try {
+      const raw = readAliasedRawRecord(id)
+      if (!raw || !raw.governed) continue
+      const status = (raw.status || 'active') as Lifecycle
+      const proposal = (raw.proposal || null) as Proposal | null
+      const note = raw.note || null
+      const fp = fpOf(status, proposal, note)
+      if (lastSeen.get(id) === fp) continue
+      if (!lastSeen.has(id)) {
+        const last = lastStatusEvent(id)
+        if (last && fpOf(last.status, last.proposal ?? null, last.note ?? null) === fp) { lastSeen.set(id, fp); continue }
+      }
+      lastSeen.set(id, fp)
+      append(id, { ts: new Date().toISOString(), kind: 'status', status, proposal, note })
+    } catch { /* one bad record must not stall the sweep */ }
+  }
+  const live = new Set(ids)
+  for (const k of [...lastSeen.keys()]) if (!live.has(k)) lastSeen.delete(k)
+}
+
+let watcher: FSWatcher | null = null
+let debounce: ReturnType<typeof setTimeout> | null = null
+let reconcile: ReturnType<typeof setInterval> | null = null
+
+// start the recorder: one debounced fs.watch on the store (a lifecycle write lands as a session.json write)
+// backstopped by a slow reconcile tick, plus an immediate first sweep. Idempotent; never throws — the
+// timeline is an accessory record, and its failure must never take the server down.
+export function superviseTimeline(): void {
+  if (!reconcile) reconcile = setInterval(scan, 60000)
+  if (!watcher) {
+    const root = sessionsRoot()
+    try { mkdirSync(root, { recursive: true }) } catch { /* best-effort */ }
+    try {
+      watcher = watch(root, { recursive: true }, () => {
+        if (debounce) return
+        debounce = setTimeout(() => { debounce = null; scan() }, 100)
+      })
+    } catch { watcher = null /* the reconcile tick still covers */ }
+  }
+  scan()
+}
+
+// the channel of the LAST HUMAN send (from == null): 'note' when the note-reply hint rode along, else null.
+// This is what makes the reply-channel hints SYMMETRIC ([[sessions-core]] sendText): a human send with no
+// note flag arriving after a note-send is the "back at a terminal" transition, and the delivery gets the
+// counter-insert. Derived from the durable log — no new state, and it survives a server restart. Agent
+// senders (`from` set) say nothing about where the HUMAN is reading, so they neither set nor clear it.
+export function lastHumanSendVia(id: string): 'note' | null {
+  const evs = readEvents(id)
+  for (let i = evs.length - 1; i >= 0; i--) {
+    const e = evs[i]
+    if (e.kind === 'sent' && e.from == null) return e.replyVia === 'note' ? 'note' : null
+  }
+  return null
+}
+
+// record a CONFIRMED prompt delivery (called by sendText after the harness accepted it). `text` is the
+// caller's message BEFORE any mechanism insert (the note-reply hint is transport, not conversation);
+// `replyVia` marks that the hint rode along so a surface can badge it.
+export function recordSent(id: string, text: string, from: string | null, replyVia?: 'note'): void {
+  try { if (!readAliasedRawRecord(id)?.governed) return } catch { return }
+  append(id, { ts: new Date().toISOString(), kind: 'sent', text, from, ...(replyVia ? { replyVia } : {}) })
+}
+
+// the read surface behind GET /api/sessions/:id/timeline: the last `limit` events, oldest first, each
+// status event carrying its composed display word. null = no such session (the route 404s).
+// Adjacent status lines with identical (status, proposal, note) fold into their first: TWO serve processes
+// observing one store (a throwaway worktree/eval serve beside the live one) each keep their own lastSeen,
+// so a single record move can append twice — cross-process write locking isn't worth buying, so the log
+// stays best-effort append-only and the read is where duplicates die, same stance as the board.
+export function readTimeline(id: string, limit = 500): { events: TimelineEvent[] } | null {
+  let raw: ReturnType<typeof readAliasedRawRecord>
+  try { raw = readAliasedRawRecord(id) } catch { return null }
+  if (!raw || !raw.governed) return null
+  const folded: TimelineEvent[] = []
+  for (const e of readEvents(id)) {
+    const prev = folded[folded.length - 1]
+    if (e.kind === 'status' && prev?.kind === 'status' && prev.status === e.status
+      && (prev.proposal ?? null) === (e.proposal ?? null) && (prev.note ?? null) === (e.note ?? null)) continue
+    folded.push(e)
+  }
+  const tail = folded.slice(Math.max(0, folded.length - Math.max(1, limit)))
+  return { events: tail.map((e) => (e.kind === 'status' ? { ...e, display: displayOf(e) } : e)) }
+}