docs: update PR body with all 4 changed files

chenyangjun-xy · chenyangjun-xy · commit bd6bbea63c14 · 2026-07-03T14:23:38.000+08:00
diff --git a/pr-body-98960.md b/pr-body-98960.md
@@ -0,0 +1,162 @@
+## What Problem This Solves
+
+Fixes #98960: The module-level `fileCache` Map in `src/auto-reply/usage-bar/template.ts` holds a live `fs.watch` watcher for each cached template file path. The cache grows without bound — entries are never evicted, and watchers are only closed in `clearUsageBarTemplateCacheForTest()`. Over time this leaks file descriptors.
+
+## Root Cause
+
+`cacheTemplateFile()` inserts without checking cache size. Each new file path creates a persistent `fs.watch` watcher that is never released in production.
+
+## Why This Change Was Made
+
+Add a maximum cache size (`MAX_CACHED_TEMPLATE_FILES = 64`). When inserting a **new** cache key that would exceed the limit, evict the oldest entry (closing its `fs.watch` watcher) **before** allocating a watcher for the new entry. This bounds watcher count and prevents unbounded FD growth.
+
+Key design decisions:
+- Eviction runs **before** watcher allocation so we never create a watcher only to close it immediately.
+- Eviction triggers only when inserting a **new** key (`!fileCache.has(path)`). Retries for an existing key (re-reading after a prior miss) must not evict other entries.
+- Eviction uses `Map.keys().next()` for oldest-entry ordering (Map maintains insertion order).
+
+## Changes
+
+- `src/auto-reply/usage-bar/template.ts`: +13 lines
+  - Added `MAX_CACHED_TEMPLATE_FILES = 64` constant
+  - Added oldest-entry eviction with watcher cleanup in `cacheTemplateFile()`, before watcher allocation, guarded by `!fileCache.has(path)`
+- `src/auto-reply/usage-bar/template.test.ts`: +79/-1 lines
+  - Two new focused tests in a `cache eviction` describe block
+- `src/auto-reply/usage-bar/template.watcher-proof.test.ts`: +125 lines (new)
+  - Direct watcher create/close measurement via `vi.mock` intercept
+- `scripts/verify-template-cache-bound.mjs`: +123 lines (new)
+  - Real-process verification loading 65 template files through production code
+
+## Evidence
+
+### Verification environment
+
+| Item | Value |
+|------|-------|
+| OS | Linux 4.19.112 x86_64 |
+| Node.js | v22.19.0 |
+| Vitest | v4.1.8 |
+
+### Regression tests (12/12, 2 new)
+
+```
+ ✓ returns the built-in template when unset
+ ✓ returns an inline template object when usable
+ ✓ falls back to the built-in template for an unusable inline object
+ ✓ falls back quietly for an empty inline template
+ ✓ loads and parses a template file
+ ✓ falls back to the built-in template for invalid JSON
+ ✓ falls back to the built-in template for an empty template file
+ ✓ reloads a path after an initial miss
+ ✓ reloads a path after invalid JSON is fixed
+ ✓ serves the cached template without re-reading the file
+ ✓ evicts the oldest entry and closes its watcher when inserting a new key over the limit  ← NEW
+ ✓ does not evict when retrying the same key after a prior miss                         ← NEW
+ Test Files  1 passed (1) | Tests  12 passed (12)
+```
+
+The two new tests cover:
+- **Overflow eviction**: 65 paths loaded → oldest evicted → re-read from disk proves eviction + watcher closure.
+- **Watcher closure**: Evicted entry's watcher is closed; re-access triggers fresh `readFileSync` instead of serving stale data. Non-evicted entry remains cached.
+- **Same-key retry**: Cache full → invalid file loaded (slot consumed) → file fixed → retry same path → does NOT evict other entries.
+
+### Real-process proof: 65-template load (production code, no mocking)
+
+Standalone script (`scripts/verify-template-cache-bound.mjs`) imports the production `loadUsageBarTemplate` module via `tsx` and exercises it with 65 real template files. No mocking — this is a real Node process running the actual production code path.
+
+```
+========================================================================
+OpenClaw Template Cache Bound — Real-Process Verification
+========================================================================
+PID:       681079
+Node:      v22.19.0
+Platform:  linux x64
+Started:   2026-07-03T02:41:33.053Z
+Temp dir:  /tmp/usage-template-proof-pxStOa
+Cache cap: 64
+Files:     65
+
+── Phase 1: Fill cache (files 0–63) ──
+  Duration: 6ms
+  Result:   64 files loaded and cached
+
+── Phase 2: Load 65th file (triggers eviction of oldest entry) ──
+  Duration: 0ms
+  File 64:  {"segments":[{"text":"v1-64"}]}
+
+── Phase 3: Non-evicted file 1 — prove watcher still alive ──
+  File 1 reloaded: "CHANGED-VIA-WATCHER"
+  Result:          PASS (live watcher updated cache)
+
+── Phase 4: Verify files 2–63 still cached ──
+  Cached: 62/62
+  Result: PASS
+
+── Phase 5: Prove eviction (modify file 0 on disk, re-read) ──
+  File 0 reloaded: "V2-EVICTED-RELOADED"
+  Result:          PASS (disk re-read — evicted watcher was closed)
+
+── Phase 6: Cleanup ──
+  Result: clearUsageBarTemplateCacheForTest called
+
+========================================================================
+VERDICT
+========================================================================
+  64 files loaded → all cached                         PASS
+  65th file → eviction + watcher close                    PASS
+  Non-evicted watcher still alive                          PASS
+  62 files remain cached                                  PASS
+  cleanup → all watchers closed                            PASS
+```
+
+### Direct watcher create/close measurement (Vitest)
+
+Verification test (`src/auto-reply/usage-bar/template.watcher-proof.test.ts`) uses `vi.mock` + `vi.hoisted` to intercept `fs.watch` before module resolution and directly count every `FSWatcher` creation and `close()` call.
+
+```
+========================================================================
+Template Cache Bound — Direct Watcher & Eviction Measurement
+========================================================================
+Phase 1: Load 64 files → 64 watchers created, 0 closed
+Phase 2: Load 65th file → 1 created, 1 closed (eviction)
+  Content: {"segments":[{"text":"v1-64"}]}
+  Oldest watcher CLOSED, new watcher CREATED
+Phase 3: Re-read all 63 cached files → 0 created, 0 closed
+Phase 4: clearUsageBarTemplateCacheForTest → 64 watchers closed
+  Remaining active: 0
+
+========================================================================
+VERDICT — Direct watcher measurement
+========================================================================
+  Watchers created : 65
+  Watchers closed  : 65
+  Leaked           : 0
+
+  ✅ 64 files → 64 watchers
+  ✅ 65th file → 1 watcher CLOSED (eviction) + 1 CREATED
+  ✅ Cache hits → 0 created/closed
+  ✅ Cleanup → all remaining closed, 0 leaked
+```
+
+**Measurement methodology**:
+
+| Intercept point | What it counts | Phase 2 result |
+|-----------------|---------------|----------------|
+| Mock `fs.watch` | `state.created++` per watcher allocated | +1 (65th file) |
+| Instance `w.close = fn` | `state.closed++` per watcher closed | +1 (oldest evicted) |
+
+| Claim | Measurement | Result |
+|-------|------------|--------|
+| Cache bound at 64 | 64 watchers created in Phase 1, eviction triggers on 65th | PASS |
+| Oldest watcher CLOSED on eviction | `state.closed` increments by 1 in Phase 2 | PASS |
+| New watcher CREATED for 65th file | `state.created` increments by 1 in Phase 2 | PASS |
+| Cache hits: no new watchers | 0 created, 0 closed in Phase 3 | PASS |
+| Cleanup closes all (no leaks) | 64 closed in Phase 4, `created - closed = 0` | PASS |
+
+## User Impact
+
+- Watcher/FD usage bounded at 64 entries instead of growing indefinitely
+- Transparent to users; no config changes required
+- Evicted template files are automatically reloaded (with a fresh watcher) on next access
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
