spexcode 0.1.5 → 0.2.0

package/spec-cli/src/sessions.ts

@@ -1,12 +1,12 @@
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { randomUUID } from 'node:crypto'
-import { readFileSync, writeFileSync, appendFileSync, existsSync, renameSync, mkdirSync, rmSync, readdirSync } from 'node:fs'
-import { join, dirname, relative } from 'node:path'
+import { readFileSync, writeFileSync, appendFileSync, existsSync, renameSync, mkdirSync, rmSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { join, dirname, relative, isAbsolute } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, type ReviewDiffFile } from './git.js'
 import { loadSpecs } from './specs.js'
-import { defaultHarness, harnessById, rvSock, type Harness, type DispatchResult } from './harness.js'
+import { defaultHarness, harnessById, resolveLauncher, rvSock, rendezvousListening, type Harness, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
 import { materialize } from './materialize.js'
 import { mainBranch, gitCommonDir, readConfig, runtimeRoot, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, readAliasedRawRecord, envSessionId, type RawRecord } from './layout.js'
 
@@ -21,9 +21,11 @@ import { mainBranch, gitCommonDir, readConfig, runtimeRoot, sessionStoreDir, ses
 //   lifecycle (authored): active | idle | awaiting | parked | error | asking | queued. `idle` is the ONE
 //              inferred one (the Notification(idle_prompt) hook, guarded active-only so it never clobbers a
 //              declaration; mark-active flips it back to active on real work).
-//   liveness (derived for EVERY session): online | starting | offline. offline = no tmux for the id, or the
-//              harness online-signal (claude's rendezvous socket) is gone past the boot grace; starting =
-//              the boot window. reconcile composes the two into the compact DisplayStatus for one-glyph surfaces.
+//   liveness (derived for EVERY session): online | starting | offline | unknown. offline = no tmux for the id,
+//              or the harness online-signal (claude's rendezvous socket LISTENER — a connect, not the socket
+//              FILE) is gone past the boot grace; starting = the boot window; unknown = the tmux probe itself
+//              failed (timed out under load) so death is UNPROVEN — render probe-failed, never offline/vanish.
+//              reconcile composes the two into the compact DisplayStatus for one-glyph surfaces.
 //   awaiting → the agent's PROPOSAL, awaiting a human:
 //                proposal=merge   → shown "review"        ("ready, merge me")
 //                proposal=nothing → shown "done"          ("finished, your call")
@@ -35,8 +37,9 @@ import { mainBranch, gitCommonDir, readConfig, runtimeRoot, sessionStoreDir, ses
 //                schedule and self-resumes); an asking agent resumes only when a human sends it a prompt.
 //   queued → a prepared worktree held below the concurrency cap; the drainer launches it as a slot frees.
 //   (closed = the worktree AND the global record are removed; not a stored status)
-// The agent only ever PROPOSES (awaiting); merge/close are human-only. Every proposal is reversible
-// via reopen() → active. `merges` is METADATA (how many times merged), shown as a badge, not a state.
+// The agent only ever PROPOSES (awaiting); merge/close are human-only. Every proposal is reversible — nothing
+// auto-disappears; to withdraw one you MESSAGE the session (mark-active clears it), and a relaunch (reopen)
+// deliberately does NOT touch it. `merges` is METADATA (how many times merged), shown as a badge, not a state.
 //
 // Launch rules (CLAUDE.md / memory): private `tmux -L <label>` socket + `--dangerously-skip-permissions`.
 // SPEXCODE_TMUX / SPEXCODE_CLAUDE_CMD override both for tests.
@@ -53,8 +56,9 @@ const COLS = 120, ROWS = 32
 // cap is QUEUED, not started: it becomes a durable `queued` worktree that the drainer launches the moment a
 // slot frees (an agent stops working/dies). NOT hardcoded — configured PER PROJECT in `spexcode.json`
 // (`sessions.maxActive`), so a box can be tuned to its capacity without touching the toolchain. Precedence:
-// spexcode.json → `SPEXCODE_MAX_ACTIVE` env → default 6. Read LIVE (cheap file read) so an edit takes effect
+// spexcode.json → `SPEXCODE_MAX_ACTIVE` env → default 8. Read LIVE (cheap file read) so an edit takes effect
 // on the next drain tick, no restart. Floored at 1 so a bad value can't wedge the queue to 0.
+const DEFAULT_MAX_ACTIVE = 8
 function maxActive(): number {
   let v: number | undefined
   try {
@@ -62,7 +66,7 @@ function maxActive(): number {
     if (typeof fromJson === 'number' && Number.isFinite(fromJson)) v = fromJson
   } catch { /* config unreadable — fall through to env/default */ }
   if (v === undefined) { const e = Number(process.env.SPEXCODE_MAX_ACTIVE); if (Number.isFinite(e) && e > 0) v = e }
-  return Math.max(1, Math.floor(v ?? 6))
+  return Math.max(1, Math.floor(v ?? DEFAULT_MAX_ACTIVE))
 }
 
 // the rendezvous control socket path + its prompt-delivery/liveness logic now live in the [[harness-adapter]]
@@ -75,10 +79,12 @@ function maxActive(): number {
 // an overridden home would silently leak the session's hook-state + codex-trust to the default ~/.spexcode /
 // ~/.codex. Deterministic: the session's store = the backend's store, never the ambient env's.
 const rvEnv = (id: string, harness = HARNESS) => {
-  // SPEXCODE_SESSION_ID is the GOVERNED record id every hook resolves (hp_session_id prefers it) — it makes a
-  // codex session, whose own thread id is un-pinnable, still feed its governed record; harmless for claude
-  // (= its pinned id). The CLAUDE_BG rendezvous control socket is the reclaude prompt-delivery path and exists
-  // ONLY for harnesses that own one (claude) — codex has no such daemon, so it's omitted there.
+  // SPEXCODE_SESSION_ID is the governed record id. Claude's harness id is the same value, so hooks and CLI
+  // calls can use it directly. Codex cannot trust this env inside the long-lived shared app-server; codex hooks
+  // start from the payload thread id and alias through harness_session_id, while the short-lived codex-launch
+  // process uses this env only to store the freshly started thread id on the governed record. The CLAUDE_BG
+  // rendezvous control socket is the reclaude prompt-delivery path and exists ONLY for harnesses that own one
+  // (claude) — codex has no such daemon, so it's omitted there.
   const parts = [`SPEXCODE_SESSION_ID=${id}`]
   if (harness.ownsRendezvous) parts.push(`CLAUDE_BG_BACKEND=daemon`, `CLAUDE_BG_RENDEZVOUS_SOCK=${rvSock(id)}`)
   for (const v of ['SPEXCODE_HOME', 'CODEX_HOME']) { const val = process.env[v]; if (val) parts.push(`${v}=${val}`) }
@@ -92,16 +98,23 @@ export type { DispatchResult }
 
 export type Lifecycle = 'active' | 'idle' | 'awaiting' | 'parked' | 'error' | 'asking' | 'queued'
 export type Proposal = 'merge' | 'nothing' | 'close'
-export type DisplayStatus = 'working' | 'idle' | 'offline' | 'starting' | 'review' | 'done' | 'close-pending' | 'parked' | 'error' | 'asking' | 'queued'
+export type DisplayStatus = 'working' | 'idle' | 'offline' | 'starting' | 'review' | 'done' | 'close-pending' | 'parked' | 'error' | 'asking' | 'queued' | 'unknown'
 // liveness — the orthogonal axis to Lifecycle: whether the agent process is actually up, derived (never
 // authored) for EVERY session regardless of its lifecycle. See [[state]]: lifecycle and liveness never
 // override each other; the UI keys the terminal-mount / relaunch panel on this, the badge on lifecycle.
-export type Liveness = 'online' | 'starting' | 'offline'
+// `unknown` = the liveness PROBE ITSELF failed (the tmux snapshot timed out / errored under load), so we
+// CANNOT tell — the row renders probe-failed, NEVER offline/closed and never vanishes (board honesty: a slow
+// box must not masquerade as a graveyard, the failure that drove the mass-restore incident).
+export type Liveness = 'online' | 'starting' | 'offline' | 'unknown'
 const PROPOSAL_STATUS: Record<Proposal, DisplayStatus> = { merge: 'review', nothing: 'done', close: 'close-pending' }
 
 export type Session = {
-  id: string; node: string | null; title: string | null; name: string | null; branch: string | null; path: string
+  id: string; node: string | null; branch: string | null; path: string
+  label: string; headline: string   // the DERIVED display strings ([[session-label]]) — the only names surfaces read
+  raw: { name: string | null; title: string | null }   // the bare parts, for explicit consumers only (rename prefill)
+  parent: string | null   // the SPAWNING session's id ([[session-nesting]]) — set once at creation when `spex new` ran inside another session, else null; the frontend folds a child under it at read time
   harness: string   // which harness (claude|codex) runs this session — carried so liveness/occupancy route through its adapter
+  launcher: string | null   // the named launcher profile this session launched under ([[launcher-select]]); null → an unnamed/zero-config launch. Surfaced so a row can badge WHICH launcher (glyph + name) actually brought the worker up
   lifecycle: Lifecycle; proposal: Proposal | null; merges: number; status: DisplayStatus; liveness: Liveness; note: string | null
   prompt: string | null; promptPreview: string | null; created: number; activity: string | null
   sortKey: number | null   // manual drag-reorder override ([[session-reorder]]); null = sort by `created`
@@ -148,24 +161,40 @@ function promptPreview(prompt: string, n = 60): string {
   return first.length > n ? first.slice(0, n - 1) + '…' : first
 }
 
-// the STABLE human label for a session row: a user-chosen NAME (the rename override) wins over everything;
-// else the spec node it references, else a prompt-derived title (node-agnostic sessions), else the branch,
-// else the id. Stable across turns — used for tables/selectors. The frontend mirrors this (session.js
-// sessionName).
-export const sessionLabel = (s: Session): string => s.name || s.node || s.title || s.branch || s.id
-
-// @@@ sessionHeadline - the cross-surface HEADLINE: the SAME chain the board card shows (frontend session.js
-// `sessionHeadline`). A user-chosen NAME wins, else the worker's LIVE self-summary (`activity`, the Claude
-// Code pane title — see [[session-activity]]), else a fuller prompt preview, else node/title/branch/id. Use
-// it wherever a session is NAMED FOR A HUMAN in CROSS-SESSION comms (the reply-channel footer, the watch
-// greeting), so an agent recognises a peer the way it reads the board — NOT the bare 7-word prompt
-// truncation `title` that `sessionLabel` stops at. `sessionLabel` stays the stable name for tables/selectors.
-export const sessionHeadline = (s: Session): string => s.name || s.activity || s.promptPreview || s.node || s.title || s.branch || s.id
-
-async function tmux(args: string[]): Promise<string> {
-  const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, ...args], { encoding: 'utf8' })
+// @@@ session-label — the ONE place a session's display strings are derived ([[session-label]]). The raw
+// parts (a user rename `name`, the 7-word prompt truncation `title`) never leave this module at the top
+// level: toSession computes `label` (STABLE: name > node > title > branch > id — tables/selectors) and
+// `headline` (LIVE: name > activity > promptPreview > node > title > branch > id — what a human reads,
+// see [[session-activity]]) and the wire carries THOSE; the parts ride only under `raw` for the few
+// explicit consumers (the rename prefill). A surface that wants a session's name reads s.label/s.headline
+// — there is no bare s.title/s.name to reach for, which is the enforcement.
+export const deriveLabel = (r: { name?: string | null; node?: string | null; title?: string | null; branch?: string | null; id: string }): string =>
+  r.name || r.node || r.title || r.branch || r.id
+export const deriveHeadline = (r: { name?: string | null; activity?: string | null; promptPreview?: string | null; node?: string | null; title?: string | null; branch?: string | null; id: string }): string =>
+  r.name || r.activity || r.promptPreview || r.node || r.title || r.branch || r.id
+
+// accessors kept for the human-naming call sites (watch/notify/reply-channel): trivially the precomputed
+// wire fields, so every surface — CLI, dashboard, comms — reads the same derivation by construction.
+export const sessionLabel = (s: Session): string => s.label
+export const sessionHeadline = (s: Session): string => s.headline
+
+// @@@ tmux probe timeout - under load (the incident: load ~30 + swap thrash) a bare `tmux list-sessions` can
+// HANG, and with no bound the whole board assembly hung behind it — the dashboard froze / dropped rows, which
+// the human read as "sessions disappeared". So the liveness/title probes pass a bounded timeout; on expiry
+// execFile SIGKILLs the child and rejects with `killed:true`, which liveSnapshot tells apart from a clean
+// "no server" exit (see probeTimedOut) so a timeout renders `unknown`, not a false `offline`.
+const TMUX_PROBE_TIMEOUT_MS = 4000
+async function tmux(args: string[], timeoutMs?: number): Promise<string> {
+  const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, ...args], { encoding: 'utf8', ...(timeoutMs ? { timeout: timeoutMs, killSignal: 'SIGKILL' as const } : {}) })
   return stdout
 }
+// a rejected pexec whose child we KILLED (timeout) vs one that exited cleanly non-zero (e.g. tmux "no server
+// running" when there are genuinely no sessions). Only the former is a PROBE FAILURE (→ unknown); a clean
+// non-zero exit is authoritative (→ everything offline). node sets `killed`/`signal` when it SIGKILLs on timeout.
+function probeTimedOut(e: unknown): boolean {
+  const err = e as { killed?: boolean; signal?: string | null; code?: string }
+  return err?.killed === true || err?.signal === 'SIGKILL' || err?.code === 'ETIMEDOUT'
+}
 async function tmuxOk(args: string[]): Promise<boolean> { try { await tmux(args); return true } catch { return false } }
 export async function alive(id: string): Promise<boolean> { return tmuxOk(['has-session', '-t', id]) }
 
@@ -189,11 +218,14 @@ function pkgRoot(): string {
 // `name` is the rename override (distinct from the prompt-derived `title`); `session` is the harness session_id
 // (the store key). The launcher mints the id (`claude --session-id <id>`) so it equals what every hook payload
 // and CLAUDE_CODE_SESSION_ID carry — one id across the record dir, tmux window, rendezvous socket, and commits.
-type SessRec = {
+export type SessRec = {
   session: string; governed: boolean; worktreePath: string; branch: string | null
   node: string | null; title: string | null; name: string | null
+  parent: string | null   // the spawning session's id ([[session-nesting]]); null for a top-level launch
   status: Lifecycle; proposal: Proposal | null; merges: number; note: string | null
   sortKey: number | null; createdAt: number; harness: string; harnessSessionId: string | null
+  launcher: string | null   // the named launcher profile this session launches under ([[launcher-select]]); null → the unnamed global default (an old record, or a zero-config launch)
+  launchCmd: string | null  // the RESOLVED base launcher command pinned at creation ([[launcher-select]] resume-launcher-pin); null → old record → fall back to the launcher name / ambient
 }
 const LIFECYCLES = new Set<Lifecycle>(['active', 'idle', 'awaiting', 'parked', 'error', 'asking', 'queued'])
 const PROPOSALS = new Set<Proposal>(['merge', 'nothing', 'close'])
@@ -214,10 +246,12 @@ function fromRaw(raw: RawRecord): SessRec {
   const sortKey = typeof sk === 'number' && Number.isFinite(sk) ? sk : null
   return {
     session: raw.session_id, governed: !!raw.governed, worktreePath: raw.worktree_path || '', branch: raw.branch || null,
-    node: raw.node || null, title: raw.title || null, name: raw.name || null,
+    node: raw.node || null, title: raw.title || null, name: raw.name || null, parent: raw.parent || null,
     status, proposal, merges: Number(raw.merges) || 0, note: raw.note || null, sortKey, createdAt: Number(raw.createdAt) || 0,
     harness: raw.harness || 'claude',   // records written before the harness field default to claude
     harnessSessionId: raw.harness_session_id || null,
+    launcher: raw.launcher || null,     // records written before launchers → null → the unnamed global resolution
+    launchCmd: raw.launch_cmd || null,  // records written before the pin → null → fall back to launcher name / ambient
   }
 }
 // @@@ session.json format - written one-field-per-line (JSON.stringify(_, null, 2)) with EVERY key ALWAYS
@@ -233,6 +267,7 @@ function writeRecord(rec: SessRec): void {
     node: rec.node ?? '',
     title: rec.title ?? '',
     name: rec.name ?? '',
+    parent: rec.parent ?? '',
     status: rec.status,
     proposal: rec.proposal ?? '',
     merges: rec.merges,
@@ -241,6 +276,8 @@ function writeRecord(rec: SessRec): void {
     createdAt: rec.createdAt,
     harness: rec.harness || 'claude',
     harness_session_id: rec.harnessSessionId ?? '',
+    launcher: rec.launcher ?? '',
+    launch_cmd: rec.launchCmd ?? '',
   }
   mkdirSync(sessionStoreDir(rec.session), { recursive: true })
   writeFileSync(sessionRecordPath(rec.session), JSON.stringify(obj, null, 2) + '\n')
@@ -270,21 +307,59 @@ async function listWorktrees(): Promise<{ path: string; branch: string | null }[
 // claude's rendezvous socket is gone (claude exited), else idle if the idle_prompt hook has fired since
 // the last tool use, else working.
 
-// @@@ liveTmux - which of OUR tmux sessions exist, in ONE tmux call. reconcile used to spawn two tmux per
-// session (has-session + display-message), so listing N sessions was 2N spawns — the dominant /api/sessions
-// cost under multi-agent load. `tmux list-sessions` returns every session on our socket at once; a session
-// present in this set has a live tmux window (session_name = the id we created it with). tmux server down /
-// no sessions → empty set → everything reconciles to offline, which is correct. We deliberately do NOT read
-// `pane_current_command` any more: workers launch through the `reclaude` wrapper, which runs claude as a
-// CHILD rather than exec'ing it, so the pane's foreground command is the wrapper/shell even while claude is
-// very much alive — the pane command is NOT a liveness signal. claude liveness is its rendezvous socket
-// (see reconcile). The per-session alive() above stays for the single-session ops (capture / rawKey).
-async function liveTmux(): Promise<Set<string>> {
-  const s = new Set<string>()
+// @@@ liveTmux - which of OUR tmux sessions exist AND each pane's runtime probe, in TWO spawns total (one
+// tmux, one ps) for the WHOLE list. reconcile used to spawn two tmux per session (has-session +
+// display-message), so listing N sessions was 2N spawns — the dominant /api/sessions cost under multi-agent
+// load. `tmux list-sessions` returns every session on our socket at once; a session present here has a live
+// tmux window (session_name = the id we created it with), mapped to a PaneProbe: its pane's ROOT pid
+// (`#{pane_pid}`) plus ONE shared whole-box pid→(ppid, comm) table from a single `ps` spawn. tmux server
+// down / no sessions → empty map → everything reconciles to offline, which is correct. `live.has(id)` = the
+// window presence; `live.get(id)` = the probe, which the CODEX adapter's liveness walks to tell a running TUI
+// (a codex/node process among the pane pid's descendants) from a failed launch that dropped back to the bare
+// shell (see [[harness-adapter]] paneTreeRunsCodex — the pane's FOREGROUND command is `bash`, the launch
+// wrapper, even while the TUI renders, so the foreground name is NOT the signal). CLAUDE ignores the probe —
+// its workers launch through the `reclaude` wrapper, which runs claude as a CHILD, so claude liveness stays
+// its rendezvous socket. The per-session alive() above stays for the single-session ops (capture / rawKey).
+async function procSnapshot(): Promise<ProcTable> {
+  const t: ProcTable = new Map()
   let out = ''
-  try { out = await tmux(['list-sessions', '-F', '#{session_name}']) } catch { return s }
-  for (const line of out.split('\n')) { const name = line.trim(); if (name) s.add(name) }
-  return s
+  try { ({ stdout: out } = await pexec('ps', ['-eo', 'pid=,ppid=,comm='], { timeout: TMUX_PROBE_TIMEOUT_MS, killSignal: 'SIGKILL' })) } catch { return t }
+  for (const line of out.split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line)
+    if (m) t.set(Number(m[1]), { ppid: Number(m[2]), comm: m[3].trim() })
+  }
+  return t
+}
+// @@@ LiveSnap - the ONE liveness snapshot the whole session list shares. `windows` = our live tmux windows
+// (id → PaneProbe) + one whole-box process table; `sockets` = the ids whose rendezvous socket has a LIVE
+// LISTENER (connect-probed once here, not the file-exists lie — [[harness-adapter]]); `probeFailed` = the tmux
+// window probe itself FAILED (timed out under load), which is DISTINCT from "tmux up, no sessions" — the former
+// means death is UNPROVEN so those rows read `unknown`, the latter is authoritative and reads `offline`.
+export type LiveSnap = { probeFailed: boolean; windows: Map<string, PaneProbe>; sockets: Set<string> }
+async function liveSnapshot(): Promise<LiveSnap> {
+  const windows = new Map<string, PaneProbe>()
+  let out: string
+  try {
+    out = await tmux(['list-sessions', '-F', '#{session_name}\t#{pane_pid}'], TMUX_PROBE_TIMEOUT_MS)
+  } catch (e) {
+    // a TIMEOUT/kill is a probe FAILURE (we can't tell who's alive → unknown, never a false graveyard). A clean
+    // non-zero exit ("no server running" — genuinely zero sessions) is authoritative → the empty map = offline.
+    return { probeFailed: probeTimedOut(e), windows, sockets: new Set() }
+  }
+  const procs = await procSnapshot().catch(() => undefined)   // codex-only, auxiliary; its failure isn't a liveness failure
+  for (const line of out.split('\n')) {
+    const tab = line.indexOf('\t'); if (tab < 0) { const name = line.trim(); if (name) windows.set(name, { procs }); continue }
+    const name = line.slice(0, tab).trim(); if (!name) continue
+    const pid = Number(line.slice(tab + 1).trim())
+    windows.set(name, { panePid: Number.isFinite(pid) && pid > 0 ? pid : undefined, procs })
+  }
+  // LISTENER probe for every windowed session, once, in parallel (tooth: a live listener, not a lingering
+  // socket file). A codex session has no rvSock → instant ENOENT → not in the set, and codex ignores it anyway.
+  const ids = [...windows.keys()]
+  const listening = await Promise.all(ids.map((id) => rendezvousListening(id)))
+  const sockets = new Set<string>()
+  ids.forEach((id, i) => { if (listening[i]) sockets.add(id) })
+  return { probeFailed: false, windows, sockets }
 }
 
 // @@@ paneTitles - every session pane's RAW tmux title, free from tmux. The worker launches one pane per
@@ -305,6 +380,19 @@ async function paneTitles(): Promise<Map<string, string>> {
   return m
 }
 
+// @@@ sessionSignature - a CHEAP fingerprint of the two live board signals the session-store fs-watch can't
+// see, because they are tmux-derived, not file writes: LIVENESS (which sessions exist — a crash/offline) and
+// ACTIVITY (each pane's self-summary title). Two tmux calls, NO git and NO store walk, so [[board-stream]] can
+// poll this to push a `board-changed` the instant a worker dies or updates its headline, instead of the
+// dashboard waiting for its slow cold-path fallback. Sorted so it only moves on a real change.
+export async function sessionSignature(): Promise<string> {
+  const [snap, titles] = await Promise.all([liveSnapshot(), paneTitles()])
+  // fold in probe-failure and the live-listener set so a socket dying (claude exit) OR the probe flipping to
+  // unknown pushes a board-changed immediately, not only on window churn.
+  return (snap.probeFailed ? 'PROBEFAIL|' : '') + [...snap.windows.keys()].sort().join(',') + '#' +
+    [...snap.sockets].sort().join(',') + '|' + [...titles].sort().map(([k, v]) => `${k}=${v}`).join(',')
+}
+
 // @@@ paneActivity - the harness-aware live self-summary: the SINGLE place a raw pane title becomes (or does
 // NOT become) a session's headline activity. The board headline derives from the pane title ONLY for a
 // harness whose pane title is its own task self-summary (`paneTitleIsSelfSummary`, an adapter capability —
@@ -328,9 +416,17 @@ export function paneActivity(harness: Harness, paneTitle: string | null | undefi
 // splash. The leading glyph run (with the spaces/`·` between and after) is stripped — the dashboard draws its
 // own status dot, a frozen spinner frame is just noise — leaving only the summary text (null if it is empty).
 // ONE regex is the single source of the glyph rule: it gates (requires ≥1 glyph) and strips in one match.
+// The glyph gate alone is not enough: Claude Code emits a glyph-led SPLASH of its own app name (`✳ Claude
+// Code`) between pane birth and its first real task summary — it CLEARS the glyph gate yet is the app naming
+// itself, not the task. GENERIC_SUMMARY rejects that stripped splash too, so the row keeps its launch-prompt
+// placeholder instead of flashing "Claude Code" for a tick (the glyph-LESS `Claude Code` splash was already
+// rejected by the gate; this catches its glyph-led twin).
+const GENERIC_SUMMARY = /^claude code$/i
 export function selfSummary(paneTitle: string): string | null {
   const m = /^[\s·]*(?:[✳✶✻✽✢⠀-⣿][\s·]*)+(.*)$/u.exec(paneTitle)
-  return m ? (m[1].trim() || null) : null
+  if (!m) return null
+  const text = m[1].trim()
+  return text && !GENERIC_SUMMARY.test(text) ? text : null
 }
 
 // @@@ launchedAt - when we last started a tmux window for an id (set in launch()). claude needs ~15-20s
@@ -339,23 +435,32 @@ export function selfSummary(paneTitle: string): string | null {
 // instead of 'offline' for BOOT_GRACE_MS after launch — so 'offline' only ever means genuinely dead. In-
 // memory in the single server process (lost on restart, which is fine: a restart has nothing in flight).
 const launchedAt = new Map<string, number>()
-const BOOT_GRACE_MS = 25000   // > waitForReady's 15s timeout, covering the observed ~15-20s agent boot window
+const BOOT_GRACE_MS = 45000   // > SOCKET_READY_TIMEOUT_MS, and spans launchScript's bounded fast-fail retry
+                              // window (~3 attempts) so a relaunching session reads 'starting', not 'offline'
+const LAUNCH_FAST_FAIL_S = 12 // launchScript retries the agent command when it exits faster than this — the
+                              // launcher daemon-not-ready race fails in ~8s; a real session runs far longer
 
 // @@@ liveness - the orthogonal axis ([[state]]): is the agent process up, for ANY session regardless of
-// lifecycle, from a prebuilt tmux set (no per-call spawn — see liveTmux) + the rendezvous socket. offline
-// iff the tmux window is gone OR claude's rendezvous socket is absent past the boot window. claude (via the
-// reclaude wrapper) holds CLAUDE_BG_RENDEZVOUS_SOCK open the whole time it is alive, so the socket — NOT
-// pane_current_command, which is the wrapper/shell while claude runs as its child — is the truth it is up.
-// A just-launched agent whose socket hasn't appeared yet reads the transient 'starting' for the grace
-// window; only past it (socket still gone) is it genuinely 'offline'.
-function liveness(rec: SessRec, live: Set<string>): Liveness {
+// lifecycle, from a prebuilt runtime snapshot (no per-call spawn — see liveSnapshot) + the adapter's own channel
+// check. Order of honesty: if the PROBE ITSELF failed (tmux timed out under load) death is UNPROVEN → `unknown`
+// (render probe-failed, NEVER a false offline that empties the board and provokes a mass-restore). Else offline
+// iff the tmux window is gone OR the adapter's online-signal is absent past the boot window. claude (via the
+// reclaude wrapper) holds CLAUDE_BG_RENDEZVOUS_SOCK open the whole time it is alive, so a LIVE LISTENER on that
+// socket (`snap.sockets`, connect-probed — NOT the socket FILE, which a crash leaves behind) is the truth —
+// not the pane, whose foreground is the wrapper/shell while claude runs as its child. codex has no such socket,
+// so its truth is the pane's DESCENDANT PROCESS TREE from the SAME snapshot: a live TUI keeps a codex/node
+// process below the pane pid; a failed launch leaves the pane at a bare shell, even while the shared app-server
+// sock lingers. A just-launched agent whose online-signal hasn't appeared yet reads the transient 'starting'
+// for the grace window; only past it (still not online) is it genuinely 'offline'.
+export function liveness(rec: SessRec, snap: LiveSnap): Liveness {
   if (!rec.session) return 'offline'
-  // ask the ADAPTER ([[harness-adapter]]): claude = tmux up AND its rendezvous socket present; codex = tmux up,
-  // app-server up, AND native thread id captured. The 'starting' grace stays here (a launcher concern): a
-  // just-launched agent whose online-signal hasn't appeared yet reads 'starting' for the boot window, only past
-  // it 'offline'.
+  if (snap.probeFailed) return 'unknown'   // the probe failed — we can't tell, and MUST NOT guess offline
+  // ask the ADAPTER ([[harness-adapter]]): claude = tmux up AND a live listener on its rendezvous socket; codex
+  // = tmux up AND a codex-ish process live among the pane pid's descendants (not the bare shell a failed launch
+  // dropped back to). The 'starting' grace stays here (a launcher concern): a just-launched agent whose
+  // online-signal hasn't appeared yet reads 'starting' for the boot window, only past it 'offline'.
   const h = harnessById(rec.harness || defaultHarness.id)
-  if (h.liveness(rec, live.has(rec.session), runtimeRoot()) === 'online') return 'online'
+  if (h.liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online') return 'online'
   const at = launchedAt.get(rec.session)
   return at && Date.now() - at < BOOT_GRACE_MS ? 'starting' : 'offline'
 }
@@ -363,14 +468,14 @@ function liveness(rec: SessRec, live: Set<string>): Liveness {
 // reconcile the compact DisplayStatus — a DERIVED label composing lifecycle + liveness for one-glyph
 // surfaces ([[state]]), never a third source of truth. Lifecycle wins the label except where liveness must
 // show through: awaiting → its proposal label; parked/error/asking/queued → themselves; active/idle → their
-// liveness (offline/starting), else the active-only idle/working inference (the mark-active hook flips idle
-// → active on the next real work, self-correcting). The orthogonal liveness field is what the UI keys
+// liveness (offline/starting/unknown), else the active-only idle/working inference (the mark-active hook flips
+// idle → active on the next real work, self-correcting). The orthogonal liveness field is what the UI keys
 // terminal-mount and the relaunch panel on; this label is for badges and `spex ls`.
-function reconcile(rec: SessRec, live: Set<string>): DisplayStatus {
+function reconcile(rec: SessRec, snap: LiveSnap): DisplayStatus {
   if (rec.status === 'awaiting') return PROPOSAL_STATUS[rec.proposal || 'nothing']
   if (rec.status !== 'active' && rec.status !== 'idle') return rec.status  // parked | error | asking | queued (no tmux yet)
-  const lv = liveness(rec, live)
-  if (lv !== 'online') return lv  // 'offline' | 'starting'
+  const lv = liveness(rec, snap)
+  if (lv !== 'online') return lv  // 'offline' | 'starting' | 'unknown'
   return rec.status === 'idle' ? 'idle' : 'working'
 }
 
@@ -383,12 +488,15 @@ async function findWorktree(id: string): Promise<{ path: string; branch: string
   return { path: rec.worktreePath, branch: rec.branch, rec }
 }
 
-function toSession(rec: SessRec, status: DisplayStatus, lv: Liveness, activity: string | null = null): Session {
+export function toSession(rec: SessRec, status: DisplayStatus, lv: Liveness, activity: string | null = null): Session {
   const prompt = readPromptFile(rec.session)   // the originating ask, captured at launch (store artifact; null for old sessions)
   // activity is the LIVE pane title; it only means anything while the worker is genuinely up — a
   // dead/booting session would show a stale or absent title, so it's suppressed unless liveness is online.
   const showActivity = lv === 'online'
-  return { id: rec.session, node: rec.node, title: rec.title, name: rec.name, branch: rec.branch, path: rec.worktreePath, harness: rec.harness, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, prompt, promptPreview: prompt ? promptPreview(prompt) : null, created: rec.createdAt, activity: showActivity ? activity : null, sortKey: rec.sortKey }
+  const act = showActivity ? activity : null
+  const pp = prompt ? promptPreview(prompt) : null
+  const parts = { id: rec.session, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch, activity: act, promptPreview: pp }
+  return { id: rec.session, node: rec.node, branch: rec.branch, label: deriveLabel(parts), headline: deriveHeadline(parts), raw: { name: rec.name, title: rec.title }, path: rec.worktreePath, parent: rec.parent, harness: rec.harness, launcher: rec.launcher, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, prompt, promptPreview: pp, created: rec.createdAt, activity: act, sortKey: rec.sortKey }
 }
 
 // @@@ renameSession - set (or clear) a session's human display NAME: the user-chosen override that wins
@@ -434,8 +542,8 @@ const lastKnownSession = new Map<string, Session>()
 export async function listSessions(): Promise<Session[]> {
   // ONE store enumeration + ONE tmux liveness snapshot + ONE pane-title snapshot for the whole list (all
   // independent), then every session reconciles by a pure set lookup + one existsSync — no per-session tmux spawn.
-  const [ids, live, titles] = await Promise.all([
-    Promise.resolve(listSessionIds()), liveTmux(), paneTitles(),
+  const [ids, snap, titles] = await Promise.all([
+    Promise.resolve(listSessionIds()), liveSnapshot(), paneTitles(),
   ])
   const rows = ids.map((id) => guardSession(id, () => {
     const rec = readRecord(id)
@@ -443,7 +551,7 @@ export async function listSessions(): Promise<Session[]> {
     // the pane title → headline activity, gated by THIS session's harness ([[harness-adapter]]): claude's title
     // is its task self-summary (used); codex's is the cwd folder name (refused → headline falls to the prompt).
     const activity = paneActivity(harnessById(rec.harness || defaultHarness.id), titles.get(id))
-    const s = toSession(rec, reconcile(rec, live), liveness(rec, live), activity)
+    const s = toSession(rec, reconcile(rec, snap), liveness(rec, snap), activity)
     lastKnownSession.set(id, s)
     return s
   }, () => {
@@ -613,17 +721,26 @@ export const reportUnwatch = (token: string): Promise<void> => postJSON('/api/se
 // backend-down poll must NOT be swallowed as a transient git/tmux hiccup: watch warns ONCE and keeps
 // streaming rather than emitting false `closed` events for every session.
 export const isBackendDown = (e: unknown): boolean => e instanceof Error && e.name === 'BackendError'
+// @@@ isBackendUnreachable - the TRANSIENT subset of isBackendDown: the fetch itself failed (nothing
+// listening — ECONNREFUSED / "fetch failed"), which client.ts throws as a BackendError with NO HTTP
+// `status`. An HTTP BackendError (the backend answered non-2xx) DOES carry a status and is a real error, not
+// a momentary blip. The distinction matters to `spex wait`: a supervisor's backgrounded wait must survive
+// the ~1s window where the supervisor reboots its hot-reloaded child behind the stable port, retrying until
+// the backend answers again or the deadline hits — never dying on the in-flight fetch that a sibling merge's
+// restart happens to interrupt. Read via a structural cast (no client.ts import — that would be a cycle).
+export const isBackendUnreachable = (e: unknown): boolean =>
+  isBackendDown(e) && (e as { status?: number }).status === undefined
 
 const slugify = (s: string | null) => (s || 'session').replace(/[^a-zA-Z0-9_-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || 'session'
 
 // @@@ node + title from the prompt - the spec node a session works on is whatever it @-mentions, NOT a UI
 // "focused node": the dashboard prefills `@<focused> ` as a deletable convenience, so the node the user
 // actually left in the prompt (changed it, or deleted it for a node-agnostic prompt) is the truth. We read
-// the FIRST `@<id>` that begins a word (same positional rule the dashboard's mention menu uses). When there
-// is none, the session is node-agnostic and we label it by the first few words of the prompt instead.
+// the FIRST `[[<id>]]` topic reference ([[mentions]]: `[[node]]` is a topic, `@` is now an actor/session).
+// When there is none, the session is node-agnostic and we label it by the first few words of the prompt.
 // The OPTIONAL leading dot is load-bearing: a node id is its dir basename, so a dot-prefixed config root
-// (`.config`) keeps the dot — without `\.?` here `@.config` captures nothing and never resolves to a node.
-const MENTION = /(?:^|\s)@(\.?[A-Za-z0-9_-]+)/
+// (`.config`) keeps the dot — without `\.?` here `[[.config]]` captures nothing and never resolves to a node.
+const MENTION = /\[\[(\.?[A-Za-z0-9_-]+)\]\]/
 const mentionedNode = (prompt: string): string | null => prompt.match(MENTION)?.[1] ?? null
 function titleFromPrompt(prompt: string): string | null {
   const first = (prompt || '').trim().split('\n')[0].trim()
@@ -642,117 +759,52 @@ function titleFromPrompt(prompt: string): string | null {
 // `reclaude` wrapper, a grandchild), so the pane command is the wrapper/shell — reconcile reads claude's
 // rendezvous socket instead (present while claude is alive, gone once it exits). The file lives OUTSIDE the
 // worktree (in the store, keyed by session_id), so it never pollutes the spec/code work.
-function launchScript(id: string, tail: string, harness: Harness = HARNESS): string {
+// the launch command for THIS session ([[launcher-select]] resume-launcher-pin): the RESOLVED base command
+// PINNED on the record at creation wins — so a (re)launch replays the EXACT launcher that made the conversation
+// (and its config-dir env), never re-resolving against a since-changed default that would send `--resume` to the
+// wrong config dir and lose the transcript. Fall back to the named-launcher resolution (an old record with a
+// launcher name but no pinned cmd; fail-loud on a since-removed launcher), then undefined (truly old record →
+// the harness adapter's ambient resolution, best-effort).
+export function launcherCmd(rec: SessRec): string | undefined {
+  if (rec.launchCmd) return rec.launchCmd
+  return rec.launcher ? resolveLauncher(rec.launcher).cmd : undefined
+}
+function launchScript(id: string, tail: string, harness: Harness = HARNESS, cmd?: string): string {
   const file = join(storeDir(id), 'launch.sh')
   // NO --append-system-prompt / --settings: the contract + hooks are materialized into the worktree at
   // createSession ([[harness-delivery]]) and the agent auto-discovers them — the SAME path as a self-launched
   // agent. The launch line is just the rendezvous env + the harness command + the session-id/spec-pointer/prompt tail.
-  writeFileSync(file, `${rvEnv(id, harness)} ${harness.launchCmd(id, runtimeRoot())} ${tail}\n`)
+  // `cmd` is the session's persisted launcher command ([[launcher-select]]); when set it OVERRIDES the harness's
+  // ambient default so resume reuses the same auth, else undefined → the unnamed global resolution.
+  const invocation = `${rvEnv(id, harness)} ${harness.launchCmd(id, runtimeRoot(), cmd)} ${tail}`
+  // Bounded relaunch on a FAST exit: the agent launcher (e.g. the reclaude daemon) can lose a startup
+  // race ("daemon did not become ready") and exit within seconds before the rendezvous socket ever
+  // appears — a fast exit is the race, not real work, so retry a few times. Once the agent has run past
+  // LAUNCH_FAST_FAIL_S it has genuinely started; its eventual (much later) exit is a normal session end
+  // and is NEVER retried — the loop exits. BOOT_GRACE_MS and SOCKET_READY_TIMEOUT_MS both span this retry
+  // window, so liveness stays 'starting' and waitForReady keeps holding the slot across retries. This only
+  // closes the startup race — it adds no fallback and never masks a genuinely dead agent (3 attempts, then give up).
+  writeFileSync(file, [
+    `for __spex_try in 1 2 3; do`,
+    `  __spex_t0=$SECONDS`,
+    `  ${invocation}`,
+    `  __spex_rc=$?`,
+    `  [ $(( SECONDS - __spex_t0 )) -ge ${LAUNCH_FAST_FAIL_S} ] && exit $__spex_rc`,
+    `  printf '[spex launch] attempt %s exited in %ss (rc=%s) — likely a launcher daemon race; retrying\\n' "$__spex_try" "$(( SECONDS - __spex_t0 ))" "$__spex_rc" >&2`,
+    `  sleep 2`,
+    `done`,
+    `exit $__spex_rc`,
+    ``,
+  ].join('\n'))
   return file
 }
-async function launch(id: string, path: string, tail: string, harness: Harness = HARNESS): Promise<void> {
+async function launch(id: string, path: string, tail: string, harness: Harness = HARNESS, cmd?: string): Promise<void> {
   await tmux(['new-session', '-d', '-s', id, '-x', String(COLS), '-y', String(ROWS), '-c', path])
-  await tmux(['send-keys', '-t', id, '-l', '--', `bash ${launchScript(id, tail, harness)}`])
+  await tmux(['send-keys', '-t', id, '-l', '--', `bash ${launchScript(id, tail, harness, cmd)}`])
   await tmux(['send-keys', '-t', id, 'Enter'])
   launchedAt.set(id, Date.now())   // stamp the boot window so reconcile reads 'starting', not 'offline', until the socket is up
 }
 
-// @@@ node directives - a dashboard board chord (nn / dd) prefixes the New Session prompt with a
-// structured op the server PERFORMS in the fresh worktree before the agent starts, then hands the agent
-// a prompt to finish it intelligently. The directive is anchored at the prompt start and carries an
-// @<target>, so it's unambiguous and wins over the plain first-@ mention. `rest` is the human's own text
-// after it (what they want the new node to be, or why the node is going away). No directive → the prompt
-// is an ordinary session prompt and nothing is mutated.
-//   @new under @<parentId>: <describe the node>   → create a placeholder child, agent names+specs+codes it
-//   @delete @<nodeId>: <why / guidance>            → remove the node's dir, agent refactors per git history
-type Directive = { kind: 'new'; targetId: string; rest: string } | { kind: 'delete'; targetId: string; rest: string }
-const NEW_OP = /^\s*@new\b[^\n@]*@([A-Za-z0-9_-]+)\s*:?\s*/i
-const DEL_OP = /^\s*@delete\b[^\n@]*@([A-Za-z0-9_-]+)\s*:?\s*/i
-function parseDirective(prompt: string): Directive | null {
-  let m = prompt.match(NEW_OP); if (m) return { kind: 'new', targetId: m[1], rest: prompt.slice(m[0].length).trim() }
-  m = prompt.match(DEL_OP); if (m) return { kind: 'delete', targetId: m[1], rest: prompt.slice(m[0].length).trim() }
-  return null
-}
-
-// find a spec node's directory inside a worktree's .spec tree (id = dir basename, the node-identity rule).
-function findNodeDir(specRoot: string, nodeId: string): string | null {
-  if (!existsSync(specRoot)) return null
-  const stack = [specRoot]
-  while (stack.length) {
-    const dir = stack.pop()!
-    for (const e of readdirSync(dir, { withFileTypes: true })) {
-      if (!e.isDirectory()) continue
-      const child = join(dir, e.name)
-      if (e.name === nodeId && existsSync(join(child, 'spec.md'))) return child
-      stack.push(child)
-    }
-  }
-  return null
-}
-
-// a lint-clean placeholder spec.md: minimal valid frontmatter + a two-part body, NO `code:` list (an
-// empty governed-files list keeps `spex lint` integrity at 0 errors). The agent replaces it wholesale.
-function placeholderSpec(id: string, sessionId: string): string {
-  return [
-    '---', `title: ${id}`, 'status: pending', 'hue: 210',
-    'desc: placeholder — to be named and specified by the dispatched session.',
-    `session: ${sessionId}`, '---', `# ${id}`, '',
-    '## raw source', '',
-    'Placeholder node. The dispatched session replaces this with the real human intent, renames the',
-    'directory to a proper id, and writes the matching spec and code.', '',
-    '## expanded spec', '',
-    'Pending — authored by the dispatched session.', '',
-  ].join('\n')
-}
-// create the placeholder child under <parentId> (or the .spec root if the parent isn't in this worktree).
-// returns the new spec.md path relative to the worktree, for the agent prompt.
-function createPlaceholder(wtPath: string, parentId: string, placeholderId: string, sessionId: string): string {
-  const specRoot = join(wtPath, '.spec')
-  const parentDir = findNodeDir(specRoot, parentId) || specRoot
-  const dir = join(parentDir, placeholderId)
-  mkdirSync(dir, { recursive: true })
-  writeFileSync(join(dir, 'spec.md'), placeholderSpec(placeholderId, sessionId))
-  return relative(wtPath, join(dir, 'spec.md'))
-}
-// remove a node's whole directory (its subtree). Returns the deleted spec.md's worktree-relative path
-// (so the agent can `git log --follow` it), or null when the node isn't present in this worktree.
-function removeNode(wtPath: string, nodeId: string): string | null {
-  const dir = findNodeDir(join(wtPath, '.spec'), nodeId)
-  if (!dir) return null
-  const rel = relative(wtPath, join(dir, 'spec.md'))
-  rmSync(dir, { recursive: true, force: true })
-  return rel
-}
-
-// @@@ directive prompts - the INTENT handed to the dispatched agent. The server did the mechanical
-// spec-tree mutation; the agent does the intelligent rest (name + spec + code, or history-driven
-// refactor). Like mergePrompt, the op is a DISPATCH: the server never authors specs or refactors code.
-// These state only the TASK — they deliberately do NOT restate the git flow's mechanics (commit format, the
-// Session: trailer, the node-branch flow, the merge style). Those are carried by product MECHANISM, not a
-// dispatch string: newSession makes the branch, the prepare-commit-msg hook stamps the trailer, the
-// `core/spec` system contract (gathered into appendSysArg) demands commit-before-declare, and mergePrompt
-// states the merge style at merge time. The only handoff detail kept here is "propose merge, don't merge
-// yourself" (the human triggers
-// the merge later, see mergePrompt).
-function newNodePrompt(placeholderId: string, parentId: string, relPath: string, rest: string): string {
-  return `A placeholder spec node \`${placeholderId}\` was created under parent \`${parentId}\` at ${relPath} in this worktree. ` +
-    `Turn it into a real node and build it, per this request:\n\n${rest || '(no extra description — infer the intent from the parent and the codebase)'}\n\n` +
-    `1. Choose a good kebab-case id reflecting the intent (node id = its directory basename) and \`git mv\` the directory \`${dirname(relPath)}\` to it, keeping it under \`${parentId}\`. ` +
-    `2. Rewrite spec.md at contract altitude: real title/desc, the two-part body (raw source = human intent · expanded spec = behavioral contract), and a \`code:\` list of the files it will govern. ` +
-    `3. Implement the code the spec describes. 4. Keep \`spex lint\` at 0 errors and the build green. ` +
-    `When it's ready, propose merge for the human to review — do NOT merge it yourself.`
-}
-function deleteNodePrompt(nodeId: string, relPath: string | null, rest: string): string {
-  const recover = relPath
-    ? `Recover what it was: \`git log --follow -- ${relPath}\` then \`git show\` the relevant commits to read its old spec and the \`code:\` files it governed.`
-    : `The node's spec.md wasn't found in the tree; recover what \`${nodeId}\` was from git history (\`git log\` / \`git show\`).`
-  return `The spec node \`${nodeId}\` has been intentionally DELETED (its directory removed) in this worktree. ` +
-    `Make the codebase consistent without it, per this request:\n\n${rest || '(no extra guidance — use your judgement)'}\n\n` +
-    `1. ${recover} ` +
-    `2. Decide what happens to that governed code now the spec is gone — remove it, fold it into another node's responsibility, or re-point references — and fix any specs that linked \`[[${nodeId}]]\`. ` +
-    `3. Apply the refactor; keep \`spex lint\` at 0 errors and the build green. ` +
-    `When it's ready, propose merge for the human to review — do NOT merge it yourself.`
-}
 
 // @@@ concurrency cap + queue - keep at most maxActive() agents AUTONOMOUSLY PROGRESSING at once. A slot is
 // COMPUTE pressure, so only an agent actually consuming it holds one: genuinely live (tmux window + rendezvous
@@ -764,11 +816,11 @@ function deleteNodePrompt(nodeId: string, relPath: string | null, rest: string):
 // directly (the socket truth reconcile uses), so an authored `parked` whose claude has since died does NOT
 // pin a slot. The cap throttles concurrent COMPUTE; everything waiting-on-you waits cheap as a live pane.
 const OCCUPIES_SLOT = new Set<DisplayStatus>(['working', 'parked', 'starting'])  // starting's boot window is also held via `launching`
-function isOccupying(s: Session, live: Set<string>): boolean {
+function isOccupying(s: Session, snap: LiveSnap): boolean {
   if (!OCCUPIES_SLOT.has(s.status)) return false                          // waiting-on-human / proposed / queued / dead → free
   const rec = readRecord(s.id)
   if (!rec) return false
-  return harnessById(rec.harness || defaultHarness.id).liveness(rec, live.has(rec.session), runtimeRoot()) === 'online'  // and only while the agent is genuinely live (its adapter's channel)
+  return harnessById(rec.harness || defaultHarness.id).liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online'  // and only while the agent is genuinely live (its adapter's channel)
 }
 // sessions we've JUST launched whose agent hasn't come online yet. During that boot window reconcile reads them
 // `offline` (the adapter's online-signal not up yet) and isOccupying would miss them, so the drainer would
@@ -790,7 +842,7 @@ async function startQueued(id: string): Promise<boolean> {
   const h = harnessById(wt.rec.harness || defaultHarness.id)   // launch THIS session's chosen harness (also drives waitForReady below)
   try {
     const sq = `'${launchPrompt.replace(/'/g, `'\\''`)}'`
-    await launch(id, wt.path, `${h.sessionIdArg(id)} ${sq}`.trim(), h)
+    await launch(id, wt.path, `${h.sessionIdArg(id)} ${sq}`.trim(), h, launcherCmd(wt.rec))
   } catch {
     launching.delete(id)
     return false   // launch failed → stays `queued`, retried on the next drain tick
@@ -812,10 +864,15 @@ export async function drainQueue(): Promise<void> {
   if (draining) return
   draining = true
   try {
-    const cap = maxActive()   // read once per drain pass (spexcode.json → env → 6); won't shift mid-burst
+    const cap = maxActive()   // read once per drain pass (spexcode.json → env → default); won't shift mid-burst
     for (;;) {
-      const [sessions, live] = await Promise.all([listSessions(), liveTmux()])
-      const occupied = sessions.reduce((n, s) => n + (launching.has(s.id) || isOccupying(s, live) ? 1 : 0), 0)
+      const [sessions, snap] = await Promise.all([listSessions(), liveSnapshot()])
+      // if the liveness probe FAILED (tmux timing out — the overload condition), occupancy is UNKNOWABLE: every
+      // session would read window-less and isOccupying would undercount, so the drainer would OVER-launch and pile
+      // MORE compute onto an already-thrashing box. Under load, do the safe thing — launch nothing this pass and
+      // let the next tick re-drain once the probe recovers ([[state]] board honesty applied to the cap).
+      if (snap.probeFailed) break
+      const occupied = sessions.reduce((n, s) => n + (launching.has(s.id) || isOccupying(s, snap) ? 1 : 0), 0)
       if (occupied >= cap) break
       const next = sessions.find((s) => s.status === 'queued' && !launching.has(s.id))
       if (!next) break
@@ -840,6 +897,32 @@ export function superviseQueue(intervalMs = 3000): void {
   void tick()
 }
 
+// @@@ assertProjectMatch - the launch is PROJECT-BOUND, but routing is by URL. `spex new`'s intent is "create a
+// session for the project my cwd is in", yet `apiBase()` is SPEXCODE_API_URL||PORT||8787 — a pure URL carrying
+// no project identity. The backend it answers builds the worktree under ITS OWN mainRoot, so a stale inherited
+// SPEXCODE_API_URL (e.g. pointing at another repo's backend) silently lands the session in the WRONG repo. Read/
+// control verbs deliberately point anywhere (viewer-points-anywhere, see remote-client); only the mutating
+// launch is bound to the caller's project. So before launching, compare the caller's repo root to the backend's
+// served root and FAIL LOUD on a provable, same-host mismatch — never a silent misroute. The guard fires only on
+// a positive mismatch: no local repo, an unreachable backend, or a backend root that isn't a resolvable local
+// path (a genuinely remote backend) all fall through to allow, so legit remote dispatch is untouched.
+async function assertProjectMatch(): Promise<void> {
+  let localMain: string
+  try { localMain = realpathSync(mainRoot()) } catch { return }   // caller not in a repo → can't prove a mismatch
+  let served: string | null = null
+  try {
+    const r = await fetch(`${apiBase()}/api/layout`)
+    if (r.ok) served = (await r.json() as { main?: string }).main ?? null
+  } catch { return }                                              // backend unreachable → the POST surfaces it (fail-loud there)
+  if (!served || !isAbsolute(served)) return                      // unknown / config-aliased root → don't risk a false refusal
+  let backendMain: string
+  try { backendMain = realpathSync(served) } catch { return }     // backend root not a local path → a remote backend, allow
+  if (backendMain !== localMain)
+    throw new Error(
+      `spex new: refusing — cwd is in ${localMain} but the backend at ${apiBase()} serves ${backendMain}.\n` +
+      `Start this project's backend:  cd ${localMain} && spex serve   (or point SPEXCODE_API_URL at it)`)
+}
+
 // @@@ createSession (dispatch via backend) - `spex new` / `spex session new` must launch the worker in the
 // BACKEND's process, not the caller's. The backend owns the launch env (notably SPEXCODE_CLAUDE_CMD, which
 // reclaude strips from agent envs) AND the concurrency cap. An agent that runs `spex new` (e.g. a supervisor)
@@ -847,17 +930,23 @@ export function superviseQueue(intervalMs = 3000): void {
 // the CLI POSTs to the running backend whenever one answers, making the backend the single owner of session
 // launching. Only when NO backend is reachable do we fall back to launching in this process (with a stderr
 // warning) — the backend's own POST handler calls newSession directly, so it never re-enters this path.
-export async function createSession(node: string | null, prompt: string, harness: string = defaultHarness.id): Promise<Session> {
+export async function createSession(node: string | null, prompt: string, harness: string = defaultHarness.id, launcher?: string): Promise<Session> {
+  await assertProjectMatch()
+  // @@@ parent = the CALLER's own session ([[session-nesting]]). Resolve it HERE, in the caller's process,
+  // via the SAME ownSessionId env read [[agent-reply-channel]] uses for its sender hint — NOT inside the
+  // backend, whose process env carries no acting session id. An agent that runs `spex new` stamps its own id;
+  // a human in a plain shell has none → null → the new session is top-level (no phantom nesting).
+  const parent = ownSessionId()
   let res: Response
   try {
     res = await fetch(`${apiBase()}/api/sessions`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ node, prompt, harness }),
+      body: JSON.stringify({ node, prompt, harness, parent, launcher }),
     })
   } catch {
     console.error('spex: no backend reachable — launching in-process (caller env owns auth, no concurrency cap)')
-    return newSession(node, prompt, harness)
+    return newSession(node, prompt, harness, parent, launcher)
   }
   if (!res.ok) throw new Error(`backend rejected session (${res.status}): ${await res.text().catch(() => '')}`)
   return await res.json() as Session
@@ -866,19 +955,25 @@ export async function createSession(node: string | null, prompt: string, harness
 // @@@ newSession - durable worktree (branch node/<slug> off main) + .session label. The agent does NOT
 // launch inline any more: the worktree is prepared and parked as `queued`, then drainQueue() launches it
 // immediately if we're under the concurrency cap, else it waits its turn. Backs both the dashboard POST and
-// `spex session new`. A board directive (nn/dd) additionally mutates the worktree's spec tree up front and
-// hands the agent a finish-the-op prompt.
-export async function newSession(node: string | null, prompt: string, harness: string = defaultHarness.id): Promise<Session> {
+// `spex session new`. Creating or deleting a spec node is NOT a server op — it is prompt-driven work the
+// launched agent does itself (the composer's nn/dd chords just prefill a plain instruction). So the server
+// only ever launches a session; it never mutates the spec tree ([[mentions]]: the issue store is the sole
+// programmatic surface, every other surface is prompt only).
+export async function newSession(node: string | null, prompt: string, harness: string = defaultHarness.id, parent: string | null = null, launcher?: string): Promise<Session> {
   const id = randomUUID()
-  const h = harnessById(harness)   // throws on an unknown id — fail loud, never silently launch the wrong harness
-  const directive = parseDirective(prompt)
-  // node identity + label: a delete targets an existing node (link it); a new op has no id yet so it's
-  // labeled by the human's text; otherwise explicit --node wins, else the prompt's first @-mention.
-  const ref = directive?.kind === 'delete' ? directive.targetId
-    : directive?.kind === 'new' ? null
-    : (node || mentionedNode(prompt))
-  const title = ref ? null : titleFromPrompt(directive?.rest ?? prompt)
-  const slug = `${slugify(ref || title || (directive ? `${directive.kind}-node` : null))}-${id.slice(0, 4)}`
+  // a named launcher ([[launcher-select]]) fixes BOTH the launch command (persisted below, re-resolved at each
+  // launch so resume reuses the same auth) AND the harness — so picking one SUBSUMES the harness axis. Explicit
+  // --launcher wins, else the configured defaultLauncher; an unknown name throws fail-loud (never a silent
+  // wrong-auth launch). No launcher → the harness arg (the zero-config path) with a null launcher field → the
+  // unnamed global command resolution at launch.
+  const lname = launcher ?? readConfig(mainRoot()).sessions?.defaultLauncher ?? null
+  const chosen = lname ? resolveLauncher(lname) : null
+  const h = harnessById(chosen ? chosen.harness : harness)   // throws on an unknown id — fail loud, never silently launch the wrong harness
+  // node identity + label: explicit --node wins, else the prompt's first `[[id]]` topic ref; a prompt with
+  // none is node-agnostic and labeled by its first few words.
+  const ref = node || mentionedNode(prompt)
+  const title = ref ? null : titleFromPrompt(prompt)
+  const slug = `${slugify(ref || title)}-${id.slice(0, 4)}`
   const branch = `node/${slug}`
   const path = join(mainRoot(), '.worktrees', slug)
   await gitA(['-C', mainRoot(), 'worktree', 'add', '-b', branch, path, mainBranch()])
@@ -889,8 +984,15 @@ export async function newSession(node: string | null, prompt: string, harness: s
   // the worktree, is the board's enumeration source now).
   const rec: SessRec = {
     session: id, governed: true, worktreePath: path, branch,
-    node: ref || null, title, name: null, status: 'queued', proposal: null, merges: 0, note: null, sortKey: null, createdAt: Date.now(),
-    harness: h.id, harnessSessionId: null,
+    // parent = the SPAWNING session's id, captured ONCE here ([[session-nesting]]): a durable pointer, never
+    // mutated after. A self-parent (a resolver quirk) is dropped so a session can't nest under itself.
+    node: ref || null, title, name: null, parent: parent && parent !== id ? parent : null,
+    status: 'queued', proposal: null, merges: 0, note: null, sortKey: null, createdAt: Date.now(),
+    harness: h.id, harnessSessionId: null, launcher: lname,
+    // PIN the resolved base launcher command NOW ([[launcher-select]] resume-launcher-pin) so every future
+    // (re)launch replays THIS exact launcher — the one whose config-dir env holds the conversation — instead of
+    // re-resolving against a default that may have flipped (a backend restarted under a different launcher).
+    launchCmd: h.baseCmd(chosen?.cmd),
   }
   writeRecord(rec)
   writePromptFile(id, prompt)   // capture the ORIGINATING prompt (the human/manager's ask) as store metadata (best-effort)
@@ -900,18 +1002,9 @@ export async function newSession(node: string | null, prompt: string, harness: s
   // --append-system-prompt / --settings, and why we no longer hide CLAUDE.md: hiding it suppressed the agent's
   // own memory load too. One delivery path for both launch modes ([[harness-delivery]]).
   try { materialize(path) } catch { /* best-effort; the dispatch.sh gate re-renders on the first event anyway */ }
-  // perform the directive's spec-tree mutation in the worktree, then PARK the finish-the-op prompt for launch.
-  // the mutation is uncommitted, so the board's overlay shows it instantly (added ghost / deleted mark) even
-  // while the session only sits queued.
   let launchPrompt = prompt
-  if (directive?.kind === 'new') {
-    const placeholderId = `untitled-${id.slice(0, 4)}`
-    const relPath = createPlaceholder(path, directive.targetId, placeholderId, id)
-    launchPrompt = newNodePrompt(placeholderId, directive.targetId, relPath, directive.rest)
-  } else if (directive?.kind === 'delete') {
-    launchPrompt = deleteNodePrompt(directive.targetId, removeNode(path, directive.targetId), directive.rest)
-  } else if (ref) {
-    // @@@ spec pointer - the ref (explicit --node, else the prompt's first @mention) named an EXISTING node.
+  if (ref) {
+    // @@@ spec pointer - the ref (explicit --node, else the prompt's first [[id]] ref) named an EXISTING node.
     // Append ONE line pointing the agent at that node's spec.md as an ABSOLUTE path INSIDE its own worktree, so
     // it reads the LIVE file (never a stale snapshot we'd inject). relPath already carries the .spec/ prefix and
     // is identical in this freshly-branched worktree, so the absolute path is just join(worktree, relPath). Only
@@ -936,50 +1029,64 @@ export async function newSession(node: string | null, prompt: string, harness: s
 // BOUNDED + fail-loud preserved: a
 // genuinely dead/unrecoverable agent never goes online, so after the timeout we return and the caller's own
 // deliver() fails loud exactly as before — this only closes the startup race, it adds no fallback.
-const SOCKET_READY_TIMEOUT_MS = 15000
+const SOCKET_READY_TIMEOUT_MS = 30000   // spans launchScript's bounded fast-fail relaunch window, so
+                                        // waitForReady (slot-hold + reopen) waits through a daemon-race retry
+                                        // instead of returning before a recovering socket
 const SOCKET_POLL_MS = 200
 async function waitForReady(id: string, harness: Harness, timeoutMs = SOCKET_READY_TIMEOUT_MS): Promise<boolean> {
   const deadline = Date.now() + timeoutMs
   for (;;) {
     const rec = readRecord(id)
-    if (rec && harness.liveness(rec, await alive(id), runtimeRoot()) === 'online') return true
+    const snap = await liveSnapshot()   // window + pane probe + live-listener set in one snapshot — all the adapter needs
+    if (rec && harness.liveness(rec, snap.windows.has(id), runtimeRoot(), snap.windows.get(id), snap.sockets.has(id)) === 'online') return true
     if (Date.now() >= deadline) return false
     await new Promise((r) => setTimeout(r, SOCKET_POLL_MS))
   }
 }
 
-// @@@ reopen - "back to working": clear any proposal → active, then ONE relaunch path. The agent needs
-// (re)starting iff it isn't running for this id — the SAME deterministic liveness the adapter computes
-// ([[harness-adapter]]): claude offline = no tmux OR no rendezvous socket (claude exited, even though the
-// wrapper/shell may still hold the pane); codex offline = no tmux, no project app-server, or no captured native
-// thread id. When it IS offline we drop any stale pane and launch a fresh window through the adapter's resumeArg
-// — claude `--resume <id>` (the SAME conversation), codex `resume <thread-id>` once captured, else a fresh TUI
-// in the same worktree/record. Then we WAIT for the
-// agent to come online (waitForReady) before returning, so a caller that dispatches immediately after reopen
-// (e.g. mergeSession) addresses a LIVE agent rather than racing the boot. If it's still live we only cleared
-// the proposal — no wait. Also serves the plain "relaunch" of an offline (already-active) one. Fail-loud is
-// unchanged: if the agent never comes online, the later deliver() fails loud.
-export async function reopen(id: string): Promise<boolean> {
+// @@@ reopen - bring the agent back up and settle its RESTING lifecycle. THREE rules:
+//   • RESUME GUARD ([[state]]): a relaunch KILLS the running agent (`kill-session` + fresh window), so it is a
+//     data-loss operation the moment the agent is actually ALIVE — the incident's kill-shot was restore-on-alive
+//     (the board LIED offline, the human relaunched, live workers died mid-work). So reopen re-derives the
+//     agent's liveness FRESH and, when the caller is guarding (the human relaunch panel / `spex session reopen`,
+//     `guard` default true), REFUSES LOUD rather than relaunch a live agent — you steer a live agent by
+//     MESSAGING it, not by restoring it. Death must be PROVEN: an `unknown` probe (tmux timed out under load —
+//     the exact condition that started the incident) also refuses, since a live worker can't be ruled out. A
+//     `force` escape exists for a genuinely-wedged-but-alive process. The merge dispatch passes `guard:false`:
+//     it only needs a LIVE agent to send the merge prompt to, so an already-online agent is a satisfied no-op
+//     (never a refusal), and only a CONFIRMED-offline one is relaunched.
+//   • liveness/relaunch: relaunch only when the agent is CONFIRMED `offline` (or `force`) — never on `online`
+//     (alive), `starting` (booting), or `unknown` (unproven). We drop any stale pane and launch a fresh window
+//     through the adapter's resumeArg — claude `--resume <id>` (the SAME conversation), codex `resume
+//     <thread-id>` once captured, else a fresh TUI — then WAIT (waitForReady) so a caller that dispatches
+//     immediately after (mergeSession's merge) addresses a LIVE agent, not a racing boot.
+//   • lifecycle: the SAME active-only guard markIdle uses — a resumed agent that was WORKING (`active`) is now
+//     just sitting at its prompt → `idle`; EVERY deliberate declaration survives untouched (`awaiting` + its
+//     proposal, `asking`, `parked`, `error`, `queued`). reopen does NOT touch the `proposal` — resuming a
+//     session that is proposing a merge must NOT silently withdraw it. Only applied when we actually relaunch;
+//     a refusal leaves the record wholly untouched.
+// Fail-loud is unchanged: if the agent never comes online, the later deliver() fails loud.
+export async function reopen(id: string, opts: { force?: boolean; guard?: boolean } = {}): Promise<{ ok: boolean; error?: string; refused?: boolean }> {
+  const { force = false, guard = true } = opts
   const wt = await findWorktree(id)
-  if (!wt) return false
+  if (!wt) return { ok: false, error: `no such session ${id}` }
   const h = harnessById(wt.rec.harness || defaultHarness.id)
-  writeRecord({ ...wt.rec, status: 'active', proposal: null })
-  if (h.liveness(wt.rec, await alive(id), runtimeRoot()) !== 'online') {
-    await tmuxOk(['kill-session', '-t', id])   // drop a dead/offline pane if any (no-op when none)
-    await launch(id, wt.path, h.resumeArg(wt.rec).trim(), h)
+  const lv = liveness(wt.rec, await liveSnapshot())   // FRESH, honest liveness (listener-verified) — the guard must not trust a stale board reading
+  if (guard && !force && lv === 'online')
+    return { ok: false, refused: true, error: `session ${id} is ALIVE — refusing to relaunch, which would kill a live worker mid-work. To steer it, send it a message; use force only for a genuinely wedged (but alive) process.` }
+  if (guard && !force && lv === 'unknown')
+    return { ok: false, refused: true, error: `session ${id}: the liveness probe failed (the box is likely overloaded) — refusing to relaunch since a live worker can't be ruled out. Retry in a moment, or use force to override.` }
+  // proceeding: settle the RESTING lifecycle (a resumed working agent is now idle), then relaunch iff the agent
+  // is CONFIRMED offline (or force — the wedged-but-alive escape). `starting`/`unknown` fall through to a no-op.
+  writeRecord({ ...wt.rec, status: wt.rec.status === 'active' ? 'idle' : wt.rec.status })
+  if (force || lv === 'offline') {
+    await tmuxOk(['kill-session', '-t', id])   // drop a dead/offline pane (or a force-killed live one)
+    await launch(id, wt.path, h.resumeArg(wt.rec).trim(), h, launcherCmd(wt.rec))   // resume under the SAME persisted launcher ([[launcher-select]])
     await waitForReady(id, h)   // a relaunched agent is "ready" only once the adapter reads it online
   }
-  return true
+  return { ok: true }
 }
 
-// agent/human PROPOSAL → awaiting (review = propose merge, done = nothing, close-pending = propose close).
-export async function propose(id: string, proposal: Proposal): Promise<boolean> {
-  const wt = await findWorktree(id)
-  if (!wt) return false
-  writeRecord({ ...wt.rec, status: 'awaiting', proposal })
-  void drainQueue()   // a proposal frees this session's slot — start the next queued one if any
-  return true
-}
 // @@@ agent-authored state - the agent (forced by gates at boundaries) writes its OWN state; it is the
 // authority on what a stop MEANS (awaiting human vs parked on a background task). External hooks only know
 // SOMETHING changed, not the transition, so they force a write, never infer. The session it writes is resolved
@@ -1064,13 +1171,15 @@ function porcelainPath(line: string): string {
 // @@@ MANAGER COCKPIT - the review payload (the cockpit's first verb; see the manager-cockpit spec node).
 // One server-side bundle that lets a manager (human or agent) decide whether to merge a session WITHOUT
 // hand-running git: how far ahead it is, its REAL changes (merge-base diff, never a phantom main..HEAD one),
-// whether uncommitted non-runtime work remains, the merge/typecheck/lint gates, and the agent's standing
-// proposal. ahead/dirty/diff/conflicts are computed against the SESSION's worktree (per id); typecheck and
-// lint reflect the CLI package's OWN location (where this runs) — the spec-cli that's actually live. null
-// when no session has that id.
+// whether uncommitted non-runtime work remains, the merge/lint gates, and the agent's standing proposal.
+// ahead/dirty/diff/conflicts are computed against the SESSION's worktree (per id); lint reflects the CLI
+// package's OWN location (where this runs) — the spec-cli that's actually live. There is deliberately NO
+// build/typecheck/test gate: whether a change is SOUND is proven by the node's yatsu (measured through the
+// real product), not by a language-specific automated checker — so the gates stay language-agnostic (git +
+// the spec↔code graph, which every governed project has, TS or Python or otherwise). null when no session
+// has that id.
 export type ReviewGates = {
   conflictsWithMain: boolean                       // a dry-run merge into main would conflict (in-memory, safe)
-  typecheck: { ok: boolean; errorCount: number }   // `tsc --noEmit` on the CLI package
   lint: { errorCount: number; warningCount: number } // the spec↔code graph lint
 }
 export type ReviewPayload = {
@@ -1082,37 +1191,59 @@ export type ReviewPayload = {
   proposal: { kind: Proposal | null; note: string | null }   // the session's standing proposal + its note
 }
 
-// @@@ typecheckPkg - `tsc --noEmit` on the CLI package at its OWN location (pkgRoot — never a hardcoded
-// path), using the tsc binary from that package's node_modules. errorCount counts `error TSxxxx` lines; ok
-// is the exit status. If tsc can't be spawned at all (no node_modules) it resolves ok:false / 0 errors — a
-// loud "couldn't typecheck" rather than a false green.
-function typecheckPkg(): Promise<{ ok: boolean; errorCount: number }> {
-  const root = pkgRoot()
-  const tsc = join(root, 'node_modules', '.bin', 'tsc')
-  return new Promise((resolve) => {
-    execFile(tsc, ['--noEmit'], { cwd: root, encoding: 'utf8', maxBuffer: 1 << 24 }, (err, stdout) => {
-      const out = (stdout || '') + (err && (err as unknown as { stdout?: string }).stdout || '')
-      resolve({ ok: !err, errorCount: (out.match(/error TS\d+/g) || []).length })
-    })
-  })
+// @@@ lintGate - the spec↔code graph lint is a LOCATION gate: a function of the backend checkout's tree ALONE
+// (its .spec graph + governed files), not of which session is reviewed, and it costs a few seconds. Re-running
+// it on every reviewPayload — i.e. on every [[review-proof]] Proof-tab open, and once per session — is
+// wasteful, so memoize it on a whole-repo fingerprint: `rev-parse HEAD` + `status --porcelain` + the mtimes of
+// the changed paths (covers committed state, the dirty SET, and dirty-file CONTENT). An identical fingerprint
+// reuses the last (in-flight) result — a re-open or a second session's proof is instant — while any commit or
+// working-tree edit moves the fingerprint and recomputes. A rejected run is not cached.
+let gateCache: { fp: string; p: Promise<ReviewGates['lint']> } | null = null
+async function lintGate(): Promise<ReviewGates['lint']> {
+  const root = repoRoot()
+  const [head, status] = await Promise.all([
+    gitA(['-C', root, 'rev-parse', 'HEAD']),
+    gitA(['-C', root, 'status', '--porcelain', '--untracked-files=all']),
+  ])
+  // `status --porcelain` gives the SET of changed paths + status letters but is CONTENT-BLIND: re-editing an
+  // already-listed (dirty or untracked) file leaves the string byte-identical, so HEAD+status alone would
+  // freeze the gate after a file first goes dirty. `--untracked-files=all` stops an untracked dir from
+  // collapsing to one line (which hides a newly-added file); then fold each listed path's mtime in, so a
+  // content edit to a dirty file also moves the fingerprint. HEAD covers committed state, this covers the
+  // working tree. (Residual, accepted: the fingerprint is snapshot just before the compute, so a change
+  // landing mid-compute is labelled with the pre-change fp — rare, and the gate is advisory, re-verified at merge.)
+  const mtimes = status.split('\n').filter(Boolean).map(porcelainPath)
+    .map((p) => { try { return statSync(join(root, p)).mtimeMs } catch { return 0 } }).join(',')
+  const fp = head.trim() + '\n' + status + '\n' + mtimes
+  if (gateCache?.fp === fp) return gateCache.p
+  const p = (async () => {
+    const { specLint } = await import('./lint.js')
+    const findings = await specLint()
+    return {
+      errorCount: findings.filter((f) => f.level === 'error').length,
+      warningCount: findings.filter((f) => f.level === 'warn').length,
+    }
+  })()
+  p.catch(() => { if (gateCache?.p === p) gateCache = null })   // don't pin a failed run
+  gateCache = { fp, p }
+  return p
 }
 
-// @@@ reviewPayload - assemble the cockpit review for one session. The five session-specific reads
-// (ahead / dirty / diff / conflict gate) plus the two location gates (typecheck / lint) are all
-// independent, so they run in parallel. lint is the existing spec-lint module run in-process (it reports
-// over this process's repo — the CLI package's own tree).
+// @@@ reviewPayload - assemble the cockpit review for one session. The four session-specific reads
+// (ahead / dirty / diff / conflict gate) plus the one location gate (lint) are all independent, so they run
+// in parallel. The lint gate goes through lintGate(), which memoizes it on the checkout's tree fingerprint —
+// so an unchanged tree doesn't re-run the lint on each review / Proof-tab open, while any commit or edit
+// invalidates and recomputes.
 export async function reviewPayload(id: string): Promise<ReviewPayload | null> {
   const wt = await findWorktree(id)
   if (!wt) return null
-  const { specLint } = await import('./lint.js')
   const base = mainBranch()
-  const [aheadOut, statusOut, diff, conflictsWithMain, typecheck, findings] = await Promise.all([
+  const [aheadOut, statusOut, diff, conflictsWithMain, lint] = await Promise.all([
     gitA(['-C', wt.path, 'rev-list', '--count', `${base}..HEAD`]),
     gitA(['-C', wt.path, 'status', '--porcelain', '--untracked-files=all']),
     mergeBaseDiff(wt.path, base),
     mergeConflicts(wt.path, base),
-    typecheckPkg(),
-    specLint(),
+    lintGate(),   // lint — memoized on the checkout fingerprint, not re-run per session/open
   ])
   // the worktree carries no SpexCode runtime files any more (the store lives in ~/.spexcode), so every dirty
   // path is genuine work — this is just the total uncommitted count.
@@ -1121,13 +1252,7 @@ export async function reviewPayload(id: string): Promise<ReviewPayload | null> {
     id, node: wt.rec.node, branch: wt.branch,
     ahead: Number(aheadOut.trim()) || 0,
     dirtyNonRuntime, diff,
-    gates: {
-      conflictsWithMain, typecheck,
-      lint: {
-        errorCount: findings.filter((f) => f.level === 'error').length,
-        warningCount: findings.filter((f) => f.level === 'warn').length,
-      },
-    },
+    gates: { conflictsWithMain, lint },
     proposal: { kind: wt.rec.proposal, note: wt.rec.note },
   }
 }
@@ -1150,8 +1275,9 @@ function mergePrompt(mainPath: string, branch: string, reason: string): string {
 
 // @@@ mergeSession - the cockpit's ACT verb, the sequel to review — but a DISPATCH, not a server script: the
 // SESSION'S OWN agent lands the merge, never the server (it carries no `git merge` logic and never touches
-// main's tree). It reopens the session (clears the proposal → active, `--resume`s via reopen if tmux died —
+// main's tree). It reopens the session (clears the proposal, `--resume`s via reopen if tmux died —
 // which waits for the rendezvous socket, closing the just-relaunched-no-socket race) and dispatches mergePrompt
+// — that delivered prompt flips the lifecycle to active regardless of reopen's resting state
 // through sendKeys. The reason = the node branch's latest commit subject minus a leading `spec: ` (visible from
 // the main checkout, no worktree path needed). Async + fail-loud: returns {dispatched:true} once the prompt is
 // CONFIRMED accepted, else {dispatched:false, reason} (the loud DispatchResult error). The server no longer
@@ -1160,7 +1286,10 @@ export async function mergeSession(id: string): Promise<{ dispatched: boolean; r
   const wt = await findWorktree(id)
   if (!wt || !wt.branch) return { dispatched: false, reason: 'no such session' }
   const branch = wt.branch, main = mainRoot()
-  if (!(await reopen(id))) return { dispatched: false, reason: 'could not reopen session' }
+  // ensure-live, NOT the guarded human relaunch: an already-online agent is reused (the merge prompt just needs
+  // a live socket), and only a confirmed-offline one is relaunched — so merge never refuses on a live agent.
+  const re = await reopen(id, { guard: false })
+  if (!re.ok) return { dispatched: false, reason: re.error || 'could not reopen session' }
   const subject = (await gitA(['-C', main, 'log', '-1', '--format=%s', branch])).trim()
   const reason = subject.replace(/^spec:\s+/, '') || branch
   const r = await sendKeys(id, mergePrompt(main, branch, reason))
@@ -1237,10 +1366,10 @@ export async function captureSessionResult(id: string): Promise<CaptureResult> {
 // @@@ presentation + selection - shared by `spex ls` (pretty), `spex watch` (events) and the API.
 export const STATUS_GLYPH: Record<DisplayStatus, string> = {
   working: '\u25cf', idle: '\u25cb', offline: '\u23fb', starting: '\u25d4', review: '\u25c6', done: '\u2713',
-  'close-pending': '\u2715', parked: '\u29d6', error: '\u2717', asking: '\u2370', queued: '\u25cc',
+  'close-pending': '\u2715', parked: '\u29d6', error: '\u2717', asking: '\u2370', queued: '\u25cc', unknown: '\u2047',
 }
 const ANSI: Record<DisplayStatus, string> = {
-  working: '33', idle: '90', offline: '90', starting: '36', review: '35', done: '34', 'close-pending': '31', parked: '36', error: '31', asking: '93', queued: '90',
+  working: '33', idle: '90', offline: '90', starting: '36', review: '35', done: '34', 'close-pending': '31', parked: '36', error: '31', asking: '93', queued: '90', unknown: '93',
 }
 
 // @@@ session selectors - the ONE matcher every session command shares (see [[session-selectors]]). A
@@ -1249,7 +1378,13 @@ const ANSI: Record<DisplayStatus, string> = {
 // resolution can never drift between "which sessions ls/watch/wait/graph show" and "which session
 // review/merge/send/close act on".
 export function matchesSelector(s: Session, q: string): boolean {
-  return s.id === q || s.id.startsWith(q) || s.node === q || s.branch === q
+  // a selector may be a comma-separated list (the same convention as `--status a,b`): it matches iff ANY part
+  // names the session, so `watch a,b` and `watch a b` are equivalent. A single name is the one-part case. This
+  // is what stops a comma-joined selector from silently matching nothing — an id/node/branch never holds a
+  // comma, so without the split `a,b` would be one literal selector that matches no session and streams in
+  // silence forever.
+  return q.split(',').map((p) => p.trim()).filter(Boolean)
+    .some((p) => s.id === p || s.id.startsWith(p) || s.node === p || s.branch === p)
 }
 
 // no selectors (or '@all') = everything. Optional status filter on top. This IS the ls/watch subscription.
@@ -1311,9 +1446,9 @@ export function formatTable(sessions: Session[], color = true): string {
 
 const WATCH_ACTIONABLE = new Set<DisplayStatus>(['review', 'done', 'close-pending', 'offline', 'error', 'asking'])
 const NEXT: Record<string, string> = {
-  review: 'merge | reopen(back-to-working) | close',
-  done: 'merge | reopen | close',
-  'close-pending': 'close | reopen',
+  review: 'merge | close',
+  done: 'merge | close',
+  'close-pending': 'close',
   offline: 'reopen (relaunch & resume)',
   error: 'reopen (relaunch & retry) | capture | close',
   asking: 'send "<msg>" | capture',
@@ -1354,6 +1489,7 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
   const deadline = until ? Date.now() + Math.max(1000, until.timeoutMs) : 0
   const isActionable = (st: DisplayStatus) => WATCH_ACTIONABLE.has(st) || (includeIdle && st === 'idle')
   let warnedDown = false
+  let downMsg: string | null = null   // set while the backend is unreachable, cleared on a good poll; the deadline reports it
   for (;;) {
     try {
       // EXISTENCE is the selector-matched board across ALL statuses — listSessions now lists every worktree
@@ -1362,7 +1498,7 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
       // emit, never whether a session is present — using it for presence would read a status change out of the
       // filtered set as a (false) removal.
       const all = selectSessions(await source(), selectors)
-      warnedDown = false   // a successful poll re-arms the down-warning, so a recovered-then-redowned backend warns again
+      warnedDown = false; downMsg = null   // a successful poll re-arms the down-warning (and clears the deadline's down-report)
       const ids = new Set(all.map((s) => s.id))
       const passesStatus = (st: DisplayStatus) => !statuses?.length || statuses.includes(st)
       for (const s of all) {
@@ -1389,23 +1525,33 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
         if (!all.length) return { gone: true }
       }
     } catch (e) {
-      // a backend-down poll must NOT be swallowed as a transient hiccup AND must NOT emit a false `closed`
-      // for every session: we skip the tick (prev is untouched → no phantom removals) and warn ONCE, loudly,
-      // so a manager sees the stream is blind rather than reading silence as "all sessions fine".
-      if (until && isBackendDown(e)) return { backendDown: (e as Error).message }   // a bounded wait fails loud, never a false timeout
-      if (isBackendDown(e) && !warnedDown) { warnedDown = true; console.error(`${tag}[spex] watch: ${(e as Error).message}; retrying every ${intervalMs / 1000}s…`) }
+      // a backend error in the poll must NOT be swallowed AND must NOT emit a false `closed` for every session:
+      // we skip the tick (prev is untouched → no phantom removals). Two shapes of BackendError diverge here:
+      //  • REACHABLE but erroring (an HTTP status) — the backend answered and is broken: a real terminal
+      //    condition, so a bounded `wait` fails loud IMMEDIATELY rather than spinning out its whole timeout.
+      //  • UNREACHABLE (no status — ECONNREFUSED / fetch failed) — nothing is listening, e.g. the supervisor
+      //    is rebooting its hot-reloaded child behind the stable port on a sibling merge. This is TRANSIENT:
+      //    record it, warn ONCE, and keep polling — the deadline (below) is the only hard wall, so a
+      //    backgrounded `spex wait` survives the ~1s restart instead of dying on the interrupted fetch.
+      if (until && isBackendDown(e) && !isBackendUnreachable(e)) return { backendDown: (e as Error).message }
+      if (isBackendDown(e)) {
+        downMsg = (e as Error).message
+        if (!warnedDown) { warnedDown = true; console.error(`${tag}[spex] watch: ${downMsg}; retrying every ${intervalMs / 1000}s…`) }
+      }
     }
-    // the HARD wall — checked every iteration, in EVERY state, even after a thrown poll, BEFORE the sleep:
-    // this is what guarantees `spex wait` can never hang on a worker stuck outside WATCH_ACTIONABLE.
-    if (until && Date.now() >= deadline) return { timedOut: true }
+    // the HARD wall — checked every iteration, in EVERY state, even after a thrown poll, BEFORE the sleep: this
+    // guarantees `spex wait` can never hang on a worker stuck outside WATCH_ACTIONABLE — nor spin forever on a
+    // backend that never comes back. Hitting the deadline while still unreachable reports THAT (`backendDown`),
+    // not a false "no actionable status" timeout, so the manager sees the honest cause.
+    if (until && Date.now() >= deadline) return downMsg ? { backendDown: downMsg } : { timedOut: true }
     await sleep(intervalMs)
   }
 }
 
 // @@@ sendKeys - PROMPT control for a session, delivered through the session's HARNESS ADAPTER
-// ([[harness-adapter]]) — claude the rendezvous control socket (inject + submit + confirm accepted), codex
-// app-server JSON-RPC into the visible TUI's thread. Either way there is NO silent fallback: a prompt that can't be
-// delivered — no socket / dead agent (claude), no app-server/thread (codex) — FAILS LOUD, returning
+// ([[harness-adapter]]) — claude the rendezvous control socket (optimistic-after-liveness: the reply line flushes
+// to a live socket), codex app-server JSON-RPC into the visible TUI's thread. Either way there is NO silent
+// fallback: a prompt that can't be delivered — no socket / dead agent (claude), no app-server/thread (codex) — FAILS LOUD, returning
 // ok:false with a reason that propagates to the caller (API non-2xx, `spex session send`, the merge dispatch),
 // instead of reporting a false success. The harness is resolved from the record; an unknown id fails before any
 // harness transport is addressed. (The separate RAW nav-key channel keeps its own `tmux send-keys` path — see rawKey.)
@@ -1441,8 +1587,9 @@ const TMUX_KEY: Record<string, string> = {
 // literal text "S-Enter" etc. (and shift is a no-op there anyway), so a stray S- is dropped. Shift+Tab is
 // the named exception: tmux spells it `BTab` (back-tab → ESC[Z, what Claude Code's mode-cycle reads).
 const SHIFTABLE = new Set(['Up', 'Down', 'Left', 'Right', 'Home', 'End', 'DC'])
-export async function rawKey(id: string, key: string): Promise<boolean> {
-  if (!key || !(await alive(id))) return false
+// resolve ONE frontend token to the `tmux send-keys` args for it, or null if it isn't a known base after its
+// prefixes (defends the send-keys arg). Pure — the batch loop below sequences the actual sends.
+function rawKeyArgs(id: string, key: string): string[] | null {
   // peel the optional C-/M-/S- modifier prefixes (each at most once, in any order) off the front; the
   // remainder is the BASE key. The frontend only ever sends {C-,M-,S-} prefixes + a named key or one char.
   let rest = key, prefix = ''
@@ -1457,13 +1604,29 @@ export async function rawKey(id: string, key: string): Promise<boolean> {
     if (prefix.includes('S-') && named === 'Tab') token = noShift + 'BTab'              // Shift+Tab → back-tab
     else if (prefix.includes('S-') && !SHIFTABLE.has(named)) token = noShift + named     // tmux can't carry S- here
     else token = prefix + named
-    await tmux(['send-keys', '-t', id, token]); return true
+    return ['send-keys', '-t', id, token]
   }
   if ([...rest].length === 1) {
     // a single printable char: bare → literal (`-l`, so tmux never reinterprets it as a key name);
     // modified → hand tmux the `C-`/`M-`/`S-` combo to parse (e.g. `C-a`), which `-l` would defeat.
-    if (prefix) { await tmux(['send-keys', '-t', id, prefix + rest]); return true }
-    await tmux(['send-keys', '-t', id, '-l', '--', rest]); return true
+    if (prefix) return ['send-keys', '-t', id, prefix + rest]
+    return ['send-keys', '-t', id, '-l', '--', rest]
+  }
+  return null
+}
+// One call carries a BATCH of tokens (or one) — the client coalesces fast typing into an ordered array. Order
+// is the whole point ([[nav-mode-key-ordering]]): the keys are sent by ONE awaited `send-keys` each, IN ARRAY
+// ORDER, so they reach the pane in exactly the order they were struck. Concurrent per-key POSTs used to race
+// (browser + server + send-keys all parallel) and scramble the sequence; a single serialised batch cannot.
+// An unknown token is skipped without dropping the rest; false only if the tmux session is gone or nothing sent.
+export async function rawKey(id: string, key: string | string[]): Promise<boolean> {
+  const list = (Array.isArray(key) ? key : [key]).filter((k) => typeof k === 'string' && k.length > 0)
+  if (list.length === 0 || !(await alive(id))) return false
+  let sent = false
+  for (const k of list) {
+    const args = rawKeyArgs(id, k)
+    if (!args) continue
+    await tmux(args); sent = true
   }
-  return false
+  return sent
 }