sprag-cli 3.53.0 → 3.55.0

package/src/codex-ledger.js

@@ -0,0 +1,143 @@
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { userDataDir } from './paths.js';
+import { discoverCodexSessionFiles, parseCodexTurns } from './codex-parser.js';
+import { codexRunCost, readCodexPrices } from './codex-cache-policy.js';
+
+/*
+ * Codex routing savings, kept apart from Claude's delegation ledger.
+ *
+ * A child rollout only counts when Sprag itself routed it: the spawn rewrite
+ * writes a random route id into the child's message and records the same id
+ * here at that moment. The marker text alone proves nothing, since a model can
+ * write it by hand; the pending record is what shows a rule existed at spawn time.
+ */
+
+export const ROUTE_ID_RE = /<!-- sprag:codex:route id=([0-9a-f]{16}) -->/;
+const PENDING_TTL_MS = 7 * 86400000;
+const pendingFile = (dir) => join(dir, 'codex-delegations.jsonl');
+const ledgerFile = (dir) => join(dir, 'codex-delegation-ledger.json');
+
+export function newRouteId() {
+  return randomBytes(8).toString('hex');
+}
+
+/** One append per spawn. Each line stays well under PIPE_BUF, so parallel spawns do not interleave. */
+export function recordCodexDelegation(entry, { dir = userDataDir() } = {}) {
+  mkdirSync(dir, { recursive: true });
+  const line = JSON.stringify({ ...entry, at: entry.at ?? Date.now() });
+  if (line.length > 3500) throw new Error('Codex delegation record too large');
+  appendFileSync(pendingFile(dir), line + '\n', { mode: 0o600 });
+}
+
+export function readCodexDelegations({ dir = userDataDir() } = {}) {
+  let text;
+  try { text = readFileSync(pendingFile(dir), 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    try {
+      const r = JSON.parse(line);
+      if (r && /^[0-9a-f]{16}$/.test(r.id) && Number.isFinite(r.at) && typeof r.to === 'string') out.push(r);
+    } catch { /* Partial trailing line. */ }
+  }
+  return out;
+}
+
+export function loadCodexLedger({ dir = userDataDir() } = {}) {
+  try {
+    const data = JSON.parse(readFileSync(ledgerFile(dir), 'utf8'));
+    if (data?.version === 1 && data.events && typeof data.events === 'object') return data;
+  } catch { /* Missing or unreadable reads as empty. */ }
+  return { version: 1, events: {} };
+}
+
+function saveLedger(data, dir) {
+  mkdirSync(dir, { recursive: true });
+  const file = ledgerFile(dir), tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+/** The route id a child rollout carries, and its own tokens, or null. */
+async function childRun(path, cutoffMs) {
+  const s = await parseCodexTurns(path, { cutoffMs });
+  if (!s.isSubagent) return null;
+  let id = null;
+  const tokens = { input: 0, cached: 0, cacheWrite: 0, output: 0 };
+  let model = null, startedAt = null, endedAt = null, complete = false, usageKnown = false, mixedModels = false;
+  for (const t of s.turns) {
+    // Only the child's own first message may carry the id; copied history does not count.
+    if (!id && t.text) { const m = ROUTE_ID_RE.exec(t.text); if (m) id = m[1]; }
+    tokens.input += t.input; tokens.cached += t.cached; tokens.cacheWrite += t.cacheWrite; tokens.output += t.out;
+    if (model && t.model && model !== t.model) mixedModels = true;
+    model ??= t.model;
+    usageKnown ||= t.usageKnown;
+    if (Number.isFinite(t.startedAt)) startedAt = Math.min(startedAt ?? t.startedAt, t.startedAt);
+    if (Number.isFinite(t.endedAt)) { endedAt = Math.max(endedAt ?? t.endedAt, t.endedAt); complete = !t.aborted; }
+  }
+  return id ? { id, sessionId: s.sessionId, parentThreadId: s.parentThreadId, provider: s.provider,
+    model, tokens, startedAt, endedAt, complete, usageKnown: usageKnown && !mixedModels } : null;
+}
+
+/**
+ * Join child rollouts to pending routes and price them. Savings hold the
+ * child's tokens constant and price them at the parent model, the same
+ * approximation Claude's ledger states. A route to a pricier model is a loss,
+ * shown as one rather than clamped away.
+ */
+export async function refreshCodexLedger({ dir = userDataDir(), home, now = Date.now(), prices = readCodexPrices({ now, home, dir }) } = {}) {
+  const pending = readCodexDelegations({ dir }).filter((r) => now - r.at < PENDING_TTL_MS);
+  const ledger = loadCodexLedger({ dir });
+  if (!pending.length) return ledger;
+  const byId = new Map(pending.map((r) => [r.id, r]));
+  const oldest = Math.min(...pending.map((r) => r.at));
+  const files = await discoverCodexSessionFiles({ home, days: Math.max(1, (now - oldest) / 86400000 + 1) });
+  let changed = false;
+  const seen = new Set();
+  for (const f of files.slice().reverse()) {
+    if (f.mtime < oldest) continue;
+    let run;
+    try { run = await childRun(f.path, oldest - 60000); } catch { continue; }
+    const route = run && byId.get(run.id);
+    // The id must come from a spawn this parent made, after the record was written.
+    if (!route || (route.parentSessionId && run.parentThreadId && route.parentSessionId !== run.parentThreadId)) continue;
+    if (route.provider && route.provider !== run.provider) continue;
+    if (Number.isFinite(run.startedAt) && run.startedAt < route.at - 5000) continue;
+    if (seen.has(route.id)) continue;
+    seen.add(route.id);
+    const to = run.model || route.to;
+    const previous = ledger.events[route.id];
+    const provider = route.provider || run.provider;
+    const sameRun = previous?.childSessionId === run.sessionId && previous.to === to && previous.from === route.from;
+    const rates = sameRun && previous.rates ? previous.rates
+      : prices?.provider === provider ? { from: prices.prices[route.from], to: prices.prices[to], checkedAt: prices.checkedAt } : null;
+    const actual = rates && run.usageKnown ? codexRunCost(run.tokens, rates.to) : null;
+    const counterfactual = rates && run.usageKnown ? codexRunCost(run.tokens, rates.from) : null;
+    const usd = actual === null || counterfactual === null ? null : counterfactual - actual;
+    const event = { ts: run.endedAt ?? route.at, parentSessionId: route.parentSessionId || run.parentThreadId || null,
+      childSessionId: run.sessionId, source: route.source, category: route.category ?? null, scope: route.scope ?? null,
+      from: route.from, to, provider, tokens: run.tokens, usd, rates: usd === null ? null : rates,
+      priceCheckedAt: rates?.checkedAt ?? null, complete: run.complete };
+    // A transient price outage must not erase a completed, unchanged priced run.
+    if (usd === null && sameRun && previous.complete && Number.isFinite(previous.usd) &&
+        JSON.stringify(previous.tokens) === JSON.stringify(run.tokens)) continue;
+    if (JSON.stringify(ledger.events[route.id]) !== JSON.stringify(event)) { ledger.events[route.id] = event; changed = true; }
+  }
+  if (changed) saveLedger(ledger, dir);
+  return ledger;
+}
+
+/** Signed totals over priced runs; unpriced runs are counted, never summed as zero. */
+export function codexRoutingSavedTotals({ dir = userDataDir(), now = Date.now() } = {}) {
+  const events = Object.values(loadCodexLedger({ dir }).events);
+  const totals = { week: 0, month: 0, total: 0, runs: events.length, priced: 0 };
+  for (const e of events) {
+    if (!Number.isFinite(e.usd)) continue;
+    totals.priced++;
+    totals.total += e.usd;
+    if (now - e.ts < 7 * 86400000) totals.week += e.usd;
+    if (now - e.ts < 30 * 86400000) totals.month += e.usd;
+  }
+  return totals;
+}

package/src/codex-panel-launcher.js

@@ -0,0 +1,48 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { codexUserDir } from './agent.js';
+
+const quote = (value) => `'${String(value).replace(/'/g, `'"'"'`)}'`;
+
+export function panelLaunchCommand(root, { node = process.execPath, cli = fileURLToPath(new URL('../bin/cli.js', import.meta.url)), home = codexUserDir(), sessionId, sessionFile } = {}) {
+  return ['env', `CODEX_HOME=${home}`, node, cli, 'panel', '--agent', 'codex', '--project', resolve(root),
+    ...(sessionId ? ['--session', sessionId] : []), ...(sessionFile ? ['--session-file', sessionFile] : [])]
+    .map(quote).join(' ');
+}
+
+export function openCodexPanel(root, { platform = process.platform, exec = execFileSync, ...options } = {}) {
+  if (platform !== 'darwin') throw new Error('Automatic panel windows currently require macOS Terminal. Run sprag panel --agent codex in a separate terminal.');
+  const identity = [options.home || codexUserDir(), options.sessionId ? `session\0${options.sessionId}` : `project\0${resolve(root)}`].join('\0');
+  const title = `Sprag | Codex | ${createHash('sha256').update(identity).digest('hex').slice(0, 16)}`;
+  // Arguments travel through osascript argv, never through AppleScript source.
+  // Reuse only the same session (or an explicitly project-following window).
+  const script = `on run argv
+set panelTitle to item 1 of argv
+set panelCommand to item 2 of argv
+tell application "Terminal"
+repeat with w in windows
+repeat with t in tabs of w
+if custom title of t is panelTitle then
+set miniaturized of w to false
+set visible of w to true
+set selected tab of w to t
+set index of w to 1
+activate
+if busy of t then return "already-open"
+do script panelCommand in t
+return "restarted"
+end if
+end repeat
+end repeat
+set t to do script panelCommand
+set custom title of t to panelTitle
+activate
+return "opened"
+end tell
+end run`;
+  return exec('/usr/bin/osascript', ['-e', script, title, panelLaunchCommand(root, options)], {
+    encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}

package/src/codex-panel-runner.js

@@ -0,0 +1,74 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { panelLaunchCommand } from './codex-panel-launcher.js';
+import { createPanelBinding } from './codex-panel-session.js';
+
+const quote = (s) => `'${String(s).replace(/'/g, `'"'"'`)}'`;
+
+export function resizeInlinePanel(rows, { exec = execFileSync, env = process.env, state } = {}) {
+  if (env.SPRAG_CODEX_PANEL !== '1' || !env.TMUX_PANE || !env.TMUX) return;
+  try {
+    const info = exec('tmux', ['display-message', '-p', '-t', env.TMUX_PANE, '#{window_height} #{pane_height} #{window_width}'], { encoding: 'utf8', timeout: 1000 }).trim().split(/\s+/).map(Number);
+    const size = `${info[2]}x${info[0]}`;
+    // Keep the high-water mark until the terminal is resized. Timer labels and
+    // disappearing warnings must not repeatedly resize the prompt above us.
+    const contentRows = state && state.size === size ? Math.max(rows, state.rows) : rows;
+    const wanted = Math.max(1, Math.min(contentRows + 1, info[0] - 11));
+    if (state) { state.size = size; state.rows = contentRows; }
+    if (Number.isFinite(wanted) && wanted !== info[1]) exec('tmux', ['resize-pane', '-t', env.TMUX_PANE, '-y', String(wanted)], { stdio: 'ignore' });
+  } catch { /* A disappearing client must not stop the panel. */ }
+}
+
+export function createInlinePanelResizer(options = {}) {
+  const state = {};
+  return (rows) => resizeInlinePanel(rows, { ...options, state });
+}
+
+// A private server leaves the user's tmux configuration and sessions untouched.
+export function runCodexWithPanel(args, { root = process.cwd(), codex = 'codex', tmux = 'tmux',
+  exec = execFileSync, spawn = spawnSync, tty = !!process.stdin.isTTY && !!process.stdout.isTTY,
+  env = process.env, columns = process.stdout.columns || 100, rows = process.stdout.rows || 30,
+  keepNativeStatusline = false } = {}) {
+  if (!tty) throw new Error('Panel run requires an interactive terminal. Use codex directly for scripts.');
+  const options = args.slice(0, args.indexOf('--') < 0 ? args.length : args.indexOf('--'));
+  if (options.some((arg) => arg === '--remote' || arg.startsWith('--remote='))) {
+    throw new Error('Inline panels require a local Codex process. For remote Codex, run codex directly and use a separate panel with --session ID and local logs.');
+  }
+  try { exec(tmux, ['-V'], { stdio: 'pipe' }); }
+  catch { throw new Error('The inline Codex panel requires tmux. Install it with brew install tmux on macOS.'); }
+  const socket = `sprag-${randomUUID()}`;
+  const base = ['-L', socket, '-f', '/dev/null'];
+  const dir = mkdtempSync(join(tmpdir(), 'sprag-codex-'));
+  const status = join(dir, 'exit');
+  const sessionFile = join(dir, 'session.json');
+  const home = resolve(env.CODEX_HOME || join(env.HOME || homedir(), '.codex'));
+  const childEnv = { ...env, TMUX: '', SPRAG_CODEX_PANEL: '1', SPRAG_CODEX_PANEL_BINDING: sessionFile };
+  // Hide duplicate model/effort only in this layout. Later caller overrides win;
+  // putting the default before args also preserves subcommands and `--` prompts.
+  const launchArgs = [...(options.includes('--no-daemon') ? [] : ['--no-daemon']),
+    ...(keepNativeStatusline ? [] : ['-c', 'tui.status_line=[]']), ...args];
+  const call = (argv) => exec(tmux, [...base, ...argv], { env: childEnv, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  try {
+    createPanelBinding(sessionFile);
+    const tmuxCommand = [tmux, ...base].map(quote).join(' ');
+    const command = `${tmuxCommand} wait-for ready; ${[codex, ...launchArgs].map(quote).join(' ')}; result=$?; printf '%s' "$result" > ${quote(status)}; ${tmuxCommand} kill-session -t codex`;
+    const top = call(['new-session', '-d', '-P', '-F', '#{pane_id}', '-s', 'codex', '-c', process.cwd(),
+      '-x', String(columns), '-y', String(Math.max(16, rows)), command]).trim();
+    call(['set-option', '-t', 'codex', 'status', 'off']);
+    call(['set-option', '-t', 'codex', 'destroy-unattached', 'off']);
+    call(['split-window', '-d', '-v', '-l', '6', '-t', top,
+      `${panelLaunchCommand(resolve(root), { home, sessionFile })} --compact`]);
+    call(['select-pane', '-t', top]);
+    call(['wait-for', '-S', 'ready']);
+    const attached = spawn(tmux, [...base, 'attach-session', '-t', 'codex'], { env: childEnv, stdio: 'inherit' });
+    if (attached.error) throw attached.error;
+    try { return Number(readFileSync(status, 'utf8')); }
+    catch { return attached.status || 0; }
+  } finally {
+    try { call(['kill-server']); } catch { /* Already gone after normal exit. */ }
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/src/codex-panel-session.js

@@ -0,0 +1,35 @@
+import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+
+export function createPanelBinding(file) {
+  writeFileSync(file, JSON.stringify({ version: 1, sessionId: null, transcriptPath: null }), { mode: 0o600 });
+}
+
+export function readPanelBinding(file) {
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    if (data.version !== 1) return null;
+    if (typeof data.sessionId !== 'string' || !data.sessionId.trim()) return null;
+    return { sessionId: data.sessionId,
+      transcriptPath: typeof data.transcriptPath === 'string' && isAbsolute(data.transcriptPath) ? data.transcriptPath : null };
+  } catch { return null; }
+}
+
+// The inline runner uses --no-daemon so this path belongs to this Codex process,
+// not an environment inherited by a shared server from a different terminal.
+export function bindPanelSession(event, payload, { file = process.env.SPRAG_CODEX_PANEL_BINDING } = {}) {
+  if (!file || !['session-start', 'panel-start'].includes(event)) return false;
+  if (!['startup', 'resume', 'clear', 'compact'].includes(payload?.source)) return false;
+  if (typeof payload.session_id !== 'string' || !payload.session_id.trim()) return false;
+  try {
+    // Never recreate a binding after its launcher has exited and cleaned up.
+    const current = JSON.parse(readFileSync(file, 'utf8'));
+    if (current.version !== 1) return false;
+    if (payload.source === 'compact' && current.sessionId && current.sessionId !== payload.session_id) return false;
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ version: 1, sessionId: payload.session_id,
+      transcriptPath: typeof payload.transcript_path === 'string' && isAbsolute(payload.transcript_path) ? payload.transcript_path : null }), { mode: 0o600 });
+    renameSync(tmp, file);
+    return true;
+  } catch { return false; }
+}

package/src/codex-panel-setup.js

@@ -0,0 +1,98 @@
+/**
+ * Sets up the Codex companion panel to run inline, inside the same terminal,
+ * instead of opening a separate macOS Terminal window. Codex's native footer
+ * cannot run a command, so the panel is the closest thing Codex has to a
+ * statusline; showing it below the Codex pane in tmux (via a zsh `codex()`
+ * wrapper) means a user does not get a new window per session. Install falls
+ * back to the separate window when tmux cannot be set up, the login shell is
+ * not zsh, or the user already has their own `codex` alias/function.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { installPanelShell } from './codex-panel-shell.js';
+
+/** Whether a tmux binary answers `-V`. */
+export function tmuxAvailable({ exec = execFileSync } = {}) {
+  try { exec('tmux', ['-V'], { stdio: 'pipe' }); return true; }
+  catch { return false; }
+}
+
+export function ensureTmux({ platform = process.platform, env = process.env, exec = execFileSync, exists = existsSync } = {}) {
+  // Checked first, before probing anything, so tests and CI never spawn brew.
+  if (env.CTS_NO_TMUX === '1' || (env.CI && env.CI !== 'false')) return { status: 'skipped' };
+  if (tmuxAvailable({ exec })) return { status: 'present' };
+  if (platform !== 'darwin') {
+    return { status: 'unavailable', detail: 'install tmux with your package manager (e.g. sudo apt install tmux)' };
+  }
+  let brew;
+  try { exec('brew', ['--prefix'], { stdio: 'pipe' }); brew = 'brew'; }
+  catch {
+    for (const p of ['/opt/homebrew/bin/brew', '/usr/local/bin/brew']) {
+      if (exists(p)) { brew = p; break; }
+    }
+  }
+  if (!brew) {
+    return { status: 'unavailable', detail: 'Homebrew not found; install tmux from https://github.com/tmux/tmux/wiki/Installing or MacPorts (sudo port install tmux)' };
+  }
+  try {
+    // brew update alone can take minutes; postinstall cannot afford that here.
+    exec(brew, ['install', 'tmux'], { stdio: 'inherit', timeout: 600_000,
+      env: { ...env, HOMEBREW_NO_AUTO_UPDATE: '1', HOMEBREW_NO_INSTALL_CLEANUP: '1' } });
+  } catch (e) {
+    return { status: 'failed', via: 'brew', detail: String(e.message).split('\n')[0] };
+  }
+  // No npm-package fallback: no official npm tmux exists, and a third-party
+  // prebuilt binary would be an unaudited supply-chain risk.
+  const fallback = join(dirname(brew === 'brew' ? '/opt/homebrew/bin/brew' : brew), 'tmux');
+  if (tmuxAvailable({ exec }) || exists(fallback)) return { status: 'installed', via: 'brew' };
+  return { status: 'failed', via: 'brew', detail: 'tmux not on PATH after brew install' };
+}
+
+export function setupCodexPanel({ platform = process.platform, env = process.env, config = {}, noPanel = false,
+  exec, exists, installShell = installPanelShell, tmux = ensureTmux } = {}) {
+  if (noPanel) return { panelAuto: false, mode: 'off' };
+  // Panel auto and the zsh integration are macOS-only today.
+  if (platform !== 'darwin') return { panelAuto: false, mode: 'off' };
+  const windowAuto = config?.codex?.panelAuto !== false;
+  if (config?.codex?.panelShell === false) {
+    return { panelAuto: windowAuto, mode: windowAuto ? 'window' : 'off', reason: 'shell integration turned off' };
+  }
+  if (basename(env.SHELL || '') !== 'zsh') {
+    return { panelAuto: windowAuto, mode: windowAuto ? 'window' : 'off', reason: 'login shell is not zsh' };
+  }
+  const t = tmux({ platform, env, ...(exec && { exec }), ...(exists && { exists }) });
+  if (!['present', 'installed'].includes(t.status)) {
+    return { panelAuto: windowAuto, mode: windowAuto ? 'window' : 'off', reason: t.detail || t.status, tmux: t };
+  }
+  let shellFile;
+  try { shellFile = installShell(); }
+  catch (e) {
+    return { panelAuto: windowAuto, mode: windowAuto ? 'window' : 'off', reason: e.message, tmux: t };
+  }
+  // The inline panel replaces the separate window by default; an explicit
+  // `panel auto on` keeps both.
+  return { panelAuto: config?.codex?.panelAuto === true, mode: 'inline', tmux: t, shellFile };
+}
+
+/** Formats a `setupCodexPanel` result as lines a caller prefixes and prints. */
+export function describePanelSetup(result, lang = 'en') {
+  if (result.mode === 'off') return [];
+  if (result.mode === 'inline') {
+    const lines = [lang === 'ko'
+      ? `패널: tmux 인라인 (${result.shellFile}). 새 터미널에서 codex 를 실행하면 같은 창 아래쪽에 패널이 붙습니다.`
+      : `panel: inline tmux (${result.shellFile}). Open a new terminal and run codex; the panel attaches below it.`];
+    if (result.tmux?.status === 'installed') {
+      lines.push(lang === 'ko' ? 'tmux 를 Homebrew 로 설치했습니다.' : 'installed tmux with Homebrew.');
+    }
+    return lines;
+  }
+  const lines = [lang === 'ko'
+    ? `패널: 별도 Terminal 창${result.reason ? ` (${result.reason})` : ''}`
+    : `panel: separate Terminal window${result.reason ? ` (${result.reason})` : ''}`];
+  if (result.tmux?.detail && ['unavailable', 'failed'].includes(result.tmux.status)) {
+    lines.push(`tmux: ${result.tmux.detail}`);
+  }
+  return lines;
+}

package/src/codex-panel-shell.js

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const BEGIN = '# >>> sprag codex panel >>>';
+const END = '# <<< sprag codex panel <<<';
+
+export const PANEL_SHELL_BLOCK = `${BEGIN}
+function codex() {
+  local sprag_root="$PWD" sprag_open=1 sprag_next=0 sprag_arg
+  case "\${1-}" in
+    exec|e|review|login|logout|mcp|plugin|app-server|remote-control|completion|update|doctor|sandbox|debug|apply|queue|archive|delete|migrate-rollouts|unarchive|cloud|exec-server|features|help|agents|app) sprag_open=0 ;;
+  esac
+  for sprag_arg in "$@"; do
+    if (( sprag_next )); then
+      sprag_root="$sprag_arg"
+      sprag_next=0
+      continue
+    fi
+    case "$sprag_arg" in
+      -C|--cd) sprag_next=1 ;;
+      --cd=*) sprag_root="\${sprag_arg#--cd=}" ;;
+      --help|-h|--version|-V) sprag_open=0 ;;
+    esac
+  done
+  if [[ -t 0 && -t 1 && "\${SPRAG_CODEX_PANEL-}" != 1 ]] && (( sprag_open )); then
+    command sprag panel run --agent codex -- "$@"
+    return $?
+  fi
+  command codex "$@"
+}
+${END}
+`;
+
+export function installPanelShell({ file = join(process.env.ZDOTDIR || homedir(), '.zshrc'), remove = false } = {}) {
+  const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const start = text.indexOf(BEGIN);
+  const end = text.indexOf(END);
+  if ((start < 0) !== (end < 0) || (start >= 0 && end < start)) throw new Error('Malformed Sprag shell block; repair it before installation.');
+  if (start < 0 && !remove && /(?:function\s+codex\b|\bcodex\s*\(\)|\balias\s+codex=)/m.test(text)) {
+    throw new Error('An existing codex alias/function is present; keeping it unchanged.');
+  }
+  const next = start >= 0 ? text.slice(0, start) + (remove ? '' : PANEL_SHELL_BLOCK.trimEnd()) + text.slice(end + END.length)
+    : remove ? text : text + (text.endsWith('\n') || !text ? '' : '\n') + PANEL_SHELL_BLOCK;
+  if (next !== text) {
+    mkdirSync(dirname(file), { recursive: true });
+    if (text) writeFileSync(`${file}.bak-${Date.now()}`, text);
+    writeFileSync(file, next);
+  }
+  return file;
+}

package/src/codex-panel-state.js

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { userDataDir } from './paths.js';
+import { codexUserDir } from './agent.js';
+
+export function panelStatePath(root, kind, dir = userDataDir(), sessionId) {
+  const key = createHash('sha256').update(codexUserDir() + '\0' + resolve(root) + (sessionId ? `\0${sessionId}` : '')).digest('hex');
+  return join(dir, `codex-panel-${key}-${kind}.json`);
+}
+
+export function recordPanelState(root, kind, value, dir = userDataDir()) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    const file = panelStatePath(root, kind, dir);
+    const tmp = `${file}.${process.pid}.tmp`;
+    const text = JSON.stringify({ ...value, at: new Date().toISOString() });
+    writeFileSync(tmp, text);
+    renameSync(tmp, file);
+    if (value.sessionId) {
+      const sessionFile = panelStatePath(root, kind, dir, value.sessionId);
+      const sessionTmp = `${sessionFile}.${process.pid}.tmp`;
+      writeFileSync(sessionTmp, text);
+      renameSync(sessionTmp, sessionFile);
+    }
+  } catch { /* Diagnostics must not stop a session or panel. */ }
+}
+
+export function readPanelState(root, kind, dir = userDataDir(), sessionId) {
+  try { return JSON.parse(readFileSync(panelStatePath(root, kind, dir, sessionId), 'utf8')); }
+  catch { return null; }
+}
+
+export function panelHealth(root, { now = Date.now(), dir, sessionId } = {}) {
+  const hook = readPanelState(root, 'hook', dir, sessionId);
+  const frame = readPanelState(root, 'frame', dir, sessionId);
+  const age = frame ? now - Date.parse(frame.at) : Infinity;
+  const live = frame?.status === 'rendered' && age >= 0 && age < 15000;
+  return { hook, frame, live };
+}