@misterhuydo/cairn-mcp 1.36.0 → 1.37.0

package/README.md

@@ -497,6 +497,61 @@ 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.
 
+**v1.36.1 is the release that made the sentence above true.** It was not. The gate would
+demand a thorough `would_be_lost`, the agent would write three and a half thousand
+characters of reasoning that existed nowhere else, correctly tell you a reset was safe —
+and the SessionStart re-injection would hand the fresh session 220 characters of it, cut
+off mid-word. Everything after the first point was gone. The agent could not remember the
+conversation you had just had with it, which read as the checkpoint failing when the
+checkpoint had worked perfectly.
+
+Storage was never the problem; delivery was. `inlineResumePayload()` rendered the restore
+payload through the same 220-character clip as the every-prompt budget line. That cap is
+right for the budget line — it rides *every* turn and has to stay one line — and ruinous
+for the restore payload, which fires **once** and is the only copy of the handoff that
+session will ever see. One cap could not serve both, so `handoffSummaryLine()` now takes
+one, and the restore path passes none. It costs about 900 tokens a session.
+
+The failure is worth naming because of its shape: the agent was right about what got
+*saved* and wrong about what got *delivered*, and no amount of care inside the writing
+session could have caught the difference. The same bug had a second instance — notes long
+enough to be filed to `.cairn/notes/` are held as objects, and the restore stringified
+them to `[object Object]`, so the most substantial notes were the ones that arrived as
+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.
+
 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