sprag-cli 3.54.0 → 3.56.0

package/src/codex-cache-policy.js

@@ -6,6 +6,10 @@ import { codexUserDir } from './agent.js';
 import { userDataDir } from './paths.js';
 import { codexBudgetProvider, codexProviderKey } from './codex-budget.js';
 import { codexCachePolicy } from './codex-cache.js';
+import { PRICE_MAX_AGE_MS, gatewayPrices } from './gateway-prices.js';
+import { OPENAI_LIST_PRICES, OPENAI_PRICES_CHECKED_AT } from './openai-prices.js';
+
+export { PRICE_MAX_AGE_MS, rate, deploymentPrice, gatewayPrices, codexRunCost } from './gateway-prices.js';
 
 export const CACHE_POLICY_MAX_AGE_MS = 300000;
 const OPENAI_POLICY = 'https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime';
@@ -51,42 +55,6 @@ export function gatewayCachePolicies(payload) {
     policies[0] && policies.every((p) => JSON.stringify(p) === JSON.stringify(policies[0])) ? policies[0] : null]));
 }
 
-export const PRICE_MAX_AGE_MS = 7 * 86400000;
-const rate = (value) => Number.isFinite(value) && value >= 0 && value < 1 ? value : null;
-
-function deploymentPrice(row) {
-  const info = row?.model_info || {};
-  const mode = typeof info.mode === 'string' ? info.mode : null;
-  if (mode && !['chat', 'responses', 'completion'].includes(mode)) return null;
-  const input = rate(info.input_cost_per_token), output = rate(info.output_cost_per_token);
-  if (input === null || output === null) return null;
-  return { input, output, cacheRead: rate(info.cache_read_input_token_cost), cacheWrite: rate(info.cache_creation_input_token_cost) };
-}
-
-/** Per-token prices by alias. Load-balanced deployments must agree, like cache policy. */
-export function gatewayPrices(payload) {
-  if (!Array.isArray(payload?.data)) throw new Error('LiteLLM model/info returned no model list');
-  const groups = new Map();
-  for (const row of payload.data) {
-    if (typeof row?.model_name !== 'string' || row.model_name.length > 256) continue;
-    groups.set(row.model_name, [...(groups.get(row.model_name) || []), deploymentPrice(row)]);
-  }
-  return Object.fromEntries([...groups].map(([name, prices]) => [name,
-    prices[0] && prices.every((p) => JSON.stringify(p) === JSON.stringify(prices[0])) ? prices[0] : null]));
-}
-
-/**
- * USD for a token mix at one model's prices, or null when a needed rate is
- * missing. Cached input without a cache-read rate is unknown, not free.
- */
-export function codexRunCost({ input = 0, cached = 0, cacheWrite = 0, output = 0 }, price) {
-  if (!price || price.input === null || price.output === null) return null;
-  if (cached > 0 && price.cacheRead === null) return null;
-  // cache_write_input_tokens is billed at the creation rate when one is published, else as input.
-  const uncached = Math.max(0, input - cached - cacheWrite);
-  return uncached * price.input + cached * (price.cacheRead ?? 0) + cacheWrite * (price.cacheWrite ?? price.input) + output * price.output;
-}
-
 function cacheFile(provider, { home = codexUserDir(), dir = userDataDir() } = {}) {
   const key = createHash('sha256').update(JSON.stringify([resolve(home), provider.name, provider.base])).digest('hex').slice(0, 24);
   return join(dir, 'codex-cache-policy', `${key}.json`);
@@ -97,14 +65,31 @@ function gatewayProvider(session, opts) {
   return codexBudgetProvider({ ...opts, providerName: session.provider });
 }
 
-function directPolicy(session, { home = codexUserDir(), now = Date.now() } = {}) {
-  if (session?.provider !== 'openai' || !codexCachePolicy(session.model)) return null;
+/** True when Codex's OpenAI provider talks to api.openai.com itself, not to a proxy. No config = direct. */
+export function isDirectOpenAI(provider, { home = codexUserDir() } = {}) {
+  if (provider !== 'openai') return false;
   try {
     let cfg = {};
     try { cfg = parse(readFileSync(join(home, 'config.toml'), 'utf8')); }
-    catch (e) { if (e.code !== 'ENOENT') return null; }
-    if (cfg.openai_base_url && new URL(cfg.openai_base_url).hostname !== 'api.openai.com') return null;
-  } catch { return null; }
+    catch (e) { if (e.code !== 'ENOENT') return false; }
+    if (cfg.openai_base_url && new URL(cfg.openai_base_url).hostname !== 'api.openai.com') return false;
+  } catch { return false; }
+  return true;
+}
+
+/**
+ * The price table a Codex provider's calls are billed by: OpenAI list prices for
+ * direct calls, the gateway's own /model/info prices for a LiteLLM provider.
+ * Never a fallback chain, so a model the gateway does not price stays unpriced.
+ */
+export function codexPriceBook(provider, litellm, opts = {}) {
+  if (isDirectOpenAI(provider, opts)) return { source: 'list', provider: 'openai', checkedAt: OPENAI_PRICES_CHECKED_AT, prices: OPENAI_LIST_PRICES };
+  if (litellm?.provider === provider) return { ...litellm, source: 'litellm' };
+  return null;
+}
+
+function directPolicy(session, { home = codexUserDir(), now = Date.now() } = {}) {
+  if (!codexCachePolicy(session?.model) || !isDirectOpenAI(session?.provider, { home })) return null;
   return { backend: 'OpenAI', model: session.model, seconds: codexCachePolicy(session.model),
     requestedModel: session.model, provider: session.provider, checkedAt: now, reference: OPENAI_POLICY };
 }

package/src/codex-delegation.js

@@ -7,6 +7,7 @@ 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';
+import { readCodexTailLines } from './codex-parser.js';
 
 export const CODEX_ROUTE_CATEGORIES = ['paste', 'translate', 'explore', 'read', 'check', 'run'];
 const MARKER = '<!-- sprag:codex:delegation -->';
@@ -88,13 +89,50 @@ export function matchCodexModelRule(text, { model, root, provider = codexProvide
   return usable.find((r) => r.scope === 'project') || usable[0] || null;
 }
 
+/**
+ * Input tokens from the rollout's last token_count record, or 0 when the
+ * transcript is missing or unreadable. Only the tail is read: the newest
+ * measurement is always near the end of the file.
+ */
+export function codexContextTokens(transcriptPath) {
+  const lines = readCodexTailLines(transcriptPath, 512 * 1024);
+  if (!lines) return 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line || !line.includes('token_count')) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const n = e?.payload?.type === 'token_count' ? e.payload?.info?.last_token_usage?.input_tokens : undefined;
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return 0;
+}
+
+/**
+ * A prompt-time routing suggestion for Codex 0.159.2, where `spawn_agent`
+ * never reaches PreToolUse (see codexDelegationTool below). Gated on parent
+ * context size: a small parent's own coordination overhead outweighs the
+ * savings from a delegated child (measured 2026-09-30, see docs/CODEX.md).
+ */
 export function codexRouteHint(payload, opts = {}) {
-  const rule = matchCodexModelRule(payload?.prompt, { provider: payload?.model_provider || codexProviderName(), ...opts, model: payload?.model, root: opts.root || payload?.cwd });
+  const provider = payload?.model_provider || codexProviderName();
+  const rule = matchCodexModelRule(payload?.prompt, { provider, ...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.';
+  const minContext = opts.minContext ?? 60000;
+  const ctx = opts.contextTokens ?? codexContextTokens(payload?.transcript_path);
+  if (ctx < minContext) return null;
+  const id = newRouteId();
+  const record = opts.record ?? recordCodexDelegation;
+  try {
+    record({ id, parentSessionId: payload?.session_id ?? null, turnId: payload?.turn_id ?? null, via: 'prompt',
+      source: 'rule', category: rule.category, scope: rule.scope, from: payload?.model, to: rule.model,
+      provider, effort: rule.effort ?? null, contextTokens: ctx }, { dir: opts.dir });
+  } catch { /* Accounting is optional; the hint still applies. */ }
+  return `[Sprag model routing] This request matches the approved ${rule.category} rule (route ${id}). `
+    + `Spawn one sub-agent with model ${rule.model}${rule.effort ? `, reasoning_effort ${rule.effort}` : ''} and fork_turns "none". `
+    + `Give it a self-contained task message that ends with the line <!-- sprag:codex:route id=${id} -->. `
+    + 'Wait for it to finish (call wait_agent with timeout_ms of at least 120000, and again if it times out) and do not do the delegated task yourself while it runs; then verify its result and report unfinished work. Do not spawn another CLI process. '
+    + 'If sub-agent 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) {
@@ -120,6 +158,8 @@ function customRole(role, root, home) {
   return false;
 }
 
+// Kept for Codex versions that do send spawn_agent through PreToolUse; on
+// 0.159.2 the hook never fires for it, so codexRouteHint above is the live path.
 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)\./, '');

package/src/codex-doctor.js

@@ -12,7 +12,7 @@ export const CODEX_CAPABILITIES = [
   { 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: 'history', support: 'supported', command: 'sprag history --agent codex', note: 'Codex-only records of context (80%/95%) and 5h/weekly rate-limit (90%) warnings, plus handoffs. Cache and TTL chips are not recorded; last shows the latest event.' },
   { 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.' },

package/src/codex-harness.js

@@ -2,7 +2,7 @@ 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';
+import { codexToolEvents, codexLegacyToolEvent, readCodexTailLines, forkedCopyFilter } from './codex-parser.js';
 
 export const CODEX_BEGIN = '<!-- sprag:codex:harness:begin -->';
 export const CODEX_END = '<!-- sprag:codex:harness:end -->';
@@ -23,7 +23,7 @@ export function codexHarnessPaths(root, scope = 'project') {
 }
 
 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`;
+  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. A [Sprag model routing] note on a request means the user has asked for that request to be delegated: spawn the sub-agent it describes (its model, reasoning_effort, fork_turns "none", and a self-contained message ending with the route line it gives), wait for it to finish instead of doing the same task yourself, then verify the result before replying.\n${CODEX_END}\n`;
 }
 
 function range(content) {
@@ -133,11 +133,8 @@ function countable(ev) {
   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 } = {}) {
+/** Countable failures in one rollout's last `window` turns. Reads only the file tail. */
+function rolloutFailures(filePath, { window, tailBytes }) {
   const lines = readCodexTailLines(filePath, tailBytes);
   if (!lines) return [];
   const order = [];
@@ -147,11 +144,14 @@ export function codexRatchetCandidates(filePath, { now = Date.now(), turns: wind
   const outputs = [];
   let cwd = null;
   let current = null;
+  const copied = forkedCopyFilter();
   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;
+    if (!/"(?:item_completed|exec_command_end|patch_apply_end|task_started|turn_context|session_meta|thread_settings_applied|function_call|function_call_output|custom_tool_call|custom_tool_call_output)"/.test(line)) continue;
     let e;
     try { e = JSON.parse(line); } catch { continue; }
+    // A forked child's copy of the parent history holds the parent's failures, not its own.
+    if (copied(e)) 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;
@@ -178,9 +178,20 @@ export function codexRatchetCandidates(filePath, { now = Date.now(), turns: wind
     if (countable(ev)) failures.push(ev);
   }
   const recent = new Set(order.slice(-window));
+  return failures.filter((ev) => recent.has(ev.turn));
+}
+
+/**
+ * Repeated failures in recent turns, newest-first by count. `siblings` are
+ * other rollouts of the same project: every `codex exec` run writes its own
+ * file, so a mistake repeated across runs only shows up when they are read
+ * together. The TTL applies to all of them.
+ */
+export function codexRatchetCandidates(filePath, { now = Date.now(), turns: window = 30, ttlMs = 30 * 60000, tailBytes = 2 * 1024 * 1024, home, siblings = [] } = {}) {
+  const failures = [filePath, ...siblings].filter(Boolean).flatMap((file) => rolloutFailures(file, { window, tailBytes }));
   const groups = new Map();
   for (const ev of failures) {
-    if (!recent.has(ev.turn) || !Number.isFinite(ev.at) || now - ev.at > ttlMs) continue;
+    if (!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++;

package/src/codex-hooks.js

@@ -1,7 +1,8 @@
 import { createRequire } from 'node:module';
 import { spawn } from 'node:child_process';
-import { readFileSync, statSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { mkdirSync, openSync, readFileSync, readSync, closeSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { loadConfig, userLanguage } from './config.js';
 import { koreanStyleInjection, koreanStyleEnabled } from './korean-style.js';
 import { cohesionInjection } from './cohesion.js';
@@ -10,8 +11,11 @@ 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 { bindCodexSubagent } from './codex-ledger.js';
 import { seedOfferBlock } from './seed-rules.js';
 import { readCodexRouteScan, openCodexCandidates, shouldRescanCodex } from './codex-route-scan.js';
+import { userDataDir } from './paths.js';
+import { debug } from './debug.js';
 
 const require = createRequire(import.meta.url);
 const lint = require('./korean-lint.cjs');
@@ -21,6 +25,80 @@ function context(event, text) {
   return text ? { hookSpecificOutput: { hookEventName: event, additionalContext: text } } : null;
 }
 
+/**
+ * Codex 0.159.2 keeps about 2,450 tokens of one hook's context and cuts the
+ * middle: a 4,500-token SessionStart kept its head and tail and dropped 2,042
+ * tokens, which was most of the Korean style guide, while the low-priority
+ * offers at the end survived. The budget leaves room for estimate error.
+ */
+export const CODEX_CONTEXT_TOKEN_BUDGET = 2000;
+
+/** Overestimates on purpose: ASCII at 3.5 chars a token, anything else at 1.3. */
+export function estimateCodexTokens(text) {
+  let ascii = 0, other = 0;
+  for (const ch of String(text ?? '')) { if (ch.codePointAt(0) < 128) ascii++; else other++; }
+  return Math.ceil(ascii / 3.5 + other / 1.3);
+}
+
+/**
+ * Fit context parts into the budget whole, never cut. Parts are tried by
+ * priority (lower first); a part that does not fit moves to `overflowFile`
+ * when `spill` is set and is dropped otherwise. A pointer to the file goes
+ * first, since the head of a context is what Codex always keeps.
+ */
+export function fitCodexContext(parts, { budget = CODEX_CONTEXT_TOKEN_BUDGET, overflowFile, write = writeOverflow } = {}) {
+  const items = parts.map((p, i) => ({ ...p, i, tokens: estimateCodexTokens(p.text) })).filter((p) => p.text);
+  const pointer = (file) => `[Sprag] Some Sprag instructions exceed Codex's hook context limit. Read ${JSON.stringify(file)} before starting work and follow it like the instructions below.`;
+  const reserve = overflowFile && items.some((p) => p.spill) ? estimateCodexTokens(pointer(overflowFile)) : 0;
+  let used = reserve;
+  const kept = new Set(), spilled = [];
+  for (const p of [...items].sort((a, b) => a.priority - b.priority || a.i - b.i)) {
+    if (used + p.tokens <= budget) { kept.add(p.i); used += p.tokens; }
+    else if (p.spill && overflowFile) spilled.push(p);
+  }
+  const out = items.filter((p) => kept.has(p.i)).map((p) => p.text);
+  if (spilled.length) {
+    try {
+      write(overflowFile, spilled.sort((a, b) => a.i - b.i).map((p) => p.text).join('\n\n') + '\n');
+      out.unshift(pointer(overflowFile));
+    } catch (e) { debug('codex:overflow', e); }
+  }
+  return out.join('\n\n');
+}
+
+function writeOverflow(file, text) {
+  mkdirSync(join(file, '..'), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, text, { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+function overflowFileFor(root) {
+  const key = createHash('sha256').update(resolve(root || '.')).digest('hex').slice(0, 16);
+  return join(userDataDir(), 'codex-context', `${key}.md`);
+}
+
+/**
+ * `codex exec` runs have no one to answer a question, yet their SessionStart
+ * payload says `source: "startup"` like an interactive one. The rollout's
+ * first record says who started it (`originator: "codex_exec"`).
+ */
+export function isCodexExecSession(transcriptPath) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath) return false;
+  let fd;
+  try {
+    fd = openSync(transcriptPath, 'r');
+    const buffer = Buffer.alloc(64 * 1024);
+    const length = readSync(fd, buffer, 0, buffer.length, 0);
+    const first = JSON.parse(buffer.subarray(0, length).toString('utf8').split('\n')[0]);
+    const meta = first?.type === 'session_meta' ? first.payload : null;
+    return meta?.originator === 'codex_exec' || meta?.source === 'exec';
+  } catch (e) {
+    if (e?.code !== 'ENOENT') debug('codex:exec-detect', e);
+    return false;
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+
 /**
  * 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
@@ -65,7 +143,7 @@ export function lintCodexTool(payload, { scope = 'all' } = {}) {
       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. */ }
+    } catch (e) { if (e?.code !== 'ENOENT') debug('codex:lint', e); }
   }
   return messages.length ? messages.join('\n\n') : null;
 }
@@ -74,38 +152,55 @@ 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;
+    if (event === 'subagent-start') {
+      try { bindCodexSubagent(payload); } catch (e) { debug('codex:bind', e); }
+    }
     const root = findProjectRoot(payload.cwd || process.cwd(), { agent: 'codex' });
     const parts = [];
-    for (const scope of ['global', 'project']) {
-      const { ratchet } = codexHarnessPaths(root, scope);
+    // 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 (e) { debug('codex:preset', e); }
+    }
+    const { presetRatchetPath } = await import('./preset-ratchet.js');
+    // Lower priority survives the budget first. Rules and style move to a file
+    // when they do not fit; offers and notices are simply left out.
+    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.`);
+          parts.push({ priority: 1, text: `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();
-          if (text) parts.push(`[Sprag Codex ratchet: ${scope}]\n${text}`);
+          // 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({ priority: 1, spill: true, text: `[Sprag Codex ratchet: ${scope}]\n${text}` });
         }
-      } catch { /* No rules registered in this scope. */ }
+      } catch (e) { if (e?.code !== 'ENOENT') debug('codex:ratchet', e); }
     }
-    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({ priority: 0, text:
+      '[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.' });
+    parts.push({ priority: 2, spill: true, text: koreanStyleInjection({ cfg }) },
+      { priority: 3, spill: true, text: await cohesionInjection({ cfg }) });
+    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) parts.push({ priority: 4, spill: true, text: codexDocumentNote() });
+    // Offers ask the user a question; a `codex exec` run has no one to answer it.
+    if (event === 'session-start' && payload.source !== 'compact' && !isCodexExecSession(payload.transcript_path)) {
+      try { parts.push({ priority: 5, text: await routeNotice(root) }); } catch (e) { debug('codex:route-notice', e); }
+      try { parts.push({ priority: 6, text: seedOfferBlock({ root, agent: 'codex' }) }); } catch (e) { debug('codex:seed-offer', e); }
     }
-    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'));
+    return context(event === 'subagent-start' ? 'SubagentStart' : 'SessionStart',
+      fitCodexContext(parts, { overflowFile: overflowFileFor(root) }));
   }
   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. */ }
+      try {
+        parts.push(codexRouteHint(payload, { root: findProjectRoot(payload.cwd || process.cwd(), { agent: 'codex' }),
+          minContext: Number.isFinite(cfg?.codex?.delegateMinContext) ? cfg.codex.delegateMinContext : undefined }));
+      } catch (e) { debug('codex:route-hint', e); }
     }
     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. */ }
+      catch (e) { debug('codex:brief', e); }
     }
     if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) {
       parts.push(doc2md.contextForPrompt(payload, { lang: userLanguage(), agent: 'codex', convert: convertCodexDocument }));

package/src/codex-ledger.js

@@ -2,21 +2,30 @@ import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } fr
 import { join } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
 import { userDataDir } from './paths.js';
+import { roundUsd } from './savings-ledger.js';
 import { discoverCodexSessionFiles, parseCodexTurns } from './codex-parser.js';
-import { codexRunCost, readCodexPrices } from './codex-cache-policy.js';
+import { codexRunCost, codexPriceBook, 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.
+ * A child rollout only counts when Sprag itself routed it: either path writes
+ * a random route id and records the same id here at that moment, so the
+ * pending record (not the marker text a model could write by hand) is what
+ * shows a rule existed before the child ran. Two ways an id reaches a child:
+ *   - the PreToolUse spawn rewrite (codexDelegationTool) writes it into the
+ *     spawned message, for Codex versions that route spawn_agent through hooks;
+ *   - on versions that don't (0.159.2), the prompt hint (codexRouteHint) can
+ *     only ask the model to include the line, so SubagentStart binds the id to
+ *     whichever spawned child matches the pending record (bindCodexSubagent),
+ *     and refreshCodexLedger falls back to that binding when no marker is found.
  */
 
 export const ROUTE_ID_RE = /<!-- sprag:codex:route id=([0-9a-f]{16}) -->/;
 const PENDING_TTL_MS = 7 * 86400000;
+const BIND_TTL_MS = 30 * 60000;
 const pendingFile = (dir) => join(dir, 'codex-delegations.jsonl');
+const bindsFile = (dir) => join(dir, 'codex-delegation-binds.jsonl');
 const ledgerFile = (dir) => join(dir, 'codex-delegation-ledger.json');
 
 export function newRouteId() {
@@ -31,6 +40,21 @@ export function recordCodexDelegation(entry, { dir = userDataDir() } = {}) {
   appendFileSync(pendingFile(dir), line + '\n', { mode: 0o600 });
 }
 
+/**
+ * The pending file is append-only, so it only shrinks here: records past the
+ * pending TTL can never bind or join a child again. Rewritten in place through
+ * a rename, and only when something is actually stale.
+ */
+export function pruneCodexDelegations({ dir = userDataDir(), now = Date.now() } = {}) {
+  const keep = readCodexDelegations({ dir }).filter((r) => now - r.at < PENDING_TTL_MS);
+  let all;
+  try { all = readFileSync(pendingFile(dir), 'utf8').split('\n').filter(Boolean).length; } catch { return; }
+  if (keep.length === all) return;
+  const file = pendingFile(dir), tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, keep.map((r) => JSON.stringify(r) + '\n').join(''), { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
 export function readCodexDelegations({ dir = userDataDir() } = {}) {
   let text;
   try { text = readFileSync(pendingFile(dir), 'utf8'); } catch { return []; }
@@ -44,6 +68,45 @@ export function readCodexDelegations({ dir = userDataDir() } = {}) {
   return out;
 }
 
+/** One append per bind, mirroring recordCodexDelegation's append-only shape. */
+export function recordCodexBinding(entry, { dir = userDataDir() } = {}) {
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(bindsFile(dir), JSON.stringify(entry) + '\n', { mode: 0o600 });
+}
+
+export function readCodexBindings({ dir = userDataDir() } = {}) {
+  let text;
+  try { text = readFileSync(bindsFile(dir), 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    try {
+      const b = JSON.parse(line);
+      if (b && /^[0-9a-f]{16}$/.test(b.id) && typeof b.childSessionId === 'string' && Number.isFinite(b.at)) out.push(b);
+    } catch { /* Partial trailing line. */ }
+  }
+  return out;
+}
+
+/**
+ * Bind a just-spawned SubagentStart child to the pending route it most likely
+ * fulfills: same parent thread, same target model, recent enough, and not
+ * already claimed by another child. Returns the bound route id, or null when
+ * nothing matches or this child is already bound.
+ */
+export function bindCodexSubagent(payload, { dir = userDataDir(), now = Date.now() } = {}) {
+  if (typeof payload?.agent_id !== 'string' || typeof payload?.session_id !== 'string' || typeof payload?.model !== 'string') return null;
+  const binds = readCodexBindings({ dir });
+  if (binds.some((b) => b.childSessionId === payload.agent_id)) return null;
+  const boundIds = new Set(binds.map((b) => b.id));
+  const pending = readCodexDelegations({ dir }).filter((r) =>
+    r.parentSessionId === payload.session_id && r.to === payload.model && now - r.at < BIND_TTL_MS && !boundIds.has(r.id));
+  if (!pending.length) return null;
+  // Oldest first: spawns are recorded in order, so the earliest unbound record belongs to the earliest child.
+  const chosen = pending.reduce((a, b) => (b.at < a.at ? b : a));
+  recordCodexBinding({ id: chosen.id, childSessionId: payload.agent_id, at: now }, { dir });
+  return chosen.id;
+}
+
 export function loadCodexLedger({ dir = userDataDir() } = {}) {
   try {
     const data = JSON.parse(readFileSync(ledgerFile(dir), 'utf8'));
@@ -59,38 +122,50 @@ function saveLedger(data, dir) {
   renameSync(tmp, file);
 }
 
-/** The route id a child rollout carries, and its own tokens, or null. */
-async function childRun(path, cutoffMs) {
+/**
+ * The route id a child rollout carries, and its own tokens, or null. When no
+ * child turn carries the marker line (the prompt-hint path can only ask the
+ * model to write it, not guarantee it), `binds` — childSessionId -> id from
+ * SubagentStart — supplies the id instead.
+ */
+async function childRun(path, cutoffMs, binds) {
   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;
+  let calls = 0, toolErrors = 0;
+  let model = null, startedAt = null, endedAt = null, complete = false, aborted = 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;
+    calls += t.calls; toolErrors += t.errors;
     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; }
+    if (Number.isFinite(t.endedAt)) { endedAt = Math.max(endedAt ?? t.endedAt, t.endedAt); complete = !t.aborted; aborted = !!t.aborted; }
   }
+  if (!id && binds) id = binds.get(s.sessionId) ?? null;
   return id ? { id, sessionId: s.sessionId, parentThreadId: s.parentThreadId, provider: s.provider,
-    model, tokens, startedAt, endedAt, complete, usageKnown: usageKnown && !mixedModels } : null;
+    model, tokens, calls, toolErrors, startedAt, endedAt, complete, aborted, 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.
+ * shown as one rather than clamped away. A child that was interrupted before
+ * it finished replaced no parent work (the parent did the task itself), so its
+ * whole cost is booked as a loss.
  */
 export async function refreshCodexLedger({ dir = userDataDir(), home, now = Date.now(), prices = readCodexPrices({ now, home, dir }) } = {}) {
+  try { pruneCodexDelegations({ dir, now }); } catch { /* Pruning is housekeeping; the TTL filter below still holds. */ }
   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 bindMap = new Map(readCodexBindings({ dir }).filter((b) => byId.has(b.id)).map((b) => [b.childSessionId, b.id]));
   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;
@@ -98,7 +173,7 @@ export async function refreshCodexLedger({ dir = userDataDir(), home, now = Date
   for (const f of files.slice().reverse()) {
     if (f.mtime < oldest) continue;
     let run;
-    try { run = await childRun(f.path, oldest - 60000); } catch { continue; }
+    try { run = await childRun(f.path, oldest - 60000, bindMap); } 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;
@@ -110,15 +185,18 @@ export async function refreshCodexLedger({ dir = userDataDir(), home, now = Date
     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;
+    // Priced by the path the child took: OpenAI list for direct calls, the gateway's prices for LiteLLM.
+    const book = codexPriceBook(provider, prices, { home });
     const rates = sameRun && previous.rates ? previous.rates
-      : prices?.provider === provider ? { from: prices.prices[route.from], to: prices.prices[to], checkedAt: prices.checkedAt } : null;
+      : book ? { from: book.prices[route.from], to: book.prices[to], checkedAt: book.checkedAt } : null;
+    const priceSource = !rates ? null : sameRun && previous.rates ? previous.priceSource ?? null : book?.source ?? 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 usd = actual === null || counterfactual === null ? null : roundUsd(run.aborted ? -actual : 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 };
+      from: route.from, to, provider, tokens: run.tokens, calls: run.calls, toolErrors: run.toolErrors, usd, rates: usd === null ? null : rates,
+      priceCheckedAt: rates?.checkedAt ?? null, priceSource, complete: run.complete, ...(run.aborted ? { aborted: true } : {}) };
     // 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;