spexcode 0.1.5 → 0.2.0

package/spec-cli/src/cli.ts

@@ -1,21 +1,43 @@
 export {} // make this a module so top-level await is allowed
 const cmd = process.argv[2]
 
-// registered before any await so a top-level-await rejection lands here; BackendError matched by name to avoid importing it.
-process.on('unhandledRejection', (e: unknown) => {
-  if (e instanceof Error && e.name === 'BackendError') console.error(`spex: ${e.message}`)
+// Registered before any await so a fatal top-level error lands here. Errors we OWN (BackendError, the
+// loud malformed-config ConfigError) are matched BY NAME — to avoid importing them — and rendered as a
+// one-line `spex: <message>` (a user's config typo must read as their typo, not a SpexCode stack dump);
+// anything else prints in full so a real bug keeps its trace. A synchronous throw inside an awaited call
+// (loadConfig on a malformed spexcode.json) surfaces as uncaughtException, not unhandledRejection, so BOTH
+// paths route through the same printer.
+function fatal(e: unknown): never {
+  if (e instanceof Error && (e.name === 'BackendError' || e.name === 'ConfigError')) console.error(`spex: ${e.message}`)
   else console.error(e)
   process.exit(1)
-})
+}
+process.on('unhandledRejection', fatal)
+process.on('uncaughtException', fatal)
 
 // tiny flag reader: --key value  (and bare positionals)
 function flag(name: string): string | undefined {
   const i = process.argv.indexOf(`--${name}`)
   return i >= 0 ? process.argv[i + 1] : undefined
 }
+
+// Exit AFTER stdout has flushed. process.exit() force-quits without draining buffered pipe writes, so a
+// large piped dump (`spex issues --json | …`, board, review --json) is silently cut off at the pipe
+// buffer (~64KB). The empty write's callback fires once every prior queued chunk has drained; the returned
+// promise never resolves (process.exit ends the process inside the callback), so `await flushExit(code)`
+// halts execution here exactly like process.exit did — safe to drop in on any unbounded-output verb.
+// EPIPE (a reader that closed early — `| head`, `| jq` exiting) can never drain, so we ALSO exit on the
+// stream error rather than hang: the truncation is the reader's choice then, not ours.
+function flushExit(code = 0): Promise<never> {
+  return new Promise<never>(() => {
+    const done = () => process.exit(code)
+    process.stdout.on('error', done)
+    process.stdout.write('', done)
+  })
+}
 const has = (name: string) => process.argv.includes(`--${name}`)
 // bare positionals after argv index `from`, skipping flags and their values (selectors for ls/watch).
-const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--harness-session', '--port', '--api-port'])
+const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api-port', '--preset'])
 function positionals(from: number): string[] {
   const out: string[] = []
   for (let i = from; i < process.argv.length; i++) {
@@ -26,6 +48,23 @@ function positionals(from: number): string[] {
   return out
 }
 
+// After a successful launch, nudge the caller to actually MONITOR the session — launch-then-forget is a real
+// gap (a supervisor or human launches and then never watches, so a review/failure goes unnoticed). Goes to
+// STDERR so the JSON on stdout (which callers parse) stays clean; keyed to whoever's calling — a supervising
+// agent has an own-session id, a human at a terminal does not.
+async function launchMonitorReminder(id: string): Promise<void> {
+  const { ownSessionId } = await import('./sessions.js')
+  const agent = ownSessionId()
+  console.error(`\nspex: launched session ${id} — now MONITOR it, or its review/failure goes unnoticed:`)
+  if (agent) {
+    // a supervising agent: the per-worker monitor is a backgrounded `spex wait`, which exits on an actionable status.
+    console.error(`  supervising agent → background \`spex wait ${id}\` (blocks until it hits an actionable status, then exits)`)
+    console.error(`  or watch the whole stream: \`spex watch\``)
+  } else {
+    console.error(`  \`spex watch\` — the live stream of actionable session transitions (or \`spex wait ${id}\` to block on this one)`)
+  }
+}
+
 const greeted = new Set<string>()
 async function greetWatchTargets(watcher: string, selectors: string[]): Promise<void> {
   try {
@@ -76,46 +115,12 @@ async function resolveSelectorOrExit(selector: string): Promise<string> {
   process.exit(2)
 }
 
-function printHelp(): void {
-  console.log(`spex — SpexCode CLI (spec↔code graph + worktree session state machine)
-
-Usage: spex <command> [args]
-
-Specs / graph
-  guide [spec|yatsu]    no topic: the setup workflow; spec/yatsu: the file-format manual for authoring nodes
-  init [dir]            scaffold a repo to adopt SpexCode (seed .spec + install git hooks; default: cwd)
-  lint                  check the spec↔code graph (integrity·living·coverage·drift); when committing, gates on heavy commit-local drift
-  ack <node>… --reason  stamp Spec-OK on HEAD for one or more nodes (this change keeps their specs valid); --reason required, not stored
-  serve                 run the API server (default :8787). [--port N] sets the listen port (mirrors
-                        dashboard --api-port, so many projects coexist on one host — cwd picks the project)
-    --public --password <pw>   expose it on a public IP behind a password + self-signed TLS (no domain
-                               needed). [--tls-cert F --tls-key F] for your own cert · [--http] to drop TLS
-  dashboard             serve the dashboard UI on its own port (default 5173), proxying /api to a running
-                        \`spex serve\`. [--port N] [--api-port N=8787]. The installed replacement for \`npm run web\`.
-  board                 dump the dashboard board state as JSON
-  forge <sub>           trace a forge's issues/PRs onto spec nodes (read-only): links | eval-pending [--host github] [--node <id>] [--json]
-  yatsu <sub>           measure a node's scenarios and keep score: scan | eval [.|<node>] [--scenario N] (--pass|--fail|--note T) [--image P|--result P|-] | show [.|<node>] [--json] | clean [--keep-latest|--all]
-  hooks <sub>           harness-agnostic hook system: compile [--out <file>] (flatten surface:hook nodes into the per-session manifest the dispatcher reads)
-  self <sub>            diagnose how the workflow reaches THIS self-launched agent: doctor (default) | contract | env
-  review <SEL>          manager cockpit: review a session (ahead·merge-base diff·gates·proposal)  [--json]
-  review proof <SEL>    render the session's proof of work — self-contained HTML, fully derived (diff·measured yatsu loss·gates)  [--open|--out P|--json]
-  merge <SEL>           manager cockpit: gated atomic merge into main (re-checks gates, then closes)  [--keep]
-
-Sessions
-  ls [SEL…]             living-sessions table          [--status a,b] [--json]
-  watch [SEL…]          stream actionable transitions — NEVER EXITS; run it in the BACKGROUND, don't block a turn on it (poll one-shot with \`wait\`)  [--as NAME] [--status a,b] [--idle] [--interval N]
-  wait <SEL>            block until <SEL> is actionable, print it, exit (one-shot — the non-blocking counterpart to watch; draws the graph edge)  [--timeout S=1200] [--interval S]
-  new "<prompt>"        start a session (= session new)  [--node X]
-  session <sub>         new | list | reopen | review | done | merge | exit | close | send | capture | prompt
-  session prompt <SEL>  print the session's originating prompt (what it was asked to do)
-
-  SEL = session id (or id-prefix), node, or branch — accepted by every read/control verb (ls·watch·wait·
-        review·merge·reopen·exit·close·send·capture·prompt); none (or @all) = every session.`)
-}
-
-// a trailing --help/-h prints the summary and exits BEFORE any verb runs, so a help probe never fires a streaming/mutating command.
+// a trailing --help/-h prints help and exits BEFORE any verb runs, so a help probe never fires a
+// streaming/mutating command. It prints THAT command's usage when an entry exists (the second layer
+// of the help journey — see help.ts), falling back to the map for an unknown token.
 if (cmd && cmd !== 'help' && (has('help') || process.argv.includes('-h'))) {
-  printHelp()
+  const { commandHelp, overviewHelp } = await import('./help.js')
+  console.log(commandHelp(cmd) ?? overviewHelp())
   process.exit(0)
 }
 
@@ -140,10 +145,22 @@ if (cmd === 'serve') {
   if (!Number.isInteger(port) || !Number.isInteger(apiPort)) { console.error('spex dashboard: --port and --api-port must be integers'); process.exit(2) }
   serveDashboardLocal({ port, apiPort })
 } else if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') {
-  printHelp()
+  // `spex help <cmd>` drills into one command; bare help is the map. Both name the next layer down.
+  const { commandHelp, overviewHelp } = await import('./help.js')
+  const topic = positionals(3)[0]
+  if (cmd === 'help' && topic) {
+    const h = commandHelp(topic)
+    if (!h) { console.error(`spex help: no command '${topic}' — run \`spex help\` for the map`); process.exit(2) }
+    console.log(h)
+  } else console.log(overviewHelp())
 } else if (cmd === 'guide') {
   const { guideText } = await import('./guide.js')
-  console.log(guideText(process.argv[3]))
+  const text = guideText(process.argv[3])
+  if (text === null) {
+    console.error(`spex guide: no topic '${process.argv[3]}'. Topics: spec, yatsu, config. Run \`spex guide\` (no topic) for the setup workflow, \`spex help\` for the command map.`)
+    process.exit(2)
+  }
+  console.log(text)
 } else if (cmd === 'owner') {
   const { specOwners } = await import('./specs.js')
   const { loadConfig } = await import('./lint.js')
@@ -200,7 +217,13 @@ if (cmd === 'serve') {
   // scaffold a repo to adopt SpexCode: copy the shipped DATA templates (seed spec tree + git hooks)
   // into <targetDir> (default cwd). spex init [targetDir]
   const { specInit } = await import('./init.js')
-  await specInit(positionals(3)[0])
+  await specInit(positionals(3)[0], flag('preset'))
+} else if (cmd === 'uninstall') {
+  // the surgical inverse of init: remove every SpexCode-generated artifact (harness shims/contract/trust, the
+  // .gitignore block, the global store, any plugin bundle) — NEVER the user's .spec/.config data or their own
+  // prose. Git hooks preserved unless --hooks. spex uninstall [targetDir] [--hooks]
+  const { uninstall } = await import('./uninstall.js')
+  uninstall(positionals(3)[0], { hooks: has('hooks') })
 } else if (cmd === 'review' && positionals(3)[0] === 'proof') {
   const sel = positionals(3)[1]
   if (!sel) { console.error('usage: spex review proof <selector> [--open | --out <path> | --json]'); process.exit(2) }
@@ -208,7 +231,7 @@ if (cmd === 'serve') {
   const { clientProof } = await import('./client.js')
   const r = await clientProof(id, has('json'))
   if (!r.ok) { console.error(`no proof for ${id} (status ${r.status})`); process.exit(1) }
-  if (has('json')) { console.log(r.body); process.exit(0) }
+  if (has('json')) { console.log(r.body); await flushExit(0) }
   const { writeFileSync } = await import('node:fs')
   const { join } = await import('node:path')
   const { tmpdir } = await import('node:os')
@@ -237,7 +260,6 @@ if (cmd === 'serve') {
     console.log(`  proposal      : ${r.proposal.kind ?? '—'}${r.proposal.note ? ` — ${r.proposal.note}` : ''}`)
     console.log('  gates:')
     console.log(`    conflicts w/ main : ${g.conflictsWithMain ? 'YES' : 'no'}`)
-    console.log(`    typecheck         : ${g.typecheck.ok ? 'ok' : `${g.typecheck.errorCount} error(s)`}`)
     console.log(`    lint              : ${g.lint.errorCount} error(s), ${g.lint.warningCount} warning(s)`)
     console.log(`  diff (merge-base, ${r.diff.length} file(s)):`)
     for (const f of r.diff) console.log(`    ${f.status.padEnd(12)} +${f.additions} -${f.deletions}  ${f.path}`)
@@ -254,16 +276,32 @@ if (cmd === 'serve') {
 } else if (cmd === 'forge') {
   // thin route — all logic lives in spec-forge.
   const { runForge } = await import('../../spec-forge/src/cli.js')
-  process.exit(await runForge(process.argv.slice(3)))
+  await flushExit(await runForge(process.argv.slice(3)))
 } else if (cmd === 'yatsu') {
   // thin route — all logic lives in spec-yatsu.
   const { runYatsu } = await import('../../spec-yatsu/src/cli.js')
-  process.exit(await runYatsu(process.argv.slice(3)))
-} else if (cmd === 'hooks') {
-  // @@@ hooks - compile the surface:hook nodes into the per-session manifest the (pure-shell) dispatcher
-  // reads. Thin route, like forge/yatsu. `spex hooks compile [--out <file>]`. Logic in hooks.ts.
-  const { runHooks } = await import('./hooks.js')
-  process.exit(await runHooks(process.argv.slice(3)))
+  await flushExit(await runYatsu(process.argv.slice(3)))
+} else if (cmd === 'blob') {
+  // @@@ blob - the bare evidence-transport verb ([[blob-put]]): put bytes in the shared content-addressed
+  // cache and print the hash, decoupled from filing a reading. Thin route — the cache lives in spec-yatsu.
+  const { runBlob } = await import('../../spec-yatsu/src/cli.js')
+  await flushExit(runBlob(process.argv.slice(3)))
+} else if (cmd === 'issues') {
+  // @@@ issues - the ONE issues surface ([[issues]]): bare it is THE read — local + forge issues as ONE
+  // store-tagged list, the supervisor's/human's drain view; a write first-positional (open|reply|sign|
+  // resolve|on|off|status, [[local-issues]]) routes to the local store's write verbs, `promote` moves a
+  // thread cross-store. (The pre-rename `spex propose` alias is gone — a deployed post-merge hook still
+  // calling it prints an unknown-command line, advisory-only, until `npm run hooks` reinstalls it.)
+  const { runIssues } = await import('./issues.js')
+  await flushExit(await runIssues(process.argv.slice(3)))
+} else if (cmd === 'remark' || cmd === 'resolve' || cmd === 'retract') {
+  // @@@ remark - the resolvable interaction primitive ([[remark-substrate]]): pin a concern to a HOST (a
+  // local issue, or a scenario `<node> --scenario <name>`) that a second agent can `resolve` and the author
+  // can `retract`. CLI-first — the whole author→resolve→retract loop is these thin store-write wrappers, so
+  // the dashboard adds no capability. `spex remark <host> --body -|<text> [--code-sha <sha>]`.
+  const m = await import('./localIssues.js')
+  const run = cmd === 'remark' ? m.runRemark : cmd === 'resolve' ? m.runResolve : m.runRetract
+  await flushExit(await run(process.argv.slice(3)))
 } else if (cmd === 'materialize') {
   // @@@ materialize - the pay-per-change render: surface nodes → manifest + AGENTS.md/CLAUDE.md block +
   // shims + Codex trust, for cwd's project. The cheap shell gate (dispatch.sh) invokes it only on change.
@@ -275,17 +313,18 @@ if (cmd === 'serve') {
   // hooks+handler-existence · backend) over the same HARNESSES materialize renders through; contract prints
   // the surface:system text; env dumps raw facts. Thin route, like forge/yatsu/hooks.
   const { runSelf } = await import('./self.js')
-  process.exit(await runSelf(process.argv.slice(3)))
+  await flushExit(await runSelf(process.argv.slice(3)))
 } else if (cmd === 'board') {
   const { buildBoard } = await import('./board.js')
   console.log(JSON.stringify(await buildBoard(), null, 2))
+  await flushExit(0)
 } else if (cmd === 'search') {
   const { searchSpecs } = await import('./search.js')
   const query = positionals(3).join(' ')
   if (!query.trim()) { console.error('usage: spex search <query> [--json] [--limit N]'); process.exit(2) }
   const limit = Number(flag('limit')) || 10
   const results = await searchSpecs(query, { limit, onStats: (s) => console.error(`[spec-search] compute ${s.ms.toFixed(1)}ms · ${s.nodes} nodes · ${s.tokens} tokens (excludes process start)`) })
-  if (has('json')) { console.log(JSON.stringify(results)); process.exit(0) }
+  if (has('json')) { console.log(JSON.stringify(results)); await flushExit(0) }
   if (!results.length) { console.log(`no spec node matches "${query}"`); process.exit(0) }
   results.forEach((r, i) => {
     console.log(`${String(i + 1).padStart(2)}. ${r.title}  [${r.id}]  ·  score ${r.score}`)
@@ -293,21 +332,7 @@ if (cmd === 'serve') {
     if (r.snippet) console.log(`    ${r.snippet}`)
   })
   process.exit(0)
-} else if (cmd === 'relay') {
-  const { relaySearch } = await import('./relay.js')
-  const query = positionals(3).join(' ')
-  if (!query.trim()) { console.error('usage: spex relay <query> [--json] [--limit N]'); process.exit(2) }
-  const limit = Number(flag('limit')) || 3
-  const hits = await relaySearch(query, { limit })
-  if (has('json')) { console.log(JSON.stringify(hits)); process.exit(0) }
-  if (!hits.length) { console.log(`no spec node matches "${query}"`); process.exit(0) }
-  hits.forEach((h, i) => {
-    console.log(`${String(i + 1).padStart(2)}. ${h.title}  [${h.id}]  ·  score ${h.score}`)
-    if (h.code.length) h.code.forEach((c) => console.log(`    ${c}`))
-    else console.log(`    (no governed code: files — a pure-prose node)`)
-  })
-  process.exit(0)
-} else if (cmd === 'ls' || cmd === 'sessions') {
+} else if (cmd === 'ls') {
   // pretty list of living sessions + states. `spex ls [SEL...] [--status a,b] [--json]`
   // the board comes from the backend (so `spex ls` shows the sessions of whatever SPEXCODE_API_URL points at,
   // incl. a remote machine); selectSessions/formatTable are pure presentation, applied client-side.
@@ -353,7 +378,9 @@ if (cmd === 'serve') {
   // it falls back to an in-process launch only when no backend answers.
   const { createSession } = await import('./sessions.js')
   const prompt = flag('prompt') ?? positionals(3)[0] ?? ''
-  console.log(JSON.stringify(await createSession(flag('node') ?? null, prompt, flag('harness') ?? undefined), null, 2))
+  const created = await createSession(flag('node') ?? null, prompt, flag('harness') ?? undefined, flag('launcher') ?? undefined)
+  console.log(JSON.stringify(created, null, 2))
+  await launchMonitorReminder(created.id)
 } else if (cmd === 'session') {
   const sub = process.argv[3]
   // `s` (sessions.ts) backs the state PRODUCERS that stay local (state/done/park/fail/ask/idle write the
@@ -368,19 +395,24 @@ if (cmd === 'serve') {
   const sess = flag('session')
   // appended to a done/ask/block declaration: states (not commands) that the next tool call's mark-active hook re-flips the global record to active, so a re-read won't show this.
   const DECLARED = ' — recorded; the human sees it in the dashboard. This state lives in your session\'s global record; your next tool call flips that record back to active (the mark-active hook, by design), so it is normal for this declaration not to persist.'
+  // appended ONLY to a propose-close declaration: a worktree about to be discarded may still own ephemeral things the agent started to test this change; nudge (not gate) it to reclaim them before the worktree goes, keyed on whether the thing should outlive the task — never on who started it (a deliberately long-running service / a production build is started-by-you yet must be left alone). Project-agnostic on purpose.
+  const CLOSE_CLEANUP = '\n\nBefore this worktree closes, check whether you left anything running that you started to test this change — a background process, a dev or preview server, a bound port, a scratch session. If nothing depends on it anymore, shut it down, or it keeps running as an orphan. Leave anything meant to keep running: a service you deliberately stood up, a production build, anything other work relies on. What matters is whether it still needs to exist after this task, not whether you started it. If unsure, leave it. This is a reminder to check, not a required step.'
   if (sub === 'new') {
     // route through the backend (auth env + concurrency cap); in-process only if no backend is reachable.
     // prompt = --prompt OR the first positional (after `session new`), so `session new "<prompt>"` works the
     // SAME as the `spex new "<prompt>"` shorthand — one prompt-resolution rule, not two.
-    console.log(JSON.stringify(await s.createSession(flag('node') ?? null, flag('prompt') ?? positionals(4)[0] ?? '', flag('harness') ?? undefined), null, 2))
-  } else if (sub === 'list') {
-    console.log(JSON.stringify(await c.clientListSessions(), null, 2))
-  } else if (sub === 'reopen' || sub === 'resume') {
-    // "back to working": clear proposal -> active, relaunch if offline (the backend owns the relaunch)
+    const created = await s.createSession(flag('node') ?? null, flag('prompt') ?? positionals(4)[0] ?? '', flag('harness') ?? undefined, flag('launcher') ?? undefined)
+    console.log(JSON.stringify(created, null, 2))
+    await launchMonitorReminder(created.id)
+  } else if (sub === 'reopen') {
+    // bring the agent back up (relaunch ONLY if confirmed offline, the backend owns it); demotes a working
+    // `active` to idle but leaves a standing declaration/proposal untouched (see sessions.ts reopen()). The
+    // RESUME GUARD refuses a relaunch on a LIVE/unproven agent (that would kill a live worker) — `--force`
+    // overrides for a genuinely wedged process. A following prompt is what actually re-drives it.
     const full = await resolveSelectorOrExit(id)
-    console.log(await c.clientReopen(full) ? `${full} -> working` : `no such session ${full}`)
-  } else if (sub === 'review') {
-    console.log(await s.propose(id, 'merge') ? `${id} -> review` : `no such session ${id}`)
+    const r = await c.clientReopen(full, process.argv.includes('--force'))
+    if (r.ok) console.log(`${full} -> reopened`)
+    else { console.error(`spex session reopen: ${r.error || `no such session ${full}`}`); process.exit(2) }
   } else if (sub === 'state') {
     // the agent authors ITS OWN state: active|awaiting|parked|error  [--propose] [--note] [--session]
     const st = process.argv[4] as any
@@ -389,7 +421,8 @@ if (cmd === 'serve') {
   } else if (sub === 'done') {
     // sugar for awaiting; --propose merge|nothing|close, optional --note
     const p = (flag('propose') as any) || 'nothing'
-    console.log(s.markDone(p, sess) ? `done (${p})${DECLARED}` : 'no session record')
+    const closeNote = p === 'close' ? CLOSE_CLEANUP : ''
+    console.log(s.markDone(p, sess) ? `done (${p})${DECLARED}${closeNote}` : 'no session record')
   } else if (sub === 'park') {
     // sugar: the agent is waiting on a background task; it will self-resume (NOT idle/awaiting)
     console.log(s.markState('parked', { note: flag('note'), sessionId: sess }) ? `parked${DECLARED}` : 'no session record')
@@ -415,15 +448,6 @@ if (cmd === 'serve') {
     // never clobbering a deliberate awaiting/asking/parked/error declaration. Distinct from `ask`
     // (the agent deliberately asking the human) — idle is the undeclared stop the Stop gate missed.
     console.log(s.markIdle(sess) ? 'idle' : 'noop (no session record, or not active)')
-  } else if (sub === 'merge') {
-    // merge dispatch (same as top-level `spex merge`): reopen the session and hand its OWN agent the merge
-    // prompt — the agent runs the --no-ff merge, resolves conflicts, verifies main advanced, and proposes
-    // close. The SERVER never touches main. Fail-loud: an unreachable agent prints the reason, exits non-zero.
-    const full = await resolveSelectorOrExit(id)
-    const r = await c.clientMerge(full)
-    if (r.dispatched) console.log(`merge dispatched to ${full} — its agent is landing the merge`)
-    else console.error(`merge dispatch failed: ${r.reason}`)
-    process.exit(r.dispatched ? 0 : 1)
   } else if (sub === 'exit') {
     // the SOFT stop: kill the agent's tmux + socket but KEEP the worktree, so the session goes offline and
     // can be resumed (reopen/relaunch). Distinct from `close`, which removes the worktree.
@@ -466,35 +490,64 @@ if (cmd === 'serve') {
     if (!r.ok) { console.error(`no prompt recorded for ${full}`); process.exit(1) }
     process.stdout.write(r.prompt.endsWith('\n') ? r.prompt : r.prompt + '\n')
   } else {
-    console.error('spex session: new|list|reopen|review|done|park|ask|idle|merge|exit|close|send|capture|prompt'); process.exit(2)
+    console.error('spex session: new|reopen|done|park|ask|idle|exit|close|send|capture|prompt'); process.exit(2)
   }
-} else if (cmd === 'codex-launch') {
-  // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }
-  // (codex loads that worktree's config/hooks/AGENTS.md), store the new id on the governed record (keyed by
-  // SPEXCODE_SESSION_ID), fire the launch prompt as the FIRST turn — materializing the rollout — and print the
-  // thread id. The launch script then `resume`s it in the visible TUI.
-  const { codexStartThread, codexTurn } = await import('./harness.js')
-  const { markHarnessSessionId } = await import('./sessions.js')
-  const sock = process.argv[3], cwd = process.argv[4]
-  const prompt = process.argv.slice(5).join(' ')
-  if (!sock || !cwd) { console.error('usage: spex codex-launch <sock> <cwd> [prompt...]'); process.exit(2) }
-  const r = await codexStartThread(sock, cwd)
-  if (!r.ok) { console.error(r.error); process.exit(1) }
-  const sid = process.env.SPEXCODE_SESSION_ID
-  if (sid) markHarnessSessionId(sid, r.threadId)
-  if (prompt) {
-    const t = await codexTurn(sock, r.threadId, prompt, cwd)
-    if (!t.ok) { console.error(t.error); process.exit(1) }
+} else if (cmd === 'internal') {
+  // @@@ internal - the machine-plumbing namespace: verbs only generated hooks and launch scripts call,
+  // kept OUT of the porcelain top level so `spex help`'s vocabulary is exactly what a human/agent types.
+  const sub = process.argv[3]
+  if (sub === 'trunk') {
+    // print the resolved source-of-truth branch (layout.ts mainBranch(): config override → the main
+    // checkout's current branch → 'main'). The pre-commit main-guard captures this so it blocks direct
+    // commits on whatever the repo's trunk is actually named, never a hardcoded 'main'. One value, one
+    // line; GET /api/layout exposes the same resolution.
+    const { mainBranch } = await import('./layout.js')
+    console.log(mainBranch())
+  } else if (sub === 'codex-launch') {
+    // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }
+    // (codex loads that worktree's config/hooks/AGENTS.md), store the new id on the governed record (keyed by
+    // SPEXCODE_SESSION_ID), fire the launch prompt as the FIRST turn — materializing the rollout — and print the
+    // thread id. The launch script then `resume`s it in the visible TUI.
+    const { codexStartThread, codexTurn, waitForCodexRollout, codexBinary, codexSupportsBypassHookTrust } = await import('./harness.js')
+    const { markHarnessSessionId } = await import('./sessions.js')
+    const sock = process.argv[4], cwd = process.argv[5]
+    const prompt = process.argv.slice(6).join(' ')
+    if (!sock || !cwd) { console.error('usage: spex internal codex-launch <sock> <cwd> [prompt...]'); process.exit(2) }
+    // On the bypass-trust path (the codex install supports the flag → materialize skipped writeCodexTrust's hash),
+    // the thread the BACKEND owns must carry `bypass_hook_trust` in thread/start's config so the app-server fires
+    // the worktree's local hooks — mirror materialize's capability decision so the two stay in lockstep.
+    const bypassHookTrust = codexSupportsBypassHookTrust(codexBinary(process.env.SPEXCODE_CODEX_CMD || 'codex --yolo'))
+    const r = await codexStartThread(sock, cwd, bypassHookTrust)
+    if (!r.ok) { console.error(r.error); process.exit(1) }
+    if (prompt) {
+      const t = await codexTurn(sock, r.threadId, prompt, cwd)
+      if (!t.ok) { console.error(t.error); process.exit(1) }
+      // The visible TUI resumes this thread from its ON-DISK rollout; a freshly-spawned app-server acks the turn
+      // but persists the rollout a few seconds LATE (verified live: the SAME thread's file lands at ~2-4s, not
+      // lost). WAIT for it to land BEFORE storing the id / printing it, else FAIL LOUD — never store a
+      // non-resumable harness_session_id (that permanently wedges every reopen). The 15s budget exceeds launch.sh's
+      // fast-fail threshold, so a real failure exits past it and the retry loop won't spray duplicate-prompt threads.
+      if (!await waitForCodexRollout(r.threadId, 20000)) {
+        console.error(`codex thread ${r.threadId} started but persisted no rollout within 20s — app-server not ready; not storing a non-resumable id`)
+        process.exit(1)
+      }
+    }
+    const sid = process.env.SPEXCODE_SESSION_ID
+    if (sid) markHarnessSessionId(sid, r.threadId)
+    console.log(r.threadId)
+  } else if (sub === 'codex-turn') {
+    // fire a follow-up turn on an OWNED thread over the per-project socket (the delivery channel, exposed for
+    // tests / scripts). steer-vs-start is chosen live from the thread read.
+    const { codexTurn } = await import('./harness.js')
+    const sock = process.argv[4], tid = process.argv[5], text = process.argv.slice(6).join(' ')
+    if (!sock || !tid || !text) { console.error('usage: spex internal codex-turn <sock> <threadId> <text...>'); process.exit(2) }
+    const r = await codexTurn(sock, tid, text)
+    if (r.ok) { console.log('ok') } else { console.error(r.error); process.exit(1) }
+  } else {
+    const { commandHelp } = await import('./help.js')
+    console.error(commandHelp('internal'))
+    process.exit(2)
   }
-  console.log(r.threadId)
-} else if (cmd === 'codex-turn') {
-  // fire a follow-up turn on an OWNED thread over the per-project socket (the delivery channel, exposed for
-  // tests / scripts). steer-vs-start is chosen live from the thread read.
-  const { codexTurn } = await import('./harness.js')
-  const sock = process.argv[3], tid = process.argv[4], text = process.argv.slice(5).join(' ')
-  if (!sock || !tid || !text) { console.error('usage: spex codex-turn <sock> <threadId> <text...>'); process.exit(2) }
-  const r = await codexTurn(sock, tid, text)
-  if (r.ok) { console.log('ok') } else { console.error(r.error); process.exit(1) }
 } else {
   console.error(`spex: unknown command '${cmd}' (try: spex help)`)
   process.exit(2)

package/spec-cli/src/client.ts

@@ -74,10 +74,12 @@ export async function clientMerge(id: string): Promise<{ dispatched: boolean; re
   return await r.json().catch(() => ({ dispatched: false, reason: `bad backend response (${r.status})` }))
 }
 
-// POST /api/sessions/:id/resume — relaunch/back-to-working. {ok:false} = no such session.
-export async function clientReopen(id: string): Promise<boolean> {
-  const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({}))
-  return !!(await r.json().catch(() => ({ ok: false })))?.ok
+// POST /api/sessions/:id/resume — bring the agent back (relaunch ONLY if confirmed offline); demotes
+// working→idle, keeps any declaration. The RESUME GUARD REFUSES (409 {refused:true}) on a live/unproven agent;
+// `force` overrides for a wedged-but-alive process. {ok:false} otherwise = no such session (404).
+export async function clientReopen(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean }> {
+  const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({ force }))
+  return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }))
 }
 
 // POST /api/sessions/:id/exit — the soft stop: kill tmux + socket, KEEP the worktree (session goes offline,

package/spec-cli/src/gateway.ts

@@ -8,11 +8,13 @@ import https from 'node:https'
 import net from 'node:net'
 import { createHmac, timingSafeEqual } from 'node:crypto'
 import { execFileSync, spawnSync } from 'node:child_process'
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { readFileSync, existsSync, mkdirSync, writeFileSync, statSync } from 'node:fs'
+import { gzipSync, createGzip } from 'node:zlib'
 import { join, normalize, extname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { homedir } from 'node:os'
 import { loginPage } from './login-page.js'
+import { listenOrExit } from './listen.js'
 
 // @@@ resolvePublicConfig - the cert/gate is a RESOLVED value, never hardcoded. Reads the same precedence
 // chain the spec promises: flag > env > spexcode.json > self-signed default. Returns null when public mode
@@ -99,8 +101,8 @@ function cookieOf(header: string | undefined, name: string): string | null {
   }
   return null
 }
-function isAuthed(req: http.IncomingMessage, token: string): boolean {
-  const c = cookieOf(req.headers.cookie, COOKIE)
+function isAuthed(req: http.IncomingMessage, token: string, cookieName: string): boolean {
+  const c = cookieOf(req.headers.cookie, cookieName)
   return c != null && constEq(c, token)
 }
 
@@ -117,14 +119,19 @@ export function resolveDistDir(): string {
   return join(pkgRoot, '..', 'spec-dashboard', 'dist')
 }
 
-export type GatewayOpts = { publicPort: number; upstreamPort: number; password: string; tls: { cert: string; key: string } | null; distDir: string; host?: string; label?: string }
+export type GatewayOpts = { publicPort: number; upstreamPort: number; password: string; tls: { cert: string; key: string } | null; distDir: string; host?: string; label?: string; onBindFail?: () => void }
 
 export function startGateway(opts: GatewayOpts): void {
   // gated ONLY when a password is set; otherwise the login layer doesn't exist and the dashboard is served open.
   const gated = !!opts.password
   const token = gated ? authToken(opts.password) : ''
   const secure = !!opts.tls
-  const setCookie = `${COOKIE}=${token}; HttpOnly; Path=/; SameSite=Lax; Max-Age=2592000${secure ? '; Secure' : ''}`
+  // the auth cookie is HOST-scoped (RFC 6265 ignores the port), so two gateways on one IP would share a
+  // single 'spex_auth' jar entry and clobber each other's login. Key the name by the public port — the
+  // unique discriminator on a host, exactly what the user's two URLs differ by — so same-host instances
+  // (e.g. :8787 and :8788) stay logged in concurrently and a logout clears only its own.
+  const cookieName = `${COOKIE}_${opts.publicPort}`
+  const setCookie = `${cookieName}=${token}; HttpOnly; Path=/; SameSite=Lax; Max-Age=2592000${secure ? '; Secure' : ''}`
 
   const handler = (req: http.IncomingMessage, res: http.ServerResponse) => {
     const url = (req.url || '/').split('?')[0]
@@ -132,23 +139,31 @@ export function startGateway(opts: GatewayOpts): void {
       // login surface — the only routes reachable without a cookie. Absent entirely when ungated.
       if (url === '/login' && req.method === 'POST') return doLogin(req, res, opts.password, setCookie)
       if (url === '/login') return sendHtml(res, 200, loginPage())
-      if (url === '/logout') { res.writeHead(302, { 'Set-Cookie': `${COOKIE}=; Path=/; Max-Age=0`, Location: '/login' }); return res.end() }
-      if (!isAuthed(req, token)) {
+      if (url === '/logout') { res.writeHead(302, { 'Set-Cookie': `${cookieName}=; Path=/; Max-Age=0`, Location: '/login' }); return res.end() }
+      if (!isAuthed(req, token, cookieName)) {
         if (url.startsWith('/api')) { res.writeHead(401, { 'Content-Type': 'application/json' }); return res.end('{"error":"authentication required"}') }
         res.writeHead(302, { Location: '/login' }); return res.end()
       }
     }
     if (url.startsWith('/api')) return proxyHttp(req, res, opts.upstreamPort)
-    return serveStatic(res, opts.distDir, url)
+    return serveStatic(req, res, opts.distDir, url)
   }
 
-  const server = secure ? https.createServer({ cert: opts.tls!.cert, key: opts.tls!.key }, handler) : http.createServer(handler)
+  // server-side connection reaping ([[spec-cli]] / [[public-mode]]) - the internet-facing gateway is the
+  // public server in public mode, so it carries the SAME reaping as the child: an abandoned/slow connection
+  // dies here instead of piling up. Idle keep-alive / slow-header / never-completing request only; the gated
+  // WS upgrade (handled below) is an active connection, not reaped by these. Set AT CONSTRUCTION so the
+  // connection-checking sweep is armed with our cadence (a post-hoc set leaves it under-effective).
+  const reap = { keepAliveTimeout: 10000, headersTimeout: 20000, requestTimeout: 60000, connectionsCheckingInterval: 10000 }
+  const server = secure
+    ? https.createServer({ cert: opts.tls!.cert, key: opts.tls!.key, ...reap }, handler)
+    : http.createServer(reap, handler)
 
   // @@@ WS gate - the terminal socket rides an HTTP upgrade. Gate it by the SAME cookie (the browser sends
   // it on the same-origin handshake), then raw-pipe to the loopback supervisor, replaying the buffered
   // upgrade request so the child completes the WebSocket handshake. Mirrors supervise.ts's byte pipe.
   server.on('upgrade', (req, socket, head) => {
-    if (gated && !isAuthed(req, token)) { socket.destroy(); return }
+    if (gated && !isAuthed(req, token, cookieName)) { socket.destroy(); return }
     const up = net.connect(opts.upstreamPort, '127.0.0.1', () => {
       up.write(`${req.method} ${req.url} HTTP/1.1\r\n` + rawHeaders(req))
       if (head && head.length) up.write(head)
@@ -168,8 +183,9 @@ export function startGateway(opts: GatewayOpts): void {
     console.log(`[gateway] ${label} on ${scheme}://${isLocal ? 'localhost' : '0.0.0.0'}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`)
     if (!secure && !isLocal) console.log('[gateway] (TLS off — --http)')
   }
-  if (opts.host) server.listen(opts.publicPort, opts.host, onListen)
-  else server.listen(opts.publicPort, onListen)
+  // a busy public port is a hard, loud, non-zero exit — the SAME contract as the supervisor's proxy
+  // (see [[spec-cli]] / listen.ts), so `spex serve` and `spex dashboard` fail a port clash identically.
+  listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, onListen })
 }
 
 function rawHeaders(req: http.IncomingMessage): string {
@@ -189,26 +205,51 @@ function doLogin(req: http.IncomingMessage, res: http.ServerResponse, password:
   })
 }
 
-// reverse-proxy an /api request to the loopback supervisor (which forwards to the live child).
+// @@@ gzip at the gateway - compression is TRANSPORT, so it lives here, once, for every deployment — the
+// loopback upstream and the product semantics never know it exists. Text-ish payloads only; three
+// structural exclusions, each load-bearing: an SSE stream must not sit in a zlib buffer (event latency),
+// an already-encoded response is not re-encoded, and binary media (video/image evidence) gains nothing
+// and would fight Range requests.
+const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml)|image\/svg)/
+const wantsGzip = (req: http.IncomingMessage) => /\bgzip\b/.test(String(req.headers['accept-encoding'] || ''))
+
+// reverse-proxy an /api request to the loopback supervisor (which forwards to the live child) —
+// stream-gzipping compressible bodies (measured: the board JSON rides down at under a third).
 function proxyHttp(req: http.IncomingMessage, res: http.ServerResponse, upstreamPort: number) {
   const up = http.request({ host: '127.0.0.1', port: upstreamPort, path: req.url, method: req.method, headers: req.headers }, (upRes) => {
-    res.writeHead(upRes.statusCode || 502, upRes.headers)
-    upRes.pipe(res)
+    const type = String(upRes.headers['content-type'] || '')
+    const skip = !wantsGzip(req) || upRes.headers['content-encoding'] || !COMPRESSIBLE.test(type) || type.startsWith('text/event-stream')
+    if (skip) { res.writeHead(upRes.statusCode || 502, upRes.headers); upRes.pipe(res); return }
+    const headers = { ...upRes.headers, 'content-encoding': 'gzip', vary: 'Accept-Encoding' }
+    delete headers['content-length']   // streamed; the encoded length isn't knowable up front
+    res.writeHead(upRes.statusCode || 502, headers)
+    upRes.pipe(createGzip()).pipe(res)
   })
   up.on('error', () => { if (!res.headersSent) res.writeHead(502); res.end('upstream unreachable') })
   req.pipe(up)
 }
 
 // serve the built dashboard (vite dist). Unknown non-file paths fall back to index.html (SPA). Path
-// traversal is blocked by normalising and confining to distDir.
-function serveStatic(res: http.ServerResponse, distDir: string, urlPath: string) {
+// traversal is blocked by normalising and confining to distDir. Compressible files ship gzipped, memoized
+// per (path, mtime) — a dist file is immutable per build, so each is compressed once, not per request.
+const gzMemo = new Map<string, { mtime: number; gz: Buffer }>()
+function serveStatic(req: http.IncomingMessage, res: http.ServerResponse, distDir: string, urlPath: string) {
   const rel = normalize(decodeURIComponent(urlPath)).replace(/^(\.\.[/\\])+/, '')
   let file = join(distDir, rel)
   if (!file.startsWith(distDir)) file = join(distDir, 'index.html')
   if (urlPath === '/' || !existsSync(file)) file = join(distDir, 'index.html')
   if (!existsSync(file)) { res.writeHead(503); return res.end('dashboard build missing') }
-  res.writeHead(200, { 'Content-Type': MIME[extname(file)] || 'application/octet-stream' })
-  res.end(readFileSync(file))
+  const type = MIME[extname(file)] || 'application/octet-stream'
+  const raw = readFileSync(file)
+  if (wantsGzip(req) && COMPRESSIBLE.test(type)) {
+    const mtime = statSync(file).mtimeMs
+    let hit = gzMemo.get(file)
+    if (!hit || hit.mtime !== mtime) { hit = { mtime, gz: gzipSync(raw) }; gzMemo.set(file, hit) }
+    res.writeHead(200, { 'Content-Type': type, 'Content-Encoding': 'gzip', Vary: 'Accept-Encoding' })
+    return res.end(hit.gz)
+  }
+  res.writeHead(200, { 'Content-Type': type })
+  res.end(raw)
 }
 
 function sendHtml(res: http.ServerResponse, status: number, html: string) {