spike: viewport hydrate — latest-page F5 (#924), slim local, scrollbar (A5 rebase) #553

Parent

#548 (agent session architecture) — A5 viewport

Type

Spike — design + maybe a throwaway prototype. Not a ship-or-fail
feature until a follow-up create-plan locks the winner. Do not convert
this issue into a plan.

Rebase (2026-09-06)

This spike was filed before durable async workflow inference. The original
problem (one JSON messages[] Blob, host Stop persist of the whole snapshot,
“do we HTTP Range or page?”) does not match main today.

Hard requirement: the winner of this spike must close
#924 (F5 / reload
fast-forward-replays the entire durable stream). A viewport design that leaves
that bug standing is not done.

Hard requirement: the follow-up plan’s DoD must include green
end-to-end integration tests on the durable-turn int project
(npm run test:int = vitest run --project int) that prove the #924
bullets (and any leftover that ships in the same cut) on a real Wasm
ring. Unit tests of coldAttachFromSnapshot / turnApply alone are
not sufficient. See End-to-end integration tests below.

A4 compaction (#552 / plan #947) is the model seed, not the canvas. This
spike is the paint window. Do not re-plan inference fold.

Leftover (this is the spike)

Three holes remain. #924 is the user-visible one and is non-negotiable.
Closing it (and any leftover that ships with it) requires e2e int rows,
not a unit-only gate.

Idle / completed F5 already lands on the latest ring page. Do not re-solve that.

Verified F5 path (why #924 still happens)

Same-tab F5 of a live (running / cancelling) turn on current main:

store.load()                         // full localStorage JSON
hydrateRingWindow(latest ≤2048)      // Wasm paints immediately (looks right)
bootCloudSession                     // envelope + full Blob GET (no Range)
adoptCloudSession                    // re-hydrate latest ring; heapAppliedRef = null
kickColdAttach
  coldAttachFromSnapshot → { startIndex: 0, dedup: true }
  // envelope turnStreamCursor is persisted, then ignored
prefixThroughLastUser                // strip this-run tool_run / assistant
  // ring = prior turns + this prompt  ← operator sees the starting prompt
GET /api/turns/:runId/stream?startIndex=0
  apply every SSE frame
  reasoning_delta → growThinking     // NEVER skipped
  tools / text skip only against the (now-empty) this-run window

The lock that causes the replay is intentional in today’s code:

• decideAttachClass / coldAttachFromSnapshot: new heap (F5 / login / new
  tab / switch) → always { kind: 'cold', startIndex: 0 } even when
  envelope C is large. Comment: “Heap has not applied this turnRunId.”
• adoptCloudSession / kickColdAttach set heapAppliedRef = null, so F5
  never takes the hot path (startIndex = heap.count).
• prefixThroughLastUser (adversarial feat(harness): E19 attach handshake — Blob hydrate + stream attach #857): Blob this-run suffix has no
  thinking; leaving it on the ring would append reasoning_delta after the
  answer. Cold attach therefore wipes tools/text off the ring and rebuilds
  them from the stream — which is why the operator sees prompt → sped-up
  thinking → tools → text, not “thinking on top of an already-painted tail.”
• lib/turnApply.ts: “Thinking is never in Blob — never skip, even on cold
  attach.”

Hot resume at heap C already works same-tab stream drop. F5 is a new
heap, so it never uses it.

'cancelling' stays attachable so F5 after an accepted cancel restores
Busy + Stop. That constraint stays. The replay does not.

Idle / completed F5: coldAttachFromSnapshot → null. Latest 2048 from
local then Blob. No stream, no thinking (thinking is not in SessionStore).
Expected #924 bullets 1–2 are already true for idle sessions.

Already shipped (do not re-solve)

There is no “hydrate tail page from Blob Range” API and no “skip
reasoning on attach” flag. #924 is a policy change on
kickColdAttach / prefixThroughLastUser / reasoning_delta, not a new
transport.

#924 requirement (non-negotiable)

The spike winner, then the follow-up plan, must deliver all three:

1. Refresh / cold open of a large session lands on the latest viewport
   (tail) — not a chronological replay from the starting prompt.
2. Thinking rows are not streamed or replayed on hydrate (collapsed /
   omitted until the operator explicitly expands or a new live thinking
   segment starts).
3. Live attach (turn still running / cancelling) resumes from a cursor
   / tail without replaying the whole history at UI speed. Busy + Stop must
   still restore.

Closing this spike’s follow-up plan closes #924. #924 stays open until
that ships and the e2e int rows below are green.

End-to-end integration tests (non-negotiable)

The follow-up create-plan DoD must include durable-turn int coverage.
This is a close gate, same class as “must close #924”: a merge that
flips attach policy without these rows is not done.

Where: int/ (npm run test:int). Load a real protocol-current
harness.wasm via int/loadBridge.ts. Fail closed if Wasm is missing
or stale (throw, never it.skip). Helpers already in tree:
bootFromMemory, hydrateRing, ringTexts, int/stores.ts.

Required rows (map 1:1 onto the three #924 bullets):

Keep an idle / completed F5 regression: no stream, latest page (already true
on main; do not drop it).

If leftover 2 (slim local) or 3 (scrollbar / load-earlier) ships in
the same cut, those need int rows too: persist/hydrate of a large transcript
must not require the full snapshot in localStorage; load-earlier prepend
must come from a Blob page, not “host already holds all rows.”

Existing int/f5-attach.int.test.ts currently locks the #859
startIndex: 0 cold-attach contract. That expect is #924. The
follow-up must rewrite those rows to the new contract (or wrap only the
pre-flip expects in it.fails until the phase that changes them). Do not
leave the old startIndex: 0 assert green as “coverage.”

Do not substitute lib/harnessChat.wasm-int.test.ts (protocol supply) or
app/api/turns/[runId]/stream/route.test.ts (HTTP startIndex parsing)
for this gate. Those stay; they do not prove F5 hydrate.

Likely multi-phase follow-up (not required)

Leftovers 1 / 2 / 3 are separable cuts. #924 (live F5 policy) can ship
without slim-local and without a document scrollbar.

The spike write-up decides whether they are one cut. If they are not,
the follow-up should be a parent create-plan with phase issues (same
shape as A4 #947 → #948–#952) so #924 is not blocked on scrollbar work.
If they are one cut, a single plan is fine.

Multi-phase is the likely shape, not a mandate. Do not invent phases
before the spike names the cut.

Reminder — one GitHub issue per phase / per PR. Invincible ships one
PR per GitHub issue. If this is multi-phase, each phase MUST be its own
issue (own DRAFT → HANDOFF-READY → IMPLEMENTED lifecycle, own PR). A
single issue that lists several phases shipping in separate PRs is
forbidden — when Phase 1 is marked IMPLEMENTED the issue closes and
Phase 2 has no home. N PRs → N phase issues plus a parent that is
tracking-only (never implemented). Do not implement this spike, the
parent, or “phase 1+2 on one issue.”

Spike questions (answer these against main)

1. F5 of a live turn (bug: F5 / reload fast-forward replays entire durable stream (need latest-page hydrate, no thinking replay) #924-1, bug: F5 / reload fast-forward replays entire durable stream (need latest-page hydrate, no thinking replay) #924-3) — Hydrate the Blob/checkpoint
   tail into Wasm (do not prefixThroughLastUser wipe), then
   GET .../stream?startIndex=C for new frames only. Can Busy + Stop
   restore without applying historical reasoning_delta? What is C when
   local turnStreamCursor is stale vs envelope C vs heap 0?
2. Thinking on hydrate (bug: F5 / reload fast-forward replays entire durable stream (need latest-page hydrate, no thinking replay) #924-2) — Skip reasoning_delta on cold attach,
   or do not subscribe the historical stream at all? Collapsed “thought”
   placeholder vs omit. Must not lose live thinking that starts after
   attach. Today’s lock (“never skip, thinking is not in Blob”) is the bug,
   not a feature to preserve.
3. Slim local (leftover spike: viewport hydrate — latest-page F5 (#924), slim local, scrollbar (A5 rebase) #553) — Persist only the latest ring window +
   envelope carriers (transcriptPointer, turn ids/status/cursor). Full
   history stays on Blob. First paint reads the slim tail; 409 adopt still
   the latest window. Does Stop persist still need a full snapshot locally?
   Independent of Range; can ship with the F5 fix if the spike says they are
   the same cut.
4. Load-earlier / scrollbar (leftover spike: viewport hydrate — latest-page F5 (#924), slim local, scrollbar (A5 rebase) #553) — Keep stepping
   session.messages (requires the host to already hold older rows — fights
   slim-local), or host-GET the previous Blob chunk via prev and prepend
   a page, Wasm paints the window only, jump-to-latest is O(1) (re-hydrate
   tail). Preference: feels like one document; almost never scroll to the
   beginning. Do not treat the existing “Load earlier” button as this
   question already answered.
5. Completed long session — No stream. Blob GET is still the full
   flatten-root JSON (up to 8 MiB) then the host slices 2048. Is reconstruct
   still stuffing the full chain into snapshot.messages before the ring
   slice? Slim-local + chunk walk on demand is the leftover of original
   spike: viewport hydrate — latest-page F5 (#924), slim local, scrollbar (A5 rebase) #553 Q2/Q3.

Dropped as a primary question: HTTP Range over one messages[] object
(original Q1). Whole-object PUT + existing prev/depth already answered it.
The three original Blob options are stale as a “does this exist?” question:
main already picked a hybrid of rewrite-OK flatten (option 2) + mid-turn
prev chunks (a bit of option 3). Remaining work is viewport policy
(#924) + slim local + scrollbar, not a new object layout.

Preference (still)

• One logical transcript (flatten root + mid-turn chunks), not thousands of
  part/*.json / SQLite-in-browser.
• Do not want 8 MiB localStorage for first paint.
• Almost never scroll to the beginning; if A1–A4 work, ask the agent instead.
• Feature-divide: host fetches, Wasm paints the window only. No dual
  DOM transcript.

Out of spike scope

• Changing the inference fold (A1–A4). Compaction docs are Phase 5 / plan: A4 compaction — phase 5 — living docs (source #552) #952.
• Implementing OpenCode SQLite / part/*.json
• Raising Function body caps / 1-hour turn wall (harness: hard-cap durable turn wall clock at 1 hour (Bjorn authorized) #923)
• Cancel/Busy unstick (bug: harness stays Busy (Waiting for model…) after Workflow run is cancelled #915)
• Occupancy meter (status bar: show current context occupancy in addition to summed turn usage #556)
• Changing existing caps (HARNESS_RING_MAX 2048, HISTORY_PAGE 512,
  Blob 8 MiB, envelope 1 MiB, prev depth 256) — any change is a BLOCK +
  human decision on the follow-up plan.

Suggested next

Spike write-up on this issue (decision table + recommended option) that
explicitly maps to the three #924 expected bullets and names the e2e int
rows above. Then a separate create-plan for the winner; that plan’s DoD
Closes #924 (and this spike) and requires the int rows green.
Slim-local tail can ship with the F5 fix if the spike says they are the
same cut; otherwise expect a parent + phases (likely, not required) —
one GitHub issue per phase, because one GitHub issue per PR.

Peer harness notes

OpenCode before / after / limit + RFC 8288 is a useful host API
shape if we page Blob chunks — not a reason to shard parts or run SQLite
in the browser.

Pi stream offset via SessionManager is closer to resume at startIndex=C
(already on the wire) than to byte-Range on one object.

References

• Must close: bug: F5 / reload fast-forward replays entire durable stream (need latest-page hydrate, no thinking replay) #924 — F5 / reload stream replay (gated on e2e int rows)
• Must ship: durable-turn int coverage (int/, npm run test:int) for the bug: F5 / reload fast-forward replays entire durable stream (need latest-page hydrate, no thinking replay) #924 bullets
• Parent umbrella: agent session architecture — model-context memory, compaction, and viewport #548 (A5)
• Existing int that currently encodes the bug: int/f5-attach.int.test.ts (startIndex: 0)
• Attach shipped: backend-agents E19: attach handshake — Blob hydrate + stream attach #813 / backend-agents F: viewport attach — GET stream + Blob hydrate + live thinking/tools/status #769 / backend-agents A3: reserved meta.turnStreamCursor carrier #797 (turnStreamCursor)
• Ring window shipped: plan: harness reveal earlier transcript messages (parent) #238 / plan: harness reveal earlier messages — phase 1 — in-ring reveal + docs #239 / plan: harness reveal earlier messages — phase 2 — session window beyond ring #240 (idle latest-page only; not the live F5 fix)
• Thinking collapse (paint cost, not skip-on-refresh): plan: harness — auto-collapse completed-turn thinking (expandable, dvui cost) #428
• Session model: https://github.com/btipling/invincible/blob/main/docs/session-model.md
• Feature-divide: https://github.com/btipling/invincible/blob/main/docs/feature-divide.md