spexcode 0.2.0 → 0.2.2

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
@@ -45,10 +46,9 @@ import { mainBranch, gitCommonDir, readConfig, runtimeRoot, sessionStoreDir, ses
 // SPEXCODE_TMUX / SPEXCODE_CLAUDE_CMD override both for tests.
 
 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 +114,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 +224,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 +250,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 +371,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 +437,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 +678,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 +777,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 +838,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,30 +966,38 @@ 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
@@ -930,8 +1007,8 @@ async function assertProjectMatch(): Promise<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, launcher?: string): Promise<Session> {
-  await assertProjectMatch()
+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 +1016,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 +1043,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 +1070,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 +1186,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()
@@ -1382,8 +1464,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 +1487,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 +1496,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 +1525,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 +1658,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 }>()

package/spec-cli/src/supervise.ts

@@ -3,13 +3,14 @@
 import net from 'node:net'
 import http from 'node:http'
 import { spawn, type ChildProcess } from 'node:child_process'
-import { statSync, readdirSync, type Dirent } from 'node:fs'
+import { statSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync, type Dirent } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { installProcessGuards } from './resilience.js'
 import { listenOrExit } from './listen.js'
 import { resolvePublicConfig, startGateway, ensureDashboardBuilt, resolveDistDir } from './gateway.js'
 import { tsxBin } from './tsx-bin.js'
+import { runtimeRoot } from './layout.js'
 
 // the supervisor OWNS the public port, so it must outlive any transient throw: an uncaught error here is
 // logged and survived, never an exit that closes the port (and the tmux session) and takes the frontend down.
@@ -74,8 +75,11 @@ async function boot(): Promise<Backend | null> {
   const port = await freePort()
   // PORT pins the child's PRIVATE bind port; SPEXCODE_API_URL pins everything the child SPAWNS (launched
   // sessions + their hooks) at the PUBLIC port, so a launched agent's own `spex` reaches the stable proxy
-  // and never inherits this ephemeral, soon-retired port (apiBase() prefers SPEXCODE_API_URL over PORT).
-  const child = spawn(tsx, [entry], { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: process.env.SPEXCODE_API_URL || childApiBase } })
+  // and never inherits this ephemeral, soon-retired port. ALWAYS childApiBase, never the ambient
+  // process.env.SPEXCODE_API_URL: the env this serve itself inherited may carry ANOTHER project's backend
+  // (the exact misroute [[remote-client]]'s ladder exists to kill), and a worker's env is its routing
+  // LIFELINE — it must be a deterministic backend-injected fact, not an inheritance gamble.
+  const child = spawn(tsx, [entry], { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: childApiBase } })
   // if the ACTIVE backend dies unexpectedly (crash, OOM), restart it so the public port keeps serving.
   // Planned retirement sets current to the NEW child first, so the old child's exit fails this identity
   // check and is ignored. boot()'s ~5s health budget rate-limits any crash loop.
@@ -130,7 +134,27 @@ const proxy = net.createServer((client) => {
   client.pipe(up); up.pipe(client)
 })
 
-const shutdown = () => { try { current?.child.kill('SIGTERM') } catch { /* */ } process.exit(0) }
+// @@@ endpoint record - this project's live backend endpoint, written into the per-project runtime tier
+// (~/.spexcode/projects/<enc>/backend.json) only AFTER the public bind succeeds. It's what lets a bare
+// `spex` run from this project's tree find ITS OWN backend instead of an env URL inherited from another
+// project's ([[remote-client]]'s resolution ladder). Readers /health-probe before trusting, so a crash
+// leaves at worst a dead record that is ignored — never followed. The recorded URL is the LOOPBACK face
+// local agents reach (equals the public port when public mode is off), never the password-gated gateway.
+const backendRecordPath = () => join(runtimeRoot(), 'backend.json')
+function recordEndpoint(url: string): void {
+  try {
+    mkdirSync(runtimeRoot(), { recursive: true })
+    writeFileSync(backendRecordPath(), JSON.stringify({ url, pid: process.pid, startedAt: new Date().toISOString() }, null, 2) + '\n')
+  } catch (e) {
+    console.error(`[supervisor] could not record the backend endpoint (${(e as Error).message}) — cwd-based \`spex\` discovery won't find this backend`)
+  }
+}
+// best-effort removal on a clean stop, only if the record is OURS (a newer serve may have overwritten it).
+function dropEndpoint(): void {
+  try { if (JSON.parse(readFileSync(backendRecordPath(), 'utf8'))?.pid === process.pid) rmSync(backendRecordPath()) } catch { /* not ours / already gone */ }
+}
+
+const shutdown = () => { dropEndpoint(); try { current?.child.kill('SIGTERM') } catch { /* */ } process.exit(0) }
 process.on('SIGINT', shutdown)
 process.on('SIGTERM', shutdown)
 
@@ -146,10 +170,10 @@ if (publicCfg) {
   // public mode: the raw proxy stays on loopback; the password-gated gateway owns the public port.
   const distDir = resolveDistDir() // bundled <pkg>/dashboard-dist when installed, else monorepo spec-dashboard/dist
   ensureDashboardBuilt(repoRoot, distDir)
-  listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: () => console.log(`spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})`) })
+  listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})`) } })
   startGateway({ publicPort, upstreamPort: proxyPort, password: publicCfg.password, tls: publicCfg.tls, distDir, onBindFail: reapChild })
 } else {
-  listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => console.log(`spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})`) })
+  listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})`) } })
 }
 
 // watch every imported source tree; debounce a burst of writes (a merge touching several files across