spexcode 0.2.1 → 0.2.3

package/spec-cli/src/search.bench.mjs

@@ -1,5 +1,10 @@
-// throwaway benchmark harness for spec-search — drives the REAL `spex search --json` over the 15 holdout
-// cases and reports recall@1, recall@3, MRR. Not shipped/committed; the cases live in the node's yatsu.md.
+// throwaway benchmark harness for spec-search — drives the REAL `spex search --json` over the holdout
+// cases and reports recall@1, recall@3, MRR. The cases live in the node's yatsu.md.
+//
+// Labels are node LEAF names, matched with the same de-collision rule the loader applies (specs.ts reId):
+// a returned id matches a label if it IS the label or ends with `_<label>` — so a bare leaf keeps matching
+// after collision-qualification renames it (e.g. `spec-scout` → `injected-context_spec-scout`). A label may
+// also be written pre-qualified to pin one collision branch.
 import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
@@ -8,29 +13,33 @@ const BIN = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'spex.mjs
 
 const CASES = [
   ['exit-cleanup', "does /exit remove the session's worktree and tmux, or just orphan them?", ['session-console']],
-  ['owner-at-edit', 'how does an agent learn which spec governs a file it just edited?', ['injected-context/spec-of-file']],
+  ['owner-at-edit', 'how does an agent learn which spec governs a file it just edited?', ['spec-of-file']],
   ['main-block', 'what stops an agent from committing or merging straight into main?', ['main-guard']],
   ['main-escape', 'the escape hatch that lets seeding run on the main branch', ['main-guard']],
   ['inter-agent-msg', 'how do two running agent sessions send messages to each other?', ['agent-reply-channel', 'comms']],
   ['search-hidden-node', 'keyboard shortcut to find a node hidden inside a collapsed subtree', ['keyboard-nav']],
-  ['session-order', 'how is the order of sessions in the session list decided?', ['session-reorder']],
+  ['session-order', 'how is the order of sessions in the session list decided?', ['session-console']],
   ['node-status', 'what makes a node show as pending vs active vs merged vs drift?', ['spec-node-states']],
   ['dashboard-backend', 'how does the dashboard reach the backend API and on which port?', ['api-endpoint']],
   ['loss-measured', "how is a node's loss measured and its scenarios scored?", ['yatsu-core']],
   ['launch-injection', "what context gets injected into a freshly launched agent's prompt?", ['injected-context']],
-  ['read-before-code', 'the one-shot nudge that makes an agent read its spec before touching code', ['injected-context/spec-first']],
+  ['read-before-code', 'the one-shot nudge that makes an agent read its spec before touching code', ['spec-first']],
   ['hot-reload', 'zero-downtime backend reload without dropping connections', ['supervisor']],
   ['many-owners', 'can several specs own the same code file, and what happens if too many do?', ['governed-related']],
   ['active-spec-search', 'an injected sub-agent that searches specs for the agent, the spec analog of Explore', ['spec-scout']],
+  ['declare-done', 'how does a worker declare it is done', ['state']],
 ]
 
+// de-collision-aware label match: exact id, or the id's trailing `_`-suffix is the label.
+const matches = (id, label) => id === label || id.endsWith('_' + label)
+
 let r1 = 0, r3 = 0, mrr = 0
 const rows = []
 for (const [name, query, expect] of CASES) {
   const out = execFileSync('node', [BIN, 'search', query, '--json', '--limit', '10'], { encoding: 'utf8' })
   const results = JSON.parse(out)
   const ids = results.map((x) => x.id)
-  const rank = ids.findIndex((id) => expect.includes(id)) + 1   // 1-based; 0 = not found
+  const rank = ids.findIndex((id) => expect.some((label) => matches(id, label))) + 1   // 1-based; 0 = not found
   const hit1 = rank === 1
   const hit3 = rank >= 1 && rank <= 3
   if (hit1) r1++
@@ -43,5 +52,19 @@ for (const row of rows) {
   const mark = row.rank === 1 ? '✓1' : (typeof row.rank === 'number' && row.rank <= 3 ? '·3' : (row.rank === '—' ? '✗ ' : `·${row.rank}`))
   console.log(`${mark} ${row.name.padEnd(20)} want=${row.expect.padEnd(22)} rank=${String(row.rank).padStart(2)}  top3: ${row.top}`)
 }
+
+// zero-result fail-loud regression: a CJK query over the English corpus returns nothing, and the
+// zero-result message must carry the corpus-is-English translate-and-retry fact (fail-loud, unconditional)
+// plus the browse-all next step (no nearest titles — a CJK query has nothing to be lexically near).
+const cjk = execFileSync('node', [BIN, 'search', '重命名一个会话'], { encoding: 'utf8' })
+const cjkPass = cjk.includes('corpus is English') && cjk.includes('spex tree')
+console.log(`${cjkPass ? '✓ ' : '✗ '} cjk-zero-result       want=corpus-is-English + spex-tree  ${cjkPass ? 'both present' : 'MISSING: ' + cjk.trim()}`)
+
+// zero-result typo routing: an English typo that matches nothing must surface the nearest node titles
+// (per-word edit distance) plus the browse-all next step, so a typo routes forward instead of dead-ending.
+const typo = execFileSync('node', [BIN, 'search', 'kyeboard'], { encoding: 'utf8' })
+const typoPass = typo.includes('nearest titles') && typo.includes('keyboard-nav') && typo.includes('spex tree')
+console.log(`${typoPass ? '✓ ' : '✗ '} typo-zero-result      want=nearest-titles(keyboard-nav) + spex-tree  ${typoPass ? 'both present' : 'MISSING: ' + typo.trim()}`)
+
 console.log('—'.repeat(72))
-console.log(`recall@1 = ${r1}/${n} = ${(r1 / n).toFixed(3)}   recall@3 = ${r3}/${n} = ${(r3 / n).toFixed(3)}   MRR = ${(mrr / n).toFixed(3)}`)
+console.log(`recall@1 = ${r1}/${n} = ${(r1 / n).toFixed(3)}   recall@3 = ${r3}/${n} = ${(r3 / n).toFixed(3)}   MRR = ${(mrr / n).toFixed(3)}   cjk-hint = ${cjkPass ? 'PASS' : 'FAIL'}   typo-route = ${typoPass ? 'PASS' : 'FAIL'}`)

package/spec-cli/src/search.ts

@@ -4,6 +4,45 @@ import { rankDocs, type RankInput } from './ranker.js'
 export type SearchResult = { id: string; title: string; path: string; score: number; snippet: string }
 export type SearchStats = { nodes: number; tokens: number; ms: number }
 
+// zero-result fallback: nearest node titles by per-word edit distance over title+id — the lightweight
+// string distance that routes a typo'd query to a next step. Each query word takes its best normalised
+// Levenshtein similarity against any title/id word (≥0.5, so unrelated words don't accumulate), then the
+// words sum. Same loadSpecsLite read as the ranker; deliberately NOT part of rankDocs scoring (this
+// tolerates typos, the ranker must not).
+export function nearestTitles(query: string, n = 3): { id: string; title: string }[] {
+  const words = (s: string) => s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 1)
+  const lev = (a: string, b: string) => {
+    const dp = Array.from({ length: b.length + 1 }, (_, i) => i)
+    for (let i = 1; i <= a.length; i++) {
+      let prev = dp[0]
+      dp[0] = i
+      for (let j = 1; j <= b.length; j++) {
+        const cur = dp[j]
+        dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+        prev = cur
+      }
+    }
+    return dp[b.length]
+  }
+  const qws = words(query)
+  if (!qws.length) return []   // nothing to be "near" (e.g. a pure-CJK query) — the caller still points at spex tree
+  return loadSpecsLite()
+    .map((s) => {
+      const tws = [...new Set(words(`${s.title} ${s.id}`))]
+      let score = 0
+      for (const q of qws) {
+        let best = 0
+        for (const t of tws) best = Math.max(best, 1 - lev(q, t) / Math.max(q.length, t.length))
+        if (best >= 0.5) score += best
+      }
+      return { id: s.id, title: s.title, score }
+    })
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, n)
+    .map(({ id, title }) => ({ id, title }))
+}
+
 export async function searchSpecs(query: string, opts: { limit?: number; onStats?: (s: SearchStats) => void } = {}): Promise<SearchResult[]> {
   const t0 = performance.now()
   // pre-sort by (shorter id, then id): rankDocs sorts stably, so for equal-scored nodes this IS the tiebreak.

package/spec-cli/src/sessions.ts

@@ -6,9 +6,10 @@ 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, resolveLauncher, rvSock, rendezvousListening, type Harness, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
+import { defaultHarness, defaultLauncher, 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'
+import { stripRefSigil } from './mentions.js'
 
 // @@@ sessions - the WORKTREE is the durable unit; tmux is a disposable runtime handle. The per-session
 // SOURCE OF TRUTH is an untracked record (`session.json`) in a per-user GLOBAL store keyed by the harness
@@ -42,13 +43,13 @@ import { mainBranch, gitCommonDir, readConfig, runtimeRoot, sessionStoreDir, ses
 // 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.
+// SPEXCODE_TMUX overrides the tmux socket for tests; the launch COMMAND comes from the session's pinned
+// launcher ([[launcher-select]]), not an env var.
 
 const pexec = promisify(execFile)
-const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
-// the harness the dashboard/CLI launcher drives. ALL harness-specific launch facts (the agent command, the
-// session-id flag, the hook shim, the session env var) come from this adapter — the launcher never names
-// Claude. Resolved once here ([[harness-adapter]]); a future codex launcher flips defaultHarness, nothing else.
+export const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
+// the legacy/default harness for helpers and old records. New sessions derive their harness from the selected
+// launcher; all harness-specific launch facts still come from the adapter.
 const HARNESS = defaultHarness
 const COLS = 120, ROWS = 32
 // @@@ concurrency cap - the most working agents we let run AT ONCE. Heavy multi-agent load (many claude
@@ -114,7 +115,7 @@ export type Session = {
   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
+  launcher: string | null   // the launcher profile this session launched under ([[launcher-select]]); null only for old records predating launchers
   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`
@@ -224,7 +225,7 @@ export type SessRec = {
   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)
+  launcher: string | null   // the launcher profile this session launches under ([[launcher-select]]); null only for old records predating launchers
   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'])
@@ -250,7 +251,7 @@ function fromRaw(raw: RawRecord): SessRec {
     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
+    launcher: raw.launcher || null,     // records written before launchers → null → old-record fallback
     launchCmd: raw.launch_cmd || null,  // records written before the pin → null → fall back to launcher name / ambient
   }
 }
@@ -371,7 +372,7 @@ async function liveSnapshot(): Promise<LiveSnap> {
 async function paneTitles(): Promise<Map<string, string>> {
   const m = new Map<string, string>()
   let out = ''
-  try { out = await tmux(['list-panes', '-a', '-F', '#{session_name}\t#{pane_title}']) } catch { return m }
+  try { out = await tmux(['list-panes', '-a', '-F', '#{session_name}\t#{pane_title}'], TMUX_PROBE_TIMEOUT_MS) } catch { return m }
   for (const line of out.split('\n')) {
     const tab = line.indexOf('\t'); if (tab < 0) continue
     const id = line.slice(0, tab), title = line.slice(tab + 1)
@@ -437,8 +438,8 @@ export function selfSummary(paneTitle: string): string | null {
 const launchedAt = new Map<string, number>()
 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
+const LAUNCH_FAST_FAIL_S = 12 // launchScript retries the agent command when it exits faster than this: fast
+                              // exit before readiness is retryable, but it is not proof of one specific cause
 
 // @@@ liveness - the orthogonal axis ([[state]]): is the agent process up, for ANY session regardless of
 // lifecycle, from a prebuilt runtime snapshot (no per-call spawn — see liveSnapshot) + the adapter's own channel
@@ -678,11 +679,80 @@ export async function sessionGraph(): Promise<{ nodes: Session[]; edges: Edge[]
   return { nodes, edges }
 }
 
+// @@@ apiBase resolution - WHICH backend a client verb talks to, resolved ONCE per process with the
+// source kept as a discriminant ([[remote-client]]). The core thesis: a FLAG is the only signal that is
+// provably deliberate — an env var cannot tell "I exported this on the command" from "I inherited this
+// from the backend that launched my shell", and that ambiguity is exactly the misroute bug (a shell
+// carrying project A's SPEXCODE_API_URL silently drives every bare `spex` in project B at A's backend).
+// The ladder:
+//   1. explicit `--api <url>` (`--port <n>` = localhost sugar)      — always wins, any verb
+//   2a. WORKER (SPEXCODE_SESSION_ID present): env SPEXCODE_API_URL  — the backend-injected lifeline; a
+//       worker's state writes must NEVER gamble on cwd discovery, so the env is not demotable by (2b)
+//   2b. HUMAN (no session id): the cwd project's RECORDED live backend (`spex serve` writes it, we
+//       /health-probe before trusting — a dead record is ignored, never followed)
+//   3. the other side as fallback (human with no live record → env; worker with no env → record)
+//   4. default http://127.0.0.1:$PORT||8787
+export type ApiBaseSource = 'flag' | 'worker-env' | 'record' | 'env-fallback' | 'default'
+export type ApiBaseInfo = { url: string; source: ApiBaseSource }
+const usageError = (msg: string): Error => { const e = new Error(msg); e.name = 'UsageError'; return e }
+// the explicit routing flag, read from THIS process's argv (never the environment — that's the point).
+// `--port` doubles as a BIND port for serve/dashboard, so the sugar is skipped for those verbs.
+function explicitApiFlag(): string | null {
+  const argv = process.argv
+  const ai = argv.indexOf('--api')
+  if (ai >= 0) {
+    const v = argv[ai + 1]
+    if (!v || v.startsWith('--')) throw usageError('--api expects a URL (e.g. --api http://127.0.0.1:8901)')
+    const withScheme = v.includes('://') ? v : `http://${v}`
+    try { new URL(withScheme) } catch { throw usageError(`--api: not a URL: ${v}`) }
+    return withScheme.replace(/\/+$/, '')
+  }
+  if (argv[2] === 'serve' || argv[2] === 'dashboard') return null   // their --port is a bind port, not routing
+  const pi = argv.indexOf('--port')
+  if (pi >= 0) {
+    const v = argv[pi + 1]
+    if (!v || !Number.isInteger(Number(v))) throw usageError('--port expects an integer (localhost sugar for --api http://127.0.0.1:<n>)')
+    return `http://127.0.0.1:${v}`
+  }
+  return null
+}
+// the cwd project's recorded backend ({url,pid}, written by `spex serve` at bind time into the per-project
+// runtime tier), trusted only after a live /health probe — a stale record must never swallow a command.
+async function liveRecordUrl(): Promise<string | null> {
+  let file: string
+  try { file = join(runtimeRoot(), 'backend.json') } catch { return null }   // cwd not in a git repo → nothing to discover
+  let url = ''
+  try { const rec = JSON.parse(readFileSync(file, 'utf8')); if (typeof rec?.url === 'string') url = rec.url.trim() } catch { return null }
+  if (!url) return null
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(), 600)
+  try { return (await fetch(`${url}/health`, { signal: ctrl.signal })).ok ? url : null }
+  catch { return null }
+  finally { clearTimeout(t) }
+}
+async function resolveApiBase(): Promise<ApiBaseInfo> {
+  const flag = explicitApiFlag()
+  if (flag) return { url: flag, source: 'flag' }
+  const env = process.env.SPEXCODE_API_URL?.trim() || null
+  if (process.env.SPEXCODE_SESSION_ID?.trim()) {
+    if (env) return { url: env, source: 'worker-env' }
+    const rec = await liveRecordUrl()
+    if (rec) return { url: rec, source: 'record' }
+  } else {
+    const rec = await liveRecordUrl()
+    if (rec) return { url: rec, source: 'record' }
+    if (env) return { url: env, source: 'env-fallback' }
+  }
+  return { url: `http://127.0.0.1:${process.env.PORT || 8787}`, source: 'default' }
+}
+let apiBaseMemo: Promise<ApiBaseInfo> | null = null
+export const apiBaseInfo = (): Promise<ApiBaseInfo> => (apiBaseMemo ??= resolveApiBase())
+export const apiBase = async (): Promise<string> => (await apiBaseInfo()).url
+
 // @@@ watch registration (CLIENT side) - a `spex watch` process is separate from the server, so it
 // REPORTS itself to the backend's registration store over HTTP: register+heartbeat while it runs,
 // deregister on exit (see cli.ts `watch`). All best-effort — if the backend is down the watch still
 // streams its events; the graph edge just won't appear until a heartbeat lands. Never throws.
-export const apiBase = () => process.env.SPEXCODE_API_URL || `http://127.0.0.1:${process.env.PORT || 8787}`
 // the agent's OWN session id from the HARNESS env var — the public name used across cli.ts/sessions.ts.
 // Single adapter-routed impl lives in layout.ts (`envSessionId`, iterating each adapter's sessionEnvVar);
 // re-exported here so callers keep one name. Used by `spex watch` + the agent-typed `spex session …`
@@ -708,7 +778,7 @@ export function withSenderHint(text: string, sender: MsgSender | null): string {
 }
 async function postJSON(path: string, body: unknown): Promise<void> {
   try {
-    await fetch(`${apiBase()}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+    await fetch(`${await apiBase()}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
   } catch { /* best-effort: backend may be down; the next heartbeat / TTL reconciles */ }
 }
 export const reportWatch = (token: string, watcher: string, selectors: string[], ttlMs: number): Promise<void> =>
@@ -769,28 +839,28 @@ 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 {
+export 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.
   // `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.
+  // ambient default so resume reuses the same auth. Undefined is only for old records before launch_cmd existed.
   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).
+  // Bounded relaunch on a FAST exit: the agent launcher can exit within seconds before the rendezvous socket
+  // ever appears. That is enough evidence to retry, but not enough evidence to name the cause. 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 startup unready failures — 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`,
+    `  printf '[spex launch] attempt %s exited in %ss (rc=%s) - fast launcher exit before readiness; retrying\\n' "$__spex_try" "$(( SECONDS - __spex_t0 ))" "$__spex_rc" >&2`,
     `  sleep 2`,
     `done`,
     `exit $__spex_rc`,
@@ -897,41 +967,50 @@ 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> {
+// @@@ assertProjectMatch - a WRITE is PROJECT-BOUND, but routing is by URL. A mutating verb's intent is
+// "act on the project my cwd is in", yet the resolved base is a pure URL carrying no project identity —
+// the backend it answers acts on ITS OWN mainRoot, so a stale inherited SPEXCODE_API_URL (pointing at
+// another repo's backend) silently lands the write in the WRONG repo. Read/control-READS deliberately
+// point anywhere (viewer-points-anywhere, see remote-client); every MUTATING verb (new/merge/send/close/
+// rename/rawkey/reopen/exit) is bound to the caller's project. So before writing, 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. An explicit `--api`/`--port` flag SKIPS the guard: the flag is the one provably-deliberate
+// cross-project signal (that's the whole flag-beats-env thesis). 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 drive stays untouched.
+export async function assertProjectMatch(verb: string): Promise<void> {
+  const { url, source } = await apiBaseInfo()
+  if (source === 'flag') return                                   // explicitly routed — the caller named the target
   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`)
+    const r = await fetch(`${url}/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)
+  } catch { return }                                              // backend unreachable → the write itself 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)`)
+  if (backendMain !== localMain) {
+    const e = new Error(
+      `${verb}: refusing WRITE — cwd is in ${localMain} but the backend at ${url} serves ${backendMain}.\n` +
+      `Name the target explicitly (--api <url> / --port <n>) to write cross-project on purpose,\n` +
+      `or run this project's own backend:  cd ${localMain} && spex serve.  (Reads stay unguarded.)`)
+    e.name = 'GuardError'
+    throw e
+  }
 }
 
 // @@@ 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)
-// has a stripped env, so an in-process launch would spawn workers under plain `claude` and 401 at boot. So
-// 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, launcher?: string): Promise<Session> {
-  await assertProjectMatch()
+// BACKEND's process, not the caller's, because the backend is the single owner of the concurrency cap and the
+// launch QUEUE (drainQueue). An in-process launch by an agent that runs `spex new` (e.g. a supervisor) would
+// bypass that queue and the maxActive gate. (The launch COMMAND is not a process-env concern anymore — it
+// comes from the session's pinned launcher, resolved from project config [[launcher-select]], identical in
+// either process.) So the CLI POSTs to the running backend whenever one answers. 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, launcher?: string): Promise<Session> {
+  await assertProjectMatch('spex new')
   // @@@ 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;
@@ -939,16 +1018,23 @@ export async function createSession(node: string | null, prompt: string, harness
   const parent = ownSessionId()
   let res: Response
   try {
-    res = await fetch(`${apiBase()}/api/sessions`, {
+    res = await fetch(`${await apiBase()}/api/sessions`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ node, prompt, harness, parent, launcher }),
+      body: JSON.stringify({ node, prompt, parent, launcher }),
     })
   } catch {
     console.error('spex: no backend reachable — launching in-process (caller env owns auth, no concurrency cap)')
-    return newSession(node, prompt, harness, parent, launcher)
+    return newSession(node, prompt, parent, launcher)
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => '')
+    let msg = text
+    try { msg = JSON.parse(text).error || text } catch {}
+    const err = new Error(`backend rejected session (${res.status}): ${msg}`)
+    err.name = 'BackendError'
+    throw err
   }
-  if (!res.ok) throw new Error(`backend rejected session (${res.status}): ${await res.text().catch(() => '')}`)
   return await res.json() as Session
 }
 
@@ -959,16 +1045,14 @@ export async function createSession(node: string | null, prompt: string, harness
 // 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> {
+export async function newSession(node: string | null, prompt: string, parent: string | null = null, launcher?: string): Promise<Session> {
   const id = randomUUID()
-  // 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
+  // a launcher ([[launcher-select]]) fixes BOTH the launch command (persisted below) AND the harness — so
+  // picking one is the ONLY launch choice. Explicit --launcher wins, else the configured defaultLauncher.
+  // A missing/unknown default throws fail-loud; there is no built-in-claude or harness fallback.
+  const lname = launcher ?? defaultLauncher(mainRoot())
+  const chosen = resolveLauncher(lname)
+  const h = harnessById(chosen.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)
@@ -988,11 +1072,11 @@ export async function newSession(node: string | null, prompt: string, harness: s
     // 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,
+    harness: h.id, harnessSessionId: null, launcher: chosen.name,
     // 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),
+    launchCmd: h.baseCmd(chosen.cmd),
   }
   writeRecord(rec)
   writePromptFile(id, prompt)   // capture the ORIGINATING prompt (the human/manager's ask) as store metadata (best-effort)
@@ -1104,7 +1188,7 @@ export function markState(status: Lifecycle, opts: { proposal?: Proposal; note?:
   })
   return true
 }
-export const markDone = (proposal: Proposal = 'nothing', sessionId?: string) => markState('awaiting', { proposal, sessionId })
+export const markDone = (proposal: Proposal = 'nothing', sessionId?: string, note?: string) => markState('awaiting', { proposal, note, sessionId })
 export const markError = (sessionId?: string) => markState('error', { sessionId })
 export function markHarnessSessionId(sessionId: string | undefined, harnessSessionId: string | undefined): boolean {
   const id = sessionId || ownSessionId()
@@ -1184,6 +1268,7 @@ export type ReviewGates = {
 }
 export type ReviewPayload = {
   id: string; node: string | null; branch: string | null
+  label: string              // the session's identity, derived ONCE via deriveLabel — the review surface renders THIS, never its own node||branch||id chain
   ahead: number              // commits the node branch is ahead of main
   dirtyNonRuntime: number    // uncommitted files excluding SpexCode's own runtime files
   diff: ReviewDiffFile[]     // the worker's real changes, anchored at the merge-base
@@ -1250,6 +1335,7 @@ export async function reviewPayload(id: string): Promise<ReviewPayload | null> {
   const dirtyNonRuntime = statusOut.split('\n').filter(Boolean).map(porcelainPath).length
   return {
     id, node: wt.rec.node, branch: wt.branch,
+    label: deriveLabel({ id, name: wt.rec.name, node: wt.rec.node, title: wt.rec.title, branch: wt.branch }),
     ahead: Number(aheadOut.trim()) || 0,
     dirtyNonRuntime, diff,
     gates: { conflictsWithMain, lint },
@@ -1382,8 +1468,9 @@ export function matchesSelector(s: Session, q: string): boolean {
   // 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)
+  // silence forever. Each part sheds an optional reference sigil (stripRefSigil): `@<sel>` / `[[<sel>]]` name
+  // the same session as the bare token, so the dashboard's mention grammar is tolerated in every CLI selector.
+  return q.split(',').map((p) => stripRefSigil(p.trim())).filter(Boolean)
     .some((p) => s.id === p || s.id.startsWith(p) || s.node === p || s.branch === p)
 }
 
@@ -1404,7 +1491,8 @@ export function selectSessions(all: Session[], selectors: string[], statuses?: s
 // otherwise a lone match is `ok`, several is `ambiguous` (a prefix/node hitting many), none is `none`.
 export type Resolved = { ok: Session } | { ambiguous: Session[] } | { none: true }
 export function resolveSession(selector: string, sessions: Session[]): Resolved {
-  const exact = sessions.find((s) => s.id === selector)
+  // the exact-id check sheds the optional sigil too, so `@<full-id>` keeps the exact-wins-over-prefix rule
+  const exact = sessions.find((s) => s.id === stripRefSigil(selector))
   if (exact) return { ok: exact }
   const hits = sessions.filter((s) => matchesSelector(s, selector))
   if (hits.length === 1) return { ok: hits[0] }
@@ -1412,6 +1500,9 @@ export function resolveSession(selector: string, sessions: Session[]): Resolved
 }
 
 const trunc = (s: string, n: number) => (s.length > n ? s.slice(0, n - 1) + '\u2026' : s)
+// the board table's NOTE display cap \u2014 exported so the declaration echo (cli.ts) can tell an author
+// exactly where their note gets cut, instead of the cap living as an anonymous magic number here.
+export const NOTE_BOARD_LIMIT = 50
 // short display label per status (only close-pending differs from the status name) \u2014 used by the legend.
 const SHORT: Partial<Record<DisplayStatus, string>> = { 'close-pending': 'close' }
 
@@ -1438,7 +1529,7 @@ export function formatTable(sessions: Session[], color = true): string {
     const st = s.status.padEnd(13)
     const merges = (s.merges ? `\u00d7${s.merges}` : '').padEnd(4)
     const prompt = c('90', (s.promptPreview ? trunc(s.promptPreview, 40) : '').padEnd(42))   // what it was asked to do
-    const note = s.note ? c('90', trunc(s.note, 50)) : ''
+    const note = s.note ? c('90', trunc(s.note, NOTE_BOARD_LIMIT)) : ''
     return `  ${c(code, g)} ${c(code, st)} ${name} ${c('90', s.id.slice(0, 8))} ${merges}${prompt}${note}`
   })
   return [c('1', `SpexCode sessions (${sessions.length})`), header, ...rows, statusLegend(color)].join('\n')
@@ -1571,7 +1662,7 @@ export async function sendKeys(id: string, text: string, from?: string): Promise
 // socket. Two channels, two jobs: the socket INJECTS a whole prompt (text + submit), which can drive the
 // agent's normal prompt but CANNOT navigate an interactive TUI select menu (e.g. `/model`'s list — ↑/↓ to
 // move, ←/→ to adjust, Enter to set, `s` for this-session, Esc to cancel). When the agent is in that
-// keystroke-navigation state its input box is replaced by the menu, so the dashboard's nav mode forwards
+// keystroke-navigation state its input box is replaced by the menu, so the dashboard's type mode forwards
 // each key here in real time. send-keys is exactly right for single raw keys: named keys map to tmux's own
 // key names; a single printable char is sent literally (`-l`) so tmux doesn't reinterpret it. The dashboard
 // also drives the agent with MODIFIER COMBOS — a terminal's three modifiers carried as a `C-`/`M-`/`S-`

package/spec-cli/src/specs.ts

@@ -149,19 +149,31 @@ async function rawsAsync(): Promise<Raw[]> {
   return acc
 }
 
-// spec node(s) that GOVERN a file by the claim rule (exact path, dir-prefix, or *-glob); reads only
-// frontmatter `code:` (cheap, no git) so a per-edit hook can call it. See [[governed-related]].
-export function specOwners(file: string): { id: string; desc: string }[] {
+// the claim rule shared by both relations (exact path, dir-prefix, or *-glob). See [[governed-related]].
+function claimMatcher(file: string): (cf: string) => boolean {
   const rel = file.startsWith('/') ? relative(ROOT, file) : file
-  const claims = (cf: string): boolean => {
+  return (cf: string): boolean => {
     if (cf === rel) return true
     if (rel.startsWith(cf.replace(/\/+$/, '') + '/')) return true
     if (cf.includes('*')) return new RegExp('^' + cf.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$').test(rel)
     return false
   }
+}
+
+// spec node(s) that GOVERN a file (frontmatter `code:` — source of truth, drives drift/yatsu); reads only
+// frontmatter (cheap, no git) so a per-edit hook can call it.
+export function specOwners(file: string): { id: string; desc: string }[] {
+  const claims = claimMatcher(file)
   return raws().filter((r) => list(r.fm.code).some(claims)).map((r) => ({ id: r.id, desc: str(r.fm.desc) }))
 }
 
+// spec node(s) that REFERENCE a file (frontmatter `related:` — carries coverage, never drift/yatsu):
+// [[governed-related]]'s other half, same claim rule, same cheap frontmatter-only read.
+export function specRelated(file: string): { id: string; desc: string }[] {
+  const claims = claimMatcher(file)
+  return raws().filter((r) => list(r.fm.related).some(claims)).map((r) => ({ id: r.id, desc: str(r.fm.desc) }))
+}
+
 // memo fileDiffAt by (version sha + spec.md path) — a commit's patch is immutable. Keyed by path too: one
 // commit can patch several nodes' spec.md. `{hash:'',patch:''}` for an unversioned node (no git call).
 const diffCache = new Map<string, { hash: string; patch: string }>()