@misterhuydo/cairn-mcp 1.33.0 → 1.34.0

package/README.md

@@ -84,7 +84,7 @@ No manual steps. The index lives in `.cairn/index.db` inside your project — li
 | `cairn_todos` | Scan codebase for TODO/FIXME/HACK comments, add manual items, resolve and list them |
 | `cairn_roadmap` | The active project plan: phases authored in `.cairn/roadmap.md`, with a cursor, dependencies, and auto-pruning of shipped phases into `.cairn/roadmap_completed.md` |
 | `cairn_bundle` | Minified source snapshot (auto-handled by hooks) |
-| `cairn_checkpoint` | Save session state (auto-handled by hooks). At a stopping point, answer `would_be_lost` — the one part that git and the index cannot recover |
+| `cairn_checkpoint` | Save session state (auto-handled by hooks). At a stopping point, answer `would_be_lost` — the one part that git and the index cannot recover. Also takes `context_window`, the one thing cairn cannot measure for itself |
 | `cairn_minify` | Minify a single file on demand (fallback when hooks are not installed) |
 | `cairn_switch` | Switch active project root mid-session (use for maintenance on a sibling service) |
 | `cairn_memo` | Save a preference, decision, or discovery to the project's persistent memory. `action: "reindex"` repairs an index that has lost entries (see below) |
@@ -389,6 +389,7 @@ and the model id is no help either: a `claude-opus-5[1m]` session writes the bas
 | v1.20.0 | fixed 120k tokens | 60% of a 200k window but 12% of a 1M one, so it fired a tenth of the way into a 1M session |
 | v1.31.0 | infer the smallest window that fits the measurement | sound as a lower bound only, so below 196k it assumed 200k — reported **96%** where `/context` said **19%** |
 | v1.32.0 | never guess downward; `CAIRN_CONTEXT_WINDOW` states the truth | nothing could ever set it. `install-hooks` cannot know the window either, so there was no correct value to write — unwritable by construction, and the feature went silently dead |
+| v1.33.0 | report the bare count, let the agent judge | right about *who* decides. But a reader handed a number with no denominator supplies one, and supplies the familiar 200k: an agent at **253,500 of a 1M window** called for a clear, twice, with 74% free |
 
 v1.31.0's false-alarm band could never have been tuned away: any firing point for a
 200k window is a point a 1M session also passes through, so no number serves both.
@@ -400,6 +401,26 @@ rules for acting on it, and never issues the verdict itself. It is the same divi
 of labour as the handoff: cairn demands the judgement and carries it, never computes
 it.
 
+**Since v1.34.0 the agent also declares the denominator.** Pass `context_window` to
+`cairn_resume` or `cairn_checkpoint` once per project (optionally with
+`context_window_model`), and every reading from then on is scaled:
+
+```
+[cairn] Context: 253,500 of 1,000,000 tokens (25%, declared for claude-opus-5[1m]).
+```
+
+Until you do, the line carries the raw count and says the window is undeclared, which
+is the honest state — cairn still never invents a denominator. The declared window is
+stored beside the handoff in `session.json` and carried forward by checkpoints that do
+not restate it, so the every-turn heartbeat cannot drop it.
+
+This is not `CAIRN_CONTEXT_WINDOW` coming back. That died on *who could ever set it*,
+and the answer turned out to be: the one party that can read it off its own system
+prompt. A declaration can still be wrong — carried into a narrower model's session, say
+— but it is wrong *on screen*, next to the model it claims to be for, and a reading over
+100% is called out as an impossible one rather than an emergency. A stated assumption
+gets corrected; the unstated one that replaced it in v1.33.0 could not be.
+
 That also removes the rate-limiting. The old block was a *verdict*, so repeating it
 was nagging and it had to be shown once per situation; this is a *measurement*, and a
 budget you are only shown once it is nearly spent cannot inform the decision to start