claude-cache-keepalive 0.1.17 → 0.1.18

package/README.md

@@ -159,6 +159,10 @@ Environment variables (mostly for testing / advanced use):
 - If you walk away with a half‑typed draft and stay idle past the threshold, the keepalive's `Esc` clears the draft before sending `hi`. Rare.
 - **A genuinely blocking prompt can't be kept warm.** While Claude Code waits on a mandatory answer, no API turn can happen, so the cache may cool during that window; warming resumes automatically once you answer.
 
+## FAQ
+
+- **The idle number in `cwarm-keepalive.log` implies the last real activity was several minutes *after* the "done HH:MM" line the terminal showed for the previous turn — is the keepalive late?** No. A few minutes after a turn visibly finishes and the session goes idle, Claude Code itself appends an `away_summary` system entry to the transcript — a built‑in feature that leaves a short catch‑up note for when you return or get a notification. It doesn't print to the terminal, but it's a real write with its own timestamp, and cwarm's idle clock deliberately reads the transcript's last real content (not the terminal's minute‑rounded "done" label — see "Idle detection" above), so that later timestamp is what it measures from. The keepalive is still firing on schedule (~2 min before the measured cache TTL, per regime); the gap you can compute from the on‑screen time is Claude Code's own bookkeeping, not cwarm running behind.
+
 ## Platform support
 
 - **Windows** (Git Bash / PowerShell / cmd / Windows Terminal): verified, including non‑ASCII (CJK) input.
@@ -275,6 +279,10 @@ CWARM_AI=1 cwarm        # 效果相同，走環境變數
 | `CWARM_CLAUDE` | `claude` 執行檔路徑（否則用 `which`／`where` 自動偵測） |
 | `CLAUDE_CONFIG_DIR` | Claude 設定目錄（預設 `~/.claude`） |
 
+### 常見問題
+
+- **`cwarm-keepalive.log` 裡的 idle 秒數，反推出來的「最後活動時間」比終端機畫面顯示的「done HH:MM」晚了好幾分鐘，是不是保溫變慢了？** 不是。一輪回應結束、session 進入閒置幾分鐘後，Claude Code 本身會自動補寫一筆看不見的 `away_summary` 系統紀錄到 transcript 檔案（給你之後回來看畫面或收到通知用的簡短摘要），這是內建功能，不會印在終端機畫面上，但它是真實寫入、有自己的時間戳。cwarm 的 idle 計時本來就是刻意讀 transcript 裡最後一筆真實內容的時間（見上面「運作原理」），不是畫面上四捨五入到分鐘的「done」字樣，所以會讀到這筆較晚的時間戳。保溫本身仍準時在算出來的快取到期前 ~2 分鐘（依檔位）注入，看到的落差是 Claude Code 自己的紀錄行為，不是 cwarm 跑慢了。
+
 ### 平台支援
 
 - **Windows**（Git Bash／PowerShell／cmd／Windows Terminal）：已驗證，含非 ASCII（中日韓）輸入。
@@ -283,6 +291,10 @@ CWARM_AI=1 cwarm        # 效果相同，走環境變數
 
 ## Changelog
 
+### 0.1.18
+- **Docs:** new FAQ entry explaining why the idle number in `cwarm-keepalive.log` can point to a "last activity" time several minutes after the terminal's own "done HH:MM" label for the previous turn — Claude Code itself appends an invisible `away_summary` system entry to the transcript a few minutes into idle, and cwarm's idle clock (by design) reads that real transcript content, not the terminal's rounded label. No code change; the keepalive was never late, only the on-screen comparison looked that way.
+- **文件：** 新增一則 FAQ，解釋為什麼 `cwarm-keepalive.log` 裡的 idle 數字，反推出來的「最後活動時間」有時會比終端機畫面上一輪回應顯示的「done HH:MM」晚上好幾分鐘——Claude Code 本身會在閒置幾分鐘後自動補寫一筆看不見的 `away_summary` 系統紀錄到 transcript，而 cwarm 的 idle 計時本來就是刻意讀 transcript 裡的真實內容，不是畫面上四捨五入的標籤。沒有動到程式碼，保溫從來沒有變慢，只是拿畫面時間去對表會看起來像慢了。
+
 ### 0.1.17
 - **Fix:** the keepalive could stay silent for hours while the cache went cold. Idle was measured from the transcript file's **mtime**, and something (still unidentified — it only ever touches the file of a *live* session, never an old one) updates that mtime without appending a single byte. Measured on a real session: mtime claimed 12 minutes idle while the last actual turn was 68 minutes old, so the ping never fired. Idle now comes from the timestamp of the last conversation turn recorded *inside* the transcript, which no outside toucher can move; the old mtime path stays as a fallback for when no timestamp can be read. The statusline countdown had the identical bug — it now calls the exact same function as the host, so the number you see is the number the keepalive decides on.
 - **修正：** 保溫可能整整幾小時不出手，眼睜睜看著 cache 冷掉。閒置時間原本是看 transcript 檔案的 **mtime**，而有東西（還沒查出是誰——它只會碰「正在使用中」的 session 檔，舊檔一個都不碰）會把 mtime 往前更新卻連一個位元組都沒寫進去。實測一個真實 session：mtime 說才閒置 12 分鐘，實際上最後一輪對話已經是 68 分鐘前，保溫因此完全沒發。現在改用 transcript **檔案內**最後一輪對話的時間戳，外部碰觸動不了它；讀不到時間戳時才退回原本的 mtime 路徑。statusline 的倒數本來有一模一樣的 bug，現在改呼叫跟 host 同一支函式——你看到的數字就是保溫拿來做決策的那個。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-cache-keepalive",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "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": {