Summary

• Problem: stale .usage-cost-cache*.tmp files can remain beside the durable usage-cost cache after older cache writers or hard process termination.
• Why it matters: these orphaned files can silently consume disk in agent session directories.
• What changed: usage-cost cache refresh now prunes stale usage-cache temp files after acquiring the cache refresh lock, while preserving recent temp files and lock-write temp files.
• Scope boundary: cache contents, pricing calculations, transcript scanning, lock semantics, and normal atomic cache writes are unchanged.

Change Type

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

Closes #78939

Real behavior proof

• Behavior or issue addressed: stale usage-cost cache temp files are reclaimed during cache refresh instead of remaining indefinitely in agent session directories.
• Real environment tested: macOS local source checkout, Node v26.3.0, pnpm v11.2.2, temporary OPENCLAW_STATE_DIR.
• Exact steps or command run after this patch: created a temporary OpenClaw state dir, seeded a real agent session transcript, wrote stale legacy/current usage-cache temp files plus a recent usage-cache temp file and a lock temp file, then imported and called refreshCostUsageCache() and loadCostUsageSummaryFromCache() with node --import tsx.
• Evidence after fix:

{
  "result": "refreshed",
  "staleLegacyExists": false,
  "staleCurrentExists": false,
  "recentTempExists": true,
  "lockTempExists": true,
  "totalTokens": 30,
  "totalCost": 0.03,
  "cacheStatus": "fresh"
}

• Observed result after fix: both stale temp-file shapes were removed, the recent temp file and lock temp file were preserved, refresh returned refreshed, and the cache summary reported fresh with the expected totals.
• What was not tested: live production cleanup on the reporter's Windows session store.

Root Cause

Current cache writes use the atomic replacement helper, which cleans up its own active temp path for ordinary failures. It does not sweep temp files left by older builds or hard exits, and the locked refresh path had no stale-temp reclamation step.

Regression Test Plan

• Target test: src/infra/session-cost-usage.test.ts
• Scenario locked in: cache refresh removes stale legacy and current usage-cost temp-file shapes while preserving recent temp files, preserving lock temp files, and producing a fresh usable cache.

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Validation

• pnpm install --frozen-lockfile passed.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.infra.config.ts src/infra/session-cost-usage.test.ts -t "reclaims stale usage cache temp files before refreshing" --reporter=verbose passed: 1 test passed.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.infra.config.ts src/infra/session-cost-usage.test.ts passed: 53 tests passed.
• node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo passed.
• node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo passed.
• node scripts/test-projects.mjs --changed origin/main passed: infra shard, 53 tests passed.
• PATH="/opt/homebrew/opt/corepack/bin:$PATH" OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 CI=1 PNPM_CONFIG_VERIFY_DEPS_BEFORE_RUN=false node scripts/check-changed.mjs passed locally. The default Testbox delegation could not run because Blacksmith auth is not configured on this machine.
• git diff --check passed.
• .agents/skills/autoreview/scripts/autoreview --mode local passed: no accepted/actionable findings.

AI Assistance

AI-assisted: yes. I used AI assistance to inspect the issue, implement the narrow fix, run local validation, and prepare this PR text. No assistant signature, co-author footer, or generated-by footer is included.