spexcode 0.5.8 → 0.6.0

package/spec-cli/src/harness.ts

@@ -17,6 +17,7 @@ import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath } from './la
 import { git } from './git.js'
 import { shQuote } from './sh.js'
 import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, processStartToken, verifyDetachedRuntime, type VerifiedDetachedRuntime } from './process-identity.js'
+import { codexGenerationEndpoints, codexGenerationSocketPath, currentCodexGeneration, legacyCodexGenerationEndpoint, readCodexGenerationLedger, resolveCodexGenerationForSession, type CodexGenerationEndpoint } from './codex-runtime-generations.js'
 
 // @@@ harness-adapter - the ONE seam between SpexCode and the coding-agent harness (Claude Code, Codex, …).
 // Every harness-specific fact lives behind THIS interface with one implementation per harness; product code
@@ -56,6 +57,9 @@ export type SharedRuntimeDescriptor = {
   label: string
   pidFile: string
   receiptFile: string
+  // When a resident adapter has several immutable generations, this resolves the one exact descriptor a
+  // governed target owns. Product code consumes the selection without learning adapter-specific identities.
+  targetDescriptorKey?: (rec: HarnessLivenessRecord & { harnessSessionId?: string | null }) => string | null
   // Lightweight project-wide resident census used by read projections. It must return exact loaded IDs without
   // per-thread reads; the full probe remains the resource/lifecycle surface that also reads turn state.
   residency?: () => Promise<{ healthy: boolean; referenceIds: string[]; error?: string; rootAbsent?: boolean }>
@@ -110,7 +114,9 @@ export async function adapterLoadedReferenceState(
   const recordKeys = new Map<string, string[]>()
   for (const rec of records) {
     if (!rec.harnessSessionId) continue
-    const keys = (harnessById(rec.harness || defaultHarness.id).sharedRuntimes?.(runtimeDir) ?? []).map((descriptor) => {
+    const harness = harnessById(rec.harness || defaultHarness.id)
+    const exactKey = harness.targetDescriptorKey?.(rec) ?? null
+    const keys = (harness.sharedRuntimes?.(runtimeDir) ?? []).filter((descriptor) => !exactKey || descriptor.key === exactKey).map((descriptor) => {
       descriptors.set(descriptor.key, descriptor)
       return descriptor.key
     })
@@ -272,14 +278,11 @@ export interface Harness {
   // token it registered for this record (session id, harness thread/generation, or null when unprovable);
   // product lifecycle code never branches on harness names to invent this identity.
   leafOwnerNeedle?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): string | null
-  // deliver a follow-up prompt to a LIVE session and report whether it landed. claude: through the rendezvous
-  // control socket — an ATOMIC reply+repaint chunk whose `repaint-done` proves the reply was PARSED; a close
-  // before it proves a concurrent connect kicked the chunk (the daemon is single-connection) → resend; a wall
-  // expiry on a still-open connection is a busy-not-lost agent → optimistic ok (see replyViaSocket). codex:
-  // JSON-RPC on the same app-server WebSocket the
+  // Poke a live session and report whether this immediate channel accepted the attempt. Claude-family adapters
+  // write one idempotent rendezvous reply; Codex uses 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.
+  // `ok=false` leaves the message OWED on the session's delivery queue, for a later pass to hand over.
   deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>
   // Observe native turn failures that this harness does not expose as a lifecycle hook. The adapter owns the
   // transport subscription; sessions owns observer reconciliation and the active-only lifecycle CAS.
@@ -311,10 +314,12 @@ export interface Harness {
   // Project-scoped runtimes are adapter facts. Resource governance consumes these descriptors to report
   // references and protect a sibling-owned control plane without learning harness command names.
   sharedRuntimes?(runtimeDir: string): readonly SharedRuntimeDescriptor[]
-  // the ONE pane state where this harness SWALLOWS a prompt that its delivery channel confirms (so no
-  // socket-side check can see it): given the live pane text, return the loud human-readable refusal (naming
-  // the recovery) or null when the pane can take a prompt. sendText captures the pane once and consults this
-  // BEFORE delivering; absent on harnesses with no such state (codex delivery ignores the pane). claude: the
+  // Select the exact shared descriptor a record owns when an adapter has more than one resident generation.
+  // Null is an unproven binding and must fail closed before lifecycle mutation.
+  targetDescriptorKey?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): string | null
+  // The one pane state where this harness swallows an immediate poke: given live pane text, return the reason
+  // to skip that courtesy attempt or null when the pane can take it. sendText consults this after append;
+  // absent on harnesses whose poke ignores pane state. Claude's
   // TUI's sessions panel ("← for agents") enqueues an injected reply to the panel context and never drains it
   // — verified live: parsed + enqueued, no dequeue, no turn, daemon silent.
   deliveryBlockedBy?(paneText: string): string | null
@@ -338,26 +343,20 @@ export interface Harness {
   resumeArg(rec: { session: string; harnessSessionId?: string | null }): string
 }
 
-// A prompt-dispatch outcome. `accepted` means the native control plane acknowledged the turn; `rejected` means
-// it definitely did not; `commit-unknown` means the request crossed a transport boundary but its native result
-// was lost, so replaying it could duplicate a turn. The latter is deliberately distinct from a normal rejection.
-export type DispatchOutcome = 'accepted' | 'rejected' | 'commit-unknown'
-// ok=true means delivery is confirmed at the layer that harness proves it: claude at
-// the DAEMON-PARSE layer (the atomic reply+repaint chunk answered `repaint-done`, or the wall expired on a
-// still-open connection — busy, not lost; see replyViaSocket); codex at the application layer (the app-server
-// accepted `turn/steer`/`turn/start`). `error` carries a human-readable reason that propagates to the API route
-// (non-2xx) and the CLI/dashboard. Defined here because it is the harness DELIVERY contract; sessions.ts
-// re-exports it for its existing importers.
-export type DispatchResult = { ok: boolean; outcome?: DispatchOutcome; error?: string }
+// `ok` describes only this round's immediate adapter poke: the socket write, native controller request, or
+// app-server turn request reached its channel. [[dispatch]] has already decided delivery at the timeline append,
+// so an error means only that the reader will show the line at a later turn boundary. Defined here because this
+// is the adapter result sessions.ts consumes for same-turn timing.
+export type DispatchResult = { ok: boolean; error?: string }
 export type HarnessDeliveryRecord = {
   session: string
   worktreePath?: string
   harnessSessionId?: string | null
   runtimeDir?: string
   launchCmd?: string | null
-  // Opaque caller-owned marker. Codex maps it to its native `clientUserMessageId`, while other adapters may
-  // ignore it; product routing never needs to know which harness recognizes the marker.
-  deliveryId?: string
+  // The message's timeline id ([[session-timeline]]). Codex maps it to its native `clientUserMessageId`, while
+  // other adapters may ignore it; product routing never needs to know which harness recognizes the marker.
+  mid?: string
 }
 // the on-demand surface artifacts a materialize pass wrote, by node NAME — so clean() knows EXACTLY which
 // skill subdirs / agent files are SpexCode's to remove (name-scoped, never a blind wipe of a dir the user may
@@ -384,8 +383,20 @@ export type HarnessArtifacts = { skills: readonly string[]; agents: readonly str
 // `legacyRvSock` is the answer for a session launched BEFORE the stamp existed — its agent really did bind
 // the unscoped path — so those keep working untouched, and the fallback retires as they turn over.
 export const legacyRvSock = (id: string) => join(tmpdir(), `spexcode-rv-${id}.sock`)
+
+// @@@ rendezvousSocketBase - macOS's TMPDIR commonly expands to /var/folders/<long-user-path>, leaving a
+// UUID-scoped socket beyond its 104-byte sun_path limit. It can be created and observed by pathname but every
+// connect fails EINVAL, which looks exactly like an unresponsive worker. Use a literal short /tmp spelling
+// (not tmpdir(), whose resolved form is long on macOS) with the same private per-uid directory pattern as the
+// Codex runtime socket. Existing launches retain their stamped old path through rvSock(); only new launches use
+// this base.
+const rendezvousSocketBase = () => {
+  const base = join('/tmp', `spexcode-rv-${process.getuid?.() ?? 0}`)
+  mkdirSync(base, { recursive: true, mode: 0o700 })
+  return base
+}
 export const scopedRvSock = (id: string, dir = runtimeRoot()) =>
-  join(tmpdir(), `spexcode-rv-${createHash('sha1').update(dir).digest('hex').slice(0, 12)}-${id}.sock`)
+  join(rendezvousSocketBase(), `spexcode-rv-${createHash('sha1').update(dir).digest('hex').slice(0, 12)}-${id}.sock`)
 const rvStamp = (id: string) => sessionArtifactPath(id, 'rv.path')
 export const rvSock = (id: string): string => {
   try { return readFileSync(rvStamp(id), 'utf8').trim() || legacyRvSock(id) } catch { return legacyRvSock(id) }
@@ -451,9 +462,7 @@ export const rendezvousListening = (id: string, timeoutMs = 800): Promise<Listen
 // (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`)
+  return codexGenerationSocketPath(dir)
 }
 export const codexAppServerPid = (dir = runtimeRoot()) => join(dir, 'codex-app-server.pid')
 export const codexAppServerReceipt = (dir = runtimeRoot()) => join(dir, 'codex-app-server.detached.json')
@@ -462,11 +471,11 @@ type CodexRuntimeGenerationProof = Readonly<{
   identity: VerifiedDetachedRuntime
   socket: Readonly<{ path: string; dev: number; ino: number }>
 }>
-function codexRuntimeGenerationProof(dir = runtimeRoot()): CodexRuntimeGenerationProof | null {
+function codexRuntimeGenerationProof(dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)): CodexRuntimeGenerationProof | null {
   try {
-    const pid = Number(readFileSync(codexAppServerPid(dir), 'utf8').trim())
-    const detached = verifyDetachedRuntime(pid, codexAppServerReceipt(dir))
-    const socketPath = codexAppServerSock(dir)
+    const pid = Number(readFileSync(endpoint.pidFile, 'utf8').trim())
+    const detached = verifyDetachedRuntime(pid, endpoint.receiptFile)
+    const socketPath = endpoint.socketPath
     const socket = statSync(socketPath)
     if (!(pid > 0) || !detached.ok || !socket.isSocket()) return null
     return Object.freeze({
@@ -477,21 +486,31 @@ function codexRuntimeGenerationProof(dir = runtimeRoot()): CodexRuntimeGeneratio
 }
 const codexRuntimeGenerationToken = (proof: CodexRuntimeGenerationProof) =>
   `${detachedRuntimeGenerationToken(proof.identity)}|${proof.socket.path}|${proof.socket.dev}:${proof.socket.ino}`
-function codexRuntimeGeneration(dir = runtimeRoot()): string | null {
-  const proof = codexRuntimeGenerationProof(dir)
+function codexRuntimeGeneration(dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)): string | null {
+  const proof = codexRuntimeGenerationProof(dir, endpoint)
   return proof ? codexRuntimeGenerationToken(proof) : null
 }
 
-function codexMutationGeneration(dir = runtimeRoot()): string | null {
-  const current = codexRuntimeGeneration(dir)
+function codexMutationGeneration(dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)): string | null {
+  const current = codexRuntimeGeneration(dir, endpoint)
   if (current) return current
+  if (endpoint.id !== 'legacy') return null
   let pid: number
   try {
     pid = Number(readFileSync(codexAppServerPid(dir), 'utf8').trim())
     if (!Number.isInteger(pid) || pid <= 0 || !statSync(codexAppServerSock(dir)).isSocket()) return null
   } catch { return null }
   if (!migrateLegacyDetachedRuntimeReceipt(pid, codexAppServerLegacyScope(dir), codexAppServerReceipt(dir))) return null
-  return codexRuntimeGeneration(dir)
+  return codexRuntimeGeneration(dir, endpoint)
+}
+
+const codexDescriptorKey = (endpoint: CodexGenerationEndpoint) => endpoint.id === 'legacy' ? 'codex-app-server' : `codex-app-server:${endpoint.id}`
+
+function codexEndpointForRecord(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }, dir = runtimeRoot()): CodexGenerationEndpoint | null {
+  if (!rec.harnessSessionId) return null
+  const ledger = readCodexGenerationLedger(dir)
+  if (ledger.revision === 0 && !ledger.current && !Object.keys(ledger.generations).length) return legacyCodexGenerationEndpoint(dir)
+  return resolveCodexGenerationForSession(dir, rec.session, rec.harnessSessionId)
 }
 
 // the spex launcher (bin/spex.mjs), baked into the codex launch script (mirrors materialize.ts's SPEX) so
@@ -501,94 +520,59 @@ function codexMutationGeneration(dir = runtimeRoot()): string | null {
 const PKG = fileURLToPath(new URL('..', import.meta.url))
 const SPEX = join(PKG, 'bin', 'spex.mjs')
 
-// @@@ replyViaSocket - ATOMIC parse-confirmed delivery. The daemon is SINGLE-CONNECTION: a new connect
-// `destroy()`s the previous socket, discarding any received-but-not-yet-parsed line with it — and our own
-// `rendezvousListening` liveness probe IS such a connect, fired for every session on every board snapshot. So
-// the previous optimistic write (return ok once the reply line flushed) LOST prompts whenever a probe landed in
-// the write→parse window, a window that widens exactly when claude is busy mid-turn (field: dashboard messages
-// recorded `sent` with no trace in the claude transcript; measured 2/10 lost under a 20ms probe hammer). The
-// daemon parses a chunk's complete lines in ONE synchronous loop, so writing `{type:reply}` + `{type:repaint}`
-// as ONE chunk makes the pair indivisible — a kick loses BOTH or NEITHER — and the outcome decidable from this
-// connection alone:
-//   `repaint-done` arrives  → the reply line before it was parsed (in-order barrier) → ok, CONFIRMED.
-//   'close' before it       → the chunk was never parsed (kicked by a concurrent connect) → resolve kicked:true
-//                             so deliverViaRendezvous RESENDS — a proven loss, so the retry cannot duplicate.
-//   wall expires, conn open → a busy event loop is DELAYING, not losing (the 2500ms-wall lesson: ack absence is
-//                             NOT non-delivery) → ok, OPTIMISTIC — never a false failure on a busy worker.
-//   `reply-rejected`/`auth-rejected`/`shutting-down` → loud failure, not retried.
-// Other daemon lines (heartbeat, state patches) are ignored. Never throws.
-type ReplyOutcome = DispatchResult & { kicked?: boolean }
-function replyViaSocket(sock: string, text: string, wallMs = 10_000): Promise<ReplyOutcome> {
+// The timeline is the message's copy, so rendezvous needs no receipt protocol. It writes one idempotent poke
+// carrying the timeline mid and reports only whether that write reached the local transport.
+function replyViaSocket(sock: string, text: string, mid?: string): Promise<DispatchResult> {
   return new Promise((resolve) => {
     let settled = false
     let c: ReturnType<typeof createConnection>
-    const done = (r: ReplyOutcome) => {
+    const done = (r: DispatchResult) => {
       if (settled) return
       settled = true
-      clearTimeout(wall)
-      try { c?.destroy() } catch { /* */ }
+      if (!r.ok) try { c?.destroy() } catch { /* */ }
       resolve(r)
     }
-    const wall = setTimeout(() => done({ ok: true }), wallMs)
     try {
       c = createConnection({ path: sock })
     } catch (e) {
       done({ ok: false, error: `rendezvous socket connect threw: ${String(e)}` })
       return
     }
-    // ECONNRESET/EPIPE are the KICK surfacing as an error: the daemon destroy()s the previous connection the
-    // moment a new one connects, and destroying a socket with OUR chunk still unread raises RST — whereas a
-    // parsed chunk answers repaint-done (readable even after a later close) before any clean FIN. So both codes
-    // PROVE the chunk was never parsed → retryable, same as the clean pre-parse close. ECONNREFUSED/ENOENT
-    // (daemon gone) stay loud.
     c.on('error', (e: NodeJS.ErrnoException) => {
       const code = e?.code || String(e)
-      const kicked = code === 'ECONNRESET' || code === 'EPIPE'
-      done({ ok: false, ...(kicked ? { kicked } : {}), error: `rendezvous socket error: ${code} — prompt NOT delivered` })
-    })
-    c.on('close', () => done({ ok: false, kicked: true, error: 'rendezvous connection was closed before the daemon parsed the prompt (kicked by a concurrent connect)' }))
-    c.on('connect', () => c.write(JSON.stringify({ type: 'reply', text }) + '\n' + JSON.stringify({ type: 'repaint' }) + '\n'))
-    let buf = ''
-    c.on('data', (d) => {
-      buf += d.toString('utf8')
-      let nl
-      while ((nl = buf.indexOf('\n')) >= 0) {
-        const line = buf.slice(0, nl)
-        buf = buf.slice(nl + 1)
-        let type = ''
-        try { type = (JSON.parse(line) as { type?: string })?.type ?? '' } catch { continue }
-        if (type === 'repaint-done') return done({ ok: true })
-        if (type === 'reply-rejected' || type === 'auth-rejected') return done({ ok: false, error: `rendezvous daemon rejected the prompt (${type}) — prompt NOT delivered` })
-        if (type === 'shutting-down') return done({ ok: false, error: 'agent is shutting down — prompt NOT delivered' })
-      }
+      done({ ok: false, error: `rendezvous socket error: ${code}` })
     })
+    c.on('close', () => done({ ok: false, error: 'rendezvous connection closed before the poke was written' }))
+    c.on('connect', () => c.write(
+      JSON.stringify({ type: 'reply', text, ...(mid ? { mid } : {}) }) + '\n',
+      (error) => {
+        if (error) return done({ ok: false, error: `rendezvous socket write failed: ${error.message}` })
+        c.end()
+        done({ ok: true })
+      },
+    ))
   })
 }
-// 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 the atomic parse-confirmed write; a KICKED outcome is a proven whole-chunk loss, so it resends
-// (bounded attempts + jitter so re-collision with the probe cadence is unlikely); exhausted retries fail loud.
-const DELIVER_ATTEMPTS = 3
-export async function deliverViaRendezvous(id: string, text: string, wallMs?: number): Promise<DispatchResult> {
+const POKE_ATTEMPTS = 2
+export async function deliverViaRendezvous(id: string, text: string, mid?: string): Promise<DispatchResult> {
   const sock = rvSock(id)
-  if (!existsSync(sock)) return { ok: false, error: `no rendezvous control socket for session ${id} (socketless/old session, or the agent is offline) — prompt NOT delivered` }
-  let last: ReplyOutcome = { ok: false, error: 'not attempted' }
-  for (let attempt = 1; attempt <= DELIVER_ATTEMPTS; attempt++) {
-    last = await replyViaSocket(sock, text, wallMs)
-    if (last.ok || !last.kicked) return { ok: last.ok, ...(last.error ? { error: last.error } : {}) }
-    await new Promise((r) => setTimeout(r, 60 + Math.random() * 140))
+  let last: DispatchResult = { ok: false, error: 'not attempted' }
+  for (let attempt = 0; attempt < POKE_ATTEMPTS; attempt++) {
+    last = await replyViaSocket(sock, text, mid)
+    if (last.ok) return last
   }
-  return { ok: false, error: `rendezvous delivery was kicked by concurrent connects ${DELIVER_ATTEMPTS}× — prompt NOT delivered, retry the send` }
+  return { ok: false, error: `rendezvous poke failed after ${POKE_ATTEMPTS} attempts: ${last.error ?? 'unknown error'}` }
 }
 
 export async function deliverViaSocketOrWake(
   id: string,
   text: string,
+  mid: string | undefined,
   coldWake: () => Promise<DispatchResult>,
   unprovenError: string,
 ): Promise<DispatchResult> {
   const probe = await rendezvousListening(id)
-  if (probe === 'live') return deliverViaRendezvous(id, text)
+  if (probe === 'live') return deliverViaRendezvous(id, text, mid)
   if (probe === 'unproven') return { ok: false, error: unprovenError }
   return coldWake()
 }
@@ -708,18 +692,8 @@ export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: s
   // 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 receipt = codexAppServerReceipt(dir)
-  const log = join(dir, 'codex-app-server.log')
-  const lock = join(dir, 'codex-app-server.lock')
   const script = [
     `dir=${shQuote(dir)}`,
-    `sock=${shQuote(sock)}`,
-    `pid=${shQuote(pid)}`,
-    `receipt=${shQuote(receipt)}`,
-    `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
@@ -727,51 +701,14 @@ export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: s
     // 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"',
-    '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.
-    // For the SAME reason it must carry no session IDENTITY: it is started by whichever session happened to
-    // launch first and then serves every later thread, whose tool shells inherit its env — so a baked
-    // SPEXCODE_SESSION_ID (or any adapter's `sessionEnvVar`) is a stale lie for every session but one, and
-    // still a lie after that session closes and its record is swept (measured: daemons here running for days
-    // under a long-gone session's id). Everything downstream that resolves identity from the env then
-    // mis-attributes; the id it needs — the ACTING thread's — codex injects per command, so stripping the
-    // inherited ones removes a wrong answer without removing a right one ([[harness-adapter]]).
-    // The adapter launches its shared control plane in a new OS process group + session. `nohup` alone was not
-    // a boundary: the Codex Node launcher reset signal handling and died with the tmux pane. The internal helper
-    // uses child_process detached=true, then the process adapter publishes a private receipt only after proving
-    // exact PID/start + PGID (and Linux SID). Every consumer re-verifies that same receipt.
-    `  ( unset ${sessionIdentityEnvVars().join(' ')}; ${SPEX} internal shared-runtime-spawn "$dir" "$log" "$pid" "$receipt" ${server} app-server --listen "unix://$sock" ) || { rmdir "$lockd" 2>/dev/null; exit 1; }`,
-    '  for i in $(seq 1 100); do [ -S "$sock" ] && break; sleep 0.05; done',
+    // The runtime command is the single generation-ledger boundary. A new turn receives canonical `current`;
+    // resume resolves its existing session/thread binding and therefore cannot jump an old conversation to a
+    // replacement root. It prints only shell assignments for the exact proven endpoint.
+    'if [ "$1" = "--resume" ]; then',
+    `  eval "$( ${SPEX} internal codex-generation-session "$dir" "$SPEXCODE_SESSION_ID" "$2" )" || exit 1`,
+    'else',
+    `  eval "$( ${SPEX} internal codex-generation-current "$dir" ${shQuote(server)} )" || exit 1`,
     'fi',
-    'rmdir "$lockd" 2>/dev/null',
-    // The delegated bearer arrived only through fd 9. The shared-spawn helper consumed it (or the already-live
-    // socket made it unnecessary); close and scrub the channel before the per-session Codex client starts.
-    '[ "${SPEXCODE_MAINTENANCE_DELEGATE_FD:-}" != "9" ] || exec 9<&-',
-    'unset SPEXCODE_MAINTENANCE_DELEGATE_FD SPEXCODE_MAINTENANCE_SESSION_ID',
     // 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`
@@ -867,7 +804,15 @@ export function codexTurnFailureObserver(
 ): FailureSubscription {
   const threadId = rec.harnessSessionId
   if (!threadId) return { close: () => {}, closed: Promise.resolve(null) }
-  const sock = codexAppServerSock(rec.runtimeDir || runtimeRoot())
+  const runtimeDir = rec.runtimeDir || runtimeRoot()
+  const endpoint = codexEndpointForRecord(rec, runtimeDir)
+  if (!endpoint) {
+    return {
+      close: () => {},
+      closed: Promise.resolve(`Codex turn observer refused: no exact generation binding for session ${rec.session}`),
+    }
+  }
+  const sock = endpoint.socketPath
   const conn: Socket = createConnection(sock)
   const frames: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
   let upgraded = false, settled = false
@@ -959,9 +904,9 @@ export function codexTurnFailureObserver(
 
 // Protocol-verified cold/restore seam. The Codex schema (`codex app-server generate-json-schema --experimental`)
 // defines thread/archive and thread/unarchive with {threadId}; no guessed method or process command is used.
-type CodexGenerationFence = { dir: string; generation: string }
+type CodexGenerationFence = { dir: string; endpoint: CodexGenerationEndpoint; generation: string }
 function codexThreadMutation(sock: string, method: 'thread/archive' | 'thread/unarchive', threadId: string, fence?: CodexGenerationFence): Promise<{ ok: true } | { ok: false; error: string }> {
-  const generationError = () => fence && codexRuntimeGeneration(fence.dir) !== fence.generation
+  const generationError = () => fence && codexRuntimeGeneration(fence.dir, fence.endpoint) !== fence.generation
     ? `Codex ${method} refused because the shared app-server generation changed`
     : null
   const before = generationError()
@@ -978,7 +923,7 @@ function codexThreadMutation(sock: string, method: 'thread/archive' | 'thread/un
       resolve(r)
     }
     // thread/archive may wait up to 10s in shutdown_and_wait before the server commits; keep a margin so a
-    // legitimate late response is not turned into an early commit-unknown race.
+    // legitimate late response is not turned into an early timeout race.
     const timer = setTimeout(() => done({ ok: false, error: generationError() || `Codex ${method} timed out after 15s` }), 15000)
     conn.on('error', (e) => done({ ok: false, error: generationError() || `Codex ${method} connection failed: ${rpcError(e)}` }))
     conn.on('close', () => { if (!settled) done({ ok: false, error: `Codex app-server closed during ${method}` }) })
@@ -1093,6 +1038,8 @@ export async function codexLoadedReferenceIds(sock: string): Promise<{ ok: true;
   return result.ok ? { ok: true, referenceIds: result.ids } : result
 }
 
+const CODEX_TARGET_TURN_CENSUS_MS = 15_000
+
 function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok: true; turnPresence: 'idle' | 'active' | 'unknown' } | { ok: false; error: string }> {
   return new Promise((resolve) => {
     const conn: Socket = createConnection(sock)
@@ -1102,23 +1049,25 @@ function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok:
       if (settled) return
       settled = true; clearTimeout(timer); try { conn.destroy() } catch {}; resolve(result)
     }
-    const timer = setTimeout(() => done({ ok: false, error: `Codex target thread ${threadId} read timed out after 5000ms` }), 5000)
-    conn.on('error', (error) => done({ ok: false, error: `Codex target thread ${threadId} read failed: ${rpcError(error)}` }))
-    conn.on('close', () => { if (!settled) done({ ok: false, error: `Codex app-server closed during target thread ${threadId} read` }) })
+    const timer = setTimeout(() => done({ ok: false, error: `Codex target thread ${threadId} turn census timed out after ${CODEX_TARGET_TURN_CENSUS_MS}ms` }), CODEX_TARGET_TURN_CENSUS_MS)
+    conn.on('error', (error) => done({ ok: false, error: `Codex target thread ${threadId} turn census failed: ${rpcError(error)}` }))
+    conn.on('close', () => { if (!settled) done({ ok: false, error: `Codex app-server closed during target thread ${threadId} turn census` }) })
     const send = (message: JsonRpc) => conn.write(wsText(JSON.stringify(message)))
     conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))))
     const handle = (json: string) => {
       let message: JsonRpc
       try { message = JSON.parse(json) } catch { return }
-      if (message.error) return done({ ok: false, error: `Codex target thread ${threadId} read failed: ${message.error.message || JSON.stringify(message.error)}` })
+      if (message.error) return done({ ok: false, error: `Codex target thread ${threadId} turn census failed: ${message.error.message || JSON.stringify(message.error)}` })
       if (message.id === 1 && message.result) {
         send({ method: 'initialized', params: {} })
-        return send({ id: 2, method: 'thread/read', params: { threadId, includeTurns: true } })
+        // The guard needs only the current turn. `thread/read {includeTurns:true}` materializes the
+        // entire persisted history, so an old but otherwise healthy thread can time out before close.
+        return send({ id: 2, method: 'thread/turns/list', params: { threadId, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' } })
       }
       if (message.id !== 2 || !message.result) return
-      const turns = (message.result as { thread?: { turns?: unknown } }).thread?.turns
+      const turns = (message.result as { data?: unknown }).data
       if (!Array.isArray(turns)) return done({ ok: true, turnPresence: 'unknown' })
-      return done({ ok: true, turnPresence: activeTurnIdFromThread(message.result) ? 'active' : 'idle' })
+      return done({ ok: true, turnPresence: turns.some((turn) => turn && typeof turn === 'object' && (turn as { status?: unknown }).status === 'inProgress') ? 'active' : 'idle' })
     }
     conn.on('data', (chunk: Buffer) => {
       fs.buf = Buffer.concat([fs.buf, chunk])
@@ -1126,10 +1075,10 @@ function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok:
         const i = fs.buf.indexOf('\r\n\r\n')
         if (i < 0) return
         const head = fs.buf.slice(0, i).toString('utf8')
-        if (!/^HTTP\/1\.1 101/.test(head)) return done({ ok: false, error: `Codex app-server refused target thread ${threadId} read: ${head.split('\r\n')[0]}` })
+        if (!/^HTTP\/1\.1 101/.test(head)) return done({ ok: false, error: `Codex app-server refused target thread ${threadId} turn census: ${head.split('\r\n')[0]}` })
         upgraded = true; fs.buf = fs.buf.slice(i + 4); send(wsInitialize)
       }
-      if (drainWsFrames(fs, conn, handle)) done({ ok: false, error: `Codex app-server closed during target thread ${threadId} read` })
+      if (drainWsFrames(fs, conn, handle)) done({ ok: false, error: `Codex app-server closed during target thread ${threadId} turn census` })
     })
   })
 }
@@ -1168,10 +1117,10 @@ function codexThreadCollection(sock: string, params: Record<string, unknown>): P
   })
 }
 
-async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot()): Promise<SharedRuntimeMutationGuard> {
-  const generationBefore = codexMutationGeneration(dir)
+async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)): Promise<SharedRuntimeMutationGuard> {
+  const generationBefore = codexMutationGeneration(dir, endpoint)
   if (!generationBefore) return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'Codex shared app-server generation is unproven' }
-  const sock = codexAppServerSock(dir)
+  const sock = endpoint.socketPath
   const [loaded, activeDescendants, archivedDescendants] = await Promise.all([
     codexLoadedReferenceIds(sock),
     codexThreadList(sock, { ancestorThreadId: threadId, archived: false, sourceKinds: [] }),
@@ -1190,7 +1139,7 @@ async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot()):
     if (!target.ok) return { healthy: false, referenceIds, targetTurnPresence: 'unknown', descendantIds, error: target.error }
     targetTurnPresence = target.turnPresence
   }
-  if (codexRuntimeGeneration(dir) !== generationBefore)
+  if (codexRuntimeGeneration(dir, endpoint) !== generationBefore)
     return { healthy: false, referenceIds, targetTurnPresence, descendantIds, error: 'shared Codex app-server generation changed during target guard' }
   return { healthy: true, referenceIds, targetTurnPresence, descendantIds }
 }
@@ -1201,6 +1150,7 @@ type CodexColdPlan = Readonly<{
   kind: 'codex-cold-subtree-v1'
   threadId: string
   generation: string
+  endpoint: CodexGenerationEndpoint
   guard: SharedRuntimeMutationGuard
   descendantIds: readonly string[]
   parentEdges: readonly (readonly [string, string])[]
@@ -1220,16 +1170,22 @@ const isCodexColdPlan = (value: unknown): value is CodexColdPlan => {
   if (!value || typeof value !== 'object') return false
   const plan = value as Partial<CodexColdPlan>
   return plan[CODEX_COLD_PLAN] === true && plan.kind === 'codex-cold-subtree-v1' && typeof plan.threadId === 'string' &&
-    typeof plan.generation === 'string' && Array.isArray(plan.descendantIds) &&
+    typeof plan.generation === 'string' && isEndpointLike(plan.endpoint) && Array.isArray(plan.descendantIds) &&
     Array.isArray(plan.parentEdges) && Array.isArray(plan.subtreeIds) &&
     Array.isArray(plan.activeIds) && Array.isArray(plan.archivedIds) && !!plan.guard
 }
 
-async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expectedGeneration?: string): Promise<CodexColdPreflight> {
-  const generation = expectedGeneration ?? codexMutationGeneration(dir)
-  if (!generation || codexRuntimeGeneration(dir) !== generation)
+function isEndpointLike(value: unknown): value is CodexGenerationEndpoint {
+  return !!value && typeof value === 'object' && typeof (value as CodexGenerationEndpoint).id === 'string' &&
+    typeof (value as CodexGenerationEndpoint).pidFile === 'string' && typeof (value as CodexGenerationEndpoint).receiptFile === 'string' &&
+    typeof (value as CodexGenerationEndpoint).socketPath === 'string'
+}
+
+async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expectedGeneration?: string, endpoint = legacyCodexGenerationEndpoint(dir)): Promise<CodexColdPreflight> {
+  const generation = expectedGeneration ?? codexMutationGeneration(dir, endpoint)
+  if (!generation || codexRuntimeGeneration(dir, endpoint) !== generation)
     return { ok: false, reason: 'Codex shared app-server generation is unproven or changed before subtree census' }
-  const sock = codexAppServerSock(dir)
+  const sock = endpoint.socketPath
   const [loaded, activeDescendants, archivedDescendants, archivedList, activeList] = await Promise.all([
     codexLoadedReferenceIds(sock),
     codexThreadCollection(sock, { ancestorThreadId: threadId, archived: false, sourceKinds: [] }),
@@ -1237,7 +1193,7 @@ async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expecte
     codexThreadList(sock, { archived: true, sourceKinds: [] }),
     codexThreadList(sock, { archived: false, sourceKinds: [] }),
   ])
-  if (codexRuntimeGeneration(dir) !== generation)
+  if (codexRuntimeGeneration(dir, endpoint) !== generation)
     return { ok: false, reason: 'shared Codex app-server generation changed during subtree census' }
   if (!loaded.ok) return { ok: false, reason: loaded.error }
   if (!activeDescendants.ok) return { ok: false, reason: activeDescendants.error }
@@ -1290,7 +1246,7 @@ async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expecte
   const loadedSet = new Set(loaded.referenceIds)
   const loadedSubtreeIds = subtreeIds.filter((id) => loadedSet.has(id))
   const turnStates = await Promise.all(loadedSubtreeIds.map(async (id) => ({ id, state: await codexTargetTurnPresence(sock, id) })))
-  if (codexRuntimeGeneration(dir) !== generation)
+  if (codexRuntimeGeneration(dir, endpoint) !== generation)
     return { ok: false, reason: 'shared Codex app-server generation changed during subtree turn census' }
   for (const { id, state } of turnStates) {
     if (!state.ok) return { ok: false, reason: state.error }
@@ -1316,6 +1272,7 @@ async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expecte
     kind: 'codex-cold-subtree-v1',
     threadId,
     generation,
+    endpoint,
     guard,
     descendantIds: Object.freeze([...descendantIds]),
     parentEdges: Object.freeze(parentEdges),
@@ -1354,7 +1311,8 @@ async function codexQuarantineOrphanThread(threadId: string, opts: { excludingSe
   if (plan.activeIds.length !== 1 || plan.activeIds[0] !== threadId || plan.archivedIds.length)
     return { ok: false, reason: `Codex native thread ${threadId} is not one exact active orphan` }
   const siblingIds = plan.guard.referenceIds.filter((id) => id !== threadId)
-  const archived = await codexThreadMutation(codexAppServerSock(dir), 'thread/archive', threadId, { dir, generation })
+  const legacy = legacyCodexGenerationEndpoint(dir)
+  const archived = await codexThreadMutation(legacy.socketPath, 'thread/archive', threadId, { dir, endpoint: legacy, generation })
   if (!archived.ok) return { ok: false, reason: `${archived.error} while archiving orphan Codex thread ${threadId}` }
   const after = await codexColdPreflight(threadId, dir, generation)
   const failed = (reason: string): HarnessOrphanThreadQuarantine => ({ ok: false, reason })
@@ -1379,13 +1337,15 @@ async function codexMutationGuard(
   threadId: string,
   dir = runtimeRoot(),
   opts: { coldReceipt?: unknown } = {},
+  endpoint = legacyCodexGenerationEndpoint(dir),
 ): Promise<SharedRuntimeMutationGuard> {
-  if (opts.coldReceipt === undefined) return codexTargetMutationGuard(threadId, dir)
+  if (opts.coldReceipt === undefined) return codexTargetMutationGuard(threadId, dir, endpoint)
   if (!isCodexColdPlan(opts.coldReceipt) || opts.coldReceipt.threadId !== threadId)
     return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'adapter cold teardown receipt is invalid' }
-  const current = await codexColdPreflight(threadId, dir, opts.coldReceipt.generation)
+  if (opts.coldReceipt.endpoint.id !== endpoint.id) return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'adapter cold teardown receipt names a different generation' }
+  const current = await codexColdPreflight(threadId, dir, opts.coldReceipt.generation, endpoint)
   if (!current.ok) {
-    const guard = await codexTargetMutationGuard(threadId, dir)
+    const guard = await codexTargetMutationGuard(threadId, dir, endpoint)
     return { ...guard, healthy: false, coldTeardownAuthorized: false, error: current.reason }
   }
   const authorized = sameIdSet(opts.coldReceipt.descendantIds, current.receipt.descendantIds) &&
@@ -1401,16 +1361,16 @@ async function codexMutationGuard(
 }
 
 async function codexRestoreColdPlan(plan: CodexColdPlan, dir = runtimeRoot()): Promise<{ ok: true } | { ok: false; reason: string }> {
-  if (codexRuntimeGeneration(dir) !== plan.generation)
+  if (codexRuntimeGeneration(dir, plan.endpoint) !== plan.generation)
     return { ok: false, reason: 'shared Codex app-server generation changed, so no compensation was attempted' }
-  const sock = codexAppServerSock(dir)
+  const sock = plan.endpoint.socketPath
   const [activeBefore, archivedBefore] = await Promise.all([
     codexThreadList(sock, { archived: false, sourceKinds: [] }),
     codexThreadList(sock, { archived: true, sourceKinds: [] }),
   ])
   if (!activeBefore.ok || !archivedBefore.ok)
     return { ok: false, reason: 'archive state is unknown and could not be reconciled' }
-  if (codexRuntimeGeneration(dir) !== plan.generation)
+  if (codexRuntimeGeneration(dir, plan.endpoint) !== plan.generation)
     return { ok: false, reason: 'shared Codex app-server generation changed, so no compensation was attempted' }
   const activeSet = new Set(activeBefore.ids)
   const archivedSet = new Set(archivedBefore.ids)
@@ -1418,7 +1378,7 @@ async function codexRestoreColdPlan(plan: CodexColdPlan, dir = runtimeRoot()): P
     return { ok: false, reason: 'an originally-archived Codex subtree member changed collection; compensation was not authorized' }
   if (plan.activeIds.some((id) => activeSet.has(id) === archivedSet.has(id)))
     return { ok: false, reason: 'an originally-active Codex subtree member has ambiguous collection state' }
-  const fence = { dir, generation: plan.generation }
+  const fence = { dir, endpoint: plan.endpoint, generation: plan.generation }
   const restoreIds = [...plan.activeIds].reverse().filter((id) => archivedSet.has(id))
   for (const id of restoreIds) {
     const restored = await codexThreadMutation(sock, 'thread/unarchive', id, fence)
@@ -1428,7 +1388,7 @@ async function codexRestoreColdPlan(plan: CodexColdPlan, dir = runtimeRoot()): P
     codexThreadList(sock, { archived: false, sourceKinds: [] }),
     codexThreadList(sock, { archived: true, sourceKinds: [] }),
   ])
-  const restored = activeAfter.ok && archivedAfter.ok && codexRuntimeGeneration(dir) === plan.generation &&
+  const restored = activeAfter.ok && archivedAfter.ok && codexRuntimeGeneration(dir, plan.endpoint) === plan.generation &&
     plan.activeIds.every((id) => activeAfter.ids.includes(id) && !archivedAfter.ids.includes(id)) &&
     plan.archivedIds.every((id) => archivedAfter.ids.includes(id) && !activeAfter.ids.includes(id))
   return restored ? { ok: true } : { ok: false, reason: 'compensation failed or archive state is unknown' }
@@ -1485,19 +1445,19 @@ export function codexThreadId(sock: string): Promise<{ ok: true; threadId: strin
 // Resource ownership asks the adapter for what the shared server actually owns now. Records are joined later;
 // they are never treated as references by themselves. A loaded thread is a control-plane reference and its
 // fresh inProgress turn (the same predicate used by delivery) distinguishes active from addressable-idle.
-export function codexSharedRuntimeProbe(dir = runtimeRoot()): Promise<SharedRuntimeProbe> {
-  const sock = codexAppServerSock(dir)
+export function codexSharedRuntimeProbe(dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)): Promise<SharedRuntimeProbe> {
+  const sock = endpoint.socketPath
   return (async () => {
     // File presence is not process identity. A dead PID plus a stale socket file is the normal crash residue;
     // only a live PID and a live listener establish a resident control plane. This keeps a deliberately absent
     // root a healthy empty census while leaving live-but-ambiguous roots loud and visible.
     let pid = 0
-    try { pid = Number(readFileSync(codexAppServerPid(dir), 'utf8').trim()) } catch { /* absent/stale */ }
+    try { pid = Number(readFileSync(endpoint.pidFile, 'utf8').trim()) } catch { /* absent/stale */ }
     const pidLive = pid > 0 && !!processStartToken(pid)
     const listener = await listenerAt(sock, 800)
     if (!pidLive && listener === 'dead') return { healthy: true, references: [] }
     if (!pidLive || listener !== 'live') return { healthy: false, references: [], error: 'Codex shared root state is unknown (PID/listener identity is not proven)' }
-    const generation = codexRuntimeGeneration(dir)
+    const generation = codexRuntimeGeneration(dir, endpoint)
     if (!generation) return { healthy: false, references: [], error: 'Codex shared root detached receipt/socket generation is not proven' }
     return new Promise<SharedRuntimeProbe>((resolve) => {
     const conn: Socket = createConnection(sock)
@@ -1516,7 +1476,7 @@ export function codexSharedRuntimeProbe(dir = runtimeRoot()): Promise<SharedRunt
       settled = true
       clearTimeout(timer)
       try { conn.destroy() } catch { /* */ }
-      resolve(result.healthy && codexRuntimeGeneration(dir) !== generation
+      resolve(result.healthy && codexRuntimeGeneration(dir, endpoint) !== generation
         ? { healthy: false, references: result.references, error: 'Codex shared root detached receipt/socket generation changed during ownership probe' }
         : result)
     }
@@ -1690,7 +1650,6 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
     let buf = Buffer.alloc(0), upgraded = false, settled = false
     let fragOp = 0, fragBuf = Buffer.alloc(0)
     let steering = false   // the id-4 message we sent was a steer → an expectedTurnId race may retry as start(5)
-    let injected = false
     const done = (r: DispatchResult) => {
       if (settled) return
       settled = true
@@ -1698,7 +1657,7 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
       try { conn.destroy() } catch { /* */ }
       resolve(r)
     }
-    const unresolved = (error: string) => done({ ok: false, outcome: injected ? 'commit-unknown' : 'rejected', error })
+    const unresolved = (error: string) => done({ ok: false, error })
     const timer = setTimeout(() => unresolved(`codex app-server did not confirm the turn within ${codexTurnConfirmMs()}ms`), codexTurnConfirmMs())
     conn.on('error', (e) => unresolved(`codex app-server connection failed: ${rpcError(e)}`))
     conn.on('close', () => unresolved('codex app-server closed the connection before the turn was confirmed'))
@@ -1715,7 +1674,7 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
           return send(codexInjectMessage(threadId, text, cwd, null, 5, clientUserMessageId))
         if (m.id === 3)                                                     // thread not readable yet (a freshly-started thread is "not materialized
           return send(codexInjectMessage(threadId, text, cwd, null, 5, clientUserMessageId)) // before its first user message") → just turn/start
-        return done({ ok: false, outcome: 'rejected', error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` })
+        return done({ ok: false, error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` })
       }
       // JSON-RPC initialization is ordered. Under a quiet server the premature notification happened to win;
       // under shared app-server load it was ignored and every later turn waited until the old 5s wall expired.
@@ -1723,16 +1682,15 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
       if (m.id === 2 && m.result) {                                         // loaded-thread list → confirm OUR thread is live, then read it
         const loaded = (m.result as { data?: unknown })?.data
         if (Array.isArray(loaded) && !loaded.includes(threadId))
-          return done({ ok: false, error: `Codex thread ${threadId} is not loaded in the app-server (loaded: ${loaded.join(', ') || 'none'}) — prompt NOT delivered` })
+          return done({ ok: false, error: `Codex thread ${threadId} is not loaded in the app-server (loaded: ${loaded.join(', ') || 'none'}) — immediate poke not accepted` })
         return send(hs[3])                                                 // thread is live → read it to decide steer-vs-start
       }
       if (m.id === 3 && m.result) {                                        // thread read → in-progress turn? steer into it; else start a new one
         const turnId = activeTurnIdFromThread(m.result)
         steering = !!turnId
-        injected = true
         return send(codexInjectMessage(threadId, text, cwd, turnId, 4, clientUserMessageId)) // id 4: turn/steer the live turn, or turn/start
       }
-      if ((m.id === 4 || m.id === 5) && m.result) return done({ ok: true, outcome: 'accepted' }) // steer/start accepted → the model has the message
+      if ((m.id === 4 || m.id === 5) && m.result) return done({ ok: true }) // steer/start accepted → the model has the message
     }
     const drainFrames = () => {
       for (;;) {
@@ -1811,26 +1769,29 @@ export async function waitForCodexRollout(threadId: string, timeoutMs = 20000):
   }
 }
 
-// codex's deliver: use the Codex app-server JSON-RPC channel that also powers rich clients, never TUI typing.
+// codex's immediate poke uses the 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
-// id or socket is a loud failure; there is no tmux send-keys fallback because that reports "typed", not "accepted".
+// id or socket makes this poke fail; there is no tmux send-keys fallback because that reports "typed", not "accepted".
 const pexec = promisify(execFile)
 const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
 async function deliverViaCodexAppServer(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult> {
   // the socket is PER-PROJECT (the runtime root), shared by every worktree's thread; the owned thread id on
   // the record picks out THIS session's thread.
-  const sock = codexAppServerSock(rec.runtimeDir)
-  if (!existsSync(sock)) return { ok: false, error: `no Codex app-server socket for this project — prompt NOT delivered` }
+  const runtimeDir = rec.runtimeDir ?? runtimeRoot()
+  const endpoint = rec.harnessSessionId ? codexEndpointForRecord(rec, runtimeDir) : currentCodexGeneration(runtimeDir)
+  if (!endpoint) return { ok: false, error: `no exact Codex generation binding for session ${rec.session} — immediate poke unavailable` }
+  const sock = endpoint.socketPath
+  if (!existsSync(sock)) return { ok: false, error: `no Codex app-server socket for this project — immediate poke unavailable` }
   // use the backend-owned thread id stored at launch; fall back to reading the one loaded thread only if it's
   // empty (a pre-existing session from before the id was stored).
   let threadId = rec.harnessSessionId
   if (!threadId) {
     const r = await codexThreadId(sock)
-    if (!r.ok) return { ok: false, error: `${r.error} — prompt NOT delivered` }
+    if (!r.ok) return { ok: false, error: `${r.error} — immediate poke unavailable` }
     threadId = r.threadId
   }
-  return sendCodexAppServerTurn(sock, threadId, text, rec.worktreePath, rec.deliveryId)
+  return sendCodexAppServerTurn(sock, threadId!, text, rec.worktreePath, rec.mid)
 }
 
 // idempotent replace of the content between sentinels; the user's own content above/below is preserved. The
@@ -2179,12 +2140,12 @@ export const claudeHarness: Harness = {
   // dead-pane-reads-working bug). See rendezvousListening.
   liveness: socketListenerLiveness,
   leafOwnerNeedle: (rec) => rec.session,
-  deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
+  deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
   cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
   coldRuntime: async () => ({ ok: true }),
-  // the TUI's sessions panel ("← for agents"): a reply injected here is parsed + enqueued to the PANEL context
-  // and never drained (verified live: `queue-operation: enqueue` with no dequeue, no turn, daemon silent), so
-  // the parse-confirmed delivery above would still report a false success into it. Matched on the panel's own
+  // The TUI's sessions panel ("← for agents") swallows an injected reply into PANEL context and never drains it
+  // (verified live: `queue-operation: enqueue` with no dequeue, no turn, daemon silent), so skip this courtesy
+  // poke and leave the timeline reader to show the message. Matched on the panel's own
   // strings — the new-session composer placeholder, or its footer key hints together (either alone could drift
   // across claude versions; requiring the footer PAIR keeps a prose false-positive unlikely).
   deliveryBlockedBy: (paneText) =>
@@ -2220,6 +2181,36 @@ export const claudeHeadlessHarness: Harness = {
   deliveryBlockedBy: undefined,
 }
 
+function codexRuntimeDescriptor(endpoint: CodexGenerationEndpoint, runtimeDir: string): SharedRuntimeDescriptor {
+  return {
+    key: codexDescriptorKey(endpoint),
+    label: endpoint.id === 'legacy' ? 'Codex app-server' : `Codex app-server ${endpoint.id.slice(0, 18)}`,
+    pidFile: endpoint.pidFile,
+    receiptFile: endpoint.receiptFile,
+    residency: async () => {
+      let pid = 0
+      try { pid = Number(readFileSync(endpoint.pidFile, 'utf8').trim()) } catch { /* stale/missing pid */ }
+      const pidLive = pid > 0 && !!processStartToken(pid)
+      const listener = await listenerAt(endpoint.socketPath, 800)
+      if (!pidLive && listener === 'dead') return { healthy: true, referenceIds: [], rootAbsent: true }
+      if (pidLive && (!codexRuntimeGeneration(runtimeDir, endpoint) || listener !== 'live'))
+        return { healthy: false, referenceIds: [], error: 'Codex shared root identity/socket generation is not proven' }
+      if (!pidLive || listener !== 'live')
+        return { healthy: false, referenceIds: [], error: 'Codex shared root state is unknown' }
+      const result = await codexLoadedReferenceIds(endpoint.socketPath)
+      return result.ok ? { healthy: true, referenceIds: result.referenceIds } : { healthy: false, referenceIds: [], error: result.error }
+    },
+    mutationGuard: (targetReferenceId, opts) => codexMutationGuard(targetReferenceId, runtimeDir, opts, endpoint),
+    probe: () => codexSharedRuntimeProbe(runtimeDir, endpoint),
+  }
+}
+
+function codexRuntimeDescriptors(runtimeDir: string): SharedRuntimeDescriptor[] {
+  const endpoints = codexGenerationEndpoints(runtimeDir)
+  return (endpoints.length ? endpoints : [legacyCodexGenerationEndpoint(runtimeDir)])
+    .map((endpoint) => codexRuntimeDescriptor(endpoint, runtimeDir))
+}
+
 export const codexHarness: Harness = {
   id: 'codex',
   dispatchId: 'codex',
@@ -2292,14 +2283,20 @@ export const codexHarness: Harness = {
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
   observeTurnFailures: codexTurnFailureObserver,
   cleanupRuntime: async () => { /* project-scoped app-server is shared; no per-session transport to remove */ },
+  targetDescriptorKey: (rec) => {
+    const endpoint = codexEndpointForRecord(rec)
+    return endpoint ? codexDescriptorKey(endpoint) : null
+  },
   coldRetirementPreflight: async (rec) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
     const threadId = rec.harnessSessionId
     const dir = runtimeRoot()
-    const generationBefore = codexRuntimeGeneration(dir)
+    const endpoint = codexEndpointForRecord(rec, dir)
+    if (!endpoint) return { ok: false, reason: 'no exact Codex generation binding is registered for this target' }
+    const generationBefore = codexRuntimeGeneration(dir, endpoint)
     if (!generationBefore) return { ok: false, reason: 'Codex shared app-server generation is unproven' }
-    const result = await codexColdPreflight(threadId, dir, generationBefore)
-    if (codexRuntimeGeneration(dir) !== generationBefore)
+    const result = await codexColdPreflight(threadId, dir, generationBefore, endpoint)
+    if (codexRuntimeGeneration(dir, endpoint) !== generationBefore)
       return { ok: false, reason: 'shared Codex app-server generation changed during cold retirement guard' }
     if (!result.ok) return result
     if (!result.alreadyCold)
@@ -2308,21 +2305,25 @@ export const codexHarness: Harness = {
   },
   coldPreflight: async (rec) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
-    return codexColdPreflight(rec.harnessSessionId)
+    const endpoint = codexEndpointForRecord(rec)
+    return endpoint ? codexColdPreflight(rec.harnessSessionId, runtimeRoot(), undefined, endpoint)
+      : { ok: false, reason: 'no exact Codex generation binding is registered for this target' }
   },
   coldRuntime: async (rec, suppliedReceipt) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
     const threadId = rec.harnessSessionId
     const dir = runtimeRoot()
-    const sock = codexAppServerSock(dir)
-    const generationBefore = codexRuntimeGeneration(dir)
+    const endpoint = codexEndpointForRecord(rec, dir)
+    if (!endpoint) return { ok: false, reason: 'no exact Codex generation binding is registered for this target' }
+    const sock = endpoint.socketPath
+    const generationBefore = codexRuntimeGeneration(dir, endpoint)
     if (!generationBefore) return { ok: false, reason: 'Codex shared app-server generation is unproven' }
     if (suppliedReceipt !== undefined && (!isCodexColdPlan(suppliedReceipt) || suppliedReceipt.threadId !== threadId))
       return { ok: false, reason: 'Codex cold teardown receipt is missing, malformed, or names a different target' }
     const frozenPlan = isCodexColdPlan(suppliedReceipt) ? suppliedReceipt : null
-    if (frozenPlan && frozenPlan.generation !== generationBefore)
+    if (frozenPlan && (frozenPlan.generation !== generationBefore || frozenPlan.endpoint.id !== endpoint.id))
       return { ok: false, reason: 'shared Codex app-server generation changed after archive preflight' }
-    const preflight = await codexColdPreflight(threadId, dir, frozenPlan?.generation ?? generationBefore)
+    const preflight = await codexColdPreflight(threadId, dir, frozenPlan?.generation ?? generationBefore, endpoint)
     if (!preflight.ok) return preflight
     const plan = frozenPlan ?? preflight.receipt
     if (frozenPlan && (!sameIdSet(frozenPlan.descendantIds, preflight.receipt.descendantIds) ||
@@ -2330,12 +2331,12 @@ export const codexHarness: Harness = {
       !sameIdSet(frozenPlan.activeIds, preflight.receipt.activeIds) ||
       !sameIdSet(frozenPlan.archivedIds, preflight.receipt.archivedIds)))
       return { ok: false, reason: 'Codex target subtree ownership or collection assignment changed after archive preflight' }
-    if (codexRuntimeGeneration(dir) !== plan.generation)
+    if (codexRuntimeGeneration(dir, endpoint) !== plan.generation)
       return { ok: false, reason: 'shared Codex app-server generation changed during target subtree guard' }
     if (plan.activeIds.length === 0) return { ok: true }
     const subtreeSet = new Set(plan.subtreeIds)
     const siblingBefore = plan.guard.referenceIds.filter((referenceId) => !subtreeSet.has(referenceId))
-    const fence = { dir, generation: plan.generation }
+    const fence = { dir, endpoint, generation: plan.generation }
 
     const compensate = async (reason: string): Promise<{ ok: false; reason: string }> => {
       const restored = await codexRestoreColdPlan(plan, dir)
@@ -2343,9 +2344,9 @@ export const codexHarness: Harness = {
     }
 
     const coldCheck = async (): Promise<{ ok: true } | { ok: false; reason: string }> => {
-      const after = await codexColdPreflight(threadId, dir, plan.generation)
+      const after = await codexColdPreflight(threadId, dir, plan.generation, endpoint)
       if (!after.ok) return after
-      if (codexRuntimeGeneration(dir) !== plan.generation) return { ok: false, reason: 'shared Codex app-server generation changed during archive' }
+      if (codexRuntimeGeneration(dir, endpoint) !== plan.generation) return { ok: false, reason: 'shared Codex app-server generation changed during archive' }
       if (!sameIdSet(plan.descendantIds, after.receipt.descendantIds) || !sameParentEdges(plan.parentEdges, after.receipt.parentEdges))
         return { ok: false, reason: `Codex target descendant closure changed during archive (before=${plan.descendantIds.join(', ')}; after=${after.receipt.descendantIds.join(', ')})` }
       if (after.receipt.activeIds.length)
@@ -2378,7 +2379,9 @@ export const codexHarness: Harness = {
         return { ok: false, reason: 'Codex cold compensation receipt is invalid or names a different target' }
       return codexRestoreColdPlan(suppliedReceipt)
     }
-    const sock = codexAppServerSock(runtimeRoot())
+    const endpoint = codexEndpointForRecord(rec)
+    if (!endpoint) return { ok: false, reason: 'no exact Codex generation binding is registered for this target' }
+    const sock = endpoint.socketPath
     const reconcile = async (): Promise<{ ok: true } | { ok: false; reason: string }> => {
       const [active, archived] = await Promise.all([
         codexThreadList(sock, { archived: false, sourceKinds: [] }),
@@ -2395,28 +2398,7 @@ export const codexHarness: Harness = {
     if (!restored.ok) return reconcile()
     return reconcile()
   },
-  sharedRuntimes: (runtimeDir) => [{
-    key: 'codex-app-server',
-    label: 'Codex app-server',
-    pidFile: codexAppServerPid(runtimeDir),
-    receiptFile: codexAppServerReceipt(runtimeDir),
-    residency: async () => {
-      const sock = codexAppServerSock(runtimeDir)
-      let pid = 0
-      try { pid = Number(readFileSync(codexAppServerPid(runtimeDir), 'utf8').trim()) } catch { /* stale/missing pid */ }
-      const pidLive = pid > 0 && !!processStartToken(pid)
-      const listener = await listenerAt(sock, 800)
-      if (!pidLive && listener === 'dead') return { healthy: true, referenceIds: [], rootAbsent: true }
-      if (pidLive && (!codexRuntimeGeneration(runtimeDir) || listener !== 'live'))
-        return { healthy: false, referenceIds: [], error: 'Codex shared root identity/socket generation is not proven' }
-      if (!pidLive || listener !== 'live')
-        return { healthy: false, referenceIds: [], error: 'Codex shared root state is unknown' }
-      const result = await codexLoadedReferenceIds(sock)
-      return result.ok ? { healthy: true, referenceIds: result.referenceIds } : { healthy: false, referenceIds: [], error: result.error }
-    },
-    mutationGuard: (targetReferenceId, opts) => codexMutationGuard(targetReferenceId, runtimeDir, opts),
-    probe: () => codexSharedRuntimeProbe(runtimeDir),
-  }],
+  sharedRuntimes: codexRuntimeDescriptors,
   // 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.
@@ -2485,10 +2467,12 @@ const governedSharedRuntimeOwners = (runtimeDir: string, descriptorKey: string,
 async function codexHeadlessReadinessProof(current: () => HarnessLaunchReadyRecord | null): Promise<CodexHeadlessLaunchReadinessProof | null> {
   const record = current()
   if (!record?.governed || record.stopped || record.archived || !record.harnessSessionId) return null
+  const endpoint = codexEndpointForRecord(record, record.runtimeDir)
+  if (!endpoint) return null
   const descriptor = codexHeadlessHarness.sharedRuntimes?.(record.runtimeDir)
-    .find((candidate) => candidate.key === 'codex-app-server')
+    .find((candidate) => candidate.key === codexDescriptorKey(endpoint))
   if (!descriptor?.residency) return null
-  const generationBefore = codexRuntimeGenerationProof(record.runtimeDir)
+  const generationBefore = codexRuntimeGenerationProof(record.runtimeDir, endpoint)
   if (!generationBefore) return null
   let resident: Awaited<ReturnType<NonNullable<SharedRuntimeDescriptor['residency']>>>
   try { resident = await descriptor.residency() }
@@ -2497,7 +2481,7 @@ async function codexHeadlessReadinessProof(current: () => HarnessLaunchReadyReco
   if (!resident.referenceIds.includes(record.harnessSessionId)) return null
   const owners = governedSharedRuntimeOwners(record.runtimeDir, descriptor.key, record.harnessSessionId)
   if (!owners || owners.length !== 1 || owners[0] !== record.session) return null
-  const generationAfter = codexRuntimeGenerationProof(record.runtimeDir)
+  const generationAfter = codexRuntimeGenerationProof(record.runtimeDir, endpoint)
   if (!generationAfter || codexRuntimeGenerationToken(generationBefore) !== codexRuntimeGenerationToken(generationAfter)) return null
   return Object.freeze({
     kind: 'codex-headless-shared-runtime',
@@ -2555,7 +2539,7 @@ export const codexHeadlessHarness: Harness = {
 // 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 (the adapter's launchEnv exports
 // CLAUDE_BG_RENDEZVOUS_SOCK) speaking the reclaude line protocol — so
-// deliverViaRendezvous and the socket-listener liveness work UNCHANGED. Trust: pi gates project-local
+// deliverViaRendezvous and the socket-listener liveness work through the same adapter seam. 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.
@@ -2589,7 +2573,7 @@ export const piHarness: Harness = {
   // socket the generated extension binds. socketLive is already probed for every windowed session.
   liveness: socketListenerLiveness,
   leafOwnerNeedle: (rec) => rec.session,
-  deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
+  deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
   cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
   coldRuntime: async () => ({ ok: true }),
   // reopen the SAME conversation: `--session <id>` resumes the exact session we pinned at launch and FAILS
@@ -2622,8 +2606,7 @@ export const opencodeHarness: Harness = {
   headless: false,
   events: OPENCODE_EVENTS,
   // LITERALLY true: the generated plugin ([[opencode-harness]], opencode.ts) BINDS the per-session rendezvous
-  // socket the launch env hands it and speaks the reply/repaint mini-protocol, so claude's deliver (atomic
-  // parse-confirmed write) and socket-listener liveness are reused verbatim — no opencode transport code.
+  // socket the launch env hands it, so the shared reply poke and socket-listener liveness are reused verbatim.
   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)
@@ -2655,7 +2638,7 @@ export const opencodeHarness: Harness = {
   // load still reads honestly from the process signal instead of a false offline.
   liveness: socketListenerOrPidAliveLiveness,
   leafOwnerNeedle: (rec) => rec.session,
-  deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
+  deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
   cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
   coldRuntime: async () => ({ ok: true }),
   // owned opencode session id → `--resume <id>` marker (the launch script re-attaches `--session <id>`, the
@@ -2681,6 +2664,7 @@ export const opencodeHeadlessHarness: Harness = {
     return deliverViaSocketOrWake(
       rec.session,
       text,
+      rec.mid,
       () => spawnOpenCodeHeadlessTurn(rec, text, opencodeBaseCmd(rec.launchCmd ?? undefined), rvSock(rec.session)),
       `opencode-headless rendezvous probe was inconclusive for session ${rec.session} - refusing to start a possibly duplicate turn`,
     )