spexcode 0.5.1 → 0.5.3

package/spec-cli/src/maintenance-wrapper.ts

@@ -0,0 +1,276 @@
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+import type { Duplex, Readable, Writable } from 'node:stream'
+import type { Capability, LeaseOwner, MaintenanceState } from './session-maintenance.js'
+import { processStartToken } from './process-identity.js'
+import {
+  clientMaintenanceAcquire,
+  clientMaintenanceHeartbeat,
+  clientMaintenanceOperation,
+  clientMaintenanceRelease,
+  clientMaintenanceStatus,
+} from './client.js'
+
+type BrokerRequest = {
+  v?: number
+  id?: string
+  op?: string
+  sessionId?: string
+  force?: boolean
+  client?: { pid?: number; startToken?: string }
+}
+type PlannedCapability = {
+  capability: Capability
+  state: 'unused' | 'inflight' | 'committed' | 'indeterminate'
+  requestId?: string
+}
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+const capabilityKey = (capability: Capability): string => JSON.stringify(capability)
+const capabilityList = (rows: unknown): Capability[] => Array.isArray(rows)
+  ? rows.map((row: any) => row?.capability ?? row)
+  : []
+const sameCapabilities = (left: readonly Capability[], right: readonly Capability[]): boolean =>
+  JSON.stringify(left) === JSON.stringify(right)
+const sameOwner = (left: LeaseOwner | null | undefined, right: LeaseOwner): boolean =>
+  !!left && left.instanceId === right.instanceId && left.pid === right.pid && left.startToken === right.startToken
+const assertLeaseView = (view: Pick<MaintenanceState, 'state' | 'epoch' | 'owner' | 'capabilities'>, epoch: number, owner: LeaseOwner, capabilities: readonly Capability[], allowDraining = false) => {
+  if (view.epoch !== epoch || (!allowDraining && view.state !== 'active') || (allowDraining && view.state !== 'active' && view.state !== 'draining'))
+    throw new Error('maintenance lease changed epoch or state')
+  if (!sameOwner(view.owner, owner)) throw new Error('maintenance lease owner generation changed')
+  if (!sameCapabilities(capabilityList(view.capabilities), capabilities)) throw new Error('maintenance lease changed its capability plan')
+}
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+const reapCommandGroup = async (child: ReturnType<typeof spawn>, closed: Promise<[number | null, NodeJS.Signals | null]>) => {
+  if (!child.pid) return
+  const groupAlive = () => {
+    try { process.kill(-child.pid!, 0); return true } catch { return false }
+  }
+  if (groupAlive()) {
+    try { process.kill(-child.pid, 'SIGTERM') } catch { /* already exited */ }
+    const deadline = Date.now() + 1_000
+    while (groupAlive() && Date.now() < deadline) await wait(20)
+    if (groupAlive()) {
+      try { process.kill(-child.pid, 'SIGKILL') } catch { /* already exited */ }
+    }
+  }
+  const closedAfterReap = await new Promise<boolean>((resolve) => {
+    let settled = false
+    const finish = (value: boolean) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(value)
+    }
+    const timer = setTimeout(() => finish(false), 2_000)
+    timer.unref()
+    void closed.then(() => finish(true))
+  })
+  if (!closedAfterReap) throw new Error('maintenance operator pipes did not close after exact process-group reap')
+}
+
+export async function runMaintenanceWrapper(input: {
+  capabilities: Capability[]
+  ttlMs: number
+  waitMs: number
+  command: string[]
+}): Promise<number> {
+  const acquired = await clientMaintenanceAcquire(input.capabilities, input.ttlMs, input.waitMs)
+  const { token, epoch, owner } = acquired.lease
+  const releaseable = typeof token === 'string' && /^[0-9a-f]{64}$/i.test(token) && Number.isSafeInteger(epoch)
+  let released = false
+  let authorityLost = false
+  let heartbeat: ReturnType<typeof setInterval> | null = null
+  let child: ReturnType<typeof spawn> | null = null
+  const pendingOperations = new Set<AbortController>()
+  let closeAdmission = () => {}
+  try {
+    if (!releaseable) throw new Error('maintenance acquire returned malformed private authority')
+    if (!owner || typeof owner.instanceId !== 'string' || !Number.isInteger(owner.pid) || typeof owner.startToken !== 'string')
+      throw new Error('maintenance acquire returned malformed supervisor authority')
+    if (!sameCapabilities(capabilityList(acquired.lease.capabilities), input.capabilities)) throw new Error('maintenance acquire returned a different capability plan')
+
+    let state = acquired.lease.state
+    const activationDeadline = Date.now() + input.ttlMs
+    try {
+      while (state === 'draining') {
+        const current = await clientMaintenanceHeartbeat(token, epoch, input.ttlMs)
+        assertLeaseView(current, epoch, owner, input.capabilities, true)
+        const status = await clientMaintenanceStatus()
+        assertLeaseView(status, epoch, owner, input.capabilities, true)
+        state = status.state as 'draining' | 'active'
+        if (state !== 'active') {
+          if (Date.now() >= activationDeadline) throw new Error('maintenance acquisition did not become active before its ttl')
+          await sleep(50)
+        }
+      }
+      if (state !== 'active') throw new Error(`maintenance acquisition entered unexpected state ${state}`)
+    } catch (error) {
+      authorityLost = true
+      throw error
+    }
+    if (!input.command.length) throw new Error('maintenance wrapper needs a command after --')
+
+    const plan: PlannedCapability[] = input.capabilities.map((capability) => ({ capability: { ...capability }, state: 'unused' }))
+    let heartbeatFailure: Error | null = null
+    let heartbeatBusy = false
+    let failAuthority!: (error: Error) => void
+    const authorityFailure = new Promise<never>((_, reject) => {
+      failAuthority = (error) => {
+        if (heartbeatFailure) return
+        heartbeatFailure = error
+        reject(error)
+      }
+    })
+    heartbeat = setInterval(() => {
+      if (heartbeatBusy || heartbeatFailure) return
+      heartbeatBusy = true
+      void clientMaintenanceHeartbeat(token, epoch, input.ttlMs)
+        .then((current) => assertLeaseView(current, epoch, owner, input.capabilities))
+        .catch((error) => failAuthority(error instanceof Error ? error : new Error(String(error))))
+        .finally(() => { heartbeatBusy = false })
+    }, Math.max(250, Math.min(1_000, Math.floor(input.ttlMs / 3))))
+    heartbeat.unref()
+
+    child = spawn(input.command[0], input.command.slice(1), {
+      stdio: ['inherit', 'inherit', 'inherit', 'pipe', 'pipe', 'pipe'],
+      env: { ...process.env, SPEXCODE_MAINTENANCE_BROKER_FDS: '3,4,5' },
+      detached: true,
+    })
+    const exited = once(child, 'exit') as Promise<[number | null, NodeJS.Signals | null]>
+    const closed = once(child, 'close') as Promise<[number | null, NodeJS.Signals | null]>
+    const childStdio = child.stdio as Array<Readable | Writable | Duplex | null | undefined>
+    const requestPipe = childStdio[3] as Readable
+    const responsePipe = childStdio[4] as Writable
+    const turnPipe = childStdio[5] as Duplex
+    requestPipe.setEncoding('utf8')
+    let pending = ''
+    let serial = Promise.resolve()
+    let brokerWork = 0
+    let brokerOpen = true
+    let transportLossTimer: ReturnType<typeof setTimeout> | null = null
+    const brokerTransportLost = (error: unknown) => {
+      if (!brokerOpen || transportLossTimer) return
+      transportLossTimer = setTimeout(() => {
+        transportLossTimer = null
+        if (brokerOpen && child?.exitCode === null && child.signalCode === null) {
+          failAuthority(error instanceof Error ? error : new Error('maintenance broker transport closed while the operator command was live'))
+        }
+      }, 50)
+      transportLossTimer.unref()
+    }
+    requestPipe.on('error', brokerTransportLost)
+    requestPipe.on('end', () => brokerTransportLost(new Error('maintenance broker request pipe closed while the operator command was live')))
+    responsePipe.on('error', brokerTransportLost)
+    responsePipe.on('close', () => brokerTransportLost(new Error('maintenance broker response pipe closed while the operator command was live')))
+    turnPipe.on('error', brokerTransportLost)
+    turnPipe.on('end', () => brokerTransportLost(new Error('maintenance broker turn pipe closed while the operator command was live')))
+    closeAdmission = () => {
+      if (!brokerOpen) return
+      brokerOpen = false
+      for (const controller of pendingOperations) controller.abort(new Error('maintenance broker admission closed'))
+      if (transportLossTimer) clearTimeout(transportLossTimer)
+      transportLossTimer = null
+      try { requestPipe.destroy() } catch { /* already closed */ }
+      try { turnPipe.destroy() } catch { /* already closed */ }
+    }
+    turnPipe.on('data', (chunk: Buffer) => {
+      if (!brokerOpen) return
+      for (const byte of chunk) {
+        if (byte !== 1) return failAuthority(new Error('maintenance broker turn token was corrupted'))
+        turnPipe.write(Buffer.from([1]))
+      }
+    })
+    turnPipe.write(Buffer.from([1]))
+    const reply = (id: string | undefined, body: Record<string, unknown>) => {
+      if (brokerOpen) responsePipe.write(`${JSON.stringify({ id, ...body })}\n`)
+    }
+    const handle = async (request: BrokerRequest) => {
+      if (!brokerOpen) return
+      if (request.v !== 1 || typeof request.id !== 'string' || typeof request.op !== 'string' || typeof request.sessionId !== 'string'
+        || !Number.isInteger(request.client?.pid) || typeof request.client?.startToken !== 'string'
+        || processStartToken(request.client.pid!) !== request.client.startToken) {
+        reply(request.id, { ok: false, code: 'maintenance_invalid', error: 'malformed broker request' })
+        return
+      }
+      const candidate: Capability | null = request.op === 'stop'
+        ? { op: 'stop', sessionId: request.sessionId }
+        : request.op === 'resume' && typeof request.force === 'boolean'
+          ? { op: 'resume', sessionId: request.sessionId, force: request.force }
+          : null
+      const matching = candidate && plan.find((entry) => capabilityKey(entry.capability) === capabilityKey(candidate))
+      const planned = matching?.state === 'unused' ? matching : null
+      if (!planned) {
+        reply(request.id, {
+          ok: false,
+          code: matching ? 'maintenance_capability_used' : 'maintenance_capability_missing',
+          error: matching ? 'operation is already inflight, committed, or indeterminate' : 'operation is not in the exact maintenance plan',
+        })
+        return
+      }
+      planned.state = 'inflight'
+      planned.requestId = request.id
+      const controller = new AbortController()
+      pendingOperations.add(controller)
+      try {
+        const result = await clientMaintenanceOperation(token, candidate!, { signal: controller.signal, timeoutMs: Math.min(5_000, input.ttlMs) })
+        planned.state = result.outcome === 'committed' ? 'committed' : result.outcome === 'refused' ? 'unused' : 'indeterminate'
+        delete planned.requestId
+        reply(request.id, result)
+      } catch (error) {
+        planned.state = 'indeterminate'
+        delete planned.requestId
+        reply(request.id, { ok: false, code: 'maintenance_broker_failed', error: error instanceof Error ? error.message : String(error) })
+      } finally {
+        pendingOperations.delete(controller)
+      }
+    }
+    requestPipe.on('data', (chunk: Buffer | string) => {
+      pending += chunk.toString()
+      for (;;) {
+        const newline = pending.indexOf('\n')
+        if (newline < 0) break
+        const line = pending.slice(0, newline); pending = pending.slice(newline + 1)
+        if (!line) continue
+        brokerWork++
+        serial = serial.then(async () => {
+          try { await handle(JSON.parse(line) as BrokerRequest) }
+          catch (error) { reply(undefined, { ok: false, code: 'maintenance_broker_failed', error: error instanceof Error ? error.message : String(error) }) }
+        }).finally(() => { brokerWork-- })
+      }
+    })
+    const outcome = await Promise.race([
+      exited.then(([code, signal]) => ({ kind: 'exit' as const, code, signal })),
+      authorityFailure.catch((error) => ({ kind: 'lost' as const, error: error instanceof Error ? error : new Error(String(error)) })),
+    ])
+    if (outcome.kind === 'lost') {
+      authorityLost = true
+      closeAdmission()
+      await reapCommandGroup(child, closed)
+      throw outcome.error
+    }
+    const brokerIndeterminate = brokerWork > 0 || pendingOperations.size > 0 || pending.trim().length > 0
+    if (brokerIndeterminate) authorityLost = true
+    closeAdmission()
+    await serial
+    try { await reapCommandGroup(child, closed) }
+    catch (error) { authorityLost = true; throw error }
+    if (brokerIndeterminate) {
+      throw new Error('operator exited while a maintenance broker operation was indeterminate')
+    }
+    if (heartbeatFailure) {
+      authorityLost = true
+      throw heartbeatFailure
+    }
+    return outcome.code ?? (outcome.signal ? 1 : 0)
+  } finally {
+    if (heartbeat) clearInterval(heartbeat)
+    closeAdmission()
+    try { child?.stdio[3]?.destroy() } catch { /* child already closed */ }
+    try { child?.stdio[4]?.destroy() } catch { /* child already closed */ }
+    try { (child?.stdio as Array<Readable | Writable | null | undefined> | undefined)?.[5]?.destroy() } catch { /* child already closed */ }
+    if (releaseable && !released && !authorityLost) {
+      await clientMaintenanceRelease(token, epoch)
+      released = true
+    }
+  }
+}

package/spec-cli/src/materialize.ts

@@ -23,7 +23,7 @@ export type MaterializeResult = { contentHash: string; planted: MaterializedArti
 // a trigger. It turns the spec tree's surface nodes into the flat artifacts each consumer reads
 // cheaply, so a USER-self-launched claude/codex (no SpexCode process in the launch) gets the whole system via
 // harness-auto-discovered files: (1) the hook MANIFEST (our dispatcher reads it), (2) the CONTRACT — the
-// tracked docs guide (docs/AGENT_GUIDE.md) FOLLOWED BY the surface:system bodies — written WHOLE into each
+// surface:system plugin bodies (in name order) — written WHOLE into each
 // harness's contract file(s), (3) the thin SHIMS (every event → dispatch.sh), (4) the per-harness TRUST
 // (Codex's deterministic trusted_hash; Claude none). EVERY harness-specific fact is owned by the
 // [[harness-adapter]] (harness.ts) — this file just loops over HARNESSES.
@@ -192,13 +192,12 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   const manifest = join(rt, 'hooks-manifest')
   writeFileSync(manifest, compileManifest())
   record('hook manifest', manifest)
-  // (2) the contract = the tracked docs guide (the hand-written agent/contributor notes — the ONE piece of
-  //     in-tree prose) FOLLOWED BY the surface:system bodies (in name order), written WHOLE into EACH harness's
+  // (2) the contract = the surface:system plugin bodies (in name order), written WHOLE into EACH harness's
   //     contract file(s) + (3) each harness's thin shim → dispatch.sh + (4) its trust. All owned by the adapter.
-  const guidePath = join(proj, 'docs', 'AGENT_GUIDE.md')
-  const guide = existsSync(guidePath) ? readFileSync(guidePath, 'utf8').trim() : ''
-  const systemBodies = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean)
-  const contract = [guide, ...systemBodies].filter(Boolean).join('\n\n')
+  // ONE source, no per-project escape hatch: the contract IS the surface:system plugin bodies. A project's
+  // own hand-written prose is not folded in — repo-local notes belong in the harness file's own
+  // block-outside region (untracked, per-clone), and anything that must reach EVERY agent is a plugin node.
+  const contract = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean).join('\n\n')
   // WHICH harnesses to deliver into ([[harness-select]]): the spexcode.json `harnesses` set (default = every
   // native harness). resolveHarnessTargets FAILS LOUD on an illegal set (plugin+native, plugin w/o folder).
   const cfg = readConfig(mainCheckout(proj))

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

@@ -1,17 +1,46 @@
 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 type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+import { headlessTurnFailureShell, type DispatchResult, type HarnessDeliveryRecord } from './harness.js'
+import { shQuote } from './sh.js'
 
 const pexec = promisify(execFile)
+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))
+
+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',
+    `  ${headlessTurnFailureShell('opencode-headless', 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 ${headlessTurnFailureShell('opencode-headless')}; 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 +50,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 +87,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 +102,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 +149,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 +165,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

@@ -1,10 +1,12 @@
-import { createConnection, createServer, type Server, type Socket } from 'node:net'
+import { createServer, type Server, type Socket } from 'node:net'
 import { spawn, type ChildProcess } from 'node:child_process'
 import { mkdirSync, rmSync } from 'node:fs'
 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 ChildTurn = { process: ChildProcess; exited: Promise<number | null> }
@@ -14,8 +16,6 @@ const SPEX = join(PKG, 'bin', 'spex.mjs')
 const CONTROL_TIMEOUT_MS = 30_000
 const START_TIMEOUT_MS = 30_000
 
-const shQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
-
 /** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
 export const piHeadlessSock = (id: string) => join(tmpdir(), `spexcode-ph-${id}.sock`)
 
@@ -23,53 +23,11 @@ export function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: s
   return [shQuote(SPEX), 'internal', 'pi-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(piCmd), '--'].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) => {
-    let socket: Socket | undefined
-    let settled = false
-    let buffer = ''
-    const finish = (result: DispatchResult) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      socket?.destroy()
-      resolve(result)
-    }
-    const timer = setTimeout(() => finish({ ok: false, error: `pi-headless control timed out for session ${id}` }), CONTROL_TIMEOUT_MS)
-    try { socket = createConnection(piHeadlessSock(id)) } catch (error) {
-      finish({ ok: false, error: `pi-headless controller connect failed for session ${id}: ${(error as Error).message}` })
-      return
-    }
-    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 || 'pi-headless controller rejected the request' })
-      } catch (error) {
-        finish({ ok: false, error: `pi-headless returned an invalid control response: ${(error as Error).message}` })
-      }
-    })
-    socket.on('error', (error) => finish({ ok: false, error: `pi-headless controller unreachable for session ${id}: ${error.message}` }))
-    socket.on('close', () => finish({ ok: false, error: `pi-headless controller closed before confirming session ${id}` }))
-  })
-}
-
 export const deliverViaPiHeadless = (rec: HarnessDeliveryRecord, text: string) =>
-  controlRequest(rec.session, { type: 'deliver', text })
+  controlRequest(piHeadlessSock(rec.session), { type: 'deliver', text }, {
+    name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'pi-headless controller rejected the request',
+  })
 
 export class PiHeadlessController {
   private server: Server | null = null
@@ -111,9 +69,10 @@ export class PiHeadlessController {
       if (!this.server) return resolve()
       this.server.close(() => resolve())
     })
-    try { rmSync(this.socketPath, { force: true }) } catch { /* best-effort cleanup after close */ }
-    const { rvSock } = await import('./harness.js')
-    try { rmSync(rvSock(this.id), { force: true }) } catch { /* pi may already have removed it */ }
+    // same proof-before-removal rule as every other teardown (harness.ts unlinkSocks): a socket path is keyed
+    // by session id alone, so only a listener PROVEN dead is ours to unlink.
+    const { rvSock, unlinkSocks } = await import('./harness.js')
+    await unlinkSocks(this.socketPath, rvSock(this.id))
   }
 
   private accept(socket: Socket): void {
@@ -144,14 +103,12 @@ export class PiHeadlessController {
 
     // A live extension listener is an in-flight pi turn. The native steer path is parse-confirmed by the
     // shared rendezvous protocol. Only a proven absent listener may cold-wake a saved session.
-    const { deliverViaRendezvous, rendezvousListening } = await import('./harness.js')
-    const listener = await rendezvousListening(this.id)
-    if (listener === 'live') return deliverViaRendezvous(this.id, request.text)
-    if (listener === 'unproven') return { ok: false, error: `could not determine whether pi turn ${this.id} is live — prompt NOT delivered` }
-
-    if (this.child) await withTimeout(this.child.exited, 5_000, `previous pi-headless turn did not exit for session ${this.id}`)
-    await this.spawnTurn(request.text, true)
-    return { ok: true }
+    const { deliverViaSocketOrWake } = await import('./harness.js')
+    return deliverViaSocketOrWake(this.id, request.text, async () => {
+      if (this.child) await withTimeout(this.child.exited, 5_000, `previous pi-headless turn did not exit for session ${this.id}`)
+      await this.spawnTurn(request.text, true)
+      return { ok: true }
+    }, `could not determine whether pi turn ${this.id} is live — prompt NOT delivered`)
   }
 
   private async spawnTurn(text: string, resume: boolean): Promise<void> {
@@ -171,6 +128,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())