## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - People often open a task by its URL, for example from a link in a message or after a reload > - #20592 made a hard load of a task URL read the chat's first frame from one `chat-bootstrap` request > - The task page still sends a large read as it mounts: 100 full recently updated tasks for the `@task` mention picker. On staging this read returned 395 KB and took 3.9 s of server time > - The hosted database is CPU-bound, so reads that do not affect the first frame must not compete with the reads that do > - Also, no test measured a cold direct load under realistic latency or guarded the one-bootstrap request shape > - This pull request starts the mention pool after the task page settles. It also adds a cold-load perf spec with a delay on each API request and an always-on request-shape test > - The benefit is less concurrent server work during a cold task open, and a regression guard for the one-round-trip first frame ## Linked Issues or Issue Description Refs #20592 (hard-load chat bootstrap that this pull request measures and guards). Refs #20355 (the `chat-bootstrap` endpoints). **What existing behavior does this improve?** The task page loads the `@task` mention pool when it mounts. **Subsystem affected** Board UI task page (`ui/src/pages/IssueDetail.tsx`) and the issue-detail perf harness (`tests/perf/issue-detail`). **Current behavior** `GET /api/companies/:id/issues?limit=100&sortField=updated&sortDir=desc` starts with the chat's first-frame reads. It starts before the first chat frame in 14 of 14 local cold loads. The picker needs it only after the person types `@`. **Proposed behavior** The read starts after the page has painted and its own reads have finished. On a page that keeps reading, it starts after at most 5 s. **Reason and benefit** The read never affects the first frame. Deferring it removes a large concurrent read from the busiest part of a cold open. **Breaking changes** None. If the person types `@task` in the first moments after a cold load, the task suggestions can appear about half a second later. ## What Changed - `ui/src/hooks/usePageSettled.ts`: new hook. It returns `true` once `whenPageSettles` runs (the page has painted, the tab is visible, no query is fetching, and the browser is idle), or after `PAGE_SETTLED_MAX_WAIT_MS` (5 s). The cap keeps a long-running read from keeping the picker empty. - `ui/src/pages/IssueDetail.tsx`: the mention-pool query is enabled only when `usePageSettled()` is true. - `ui/src/hooks/usePageSettled.test.tsx`: tests that the hook waits for in-flight reads and that the cap applies. - `ui/src/pages/IssueDetail.test.tsx`: mocks the hook to `true`, so existing tests keep their behavior. - `tests/perf/issue-detail/cold-bootstrap.perf.spec.ts`: new spec. It delays every API response (300 ms by default) and opens the task URL in a new browser context, with the JavaScript in the HTTP cache and no app storage. The finish event is the first readable frame: the history is revealed, the latest saved message is visible and the composer is editable. - The request-shape test always runs. It requires one `chat-bootstrap` request and no per-endpoint first-frame read before the frame. Reads that start after the live socket is created are excluded, because they are its catch-up refresh. - The benchmark runs only when `PAPERCLIP_ISSUE_PERF_COLD_RUNS` is set. It writes the median, the spread, the request count before the frame, the last requests before the frame, the JavaScript bytes transferred and a request timeline. - The delay uses CDP `Fetch` interception instead of Playwright routing, because routing disables the HTTP cache. - `tests/perf/issue-detail/README.md`: documents the spec. - My earlier draft also added a deadline for a stalled bootstrap. Master already has one (`CHAT_BOOTSTRAP_SHARE_DEADLINE_MS`, 5 s), so this pull request does not include it. ## Verification Measurement setup: - Production UI builds of master `4a78124a3e` and of this branch, served by one local server (`PAPERCLIP_UI_DEV_MIDDLEWARE=false`, embedded PostgreSQL). - A delay of 300 ms on each API request. - Cold direct task URL with 24 saved comments and a plan. - Master and the branch alternated: 2 rounds of 7 runs each. - The host was shared with other agent sessions. | Build | Runs | First readable frame, median | p25–p75 | Min–max | API requests before frame (median) | Mention pool started before frame | |---|---:|---:|---:|---:|---:|---:| | master | 14 | 1,422 ms | 1,336–1,525 | 1,284–7,398 | 50 | 14 / 14 | | this branch | 14 | 1,390 ms | 1,338–1,457 | 1,272–2,207 | 49 | 0 / 14 | - The spec adds the API delay through CDP request interception, so the HTTP cache stays on. The measured loads downloaded 0 KiB of JavaScript in every run. The spec records this as `jsTransferBytes`. Each build has one outlier (7,398 ms on master, 2,207 ms on this branch), from host contention. - With this branch, the mention pool starts after the frame in every run (350–400 ms after it in an earlier set). - The first-frame timing is neutral locally. The local database answers the pool read in milliseconds, so it does not compete with other reads. The intended benefit is lower concurrent server load on a busy database. This pull request does not show it as a local latency gain. - On master and on this branch, the hard load adopts the bootstrap and the frame is no longer held by task reads. The frame now comes right after the shell reads return: `auth/get-session` and `instance/settings/experimental`, then `companies` and `workspace-preferences/me`. Profiling marks confirm this: the chat thread mounts after `workspace-preferences/me` returns, and all readiness gates are ready within 30 ms. - The request-shape test passed 5 of 5 on master and 5 of 5 on this branch. - `layout-stability.spec.ts`, `plan-startup.spec.ts` and `cold-bootstrap.perf.spec.ts` against this branch's build: 18 passed. - `ui` Vitest for `usePageSettled.test.tsx` and `IssueDetail.test.tsx`: 278 passed. The `ui` typecheck passed. `pnpm check:token-gates` passed. - `pnpm verify` exits 2 because `tests/perf/issue-detail/README.md` is a global CI input. Required CI supplies the broad coverage. To reproduce the measurement: ```sh PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:3287 PAPERCLIP_ISSUE_PERF_COLD_RUNS=7 PAPERCLIP_ISSUE_PERF_LABEL=branch \ pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts cold-bootstrap -g benchmark ``` ## Risks - Low risk. The only product change is when one read starts. - If the page keeps a query in flight, the pool waits up to 5 s. During that time, `@task` suggestions list only agents, projects and members. - The request-shape test treats reads that start after the live socket is created as catch-up refreshes. If the socket connects before the task page mounts, such a test would not see a first-frame read that started later. The test still requires exactly one bootstrap request before the frame. - The perf spec is not in the default CI browser suites. It runs when the issue-detail harness runs. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used in Claude Code with tool use (shell, file editing, Playwright browser runs). It wrote the change, the tests and the measurements. ## 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 - [ ] All Paperclip CI gates are green - [ ] 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>
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).
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:
- Open an Issues list, for example
/<company>/issues?view=mine. - Paste the file into the DevTools console (or evaluate it through a browser automation tool).
- 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.