spexcode 0.4.3 → 0.5.0

package/README.md

@@ -82,7 +82,7 @@ Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
 ```sh
 npm i -g spexcode                              # installs the `spex` command
 cd your-repo
-spex init --harness claude,codex,opencode,pi   # seeds .spec/, installs hooks, materializes the agent contracts
+spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless   # seeds .spec/, installs hooks, materializes the agent contracts
 ```
 
 That's the whole adoption. The example lists all the built-in harnesses — remove the ones you don't

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

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

@@ -786,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}`)
@@ -868,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)
     }
   }
@@ -938,6 +943,24 @@ if (cmd === 'serve') {
     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

@@ -132,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')

package/spec-cli/src/guide.ts

@@ -14,7 +14,7 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    startup commands.)
 
 2. Adopt a repo
-     cd <your-repo> && spex init --harness claude,codex,opencode,pi   # seeds .spec/ + git hooks (additive, never overwrites)
+     cd <your-repo> && spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless   # seeds .spec/ + git hooks (additive, never overwrites)
    --harness is required and has no default — the explicit choice of which harness(es) materialize
    delivers into. The example lists every built-in; drop the ones you don't use (any one id or
    comma-separated subset is valid).
@@ -259,14 +259,14 @@ settings verb — an agent CONFIGURES SpexCode by EDITING these files directly.
 PORTABILITY, and picking the right one is the whole discipline:
 
   spexcode.json         COMMITTED — portable, shared by everyone on the repo. Layout, policy, dashboard
-                        identity, lint policy, doctor health budgets, launcher NAMES. "Git is the database": tracked so the
+                        identity and launcher visibility, lint policy, doctor health budgets, launcher NAMES. "Git is the database": tracked so the
                         team shares ONE configuration.
   spexcode.local.json   GITIGNORED — host-specific, never committed. Absolute launcher paths, cert/secret
                         paths. Layered OVER spexcode.json (see MERGE
                         below); a targeted env override (SPEXCODE_CODEX_SERVER_CMD, …) still wins at its read site.
 
 Rule of thumb — is the value TRUE FOR THE PROJECT or TRUE FOR THIS MACHINE? A branch name, a dashboard
-icon, lint policy, doctor health budgets, and a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
+icon or launcher-visibility policy, lint policy, doctor health budgets, and a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
 PATH of a launcher wrapper or a TLS cert path are machine facts → gitignored spexcode.local.json.
 Both files are optional; omit any field to take its default, except \`sessions.defaultLauncher\` when using
 \`spex session new\` or the dashboard without an explicit launcher choice.
@@ -296,8 +296,13 @@ Example — a repo whose trunk is \`staging\`, not \`main\`:
   dashboard.apiUrl  the per-project backend the dashboard proxies to (read frontend-side). For a SHARED
                     install prefer the API_URL env var; apiUrl here is the default only when the dashboard
                     lives inside the project.
+  dashboard.showHeadlessLaunchers
+                    include launchers whose harness declares itself headless in the dashboard New Session
+                    picker. Default: false. This changes dashboard visibility only; explicit CLI
+                    --launcher selection can still use every configured launcher.
 Example:
-  { "dashboard": { "title": "MyApp specs", "icon": "mdi:rocket-launch" } }
+  { "dashboard": { "title": "MyApp specs", "icon": "mdi:rocket-launch",
+                   "showHeadlessLaunchers": false } }
 
 ── HOST GATEWAY ($SPEXCODE_HOME/config.json — per-user host identity, never a project file) ──
   gateway.icon      the global /projects icon, using the same preset ids above. Default: "gateway".
@@ -326,16 +331,20 @@ by name with --launcher/the dashboard dropdown, and the chosen name is persisted
 reuses the same auth. There are NO magic built-ins: \`spex init\` SEEDS an ordinary named launcher for each
 harness the adopter SELECTED (--harness), from the template pool
   "claude"   → { "harness": "claude",   "cmd": "claude" }
+  "claude-headless" → { "harness": "claude-headless", "cmd": "claude" }
   "codex"    → { "harness": "codex",    "cmd": "codex" }
   "opencode" → { "harness": "opencode", "cmd": "opencode" }
+  "opencode-headless" → { "harness": "opencode-headless", "cmd": "opencode --auto" }
   "pi"       → { "harness": "pi",       "cmd": "pi" }
-These plain commands preserve each harness's normal permission model. Automatic-permission commands such as
-\`claude --dangerously-skip-permissions\`, \`codex --yolo\`, or \`opencode --auto\` are NEVER clean-init
-defaults: define and select one explicitly only when that access is intended. To run workers under an auth
+  "pi-headless" → { "harness": "pi-headless", "cmd": "pi" }
+The interactive profiles preserve each harness's normal permission model. \`opencode-headless\` is the one
+deliberate seed exception: its terminal-free run requires \`opencode --auto\`; interactive \`opencode\` stays
+plain. Other automatic-permission commands are NEVER clean-init defaults: define and select one explicitly
+only when that access is intended. To run workers under an auth
 wrapper (e.g. reclaude), point a launcher's \`cmd\` at it in spexcode.local.json — there is no environment
 override that rewrites a launcher's command. Add more profiles when a project needs named auth/config-dir or
 permission variants. Shape:
-  "launchers": { "<name>": { "harness": "claude" | "codex" | "opencode" | "pi",
+  "launchers": { "<name>": { "harness": "claude" | "codex" | "opencode" | "pi" | "claude-headless" | "opencode-headless" | "pi-headless",
                              "cmd": "<launch command>" } }
 \`harness\` defaults to "claude"; \`cmd\` is required and embedded whole. A portable plain command may live
 in committed spexcode.json (as the init seeds do). A host-specific command — an absolute wrapper path,
@@ -444,7 +453,7 @@ Example — tune opt-in health diagnosis without changing the lint gate:
   preset      the SELECTED init preset — which cumulative .plugins tier \`spex init\` seeds (default
               'default'; seed-time only, read by init.ts).
   harnesses   which harness targets \`spex materialize\` delivers into — native ids
-              ("claude"|"codex"|"opencode"|"pi") or a
+              ("claude"|"codex"|"opencode"|"pi"|"claude-headless"|"opencode-headless"|"pi-headless") or a
               { "plugin": "<folder>" } bundle. REQUIRED — there is no default set: \`spex init --harness\`
               stamps the explicit choice, and a missing field fails materialize loud. PERSISTENT and
               git-transactional: the edit takes effect at the next git-native materialize anchor (the commit