sprag-cli 3.53.0 → 3.54.0

package/src/doc2md.cjs

@@ -182,7 +182,7 @@ function banner(sourcePath, saving) {
   return lines.join('\n');
 }
 
-function writeCache(filePath, markdown, extra) {
+function writeCache(filePath, markdown, extra, { agent } = {}) {
   ensureCacheDir();
   const cacheFile = cachePathFor(filePath);
   const src = fs.statSync(filePath);
@@ -197,7 +197,7 @@ function writeCache(filePath, markdown, extra) {
     { markdown },
   );
   fs.writeFileSync(cacheFile, banner(filePath, saving) + markdown, { encoding: 'utf8', mode: 0o600 });
-  ledger.recordConversion(userDataDir(), {
+  if (agent !== 'codex') ledger.recordConversion(userDataDir(), {
     key: path.resolve(filePath),
     ts: Date.now(),
     usd: saving.usd,
@@ -447,7 +447,7 @@ function spawnFigConvert(fig2md, filePath) {
   }
 }
 
-function convert(filePath, { converter = CONVERTER, python: pythonOverride = null } = {}) {
+function convert(filePath, { converter = CONVERTER, python: pythonOverride = null, agent } = {}) {
   if (!isTargetPath(filePath)) return { ok: false, reason: 'not-target' };
   if (isSensitivePath(filePath)) return { ok: false, reason: 'sensitive' };
 
@@ -478,7 +478,7 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
     if (!result.ok) return result;
     const written = writeCache(filePath, result.markdown, {
       note: result.note, truncated: false, rows: 0, pages: 0, markupBytes: 0,
-    });
+    }, { agent });
     return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
   }
 
@@ -537,7 +537,7 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
     pages: payload.pages || 0,
     markupBytes: payload.markup_bytes || 0,
     clipped,
-  });
+  }, { agent });
   return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
 }
 
@@ -763,19 +763,38 @@ function decideForRead(context, opts = {}) {
  * Quoted, `@`-prefixed and bare paths all count. Windows drive letters are
  * matched too, since the rest of the module is path-agnostic.
  */
-function documentPathsIn(text) {
+function documentPathsIn(text, cwd = process.cwd()) {
   if (typeof text !== 'string' || !text) return [];
   const exts = TARGET_EXTENSIONS.map((e) => e.slice(1)).join('|');
   // Backslashes count as path characters, not just separators to tolerate:
   // `C:\\Users\\me\\deck.pptx` and `\\\\server\\share\\deck.pptx` are how
   // Windows users write a path, and without them the scanner silently sees no
   // documents at all on that platform.
-  const re = new RegExp(`[@'"\`]?((?:[A-Za-z]:)?[~./\\\\][^\\s'"\`]*\\.(?:${exts}))`, 'gi');
+  //
+  // The extension may be followed by anything except more of a filename, so
+  // `deck.pptx를` and `(./a.pdf)` still count while `a.pdfx` does not. Korean
+  // attaches a particle straight to the path, and a whitelist of punctuation
+  // after the extension silently dropped every such prompt.
+  const tail = '(?![A-Za-z0-9_])';
+  const forms = [
+    // A path that starts like one (`~`, `.`, `/`, `\`, a drive letter), found
+    // anywhere in the text. This is the original scanner, kept whole so that a
+    // new form can only add paths, never lose one it used to find.
+    new RegExp(`((?:[A-Za-z]:)?[~./\\\\][^\\s'"\x60]*\\.(?:${exts}))${tail}`, 'gi'),
+    // A quoted path, which may contain spaces and needs no leading `./`.
+    new RegExp(`["'\x60]([^"'\x60]+\\.(?:${exts}))["'\x60]`, 'gi'),
+    // A bare name such as `book.pdf` or `docs/a.pdf`, starting a word. An
+    // opening bracket or an `@` is a word boundary, not part of the name.
+    new RegExp(`(?:^|[\\s@(\\[{<])([^\\s'"\x60()\\[\\]{}<>@][^\\s'"\x60]*\\.(?:${exts}))${tail}`, 'gi'),
+  ];
   const found = [];
-  for (const m of text.matchAll(re)) {
-    const raw = m[1];
-    const abs = raw.startsWith('~') ? path.join(os.homedir(), raw.slice(1)) : path.resolve(raw);
-    if (!found.includes(abs)) found.push(abs);
+  for (const re of forms) {
+    for (const m of text.matchAll(re)) {
+      const raw = m[1];
+      if (raw.includes('://')) continue;
+      const abs = raw.startsWith('~') ? path.join(os.homedir(), raw.slice(1)) : path.resolve(cwd, raw);
+      if (!found.includes(abs)) found.push(abs);
+    }
   }
   return found;
 }
@@ -812,25 +831,30 @@ function conversionSummary(sourcePath, meta = {}) {
 function contextForPrompt(payload, opts = {}) {
   const lang = opts.lang === 'ko' ? 'ko' : 'en';
   if (!payload || typeof payload.prompt !== 'string') return null;
-  const paths = documentPathsIn(payload.prompt).filter((p) => {
+  const paths = documentPathsIn(payload.prompt, payload.cwd || process.cwd()).filter((p) => {
     try { return fs.statSync(p).isFile(); } catch { return false; }
   });
   if (paths.length === 0) return null;
 
   const lines = [];
   const targets = paths.slice(0, MAX_PROMPT_CONVERSIONS);
+  const { convert: convertFn = convert, ...convertOptions } = opts;
   for (const p of targets) {
     const name = path.basename(p);
-    const result = convert(p, opts);
+    const result = convertFn(p, convertOptions);
     if (result.ok) {
       lines.push(`  ${name} → ${result.cacheFile}`);
-      lines.push(`      ${conversionSummary(p, result.meta)}`);
+      lines.push(`      ${conversionSummary(p, opts.agent === 'codex' ? { ...result.meta, savedUsd: 0 } : result.meta)}`);
       if (result.meta && result.meta.note) lines.push(`      ${result.meta.note}`);
-      if (result.meta && result.meta.clipped) {
+      if (opts.agent === 'codex' && (result.meta?.clipped || result.meta?.truncated)) {
+        lines.push('      Text extraction is incomplete; inspect the source for omitted content.');
+      } else if (result.meta && result.meta.clipped) {
         lines.push('      변환 결과가 너무 커서 뒷부분을 잘랐습니다. 전체가 필요하면 원본을 직접 다루십시오.');
       }
     } else if (result.reason === 'no-markitdown') {
-      lines.push(lang === 'ko'
+      lines.push(opts.agent === 'codex'
+        ? `  ${name}: converter unavailable. Run sprag doc2md install-converter --agent codex, then retry.`
+        : lang === 'ko'
         ? `  ${name}: 변환기를 설치하는 중입니다(첫 실행에만 걸립니다). 설치가 끝나면 다음 요청부터 자동 변환됩니다.`
         : `  ${name}: the converter is installing now (first run only). It will convert automatically from the next request.`);
     } else if (result.reason === 'drm-protected') {
@@ -865,6 +889,12 @@ function contextForPrompt(payload, opts = {}) {
       : `  (converted the first ${targets.length} of ${paths.length} documents; run \`sprag doc2md <path>\` for the rest.)`);
   }
 
+  if (opts.agent === 'codex') return [
+    '[doc2md] Document conversion results:', ...lines,
+    'Read each successfully converted Markdown file instead of extracting the original document again.',
+    'Report conversion failures accurately. For successful conversions, mention the source and Markdown sizes.',
+    'For other documents, run sprag doc2md <path> --agent codex. Text extraction does not verify images or layout.',
+  ].join('\n');
   return lang === 'ko'
     ? [
       '[doc2md] 이 프롬프트에 문서 경로가 있어 Markdown 으로 변환해 두었습니다.',
@@ -919,12 +949,13 @@ function sessionNote(lang = 'en') {
  * .fig overwritten with text is destroyed, not edited. Nothing this tool
  * ships can write those formats back.
  */
-function decideForWrite(context) {
+function decideForWrite(context, opts = {}) {
   if (!context || (context.tool_name !== 'Edit' && context.tool_name !== 'Write')) return null;
   const toolInput = context.tool_input;
   const filePath = toolInput && typeof toolInput.file_path === 'string' ? toolInput.file_path : '';
   if (!filePath) return null;
   const abs = path.resolve(filePath);
+  const codex = opts.agent === 'codex';
 
   if (abs.startsWith(cacheDir() + path.sep)) {
     let source = null;
@@ -933,23 +964,36 @@ function decideForWrite(context) {
     } catch { /* the deny stands on its own */ }
     return {
       deny: true,
-      reason: '[doc2md] 이 파일은 변환 캐시입니다. 여기를 고쳐도 원본 문서에는 아무것도 반영되지 않고, '
-        + '캐시만 오염된 채 다음 읽기부터 계속 서빙됩니다.\n'
-        + (source ? `  원본: ${source}\n` : '')
-        + '  문서 수정이 목적이라면: 원본을 복사한 뒤(cp) 복사본을 스크립트로 수정하십시오. '
-        + `pptx·docx·xlsx 는 ${managedPython()} 에 python-pptx·python-docx·openpyxl 이 설치되어 있고, `
-        + '.fig 는 doc2md-fig 의 openfig-core 로 편집·재인코드할 수 있습니다. '
-        + '수정 후 복사본을 `sprag doc2md <복사본>` 으로 재변환해 의도한 변경이 들어갔는지 확인하십시오. 원본은 절대 직접 수정하지 마십시오.',
+      reason: codex
+        ? '[doc2md] This file is a conversion cache. Editing it changes nothing in the source document; '
+          + 'it only corrupts the cache, which keeps being served on every later read.\n'
+          + (source ? `  Source: ${source}\n` : '')
+          + '  To modify the document instead: copy the original, then edit the copy with a script. '
+          + `pptx/docx/xlsx have python-pptx/python-docx/openpyxl installed under ${managedPython()}, `
+          + "and .fig edits go through doc2md-fig's openfig-core. "
+          + 'After editing, reconvert the copy with `sprag doc2md <copy> --agent codex` to verify the change landed. Never edit the original directly.'
+        : '[doc2md] 이 파일은 변환 캐시입니다. 여기를 고쳐도 원본 문서에는 아무것도 반영되지 않고, '
+          + '캐시만 오염된 채 다음 읽기부터 계속 서빙됩니다.\n'
+          + (source ? `  원본: ${source}\n` : '')
+          + '  문서 수정이 목적이라면: 원본을 복사한 뒤(cp) 복사본을 스크립트로 수정하십시오. '
+          + `pptx·docx·xlsx 는 ${managedPython()} 에 python-pptx·python-docx·openpyxl 이 설치되어 있고, `
+          + '.fig 는 doc2md-fig 의 openfig-core 로 편집·재인코드할 수 있습니다. '
+          + '수정 후 복사본을 `sprag doc2md <복사본>` 으로 재변환해 의도한 변경이 들어갔는지 확인하십시오. 원본은 절대 직접 수정하지 마십시오.',
     };
   }
 
   if (isTargetPath(abs)) {
     return {
       deny: true,
-      reason: `[doc2md] ${path.basename(abs)} 는 이진 문서입니다. Edit/Write 는 텍스트를 쓰므로 이 파일을 파괴합니다. `
-        + '수정하려면 원본을 복사한 뒤(cp) 복사본을 스크립트로 고치십시오. '
-        + `pptx·docx·xlsx 는 ${managedPython()} 의 python-pptx·python-docx·openpyxl, .fig 는 openfig-core 를 쓰고, `
-        + '수정 후 `sprag doc2md <복사본>` 재변환으로 결과를 검증하십시오.',
+      reason: codex
+        ? `[doc2md] ${path.basename(abs)} is a binary document. Edit/Write emit text, so this call would destroy it. `
+          + 'To modify it, copy the original, then edit the copy with a script. '
+          + `pptx/docx/xlsx use python-pptx/python-docx/openpyxl under ${managedPython()}, and .fig uses openfig-core. `
+          + 'After editing, reconvert with `sprag doc2md <copy> --agent codex` to verify the change landed.'
+        : `[doc2md] ${path.basename(abs)} 는 이진 문서입니다. Edit/Write 는 텍스트를 쓰므로 이 파일을 파괴합니다. `
+          + '수정하려면 원본을 복사한 뒤(cp) 복사본을 스크립트로 고치십시오. '
+          + `pptx·docx·xlsx 는 ${managedPython()} 의 python-pptx·python-docx·openpyxl, .fig 는 openfig-core 를 쓰고, `
+          + '수정 후 `sprag doc2md <복사본>` 재변환으로 결과를 검증하십시오.',
     };
   }
   return null;

package/src/handoff.js

@@ -66,11 +66,11 @@ function pickPath(cwd, now) {
   return join(cwd, `${stem}-${Date.now()}.md`);
 }
 
-function renderTemplate({ now, cwd, git, caps }) {
+function renderTemplate({ now, cwd, git, caps, agent, session }) {
   const lines = [];
   lines.push(`# Handoff — ${ymd(now)} ${pad(now.getHours())}:${pad(now.getMinutes())}`);
   lines.push('');
-  lines.push(`Generated by \`sprag handoff\`.`);
+  lines.push(`Generated by \`sprag handoff${agent === 'codex' ? ' --agent codex' : ''}\`.`);
   lines.push('');
   lines.push('## Context');
   lines.push('');
@@ -92,7 +92,27 @@ function renderTemplate({ now, cwd, git, caps }) {
 
   lines.push('## Cap snapshot');
   lines.push('');
-  if (caps && Array.isArray(caps.windows) && caps.windows.length > 0) {
+  if (agent === 'codex') {
+    lines.push('- Source: recorded Codex rollout, not a live quota or billing response.');
+    if (session) {
+      lines.push(`- Session: ${JSON.stringify(session.sessionId)}`);
+      lines.push(`- Model: ${JSON.stringify(session.model)}; effort: ${JSON.stringify(session.effort)}`);
+      lines.push(`- Last activity: ${session.lastActivity ? new Date(session.lastActivity).toISOString() : 'unknown'}`);
+      lines.push(`- Recorded input context: ${session.lastContextTokens ?? 'unknown'} / ${session.contextWindow ?? 'unknown'} tokens`);
+      lines.push(`- Tokens: input ${session.totals.input + session.totals.cacheRead}, cached ${session.totals.cacheRead}, output ${session.totals.output}`);
+      lines.push(`- Limits snapshot: ${session.rateLimitsAt ? new Date(session.rateLimitsAt).toISOString() : 'not reported'}`);
+      for (const key of ['primary', 'secondary']) {
+        const win = session.rateLimits?.[key];
+        if (!Number.isFinite(win?.used_percent)) continue;
+        const reset = Number.isFinite(win.resets_at) ? win.resets_at * 1000 : null;
+        const resetDate = reset === null ? null : new Date(reset);
+        const resetText = resetDate && Number.isFinite(resetDate.getTime())
+          ? reset <= now.getTime() ? 'awaiting new usage' : `reset at ${resetDate.toISOString()}` : 'reset unknown';
+        lines.push(`- ${key}: ${win.used_percent}% used (${resetText})`);
+      }
+    } else lines.push('- No matching Codex session log.');
+    lines.push('- Cost and cache TTL: unavailable.');
+  } else if (caps && Array.isArray(caps.windows) && caps.windows.length > 0) {
     for (const win of caps.windows) {
       const label = labelForKey(win.key).long;
       if (!Number.isFinite(win.usedPct)) {
@@ -132,7 +152,7 @@ function renderTemplate({ now, cwd, git, caps }) {
   lines.push('- _(non-obvious gotchas, half-finished refactors, failing tests)_');
   lines.push('');
 
-  lines.push('## Resume prompt for the next Claude Code session');
+  lines.push(`## Resume prompt for the next ${agent === 'codex' ? 'Codex' : 'Claude Code'} session`);
   lines.push('');
   lines.push('```');
   lines.push('Read the most recent HANDOFF-*.md in this directory and continue the work.');
@@ -151,11 +171,11 @@ function renderTemplate({ now, cwd, git, caps }) {
  * @param {Date} [opts.now=new Date()]
  * @returns {{ path: string, git: { branch: string, head: string, status: string } | null }}
  */
-export function writeHandoff({ cwd = process.cwd(), caps = null, now = new Date() } = {}) {
+export function writeHandoff({ cwd = process.cwd(), caps = null, now = new Date(), agent = 'claude', session = null } = {}) {
   const absCwd = resolve(cwd);
   const git = gitSnapshot(absCwd);
   const path = pickPath(absCwd, now);
-  const body = renderTemplate({ now, cwd: absCwd, git, caps });
-  writeFileSync(path, body);
+  const body = renderTemplate({ now, cwd: absCwd, git, caps, agent, session });
+  writeFileSync(path, body, { flag: 'wx' });
   return { path, git };
 }

package/src/harness.js

@@ -26,6 +26,7 @@ import { routeWarningForStatusline } from './route-scan.js';
 import { ruleHealthWarningForStatusline, modelRatchetPathFor, renderModelRatchet } from './model-rules.js';
 import { compactWindowWarningForStatusline } from './compact-window.js';
 import { userLanguage } from './config.js';
+import { codexUserDir } from './agent.js';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -42,11 +43,13 @@ function readHarnessState() {
  * or package.json). Falls back to `start` itself so harness commands always
  * have *some* directory to write into, even outside a repo.
  */
-export function findProjectRoot(start = process.cwd()) {
+export function findProjectRoot(start = process.cwd(), { agent = 'claude' } = {}) {
   let dir = resolve(start);
   for (;;) {
     if (
-      existsSync(join(dir, 'CLAUDE.md')) ||
+      (agent === 'codex'
+        ? existsSync(join(dir, 'AGENTS.md')) || existsSync(join(dir, 'AGENTS.override.md'))
+        : existsSync(join(dir, 'CLAUDE.md'))) ||
       existsSync(join(dir, '.git')) ||
       existsSync(join(dir, 'package.json'))
     ) {
@@ -70,10 +73,15 @@ function globalRatchetMdPath() {
   return join(homedir(), '.claude', 'ratchet.md');
 }
 
-function resolveRatchetPath(scope, root) {
+function resolveRatchetPath(scope, root, agent = 'claude') {
+  if (agent === 'codex') return scope === 'global' ? join(codexUserDir(), 'ratchet.md') : join(root, '.codex', 'ratchet.md');
   return scope === 'global' ? globalRatchetMdPath() : ratchetMdPath(root);
 }
 
+function initialRatchet(agent) {
+  return agent === 'codex' ? '# Codex Ratchet Rules\n\n## Rules\n\n' : harnessRatchetMdInitial();
+}
+
 // Global harness lives in ~/.claude/CLAUDE.md — Claude Code loads this for every
 // project, so a global init makes the 5 harness sections apply everywhere
 // (mirrors the project/global split that ratchet.md already has).
@@ -312,14 +320,14 @@ export function harnessUninit({ root = findProjectRoot(), purgeRatchet = false,
  * harness promote — append a one-line rule to .claude/ratchet.md.
  * Creates the file from the initial template if missing.
  */
-export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'project' } = {}) {
-  const rmPath = resolveRatchetPath(scope, root);
+export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'project', agent = 'claude' } = {}) {
+  const rmPath = resolveRatchetPath(scope, root, agent);
   let existing = '';
   if (existsSync(rmPath)) {
     existing = readFileSync(rmPath, 'utf8');
   } else {
     mkdirSync(dirname(rmPath), { recursive: true });
-    existing = harnessRatchetMdInitial();
+    existing = initialRatchet(agent);
   }
   const next = appendRatchetRule(existing, ruleText);
   writeFileSync(rmPath, next);
@@ -339,17 +347,17 @@ export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'pr
  * Deduped by rule text (ignoring the YYYY-MM-DD stamp) — idempotent.
  * Returns { path, scope, added, skippedRules, presets }.
  */
-export function harnessPull({ root = findProjectRoot(), scope = 'global' } = {}) {
+export function harnessPull({ root = findProjectRoot(), scope = 'global', agent = 'claude' } = {}) {
   const presets = presetRules();
-  const rmPath = resolveRatchetPath(scope, root);
+  const rmPath = resolveRatchetPath(scope, root, agent);
   const result = { path: rmPath, scope, added: [], skippedRules: 0, presets: presets.length };
   const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}:\s*/, '').trim();
 
   let content = existsSync(rmPath)
     ? readFileSync(rmPath, 'utf8')
-    : harnessRatchetMdInitial();
+    : initialRatchet(agent);
   const have = new Set(
-    harnessListRules({ root, scope }).rules.map((r) => stripDate(r.text)),
+    harnessListRules({ root, scope, agent }).rules.map((r) => stripDate(r.text)),
   );
   for (const rule of presets) {
     if (have.has(rule)) {
@@ -385,7 +393,8 @@ export function presetRuleEntries() {
     const data = JSON.parse(readFileSync(path, 'utf8'));
     return (Array.isArray(data.rules) ? data.rules : [])
       .filter((r) => r && typeof r.ko === 'string' && r.ko.trim())
-      .map((r) => ({ ko: r.ko.trim(), en: (r.en || r.ko).trim() }));
+      .map((r) => ({ ko: r.ko.trim(), en: (r.en || r.ko).trim(),
+        ...(Array.isArray(r.agents) ? { agents: r.agents.filter((a) => typeof a === 'string') } : {}) }));
   } catch {
     return [];
   }
@@ -400,8 +409,8 @@ export function presetRules(lang = userLanguage()) {
  * harness list — return numbered ratchet rules from .claude/ratchet.md.
  * Numbering is 1-based and matches `harness rm <N>`.
  */
-export function harnessListRules({ root = findProjectRoot(), scope = 'project' } = {}) {
-  const rmPath = resolveRatchetPath(scope, root);
+export function harnessListRules({ root = findProjectRoot(), scope = 'project', agent = 'claude' } = {}) {
+  const rmPath = resolveRatchetPath(scope, root, agent);
   if (!existsSync(rmPath)) return { path: rmPath, rules: [] };
   const lines = readFileSync(rmPath, 'utf8').split('\n');
   const rules = [];
@@ -482,8 +491,8 @@ export function contextWeightStatus({ root = findProjectRoot() } = {}) {
  * it. Selection is by tag and/or age; nothing is deleted, so a pruned rule can
  * be pasted back. Returns the pruned rules for the CLI to echo.
  */
-export function harnessPrune({ root = findProjectRoot(), scope = 'project', tag = null, olderThanMonths = null, dryRun = false } = {}) {
-  const { path: rmPath, rules } = harnessListRules({ root, scope });
+export function harnessPrune({ root = findProjectRoot(), scope = 'project', agent = 'claude', tag = null, olderThanMonths = null, dryRun = false } = {}) {
+  const { path: rmPath, rules } = harnessListRules({ root, scope, agent });
   if (!existsSync(rmPath)) return { ok: false, error: `ratchet.md not found at ${rmPath}` };
   if (!tag && !olderThanMonths) return { ok: false, error: 'Nothing selected — pass --tag <t> and/or --older-than <months>' };
   const cutoff = olderThanMonths ? Date.now() - olderThanMonths * 30 * 24 * 60 * 60 * 1000 : null;
@@ -519,8 +528,8 @@ export function harnessPrune({ root = findProjectRoot(), scope = 'project', tag
  * value is one-way accumulation; deleting should feel deliberate. The CLI
  * surfaces a "narrow the condition instead" reminder around this call.
  */
-export function harnessRmRule(n, { root = findProjectRoot(), scope = 'project' } = {}) {
-  const { path: rmPath, rules } = harnessListRules({ root, scope });
+export function harnessRmRule(n, { root = findProjectRoot(), scope = 'project', agent = 'claude' } = {}) {
+  const { path: rmPath, rules } = harnessListRules({ root, scope, agent });
   if (!existsSync(rmPath)) {
     return { ok: false, error: `ratchet.md not found at ${rmPath}` };
   }

package/src/seed-rules.js

@@ -46,23 +46,25 @@ import {
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 
-export function seedStatePath() {
-  return join(userDataDir(), 'seed-state.json');
+// Codex answers are kept apart: saying no in one agent must not consume the
+// other agent's offer, and the two agents write to different ratchet files.
+export function seedStatePath({ agent = 'claude' } = {}) {
+  return join(userDataDir(), agent === 'codex' ? 'codex-seed-state.json' : 'seed-state.json');
 }
 
-export function loadSeedState() {
+export function loadSeedState(opts = {}) {
   try {
-    const data = JSON.parse(readFileSync(seedStatePath(), 'utf8'));
+    const data = JSON.parse(readFileSync(seedStatePath(opts), 'utf8'));
     return data && typeof data.decided === 'object' && data.decided ? data : { decided: {} };
   } catch {
     return { decided: {} };
   }
 }
 
-export function saveSeedState(state) {
+export function saveSeedState(state, opts = {}) {
   const dir = userDataDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(seedStatePath(), JSON.stringify(state, null, 2) + '\n');
+  writeFileSync(seedStatePath(opts), JSON.stringify(state, null, 2) + '\n');
 }
 
 /** Bundled tier-delegation presets (empty array when the file is unreadable). */
@@ -80,15 +82,19 @@ export function modelPresets() {
  * ids would renumber the moment a rule is inserted above them, silently moving
  * a user's "no" onto a different rule.
  */
-export function ratchetPresets(lang = userLanguage()) {
-  return presetRuleEntries().map((r) => ({
-    // Hashed from the Korean text in both languages: the id has to survive a
-    // reworded translation, or a user who declined a rule would be asked again
-    // the next time its English copy changes.
-    id: `fix-${createHash('sha1').update(r.ko).digest('hex').slice(0, 6)}`,
-    text: lang === 'ko' ? r.ko : r.en,
-    ko: r.ko,
-  }));
+export function ratchetPresets(lang = userLanguage(), { agent = 'claude' } = {}) {
+  return presetRuleEntries()
+    // A preset without `agents` applies everywhere; one naming Claude model
+    // tiers would only mislead a Codex session.
+    .filter((r) => !r.agents || r.agents.includes(agent))
+    .map((r) => ({
+      // Hashed from the Korean text in both languages: the id has to survive a
+      // reworded translation, or a user who declined a rule would be asked again
+      // the next time its English copy changes.
+      id: `fix-${createHash('sha1').update(r.ko).digest('hex').slice(0, 6)}`,
+      text: lang === 'ko' ? r.ko : r.en,
+      ko: r.ko,
+    }));
 }
 
 const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}(\s*\([^)]*\))?:\s*/, '').trim();
@@ -102,9 +108,11 @@ const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}(\s*\([^)]*\))?:\s*/, '').
  * whose own route-scan already promoted that shape does not need ours, and
  * offering it anyway would read as the tool failing to notice its own state.
  */
-export function pendingSeeds({ lang = userLanguage(), root = findProjectRoot() } = {}) {
-  const { decided } = loadSeedState();
-  const registered = (() => {
+export function pendingSeeds({ lang = userLanguage(), root = findProjectRoot(), agent = 'claude' } = {}) {
+  const { decided } = loadSeedState({ agent });
+  // Codex model routing comes from its own measured route-scan candidates;
+  // Claude tier presets name models Codex does not run.
+  const registered = agent === 'codex' ? [] : (() => {
     try {
       return loadModelRules().rules;
     } catch {
@@ -116,12 +124,12 @@ export function pendingSeeds({ lang = userLanguage(), root = findProjectRoot() }
   const haveText = new Set();
   for (const scope of ['global', 'project']) {
     try {
-      for (const r of harnessListRules({ root, scope }).rules) haveText.add(stripDate(r.text));
+      for (const r of harnessListRules({ root, scope, agent }).rules) haveText.add(stripDate(r.text));
     } catch { /* a missing ratchet file just means nothing is registered yet */ }
   }
 
   const out = [];
-  for (const p of modelPresets()) {
+  for (const p of agent === 'codex' ? [] : modelPresets()) {
     if (decided[p.id]) continue;
     if (haveModel.has(`${p.tier}|${p.category}`)) continue;
     out.push({
@@ -134,7 +142,7 @@ export function pendingSeeds({ lang = userLanguage(), root = findProjectRoot() }
       preset: p,
     });
   }
-  for (const p of ratchetPresets(lang)) {
+  for (const p of ratchetPresets(lang, { agent })) {
     if (decided[p.id]) continue;
     // Either language counts as already registered: `harness pull` may have
     // written the other one.
@@ -149,10 +157,10 @@ export function findSeed(id, opts = {}) {
   return pendingSeeds(opts).find((s) => s.id === id) || null;
 }
 
-function recordDecision(id, action, extra = {}) {
-  const state = loadSeedState();
+function recordDecision(id, action, extra = {}, { agent = 'claude' } = {}) {
+  const state = loadSeedState({ agent });
   state.decided[id] = { action, at: new Date().toISOString().slice(0, 10), ...extra };
-  saveSeedState(state);
+  saveSeedState(state, { agent });
 }
 
 /**
@@ -162,13 +170,15 @@ function recordDecision(id, action, extra = {}) {
  *
  * Returns { id, kind, scope, path?, rule } or null when the id is not pending.
  */
-export async function acceptSeed(id, { scope = 'global', root = findProjectRoot(), lang = userLanguage() } = {}) {
-  const seed = findSeed(id, { lang, root });
+export async function acceptSeed(id, { scope, root = findProjectRoot(), lang = userLanguage(), agent = 'claude' } = {}) {
+  // No default: a rule in the wrong scope is noise everywhere or missing where it mattered.
+  if (scope !== 'global' && scope !== 'project') throw new Error('acceptSeed needs an explicit scope: global or project');
+  const seed = findSeed(id, { lang, root, agent });
   if (!seed) return null;
 
   if (seed.kind === 'ratchet') {
-    const res = harnessPromote(seed.ruleText, { root, scope });
-    recordDecision(id, 'accepted', { scope });
+    const res = harnessPromote(seed.ruleText, { root, scope, agent });
+    recordDecision(id, 'accepted', { scope }, { agent });
     return { id, kind: 'ratchet', scope, path: res.path, rule: seed.ruleText };
   }
 
@@ -216,15 +226,15 @@ export async function acceptSeed(id, { scope = 'global', root = findProjectRoot(
 export function skipSeed(id, opts = {}) {
   const seed = findSeed(id, opts);
   if (!seed) return null;
-  recordDecision(id, 'skipped');
+  recordDecision(id, 'skipped', {}, { agent: opts.agent });
   return { id, kind: seed.kind, rule: seed.ruleText };
 }
 
 /** Forget every recorded answer — the full set becomes pending again. */
-export function resetSeeds() {
-  const state = loadSeedState();
+export function resetSeeds({ agent = 'claude' } = {}) {
+  const state = loadSeedState({ agent });
   const count = Object.keys(state.decided).length;
-  saveSeedState({ decided: {} });
+  saveSeedState({ decided: {} }, { agent });
   return count;
 }
 
@@ -236,9 +246,23 @@ export function resetSeeds() {
  * asked for, and because a single "register all of these?" question invites a
  * yes to rules the user never read.
  */
-export function seedOfferBlock({ lang = userLanguage(), root = findProjectRoot() } = {}) {
-  const pending = pendingSeeds({ lang, root });
+export function seedOfferBlock({ lang = userLanguage(), root = findProjectRoot(), agent = 'claude' } = {}) {
+  const pending = pendingSeeds({ lang, root, agent });
   if (pending.length === 0) return null;
+  if (agent === 'codex') {
+    // Codex hook text stays English; the rule text itself follows the user's language.
+    const cmd = (s) => `${CLI_NAME} seed ${s} --agent codex`;
+    return [
+      `[Sprag seed] ${pending.length} recommended Codex ratchet rule(s) from the bundled presets are not registered yet.`,
+      'Ask in your first reply, after answering any request the user opened with. Offer these choices in this order:',
+      `  1. Register all, globally: ${cmd('accept all --global')}`,
+      `  2. Register all, this project only: ${cmd('accept all --project')}`,
+      '  3. Decide one at a time: ask about each rule below and run its command as soon as they answer',
+      `  4. Register none: ${cmd('skip all')} (never offered again)`,
+      'Always confirm the scope with the user before running an accept command.',
+      ...pending.map((s) => `  [${s.id}] ${s.ruleText}`),
+    ].join('\n');
+  }
   const models = pending.filter((s) => s.kind === 'model');
   const fixes = pending.filter((s) => s.kind === 'ratchet');
   const lines = [];

package/src/update-check.js

@@ -266,16 +266,51 @@ export function releaseHighlights(body, lang = 'en') {
   return out;
 }
 
+/**
+ * The releases endpoint for one version, or a throw.
+ *
+ * The version that arrives here came out of a registry response rather than out
+ * of this process, so it is checked rather than trusted: a value carrying a
+ * slash or a scheme would otherwise have a say in which URL this function
+ * requests. Two checks are needed, because either one alone leaves a gap. The
+ * shape test rejects anything that is not a version, and the prefix test runs
+ * against the parsed URL rather than against the string it was built from,
+ * because `new URL` has collapsed `../` segments by that point and the same
+ * test on the raw string would pass a value that walks back out of the path.
+ * The origin is a constant either way, so no input can move the request to
+ * another host; this states that guarantee in code instead of leaving it
+ * implied.
+ */
+function releaseTagUrl(version) {
+  const tag = String(version);
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(tag)) {
+    throw new Error(`refusing to request notes for ${JSON.stringify(tag)}: not a version`);
+  }
+  const url = new URL(`${RELEASES_API}/v${tag}`);
+  if (!url.href.startsWith(`${RELEASES_API}/`)) {
+    throw new Error(`refusing to request ${url.href}: outside ${RELEASES_API}`);
+  }
+  return url;
+}
+
 /**
  * Fetch the highlights for one version. Returns [] on any failure: the notice
  * is worth showing with a bare version number, so a missing release, a rate
- * limit, or an offline machine must not cost the user the notice itself.
+ * limit, or an offline machine must not cost the user the notice itself. A
+ * version that fails the endpoint check above lands in that same place: no
+ * highlights, and the notice still goes out.
  */
 export async function fetchHighlights(version, { timeoutMs = FETCH_TIMEOUT_MS, lang = 'en' } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${RELEASES_API}/v${version}`, {
+    const endpoint = releaseTagUrl(version);
+    // The URL is this module's own constant plus a checked version. The
+    // scanner's node_ssrf heuristic reads any two-argument function as an HTTP
+    // handler and its first argument as request input, which is what it matched
+    // on here; this module serves nothing and has no request to read.
+    // nosemgrep: rules.lgpl.nodejs_scan.javascript-ssrf-rule-node_ssrf
+    const res = await fetch(endpoint, {
       signal: controller.signal,
       headers: { accept: 'application/vnd.github+json' },
     });