spexcode 0.1.5 → 0.2.0

package/spec-cli/src/harness.ts

@@ -1,9 +1,9 @@
-import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs'
+import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir, tmpdir } from 'node:os'
 import { createHash, randomBytes } from 'node:crypto'
 import { createConnection, type Socket } from 'node:net'
-import { execFile } from 'node:child_process'
+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'
@@ -24,6 +24,11 @@ import { tsxBin } from './tsx-bin.js'
 
 export type HarnessId = 'claude' | 'codex'
 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}`) plus one whole-box pid→(ppid, comm) table (a single `ps` spawn).
+// The adapter that cares (codex) walks the pane pid's descendants in that table; claude ignores it.
+export type ProcTable = Map<number, { ppid: number; comm: string }>
+export type PaneProbe = { panePid?: number; procs?: ProcTable }
 
 export interface Harness {
   readonly id: HarnessId
@@ -44,9 +49,19 @@ export interface Harness {
   readonly paneTitleIsSelfSummary: boolean
 
   // --- launch / sessionId ---
-  // the base agent command (env-overridable for tests). Claude: `claude …`; Codex starts a project-scoped
-  // app-server and launches the visible TUI with `--remote` pointed at it.
-  launchCmd(id: string, runtimeDir?: string): string
+  // the base agent command. Claude: `claude …`; Codex starts a project-scoped app-server and launches the
+  // visible TUI with `--remote` pointed at it. `cmd`, when given, is the SESSION's persisted launcher command
+  // ([[launcher-select]]) and OVERRIDES the ambient env→config→default resolution — so a session created under a
+  // named launcher keeps that exact command (and auth) on resume, never silently reverting to the global
+  // default. Omitted → the unnamed default resolution (env-overridable, for tests + old records).
+  launchCmd(id: string, runtimeDir?: string, cmd?: string): string
+  // the RESOLVED base launcher command alone — the wrapper/binary that carries the agent's config-dir env
+  // (claude `CLAUDE_CONFIG_DIR`, codex `CODEX_HOME`), WITHOUT the per-launch script built around it. `cmd`,
+  // when given, wins; else the ambient env→config→default resolution. The launch owner PINS this on the record
+  // at creation so a resume replays the EXACT launcher that created the conversation — never re-resolving
+  // against a since-changed default, which would point `--resume` at the wrong config dir and lose the
+  // transcript ([[launcher-select]], the resume-launcher-pin). launchCmd builds its invocation ON TOP of this.
+  baseCmd(cmd?: string): string
   // the flag that pins the session id at launch. Claude lets the caller choose (`--session-id <id>`); Codex
   // assigns its own, so there is nothing to pass (the id is captured/resumed afterwards).
   sessionIdArg(id: string): string
@@ -56,16 +71,37 @@ export interface Harness {
   // --- materialize: shim + contract + trust ([[harness-delivery]]) ---
   // the auto-discovered hook shim file for this harness (.claude/settings.json vs .codex/hooks.json).
   shimFile(proj: string): string
+  // a LINKED WORKTREE's extra shim copy — the worktree-side `.codex` hook file that ANCHORS codex's project
+  // config layer, or null when the harness needs none. codex-rs only builds a project config layer (and thus
+  // only DISCOVERS a worktree thread's hooks) for a dir in [cwd..project_root] that contains a `.codex/`
+  // directory; it then REWRITES that layer's hooks-config folder to the ROOT checkout (root_checkout_hooks_-
+  // folder_for_dir), so the shim CONTENT is still read from `shimFile` at the main checkout. But with the codex
+  // shim living ONLY at the main checkout, a linked worktree has NO `.codex/` at all → codex anchors no layer →
+  // the rewritten root hooks are never visited → ZERO hooks fire (bypass_hook_trust can't help: it only rescues
+  // an untrusted HANDLER inside an already-discovered layer, it never creates one). So codex ALSO writes its
+  // shim into the worktree's own `.codex/hooks.json` purely to anchor the layer (the rewrite ignores its
+  // content, reading the root's — and a codex that DIDN'T rewrite would read this identical shim, so it is
+  // correct either way). Claude: null — its shim already lives IN the worktree (`.claude/settings.json`) and
+  // self-anchors; it has no root-checkout rewrite. Non-worktree (proj == main checkout): null — `shimFile`
+  // already wrote `.codex/hooks.json` there.
+  worktreeHookAnchor(proj: string): string | null
   // the contract file(s) the `surface: system` block is folded into. Claude: ./CLAUDE.md; Codex: ONLY ./AGENTS.md.
   contractFiles(proj: string): string[]
   // the dir this harness auto-discovers skills from, or null if it has no skill primitive — the ONLY place skill-surface divergence lives.
   skillDir(proj: string): string | null
+  // the dir this harness auto-discovers sub-agent definitions from, or null if it has no agent primitive — the
+  // 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 }
-  // make a user-self-launched agent run the hooks with zero prompts. Codex writes a deterministic trusted_hash
-  // into the GLOBAL ~/.codex/config.toml (codex's security model: trust is global-only); Claude is a no-op
-  // (it relies on folder-trust). `cmdFor` MUST be the same per-event command the shim emitted.
+  // 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
 
   // --- the `/` menu ---
@@ -73,21 +109,38 @@ export interface Harness {
   slashCommands(): SlashCommand[]
 
   // --- runtime: liveness + prompt delivery ([[harness-delivery]]) ---
-  // is this session's agent process up? The caller passes in the tmux-window presence it already computed
-  // (one tmux snapshot for the whole list — see sessions.ts liveTmux), and the adapter adds ONLY its own
-  // channel check. claude: online iff the tmux window is up AND its reclaude rendezvous socket exists (the
-  // socket is the truth claude is alive — the pane command is the wrapper/shell while claude runs as a child).
-  // codex: online iff the tmux window is up AND the project-scoped app-server socket exists (one socket per
-  // PROJECT, shared by every worktree's thread); the per-session window presence is the session signal, the
-  // socket is a project control plane, not session identity.
-  liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string): 'online' | 'offline'
+  // is this session's agent process up? The caller passes the runtime facts it already computed in ONE
+  // snapshot (see sessions.ts liveSnapshot): the window's presence, a PaneProbe — the pane's root pid plus one
+  // whole-box process table — AND `socketLive`, whether a CONNECT to this session's rendezvous socket found a
+  // live listener (the caller probes all windowed sessions once per snapshot). The adapter adds only its own
+  // channel check. claude: online iff the window is up AND its reclaude rendezvous socket has a live LISTENER
+  // (`socketLive` — a connect that a live claude accepts and a stale socket FILE refuses; claude IGNORES the
+  // pane probe). codex: online iff the window is up AND a codex-ish process (`codex` by any
+  // name, or the `node` its CLI runs under) is live in the pane pid's DESCENDANT tree — NOT the pane's
+  // foreground command name (that is `bash`, the launch wrapper, even while the TUI renders — field-confirmed),
+  // and NOT the SHARED per-project app-server socket (it stays bound after a failed `--remote resume` dropped
+  // the pane back to the shell). A missing probe (tmux/ps couldn't report) is not-live. The 'starting' boot
+  // 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, which injects + submits the prompt and CONFIRMS the daemon accepted it (loud failure on a
-  // missing/dead socket — never a silent degradation). codex: JSON-RPC on the same app-server WebSocket the
+  // 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
   // 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>
+  // --- 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
+  // skill/agent files named in `arts` — never the user's surrounding prose, their other settings, or any .spec
+  // data. materialize calls it for every UNSELECTED harness, so dropping a harness from spexcode.json's
+  // `harnesses` prunes that harness's products on the next re-materialize.
+  clean(proj: string, arts: HarnessArtifacts): void
+  // the inverse of writeTrust: strip THIS project's spexcode trust block from the harness's global config.
+  // Codex removes its `~/.codex/config.toml` block; Claude is a no-op (it wrote none).
+  removeTrust(proj: string): void
+
   // the relaunch tail reopen() hands launch() to bring the SAME work back up. claude resumes the same
   // conversation (`--resume <id>`, the id we pinned at launch). codex's own thread id is un-pinnable on the
   // launch flag, so the BACKEND owns it: it `thread/start`s the thread and stores the id at launch, so reopen
@@ -97,12 +150,18 @@ export interface Harness {
   resumeArg(rec: { session: string; harnessSessionId?: string | null }): string
 }
 
-// a prompt-dispatch outcome. ok=true ONLY when delivery is CONFIRMED (claude: the daemon ACCEPTED the prompt;
-// codex: app-server accepted `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.
+// 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.
 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 render 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.
+export type HarnessArtifacts = { skills: readonly string[]; agents: readonly string[] }
 
 // @@@ rendezvous control socket - claude's DETERMINISTIC, ONLY input path for PROMPTS to sessions WE launch.
 // sessions.ts starts `claude` with CLAUDE_BG_BACKEND=daemon + CLAUDE_BG_RENDEZVOUS_SOCK=<this path> set ONLY on
@@ -110,12 +169,58 @@ export type HarnessDeliveryRecord = { session: string; worktreePath?: string; ha
 // `{"type":"reply","text":"…"}\n` injects + submits the text as a prompt — no PTY typing, so multi-line input
 // and Enters can't be corrupted the way `tmux send-keys` was. The path is uniquely derived from the session id,
 // so we only ever address OUR OWN sockets (HARD ethics rule: never touch a session outside this product). It
-// lives in tmpdir tied to the claude process, so no extra lifecycle. liveness reads its existence (present while
-// claude is alive, gone once it exits); deliver writes to it. Exported because sessions.ts builds the launch env
-// var from it and best-effort sweeps it on close — but the liveness/delivery USE is the adapter's, below.
+// lives in tmpdir tied to the claude process, so no extra lifecycle. liveness CONNECTS to it (a live LISTENER,
+// not merely the file — see rendezvousListening); deliver writes to it. Exported because sessions.ts builds the
+// launch env var from it and best-effort sweeps it on close — but the liveness/delivery USE is the adapter's, below.
 export const rvSock = (id: string) => join(tmpdir(), `spexcode-rv-${id}.sock`)
-export const codexAppServerSock = (dir = process.env.SPEXCODE_CODEX_SOCKET_DIR || tmpdir()) => join(dir, 'codex-app-server.sock')
-export const codexAppServerPid = (dir = process.env.SPEXCODE_CODEX_SOCKET_DIR || tmpdir()) => join(dir, 'codex-app-server.pid')
+
+// @@@ rendezvousListening - the LISTENER check that IS claude's liveness truth ([[state]], [[harness-adapter]]).
+// A crashed/killed claude can leave its rvSock FILE on disk (a unix-domain socket path is NOT auto-unlinked on
+// an unclean exit), so the old `existsSync(rvSock)` read a DEAD pane as `online` for as long as the stale file
+// lingered — the incident's "dead pane stuck `working` for 30+ min". The honest signal is a live LISTENER:
+// connect() to the socket. A real claude is accepting → connects; a stale file → ECONNREFUSED (instant); an
+// absent file → ENOENT (instant). So the common cases cost no waiting; the short timeout only bounds the
+// pathological file-present-but-listener-wedged case (then treated as not-live). Never throws.
+export function rendezvousListening(id: string, timeoutMs = 800): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false
+    let c: ReturnType<typeof createConnection> | undefined
+    const done = (v: boolean) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { c?.destroy() } catch { /* */ }
+      resolve(v)
+    }
+    const timer = setTimeout(() => done(false), timeoutMs)
+    try { c = createConnection({ path: rvSock(id) }) } catch { return done(false) }
+    c.on('connect', () => done(true))
+    c.on('error', () => done(false))   // ECONNREFUSED (stale file) / ENOENT (gone) — both mean no live agent
+  })
+}
+// The app-server Unix socket MUST live on a SHORT, sun_path-safe path — NOT nested under the project runtime
+// dir. macOS caps `sun_path` at ~104 bytes, and `runtimeRoot()` flattens the ENTIRE project path into one
+// dash-segment (`encodeProject`), so `<runtimeRoot>/codex-app-server.sock` blew past the cap on a deep macOS
+// project (~111 chars) → `path must be shorter than SUN_LEN` + connect EINVAL, and the app-server never bound
+// (Linux's 108 limit + shorter `/root` paths happened to fit; macOS did not). So the socket is
+// `<socketBase>/spexcode-cx-<hash>.sock`, where `<hash>` is a short STABLE digest of the PROJECT identity — the
+// `dir` (runtimeDir) the callers pass — so launch, liveness, and delivery all compute the IDENTICAL sock for a
+// given project (the ONE-app-server-per-project invariant). This is UNCONDITIONAL on every platform (a short
+// hashed path is strictly better everywhere — no darwin branch; platform differences stay at this path seam).
+// `<socketBase>` = the `SPEXCODE_CODEX_SOCKET_DIR` override, else an OWNED per-uid subdir of the platform
+// tmpdir (`spexcode-cx-<uid>`, created 0700) — NEVER bare tmpdir: codex (0.137+ field-confirmed) refuses to
+// bind a unix socket directly in the shared sticky `/tmp` on a host with `fs.protected_regular=2` (EPERM), so
+// the bare-tmpdir default failed every codex launch on a stock hardened Ubuntu out of the box (github#30),
+// while the SAME codex binds fine in any owned subdirectory. Per-uid (not one shared `spexcode-cx`) so a
+// second user on the box never lands in the first user's 0700 dir. The derivation GUARANTEES the dir exists
+// (idempotent mkdir) so every consumer — launch bake, liveness connect, delivery, tests — shares one creation
+// point. The `.pid`/`.log`/`.lock` files carry no sun_path limit and stay in `runtimeRoot`.
+export const codexAppServerSock = (dir = runtimeRoot()) => {
+  const base = process.env.SPEXCODE_CODEX_SOCKET_DIR || join(tmpdir(), `spexcode-cx-${process.getuid?.() ?? 0}`)
+  mkdirSync(base, { recursive: true, mode: 0o700 })
+  return join(base, `spexcode-cx-${createHash('sha1').update(dir).digest('hex').slice(0, 16)}.sock`)
+}
+export const codexAppServerPid = (dir = runtimeRoot()) => join(dir, 'codex-app-server.pid')
 
 function shQuote(s: string): string {
   return `'${s.replace(/'/g, `'\\''`)}'`
@@ -127,31 +232,30 @@ function shQuote(s: string): string {
 const PKG = fileURLToPath(new URL('..', import.meta.url))
 const SPEX = `${tsxBin(PKG)} ${join(PKG, 'src', 'cli.ts')}`
 
-const ACCEPT_TIMEOUT_MS = 2500
-// @@@ replyViaSocket - inject `text` as a prompt AND confirm the daemon ACCEPTED it (not mere write-success,
-// which is what silently masked dead dispatches before). The CLAUDE_BG_BACKEND=daemon rendezvous server sends
-// NO ack for an accepted reply, so we confirm via an IN-ORDER round-trip: we write `{type:reply}\n{type:repaint}\n`.
-// The daemon dispatches socket lines strictly in order and ENQUEUES the reply BEFORE it handles the repaint and
-// answers `{type:repaint-done}` — so a `repaint-done` with NO preceding `reply-rejected` proves the reply was
-// processed. `repaint` is auth-exempt and always answers, so it's a reliable probe even against a future daemon
-// that gates `reply` behind auth (a gated reply emits `reply-rejected` FIRST). `reply-rejected`/`shutting-down`,
-// a connect/socket error, an early close, or no confirmation within ACCEPT_TIMEOUT_MS ALL resolve to a loud
-// failure with a specific reason. The forced repaint is a harmless redraw of the agent's OWN TUI. Never throws.
+// @@@ 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> {
   return new Promise((resolve) => {
-    let settled = false, buf = ''
+    let settled = false
     let c: ReturnType<typeof createConnection>
     const done = (r: DispatchResult) => {
       if (settled) return
       settled = true
-      clearTimeout(timer)
       try { c?.destroy() } catch { /* */ }
       resolve(r)
     }
-    const timer = setTimeout(
-      () => done({ ok: false, error: `rendezvous socket gave no acceptance confirmation within ${ACCEPT_TIMEOUT_MS}ms` }),
-      ACCEPT_TIMEOUT_MS,
-    )
     try {
       c = createConnection({ path: sock })
     } catch (e) {
@@ -159,26 +263,15 @@ function replyViaSocket(sock: string, text: string): Promise<DispatchResult> {
       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 confirmed accepted' }))
-    c.on('connect', () => c.write(JSON.stringify({ type: 'reply', text }) + '\n' + JSON.stringify({ type: 'repaint' }) + '\n'))
-    c.on('data', (chunk: Buffer) => {
-      buf += chunk.toString('utf8')
-      let i: number
-      while ((i = buf.indexOf('\n')) >= 0) {
-        const line = buf.slice(0, i); buf = buf.slice(i + 1)
-        if (!line) continue
-        let type: string | undefined
-        try { type = JSON.parse(line)?.type } catch { continue }   // ignore any non-JSON noise on the wire
-        if (type === 'reply-rejected') return done({ ok: false, error: 'agent REJECTED the prompt (rendezvous reply-rejected — auth-gated daemon?)' })
-        if (type === 'shutting-down') return done({ ok: false, error: 'agent is shutting down — prompt not accepted' })
-        if (type === 'repaint-done') return done({ ok: true })   // reply was enqueued in-order before this
-        // heartbeat / state / other frames → keep waiting for the decisive repaint-done or a rejection.
-      }
-    })
+    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 })))
   })
 }
-// claude's deliver: fail loud BEFORE attempting the socket if it isn't there (a clearer message than a raw
-// connect error), exactly as the old sendKeys did, then inject + confirm via the rendezvous round-trip.
+// 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> {
   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` })
@@ -233,8 +326,50 @@ export function activeTurnIdFromThread(readResult: unknown): string | null {
   return active?.id ?? null
 }
 
-export function codexLaunchCommand(_id: string, codexCmd = process.env.SPEXCODE_CODEX_CMD || 'codex --yolo', serverCmd = process.env.SPEXCODE_CODEX_SERVER_CMD || 'codex', dir = process.env.SPEXCODE_CODEX_SOCKET_DIR || runtimeRoot()): string {
-  const sock = codexAppServerSock(dir)
+// The app-server and the visible `--remote … resume` TUI share ONE socket, so they MUST be the SAME codex
+// install — a version split across that socket breaks the thread/start→resume handoff (an app-server on one
+// version creates a thread a differently-versioned resume can't find; an old-enough app-server can't serve
+// `--remote unix://` at all). So `serverCmd` is DERIVED from the in-effect `codexCmd`'s binary (its first shell
+// token, dropping args like `--yolo`) whenever it isn't explicitly forced: `<bin> app-server` then runs the
+// SAME install as `<bin> --remote … resume`. Bare `codex` is NOT the default anymore — on a multi-install host
+// (e.g. homebrew codex shadowing an nvm codex) a bare `codex` resolves via the login-shell PATH to a DIFFERENT
+// binary than the launcher's, which is exactly the version-skew bug. `SPEXCODE_CODEX_SERVER_CMD` stays the
+// explicit escape hatch (highest precedence). Caveat: if `codexCmd`'s first token is a WRAPPER script rather
+// than codex itself, the derived `<wrapper> app-server` only works if the wrapper forwards to codex — the
+// common direct-binary case (`codex …`, `/abs/codex --yolo`) is what this fixes.
+export function codexBinary(codexCmd: string): string {
+  return codexCmd.trim().split(/\s+/)[0] || 'codex'
+}
+// codex >=0.142 adds `--dangerously-bypass-hook-trust` — run our OWN (vetted) dispatch hooks without a persisted
+// trusted_hash. We PREFER it over reverse-engineering codexHookHash: that hash is pinned to one codex version's
+// format and silently breaks on a bump (codex then skips ALL our hooks -> no Stop gate, no mark-active, sessions
+// die undeclared). The flag is version-robust. But an OLDER codex HARD-ERRORS on the unknown flag (the whole
+// app-server fails to boot), so we CAPABILITY-PROBE the binary once (`--help` grep) and only pass it when
+// present; otherwise the writeCodexTrust hash path still stands in. Memoized — a per-binary constant.
+const bypassProbe = new Map<string, boolean>()
+export function codexSupportsBypassHookTrust(binary: string): boolean {
+  // explicit escape hatch (also what makes this deterministic in tests): force the capability on/off regardless
+  // of the binary — e.g. if the `--help` probe is unreliable on a wrapper, or to pin behaviour.
+  const env = process.env.SPEXCODE_CODEX_BYPASS_HOOK_TRUST
+  if (env !== undefined) return env === '1' || env === 'true'
+  const hit = bypassProbe.get(binary)
+  if (hit !== undefined) return hit
+  let ok = false
+  try { ok = execFileSync(binary, ['--help'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).includes('--dangerously-bypass-hook-trust') } catch { ok = false }
+  bypassProbe.set(binary, ok)
+  return ok
+}
+export function codexLaunchCommand(_id: string, codexCmd = process.env.SPEXCODE_CODEX_CMD || 'codex --yolo', 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
+  // thread — it was INERT there, the bug). Two thread paths carry it: (1) the BACKEND-owned `thread/start` sends
+  // `config.bypass_hook_trust` from codex-launch ([[harness-adapter]]); (2) the visible `--remote … resume` TUI,
+  // where codex's OWN client forwards this flag into its thread/start+thread/resume config — so a reopen in a
+  // fresh app-server (where codex-launch never runs) still trusts our hooks. Hence the flag lives on the resume
+  // TUI, never on the app-server invocation. Guarded against a double-flag when an env override already carries it.
+  const tuiBypass = !codexCmd.includes('--dangerously-bypass-hook-trust') && codexSupportsBypassHookTrust(codexBinary(codexCmd)) ? ' --dangerously-bypass-hook-trust' : ''
+  const sock = codexAppServerSock(dir)         // short sun_path-safe path in the owned tmp subdir/override — NOT under "$dir"
   const pid = codexAppServerPid(dir)
   const log = join(dir, 'codex-app-server.log')
   const lock = join(dir, 'codex-app-server.lock')
@@ -244,27 +379,61 @@ export function codexLaunchCommand(_id: string, codexCmd = process.env.SPEXCODE_
     `pid=${shQuote(pid)}`,
     `log=${shQuote(log)}`,
     `lock=${shQuote(lock)}`,
+    // codex-launch's bypass-trust gate (and writeTrust's) resolves the codex binary from SPEXCODE_CODEX_CMD;
+    // WE already hold the launcher's real cmd here (it drives the app-server + resume TUI + tuiBypass above), so
+    // pin it into the environment the codex-launch child inherits. Without this the child falls back to a bare
+    // `codex`, which on a multi-install box (e.g. an old Homebrew codex on PATH beside the launcher's newer one)
+    // probes the WRONG binary — deciding "no --dangerously-bypass-hook-trust support" and silently dropping the
+    // thread/start bypass, so the worktree's hooks stay untrusted and NO lifecycle hooks fire.
+    `export SPEXCODE_CODEX_CMD=${shQuote(codexCmd)}`,
     'mkdir -p "$dir"',
-    '(',
-    '  flock 9',
-    '  if [ -S "$sock" ] && [ -s "$pid" ] && ! kill -0 "$(cat "$pid")" 2>/dev/null; then rm -f "$sock"; fi',
-    '  if [ ! -S "$sock" ]; then',
-    // 9>&- : do NOT let the long-lived app-server inherit fd 9 (the flock fd). An flock is held until
-    // EVERY fd on its open file description is closed; if the daemon keeps fd 9 open it pins the lock
-    // forever, so every later launcher blocks on `flock 9` and never reaches the thread-owning step
-    // (the pane stays at the shell, no TUI, no thread). </dev/null detaches its stdin from the pane so
-    // it can't fight the TUI for the tty.
-    `    ${serverCmd} app-server --listen unix://"$sock" >"$log" 2>&1 9>&- </dev/null &`,
-    '    echo $! > "$pid"',
-    '    for i in $(seq 1 100); do [ -S "$sock" ] && break; sleep 0.05; done',
-    '  fi',
-    ') 9>"$lock"',
-    // BACKEND owns the thread: `codex-launch` does thread/start { cwd = this worktree } on the shared
-    // per-project app-server, stores the new thread id on the governed record (SPEXCODE_SESSION_ID), and
-    // fires the launch prompt as the first turn — materializing the rollout. It prints the thread id, which
-    // the visible TUI then RESUMES (the rollout persists on disk), rendering it natively. "$@" is the prompt.
-    `tid=$(${SPEX} codex-launch "$sock" "$PWD" "$@")`,
-    `exec ${codexCmd} --remote unix://"$sock" resume "$tid"`,
+    'mkdir -p -m 700 "$(dirname "$sock")"',    // the socket base (owned tmp subdir or the SPEXCODE_CODEX_SOCKET_DIR override) — re-created here because a tmp cleaner may have wiped it since the bake; NEVER bare /tmp (codex EPERMs binding there on hardened hosts, github#30)
+    // self-heal: the pre-fix flock design left an orphaned `codex-app-server.lock` FILE; the mkdir mutex now
+    // uses `"$lock.d"`, so drop that dead residue on already-run deployments (harmless if absent).
+    'rm -f "$lock"',
+    // POSIX-portable mutex: mkdir is atomic on every POSIX fs, so it serializes the check-and-start with NO
+    // dependency on util-linux `flock` (absent on macOS — where the old flock path failed the whole app-server
+    // bootstrap, leaving the pane at the shell). Spin on `mkdir "$lock.d"` with a bounded wait; after ~10s
+    // (200 * 0.05s, safely above the ~5s socket-wait a legit holder needs) treat the dir as orphaned by a dead
+    // launcher and clear it, so a stale lock can never deadlock a launch. Held ONLY across the check-and-start,
+    // released immediately after. Unlike flock (held until every fd on its open file description closes) a mkdir
+    // lock has no inherited-fd hazard, so the long-lived daemon can't pin it — no fd-9 gymnastics needed.
+    'lockd="$lock.d"',
+    '_lk=0',
+    'until mkdir "$lockd" 2>/dev/null; do',
+    '  _lk=$((_lk+1)); [ "$_lk" -ge 200 ] && { rm -rf "$lockd" 2>/dev/null; _lk=0; }',
+    '  sleep 0.05',
+    'done',
+    'if [ -S "$sock" ] && [ -s "$pid" ] && ! kill -0 "$(cat "$pid")" 2>/dev/null; then rm -f "$sock"; fi',
+    'if [ ! -S "$sock" ]; then',
+    // The app-server is a per-PROJECT daemon SHARED across every worktree's threads, so it must run in a STABLE
+    // cwd — the runtime dir "$dir", NOT the launch.sh's transient worktree. A daemon started inside a worktree
+    // keeps that worktree as its process cwd for its whole life; when the session closes and the worktree is
+    // removed, the daemon's cwd becomes a DELETED dir, and codex then fails EVERY new thread's config load with
+    // `failed to load configuration: No such file or directory` — bricking codex launch for the whole project
+    // until the daemon is killed. Running it from "$dir" (which never gets deleted) makes it deletion-proof.
+    // exec so $! is the daemon itself; </dev/null detaches its stdin from the pane so it can't fight the TUI.
+    `  ( cd "$dir" && exec ${server} app-server --listen unix://"$sock" >"$log" 2>&1 </dev/null ) &`,
+    '  echo $! > "$pid"',
+    '  for i in $(seq 1 100); do [ -S "$sock" ] && break; sleep 0.05; done',
+    'fi',
+    'rmdir "$lockd" 2>/dev/null',
+    // TWO launch modes, on ONE tail channel ("$@"). reopen() hands a `--resume <thread-id>` tail (see
+    // codexHarness.resumeArg) to bring the SAME conversation back: resume that OWNED thread DIRECTLY — no new
+    // thread, no first-turn prompt. ANY other tail is a NEW launch: BACKEND owns the thread — `codex-launch`
+    // does thread/start { cwd = this worktree } on the shared per-project app-server, stores the new id on the
+    // governed record (SPEXCODE_SESSION_ID), and fires the tail as the FIRST turn, materializing the rollout.
+    // Either way it ends with a thread id, which the visible TUI then RESUMES (the rollout persists on disk),
+    // rendering it natively. A new launch's tail is always ONE single-quoted prompt arg, so it can never be the
+    // literal "--resume" marker — the discriminator is unambiguous. codex-launch only prints an id once its
+    // rollout has landed (resume-ready), so a fail-loud (empty output / non-zero) must ABORT — never `resume ""`.
+    `if [ "$1" = "--resume" ]; then`,
+    `  tid=$2`,
+    `else`,
+    `  tid=$(${SPEX} internal codex-launch "$sock" "$PWD" "$@") || exit 1`,
+    `fi`,
+    `[ -n "$tid" ] || { echo "[spex] codex-launch produced no resumable thread" >&2; exit 1; }`,
+    `exec ${codexCmd}${tuiBypass} --remote unix://"$sock" resume "$tid"`,
   ].join('\n')
   return `bash -lc ${shQuote(script)} spexcode-codex`
 }
@@ -374,7 +543,7 @@ export function codexThreadId(sock: string): Promise<{ ok: true; threadId: strin
 // carries the new thread id (`result.thread.id`). The launcher stores that id on the governed record and
 // fires the first turn; there is no capture hook and no rollout/cwd scan. Same WS framing as codexThreadId.
 // Never throws.
-export function codexStartThread(sock: string, cwd?: string): Promise<{ ok: true; threadId: string } | { ok: false; error: string }> {
+export function codexStartThread(sock: string, cwd?: string, bypassHookTrust = false): Promise<{ ok: true; threadId: string } | { ok: false; error: string }> {
   return new Promise((resolve) => {
     const conn: Socket = createConnection(sock)
     const fs: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
@@ -395,7 +564,18 @@ export function codexStartThread(sock: string, cwd?: string): Promise<{ ok: true
       let m: JsonRpc
       try { m = JSON.parse(json) } catch { return }
       if (m.error) return done({ ok: false, error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` })
-      if (m.id === 1 && m.result) { send({ method: 'initialized', params: {} }); return send({ id: 2, method: 'thread/start', params: cwd ? { cwd } : {} }) }
+      if (m.id === 1 && m.result) {
+        send({ method: 'initialized', params: {} })
+        // thread/start's `config` is the per-request override map the app-server reads (config_manager reads
+        // `request_overrides["bypass_hook_trust"]`) — the ONLY channel that reaches the thread config; the
+        // `--dangerously-bypass-hook-trust` flag on the `codex app-server` invocation is INERT (the app-server
+        // never reads it for a thread), so a BACKEND-owned thread must carry the bypass here, exactly as codex's
+        // own `--remote resume` TUI client injects it. Without it the worktree's UNtrusted `.codex` config layer
+        // stays disabled → no local hooks discovered → no Stop gate. Only on the bypass path (older codex without
+        // the flag uses writeCodexTrust's hash and never sees this key).
+        const params = { ...(cwd ? { cwd } : {}), ...(bypassHookTrust ? { config: { bypass_hook_trust: true } } : {}) }
+        return send({ id: 2, method: 'thread/start', params })
+      }
       if (m.id === 2 && m.result) {
         const tid = (m.result as { thread?: { id?: string } })?.thread?.id
         return tid ? done({ ok: true, threadId: tid }) : done({ ok: false, error: 'codex thread/start returned no thread id' })
@@ -506,6 +686,35 @@ export function codexTurn(sock: string, threadId: string, text: string, cwd?: st
   return sendCodexAppServerTurn(sock, threadId, text, cwd)
 }
 
+// @@@ codex rollout on disk - the visible TUI resumes a thread via `codex --remote resume <tid>`, which reads
+// the thread's ROLLOUT FILE (`<CODEX_HOME>/sessions/YYYY/MM/DD/rollout-<ts>-<tid>.jsonl`) — so a thread the
+// TUI can render is exactly one whose rollout exists on disk. VERIFIED live (real codex 0.142.5): `thread/start`
+// ALONE writes NO rollout — only the first fired turn materializes it; and a FRESHLY-spawned app-server accepts
+// thread/start+turn but does NOT persist the rollout for its first ~2-4s (a warm-up window) — the SAME thread's
+// 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.
+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)))
+}
+// 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
+// exceed launch.sh's fast-fail threshold so a genuine failure exits PAST it — the retry loop then treats it as a
+// real end, not a daemon race, and never sprays fresh (duplicate-prompt) threads.
+export async function waitForCodexRollout(threadId: string, timeoutMs = 20000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    if (codexRolloutExists(threadId)) return true
+    if (Date.now() >= deadline) return false
+    await new Promise((r) => setTimeout(r, 250))
+  }
+}
+
 // codex's deliver: use the Codex app-server JSON-RPC channel that also powers rich clients, never TUI typing.
 // The visible TUI is launched against the same project app-server Unix socket, so this injects into the same
 // thread the pane is showing — steering an in-progress turn or starting one if idle. A missing captured thread
@@ -544,6 +753,29 @@ export function writeManagedBlock(file: string, body: string, comment: readonly
   writeFileSync(file, cur)
 }
 
+// the INVERSE of writeManagedBlock: strip the spexcode sentinel block (with the blank space around it),
+// leaving every other byte of the user's file intact. When deleteIfEmpty and nothing but whitespace remains,
+// remove the file — it was WHOLLY ours (e.g. a CLAUDE.md that carried only the generated contract block). Same
+// comment-style parameter so ONE primitive un-writes every managed file. No-op when the file/block is absent.
+export function removeManagedBlock(file: string, comment: readonly [string, string] = ['<!-- ', ' -->'], deleteIfEmpty = false): void {
+  if (!existsSync(file)) return
+  const [open, close] = comment
+  const START = `${open}spexcode:start${close}`
+  const END = `${open}spexcode:end${close}`
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const re = new RegExp(`\\n*${esc(START)}[\\s\\S]*?${esc(END)}\\n*`)
+  const cur = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  if (!re.test(cur)) return
+  // remove ONLY our block plus the blank lines writeManagedBlock inserted around it; do NOT normalize the
+  // user's OWN whitespace elsewhere — this must leave every other byte intact so it is a faithful INVERSE of
+  // writeManagedBlock's append. A global `\n{3,}→\n\n` collapse used to sit here and mutated pre-existing
+  // blank-line runs in the user's file, which broke the private⇄default round-trip ([[private-overlay]]):
+  // default→private→default left a spurious one-line diff on a .gitignore that had internal blank lines.
+  const out = cur.replace(re, '\n').replace(/^\n+/, '')
+  if (deleteIfEmpty && !out.trim()) { rmSync(file, { force: true }); return }
+  writeFileSync(file, out)
+}
+
 // 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 + the gate's `spex materialize`.
@@ -576,10 +808,41 @@ export function codexHookHash(snakeEvent: string, command: string, timeout = 600
   return 'sha256:' + createHash('sha256').update(JSON.stringify(canon(obj))).digest('hex')
 }
 
-// additively stamp directory + per-hook trust into the user's GLOBAL ~/.codex/config.toml so a user-self-
-// launched codex skips the trust prompts. Scoped to THIS project path; replaces our own prior block (between
-// sentinels) idempotently; never touches the user's other config. CODEX_HOME respected for testability.
-function writeCodexTrust(proj: string, events: readonly string[], cmdFor: (e: string) => string): void {
+// @@@ stripCodexTrustFor - remove EVERY prior definition of THIS project's codex trust from a config.toml body,
+// in ANY form: our own sentinel block (whatever past format its comments used), a BARE `[projects."<proj>"]`
+// table (codex AUTO-writes one the moment it trusts a folder interactively/`exec` — NOT sentinel-wrapped), and
+// any `[hooks.state."<hooksJson>:…"]` tables. This is what makes the UNCONDITIONAL write duplicate-SAFE and
+// SELF-HEALING: codex REFUSES to load a config.toml with a duplicate key ("duplicate key"), so a sentinel-only
+// replace (the old behaviour) that missed a pre-existing bare/old block APPENDED a second `[projects."<proj>"]`
+// and took codex fully OFFLINE (the real cause of the public-vps outage). It is TABLE-scoped and STRING-compared
+// (no regex escaping of the path), so other projects' trust, the shared parent tables (`[projects]`,
+// `[hooks.state]`), and every other config key are untouched; a skipped table's body ends at the next header,
+// blank, or comment, so a user comment attached to a following table is preserved.
+function stripCodexTrustFor(cur: string, proj: string, hooksJson: string): string {
+  const projHeader = `[projects."${proj}"]`
+  const hooksPrefix = `[hooks.state."${hooksJson}:`
+  const out: string[] = []
+  let skip = false
+  for (const line of cur.split('\n')) {
+    const t = line.trim()
+    const isHeader = /^\[\[?/.test(t)                       // a TOML table / array-of-tables header
+    if (skip) { if (t === '' || t.startsWith('#') || isHeader) skip = false; else continue }   // end THIS table's body
+    if (isHeader && (t === projHeader || t.startsWith(hooksPrefix))) { skip = true; continue }
+    if (t === `# spexcode:trust:${proj} (managed — do not edit)` || t === `# spexcode:trust:end:${proj}`) continue
+    out.push(line)
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n*$/, '')
+}
+
+// additively stamp PROJECT trust (`[projects."<proj>"] trust_level = "trusted"`) AND the per-hook
+// `trusted_hash` blocks for each event into the user's GLOBAL ~/.codex/config.toml, so a dispatched or
+// self-launched codex trusts THIS project's config layer (enabling hook discovery) AND treats each hook as
+// already-reviewed (no "Hooks need review" prompt on a persistent resume — see writeTrust). ALL prior
+// definitions of this project's trust (ours, bare, or old-format) are STRIPPED first, so the write can never
+// 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 {
   const home = process.env.CODEX_HOME || join(homedir(), '.codex')
   const file = join(home, 'config.toml')
   const hooksJson = join(proj, '.codex', 'hooks.json')
@@ -589,13 +852,79 @@ function writeCodexTrust(proj: string, events: readonly string[], cmdFor: (e: st
     lines.push(`[hooks.state."${hooksJson}:${snake}:0:0"]`, `trusted_hash = "${codexHookHash(snake, cmdFor(e))}"`)
   }
   const blk = `# spexcode:trust:${proj} (managed — do not edit)\n${lines.join('\n')}\n# spexcode:trust:end:${proj}`
-  const esc = proj.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  let cur = existsSync(file) ? readFileSync(file, 'utf8') : ''
-  const re = new RegExp(`# spexcode:trust:${esc} \\(managed[\\s\\S]*?# spexcode:trust:end:${esc}`)
-  if (re.test(cur)) cur = cur.replace(re, blk)
-  else cur = cur.trim() ? `${cur.replace(/\n*$/, '')}\n\n${blk}\n` : `${blk}\n`
+  const cleaned = stripCodexTrustFor(existsSync(file) ? readFileSync(file, 'utf8') : '', proj, hooksJson)
   if (!existsSync(home)) mkdirSync(home, { recursive: true })
-  writeFileSync(file, cur)
+  writeFileSync(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`)
+}
+
+// the inverse of writeCodexTrust: strip THIS project's codex trust from the GLOBAL config.toml — the SAME
+// removal writeCodexTrust does before it writes, so uninstall fully clears our trust (sentinel, bare, and
+// hooks.state) and can never leave a half-block. No-op when the file/nothing-of-ours is absent (so it never
+// rewrites/normalizes a config that carries none of our trust). CODEX_HOME respected for testability.
+function removeCodexTrust(proj: string): void {
+  const home = process.env.CODEX_HOME || join(homedir(), '.codex')
+  const file = join(home, 'config.toml')
+  if (!existsSync(file)) return
+  const hooksJson = join(proj, '.codex', 'hooks.json')
+  const cur = readFileSync(file, 'utf8')
+  if (!cur.includes(`[projects."${proj}"]`) && !cur.includes(`[hooks.state."${hooksJson}:`) &&
+      !cur.includes(`# spexcode:trust:${proj} `) && !cur.includes(`# spexcode:trust:end:${proj}`)) return
+  const cleaned = stripCodexTrustFor(cur, proj, hooksJson)
+  writeFileSync(file, cleaned ? `${cleaned}\n` : '')
+}
+
+// @@@ cleanHarness - the shared clean: the inverse of materialize's per-harness write, expressed PURELY
+// through the adapter's own path methods so it can never drift from what write put there. Each step is
+// surgical, gated on a SpexCode identity stamp: the contract files carry the managed-block sentinels; the shim
+// is a generated file whose command line names our `dispatch.sh`; the trust is a sentinel-delimited config
+// block; the skill/agent files sit at name-scoped paths reconstructed from `arts`. So it removes ONLY our own
+// blocks and our own named products — never a user's CLAUDE.md/AGENTS.md prose, a hand-made settings.json, or
+// a sibling skill/agent the user added, and NEVER any .spec data.
+function cleanHarness(h: Harness, proj: string, arts: HarnessArtifacts): void {
+  for (const f of h.contractFiles(proj)) removeManagedBlock(f, ['<!-- ', ' -->'], true)
+  const shim = h.shimFile(proj)
+  if (existsSync(shim) && readFileSync(shim, 'utf8').includes('dispatch.sh')) rmSync(shim, { force: true })
+  const anchor = h.worktreeHookAnchor(proj)   // the linked-worktree anchor copy, same identity gate as the shim
+  if (anchor && existsSync(anchor) && readFileSync(anchor, 'utf8').includes('dispatch.sh')) rmSync(anchor, { force: true })
+  h.removeTrust(proj)
+  const sd = h.skillDir(proj)
+  if (sd) for (const n of arts.skills) rmSync(join(sd, n), { recursive: true, force: true })
+  const ad = h.agentDir(proj)
+  if (ad) for (const n of arts.agents) rmSync(join(ad, `${n}.md`), { force: true })
+}
+
+// ---------------------------------------------------------------------------------------------------------
+// codex per-session liveness signal — a codex process live in the pane's DESCENDANT tree, NOT the pane's
+// foreground command name, and NOT the shared app-server socket.
+
+// @@@ paneTreeRunsCodex - the codex TUI is alive iff a codex-ish process is live SOMEWHERE in the launch
+// pane's descendant process tree. The pane's FOREGROUND name is NOT the signal: the pane runs
+// `bash <launch.sh>` → `bash -lc <codex script>` → node (the codex CLI) → the vendored `codex` binary, and
+// tmux's `pane_current_command` reports the OUTERMOST of those — `bash` — for the entire life of a healthy,
+// rendering TUI (field-confirmed on macmini and Linux). So "foreground == codex" false-read every live codex
+// as offline, and the earlier sock-presence check false-read a dead one as online (the SHARED per-project
+// app-server socket survives a failed `--remote resume`). The honest shape test: HEALTHY = codex (by whatever
+// name — `codex`, the vendored musl binary, or the `node` its CLI runs under) exists among the pane pid's
+// descendants; FAILED = the launch script's bounded retries exhausted, everything under the pane exited, and
+// the pane sits at the bare shell — no codex/node anywhere below it. The walk is over ONE whole-box
+// pid→(ppid, comm) snapshot the caller took (a single `ps` for the whole session list); missing probe data
+// (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 {
+  if (!pane?.panePid || !pane.procs?.size) return false
+  const kids = new Map<number, number[]>()
+  for (const [pid, p] of pane.procs) {
+    const arr = kids.get(p.ppid); if (arr) arr.push(pid); else kids.set(p.ppid, [pid])
+  }
+  const stack = [...(kids.get(pane.panePid) ?? [])]   // descendants only — the pane pid itself is the shell
+  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
+    const c = kids.get(pid); if (c) stack.push(...c)
+  }
+  return false
 }
 
 // ---------------------------------------------------------------------------------------------------------
@@ -604,21 +933,34 @@ function writeCodexTrust(proj: string, events: readonly string[], cmdFor: (e: st
 const CLAUDE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'] as const
 const CODEX_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: `cmd` override wins, else ambient env→config→default.
+const claudeBaseCmd = (cmd?: string) => cmd || process.env.SPEXCODE_CLAUDE_CMD || readConfig(mainCheckout()).sessions?.claudeCmd || 'claude --dangerously-skip-permissions'
+const codexBaseCmd = (cmd?: string) => cmd || process.env.SPEXCODE_CODEX_CMD || readConfig(mainCheckout()).sessions?.codexCmd || 'codex --yolo'
+
 export const claudeHarness: Harness = {
   id: 'claude',
   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
-  launchCmd: () => process.env.SPEXCODE_CLAUDE_CMD || readConfig(mainCheckout()).sessions?.claudeCmd || 'claude --dangerously-skip-permissions',
+  launchCmd: (_id, _rt, cmd) => claudeBaseCmd(cmd),  // claude's full invocation IS its base command (the tail is appended by the caller)
+  baseCmd: claudeBaseCmd,
   sessionIdArg: (id) => `--session-id ${id}`,        // the caller chooses the id
   sessionEnvVar: 'CLAUDE_CODE_SESSION_ID',
   shimFile: (proj) => join(proj, '.claude', 'settings.json'),
+  worktreeHookAnchor: () => null,                    // claude's shim already lives in the worktree (.claude/settings.json) — self-anchors, no root rewrite
   contractFiles: (proj) => [join(proj, 'CLAUDE.md')],
   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 */ },
+  removeTrust: () => { /* Claude wrote no trust — nothing to strip */ },
+  clean(proj, arts) { cleanHarness(this, proj, arts) },
   slashCommands: claudeSlashCommands,
-  liveness: (rec, tmuxAlive) => (tmuxAlive && existsSync(rvSock(rec.session)) ? 'online' : 'offline'),
+  // online iff the window is up AND a LIVE LISTENER is on the rendezvous socket (`socketLive`, connect-probed by
+  // the caller) — NOT the mere existence of a stale socket FILE a crashed claude leaves behind (the 30-min
+  // dead-pane-reads-working bug). See rendezvousListening.
+  liveness: (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) => (tmuxAlive && !!socketLive ? 'online' : 'offline'),
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
   resumeArg: (rec) => `--resume ${rec.session}`,
 }
@@ -628,7 +970,8 @@ export const codexHarness: Harness = {
   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
-  launchCmd: (id, runtimeDir) => codexLaunchCommand(id, process.env.SPEXCODE_CODEX_CMD || readConfig(mainCheckout()).sessions?.codexCmd, undefined, runtimeDir ?? runtimeRoot()),   // env→config→default; ONE app-server per PROJECT
+  launchCmd: (id, runtimeDir, cmd) => codexLaunchCommand(id, codexBaseCmd(cmd), undefined, runtimeDir ?? runtimeRoot()),   // the full app-server+TUI script BUILT AROUND the resolved base command; ONE app-server per PROJECT
+  baseCmd: codexBaseCmd,
   sessionIdArg: () => '',                            // codex assigns its own id (the backend owns it via thread/start)
   sessionEnvVar: 'CODEX_THREAD_ID',
   // Codex discovers a LINKED worktree's PROJECT hooks from the ROOT CHECKOUT's `.codex`, NOT the worktree's
@@ -639,14 +982,50 @@ export const codexHarness: Harness = {
   // per-worktree (codex loads THOSE by walking the thread cwd). dispatch.sh resolves `proj` from the thread
   // cwd, so one shared shim serves every worktree.
   shimFile: (proj) => join(mainCheckout(proj), '.codex', 'hooks.json'),
+  // a LINKED worktree also needs its OWN `.codex/hooks.json` so codex-rs anchors the project config layer for
+  // the worktree cwd (without a `.codex/` under the worktree root, codex builds no layer, so the rewritten
+  // root-checkout hooks are never discovered and NO hooks fire — bypass_hook_trust cannot rescue a layer that
+  // was never built). Its content is ignored (the rewrite reads the root's shim above), so it is a pure anchor.
+  // Only for a genuine worktree: on the main checkout, shimFile already wrote `.codex/hooks.json` there.
+  worktreeHookAnchor: (proj) => (mainCheckout(proj) === proj ? null : join(proj, '.codex', 'hooks.json')),
   contractFiles: (proj) => [join(proj, 'AGENTS.md')],
   skillDir: (proj) => join(proj, '.codex', 'skills'),
+  agentDir: () => null,                              // codex has no file-discovered agent-definition primitive — materialize skips it
   shim: (dispatch, spex) => buildShim('codex', CODEX_EVENTS, dispatch, spex),
+  // Write the FULL codex trust — BOTH tiers, UNCONDITIONALLY — because `bypass_hook_trust` covers neither on
+  // the dispatched-worker path:
+  //   (1) PROJECT trust (`[projects."<mainCheckout>"] trust_level = "trusted"`) ENABLES the project config
+  //       layer — the precondition for codex to DISCOVER our hooks AT ALL. codex-rs `get_layers` drops a
+  //       disabled (untrusted) project layer BEFORE hook discovery runs, and bypass_hook_trust is read only
+  //       AFTER, per-handler — so it can NEVER enable a layer. A dispatched worker's app-server does NOT
+  //       auto-trust the project (only the interactive TUI / `codex exec` approval flow does), so without this
+  //       an untrusted worktree thread fires ZERO hooks ("Project-local config, hooks … are disabled until the
+  //       project is trusted").
+  //   (2) per-HOOK trust (the reverse-engineered `trusted_hash` blocks — codexHookHash) marks each hook Trusted
+  //       so it is NOT "new or changed". This is REQUIRED even though the launch carries
+  //       `--dangerously-bypass-hook-trust`: our visible TUI attaches to the backend-owned thread via `codex …
+  //       resume <tid>`, and codex-rs FORCES the startup hook-review prompt on a PERSISTENT RESUME regardless of
+  //       the flag (`bypass_hook_trust_for_startup_review = config.bypass_hook_trust && !is_persistent_resume`,
+  //       tui/src/lib.rs) — an untrusted/modified hook (no matching hash) leaves the worker WEDGED at an
+  //       interactive "Hooks need review" menu. Matching hashes make review_needed_count == 0, so codex skips
+  //       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),
+  // 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) },
   slashCommands: codexSlashCommands,
-  liveness: (rec, tmuxAlive, runtimeDir) => (tmuxAlive && existsSync(codexAppServerSock(runtimeDir)) ? 'online' : 'offline'),
+  // online iff the tmux window is up AND a codex-ish process is live in the pane pid's DESCENDANT tree — see
+  // paneTreeRunsCodex. NOT the pane's foreground command (that is `bash`, the launch wrapper, even while the
+  // TUI renders — the field-confirmed false-OFFLINE) and NOT the app-server socket (SHARED per-project, it
+  // survives a failed `--remote resume` — the earlier false-ONLINE).
+  liveness: (_rec, tmuxAlive, _runtimeDir, pane) => (tmuxAlive && paneTreeRunsCodex(pane) ? 'online' : 'offline'),
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
-  resumeArg: (rec) => (rec.harnessSessionId ? `resume ${rec.harnessSessionId}` : ''),   // owned thread id → codex `resume <id>` (SAME conversation); none → relaunch FRESH
+  // 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}` : ''),
 }
 
 // every adapter — materialize iterates this to render each harness's artifacts in one pass.
@@ -662,3 +1041,30 @@ export function harnessById(id: string): Harness {
   if (!h) throw new Error(`unknown harness '${id}' (known: ${HARNESSES.map((x) => x.id).join(', ')})`)
   return h
 }
+
+// --- named launcher profiles ([[launcher-select]]) ----------------------------------------------------------
+// a launcher = a `{ harness, cmd }` pair in spexcode.json's `sessions.launchers`, keyed by a human-chosen name.
+// 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.
+export type Launcher = { name: string; harness: string; cmd: string }
+
+// the configured launchers, as a stable name-sorted list (for the dashboard dropdown + the CLI). Empty when a
+// project configured none — the caller then falls back to the unnamed harness pick.
+export function launcherList(root = mainCheckout()): Launcher[] {
+  const m = readConfig(root).sessions?.launchers || {}
+  return Object.keys(m).sort().map((name) => ({ name, harness: m[name].harness || defaultHarness.id, cmd: m[name].cmd }))
+}
+
+// the configured default launcher NAME ([[launcher-select]]) — the profile `spex new`/a dropdown pick with no
+// explicit choice resolves. '' when none configured. The dashboard reads this to PRE-SELECT its New-Session
+// dropdown to match the CLI/config default, so the two surfaces agree on which launcher a bare create uses.
+export function defaultLauncher(root = mainCheckout()): string {
+  return readConfig(root).sessions?.defaultLauncher || ''
+}
+
+export function resolveLauncher(name: string, root = mainCheckout()): Launcher {
+  const l = readConfig(root).sessions?.launchers?.[name]
+  if (!l || !l.cmd) throw new Error(`unknown launcher '${name}' (configured: ${launcherList(root).map((x) => x.name).join(', ') || 'none'})`)
+  harnessById(l.harness || defaultHarness.id)   // validate the harness id fail-loud
+  return { name, harness: l.harness || defaultHarness.id, cmd: l.cmd }
+}