Skip to content

Ticket #141 verification — scoped reads and transcript windows — 2026-11-07 ​

Parent spec #130, child ticket #141 (gated Tier 3 scoped bootstrap, Work projection, transcript windows, on-demand results, server counts). Worktree /home/tristan/dev/ensemble-t141, branch ticket/141-scoped-reads, based on integration/ensemble-v7 at f12eda8 and merged with the final integration tip 833f0de (#142) before this pass.

Environment ​

sh
export PATH=$HOME/.nvm/versions/node/v26.12.1/bin:$HOME/.local/bin:$PATH
  • Node v26.12.1, npm 12.2.1
  • OpenCode 2.2.6 (local host; package lock pins @opencode/plugin 2.2.1)
  • tmux 3.5a, Linux
  • node_modules symlinked from the parent checkout; it is gitignored and no tracked file depends on the link.

Command results ​

Exact commandResult
npm run checkExit 0; strict no-emit TypeScript check.
npm run verifyExit 0; 921 passed, 0 failed.
git diff --checkExit 0; no whitespace errors.
npm run test:live:fakeExit 0; full deterministic fake TUI scenario, including Work groups, settings, approvals, skills, and streaming.

The four-size matrix (npm run test:live:sizes) was not rerun: this ticket does not change card layout or animation, and #142's recorded matrix remains the valid visual evidence. The Work group helpers were split into a shared domain module; their existing unit tests and the full fake TUI scenario pass.

Tier 3 gate decision ​

src/v2/scoped-read.ts is the only gate policy. Scoped bootstrap/projection engages when any of:

  • durable messages >= 1,000,
  • retained task rows >= 500,
  • the last measured full snapshot payload >= 512 KiB,
  • the last measured full snapshot build >= 120 ms.

Small workspaces keep the full snapshot path; the response records the gate, its reason, and its measured inputs. Epoch changes, malformed feeds, and a failed scoped read still fall back to the full snapshot.

Measured budget ​

The large-history service test seeds 10,000 durable messages and 602 retained tasks (600 long-terminal rows plus one visible group), then calls the scoped bootstrap handler over durable storage:

MeasureObservedBudget
Bootstrap payload26,367 B< 128 KiB
Bootstrap latency~8 ms< 500 ms
Transcript rows in payload40one active window
Work rows in payload2visible group only

The client-memory benchmark applies 5,000 message patches plus 1,000 invisible terminal tasks:

MeasureObservedBudget
Loaded message rows240CLIENT_MESSAGE_LIMIT
Loaded Work rows1 (active)visible projection
5,000 patch applications~80 ms< 5,000 ms

Scoped recovery ​

The store records the latest version that changed shell, work, and transcript. A gap calls changes.since, derives only the scopes with a version newer than the client cursor, and calls resync with exactly those scopes. The service test proves a work-only gap returns no shell or transcript payload, and a shell/transcript gap returns no Work payload.

Residual risks ​

  • Unread/busy counts are recalculated on the revision heartbeat, bootstrap, and scoped resync rather than on every patch; the rail may trail a live message by up to one heartbeat (1 s active, 2 s idle).
  • Older transcript pages are fetched by keyboard scrolling (PageUp/Top and scroll-up keys). Mouse-wheel pagination is not wired through the host scrollbox API.
  • Client windows keep the newest 240 rows; paging far back can evict the newest rows until the next latest-window refresh.
  • macOS/Herdr checks remain for #143.

Released under the MIT License.