Repository navigation
session-flow handoff: cap size below the Read cap and split hot file from archive #9238
Description
Problem
Hand-offs grow without bound, and resumed sessions only partly read them.
.work/handoffs/in this repo holds 456 files totalling 22 MB.- The latest automation-lanes hand-off is 348,178 bytes (about 87K tokens). It grew roughly in a straight line over 53 hops, because five sections are copied forward on every hop (
plugins/session-flow/reference/structure.md:97-100), and the size and promote rules only warn (skills/handoff/SKILL.md:142-172). - Partial reads on resume. Of six resumed sessions measured on 2026-10-22:
- In one, the @-mention failed with
"unread":"too_large","fileSize":337835, and the session then read about 23% of the file. - The other five hit the Read tool's 25K-token cap ("showing lines 1-304 of 743 total (51831 tokens, cap 25000)") and paged through 2–4 reads, some of them re-reads.
- In one, the @-mention failed with
- Cost before the first edit: 1.1M–11.2M cached input tokens per resume.
- A standing preference failed to stick. The owner had to restate it even though the hand-off held it in up to five places, each a single line among 300–500 entries.
Anthropic's current prompting guide (https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices, "Workflows across multiple context windows") says a fresh context window can rebuild state from the filesystem ("Claude's latest models are extremely effective at discovering state from the local filesystem"), using progress files and git logs.
Wanted (owner-approved direction, 2026-10-22; the exact design goes through /planning:interview)
-
validatefails, rather than warns, when the file to be read on resume exceeds the Read page cap (about 25K tokens). -
Split each hand-off into:
- a short hot file: goal, brief, remaining actions, open items;
- an archive for resolved and older entries.
The resume directive reads only the hot file.
-
Stop copying facts GitHub already records, such as merged PRs and SHAs, into Side effects; point to a
git logrange or aghsearch instead. -
Keep the last 3 Prior-sessions rows and point to the
chain:frontmatter for the rest. -
Move durable owner preferences to CLAUDE.md or memory instead of repeating them in each hand-off.
🤖 Generated with Claude Code
Activity
github-actions commentedon Oct 22, 2026
Proposed work class: work-class: structural
Basis: automated intake triage; a maintainer confirms or changes it.
Size: Large
Complexity: High
Uncertainty: Knowable
Flags: none
Blocked by: none
Understood: session-flow hand-offs grow without bound and exceed the Read cap on resume. The owner-approved direction is to make
validatefail above the cap, split each hand-off into a short hot file and an archive, stop copying GitHub-recorded facts, keep the last 3 Prior-sessions rows, and move durable preferences out of hand-offs. The exact design is deferred to /planning:interview. This touches the validator, the handoff skill, the structure reference and the resume directive, so it likely needs splitting into several changes. I found no likely duplicates among the open issues.Automated triage. A maintainer reviews it.
fix(session-flow): fail a hot file over the Read page cap
kyle-sexton commentedon Oct 25, 2026
Open: #9918 restores Suggested skills to the shape-3 hot file (dropped in #9817; spot-check eval on se-handoff-9 measured 0.78 before against 0.39 after, 3 runs each). Whether the fix fully restores that score is unmeasured: no new eval runs, by owner decision, and se-handoff-9 is setup-fragile (in the 3 after runs, one Write was denied by the sandbox fence and one run declined to write a handoff in an empty session).
Follow-up: re-run se-handoff-9 x3 on main once its scaffold seeds prior work, so the drop can be attributed. Evidence: the verify runs in the handoff-efficiency eval record (
.work/handoff-efficiency/eval-runs/verify/, local to the run).kyle-sexton commentedon Oct 25, 2026
Scope note (owner decision, 2026-10-25): two parts of this issue's plan stay out of what shipped in #9817 and #9918, and are not tracked as new issues:
/planning:interviewemoji-marker fix (plan Phase 2), which also needs the owner's re-pin of the interview Stance digest.This issue stays open for the shape-3 accuracy check: 12 capped writer runs, 3 cases x 2 runs x before/after at the 10K cap, both readers (ADR 0084). The se-handoff-9 case is being made self-contained before its own re-run. The 142-run full skill-eval re-run is skipped by owner decision, because the 26-run spot check already found the one real drop.
kyle-sexton commentedon Oct 25, 2026
Remaining for this issue (owner decision, 2026-10-25, "go w/ recommendations"):
se-handoff-9x3 on main (now self-contained, test(session-flow): give handoff eval case 9 the prior session it assumes #10026), to attribute its 0.78 to 0.39 drop.d42b1ad700) and after (main) at the 10K cap, Claude Code and Codex readers, throughplugins/session-flow/scripts/harness/resume_eval.py run --max-writer-runs 12(seeplugins/session-flow/evals/resume-eval.md). Claude Code must read non-inferior (noise-report.py --margin 0.05, no case drop); Codex is the improvement signal. Report tokens per run after the first 2.Landed: #9817 (shape 3), #9918 (Suggested skills restored), #10026 (case 9 self-contained), #9819 (plan run budgets), #10024 (hold PRs with
do-not-merge).kyle-sexton commentedon Oct 25, 2026
se-handoff-9re-check (2026-10-25), self-contained case from #10026,claude plugin eval --scaffold --ablation none, Opus writer and judge:d42b1ad700, new case)Inconclusive. Each arm stopped at 2 runs on its 5 USD cost ceiling (about 2.8-3.5 USD per run, an order of magnitude above the earlier 1-run pilot of other cases), and each arm has one run that scored 0-0.17 on most expectations, so n=2 cannot separate the arms. The one failing expectation on after's 0.83 run is
expectation-2(Resumption brief leads with the stated purpose).The 12-run accuracy check did not run: this pair moved the 7-day window from 81% to 85%, so 12 heavier real-setup runs would cross the 95% lane-pause line. Next window: run both with the cost ceiling sized from these figures (
--max-cost-usdabout 4 x runs), 3+ runs per arm.kyle-sexton commentedon Oct 25, 2026
Accuracy check results (2026-10-25), the capped run recorded above:
resume_eval.py run, re-skipped-rule, re-restated-preference and re-superseded-rule x 2 runs x before (d42b1ad700, shape 2) and after (main, shape 3), Claude Code (real setup) and Codex readers. 12 writer runs, 0 harness errors; 2 before-arm Claude Code reads excluded (the reader's Bash was denied by the auto-mode classifier).Claude Code reader (deciding): after 1.00 on every case, before 1.00 on every kept run.
noise-report.py --margin 0.05: change +0.00, interval +0.00 to +0.00, non-inferior, no case drop.Codex reader (signal): after 0.63 mean against before 0.67; change -0.04, interval -0.12 to +0.04, not shown non-inferior at n=2. Two cases are identical. re-restated-preference fell 0.875 to 0.75 in both runs on one probe:
artifact-4277-change(an artifact detail now held in the archive). So Codex did not make the targeted archive read the hot file points to.Tokens (writer plus reader to the first state change):
Reading: no accuracy loss for the Claude Code reader, which is what the lanes run. A measured token drop that n=2 cannot separate from noise. One archive-recall miss for Codex.
Also from this session's
se-handoff-9work: a trace judge cannot see a handoff file written mid-run, so that case cannot grade the file's content in any arm. It should grade the written file instead of the trace.Closing per the plan recorded above. Open follow-ups: Codex archive recall (
artifact-4277-change); case 9 grading the written file.kyle-sexton commentedon Oct 25, 2026
Released for re-triage under the owner's 2026-10-24 rule: an issue stops for a person only for an intent or vision question, a security call, a host or attended run, or spend outside prepaid credit. The hold label came off and intake triage runs again now; it re-applies a hold, with a numbered question, when one of those applies.
To hold this issue again, add
needs-human(orstatus: needs-decision) and say why in a comment.