claude-token-saver 3.44.0 → 3.55.0

package/src/codex-hooks.js

@@ -0,0 +1,138 @@
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig, userLanguage } from './config.js';
+import { koreanStyleInjection, koreanStyleEnabled } from './korean-style.js';
+import { cohesionInjection } from './cohesion.js';
+import { codexHarnessPaths } from './codex-harness.js';
+import { findProjectRoot } from './harness.js';
+import { runCodexBrief } from './codex-brief.js';
+import { codexDocumentTool, codexDocumentNote, convertCodexDocument } from './codex-doc2md.js';
+import { codexDelegationTool, codexRouteHint } from './codex-delegation.js';
+import { seedOfferBlock } from './seed-rules.js';
+import { readCodexRouteScan, openCodexCandidates, shouldRescanCodex } from './codex-route-scan.js';
+
+const require = createRequire(import.meta.url);
+const lint = require('./korean-lint.cjs');
+const doc2md = require('./doc2md.cjs');
+
+function context(event, text) {
+  return text ? { hookSpecificOutput: { hookEventName: event, additionalContext: text } } : null;
+}
+
+/**
+ * Project route candidates from the last scan. Never scans inline: session
+ * start must stay fast, so a stale scan is refreshed in a detached process
+ * and its results show up next session.
+ */
+async function routeNotice(root, { spawnRescan = defaultRescan } = {}) {
+  const cache = readCodexRouteScan();
+  if (await shouldRescanCodex(cache)) spawnRescan();
+  const open = openCodexCandidates(cache, { root });
+  if (!open.length) return null;
+  return [`[Sprag route-scan] ${open.length} recurring delegable pattern(s) in this project. Mention them once; do not register without the user's scope decision.`,
+    ...open.slice(0, 3).map((c) => `  R${c.id} ${c.category} x${c.count}: ${c.from} -> ${c.suggestedModel || '(choose a model)'}`),
+    '  Review: sprag route-scan --agent codex | approve: sprag delegate rules add R<N> --global|--project --agent codex'].join('\n');
+}
+
+function defaultRescan() {
+  if (process.env.CTS_NO_ROUTE_SCAN === '1') return;
+  spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet', '--agent', 'codex'],
+    { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+}
+
+export function lintCodexTool(payload, { scope = 'all' } = {}) {
+  if (!payload || typeof payload !== 'object') return null;
+  const input = payload.tool_input;
+  const command = typeof input === 'string' ? input : input?.command ?? input?.cmd ?? input?.content ?? input?.patch;
+  const tool = payload.tool_name?.replace(/^(?:functions|tools)\./, '');
+  let paths = [];
+  if (['Bash', 'exec_command', 'shell_command', 'shell'].includes(tool)) paths = lint.writtenPathsOfBash(command);
+  else if (['apply_patch', 'Edit', 'Write'].includes(tool) && typeof command === 'string' && command.startsWith('*** Begin Patch')) {
+    // Patch headers are the path-bearing records of Codex's patch grammar.
+    // Check the final file, including move destinations, not diff markers.
+    paths = [...command.matchAll(/^\*\*\* (?:Add File|Update File|Move to): (.+)\r?$/gm)].map((m) => m[1].trimEnd());
+  } else return lint.lintToolUse(payload, { scope });
+  const messages = [];
+  for (const path of new Set(paths)) {
+    const file = resolve(payload.cwd || process.cwd(), typeof input?.workdir === 'string' ? input.workdir : '.', path);
+    if (!lint.isLintTarget(file, scope)) continue;
+    try {
+      const s = statSync(file);
+      if (!s.isFile() || s.size > 512 * 1024) continue;
+      let text = readFileSync(file, 'utf8');
+      if (lint.isHtmlFile(file)) text = lint.stripHtml(text);
+      const findings = lint.lintKoreanText(text, { code: !lint.isProseFile(file) });
+      if (findings.length) messages.push(lint.formatFindings(file, findings));
+    } catch { /* Deleted, moved, or unreadable files need no feedback. */ }
+  }
+  return messages.length ? messages.join('\n\n') : null;
+}
+
+export async function codexHookOutput(event, payload, { cfg = loadConfig() } = {}) {
+  if (!payload || typeof payload !== 'object') return null;
+  if (event === 'session-start' || event === 'subagent-start') {
+    if (event === 'subagent-start' && cfg?.codex?.delegate !== true) return null;
+    const root = findProjectRoot(payload.cwd || process.cwd(), { agent: 'codex' });
+    const parts = [];
+    // Keep the preset file current with this version's wording before it is read.
+    if (event === 'session-start') {
+      try { (await import('./preset-ratchet.js')).preparePresetRatchet({ agent: 'codex' }); } catch { /* Presets are optional. */ }
+    }
+    const { presetRatchetPath } = await import('./preset-ratchet.js');
+    for (const [scope, ratchet] of [['global', codexHarnessPaths(root, 'global').ratchet],
+      ['preset', presetRatchetPath({ agent: 'codex' })], ['project', codexHarnessPaths(root, 'project').ratchet]]) {
+      try {
+        if (statSync(ratchet).size > 32 * 1024) {
+          parts.push(`Read the ${scope} Sprag ratchet rules at ${JSON.stringify(ratchet)} before working; they exceed the automatic injection limit.`);
+        } else {
+          const text = readFileSync(ratchet, 'utf8').trim();
+          // An empty preset file is only its header; injecting it would spend
+          // tokens every session on no rules.
+          if (text && (scope !== 'preset' || /^- /m.test(text))) parts.push(`[Sprag Codex ratchet: ${scope}]\n${text}`);
+        }
+      } catch { /* No rules registered in this scope. */ }
+    }
+    parts.push(koreanStyleInjection({ cfg }), await cohesionInjection({ cfg }));
+    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) parts.push(codexDocumentNote());
+    if (event === 'session-start' && payload.source !== 'compact') {
+      try { parts.push(seedOfferBlock({ root, agent: 'codex' })); } catch { /* Offers are optional. */ }
+      try { parts.push(await routeNotice(root)); } catch { /* A missing scan only delays candidates. */ }
+    }
+    if (event === 'subagent-start') parts.push(
+      '[Sprag Codex delegation]\nStay within the assigned task and any caller-provided budget. Return findings with file references and actual verification results; state unfinished work. Use only available Codex tools and configured roles. Do not infer a model tier or invent a tool-call budget.');
+    return context(event === 'subagent-start' ? 'SubagentStart' : 'SessionStart', parts.filter(Boolean).join('\n\n'));
+  }
+  if (event === 'prompt') {
+    const parts = [];
+    if (cfg?.codex?.delegate === true) {
+      try { parts.push(codexRouteHint(payload, { root: findProjectRoot(payload.cwd || process.cwd(), { agent: 'codex' }) })); }
+      catch { /* Invalid routing state must not suppress briefing or conversion. */ }
+    }
+    if (cfg?.codex?.brief !== false) {
+      try { parts.push(runCodexBrief({ sessionId: payload.session_id, transcriptPath: payload.transcript_path, cwd: payload.cwd })); }
+      catch { /* Local telemetry must not prevent document conversion. */ }
+    }
+    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) {
+      parts.push(doc2md.contextForPrompt(payload, { lang: userLanguage(), agent: 'codex', convert: convertCodexDocument }));
+    }
+    return context('UserPromptSubmit', parts.filter(Boolean).join('\n\n'));
+  }
+  if (event === 'pre-tool') {
+    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) {
+      const result = codexDocumentTool(payload);
+      if (result) return result;
+    }
+    return codexDelegationTool(payload, { cfg, root: findProjectRoot(payload.cwd || process.cwd(), { agent: 'codex' }) });
+  }
+  if (event === 'post-tool') {
+    if (!koreanStyleEnabled(cfg) || cfg?.koreanStyle?.lint === 'off') return null;
+    const result = lintCodexTool(payload, { scope: cfg?.koreanStyle?.lintScope === 'prose' ? 'prose' : 'all' });
+    const text = typeof result === 'string' ? result : result ? lint.formatFindings(result.filePath, result.findings) : null;
+    if (!text) return null;
+    if (cfg?.koreanStyle?.lint === 'warn') return context('PostToolUse', text);
+    return { decision: 'block', reason: text };
+  }
+  throw new Error(`Unknown Codex hook event: ${event}`);
+}

package/src/codex-installer.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { codexUserDir } from './agent.js';
+
+export const CODEX_HANDLERS = {
+  SessionStart: { matcher: 'startup|resume|clear|compact', command: 'sprag codex-hook --agent codex --event session-start', timeout: 15 },
+  UserPromptSubmit: { command: 'sprag codex-hook --agent codex --event prompt', timeout: 600 },
+  PreToolUse: { matcher: '^(Bash|Read|read_file|Edit|Write|Agent|spawn_agent|mcp__filesystem__read_(?:text_)?file|(?:functions\\.|tools\\.)?(?:exec_command|shell_command|shell|apply_patch|spawn_agent))$', command: 'sprag codex-hook --agent codex --event pre-tool', timeout: 600 },
+  PostToolUse: { matcher: '^(Bash|apply_patch|Edit|Write|(?:functions\\.|tools\\.)?(?:exec_command|shell_command|shell|apply_patch))$', command: 'sprag codex-hook --agent codex --event post-tool', timeout: 15 },
+  SubagentStart: { command: 'sprag codex-hook --agent codex --event subagent-start', timeout: 15 },
+};
+const ownCommands = new Set(Object.values(CODEX_HANDLERS).map((h) => h.command));
+const PANEL_COMMAND = 'sprag codex-hook --agent codex --event panel-start';
+ownCommands.add(PANEL_COMMAND);
+
+export function codexPanelAutoEnabled() {
+  const data = readHooks(join(codexUserDir(), 'hooks.json'));
+  return (data.hooks?.SessionStart || []).some((g) => g.hooks.some((h) => h?.command === PANEL_COMMAND));
+}
+
+export function readCodexHooks(file = join(codexUserDir(), 'hooks.json')) {
+  if (!existsSync(file)) return {};
+  const data = JSON.parse(readFileSync(file, 'utf8'));
+  if (!data || typeof data !== 'object' || Array.isArray(data) ||
+      (data.hooks !== undefined && (!data.hooks || typeof data.hooks !== 'object' || Array.isArray(data.hooks)))) {
+    throw new Error(`Invalid Codex hooks configuration: ${file}`);
+  }
+  for (const groups of Object.values(data.hooks || {})) {
+    if (!Array.isArray(groups) || groups.some((g) => !g || !Array.isArray(g.hooks))) {
+      throw new Error(`Invalid Codex hook groups: ${file}`);
+    }
+  }
+  return data;
+}
+
+const readHooks = readCodexHooks;
+
+export function codexHookStatus() {
+  const data = readCodexHooks();
+  return Object.entries(CODEX_HANDLERS).map(([event, expected]) => {
+    const groups = data.hooks?.[event] || [];
+    // Async hooks cannot enforce write guards or lint feedback. Conversion hooks
+    // also need time for interpreter probes and multiple bounded conversions.
+    const registered = groups.some((group) => group.matcher === expected.matcher && group.hooks.some((hook) =>
+      hook?.type === 'command' && hook.command === expected.command && hook.enabled !== false && hook.async !== true &&
+      Number.isFinite(hook.timeout ?? 600) && (hook.timeout ?? 600) >= expected.timeout));
+    return { event, registered };
+  });
+}
+
+export function configureCodexHooks({ remove = false, panelAuto } = {}) {
+  const file = join(codexUserDir(), 'hooks.json');
+  const data = readHooks(file);
+  const before = JSON.stringify(data);
+  const auto = panelAuto ?? (data.hooks?.SessionStart || []).some((g) => g.hooks.some((h) => h?.command === PANEL_COMMAND));
+  data.hooks ||= {};
+  for (const [event, groups] of Object.entries(data.hooks)) {
+    data.hooks[event] = groups.map((g) => ({ ...g, hooks: g.hooks.filter((h) => !ownCommands.has(h?.command)) }))
+      .filter((g) => g.hooks.length);
+    if (!data.hooks[event].length) delete data.hooks[event];
+  }
+  if (!remove) {
+    for (const [event, { matcher, command, timeout }] of Object.entries(CODEX_HANDLERS)) {
+      const group = { hooks: [{ type: 'command', command, timeout }] };
+      if (matcher) group.matcher = matcher;
+      (data.hooks[event] ||= []).push(group);
+    }
+    if (auto) data.hooks.SessionStart.push({ matcher: 'startup|resume', hooks: [{ type: 'command', command: PANEL_COMMAND, timeout: 10 }] });
+  }
+  if (remove && !Object.keys(data.hooks).length) delete data.hooks;
+  if (JSON.stringify(data) !== before) {
+    mkdirSync(dirname(file), { recursive: true });
+    if (existsSync(file)) writeFileSync(`${file}.bak-${Date.now()}`, readFileSync(file));
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+    renameSync(tmp, file);
+  }
+  return { file, action: remove ? 'removed' : 'configured' };
+}

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;
+}