@misterhuydo/cairn-mcp 1.36.1 → 1.38.0

package/README.md

@@ -520,6 +520,76 @@ them to `[object Object]`, so the most substantial notes were the ones that arri
 noise. When a feature demands expensive judgement from the agent, test the whole return
 path, not just the write.
 
+**v1.37.0 gives the handoff somewhere permanent to live, and stops previews cutting
+mid-word.** `session.json` holds exactly *one* `would_be_lost`, and every manual
+checkpoint overwrites the last, so a project's history of what each session would have
+lost was destroyed one checkpoint at a time — and the rotation at 100KB scattered
+whatever survived across `session.N.json` files nobody reads. The most expensive field
+cairn ever asks an agent to produce had the shortest life of anything cairn stores.
+
+Every answered handoff is now appended to **`.cairn/handoff.md`**: full text, never
+clipped, newlines intact, plain Markdown you can read or grep without cairn. Newest
+first — unlike `roadmap_completed.md`, which appends at the end because it is a shipping
+record read in order. This is a lookup, so it is ordered for the lookup. The every-turn
+heartbeat is not logged; only a real answer is, or a handful of genuine judgements would
+be buried under thousands of identical copies. It is an addition rather than a migration:
+`session.json` keeps the field unchanged as the hooks' fast path, so nothing that reads
+it needs to know the file exists.
+
+Previews no longer end mid-word. A cut like `…the re-injection clipped would…` is worse
+than a shorter clean one: the reader cannot tell whether the truncated token was `would`,
+`would_be_lost` or `wouldn't`, so the last thing they are shown is the one thing they
+must not trust. `clip()` backs up to the last space and drops trailing punctuation. The
+exception is deliberate — an unbroken run longer than the cap (a stack trace, a base64
+blob, a Windows path) has no boundary to back up to, so below a 0.6 floor it takes the
+hard cut rather than returning almost nothing. The cap itself went 220 → 400, because at
+220 the budget line reliably died inside the first sentence of point (1): enough to prove
+a handoff existed, not enough to say what it was about.
+
+One test had to change, and it is worth saying which. The v1.36.1 guard asserted the
+every-prompt line stayed under 300 characters — a magic number tied to the old cap, so it
+failed on a change that was entirely intended. It now asserts a *ratio*: the preview must
+stay under half the payload. The invariant was never a particular length, it was that one
+channel stays a preview while the other carries everything.
+
+**v1.38.0 adds the other half of the question.** Everything above is retrospective.
+`would_be_lost` asks what a fresh session would not *know*, and every example in it is
+something that already happened. So a restored session inherited the whole of what the
+last one learned and nothing of what it was going to do with it — thorough notes, a
+legible thread, and an agent that still opened with "what now?" to a user who had
+answered that an hour earlier.
+
+`cairn_checkpoint` now takes **`next_step`**, carried by exactly the same rules as the
+handoff: the heartbeat copies it forward but never restamps it, it ages against commits,
+and it is delivered in full on restore, directly under the handoff. It asks for the
+*reason* as well as the action, because the action alone already survives in the roadmap
+and the message field — what does not survive is why that action was next rather than the
+alternatives, and an agent that inherits only "run the Windows fixtures" will happily do
+it in the wrong order or redo the deliberation that chose it.
+
+Staleness means something sharper on this half. A stale handoff is still *true*: what was
+learned stays learned, and later commits only mean it may be incomplete. A stale next step
+may be actively *false* — commits landing after "next I will run the fixtures" are quite
+often that step being done, so the warning says **verify before acting on it** rather than
+"may be stale". A restored agent acting confidently on a completed instruction is worse
+than one told nothing.
+
+The 90% gate now demands both halves, and only the missing one. Asking for a handoff that
+is already current invites it to be rewritten, and a rewrite restamps `at` — which is how
+a thorough answer gets replaced by a hurried one at the worst possible moment.
+
+**And when nothing forward is registered anywhere, the gate says so.** If the roadmap has
+no cursor and no open phase, then after the reset there is nothing outside the discarded
+conversation that says what comes next, and the gate suggests registering the phase. This
+is not cairn inferring the plan — that remains the thing it cannot see and must not guess.
+It reports an *observed absence*: the plan points at nothing. Absence is observable,
+content is not, and that distinction is the only reason this arm is allowed to exist. When
+the roadmap cannot be read at all — no index, no sqlite — it stays silent rather than
+claiming a bare plan it never saw, the same honest-absence rule the commit counter uses.
+
+The probe is deliberately not the roadmap renderer: it is two cheap queries, run only when
+the gate is actually crossing, so the every-prompt path opens no database at all.
+
 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