git:20260925.9069921 to git:20261012.11f465d

- description: How long this machine's sessions actually sit idle, how many prompt-cache entries that lets expire, what those expiries cost, and what a keep-alive strategy would have saved over the same window - with the exact setting that turns it on. Use when the user asks about idle time, cache misses, cache expiry, why the cache went cold, keep-alive pings, whether keep-alive is worth it, which cache strategy to use, or what walking away from the keyboard costs them. Accepts --json.

- allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/insights.py)

- # Idle time, cache misses, and what a ping is worth

-

- ```bash

- "${CLAUDE_PLUGIN_ROOT}/scripts/insights.py" idle

- ```

-

- **With `--json`**, add `--json` and print the output verbatim.

-

- ## The chain, in this order, because each link is a separate measurement

-

- Present it as the chain. Jumping to the dollar figure skips the two facts that make it believable.

-

- **1. How long they actually go idle.** `idle_gap_p10_hours` / `idle_gap_p50_hours` /

- `idle_gap_p90_hours`, and the `gap_band.*` histogram with a count and a cost per band. Give the

- median and the p90, not a mean — a mean over gaps that range from seconds to days describes none of

- them.

-

- **This is not a criticism and must not be phrased as one.** An idle gap is a developer reading a

- diff, thinking, or in a meeting. The gap is the input to the problem, never the problem.

-

- **2. How many of the resulting expiries are ADDRESSABLE.** `addressable_misses` and

- `addressable_usd`. Addressable means a ping placed inside the entry's own lifetime could have

- refreshed it. A gap longer than the pings can reach is not addressable at any price, and counting

- those in a saving is the single easiest way to inflate this whole report — so quote

- `addressable_misses`, never a total miss count, as the size of the opportunity.

-

- `coverage_seconds` is how far the current policy actually reaches: **K pings x the interval, plus the

- entry lifetime.** Reach is what more pings buy, not a deeper discount. Two pings at 280s reach 860s;

- one reaches 580s.

-

- **3. What the pings DID**, if any ran. `keepalive_pings`, `keepalive_ping_usd` (what they cost),

- `keepalive_saved_usd` (the prefix re-creations they avoided), `keepalive_net_usd` (the difference,

- and **the only one of the three a saving may be reported from**). Plus `keepalive_winners` /

- `keepalive_losers` / `keepalive_sessions_touched` — a positive total over a losing majority is a

- different fact from a broadly positive one, and the split is how a reader tells them apart.

-

- `keepalive_misses_avoided` is prefixed **"at most"** wherever you quote it, and say why once: the

- provider's cache is keyed on content, so another session sending a byte-identical prefix would have

- refreshed the same entry anyway. That confound cannot be measured from our side, so the count is a

- ceiling on coverage rather than an attribution.

-

- **4. What they WOULD have done**, if they did not. This is `recommend_*`, and it has two shapes.

-

- ## The recommendation, or the refusal

-

- **`recommend_refused` non-empty is the answer, not a gap in it.** Report the reason verbatim and

- stop. Below its floor the interval the bootstrap produces is an artefact of the resample rather than

- a property of the traffic. The `service_lo_usd`/`service_hi_usd` pair in that finding is

- **service-wide scale, explicitly not the user's figure** — say which it is or do not say it.

-

- Where it is not refused: `recommend_idle_seconds`, `recommend_max_pings`, and `recommend_lo_usd` to

- `recommend_hi_usd` over `recommend_n` addressable expiries in `recommend_sessions` sessions.

-

- **Quote both ends of that range. Always. Never average them into one number.** There is deliberately

- no point-estimate field on the wire: every account measured has a 90% interval whose relative

- half-width is at least 62%, and some cross zero. A midpoint would be a number nobody measured, and

- the field was left out precisely so nobody could render one.

-

- ## The K ladder

-

- `calc.k1..kN.{convertible_misses,net_usd,coverage_seconds}`, with `calc_current_k` marking the

- policy in force. This is where "what would have saved me money" becomes a table rather than an

- assertion. Alongside it:

-

- - `calc_prefix_tokens` with **`calc_prefix_source`** — `session`, `account_median` or `given`. Per-ping

- cost is bimodal (p50 $0.0004, p99 $0.2275), so there is no honest average of it; the source field

- exists so a typed number is never read as a measured one. If it says `none`, there was no prefix to

- measure and the ladder's dollars are absent rather than assumed.

- - `calc_ping_usd_each` — one ping on that prefix. `calc_avoided_usd_each` — what one converted miss

- is worth, which is the avoidable **write premium** `(cache_write - cache_read) x prefix`, not the

- whole cost of the miss. Quoting the whole miss would overstate every figure here by roughly a fifth.

- - `calc_priced=false` means the model has no rate. Every dollar in the ladder is then absent. It does

- **not** fall back to a blended rate.

-

- ## What is at risk right now

-

- `live_sessions_expiring_soon`, `live_soon_usd`, `live_potential_usd` — the only part of this report

- about the present rather than the window, and the most persuasive thing in it. A session whose cache

- entry lapses in ninety seconds has a named dollar cost attached to walking away. Mention it when it

- is non-zero; skip it silently when it is not.

-

- ## Turning it on

- /plugin configure context-guru

- `cache strategy: 5-min-ping` — and **say the cost in the same breath, once**: it spends the user's

- own credential on pings while nobody is at the keyboard, and it applies to every session routed

- through this proxy rather than just this one. The range in the finding is already net of that spend.

- `/context-guru:cache-strategy-picker` explains `none` and `1-hour-head` and does the switching.

-

- **A restart is required and saying otherwise is the failure mode.** The strategy is picked up when a

- proxy starts, and a running proxy keeps its current one until it is stopped and started again. A new

- session does that; do not restart the proxy from inside a session routed through it.

-

- ## The two findings that are problems, not savings

-

- - **`keepalive-wrote`** — pings that CREATED a cache entry instead of refreshing one. That pays the

- premium write rate to cache something nothing will re-read: the one keep-alive outcome with no

- upside at all. Report it as a bug, never fold it into the saving, and say that switching to `none`

- stops the spend meanwhile.

- - **`keepalive-underwater`** — running, and net negative. **A negative net is a real outcome and is

- shown as one.** Do not clamp it to zero, do not lead with the ping count as though firing were the

- achievement, and do say that a few long sessions with large prefixes can flip the sign — so

- "check again in a week" is honest advice rather than a hedge.

-

- `phantom_ttl_rows` above zero is a data-quality count, not a saving: the expiry attribution behind

- every figure in this section is weaker than it looks. Mention it if it is large relative to

- `addressable_misses`.

-

- ## On a non-Anthropic backend

-

- Keep-alive still spends, and a chosen pipeline preset may save nothing — vLLM, llm-d and similar

- match an implicit longest prefix on their own. Zero pipeline saving there is correct behaviour rather

- than a failure, and it does not make the keep-alive figures wrong.