spexcode 0.5.1 → 0.5.3

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

@@ -1,17 +1,24 @@
-import { appendFileSync, mkdirSync, rmSync } from 'node:fs'
-import { createConnection, createServer, type Server, type Socket } from 'node:net'
+import { rmSync } from 'node:fs'
+import { 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'
+import { controlRequest, withTimeout } from './headless-controller.js'
+import { shQuote } from './sh.js'
 
-type ControlRequest = { type: 'deliver'; text: string } | { type: 'interrupt' }
+type ControlRequest = { type: 'deliver'; text: string; mode: 'steer' | 'wake' } | { type: 'interrupt' }
+type ClaudeHeadlessDeliveryRecord = HarnessDeliveryRecord & { status?: string }
 type ChildTurn = {
   process: ChildProcessWithoutNullStreams
   active: boolean
+  completed: boolean
   exited: Promise<number | null>
+  teardown: Promise<void> | null
+  result: Promise<void>
+  sawResult: () => void
   firstEvent: Promise<void>
   sawFirstEvent: () => void
   interruptAcks: Map<string, () => void>
@@ -19,11 +26,14 @@ type ChildTurn = {
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))
 const SPEX = join(PKG, 'bin', 'spex.mjs')
-const CONTROL_TIMEOUT_MS = 30_000
+const CONTROL_TIMEOUT_MS = 60_000
 const START_TIMEOUT_MS = 30_000
 const INTERRUPT_TIMEOUT_MS = 10_000
+const RESULT_WAIT_MS = 20_000
+const RESULT_EXIT_GRACE_MS = 500
+const TERM_EXIT_GRACE_MS = 500
+const KILL_EXIT_GRACE_MS = 2_000
 
-const shQuote = (s: string) => `'${s.replace(/'/g, `'\''`)}'`
 const userEvent = (text: string) => JSON.stringify({
   type: 'user',
   message: { role: 'user', content: [{ type: 'text', text }] },
@@ -35,70 +45,31 @@ export function claudeHeadlessLaunchCommand(id: string, runtimeDir: string, clau
   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) },
-    )
+export const deliverViaClaudeHeadless = (rec: ClaudeHeadlessDeliveryRecord, text: string) =>
+  controlRequest(claudeHeadlessSock(rec.session), { type: 'deliver', text, mode: rec.status === 'active' ? 'steer' : 'wake' }, {
+    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'claude-headless control rejected the request',
   })
-}
-
-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' })
+  controlRequest(claudeHeadlessSock(rec.session), { type: 'interrupt' }, {
+    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'claude-headless control rejected the request',
+  })
 
 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,
+    _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)
   }
 
@@ -121,12 +92,15 @@ export class ClaudeHeadlessController {
     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 */ }
+    try {
+      if (child) await this.ensureTurnExit(child)
+    } finally {
+      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 {
@@ -157,11 +131,17 @@ export class ClaudeHeadlessController {
     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) {
+      if (request.mode === 'steer' && 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')
+      if (current?.active) {
+        await Promise.race([
+          withTimeout(current.result, RESULT_WAIT_MS, 'previous claude-headless turn did not reach its result before idle wake'),
+          current.exited.then((code) => { throw new Error(`previous claude-headless turn exited before its result (code ${code ?? 'signal'})`) }),
+        ])
+      }
+      if (current) await this.ensureTurnExit(current)
       await this.spawnTurn(request.text, true)
       return { ok: true }
     }
@@ -192,12 +172,30 @@ export class ClaudeHeadlessController {
     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'] })
+    const childProcess = spawn('/bin/sh', ['-lc', command], {
+      cwd: this.cwd,
+      env: process.env,
+      detached: true,
+      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() }
+    let sawResult!: () => void
+    const result = new Promise<void>((resolve) => { sawResult = resolve })
+    const turn: ChildTurn = {
+      process: childProcess,
+      active: true,
+      completed: false,
+      exited,
+      teardown: null,
+      result,
+      sawResult,
+      firstEvent,
+      sawFirstEvent,
+      interruptAcks: new Map(),
+    }
     this.child = turn
     let stdoutBuffer = ''
     childProcess.stdout.setEncoding('utf8')
@@ -210,7 +208,6 @@ export class ClaudeHeadlessController {
         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)
@@ -224,6 +221,9 @@ export class ClaudeHeadlessController {
       if (stdoutBuffer) console.error('[spex claude-headless] dropped a partial non-line stdout event')
       if (this.child === turn) this.child = null
       resolveExit(code)
+      if (!turn.completed && code !== 0 && !this.closing) {
+        void import('./harness.js').then(({ reportHeadlessTurnExit }) => reportHeadlessTurnExit(this.id, 'claude-headless', code, this.cwd))
+      }
     })
     await this.writeLine(turn, userEvent(text))
     await Promise.race([
@@ -238,9 +238,59 @@ export class ClaudeHeadlessController {
     if (event?.type === 'control_response' && typeof event?.response?.request_id === 'string') {
       turn.interruptAcks.get(event.response.request_id)?.()
     }
-    if (event?.type === 'result') {
+    if (event?.type === 'result' && !turn.completed) {
+      turn.completed = true
       turn.active = false
-      turn.process.stdin.end()
+      turn.sawResult()
+      void this.ensureTurnExit(turn).catch((error) => {
+        console.error(`[spex claude-headless] completed turn teardown failed: ${(error as Error).message}`)
+      })
+    }
+  }
+
+  private ensureTurnExit(turn: ChildTurn): Promise<void> {
+    turn.teardown ??= this.terminateTurn(turn)
+    return turn.teardown
+  }
+
+  private async terminateTurn(turn: ChildTurn): Promise<void> {
+    if (turn.completed) {
+      if (turn.process.stdin.writable) turn.process.stdin.end()
+      if (await this.waitForTurnExit(turn, RESULT_EXIT_GRACE_MS)) return
+      this.signalTurn(turn, 'SIGKILL')
+      await withTimeout(
+        turn.exited,
+        KILL_EXIT_GRACE_MS,
+        `claude-headless completed turn process group ${turn.process.pid ?? 'unknown'} did not exit after SIGKILL`,
+      )
+      return
+    }
+    this.signalTurn(turn, 'SIGTERM')
+    if (await this.waitForTurnExit(turn, TERM_EXIT_GRACE_MS)) return
+    this.signalTurn(turn, 'SIGKILL')
+    await withTimeout(
+      turn.exited,
+      KILL_EXIT_GRACE_MS,
+      `claude-headless turn process group ${turn.process.pid ?? 'unknown'} did not exit after SIGKILL`,
+    )
+  }
+
+  private async waitForTurnExit(turn: ChildTurn, timeoutMs: number): Promise<boolean> {
+    try {
+      await withTimeout(turn.exited, timeoutMs, 'turn exit grace elapsed')
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  private signalTurn(turn: ChildTurn, signal: NodeJS.Signals): void {
+    const pid = turn.process.pid
+    try {
+      if (pid) process.kill(-pid, signal)
+      else turn.process.kill(signal)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error
     }
   }