@jhizzard/termdeck 1.2.0 → 1.3.0

package/packages/cli/src/os-detect.js

@@ -0,0 +1,297 @@
+// Sprint 64 T1 — OS detection module for the unified `termdeck init` wizard.
+//
+// Returns a normalized facts object the wizard branches on for: default shell,
+// node-pty rebuild guidance, install path, autostart unit emission, and the
+// in-Docker fixture detection that Path B / Sprint 67+ multi-port work depends on.
+//
+// All inputs are injectable via the `deps` parameter so tests can pin every
+// branch without touching the actual host. Production callers pass nothing
+// and get real `process.platform` / `os.arch()` / `fs.readFileSync` behavior.
+//
+// Cross-references:
+//  - Sprint 59 T2's `resolveSpawnShell` at packages/server/src/index.js — that
+//    runtime helper chains `config.shell` → `$SHELL` → `/bin/sh`. THIS module's
+//    `defaultShell` field is what the wizard reports / writes; both should agree.
+//  - BACKLOG §D.5 multi-port verification 2026-05-14 15:28 ET — second-instance
+//    boot under WAL-mode SQLite confirmed safe. Path B (per-instance DB, signal
+//    handling, autostart) is Sprint 67+. This module emits autostart STUBS only
+//    with a TODO marker — full wiring deferred per T1 brief §1.2.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Minimal /etc/os-release parser. Strips matched surrounding quotes. Returns
+// an object of all parsed keys (ID, VERSION_ID, PRETTY_NAME, ID_LIKE, etc.)
+// or null if nothing usable parsed.
+function parseOsRelease(content) {
+  if (!content || typeof content !== 'string') return null;
+  const out = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    if (!/^[A-Z][A-Z0-9_]*$/.test(key)) continue;
+    let value = line.slice(eq + 1).trim();
+    if (value.length >= 2) {
+      const first = value[0];
+      const last = value[value.length - 1];
+      if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+        value = value.slice(1, -1);
+      }
+    }
+    out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+// Distro → defaults map. Used by detectOS() for the Linux branch.
+// Keep in sync with INSTALLER-PITFALLS.md taxonomy if new distros show up
+// in Brad's tester pool (currently Ubuntu 24.04 r730; macOS for Joshua).
+const LINUX_DEFAULTS = {
+  ubuntu:   { defaultShell: 'bash', rebuildHint: 'sudo apt install -y build-essential python3' },
+  debian:   { defaultShell: 'bash', rebuildHint: 'sudo apt install -y build-essential python3' },
+  pop:      { defaultShell: 'bash', rebuildHint: 'sudo apt install -y build-essential python3' },
+  linuxmint:{ defaultShell: 'bash', rebuildHint: 'sudo apt install -y build-essential python3' },
+  fedora:   { defaultShell: 'bash', rebuildHint: 'sudo dnf install -y gcc-c++ make python3' },
+  rhel:     { defaultShell: 'bash', rebuildHint: 'sudo dnf install -y gcc-c++ make python3' },
+  centos:   { defaultShell: 'bash', rebuildHint: 'sudo dnf install -y gcc-c++ make python3' },
+  rocky:    { defaultShell: 'bash', rebuildHint: 'sudo dnf install -y gcc-c++ make python3' },
+  alma:     { defaultShell: 'bash', rebuildHint: 'sudo dnf install -y gcc-c++ make python3' },
+  alpine:   { defaultShell: 'sh',   rebuildHint: 'apk add --no-cache build-base python3' },
+  arch:     { defaultShell: 'bash', rebuildHint: 'sudo pacman -S --needed base-devel python' },
+  manjaro:  { defaultShell: 'bash', rebuildHint: 'sudo pacman -S --needed base-devel python' },
+  opensuse: { defaultShell: 'bash', rebuildHint: 'sudo zypper install -t pattern devel_C_C++' },
+};
+
+const ID_LIKE_FALLBACK = [
+  { match: /\b(debian|ubuntu)\b/, defaults: LINUX_DEFAULTS.debian },
+  { match: /\b(rhel|fedora|centos)\b/, defaults: LINUX_DEFAULTS.fedora },
+  { match: /\b(alpine|musl)\b/, defaults: LINUX_DEFAULTS.alpine },
+  { match: /\b(arch)\b/, defaults: LINUX_DEFAULTS.arch },
+  { match: /\b(suse)\b/, defaults: LINUX_DEFAULTS.opensuse },
+];
+
+// Heuristic in-container detection. Multiple signals because no single one
+// is reliable across container runtimes (Docker, Podman, BuildKit, K8s).
+function detectInContainer({ existsSync, readFile, getEnv }) {
+  if (getEnv('container')) return true;             // systemd-nspawn / Podman set this
+  if (existsSync('/.dockerenv')) return true;
+  if (existsSync('/run/.containerenv')) return true; // Podman fixture
+  const cgroup = readFile('/proc/1/cgroup');
+  if (cgroup && /\b(docker|kubepods|containerd|libpod)\b/.test(cgroup)) return true;
+  const mountinfo = readFile('/proc/self/mountinfo');
+  if (mountinfo && /\b(overlay|docker|kubelet)\b/.test(mountinfo)) return true;
+  return false;
+}
+
+// launchd plist stub for macOS. Path B / Sprint 65+ replaces the stub with
+// full wiring including KeepAlive policy variants, log rotation, EnvironmentVariables,
+// and per-port instance labels. v1.3.0 ships stub only.
+function launchdPlistStub(homedir) {
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTD/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <!-- TermDeck launchd autostart STUB — Sprint 64 T1. Full wiring in Sprint 65+. -->',
+    '  <!-- TODO(sprint-65): per-port label, log rotation, EnvironmentVariables block. -->',
+    '  <key>Label</key>',
+    '  <string>com.jhizzard.termdeck</string>',
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    '    <string>/usr/local/bin/termdeck</string>',
+    '    <string>--service</string>',
+    '  </array>',
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>KeepAlive</key>',
+    '  <true/>',
+    '  <key>StandardOutPath</key>',
+    `  <string>${homedir}/.termdeck/termdeck.log</string>`,
+    '  <key>StandardErrorPath</key>',
+    `  <string>${homedir}/.termdeck/termdeck.err.log</string>`,
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+// systemd user unit stub for Linux (outside Docker). Path B / Sprint 65+
+// replaces the stub with full wiring (per-port unit instance, Environment=,
+// proper Restart policy tuning, journald integration). v1.3.0 ships stub only.
+function systemdUserUnitStub() {
+  return [
+    '# TermDeck systemd user unit STUB — Sprint 64 T1. Full wiring in Sprint 65+.',
+    '# TODO(sprint-65): templated unit @<port>, Environment=TERMDECK_PORT=, journald gates.',
+    '#',
+    '# Install:  systemctl --user enable --now termdeck.service',
+    '# Status:   systemctl --user status termdeck.service',
+    '# Logs:     journalctl --user -u termdeck.service -f',
+    '',
+    '[Unit]',
+    'Description=TermDeck — browser terminal multiplexer',
+    'After=network-online.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    'ExecStart=/usr/local/bin/termdeck --service',
+    'Restart=on-failure',
+    'RestartSec=5s',
+    'StandardOutput=append:%h/.termdeck/termdeck.log',
+    'StandardError=append:%h/.termdeck/termdeck.err.log',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+// Detect the host OS and build the wizard-facing facts object.
+//
+// Deps (all optional; tests inject):
+//   platform   — process.platform replacement ('darwin'|'linux'|'win32'|...)
+//   arch       — os.arch() replacement
+//   homedir    — os.homedir() replacement
+//   getEnv     — (key) => string|undefined  (defaults to process.env[key])
+//   readFile   — (path) => string|null
+//   existsSync — (path) => boolean
+//   macosVersion — pre-resolved 'YY.YY.YY' string (e.g. '14.3.1'); when omitted
+//                  the function does NOT shell out (no spawnSync to `sw_vers`)
+//                  — keeps boot deterministic for the wizard. Callers wanting
+//                  the version can pass it via deps.
+//
+// Returns: {
+//   family:        'macos' | 'linux' | 'docker' | 'unknown'
+//   distro:        string | null                    (e.g. 'ubuntu', 'fedora', 'alpine')
+//   version:       string | null                    (VERSION_ID for linux, macosVersion for macos)
+//   isAppleSilicon:boolean                          (true only on darwin+arm64)
+//   inDocker:      boolean                          (always present)
+//   defaultShell:  'zsh' | 'bash' | 'sh'
+//   rebuildHint:   string                           (node-pty rebuild remediation)
+//   paths: {
+//     home, termdeck, secretsEnv, configYaml, autostartDir
+//   }
+//   autostartUnit: { kind, path, content, note? }   (kind: 'launchd'|'systemd'|null)
+// }
+function detectOS(deps) {
+  deps = deps || {};
+  const platform = deps.platform || process.platform;
+  const arch = deps.arch || os.arch();
+  const homedir = deps.homedir || os.homedir();
+  const getEnv = deps.getEnv || ((k) => process.env[k]);
+  const readFile = deps.readFile || ((p) => {
+    try { return fs.readFileSync(p, 'utf8'); }
+    catch (_e) { return null; }
+  });
+  const existsSync = deps.existsSync || ((p) => fs.existsSync(p));
+
+  const termdeckDir = path.join(homedir, '.termdeck');
+  const basePaths = {
+    home: homedir,
+    termdeck: termdeckDir,
+    secretsEnv: path.join(termdeckDir, 'secrets.env'),
+    configYaml: path.join(termdeckDir, 'config.yaml'),
+  };
+
+  if (platform === 'darwin') {
+    const isAppleSilicon = arch === 'arm64';
+    const macosVersion = deps.macosVersion || null;
+    return {
+      family: 'macos',
+      distro: null,
+      version: macosVersion,
+      isAppleSilicon,
+      inDocker: false,
+      defaultShell: 'zsh',
+      rebuildHint: 'xcode-select --install   # installs the macOS Command Line Tools (clang, make)',
+      paths: {
+        ...basePaths,
+        autostartDir: path.join(homedir, 'Library', 'LaunchAgents'),
+      },
+      autostartUnit: {
+        kind: 'launchd',
+        path: path.join(homedir, 'Library', 'LaunchAgents', 'com.jhizzard.termdeck.plist'),
+        content: launchdPlistStub(homedir),
+        note: 'STUB only — full wiring deferred to Sprint 65+',
+      },
+    };
+  }
+
+  if (platform === 'linux') {
+    const inDocker = detectInContainer({ existsSync, readFile, getEnv });
+    const osRelease = parseOsRelease(readFile('/etc/os-release')) || {};
+    const rawId = (osRelease.ID || '').toLowerCase();
+    const idLike = (osRelease.ID_LIKE || '').toLowerCase();
+    const version = osRelease.VERSION_ID || null;
+
+    let distro = rawId || null;
+    let defaults = LINUX_DEFAULTS[rawId];
+    if (!defaults && idLike) {
+      for (const f of ID_LIKE_FALLBACK) {
+        if (f.match.test(idLike)) {
+          defaults = f.defaults;
+          if (!distro) distro = idLike.split(/\s+/)[0];
+          break;
+        }
+      }
+    }
+    if (!defaults) {
+      defaults = { defaultShell: 'bash', rebuildHint: 'install your distro\'s C++ build toolchain (gcc, make, python3)' };
+      if (!distro) distro = 'unknown';
+    }
+
+    const autostartDir = path.join(homedir, '.config', 'systemd', 'user');
+    return {
+      family: inDocker ? 'docker' : 'linux',
+      distro,
+      version,
+      isAppleSilicon: false,
+      inDocker,
+      defaultShell: defaults.defaultShell,
+      rebuildHint: defaults.rebuildHint,
+      paths: {
+        ...basePaths,
+        autostartDir: inDocker ? null : autostartDir,
+      },
+      autostartUnit: inDocker
+        ? {
+            kind: null,
+            path: null,
+            content: null,
+            note: 'in-container fixture — TermDeck runs as the container entrypoint; no per-user systemd unit',
+          }
+        : {
+            kind: 'systemd',
+            path: path.join(autostartDir, 'termdeck.service'),
+            content: systemdUserUnitStub(),
+            note: 'STUB only — full wiring deferred to Sprint 65+',
+          },
+    };
+  }
+
+  return {
+    family: 'unknown',
+    distro: null,
+    version: null,
+    isAppleSilicon: false,
+    inDocker: false,
+    defaultShell: 'sh',
+    rebuildHint: 'install your platform\'s C++ toolchain manually (gcc, make, python3) before re-running termdeck init',
+    paths: { ...basePaths, autostartDir: null },
+    autostartUnit: { kind: null, path: null, content: null, note: 'unknown platform — autostart unit not auto-emitted' },
+  };
+}
+
+module.exports = {
+  detectOS,
+  parseOsRelease,
+  // Exported for tests:
+  _LINUX_DEFAULTS: LINUX_DEFAULTS,
+  _ID_LIKE_FALLBACK: ID_LIKE_FALLBACK,
+  _launchdPlistStub: launchdPlistStub,
+  _systemdUserUnitStub: systemdUserUnitStub,
+  _detectInContainer: detectInContainer,
+};

package/packages/server/src/agent-adapters/claude.js

@@ -221,6 +221,17 @@ const claudeAdapter = {
     binary: 'claude',
     defaultArgs: [],
     env: {},
+    // Sprint 64 T2 (carve-out 2.4) — when shellWrap is `false`, spawnTerminalSession
+    // bypasses the `zsh -c <command>` wrapper and execs `binary` + `defaultArgs`
+    // directly via `pty.spawn`. Preserves the user's PATH lookup of `claude`
+    // while keeping the PTY rooted in an interactive context (zsh -c discards
+    // the TTY-interactive flags Claude Code's input handler needs). Falls back
+    // to the legacy wrapper when the user-supplied `command` carries additional
+    // args (e.g. `claude --resume <uuid>` from a launcher button) so user args
+    // are not silently dropped. See packages/server/src/index.js:1118-1175 for
+    // the dispatch logic and packages/server/tests/adapter-spawn-shell-wrap.test.js
+    // for the fence.
+    shellWrap: false,
   },
   patterns: {
     prompt: PROMPT,

package/packages/server/src/agent-adapters/codex.js

@@ -155,6 +155,41 @@ function _codexCandidateDirs(homedir, now) {
   return out;
 }
 
+// Sprint 64 T2 (carve-out 2.1) — `min(birthtime, mtime)` is the right gate
+// for cross-panel contamination. Sprint 63 EXIT-CAPTURE-VERIFICATION.md
+// Finding #1 documents the failure mode: when codex panel-B spawned and
+// self-exited during the 0.129→0.130 auto-update, panel-A's rollout was
+// still being written by panel-A's ongoing turns; A's `mtimeMs` exceeded
+// B's `createdAtMs`, so A was returned as B's transcript.
+//
+// Why `min(birthtime, mtime)` rather than birthtime alone or mtime alone:
+//   • Cross-panel contamination (Sprint 63 Finding #1): Panel-A active panel
+//     has `birthtime=T_A_create` (in the past) and `mtime=NOW` (bumped each
+//     turn). min = birthtime — correctly rejects when birthtime < spawn time.
+//   • Backdated-mtime stale rollouts: mtime < birthtime. min = mtime —
+//     correctly rejects when backdated mtime < spawn time.
+//   • Same-session rollout (this panel's own): birthtime AND mtime both
+//     post-spawn. min = birthtime ≈ mtime — correctly admits.
+//   • Platforms without birthtime (some Linux tmpfs returns birthtimeMs=0):
+//     fall back to `mtime` for both terms of the min → equivalent to mtime
+//     gate, same behavior as pre-fix.
+//
+// Gate epsilon (per Sprint 64 T4-CODEX 16:21 AUDIT-CONCERN — deterministic
+// pre-spawn rejection on birthtime-capable platforms):
+//   • Birthtime-capable platforms (APFS, ext4 with `statx`, NTFS): STRICT,
+//     no epsilon. Birthtime is deterministic FS metadata — no jitter, no
+//     quantization beyond ~1ns. A file with `birthtimeMs < spawnTimestampMs`
+//     was unambiguously created before this panel spawned and CANNOT be
+//     this panel's rollout. Strict gate is correct.
+//   • Mtime-fallback platforms (rare; some Linux tmpfs): use
+//     `_CODEX_GATE_EPSILON_MS_MTIME_FALLBACK = 5000ms` to absorb FS time
+//     quantization rounding plus any small clock-skew between OS time and
+//     `Date.now()`. mtime can drift in production (active concurrent panel
+//     bumps it), so this epsilon path is intentionally narrower than
+//     birthtime — it's a structural fallback, not a tolerance knob.
+const _CODEX_GATE_EPSILON_MS_BIRTHTIME = 0;
+const _CODEX_GATE_EPSILON_MS_MTIME_FALLBACK = 5000;
+
 async function resolveTranscriptPath(session) {
   const fs = require('fs');
   const path = require('path');
@@ -164,6 +199,15 @@ async function resolveTranscriptPath(session) {
   const createdAtMs = session.meta.createdAt
     ? Date.parse(session.meta.createdAt)
     : 0;
+  // Sprint 64 T2 (carve-out 2.1) — spawnTimestampMs is set in spawnTerminalSession
+  // immediately after `pty.spawn` returns; strictly later than createdAt (which
+  // is set in `sessions.create` BEFORE pty.spawn). Use it when present; fall
+  // back to createdAt for older sessions reloaded from SQLite that pre-date the
+  // field. The `- _CODEX_GATE_EPSILON_MS` accounts for filesystem time-stamp
+  // quantization rounding (worst-case 1s on some platforms).
+  const spawnAtMs = (typeof session.meta.spawnTimestampMs === 'number' && session.meta.spawnTimestampMs > 0)
+    ? session.meta.spawnTimestampMs
+    : createdAtMs;
   const candidates = [];
   for (const dir of _codexCandidateDirs(os.homedir(), Date.now())) {
     let entries;
@@ -174,7 +218,18 @@ async function resolveTranscriptPath(session) {
       const full = path.join(dir, name);
       let st;
       try { st = fs.statSync(full); } catch (_) { continue; }
-      if (createdAtMs && st.mtimeMs < createdAtMs) continue;
+      // Per-file gate: prefer strict birthtime when the platform exposes it;
+      // fall back to epsilon-tolerant mtime only when birthtime is unavailable.
+      // Either signal indicates "this rollout existed before the panel
+      // spawned" → reject the candidate.
+      const hasBirthtime = (typeof st.birthtimeMs === 'number' && st.birthtimeMs > 0);
+      const epsilonForFile = hasBirthtime
+        ? _CODEX_GATE_EPSILON_MS_BIRTHTIME
+        : _CODEX_GATE_EPSILON_MS_MTIME_FALLBACK;
+      const gateMsForFile = spawnAtMs > 0 ? spawnAtMs - epsilonForFile : 0;
+      const fileBirthMs = hasBirthtime ? st.birthtimeMs : st.mtimeMs;
+      const fileMinMs = Math.min(fileBirthMs, st.mtimeMs);
+      if (gateMsForFile && fileMinMs < gateMsForFile) continue;
       candidates.push({ full, mtime: st.mtimeMs });
     }
   }
@@ -264,6 +319,138 @@ function bootPromptTemplate(lane = {}, sprint = {}) {
   ].join('\n');
 }
 
+// ──────────────────────────────────────────────────────────────────────────
+// probeCodexVersion — Sprint 64 T2 (carve-out 2.3).
+//
+// Pre-spawn version probe for the Codex CLI auto-update lifecycle hazard
+// documented in Sprint 63 EXIT-CAPTURE-VERIFICATION.md Finding #1. Codex CLI
+// has no `--no-update` flag (verified 2026-05-11 against codex 0.130.0), so a
+// stale codex panel may fire its interactive update picker on spawn, accept
+// "Update now," `npm install -g @openai/codex`, and exit 0 — BEFORE any canary
+// inject lands. Joshua's Sprint 63 T2 lost a codex canary panel to exactly
+// this failure mode at 13:26 ET.
+//
+// Approach (per Sprint 64 ORCH SCOPE 16:14 ET adjudication of T4-CODEX 16:11
+// AUDIT-CONCERN #3 default-install visibility): two complementary WARN paths.
+//
+//   • **Persisted last-seen-version drift.** Read
+//     `~/.termdeck/.last-codex-version`. Absent → write `observed` silently,
+//     no WARN (first run is "baseline," not "drift"). Present and
+//     `observed !== persisted` → log WARN + update persisted to new observed
+//     (self-heals: next spawn is silent on the new version). Catches the
+//     Sprint 63 auto-update hazard for the default operator with no env-var
+//     setup required. Doesn't false-alarm on stable installs (no env, no
+//     persisted file changes once written).
+//
+//   • **`CODEX_PINNED_VERSION` env knob.** Operator-explicit pin retained
+//     as a separate signal — useful in CI / multi-user installs where the
+//     persisted file is per-user but the pin is global. WARN on observed ≠
+//     pinned; independent of the drift path above.
+//
+// Why not a hardcoded "known-good window"? Codex shipped 0.125 → 0.129 →
+// 0.130 in ~10 days; a baked-in version list goes stale in a week. The
+// persisted-self-heal path is the deterministic answer.
+//
+// Why not a wrapper shim (option B) that intercepts the update picker? The
+// picker has already shifted shape across recent codex releases; a shim that
+// answers "n\n" today may answer "yes\n" to a future renamed prompt. Real
+// fix lives upstream — file a `--no-update` flag against the Codex CLI repo.
+// Tracking that filing is cheaper than maintaining a shim.
+//
+// Dependency-injected `spawnSync` + `logger` + `fsApi` keep the fence test
+// free of a live codex binary on PATH or filesystem dependence.
+// ──────────────────────────────────────────────────────────────────────────
+
+// Module-level constants for testability — ORCH SCOPE 16:14 ET. Fence tests
+// override the path by passing `{ persistedVersionPath: '...' }`.
+const _CODEX_PERSISTED_VERSION_FILENAME = '.last-codex-version';
+
+function _defaultPersistedVersionPath() {
+  const os = require('os');
+  const path = require('path');
+  return path.join(os.homedir(), '.termdeck', _CODEX_PERSISTED_VERSION_FILENAME);
+}
+
+function probeCodexVersion({
+  pinnedVersion = process.env.CODEX_PINNED_VERSION,
+  spawnSync = require('child_process').spawnSync,
+  logger = console,
+  fsApi = require('fs'),
+  persistedVersionPath = _defaultPersistedVersionPath(),
+} = {}) {
+  let observed = null;
+  try {
+    const res = spawnSync('codex', ['--version'], { encoding: 'utf8', timeout: 2000 });
+    if (!res || res.status !== 0 || !res.stdout) {
+      return { ok: null, observed: null, reason: 'probe-failed' };
+    }
+    const match = String(res.stdout).match(/(\d+\.\d+\.\d+)/);
+    observed = match ? match[1] : null;
+  } catch (_) {
+    return { ok: null, observed: null, reason: 'probe-error' };
+  }
+  if (!observed) {
+    return { ok: null, observed: null, reason: 'no-version-string' };
+  }
+
+  // Drift path: compare observed against persisted last-seen value.
+  let persisted = null;
+  let driftDetected = false;
+  try {
+    if (fsApi.existsSync(persistedVersionPath)) {
+      const raw = fsApi.readFileSync(persistedVersionPath, 'utf8');
+      const trimmed = String(raw || '').trim();
+      persisted = trimmed.length > 0 ? trimmed : null;
+    }
+  } catch (_) {
+    // Read failure is non-fatal — treat as absent. Persistence is best-effort.
+    persisted = null;
+  }
+  if (persisted === null) {
+    // First-run baseline — write silently, no WARN.
+    _writePersistedVersion(fsApi, persistedVersionPath, observed);
+  } else if (persisted !== observed) {
+    driftDetected = true;
+    if (logger && typeof logger.warn === 'function') {
+      logger.warn(
+        `[codex] version drift detected: observed=${observed} persisted=${persisted} — `
+        + 'codex CLI may have auto-updated since last spawn (Sprint 63 lifecycle hazard).'
+      );
+    }
+    _writePersistedVersion(fsApi, persistedVersionPath, observed);
+  }
+
+  // Pin path: independent of drift. Warns on every spawn where pin ≠ observed.
+  let pinnedMismatch = false;
+  if (pinnedVersion && observed !== pinnedVersion) {
+    pinnedMismatch = true;
+    if (logger && typeof logger.warn === 'function') {
+      logger.warn(
+        `[codex] version pin mismatch: observed=${observed} pinned=${pinnedVersion} — `
+        + 'CODEX_PINNED_VERSION env var requires explicit re-pin (Sprint 63 lifecycle hazard).'
+      );
+    }
+  }
+
+  if (driftDetected || pinnedMismatch) {
+    return { ok: false, observed, persisted, pinned: pinnedVersion || null, driftDetected, pinnedMismatch };
+  }
+  return { ok: true, observed, persisted, pinned: pinnedVersion || null, driftDetected: false, pinnedMismatch: false };
+}
+
+function _writePersistedVersion(fsApi, p, version) {
+  try {
+    const path = require('path');
+    const dir = path.dirname(p);
+    try { fsApi.mkdirSync(dir, { recursive: true }); }
+    catch (_) { /* fail-soft — usually already exists */ }
+    fsApi.writeFileSync(p, `${version}\n`, 'utf8');
+  } catch (_) {
+    // Persistence failure is non-fatal — WARN behavior is unaffected the
+    // next spawn (we'll re-detect drift against whatever is/isn't on disk).
+  }
+}
+
 const codexAdapter = {
   name: 'codex',
   sessionType: 'codex',
@@ -274,6 +461,14 @@ const codexAdapter = {
     binary: 'codex',
     defaultArgs: [],
     env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY },
+    // Sprint 64 T2 (carve-out 2.4) — direct spawn (no `zsh -c` wrapper) when
+    // the launching command is exactly the binary name. Sprint 63
+    // EXIT-CAPTURE-VERIFICATION.md § 6 flagged this as a probable contributor
+    // to codex's fast-death window during the 2026-05-11 13:26 ET update-picker
+    // event — codex spawned through `zsh -c codex` may have lost the
+    // interactive-TTY context the update-picker dialog needed. See claude.js
+    // for the full rationale + fallback semantics.
+    shellWrap: false,
   },
   patterns: {
     prompt: PROMPT,
@@ -329,4 +524,11 @@ const codexAdapter = {
   },
 };
 
+// Sprint 64 T2 (carve-out 2.3) — expose probeCodexVersion on the adapter object
+// so call sites can `require('./codex').probeCodexVersion(...)` without
+// threading through the registry. Adapter-shape parity tests (Sprint 45 T4's
+// tests/agent-adapter-parity.test.js) iterate a fixed allowlist of fields and
+// tolerate extra properties — adding this function is safe.
+codexAdapter.probeCodexVersion = probeCodexVersion;
+
 module.exports = codexAdapter;

package/packages/server/src/agent-adapters/gemini.js

@@ -247,6 +247,10 @@ const geminiAdapter = {
     // not for in-adapter overriding. OAuth-personal is the typical auth
     // path (settings.json `security.auth.selectedType: 'oauth-personal'`).
     env: {},
+    // Sprint 64 T2 (carve-out 2.4) — direct spawn (no `zsh -c` wrapper) when
+    // the launching command is exactly the binary name. See claude.js for the
+    // full rationale + fallback semantics.
+    shellWrap: false,
   },
   patterns: {
     prompt: PROMPT,

package/packages/server/src/agent-adapters/grok.js

@@ -446,6 +446,10 @@ const grokAdapter = {
     env: {
       GROK_MODEL: chooseModel(),
     },
+    // Sprint 64 T2 (carve-out 2.4) — direct spawn (no `zsh -c` wrapper) when
+    // the launching command is exactly the binary name. See claude.js for the
+    // full rationale + fallback semantics.
+    shellWrap: false,
   },
   patterns: {
     prompt: PROMPT,