spexcode 0.4.1 → 0.5.0

package/spec-cli/src/claude-headless.ts

@@ -0,0 +1,271 @@
+import { appendFileSync, mkdirSync, rmSync } from 'node:fs'
+import { createConnection, createServer, type Server, type Socket } from 'node:net'
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+
+type ControlRequest = { type: 'deliver'; text: string } | { type: 'interrupt' }
+type ChildTurn = {
+  process: ChildProcessWithoutNullStreams
+  active: boolean
+  exited: Promise<number | null>
+  firstEvent: Promise<void>
+  sawFirstEvent: () => void
+  interruptAcks: Map<string, () => void>
+}
+
+const PKG = fileURLToPath(new URL('..', import.meta.url))
+const SPEX = join(PKG, 'bin', 'spex.mjs')
+const CONTROL_TIMEOUT_MS = 30_000
+const START_TIMEOUT_MS = 30_000
+const INTERRUPT_TIMEOUT_MS = 10_000
+
+const shQuote = (s: string) => `'${s.replace(/'/g, `'\''`)}'`
+const userEvent = (text: string) => JSON.stringify({
+  type: 'user',
+  message: { role: 'user', content: [{ type: 'text', text }] },
+})
+
+export const claudeHeadlessSock = (id: string) => join(tmpdir(), `spexcode-ch-${id}.sock`)
+
+export function claudeHeadlessLaunchCommand(id: string, runtimeDir: string, claudeCmd: string): string {
+  return [shQuote(SPEX), 'internal', 'claude-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(claudeCmd), '--'].join(' ')
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms)
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value) },
+      (error) => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+function controlRequest(id: string, request: ControlRequest): Promise<DispatchResult> {
+  return new Promise((resolve) => {
+    const socket = createConnection(claudeHeadlessSock(id))
+    let buffer = ''
+    let settled = false
+    const finish = (result: DispatchResult) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      socket.destroy()
+      resolve(result)
+    }
+    const timer = setTimeout(() => finish({ ok: false, error: `claude-headless control timed out for session ${id}` }), CONTROL_TIMEOUT_MS)
+    socket.setEncoding('utf8')
+    socket.on('connect', () => socket.write(`${JSON.stringify(request)}\n`))
+    socket.on('data', (chunk) => {
+      buffer += chunk
+      const nl = buffer.indexOf('\n')
+      if (nl < 0) return
+      try {
+        const response = JSON.parse(buffer.slice(0, nl)) as DispatchResult
+        finish(response.ok ? { ok: true } : { ok: false, error: response.error || 'claude-headless control rejected the request' })
+      } catch (error) {
+        finish({ ok: false, error: `claude-headless returned an invalid control response: ${(error as Error).message}` })
+      }
+    })
+    socket.on('error', (error) => finish({ ok: false, error: `claude-headless controller unreachable for session ${id}: ${error.message}` }))
+    socket.on('close', () => finish({ ok: false, error: `claude-headless controller closed before confirming session ${id}` }))
+  })
+}
+
+export const deliverViaClaudeHeadless = (rec: HarnessDeliveryRecord, text: string) =>
+  controlRequest(rec.session, { type: 'deliver', text })
+
+export const interruptClaudeHeadless = (rec: HarnessDeliveryRecord) =>
+  controlRequest(rec.session, { type: 'interrupt' })
+
+export class ClaudeHeadlessController {
+  private server: Server | null = null
+  private child: ChildTurn | null = null
+  private controlQueue: Promise<void> = Promise.resolve()
+  private closing = false
+  private readonly messagesPath: string
+  private readonly socketPath: string
+
+  constructor(
+    private readonly id: string,
+    runtimeDir: string,
+    private readonly claudeCmd: string,
+    private readonly cwd = process.cwd(),
+  ) {
+    const dir = join(runtimeDir, 'sessions', id)
+    mkdirSync(dir, { recursive: true })
+    this.messagesPath = join(dir, 'messages.ndjson')
+    this.socketPath = claudeHeadlessSock(id)
+  }
+
+  async start(initialPrompt?: string): Promise<void> {
+    try { rmSync(this.socketPath, { force: true }) } catch { /* stale control socket is replaced at startup */ }
+    this.server = createServer((socket) => this.accept(socket))
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error) => { this.server?.off('listening', onListening); reject(error) }
+      const onListening = () => { this.server?.off('error', onError); resolve() }
+      this.server!.once('error', onError)
+      this.server!.once('listening', onListening)
+      this.server!.listen(this.socketPath)
+    })
+    if (initialPrompt) void this.spawnTurn(initialPrompt, false).catch((error) => {
+      console.error(`[spex claude-headless] initial turn failed: ${(error as Error).message}`)
+    })
+  }
+
+  async close(): Promise<void> {
+    if (this.closing) return
+    this.closing = true
+    const child = this.child
+    if (child && child.process.exitCode === null) child.process.kill('SIGTERM')
+    await new Promise<void>((resolve) => {
+      if (!this.server) return resolve()
+      this.server.close(() => resolve())
+    })
+    try { rmSync(this.socketPath, { force: true }) } catch { /* best-effort cleanup after close */ }
+  }
+
+  private accept(socket: Socket): void {
+    socket.setEncoding('utf8')
+    let buffer = ''
+    let handled = false
+    socket.on('data', (chunk) => {
+      if (handled) return
+      buffer += chunk
+      const nl = buffer.indexOf('\n')
+      if (nl < 0) return
+      handled = true
+      let request: ControlRequest
+      try {
+        request = JSON.parse(buffer.slice(0, nl)) as ControlRequest
+      } catch (error) {
+        socket.end(`${JSON.stringify({ ok: false, error: `invalid control request: ${(error as Error).message}` })}\n`)
+        return
+      }
+      this.controlQueue = this.controlQueue.then(async () => {
+        const result = await this.handle(request).catch((error) => ({ ok: false, error: (error as Error).message }))
+        socket.end(`${JSON.stringify(result)}\n`)
+      })
+    })
+  }
+
+  private async handle(request: ControlRequest): Promise<DispatchResult> {
+    if (request.type === 'deliver') {
+      if (!request.text) return { ok: false, error: 'empty prompt - nothing to deliver' }
+      const current = this.child
+      if (current?.active && current.process.stdin.writable) {
+        await this.writeLine(current, userEvent(request.text))
+        return { ok: true }
+      }
+      if (current) await withTimeout(current.exited, 5_000, 'previous claude-headless turn did not exit after its result')
+      await this.spawnTurn(request.text, true)
+      return { ok: true }
+    }
+    if (request.type === 'interrupt') return this.interrupt()
+    return { ok: false, error: 'unknown claude-headless control request' }
+  }
+
+  private async interrupt(): Promise<DispatchResult> {
+    const child = this.child
+    if (!child?.active || !child.process.stdin.writable) return { ok: true }
+    const requestId = randomUUID()
+    const ack = new Promise<void>((resolve) => child.interruptAcks.set(requestId, resolve))
+    await this.writeLine(child, JSON.stringify({
+      type: 'control_request',
+      request_id: requestId,
+      request: { subtype: 'interrupt' },
+    }))
+    try {
+      await withTimeout(ack, INTERRUPT_TIMEOUT_MS, `claude-headless interrupt was not confirmed for session ${this.id}`)
+      return { ok: true }
+    } finally {
+      child.interruptAcks.delete(requestId)
+    }
+  }
+
+  private async spawnTurn(text: string, resume: boolean): Promise<void> {
+    if (this.closing) throw new Error('claude-headless controller is closing')
+    const mode = resume ? ['--resume', this.id] : ['--session-id', this.id]
+    const args = ['-p', ...mode, '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose']
+    const command = `exec ${this.claudeCmd} ${args.map(shQuote).join(' ')}`
+    const childProcess = spawn('/bin/sh', ['-lc', command], { cwd: this.cwd, env: process.env, stdio: ['pipe', 'pipe', 'pipe'] })
+    let sawFirstEvent!: () => void
+    const firstEvent = new Promise<void>((resolve) => { sawFirstEvent = resolve })
+    let resolveExit!: (code: number | null) => void
+    const exited = new Promise<number | null>((resolve) => { resolveExit = resolve })
+    const turn: ChildTurn = { process: childProcess, active: true, exited, firstEvent, sawFirstEvent, interruptAcks: new Map() }
+    this.child = turn
+    let stdoutBuffer = ''
+    childProcess.stdout.setEncoding('utf8')
+    childProcess.stderr.pipe(process.stderr)
+    childProcess.stdout.on('data', (chunk) => {
+      stdoutBuffer += chunk
+      for (;;) {
+        const nl = stdoutBuffer.indexOf('\n')
+        if (nl < 0) break
+        const line = stdoutBuffer.slice(0, nl)
+        stdoutBuffer = stdoutBuffer.slice(nl + 1)
+        const nativeLine = `${line}\n`
+        appendFileSync(this.messagesPath, nativeLine)
+        globalThis.process.stdout.write(nativeLine)
+        turn.sawFirstEvent()
+        this.observeEvent(turn, line)
+      }
+    })
+    childProcess.once('error', (error) => {
+      console.error(`[spex claude-headless] child spawn failed: ${error.message}`)
+    })
+    childProcess.once('close', (code) => {
+      turn.active = false
+      if (stdoutBuffer) console.error('[spex claude-headless] dropped a partial non-line stdout event')
+      if (this.child === turn) this.child = null
+      resolveExit(code)
+    })
+    await this.writeLine(turn, userEvent(text))
+    await Promise.race([
+      withTimeout(turn.firstEvent, START_TIMEOUT_MS, `claude-headless child produced no stream event for session ${this.id}`),
+      turn.exited.then((code) => { throw new Error(`claude-headless child exited before accepting the turn (code ${code ?? 'signal'})`) }),
+    ])
+  }
+
+  private observeEvent(turn: ChildTurn, line: string): void {
+    let event: any
+    try { event = JSON.parse(line) } catch { return }
+    if (event?.type === 'control_response' && typeof event?.response?.request_id === 'string') {
+      turn.interruptAcks.get(event.response.request_id)?.()
+    }
+    if (event?.type === 'result') {
+      turn.active = false
+      turn.process.stdin.end()
+    }
+  }
+
+  private writeLine(turn: ChildTurn, line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!turn.process.stdin.writable) return reject(new Error('claude-headless child stdin is not writable'))
+      turn.process.stdin.write(`${line}\n`, (error) => error ? reject(error) : resolve())
+    })
+  }
+}
+
+export async function runClaudeHeadlessController(
+  id: string,
+  runtimeDir: string,
+  claudeCmd: string,
+  tail: string[],
+): Promise<void> {
+  const controller = new ClaudeHeadlessController(id, runtimeDir, claudeCmd)
+  const resume = tail[0] === '--resume'
+  const prompt = resume ? undefined : tail[0] === '--session-id' ? tail.slice(2).join(' ') : tail.join(' ')
+  await controller.start(prompt)
+  await new Promise<void>((resolve) => {
+    const stop = () => void controller.close().finally(resolve)
+    process.once('SIGINT', stop)
+    process.once('SIGTERM', stop)
+    process.once('SIGHUP', stop)
+  })
+}

package/spec-cli/src/cli.ts

@@ -1,6 +1,6 @@
 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 (spec owner, session new, graph) — a CLI reference arg tolerates an optional @/[[ ]]
+// by several verbs (spec owner, graph, issue/eval node args) — a CLI reference arg tolerates an optional @/[[ ]]
 // sigil ([[mentions]]).
 import { stripRefSigil } from './mentions.js'
 
@@ -60,6 +60,19 @@ function positionals(from: number): string[] {
   return out
 }
 
+function rejectUnknownFlags(command: string, from: number, allowed: readonly string[]): void {
+  const known = new Set(allowed.map((name) => `--${name}`))
+  for (let i = from; i < process.argv.length; i++) {
+    const token = process.argv[i]
+    if (!token.startsWith('--')) continue
+    if (!known.has(token)) {
+      console.error(`${command}: unknown flag ${token}`)
+      process.exit(2)
+    }
+    if (VALUE_FLAGS.has(token)) i++
+  }
+}
+
 // @@@ signposts (one version only — delete in 0.4.0) - every spelling v0.3.0 removed maps to its new home.
 // A signpost REPORTS and exits 2; it never executes (not an alias): a stale hook or a human's muscle memory
 // gets a readable failure that names the migration, and nothing old keeps silently working.
@@ -73,7 +86,6 @@ const SIGNPOSTS: Record<string, string> = {
   blob: 'spex evidence put|get',
   issues: 'spex issue — ls (was: bare issues) · show · open · reply · close · promote; on|off|status → the `issues.enabled` key in spexcode.json; `issues nudge` → spex internal nudge',
   forge: 'spex issue links [--pending] [--store <host>]  (--host is now --store)',
-  dashboard: 'spex serve ui',
   new: 'spex session new',
   ls: 'spex session ls',
   watch: 'spex session watch',
@@ -173,7 +185,7 @@ 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) }
+  if (!selector) { console.error('spex: missing session selector (id | id-prefix | node | branch | . for self)'); process.exit(2) }
   const { resolveClientSession } = await import('./client.js')
   const { sessionLabel } = await import('./sessions.js')
   const r = await resolveClientSession(selector)
@@ -309,6 +321,19 @@ if (cmd === 'serve') {
     console.error(`spex serve: unknown target '${target}' — spex serve [api] (the backend) | spex serve ui (the dashboard)`)
     process.exit(2)
   }
+} else if (cmd === 'dashboard') {
+  // the HOST-level dashboard ([[host-gateway]]): ONE gateway for every project this user serves. The
+  // engine is [[gateway-hub]] (routing + [[gateway-auth]] authorization: admin scope implicit from
+  // loopback until an admin password is set; per-project gates as configured); the host layer mounts the
+  // instance-validated project registry, its SSE stream, the durable catalog, and the /projects
+  // operations (register · init · doctor · start a backend) as the hub's admin extension. No --api-port
+  // pairing: which backend a request reaches is named in its /p/:projectId path, resolved per request.
+  // `spex serve ui` remains the explicit one-backend pairing; this verb is the zero-config many-project face.
+  const { startHostDashboard } = await import('./host.js')
+  const port = Number(flag('port') ?? process.env.SPEXCODE_DASHBOARD_PORT ?? 5173)
+  const host = flag('host') ?? '127.0.0.1'
+  if (!Number.isInteger(port)) { console.error('spex dashboard: --port must be an integer'); process.exit(2) }
+  startHostDashboard({ port, host })
 } else if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   // `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')
@@ -467,9 +492,9 @@ if (cmd === 'serve') {
   }
 } else if (cmd === 'init') {
   // scaffold a repo to adopt SpexCode: copy the shipped DATA templates (seed spec tree + git hooks)
-  // into <targetDir> (default cwd). spex init [targetDir] [--preset <tier>]
+  // into <targetDir> (default cwd). spex init [targetDir] --harness <ids> [--preset <tier>]
   const { specInit } = await import('./init.js')
-  await specInit(positionals(3)[0], flag('preset'))
+  await specInit(positionals(3)[0], flag('preset'), flag('harness'))
 } 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/.plugins data or their own
@@ -497,42 +522,35 @@ if (cmd === 'serve') {
     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`)
+    const byNode = new Map<string, any[]>()
+    for (const item of m.items) {
+      const rows = byNode.get(item.node) ?? []
+      rows.push(item)
+      byNode.set(item.node, rows)
+    }
+    const groups = [...byNode].map(([node, rows]) => ({ node, rows }))
+    const own = m.items.filter((item) => item.inSession).length
+    console.log(`eval session  [${m.id}]`)
     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 eval.md — a blind spot: give it a scenario' : ''}`)
-      for (const s of blind) console.log(`      ∅ unmeasured  ${s.name}  — declared, never measured (blind spot)`)
+    if (!m.items.length) console.log('\n  no affected scenarios to evaluate yet')
+    for (const { node, rows } of groups) {
+      console.log(`\n${node}`)
+      for (const item of rows.filter((row) => row.filterKind === 'blind')) console.log(`      ∅ unmeasured  ${item.scenario}  — 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 evals) ──`); divided = true }
+      for (const e of rows.filter((row) => row.filterKind === 'result')) {
+        if (!e.inSession && !divided && rows.some((x) => x.filterKind === 'result' && x.inSession)) { console.log(`      ── inherited baseline (other sessions' latest evals) ──`); divided = true }
         const verdict = e.verdict?.status === 'pass' ? '✓ pass' : e.verdict?.status === 'fail' ? '✗ fail' : '· unscored'
-        const stale = e.fresh ? '' : ` (stale: ${e.staleAxes.join(',')})`
+        const stale = e.fresh ? '' : ` (stale: ${(e.staleAxes || []).join(',')})`
         console.log(`    ${e.inSession ? '✦' : ' '} ${verdict}${stale}  ${e.scenario}  — ${e.ts}${e.evaluator ? ` · ${e.evaluator}` : ''}`)
       }
-      if (!n.hasEvalFile && !n.uncoveredFrontend) console.log('      (no eval.md — nothing declared to measure)')
-      else if (n.hasEvalFile && !n.scenarios.length) console.log('      (eval.md declares no scenarios)')
     }
-  } else if (['add', 'ls', 'scenario', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
+  } else if (['add', 'ls', 'scenario', 'matrix', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
     // node-scoped verbs — thin route; the logic lives in spec-eval.
     const { runEval } = await import('../../spec-eval/src/cli.js')
     await flushExit(await runEval(process.argv.slice(3)))
   } else {
-    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls | lint | ok | retract | clean  (spex help eval)`)
+    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls | matrix | lint | ok | retract | clean  (spex help eval)`)
     if (!sub.startsWith('--')) console.error(`  (the old \`spex eval <SEL>\` session read is now \`spex eval ls --session <SEL>\` [--export])`) // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
     process.exit(2)
   }
@@ -583,7 +601,14 @@ if (cmd === 'serve') {
   // trust, for cwd's project. Anchored on git-native events only ([[commit-surgery]]): this verb, init,
   // session-worktree creation, and the planted pre-commit/post-checkout/post-merge hooks.
   const { materialize } = await import('./materialize.js')
-  console.log(`materialized — content-hash ${materialize()}`)
+  try {
+    console.log(`materialized — content-hash ${materialize().contentHash}`)
+  } catch (e) {
+    // a policy error (e.g. a missing/illegal `harnesses` set) is a user-facing verdict, not a crash — one
+    // line + the repair it already carries, never a stack trace.
+    console.error(`spex materialize: ${(e as Error).message}`)
+    process.exit(1)
+  }
 } 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
@@ -599,12 +624,16 @@ if (cmd === 'serve') {
   } else if (SESSION_SIGNPOSTS[sub]) {
     signpost(`spex session ${sub}`, SESSION_SIGNPOSTS[sub])
   } else if (sub === 'new') {
-    // spex session new "<prompt>" [--node X]  (prompt = first positional or --prompt, or --prompt-file
+    // spex session new "<prompt>"  (prompt = first positional or --prompt, or --prompt-file
     // <path>|- so a long multi-paragraph prompt never fights shell quoting — [[prompt-file]]).
     // 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.
+    if (has('node')) {
+      console.error('spex session new: --node was removed — put a [[<id>]] mention in the prompt — the first mention binds')
+      process.exit(2)
+    }
+    rejectUnknownFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'api', 'port'])
     const { createSession } = await import('./sessions.js')
-    if (has('harness')) { console.error('spex session new: --harness was removed; use --launcher <name> (for example --launcher codex)'); process.exit(2) }
     const promptFile = flag('prompt-file')
     const inline = flag('prompt') ?? positionals(4)[0]
     let prompt = inline ?? ''
@@ -616,8 +645,7 @@ if (cmd === 'serve') {
       catch (e) { console.error(`spex session new: --prompt-file ${promptFile}: ${e instanceof Error ? e.message : e}`); process.exit(2) }
       if (!prompt.trim()) { console.error(`spex session new: --prompt-file ${promptFile === '-' ? 'stdin' : promptFile} is empty — refusing a promptless launch`); process.exit(2) }
     }
-    const nodeArg = flag('node')
-    const created = await createSession(nodeArg ? stripRefSigil(nodeArg) : null, prompt, flag('launcher') ?? undefined)
+    const created = await createSession(prompt, flag('launcher') ?? undefined)
     console.log(JSON.stringify(created, null, 2))
     await launchMonitorReminder(created.id)
   } else if (sub === 'ls') {
@@ -728,7 +756,7 @@ if (cmd === 'serve') {
       // overrides for a genuinely wedged process. A following prompt is what actually re-drives it.
       const full = await resolveSelectorOrExit(id)
       const r = await c.clientResume(full, process.argv.includes('--force'))
-      if (r.ok) console.log(`${full} -> resumed`)
+      if (r.ok) console.log(r.info ? `${full} -> ${r.info}` : `${full} -> resumed`)
       else { console.error(`spex session resume: ${r.error || `no such session ${full}`}`); process.exit(2) }
     } else if (sub === 'done') {
       // sugar for awaiting; --propose merge|nothing|close, optional --note
@@ -758,6 +786,11 @@ if (cmd === 'serve') {
       // can be resumed (`session resume`). Distinct from `close`, which removes the worktree.
       const full = await resolveSelectorOrExit(id)
       console.log(await c.clientStop(full) ? `stopped ${full} (worktree kept — resumable)` : `no such session ${full}`)
+    } else if (sub === 'interrupt') {
+      const full = await resolveSelectorOrExit(id)
+      const r = await c.clientInterrupt(full)
+      console.log(r.ok ? `interrupted ${full}` : `interrupt failed: ${r.error}`)
+      process.exit(r.ok ? 0 : 1)
     } else if (sub === 'close') {
       const full = await resolveSelectorOrExit(id)
       console.log(await c.clientClose(full) ? `closed ${full}` : `no such session ${full}`)
@@ -840,7 +873,7 @@ if (cmd === 'serve') {
       await assertLocalBackend()
       await attachSession(await resolveSelectorOrExit(id))
     } else {
-      console.error(`spex session: unknown verb '${sub}' — new | ls | show | watch | wait | review | merge | send | rename | resume | stop | close | attach | done | park | ask  (spex help session)`)
+      console.error(`spex session: unknown verb '${sub}' — new | ls | show | watch | wait | review | merge | send | interrupt | rename | resume | stop | close | attach | done | park | ask  (spex help session)`)
       process.exit(2)
     }
   }
@@ -855,6 +888,18 @@ if (cmd === 'serve') {
     // line; GET /api/settings exposes the same resolution (`.layout`).
     const { mainBranch } = await import('./layout.js')
     console.log(mainBranch())
+  } else if (sub === 'spec-governors') {
+    // Stable machine projection for spec-aware hooks: one real code: governor per row, with the live spec
+    // path the block reason can point at. Empty stdout means ungoverned (including related-only).
+    const file = process.argv[4]
+    if (!file) { console.error('usage: spex internal spec-governors <path>'); process.exit(2) }
+    const { specOwners, loadSpecsLite } = await import('./specs.js')
+    const paths = new Map(loadSpecsLite().map((node) => [node.id, node.path]))
+    for (const owner of specOwners(file)) {
+      const path = paths.get(owner.id)
+      if (!path) throw new Error(`governor '${owner.id}' has no live spec path`)
+      console.log(`${owner.id}\t${path}`)
+    }
   } 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
@@ -868,7 +913,7 @@ if (cmd === 'serve') {
     // 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 bypassHookTrust = codexSupportsBypassHookTrust(codexBinary(process.env.SPEXCODE_CODEX_CMD || 'codex'))
     const r = await codexStartThread(sock, cwd, bypassHookTrust)
     if (!r.ok) { console.error(r.error); process.exit(1) }
     if (prompt) {
@@ -887,6 +932,35 @@ if (cmd === 'serve') {
     const sid = process.env.SPEXCODE_SESSION_ID
     if (sid) markHarnessSessionId(sid, r.threadId)
     console.log(r.threadId)
+  } else if (sub === 'opencode-capture') {
+    // opencode MINTS its own session id (no launch flag pins it), so the generated plugin's FIRST event calls
+    // this to store that id as harness_session_id on the governed record (SPEXCODE_SESSION_ID from the launch
+    // env, inherited by the opencode process → plugin). That is what lets reopen() resume the SAME
+    // conversation (`--session <id>`). A missing record/env is a clean no-op — a plugin loaded outside a
+    // governed launch has nothing to mark.
+    const { markHarnessSessionId } = await import('./sessions.js')
+    const ocid = process.argv[4]
+    if (!ocid) { console.error('usage: spex internal opencode-capture <opencode-session-id>'); process.exit(2) }
+    const sid = process.env.SPEXCODE_SESSION_ID
+    console.log(sid && markHarnessSessionId(sid, ocid) ? `captured ${ocid}` : 'noop (no governed session record)')
+  } else if (sub === 'claude-headless-run') {
+    const id = process.argv[4], runtimeDir = process.argv[5], claudeCmd = process.argv[6]
+    const divider = process.argv[7]
+    if (!id || !runtimeDir || !claudeCmd || divider !== '--') {
+      console.error('usage: spex internal claude-headless-run <session-id> <runtime-dir> <claude-cmd> -- [--session-id <id> <prompt> | --resume <id>]')
+      process.exit(2)
+    }
+    const { runClaudeHeadlessController } = await import('./claude-headless.js')
+    await runClaudeHeadlessController(id, runtimeDir, claudeCmd, process.argv.slice(8))
+  } else if (sub === 'pi-headless-run') {
+    const id = process.argv[4], runtimeDir = process.argv[5], piCmd = process.argv[6]
+    const divider = process.argv[7]
+    if (!id || !runtimeDir || !piCmd || divider !== '--') {
+      console.error('usage: spex internal pi-headless-run <session-id> <runtime-dir> <pi-cmd> -- [--session-id <id> <prompt> | --session <id>]')
+      process.exit(2)
+    }
+    const { runPiHeadlessController } = await import('./pi-headless.js')
+    await runPiHeadlessController(id, runtimeDir, piCmd, process.argv.slice(8))
   } else if (sub === 'commit-surgery') {
     // the pre-commit footprint anchor ([[commit-surgery]]): unconditional materialize + staged-index repair
     // (strip our sentinel block from staged blobs, unstage HEAD-untracked generated artifacts). Called only

package/spec-cli/src/client.ts

@@ -1,5 +1,4 @@
 import { apiBase, assertProjectMatch, resolveSession, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
-import type { SessionEvals } from '../../spec-eval/src/sessioneval.js'
 
 export class BackendError extends Error {
   constructor(message: string, readonly status?: number) {
@@ -74,15 +73,38 @@ export async function clientEvalExport(id: string): Promise<ExportResult> {
   return { ok: false, status: r.status }
 }
 
-// GET /api/sessions/:id/evals — the session EVAL model ([[session-eval]]'s interactive face, the same
-// route's default JSON representation): 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 }
+// The CLI's explicit aggregate walks the same 25-row pages as the dashboard. No server response contains
+// the full session model; aggregation exists only for this one-shot terminal rendering.
+type SessionEvalPage = {
+  items: any[]
+  page: number
+  pageCount: number
+  total: number
+  gates: any[]
+  unknown: number
+  revision: string
+  summary?: any
+  evalRevision?: any
+}
+export type EvalsResult = { ok: true; model: SessionEvalPage & { id: string } } | { 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 }
+  const q = encodeURIComponent(`is:eval scope:${id}`)
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const items: any[] = []
+    let first: SessionEvalPage | null = null
+    let changed = false
+    for (let page = 1;; page++) {
+      const r = await apiFetch(`/api/evals?q=${q}&page=${page}`)
+      if (!r.ok) return { ok: false, status: r.status }
+      const current = await r.json() as SessionEvalPage
+      first ??= current
+      if (current.revision !== first.revision) { changed = true; break }
+      items.push(...current.items)
+      if (page >= current.pageCount) break
+    }
+    if (!changed) return { ok: true, model: { ...first!, id, items } }
+  }
+  throw new BackendError(`session eval pages changed while reading ${id}; retry the command`)
 }
 
 // POST /api/sessions/:id/merge — the cockpit's merge DISPATCH (200 {dispatched:true} / 409 {reason}).
@@ -94,8 +116,9 @@ export async function clientMerge(id: string): Promise<{ dispatched: boolean; re
 
 // 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 clientResume(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean }> {
+// `force` overrides for a wedged-but-alive process. {ok:false} otherwise = no such session (404). `info`
+// carries a non-error advisory.
+export async function clientResume(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean; info?: string }> {
   await guarded('session resume')
   const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({ force }))
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }))
@@ -109,6 +132,14 @@ export async function clientStop(id: string): Promise<boolean> {
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
+// POST /api/sessions/:id/interrupt - native hard interrupt of the current turn. Unsupported harnesses and
+// unreachable control planes return the backend's loud DispatchResult; no signal/raw-key fallback exists.
+export async function clientInterrupt(id: string): Promise<DispatchResult> {
+  await guarded('session interrupt')
+  const r = await apiFetch(`/api/sessions/${seg(id)}/interrupt`, post({}))
+  return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` })) as DispatchResult
+}
+
 // 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')