claude-cache-keepalive 0.1.2 → 0.1.4

package/README.md

@@ -6,11 +6,11 @@
 
 Keep [Claude Code](https://claude.com/claude-code)'s **prompt cache warm while you're idle**, so coming back to a session you stepped away from doesn't pay a full cache‑miss.
 
-It runs `claude` inside a PTY it controls (via [node-pty](https://github.com/microsoft/node-pty)) and, when you've been idle past your plan's cache TTL, injects a tiny keepalive so the cache stays warm. Because injection is an in‑process PTY write, **it keeps working when the window is unfocused, minimized, or in the background** — only closing the window stops it.
+It runs `claude` inside a PTY it controls (via [node-pty](https://github.com/microsoft/node-pty)) and, when you've been idle past your cache's TTL, injects a tiny keepalive so the cache stays warm. Because injection is an in‑process PTY write, **it keeps working when the window is unfocused, minimized, or in the background** — only closing the window stops it.
 
 Cross‑platform, **no tmux required**. This is the missing piece for setups (Windows / Git Bash, plain terminals) where the usual tmux‑based keepalive isn't available.
 
-> ⚠️ **Honest note — this uses your usage/quota.** Keeping the cache warm means sending a small message (`hi`) when you go idle, which counts against your plan usage and leaves `hi` turns in the conversation. It only fires after a long idle (≈58 min on Max, ≈4 min on Pro) with a one‑TTL cooldown, so it's conservative — but it is opt‑in by design. If that trade‑off isn't for you, don't use it.
+> ⚠️ **Honest note — this uses your usage/quota.** Keeping the cache warm means sending a small message (`hi`) when you go idle, which counts against your plan usage and leaves `hi` turns in the conversation. It only fires after a long idle (≈58 min on a 1‑hour cache, ≈4 min on a 5‑minute cache) with a one‑TTL cooldown, so it's conservative — but it is opt‑in by design. If that trade‑off isn't for you, don't use it.
 
 ## Install
 
@@ -40,9 +40,10 @@ It's transparent — type and use claude exactly as normal (no `Ctrl-b` prefix,
 
 - **PTY host** — `cwarm` spawns `claude` inside a pseudo‑terminal it owns and transparently pipes your keyboard ↔ claude ↔ screen (and window resizes). This is the same approach tmux / expect / VS Code's terminal use, and the only robust way to inject input into a terminal program.
 - **Idle detection** — idle = time since your last **message**, measured from the newest transcript file under `~/.claude/projects/`. This is what actually governs cache age: scrolling, arrow‑key reading, or a half‑typed prompt are terminal input but don't refresh the cache, so they must *not* count as activity. (Earlier versions timed keystrokes, which let the cache go cold while you were reading.)
-- **Plan‑aware** — reads your plan from `~/.claude/.credentials.json`:
-  - **Max** → cache TTL 1 h → inject after ~58 min idle, cooldown 1 h.
-  - **Pro** → cache TTL 5 min → inject after ~4 min idle, cooldown 5 min.
+- **TTL‑aware (measured, not guessed)** — the cache TTL is read straight from the transcript's `message.usage.cache_creation`, not inferred from your subscription:
+  - any recent turn wrote `ephemeral_1h_input_tokens` → **1 h cache** → inject after ~58 min idle, cooldown 1 h.
+  - only `ephemeral_5m_input_tokens` (or no evidence yet) → **5 min cache** (conservative) → inject after ~4 min idle, cooldown 5 min.
+  - This survives client‑version, env‑var and server‑flag changes that the plan string can't see (e.g. a Pro account can still get a 1 h cache).
 - **Focus/minimize independent** — injection is an in‑process `pty.write`, unrelated to window state. Only closing the window (ending the host process) stops it.
 
 ## Optional: cache‑countdown statusline
@@ -91,9 +92,9 @@ Environment variables (mostly for testing / advanced use):
 
 讓 [Claude Code](https://claude.com/claude-code) 的 **prompt cache 在你離開時保持溫熱**，回來時就不必再付一次完整的 cache‑miss。
 
-`cwarm` 把 `claude` 跑在自己控制的 PTY 裡；當你閒置超過方案的 cache TTL 時，注入一個極小的 keepalive 訊息讓 cache 不過期。因為注入是行程內部的 PTY 寫入，**視窗非焦點、縮小、在背景都照常運作**——只有關閉視窗才會停。跨平台、**不需要 tmux**。
+`cwarm` 把 `claude` 跑在自己控制的 PTY 裡；當你閒置超過 cache 的 TTL 時，注入一個極小的 keepalive 訊息讓 cache 不過期。因為注入是行程內部的 PTY 寫入，**視窗非焦點、縮小、在背景都照常運作**——只有關閉視窗才會停。跨平台、**不需要 tmux**。
 
-> ⚠️ **誠實說明**：保溫＝閒置時送一則小訊息（`hi`），會消耗你的方案用量、並在對話留下 `hi` 紀錄。只在長時間閒置後才觸發（Max 約 58 分、Pro 約 4 分）且有冷卻，屬保守設計、明確 opt‑in。不接受這個取捨就別用。
+> ⚠️ **誠實說明**：保溫＝閒置時送一則小訊息（`hi`），會消耗你的方案用量、並在對話留下 `hi` 紀錄。只在長時間閒置後才觸發（1h cache 約 58 分、5m cache 約 4 分）且有冷卻，屬保守設計、明確 opt‑in。不接受這個取捨就別用。
 
 - **安裝**：`npm install -g claude-cache-keepalive`
 - **使用**：`cwarm`（＝`claude --continue` 跑在保溫 host 裡；其餘參數原樣轉給 claude）
@@ -101,6 +102,20 @@ Environment variables (mostly for testing / advanced use):
 - **選配 statusline**（顯示 `♻️ cache 58m12s` 倒數；會先備份、包裝既有 statusline、可一鍵還原）：`cwarm setup` / `cwarm setup --remove`
 - **限制**：不能 detach（關視窗＝結束，但縮小／背景照常保溫）。
 
+## Changelog
+
+### 0.1.4
+- **Fix:** the terminal could be left unusable after `/exit` or Ctrl‑C (keystrokes garbled / no usable input). The PTY host now restores the terminal on every exit path: it emits an explicit reset (disabling alt‑screen, bracketed‑paste, mouse, cursor‑hide, and — critically on Windows — `win32‑input‑mode` `?9001` and focus‑reporting `?1004`, which otherwise make the shell receive keystrokes as unparseable `ESC[…_` packets) and flushes stdout before exiting. Adds a `SIGINT` handler that forwards `0x03` to claude instead of letting the host be killed before cleanup, plus `SIGHUP`/`exit` safety restores.
+
+### 0.1.3
+- **Change:** the cache TTL is now **measured from the transcript** (`message.usage.cache_creation`'s `ephemeral_1h` / `ephemeral_5m` tokens) instead of being guessed from your subscription plan. A recent 1h write → 1h regime; only 5m writes (or no evidence) → 5m regime (conservative). This drops the `~/.claude/.credentials.json` read entirely and is correct even when a Pro account gets a 1h cache. Adds `transcriptPath` / `readTtlRegime` / `detectTtlRegime` / `regimeParams`; removes `detectPlan` / `planParams`.
+
+### 0.1.2
+- **Fix:** idle is now measured from the newest transcript file's mtime — i.e. time since your last *message* — instead of keystrokes. Scrolling, arrow‑key reading, or a half‑typed prompt no longer reset the idle timer, so the keepalive actually fires while you're reading and the cache stops going cold. Adds `encodeProjectDir` / `transcriptMtimeMs` / `transcriptIdleMs`.
+
+### 0.1.0
+- Initial release. (0.1.1 was a version‑only bump and was never published to npm.)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-cache-keepalive",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Keep Claude Code's prompt cache warm while idle, by running claude inside a PTY host and injecting a tiny keepalive when you step away. Cross-platform, no tmux required.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -27,8 +27,10 @@ Usage:
 Everything except the 'setup' subcommand is passed straight to claude
 (e.g. \`cwarm --version\`, \`cwarm resume\`, \`cwarm -p "..."\`).
 
-Keepalive only fires after you've been idle past the plan threshold
-(max ~58min / pro ~4min). Pause anytime:  touch ~/.claude/cwarm.disabled
+Keepalive only fires after you've been idle past the cache-TTL threshold.
+The TTL is auto-detected from the transcript's cache_creation (1h cache ->
+fire after ~58min idle; 5m cache -> ~4min), not guessed from your plan.
+Pause anytime:  touch ~/.claude/cwarm.disabled
 Log:  ~/.claude/cwarm-keepalive.log
 `);
 }

package/src/host.mjs

@@ -5,7 +5,7 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { defaultClaudeDir, planParams, detectPlan, decideInject, transcriptIdleMs } from './keepalive.mjs';
+import { defaultClaudeDir, regimeParams, detectTtlRegime, decideInject, transcriptIdleMs } from './keepalive.mjs';
 
 const require = createRequire(import.meta.url);
 const isWin = process.platform === 'win32';
@@ -69,30 +69,52 @@ export function startHost(opts = {}) {
 
   let lastFire = 0;
   const timer = setInterval(() => {
-    const plan = detectPlan(claudeDir);
-    const { ttl, idleThreshold } = planParams(plan, overrides);
+    const cwd = process.cwd();
+    const regime = detectTtlRegime(claudeDir, cwd);           // 從 transcript 實測 1h/5m，不再猜方案
+    const { ttl, idleThreshold } = regimeParams(regime, overrides);
     const now = Date.now();
-    const idleMs = transcriptIdleMs(claudeDir, process.cwd(), now);
+    const idleMs = transcriptIdleMs(claudeDir, cwd, now);
     if (decideInject({ now, idleMs, lastFire, idleThreshold, ttl, disabled: fs.existsSync(DISABLE) })) {
       ptyProc.write(msg + '\r');
       lastFire = now;
       const idle = idleMs == null ? -1 : Math.round(idleMs / 1000);
-      try { fs.appendFileSync(LOG, `${new Date().toISOString()} inject "${msg}" plan=${plan} idle=${idle}s\n`); } catch {}
+      try { fs.appendFileSync(LOG, `${new Date().toISOString()} inject "${msg}" regime=${regime ?? 'unknown'} idle=${idle}s\n`); } catch {}
     }
   }, tickMs);
 
   // ---- 收尾 ----
-  function restore() {
+  // claude（TUI）會開 alt-screen / bracketed-paste / mouse / 隱藏游標等終端模式。正常 /exit 時它自己會還原，
+  // 但 (1) 被 Ctrl-C 中斷時來不及還原；(2) 在 onExit 內立刻 process.exit() 會跟 claude 最後一段輸出（含還原
+  // 序列）賽跑而把它截斷。任一情況都會讓真終端卡在這些模式 → 回到 shell 後「鍵盤輸入不正常」。
+  // 故 shutdown()：還原 raw mode + 主動補一份終端還原序列 + 等 stdout flush 再退出。
+  // 關鍵（Windows）：node-pty 啟動時對真終端開了 ?9001h(win32-input-mode) 與 ?1004h(focus reporting)，
+  // 若沒關掉，回到 shell 後終端會把每個鍵碼以 ESC[…_ 封包送出，readline 無法解析 → 鍵盤輸入全亂。
+  // ?2004=bracketed paste、?1000/1002/1003/1006=mouse、?25=cursor、?1049=alt-screen、?9001=win32-input、?1004=focus。
+  const RESET = '\x1b[?2004l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?25h\x1b[?1049l\x1b[?9001l\x1b[?1004l\x1b[0m';
+  let exiting = false;
+  function shutdown(code) {
+    if (exiting) return;
+    exiting = true;
+    clearInterval(timer);
     try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch {}
     try { process.stdin.pause(); } catch {}
+    try { process.stdout.write(RESET, () => process.exit(code)); }
+    catch { process.exit(code); }
+    setTimeout(() => process.exit(code), 200).unref(); // 保險：flush callback 沒回也強制退出
   }
-  ptyProc.onExit(({ exitCode }) => {
-    clearInterval(timer);
-    restore();
-    process.exit(exitCode || 0); // node-pty 會卡住 event loop，必須主動退出
+  ptyProc.onExit(({ exitCode }) => shutdown(exitCode || 0)); // node-pty 會卡住 event loop，必須主動退出
+  // Windows：真主控台的 Ctrl-C 以 SIGINT 送到 host（claude 在獨立 ConPTY、收不到真主控台的 Ctrl-C），
+  // 轉成 0x03 寫進 pty 交給 claude 自己處理；不要讓 host 被預設行為直接殺掉（那會跳過終端還原 → 卡 raw mode）。
+  // Unix raw mode 下 Ctrl-C 是位元組(0x03)、不觸發 SIGINT，故此 handler 不影響 Unix。
+  process.on('SIGINT', () => { try { ptyProc.write('\x03'); } catch {} });
+  process.on('SIGTERM', () => shutdown(0));
+  process.on('SIGHUP', () => shutdown(0));
+  // 任何路徑退出都殺掉 pty，並盡力（同步）還原終端，作為最後保險。
+  process.on('exit', () => {
+    try { ptyProc.kill(); } catch {}
+    try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch {}
+    try { process.stdout.write(RESET); } catch {}
   });
-  process.on('exit', () => { try { ptyProc.kill(); } catch {} });
-  process.on('SIGTERM', () => { try { ptyProc.kill(); } catch {} process.exit(0); });
 
   return ptyProc;
 }

package/src/keepalive.mjs

@@ -1,16 +1,17 @@
-// keepalive.mjs — 決策邏輯 + plan / 閒置偵測（無 PTY，便於單元測試）。
+// keepalive.mjs — 決策邏輯 + TTL 檔位 / 閒置偵測（無 PTY，便於單元測試）。
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-// plan → { ttl(秒), idleThreshold(秒) }。對齊各家慣例：max 提早 ~2 分注入、pro 提早 1 分。
-export const PLAN_PARAMS = {
-  max: { ttl: 3600, idleThreshold: 3480 },
-  pro: { ttl: 300, idleThreshold: 240 },
+// TTL 檔位 → { ttl(秒), idleThreshold(秒) }。long=1h cache、short=5m cache。
+// 提早注入幅度對齊各家慣例：long 提早 ~2 分、short 提早 1 分。
+export const REGIME_PARAMS = {
+  long: { ttl: 3600, idleThreshold: 3480 },
+  short: { ttl: 300, idleThreshold: 240 },
 };
 
-export function planParams(plan, overrides = {}) {
-  const base = PLAN_PARAMS[plan] || PLAN_PARAMS.pro;
+export function regimeParams(regime, overrides = {}) {
+  const base = REGIME_PARAMS[regime] || REGIME_PARAMS.short; // 未知一律 short（保守，門檻短不讓 cache 冷掉）
   return {
     ttl: overrides.ttl ?? base.ttl,
     idleThreshold: overrides.idleThreshold ?? base.idleThreshold,
@@ -21,52 +22,53 @@ export function defaultClaudeDir() {
   return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 }
 
-// 從 Claude Code 憑證判方案；讀不到一律當 'pro'（保守）。
-export function detectPlan(claudeDir = defaultClaudeDir()) {
-  try {
-    const cred = JSON.parse(fs.readFileSync(path.join(claudeDir, '.credentials.json'), 'utf8'));
-    return cred?.claudeAiOauth?.subscriptionType === 'max' ? 'max' : 'pro';
-  } catch {
-    return 'pro';
-  }
-}
-
 // Claude Code 把 transcript 存在 ~/.claude/projects/<編碼後的 cwd>/<uuid>.jsonl，
 // 編碼規則為「非英數字元一律換成 '-'」（例：C:\temp\scripts\cwarm → C--temp-scripts-cwarm）。
 export function encodeProjectDir(cwd) {
   return String(cwd).replace(/[^a-zA-Z0-9]/g, '-');
 }
 
-// 某資料夾內所有 *.jsonl 的最新 mtime（毫秒）；沒有則 null。
-function newestJsonlMtime(dir) {
+// 某資料夾內 mtime 最新的 *.jsonl 完整路徑；沒有則 null。
+function newestJsonlPath(dir) {
   let entries;
   try { entries = fs.readdirSync(dir); } catch { return null; }
-  let newest = null;
+  let best = null, bestM = null;
   for (const name of entries) {
     if (!name.endsWith('.jsonl')) continue;
     try {
       const m = fs.statSync(path.join(dir, name)).mtimeMs;
-      if (newest == null || m > newest) newest = m;
+      if (bestM == null || m > bestM) { bestM = m; best = path.join(dir, name); }
     } catch { /* skip unreadable */ }
   }
-  return newest;
+  return best;
 }
 
-// 本 session transcript 的最新 mtime（毫秒）：優先 cwd 對應的 project 資料夾，
+// 本 session transcript 的完整路徑：優先 cwd 對應的 project 資料夾，
 // 找不到再退回 projects 底下全域最新（cwarm 本就假設單一 session）。null = 完全找不到。
-export function transcriptMtimeMs(claudeDir, cwd) {
+export function transcriptPath(claudeDir, cwd) {
   const projects = path.join(claudeDir, 'projects');
-  const direct = newestJsonlMtime(path.join(projects, encodeProjectDir(cwd)));
+  const direct = newestJsonlPath(path.join(projects, encodeProjectDir(cwd)));
   if (direct != null) return direct;
   let subdirs;
   try { subdirs = fs.readdirSync(projects, { withFileTypes: true }); } catch { return null; }
-  let newest = null;
+  let best = null, bestM = null;
   for (const d of subdirs) {
     if (!d.isDirectory()) continue;
-    const m = newestJsonlMtime(path.join(projects, d.name));
-    if (m != null && (newest == null || m > newest)) newest = m;
+    const p = newestJsonlPath(path.join(projects, d.name));
+    if (p == null) continue;
+    try {
+      const m = fs.statSync(p).mtimeMs;
+      if (bestM == null || m > bestM) { bestM = m; best = p; }
+    } catch { /* skip */ }
   }
-  return newest;
+  return best;
+}
+
+// 本 session transcript 的最新 mtime（毫秒）；null = 完全找不到。
+export function transcriptMtimeMs(claudeDir, cwd) {
+  const p = transcriptPath(claudeDir, cwd);
+  if (!p) return null;
+  try { return fs.statSync(p).mtimeMs; } catch { return null; }
 }
 
 // 距上次訊息（transcript 寫入）多久（毫秒）；找不到 transcript 回 null。
@@ -77,6 +79,53 @@ export function transcriptIdleMs(claudeDir, cwd, now = Date.now()) {
   return m == null ? null : now - m;
 }
 
+// 讀 transcript 尾端，判斷這個 session 實際拿到的 cache TTL 檔位。
+// 回傳 'long'(1h) / 'short'(5m) / null（找不到可判讀的 cache_creation）。
+// 為什麼讀 transcript 而非帳號方案：message.usage.cache_creation 的
+// ephemeral_1h_input_tokens / ephemeral_5m_input_tokens 是 API 親口回報「這批 token
+// 寫進哪個 TTL 桶」的實測值；subscriptionType 只是間接猜測，且會被 client 版本、
+// 環境變數、伺服器端旗標影響而失準（實測 pro 帳號也可能拿到 1h）。
+export function readTtlRegime(tpath, { maxBytes = 65536, scanTurns = 8 } = {}) {
+  if (!tpath) return null;
+  let size, buf;
+  let fd = null;
+  try {
+    size = fs.statSync(tpath).size;
+    const start = Math.max(0, size - maxBytes);
+    const len = size - start;
+    buf = Buffer.alloc(len);
+    fd = fs.openSync(tpath, 'r');
+    fs.readSync(fd, buf, 0, len, start);
+  } catch {
+    return null;
+  } finally {
+    if (fd != null) { try { fs.closeSync(fd); } catch {} }
+  }
+  let lines = buf.toString('utf8').split(/\r?\n/);
+  if (size > maxBytes && lines.length) lines = lines.slice(1); // 丟掉被切半的第一行
+  let sawShort = false;
+  let examined = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    if (!obj || obj.type !== 'assistant') continue;
+    const cc = obj.message && obj.message.usage && obj.message.usage.cache_creation;
+    if (!cc || typeof cc !== 'object') continue;
+    const h = cc.ephemeral_1h_input_tokens || 0;
+    const m = cc.ephemeral_5m_input_tokens || 0;
+    if (h > 0) return 'long';                 // 最近任一回合寫過 1h → 1h 檔位（決定性）
+    if (m > 0) { sawShort = true; if (++examined >= scanTurns) break; } // 只看最近數筆有寫 cache 的回合
+  }
+  return sawShort ? 'short' : null;
+}
+
+// 找出本 session transcript 並判斷 TTL 檔位。'long' / 'short' / null。
+export function detectTtlRegime(claudeDir, cwd, opts) {
+  return readTtlRegime(transcriptPath(claudeDir, cwd), opts);
+}
+
 // 純決策：現在該不該注入 keepalive？idleMs = 距上次訊息多久（由 transcriptIdleMs 算）。
 export function decideInject({ now, idleMs, lastFire, idleThreshold, ttl, disabled }) {
   if (disabled) return false;                          // 暫停開關

package/src/statusline/segment.mjs

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { defaultClaudeDir, detectPlan } from '../keepalive.mjs';
+import { defaultClaudeDir, readTtlRegime, regimeParams } from '../keepalive.mjs';
 
 const claudeDir = defaultClaudeDir();
 const ORIG = path.join(claudeDir, 'cwarm-statusline-orig.json');
@@ -13,14 +13,14 @@ function readStdin() {
   try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
 }
 
-// cache 倒數段：用 transcript mtime 當 idle、plan 決定 TTL（max 1h / pro 5min）。
+// cache 倒數段：用 transcript mtime 當 idle、用 transcript 實測的 cache_creation 判 TTL（1h / 5m）。
 function cacheSegment(payload) {
   const tp = payload?.transcript_path;
   if (!tp) return '';
   let mtimeMs;
   try { mtimeMs = fs.statSync(tp).mtimeMs; } catch { return ''; }
-  const plan = detectPlan(claudeDir);
-  const ttl = plan === 'max' ? 3600 : 300;
+  const { ttl } = regimeParams(readTtlRegime(tp));   // 'long'→3600 / 'short'|null→300
+
   const idle = Math.max(0, Math.floor((Date.now() - mtimeMs) / 1000));
   const rem = ttl - idle;
   if (rem <= 0) return `\u{1F534} cache ${Math.floor(idle / 60)}m`;      // 🔴 已冷