sprag-cli 3.54.0 → 3.55.0

package/README.ko.md

@@ -5,7 +5,7 @@
   <img alt="Sprag" src="https://raw.githubusercontent.com/rootstudioyaml/sprag/main/site/assets/logo/sprag-lockup-light.svg" width="220">
 </picture>
 
-**Claude Code와 Codex용 품질 래칫**
+**Claude Code와 Codex가 쓰는 토큰을 첫 세션부터 줄입니다**
 
 [![npm](https://img.shields.io/npm/v/sprag-cli.svg?label=sprag-cli)](https://www.npmjs.com/package/sprag-cli)
 [![downloads](https://img.shields.io/npm/dm/sprag-cli.svg)](https://www.npmjs.com/package/sprag-cli)
@@ -15,10 +15,17 @@
 
 [sprag.io](https://sprag.io) · [벤치마크](https://github.com/rootstudioyaml/sprag/blob/main/docs/BENCHMARK.md)
 
+<a href="https://sprag.io/assets/video/sprag-compare-ko.mp4"><img src="https://raw.githubusercontent.com/rootstudioyaml/sprag/main/docs/sprag-compare-ko.gif" width="760" alt="두 터미널에 같은 요청 12건을 넣습니다. sprag 를 적용한 쪽은 조회와 테스트 실행을 저렴한 모델에 넘기고 문서를 Markdown 으로 바꿔 넣어, 하루를 $6.68 대신 $1.83 로 마칩니다."></a>
+
+같은 요청 12건, 두 터미널: sprag 적용 시 **$6.68 → $1.83 (72.6% 절감)**<br>
+<sub>예시 요청을 공개 단가로 계산했습니다. <a href="https://sprag.io/assets/video/sprag-compare-ko.mp4">전체 영상 (41초)</a></sub>
+
 </div>
 
 ---
 
+**일하는 방식은 그대로 두고 토큰만 줄입니다.** 조회와 확인, 테스트 실행은 저렴한 모델에 넘기고, 문서는 가벼운 Markdown으로 바꿔 넣습니다(54만 토큰짜리 발표 자료가 2.3만 토큰이 됩니다). 세션마다 쓴 금액과 아낀 금액은 상태줄에 바로 나타납니다. `npm i -g sprag-cli` 하나로 설정이 끝나며, 프로젝트마다 따로 설정할 것은 없습니다.
+
 **에이전트는 그대로 일하고, 퇴행만 막습니다.** 이름은 스프래그 클러치에서 왔습니다. 앞으로 도는 힘은 그대로 통과시키고, 역회전하는 순간 잠기는 부품입니다.
 
 Sprag는 Claude Code와 Codex가 남기는 세션 기록을 읽어 반복 실패와 위임 후보를 찾습니다. 사용자가 승인한 규칙은 다음 세션에도 적용하며, 위임 기록과 모델 단가를 확인할 수 있으면 예상 차액을 원장에 적습니다. 캐시와 사용량 한도 문제는 상태줄이나 패널에서 확인할 수 있습니다.
@@ -33,6 +40,8 @@ npm i -g sprag-cli   # 예전 이름 claude-token-saver 와 같은 패키지입
 
 Codex 기본 훅과 `AGENTS.md` 하네스, 범위별 래칫 규칙,
 한국어 검사, 프롬프트의 문서 경로 자동 변환, 로컬 토큰 보고서를 사용할 수 있습니다.
+Codex가 설치되어 있으면 `npm i -g sprag-cli` 하나로 Codex도 설정하고, 추천 룰을 묻지 않고
+전역으로 등록합니다(단계마다 확인하려면 `sprag install --manual`). Claude Code를 건드리지 않고
 Codex만 쓴다면 다음과 같이 설치하십시오.
 
 ```bash
@@ -41,14 +50,13 @@ sprag install --agent codex
 sprag --agent codex --days 7
 sprag panel --agent codex  # 별도 터미널에서 실시간 패널 실행
 sprag --statusline --agent codex --text
-sprag doctor --agent codex
+sprag doctor --agent codex  # 문제가 생겼을 때만
 sprag route-scan --agent codex
 sprag seed --agent codex
 ```
 
-설치 후 Codex의 `/hooks`에서 새 훅을 검토하고 신뢰해야 실행됩니다. 기본 대상은
-여전히 Claude Code입니다. 이미 Sprag를 설치했다면 두 번째 명령만 실행하여
-Codex 연동을 추가할 수 있습니다. Codex에서도 세션 브리핑, 경고 이력, 인수인계
+설치 후 Codex의 `/hooks`에서 새 훅을 검토하고 신뢰해야 실행됩니다. Codex가 요구하는
+절차입니다. 명령의 기본 대상은 여전히 Claude Code이며, `--agent codex`를 붙이면 Codex를 고릅니다. Codex에서도 세션 브리핑, 경고 이력, 인수인계
 파일을 지원합니다. `sprag delegate on --agent codex`로 모델 위임과 하위 에이전트
 지침 전달을 켤 수 있습니다. 상태 표시는 Sprag 터미널 상태줄과 패널을 사용하십시오.
 Codex 기본 상태줄은 셸 명령을 실행하지 않습니다. 반복된 단순 작업은 위임 후보로,

package/README.md

@@ -5,7 +5,7 @@
   <img alt="Sprag" src="https://raw.githubusercontent.com/rootstudioyaml/sprag/main/site/assets/logo/sprag-lockup-light.svg" width="220">
 </picture>
 
-**A quality ratchet for Claude Code and Codex.**
+**Cut the tokens Claude Code and Codex spend, from the first session.**
 
 [![npm](https://img.shields.io/npm/v/sprag-cli.svg?label=sprag-cli)](https://www.npmjs.com/package/sprag-cli)
 [![downloads](https://img.shields.io/npm/dm/sprag-cli.svg)](https://www.npmjs.com/package/sprag-cli)
@@ -15,10 +15,21 @@
 
 [sprag.io](https://sprag.io) · [Benchmark](https://github.com/rootstudioyaml/sprag/blob/main/docs/BENCHMARK.md)
 
+<a href="https://sprag.io/assets/video/sprag-compare-en.mp4"><img src="https://raw.githubusercontent.com/rootstudioyaml/sprag/main/docs/sprag-compare-en.gif" width="760" alt="Two terminals receive the same twelve requests. With Sprag, lookups and test runs go to cheaper models and documents go in as Markdown; the day ends at $1.83 against $6.68 without Sprag."></a>
+
+Same 12 requests, two terminals: **$6.68 → $1.83 (−72.6%)** with Sprag.<br>
+<sub>Example requests priced at public list rates. <a href="https://sprag.io/assets/video/sprag-compare-en.mp4">Full video (41s)</a></sub>
+
 </div>
 
 ---
 
+**Sprag saves tokens without changing how you work.** Lookups, checks and test
+runs go to a cheaper model, documents reach the context as compact Markdown (a
+540k-token deck becomes 23k tokens), and the statusline shows what each session
+spent and saved while it runs. `npm i -g sprag-cli` sets it all up; nothing to
+configure per project.
+
 Sprag is named after the sprag clutch: forward motion passes, backspin locks.
 Your agent keeps working, it just stops regressing.
 
@@ -34,14 +45,16 @@ budget and price lookups contact your configured LiteLLM endpoint using its
 existing credentials. The CLI requires Node.js 18+ and one TOML parser dependency.
 
 ```bash
-npm i -g sprag-cli   # default: Claude Code integration
+npm i -g sprag-cli   # Claude Code, plus Codex when it is installed
 ```
 
 ## Codex
 
 Native hooks, an `AGENTS.md` harness, scoped ratchet rules, Korean lint,
 document conversion, token reports, and a session-bound companion panel.
-For a Codex-only install:
+`npm i -g sprag-cli` sets Codex up too when it is installed, with the rule
+presets registered globally and nothing asked (`sprag install --manual` asks at
+each step). For a Codex-only install that leaves Claude Code alone:
 
 ```bash
 npm i -g sprag-cli --ignore-scripts
@@ -49,13 +62,13 @@ sprag install --agent codex
 sprag --agent codex --days 7
 sprag panel --agent codex  # live companion in a separate terminal
 sprag --statusline --agent codex --text
-sprag doctor --agent codex
+sprag doctor --agent codex  # troubleshooting only
 sprag route-scan --agent codex
 sprag seed --agent codex
 ```
 
-Review and trust the new hooks in Codex's `/hooks` menu. The default remains
-Claude Code; existing users can add Codex with the second command alone.
+Review and trust the new hooks in Codex's `/hooks` menu; Codex requires that
+step. Commands still default to Claude Code; add `--agent codex` to pick Codex.
 Codex also supports session briefings, warning history, handoffs, and opt-in
 model routing and subagent guidance (`sprag delegate on --agent codex`). The native Codex footer
 does not accept shell commands; Sprag provides a terminal statusline and panel.

package/bin/cli.js

@@ -10,8 +10,8 @@
  *   npx sprag --format csv       # CSV output
  *   npx sprag --project myproj   # filter by project
  *   npx sprag route-scan         # detect recurring easy work → haiku-delegation candidates
- *   npx sprag install            # set up skill/hooks/statusline; asks about harness + Korean guidance
- *   npx sprag install --yes      # take the defaults without asking (same as --no-input)
+ *   npx sprag install            # set up everything, presets and Codex included, without asking
+ *   npx sprag install --manual   # confirm each optional step
  *   npx sprag --install-hook     # install PostToolUse hook
  *   npx sprag --uninstall-hook   # remove hook
  *   npx claude-token-saver --hook-run         # internal: called by hook
@@ -123,8 +123,8 @@ Usage:
       --agent claude|codex (default: claude; accepted before or after subcommands)
   sprag route-scan         detect recurring easy work → delegation candidates
   sprag profile-map        show/refresh the gateway model map (LiteLLM /model/info)
-  sprag install            set up skill/hooks/statusline
-  sprag install --yes      take the defaults without asking
+  sprag install            set up everything (presets, and Codex when present) without asking
+  sprag install --manual   confirm each optional step
   sprag uninstall          remove everything install added
   sprag harness check      score the harness setup in CLAUDE.md
   sprag harness analyze    run the harness transcript analysis manually

package/docs/CODEX.ko.md

@@ -7,13 +7,20 @@ Sprag는 Codex의 기본 훅과 `AGENTS.md`를 사용합니다. Claude Code와
 
 ## 설치
 
+```sh
+npm i -g sprag-cli
+```
+
+Codex가 설치되어 있으면 패키지 설치가 Claude Code 연동, 추천 룰과 함께 Codex도 설정합니다.
+설치 중에 묻는 것은 없으며, 단계마다 확인하려면 `sprag install --manual`을 쓰십시오.
+Claude Code 설정을 건드리지 않고 Codex만 쓰려면 postinstall을 건너뛰고 Codex 설치를 직접 실행합니다.
+
 ```sh
 npm i -g sprag-cli --ignore-scripts
 sprag install --agent codex
-sprag doctor --agent codex
 ```
 
-이미 Sprag를 설치했다면 두 번째 명령부터 실행하십시오. Codex의 `/hooks`에서 등록된 명령을
+`sprag doctor --agent codex`는 문제가 생겼을 때 쓰는 진단 명령입니다. Codex의 `/hooks`에서 등록된 명령을
 검토하고 신뢰해야 훅이 동작합니다. 설치는 훅을 등록할 뿐 신뢰 설정을 바꾸지 않습니다.
 관리자 정책이나 `features.hooks = false` 설정이 훅을 막을 수도 있습니다.
 
@@ -22,7 +29,12 @@ sprag doctor --agent codex
 `AGENTS.override.md`가 있으면 그 파일을 사용하며, 변경 전 사본을 남깁니다.
 Claude 설정이나 `config.toml`은 고치지 않습니다.
 
-macOS에서는 별도 패널을 여는 훅도 기본 등록합니다. `--no-panel`로 제외할 수 있고,
+macOS zsh 환경에서는 설치가 tmux 설치 여부를 먼저 확인합니다. tmux가 없으면 Homebrew로 설치하고,
+`CTS_NO_TMUX=1`을 지정하면 이 단계를 건너뜁니다. 이어서 zsh 연동을 추가해 `codex`를 입력하면 같은
+터미널 안에 패널이 인라인으로 붙으며, 이때는 별도 창을 여는 훅을 등록하지 않습니다. tmux를 설치할 수
+없거나 로그인 셸이 zsh가 아니거나 이미 사용자의 `codex` 별칭·함수가 있으면 별도 Terminal 창 방식으로
+대신 동작합니다. `sprag panel shell remove --agent codex`로 끈 설정은 재설치와 업그레이드에도 그대로
+유지되며, `--no-panel`은 tmux 설정과 zsh 연동을 모두 건너뜁니다.
 `sprag panel auto off --agent codex`로 끈 설정은 재설치해도 유지합니다.
 패널 실행 여부는 `sprag panel doctor --agent codex`로 확인하십시오.
 
@@ -62,8 +74,8 @@ tmux 실행은 `--no-daemon`과 호출별 상태줄 설정을 사용합니다. C
 설정 파일은 바꾸지 않으며, `--keep-native-statusline`으로 기존 상태줄을 유지할 수 있습니다.
 패널은 Codex 기본 상태줄에 셸 명령을 넣는 방식이 아닙니다.
 
-macOS zsh에서 `codex`를 입력할 때 tmux 패널을 함께 열려면 다음 명령을 사용하십시오.
-기존 별칭이나 함수는 덮어쓰지 않습니다.
+설치는 이제 이 연동을 기본으로 추가합니다. macOS zsh에서 `codex`를 입력할 때 tmux 패널을 함께 열려면
+다음 명령을 사용하십시오. 기존 별칭이나 함수는 덮어쓰지 않습니다.
 
 ```sh
 sprag panel shell install --agent codex

package/docs/CODEX.md

@@ -8,14 +8,21 @@ subcommand to select Codex explicitly; this does not change a global default.
 
 ## Install
 
-For a Codex-only installation, skip npm's existing Claude Code postinstall:
+```sh
+npm i -g sprag-cli
+```
+
+The package install sets up Codex on its own when Codex is present, together
+with the Claude Code integration and the bundled presets; nothing is asked
+(`sprag install --manual` asks at each step). For a Codex-only installation that
+leaves Claude Code settings alone, skip the postinstall and run the Codex
+install directly:
 
 ```sh
 npm i -g sprag-cli --ignore-scripts
 sprag install --agent codex
 ```
 
-If Sprag is already installed for Claude Code, just run the second command.
 Both integrations can coexist. Codex installation uses `$CODEX_HOME` when set,
 otherwise `~/.codex`. It adds the integration hooks to `hooks.json` and a marked harness
 block to the global `AGENTS.md`. A non-empty `AGENTS.override.md` takes precedence,
@@ -28,10 +35,15 @@ changed hooks do not run until trusted. Use a Codex release that supports the
 events documented below. Admin policies or `features.hooks = false` may disable
 hooks. The `sprag` executable and Node.js must be on Codex's PATH.
 
-On macOS, installation also registers the panel-start hook in the same step,
-so all six hooks can be reviewed together (five without the optional panel).
-`install --no-panel --agent codex`
-skips it; an explicit `panel auto off` preference survives reinstall. Installation
+On macOS with zsh, installation also makes sure tmux is present: it installs
+tmux with Homebrew when missing (skip this with `CTS_NO_TMUX=1`) and adds the
+zsh integration so typing `codex` shows the panel inline in the same terminal.
+The separate-window hook is then not registered. When tmux cannot be
+installed, the login shell is not zsh, or an existing `codex` alias or
+function is already present, installation falls back to the separate window
+instead. `sprag panel shell remove --agent codex` is remembered across
+reinstalls and upgrades, and `--no-panel` skips both.
+An explicit `panel auto off` preference survives reinstall. Installation
 reports registration, not successful activation. After approval and restarting
 Codex, run `sprag panel doctor --agent codex` to check the last hook execution,
 any launch failure, and recent rendered frames. These diagnostics are local;
@@ -308,8 +320,8 @@ counts rather than a Codex dollar saving or billing measurement.
 ### Live Companion Panel
 
 Codex 0.157.1 was observed to defer SessionStart until the first submitted prompt,
-even after hook trust is granted. For immediate opening when typing `codex` in
-macOS zsh, install the optional shell integration:
+even after hook trust is granted. Installation now adds this shell integration by
+default on macOS zsh; to install or remove it manually:
 
 ```sh
 sprag panel shell install --agent codex

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sprag-cli",
-  "version": "3.54.0",
-  "description": "Sprag - a local harness for Claude Code and Codex: ratchet rules, model delegation, token telemetry, companion panels, document conversion, and Korean writing checks.",
+  "version": "3.55.0",
+  "description": "Cut the tokens Claude Code and Codex spend: routes simple work to cheaper models, converts documents to compact Markdown, and shows spend and savings live. Ratchet rules and Korean writing checks included.",
   "type": "module",
   "bin": {
     "sprag": "bin/cli.js",
@@ -14,7 +14,8 @@
     "publish:legacy": "node scripts/publish-legacy.mjs",
     "release:notes": "node scripts/release-notes.mjs",
     "site:docs": "node scripts/build-site-docs.mjs",
-    "test": "node --test"
+    "test": "node --test",
+    "version": "node scripts/sync-site-version.mjs"
   },
   "files": [
     "bin/",
@@ -48,6 +49,8 @@
     "subagent",
     "haiku",
     "cost-savings",
+    "token-saver",
+    "reduce-tokens",
     "token-usage",
     "prompt-caching",
     "cache",

package/src/codex-hooks.js

@@ -76,14 +76,21 @@ export async function codexHookOutput(event, payload, { cfg = loadConfig() } = {
     if (event === 'subagent-start' && cfg?.codex?.delegate !== true) return null;
     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 { /* Presets are optional. */ }
+    }
+    const { presetRatchetPath } = await import('./preset-ratchet.js');
+    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.`);
         } 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(`[Sprag Codex ratchet: ${scope}]\n${text}`);
         }
       } catch { /* No rules registered in this scope. */ }
     }

package/src/codex-panel-setup.js

@@ -0,0 +1,98 @@
+/**
+ * Sets up the Codex companion panel to run inline, inside the same terminal,
+ * instead of opening a separate macOS Terminal window. Codex's native footer
+ * cannot run a command, so the panel is the closest thing Codex has to a
+ * statusline; showing it below the Codex pane in tmux (via a zsh `codex()`
+ * wrapper) means a user does not get a new window per session. Install falls
+ * back to the separate window when tmux cannot be set up, the login shell is
+ * not zsh, or the user already has their own `codex` alias/function.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { installPanelShell } from './codex-panel-shell.js';
+
+/** Whether a tmux binary answers `-V`. */
+export function tmuxAvailable({ exec = execFileSync } = {}) {
+  try { exec('tmux', ['-V'], { stdio: 'pipe' }); return true; }
+  catch { return false; }
+}
+
+export function ensureTmux({ platform = process.platform, env = process.env, exec = execFileSync, exists = existsSync } = {}) {
+  // Checked first, before probing anything, so tests and CI never spawn brew.
+  if (env.CTS_NO_TMUX === '1' || (env.CI && env.CI !== 'false')) return { status: 'skipped' };
+  if (tmuxAvailable({ exec })) return { status: 'present' };
+  if (platform !== 'darwin') {
+    return { status: 'unavailable', detail: 'install tmux with your package manager (e.g. sudo apt install tmux)' };
+  }
+  let brew;
+  try { exec('brew', ['--prefix'], { stdio: 'pipe' }); brew = 'brew'; }
+  catch {
+    for (const p of ['/opt/homebrew/bin/brew', '/usr/local/bin/brew']) {
+      if (exists(p)) { brew = p; break; }
+    }
+  }
+  if (!brew) {
+    return { status: 'unavailable', detail: 'Homebrew not found; install tmux from https://github.com/tmux/tmux/wiki/Installing or MacPorts (sudo port install tmux)' };
+  }
+  try {
+    // brew update alone can take minutes; postinstall cannot afford that here.
+    exec(brew, ['install', 'tmux'], { stdio: 'inherit', timeout: 600_000,
+      env: { ...env, HOMEBREW_NO_AUTO_UPDATE: '1', HOMEBREW_NO_INSTALL_CLEANUP: '1' } });
+  } catch (e) {
+    return { status: 'failed', via: 'brew', detail: String(e.message).split('\n')[0] };
+  }
+  // No npm-package fallback: no official npm tmux exists, and a third-party
+  // prebuilt binary would be an unaudited supply-chain risk.
+  const fallback = join(dirname(brew === 'brew' ? '/opt/homebrew/bin/brew' : brew), 'tmux');
+  if (tmuxAvailable({ exec }) || exists(fallback)) return { status: 'installed', via: 'brew' };
+  return { status: 'failed', via: 'brew', detail: 'tmux not on PATH after brew install' };
+}
+
+export function setupCodexPanel({ platform = process.platform, env = process.env, config = {}, noPanel = false,
+  exec, exists, installShell = installPanelShell, tmux = ensureTmux } = {}) {
+  if (noPanel) return { panelAuto: false, mode: 'off' };
+  // Panel auto and the zsh integration are macOS-only today.
+  if (platform !== 'darwin') return { panelAuto: false, mode: 'off' };
+  const windowAuto = config?.codex?.panelAuto !== false;
+  if (config?.codex?.panelShell === false) {
+    return { panelAuto: windowAuto, mode: windowAuto ? 'window' : 'off', reason: 'shell integration turned off' };
+  }
+  if (basename(env.SHELL || '') !== 'zsh') {
+    return { panelAuto: windowAuto, mode: windowAuto ? 'window' : 'off', reason: 'login shell is not zsh' };
+  }
+  const t = tmux({ platform, env, ...(exec && { exec }), ...(exists && { exists }) });
+  if (!['present', 'installed'].includes(t.status)) {
+    return { panelAuto: windowAuto, mode: windowAuto ? 'window' : 'off', reason: t.detail || t.status, tmux: t };
+  }
+  let shellFile;
+  try { shellFile = installShell(); }
+  catch (e) {
+    return { panelAuto: windowAuto, mode: windowAuto ? 'window' : 'off', reason: e.message, tmux: t };
+  }
+  // The inline panel replaces the separate window by default; an explicit
+  // `panel auto on` keeps both.
+  return { panelAuto: config?.codex?.panelAuto === true, mode: 'inline', tmux: t, shellFile };
+}
+
+/** Formats a `setupCodexPanel` result as lines a caller prefixes and prints. */
+export function describePanelSetup(result, lang = 'en') {
+  if (result.mode === 'off') return [];
+  if (result.mode === 'inline') {
+    const lines = [lang === 'ko'
+      ? `패널: tmux 인라인 (${result.shellFile}). 새 터미널에서 codex 를 실행하면 같은 창 아래쪽에 패널이 붙습니다.`
+      : `panel: inline tmux (${result.shellFile}). Open a new terminal and run codex; the panel attaches below it.`];
+    if (result.tmux?.status === 'installed') {
+      lines.push(lang === 'ko' ? 'tmux 를 Homebrew 로 설치했습니다.' : 'installed tmux with Homebrew.');
+    }
+    return lines;
+  }
+  const lines = [lang === 'ko'
+    ? `패널: 별도 Terminal 창${result.reason ? ` (${result.reason})` : ''}`
+    : `panel: separate Terminal window${result.reason ? ` (${result.reason})` : ''}`];
+  if (result.tmux?.detail && ['unavailable', 'failed'].includes(result.tmux.status)) {
+    lines.push(`tmux: ${result.tmux.detail}`);
+  }
+  return lines;
+}

package/src/commands/codex.js

@@ -272,6 +272,11 @@ export async function run({ args, version }) {
       if (!['install', 'remove'].includes(args[2])) throw new Error('Usage: sprag panel shell install|remove --agent codex');
       const { installPanelShell } = await import('../codex-panel-shell.js');
       const file = installPanelShell({ remove: args[2] === 'remove' });
+      // install adds the integration by default, so a removal must be
+      // remembered or the next upgrade puts it back.
+      const cfg = loadConfig();
+      cfg.codex = { ...cfg.codex, panelShell: args[2] === 'install' };
+      saveConfig(cfg);
       console.log(`Shell integration ${args[2]}: ${file}. Open a new terminal to apply it.`);
       return;
     }
@@ -377,17 +382,25 @@ export async function run({ args, version }) {
   }
   if (cmd === 'install') {
     const cfg = loadConfig();
-    const panelAuto = process.platform === 'darwin' && !hasFlag('--no-panel') && cfg?.codex?.panelAuto !== false;
+    const { setupCodexPanel, describePanelSetup } = await import('../codex-panel-setup.js');
+    const panel = setupCodexPanel({ config: cfg || {}, noPanel: hasFlag('--no-panel') });
+    const panelAuto = panel.panelAuto;
     const hook = configureCodexHooks({ panelAuto });
     console.log(`Codex hooks: ${hook.file} (${hook.action})`);
+    for (const line of describePanelSetup(panel)) console.log(`Codex ${line}`);
     if (process.env.CTS_NO_HARNESS !== '1') {
       const h = initCodexHarness({ root, scope: 'global' });
       console.log(`Codex harness: ${h.file}`);
     }
+    try {
+      const { preparePresetRatchet } = await import('../preset-ratchet.js');
+      const p = preparePresetRatchet({ agent: 'codex' });
+      console.log(`Codex preset rules: ${p.file} (${p.rules} registered${p.moved ? `, ${p.moved} moved from ratchet.md` : ''})`);
+    } catch { /* Presets are optional; `seed` still registers them. */ }
     console.log('Open /hooks in Codex and review/trust the Sprag hooks before they can run.');
     console.log(`Panel auto-start: ${panelAuto ? 'registered with the other hooks' : 'off'}. Hook registration is complete; runtime activation is not verified.`);
     console.log('After approval, start or resume Codex and run: sprag panel doctor --agent codex');
-    if (panelAuto) console.log('Some Codex versions defer SessionStart until the first prompt. For immediate opening on typing codex: sprag panel shell install --agent codex (optional zsh integration).');
+    if (panel.mode === 'window') console.log('Some Codex versions defer SessionStart until the first prompt. For immediate opening on typing codex: sprag panel shell install --agent codex (optional zsh integration).');
     console.log('Existing config.toml, Claude Code settings, and ratchet rules are preserved.');
     console.log('Korean guidance is opt-in: sprag korean on --agent codex');
     return;
@@ -444,6 +457,15 @@ export async function run({ args, version }) {
       const r = harnessListRules(opts);
       console.log(`Codex ratchet [${scope}]: ${r.path}`);
       for (const rule of r.rules) console.log(`#${rule.index} ${rule.text}`);
+      if (scope === 'global') {
+        const { acceptedGlobalPresets, presetRatchetPath } = await import('../preset-ratchet.js');
+        const presets = acceptedGlobalPresets({ agent: 'codex' });
+        if (presets.length) {
+          console.log(`Codex preset rules [global]: ${presetRatchetPath({ agent: 'codex' })}`);
+          for (const p of presets) console.log(`${p.id} ${p.text}`);
+          console.log('Remove a preset with: sprag seed skip <id> --agent codex');
+        }
+      }
     } else if (sub === 'rm') {
       const raw = args[2];
       // Locate the index even when scope flags precede it.

package/src/commands/harness.js

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

package/src/commands/install.js

@@ -5,8 +5,12 @@
  * a legacy command file is removed automatically. Cross-platform.
  *   sprag install              # install/update the skill
  *   sprag install --force      # overwrite existing skill file
- *   sprag install --yes        # take the defaults instead of asking
- *   sprag install --no-input   # same as --yes; also implied by CTS_NO_INPUT=1
+ *   sprag install --manual     # ask before each optional step instead
+ *
+ * The default is automatic: nothing is asked, the bundled presets are
+ * registered globally, and Codex is set up too when ~/.codex exists. `--manual`
+ * restores the step-by-step questions (they still need a terminal attached).
+ * `--yes` and `--no-input` are accepted as the explicit spelling of the default.
  */
 
 import { debug } from '../debug.js';
@@ -19,12 +23,13 @@ export async function run({ hasFlag }) {
     const { userLanguage, languageDecided, setUserLanguage } = await import('../config.js');
     const { canPrompt, confirm } = await import('../prompt.js');
     const force = hasFlag('--force');
-    // Two features below write to ~/.claude and cost tokens in every session,
-    // so the install shows what they contain and asks before turning them on.
-    // Asking is only possible with a human attached: postinstall, CI and pipes
-    // fall through to the previous automatic defaults so an unattended upgrade
-    // behaves exactly as it did before.
-    const interactive = canPrompt() && !hasFlag('--yes') && !hasFlag('--no-input');
+    // Automatic unless asked otherwise. A question per step turned the install
+    // into a dozen answers before any work, and every answer has a sensible
+    // default: the harness and presets are what make the first session save
+    // tokens. `--manual` brings the questions back, and only with a terminal
+    // attached, so postinstall, CI and pipes never wait on input.
+    const manual = hasFlag('--manual') && !hasFlag('--yes') && !hasFlag('--no-input');
+    const interactive = manual && canPrompt();
 
     // Output language, decided first because every line below it — and every
     // briefing the hooks inject from here on — is written in it. Until now it
@@ -342,10 +347,37 @@ export async function run({ hasFlag }) {
     // postinstall cannot hold a conversation, and a prompt here would be
     // answered by whoever happens to be at the terminal for a set of rules
     // they have not read. All the install does is say what is waiting.
+    // Presets now live in ratchet-preset.md. Moving the ones older versions
+    // appended to ratchet.md comes first, so they are not offered again below.
     try {
-      const { pendingSeeds } = await import('../seed-rules.js');
+      const { preparePresetRatchet } = await import('../preset-ratchet.js');
+      const p = preparePresetRatchet();
+      if (p.moved) {
+        console.log('');
+        console.log(lang === 'ko'
+          ? `  preset: ratchet.md 에 있던 추천 룰 ${p.moved}건을 ${p.file} 로 옮겼습니다 (원본은 ratchet.md.bak-preset-migration).`
+          : `  preset: moved ${p.moved} bundled rule(s) from ratchet.md to ${p.file} (original kept as ratchet.md.bak-preset-migration).`);
+      }
+    } catch (e) {
+      debug('install:preset-ratchet', e); // the next session start retries
+    }
+
+    try {
+      const { pendingSeeds, acceptSeed } = await import('../seed-rules.js');
       const pending = pendingSeeds();
-      if (pending.length > 0) {
+      if (pending.length > 0 && !manual) {
+        // Automatic install registers every preset globally. Global because a
+        // preset is a tool-wide rule, not a project's; `sprag seed` lists them
+        // and `sprag harness rm` removes any one afterwards.
+        let n = 0;
+        for (const p of pending) {
+          try { if (await acceptSeed(p.id, { scope: 'global' })) n += 1; } catch (e) { debug('install:seed-accept', e); }
+        }
+        console.log('');
+        console.log(lang === 'ko'
+          ? `  seed: 추천 룰 ${n}건을 전체 프로젝트에 등록했습니다 (모델 피팅 + 래칫 프리셋). 목록: sprag seed`
+          : `  seed: registered ${n} recommended rule(s) for all projects (model-fitting + ratchet presets). List: sprag seed`);
+      } else if (pending.length > 0) {
         console.log('');
         console.log(lang === 'ko'
           ? `  seed: 추천 룰 ${pending.length}건이 대기 중입니다 (모델 피팅 + 래칫 프리셋).`
@@ -358,6 +390,70 @@ export async function run({ hasFlag }) {
       debug('install:seed-offer', e); // optional feature; never fail install
     }
 
+    // Codex, when it is installed on this machine. Without this a Codex user
+    // had to know to run `sprag install --agent codex` after the package
+    // install. Registration is all we can do: Codex still asks the user to
+    // trust the hooks in /hooks before they run, and that step stays theirs.
+    try {
+      const { codexUserDir } = await import('../agent.js');
+      const { existsSync } = await import('node:fs');
+      if (process.env.CTS_NO_CODEX !== '1' && existsSync(codexUserDir())) {
+        let proceed = true;
+        if (interactive) {
+          console.log('');
+          proceed = await confirm(lang === 'ko'
+            ? '  codex: Codex 가 설치되어 있습니다. Codex 훅과 하네스도 함께 설정할까요?'
+            : '  codex: Codex is installed here. Set up its hooks and harness too?', { defaultValue: true });
+        }
+        if (proceed) {
+          const { configureCodexHooks } = await import('../codex-installer.js');
+          const { initCodexHarness } = await import('../codex-harness.js');
+          const { loadConfig } = await import('../config.js');
+          const { setupCodexPanel, describePanelSetup } = await import('../codex-panel-setup.js');
+          const config = loadConfig() || {};
+          // A manual install asks before touching the system package manager.
+          let env = process.env;
+          if (interactive && process.platform === 'darwin') {
+            const { tmuxAvailable } = await import('../codex-panel-setup.js');
+            if (!tmuxAvailable() && !await confirm(lang === 'ko'
+              ? '  codex: tmux 가 없습니다. Homebrew 로 설치해 같은 창에 패널을 붙일까요?'
+              : '  codex: tmux is missing. Install it with Homebrew so the panel shares the Codex window?', { defaultValue: true })) {
+              env = { ...process.env, CTS_NO_TMUX: '1' };
+            }
+          }
+          let panel;
+          try { panel = setupCodexPanel({ config, env }); }
+          catch (e) {
+            debug('install:codex-panel', e);
+            const auto = process.platform === 'darwin' && config.codex?.panelAuto !== false;
+            panel = { panelAuto: auto, mode: auto ? 'window' : 'off' };
+          }
+          const hook = configureCodexHooks({ panelAuto: panel.panelAuto });
+          console.log('');
+          console.log(`  codex: hooks ${hook.action} (${hook.file})`);
+          for (const line of describePanelSetup(panel, lang)) console.log(`  codex: ${line}`);
+          if (process.env.CTS_NO_HARNESS !== '1') {
+            const h = initCodexHarness({ scope: 'global' });
+            console.log(`  codex: harness ${h.file}`);
+          }
+          try { (await import('../preset-ratchet.js')).preparePresetRatchet({ agent: 'codex' }); } catch (e) { debug('install:codex-preset', e); }
+          if (!manual) {
+            const { pendingSeeds, acceptSeed } = await import('../seed-rules.js');
+            let n = 0;
+            for (const p of pendingSeeds({ agent: 'codex' })) {
+              try { if (await acceptSeed(p.id, { scope: 'global', agent: 'codex' })) n += 1; } catch (e) { debug('install:codex-seed', e); }
+            }
+            if (n) console.log(lang === 'ko' ? `  codex: 추천 룰 ${n}건 등록` : `  codex: registered ${n} recommended rule(s)`);
+          }
+          console.log(lang === 'ko'
+            ? '  codex: Codex 에서 /hooks 를 열어 Sprag 훅을 신뢰해야 실행됩니다 (Codex 보안 정책이라 자동화할 수 없습니다).'
+            : "  codex: open /hooks in Codex and trust the Sprag hooks; Codex requires that step and it cannot be automated.");
+        }
+      }
+    } catch (e) {
+      debug('install:codex', e); // optional; `sprag install --agent codex` still works
+    }
+
     console.log('');
     console.log('Open Claude Code in any directory and just mention:');
     console.log('  "cache hit rate" / "1M context" / "5H cap" — the skill auto-activates.');

package/src/commands/route-scan.js

@@ -277,6 +277,10 @@ export async function run({ args, hasFlag, numArg }) {
       // when the rendering differs, so the common case is a read and a string
       // compare.
       try { mrHook.syncAllFiles(); } catch (e) { debug('route-scan:sync-ratchet', e); }
+      // Same reason for the preset ratchet: an upgrade that rewords or drops a
+      // bundled rule reaches ratchet-preset.md here, without a reinstall. It
+      // also moves presets older versions appended to ratchet.md.
+      try { (await import('../preset-ratchet.js')).preparePresetRatchet(); } catch (e) { debug('route-scan:sync-preset', e); }
       // Registered rules whose delegated-category error rate crossed the
       // health threshold since promotion — the user approved these, so a
       // status change must be briefed, not just written into the md file.

package/src/commands/seed.js

@@ -5,7 +5,8 @@
  *   sprag seed accept <id> --global     # register one rule
  *   sprag seed accept <id> --project    # ... into this project only
  *   sprag seed accept all --global      # when the user says "all of them"
- *   sprag seed skip <id> | skip all     # never offer it again
+ *   sprag seed skip <id> | skip all     # never offer it again; for an
+ *                                       # accepted preset, drop it from ratchet-preset.md
  *   sprag seed reset                    # make every preset pending again
  *
  * Scope is explicit on purpose, exactly as `harness promote` requires it: the
@@ -26,7 +27,7 @@ export async function run({ args, hasFlag, agent = 'claude', root: rootArg }) {
   const scopeFlag = () => (hasFlag('--global') ? 'global' : hasFlag('--project') ? 'project' : null);
 
   if (sub === 'reset') {
-    const n = seed.resetSeeds({ agent });
+    const n = await seed.resetSeeds({ agent });
     console.log(ko
       ? `기록된 응답 ${n}건을 지웠습니다 — 프리셋 전체가 다시 제안 대상이 됩니다.`
       : `Cleared ${n} recorded answer(s) — every preset is pending again.`);
@@ -46,9 +47,11 @@ export async function run({ args, hasFlag, agent = 'claude', root: rootArg }) {
 
     if (sub === 'skip') {
       for (const id of targets) {
-        const r = seed.skipSeed(id, { lang, root, agent });
+        const r = await seed.skipSeed(id, { lang, root, agent });
         console.log(r
-          ? (ko ? `건너뜀: ${id}` : `skipped: ${id}`)
+          ? (r.removed
+            ? (ko ? `프리셋 파일에서 뺐습니다: ${id}` : `removed from the preset file: ${id}`)
+            : (ko ? `건너뜀: ${id}` : `skipped: ${id}`))
           : (ko ? `대기 중인 프리셋이 아닙니다: ${id}` : `not a pending preset: ${id}`));
       }
       return;

package/src/commands/uninstall.js

@@ -35,6 +35,29 @@ export async function run({ hasFlag, args = [] }) {
   for (const item of r.kept) {
     console.log(lang === 'ko' ? `  유지: ${item}` : `  kept: ${item}`);
   }
+  // The install now registers Codex too when it finds it, so removal has to
+  // undo that as well; otherwise Codex keeps calling a command that may no
+  // longer exist. Only our own entries go, exactly as `uninstall --agent codex`.
+  try {
+    const { codexHookStatus, configureCodexHooks } = await import('../codex-installer.js');
+    const { codexHarnessStatus, uninitCodexHarness } = await import('../codex-harness.js');
+    const hooked = codexHookStatus().some((h) => h.registered);
+    let harness = false;
+    try { harness = codexHarnessStatus({ scope: 'global' }).configured > 0; } catch { /* no AGENTS.md */ }
+    if (hooked || harness) {
+      const hook = configureCodexHooks({ remove: true });
+      const h = uninitCodexHarness({ scope: 'global' });
+      console.log(lang === 'ko'
+        ? `  Codex: 훅 ${hook.action} (${hook.file}), 하네스 ${h.removed ? '제거' : '없음'}`
+        : `  Codex: hooks ${hook.action} (${hook.file}), harness ${h.removed ? 'removed' : 'absent'}`);
+      if (process.platform === 'darwin') {
+        try {
+          const { installPanelShell } = await import('../codex-panel-shell.js');
+          installPanelShell({ remove: true });
+        } catch (e) { /* a malformed or foreign block stays for the user to repair */ }
+      }
+    }
+  } catch { /* Codex state is optional; the Claude removal above already succeeded */ }
   if (!purge) {
     console.log(lang === 'ko'
       ? `  기록된 절감액과 설정까지 지우려면 \`${CLI_NAME} uninstall --purge\` 를 실행하십시오.`

package/src/commands/upgrade.js

@@ -31,6 +31,17 @@ export async function run({ hasFlag, version }) {
   const lang = userLanguage();
   const cmd = upgradeCommand();
 
+  // pnpm and bun skip lifecycle scripts by default, and npm skips them under
+  // ignore-scripts, so the new copy's setup (Codex hooks, tmux panel) runs here.
+  // The install is idempotent, so npm running it twice changes nothing.
+  async function runSetup() {
+    console.log('$ sprag install');
+    const installCode = await runCommand('sprag install');
+    if (installCode !== 0) console.error(lang === 'ko'
+      ? '설치 후 설정(sprag install)이 실패했습니다. 새 셸에서 sprag install 을 직접 실행하십시오.'
+      : 'Post-upgrade setup (sprag install) failed. Run sprag install in a fresh shell.');
+  }
+
   if (hasFlag('--print')) {
     console.log(cmd);
     return;
@@ -55,6 +66,7 @@ export async function run({ hasFlag, version }) {
         : `Migration command failed with exit code ${migrateCode}. Check the output above.`);
       process.exit(migrateCode);
     }
+    await runSetup();
     console.log(lang === 'ko'
       ? '이전이 끝났습니다. 새 셸에서 sprag --version 으로 확인하십시오.'
       : 'Migration done. Confirm with sprag --version in a fresh shell.');
@@ -86,6 +98,7 @@ export async function run({ hasFlag, version }) {
   // still reports the old version. Refresh the cache against the new latest so
   // the statusline chip clears on the next render instead of lingering.
   await refreshUpdateState(s.latest);
+  await runSetup();
   console.log(lang === 'ko'
     ? `설치가 끝났습니다. 새 셸에서 sprag --version 으로 ${s.latest} 인지 확인하십시오.`
     : `Done. In a fresh shell, run sprag --version to confirm ${s.latest}.`);

package/src/harness-templates.js

@@ -40,6 +40,38 @@ export function modelRatchetImportLine(scope = 'project') {
   return scope === 'global' ? '@~/.claude/ratchet-model.md' : '@.claude/ratchet-model.md';
 }
 
+/**
+ * The preset ratchet: the bundled rules the user accepted globally. It is a
+ * tool-owned file like ratchet-model.md, regenerated whole from the recorded
+ * answers, so an upgrade can reword, add or drop presets without touching the
+ * rules the user wrote into ratchet.md. Presets are global-only, so only the
+ * global block imports it.
+ */
+export function presetRatchetImportLine() {
+  return '@~/.claude/ratchet-preset.md';
+}
+export const PRESET_RATCHET_IMPORT_RE = /^@~\/\.claude\/ratchet-preset\.md\s*$/m;
+
+/**
+ * Render ratchet-preset.md. `rules` is [{ id, text }] in display order. The
+ * file is loaded into every session, so the header stays short.
+ */
+export function renderPresetRatchet(rules, { lang = 'en', agent = 'claude' } = {}) {
+  const ko = lang === 'ko' && agent !== 'codex';
+  const suffix = agent === 'codex' ? ' --agent codex' : '';
+  const head = ko
+    ? `# Preset Ratchet Rules (sprag 관리)
+
+sprag 에 동봉된 추천 룰 가운데 전역으로 등록한 것입니다. sprag 가 이 파일을 통째로 다시 쓰므로
+직접 고치지 마십시오. 하나를 빼려면 \`sprag seed skip <id>${suffix}\`, 직접 쓰는 룰은 ratchet.md 에 둡니다.`
+    : `# Preset Ratchet Rules (managed by sprag)
+
+Bundled rules you registered globally. Sprag rewrites this file whole, so do not
+edit it. Drop one with \`sprag seed skip <id>${suffix}\`; your own rules belong in ratchet.md.`;
+  const body = rules.map((r) => `- [${r.id}] ${r.text}`).join('\n');
+  return `${head}\n\n## Rules\n\n${body}${body ? '\n' : ''}`;
+}
+
 // Matches either scope's import line, so completeness checks don't need to know
 // which scope wrote the block. `(?!-)` keeps the ratchet-model import from
 // counting as the ratchet.md one.
@@ -118,7 +150,7 @@ ${HARNESS_SECTIONS[4].heading}
 📥 ratchet 룰 로드 (이 줄들을 지우면 룰이 적용되지 않습니다):
 
 ${ratchetImportLine(scope)}
-${modelRatchetImportLine(scope)}
+${modelRatchetImportLine(scope)}${scope === 'global' ? `\n${presetRatchetImportLine()}` : ''}
 ${HARNESS_BLOCK_END}
 `;
 }

package/src/harness.js

@@ -21,6 +21,7 @@ import {
   appendRatchetRule,
   RATCHET_IMPORT_RE,
   MODEL_RATCHET_IMPORT_RE,
+  renderPresetRatchet,
 } from './harness-templates.js';
 import { routeWarningForStatusline } from './route-scan.js';
 import { ruleHealthWarningForStatusline, modelRatchetPathFor, renderModelRatchet } from './model-rules.js';
@@ -265,6 +266,18 @@ export function harnessInit({ root = findProjectRoot(), force = false, scope = '
     result.skipped.push(mrPath + ' (already exists)');
   }
 
+  // ratchet-preset.md — tool-owned and imported by the global block only, so
+  // it is seeded here for the same reason as ratchet-model.md above.
+  if (scope === 'global') {
+    const prPath = join(homedir(), '.claude', 'ratchet-preset.md');
+    if (!existsSync(prPath)) {
+      try {
+        writeFileSync(prPath, renderPresetRatchet([], { lang: userLanguage() }));
+        result.wrote.push(prPath);
+      } catch { /* unwritable — the next session start renders it */ }
+    }
+  }
+
   return result;
 }
 
@@ -347,7 +360,19 @@ 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', agent = 'claude' } = {}) {
+export async function harnessPull({ root = findProjectRoot(), scope = 'global', agent = 'claude' } = {}) {
+  // Global presets live in ratchet-preset.md now, rendered from recorded
+  // answers, so pulling them globally is accepting every one of them.
+  if (scope === 'global') {
+    const { acceptedGlobalPresets, presetRatchetPath } = await import('./preset-ratchet.js');
+    const { pendingSeeds, acceptSeed } = await import('./seed-rules.js');
+    const added = [];
+    for (const s of pendingSeeds({ root, agent }).filter((x) => x.kind === 'ratchet')) {
+      if (await acceptSeed(s.id, { scope: 'global', root, agent })) added.push(s.ruleText);
+    }
+    const all = acceptedGlobalPresets({ agent }).length;
+    return { path: presetRatchetPath({ agent }), scope, added, skippedRules: all - added.length, presets: presetRuleEntries().length };
+  }
   const presets = presetRules();
   const rmPath = resolveRatchetPath(scope, root, agent);
   const result = { path: rmPath, scope, added: [], skippedRules: 0, presets: presets.length };

package/src/preset-ratchet.js

@@ -0,0 +1,133 @@
+/**
+ * preset-ratchet — the bundled ratchet presets the user accepted globally,
+ * kept in a file of their own.
+ *
+ * Presets used to be appended to ratchet.md next to the user's own rules. Once
+ * there, an upgrade could not reword a preset, drop one that turned out wrong,
+ * or tell which lines were ours: every line looked like the user's. This file
+ * holds only presets and is regenerated whole from the recorded answers in
+ * seed-state, the same way ratchet-model.md is regenerated from the rule
+ * registry. So an upgrade updates it by itself, `seed skip` removes one, and
+ * ratchet.md stays the user's.
+ *
+ *   Claude Code  ~/.claude/ratchet-preset.md   (imported by the global harness block)
+ *   Codex        <CODEX_HOME>/ratchet-preset.md (injected by the SessionStart hook)
+ *
+ * Presets accepted into a project scope still go to that project's ratchet.md:
+ * a project rule is the user's placement decision, not a tool-wide default.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { codexUserDir } from './agent.js';
+import { userLanguage } from './config.js';
+import {
+  HARNESS_BLOCK_BEGIN,
+  HARNESS_BLOCK_END,
+  PRESET_RATCHET_IMPORT_RE,
+  presetRatchetImportLine,
+  renderPresetRatchet,
+} from './harness-templates.js';
+import { loadSeedState, ratchetPresets, saveSeedState } from './seed-rules.js';
+
+export function presetRatchetPath({ agent = 'claude' } = {}) {
+  return agent === 'codex'
+    ? join(codexUserDir(), 'ratchet-preset.md')
+    : join(homedir(), '.claude', 'ratchet-preset.md');
+}
+
+function globalRatchetPath(agent) {
+  return agent === 'codex' ? join(codexUserDir(), 'ratchet.md') : join(homedir(), '.claude', 'ratchet.md');
+}
+
+function writeIfChanged(file, text) {
+  let before = null;
+  try { before = readFileSync(file, 'utf8'); } catch { /* first write */ }
+  if (before === text) return false;
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, file);
+  return true;
+}
+
+/** The accepted-global presets, in the bundled order, with this version's wording. */
+export function acceptedGlobalPresets({ agent = 'claude', lang = userLanguage() } = {}) {
+  const { decided } = loadSeedState({ agent });
+  return ratchetPresets(lang, { agent })
+    .filter((p) => decided[p.id]?.action === 'accepted' && decided[p.id]?.scope === 'global')
+    .map((p) => ({ id: p.id, text: p.text }));
+}
+
+/**
+ * Rewrite the preset file from the recorded answers. A preset that a newer
+ * release removed simply stops being rendered; its answer stays in seed-state
+ * so it is not offered again if it comes back under the same text.
+ */
+export function syncPresetRatchet({ agent = 'claude', lang = userLanguage() } = {}) {
+  const file = presetRatchetPath({ agent });
+  const rules = acceptedGlobalPresets({ agent, lang });
+  const changed = writeIfChanged(file, renderPresetRatchet(rules, { lang, agent }));
+  return { file, rules: rules.length, changed };
+}
+
+/**
+ * Move presets that earlier versions appended to the global ratchet.md into
+ * the preset file. A line counts as a preset only when its text, without the
+ * date stamp, equals a bundled rule in either language, so nothing the user
+ * wrote themselves is touched. The original is backed up once before the
+ * first change.
+ */
+export function migrateLegacyPresetRules({ agent = 'claude' } = {}) {
+  const file = globalRatchetPath(agent);
+  if (!existsSync(file)) return { file, moved: 0 };
+  const byText = new Map();
+  for (const lang of ['ko', 'en']) {
+    for (const p of ratchetPresets(lang, { agent })) byText.set(p.text.trim(), p.id);
+  }
+  const stamp = /^\d{4}-\d{2}-\d{2}(\s*\([^)]*\))?:\s*/;
+  const original = readFileSync(file, 'utf8');
+  const moved = [];
+  const kept = original.split('\n').filter((line) => {
+    const m = line.match(/^\s*-\s+(.*)$/);
+    if (!m) return true;
+    const id = byText.get(m[1].replace(stamp, '').trim());
+    if (!id) return true;
+    moved.push(id);
+    return false;
+  });
+  if (!moved.length) return { file, moved: 0 };
+  writeFileSync(`${file}.bak-preset-migration`, original);
+  writeIfChanged(file, kept.join('\n'));
+  const state = loadSeedState({ agent });
+  const today = new Date().toISOString().slice(0, 10);
+  for (const id of moved) state.decided[id] = { action: 'accepted', at: today, scope: 'global', migrated: true };
+  saveSeedState(state, { agent });
+  return { file, moved: moved.length };
+}
+
+/**
+ * Add the preset import to a global harness block written before the file
+ * existed. Only the tool's own marked block is edited; a CLAUDE.md without the
+ * block is left alone, since the user chose not to install the harness there.
+ */
+export function ensurePresetImport() {
+  const file = join(homedir(), '.claude', 'CLAUDE.md');
+  let text;
+  try { text = readFileSync(file, 'utf8'); } catch { return { file, added: false }; }
+  const begin = text.indexOf(HARNESS_BLOCK_BEGIN);
+  const end = text.indexOf(HARNESS_BLOCK_END);
+  if (begin < 0 || end < begin) return { file, added: false };
+  if (PRESET_RATCHET_IMPORT_RE.test(text.slice(begin, end))) return { file, added: false };
+  writeFileSync(file, `${text.slice(0, end)}${presetRatchetImportLine()}\n${text.slice(end)}`);
+  return { file, added: true };
+}
+
+/** Everything a session start or an install does: migrate, render, and wire the import. */
+export function preparePresetRatchet({ agent = 'claude', lang = userLanguage() } = {}) {
+  const migrated = migrateLegacyPresetRules({ agent });
+  const synced = syncPresetRatchet({ agent, lang });
+  const imported = agent === 'codex' ? { added: false } : ensurePresetImport();
+  return { ...synced, moved: migrated.moved, importAdded: imported.added };
+}

package/src/seed-rules.js

@@ -177,6 +177,15 @@ export async function acceptSeed(id, { scope, root = findProjectRoot(), lang = u
   if (!seed) return null;
 
   if (seed.kind === 'ratchet') {
+    // A global preset goes to the tool-owned preset file, which is rendered
+    // from the recorded answer; a project one is the user's placement and is
+    // appended to that project's ratchet.md as before.
+    if (scope === 'global') {
+      recordDecision(id, 'accepted', { scope }, { agent });
+      const { syncPresetRatchet } = await import('./preset-ratchet.js');
+      const res = syncPresetRatchet({ agent, lang });
+      return { id, kind: 'ratchet', scope, path: res.file, rule: seed.ruleText };
+    }
     const res = harnessPromote(seed.ruleText, { root, scope, agent });
     recordDecision(id, 'accepted', { scope }, { agent });
     return { id, kind: 'ratchet', scope, path: res.path, rule: seed.ruleText };
@@ -218,23 +227,39 @@ export async function acceptSeed(id, { scope, root = findProjectRoot(), lang = u
     lastSeen: today,
   });
   const written = syncAllFiles();
-  recordDecision(id, 'accepted', { scope });
+  recordDecision(id, 'accepted', { scope }, { agent });
   return { id, kind: 'model', scope, paths: written, rule: composeRuleText(entry.rule, entry, lang) };
 }
 
-/** Record a "no" so the rule is never offered again (until `seed reset`). */
-export function skipSeed(id, opts = {}) {
+/**
+ * Record a "no" so the rule is never offered again (until `seed reset`).
+ *
+ * A preset already accepted globally can be skipped too: that is how one comes
+ * out of the preset file, which is rendered from these answers.
+ */
+export async function skipSeed(id, opts = {}) {
   const seed = findSeed(id, opts);
-  if (!seed) return null;
-  recordDecision(id, 'skipped', {}, { agent: opts.agent });
-  return { id, kind: seed.kind, rule: seed.ruleText };
+  if (seed) {
+    recordDecision(id, 'skipped', {}, { agent: opts.agent });
+    return { id, kind: seed.kind, rule: seed.ruleText };
+  }
+  const { decided } = loadSeedState({ agent: opts.agent });
+  const preset = ratchetPresets(opts.lang, { agent: opts.agent }).find((p) => p.id === id);
+  if (!preset || decided[id]?.action !== 'accepted' || decided[id]?.scope !== 'global') return null;
+  recordDecision(id, 'skipped', { was: 'accepted' }, { agent: opts.agent });
+  const { syncPresetRatchet } = await import('./preset-ratchet.js');
+  syncPresetRatchet({ agent: opts.agent, lang: opts.lang });
+  return { id, kind: 'ratchet', rule: preset.text, removed: true };
 }
 
 /** Forget every recorded answer — the full set becomes pending again. */
-export function resetSeeds({ agent = 'claude' } = {}) {
+export async function resetSeeds({ agent = 'claude' } = {}) {
   const state = loadSeedState({ agent });
   const count = Object.keys(state.decided).length;
   saveSeedState({ decided: {} }, { agent });
+  // The preset file mirrors the answers, so forgetting them empties it.
+  const { syncPresetRatchet } = await import('./preset-ratchet.js');
+  syncPresetRatchet({ agent });
   return count;
 }