spexcode 0.4.1 → 0.5.0

package/spec-cli/src/harness.ts

@@ -6,7 +6,12 @@ import { createConnection, type Socket } from 'node:net'
 import { execFile, execFileSync } from 'node:child_process'
 import { promisify } from 'node:util'
 import { fileURLToPath } from 'node:url'
-import { claudeSlashCommands, codexSlashCommands, type SlashCommand } from './slash-commands.js'
+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'
 
@@ -22,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'
+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 —
@@ -39,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,
@@ -54,7 +65,6 @@ export interface Harness {
   // instead of showing the folder name. This is the ONLY harness branch in the headline path: the capability
   // is data on the adapter, not an `if (codex)` in sessions.ts.
   readonly paneTitleIsSelfSummary: boolean
-
   // --- launch / sessionId ---
   // the base agent command. Claude: `claude …`; Codex starts a project-scoped app-server and launches the
   // visible TUI with `--remote` pointed at it. `cmd` is the SESSION's persisted launcher command
@@ -101,16 +111,18 @@ export interface Harness {
   // ONLY place agent-surface divergence lives (the skillDir analog). Claude reads .claude/agents/<name>.md;
   // Codex has no file-discovered agent-definition primitive, so it returns null and materialize skips it.
   agentDir(proj: string): string | null
-  // the shim payload: the settings/hooks JSON binding every event → the dispatcher (harness id baked in), and
-  // the per-event command string (shared with the trust writer so they hash identically).
-  shim(dispatch: string, spex: string): { json: string; cmd: (e: string) => string }
+  // the shim payload: `content` is whatever artifact THIS harness auto-discovers to wire every event to the
+  // dispatcher (harness id baked in) — a settings/hooks JSON for claude/codex, a generated event-bus PLUGIN
+  // for opencode, a generated TypeScript EXTENSION for pi — plus the per-event command string (shared with
+  // the trust writer so they hash identically).
+  shim(dispatch: string, spex: string): { content: string; cmd: (e: string) => string }
   // make a dispatched/self-launched agent run the hooks with zero prompts. Codex writes PROJECT trust — and, on
   // a binary without `--dangerously-bypass-hook-trust`, per-hook trusted_hash blocks — into the GLOBAL
   // ~/.codex/config.toml (codex's security model: trust is global-only). PROJECT trust is UNCONDITIONAL: it
   // ENABLES the project config layer so codex discovers our hooks at all, a tier bypass_hook_trust does NOT
   // cover. Claude is a no-op (it relies on folder-trust). `cmdFor` MUST be the same per-event command the shim
   // emitted.
-  writeTrust(proj: string, cmdFor: (e: string) => string): void
+  writeTrust(proj: string, cmdFor: (e: string) => string): readonly string[]
 
   // --- the `/` menu ---
   // the slash-command list, computed the way THIS harness computes its own `/` menu.
@@ -141,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
@@ -175,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.
@@ -421,7 +446,7 @@ export function codexSupportsBypassHookTrust(binary: string): boolean {
   bypassProbe.set(binary, ok)
   return ok
 }
-export function codexLaunchCommand(_id: string, codexCmd = 'codex --yolo', serverCmd?: string, dir = runtimeRoot()): string {
+export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?: string, dir = runtimeRoot()): 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
@@ -756,13 +781,18 @@ export function codexTurn(sock: string, threadId: string, text: string, cwd?: st
 // rollout just lands a few seconds LATE (not lost). Handing the id to `resume` before then is the "no rollout
 // found for thread id" failure, so codex-launch WAITS for the rollout to land before it trusts the id.
 const codexSessionsDir = () => join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions')
-// does a rollout file for this thread id exist yet? Rollouts are grouped by date, so scan only the newest few
-// day-dirs (lexical order = chronological on zero-padded YYYY/MM/DD) — clock-agnostic and cheap on a big history.
+// does a rollout file for this thread id exist yet? Rollouts are grouped by date; walk day-dirs newest-first
+// (lexical order = chronological on zero-padded YYYY/MM/DD) and return on first hit — the fresh rollout lives in
+// the newest real dir, so the common case reads one dir. The walk is exhaustive, never capped at "the newest few
+// dirs": future-dated junk under sessions/ (a test once planted 2099/12/* in the real CODEX_HOME) sorts above
+// every real day-dir, and a cap let three such dirs mask ALL real rollouts — every codex launch then failed
+// "persisted no rollout" with the rollout sitting on disk. A full walk is a readdir per day-dir — still cheap.
 export function codexRolloutExists(threadId: string, root = codexSessionsDir()): boolean {
   const kids = (d: string) => { try { return readdirSync(d).sort().reverse() } catch { return [] as string[] } }
-  const days: string[] = []
-  for (const y of kids(root)) { for (const m of kids(join(root, y))) { for (const d of kids(join(root, y, m))) { days.push(join(root, y, m, d)); if (days.length >= 3) break } if (days.length >= 3) break } if (days.length >= 3) break }
-  return days.some((d) => kids(d).some((f) => f.includes(threadId)))
+  for (const y of kids(root)) for (const m of kids(join(root, y))) for (const d of kids(join(root, y, m))) {
+    if (kids(join(root, y, m, d)).some((f) => f.includes(threadId))) return true
+  }
+  return false
 }
 // poll until the thread's rollout lands (resume-ready) or the budget runs out. Returns false on timeout so the
 // caller can FAIL LOUD instead of handing `resume` / the stored record a non-resumable id. The budget must
@@ -846,11 +876,11 @@ export function removeManagedBlock(file: string, comment: readonly [string, stri
 // the shim for one harness: every event → `SPEX='…' bash <dispatch> <harnessId> <Event>`. The harness id is
 // baked in so dispatch.sh can export SPEXCODE_HARNESS (the detector for the shell side). SPEX is inherited by
 // the cli-needing handlers.
-function buildShim(id: HarnessId, events: readonly string[], dispatch: string, spex: string): { json: string; cmd: (e: string) => string } {
+function buildShim(id: HarnessId, events: readonly string[], dispatch: string, spex: string): { content: string; cmd: (e: string) => string } {
   const cmd = (e: string) => `SPEX='${spex}' bash ${dispatch} ${id} ${e}`
   const hooks: Record<string, unknown> = {}
   for (const e of events) hooks[e] = [{ hooks: [{ type: 'command', command: cmd(e) }] }]
-  return { json: JSON.stringify({ hooks }, null, 2), cmd }
+  return { content: JSON.stringify({ hooks }, null, 2), cmd }
 }
 
 // ---------------------------------------------------------------------------------------------------------
@@ -909,7 +939,7 @@ function stripCodexTrustFor(cur: string, proj: string, hooksJson: string): strin
 // leave a DUPLICATE key (which breaks codex config loading) and self-heals a config that already carried one.
 // Scoped to THIS project path; never touches the user's other config. CODEX_HOME respected for testability.
 // (`events` may be empty for a trust-only stamp in tests.)
-export function writeCodexTrust(proj: string, events: readonly string[], cmdFor: (e: string) => string): void {
+export function writeCodexTrust(proj: string, events: readonly string[], cmdFor: (e: string) => string): string {
   const home = process.env.CODEX_HOME || join(homedir(), '.codex')
   const file = join(home, 'config.toml')
   const hooksJson = join(proj, '.codex', 'hooks.json')
@@ -922,6 +952,7 @@ export function writeCodexTrust(proj: string, events: readonly string[], cmdFor:
   const cleaned = stripCodexTrustFor(existsSync(file) ? readFileSync(file, 'utf8') : '', proj, hooksJson)
   if (!existsSync(home)) mkdirSync(home, { recursive: true })
   writeFileSync(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`)
+  return file
 }
 
 // the inverse of writeCodexTrust: strip THIS project's codex trust from the GLOBAL config.toml — the SAME
@@ -986,7 +1017,9 @@ function cleanHarness(h: Harness, proj: string, arts: HarnessArtifacts): void {
 // (tmux/ps couldn't report) is not-live, and the caller's boot grace still shows a fresh launch — whose tree
 // may not yet contain codex — as 'starting', not 'offline'.
 const CODEXISH = /^(codex|node)/i   // the vendored binary ('codex', 'codex-x86_64…') or the CLI's node runtime
-export function paneTreeRunsCodex(pane?: PaneProbe): boolean {
+// the shared descendant-tree walk: does a process matching `re` live BELOW the pane pid? (The pane pid itself
+// is the shell, so descendants only.) Pure over the caller's one ps snapshot.
+function paneTreeRuns(pane: PaneProbe | undefined, re: RegExp): boolean {
   if (!pane?.panePid || !pane.procs?.size) return false
   const kids = new Map<number, number[]>()
   for (const [pid, p] of pane.procs) {
@@ -996,27 +1029,80 @@ export function paneTreeRunsCodex(pane?: PaneProbe): boolean {
   while (stack.length) {
     const pid = stack.pop()!
     const comm = pane.procs.get(pid)?.comm ?? ''
-    if (CODEXISH.test(comm.slice(comm.lastIndexOf('/') + 1))) return true   // basename — macOS ps comm is a full path
+    if (re.test(comm.slice(comm.lastIndexOf('/') + 1))) return true   // basename — macOS ps comm is a full path
     const c = kids.get(pid); if (c) stack.push(...c)
   }
   return false
 }
+export function paneTreeRunsCodex(pane?: PaneProbe): boolean { return paneTreeRuns(pane, CODEXISH) }
+
+// ONE whole-box pid→(ppid, comm) snapshot (a single `ps` spawn) — the table paneTreeRuns walks. Owned here
+// (beside its consumers) and shared with sessions.ts's liveSnapshot, so the two probe layers can never parse
+// ps differently. A failed/timed-out ps returns an empty table: the callers read that as not-provably-running.
+export async function procSnapshot(timeoutMs = 4000): Promise<ProcTable> {
+  const t: ProcTable = new Map()
+  let out = ''
+  try { ({ stdout: out } = await pexec('ps', ['-eo', 'pid=,ppid=,comm='], { timeout: timeoutMs, killSignal: 'SIGKILL' })) } catch { return t }
+  for (const line of out.split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line)
+    if (m) t.set(Number(m[1]), { ppid: Number(m[2]), comm: m[3].trim() })
+  }
+  return t
+}
 
 // ---------------------------------------------------------------------------------------------------------
 // the two implementations.
 
 const CLAUDE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'] as const
 const CODEX_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'] as const
+// the five claude-shaped events pi's generated extension SYNTHESIZES from its own lifecycle (session_start →
+// SessionStart, input → UserPromptSubmit, tool_call → PreToolUse, tool_result → PostToolUse, agent_end +
+// agent_settled → Stop). pi has no idle/attention or failed-stop event → no Notification/StopFailure, same
+// real gap as codex.
+const PI_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'] as const
 
 // the resolved base launcher command per harness (the wrapper that sets the config-dir env), shared by
-// launchCmd and baseCmd so the two never diverge: the launcher's pinned `cmd` wins. The bare default is only
-// the fallback for a truly-old record with NO pinned cmd and NO launcher name — there is no env/config-field
-// resolution, because claude/codex are ordinary named launchers now ([[launcher-select]]), resolved by name.
-const claudeBaseCmd = (cmd?: string) => cmd || 'claude --dangerously-skip-permissions'
-const codexBaseCmd = (cmd?: string) => cmd || 'codex --yolo'
+// launchCmd and baseCmd so the two never diverge: the launcher's pinned `cmd` wins. The plain command is only
+// the fallback for a truly-old record with NO pinned cmd and NO launcher name — compatibility must preserve
+// the harness's normal permission model, never silently introduce an automatic-permission flag. There is no
+// env/config-field resolution because launchers are ordinary named config entries ([[launcher-select]]).
+const claudeBaseCmd = (cmd?: string) => cmd || 'claude'
+const codexBaseCmd = (cmd?: string) => cmd || 'codex'
+const piBaseCmd = (cmd?: string) => cmd || 'pi'   // pi runs tools without permission prompts — no yolo flag exists or is needed
+const opencodeBaseCmd = (cmd?: string) => cmd || 'opencode'
+
+// @@@ opencodeLaunchCommand - the tail-branching launch script (the codex marker pattern, minus any server:
+// opencode is a per-session process like claude). The caller-appended tail ("$@") is EITHER one single-quoted
+// prompt arg (a NEW launch → `--prompt`), or a resume marker from opencodeHarness.resumeArg: `--resume <id>`
+// re-attaches the owned opencode session (`--session <id>`, the SAME conversation), `--continue` re-attaches
+// the worktree's last session when no id was ever captured (the plugin failed before its first event). A new
+// launch's tail can never BE a literal marker (it's one quoted prompt), so the branch is unambiguous.
+export function opencodeLaunchCommand(opencodeCmd = 'opencode'): string {
+  const script = [
+    `if [ "\${1:-}" = "--resume" ]; then`,
+    // the marker carries the owned session id — export it so the plugin can seed rootSession at load: a
+    // resumed session re-fires NO bus event until poked, so without this the rendezvous daemon rejects
+    // every delivery (resume-continuity A-side: continuity ✓, steerability ✗).
+    `  export SPEXCODE_OPENCODE_RESUME_ID="$2"`,
+    `  exec ${opencodeCmd} --session "$2"`,
+    `elif [ "\${1:-}" = "--continue" ]; then`,
+    // no owned id to seed — mark the continue-resume so the plugin knows to ask the SDK for the
+    // reattached session (scoped to this marker so a FRESH launch can never adopt a stale session).
+    `  export SPEXCODE_OPENCODE_CONTINUE=1`,
+    `  exec ${opencodeCmd} --continue`,
+    `elif [ -n "\${1:-}" ]; then`,
+    `  exec ${opencodeCmd} --prompt "$1"`,
+    `else`,
+    `  exec ${opencodeCmd}`,
+    `fi`,
+  ].join('\n')
+  return `bash -lc ${shQuote(script)} spexcode-opencode`
+}
 
 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
@@ -1030,7 +1116,7 @@ export const claudeHarness: Harness = {
   skillDir: (proj) => join(proj, '.claude', 'skills'),
   agentDir: (proj) => join(proj, '.claude', 'agents'),
   shim: (dispatch, spex) => buildShim('claude', CLAUDE_EVENTS, dispatch, spex),
-  writeTrust: () => { /* Claude relies on folder-trust — nothing to write */ },
+  writeTrust: () => [],                            // Claude relies on folder-trust — no artifact to report
   removeTrust: () => { /* Claude wrote no trust — nothing to strip */ },
   clean(proj, arts) { cleanHarness(this, proj, arts) },
   slashCommands: claudeSlashCommands,
@@ -1039,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
@@ -1051,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
@@ -1097,7 +1205,7 @@ export const codexHarness: Harness = {
   //       the prompt and the worker runs unattended. bypass_hook_trust stays on `thread/start` + the resume flag
   //       as DEFENCE for the non-resume paths (and if a version bump makes a hash mismatch, the app-server
   //       thread still runs the hooks); it does not REPLACE the hashes here.
-  writeTrust: (proj, cmdFor) => writeCodexTrust(mainCheckout(proj), CODEX_EVENTS, cmdFor),
+  writeTrust: (proj, cmdFor) => [writeCodexTrust(mainCheckout(proj), CODEX_EVENTS, cmdFor)],
   // trust is keyed by the MAIN checkout (where the codex shim materializes) — strip it at the same key.
   removeTrust: (proj) => removeCodexTrust(mainCheckout(proj)),
   clean(proj, arts) { cleanHarness(this, proj, arts) },
@@ -1115,14 +1223,151 @@ 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.
   resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : ''),
 }
 
+// @@@ 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
+// hook binding (its lifecycle surface is the in-process extension API), so the shim is a GENERATED TypeScript
+// extension (.pi/extensions/spexcode.ts, run natively by pi) that forwards five claude-shaped events to
+// dispatch.sh AND binds this session's rendezvous socket itself (sessions.ts already exports
+// CLAUDE_BG_RENDEZVOUS_SOCK to every ownsRendezvous launch) speaking the reclaude line protocol — so
+// deliverViaRendezvous and the socket-listener liveness work UNCHANGED. Trust: pi gates project-local
+// extensions behind saved per-directory trust (~/.pi/agent/trust.json), so writeTrust stamps the main
+// checkout there (the nearest-parent lookup covers nested worktrees) and the launch carries `--approve` as
+// 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
+  launchCmd: (_id, _rt, cmd) => `${piBaseCmd(cmd)} --approve`,   // --approve = one-run project trust (belt to writeTrust's braces)
+  baseCmd: piBaseCmd,
+  sessionIdArg: (id) => `--session-id ${id}`,        // caller pins the exact session id, claude-style (created if missing)
+  sessionEnvVar: 'PI_SESSION_ID',                    // exported by the generated extension at session_start; tool subprocesses inherit it
+  shimFile: (proj) => join(proj, '.pi', 'extensions', 'spexcode.ts'),
+  worktreeHookAnchor: () => null,                    // the extension lives in the worktree and self-anchors, like claude
+  contractFiles: (proj) => [join(proj, 'AGENTS.md')],   // pi auto-loads AGENTS.md context files (shared with codex — writeManagedBlock is idempotent)
+  skillDir: (proj) => join(proj, '.pi', 'skills'),   // Agent Skills standard dirs, discovered after project trust
+  agentDir: () => null,                              // pi has no file-discovered sub-agent primitive — materialize skips it
+  shim: (dispatch, spex) => ({
+    content: piExtensionSource(dispatch, spex),
+    cmd: (e: string) => `SPEX='${spex}' bash ${dispatch} pi ${e}`,   // what the extension actually spawns, for parity with buildShim
+  }),
+  writeTrust: (proj) => [writePiTrust(mainCheckout(proj))], // trust keys on the MAIN checkout; nearest-parent lookup covers worktrees
+  removeTrust: (proj) => removePiTrust(mainCheckout(proj)),
+  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  slashCommands: piSlashCommands,
+  // claude's exact liveness: the window is up AND a live LISTENER answers on the rendezvous socket — the
+  // 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
+  // parse-confirmed write) and socket-listener liveness are reused verbatim — no opencode transport code.
+  ownsRendezvous: true,
+  paneTitleIsSelfSummary: false,                     // opencode's TUI title is not the agent's live task self-summary → headline uses the prompt
+  launchCmd: (_id, _rt, cmd) => opencodeLaunchCommand(opencodeBaseCmd(cmd)),   // the tail-branching script (prompt vs --resume/--continue marker)
+  baseCmd: opencodeBaseCmd,
+  sessionIdArg: () => '',                            // opencode mints its own session id; the plugin's first event reports it back (opencode-capture)
+  // opencode exports NO per-session env var to its tool subprocesses (probed, 1.18.3). Identity flows through
+  // the launch-injected SPEXCODE_SESSION_ID — honest here because each opencode TUI is a per-session process
+  // (no codex-style shared-server contamination). This var is therefore never set; envSessionId's
+  // SPEXCODE_SESSION_ID tier resolves the record.
+  sessionEnvVar: 'OPENCODE_SESSION_ID',
+  // the "shim" is a generated opencode PLUGIN in the worktree's own tree — opencode auto-loads project plugins
+  // by walking the cwd, so like claude it self-anchors and needs no root-checkout rewrite or worktree anchor.
+  shimFile: (proj) => join(proj, '.opencode', 'plugins', 'spexcode.ts'),
+  worktreeHookAnchor: () => null,
+  contractFiles: (proj) => [join(proj, 'AGENTS.md')],   // opencode reads AGENTS.md natively (same file codex owns; the managed block is idempotent across writers)
+  skillDir: (proj) => join(proj, '.opencode', 'skills'),
+  agentDir: (proj) => join(proj, '.opencode', 'agents'),
+  // content = the plugin source; cmd = the SAME per-event command the plugin bakes into dispatch calls, so
+  // any consumer that hashes/inspects commands sees one truth (trust is a no-op here regardless).
+  shim: (dispatch, spex) => ({ content: opencodePluginSource(dispatch, spex), cmd: (e) => `SPEX='${spex}' bash ${dispatch} opencode ${e}` }),
+  writeTrust: () => [],                            // permission policy stays with the launcher command; no trust artifact to report
+  removeTrust: () => { /* nothing was written */ },
+  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  slashCommands: opencodeSlashCommands,
+  // online iff the window is up AND the agent answers on a channel: PREFER the rendezvous socket listener
+  // (the plugin is alive), FALL BACK to the launch-registered agent.pid (kill-0) so a plugin that failed to
+  // load still reads honestly from the process signal instead of a false offline.
+  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
+  // is: a NEW launch's tail is always ONE single-quoted prompt arg, never a literal marker.
+  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]
+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
@@ -1135,23 +1380,35 @@ export function harnessById(id: string): Harness {
 }
 
 // --- named launcher profiles ([[launcher-select]]) ----------------------------------------------------------
-// a launcher = a `{ harness, cmd }` pair in spexcode.json's `sessions.launchers`, keyed by a 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 }
+// a launcher = a `{ harness, cmd }` entry in spexcode.json's `sessions.launchers`, keyed by a
+// 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: 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"}})'
 
@@ -1178,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 }
 }