claude-token-saver 3.44.0 → 3.55.0

package/src/codex-cache.js

@@ -0,0 +1,46 @@
+// Minimum retention windows, not exact expiration timestamps. Gateway aliases
+// require a resolved deployment before applying a provider's documented policy.
+// https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime
+export function codexCachePolicy(model) {
+  return /^gpt-(?:5\.6(?:-(?:sol|terra|luna))?|6-(?:astra|sol|luna))(?:-\d{4}-\d{2}-\d{2})?$/i.test(model || '') ? 1800 : null;
+}
+
+export function parseCodexCacheTtl(value) {
+  if (value === 'auto' || value === 'off') return value;
+  const match = /^(\d+)(m|h)$/.exec(value || '');
+  const seconds = match ? Number(match[1]) * (match[2] === 'h' ? 3600 : 60) : NaN;
+  if (!Number.isSafeInteger(seconds) || seconds < 60 || seconds > 86400) {
+    throw new Error('Cache TTL expects auto, off, or 1m through 24h (for example 30m). This changes the display estimate, not provider retention.');
+  }
+  return seconds;
+}
+
+export function codexCacheTimer(session, { now = Date.now(), ttl = 'auto', policy } = {}) {
+  if (ttl === 'off') return null;
+  const activity = session?.cacheActivity;
+  const at = activity?.at ? new Date(activity.at).getTime() : NaN;
+  const sameModel = activity?.model === session?.model;
+  if (!Number.isFinite(at) || at > now || !sameModel || activity?.provider !== session?.provider) {
+    return { text: 'Cache timer n/a', tone: 90, source: 'unavailable' };
+  }
+  const elapsed = Math.floor((now - at) / 1000);
+  const configured = Number.isSafeInteger(ttl) && ttl >= 60 && ttl <= 86400;
+  const resolved = policy && policy.requestedModel === session.model && policy.provider === session.provider &&
+    ['OpenAI', 'Bedrock'].includes(policy.backend) && policy.seconds === codexCachePolicy(policy.model) &&
+    Number.isFinite(policy.checkedAt) && now >= policy.checkedAt && now - policy.checkedAt < 300000;
+  const direct = policy === undefined && session.provider === 'openai' && codexCachePolicy(session.model);
+  const seconds = configured ? ttl : resolved ? policy.seconds : direct;
+  if (!seconds) return { text: `Cache age ${clock(elapsed)} / TTL unknown`, tone: 90, source: 'age', elapsed };
+  const remaining = Math.max(0, seconds - elapsed);
+  const source = configured ? 'configured estimate' : `${resolved ? policy.backend : 'OpenAI'} 30m`;
+  const text = remaining > 0 ? `Cache ${clock(remaining)} (${source})` : `Cache window elapsed (${source}; expiry unknown)`;
+  return { text, tone: remaining <= 0 ? 90 : remaining <= 60 ? 31 : remaining <= 300 ? 33 : 32,
+    source: configured ? 'configured' : 'provider-policy', seconds, elapsed, remaining };
+}
+
+function clock(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = seconds % 60;
+  return h ? `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}` : `${m}:${String(s).padStart(2, '0')}`;
+}

package/src/codex-delegation.js

@@ -0,0 +1,154 @@
+import { readFileSync, readdirSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parse } from 'smol-toml';
+import { userDataDir } from './paths.js';
+import { codexUserDir, codexProviderName } from './agent.js';
+import { categorize, ESCALATE_RE, EDIT_RE } from './route-scan.js';
+import { looksPasted } from './route-inject.js';
+import { newRouteId, recordCodexDelegation } from './codex-ledger.js';
+
+export const CODEX_ROUTE_CATEGORIES = ['paste', 'translate', 'explore', 'read', 'check', 'run'];
+const MARKER = '<!-- sprag:codex:delegation -->';
+const safeId = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,255}$/.test(value);
+const validEffort = (value) => value === undefined || ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'].includes(value);
+
+export function validateCodexTarget(model, effort) {
+  if (!safeId(model)) throw new Error('Provide a literal Codex model ID.');
+  if (!validEffort(effort)) {
+    throw new Error('Invalid reasoning effort; choose a value supported by the target model.');
+  }
+  return { model, ...(effort === undefined ? {} : { effort }) };
+}
+
+const rulesFile = (dir) => join(dir, 'codex-model-rules.json');
+export function loadCodexModelRules({ dir = userDataDir() } = {}) {
+  try {
+    const data = JSON.parse(readFileSync(rulesFile(dir), 'utf8'));
+    if (data?.version !== 1 || !Array.isArray(data.rules) || data.rules.some((r) => !r ||
+      !CODEX_ROUTE_CATEGORIES.includes(r.category) || !safeId(r.from) || !safeId(r.model) || r.from === r.model ||
+      !validEffort(r.effort) || r.status !== 'active' || !['global', 'project'].includes(r.scope) ||
+      (r.provider != null && !safeId(r.provider)) ||
+      (r.scope === 'project' ? typeof r.targetRoot !== 'string' || resolve(r.targetRoot) !== r.targetRoot : r.targetRoot !== null))) throw new Error();
+    return data.rules;
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw new Error('Cannot parse Codex model rules; file left unchanged.');
+  }
+}
+
+function saveRules(rules, dir) {
+  mkdirSync(dir, { recursive: true });
+  const file = rulesFile(dir), tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, rules }, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+export function addCodexModelRule({ category, model, effort, from, scope, root, provider }, { dir = userDataDir() } = {}) {
+  validateCodexTarget(model, effort);
+  if (!CODEX_ROUTE_CATEGORIES.includes(category)) throw new Error(`Category must be ${CODEX_ROUTE_CATEGORIES.join(', ')}`);
+  if (!safeId(from) || from === model) throw new Error('--from must name a different parent model.');
+  if (!['global', 'project'].includes(scope)) throw new Error('Choose --global or --project for the rule.');
+  if (provider != null && !safeId(provider)) throw new Error('Invalid Codex provider ID.');
+  const rules = loadCodexModelRules({ dir });
+  const targetRoot = scope === 'project' ? resolve(root) : null;
+  const rule = { category, model, effort, from, scope, targetRoot, ...(provider ? { provider } : {}), status: 'active', createdAt: new Date().toISOString() };
+  const old = rules.findIndex((r) => r.category === category && r.from === from && r.scope === scope && r.targetRoot === targetRoot && r.provider === provider);
+  if (old < 0) rules.push(rule); else rules[old] = rule;
+  saveRules(rules, dir);
+  return rule;
+}
+
+export function removeCodexModelRule(index, { dir = userDataDir() } = {}) {
+  const rules = loadCodexModelRules({ dir });
+  if (!Number.isSafeInteger(index) || index < 1 || index > rules.length) throw new Error('Unknown Codex rule index.');
+  rules.splice(index - 1, 1);
+  saveRules(rules, dir);
+}
+
+/**
+ * The category a prompt can be routed under at runtime, or null. The route
+ * scan counts episodes with this same gate, so a rule it proposes is one the
+ * prompt hook can actually match.
+ */
+export function codexPromptCategory(text) {
+  const prompt = typeof text === 'string' ? text.trim() : '';
+  if (prompt.length < 8 || ESCALATE_RE.test(prompt) || EDIT_RE.test(prompt) || /\b(?:implement|modify|fix|delete|push|commit)\b/i.test(prompt)) return null;
+  const category = categorize(prompt, null);
+  if (!category || (category.id === 'paste' && !looksPasted(prompt))) return null;
+  return category;
+}
+
+export function matchCodexModelRule(text, { model, root, provider = codexProviderName(), rules = loadCodexModelRules() } = {}) {
+  const category = codexPromptCategory(text);
+  if (!category) return null;
+  const usable = rules.filter((r) => r?.status === 'active' && r.category === category.id && r.from === model &&
+    (!r.provider || r.provider === provider) &&
+    safeId(r.model) && validEffort(r.effort) && r.model !== model && (r.scope === 'global' || (r.scope === 'project' && r.targetRoot === resolve(root || '.'))));
+  return usable.find((r) => r.scope === 'project') || usable[0] || null;
+}
+
+export function codexRouteHint(payload, opts = {}) {
+  const rule = matchCodexModelRule(payload?.prompt, { provider: payload?.model_provider || codexProviderName(), ...opts, model: payload?.model, root: opts.root || payload?.cwd });
+  if (!rule) return null;
+  return `[Sprag model routing] This request matches the approved ${rule.category} rule: delegate the bounded task to model ${rule.model}`
+    + (rule.effort ? ` with reasoning_effort ${rule.effort}` : '')
+    + '. Use the available native Codex subagent tool and a built-in role. Wait for its result, verify it, and report unfinished work. '
+    + 'Do not spawn another CLI process. If subagent tools or the target model are unavailable, keep the task on the main agent and state that delegation was unavailable.';
+}
+
+function customRole(role, root, home) {
+  // Custom role files override an explicit spawn model. Leave those calls alone.
+  const layers = new Set([home]);
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    layers.add(join(dir, '.codex'));
+    if (dirname(dir) === dir) break;
+  }
+  for (const layer of layers) {
+    try {
+      const cfg = parse(readFileSync(join(layer, 'config.toml'), 'utf8'));
+      if (Object.hasOwn(cfg.agents || {}, role)) return true;
+    } catch (e) { if (e.code !== 'ENOENT') return true; }
+    const dir = join(layer, 'agents');
+    let names;
+    try { names = readdirSync(dir); } catch (e) { if (e.code === 'ENOENT') continue; return true; }
+    for (const name of names.filter((n) => n.endsWith('.toml'))) {
+      try { if (parse(readFileSync(join(dir, name), 'utf8')).name === role) return true; }
+      catch { return true; }
+    }
+  }
+  return false;
+}
+
+export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd || process.cwd(), home = codexUserDir(), rules, dir = userDataDir(), record = recordCodexDelegation } = {}) {
+  if (cfg.codex?.delegate !== true) return null;
+  const tool = payload?.tool_name?.replace(/^(?:functions|tools)\./, '');
+  if (!['spawn_agent', 'Agent'].includes(tool)) return null;
+  const input = payload.tool_input;
+  if (!input || typeof input !== 'object' || Array.isArray(input) || typeof input.message !== 'string' || !input.message.trim() || input.message.includes(MARKER)) return null;
+  const role = input.agent_type || 'default';
+  if (!['default', 'worker', 'explorer'].includes(role) || customRole(role, payload.cwd || root, home)) return null;
+  const explicit = Object.hasOwn(input, 'model');
+  const provider = payload.model_provider || codexProviderName({ home });
+  const rule = explicit ? null : matchCodexModelRule(input.message, { model: payload.model, provider, root, rules });
+  const target = rule || (!explicit && cfg.codex?.delegateTarget);
+  const updatedInput = { ...input };
+  let routeLine = '';
+  if (target) {
+    validateCodexTarget(target.model, target.effort);
+    updatedInput.model = target.model;
+    if (target.effort !== undefined && !Object.hasOwn(input, 'reasoning_effort')) updatedInput.reasoning_effort = target.effort;
+    // Only a route Sprag applied, with a known parent, can be credited later.
+    if (safeId(payload.model) && payload.model !== target.model) {
+      const id = newRouteId();
+      try {
+        record({ id, parentSessionId: typeof payload.session_id === 'string' ? payload.session_id : null,
+          source: rule ? 'rule' : 'default', category: rule?.category ?? null, scope: rule?.scope ?? null,
+          from: payload.model, to: target.model, provider, effort: updatedInput.reasoning_effort ?? null }, { dir });
+        routeLine = `\n<!-- sprag:codex:route id=${id} -->`;
+      } catch { /* Accounting is optional; the route itself still applies. */ }
+    }
+  }
+  updatedInput.message += `\n\n${MARKER}${routeLine}\nStay within the assigned task and requested output shape. Back findings with file references or actual command results. State what you could not verify. Honor caller-provided limits; do not invent a budget or assume the parent's model tier. Stop and report partial work when a limit or unavailable dependency prevents completion. Do not recursively delegate this bounded task.`;
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', updatedInput } };
+}

package/src/codex-doc2md-ledger.js

@@ -0,0 +1,45 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, realpathSync } from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+import { codexUserDir } from './agent.js';
+import { userDataDir } from './paths.js';
+
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const ledgerDir = ({ home = codexUserDir(), dir = userDataDir() } = {}) => join(dir, 'codex-doc2md', hash(resolve(home)));
+const finite = (n) => Number.isSafeInteger(n) && n >= 0;
+
+// One file per source avoids lost updates when parallel hooks prepare documents.
+export function recordCodexDocument(source, result, opts) {
+  if (!result?.ok) return;
+  try {
+    const dir = ledgerDir(opts);
+    const file = join(dir, `${hash(realpathSync(source))}.json`);
+    const meta = result.meta || {};
+    const event = { version: 1, ext: extname(source).slice(1).toLowerCase(),
+      sourceBytes: finite(meta.size) ? meta.size : null,
+      markdownBytes: finite(meta.markdownBytes) ? meta.markdownBytes : null,
+      clipped: !!(meta.clipped || meta.truncated) };
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(event) + '\n', { mode: 0o600 });
+    renameSync(tmp, file);
+  } catch { /* Accounting must not prevent document conversion. */ }
+}
+
+export function codexDocumentTotals(opts) {
+  const total = { docs: 0, byExt: [], scope: 'codex-total' };
+  const byExt = new Map();
+  try {
+    const dir = ledgerDir(opts);
+    for (const file of readdirSync(dir).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))) {
+      try {
+        const event = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+        if (event?.version !== 1 || !['pdf', 'pptx', 'xlsx', 'xls', 'docx', 'fig'].includes(event.ext)) continue;
+        total.docs++;
+        byExt.set(event.ext, (byExt.get(event.ext) || 0) + 1);
+      } catch { /* Ignore only the damaged record. */ }
+    }
+  } catch { /* No Codex document history yet. */ }
+  total.byExt = [...byExt].map(([ext, docs]) => ({ ext, docs })).sort((a, b) => b.docs - a.docs || a.ext.localeCompare(b.ext));
+  return total;
+}

package/src/codex-doc2md.js

@@ -0,0 +1,99 @@
+import { createRequire } from 'node:module';
+import { realpathSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { recordCodexDocument } from './codex-doc2md-ledger.js';
+
+const require = createRequire(import.meta.url);
+const doc2md = require('./doc2md.cjs');
+const lint = require('./korean-lint.cjs');
+const shellTools = new Set(['Bash', 'exec_command', 'shell_command', 'shell']);
+
+function canonicalPath(file) {
+  const missing = [];
+  for (let current = file; ; current = dirname(current)) {
+    try { return resolve(realpathSync(current), ...missing.reverse()); }
+    catch (e) { if (!['ENOENT', 'ENOTDIR'].includes(e.code) || dirname(current) === current) return file; }
+    missing.push(basename(current));
+  }
+}
+
+export function codexDocumentNote() {
+  return '[Sprag Doc2md]\nBefore reading PDF, Office, or Figma documents, run sprag doc2md <path> --agent codex and read the resulting Markdown. '
+    + 'Conversions are one-way: never edit the cached Markdown. To modify a document, copy the original and edit the copy with a format-aware library, then reconvert it to verify the text. '
+    + 'Text extraction does not verify charts, images, or layout. Report conversion failures and do not claim visual verification from text alone.';
+}
+
+export function convertCodexDocument(source, { convert = doc2md.convert, ...opts } = {}) {
+  let result;
+  try { result = convert(source, { agent: 'codex' }); }
+  catch { return { ok: false, reason: 'convert-failed' }; }
+  if (!result?.ok) return result || { ok: false, reason: 'convert-failed' };
+  let tmp;
+  try {
+    // Existing shared caches can carry Claude attachment baselines and prices.
+    // Keep their body, but give Codex a separate view with neutral provenance.
+    const original = readFileSync(result.cacheFile, 'utf8');
+    const end = original.startsWith('<!--\nsprag doc2md') ? original.indexOf('\n-->\n') : -1;
+    const body = end >= 0 ? original.slice(end + 5) : original;
+    const cacheFile = result.cacheFile.replace(/\.md$/, '.codex.md');
+    const text = `<!--\nsprag doc2md: generated Markdown; do not edit.\nSource: ${JSON.stringify(resolve(source))}\nText extraction does not verify images or layout.\n-->\n${body}`;
+    let previous;
+    try { previous = readFileSync(cacheFile, 'utf8'); } catch { /* First Codex use. */ }
+    if (previous !== text) {
+      tmp = `${cacheFile}.${randomUUID()}.tmp`;
+      writeFileSync(tmp, text, { mode: 0o600 });
+      renameSync(tmp, cacheFile);
+      tmp = null;
+    }
+    const { savedUsd, baselineTokens, ...meta } = result.meta || {};
+    const prepared = { ...result, cacheFile, meta };
+    recordCodexDocument(source, prepared, opts);
+    return prepared;
+  } catch {
+    return { ok: false, reason: 'cache-unavailable' };
+  } finally {
+    if (tmp) { try { rmSync(tmp, { force: true }); } catch { /* Best-effort temporary file cleanup. */ } }
+  }
+}
+
+/** Adapt supported Codex calls to the shared converter and write guard. */
+export function codexDocumentTool(payload, { convert = convertCodexDocument, guard = doc2md.decideForWrite } = {}) {
+  const tool = payload?.tool_name?.replace(/^(?:functions|tools)\./, '');
+  const input = payload?.tool_input;
+  const command = typeof input === 'string' ? input : input?.command ?? input?.cmd ?? input?.content ?? input?.patch;
+  const cwd = resolve(payload?.cwd || process.cwd(), typeof input?.workdir === 'string' ? input.workdir : '.');
+  let writes = [];
+  if (tool === 'apply_patch' && typeof command === 'string' && command.startsWith('*** Begin Patch')) {
+    writes = [...command.matchAll(/^\*\*\* (?:Add File|Update File|Move to): (.+)\r?$/gm)].map((m) => m[1].trimEnd());
+  } else if (['Edit', 'Write'].includes(tool) && typeof input?.file_path === 'string') writes = [input.file_path];
+  else if (shellTools.has(tool)) writes = lint.writtenPathsOfBash(command);
+  for (const path of writes) {
+    const file = resolve(cwd, path);
+    const canonical = canonicalPath(file);
+    for (const target of new Set([file, canonical])) {
+      const decision = guard({ tool_name: 'Write', tool_input: { file_path: target } }, { agent: 'codex' });
+      if (decision?.deny) return { hookSpecificOutput: { hookEventName: 'PreToolUse',
+        permissionDecision: 'deny', permissionDecisionReason: decision.reason } };
+    }
+  }
+
+  let file;
+  if (['Read', 'read_file', 'mcp__filesystem__read_file', 'mcp__filesystem__read_text_file'].includes(tool)) {
+    file = input?.file_path ?? input?.path;
+  } else if (shellTools.has(tool) && typeof command === 'string') {
+    // Only literal, single-file reads. Compound commands and expansions stay untouched.
+    const match = /^(?:cat\s+(?:--\s+)?|(?:head|tail)\s+(?:-n\s+\d+\s+)?)(?:"([^"$`\n]+)"|'([^'\n]+)'|([^\s'"`$;&|<>*?(){}\\]+))\s*$/.exec(command.trim());
+    if (match) file = match[1] || match[2] || match[3];
+  }
+  if (typeof file !== 'string' || !doc2md.isTargetPath(file)) return null;
+  const result = convert(resolve(cwd, file));
+  if (!result.ok) return { hookSpecificOutput: { hookEventName: 'PreToolUse',
+    ...(result.reason === 'unsafe-archive' ? { permissionDecision: 'deny', permissionDecisionReason: '[doc2md] Unsafe archive; do not extract it.' }
+      : { additionalContext: `[doc2md] Conversion failed (${result.reason}). Do not claim this document was converted. ${codexDocumentNote()}` }) } };
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny',
+    permissionDecisionReason: `[doc2md] Read the converted Markdown at ${JSON.stringify(result.cacheFile)} instead of extracting ${JSON.stringify(file)} again. `
+      + `Source ${result.meta?.size ?? 'unknown'} bytes; Markdown ${result.meta?.markdownBytes ?? 'unknown'} bytes.`
+      + (result.meta?.clipped ? ' The conversion is clipped; it is not the complete document.'
+        : result.meta?.truncated ? ' Text extraction is incomplete; it is not the complete document.' : '') } };
+}

package/src/codex-doctor.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'smol-toml';
+import { codexUserDir } from './agent.js';
+import { codexHookStatus } from './codex-installer.js';
+import { createPanelReader } from './codex-panel.js';
+import { panelHealth } from './codex-panel-state.js';
+
+export const CODEX_CAPABILITIES = [
+  { feature: 'statusline', support: 'supported', command: 'sprag --statusline --agent codex', note: 'Local terminal output; native footer accepts only Codex item identifiers.' },
+  { feature: 'panel', support: 'supported', command: 'sprag panel --agent codex', note: 'Local logs; tmux inline layout; optional macOS window.' },
+  { feature: 'reports', support: 'supported', command: 'sprag --agent codex --format json', note: 'Token usage, cached input, reasoning, session and project filters.' },
+  { feature: 'harness', support: 'supported', command: 'sprag harness check --agent codex', note: 'AGENTS.md, overrides, explicit-scope ratchet rule management.' },
+  { feature: 'brief', support: 'supported', command: 'sprag brief --agent codex', note: 'Fresh context and limit warnings; change-triggered prompt hook.' },
+  { feature: 'history', support: 'supported', command: 'sprag history --agent codex', note: 'Codex-only session warning records; last shows the latest warning.' },
+  { feature: 'handoff', support: 'supported', command: 'sprag handoff --agent codex', note: 'Git state and recorded Codex session usage; never reads Claude caps.' },
+  { feature: 'korean', support: 'supported', command: 'sprag korean status --agent codex', note: 'Session guidance and recognized write-target lint; shared preference.' },
+  { feature: 'cohesion', support: 'supported', command: 'sprag cohesion status --agent codex', note: 'Shared English guidance preference.' },
+  { feature: 'doc2md', support: 'supported', command: 'sprag doc2md status --agent codex', note: 'Shared converter, prompt paths, supported file reads, and recognized document/cache write guards; not arbitrary shell extraction.' },
+  { feature: 'delegate', support: 'supported', command: 'sprag delegate on --agent codex', note: 'Opt-in native spawn model routing, scoped category rules, and SubagentStart guidance. Explicit models/custom roles preserved; no enforced budget.' },
+  { feature: 'routing-saved', support: 'partial', command: 'sprag route-scan savings --agent codex', note: 'Sprag-routed child usage with matching LiteLLM prices; counterfactual estimate, not billed savings. Unpriced runs stay unknown.' },
+  { feature: 'cache-timer', support: 'partial', command: 'sprag cache status --refresh --agent codex', note: 'Documented minimum retention after recorded cache usage; LiteLLM deployments resolved through model/info. Unknown routes show age; exact expiry is not reported.' },
+  { feature: 'mode', support: 'partial', command: 'sprag mode --agent codex', note: 'Labels, color, and timer apply to panel/statusline; Claude TTL buckets do not.' },
+  { feature: 'upgrade', support: 'manual', command: 'sprag upgrade --print --agent codex', note: 'Skip the Claude npm postinstall; reinstall Codex hooks after upgrade.' },
+  { feature: 'route-scan', support: 'supported', command: 'sprag route-scan --agent codex', note: 'Recurring simple turns grouped by project, provider, and parent model; explicit approval before routing.' },
+  { feature: 'seed', support: 'supported', command: 'sprag seed --agent codex', note: 'Agent-compatible ratchet presets; separate decisions and explicit scope. No Claude tier presets.' },
+  { feature: 'transcript ratchet', support: 'supported', command: 'sprag --statusline --agent codex', note: 'Recent repeated tool failures become ratchet? candidates; no automatic rule registration.' },
+  { feature: 'compact-window', support: 'native', note: 'Codex uses model_auto_compact_token_limit; no Claude autoCompactWindow heuristic.' },
+  { feature: 'cost / exact cache expiry', support: 'unavailable', note: 'Not measured in rollout logs; never estimated with Anthropic prices.' },
+];
+
+export async function codexDoctor({ root = process.cwd(), sessionId, days = 7 } = {}) {
+  const home = codexUserDir();
+  const file = join(home, 'config.toml');
+  const config = { file, present: existsSync(file) };
+  try {
+    const cfg = config.present ? parse(readFileSync(file, 'utf8')) : {};
+    // Only expose an allowlist. Provider auth and arbitrary config may hold secrets.
+    config.hooksDisabled = cfg.features?.hooks === false || (cfg.features?.hooks === undefined && cfg.features?.codex_hooks === false);
+    config.statusLine = Array.isArray(cfg.tui?.status_line) ? cfg.tui.status_line.filter((item) => typeof item === 'string') : null;
+    config.autoCompactTokenLimit = Number.isFinite(cfg.model_auto_compact_token_limit) ? cfg.model_auto_compact_token_limit : null;
+    config.note = 'User config only; active profile, project, managed policy, and runtime overrides may differ.';
+  } catch { config.error = 'Cannot parse user config.toml; file left unchanged.'; }
+  let hooks;
+  try { hooks = { file: join(home, 'hooks.json'), events: codexHookStatus(), trust: 'unknown; review in Codex /hooks' }; }
+  catch { hooks = { error: 'Cannot parse Codex hooks.json; file left unchanged.', events: [] }; }
+  const data = await createPanelReader({ root, sessionId, days })();
+  const session = data.session ? { id: data.session.sessionId, model: data.session.model,
+    lastActivity: data.session.lastActivity, usageUpdates: data.session.requestCount } : null;
+  return { agent: 'codex', home, root, config, hooks, harness: data.harness, rules: data.rules,
+    preferences: { korean: data.korean, lint: data.lint, cohesion: data.cohesion, doc2md: data.doc2md, brief: data.brief, delegate: data.delegate },
+    session, panel: panelHealth(root, { sessionId }), capabilities: CODEX_CAPABILITIES };
+}

package/src/codex-harness.js

@@ -0,0 +1,200 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { codexUserDir } from './agent.js';
+import { codexToolEvents, codexLegacyToolEvent, readCodexTailLines } from './codex-parser.js';
+
+export const CODEX_BEGIN = '<!-- sprag:codex:harness:begin -->';
+export const CODEX_END = '<!-- sprag:codex:harness:end -->';
+const sections = [
+  ['Ratchet', 'When a mistake recurs, propose a concise condition/action rule. Ask the user for global or project scope before registering it with `sprag harness promote --agent codex --global|--project "rule"`.'],
+  ['Evidence', 'Support completion claims with actual test results, command output, a file diff, or a screenshot. State any verification you could not run.'],
+  ['Plan, Execute, Verify', 'For multi-step work, plan the steps, execute them, and verify the result before reporting completion.'],
+  ['Structured Task', 'Establish the goal, constraints, verification method, and completion criteria before substantial work.'],
+  ['Default Safe Path', 'Ask before destructive or external actions unless already authorized. Proceed with reads, local edits, and tests within the granted permissions.'],
+];
+
+export function codexHarnessPaths(root, scope = 'project') {
+  const dir = scope === 'global' ? codexUserDir() : root;
+  // Codex reads the override instead of AGENTS.md when it is non-empty.
+  const override = join(dir, 'AGENTS.override.md');
+  const file = existsSync(override) && readFileSync(override, 'utf8').trim() ? override : join(dir, 'AGENTS.md');
+  return { file, ratchet: scope === 'global' ? join(dir, 'ratchet.md') : join(dir, '.codex', 'ratchet.md') };
+}
+
+export function codexHarnessBlock() {
+  return `${CODEX_BEGIN}\n## Sprag Harness\n\n${sections.map(([name, text], i) => `### ${i + 1}. ${name}\n${text}`).join('\n\n')}\n\nRead the global and project Codex ratchet files before working when present. Run \`sprag harness list --agent codex --global\` and \`sprag harness list --agent codex --project\` to retrieve them. These are instructions, not Claude-style @ imports.\nUse \`sprag doc2md <file> --agent codex\` before reading PDF, Office, or Figma documents. Delegate only through available Codex tools and configured roles; do not assume Claude model names or Task/Agent arguments.\n${CODEX_END}\n`;
+}
+
+function range(content) {
+  const begin = content.indexOf(CODEX_BEGIN);
+  const end = content.indexOf(CODEX_END);
+  if ((begin < 0) !== (end < 0) || (begin >= 0 && end < begin) || content.indexOf(CODEX_BEGIN, begin + CODEX_BEGIN.length) >= 0) {
+    throw new Error('Malformed Sprag Codex harness markers; repair them before updating this file.');
+  }
+  return begin < 0 ? null : [begin, end + CODEX_END.length];
+}
+
+export function initCodexHarness({ root, scope = 'project' }) {
+  const paths = codexHarnessPaths(root, scope);
+  const existing = existsSync(paths.file) ? readFileSync(paths.file, 'utf8') : '';
+  const span = range(existing);
+  const block = codexHarnessBlock();
+  const next = span ? existing.slice(0, span[0]) + block.trimEnd() + existing.slice(span[1])
+    : existing + (existing ? '\n\n' : '') + block;
+  mkdirSync(dirname(paths.file), { recursive: true });
+  if (next !== existing) {
+    if (existing) writeFileSync(`${paths.file}.bak-${Date.now()}`, existing);
+    writeFileSync(paths.file, next);
+  }
+  if (!existsSync(paths.ratchet)) {
+    mkdirSync(dirname(paths.ratchet), { recursive: true });
+    writeFileSync(paths.ratchet, '# Codex Ratchet Rules\n\n## Rules\n\n');
+  }
+  return paths;
+}
+
+export function uninitCodexHarness({ root, scope = 'project' }) {
+  const { file } = codexHarnessPaths(root, scope);
+  if (!existsSync(file)) return { file, removed: false };
+  const existing = readFileSync(file, 'utf8');
+  const span = range(existing);
+  if (!span) return { file, removed: false };
+  writeFileSync(`${file}.bak-${Date.now()}`, existing);
+  writeFileSync(file, existing.slice(0, span[0]) + existing.slice(span[1]));
+  return { file, removed: true };
+}
+
+export function codexHarnessStatus({ root, scope = 'project' }) {
+  const { file } = codexHarnessPaths(root, scope);
+  const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const span = range(text);
+  const block = span ? text.slice(...span) : '';
+  const missing = sections.filter(([name], i) => !block.includes(`### ${i + 1}. ${name}`)).map(([name]) => name);
+  return { file, configured: sections.length - missing.length, total: sections.length, missing };
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const LOOKUP = new Set(['read', 'search', 'list_files']);
+
+/** The script a `zsh -lc` argv runs, or the argv itself. */
+function commandLine(argv) {
+  const i = argv.findIndex((a) => a === '-lc' || a === '-c');
+  return (i >= 0 ? argv[i + 1] : argv.join(' ')) || '';
+}
+
+/** Shell words of a script's first command, honoring simple quotes. */
+function firstWords(script, n) {
+  const words = [];
+  for (const m of String(script).matchAll(/'([^']*)'|"([^"]*)"|([^\s'"|;&]+)|([|;&])/g)) {
+    if (m[4]) break;
+    words.push(m[1] ?? m[2] ?? m[3]);
+    if (words.length === n) break;
+  }
+  return words;
+}
+
+// Tools whose exit 1 is an answer, not an error: grep-style "no match" and
+// diff/cmp-style "the inputs differ". Only exit 1 is exempt; 2+ still counts.
+const ANSWER_EXIT_1 = /^(?:diff|cmp|grep|egrep|fgrep|rg|ag|test|\[|comm)$|^git (?:diff|grep)$/;
+
+/**
+ * A failure's identity across retries: the command's first two words plus the
+ * start of its output, with run-specific noise (paths, ids, positions) removed
+ * so the same failure in another temp dir still matches. Other numbers stay,
+ * since exit codes and counts carry meaning.
+ */
+export function codexErrorSignature(ev, { cwd, home = homedir() } = {}) {
+  let text = String(ev.output || '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+  if (cwd) text = text.replace(new RegExp(escapeRe(cwd), 'g'), '.');
+  if (home) text = text.replace(new RegExp(escapeRe(home), 'g'), '~');
+  text = text.replace(/(?:\/private)?\/(?:tmp|var\/folders)\/[^\s:'"]+/g, '<tmp>')
+    .replace(/\b[0-9a-f]{8,}(?:-[0-9a-f]{4,}){0,4}\b/gi, '<id>')
+    .replace(/:\d+:\d+/g, ':N:N')
+    .replace(/\s+/g, ' ').trim().slice(0, 80);
+  const head = ev.kind === 'patch' ? 'apply_patch'
+    : firstWords(commandLine(ev.argv || []), 2).map((w) => w.split('/').pop()).join(' ');
+  return `${head}: ${text}`;
+}
+
+/** Whether a failure is worth remembering, rather than a probe or Sprag's own feedback. */
+function countable(ev) {
+  if (!ev.failed) return false;
+  // Sprag's write lint rewrites the tool output; that is feedback, not a mistake to learn from.
+  if (/^\[(?:korean-style|claude-token-saver|sprag)/.test(String(ev.output || '').trim())) return false;
+  if (ev.kind === 'patch') return true;
+  // `rg` finding nothing and `ls` on an absent path are how exploration works.
+  const types = (ev.parsed || []).map((c) => c?.type);
+  if (types.length && types.every((t) => LOOKUP.has(t))) return false;
+  if (ev.exit === 1) {
+    const words = firstWords(commandLine(ev.argv || []), 2).map((w) => w.split('/').pop());
+    if (ANSWER_EXIT_1.test(words[0]) || ANSWER_EXIT_1.test(words.join(' '))) return false;
+  }
+  return true;
+}
+
+/**
+ * Repeated failures in a rollout's recent turns, newest-first by count. Reads
+ * only the file tail, which is where the current session's recent work is.
+ */
+export function codexRatchetCandidates(filePath, { now = Date.now(), turns: window = 30, ttlMs = 30 * 60000, tailBytes = 2 * 1024 * 1024, home } = {}) {
+  const lines = readCodexTailLines(filePath, tailBytes);
+  if (!lines) return [];
+  const order = [];
+  const seen = new Set();
+  const failures = [];
+  const calls = new Map();
+  const outputs = [];
+  let cwd = null;
+  let current = null;
+  for (const line of lines) {
+    // Cheap prefilter: these candidate lines are a small share of a rollout.
+    if (!/"(?:item_completed|exec_command_end|patch_apply_end|task_started|turn_context|session_meta|function_call|function_call_output|custom_tool_call|custom_tool_call_output)"/.test(line)) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const p = e?.payload;
+    if (e?.type === 'session_meta' && typeof p?.cwd === 'string') cwd ??= p.cwd;
+    if (e?.type === 'turn_context' && typeof p?.cwd === 'string') cwd = p.cwd;
+    if (e?.type === 'event_msg' && p?.type === 'task_started') current = p.turn_id || current;
+    for (const ev of codexToolEvents(e)) {
+      if (ev.kind === 'call') { if (ev.callId) calls.set(ev.callId, ev); continue; }
+      if (ev.kind === 'output') {
+        if (ev.exit !== null && ev.callId) outputs.push({ ...ev, turn: current, cwd });
+        continue;
+      }
+      if (ev.kind !== 'command' && ev.kind !== 'patch') continue;
+      if (ev.callId) { if (seen.has(ev.callId)) continue; seen.add(ev.callId); }
+      const turn = ev.turnId || current;
+      if (turn && !order.includes(turn)) order.push(turn);
+      if (countable(ev)) failures.push({ ...ev, turn, cwd: ev.cwd || cwd });
+    }
+  }
+  for (const out of outputs) {
+    if (seen.has(out.callId)) continue;
+    const ev = codexLegacyToolEvent(calls.get(out.callId), out);
+    if (!ev) continue;
+    seen.add(out.callId);
+    if (ev.turn && !order.includes(ev.turn)) order.push(ev.turn);
+    if (countable(ev)) failures.push(ev);
+  }
+  const recent = new Set(order.slice(-window));
+  const groups = new Map();
+  for (const ev of failures) {
+    if (!recent.has(ev.turn) || !Number.isFinite(ev.at) || now - ev.at > ttlMs) continue;
+    const pattern = codexErrorSignature(ev, { cwd: ev.cwd, home });
+    const g = groups.get(pattern) || { pattern, count: 0, lastAt: 0 };
+    g.count++;
+    g.lastAt = Math.max(g.lastAt, ev.at);
+    groups.set(pattern, g);
+  }
+  return [...groups.values()].filter((g) => g.count >= 2)
+    .sort((a, b) => b.count - a.count || b.lastAt - a.lastAt).slice(0, 5)
+    .map((g, i) => ({ id: i + 1, ...g }));
+}
+
+/** The ratchet text a candidate promotes to; the user replaces the TODO. */
+export function codexCandidateRule(cand, lang) {
+  return lang === 'ko'
+    ? `반복 감지 ×${cand.count}: ${cand.pattern} · TODO: 원인과 예방책을 한 줄로 적습니다`
+    : `Repeated failure x${cand.count}: ${cand.pattern} · TODO: write the cause and prevention in one line`;
+}