spexcode 0.1.6 → 0.2.1

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', '--host', '--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)
 }
 
@@ -132,18 +137,32 @@ if (cmd === 'serve') {
   }
   await import('./supervise.js')
 } else if (cmd === 'dashboard') {
-  // the natural post-install UI: serve the bundled dashboard on its OWN loopback port, proxying /api +
-  // the terminal socket to a separately-run `spex serve`. Replaces the dogfood-only `npm run web` (vite).
+  // the natural post-install UI: serve the bundled dashboard on its OWN port (loopback by default;
+  // --host widens the bind for LAN/tailnet viewing), proxying /api + the terminal socket to a
+  // separately-run `spex serve`. Replaces the dogfood-only `npm run web` (vite).
   const { serveDashboardLocal } = await import('./gateway.js')
   const port = Number(flag('port') ?? process.env.SPEXCODE_DASHBOARD_PORT ?? 5173)
   const apiPort = Number(flag('api-port') ?? process.env.PORT ?? 8787)
+  const host = flag('host') ?? '127.0.0.1'
   if (!Number.isInteger(port) || !Number.isInteger(apiPort)) { console.error('spex dashboard: --port and --api-port must be integers'); process.exit(2) }
-  serveDashboardLocal({ port, apiPort })
+  serveDashboardLocal({ port, apiPort, host })
 } 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 +219,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 +233,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 +262,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 +278,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 +315,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 +334,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 +380,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 +397,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 +423,15 @@ 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')
+    let closeNote = p === 'close' ? CLOSE_CLEANUP : ''
+    if (p === 'close') {
+      // the DATA half of the close nudge ([[local-issues]] closeoutNudge): the still-open local issues this
+      // session touched, listed by id — empty/OFF/no-identity prints nothing. Loud on failure but never
+      // gating: the declaration must land whatever the issue store is doing.
+      try { closeNote += (await import('./localIssues.js')).closeoutNudge(sess ?? s.ownSessionId()) }
+      catch (e) { console.error(`issue closeout check failed (declaration unaffected): ${e instanceof Error ? e.message : e}`) }
+    }
+    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 +457,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 +499,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,