sprag-cli 3.54.0 → 3.56.0

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.js

@@ -9,7 +9,7 @@ import { loadConfig, statuslineDefaults } from './config.js';
 import { glyphsFor } from './glyphs.js';
 import { gaugeBar, formatMoney } from './formatters/statusline.js';
 import { codexCacheTimer } from './codex-cache.js';
-import { readCodexCachePolicy, readCodexPrices } from './codex-cache-policy.js';
+import { readCodexCachePolicy, readCodexPrices, isDirectOpenAI } from './codex-cache-policy.js';
 import { codexIssues } from './codex-brief.js';
 import { labelForKey } from './window-labels.js';
 import { resolveLabelMode } from './statusline-mode.js';
@@ -28,20 +28,22 @@ export const CODEX_SEGMENT_ORDER = [
 
 // Only cache full-session parses. A moving time cutoff would make an unchanged
 // file's cached totals stale. The panel reports session totals, not window totals.
+// Matches the candidate TTL: older runs could not contribute a candidate anyway.
+const RATCHET_SIBLING_MS = 30 * 60000;
+
 export function createPanelReader({ root = process.cwd(), home, sessionId: pinnedId, sessionFile, days = 7, readBudget = () => null,
   readCachePolicy = (session) => readCodexCachePolicy(session, { home }), hasFlag = () => false } = {}) {
   if (pinnedId && sessionFile) throw new Error('Choose --session or --session-file, not both.');
   const cache = new Map();
   const ratchetCache = new Map();
-  const ratchetFor = (session) => {
+  const ratchetFor = (session, siblings = []) => {
     if (!session?.filePath) return [];
     try {
-      const s = statSync(session.filePath);
-      const key = `${s.mtimeMs}:${s.size}`;
+      const key = [session.filePath, ...siblings].map((file) => { const s = statSync(file); return `${file}:${s.mtimeMs}:${s.size}`; }).join('|');
       // Candidates expire by age, so a quiet file still needs a periodic re-read.
       const hit = ratchetCache.get(session.filePath);
       if (hit?.key === key && Date.now() - hit.at < 60000) return hit.value;
-      const value = codexRatchetCandidates(session.filePath);
+      const value = codexRatchetCandidates(session.filePath, { siblings });
       ratchetCache.clear();
       ratchetCache.set(session.filePath, { key, at: Date.now(), value });
       return value;
@@ -65,6 +67,8 @@ export function createPanelReader({ root = process.cwd(), home, sessionId: pinne
     let selected = null;
     let matches = 0;
     const seen = new Set();
+    // Recent rollouts of the same project, for repeats across `codex exec` runs.
+    const recent = [];
     for (const f of files.slice().reverse()) {
       let entry = cache.get(f.path);
       if (!entry || entry.mtime !== f.mtime || entry.size !== f.size) {
@@ -80,6 +84,7 @@ export function createPanelReader({ root = process.cwd(), home, sessionId: pinne
       if (seen.has(key)) continue;
       seen.add(key);
       matches++;
+      if (!sessionId && Date.now() - f.mtime < RATCHET_SIBLING_MS) recent.push(s.filePath);
       // Activity timestamps survive archive moves that update filesystem mtime.
       if (!selected || (s.lastActivity?.getTime() || 0) > (selected.lastActivity?.getTime() || 0)) selected = s;
     }
@@ -98,10 +103,10 @@ export function createPanelReader({ root = process.cwd(), home, sessionId: pinne
     let route = [];
     try { route = openCodexCandidates(readCodexRouteScan(), { root: project }); } catch { /* No scan yet. */ }
     let routingSaved = null;
-    try { routingSaved = { ...codexRoutingSavedTotals(), pricesAvailable: !!readCodexPrices({ provider: codexBudgetProvider(home ? { home } : {}), ...(home ? { home } : {}) }) }; }
+    try { routingSaved = { ...codexRoutingSavedTotals(), pricesAvailable: isDirectOpenAI(selected?.provider, home ? { home } : {}) || !!readCodexPrices({ provider: codexBudgetProvider(home ? { home } : {}), ...(home ? { home } : {}) }) }; }
     catch { /* Unreadable ledger reads as n/a. */ }
     return { session: selected, matches, root, sessionId, selection, bindingPending: !!sessionFile && !sessionId, days, harness, rules,
-      ratchet: ratchetFor(selected), route, routingSaved,
+      ratchet: ratchetFor(selected, recent.filter((file) => file !== selected?.filePath)), route, routingSaved,
       labelMode: resolveLabelMode({ cfg: statuslineDefaults(), hasFlag }).mode,
       color: statuslineDefaults().color,
       timer: !hasFlag('--no-timer') && (hasFlag('--timer') || statuslineDefaults().timer),

package/src/codex-parser.js

@@ -7,16 +7,45 @@ import { codexUserDir } from './agent.js';
 const count = (n) => Number.isSafeInteger(n) && n >= 0 ? n : 0;
 const emptyTotals = () => ({ input: 0, cacheRead: 0, cacheCreation: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0 });
 
+/**
+ * A child spawned with fork_turns "all" writes its own session_meta first,
+ * then a copy of the parent's session_meta and history, then its own work.
+ * The copy belongs to the parent: identity comes from the first session_meta,
+ * and the copied lines are skipped so the parent's request is not counted a
+ * second time. The copy ends at the child's own thread_settings_applied, or
+ * at the first line written after the batch copy, whichever comes first.
+ */
+export function forkedCopyFilter() {
+  let ownId = null, copyStamp = null;
+  return (e) => {
+    const p = e?.payload;
+    if (e?.type === 'session_meta') {
+      const id = p?.id || p?.session_id || null;
+      if (ownId === null) { ownId = id; return false; }
+      // A resumed rollout can repeat its own meta; only another thread's is a copy.
+      if (id && id !== ownId) { copyStamp = e.timestamp ?? null; return true; }
+      return true;
+    }
+    if (copyStamp === null) return false;
+    const own = e?.type === 'event_msg' && p?.type === 'thread_settings_applied' && p.thread_id === ownId;
+    if (own || e?.timestamp !== copyStamp) { copyStamp = null; return false; }
+    return true;
+  };
+}
+
 function updateSnapshot(session, e) {
   const p = e?.payload;
   if (!p || typeof p !== 'object') return;
   const activity = Date.parse(e.timestamp);
   if (Number.isFinite(activity)) session.lastActivity = new Date(activity);
   if (e.type === 'session_meta') {
+    // Callers drop forked copies, so a later meta can only be this thread's own repeat.
+    if (session.sessionId) return;
     session.sessionId = p.id || p.session_id || null;
     session.projectDir = typeof p.cwd === 'string' ? p.cwd : '';
     session.source = p.source ?? null;
     session.isSubagent = typeof p.source === 'object' && p.source !== null && 'subagent' in p.source;
+    session.forkedFrom = typeof p.forked_from_id === 'string' ? p.forked_from_id : null;
     session.branch = typeof p.git?.branch === 'string' ? p.git.branch : null;
     session.provider = typeof p.model_provider === 'string' ? p.model_provider : null;
   }
@@ -63,8 +92,12 @@ export function readCodexSnapshot(filePath, { tailBytes = 256 * 1024 } = {}) {
   const lines = readCodexTailLines(filePath, tailBytes);
   if (!lines) return null;
   const snapshot = {};
+  const copied = forkedCopyFilter();
   for (const line of lines) {
-    try { updateSnapshot(snapshot, JSON.parse(line)); } catch { /* Partial or malformed record. */ }
+    try {
+      const e = JSON.parse(line);
+      if (!copied(e)) updateSnapshot(snapshot, e);
+    } catch { /* Partial or malformed record. */ }
   }
   return snapshot;
 }
@@ -164,7 +197,8 @@ const emptyTurn = (turnId) => ({ turnId, startedAt: null, endedAt: null, aborted
  * structured event described, so a call is never counted twice.
  */
 export async function parseCodexTurns(filePath, { cutoffMs = -Infinity } = {}) {
-  const session = { filePath, sessionId: null, projectDir: '', isSubagent: false, parentThreadId: null, provider: null, turns: [] };
+  const session = { filePath, sessionId: null, projectDir: '', isSubagent: false, parentThreadId: null, forkedFrom: null, provider: null, turns: [] };
+  const copied = forkedCopyFilter();
   const turns = new Map();
   const turnOf = (id) => {
     if (!id) return null;
@@ -184,12 +218,14 @@ export async function parseCodexTurns(filePath, { cutoffMs = -Infinity } = {}) {
     let e;
     try { e = JSON.parse(line); } catch { continue; }
     const p = e?.payload;
-    if (!p || typeof p !== 'object') continue;
+    if (!p || typeof p !== 'object' || copied(e)) continue;
     if (e.type === 'session_meta') {
+      if (session.sessionId) continue;
       session.sessionId = p.id || p.session_id || null;
       session.projectDir = typeof p.cwd === 'string' ? p.cwd : '';
       session.isSubagent = typeof p.source === 'object' && p.source !== null && 'subagent' in p.source;
       session.parentThreadId = p.source?.subagent?.thread_spawn?.parent_thread_id || null;
+      session.forkedFrom = typeof p.forked_from_id === 'string' ? p.forked_from_id : null;
       session.provider = typeof p.model_provider === 'string' ? p.model_provider : null;
       continue;
     }
@@ -303,6 +339,7 @@ export async function parseCodexSessionFile(filePath, { cutoffMs = -Infinity } =
     lastContextTokens: null, rateLimits: null, lastActivity: null, effort: null,
     cacheActivity: null,
   };
+  const copied = forkedCopyFilter();
   let previous = null;
   const stream = createReadStream(filePath, { encoding: 'utf8' });
   const lines = createInterface({ input: stream, crlfDelay: Infinity });
@@ -310,7 +347,7 @@ export async function parseCodexSessionFile(filePath, { cutoffMs = -Infinity } =
     let e;
     try { e = JSON.parse(line); } catch { continue; }
     const p = e?.payload;
-    if (!p) continue;
+    if (!p || copied(e)) continue;
     updateSnapshot(session, e);
     if (e.type !== 'event_msg' || p.type !== 'token_count') continue;
     if (!p.info) continue;

package/src/codex-route-scan.js

@@ -8,7 +8,8 @@ import { discoverCodexSessionFiles, parseCodexTurns } from './codex-parser.js';
 import { categorize, isSkippable, tierOf, calibrateThresholds, MIN_RECURRENCE,
   RESCAN_MIN_INTERVAL_MS, RESCAN_BIG_DELTA_BYTES, RESCAN_MAX_AGE_MS } from './route-scan.js';
 import { codexPromptCategory, loadCodexModelRules } from './codex-delegation.js';
-import { codexRunCost, readCodexPrices } from './codex-cache-policy.js';
+import { codexRunCost, codexPriceBook, isDirectOpenAI, readCodexPrices } from './codex-cache-policy.js';
+import { OPENAI_PRICES_CHECKED_AT } from './openai-prices.js';
 import { refreshCodexLedger } from './codex-ledger.js';
 
 /*
@@ -81,11 +82,12 @@ export async function shouldRescanCodex(cache, { home, days = 14, now = Date.now
  * a rule target, so a gateway that also serves unrelated models (embeddings,
  * other vendors) never has one suggested blind.
  */
-function pickTarget(group, { prices, known }) {
-  const cost = (model) => prices?.provider === group.provider ? codexRunCost(group.tokens, prices.prices[model]) : null;
+function pickTarget(group, { prices, known, home }) {
+  const book = codexPriceBook(group.provider, prices, { home });
+  const cost = (model) => book ? codexRunCost(group.tokens, book.prices[model]) : null;
   const parent = cost(group.from);
   if (parent === null) return { suggestedModel: null, alternatives: [], estSavedUsd: null };
-  const cheaper = Object.keys(prices.prices).filter((m) => m !== group.from && prices.prices[m])
+  const cheaper = Object.keys(book.prices).filter((m) => m !== group.from && book.prices[m])
     .map((m) => ({ model: m, usd: cost(m) })).filter((x) => x.usd !== null && x.usd < parent)
     .sort((a, b) => a.usd - b.usd);
   const eligible = cheaper.filter((x) => known.has(`${group.provider}|${x.model}`));
@@ -151,7 +153,11 @@ export async function runCodexRouteScan({ days = 14, now = Date.now(), home, dir
     (!r.provider || r.provider === g.provider) &&
     (r.scope === 'global' || r.targetRoot === g.projectRoot));
   const known = new Set([...observed, ...rules.filter((r) => r.provider).map((r) => `${r.provider}|${r.model}`)]);
-  if (prices?.provider && cfg?.codex?.delegateTarget?.model) known.add(`${prices.provider}|${cfg.codex.delegateTarget.model}`);
+  const target = cfg?.codex?.delegateTarget?.model;
+  if (target) {
+    if (prices?.provider) known.add(`${prices.provider}|${target}`);
+    if (isDirectOpenAI('openai', { home })) known.add(`openai|${target}`);
+  }
   const prev = readCodexRouteScan({ dir });
   const resolved = new Set(prev?.resolved || []);
   const candidates = [...groups.values()]
@@ -160,9 +166,10 @@ export async function runCodexRouteScan({ days = 14, now = Date.now(), home, dir
     .slice(0, MAX_CANDIDATES)
     .map((g, i) => ({ id: i + 1, signature: g.signature, category: g.category, label: g.label, labelEn: g.labelEn,
       from: g.from, provider: g.provider, projectRoot: g.projectRoot, count: g.count, tiers: g.tiers, example: g.example.slice(0, 160),
-      lastSeen: g.lastSeen || null, suggestedScope: 'project', ...pickTarget(g, { prices, known }) }));
+      lastSeen: g.lastSeen || null, suggestedScope: 'project', ...pickTarget(g, { prices, known, home }) }));
+  const priceCheckedAt = prices?.checkedAt ?? ([...groups.values()].some((g) => isDirectOpenAI(g.provider, { home })) ? OPENAI_PRICES_CHECKED_AT : null);
   const data = { version: 1, scannedAt: new Date(now).toISOString(), days, dataBytes, totalEpisodes: episodes.length,
-    thresholds, observedModels: [...observed], priceCheckedAt: prices?.checkedAt ?? null, candidates, resolved: [...resolved] };
+    thresholds, observedModels: [...observed], priceCheckedAt, candidates, resolved: [...resolved] };
   writeCache(data, dir);
   if (refreshLedger) {
     try { await refreshCodexLedger({ dir, home, now, prices }); } catch { /* The ledger catches up on the next scan. */ }

package/src/codex-rule-health.js

@@ -0,0 +1,18 @@
+import { loadCodexLedger } from './codex-ledger.js';
+import { isFailedRun } from './route-scan.js';
+import { wilsonLowerBound, HEALTH_ERR_RATE, HEALTH_MIN_SAMPLE_DELEGATED } from './model-rules.js';
+
+/**
+ * Measured outcome of one Codex rule, judged as Claude's rule health judges
+ * its delegations: a run fails when interrupted or when its tool-error density
+ * crosses isFailedRun's line, and the rule goes to review only when the Wilson
+ * lower bound of the failure rate clears HEALTH_ERR_RATE over enough runs.
+ */
+export function codexRuleHealth(rule, { events = Object.values(loadCodexLedger().events) } = {}) {
+  const runs = events.filter((e) => e && e.category === rule.category && e.from === rule.from && e.to === rule.model &&
+    (!rule.provider || !e.provider || e.provider === rule.provider) && (e.complete || e.aborted));
+  const errs = runs.filter((e) => e.aborted || isFailedRun({ toolErrors: e.toolErrors, calls: e.calls })).length;
+  const saved = runs.filter((e) => Number.isFinite(e.usd)).reduce((sum, e) => sum + e.usd, 0);
+  const review = runs.length >= HEALTH_MIN_SAMPLE_DELEGATED && wilsonLowerBound(errs, runs.length) > HEALTH_ERR_RATE;
+  return { runs: runs.length, errs, rate: runs.length ? errs / runs.length : 0, saved, status: review ? 'review' : 'active' };
+}

package/src/commands/codex-delegate.js

@@ -2,7 +2,9 @@ import { loadConfig, saveConfig } from '../config.js';
 import { configureCodexHooks } from '../codex-installer.js';
 import { validateCodexTarget, loadCodexModelRules, addCodexModelRule, removeCodexModelRule } from '../codex-delegation.js';
 import { findCodexCandidate, resolveCodexCandidate } from '../codex-route-scan.js';
-import { codexRoutingSavedTotals } from '../codex-ledger.js';
+import { codexRoutingSavedTotals, loadCodexLedger } from '../codex-ledger.js';
+import { codexRuleHealth } from '../codex-rule-health.js';
+import { signedUsd } from '../money.js';
 import { codexProviderName } from '../agent.js';
 
 export function run({ args, getArg, hasFlag, root }) {
@@ -31,7 +33,14 @@ export function run({ args, getArg, hasFlag, root }) {
     else if (args[2]) throw new Error('Usage: delegate rules [add <category|R<N>> --from <model> --model <model> --global|--project | rm <N>]');
     const rules = loadCodexModelRules();
     if (!rules.length) console.log('No Codex model rules. Claude rules are not imported.');
-    rules.forEach((r, i) => console.log(`#${i + 1} ${r.category} | ${r.from} -> ${r.model} | ${r.scope}${r.targetRoot ? ` ${r.targetRoot}` : ''}`));
+    let events = [];
+    try { events = Object.values(loadCodexLedger().events); } catch { /* No ledger yet: rules list without outcomes. */ }
+    rules.forEach((r, i) => {
+      const h = codexRuleHealth(r, { events });
+      const outcome = h.runs ? ` | measured x${h.runs}, err ${Math.round(h.rate * 100)}%, saved ${signedUsd(h.saved, 4)}` : '';
+      const warn = h.status === 'review' ? ` | rule-health: ${h.errs}/${h.runs} runs failed, narrow the condition or remove (delegate rules rm ${i + 1} --agent codex)` : '';
+      console.log(`#${i + 1} ${r.category} | ${r.from} -> ${r.model} | ${r.scope}${r.targetRoot ? ` ${r.targetRoot}` : ''}${outcome}${warn}`);
+    });
     return;
   }
   if (!['on', 'off', 'status', 'model'].includes(sub)) throw new Error('Usage: delegate on|off|status|model <model>|rules --agent codex');
@@ -54,6 +63,6 @@ export function run({ args, getArg, hasFlag, root }) {
   console.log('Explicit spawn models and custom roles are preserved. Targets must be available from your Codex provider.');
   const saved = codexRoutingSavedTotals();
   console.log(saved.priced
-    ? `Routing saved: $${saved.total.toFixed(4)} over ${saved.priced} priced run(s). Details: sprag route-scan savings --agent codex`
+    ? `Routing saved: ${saved.total < 0 ? '-' : ''}$${Math.abs(saved.total).toFixed(4)} over ${saved.priced} priced run(s). Details: sprag route-scan savings --agent codex`
     : `Routing saved: n/a (${saved.runs ? `${saved.runs} attributed run(s), none priced` : 'no attributed runs yet'}). Review/trust the Sprag hooks in Codex /hooks.`);
 }

package/src/commands/codex.js

@@ -4,6 +4,8 @@ import { initCodexHarness, uninitCodexHarness, codexHarnessStatus } from '../cod
 import { findProjectRoot, harnessPromote, harnessListRules, harnessRmRule, harnessPrune } from '../harness.js';
 import { loadConfig, saveConfig } from '../config.js';
 import { resolve } from 'node:path';
+import { debug } from '../debug.js';
+import { signedUsd } from '../money.js';
 
 const HELP = `Sprag / Codex
 
@@ -19,7 +21,7 @@ Usage: sprag <command> --agent codex [options]
   doctor [--format json]         Config, hooks, harness, logs, and capabilities
   capabilities [--format json]   Support matrix, including native/unsupported areas
   brief [on|off|status]          Current warnings or prompt-briefing preference
-  last / history                Codex warning history; --days, --session, --project
+  last / history                Context/rate-limit warnings and handoffs; --days, --session, --project
   handoff [--cwd path]           Write Git state and Codex usage to HANDOFF-*.md
   delegate on|off|status         Native model routing and SubagentStart guidance
   delegate model <model>         Default target for spawns without an explicit model
@@ -155,7 +157,7 @@ export async function run({ args, version }) {
       const money = (usd) => Number.isFinite(usd) ? `${usd < 0 ? '-' : ''}$${Math.abs(usd).toFixed(4)}` : 'n/a (unpriced)';
       console.log(`Codex routing saved: ${totals.priced ? `${money(totals.week)} (7d) / ${money(totals.total)} total` : 'n/a'} | ${totals.runs} attributed run(s), ${totals.runs - totals.priced} unpriced`);
       for (const e of events.slice(0, 20)) {
-        console.log(`${new Date(e.ts).toISOString().slice(0, 16)} ${e.source}${e.category ? `/${e.category}` : ''} ${e.from} -> ${e.to} ${money(e.usd)}${e.complete ? '' : ' (incomplete)'}`);
+        console.log(`${new Date(e.ts).toISOString().slice(0, 16)} ${e.source}${e.category ? `/${e.category}` : ''} ${e.from} -> ${e.to} ${money(e.usd)}${e.aborted ? ' (interrupted: whole cost counted as a loss)' : e.complete ? '' : ' (incomplete)'}`);
       }
       console.log('Counterfactual: the child run\'s own tokens priced at the parent model. Only Sprag-routed spawns with a recorded route id count.');
       return;
@@ -172,7 +174,7 @@ export async function run({ args, version }) {
     if (hasFlag('--refresh') || !cache) {
       // Prices live in the gateway snapshot; refresh it when stale so candidates can name a target.
       const { readCodexPrices, refreshCodexPrices } = await import('../codex-cache-policy.js');
-      if (!readCodexPrices()) { try { await refreshCodexPrices(); } catch { /* Candidates still list; targets need --model. */ } }
+      if (!readCodexPrices()) { try { await refreshCodexPrices(); } catch (e) { debug('codex:prices', e); } }
       cache = await rs.runCodexRouteScan({ days });
     }
     if (hasFlag('--quiet')) return;
@@ -181,7 +183,7 @@ export async function run({ args, version }) {
     console.log(`Codex route-scan: ${cache.totalEpisodes} turns in ${cache.days} days, scanned ${cache.scannedAt}${cache.priceCheckedAt ? '' : ' | prices unavailable'}`);
     if (!open.length) console.log('No recurring delegable pattern. Needs 3+ similar simple turns per project and parent model.');
     for (const c of open) {
-      const target = c.suggestedModel ? `-> ${c.suggestedModel}${Number.isFinite(c.estSavedUsd) ? ` (~$${c.estSavedUsd.toFixed(4)} over ${c.count} turns)` : ''}`
+      const target = c.suggestedModel ? `-> ${c.suggestedModel}${Number.isFinite(c.estSavedUsd) ? ` (~${signedUsd(c.estSavedUsd, 4)} over ${c.count} turns)` : ''}`
         : `-> choose --model${c.alternatives.length ? ` (priced cheaper: ${c.alternatives.join(', ')})` : ''}`;
       console.log(`R${c.id} ${c.category} x${c.count} [T2 ${c.tiers.T2} / T1 ${c.tiers.T1}] ${c.provider || 'unknown provider'} / ${c.from} ${target}`);
       console.log(`   ${c.projectRoot}`);
@@ -225,7 +227,7 @@ export async function run({ args, version }) {
       sessionId: getArg('--session'), project: getArg('--project') || getArg('-p') });
     if (cmd === 'last') events = events.slice(-1);
     if (format === 'json') { console.log(JSON.stringify({ agent: 'codex', events }, null, 2)); return; }
-    if (!events.length) console.log('No Codex warning history in this window. Records are written by the trusted prompt hook.');
+    if (!events.length) console.log('No Codex warning history in this window. The trusted prompt hook records context and rate-limit warnings; handoffs are recorded when written.');
     else if (hasFlag('--list')) console.log([...new Set(events.map((event) => event.at.slice(0, 10)))].reverse().join('\n'));
     else for (const event of events) {
       console.log(terminalText(`${event.at} [${event.sessionId}] ${event.message}`));
@@ -239,6 +241,11 @@ export async function run({ args, version }) {
     const cwd = getArg('--cwd') || process.cwd();
     const data = await createPanelReader({ root: findProjectRoot(resolve(cwd), { agent: 'codex' }), sessionId: getArg('--session'), days: numArg('--days', { dflt: 7, min: 0 }) })();
     const result = writeHandoff({ cwd, agent: 'codex', session: data.session });
+    try {
+      const { recordCodexHistoryEvent } = await import('../codex-brief.js');
+      recordCodexHistoryEvent({ sessionId: data.session?.sessionId, project: cwd, key: 'handoff',
+        message: `Handoff written: ${result.path}` });
+    } catch (e) { debug('codex:handoff-record', e); }
     console.log(`Handoff written: ${result.path}`);
     console.log('Fill in the remaining-work sections, then ask the next Codex session to read this file.');
     return;
@@ -272,6 +279,11 @@ export async function run({ args, version }) {
       if (!['install', 'remove'].includes(args[2])) throw new Error('Usage: sprag panel shell install|remove --agent codex');
       const { installPanelShell } = await import('../codex-panel-shell.js');
       const file = installPanelShell({ remove: args[2] === 'remove' });
+      // install adds the integration by default, so a removal must be
+      // remembered or the next upgrade puts it back.
+      const cfg = loadConfig();
+      cfg.codex = { ...cfg.codex, panelShell: args[2] === 'install' };
+      saveConfig(cfg);
       console.log(`Shell integration ${args[2]}: ${file}. Open a new terminal to apply it.`);
       return;
     }
@@ -319,7 +331,7 @@ export async function run({ args, version }) {
     })() : { read: createCodexBudgetReader() };
     if (hasFlag('--once')) {
       const provider = codexBudgetProvider();
-      if (provider) { try { readBudget.set(await fetchCodexBudget(provider)); } catch { /* No verified budget. */ } }
+      if (provider) { try { readBudget.set(await fetchCodexBudget(provider)); } catch (e) { debug('codex:budget', e); } }
     }
     const { createInlinePanelResizer } = await import('../codex-panel-runner.js');
     const rawInterval = getArg('--interval');
@@ -335,7 +347,7 @@ export async function run({ args, version }) {
         readCachePolicy: hasFlag('--once') ? async (session) => {
           const { readCodexCachePolicy } = await import('../codex-cache-policy.js');
           try { return readCodexCachePolicy(session) || await refreshCodexCachePolicy(session); }
-          catch { return null; }
+          catch (e) { debug('codex:cache-policy', e); return null; }
         } : createCodexCachePolicyReader(), hasFlag }),
       interval: interval * 1000, once: hasFlag('--once'),
       color: !hasFlag('--no-color') && !process.env.NO_COLOR && !!process.stdout.isTTY, version, compact: hasFlag('--compact'),
@@ -372,22 +384,30 @@ export async function run({ args, version }) {
       }
       const out = await codexHookOutput(getArg('--event'), payload);
       if (out) console.log(JSON.stringify(out));
-    } catch { /* Hook failures must not break the agent loop. */ }
+    } catch (e) { debug('codex:hook', e); /* Hook failures must not break the agent loop. */ }
     return;
   }
   if (cmd === 'install') {
     const cfg = loadConfig();
-    const panelAuto = process.platform === 'darwin' && !hasFlag('--no-panel') && cfg?.codex?.panelAuto !== false;
+    const { setupCodexPanel, describePanelSetup } = await import('../codex-panel-setup.js');
+    const panel = setupCodexPanel({ config: cfg || {}, noPanel: hasFlag('--no-panel') });
+    const panelAuto = panel.panelAuto;
     const hook = configureCodexHooks({ panelAuto });
     console.log(`Codex hooks: ${hook.file} (${hook.action})`);
+    for (const line of describePanelSetup(panel)) console.log(`Codex ${line}`);
     if (process.env.CTS_NO_HARNESS !== '1') {
       const h = initCodexHarness({ root, scope: 'global' });
       console.log(`Codex harness: ${h.file}`);
     }
+    try {
+      const { preparePresetRatchet } = await import('../preset-ratchet.js');
+      const p = preparePresetRatchet({ agent: 'codex' });
+      console.log(`Codex preset rules: ${p.file} (${p.rules} registered${p.moved ? `, ${p.moved} moved from ratchet.md` : ''})`);
+    } catch (e) { debug('codex:preset', e); /* Presets are optional; `seed` still registers them. */ }
     console.log('Open /hooks in Codex and review/trust the Sprag hooks before they can run.');
     console.log(`Panel auto-start: ${panelAuto ? 'registered with the other hooks' : 'off'}. Hook registration is complete; runtime activation is not verified.`);
     console.log('After approval, start or resume Codex and run: sprag panel doctor --agent codex');
-    if (panelAuto) console.log('Some Codex versions defer SessionStart until the first prompt. For immediate opening on typing codex: sprag panel shell install --agent codex (optional zsh integration).');
+    if (panel.mode === 'window') console.log('Some Codex versions defer SessionStart until the first prompt. For immediate opening on typing codex: sprag panel shell install --agent codex (optional zsh integration).');
     console.log('Existing config.toml, Claude Code settings, and ratchet rules are preserved.');
     console.log('Korean guidance is opt-in: sprag korean on --agent codex');
     return;
@@ -444,6 +464,15 @@ export async function run({ args, version }) {
       const r = harnessListRules(opts);
       console.log(`Codex ratchet [${scope}]: ${r.path}`);
       for (const rule of r.rules) console.log(`#${rule.index} ${rule.text}`);
+      if (scope === 'global') {
+        const { acceptedGlobalPresets, presetRatchetPath } = await import('../preset-ratchet.js');
+        const presets = acceptedGlobalPresets({ agent: 'codex' });
+        if (presets.length) {
+          console.log(`Codex preset rules [global]: ${presetRatchetPath({ agent: 'codex' })}`);
+          for (const p of presets) console.log(`${p.id} ${p.text}`);
+          console.log('Remove a preset with: sprag seed skip <id> --agent codex');
+        }
+      }
     } else if (sub === 'rm') {
       const raw = args[2];
       // Locate the index even when scope flags precede it.
@@ -486,7 +515,8 @@ export async function run({ args, version }) {
     console.log(`Cache: ${doc2md.cacheDir()}`);
     try {
       for (const hook of codexHookStatus().filter((h) => ['PreToolUse', 'UserPromptSubmit'].includes(h.event))) console.log(`${hook.event}: ${hook.registered ? 'registered' : 'missing/outdated'}`);
-    } catch {
+    } catch (e) {
+      debug('codex:hook-status', e);
       console.log('Hooks: cannot read Codex hooks.json; file left unchanged. Run sprag doctor --agent codex for diagnostics.');
     }
     console.log('Prompt conversion, supported reads, and document/cache write guards require trusted hooks. Review in Codex /hooks.');

package/src/commands/harness.js

@@ -337,7 +337,7 @@ export async function run({ args, hasFlag }) {
       // rules, and a project ratchet inherits global anyway). Strictly opt-in:
       // install/init never auto-injects rules.
       const scope = parseHarnessScope(args.slice(2), 'global');
-      const r = harnessPull({ scope });
+      const r = await harnessPull({ scope });
       console.log(`Curated preset rules → ${r.path} [${r.scope}]`);
       if (r.added.length) {
         console.log(`✅ ${r.added.length}/${r.presets} rule(s) registered:`);
@@ -366,7 +366,18 @@ export async function run({ args, hasFlag }) {
         console.log('');
       };
       if (wantProject) print('project');
-      if (wantGlobal) print('global');
+      if (wantGlobal) {
+        print('global');
+        // Presets live in their own tool-owned file and are removed by id,
+        // so they are listed apart from the numbered rules `rm <N>` acts on.
+        const { acceptedGlobalPresets, presetRatchetPath } = await import('../preset-ratchet.js');
+        const presets = acceptedGlobalPresets();
+        if (presets.length) {
+          console.log(`📦 Preset rules [global] — ${presetRatchetPath()}\n`);
+          for (const p of presets) console.log(`  ${p.id}  ${p.text}`);
+          console.log('\nRemove a preset with: sprag seed skip <id>\n');
+        }
+      }
       console.log('Remove with: sprag harness rm [--global|--project] <N>');
       console.log('Archive in bulk:  sprag harness prune [--global] [--tag <t>] [--older-than <months>] [--dry-run]');
       return;