spexcode 0.4.0 → 0.4.3

package/spec-cli/src/harness.ts

@@ -6,7 +6,9 @@ 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 { runtimeRoot, mainCheckout, readConfig } from './layout.js'
 import { git } from './git.js'
 
@@ -22,7 +24,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'
 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 —
@@ -54,7 +56,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 +102,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.
@@ -133,13 +136,21 @@ export interface Harness {
   // grace lives in the caller (sessions.ts liveness), so a still-booting pane reads starting, not offline.
   liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline'
   // deliver a follow-up prompt to a LIVE session and report whether it landed. claude: through the rendezvous
-  // control socket — OPTIMISTIC-after-liveness (loud failure when the socket is missing/dead or the write can't
-  // flush; once the reply line flushes to a live socket it returns ok, without waiting for an application ack —
-  // see replyViaSocket). codex: JSON-RPC on the same app-server WebSocket the
+  // control socket — an ATOMIC reply+repaint chunk whose `repaint-done` proves the reply was PARSED; a close
+  // before it proves a concurrent connect kicked the chunk (the daemon is single-connection) → resend; a wall
+  // expiry on a still-open connection is a busy-not-lost agent → optimistic ok (see replyViaSocket). codex:
+  // JSON-RPC on the same app-server WebSocket the
   // visible TUI uses — it reads the thread live and either `turn/steer`s the message INTO an in-progress turn
   // (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>
+  // 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
+  // BEFORE delivering; absent on harnesses with no such state (codex delivery ignores the pane). claude: the
+  // TUI's sessions panel ("← for agents") enqueues an injected reply to the panel context and never drains it
+  // — verified live: parsed + enqueued, no dequeue, no turn, daemon silent.
+  deliveryBlockedBy?(paneText: string): string | null
   // --- materialize: clean (the inverse of write — [[harness-select]] prunes a deselected harness) ---
   // clean is the EXACT inverse of materialize's per-harness write: SURGICALLY remove ONLY SpexCode's own
   // artifacts — the managed contract block (sentinels), the generated shim file, the trust block, and the
@@ -161,11 +172,11 @@ export interface Harness {
 }
 
 // a prompt-dispatch outcome. ok=true means delivery is confirmed at the layer that harness proves it: claude at
-// the TRANSPORT/liveness layer (the reply line flushed to a live rendezvous socket — see replyViaSocket for why
-// it is OPTIMISTIC-after-liveness, not a round-trip ack); codex at the application layer (the app-server accepted
-// `turn/steer`/`turn/start`). `error` carries a human-readable reason that propagates to the API route (non-2xx)
-// and the CLI/dashboard. Defined here because it is the harness DELIVERY contract; sessions.ts re-exports it for
-// its existing importers.
+// the DAEMON-PARSE layer (the atomic reply+repaint chunk answered `repaint-done`, or the wall expired on a
+// still-open connection — busy, not lost; see replyViaSocket); codex at the application layer (the app-server
+// accepted `turn/steer`/`turn/start`). `error` carries a human-readable reason that propagates to the API route
+// (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 }
 // the on-demand surface artifacts a materialize pass wrote, by node NAME — so clean() knows EXACTLY which
@@ -252,50 +263,84 @@ function shQuote(s: string): string {
 const PKG = fileURLToPath(new URL('..', import.meta.url))
 const SPEX = join(PKG, 'bin', 'spex.mjs')
 
-// @@@ replyViaSocket - OPTIMISTIC-after-liveness delivery: connect to the LIVE rendezvous socket and WRITE the
-// `{type:reply}\n` line; once that line FLUSHES to the socket with no immediate transport error, the reply is on
-// the wire and claude submits it the moment it yields the event loop — so we return ok:true right there. We do
-// NOT wait for an application-level acceptance ack. The old code wrote a `{type:repaint}` probe after the reply
-// and waited up to 2500ms for a `{type:repaint-done}` to CONFIRM the reply was processed; the ordering barrier is
-// sound one-way (repaint-done ⟹ delivered) but its ABSENCE is NOT proof of non-delivery — a mid-turn/BUSY claude
-// can't answer the probe within the wall, so a message that actually landed reported a COMMON, misleading false
-// failure. The delivery confirmation therefore lives at the TRANSPORT/liveness layer, not the application layer:
-// deliverViaRendezvous already gates on the socket's existence (liveness), and here the FREE, INSTANT transport
-// signals — a connect that throws, a socket 'error' (ECONNREFUSED / EPIPE), or a 'close' BEFORE the write flushes —
-// are still reported as real failures (they cost no waiting). What we knowingly give up is detection of the narrow
-// alive-but-wedged / reply-rejected / shutting-down cases: a rare silent drop, recoverable because the supervisor
-// sees the worker never transition. That tradeoff is the deliberate contract now — see [[harness-adapter]].
-// Never throws.
-function replyViaSocket(sock: string, text: string): Promise<DispatchResult> {
+// @@@ replyViaSocket - ATOMIC parse-confirmed delivery. The daemon is SINGLE-CONNECTION: a new connect
+// `destroy()`s the previous socket, discarding any received-but-not-yet-parsed line with it — and our own
+// `rendezvousListening` liveness probe IS such a connect, fired for every session on every board snapshot. So
+// the previous optimistic write (return ok once the reply line flushed) LOST prompts whenever a probe landed in
+// the write→parse window, a window that widens exactly when claude is busy mid-turn (field: dashboard messages
+// recorded `sent` with no trace in the claude transcript; measured 2/10 lost under a 20ms probe hammer). The
+// daemon parses a chunk's complete lines in ONE synchronous loop, so writing `{type:reply}` + `{type:repaint}`
+// as ONE chunk makes the pair indivisible — a kick loses BOTH or NEITHER — and the outcome decidable from this
+// connection alone:
+//   `repaint-done` arrives  → the reply line before it was parsed (in-order barrier) → ok, CONFIRMED.
+//   'close' before it       → the chunk was never parsed (kicked by a concurrent connect) → resolve kicked:true
+//                             so deliverViaRendezvous RESENDS — a proven loss, so the retry cannot duplicate.
+//   wall expires, conn open → a busy event loop is DELAYING, not losing (the 2500ms-wall lesson: ack absence is
+//                             NOT non-delivery) → ok, OPTIMISTIC — never a false failure on a busy worker.
+//   `reply-rejected`/`auth-rejected`/`shutting-down` → loud failure, not retried.
+// Other daemon lines (heartbeat, state patches) are ignored. Never throws.
+type ReplyOutcome = DispatchResult & { kicked?: boolean }
+function replyViaSocket(sock: string, text: string, wallMs = 10_000): Promise<ReplyOutcome> {
   return new Promise((resolve) => {
     let settled = false
     let c: ReturnType<typeof createConnection>
-    const done = (r: DispatchResult) => {
+    const done = (r: ReplyOutcome) => {
       if (settled) return
       settled = true
+      clearTimeout(wall)
       try { c?.destroy() } catch { /* */ }
       resolve(r)
     }
+    const wall = setTimeout(() => done({ ok: true }), wallMs)
     try {
       c = createConnection({ path: sock })
     } catch (e) {
       done({ ok: false, error: `rendezvous socket connect threw: ${String(e)}` })
       return
     }
-    c.on('error', (e: NodeJS.ErrnoException) => done({ ok: false, error: `rendezvous socket connect failed: ${e?.code || String(e)}` }))
-    c.on('close', () => done({ ok: false, error: 'rendezvous connection closed before the prompt was written' }))
-    // write the reply line; the write callback fires once it flushes to the live socket → optimistic ok. An
-    // immediate transport 'error'/'close' beats the callback and reports the real failure (done is idempotent).
-    c.on('connect', () => c.write(JSON.stringify({ type: 'reply', text }) + '\n', () => done({ ok: true })))
+    // ECONNRESET/EPIPE are the KICK surfacing as an error: the daemon destroy()s the previous connection the
+    // moment a new one connects, and destroying a socket with OUR chunk still unread raises RST — whereas a
+    // parsed chunk answers repaint-done (readable even after a later close) before any clean FIN. So both codes
+    // PROVE the chunk was never parsed → retryable, same as the clean pre-parse close. ECONNREFUSED/ENOENT
+    // (daemon gone) stay loud.
+    c.on('error', (e: NodeJS.ErrnoException) => {
+      const code = e?.code || String(e)
+      const kicked = code === 'ECONNRESET' || code === 'EPIPE'
+      done({ ok: false, ...(kicked ? { kicked } : {}), error: `rendezvous socket error: ${code} — prompt NOT delivered` })
+    })
+    c.on('close', () => done({ ok: false, kicked: true, error: 'rendezvous connection was closed before the daemon parsed the prompt (kicked by a concurrent connect)' }))
+    c.on('connect', () => c.write(JSON.stringify({ type: 'reply', text }) + '\n' + JSON.stringify({ type: 'repaint' }) + '\n'))
+    let buf = ''
+    c.on('data', (d) => {
+      buf += d.toString('utf8')
+      let nl
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl)
+        buf = buf.slice(nl + 1)
+        let type = ''
+        try { type = (JSON.parse(line) as { type?: string })?.type ?? '' } catch { continue }
+        if (type === 'repaint-done') return done({ ok: true })
+        if (type === 'reply-rejected' || type === 'auth-rejected') return done({ ok: false, error: `rendezvous daemon rejected the prompt (${type}) — prompt NOT delivered` })
+        if (type === 'shutting-down') return done({ ok: false, error: 'agent is shutting down — prompt NOT delivered' })
+      }
+    })
   })
 }
 // claude's deliver: the pre-write LIVENESS gate — fail loud BEFORE attempting the socket if it isn't there (a
-// clearer message than a raw connect error, and the delivery's confirmation layer: socket present = agent alive).
-// Then inject the reply optimistically via replyViaSocket (no round-trip ack).
-function deliverViaRendezvous(id: string, text: string): Promise<DispatchResult> {
+// clearer message than a raw connect error, and the delivery's confirmation layer: socket present = agent
+// alive). Then the atomic parse-confirmed write; a KICKED outcome is a proven whole-chunk loss, so it resends
+// (bounded attempts + jitter so re-collision with the probe cadence is unlikely); exhausted retries fail loud.
+const DELIVER_ATTEMPTS = 3
+export async function deliverViaRendezvous(id: string, text: string, wallMs?: number): Promise<DispatchResult> {
   const sock = rvSock(id)
-  if (!existsSync(sock)) return Promise.resolve({ ok: false, error: `no rendezvous control socket for session ${id} (socketless/old session, or the agent is offline) — prompt NOT delivered` })
-  return replyViaSocket(sock, text)
+  if (!existsSync(sock)) return { ok: false, error: `no rendezvous control socket for session ${id} (socketless/old session, or the agent is offline) — prompt NOT delivered` }
+  let last: ReplyOutcome = { ok: false, error: 'not attempted' }
+  for (let attempt = 1; attempt <= DELIVER_ATTEMPTS; attempt++) {
+    last = await replyViaSocket(sock, text, wallMs)
+    if (last.ok || !last.kicked) return { ok: last.ok, ...(last.error ? { error: last.error } : {}) }
+    await new Promise((r) => setTimeout(r, 60 + Math.random() * 140))
+  }
+  return { ok: false, error: `rendezvous delivery was kicked by concurrent connects ${DELIVER_ATTEMPTS}× — prompt NOT delivered, retry the send` }
 }
 
 type JsonRpc = { id?: number; method?: string; params?: unknown; result?: unknown; error?: { code?: number; message?: string } }
@@ -379,7 +424,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
@@ -714,13 +759,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
@@ -804,11 +854,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 }
 }
 
 // ---------------------------------------------------------------------------------------------------------
@@ -867,7 +917,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')
@@ -880,6 +930,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
@@ -944,7 +995,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) {
@@ -954,24 +1007,75 @@ 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',
@@ -988,7 +1092,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,
@@ -997,6 +1101,15 @@ 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),
+  // 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
+  // strings — the new-session composer placeholder, or its footer key hints together (either alone could drift
+  // across claude versions; requiring the footer PAIR keeps a prose false-positive unlikely).
+  deliveryBlockedBy: (paneText) =>
+    paneText.includes('describe a task for a new session') || (paneText.includes('enter to return') && paneText.includes('space to reply'))
+      ? 'the claude TUI is focused on its sessions panel ("← for agents"), which silently swallows injected prompts — press Enter in the session terminal to return to the composer, then resend'
+      : null,
   resumeArg: (rec) => `--resume ${rec.session}`,
 }
 
@@ -1046,7 +1159,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) },
@@ -1070,8 +1183,93 @@ export const codexHarness: Harness = {
   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',
+  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),
+  // 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}`,
+}
+
+export const opencodeHarness: Harness = {
+  id: 'opencode',
+  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),
+  // 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'),
+}
+
 // 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]
 
 // the legacy/default adapter for old records and config defaults. New launches derive harness from a launcher.
 export const defaultHarness: Harness = claudeHarness
@@ -1084,16 +1282,17 @@ 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.
+// 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: the dropdown lists exactly
+// the config's real launchers.
 export type Launcher = { name: string; harness: string; cmd: string }
 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 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.
 export function launcherList(root = mainCheckout()): Launcher[] {
   const m = readConfig(root).sessions?.launchers || {}
   return Object.keys(m)