spexcode 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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

@@ -7,11 +7,16 @@ 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 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,9 +24,13 @@ 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({
@@ -76,8 +85,8 @@ function controlRequest(id: string, request: ControlRequest): Promise<DispatchRe
   })
 }
 
-export const deliverViaClaudeHeadless = (rec: HarnessDeliveryRecord, text: string) =>
-  controlRequest(rec.session, { type: 'deliver', text })
+export const deliverViaClaudeHeadless = (rec: ClaudeHeadlessDeliveryRecord, text: string) =>
+  controlRequest(rec.session, { type: 'deliver', text, mode: rec.status === 'active' ? 'steer' : 'wake' })
 
 export const interruptClaudeHeadless = (rec: HarnessDeliveryRecord) =>
   controlRequest(rec.session, { type: 'interrupt' })
@@ -121,12 +130,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 +169,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 +210,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')
@@ -224,6 +260,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 +277,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
     }
   }
 

package/spec-cli/src/cli.ts

@@ -216,8 +216,9 @@ async function evalExport(id: string): Promise<never> {
   process.exit(0)
 }
 
-// appended to a done/ask/block declaration: states (not commands) that the next tool call's mark-active hook re-flips the global record to active, so a re-read won't show this.
-const DECLARED = ' — recorded; the human sees it in the dashboard. This state lives in your session\'s global record; your next tool call flips that record back to active (the mark-active hook, by design), so it is normal for this declaration not to persist.'
+// appended to a done/ask/block declaration: the note is durable conversation history even though the
+// CURRENT board projection correctly flips back to active on the next tool call.
+const DECLARED = ' — recorded; the human sees it in the dashboard. This declaration remains in the session timeline; your next tool call flips only the current board state back to active (the mark-active hook, by design).'
 // 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.'
 
@@ -998,6 +999,16 @@ if (cmd === 'serve') {
     // the StopFailure hook marks its session (--session from the payload) as error (turn died on an API error)
     const { s, sess, mark, noRecord } = await stateKit()
     console.log(mark(() => s.markError(sess)) ? 'marked error' : noRecord())
+  } else if (sub === 'session-turn-fail') {
+    // Headless adapters report an ephemeral turn's non-zero exit through this one shared CAS. A declaration
+    // that landed before teardown wins, so a late child close can never erase an agent-authored state.
+    const sessionId = process.argv[4], harness = process.argv[5], exitCode = process.argv[6]
+    if (!sessionId || !harness || !exitCode) {
+      console.error('usage: spex internal session-turn-fail <session-id> <harness> <exit-code|signal>')
+      process.exit(2)
+    }
+    const { markHeadlessTurnFailure } = await import('./sessions.js')
+    console.log(markHeadlessTurnFailure(sessionId, harness, exitCode) ? `marked error (${harness} ${exitCode})` : 'noop (no active session record)')
   } else if (sub === 'session-idle') {
     // the Notification(idle_prompt) hook marks its session (--session from the payload) idle when claude waits
     // at its prompt. INFERRED, so guarded active-only: it no-ops unless the current status is exactly `active`,

package/spec-cli/src/harness.ts

@@ -450,6 +450,22 @@ export function codexSupportsBypassHookTrust(binary: string): boolean {
   bypassProbe.set(binary, ok)
   return ok
 }
+
+// Headless adapters all feed non-zero ephemeral turn exits through one state writer. Keep this reporter at the
+// adapter seam: controllers may call it directly, while shell-homed turns use headlessTurnFailureShell below.
+export async function reportHeadlessTurnExit(id: string, harness: string, code: number | null, cwd = process.cwd()): Promise<void> {
+  if (code === 0) return
+  const exitCode = code === null ? 'signal' : String(code)
+  try {
+    await pexec(SPEX, ['internal', 'session-turn-fail', id, harness, exitCode], { cwd, env: process.env })
+  } catch (error) {
+    console.error(`[spex ${harness}] could not record turn failure for ${id}: ${(error as Error).message}`)
+  }
+}
+
+export function headlessTurnFailureShell(harness: string): string {
+  return `${shQuote(SPEX)} internal session-turn-fail "$SPEXCODE_SESSION_ID" ${shQuote(harness)} "$__spex_rc" || true`
+}
 export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?: string, dir = runtimeRoot(), attachTui = true): string {
   const server = process.env.SPEXCODE_CODEX_SERVER_CMD || serverCmd || codexBinary(codexCmd)
   // The bypass flag ONLY reaches a thread's hook trust as a per-request `config` override, NOT as a CLI flag on
@@ -527,7 +543,11 @@ export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?:
       `  exit 0`,
     ]),
     `else`,
-    `  tid=$(${SPEX} internal codex-launch "$sock" "$PWD" "$@") || exit 1`,
+    `  tid=$(${SPEX} internal codex-launch "$sock" "$PWD" "$@")`,
+    `  __spex_rc=$?`,
+    ...(attachTui ? [`  [ "$__spex_rc" -eq 0 ] || exit 1`] : [
+      `  if [ "$__spex_rc" -ne 0 ]; then ${headlessTurnFailureShell('codex-headless')}; exit "$__spex_rc"; fi`,
+    ]),
     `fi`,
     `[ -n "$tid" ] || { echo "[spex] codex-launch produced no resumable thread" >&2; exit 1; }`,
     ...(attachTui ? [`exec ${codexCmd}${tuiBypass} --remote unix://"$sock" resume "$tid"`] : []),

package/spec-cli/src/host.ts

@@ -223,6 +223,7 @@ export async function reconcileProjects(): Promise<ProjectEntry[]> {
 
   const byId = new Map<string, ProjectEntry>()
   const push = (root: string) => {
+    if (!existsSync(root)) return
     const projectId = encodeProject(root)
     if (byId.has(projectId)) return   // encodeProject is lossy; first root wins a (pathological) collision
     const active = live.get(root) ?? null

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

@@ -1,17 +1,50 @@
 import { execFile } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir, userInfo } from 'node:os'
+import { join } from 'node:path'
 import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
 import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
 
 const pexec = promisify(execFile)
+const SPEX = join(fileURLToPath(new URL('..', import.meta.url)), 'bin', 'spex.mjs')
+const WAKE_EARLY_EXIT_MS = 5_000
+const OUTCOME_POLL_MS = 25
 
 const shQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+const turnFailureShell = (swallow: boolean) =>
+  `${shQuote(SPEX)} internal session-turn-fail "$SPEXCODE_SESSION_ID" ${shQuote('opencode-headless')} "$__spex_rc"${swallow ? ' || true' : ''}`
+
+function accountLoginShell(): string {
+  try { return userInfo().shell || '' } catch { return '' }
+}
 
 // A headless turn owns the pane only while `opencode run` is alive. Returning to a shell keeps the tmux
 // window as the session's durable home without adding a resident controller or an stdin bridge.
-function turnHome(command: string): string {
+function turnHome(command: string, outcomePath?: string): string {
+  const outcomeSetup = outcomePath ? [
+    `__spex_outcome_path=${shQuote(outcomePath)}`,
+    `__spex_outcome_tmp=${shQuote(`${outcomePath}.tmp`)}`,
+    '__spex_outcome() { printf \'%s\\n\' "$1" > "$__spex_outcome_tmp" && mv -f "$__spex_outcome_tmp" "$__spex_outcome_path"; }',
+    '__spex_outcome "running:$$" || { printf "[spex opencode-headless] could not create turn outcome marker\\n" >&2; exit 125; }',
+  ] : []
+  const failure = outcomePath ? [
+    '__spex_cas_rc=0',
+    'if [ "$__spex_rc" -ne 0 ]; then',
+    '  __spex_outcome "reporting:$$:$__spex_rc" || true',
+    `  ${turnFailureShell(false)}`,
+    '  __spex_cas_rc=$?',
+    'fi',
+    '__spex_outcome "exit:$__spex_rc:cas:$__spex_cas_rc" || printf "[spex opencode-headless] could not finalize turn outcome marker\\n" >&2',
+  ] : [
+    `if [ "$__spex_rc" -ne 0 ]; then ${turnFailureShell(true)}; fi`,
+  ]
   const script = [
+    ...outcomeSetup,
     command,
     '__spex_rc=$?',
+    ...failure,
     '[ "$__spex_rc" -eq 0 ] || printf "[spex opencode-headless] turn exited rc=%s\\n" "$__spex_rc" >&2',
     'exec "${SHELL:-/bin/sh}"',
   ].join('\n')
@@ -21,14 +54,19 @@ function turnHome(command: string): string {
 // Launcher profiles carry a base executable plus its configured flags (`opencode --auto`). OpenCode parses
 // `run` as a subcommand, so it must sit between those two halves (`opencode run --auto`), not at the tail.
 function runPrelude(opencodeCmd: string): string[] {
+  const accountShell = accountLoginShell()
   return [
+    '__spex_login_shell="${SHELL:-}"',
+    `[ -n "$__spex_login_shell" ] || __spex_login_shell=${shQuote(accountShell)}`,
     `__spex_cmd=(${opencodeCmd})`,
     '__spex_env=()',
     'while [ "${#__spex_cmd[@]}" -gt 0 ] && [[ "${__spex_cmd[0]}" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do',
     '  __spex_env+=("${__spex_cmd[0]}")',
     '  __spex_cmd=("${__spex_cmd[@]:1}")',
     'done',
-    '__spex_run() { env "${__spex_env[@]}" "${__spex_cmd[0]}" run "${__spex_cmd[@]:1}" "$@"; }',
+    // Resolve OpenCode in the same login + interactive environment the user relies on. The launcher-leading
+    // assignments are applied after shell startup, so its explicit per-session config still wins.
+    '__spex_run() { [ -n "$__spex_login_shell" ] || { printf "[spex opencode-headless] no login shell could be resolved - turn NOT started\\n" >&2; return 126; }; "$__spex_login_shell" -ilc \'exec env "$@"\' spexcode-opencode-headless "${__spex_env[@]}" "${__spex_cmd[0]}" run "${__spex_cmd[@]:1}" "$@"; }',
   ]
 }
 
@@ -53,7 +91,12 @@ export function opencodeHeadlessLaunchCommand(opencodeCmd = 'opencode'): string
   return turnHome(script)
 }
 
-export function opencodeHeadlessWakeCommand(opencodeCmd: string, harnessSessionId: string | null | undefined, text: string): string {
+export function opencodeHeadlessWakeCommand(
+  opencodeCmd: string,
+  harnessSessionId: string | null | undefined,
+  text: string,
+  outcomePath?: string,
+): string {
   const resume = harnessSessionId ? [
     `export SPEXCODE_OPENCODE_RESUME_ID=${shQuote(harnessSessionId)}`,
     'unset SPEXCODE_OPENCODE_CONTINUE',
@@ -63,7 +106,44 @@ export function opencodeHeadlessWakeCommand(opencodeCmd: string, harnessSessionI
     'export SPEXCODE_OPENCODE_CONTINUE=1',
     `__spex_run --continue ${shQuote(text)}`,
   ]
-  return turnHome([...runPrelude(opencodeCmd), ...resume].join('\n'))
+  return turnHome([...runPrelude(opencodeCmd), ...resume].join('\n'), outcomePath)
+}
+
+type TurnOutcome =
+  | { state: 'running'; pid: number }
+  | { state: 'reporting'; pid: number; code: number }
+  | { state: 'exit'; code: number; casCode: number }
+  | { state: 'invalid' }
+
+function readTurnOutcome(path: string): TurnOutcome | undefined {
+  let value: string
+  try { value = readFileSync(path, 'utf8').trim() } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw error
+  }
+  let match = /^running:(\d+)$/.exec(value)
+  if (match) return { state: 'running', pid: Number(match[1]) }
+  match = /^reporting:(\d+):(-?\d+)$/.exec(value)
+  if (match) return { state: 'reporting', pid: Number(match[1]), code: Number(match[2]) }
+  match = /^exit:(-?\d+):cas:(\d+)$/.exec(value)
+  if (match) return { state: 'exit', code: Number(match[1]), casCode: Number(match[2]) }
+  return { state: 'invalid' }
+}
+
+function turnExited(rec: HarnessDeliveryRecord, outcome: Extract<TurnOutcome, { state: 'exit' }>): DispatchResult {
+  if (outcome.code === 0) return { ok: true }
+  const cas = outcome.casCode === 0 ? '' : `; error CAS reporter also exited with code ${outcome.casCode}`
+  return {
+    ok: false,
+    error: `opencode-headless turn exited with code ${outcome.code} during startup for session ${rec.session}${cas} - prompt delivery FAILED`,
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try { process.kill(pid, 0); return true } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
 }
 
 export async function spawnOpenCodeHeadlessTurn(
@@ -73,6 +153,11 @@ export async function spawnOpenCodeHeadlessTurn(
   socketPath: string,
 ): Promise<DispatchResult> {
   if (!rec.worktreePath) return { ok: false, error: `opencode-headless session ${rec.session} has no worktree path - turn NOT started` }
+  let outcomeDir: string
+  try { outcomeDir = mkdtempSync(join(tmpdir(), 'spexcode-oh-turn-')) } catch (error) {
+    return { ok: false, error: `opencode-headless could not prepare turn confirmation for session ${rec.session}: ${(error as Error).message}` }
+  }
+  const outcomePath = join(outcomeDir, 'exit-code')
   const tmuxSock = process.env.SPEXCODE_TMUX || 'spexcode'
   const args = [
     '-L', tmuxSock, 'respawn-pane', '-k', '-t', rec.session, '-c', rec.worktreePath,
@@ -84,12 +169,41 @@ export async function spawnOpenCodeHeadlessTurn(
     const value = process.env[name]
     if (value) args.push('-e', `${name}=${value}`)
   }
-  args.push(opencodeHeadlessWakeCommand(opencodeCmd, rec.harnessSessionId, text))
+  args.push(opencodeHeadlessWakeCommand(opencodeCmd, rec.harnessSessionId, text, outcomePath))
   try {
     await pexec('tmux', args, { timeout: 5_000 })
+    const deadline = Date.now() + WAKE_EARLY_EXIT_MS
+    for (;;) {
+      const outcome = readTurnOutcome(outcomePath)
+      if (outcome?.state === 'exit') return turnExited(rec, outcome)
+      if (outcome?.state === 'invalid') {
+        return { ok: false, error: `opencode-headless turn for session ${rec.session} wrote an invalid exit outcome - prompt delivery NOT confirmed` }
+      }
+      if (Date.now() >= deadline) break
+      await sleep(Math.min(OUTCOME_POLL_MS, deadline - Date.now()))
+    }
+
+    const first = readTurnOutcome(outcomePath)
+    if (first?.state === 'exit') return turnExited(rec, first)
+    if (!first) return { ok: false, error: `opencode-headless turn for session ${rec.session} never confirmed startup - prompt delivery FAILED` }
+    if (first.state === 'invalid') return { ok: false, error: `opencode-headless turn for session ${rec.session} wrote an invalid exit outcome - prompt delivery NOT confirmed` }
+    if (first.state === 'reporting') {
+      return { ok: false, error: `opencode-headless turn exited with code ${first.code} but its error CAS reporter did not finish for session ${rec.session} - prompt delivery FAILED` }
+    }
+    if (!pidAlive(first.pid)) {
+      return { ok: false, error: `opencode-headless turn wrapper died before reporting an outcome for session ${rec.session} - prompt delivery FAILED` }
+    }
+    await sleep(OUTCOME_POLL_MS)
+    const settled = readTurnOutcome(outcomePath)
+    if (settled?.state === 'exit') return turnExited(rec, settled)
+    if (settled?.state !== 'running' || settled.pid !== first.pid || !pidAlive(settled.pid)) {
+      return { ok: false, error: `opencode-headless turn did not remain live through startup for session ${rec.session} - prompt delivery FAILED` }
+    }
     return { ok: true }
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error)
     return { ok: false, error: `opencode-headless could not start a turn for session ${rec.session}: ${detail}` }
+  } finally {
+    rmSync(outcomeDir, { recursive: true, force: true })
   }
 }

package/spec-cli/src/opencode.ts

@@ -120,10 +120,14 @@ export const SpexcodePlugin = async (ctx) => {
         const sid = p.sessionID || ""
         if (sid && rootSession && sid !== rootSession) return   // a subagent going idle is not this worker's Stop
         adopt(sid)
-        // the stop-gate loop closes in-process via the runtime's dispatchStop: stop_hook_active rides the
-        // payload (the gate's loop-termination bit) and the gate's parsed reason re-enters as a follow-up
-        // prompt; an inject the host can no longer take is reported loud.
-        await rt.dispatchStop((reason) => injectPrompt(reason), "blocked by a spexcode hook")
+        // Start the Stop dispatch now, but RETURN this idle callback before a blocked verdict injects its
+        // follow-up turn. Awaiting client.session.prompt here re-enters opencode before it has published the
+        // just-finished assistant text: the continuation can declare success while the requested final answer
+        // disappears. This is opencode host scheduling, not shared dispatchStop semantics (pi correctly awaits
+        // its agent_end continuation). dispatchStop catches inject failures; this final catch keeps substrate
+        // failures loud without throwing them into opencode after the event callback has returned.
+        void rt.dispatchStop((reason) => injectPrompt(reason), "blocked by a spexcode hook")
+          .catch((e) => console.error("spexcode: Stop dispatch failed: " + String(e)))
       }
     },
     "chat.message": async (input, output) => {

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

@@ -171,6 +171,7 @@ export class PiHeadlessController {
     childProcess.once('close', (code) => {
       if (this.child === turn) this.child = null
       resolveExit(code)
+      if (code !== 0 && !this.closing) void import('./harness.js').then(({ reportHeadlessTurnExit }) => reportHeadlessTurnExit(this.id, 'pi-headless', code, this.cwd))
     })
     await withTimeout(new Promise<void>((resolve, reject) => {
       childProcess.once('spawn', () => resolve())

package/spec-cli/src/pty-bridge.ts

@@ -20,6 +20,7 @@ type Subscription = {
   bridge?: Bridge
   lingerTimer?: ReturnType<typeof setTimeout>
   restoreTimer?: ReturnType<typeof setTimeout>
+  startupError?: string
 }
 
 type Bridge = {
@@ -37,6 +38,7 @@ type Bridge = {
   refreshRunning: boolean
   refreshOffset?: number
   deliveryTimer?: ReturnType<typeof setTimeout>
+  startupError?: string
 }
 
 const subscribers = new Map<string, Map<Viewer, Subscription>>()
@@ -103,6 +105,8 @@ function onHelperStderr(bridge: Bridge, chunk: Buffer): void {
     const ready = line.match(/^READY (\d+)$/)
     if (ready) {
       bridge.ptyPid = Number(ready[1])
+      const subscription = currentSubscription(bridge.id, bridge.viewer)
+      if (subscription) subscription.startupError = undefined
       if (bridge.delivery === 'initial') {
         armDeliveryBoundary(bridge)
         queueRefresh(bridge)
@@ -117,11 +121,28 @@ function onHelperStderr(bridge: Bridge, chunk: Buffer): void {
         queueRefresh(bridge)
       }
     } else if (line) {
+      const failed = line.match(/^ERROR (.+)$/)
+      if (failed) reportStartupError(bridge, failed[1])
       console.error(`[terminal helper ${bridge.id}/${bridge.ptyPid ?? 'starting'}] ${line}`)
     }
   }
 }
 
+function reportStartupError(bridge: Bridge, detail: string): void {
+  const subscription = currentSubscription(bridge.id, bridge.viewer)
+  if (!subscription || subscription.bridge !== bridge) return
+  const message = boundedStartupError(detail)
+  bridge.startupError = message
+  if (!message || subscription.startupError === message) return
+  subscription.startupError = message
+  deliver(bridge, Buffer.from(`\r\n[SpexCode terminal unavailable] ${message}\r\n`, 'utf8'))
+}
+
+function boundedStartupError(detail: unknown): string {
+  return (detail instanceof Error ? detail.message : String(detail))
+    .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500) || 'native PTY failed to start'
+}
+
 function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, cols: number, rows: number): { bridge: Bridge | null; created: boolean } {
   if (subscription.bridge) return { bridge: subscription.bridge, created: false }
   let proc: ChildProcessWithoutNullStreams | undefined
@@ -130,8 +151,13 @@ function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, co
       stdio: ['pipe', 'pipe', 'pipe'],
       env: process.env,
     })
-  } catch {
+  } catch (error) {
     try { proc?.kill() } catch { /* spawn did not complete */ }
+    const detail = boundedStartupError(error)
+    if (subscription.startupError !== detail) {
+      subscription.startupError = detail
+      try { viewer.send(Buffer.from(`\r\n[SpexCode terminal unavailable] ${detail}\r\n`, 'utf8')) } catch { /* socket closed */ }
+    }
     return { bridge: null, created: false }
   }
   const bridge: Bridge = {
@@ -142,18 +168,19 @@ function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, co
   proc.stdout.on('data', (data: Buffer) => onHelperOutput(bridge, data))
   proc.stderr.on('data', (data: Buffer) => onHelperStderr(bridge, data))
   let reaped = false
-  const gone = () => {
+  const gone = (detail?: string) => {
     if (reaped) return
     reaped = true
     const current = currentSubscription(id, viewer)
     if (current?.bridge !== bridge) return
+    if (!bridge.ptyPid && !bridge.startupError) reportStartupError(bridge, detail || 'helper exited before native PTY startup')
     current.bridge = undefined
     clearDelivery(bridge)
     try { bridge.proc.kill() } catch { /* already gone */ }
     scheduleRestore(id, viewer, current)
   }
-  proc.on('exit', gone)
-  proc.on('error', gone)
+  proc.on('exit', (code, signal) => gone(`helper exited before native PTY startup (${signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`})`))
+  proc.on('error', (error) => gone(`helper process failed: ${error.message}`))
   return { bridge, created: true }
 }
 

package/spec-cli/src/pty-helper.mjs

@@ -1,5 +1,6 @@
 import * as pty from 'node-pty'
 import { execFileSync } from 'node:child_process'
+import { ensureExecutableIfPresent, nodePtySpawnHelperPath } from './pty-native-helper.mjs'
 
 const [id, colsArg, rowsArg] = process.argv.slice(2)
 const cols = Number(colsArg)
@@ -40,12 +41,21 @@ try {
   }
 } catch { /* attach below fails loudly if the tmux server/session is unavailable */ }
 
-const terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
-  name: 'xterm-256color',
-  cols,
-  rows,
-  env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
-})
+let terminal
+try {
+  ensureExecutableIfPresent(nodePtySpawnHelperPath(pty.native))
+  terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
+    name: 'xterm-256color',
+    cols,
+    rows,
+    env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
+  })
+} catch (error) {
+  const detail = (error instanceof Error ? error.message : String(error))
+    .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500)
+  process.stderr.write(`ERROR ${detail || 'native PTY failed to start'}\n`)
+  process.exit(1)
+}
 
 terminal.onData((data) => process.stdout.write(Buffer.from(data, 'utf8')))
 terminal.onExit(({ exitCode }) => process.exit(exitCode === 0 ? 0 : 1))

package/spec-cli/src/pty-native-helper.mjs

@@ -0,0 +1,22 @@
+import { chmodSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+export function nodePtySpawnHelperPath(nativeModule) {
+  const nativeAddon = Object.values(require.cache).find((loaded) => loaded?.exports === nativeModule)?.filename
+  if (!nativeAddon) throw new Error('cannot locate node-pty loaded native addon')
+  return join(dirname(nativeAddon), 'spawn-helper')
+}
+
+export function ensureExecutableIfPresent(path) {
+  let mode
+  try {
+    mode = statSync(path).mode & 0o777
+  } catch (error) {
+    if (error?.code === 'ENOENT') return
+    throw error
+  }
+  if ((mode & 0o111) !== 0o111) chmodSync(path, mode | 0o111)
+}