spexcode 0.4.1 → 0.5.0

package/spec-cli/src/shim-runtime.ts

@@ -0,0 +1,169 @@
+// @@@ shim-runtime - the ONE shared runtime every GENERATIVE per-session shim embeds ([[shim-runtime]]).
+// pi's extension and opencode's plugin (and any future in-process harness shim) are thin hosts: they declare
+// an event-name mapping and bind their host's API; the machinery they share — claude-shaped payload synthesis
+// into dispatch.sh, the block-verdict parse, the rendezvous socket server, tool-input normalization — is THIS
+// module's generated chunk, embedded verbatim by each generator. One source of truth: the deliver-confirm and
+// stop-gate-rejection bugs were each fixed in only one of the two hand-written copies this replaces; a fix
+// here reaches every generative shim at the next materialize.
+//
+// The chunk is PLAIN JavaScript (no type annotations, no non-builtin imports): pi loads its shim as a native
+// .ts extension, opencode as a project plugin, and tests import the generated file directly under node — the
+// lowest common denominator is untyped ESM against node builtins. Identifiers are __spex-prefixed so a host
+// section can never collide with them.
+
+// the embedded runtime chunk. `harnessId` is baked as dispatch.sh's argv[1] (the deterministic shell-side
+// harness detector); `dispatch`/`spex` are the absolute paths materialize bakes into every shim — the
+// 'dispatch.sh' substring doubles as the identity stamp cleanHarness gates removal on.
+export function shimRuntimeSource(harnessId: string, dispatch: string, spex: string): string {
+  return `// ---- spexcode shared shim runtime (embedded from spec-cli/src/shim-runtime.ts — edit THERE) ----
+import { spawn as __spexSpawn } from "node:child_process"
+import { createServer as __spexCreateServer } from "node:net"
+import { unlinkSync as __spexUnlink } from "node:fs"
+
+const DISPATCH = ${JSON.stringify(dispatch)}
+const SPEX = ${JSON.stringify(spex)}
+const HARNESS = ${JSON.stringify(harnessId)}
+
+// cfg: { sessionId: () => string, cwd?: () => string } — the two identity accessors a host binds; everything
+// else is shared machinery.
+const spexShimRuntime = (cfg) => {
+  const cwd = cfg.cwd || (() => process.cwd())
+
+  // feed ONE claude-shaped payload ({ session_id, cwd, hook_event_name, ...extra }) to dispatch.sh, the
+  // harness id baked as argv[1]. Payload key order matters for tool events: a host must put agent_id (when
+  // present) BEFORE tool_input because harness.sh's hp_is_subagent checks keys only before tool_input. Resolves with the exit
+  // code + both streams for the verdict helpers below; never rejects.
+  const dispatchEvent = (event, extra) => new Promise((resolve) => {
+    let out = "", err = ""
+    let child
+    try {
+      child = __spexSpawn("bash", [DISPATCH, HARNESS, event], {
+        cwd: cwd(), env: { ...process.env, SPEX }, stdio: ["pipe", "pipe", "pipe"], timeout: 600_000,
+      })
+    } catch (e) { resolve({ code: 1, out, err: String(e) }); return }
+    child.stdout.on("data", (d) => { out += d })
+    child.stderr.on("data", (d) => { err += d })
+    child.on("error", (e) => resolve({ code: 1, out, err: err || String(e) }))
+    child.on("close", (code) => resolve({ code: code == null ? 1 : code, out, err }))
+    // a handler may exit without draining stdin (fast-fail scripts, a missing dispatch file) — the write then
+    // EPIPEs; that must never throw into the host's event handler, the child's exit code still answers.
+    child.stdin.on("error", () => { /* child exited before consuming stdin — fine */ })
+    try { child.stdin.end(JSON.stringify({ session_id: cfg.sessionId(), cwd: cwd(), hook_event_name: event, ...(extra || {}) })) } catch { /* same */ }
+  })
+
+  // the ONE block contract: dispatch.sh signals a block by EXIT 2 (a handler's stdout
+  // {"decision":"block","reason":…} JSON is mapped to exit 2 by dispatch itself, stderr staying empty; a
+  // bare exit-2 handler writes its reason on stderr instead). codex's stderr bridge is codex's own native
+  // protocol and lives in dispatch.sh — not here.
+  const blocked = (r) => r.code === 2
+
+  // the human-readable rejection, extracted in contract order — never the raw wire JSON (an escaped-\\n payload
+  // turned the stop-gate's teaching menu into one unreadable line on one harness before this was shared):
+  //   1. a decision:block JSON line on stdout, strictly parsed (the designed channel);
+  //   2. several handlers' stdout objects can arrive GLUED without separators — regex the reason string out
+  //      (JSON.parse of the string literal unescapes it);
+  //   3. stderr — the channel a bare exit-2 handler writes;
+  //   4. the caller's fallback.
+  const blockReason = (r, fallback) => {
+    for (const line of (r.out || "").split("\\n")) {
+      const s = line.trim()
+      if (!s.startsWith("{")) continue
+      try {
+        const o = JSON.parse(s)
+        if (o && o.decision === "block" && typeof o.reason === "string" && o.reason) return o.reason
+      } catch { /* not a lone JSON line — the glued fallback below */ }
+    }
+    if (/"decision"\\s*:\\s*"block"/.test(r.out || "")) {
+      const m = (r.out || "").match(/"reason"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)"/)
+      if (m) { try { return JSON.parse('"' + m[1] + '"') } catch { /* malformed escape — fall through */ } }
+    }
+    return (r.err || "").trim() || fallback
+  }
+
+  // the Stop dispatch with the gate's LOOP-TERMINATION bit. Claude's native Stop payload carries
+  // stop_hook_active=true when the stop happens inside a continuation a Stop-hook block itself forced, and
+  // the stop-gate's escape paths key on exactly that bit to guarantee the loop ends (auto-declare /
+  // downgrade-to-ask instead of a fresh block). A generative host has no native bit, so the runtime supplies
+  // it: false on a natural stop, true on the settle that follows a blocked one, reset by the first allowed
+  // stop. Without it every settle reads as a FIRST stop and a gate that can never pass (e.g. the commit gate
+  // on a 0-commit worktree) blocks forever. On block, the host's inject re-enters the gate's reason as the
+  // continuation; an inject that cannot land is caught LOUD on stderr — never thrown into the host, never
+  // silent. stopPending exposes whether the
+  // last Stop verdict was a block still awaiting its continuation's allow — the state a host's backstop
+  // binding (pi's agent_settled) keys on to consume exactly one pending blocked stop, never duplicating a
+  // naturally-allowed dispatch.
+  let stopBlocked = false
+  const stopPending = () => stopBlocked
+  const dispatchStop = async (inject, fallback) => {
+    const r = await dispatchEvent("Stop", { stop_hook_active: stopBlocked })
+    if (blocked(r)) {
+      stopBlocked = true
+      try { await inject(blockReason(r, fallback)) } catch (e) {
+        console.error("spexcode: a blocked stop's continuation could not be re-injected: " + String(e))
+      }
+    } else stopBlocked = false
+    return r
+  }
+
+  // normalize a host tool-input onto the claude accessor shape: mirror the host's file-path spelling onto
+  // file_path (the key harness.sh and every claude-family handler read), dropping the host spelling.
+  const toolInput = (input, fileAlias) => {
+    const args = { ...(input && typeof input === "object" ? input : {}) }
+    if (fileAlias && args[fileAlias] !== undefined && args.file_path === undefined) {
+      args.file_path = args[fileAlias]
+      delete args[fileAlias]
+    }
+    return args
+  }
+
+  // the per-session rendezvous control socket: bind a line-JSON server on CLAUDE_BG_RENDEZVOUS_SOCK (handed
+  // by every ownsRendezvous launch; a self-launched bare harness has no env → no server) speaking the
+  // reclaude mini-protocol, so claude's deliverViaRendezvous and socket-listener liveness work UNCHANGED.
+  // MULTI-connection (unlike reclaude's daemon): a session-liveness probe connect can never kick a concurrent
+  // delivery, so the sender's atomic reply+repaint chunk always resolves on its own connection. The data
+  // handler is deliberately SYNCHRONOUS — a chunk's lines parse in one pass and repaint-done (the in-order
+  // parse barrier) flushes before any other event can run: confirmation means PARSED, not processed; the
+  // injection (a whole model turn on some hosts) runs BEHIND the confirm. A known-unable inject answers
+  // reply-rejected BEFORE repaint-done so the sender fails loud instead of confirming a prompt that can
+  // never land; a LATE inject failure best-effort reply-rejects (the sender has usually resolved and gone).
+  const serveRendezvous = (inject, opts) => {
+    const sock = (process.env.CLAUDE_BG_RENDEZVOUS_SOCK || "").trim()
+    if (!sock) return null
+    try { __spexUnlink(sock) } catch { /* no stale socket — fine */ }
+    const reject = (c) => { try { c.write(JSON.stringify({ type: "reply-rejected" }) + "\\n") } catch { /* peer gone */ } }
+    const server = __spexCreateServer((c) => {
+      let buf = ""
+      c.on("error", () => { /* probes disconnect abruptly — expected */ })
+      c.on("data", (d) => {
+        buf += d.toString("utf8")
+        let nl
+        while ((nl = buf.indexOf("\\n")) >= 0) {
+          const line = buf.slice(0, nl)
+          buf = buf.slice(nl + 1)
+          let msg
+          try { msg = JSON.parse(line) } catch { continue }
+          if (msg && msg.type === "reply" && typeof msg.text === "string") {
+            if (opts && opts.canInject && !opts.canInject()) { reject(c); continue }
+            try {
+              const p = inject(msg.text)
+              if (p && typeof p.catch === "function") p.catch(() => reject(c))
+            } catch { reject(c) }
+          } else if (msg && msg.type === "repaint") {
+            try { c.write(JSON.stringify({ type: "repaint-done" }) + "\\n") } catch { /* peer gone */ }
+          }
+        }
+      })
+    })
+    server.on("error", (e) => console.error("spexcode: rendezvous socket failed to bind at " + sock + ": " + String(e)))
+    server.listen(sock)
+    server.unref()   // never hold the host process open for our socket; the harness's own loop keeps it alive
+    return { close: () => {
+      try { server.close() } catch { /* already closed */ }
+      try { __spexUnlink(sock) } catch { /* already gone */ }
+    } }
+  }
+
+  return { dispatchEvent, dispatchStop, stopPending, blocked, blockReason, toolInput, serveRendezvous }
+}
+// ---- end spexcode shared shim runtime ----`
+}

package/spec-cli/src/slash-commands.ts

@@ -227,6 +227,48 @@ const CODEX_BUILT_IN: ReadonlyArray<readonly [string, string]> = [
 // the user's saved prompts in `$CODEX_HOME/prompts/*.md` (each filename becomes `/<name>`, codex's custom-
 // prompt convention). Like the Claude builder it NEVER guesses — plugin commands that aren't readable as
 // simple files contribute nothing. Presentation order: built-ins first (codex's enum order), then prompts.
+// @@@ PI_BUILT_IN seed - pi's `/` menu, extracted from the INSTALLED pi's own command table
+// (dist/core/slash-commands.js, @earendil-works/pi-coding-agent 0.80.10) — discovered, not guessed, same
+// discipline as the claude/codex captures; to refresh for a new pi, re-read that module.
+const PI_BUILT_IN: ReadonlyArray<readonly [string, string]> = [
+  ['settings', 'Open settings menu'],
+  ['model', 'Select model (opens selector UI)'],
+  ['scoped-models', 'Enable/disable models for Ctrl+P cycling'],
+  ['export', 'Export session (HTML default, or specify path: .html/.jsonl)'],
+  ['import', 'Import and resume a session from a JSONL file'],
+  ['share', 'Share session as a secret GitHub gist'],
+  ['copy', 'Copy last agent message to clipboard'],
+  ['name', 'Set session display name'],
+  ['session', 'Show session info and stats'],
+  ['changelog', 'Show changelog entries'],
+  ['hotkeys', 'Show all keyboard shortcuts'],
+  ['fork', 'Create a new fork from a previous user message'],
+  ['clone', 'Duplicate the current session at the current position'],
+  ['tree', 'Navigate session tree (switch branches)'],
+  ['trust', 'Save project trust decision for future sessions'],
+  ['login', 'Configure provider authentication'],
+  ['logout', 'Remove provider authentication'],
+  ['new', 'Start a new session'],
+  ['compact', 'Manually compact the session context'],
+  ['resume', 'Resume a different session'],
+  ['reload', 'Reload keybindings, extensions, skills, prompts, themes, and context files'],
+]
+
+// @@@ piSlashCommands - pi's `/` menu, computed the way pi computes its own: built-ins (above) + prompt
+// templates (`~/.pi/agent/prompts/*.md` global, `.pi/prompts/*.md` project — each filename becomes `/<name>`)
+// + skills (`/skill:<name>` is pi's spelling, but the bare name is what our dropdown wants). Best-effort like
+// the codex builder: what isn't readable as simple files contributes nothing.
+export function piSlashCommands(): SlashCommand[] {
+  const repo = repoRoot()
+  const all: SlashCommand[] = []
+  for (const [name, description] of PI_BUILT_IN) all.push({ name, description, source: 'built-in' })
+  scanCommands(join(homedir(), '.pi', 'agent', 'prompts'), 'user', all)
+  scanCommands(join(repo, '.pi', 'prompts'), 'project', all)
+  scanSkills(join(homedir(), '.pi', 'agent', 'skills'), all)
+  scanSkills(join(repo, '.pi', 'skills'), all)
+  return dedupeSort(all)
+}
+
 export function codexSlashCommands(): SlashCommand[] {
   const all: SlashCommand[] = []
   for (const [name, description] of CODEX_BUILT_IN) all.push({ name, description, source: 'built-in' })
@@ -240,3 +282,37 @@ export function codexSlashCommands(): SlashCommand[] {
   const prompts = [...seen.values()].filter((c) => c.source !== 'built-in').sort((a, b) => a.name.localeCompare(b.name))
   return [...builtins, ...prompts]
 }
+
+// opencode built-ins — a conservative pinned set (opencode 1.18.x TUI commands; its TUI registry is compiled,
+// not file-discoverable, so like the other two capture blocks this is version-specific and re-pinned by hand).
+const OPENCODE_BUILT_IN: ReadonlyArray<readonly [string, string]> = [
+  ['compact', 'Summarize and compact the current session'],
+  ['editor', 'Open the external editor for the message'],
+  ['exit', 'Exit opencode'],
+  ['export', 'Export the session'],
+  ['help', 'Show help'],
+  ['init', 'Create or update AGENTS.md'],
+  ['models', 'List and switch models'],
+  ['new', 'Start a new session'],
+  ['redo', 'Redo a previously undone message'],
+  ['sessions', 'List and switch sessions'],
+  ['share', 'Share the current session'],
+  ['themes', 'List and switch themes'],
+  ['undo', 'Undo the last message'],
+  ['unshare', 'Unshare the current session'],
+]
+
+// @@@ opencodeSlashCommands - opencode's `/` menu: the pinned built-ins + custom commands discovered the way
+// opencode discovers its own — `.opencode/command(s)/**/*.md` in the project and `~/.config/opencode/command(s)`
+// globally (both spellings are native). Like the other builders it never guesses: what isn't readable as a
+// file contributes nothing.
+export function opencodeSlashCommands(): SlashCommand[] {
+  const all: SlashCommand[] = []
+  const cfgHome = process.env.OPENCODE_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'opencode')
+  for (const d of ['command', 'commands']) scanCommands(join(cfgHome, d), 'user', all)
+  const repo = repoRoot()
+  for (const d of ['command', 'commands']) scanCommands(join(repo, '.opencode', d), 'project', all)
+  for (const [name, description] of OPENCODE_BUILT_IN) all.push({ name, description, source: 'built-in' })
+  scanSkills(join(repo, '.opencode', 'skills'), all)
+  return dedupeSort(all)
+}

package/spec-cli/src/source-files.ts

@@ -0,0 +1,79 @@
+import { closeSync, lstatSync, openSync, readSync } from 'node:fs'
+import { join } from 'node:path'
+import { git } from './git.js'
+
+export type SourcePolicy = {
+  sourceIncludeGlobs: string[] | null
+  sourceExcludeGlobs: string[]
+  testGlobs: string[]
+}
+
+export const DEFAULT_TEST_GLOBS = [
+  '**/*.test.*',
+  '**/*.spec.*',
+  '**/test_*.*',
+  '**/*_test.*',
+  '**/test/**',
+  '**/tests/**',
+  '**/__tests__/**',
+]
+
+function globToRe(glob: string): RegExp {
+  const body = glob.split(/(\*\*\/|\*\*|\*|\?)/).map((seg) => {
+    if (seg === '**/') return '(?:.*/)?'
+    if (seg === '**') return '.*'
+    if (seg === '*') return '[^/]*'
+    if (seg === '?') return '[^/]'
+    return seg.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }).join('')
+  return new RegExp(`^${body}$`)
+}
+
+function isSpexCodeData(path: string): boolean {
+  return path === 'spexcode.json' || path === 'spexcode.local.json'
+    || path === '.spec' || path.startsWith('.spec/')
+    || path === '.plugins' || path.startsWith('.plugins/')
+}
+
+function isTextWorktreeFile(root: string, path: string): boolean {
+  const full = join(root, path)
+  let fd: number | null = null
+  try {
+    if (!lstatSync(full).isFile()) return false
+    fd = openSync(full, 'r')
+    const sample = Buffer.allocUnsafe(8000)
+    const bytes = readSync(fd, sample, 0, sample.length, 0)
+    return !sample.subarray(0, bytes).includes(0)
+  } catch {
+    return false
+  } finally {
+    if (fd !== null) closeSync(fd)
+  }
+}
+
+// Source discovery classifies tracked paths and bytes only. Language structure belongs to anchors.ts's
+// adapter registry; adding a language must never add a branch here.
+export function isSourceFile(root: string, path: string, policy: SourcePolicy): boolean {
+  if (isSpexCodeData(path)) return false
+  if (policy.sourceIncludeGlobs !== null && !policy.sourceIncludeGlobs.some((glob) => globToRe(glob).test(path))) return false
+  if (policy.sourceExcludeGlobs.some((glob) => globToRe(glob).test(path))) return false
+  if (policy.testGlobs.some((glob) => globToRe(glob).test(path))) return false
+  return isTextWorktreeFile(root, path)
+}
+
+export function trackedSourceFiles(root: string, roots: string[], policy: SourcePolicy): string[] {
+  const out = new Set<string>()
+  for (const governedRoot of roots) {
+    let listed = ''
+    try { listed = git(['-C', root, 'ls-files', '-z', '--', governedRoot]) } catch { continue }
+    for (const path of listed.split('\0')) {
+      if (path && isSourceFile(root, path, policy)) out.add(path)
+    }
+  }
+  return [...out]
+}
+
+export function sourcePolicyDescription(policy: SourcePolicy): string {
+  const includes = policy.sourceIncludeGlobs === null ? 'ALL tracked regular text' : `[${policy.sourceIncludeGlobs.join(', ')}]`
+  return `includes ${includes}; sourceExcludeGlobs [${policy.sourceExcludeGlobs.join(', ')}]; testGlobs [${policy.testGlobs.join(', ')}] (SpexCode-owned data always excluded)`
+}

package/spec-cli/src/specs.ts

@@ -141,21 +141,22 @@ function raws(): Raw[] {
 // way the sync walk (one ~450ms uninterrupted stretch) did. Same output as raws() — identical push order
 // (pre-order DFS, dir before children) and the same reId — so every caller reads the same nodes; only
 // loadSpecs (already async, on the hot path) uses it, the light one-shot callers keep the sync raws().
-async function walkAsync(dir: string, parent: string | null, acc: Raw[]): Promise<void> {
+async function walkAsync(dir: string, parent: string | null, acc: Raw[], root: string): Promise<void> {
   let myId = parent
   if (existsSync(join(dir, 'spec.md'))) {
     myId = basename(dir)
-    const relPath = relative(ROOT, join(dir, 'spec.md'))
+    const relPath = relative(root, join(dir, 'spec.md'))
     const { fm, body } = parseFrontmatter(await readFile(join(dir, 'spec.md'), 'utf8'))
     acc.push({ id: myId, parent, relPath, fm, body })
   }
   for (const e of await readdir(dir, { withFileTypes: true })) {
-    if (e.isDirectory()) await walkAsync(join(dir, e.name), myId, acc)
+    if (e.isDirectory()) await walkAsync(join(dir, e.name), myId, acc, root)
   }
 }
-async function rawsAsync(): Promise<Raw[]> {
+async function rawsAsync(root: string): Promise<Raw[]> {
   const acc: Raw[] = []
-  if (existsSync(SPEC_DIR)) await walkAsync(SPEC_DIR, null, acc)
+  const specDir = join(root, '.spec')
+  if (existsSync(specDir)) await walkAsync(specDir, null, acc, root)
   reId(acc)
   return acc
 }
@@ -222,10 +223,14 @@ export function specContent(id: string): { body: string; parts: ReturnType<typeo
   return r ? { body: r.body.trim(), parts: parseParts(r.body) } : null
 }
 
-export async function loadSpecs() {
+// `root` defaults to the backend's own checkout — the canonical tree. A session worktree may be passed
+// instead ([[source-of-truth]]'s several-checkouts principle at the loader level): its .spec is the
+// branch's pending proposal, so eval surfaces rooted at a session must load the spec tree from the SAME
+// root as their readings/indexes, or a branch-NEW node simply does not exist for them.
+export async function loadSpecs(root: string = ROOT) {
   // both indexes are one cached git walk each and independent — fetch them in parallel (async git, off
   // the event loop). Every node below is then a pure lookup.
-  const [idx, didx, allRaws] = await Promise.all([historyIndex(ROOT), driftIndex(ROOT), rawsAsync()])
+  const [idx, didx, allRaws] = await Promise.all([historyIndex(root), driftIndex(root), rawsAsync(root)])
   return Promise.all(allRaws.map(async (r) => {
     const h = rowsFor(idx, r.relPath)
     // session = the Session: trailer of the node's latest version; frontmatter `session:` is the fallback.

package/spec-cli/src/supervise.ts

@@ -2,15 +2,18 @@
 // runs the Hono server as a child on a private port (raw piping carries WS upgrades too).
 import net from 'node:net'
 import http from 'node:http'
+import { randomUUID } from 'node:crypto'
 import { spawn, type ChildProcess } from 'node:child_process'
-import { statSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync, type Dirent } from 'node:fs'
+import { statSync, readdirSync, 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'
+import { publishEndpoint, dropOwnEndpoint } from './host.js'
+import { repoRoot as servedRepoRoot } from './git.js'
+import { resolveProjectIdentity } from './project-identity.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.
@@ -40,6 +43,14 @@ const watchRoots = [
   join(repoRoot, 'spec-eval', 'src'),
 ]
 
+// @@@ instance identity - one id for this serve's whole lifetime, minted at supervisor start and handed to
+// every child via env, so the endpoint record and the live backend answer with the SAME identity across
+// zero-downtime reloads. The host gateway ([[host-gateway]]) validates a record by comparing this id (and the
+// served root) against the live /api/instance answer — a recycled port serving a DIFFERENT project or a
+// different serve generation fails the match and is treated as offline, never proxied to.
+const instanceId = randomUUID()
+const projectRoot = servedRepoRoot() // the actual git tree whose source/spec/config the child serves
+
 type Backend = { port: number; child: ChildProcess }
 let current: Backend | null = null   // which internal port new proxy connections forward to
 let reloading = false                // single-flight guard for reload()
@@ -79,7 +90,7 @@ async function boot(): Promise<Backend | null> {
   // 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(process.execPath, [tsx, entry], { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: childApiBase } })
+  const child = spawn(process.execPath, [tsx, entry], { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: childApiBase, SPEXCODE_INSTANCE_ID: instanceId } })
   // 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.
@@ -115,9 +126,9 @@ async function reload(reason: string): Promise<void> {
 // client-side timeout-kill left the client's UPSTREAM socket half-open to the child (the old handler bailed
 // only on `error`, so a clean FIN / a silent drop never reaped the upstream) — 135 leaked conns piled on the
 // child and it looked dead. So a close on either side destroys BOTH (idempotent). The abandoned-but-silent
-// case (no FIN/RST ever arrives) is reaped from the CHILD instead — its HTTP keepAliveTimeout/requestTimeout
-// close an idle/stalled socket, whose close then propagates here — so an active WS/SSE (not idle keep-alive)
-// is never mistaken for abandoned and cut.
+// case (no FIN/RST ever arrives) is reaped from the CHILD instead — its socket-level reaper (reaper.ts)
+// destroys an idle/stalled socket, whose close then propagates here — so an active WS/SSE (not idle
+// keep-alive) is never mistaken for abandoned and cut.
 const proxy = net.createServer((client) => {
   const target = current
   if (!target) { client.destroy(); return }
@@ -134,24 +145,35 @@ const proxy = net.createServer((client) => {
   client.pipe(up); up.pipe(client)
 })
 
-// @@@ endpoint record - this project's live backend endpoint, written into the per-project runtime tier
+// @@@ endpoint record - this project's live backend endpoint, published 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')
+// project's ([[remote-client]]'s resolution ladder), and what the host gateway ([[host-gateway]]) reconciles
+// its project list from. The write is ATOMIC (tmp + rename) and carries the serve's actual git toplevel +
+// resolved identity — so a reader can VALIDATE the record against the live /api/instance answer,
+// never just trust a URL. Readers health-probe before trusting, so a crashed serve 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. A linked worktree therefore
+// gets its own encoded slot and can never overwrite the main checkout's endpoint.
 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')
+    publishEndpoint({
+      version: 2,
+      url,
+      pid: process.pid,
+      instanceId,
+      root: projectRoot,
+      identity: resolveProjectIdentity(projectRoot, projectRoot),
+      startedAt: new Date().toISOString(),
+    })
   } 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).
+// best-effort removal on a clean stop, only if the record is OURS — matched by instanceId, so a newer serve
+// that already overwrote the record (or another project's) is never deleted by a retiring one.
 function dropEndpoint(): void {
-  try { if (JSON.parse(readFileSync(backendRecordPath(), 'utf8'))?.pid === process.pid) rmSync(backendRecordPath()) } catch { /* not ours / already gone */ }
+  try { dropOwnEndpoint(instanceId, projectRoot) } catch { /* not ours / already gone */ }
 }
 
 const shutdown = () => { dropEndpoint(); try { current?.child.kill('SIGTERM') } catch { /* */ } process.exit(0) }

package/spec-cli/src/tree.ts

@@ -12,9 +12,10 @@ export type TreeNode = {
   version?: number
   drift?: number
   ghost?: boolean
-  openIssues?: unknown[]
-  scenarios?: { name: string }[]
-  evals?: { scenario: string; fresh?: boolean }[]
+  reviewSummary?: {
+    issues?: { open: number }
+    evals?: { stalePass: number; staleFail: number }
+  }
 }
 
 export type TreeOpts = { node?: string; depth?: number; color?: boolean }
@@ -27,9 +28,8 @@ const STATUS_ANSI: Record<string, string> = { merged: '32', active: '36', drift:
 // board `evals` is already latest-per-scenario, so this is a straight filter — the same freshness
 // axis the dashboard's grey ✓/✗ badges read (score.jsx readingScore).
 function staleYatsu(n: TreeNode): number {
-  if (!n.scenarios?.length || !n.evals?.length) return 0
-  const latest = new Map(n.evals.map((r) => [r.scenario, r]))
-  return n.scenarios.filter((s) => { const r = latest.get(s.name); return r && r.fresh === false }).length
+  const summary = n.reviewSummary?.evals
+  return summary ? summary.stalePass + summary.staleFail : 0
 }
 
 function childrenIndex(nodes: TreeNode[]): Map<string | null, TreeNode[]> {
@@ -67,7 +67,7 @@ export function renderTree(nodes: TreeNode[], opts: TreeOpts = {}): string {
     if (n.drift) parts.push(c('33', `drift:${n.drift}`))
     const stale = staleYatsu(n)
     if (stale) parts.push(c('90', `stale:${stale}`))
-    if (n.openIssues?.length) parts.push(c('31', `issues:${n.openIssues.length}`))
+    if (n.reviewSummary?.issues?.open) parts.push(c('31', `issues:${n.reviewSummary.issues.open}`))
     return parts.length ? '  ' + parts.join(' ') : ''
   }
 
@@ -109,7 +109,7 @@ export function treeJson(nodes: TreeNode[], opts: TreeOpts = {}): object[] {
     const pruned = opts.depth !== undefined && depth >= opts.depth
     return {
       id: n.id, title: n.title, status: n.status, version: n.version ?? 0,
-      drift: n.drift ?? 0, staleYatsu: staleYatsu(n), openIssues: n.openIssues?.length ?? 0,
+      drift: n.drift ?? 0, staleYatsu: staleYatsu(n), openIssues: n.reviewSummary?.issues?.open ?? 0,
       ...(n.ghost ? { ghost: true } : {}),
       children: pruned ? kids.map((k) => k.id) : kids.map((k) => shape(k, depth + 1)),
     }