claude-token-saver 2.14.2 → 2.16.0

package/README.en.md

@@ -1,6 +1,8 @@
 [한국어](./README.md) · **English**
 
 [![DeepPulse YouTube](https://img.shields.io/badge/YouTube-@DeepPulseKR-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@DeepPulseKR)
+[![DeepPulseEN YouTube](https://img.shields.io/badge/YouTube-@DeepPulseEN-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@DeepPulseEN)
+[![Homepage](https://img.shields.io/badge/Homepage-rootstudioyaml.github.io-2ea44f)](https://rootstudioyaml.github.io/)
 [![npm](https://img.shields.io/npm/v/claude-token-saver.svg)](https://www.npmjs.com/package/claude-token-saver)
 
 # claude-token-saver
@@ -256,7 +258,9 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 
 - [GitHub Issue #46829](https://github.com/anthropics/claude-code/issues/46829) — cache TTL regression
 - [HN discussion](https://news.ycombinator.com/item?id=47736476) — 168 points, 142 comments
-- [HNPulse KR](https://www.youtube.com/@DeepPulseKR) — Korean HN tech deep-dives
+- [DeepPulse KR](https://www.youtube.com/@DeepPulseKR) — Korean HN tech deep-dives
+- [DeepPulse EN](https://www.youtube.com/@DeepPulseEN) — English HN tech deep-dives
+- [Homepage](https://rootstudioyaml.github.io/) — project site
 
 ## Known environment quirks
 
@@ -264,6 +268,11 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 
 ## Release notes
 
+### v2.15.0 (2026-06-13)
+- **Global harness init** — `harness init`/`uninit`/`check` gain the same scope concept ratchet already had. `harness init --global` installs the 5 sections into `~/.claude/CLAUDE.md` (+ `~/.claude/ratchet.md`) once, so they **apply to every project**. The no-flag default stays `project` (back-compat).
+- `harness check` now treats global as a **fallback** — a project with no local block but a global harness installed reports `🅷 5/5 (covered by global)`, matching how Claude Code loads the global `CLAUDE.md` for every project. Use `--project`/`--global` to inspect a single scope.
+- npm package homepage changed to `https://rootstudioyaml.github.io/`; README adds the **@DeepPulseEN** channel and a homepage badge.
+
 ### v2.13.3 (2026-05-04)
 - "Real-world impact" section restructured as a **harness + ratchet adoption cost-savings report**. Added Max(1h)/Pro(5m) cache TTL distinction (different hit-rate headroom), the handoff-before-expiry workflow, and the 2026-05-09 refresh promise. Chart title updated to match.
 

package/README.md

@@ -1,6 +1,8 @@
 **한국어** · [English](./README.en.md)
 
 [![DeepPulse YouTube](https://img.shields.io/badge/YouTube-@DeepPulseKR-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@DeepPulseKR)
+[![DeepPulseEN YouTube](https://img.shields.io/badge/YouTube-@DeepPulseEN-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@DeepPulseEN)
+[![Homepage](https://img.shields.io/badge/Homepage-rootstudioyaml.github.io-2ea44f)](https://rootstudioyaml.github.io/)
 [![npm](https://img.shields.io/npm/v/claude-token-saver.svg)](https://www.npmjs.com/package/claude-token-saver)
 
 # claude-token-saver
@@ -224,6 +226,11 @@ Node.js ≥ 18 · macOS / Linux / Windows / WSL · 의존성 0.
 
 ## 릴리스 노트
 
+### v2.15.0 (2026-06-13)
+- **글로벌 harness init** — `harness init`/`uninit`/`check`에 ratchet과 동일한 스코프 개념 도입. `harness init --global`이 `~/.claude/CLAUDE.md`(+ `~/.claude/ratchet.md`)에 5개 섹션을 한 번에 깔아 **모든 프로젝트에 적용**됩니다. 무플래그 기본값은 종전대로 `project`(하위호환).
+- `harness check`는 이제 글로벌을 **fallback**으로 인정 — 로컬 블록이 없어도 글로벌 harness가 깔려 있으면 `🅷 5/5 (covered by global)`로 표시(Claude Code가 전역 `CLAUDE.md`를 모든 프로젝트에 로드하는 실제 동작과 일치). `--project`/`--global`로 특정 스코프만 조회 가능.
+- npm 패키지 homepage를 `https://rootstudioyaml.github.io/`로 변경, README에 **@DeepPulseEN** 채널·홈페이지 배지 추가.
+
 ### v2.13.3 (2026-05-04)
 - "실제 효과" 섹션을 **harness + ratchet 도입 전후 비용 절감 리포트** 형태로 재구성. Max(1h)/Pro(5m) 캐시 TTL 차이에 따른 히트율 개선 여지 차이 설명, 만료 직전 handoff 워크플로 안내, 7일치 누적 시점(2026-05-09) 갱신 예고 추가. 차트 제목도 동일하게 갱신.
 

package/bin/cli.js

@@ -452,24 +452,44 @@ async function main() {
   //   claude-token-saver harness off | on   # toggle the statusline 🅷 segment
   if (args[0] === 'harness') {
     const sub = args[1];
+    // Scope flags for init/uninit/check (same convention as promote/list/rm):
+    //   --global | --project | --scope=global|project | --scope global|project
+    const parseHarnessScope = (argv, dflt) => {
+      for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--global') return 'global';
+        if (a === '--project') return 'project';
+        if (a === '--scope' && (argv[i + 1] === 'global' || argv[i + 1] === 'project')) return argv[i + 1];
+        if (a.startsWith('--scope=')) {
+          const v = a.slice('--scope='.length);
+          if (v === 'global' || v === 'project') return v;
+        }
+      }
+      return dflt;
+    };
     const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessListRules, harnessRmRule, findProjectRoot } =
       await import('../src/harness.js');
     const { HARNESS_SECTIONS } = await import('../src/harness-templates.js');
     const { loadConfig, saveConfig } = await import('../src/config.js');
 
     if (!sub || sub === 'check') {
+      const scope = parseHarnessScope(args.slice(2), 'auto'); // auto = project, else global fallback
       const root = findProjectRoot();
-      const s = harnessStatus(root);
-      console.log(`🅷 ${s.configured}/${s.total} — ${root}`);
+      const s = harnessStatus(root, { scope });
+      // Only call out "covered by global" when we *fell back* to it (auto), not
+      // when the user explicitly asked for the global scope.
+      const via = (scope === 'auto' && s.source === 'global') ? ' (covered by global ~/.claude/CLAUDE.md)' : '';
+      console.log(`🅷 ${s.configured}/${s.total} — ${s.file}${via}`);
       console.log(`CLAUDE.md: ${s.hasFile ? 'present' : 'missing'}` +
-        (s.hasFile ? `, harness block: ${s.hasBlock ? 'yes' : 'no'}` : ''));
+        (s.hasFile ? `, harness block: ${s.hasBlock ? 'yes' : 'no'}` : '') + ` [${s.source}]`);
       if (s.missing.length) {
         console.log('Missing sections:');
         for (const id of s.missing) {
           const sec = HARNESS_SECTIONS.find((x) => x.id === id);
           console.log(`  - ${id}: ${sec ? sec.heading.replace(/^#+\s*/, '') : ''}`);
         }
-        console.log('\nRun: claude-token-saver harness init');
+        console.log('\nRun: claude-token-saver harness init        (this project)');
+        console.log('  or: claude-token-saver harness init --global  (all projects, ~/.claude/CLAUDE.md)');
       } else {
         console.log('All 5 harness sections present. ✅');
       }
@@ -477,9 +497,10 @@ async function main() {
     }
 
     if (sub === 'init') {
+      const scope = parseHarnessScope(args.slice(2), 'project'); // default project (back-compat)
       const force = hasFlag('--force');
-      const r = harnessInit({ force });
-      console.log(`Project root: ${r.root}`);
+      const r = harnessInit({ force, scope });
+      console.log(`Scope: ${scope}${scope === 'global' ? '  (~/.claude/CLAUDE.md — applies to all projects)' : `  (${r.root})`}`);
       for (const p of r.backedUp) console.log(`Backed up: ${p}`);
       for (const p of r.wrote) console.log(`Wrote:     ${p}`);
       for (const p of r.skipped) console.log(`Skipped:   ${p}`);
@@ -609,9 +630,10 @@ async function main() {
     }
 
     if (sub === 'uninit' || sub === 'remove') {
+      const scope = parseHarnessScope(args.slice(2), 'project');
       const purgeRatchet = args.includes('--purge-ratchet');
-      const r = harnessUninit({ purgeRatchet });
-      console.log(`Project root: ${r.root}`);
+      const r = harnessUninit({ purgeRatchet, scope });
+      console.log(`Scope: ${scope}${scope === 'global' ? '  (~/.claude/CLAUDE.md)' : `  (${r.root})`}`);
       r.removed.forEach((f) => console.log(`  removed: ${f}`));
       r.backedUp.forEach((f) => console.log(`  backup:  ${f}`));
       r.skipped.forEach((f) => console.log(`  skip:    ${f}`));
@@ -816,12 +838,31 @@ async function main() {
   const sessions = await parseAllSessions({ days, projectFilter });
 
   if (sessions.length === 0) {
-    // Statusline must always emit a single line (no multi-line help spam every 300ms)
+    // Statusline must always emit a single line (no multi-line help spam every
+    // 300ms) — but the stdin payload (rate limits, model) is still live even
+    // with an empty analysis window (e.g. `mode 1h` + idle), and cap-warn /
+    // harness are exactly the signals that must not vanish then.
     if (format === 'statusline') {
-      const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR;
-      const gray = colorOk ? '\x1b[90m' : '';
-      const reset = colorOk ? '\x1b[0m' : '';
-      console.log(`${gray}🧠 no session data · ${days}d${reset}`);
+      const { formatNoSession } = await import('../src/formatters/statusline.js');
+      const { statuslineDefaults } = await import('../src/config.js');
+      const cfg = statuslineDefaults();
+      const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR && cfg.color;
+      const isIcon = hasFlag('--icon')
+        ? true
+        : (hasFlag('--no-icon') || hasFlag('--text') ? false : cfg.icon);
+      const stdinJson = readStdinJson();
+      const caps = extractCaps(stdinJson);
+      const model = extractModel(stdinJson);
+      if (caps || model) {
+        try {
+          const { persistSnapshot } = await import('../src/caps-cache.js');
+          persistSnapshot({ caps, model });
+        } catch { /* non-critical */ }
+      }
+      console.log(formatNoSession(
+        { caps, model, windowLabel },
+        { color: colorOk, mode: isIcon ? 'icon' : 'text' },
+      ));
       return;
     }
     console.log('No session data found for the given period.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "2.14.2",
+  "version": "2.16.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
     "type": "git",
     "url": "git+https://github.com/rootstudioyaml/claude-token-saver.git"
   },
-  "homepage": "https://www.youtube.com/@DeepPulseKR",
+  "homepage": "https://rootstudioyaml.github.io/",
   "bugs": {
     "url": "https://github.com/rootstudioyaml/claude-token-saver/issues"
   },

package/src/formatters/statusline.js

@@ -137,6 +137,73 @@ export function pickCapWarn(caps) {
   return candidates[0];
 }
 
+/**
+ * Harness 🅷 segment builder — shared by the full report and the no-session
+ * fallback line. Best-effort: never throws into the statusline (corrupted
+ * CLAUDE.md, permission issue, etc. → null).
+ */
+function buildHarnessSeg(c, isIcon) {
+  try {
+    const harnessInfo = harnessStatusForStatusline(loadConfig());
+    if (!harnessInfo) return null;
+    const icon = isIcon ? '🅷' : 'H';
+    if (harnessInfo.warning) {
+      // Warning state outranks the N/5 count — a runtime issue (repeated
+      // error / no-evidence / racing edits) is more actionable than a
+      // missing ratchet section. Always red so it stands out.
+      return `${c(RED)}${icon}⚠ ${harnessInfo.warning}${c(RESET)}`;
+    }
+    if (harnessInfo.custom) return `${c(CYAN)}${icon} custom${c(RESET)}`;
+    const tone = harnessInfo.configured >= harnessInfo.total ? GREEN : YELLOW;
+    return `${c(tone)}${icon} ${harnessInfo.configured}/${harnessInfo.total}${c(RESET)}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Cap-warn chip builder — shared by the full report and the no-session
+ * fallback line. At 90%+ the user wants to know "when can I send again", so
+ * the wall-clock reset time rides along in the same `🔄 HH:MM` shape as the
+ * always-on usage segments.
+ */
+function buildCapWarnSeg(capWarn, c, isIcon) {
+  if (!capWarn) return null;
+  const pct = Math.round(capWarn.usedPct);
+  const clock = formatResetClock(capWarn.resetsAt);
+  const clockTail = clock ? ` 🔄 ${clock}` : '';
+  if (isIcon) {
+    // Gauge keeps shape parity with the always-on usage segment — the
+    // cap-warn is just the same gauge "filled to alarm". Visual continuity
+    // helps the eye understand "this is the 5H bar I was watching, just red now."
+    const bar = gaugeBar(pct);
+    return `${c(BOLD)}${c(RED)}🚨 ${capWarn.label} ${bar} ${pct}%${clockTail}${c(RESET)}`;
+  }
+  return `${c(BOLD)}${c(RED)}${capWarn.label} cap ${pct}%${clockTail}${c(RESET)}`;
+}
+
+/**
+ * Fallback line for when no session data exists in the analysis window.
+ * The stdin payload (rate limits, model) is still live in that case, and a
+ * 90%+ cap warning is exactly the kind of signal that must not disappear
+ * just because the user has been idle past the window — so cap-warn,
+ * harness, and model chips still render around the "no session data" note.
+ */
+export function formatNoSession({ caps = null, model = null, windowLabel = '' } = {}, { color = true, mode = 'icon' } = {}) {
+  const c = (v) => (color ? v : '');
+  const isIcon = mode === 'icon';
+  const segs = [];
+  const capSeg = buildCapWarnSeg(pickCapWarn(caps), c, isIcon);
+  if (capSeg) segs.push(capSeg);
+  const harnessSeg = buildHarnessSeg(c, isIcon);
+  if (harnessSeg) segs.push(harnessSeg);
+  if (typeof model === 'string' && model.length > 0) {
+    segs.push(isIcon ? `${c(MAGENTA)}🤖 ${model}${c(RESET)}` : `${c(MAGENTA)}${model}${c(RESET)}`);
+  }
+  segs.push(`${c(GRAY)}🧠 no session data${windowLabel ? ` · ${windowLabel}` : ''}${c(RESET)}`);
+  return segs.join(' · ') + (color ? '\x1b[K' : '');
+}
+
 /**
  * @param {object} data - output of main report pipeline (summary, ttl, cost, options, lastActivity)
  * @param {object} [opts]
@@ -144,7 +211,7 @@ export function pickCapWarn(caps) {
  * @param {boolean} [opts.verbose=false] - longer layout with labels
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
- * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, model, hit, ttl, saved, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
+ * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, harness, model, hit, ttl, saved, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
  */
 export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null } = {}) {
   const { summary, ttl, cost, options, lastActivity, contextWindow, spikeChip, caps, model } = data;
@@ -279,28 +346,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // Silent when the project hasn't opted in (no CLAUDE.md and no .claude/);
   // otherwise renders 🅷 5/5 (green) / 🅷 N/5 (yellow) so the user can spot
   // a missing section at a glance and know to run `harness init`.
-  let harnessSeg = null;
-  try {
-    const harnessInfo = harnessStatusForStatusline(loadConfig());
-    if (harnessInfo) {
-      const icon = isIcon ? '🅷' : 'H';
-      if (harnessInfo.warning) {
-        // Warning state outranks the N/5 count — a runtime issue (repeated
-        // error / no-evidence / racing edits) is more actionable than a
-        // missing ratchet section. Always red so it stands out.
-        harnessSeg = `${c(RED)}${icon}⚠ ${harnessInfo.warning}${c(RESET)}`;
-      } else if (harnessInfo.custom) {
-        harnessSeg = `${c(CYAN)}${icon} custom${c(RESET)}`;
-      } else {
-        const tone = harnessInfo.configured >= harnessInfo.total ? GREEN : YELLOW;
-        harnessSeg = `${c(tone)}${icon} ${harnessInfo.configured}/${harnessInfo.total}${c(RESET)}`;
-      }
-    }
-  } catch {
-    // Harness check is best-effort — never break the statusline if the file
-    // read fails (corrupted CLAUDE.md, permission issue, etc.).
-    harnessSeg = null;
-  }
+  const harnessSeg = buildHarnessSeg(c, isIcon);
 
   // Model chip — pulled from Claude Code's stdin payload (`model.display_name`).
   // Cheap identity context: useful when the user toggles between Sonnet/Opus
@@ -322,12 +368,14 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // Today the stdin payload exposes the 5h ("Current session") and 7-day
   // rolling ("Current week") windows; if Anthropic ships more (e.g. a
   // Sonnet-only weekly), they render automatically with derived labels.
-  // Each renders as `{label} {pct}% · {countdown}`. When a window is at >=90%
-  // the cap-warn chip already shouts about it, so we suppress the always-on
-  // segment to avoid duplicate noise.
-  function buildUsageSeg({ labels, info, color: tone }) {
+  // Each renders as `{label} {pct}% · {countdown}`. The window promoted to the
+  // cap-warn chip is suppressed here to avoid duplicate noise — but ONLY that
+  // one. When several windows are at 90%+ the chip shows just the most
+  // imminent, so the others must keep their always-on segment (red) or they'd
+  // vanish from the statusline entirely at the worst possible moment.
+  function buildUsageSeg({ labels, info, color: tone, suppressed }) {
     if (!info || !Number.isFinite(info.usedPct)) return null;
-    if (info.usedPct >= 90) return null; // cap-warn chip handles this case
+    if (suppressed) return null; // cap-warn chip handles this window
     const pct = Math.round(info.usedPct);
     // Show only the wall-clock reset time (e.g. `🔄 21:10`). Absolute time
     // doesn't tick second-by-second so the statusline reads stable, and the
@@ -351,14 +399,20 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     }
     return `${c(tone)}${labels.short} cap ${pct}%${tail}${c(RESET)}`;
   }
-  // Color tone: green when <70%, yellow 70-89% (the segment is suppressed at
-  // 90+% in favor of cap-warn). Lets the user spot "I'm getting close" without
-  // waiting for the alarm chip.
+  // Color tone: green <70%, yellow 70-89%, red 90+% (a 90+% window only
+  // renders here when a *different* window won the cap-warn chip slot).
   function usageTone(info) {
     if (!info || !Number.isFinite(info.usedPct)) return GRAY;
+    if (info.usedPct >= 90) return RED;
     if (info.usedPct >= 70) return YELLOW;
     return GREEN;
   }
+  // Cap-warn chip — leads everything when ANY rate-limit window is at 90%+.
+  // It's the most actionable signal we can show: no point optimizing cache
+  // hits if you're about to be rate-limited anyway. The chip body matches the
+  // English shape `🚨 5H 94%` / `🚨 7D 92%` so history parsers can dedupe on it.
+  // Computed before the usage segments so they know which window it claimed.
+  const capWarn = pickCapWarn(caps);
   const usageSegs = [];
   if (caps && Array.isArray(caps.windows)) {
     for (const win of caps.windows) {
@@ -367,34 +421,13 @@ export function formatReport(data, { color = true, verbose = false, timer = true
         labels,
         info: win,
         color: usageTone(win),
+        suppressed: !!capWarn && capWarn.key === win.key,
       });
       if (seg) usageSegs.push({ key: win.key, seg });
     }
   }
 
-  // Cap-warn chip — leads everything when ANY rate-limit window is at 90%+.
-  // It's the most actionable signal we can show: no point optimizing cache
-  // hits if you're about to be rate-limited anyway. The chip body matches the
-  // English shape `🚨 5H 94%` / `🚨 7D 92%` so history parsers can dedupe on it.
-  const capWarn = pickCapWarn(caps);
-  let capWarnSeg = null;
-  if (capWarn) {
-    const pct = Math.round(capWarn.usedPct);
-    // At 90%+ the user wants to know "when can I send again" — wall-clock is
-    // the actionable bit. Same `🔄 HH:MM` shape as the always-on segments so
-    // the icon's meaning carries over to the alarm chip.
-    const clock = formatResetClock(capWarn.resetsAt);
-    const clockTail = clock ? ` 🔄 ${clock}` : '';
-    if (isIcon) {
-      // Gauge keeps shape parity with the always-on usage segment — the
-      // cap-warn is just the same gauge "filled to alarm". Visual continuity
-      // helps the eye understand "this is the 5H bar I was watching, just red now."
-      const bar = gaugeBar(pct);
-      capWarnSeg = `${c(BOLD)}${c(RED)}🚨 ${capWarn.label} ${bar} ${pct}%${clockTail}${c(RESET)}`;
-    } else {
-      capWarnSeg = `${c(BOLD)}${c(RED)}${capWarn.label} cap ${pct}%${clockTail}${c(RESET)}`;
-    }
-  }
+  const capWarnSeg = buildCapWarnSeg(capWarn, c, isIcon);
 
   // Warning chip leads — a glance at the statusline catches "something's wrong"
   // before parsing any numbers. Healthy states have no chip and look unchanged.
@@ -431,7 +464,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   if (want('period')) segs.push(periodSeg);
   // Trailing erase-to-end-of-line so any leftover characters from a previous
   // (longer) statusline render don't bleed into ours. \x1b[K is the standard
-  // "erase from cursor to EOL" CSI; safe on any ANSI-compatible terminal and
-  // a no-op when stdout isn't a TTY.
-  return segs.join(' · ') + '\x1b[K';
+  // "erase from cursor to EOL" CSI. Only emitted when color (i.e. ANSI) is
+  // allowed — --no-color/NO_COLOR consumers expect escape-free output.
+  return segs.join(' · ') + (color ? '\x1b[K' : '');
 }

package/src/harness-analyzer.cjs

@@ -12,9 +12,11 @@
  *    keywords). <30% → ⚠ no-evidence — high chance the model is reporting
  *    "done" without showing it.
  *
- * 3. PEV-skip — many tool_use calls (5+) in the last 15 turns with no plan
- *    signal (no TodoWrite, no "plan"/"Phase"/"단계" mention). Suggests the
- *    model is racing through edits without a verify pass.
+ * 3. PEV-skip — many *mutating* tool_use calls (Edit/Write/Bash…, 5+) in the
+ *    last 15 assistant turns with no plan signal (no TodoWrite, no
+ *    "plan"/"Phase"/"단계" mention). Suggests the model is racing through
+ *    edits without a verify pass. Read-only exploration (Read/Grep/Glob)
+ *    deliberately doesn't count — reading five files is research, not racing.
  *
  * CommonJS so hook.cjs can `require()` it without a bundler step.
  */
@@ -28,10 +30,14 @@ const os = require('node:os');
 const STATE_DIR = stateDir();
 const STATE_PATH = path.join(STATE_DIR, 'harness-state.json');
 
-const RECENT_TURNS = 15;        // PEV / evidence window
+const RECENT_TURNS = 15;        // PEV / evidence window (assistant turns)
 const RATCHET_TURNS = 30;       // ratchet-candidate window
 const EVIDENCE_THRESHOLD = 0.3; // <30% → ⚠ no-evidence
 const PEV_TOOLUSE_THRESHOLD = 5;
+// Tools that change state. Only these count toward PEV-skip — an agentic
+// session trivially racks up 5+ *read* tool calls (Read/Grep/Glob) while
+// researching, which is exactly the behavior we don't want to punish.
+const MUTATING_TOOL_RE = /^(edit|write|multiedit|notebookedit|bash)$/i;
 
 function stateDir() {
   if (process.platform === 'win32') {
@@ -167,39 +173,42 @@ function findRatchetCandidates(entries) {
  * the immediate next user message also count as "shown the work."
  */
 function computeEvidenceRate(entries) {
-  const recent = entries.slice(-RECENT_TURNS * 2); // both user/assistant
-  const assistants = [];
-  for (let i = 0; i < recent.length; i++) {
-    const e = recent[i];
-    if (e && e.type === 'assistant') {
-      const text = assistantText(e.message);
-      let proof = looksLikeEvidence(text);
-      // If the *next* entry is a user message with tool_result blocks, count
-      // that as evidence for the assistant turn that triggered it.
-      const next = recent[i + 1];
-      if (!proof && next && next.type === 'user' && toolResultsIn(next.message).length > 0) {
-        proof = true;
-      }
-      assistants.push(proof);
+  // Window by *assistant turns*, not raw JSONL entries — one agentic turn can
+  // span dozens of entries, so an entry-sliced window covered only 1-2 real
+  // turns and made the rate jumpy.
+  const idxs = [];
+  for (let i = 0; i < entries.length; i++) {
+    if (entries[i] && entries[i].type === 'assistant') idxs.push(i);
+  }
+  const recentIdxs = idxs.slice(-RECENT_TURNS);
+  if (recentIdxs.length === 0) return null;
+  let proofCount = 0;
+  for (const i of recentIdxs) {
+    const text = assistantText(entries[i].message);
+    let proof = looksLikeEvidence(text);
+    // If the *next* entry is a user message with tool_result blocks, count
+    // that as evidence for the assistant turn that triggered it.
+    const next = entries[i + 1];
+    if (!proof && next && next.type === 'user' && toolResultsIn(next.message).length > 0) {
+      proof = true;
     }
+    if (proof) proofCount++;
   }
-  if (assistants.length === 0) return null;
-  const proofCount = assistants.filter(Boolean).length;
-  return proofCount / assistants.length;
+  return proofCount / recentIdxs.length;
 }
 
 function computePevSkip(entries) {
-  const recent = entries.slice(-RECENT_TURNS);
-  let toolUseCount = 0;
+  const assistants = entries.filter((e) => e && e.type === 'assistant');
+  const recent = assistants.slice(-RECENT_TURNS);
+  let mutatingCount = 0;
   let planSignal = false;
   for (const e of recent) {
-    if (!e || e.type !== 'assistant') continue;
     const text = assistantText(e.message);
     const tus = toolUsesIn(e.message);
-    toolUseCount += tus.length;
+    mutatingCount += tus.filter((t) => MUTATING_TOOL_RE.test(t.name || '')).length;
     if (looksLikePlanSignal(text, tus)) planSignal = true;
   }
-  return toolUseCount >= PEV_TOOLUSE_THRESHOLD && !planSignal;
+  return mutatingCount >= PEV_TOOLUSE_THRESHOLD && !planSignal;
 }
 
 function analyzeTranscript(transcriptPath, opts) {

package/src/harness.js

@@ -67,28 +67,43 @@ function resolveRatchetPath(scope, root) {
   return scope === 'global' ? globalRatchetMdPath() : ratchetMdPath(root);
 }
 
+// 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).
+function globalClaudeMdPath() {
+  return join(homedir(), '.claude', 'CLAUDE.md');
+}
+
+function resolveClaudeMdPath(scope, root) {
+  return scope === 'global' ? globalClaudeMdPath() : claudeMdPath(root);
+}
+
 /**
  * Count how many of the 5 harness sections appear in the project's CLAUDE.md.
  * Returns { configured, total, missing, hasBlock }. Cheap enough to call from
  * statusline — single file read + regex.
  */
-export function harnessStatus(root = findProjectRoot()) {
-  const path = claudeMdPath(root);
-  if (!existsSync(path)) {
+// Count harness sections in a single CLAUDE.md file. Shared by both scopes.
+function statusForFile(filePath) {
+  if (!existsSync(filePath)) {
     return {
       configured: 0,
       total: HARNESS_SECTIONS.length,
       missing: HARNESS_SECTIONS.map((s) => s.id),
       hasBlock: false,
       hasFile: false,
-      root,
+      optOut: false,
+      custom: false,
+      file: filePath,
     };
   }
   let content = '';
   try {
-    content = readFileSync(path, 'utf8');
+    content = readFileSync(filePath, 'utf8');
   } catch {
-    return { configured: 0, total: HARNESS_SECTIONS.length, missing: [], hasBlock: false, hasFile: true, root };
+    // Unreadable file (permissions, etc.) — report every section missing so
+    // `harness check` can't print "All 5 sections present ✅" over a 0/5.
+    return { configured: 0, total: HARNESS_SECTIONS.length, missing: HARNESS_SECTIONS.map((s) => s.id), hasBlock: false, hasFile: true, optOut: false, custom: false, file: filePath };
   }
   const hasBlock = content.includes(HARNESS_BLOCK_BEGIN);
   // Opt-out marker — when the user intentionally customizes the harness block
@@ -114,10 +129,30 @@ export function harnessStatus(root = findProjectRoot()) {
     hasFile: true,
     optOut,
     custom,
-    root,
+    file: filePath,
   };
 }
 
+/**
+ * Harness status for a project, with scope control:
+ *   scope 'project' — count only <root>/CLAUDE.md
+ *   scope 'global'  — count only ~/.claude/CLAUDE.md
+ *   scope 'auto' (default) — use the project file if it carries the harness
+ *     block, otherwise fall back to the global file. This makes a project that
+ *     relies on a globally-installed harness report 🅷 5/5 (covered by global),
+ *     matching reality: Claude Code loads ~/.claude/CLAUDE.md for every project.
+ * The returned `source` ('project'|'global') tells callers which file was used.
+ */
+export function harnessStatus(root = findProjectRoot(), { scope = 'auto' } = {}) {
+  if (scope === 'project') return { ...statusForFile(claudeMdPath(root)), root, source: 'project' };
+  if (scope === 'global') return { ...statusForFile(globalClaudeMdPath()), root, source: 'global' };
+  const project = statusForFile(claudeMdPath(root));
+  if (project.hasBlock) return { ...project, root, source: 'project' };
+  const global = statusForFile(globalClaudeMdPath());
+  if (global.hasBlock) return { ...global, root, source: 'global' };
+  return { ...project, root, source: 'project' };
+}
+
 /**
  * harness init — write CLAUDE.md (single file, 5 sections) + .claude/ratchet.md.
  * If CLAUDE.md exists, back it up to CLAUDE.md.bak-YYYYMMDD-HHMMSS first
@@ -125,10 +160,10 @@ export function harnessStatus(root = findProjectRoot()) {
  *
  * Returns { wrote: [], backedUp: [], skipped: [] } so the CLI can report.
  */
-export function harnessInit({ root = findProjectRoot(), force = false } = {}) {
-  const cmPath = claudeMdPath(root);
-  const rmPath = ratchetMdPath(root);
-  const result = { wrote: [], backedUp: [], skipped: [], root };
+export function harnessInit({ root = findProjectRoot(), force = false, scope = 'project' } = {}) {
+  const cmPath = resolveClaudeMdPath(scope, root); // global → ~/.claude/CLAUDE.md
+  const rmPath = resolveRatchetPath(scope, root);  // global → ~/.claude/ratchet.md
+  const result = { wrote: [], backedUp: [], skipped: [], root, scope };
 
   // CLAUDE.md
   const block = harnessClaudeMdBlock();
@@ -158,11 +193,12 @@ export function harnessInit({ root = findProjectRoot(), force = false } = {}) {
       result.wrote.push(cmPath + ' (harness block appended)');
     }
   } else {
+    mkdirSync(dirname(cmPath), { recursive: true }); // global: ensure ~/.claude exists
     writeFileSync(cmPath, block);
     result.wrote.push(cmPath);
   }
 
-  // .claude/ratchet.md (only if missing — don't clobber user-grown rules)
+  // ratchet.md (only if missing — don't clobber user-grown rules)
   if (!existsSync(rmPath)) {
     mkdirSync(dirname(rmPath), { recursive: true });
     writeFileSync(rmPath, harnessRatchetMdInitial());
@@ -181,10 +217,10 @@ export function harnessInit({ root = findProjectRoot(), force = false } = {}) {
  *
  * Returns { removed: [], backedUp: [], skipped: [] }.
  */
-export function harnessUninit({ root = findProjectRoot(), purgeRatchet = false } = {}) {
-  const cmPath = claudeMdPath(root);
-  const rmPath = ratchetMdPath(root);
-  const result = { removed: [], backedUp: [], skipped: [], root };
+export function harnessUninit({ root = findProjectRoot(), purgeRatchet = false, scope = 'project' } = {}) {
+  const cmPath = resolveClaudeMdPath(scope, root);
+  const rmPath = resolveRatchetPath(scope, root);
+  const result = { removed: [], backedUp: [], skipped: [], root, scope };
 
   if (existsSync(cmPath)) {
     const existing = readFileSync(cmPath, 'utf8');
@@ -300,13 +336,24 @@ export function harnessStatusForStatusline(cfg, { root } = {}) {
   if (!status.hasFile && !existsSync(join(projectRoot, '.claude'))) return null;
   if (status.optOut) return null;
   // Attach a warning derived from the analyzer state file (if any). Precedence:
-  //   ratchet? > no-evidence > PEV-skip. Only surfaces when the state's
-  //   sessionId or cwd matches this project, so unrelated sessions don't leak.
+  //   ratchet? > no-evidence > PEV-skip. Guards, in order:
+  //   - freshness: the hook rewrites the state on every tool use, so anything
+  //     older than WARNING_TTL_MS is a dead session's leftovers — a red 🅷⚠
+  //     must never linger for days after the triggering session ended.
+  //   - project match: state.cwd is the *session* cwd, which may be a subdir
+  //     of the repo, while projectRoot is the walked-up root. Normalize both
+  //     through findProjectRoot so launching Claude Code in a subdirectory
+  //     still surfaces (and correctly scopes) the warning. A state with no
+  //     cwd at all is unattributable — stay silent rather than leak it into
+  //     every project.
+  const WARNING_TTL_MS = 30 * 60 * 1000;
   const state = readHarnessState();
   let warning = null;
   if (state) {
-    const matches = (state.cwd && state.cwd === projectRoot) || !state.cwd;
-    if (matches) {
+    const ts = state.timestamp ? Date.parse(state.timestamp) : NaN;
+    const fresh = Number.isFinite(ts) && Date.now() - ts <= WARNING_TTL_MS;
+    const matches = !!state.cwd && findProjectRoot(state.cwd) === projectRoot;
+    if (fresh && matches) {
       if (state.ratchetCandidate && state.ratchetCandidate.count >= 2) {
         const id = state.ratchetCandidate.id || 1;
         warning = `ratchet? #${id}`;