feat(compact): reserve a buffer and write notes-to-self before context rollover (#391)

[justrach]

Closes #391. The Codex auto_compact_fallback_buffer_tokens / auto_compact_fallback_prompt pattern: the agent writes what its future self needs before compaction, instead of losing working state silently.

The reserve shares #390's ledger, it does not add a second one

This was the issue's hardest constraint, so it gets the detail. The reservation lives in src/phase_budget.zig, the ledger over the shared RunBudget pool where #390's landing reserve already lives (landingReserve, Ledger.reserve; its hard half is the depth > 0 and remaining() <= 1 guard in run_budget.zig:97). The addition is cost_precompact_note: u64 = 1 plus Ledger.affordsHarnessNote(remaining), which is literally fits(remaining, cost_precompact_note) — the same "must fit on top of the reserve" predicate subagent.scoreVariants uses for judges.

The note is deliberately the junior liability: narration is mandatory and owns the reserve, the note is optional and must clear it. A separate reserve would have been a second ledger over one pool, double-counting the last call.

Confirmed three ways rather than asserted: decideCalls constructs a phase_budget.Ledger and calls nothing else for the budget answer, so there is no second constant; a test derives the admit boundary as landingReserve(cap) + cost_precompact_note and then sweeps every remaining from zero upward asserting affordsHarnessNote(r) == (decideCalls(...) == .fire), which a parallel mechanism would fail; and the note turn passes the same shared run_budget instance, so it is counted in the pool where it is spent.

The token half (note_reserve_tokens = 2_000, checked against provider.context) is the direct analogue of Codex's buffer and is a gate, not a second call reserve.

Persistence: a session-scoped file, not playbook items

The issue suggested playbook items with source=session. Rejected on four structural grounds:

1. The playbook is project-scoped and deliberately cross-session — blockNow reads one .graff/playbook.jsonl from any session in the repo. A note about the refactor in flight is noise tomorrow, and source=session would force every existing reader to learn a session filter.
2. playbook.max_text is 240 bytes per item with 2048/1024-byte block caps. Subgoal plus anchors plus decisions plus dead ends is 1–2k on its own.
3. Every item rides every subagent/workflow brief via rideBrief. Pre-compaction notes-to-self: reserve buffer tokens so the agent writes durable state before context rollover (Codex pattern) #391 requires the opposite.
4. Items are permanent until retired by id; a note is superseded wholesale by the next one.

So: .graff/notes/<session>.notes.jsonl, injected into the root system prompt beside HARD CONSTRAINTS. What #383's mechanism did contribute, unchanged: append-only JSONL written whole-or-not-at-all, replayed deterministically, and assembled from the file at injection time rather than from conversation memory. That single property is why it survives compaction with no extra machinery — there is no in-context copy for a summarizer to paraphrase — and the system prompt is re-sent verbatim every request.

Verification

zig build test → 1058/1058, exit 0 (baseline 1043, +15). A deliberate break confirmed the suite goes red before restoring, so the new modules genuinely compile in. scripts/eval-tier1.sh green, reachability at 1021 declared tests.

Covered: fires exactly once when compaction is imminent, and the same history_rewrites generation never buys a second note (so it survives #379's retry loop) while the next generation does; never fires for a subagent, asserted through the production entry point with provider/client left undefined, so a pass proves no request was attempted; budget refusal at the exact landingReserve + 1 boundary plus the full sweep; token-headroom refusal at the buffer boundary; a real file round trip in a scratch cwd with byte-identical readback, sessions not reading each other's notes, newest superseding, and torn tails or junk lines costing at most their own record; survives compaction and re-injects verbatim with the entire conversation replaced by a summary mentioning none of it; graceful degradation on empty/whitespace/"none"/path-escaping session names.

src/agent_compact.zig ends at 569 (+5: one import, three comment, one call). With #445 and #440 on top that lands near 588/600.

Not covered

The .fire branch issues a live provider request, which no unit test can drive, so the model call, the reply text, and the compact() call site firing are uncovered. Every refusal path is exercised through the real entry point, and the request is built from shapes already proven elsewhere (playbook_reflect.askModel's throwaway tool-less agent, compact()'s own history clone). compaction_request = true is set on the note agent so applyOverflowRecovery's early-out stops the note turn recursing into emergencyTrim mid-compaction — that reasoning is read off the source, not exercised by a test.

Integration note: this branch and #459 (#411) independently created a src/compact_note.zig for different purposes. They collide by filename and will be disambiguated when the two are integrated.