@misterhuydo/cairn-mcp 1.34.0 → 1.36.0

package/README.md

@@ -426,6 +426,85 @@ was nagging and it had to be shown once per situation; this is a *measurement*,
 budget you are only shown once it is nearly spent cannot inform the decision to start
 something. It rides every prompt.
 
+**Since v1.35.0 the line also says which reset to use.** Every reading carries a
+second line naming `/clear` or `/compact` and why:
+
+```
+[cairn] Context: 90,000 of 1,000,000 tokens (9%, declared for claude-opus-5[1m]).
+Handoff is STALE, written before the 1 commit(s) since: the retry path is untested…
+→ If you reset: /compact — the handoff predates the 1 commit(s) since, so it no
+  longer describes the work in flight.
+```
+
+Cairn had been computing that recommendation since v1.29.0 and printing none of it:
+`recommendedAction()` decided between the two on every prompt, and the hook built its
+output from the measurement and the protocol alone, so the advice reached the screen
+only if the agent chose to raise it. That routed the whole path through the one
+component with a demonstrated failure record — the same judgement that read 253,500 of
+1M as an emergency, twice.
+
+The advice turns on **what is saved, never on how full the window is**. A current
+handoff means the thread survives a hard reset, so `/clear` is the better trade; a
+missing or stale one means something unwritten is still at risk, so `/compact` keeps it
+reachable. That is why it can print at 9% as readily as at 94%, and why the wording is
+strictly conditional. *If* you reset, use this one. It never says to reset — that
+judgement is still the agent's, and still yours to act on, since cairn cannot type
+either command. A fact about your saved state does not become false or urgent by being
+displayed; the verdict it replaced did, which is why that one had to be rationed.
+
+**Since v1.36.0 there is exactly one threshold again: the 90% gate.** At 90% of the
+*declared* window, cairn asks the agent for one specific thing:
+
+```
+⚠ [cairn] 94% of the declared window (940,000 of 1,000,000 tokens, 60,000 left) and
+nothing has been written down about what this session would lose. Call cairn_checkpoint
+with would_be_lost: the every-turn auto-checkpoint carries that field forward but never
+writes it, so nothing else will. This is not a verdict on whether your next task fits —
+that judgement is still yours.
+```
+
+A threshold is defensible now for a reason that did not exist before v1.34.0: **the
+window is declared, not guessed.** The gate fires only when an agent has stated its
+denominator and never otherwise, so a project that has declared nothing gets no trigger
+and no false alarm — by construction, not by tuning. That is the property the fixed
+120k, the inferred-smallest and the unwritable env var could never have had.
+
+It also asks for something none of them asked for. It does not say stop, and it does not
+rule on whether the work fits. It demands the one field an automatic save must never
+invent: the Stop hook checkpoints every turn, but `would_be_lost` is deliberately carried
+forward untouched rather than fabricated (`checkpoint.js:68`), which makes it precisely
+the field still missing when the window runs out.
+
+90% rather than 95% because the cost is asymmetric — firing early costs about 1k tokens
+for a handoff worth writing anyway, firing late costs the session's whole unwritten
+reasoning — and because usage does not climb smoothly. A single image read or large test
+dump can take 10k in one turn, which is the entire margin 95% leaves on a 200k window.
+
+**It also names who picks `/clear` vs `/compact`, and on what basis.** Cairn's own
+recommendation is about *what is saved* — but that is a precondition, not the decision.
+The decision is whether the work ahead needs the context already loaded: a new,
+unrelated phase gains nothing from this conversation, so `/clear` is the better trade,
+while a phase continuing this one would force a re-read of everything, so `/compact` is.
+
+Cairn cannot see which of those is coming, and does not try — that is the
+window-inference mistake in a new costume. The *agent* can: it has the incoming
+request, the roadmap cursor, and where the conversation was heading. So the gate demands
+that judgement rather than leaving you a two-branch menu, and the user-facing half
+explains what each command does so you can act on it or overrule it. Same division of
+labour as everywhere else here: cairn measures, the agent judges, you act — because
+cairn cannot type either command.
+
+Once the handoff is written, neither option drops anything that was written down, so the
+choice collapses to that single question about what comes next.
+
+It needs no rate limit: it self-extinguishes. The moment the handoff is written the
+demand returns null, and it speaks again only if later commits make that answer stale.
+Crossing is remembered in `.cairn/.handoff-gate` and forgotten when usage drops back
+below the gate, so a `/clear` makes the next crossing a genuinely new event. The stored
+crossing also closes a hole that `stale` alone cannot: staleness is counted in *commits*,
+so a long research session that commits nothing would keep a handoff from its opening
+minutes marked current all the way to the top of the window.
+
 `CAIRN_CONTEXT_HINT_TOKENS` no longer gates anything, but if you set it, cairn tells
 the agent when you have passed it rather than ignoring you.