dsh-cache-guard

LIMITATIONS

Known limitations

- **The cold split is calibrated, not guaranteed.** The request total comes from the harness's own pressure number (provider-anchored where the session has provider usage); the fixed part is read from the session's cheapest real request. A very large opening message makes the fixed part slightly high and the cold estimate slightly low. - **The checkpoint size is an estimate** — a planned summarization is priced with `estimatedSummaryTokens`, because the real summary does not exist before it runs. Prune numbers are exact, and the plan states which of the two it is. - **The per-session mode is process-local.** "Allow automatically for this session" lasts until the harness restarts; a durable record would need a session event type this build knows, which an out-of-repo plugin cannot add. - **A declined overflow still ends the turn.** At a provider-confirmed context overflow the window is already exhausted, so declining preserves the original provider error. - **The plan mirrors the engine's resolution.** The trigger ratio, the retention budget, the routed provider/model (from the durable `request/header` the engine itself reads), and the safe-cut rule are recomputed here from the public engine config and the session surface — because the guard selects the range it replaces. A change upstream must be followed here; a range the engine rejects leaves the surface untouched and logs the failure. - **A profile without the host half is not guarded at all.** The gate is installed by the bundle's host row; a profile that composes without it (or disables it) has no veto, no dialog, and no pill. The preset row covers that case, one preset at a time. - **The pill's reassurance is derived, not promised.** `Cache: ask` means the process guards at least one engine; a fresh session confirms it after its first step, when the live context line appears. `Cache: not armed` is the honest answer when nothing is guarded. - **A pricing failure spends rather than strands.** If the guard cannot price an operation it hands the operation to the engine and says so in the log. That is the same cache cost the session would have paid without the plugin — deliberately chosen over declining every rewrite in every session. - **A profile with no question provider blocks rather than spends.** With `mode: manual` and nothing to ask, the guard declines and logs it; the session then runs to its window limit. Use `mode: auto` for a headless profile's row. - **Everything but the harness vocabulary is English.** Code, comments, docs, dialog copy, and the pill are English; only the harness terms the guard reports (`compaction/prune`, `thresholdRatio`, `retainRatio`) keep their upstream spelling.