spexcode 0.5.0 → 0.5.2

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,claude-headless,opencode-headless,pi-headless   # seeds .spec/, installs hooks, materializes the agent contracts
+spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless,codex-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.5.0",
+  "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",
@@ -39,7 +39,7 @@
     "@hono/node-server": "^1.13.7",
     "@hono/node-ws": "^1.0.4",
     "hono": "^4.6.14",
-    "node-pty": "^1.1.0",
+    "node-pty": "1.2.0-beta.14",
     "tsx": "^4.19.2"
   },
   "devDependencies": {

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/codex-headless.ts

@@ -0,0 +1,13 @@
+import { codexLaunchCommand } from './harness.js'
+
+// Codex headless keeps the existing app-server bootstrap and backend-owned thread/start + first turn, but
+// deliberately omits the final interactive `--remote … resume` attach. The shared app-server remains the
+// durable home for the thread; follow-up delivery uses codexHarness' existing JSON-RPC transport.
+export function codexHeadlessLaunchCommand(
+  id: string,
+  codexCmd = 'codex',
+  serverCmd?: string,
+  dir?: string,
+): string {
+  return codexLaunchCommand(id, codexCmd, serverCmd, dir, false)
+}

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,claude-headless,opencode-headless,pi-headless   # seeds .spec/ + git hooks (additive, never overwrites)
+     cd <your-repo> && spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless,codex-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).
@@ -333,18 +333,19 @@ 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" }
+  "codex-headless" → { "harness": "codex-headless", "cmd": "codex --yolo" }
   "opencode" → { "harness": "opencode", "cmd": "opencode" }
   "opencode-headless" → { "harness": "opencode-headless", "cmd": "opencode --auto" }
   "pi"       → { "harness": "pi",       "cmd": "pi" }
   "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
+The interactive profiles preserve each harness's normal permission model. \`opencode-headless\` and
+\`codex-headless\` are deliberate seed exceptions: their terminal-free runs require \`opencode --auto\` and
+\`codex --yolo\`; interactive profiles stay 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" | "claude-headless" | "opencode-headless" | "pi-headless",
+  "launchers": { "<name>": { "harness": "claude" | "codex" | "opencode" | "pi" | "claude-headless" | "codex-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,
@@ -453,7 +454,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"|"claude-headless"|"opencode-headless"|"pi-headless") or a
+              ("claude"|"codex"|"opencode"|"pi"|"claude-headless"|"codex-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

package/spec-cli/src/harness.ts

@@ -10,6 +10,7 @@ import { claudeSlashCommands, codexSlashCommands, opencodeSlashCommands, piSlash
 import { OPENCODE_EVENTS, opencodePluginSource } from './opencode.js'
 import { piExtensionSource, writePiTrust, removePiTrust } from './pi-harness.js'
 import { claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js'
+import { codexHeadlessLaunchCommand } from './codex-headless.js'
 import { opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js'
 import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless } from './pi-headless.js'
 import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
@@ -27,7 +28,7 @@ import { git } from './git.js'
 // payload shape. On the TS side the harness is derived from the selected launcher or ALL adapters at once
 // (materialize writes every harness's artifacts).
 
-export type HarnessId = 'claude' | 'codex' | 'opencode' | 'pi' | 'claude-headless' | 'opencode-headless' | 'pi-headless'
+export type HarnessId = 'claude' | 'codex' | 'opencode' | 'pi' | 'claude-headless' | 'codex-headless' | 'opencode-headless' | 'pi-headless'
 export type HarnessLivenessRecord = { session: string; harnessSessionId?: string | null }
 // the per-pane runtime probe the caller snapshots ONCE for the whole session list and hands liveness():
 // the pane's root pid (tmux `#{pane_pid}`), the hot-tier `pidAlive` verdict, and — ONLY on the legacy path —
@@ -47,6 +48,9 @@ export interface Harness {
   // whether this harness runs without an interactive TUI. The dashboard launcher picker hides headless
   // adapters by default ([[launcher-visibility]]); CLI launcher resolution never consumes that policy.
   readonly headless: boolean
+  // whether the launch command intentionally exits after its first turn instead of owning a resident process.
+  // One-shot adapters must not be mistaken for a failed fast boot and retried with a duplicate prompt.
+  readonly launchOneShot?: boolean
   // whether this harness persists a native event stream that the console may expose as an optional
   // full-process drill-down ([[message-stream]]). This is adapter data, never a harness-id branch in UI.
   readonly messageStream: boolean
@@ -446,7 +450,23 @@ export function codexSupportsBypassHookTrust(binary: string): boolean {
   bypassProbe.set(binary, ok)
   return ok
 }
-export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?: string, dir = runtimeRoot()): string {
+
+// 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
   // the shared `app-server` process (the app-server never reads its own `--dangerously-bypass-hook-trust` for a
@@ -516,11 +536,21 @@ export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?:
     // rollout has landed (resume-ready), so a fail-loud (empty output / non-zero) must ABORT — never `resume ""`.
     `if [ "$1" = "--resume" ]; then`,
     `  tid=$2`,
+    ...(attachTui ? [] : [
+      // A headless forced reopen has no TUI to attach and the shared app-server already owns the thread. Keep it
+      // a no-op instead of calling codex-launch without a prompt (which would mint an unrelated empty thread).
+      `elif [ "$#" -eq 0 ]; then`,
+      `  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; }`,
-    `exec ${codexCmd}${tuiBypass} --remote unix://"$sock" resume "$tid"`,
+    ...(attachTui ? [`exec ${codexCmd}${tuiBypass} --remote unix://"$sock" resume "$tid"`] : []),
   ].join('\n')
   return `bash -lc ${shQuote(script)} spexcode-codex`
 }
@@ -1230,6 +1260,24 @@ export const codexHarness: Harness = {
   resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : ''),
 }
 
+// Codex headless is an independent adapter: its materialization and app-server delivery are exactly Codex's,
+// while launch only runs the backend-owned thread/start + first turn. There is no TUI to attach after that turn;
+// the shared project app-server keeps the thread addressable and idle sends use the inherited JSON-RPC channel.
+export const codexHeadlessHarness: Harness = {
+  ...codexHarness,
+  id: 'codex-headless',
+  headless: true,
+  launchOneShot: true,
+  messageStream: false,
+  launchCmd: (id, runtimeDir, cmd) => codexHeadlessLaunchCommand(id, codexBaseCmd(cmd), undefined, runtimeDir ?? runtimeRoot()),
+  // Record-backed liveness is the family contract for sleeping headless threads. A broken app-server or missing
+  // thread is surfaced by the inherited delivery call rather than converted into a speculative offline state.
+  liveness: () => 'online',
+  // There is no TUI to restart and the project app-server keeps the thread addressable. A forced reopen therefore
+  // runs the headless launch's empty-tail no-op; normal resume remains guarded by record-backed online liveness.
+  resumeArg: () => '',
+}
+
 // @@@ piHarness - the pi adapter (@earendil-works/pi-coding-agent). pi is the CLOSEST to claude of the four:
 // the caller pins the session id at launch (`--session-id <id>`, creating the session if missing), the shim
 // lives IN the worktree, and the rendezvous prompt/liveness channel is REUSED wholesale — pi has no external
@@ -1367,7 +1415,7 @@ export const opencodeHeadlessHarness: Harness = {
 }
 
 // every adapter — materialize iterates this to write each harness's artifacts in one pass.
-export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness, opencodeHarness, piHarness, claudeHeadlessHarness, opencodeHeadlessHarness, piHeadlessHarness]
+export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness, opencodeHarness, piHarness, claudeHeadlessHarness, opencodeHeadlessHarness, piHeadlessHarness, codexHeadlessHarness]
 
 // the legacy/default adapter for old records and config defaults. New launches derive harness from a launcher.
 export const defaultHarness: Harness = claudeHarness

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())