spexcode 0.4.1 → 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.
@@ -421,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
@@ -756,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
@@ -846,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 }
 }
 
 // ---------------------------------------------------------------------------------------------------------
@@ -909,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')
@@ -922,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
@@ -986,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) {
@@ -996,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',
@@ -1030,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,
@@ -1097,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) },
@@ -1121,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
@@ -1135,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)

package/spec-cli/src/help.ts

@@ -14,7 +14,8 @@
 type Entry = { line: string; body: string; see?: string }
 
 const SEL_NOTE = `SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
-accepts any of the three; on the list verbs (ls/watch), none (or @all) means every session.`
+accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
+none (or @all) means every session.`
 
 const ROUTING_NOTE = `Backend routing: every backend-touching verb accepts --api <url> (--port <n> = localhost sugar) to name
 its backend explicitly — the flag always wins. Bare, it resolves: worker env / the cwd project's live
@@ -24,9 +25,9 @@ const DOT_NOTE = `\`.\` as a node argument means the node THIS worktree works on
 node/<id> branch). One-shot payload reads (graph · spec search · session ls/show/review · eval ls ·
 scenario ls · issue ls/show/links) take --json.`
 
-const MENTION_NOTE = `Mentions: @session · [[node]] · @new work in ANY prompt, issue, or remark body — text passed as a CLI
-arg included. [[node]] names the topic node; @session hands the text to that live agent; @new spawns a
-fresh worker on the thread's node.`
+const MENTION_NOTE = `Mentions: @session · [[node]] · @new / @new:<launcher> work in ANY prompt, issue, or remark body —
+text passed as a CLI arg included. [[node]] names the topic node; @session hands the text to that live agent;
+@new spawns a fresh worker on the thread's node (bare = configured default; :<launcher> = that named profile).`
 
 const ENTRIES: Record<string, Entry> = {
   // ── project verbs (implicit object = this project) ────────────────────────
@@ -44,12 +45,14 @@ derived status, title, and attention badges (drift:N · stale:N · issues:N · g
     see: 'spex spec search (find one node by intent) · spex session ls (just the sessions, as a table)',
   },
   init: {
-    line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  [--preset name]',
-    body: `Usage: spex init [dir=cwd] [--preset default]
+    line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  --harness <ids> [--preset name]',
+    body: `Usage: spex init [dir=cwd] --harness <id[,id]|plugin:<folder>> [--preset default]
 
 Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .plugins plugins), plants
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
-shims). Additive — never overwrites your files. --preset picks the .plugins plugin tier (cumulative).
+shims). --harness is REQUIRED — the explicit choice of which harnesses materialize delivers into
+(stamped as spexcode.json "harnesses"; only their launchers are seeded); a pre-existing "harnesses"
+field satisfies it. Additive — never overwrites your files. --preset picks the .plugins plugin tier (cumulative).
 Footprint is fixed: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
 a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex guide footprint).`,
     see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex spec lint (adoption TODO)',
@@ -69,24 +72,26 @@ hooks yet (CI, a cloud agent): generated and excluded, the artifacts never arriv
     see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
   },
   doctor: {
-    line: 'doctor                diagnose whether the workflow actually reaches this agent  [--contract|--conflicts]',
-    body: `Usage: spex doctor                per-layer coverage report: preconditions · git-hook floor · contract ·
-                                  hooks + handler existence · backend — for every harness materialize delivers to
+    line: 'doctor                diagnose spec health and whether the workflow reaches this agent  [--contract|--conflicts]',
+    body: `Usage: spex doctor                spec-health findings + delivery report: preconditions · git-hook floor ·
+                                  contract · hooks + handler existence · backend · footprint
        spex doctor --contract     print the composed surface:system text any agent here reads
        spex doctor --conflicts    detect double-delivery (loose artifacts beside the managed ones)
 
-Run it when a worker seems to be missing its contract or hooks — it names the broken layer and the
-repair, instead of you diffing materialized files by hand.`,
-    see: 'spex materialize (re-materialize the artifacts doctor checks)',
+Bare doctor is the opt-in, read-only health surface: it reports altitude and breadth findings without
+putting them in the lint gate, then audits workflow delivery. Run it directly or let the tidy workflow
+consume the same visible diagnosis.`,
+    see: 'spex spec lint (deterministic graph/contract gate) · spex materialize (repair delivery artifacts)',
   },
   uninstall: {
-    line: 'uninstall [dir]       surgical inverse of init — removes generated artifacts, keeps your .spec  [--hooks]',
+    line: 'uninstall [dir]       remove all derived artifacts + local state; preserve tracked intent  [--hooks]',
     body: `Usage: spex uninstall [dir=cwd] [--hooks]
 
-Removes every SpexCode-GENERATED artifact (harness shims · contract blocks · trust entries ·
-exclude/ignore blocks · global store · plugin bundle) and never your .spec/.plugins data or your own
-prose. Git hooks are preserved unless --hooks.`,
-    see: 'spex init (re-adopt later — your .spec survives)',
+Removes all SpexCode-derived wiring and project-local state: contract blocks, harness shims,
+generated skills/agents, plugin bundles, trust/filter/exclude entries, and the global per-project
+store. Your tracked intent (.spec including .plugins, plus spexcode.json) and surrounding user prose
+are preserved. Git hooks remain unless --hooks; that flag removes only unmodified canonical copies.`,
+    see: 'spex init (re-adopt later — your tracked intent survives)',
   },
   serve: {
     line: 'serve [api|ui]        api (default) = the backend :8787 · ui = the dashboard :5173 on top of it',
@@ -106,6 +111,30 @@ projects coexist on one host). Loopback-only by default; --host 0.0.0.0 opens it
 still plain HTTP with no gate, so bind wide only on a network you trust.`,
     see: 'GET /health (backend liveness probe)',
   },
+  dashboard: {
+    line: 'dashboard             ONE dashboard for every project you serve — no --api-port pairing  [--port N=5173]',
+    body: `Usage: spex dashboard [--port N=5173] [--host H=127.0.0.1]
+
+The HOST gateway: serves the built dashboard once and routes to EVERY backend the current user runs —
+the multi-project hub engine plus the host registry on top. It continuously reconciles the per-project
+endpoint records each \`spex serve\` publishes (validating each against the live backend's /api/instance
+identity), keeps a durable known-project catalog, and proxies each project's API + SSE + terminal
+socket under /p/<projectId>/* — the project is named in the path, so nothing is "current" and no
+pairing flag exists.
+
+Admin surface (hub-authorized: implicit from loopback until an admin password is set, then cookie
+sessions): GET /projects (the validated list + gating state) · GET /projects/stream (SSE) ·
+GET /projects/browse?path=… (read-only host folder picker) · POST /projects {root, initGit?, init?}
+(explicit setup, then register) · GET|PUT /projects/<id>/config (raw portable
+spexcode.json, revision-guarded) · POST /projects/<id>/init|doctor|serve
+(run the real \`spex init\`/\`spex doctor\`, or start an offline project's backend, detached — a
+backend never depends on this gateway staying up) · PUT|DELETE /projects/admin-password and
+/projects/<id>/password (the gates). A gated project answers /p/<id>/login with the designed page.
+
+Loopback-only by default; --host widens the bind — the admin surface stays locked to loopback until
+an admin password exists, and ungated projects serve open.`,
+    see: 'spex serve (each project\'s backend) · spex serve ui (explicit one-backend pairing)',
+  },
 
   // ── the noun drawers ──────────────────────────────────────────────────────
   spec: {
@@ -131,7 +160,7 @@ commit since the spec's version touched an ANCHORED unit's lines, unacked — th
 drift; same-file selectors OR'd, one error naming the hit selectors) · one-govern (a node
 governs >1 DISTINCT file) · living (a "## vN" changelog heading) · id-format (an
 id char outside the whitelist — ascii [a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a
-leaf id reused) · mention (a [[id]] naming no node). Warns: altitude · breadth · coverage · drift
+leaf id reused) · mention (a [[id]] naming no node). Warns: coverage · drift
 (UNANCHORED drift — always advisory, never blocks; on a scoped file's MISS, \`lint.scopedCodeMiss:
 "ignore"\` may silence it) · anchor (anchoring a type) · related-drift (a scoped related row warns
 per selector HIT, misses silent) · owners (whole-file governors only; scoped don't count) ·
@@ -147,10 +176,10 @@ edit the spec instead — same commit as the code.`,
   session: {
     line: 'session <verb>        the worktree state machine: new · ls · watch · wait · review · merge · send · …',
     body: `Manager verbs (dispatch, monitor, land):
-  spex session new "<prompt>" [--prompt-file <path>|-] [--node <id>] [--launcher <name>]
+  spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>]
       Launch a worker in its own node worktree. Give it ONLY its task — the dev-flow contract
-      reaches it through the materialized system prompt. --node (or the prompt's first [[id]],
-      same effect) binds the session to that node. --prompt-file <path>|- carries a long prompt
+      reaches it through the materialized system prompt. The prompt's first [[id]] mention binds
+      the session to that node. --prompt-file <path>|- carries a long prompt
       without shell quoting (exclusive with the inline prompt). Then MONITOR it (wait/watch below).
   spex session ls [SEL…] [--status a,b] [--json]        one-shot table of living sessions
   spex session watch [SEL…] [--as NAME] [--idle] [--interval N=5]
@@ -202,15 +231,16 @@ ${MENTION_NOTE}`,
     see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
   },
   eval: {
-    line: 'eval <verb>           the measurement system: add · ls · scenario ls · lint · ok · retract · clean',
+    line: 'eval <verb>           the measurement system: add · ls · scenario ls · matrix · lint · ok · retract · clean',
     body: `Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
                     [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
        spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
        spex eval ls --session <SEL> [--json]           a session's aggregate: its changed nodes' scores
        spex eval ls --session <SEL> --export [--open | --out <path>]
        spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; bare = every node
+       spex eval matrix <launcher> [--node <id>] [--rows k1,k2]   the harness live-behavior matrix
        spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
-       spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest reading
+       spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest measurement
        spex eval retract [<node>|.] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
        spex eval clean [--keep-latest | --all]         GC the content-addressed evidence cache
 
@@ -227,16 +257,22 @@ HTML artifact (diff · evidence inlined · gates) for CI/sharing.
 scenario ls — the DECLARED contracts (name · tags · normalized test reference · latest verdict), no evals: bare lists every
 measurable node's scenarios; --unmeasured keeps only the never-measured — the blind-spot worklist.
 
+matrix — run the eight-row harness live-behavior matrix against a REAL dispatched session of the named
+launcher (the harness-adapter acceptance rule, defined once in spec-eval/src/matrix.ts): it syncs the
+rows into the \`<harness>-harness\` node's eval.md scenarios, drives one worker through undeclared-stop ·
+pretooluse-block · ask-note · deliver-steer · resume · liveness · commit-gate · close-residue, and files
+a per-row measurement with its evidence transcript. A new harness needs only its launcher + spec node.
+
 lint — the measurement layer's findings: malformed eval.md (eval-schema) · unmeasured (eval-missing) ·
 stale (eval-drift) · orphaned remark tracks (eval-dangling) · governed source with no eval.md
 (eval-coverage — the same name and shape as spec lint's coverage, one rule per layer) · over-owned
 files (eval-owners). --changed scopes to the nodes THIS branch touched. spec lint's errors block
 commits; eval lint is PURE ADVISORY, always exit 0 — a measurement gap never blocks anyone.
 
-ok — the human's reviewed-and-agreed mark on the scenario's LATEST reading: an appended, monotonic
-sign-off bound to that one immutable reading (a newer reading or staleness releases it on its own —
+ok — the human's reviewed-and-agreed mark on the scenario's LATEST measurement: an appended, monotonic
+sign-off bound to that one immutable measurement (a newer measurement or staleness releases it on its own —
 no un-ok exists). The evals feed default-hides a fresh, ok'd scenario; a governed session is refused
-(an agent's judgment on a reading is a remark, never a self-blessing).
+(an agent's judgment on a measurement is a remark, never a self-blessing).
 
 retract — the sanctioned undo for a botched filing: APPENDS a retraction event (traceable, never
 deletes a line); the previous eval becomes latest again, or the scenario honestly returns to
@@ -363,6 +399,7 @@ Project verbs (implicit object = this project)
   ${ENTRIES.doctor.line}
   ${ENTRIES.uninstall.line}
   ${ENTRIES.serve.line}
+  ${ENTRIES.dashboard.line}
 
 Noun drawers
   ${ENTRIES.spec.line}