sprag-cli 3.55.0 → 3.57.0

package/src/codex-brief.js

@@ -1,10 +1,14 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync, renameSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { codexUserDir } from './agent.js';
 import { userDataDir } from './paths.js';
 import { readCodexSnapshot } from './codex-parser.js';
+import { loadCodexModelRules } from './codex-delegation.js';
+import { loadCodexLedger } from './codex-ledger.js';
+import { codexRulesInReview } from './codex-rule-health.js';
 
+const RESET_TOLERANCE_S = 300;
 const hash = (value) => createHash('sha256').update(value).digest('hex');
 const stateDir = (dir) => join(dir, 'codex', hash(codexUserDir()), 'sessions');
 const fresh = (value, now) => {
@@ -45,7 +49,7 @@ function readState(file) {
 }
 
 /** One file per home/session keeps unrelated sessions out of the same dedup state. */
-export function runCodexBrief({ sessionId, transcriptPath, cwd, now = Date.now(), dir = userDataDir() } = {}) {
+export function runCodexBrief({ sessionId, transcriptPath, cwd, root: projectRoot, now = Date.now(), dir = userDataDir() } = {}) {
   if (typeof sessionId !== 'string' || !sessionId) return null;
   const snapshot = readCodexSnapshot(transcriptPath);
   if (!snapshot || (snapshot.sessionId && snapshot.sessionId !== sessionId)) return null;
@@ -54,6 +58,35 @@ export function runCodexBrief({ sessionId, transcriptPath, cwd, now = Date.now()
   const file = join(directory, `${hash(sessionId)}.json`);
   const state = readState(file);
   const active = Array.isArray(state.active) ? state.active.filter((sig) => typeof sig === 'string') : [];
+  // Codex rewrites resets_at by about a second between records, so a limit
+  // already announced for the same window keeps its first signature.
+  for (const issue of issues) {
+    const m = /^limit:(primary|secondary):(\d+(?:\.\d+)?)$/.exec(issue.signature);
+    if (!m) continue;
+    const resetsAt = Number(m[2]);
+    const known = active.find((sig) => {
+      const k = /^limit:(primary|secondary):(\d+(?:\.\d+)?)$/.exec(sig);
+      return k && k[1] === m[1] && Math.abs(Number(k[2]) - resetsAt) <= RESET_TOLERANCE_S;
+    });
+    if (known) issue.signature = known;
+  }
+  // A failing model rule is announced once per session; the lines never block the other warnings.
+  try {
+    // The hook passes the project root its rule matching uses; a prompt sent from
+    // a subdirectory must still see the project's rules.
+    const root = resolve(projectRoot || cwd || snapshot.projectDir || '.');
+    const rules = loadCodexModelRules({ dir });
+    if (rules.length) {
+      const events = Object.values(loadCodexLedger({ dir }).events);
+      for (const { index, rule, health } of codexRulesInReview({ root, rules, events })) {
+        issues.push({ key: 'rule-health', tier: 1,
+          signature: `rule-health:${rule.scope}:${rule.targetRoot ?? ''}:${rule.category}:${rule.from}:${rule.model}:${rule.createdAt ?? ''}`,
+          level: 'warning',
+          message: `Codex model rule #${index} (${rule.category}, ${rule.from} -> ${rule.model}) failed ${health.errs} of ${health.runs} measured runs.`,
+          advice: `Narrow or remove it: sprag delegate rules rm ${index} --agent codex` });
+      }
+    }
+  } catch { /* An unreadable rule file or ledger only skips this line. */ }
   const next = issues.filter((issue) => !active.includes(issue.signature) &&
     !(issue.key === 'context' && issue.tier === 1 && active.includes('context:2')));
   // Missing or stale measurements do not resolve an earlier warning. A fresh
@@ -77,6 +110,26 @@ export function runCodexBrief({ sessionId, transcriptPath, cwd, now = Date.now()
   return next.length ? ['[Sprag Codex briefing]', ...next.map((issue) => `${issue.message} ${issue.advice}`)].join('\n') : null;
 }
 
+/**
+ * Append one event outside the warning dedup, such as a handoff the user
+ * wrote. Claude's history records handoffs too, so both agents' timelines
+ * show when work was preserved.
+ */
+export function recordCodexHistoryEvent({ sessionId, project = '', key, level = 'info', message, advice = '', now = Date.now(), dir = userDataDir() } = {}) {
+  if (typeof message !== 'string' || !message) return false;
+  const owner = typeof sessionId === 'string' && sessionId ? sessionId : 'no-session';
+  const directory = stateDir(dir);
+  const file = join(directory, `${hash(owner)}.json`);
+  const state = readState(file);
+  const events = [...state.events, { key, tier: 0, signature: key, level, message, advice,
+    at: new Date(now).toISOString(), sessionId: owner, project }].slice(-200);
+  mkdirSync(directory, { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ ...state, events }) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+  return true;
+}
+
 export function readCodexHistory({ days = 7, sessionId, project, dir = userDataDir(), now = Date.now() } = {}) {
   const directory = stateDir(dir);
   let files;

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 -->';
@@ -53,7 +54,10 @@ export function addCodexModelRule({ category, model, effort, from, scope, root,
   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);
+  // A rule saved without a provider has no `provider` key, and a caller with
+  // none passes null. Compared as they are, undefined !== null, so re-adding
+  // the same rule stacked a duplicate instead of replacing it.
+  const old = rules.findIndex((r) => r.category === category && r.from === from && r.scope === scope && r.targetRoot === targetRoot && (r.provider ?? null) === (provider ?? null));
   if (old < 0) rules.push(rule); else rules[old] = rule;
   saveRules(rules, dir);
   return rule;
@@ -88,13 +92,51 @@ 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,
+      targetRoot: rule.targetRoot ?? null, ruleCreatedAt: rule.createdAt ?? null }, { 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,7 +162,9 @@ function customRole(role, root, home) {
   return false;
 }
 
-export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd || process.cwd(), home = codexUserDir(), rules, dir = userDataDir(), record = recordCodexDelegation } = {}) {
+// 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: given, 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;
@@ -129,6 +173,9 @@ export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd ||
   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');
+  // An unreadable rule file must not stop the default target or the spawn itself.
+  let rules = given;
+  if (!rules) { try { rules = loadCodexModelRules({ dir }); } catch { rules = []; } }
   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);
@@ -144,7 +191,8 @@ export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd ||
       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 });
+          from: payload.model, to: target.model, provider, effort: updatedInput.reasoning_effort ?? null,
+          ...(rule ? { targetRoot: rule.targetRoot ?? null, ruleCreatedAt: rule.createdAt ?? null } : {}) }, { dir });
         routeLine = `\n<!-- sprag:codex:route id=${id} -->`;
       } catch { /* Accounting is optional; the route itself still applies. */ }
     }

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 -->';
@@ -14,16 +14,24 @@ const sections = [
   ['Default Safe Path', 'Ask before destructive or external actions unless already authorized. Proceed with reads, local edits, and tests within the granted permissions.'],
 ];
 
+const scopeDir = (root, scope) => (scope === 'global' ? codexUserDir() : root);
+
 export function codexHarnessPaths(root, scope = 'project') {
-  const dir = scope === 'global' ? codexUserDir() : root;
+  const dir = scopeDir(root, scope);
   // 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') };
 }
 
+/** Every instruction file of a scope that init may have written to, active or not. */
+function harnessFiles(root, scope) {
+  const dir = scopeDir(root, scope);
+  return [join(dir, 'AGENTS.override.md'), join(dir, 'AGENTS.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`;
+  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) {
@@ -40,8 +48,11 @@ export function initCodexHarness({ root, scope = 'project' }) {
   const existing = existsSync(paths.file) ? readFileSync(paths.file, 'utf8') : '';
   const span = range(existing);
   const block = codexHarnessBlock();
+  // Trailing newlines are dropped before the separator is added, so the gap
+  // above the block is always one blank line however the file ended.
+  const body = existing.replace(/\n+$/, '');
   const next = span ? existing.slice(0, span[0]) + block.trimEnd() + existing.slice(span[1])
-    : existing + (existing ? '\n\n' : '') + block;
+    : body + (body ? '\n\n' : '') + block;
   mkdirSync(dirname(paths.file), { recursive: true });
   if (next !== existing) {
     if (existing) writeFileSync(`${paths.file}.bak-${Date.now()}`, existing);
@@ -54,15 +65,38 @@ export function initCodexHarness({ root, scope = 'project' }) {
   return paths;
 }
 
+/**
+ * The file without the block, and without the blank lines init put around it.
+ * Cutting the block alone left those behind, so each install and uninstall
+ * added three more.
+ */
+function withoutBlock(text, [begin, end]) {
+  const before = text.slice(0, begin).replace(/\n+$/, '');
+  const after = text.slice(end).replace(/^\n+/, '');
+  if (!before) return after;
+  return after ? `${before}\n\n${after}` : `${before}\n`;
+}
+
+/**
+ * Removes the block from every file of the scope that holds one. The active
+ * file alone is not enough: init writes AGENTS.md, and an AGENTS.override.md
+ * created afterwards becomes the active file while the block stays in the
+ * other one, where a later uninit never looked.
+ */
 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 };
+  const cleaned = [];
+  for (const candidate of harnessFiles(root, scope)) {
+    if (!existsSync(candidate)) continue;
+    const existing = readFileSync(candidate, 'utf8');
+    const span = range(existing);
+    if (!span) continue;
+    writeFileSync(`${candidate}.bak-${Date.now()}`, existing);
+    writeFileSync(candidate, withoutBlock(existing, span));
+    cleaned.push(candidate);
+  }
+  if (!cleaned.length) return { file, removed: false };
+  return { file: cleaned.includes(file) ? file : cleaned[0], removed: true, ...(cleaned.length > 1 ? { files: cleaned } : {}) };
 }
 
 export function codexHarnessStatus({ root, scope = 'project' }) {
@@ -133,11 +167,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 +178,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 +212,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++;