Files
PaperClipAI/tests/perf/issue-detail
DottaandClaude Opus 5.5 ecdeed5e7e perf(ui): open a task restored from the saved read cache through the chat bootstrap (#21650)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The board UI opens a task page as a chat. A hard load of a task URL
starts one chat bootstrap request before the app's JavaScript runs.
> - A returning browser also restores a saved read cache from local
storage. This cache holds the core fields of recently opened tasks, but
no chat history.
> - The task page started the bootstrap only when the core task was not
cached. A restored core task skipped it. The early bootstrap request
ran, but nothing used its answer.
> - So every first-frame read went to its own endpoint, and the comment
input facts waited for the recent comments. A returning load was slower
than a cold load: on staging, 3.6–3.8 s against 1.9–2.4 s.
> - This pull request treats a task that only the saved cache holds as
cold for the chat. The page adopts the bootstrap, the restored task's
own revalidation shares it, and the answer replaces the restored data.
> - The benefit is that a returning load is now faster than a cold load,
not slower.

## Linked Issues or Issue Description

**Describe the bug**
A hard load of a task page is slower when the browser has a saved read
cache than when it has none. Measured on staging on 2026-11-14 (hard
load, JavaScript in the HTTP cache, 3 alternating pairs on one task):
saved cache cleared 1.9–2.4 s, saved cache present 3.6–3.8 s, until the
chat composer exists.

**Steps to reproduce**
1. Open a task page so that the saved read cache
(`paperclip:query-cache:v1:*`) holds it.
2. Close the tab and open the same task URL again.
3. Compare the time to the first chat frame with a load where the saved
read cache is cleared.

**Expected behavior**
A load with a saved read cache is at least as fast as a load without
one. The chat's first-frame reads share the one bootstrap request.

**Actual behavior**
With a saved read cache, the bootstrap request runs but its answer is
not used. About 16 more per-endpoint reads run before the frame, and the
frame waits for a second, serial wave of reads.

Related: #20355 (chat bootstrap endpoints), #20592 (cold task open from
one bootstrap), #20591 and #20594 (returning Mine inbox from the saved
read cache), #21557 (cold-load perf spec).

## What Changed

- `ui/src/lib/persisted-query-cache.ts`: records which queries a page
restored from the saved read cache. `isRestoredSavedRead(client, key)`
is true until a read or a local write in this page replaces that data.
- `ui/src/pages/IssueDetail.tsx`: starts (or adopts) the chat bootstrap
when the core task is missing or only restored. It passes the restored
task's id and identifier as aliases, so reads keyed by the id share the
request while it loads.
- `ui/src/lib/issue-chat-bootstrap.ts`: `readFromIssueChatBootstrap`
lets a key that holds only restored data share the bootstrap, like an
empty key. `startIssueChatBootstrap` accepts aliases.
- `ui/src/lib/issueChatBootstrapCache.ts` and
`ui/src/lib/issueDetailCache.ts`: the bootstrap answer replaces restored
data (core task under every ref). The restored core task's revalidation
shares the bootstrap. A core task that was read in this page keeps its
own small read.
- `ui/src/hooks/useIssuePlanDocument.ts`: the first plan read shares the
bootstrap's plan projection instead of reading `documents/plan` before
the frame.
- `tests/perf/issue-detail/cold-bootstrap.perf.spec.ts`: an always-on
request-shape test for a returning load with a saved read cache, and an
opt-in benchmark of alternating pairs (saved cache present and cleared).
The harness now clears storage after the warm-up page closes, because
closing the app saves its read cache again.
- `ui/src/lib/restored-task-chat-bootstrap.test.ts`: unit tests for the
restore-then-bootstrap path.
- `tests/perf/issue-detail/README.md`: documents the returning-load test
and benchmark.

## Verification

Local production build (`PAPERCLIP_UI_DEV_MIDDLEWARE=false`),
local_trusted instance, CDP delay of 300 ms on every API request, fresh
browser context per run, JavaScript in the HTTP cache. Time from
navigation start to the revealed history with the latest message and an
editable composer.

| Build | Saved read cache | Runs | Median | Spread | API requests
before frame | Frame released by |
| --- | --- | ---: | ---: | ---: | ---: | --- |
| master `95a6ab31e6` | cleared | 5 | 913 ms | 908–957 | 33 | company
list (shell stage 2) |
| master `95a6ab31e6` | present | 5 | 1,204 ms | 1,178–1,215 | 49 |
`activity?view=comment-inputs` (serial second wave) |
| this PR | cleared | 7 | 942 ms | 925–997 | 35 | company list (shell
stage 2) |
| this PR | present | 7 | 573 ms | 566–658 | 37 | app boot and route
mount (all task data is the bootstrap) |

- Paired delta with this PR (present − cleared): median −376 ms over 7
pairs, all negative (−267 to −400). On master it was +292 ms over 5
pairs, all positive.
- With an 800 ms API delay (this PR, 5 pairs): present 890 ms, released
by the bootstrap response; cleared 1,910 ms.
- Cold load with no app storage (existing benchmark, 7 runs): master 910
ms, this PR 939 ms. The host load average was about 20 during the PR run
(other work on the machine). Requests before the frame are 35 in both. I
make no claim of a cold change.
- Request-shape tests (`cold-bootstrap.perf.spec.ts`): the new
returning-load test fails on master (the timeline shows `?view=core`,
`recent-comments`, `activity`, `runs`, `interactions`, `attachments`,
`live-runs` before the frame) and passes with this PR. The existing cold
test passes.
- Unit tests: `restored-task-chat-bootstrap.test.ts` has 10 cases. With
the behavior changes reverted (the restore marker kept so the file
imports), 3 fail: the bootstrap refreshes the restored task and fills
the chat, id-keyed reads share the loading bootstrap, and a partial
answer. All 10 pass with this PR. The other 7 cases are guards that hold
on both: a stale refresh reads the server, a failed bootstrap falls
back, a 403 removes the restored task from memory and storage, another
company's answer is not seeded, an answer is not used after another user
signs in, and another user's saved task is not restored.
- Focused Vitest: 27 files that use the changed modules, including
`IssueDetail.test.tsx` and `TaskChatThread.test.tsx`: 1,208 passed.
- Browser layout journeys against the PR build:
`layout-stability.spec.ts` and `plan-startup.spec.ts`, 17 of 17 passed
(reveal order, reading anchor, older history, Back, comment links,
drafts during background refresh, failed and stalled reads with Retry,
plan projection with stalled plan reads).
- `pnpm verify` exit 2 (the README is a global CI input), so required CI
supplies the broad coverage.

Commands:

```sh
cd ui && npx vitest run src/lib/restored-task-chat-bootstrap.test.ts
PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:<port> pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts cold-bootstrap
PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:<port> PAPERCLIP_ISSUE_PERF_COLD_RUNS=7 pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts cold-bootstrap -g returning
```

## Risks

- Low risk. The change only affects data that the saved read cache
restored and that no read in this page has confirmed. Data read in this
page keeps the old rule: a refresh asks the server.
- The saved read cache content is unchanged. It still excludes comments
and bootstrap payloads, so the first chat frame still needs one response
(the bootstrap). It cannot appear before any task response without
saving chat history, which the documented allowlist excludes.
- If the bootstrap fails, stalls or omits the task, each read falls back
to its own request, as on a cold load. A 403 or 404 on the restored
task's fallback read removes it from memory and storage, as before.
- Account changes: a bootstrap answer is bound to the session's user, as
before. The saved cache restores data only for the same user.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, browser automation through
Playwright).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 15:16:43 -06:00
..

Issue-detail performance baseline

Run the repeatable baseline from the repository root:

pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts

The rig starts an isolated seeded Paperclip instance, runs five samples for each scenario/profile, and writes median-ready raw data plus a Markdown table to test-results/issue-detail-perf/.

Scenarios:

  • S1 warm in-app navigation: loads the Issues list, clears the waterfall, and clicks the seeded issue.
  • S2 cold open: creates a fresh browser context and deep-links to the seeded issue.

Profiles:

  • Unthrottled.
  • Fast 4G network with 4x CPU slowdown.

Override the sample count (minimum five) or port when needed:

PAPERCLIP_ISSUE_PERF_RUNS=7 PAPERCLIP_ISSUE_PERF_PORT=3210 pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts

S1 clicks as soon as the list row is visible. Set PAPERCLIP_ISSUE_PERF_LIST_DWELL_MS=1500 to wait on the list first, as a person does. Task lists preload the chat of their top rows after the list's own reads settle, so S1 with a dwell measures a preloaded open and S1 without one measures an open that usually has to read the task.

Outputs include baseline.md, baseline.json, and a Chrome trace for the first run of each scenario/profile. Open *.trace.json in Chrome DevTools Performance to inspect the issue-detail:* user-timing marks.

Set PAPERCLIP_ISSUE_PERF_PROFILE=1 to capture actual Chrome CPU samples and conversation-readiness transitions in one diagnostic sample per scenario/profile. Import the resulting *.cpuprofile in DevTools and inspect *.readiness.json for the task, comments, metadata, activity, runs, runtime, plan and transcript gates. Each gate records changes with detail.ready; use its last transition before content paint when a gate becomes pending after mount. These diagnostic runs include profiler overhead. Run without the flag for before/after latency claims. Readiness marks stay in the local browser and contain only fixed gate names and booleans; the harness enables them before navigation.

For bundle comparisons, build the UI and serve the production assets from an isolated local instance with PAPERCLIP_UI_DEV_MIDDLEWARE=false. The default managed server above uses development middleware, which does not reproduce production chunk loading. Keep the server, database, browser profile and sample count the same for both builds, and avoid concurrent builds or test suites while measuring latency.

Copy the first run's output outside test-results/issue-detail-perf, then reuse its persisted task with PAPERCLIP_ISSUE_PERF_SEED_FILE=/path/to/before/baseline.json and PAPERCLIP_ISSUE_PERF_BASE_URL pointing to that disposable instance. The harness validates the task identity before measuring. Network spans in the trace use recorded request start/end timestamps relative to task navigation; they include completed requests observed during the sample, even after content paint.

Cold direct task load (chat bootstrap)

A hard load of a task URL starts GET /api/issues/:ref/chat-bootstrap from the inline preload script, before the app's JavaScript loads. The chat's first-frame reads share that answer (ui/src/lib/issue-chat-bootstrap.ts) and fall back to their own requests when it fails, lacks a field, or stalls.

cold-bootstrap.perf.spec.ts delays every API response (300 ms by default) so serial request stages show up as wall-clock time. It opens the task by URL in a fresh browser context with the app's JavaScript in the HTTP cache and no app storage. The finish event is the revealed history with the latest saved message and an editable composer. Its request-shape test always runs: one bootstrap request, no per-endpoint first-frame read before the frame, and no such read completing before it. Reads that start after the live socket connects are its catch-up refresh and are excluded. The benchmark is opt-in:

PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:3287 \
PAPERCLIP_ISSUE_PERF_COLD_RUNS=7 PAPERCLIP_ISSUE_PERF_LABEL=candidate \
  pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts cold-bootstrap -g benchmark

It writes cold-bootstrap-<label>.{json,md} with the median, spread, the request count before the frame, the requests that finished last before it, and the first run's request timeline. PAPERCLIP_ISSUE_PERF_API_DELAY_MS changes the delay. PAPERCLIP_ISSUE_PERF_COLD_HTTP_CACHE=1 downloads the JavaScript on every run. Serve a production build (PAPERCLIP_UI_DEV_MIDDLEWARE=false).

Returning direct task load (saved read cache)

A returning browser restores the saved read cache (paperclip:query-cache:v1:*) before the first render, including the core fields of recently opened tasks. Chat history is never saved, so the restored task's chat still reads the bootstrap. Its reads, including the restored task's own revalidation and its plan projection, share that one request instead of reading each endpoint. The always-on request-shape test checks this with a saved cache. The opt-in benchmark runs alternating pairs with the saved read cache present and cleared (other app storage kept) and writes returning-task-<label>.{json,md}:

PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:3287 \
PAPERCLIP_ISSUE_PERF_COLD_RUNS=5 PAPERCLIP_ISSUE_PERF_LABEL=candidate \
  pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts cold-bootstrap -g returning

Closing a page saves its read cache, so the harness clears storage from a separate same-origin page after the warm-up page closes.

Real-instance click harness

Local fixtures cannot reproduce staging's network round trips, server contention or object-store latency. staging-click-harness.js measures the same journey on any running instance, including staging, from the signed-in browser:

  1. Open an Issues list, for example /<company>/issues?view=mine.
  2. Paste the file into the DevTools console (or evaluate it through a browser automation tool).
  3. Run await __taskOpenHarness.series(["ABC-1", "ABC-2", "ABC-3"]).

Each sample reports the time from the row click to a visible composer and to the latest message in the viewport, the requests started before that point, the requests that finished last before it (releasedBy), the slowest and repeated requests, layout shifts, and any movement of the latest message after it first appeared. serverMs comes from the paperclip_api Server-Timing entry that every API response carries, so a long duration with a short serverMs points to the network or browser queueing rather than the handler. A fetch that is still running when the sample ends is listed with pending: true. Run samples serially and record whether each task's data was already cached (a revisit) or not.

The summary labels each sample (sample 1, ...) instead of the task reference. It replaces query values and every path segment that contains a digit with a placeholder. Other path segments can stay, so review the output before you share it outside the instance.

Task layout stability

The normal browser CI suite also runs tests/e2e/task-loading-frame.spec.ts. It seeds a smaller API-only task and checks desktop/mobile frame and composer geometry, title typography, the initial reading position, Classic preference loading and typography, mobile shell handoff, and a stalled font request. It does not require a separate database URL. The rich 200-message fixture below remains an additional local stress journey.

loading-layout.spec.ts uses a retained synthetic task with a wrapping title, 200 saved messages, document and PR cards, a monitor, and a pending confirmation. It records every animation frame during direct and list-based entry on desktop and mobile, including delayed web fonts and workspace preferences. It rejects real headers shown before the initial conversation is ready, loading-frame movement, different header typography, composer displacement, and movement of the initial reading position. The fixture requires the disposable PostgreSQL URL described below. Its agent has interval and on-demand wakes disabled, including when the retained fixture is reused. The suite does not start provider work. Videos, screenshots, and frames.json are retained with each result.

compact-startup.spec.ts keeps a synthetic local reproduction with 24 messages, a plan, three documents and three saved PR cards. It holds the enriched task response, records each visible frame's card count and geometry, and rejects cards inserted after the conversation becomes readable. It also checks document, older-comment and unknown anchors without full comments/activity/run reads. Run it with the same loopback-only URL override below. The fixture URL is saved in test-results/compact-startup-fixture.json for manual inspection and reuse. It also checks a delayed Coordinator preference with Classic enabled, index-based Coordinator list navigation, and the responder identity through reassignment, comment acknowledgement and legacy runtime discovery. The last case uses a deterministic local process, records identity continuity on each frame, and saves startup/running screenshots. It does not call a model provider. Each send fixture uses a unique task title so repeated runs cannot reuse a previous task and its cancelled run through ordinary task deduplication.

layout-stability.spec.ts exercises the real task route, including Inbox navigation, with 160 Markdown comments and a resolved interaction. It delays initial comments, tests failures and retry, tracks a reading anchor across media growth, composer resizing, properties toggles, older-page loading and Back navigation, and covers mobile reduced motion and explicit comment links. The eight scenarios also exercise same-task hash navigation without remounting on desktop and mobile, and stalled native/log reads that expose Retry after the 15-second request deadline. plan-startup.spec.ts opens tasks directly and from the task list, with and without a saved plan, while holding separate plan reads. The core projection must reveal the saved conversation and plan before those reads finish. Separate plan reads are recorded as diagnostics. The hook tests cover fallback reads for list-only snapshots and responses without a plan projection. Videos and per-frame layout.json measurements are written under each test's output directory. The two-pixel assertion measures a logical row's viewport offset; total scroll offset legitimately changes when history is prepended.

Ordinary task opens defer the concealed history and composer until their initial data is ready. The skeleton and scroll/composer containers retain their geometry. Compact tasks reuse saved replies from completed runs. Their transcript reads start when the reader opens older history through More messages or More run output. Saved Plans from completed runs stay visible while their output is deferred or pending. Live runs, failures, yielded runs, explicit anchors, and runs without a saved reply still load their output. A transcript already shown during this visit stays mounted when the run completes. Comment-link navigation prepares content eagerly so the target can be positioned before reveal. Revealed content stays mounted during refresh. The draft scenario holds a background task read, checks the same editor remains mounted, reloads the saved draft, sends one reply, and independently checks its persisted comment.

To run against an existing disposable local test-drive instance:

PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:3102 \
  pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts layout-stability.spec.ts

The suite creates its own company and fixtures. The URL override accepts only loopback origins and rejects remote hosts. Use a disposable local instance, not a shared or production instance. Without the override, the harness starts its own isolated instance as before. Live provider walkthroughs additionally require a configured native Paperclip runner and Codex authentication; deterministic browser fixtures do not substitute for watching an actual provider run.

saved-reply-startup.spec.ts adds a PostgreSQL fixture with 200 long saved agent replies, 200 completed native runs, and a Plan linked to the latest run. It holds transcript requests, checks both task presentations on desktop and mobile, and measures reply positions on each frame. Opening older history must start the transcript reads and preserve the editor and draft. This case is skipped unless PAPERCLIP_ISSUE_PERF_DATABASE_URL points to a disposable loopback PostgreSQL database whose name ends in _test. Use the same database as the local server:

PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:3102 \
PAPERCLIP_ISSUE_PERF_DATABASE_URL=postgres://paperclip:paperclip@127.0.0.1:5432/task_loading_test \
  pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts saved-reply-startup.spec.ts

For the live walkthrough, first assign a disposable task to a native Paperclip runner configured with the Codex provider. Its scratch project should contain a small sum.mjs fixture. The script sends a paced job, scrolls up, disconnects and reconnects, steers a follow-up, and records through completion:

PAPERCLIP_LAYOUT_LIVE_URL=http://127.0.0.1:3102/LAY/issues/LAY-8 \
  node tests/perf/issue-detail/live-feed.walkthrough.mjs

Inspect test-results/task-layout/live-acceptance/ for the video, screenshots, per-frame positions, layout shifts, browser timing counters, and reading-anchor measurement. The live script rejects non-local URLs and uses real provider capacity. Review the video as well as the assertions: layout-shift scores alone do not capture programmatic scrolling or replacement flashes.

Long-running agent chats

The separate agent-chat performance rig covers recent-only startup and scrolling history with long-lived conversations. It is opt-in and does not run in this task-detail rig.