spexcode 0.2.1 → 0.2.3

package/spec-cli/src/cli.ts

@@ -1,14 +1,29 @@
 export {} // make this a module so top-level await is allowed
+// static import is fine here: mentions.ts is dependency-free at module level, and stripRefSigil is needed
+// by several verbs (owner, new, tree) — a CLI reference arg tolerates an optional @/[[ ]] sigil ([[mentions]]).
+import { stripRefSigil } from './mentions.js'
+
+// @@@ verb mirror - one verb, either drawer ([[cli-surface]]): a session verb promoted to the top
+// level also answers under `spex session …`, and a typeable session sub also answers bare at the top
+// level. Pure argv rewrite BEFORE the single dispatch — an alias, never a second copy of the logic —
+// so every downstream reader (--help interception included) sees the canonical spelling. Hook-driven
+// subs (state · fail · idle · commit-gate) stay namespace-only: nobody types them, so they are not
+// vocabulary to guess.
+const PROMOTED_SESSION_VERBS = new Set(['new', 'ls', 'watch', 'wait', 'review', 'merge'])
+const SESSION_SUBS = new Set(['reopen', 'done', 'park', 'ask', 'exit', 'close', 'send', 'capture', 'attach', 'rename', 'rawkey', 'prompt'])
+if (process.argv[2] === 'session' && PROMOTED_SESSION_VERBS.has(process.argv[3])) process.argv.splice(2, 1)
+else if (SESSION_SUBS.has(process.argv[2])) process.argv.splice(2, 0, 'session')
 const cmd = process.argv[2]
 
-// 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);
+// Registered before any await so a fatal top-level error lands here. Errors we OWN — BackendError, the
+// loud malformed-config ConfigError, the --api/--port UsageError, the write-guard GuardError — are
+// matched BY NAME (to avoid importing them) and rendered as a one-line `spex: <message>` (a user's
+// config typo or a refused cross-project write must read as their situation, 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}`)
+  if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError'].includes(e.name)) console.error(`spex: ${e.message}`)
   else console.error(e)
   process.exit(1)
 }
@@ -37,7 +52,7 @@ function flushExit(code = 0): Promise<never> {
 }
 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', '--launcher', '--harness-session', '--port', '--api-port', '--host', '--preset'])
+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', '--api-port', '--host', '--preset', '--limit', '--session', '--depth'])
 function positionals(from: number): string[] {
   const out: string[] = []
   for (let i = from; i < process.argv.length; i++) {
@@ -107,14 +122,37 @@ async function withWatchEdge<T>(selectors: string[], intervalMs: number, body: (
 async function resolveSelectorOrExit(selector: string): Promise<string> {
   if (!selector) { console.error('spex: missing session selector (id | id-prefix | node | branch)'); process.exit(2) }
   const { resolveClientSession } = await import('./client.js')
+  const { sessionLabel } = await import('./sessions.js')
   const r = await resolveClientSession(selector)
   if ('ok' in r) return r.ok.id
   if ('none' in r) { console.error(`spex: no such session: ${selector}`); process.exit(2) }
   console.error(`spex: ambiguous selector "${selector}" matches ${r.ambiguous.length} sessions — be more specific:`)
-  for (const s of r.ambiguous) console.error(`  ${s.id.slice(0, 8)}  ${s.node || s.branch || s.id}`)
+  for (const s of r.ambiguous) console.error(`  ${s.id.slice(0, 8)}  ${sessionLabel(s)}`)
   process.exit(2)
 }
 
+// the [[review-proof]] EXPORT artifact, shared by `spex eval <SEL> --export` (canonical) and the deprecated
+// `spex review proof` alias: fetch the backend-rendered self-contained HTML (or the model, --json), write
+// it (--out, else a tmp file) or open it (--open). Never returns.
+async function proofExport(id: string): Promise<never> {
+  const { clientProof } = await import('./client.js')
+  const r = await clientProof(id, has('json'))
+  if (!r.ok) { console.error(`no export for ${id} (status ${r.status})`); process.exit(1) }
+  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')
+  const out = flag('out') ?? join(tmpdir(), `spexcode-eval-${id.slice(0, 8)}.html`)
+  writeFileSync(out, r.body)
+  if (has('open')) {
+    const { spawn } = await import('node:child_process')
+    const opener = process.platform === 'darwin' ? 'open' : 'xdg-open'
+    try { spawn(opener, [out], { detached: true, stdio: 'ignore' }).unref(); console.log(`opened ${out}`) }
+    catch { console.log(`wrote ${out} — couldn't auto-open, open it in a browser`) }
+  } else console.log(out)
+  process.exit(0)
+}
+
 // 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.
@@ -164,25 +202,36 @@ if (cmd === 'serve') {
   }
   console.log(text)
 } else if (cmd === 'owner') {
-  const { specOwners } = await import('./specs.js')
+  // BOTH [[governed-related]] relations, distinctly: governors (code: — the verdict) and referencers
+  // (related: — pointers; coverage only, never drift/yatsu).
+  const { specOwners, specRelated } = await import('./specs.js')
   const { loadConfig } = await import('./lint.js')
-  const p = positionals(3)[0]
-  if (!p) { console.error('usage: spex owner <path>'); process.exit(2) }
+  const p0 = positionals(3)[0]
+  if (!p0) { console.error('usage: spex owner <path> [--actionable]'); process.exit(2) }
+  const p = stripRefSigil(p0)
   const rel = p.startsWith(process.cwd()) ? p.slice(process.cwd().length + 1) : p
   const owners = specOwners(p)
+  const related = specRelated(p)
   const maxOwners = loadConfig(process.cwd()).maxOwners
-  if (owners.length === 0) {
-    console.log(`${rel} — no spec governs this yet (uncovered). If your change is substantive, give it a home before it drifts.`)
+  const names = (xs: { id: string }[]) => xs.map((o) => `'${o.id}'`).join(', ')
+  const relLine = related.length ? `\n  also referenced by ${names(related)} (related: coverage only — no drift, no yatsu)` : ''
+  if (owners.length === 0 && related.length === 0) {
+    console.log(`${rel} — no spec claims this yet (uncovered). If your change is substantive, give it a home before it drifts.`)
+  } else if (owners.length === 0) {
+    // related-only: lint's coverage is satisfied, so the per-edit hook stays silent (lint-consistent) —
+    // but a human asking gets the honest nuance: nothing tracks this file's drift.
+    if (has('actionable')) process.exit(0)
+    console.log(`${rel} — not governed (no code: claim), but referenced by ${names(related)} (related: coverage only). Nothing tracks its drift; if your change is substantive, consider giving it a governing home.`)
   } else if (owners.length <= maxOwners) {
     // a sanely-owned file is NOT actionable: --actionable callers (the per-edit spec-of-file hook) stay
     // silent here, so the annotation fires only on an OVER-owned or uncovered file — rare and worth acting on.
     if (has('actionable')) process.exit(0)
     const named = owners.map((o) => `'${o.id}'`).join(', ')
     const lead = owners.length === 1 ? `${rel} is governed by ${named} — ${owners[0].desc}` : `${rel} is governed by ${named} (shared, fine).`
-    console.log(`${lead} Read/honor the spec; if your change shifts the intent, update the spec in the SAME commit.`)
+    console.log(`${lead} Read/honor the spec; if your change shifts the intent, update the spec in the SAME commit.${relLine}`)
   } else {
     const ids = owners.map((o) => o.id).join(', ')
-    console.log(`${rel} is governed by ${owners.length} specs (${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).`)
+    console.log(`${rel} is governed by ${owners.length} specs (${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
   }
 } else if (cmd === 'lint') {
   const { specLint, driftGate, DRIFT_GUIDANCE } = await import('./lint.js')
@@ -200,7 +249,12 @@ if (cmd === 'serve') {
   if (blocked.length) console.error(`\n✗ SpexCode: ${blocked.join(', ')} ${blocked.length === 1 ? 'is' : 'are'} ≥ ${threshold} commit(s) behind. Reconcile (above) or bypass with SPEXCODE_SKIP_LINT=1.`)
   process.exit(errors.length || blocked.length ? 1 : 0)
 } else if (cmd === 'ack') {
-  // --amend stamps the Spec-OK trailers in the same block as Session:; git de-dupes adjacent trailers, so re-acking is harmless.
+  // An EMPTY stamp commit on top of HEAD, never an amend: driftFor (git.ts) quiets every drift commit
+  // REACHABLE from an ack, so a child stamp covers exactly what amending HEAD would — and it works where
+  // amend can't: on a trunk merge commit, re-authoring it after MERGE_HEAD is gone reads to main-guard as
+  // a direct trunk commit. The guard passes the stamp through its tree-unchanged gate instead. `--only`
+  // with no paths pins the commit to HEAD's tree even when the index is dirty — an ack must never sweep
+  // staged files along. git de-dupes adjacent trailers, so re-acking is harmless.
   const { git } = await import('./git.js')
   const nodes = positionals(3)
   const reason = (flag('reason') ?? '').trim()
@@ -210,8 +264,9 @@ if (cmd === 'serve') {
     process.exit(2)
   }
   try {
-    git(['commit', '--amend', '--no-edit', ...nodes.flatMap((n) => ['--trailer', `Spec-OK: ${n}`])])
-    console.log(`Spec-OK: ${nodes.join(', ')} → ${git(['rev-parse', '--short', 'HEAD']).trim()}  (reason required, not stored)`)
+    git(['commit', '--only', '--allow-empty', '-m', `ack: Spec-OK ${nodes.join(', ')}`,
+      ...nodes.flatMap((n) => ['--trailer', `Spec-OK: ${n}`])])
+    console.log(`Spec-OK: ${nodes.join(', ')} → ${git(['rev-parse', '--short', 'HEAD']).trim()}  (empty stamp commit; reason required, not stored)`)
   } catch (e: any) {
     console.error(`ack failed: ${e?.message ?? e}`); process.exit(1)
   }
@@ -226,26 +281,58 @@ if (cmd === 'serve') {
   // 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 === 'eval') {
+  // the session EVAL read ([[review-proof]]'s interactive face as a CLI verb): the dashboard Eval tab's
+  // text twin. Renders the session's changed nodes with each DECLARED scenario at its CURRENT score
+  // (latest reading per scenario, worktree-rooted) — blind spots lead, the session's OWN measurements
+  // ✦-marked ahead of the inherited baseline under its divider. --export writes the self-contained HTML
+  // artifact instead (the demoted `spex review proof`).
+  const sel = positionals(3)[0]
+  if (!sel) { console.error('usage: spex eval <SEL> [--json]   |   spex eval <SEL> --export [--open | --out <path> | --json]'); process.exit(2) }
+  const id = await resolveSelectorOrExit(sel)
+  if (has('export')) await proofExport(id)
+  const { clientEvals } = await import('./client.js')
+  const r = await clientEvals(id)
+  if (!r.ok) { console.error(`no evals for ${id} (status ${r.status})`); process.exit(1) }
+  if (has('json')) { console.log(JSON.stringify(r.model, null, 2)); await flushExit(0) }
+  const m = r.model
+  // mirror the tab's scenarioStates per node: latest reading per DECLARED scenario (evals arrive
+  // newest-first), so a retired scenario's residual reading contributes no row; the ✦ count is over
+  // these rows — the same number the tab's chip shows.
+  const groups = m.nodes.map((n) => {
+    const latest = new Map<string, (typeof n.evals)[number]>()
+    for (const e of n.evals) if (!latest.has(e.scenario)) latest.set(e.scenario, e)
+    const blind = n.scenarios.filter((s) => !latest.has(s.name))
+    const rows = n.scenarios.filter((s) => latest.has(s.name)).map((s) => latest.get(s.name)!)
+      .sort((a, b) => (Number(b.inSession) - Number(a.inSession)) || (a.ts < b.ts ? 1 : -1))
+    return { n, blind, rows }
+  })
+  const own = groups.reduce((a, g) => a + g.rows.filter((e) => e.inSession).length, 0)
+  console.log(`eval ${m.title}  [${m.id}]`)
+  console.log(`  branch : ${m.branch ?? '—'} · ${m.ahead} commit(s) ahead · ${m.dirtyNonRuntime} uncommitted`)
+  console.log(`  gates  : ${m.gates.map((g) => `${g.ok ? '✓' : '✗'} ${g.label} — ${g.detail}`).join(' · ')}`)
+  if (own) console.log(`  ✦      : ${own} scenario(s) measured by THIS session (unmarked rows = inherited baseline)`)
+  if (!m.nodes.length) console.log('\n  no changed spec nodes — nothing to evaluate yet (empty diff)')
+  for (const { n, blind, rows } of groups) {
+    console.log(`\n${n.title}  [${n.id}]${n.uncoveredFrontend ? '  ⚠ frontend change with NO yatsu.md — a blind spot: give it a scenario' : ''}`)
+    for (const s of blind) console.log(`      ∅ unmeasured  ${s.name}  — declared, never measured (blind spot)`)
+    let divided = false
+    for (const e of rows) {
+      if (!e.inSession && !divided && rows.some((x) => x.inSession)) { console.log(`      ── inherited baseline (other sessions' latest readings) ──`); divided = true }
+      const verdict = e.verdict?.status === 'pass' ? '✓ pass' : e.verdict?.status === 'fail' ? '✗ fail' : '· unscored'
+      const stale = e.fresh ? '' : ` (stale: ${e.staleAxes.join(',')})`
+      console.log(`    ${e.inSession ? '✦' : ' '} ${verdict}${stale}  ${e.scenario}  — ${e.ts}${e.evaluator ? ` · ${e.evaluator}` : ''}`)
+    }
+    if (!n.hasYatsu && !n.uncoveredFrontend) console.log('      (no yatsu.md — nothing declared to measure)')
+    else if (n.hasYatsu && !n.scenarios.length) console.log('      (yatsu.md declares no scenarios)')
+  }
 } else if (cmd === 'review' && positionals(3)[0] === 'proof') {
+  // deprecated alias — proof was demoted from a review sub-noun to the export face of the ONE eval read.
+  // Still runs, but echoes the canonical form so callers migrate.
   const sel = positionals(3)[1]
-  if (!sel) { console.error('usage: spex review proof <selector> [--open | --out <path> | --json]'); process.exit(2) }
-  const id = await resolveSelectorOrExit(sel)
-  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); await flushExit(0) }
-  const { writeFileSync } = await import('node:fs')
-  const { join } = await import('node:path')
-  const { tmpdir } = await import('node:os')
-  const out = flag('out') ?? join(tmpdir(), `spexcode-proof-${id.slice(0, 8)}.html`)
-  writeFileSync(out, r.body)
-  if (has('open')) {
-    const { spawn } = await import('node:child_process')
-    const opener = process.platform === 'darwin' ? 'open' : 'xdg-open'
-    try { spawn(opener, [out], { detached: true, stdio: 'ignore' }).unref(); console.log(`opened ${out}`) }
-    catch { console.log(`wrote ${out} — couldn't auto-open, open it in a browser`) }
-  } else console.log(out)
-  process.exit(0)
+  if (!sel) { console.error('usage: spex eval <SEL> --export [--open | --out <path> | --json]   (`spex review proof` is a deprecated alias)'); process.exit(2) }
+  console.error('spex: `spex review proof` is deprecated ≡ spex eval <SEL> --export')
+  await proofExport(await resolveSelectorOrExit(sel))
 } else if (cmd === 'review') {
   const { clientReview } = await import('./client.js')
   const sel = positionals(3)[0]
@@ -256,7 +343,7 @@ if (cmd === 'serve') {
   if (has('json')) { console.log(JSON.stringify(r, null, 2)) }
   else {
     const g = r.gates
-    console.log(`review ${r.node || r.branch || r.id}  [${r.id}]`)
+    console.log(`review ${r.label}  [${r.id}]`)
     console.log(`  ahead of main : ${r.ahead} commit(s)`)
     console.log(`  uncommitted   : ${r.dirtyNonRuntime} non-runtime file(s)`)
     console.log(`  proposal      : ${r.proposal.kind ?? '—'}${r.proposal.note ? ` — ${r.proposal.note}` : ''}`)
@@ -284,14 +371,16 @@ if (cmd === 'serve') {
   const { runYatsu } = await import('../../spec-yatsu/src/cli.js')
   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.
+  // @@@ blob - the bare evidence-transport pair ([[blob-put]], [[blob-get]]): put bytes in the shared
+  // content-addressed cache / read them back by hash, decoupled from filing a reading. Thin route — the
+  // cache lives in spec-yatsu. flushExit matters here: `get` pipes raw blob bytes to stdout.
   const { runBlob } = await import('../../spec-yatsu/src/cli.js')
-  await flushExit(runBlob(process.argv.slice(3)))
+  await flushExit(await 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
+  // store-tagged list, the supervisor's/human's drain view; a write first-positional (open|reply|
+  // on|off|status, [[local-issues]]) routes to the write verbs (open/reply/close are store-routed —
+  // the SAME createIssue/replyIssue/closeIssue the dashboard's API calls), `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')
@@ -309,25 +398,61 @@ if (cmd === 'serve') {
   // shims + Codex trust, for cwd's project. The cheap shell gate (dispatch.sh) invokes it only on change.
   const { materialize } = await import('./materialize.js')
   console.log(`materialized — content-hash ${materialize()}`)
-} else if (cmd === 'self') {
-  // @@@ self - the self-diagnosis surface (spec-cli/self): does the materialized workflow actually reach
-  // THIS self-launched agent? doctor reports per-layer coverage (preconditions · git-hook floor · contract ·
-  // 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')
-  await flushExit(await runSelf(process.argv.slice(3)))
+} else if (cmd === 'doctor') {
+  // @@@ doctor - the diagnosis surface ([[doctor]], né `self` — renamed: "self" read as the tool itself /
+  // the global install, while the report is about THIS agent's wiring): does the materialized workflow
+  // actually reach this agent? Bare `doctor` reports per-layer coverage (preconditions · git-hook floor ·
+  // contract · hooks+handler-existence · backend) over the same HARNESSES materialize renders through;
+  // `contract` prints the surface:system text; `conflicts` just the double-delivery check. Thin route.
+  const { runDoctor } = await import('./doctor.js')
+  await flushExit(await runDoctor(process.argv.slice(3)))
 } else if (cmd === 'board') {
   const { buildBoard } = await import('./board.js')
+  // interactive-only stderr hint: the JSON dump is machine food; a human at a tty gets pointed at
+  // the readable twin. Piped/redirected stdout stays byte-identical (the hint never touches stdout).
+  if (process.stdout.isTTY) console.error('(human-readable tree: spex tree)')
   console.log(JSON.stringify(await buildBoard(), null, 2))
   await flushExit(0)
+} else if (cmd === 'tree') {
+  // @@@ tree - the human-readable graph ([[spex-tree]]): the same buildBoard() the dashboard renders,
+  // as an indented status-coloured terminal tree. Colour degrades cleanly: off unless stdout is a tty,
+  // and NO_COLOR always wins.
+  const { buildBoard } = await import('./board.js')
+  const { renderTree, treeJson } = await import('./tree.js')
+  const depthRaw = flag('depth')
+  const depth = depthRaw === undefined ? undefined : Number(depthRaw)
+  if (depth !== undefined && (!Number.isInteger(depth) || depth < 0)) { console.error('spex tree: --depth must be a non-negative integer'); process.exit(2) }
+  const opts = { node: flag('node') && stripRefSigil(flag('node')!), depth, color: process.stdout.isTTY && !process.env.NO_COLOR }
+  const { nodes } = await buildBoard()
+  try {
+    console.log(has('json') ? JSON.stringify(treeJson(nodes, opts), null, 2) : renderTree(nodes, opts))
+  } catch (e: any) {
+    console.error(`spex tree: ${e?.message ?? e}`)
+    process.exit(2)
+  }
+  await flushExit(0)
 } else if (cmd === 'search') {
-  const { searchSpecs } = await import('./search.js')
+  const { searchSpecs, nearestTitles } = 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)); await flushExit(0) }
-  if (!results.length) { console.log(`no spec node matches "${query}"`); process.exit(0) }
+  // zero-result fail-loud + route-to-next-step: always the corpus-is-English fact (unconditional — no
+  // language sniffing, no score threshold), plus the nearest titles when anything is even near (typo
+  // recovery) and the browse-all pointer, so no query dead-ends.
+  const NO_MATCH = (q: string) => {
+    const near = nearestTitles(q, 3)
+    return [
+      `no spec node matches "${q}" (the corpus is English — if your query isn't, translate and retry)`,
+      ...(near.length ? ['nearest titles:', ...near.map((t) => `  ${t.title}  [${t.id}]`)] : []),
+      'browse all: spex tree',
+    ].join('\n')
+  }
+  if (has('json')) {
+    if (!results.length) console.error(NO_MATCH(query))   // stderr: the stdout JSON contract stays verbatim
+    console.log(JSON.stringify(results)); await flushExit(0)
+  }
+  if (!results.length) { console.log(NO_MATCH(query)); process.exit(0) }
   results.forEach((r, i) => {
     console.log(`${String(i + 1).padStart(2)}. ${r.title}  [${r.id}]  ·  score ${r.score}`)
     console.log(`    ${r.path}`)
@@ -379,8 +504,10 @@ if (cmd === 'serve') {
   // createSession POSTs to the running backend so the launch runs in the backend's process (auth env + cap);
   // it falls back to an in-process launch only when no backend answers.
   const { createSession } = await import('./sessions.js')
+  if (has('harness')) { console.error('spex new: --harness was removed; use --launcher <name> (for example --launcher codex)'); process.exit(2) }
   const prompt = flag('prompt') ?? positionals(3)[0] ?? ''
-  const created = await createSession(flag('node') ?? null, prompt, flag('harness') ?? undefined, flag('launcher') ?? undefined)
+  const nodeArg = flag('node')
+  const created = await createSession(nodeArg ? stripRefSigil(nodeArg) : null, prompt, flag('launcher') ?? undefined)
   console.log(JSON.stringify(created, null, 2))
   await launchMonitorReminder(created.id)
 } else if (cmd === 'session') {
@@ -399,14 +526,14 @@ if (cmd === 'serve') {
   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.
-    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') {
+  // truncation transparency ([[state]]): the board table shows only the first NOTE_BOARD_LIMIT chars of a
+  // note. When a declared note overflows that cap, the confirmation says so — length, what the board shows,
+  // where the full text is readable — so the cut is visible to the author instead of silently eaten.
+  // A nudge riding the echo, never a gate: the declaration has already landed.
+  const noteEcho = (note?: string) => (note && note.length > s.NOTE_BOARD_LIMIT)
+    ? `\nyour note is ${note.length} chars; the board table shows only the first ${s.NOTE_BOARD_LIMIT} — the full text IS recorded, and readable via spex review ${(sess || s.ownSessionId() || '<your-session>').slice(0, 8)} / spex ls --json.`
+    : ''
+  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`
@@ -419,7 +546,7 @@ if (cmd === 'serve') {
     // the agent authors ITS OWN state: active|awaiting|parked|error  [--propose] [--note] [--session]
     const st = process.argv[4] as any
     const ok = s.markState(st, { proposal: flag('propose') as any, note: flag('note'), sessionId: sess })
-    console.log(ok ? `state -> ${st}` : 'no session record (unknown --session / no CLAUDE_CODE_SESSION_ID, or bad status)')
+    console.log(ok ? `state -> ${st}${noteEcho(flag('note'))}` : 'no session record (unknown --session / no CLAUDE_CODE_SESSION_ID, or bad status)')
   } else if (sub === 'done') {
     // sugar for awaiting; --propose merge|nothing|close, optional --note
     const p = (flag('propose') as any) || 'nothing'
@@ -431,10 +558,10 @@ if (cmd === 'serve') {
       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')
+    console.log(s.markDone(p, sess, flag('note')) ? `done (${p})${DECLARED}${noteEcho(flag('note'))}${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')
+    console.log(s.markState('parked', { note: flag('note'), sessionId: sess }) ? `parked${DECLARED}${noteEcho(flag('note'))}` : 'no session record')
   } else if (sub === 'fail') {
     // the StopFailure hook marks its session (--session from the payload) as error (turn died on an API error)
     console.log(s.markError(sess) ? 'marked error' : 'no session record')
@@ -442,7 +569,7 @@ if (cmd === 'serve') {
     // the agent DELIBERATELY declares it is pausing to ask the human a question (like `done`/`park`, an
     // authored state — NOT guarded active-only). The --note carries the question. Distinct from `park`
     // (waiting on a background task, self-resumes): an asking agent resumes only when the human replies.
-    console.log(s.markState('asking', { note: flag('note'), sessionId: sess }) ? `asking${DECLARED}` : 'no session record')
+    console.log(s.markState('asking', { note: flag('note'), sessionId: sess }) ? `asking${DECLARED}${noteEcho(flag('note'))}` : 'no session record')
   } else if (sub === 'commit-gate') {
     // the Stop gate's deterministic commit check (from cwd = the worktree): exit 0 if the node branch is
     // ready to declare done/merge (work committed + ahead of main), else print the reason and exit 1. Uses
@@ -492,6 +619,32 @@ if (cmd === 'serve') {
     const r = await c.clientCapture(full)
     if (r.ok) { process.stdout.write(r.pane) }
     else { console.error(`spex capture: ${r.reason}`); process.exit(r.status === 404 ? 2 : 1) }
+  } else if (sub === 'rename') {
+    // set the session's display-name override — the right-click rename ([[session-rename]]) as a verb, so an
+    // agent manager can fix a label without the GUI. An EXPLICIT "" clears back to the derived label; a
+    // MISSING argument is a usage error, never a silent clear. Unknown session → the endpoint's 404, loud.
+    const full = await resolveSelectorOrExit(id)
+    const name = process.argv[5]
+    if (name === undefined) { console.error('usage: spex session rename <SEL> "<name>"   (an explicit "" clears the override)'); process.exit(2) }
+    if (await c.clientRename(full, name)) console.log(name.trim() ? `${full} -> renamed "${name.trim()}"` : `${full} -> name cleared (derived label restored)`)
+    else { console.error(`spex session rename: no such session ${full}`); process.exit(2) }
+  } else if (sub === 'rawkey') {
+    // forward raw nav-mode keystrokes (tmux send-keys, NEVER the prompt socket) — how a manager drives a
+    // worker wedged in an interactive TUI dialog the prompt channel can't reach (a select menu wanting one
+    // Enter/arrow). Tokens = named keys, single chars, C-/M-/S- combos; whitespace-separated, delivered as
+    // ONE ordered batch ([[nav-mode-key-ordering]]). Fail-loud: nothing delivered exits non-zero.
+    const full = await resolveSelectorOrExit(id)
+    const keys = process.argv.slice(5).flatMap((s) => s.split(/\s+/)).filter(Boolean)
+    if (keys.length === 0) { console.error('usage: spex session rawkey <SEL> "<keys>"   (e.g. "Up Up Enter", "C-r", single chars)'); process.exit(2) }
+    if (await c.clientRawkey(full, keys)) console.log(`sent ${keys.length} key${keys.length === 1 ? '' : 's'} -> ${full}`)
+    else { console.error(`spex session rawkey: nothing delivered to ${full} (offline, unknown session, or no valid key token)`); process.exit(1) }
+  } else if (sub === 'attach') {
+    // the HUMAN escape hatch (attach.ts, [[session-attach]]): foreground `tmux attach` into the worker's
+    // real session. Guards fail loud BEFORE resolving: local-only (the tmux server is the backend
+    // machine's) and terminal-only (an agent must never block its turn on it — capture/send/rawkey).
+    const { assertLocalBackend, attachSession } = await import('./attach.js')
+    await assertLocalBackend()
+    await attachSession(await resolveSelectorOrExit(id))
   } else if (sub === 'prompt') {
     // print the session's full ORIGINATING prompt (what it was asked to do), captured at launch.
     const full = await resolveSelectorOrExit(id)
@@ -499,7 +652,7 @@ 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|reopen|done|park|ask|idle|exit|close|send|capture|prompt'); process.exit(2)
+    console.error('spex session: new|ls|watch|wait|review|merge|reopen|done|park|ask|exit|close|send|capture|attach|rename|rawkey|prompt  (spex help session)'); process.exit(2)
   }
 } else if (cmd === 'internal') {
   // @@@ internal - the machine-plumbing namespace: verbs only generated hooks and launch scripts call,

package/spec-cli/src/client.ts

@@ -1,4 +1,5 @@
-import { apiBase, resolveSession, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
+import { apiBase, assertProjectMatch, resolveSession, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
+import type { SessionEvals } from '../../spec-yatsu/src/proof.js'
 
 export class BackendError extends Error {
   constructor(message: string, readonly status?: number) {
@@ -7,15 +8,20 @@ export class BackendError extends Error {
   }
 }
 
-// the ONE seam where "no backend" becomes loud. A network failure (nothing listening at apiBase) is the only
-// thing thrown; an HTTP Response of any status is returned for the caller to interpret.
+// the ONE seam where "no backend" becomes loud. A network failure (nothing listening at the resolved base)
+// is the only thing thrown; an HTTP Response of any status is returned for the caller to interpret.
 async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
+  const base = await apiBase()
   try {
-    return await fetch(`${apiBase()}${path}`, init)
+    return await fetch(`${base}${path}`, init)
   } catch (e) {
-    throw new BackendError(`no backend reachable at ${apiBase()} — run \`spex serve\` there, or set SPEXCODE_API_URL (${(e as Error).message})`)
+    throw new BackendError(`no backend reachable at ${base} — run \`spex serve\` in the project, or name one with --api <url> (${(e as Error).message})`)
   }
 }
+// every MUTATING verb is project-bound ([[remote-client]]'s write guard): resolve the backend, compare its
+// served root to the cwd project, refuse loudly on a same-host mismatch — an explicit --api/--port skips it.
+// Reads stay unguarded (viewer-points-anywhere). Guarding HERE (not per cli.ts branch) covers every caller.
+const guarded = (verb: string) => assertProjectMatch(`spex ${verb}`)
 const post = (body: unknown): RequestInit => ({ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
 const seg = (id: string) => encodeURIComponent(id)
 
@@ -43,6 +49,7 @@ export async function clientCapture(id: string): Promise<CaptureResult> {
 // POST /api/sessions/:id/keys — prompt dispatch (the backend routes it through the rendezvous socket,
 // socket-only + fail-loud; a non-accepted prompt comes back ok:false / HTTP 502).
 export async function clientSend(id: string, text: string, from?: string): Promise<DispatchResult> {
+  await guarded('session send')
   // `from` = the sending agent's own session id; the backend logs the comms edge ([[comms-edge]]) only when
   // it's present (an agent send), so a human-shell send stays unrecorded.
   const r = await apiFetch(`/api/sessions/${seg(id)}/keys`, post({ text, ...(from ? { from } : {}) }))
@@ -57,10 +64,10 @@ export async function clientReview(id: string): Promise<ReviewPayload | null> {
   return await r.json() as ReviewPayload
 }
 
-// GET /api/sessions/:id/proof — the rendered review PROOF ([[review-proof]]): the self-contained HTML the
-// backend builds (default), or the model JSON (`json:true` → ?format=json). The engine runs on the backend,
-// so the CLI is a thin fetcher that writes/opens these bytes — works against a remote backend unchanged.
-// 404 → no such session.
+// GET /api/sessions/:id/proof — the rendered proof EXPORT artifact ([[review-proof]]): the self-contained
+// HTML the backend builds (default), or the model JSON (`json:true` → ?format=json). The engine runs on the
+// backend, so the CLI is a thin fetcher that writes/opens these bytes — works against a remote backend
+// unchanged. 404 → no such session.
 export type ProofResult = { ok: true; body: string } | { ok: false; status: number }
 export async function clientProof(id: string, json = false): Promise<ProofResult> {
   const r = await apiFetch(`/api/sessions/${seg(id)}/proof${json ? '?format=json' : ''}`)
@@ -68,8 +75,19 @@ export async function clientProof(id: string, json = false): Promise<ProofResult
   return { ok: false, status: r.status }
 }
 
+// GET /api/sessions/:id/evals — the session EVAL model ([[review-proof]]'s interactive face): the changed
+// nodes' worktree-rooted reading rows (each carrying `inSession`), no diff enrichment, no inlined evidence
+// bytes — what `spex eval` renders, the dashboard Eval tab's source. 404 → no such session.
+export type EvalsResult = { ok: true; model: SessionEvals } | { ok: false; status: number }
+export async function clientEvals(id: string): Promise<EvalsResult> {
+  const r = await apiFetch(`/api/sessions/${seg(id)}/evals`)
+  if (!r.ok) return { ok: false, status: r.status }
+  return { ok: true, model: await r.json() as SessionEvals }
+}
+
 // POST /api/sessions/:id/merge — the cockpit's merge DISPATCH (200 {dispatched:true} / 409 {reason}).
 export async function clientMerge(id: string): Promise<{ dispatched: boolean; reason?: string }> {
+  await guarded('merge')
   const r = await apiFetch(`/api/sessions/${seg(id)}/merge`, post({}))
   return await r.json().catch(() => ({ dispatched: false, reason: `bad backend response (${r.status})` }))
 }
@@ -78,6 +96,7 @@ export async function clientMerge(id: string): Promise<{ dispatched: boolean; re
 // 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 }> {
+  await guarded('session reopen')
   const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({ force }))
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }))
 }
@@ -85,16 +104,35 @@ export async function clientReopen(id: string, force = false): Promise<{ ok: boo
 // POST /api/sessions/:id/exit — the soft stop: kill tmux + socket, KEEP the worktree (session goes offline,
 // resumable). Distinct from close. {ok:false} = no such session.
 export async function clientExit(id: string): Promise<boolean> {
+  await guarded('session exit')
   const r = await apiFetch(`/api/sessions/${seg(id)}/exit`, post({}))
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
 // POST /api/sessions/:id/close — the human-only worktree removal. {ok:false} = no such session.
 export async function clientClose(id: string): Promise<boolean> {
+  await guarded('session close')
   const r = await apiFetch(`/api/sessions/${seg(id)}/close`, post({}))
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
+// POST /api/sessions/:id/rename — set (or clear, with a blank) the session's display-name override
+// ([[session-rename]] as a CLI verb). {ok:false} = no such session (404).
+export async function clientRename(id: string, name: string): Promise<boolean> {
+  await guarded('session rename')
+  const r = await apiFetch(`/api/sessions/${seg(id)}/rename`, post({ name }))
+  return !!(await r.json().catch(() => ({ ok: false })))?.ok
+}
+
+// POST /api/sessions/:id/rawkey — the raw nav-key channel (tmux send-keys, NEVER the prompt socket): an
+// ordered token batch drives an interactive TUI menu ([[nav-mode-key-ordering]]). {ok:false} = unknown
+// session, no live pane, or no valid token delivered.
+export async function clientRawkey(id: string, keys: string[]): Promise<boolean> {
+  await guarded('session rawkey')
+  const r = await apiFetch(`/api/sessions/${seg(id)}/rawkey`, post({ keys }))
+  return !!(await r.json().catch(() => ({ ok: false })))?.ok
+}
+
 // GET /api/sessions/:id/prompt — the session's originating prompt (404 if none recorded).
 export type PromptResult = { ok: true; prompt: string } | { ok: false; status: number }
 export async function clientPrompt(id: string): Promise<PromptResult> {