spexcode 0.4.3 → 0.5.0

package/spec-cli/src/harness.ts

@@ -9,6 +9,9 @@ import { fileURLToPath } from 'node:url'
 import { claudeSlashCommands, codexSlashCommands, opencodeSlashCommands, piSlashCommands, type SlashCommand } from './slash-commands.js'
 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 { opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js'
+import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless } from './pi-headless.js'
 import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
 import { git } from './git.js'
 
@@ -24,7 +27,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'
+export type HarnessId = 'claude' | 'codex' | 'opencode' | 'pi' | 'claude-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 —
@@ -41,6 +44,12 @@ export type PaneProbe = { panePid?: number; procs?: ProcTable; pidAlive?: boolea
 
 export interface Harness {
   readonly id: HarnessId
+  // 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 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
   // the lifecycle events this harness fires (drives the shim + the trust hashes). Claude binds the full set;
   // Codex's canonical hook event set (its `HookEventName` enum, codex 0.142.3) has no failed-stop and no
   // idle/attention event, so Codex has NO equivalent of StopFailure / Notification — a real harness difference,
@@ -144,6 +153,13 @@ export interface Harness {
   // (mid-turn, not queued for after the agent stops) or `turn/start`s a fresh turn when the thread is idle.
   // Returns ok=false with a reason that propagates to the API.
   deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>
+  // Hard-interrupt the current turn through the harness's native control plane. Optional because a harness
+  // without a confirmed native interrupt must refuse rather than emulate one with a signal or PTY key.
+  interrupt?(rec: HarnessDeliveryRecord): Promise<DispatchResult>
+  // Remove this harness's ephemeral runtime transport after stop/close. This is the runtime inverse of
+  // launch: rendezvous owners unlink rvSock, claude-headless unlinks its control socket, Codex owns no
+  // per-session socket. Product teardown calls only this adapter method.
+  cleanupRuntime(rec: HarnessLivenessRecord): void
   // the ONE pane state where this harness SWALLOWS a prompt that its delivery channel confirms (so no
   // socket-side check can see it): given the live pane text, return the loud human-readable refusal (naming
   // the recovery) or null when the pane can take a prompt. sendText captures the pane once and consults this
@@ -178,7 +194,13 @@ export interface Harness {
 // (non-2xx) and the CLI/dashboard. Defined here because it is the harness DELIVERY contract; sessions.ts
 // re-exports it for its existing importers.
 export type DispatchResult = { ok: boolean; error?: string }
-export type HarnessDeliveryRecord = { session: string; worktreePath?: string; harnessSessionId?: string | null; runtimeDir?: string }
+export type HarnessDeliveryRecord = {
+  session: string
+  worktreePath?: string
+  harnessSessionId?: string | null
+  runtimeDir?: string
+  launchCmd?: string | null
+}
 // the on-demand surface artifacts a materialize pass wrote, by node NAME — so clean() knows EXACTLY which
 // skill subdirs / agent files are SpexCode's to remove (name-scoped, never a blind wipe of a dir the user may
 // also populate). materialize passes the live skill/agent node names; clean reconstructs the same paths.
@@ -1079,6 +1101,8 @@ export function opencodeLaunchCommand(opencodeCmd = 'opencode'): string {
 
 export const claudeHarness: Harness = {
   id: 'claude',
+  headless: false,
+  messageStream: false,
   events: CLAUDE_EVENTS,
   ownsRendezvous: true,                              // reclaude opens the rendezvous control socket (prompt delivery + liveness)
   paneTitleIsSelfSummary: true,                      // claude writes its live task summary into the OSC pane title → headline derives from it
@@ -1101,6 +1125,7 @@ export const claudeHarness: Harness = {
   // dead-pane-reads-working bug). See rendezvousListening.
   liveness: (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) => (tmuxAlive && !!socketLive ? 'online' : 'offline'),
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
+  cleanupRuntime: (rec) => { try { rmSync(rvSock(rec.session), { force: true }) } catch { /* already gone */ } },
   // the TUI's sessions panel ("← for agents"): a reply injected here is parsed + enqueued to the PANEL context
   // and never drained (verified live: `queue-operation: enqueue` with no dequeue, no turn, daemon silent), so
   // the parse-confirmed delivery above would still report a false success into it. Matched on the panel's own
@@ -1113,8 +1138,29 @@ export const claudeHarness: Harness = {
   resumeArg: (rec) => `--resume ${rec.session}`,
 }
 
+// Claude headless is a separate harness, not a claude mode. Its materialize half is exactly Claude's and is
+// reused by object composition; the whole runtime half is replaced by the stream-json controller.
+export const claudeHeadlessHarness: Harness = {
+  ...claudeHarness,
+  id: 'claude-headless',
+  headless: true,
+  messageStream: true,
+  ownsRendezvous: false,
+  paneTitleIsSelfSummary: false,
+  launchCmd: (id, runtimeDir, cmd) => claudeHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), claudeBaseCmd(cmd)),
+  // Liveness is the intact record's property. A missing controller/child fails loudly at control time rather
+  // than turning an idle (no child) session into a speculative offline row.
+  liveness: () => 'online',
+  deliver: deliverViaClaudeHeadless,
+  interrupt: interruptClaudeHeadless,
+  cleanupRuntime: (rec) => { try { rmSync(claudeHeadlessSock(rec.session), { force: true }) } catch { /* already gone */ } },
+  deliveryBlockedBy: undefined,
+}
+
 export const codexHarness: Harness = {
   id: 'codex',
+  headless: false,
+  messageStream: false,
   events: CODEX_EVENTS,
   ownsRendezvous: false,                             // no reclaude daemon — liveness + prompts through the project app-server socket
   paneTitleIsSelfSummary: false,                     // codex's pane title is a spinner + the cwd folder name, NOT a task summary → headline uses the prompt
@@ -1177,6 +1223,7 @@ export const codexHarness: Harness = {
     return paneTreeRunsCodex(pane) ? 'online' : 'offline'
   },
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
+  cleanupRuntime: () => { /* project-scoped app-server is shared; no per-session transport to remove */ },
   // owned thread id → `--resume <id>` MARKER the codex launch script reads to resume that thread DIRECTLY (NOT
   // a tail handed to a bare `codex` — the script's final `codex … resume "$tid"` performs codex's own resume on
   // the owned id, the SAME conversation); none → empty tail → relaunch a FRESH thread on the same worktree/record.
@@ -1196,6 +1243,8 @@ export const codexHarness: Harness = {
 // one-run defence. See pi-harness.ts for the extension source + trust mechanics.
 export const piHarness: Harness = {
   id: 'pi',
+  headless: false,
+  messageStream: false,
   events: PI_EVENTS,
   ownsRendezvous: true,                              // the generated extension binds rvSock(id) and speaks the reclaude protocol
   paneTitleIsSelfSummary: false,                     // pi's pane title is not an agent-written task summary → headline uses the prompt preview
@@ -1220,13 +1269,37 @@ export const piHarness: Harness = {
   // socket the generated extension binds. socketLive is already probed for every windowed session.
   liveness: (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) => (tmuxAlive && !!socketLive ? 'online' : 'offline'),
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
+  cleanupRuntime: (rec) => { try { rmSync(rvSock(rec.session), { force: true }) } catch { /* already gone */ } },
   // reopen the SAME conversation: `--session <id>` resumes the exact session we pinned at launch and FAILS
   // LOUD when its file is gone (unlike `--session-id`, which would silently mint a fresh empty session).
   resumeArg: (rec) => `--session ${rec.session}`,
 }
 
+// pi-headless is an independent harness: its materialization surface is literally pi's, while a resident
+// controller owns non-interactive text-mode turns. Active turns steer through pi's rendezvous extension;
+// idle delivery cold-wakes the exact saved session with `--session` (never `--session-id`, which would create a
+// new conversation). The controller deliberately reports record-backed liveness, matching Claude headless.
+export const piHeadlessHarness: Harness = {
+  ...piHarness,
+  id: 'pi-headless',
+  headless: true,
+  messageStream: false,
+  paneTitleIsSelfSummary: false,
+  launchCmd: (id, runtimeDir, cmd) => piHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), piBaseCmd(cmd)),
+  liveness: () => 'online',
+  deliver: deliverViaPiHeadless,
+  cleanupRuntime: (rec) => {
+    try { rmSync(piHeadlessSock(rec.session), { force: true }) } catch { /* already gone */ }
+    try { rmSync(rvSock(rec.session), { force: true }) } catch { /* already gone */ }
+  },
+  deliveryBlockedBy: undefined,
+  resumeArg: (rec) => `--session ${rec.session}`,
+}
+
 export const opencodeHarness: Harness = {
   id: 'opencode',
+  headless: false,
+  messageStream: false,
   events: OPENCODE_EVENTS,
   // LITERALLY true: the generated plugin ([[opencode-harness]], opencode.ts) BINDS the per-session rendezvous
   // socket the launch env hands it and speaks the reply/repaint mini-protocol, so claude's deliver (atomic
@@ -1261,6 +1334,7 @@ export const opencodeHarness: Harness = {
   liveness: (_rec, tmuxAlive, _runtimeDir, pane, socketLive) =>
     (tmuxAlive && (!!socketLive || pane?.pidAlive === true) ? 'online' : 'offline'),
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
+  cleanupRuntime: (rec) => { try { rmSync(rvSock(rec.session), { force: true }) } catch { /* already gone */ } },
   // owned opencode session id → `--resume <id>` marker (the launch script re-attaches `--session <id>`, the
   // SAME conversation); never captured → `--continue` marker (opencode's own "last session in this directory",
   // which in a dedicated worktree is this worker's). The discriminator is sound for the same reason codex's
@@ -1268,8 +1342,32 @@ export const opencodeHarness: Harness = {
   resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : '--continue'),
 }
 
+// OpenCode headless is a separate harness, not an opencode mode. Its materialize half is exactly
+// opencodeHarness; only the one-turn runtime and its capability row differ.
+export const opencodeHeadlessHarness: Harness = {
+  ...opencodeHarness,
+  id: 'opencode-headless',
+  headless: true,
+  messageStream: false,
+  launchCmd: (_id, _runtimeDir, cmd) => opencodeHeadlessLaunchCommand(opencodeBaseCmd(cmd)),
+  // A sleeping native conversation is still addressable by its record. Transport breakage belongs to the
+  // next delivery, where the live rendezvous or pane wake reports it loudly.
+  liveness: () => 'online',
+  deliver: async (rec, text) => {
+    const probe = await rendezvousListening(rec.session)
+    if (probe === 'live') return deliverViaRendezvous(rec.session, text)
+    if (probe === 'unproven') {
+      return {
+        ok: false,
+        error: `opencode-headless rendezvous probe was inconclusive for session ${rec.session} - refusing to start a possibly duplicate turn`,
+      }
+    }
+    return spawnOpenCodeHeadlessTurn(rec, text, opencodeBaseCmd(rec.launchCmd ?? undefined), rvSock(rec.session))
+  },
+}
+
 // every adapter — materialize iterates this to write each harness's artifacts in one pass.
-export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness, opencodeHarness, piHarness]
+export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness, opencodeHarness, piHarness, claudeHeadlessHarness, opencodeHeadlessHarness, piHeadlessHarness]
 
 // the legacy/default adapter for old records and config defaults. New launches derive harness from a launcher.
 export const defaultHarness: Harness = claudeHarness
@@ -1286,20 +1384,31 @@ export function harnessById(id: string): Harness {
 // human-chosen name. `claude` and `codex` are NOT special built-ins — `spex init` SEEDS them as ordinary named
 // launchers (with the regular command path), so they are edited like any other. harness defaults to claude.
 // resolveLauncher throws fail-loud on an unknown name (a session must never silently launch under the wrong
-// auth) and validates the harness id. There is NO env-derived built-in fallback: the dropdown lists exactly
-// the config's real launchers.
-export type Launcher = { name: string; harness: string; cmd: string }
+// auth) and validates the harness id. There is NO env-derived built-in fallback: this registry lists exactly
+// the config's real launchers; dashboardLauncherList applies only the dashboard visibility projection.
+export type Launcher = { name: string; harness: string; cmd: string; headless: boolean }
 export type LauncherDefault = { default: string | null; error: string | null }
 
-// the configured named launchers from spexcode.json, as a stable name-sorted list (for the dashboard dropdown
-// + the CLI). Picking a launcher is the ONLY launch choice; the old separate harness pick is gone.
+// the complete configured named launchers from spexcode.json, as a stable name-sorted list (for CLI/session
+// resolution and downstream projections). Picking a launcher is the ONLY launch choice; the old separate
+// harness pick is gone.
 export function launcherList(root = mainCheckout()): Launcher[] {
   const m = readConfig(root).sessions?.launchers || {}
   return Object.keys(m)
-    .map((name) => ({ name, harness: m[name].harness || defaultHarness.id, cmd: m[name].cmd }))
+    .map((name) => {
+      const harness = harnessById(m[name].harness || defaultHarness.id)
+      return { name, harness: harness.id, cmd: m[name].cmd, headless: harness.headless }
+    })
     .sort((a, b) => a.name.localeCompare(b.name))
 }
 
+// The dashboard's visibility projection. It never removes a launcher from the complete config/CLI path;
+// it only narrows GET /api/settings for the New Session picker ([[launcher-visibility]]).
+export function dashboardLauncherList(root = mainCheckout()): Launcher[] {
+  const showHeadless = readConfig(root).dashboard?.showHeadlessLaunchers === true
+  return launcherList(root).filter((launcher) => showHeadless || !launcher.headless)
+}
+
 export const MISSING_DEFAULT_LAUNCHER_ERROR =
   'sessions.defaultLauncher is required for a launch without --launcher; set it in spexcode.json or spexcode.local.json (for example {"sessions":{"defaultLauncher":"claude"}})'
 
@@ -1326,7 +1435,6 @@ export function resolveLauncher(name: string, root = mainCheckout()): Launcher {
   const l = readConfig(root).sessions?.launchers?.[name]
   if (!l) throw new Error(`unknown launcher '${name}' (configured: ${launcherList(root).map((x) => x.name).join(', ') || 'none'})`)
   if (!l.cmd) throw new Error(`launcher '${name}' is missing cmd`)
-  const resolved = { name, harness: l.harness || defaultHarness.id, cmd: l.cmd }
-  harnessById(resolved.harness)   // validate the harness id fail-loud
-  return resolved
+  const harness = harnessById(l.harness || defaultHarness.id)   // validate the harness id fail-loud
+  return { name, harness: harness.id, cmd: l.cmd, headless: harness.headless }
 }

package/spec-cli/src/help.ts

@@ -202,6 +202,7 @@ edit the spec instead — same commit as the code.`,
 
 Control another session (all take SEL):
   spex session send <SEL> "<msg>"        deliver a message (fail-loud: a dead dispatch exits non-zero)
+  spex session interrupt <SEL>           hard-interrupt the current turn through native harness control
   spex session send <SEL> --keys "<keys>"
       LAST RESORT: raw nav-mode keystrokes to a TUI dialog ("Up Up Enter", C-/M-/S- combos). The raw
       key surface is UNSTABLE and can confirm dangerous dialogs — don't reach for it unless a plain
@@ -225,7 +226,7 @@ Human escape hatch:
                                          show --capture / send. LOCAL-only (fails loud on a remote backend).
 
 ${SEL_NOTE}
-Manager verbs that WRITE (send/rename/resume/stop/close/merge) are PROJECT-BOUND: a backend serving
+Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge) are PROJECT-BOUND: a backend serving
 another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.
 ${MENTION_NOTE}`,
     see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
@@ -360,6 +361,8 @@ Machine plumbing — called by generated hooks and launch scripts, never typed b
   nudge <node>      the post-merge hook prints the issue nudge for a merged node
   codex-launch <sock> <cwd> [prompt…]   backend-owned codex thread/start + first turn (launch script)
   codex-turn   <sock> <threadId> <text…>  fire a follow-up turn on an owned thread (tests/scripts)
+  claude-headless-run <id> <runtime> <cmd> -- <tail…>  resident stream-json controller (launch script)
+  pi-headless-run <id> <runtime> <cmd> -- <tail…>      resident pi text-mode controller (launch script)
 
 If you reached for one of these by hand, the porcelain you want is probably elsewhere: the trunk
 name also lives at GET /api/settings (.layout); sessions are driven with spex session new / session send;

package/spec-cli/src/index.ts

@@ -15,9 +15,10 @@ import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './graphCache.js'
 import { boardStream, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
-import { listSessions, sendText, rawKey, stopSession, closeSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, TMUX_SOCK } from './sessions.js'
+import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, TMUX_SOCK } from './sessions.js'
 import { superviseTimeline, readTimeline } from './session-timeline.js'
-import { defaultHarness, HARNESSES, launcherList, launcherDefault } from './harness.js'
+import { readSessionMessages, sessionMessageStream } from './message-stream.js'
+import { defaultHarness, HARNESSES, dashboardLauncherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
 import { putBlob } from '../../spec-eval/src/cache.js'
 import { fileHumanReading } from '../../spec-eval/src/filing.js'
@@ -175,11 +176,11 @@ app.post('/api/evidence', async (c) => {
 })
 // the SETTINGS read surface — one route for everything spexcode.json / spexcode.local.json resolves to:
 // `layout` (resolveLayout()'s main/worktrees/branch shape — the write-guard's project-identity probe reads
-// `.layout.main`) and the named launcher profiles ([[launcher-select]]) the New-Session picker
-// offers — `{ name, harness, cmd }`: the cmd is read-only display data for the picker (the dashboard sits
+// `.layout.main`) and the dashboard-visible launcher profiles ([[launcher-visibility]]) the New-Session picker
+// offers — `{ name, harness, cmd, headless }`: the cmd is read-only display data for the picker (the dashboard sits
 // behind the gateway auth; the browser can read but never edit config) — plus the configured `default` NAME
-// so the picker pre-selects the SAME
-// launcher a bare `spex session new` uses (the CLI/config default), instead of the alphabetically-first one,
+// so the picker pre-selects the SAME launcher a bare `spex session new` uses when that row is visible, else
+// its first visible row rather than a hidden headless default,
 // Missing defaultLauncher is returned as an actionable config error, not hidden by falling through to the
 // built-in `claude` launcher.
 // `tmuxSocket` is the `-L <name>` label our private tmux server runs under (a backend fact, env-overridable),
@@ -187,7 +188,7 @@ app.post('/api/evidence', async (c) => {
 // beside the blessed `spex session attach` command — the frontend never hardcodes the socket.
 app.get('/api/settings', async (c) => c.json({
   layout: await resolveLayout(),
-  launchers: launcherList(),
+  launchers: dashboardLauncherList(),
   tmuxSocket: TMUX_SOCK,
   ...launcherDefault(),
 }))
@@ -436,6 +437,13 @@ app.get('/api/sessions/:id/timeline', (c) => {
   const r = readTimeline(c.req.param('id'), Number.isFinite(limit) && limit > 0 ? limit : undefined)
   return r ? c.json(r) : c.json({ error: 'no such session' }, 404)
 })
+// An adapter may expose its native event log as the console's optional full-process drill-down. REST establishes
+// the complete ordered snapshot + byte cursor; SSE follows appends from that cursor (or Last-Event-ID on reconnect).
+app.get('/api/sessions/:id/messages', (c) => {
+  const r = readSessionMessages(c.req.param('id'))
+  return r ? c.json(r) : c.json({ error: 'no such session' }, 404)
+})
+app.get('/api/sessions/:id/messages/stream', (c) => sessionMessageStream(c))
 // the session RECORD detail (`spex session show`): the board row (status · node · branch · launcher · …)
 // plus the full originating prompt (the row itself carries only the preview). One id-addressed read backs
 // the CLI's show; 404 for an unknown id.
@@ -567,6 +575,10 @@ app.post('/api/sessions/:id/input', async (c) => {
 // soft stop: kill the agent's tmux + socket but KEEP the worktree (resumable). Distinct from close, which
 // removes the worktree. {ok:false} = no such session.
 app.post('/api/sessions/:id/stop', async (c) => c.json({ ok: await stopSession(c.req.param('id')) }))
+app.post('/api/sessions/:id/interrupt', async (c) => {
+  const result = await interruptSession(c.req.param('id'))
+  return c.json(result, result.ok ? 200 : 502)
+})
 app.post('/api/sessions/:id/close', async (c) => c.json({ ok: await closeSession(c.req.param('id')) }))
 // set (or clear, with a blank) a session's display-name override; persists to the session's global record
 // (`session.json`) so it survives a restart. Unknown id → 404. That record sits INSIDE the watched store, but

package/spec-cli/src/layout.ts

@@ -27,6 +27,7 @@ type Config = {
     apiUrl?: string                // the per-project backend the board proxies to (read frontend-side; see api-endpoint)
     title?: string                 // override for the browser-tab name (default: the repo-root basename; see tab-title)
     icon?: string                  // project identity icon: a picker preset id; existing emoji/Iconify/URL values remain supported ([[identity-config]])
+    showHeadlessLaunchers?: boolean // include headless harness profiles in the dashboard New Session picker (default false; [[launcher-visibility]])
   }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)

package/spec-cli/src/message-stream.ts

@@ -0,0 +1,147 @@
+import { closeSync, fstatSync, openSync, readSync, watch, type FSWatcher } from 'node:fs'
+import { streamSSE } from 'hono/streaming'
+import type { Context } from 'hono'
+
+import { readAliasedRawRecord, sessionArtifactPath, sessionStoreDir } from './layout.js'
+
+export type NativeMessageEvent = Record<string, unknown>
+export type MessageEnvelope = { cursor: number; event: NativeMessageEvent }
+export type MessageBatch = { messages: MessageEnvelope[]; cursor: number }
+
+function fileBytes(path: string, cursor: number): Buffer {
+  let fd: number
+  try { fd = openSync(path, 'r') }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && cursor === 0) return Buffer.alloc(0)
+    throw error
+  }
+  try {
+    const size = fstatSync(fd).size
+    if (cursor > size) throw new Error(`messages.ndjson cursor ${cursor} is past file size ${size}`)
+    const bytes = Buffer.alloc(size - cursor)
+    let read = 0
+    while (read < bytes.length) {
+      const count = readSync(fd, bytes, read, bytes.length - read, cursor + read)
+      if (count === 0) break
+      read += count
+    }
+    return read === bytes.length ? bytes : bytes.subarray(0, read)
+  } finally { closeSync(fd) }
+}
+
+// Parse only newline-terminated records. The cursor is a byte offset, not a character count, so an SSE
+// reconnect resumes correctly even when a native event contains non-ASCII text.
+export function readMessageBatchFile(path: string, requestedCursor = 0): MessageBatch {
+  const cursor = Number.isSafeInteger(requestedCursor) && requestedCursor >= 0 ? requestedCursor : 0
+  const bytes = fileBytes(path, cursor)
+
+  const messages: MessageEnvelope[] = []
+  let lineStart = 0
+  while (lineStart < bytes.length) {
+    const newline = bytes.indexOf(0x0a, lineStart)
+    if (newline < 0) break
+    const nextCursor = cursor + newline + 1
+    const text = bytes.subarray(lineStart, newline).toString('utf8')
+    let event: unknown
+    try { event = JSON.parse(text) }
+    catch (error) {
+      throw new Error(`invalid messages.ndjson event at byte ${cursor + lineStart}: ${(error as Error).message}`)
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event)) {
+      throw new Error(`invalid messages.ndjson event at byte ${cursor + lineStart}: expected a JSON object`)
+    }
+    messages.push({ cursor: nextCursor, event: event as NativeMessageEvent })
+    lineStart = newline + 1
+  }
+  return { messages, cursor: cursor + lineStart }
+}
+
+// null means the id is unknown or is not a governed session. A known session with no adapter output yet is
+// an ordinary empty stream: the adapter may create messages.ndjson after the browser has connected.
+export function readSessionMessages(id: string, cursor = 0): MessageBatch | null {
+  const record = readAliasedRawRecord(id)
+  if (!record?.governed) return null
+  return readMessageBatchFile(sessionArtifactPath(record.session_id, 'messages.ndjson'), cursor)
+}
+
+type StreamSignal = 'append' | 'ping' | 'abort' | 'watch-error'
+
+function signalQueue() {
+  const queued: StreamSignal[] = []
+  let waiter: ((signal: StreamSignal) => void) | null = null
+  const push = (signal: StreamSignal) => {
+    if (signal === 'append' && queued.includes('append')) return
+    if (waiter) {
+      const resolve = waiter
+      waiter = null
+      resolve(signal)
+    } else queued.push(signal)
+  }
+  const next = (): Promise<StreamSignal> => {
+    const ready = queued.shift()
+    return ready ? Promise.resolve(ready) : new Promise((resolve) => { waiter = resolve })
+  }
+  return { push, next }
+}
+
+function cursorParam(value: string | undefined): number | null {
+  if (!value || !/^\d+$/.test(value)) return null
+  const cursor = Number(value)
+  return Number.isSafeInteger(cursor) ? cursor : null
+}
+
+// GET /api/sessions/:id/messages/stream — the append-follow half of [[message-stream]]. REST establishes a
+// complete snapshot + cursor; this stream starts there. Standard SSE ids let EventSource reconnect through
+// Last-Event-ID even though its original URL still carries the older cursor.
+export function sessionMessageStream(c: Context): Response {
+  const record = readAliasedRawRecord(c.req.param('id') as string)
+  if (!record?.governed) return c.json({ error: 'no such session' }, 404)
+
+  const lastEventCursor = cursorParam(c.req.header('Last-Event-ID'))
+  const queryCursor = cursorParam(c.req.query('cursor'))
+  const startCursor = lastEventCursor ?? queryCursor ?? 0
+  const id = record.session_id
+
+  return streamSSE(c, async (stream) => {
+    const signals = signalQueue()
+    let aborted = false
+    let watcher: FSWatcher | null = null
+    const ping = setInterval(() => signals.push('ping'), 10_000)
+    ping.unref()
+    stream.onAbort(() => { aborted = true; signals.push('abort') })
+
+    try {
+      watcher = watch(sessionStoreDir(id), { persistent: false }, (_event, filename) => {
+        if (filename == null || String(filename) === 'messages.ndjson') signals.push('append')
+      })
+      watcher.on('error', () => signals.push('watch-error'))
+
+      let cursor = startCursor
+      await stream.writeSSE({ event: 'ready', data: JSON.stringify({ cursor }) })
+      const flush = async () => {
+        const batch = readSessionMessages(id, cursor)
+        if (!batch) throw new Error('session closed')
+        cursor = batch.cursor
+        for (const message of batch.messages) {
+          await stream.writeSSE({ event: 'message', id: String(message.cursor), data: JSON.stringify(message) })
+        }
+      }
+      await flush()
+
+      while (!aborted) {
+        const signal = await signals.next()
+        if (signal === 'abort') break
+        if (signal === 'watch-error') throw new Error('messages.ndjson watcher failed')
+        if (signal === 'ping') await stream.writeSSE({ event: 'ping', data: 'x' })
+        else await flush()
+      }
+    } catch (error) {
+      if (!aborted) {
+        await stream.writeSSE({ event: 'stream-error', data: JSON.stringify({ error: (error as Error).message }) }).catch(() => {})
+      }
+    } finally {
+      clearInterval(ping)
+      watcher?.close()
+    }
+  })
+}

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

@@ -0,0 +1,95 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+
+const pexec = promisify(execFile)
+
+const shQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+// 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 {
+  const script = [
+    command,
+    '__spex_rc=$?',
+    '[ "$__spex_rc" -eq 0 ] || printf "[spex opencode-headless] turn exited rc=%s\\n" "$__spex_rc" >&2',
+    'exec "${SHELL:-/bin/sh}"',
+  ].join('\n')
+  return `bash -lc ${shQuote(script)} spexcode-opencode-headless`
+}
+
+// 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[] {
+  return [
+    `__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}" "$@"; }',
+  ]
+}
+
+export function opencodeHeadlessLaunchCommand(opencodeCmd = 'opencode'): string {
+  const script = [
+    ...runPrelude(opencodeCmd),
+    'if [ "${1:-}" = "--resume" ]; then',
+    '  export SPEXCODE_OPENCODE_RESUME_ID="$2"',
+    '  unset SPEXCODE_OPENCODE_CONTINUE',
+    '  __spex_run --session "$2"',
+    'elif [ "${1:-}" = "--continue" ]; then',
+    '  unset SPEXCODE_OPENCODE_RESUME_ID',
+    '  export SPEXCODE_OPENCODE_CONTINUE=1',
+    '  __spex_run --continue',
+    'elif [ -n "${1:-}" ]; then',
+    '  unset SPEXCODE_OPENCODE_RESUME_ID SPEXCODE_OPENCODE_CONTINUE',
+    '  __spex_run "$1"',
+    'else',
+    '  __spex_run',
+    'fi',
+  ].join('\n')
+  return turnHome(script)
+}
+
+export function opencodeHeadlessWakeCommand(opencodeCmd: string, harnessSessionId: string | null | undefined, text: string): string {
+  const resume = harnessSessionId ? [
+    `export SPEXCODE_OPENCODE_RESUME_ID=${shQuote(harnessSessionId)}`,
+    'unset SPEXCODE_OPENCODE_CONTINUE',
+    `__spex_run --session ${shQuote(harnessSessionId)} ${shQuote(text)}`,
+  ] : [
+    'unset SPEXCODE_OPENCODE_RESUME_ID',
+    'export SPEXCODE_OPENCODE_CONTINUE=1',
+    `__spex_run --continue ${shQuote(text)}`,
+  ]
+  return turnHome([...runPrelude(opencodeCmd), ...resume].join('\n'))
+}
+
+export async function spawnOpenCodeHeadlessTurn(
+  rec: HarnessDeliveryRecord,
+  text: string,
+  opencodeCmd: string,
+  socketPath: string,
+): Promise<DispatchResult> {
+  if (!rec.worktreePath) return { ok: false, error: `opencode-headless session ${rec.session} has no worktree path - turn NOT started` }
+  const tmuxSock = process.env.SPEXCODE_TMUX || 'spexcode'
+  const args = [
+    '-L', tmuxSock, 'respawn-pane', '-k', '-t', rec.session, '-c', rec.worktreePath,
+    '-e', `SPEXCODE_SESSION_ID=${rec.session}`,
+    '-e', 'CLAUDE_BG_BACKEND=daemon',
+    '-e', `CLAUDE_BG_RENDEZVOUS_SOCK=${socketPath}`,
+  ]
+  for (const name of ['SPEXCODE_HOME', 'CODEX_HOME']) {
+    const value = process.env[name]
+    if (value) args.push('-e', `${name}=${value}`)
+  }
+  args.push(opencodeHeadlessWakeCommand(opencodeCmd, rec.harnessSessionId, text))
+  try {
+    await pexec('tmux', args, { timeout: 5_000 })
+    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}` }
+  }
+}