## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The board UI keeps one live-updates WebSocket per company and saves
a copy of its query cache in `localStorage` so a returning visit can
paint from it
> - On a returning hard load of the Mine inbox, about eight shell and
inbox reads ran a second time 1.5–2.5 s after load (session, health,
company list, agents, inbox dismissals, user directory, approvals,
execution workspaces)
> - The cause is the socket's sign-in key. A session restored from the
saved cache has the user but no session id. The first session read adds
the id, the key changes, the socket closes and opens again, and that
second open refreshes every active query, session and health included
> - This pull request keeps the socket when the verified session belongs
to the same user as the restored one
> - The benefit is one read of each shell request per returning load and
one socket instead of two, with no change to the catch-up read that
covers the gap before the first subscription
## Linked Issues or Issue Description
**What happened?**
A returning hard load of `/:companyPrefix/issues?view=mine` sent
`auth/get-session`, `health`, `companies?scope=accessible`, agents,
inbox-dismissals, user-directory, approvals and execution-workspaces
twice. The second copy started about 1.5–2.5 s after load on the hosted
staging instance.
**Steps to reproduce**
1. Open Mine once so the app saves its query cache.
2. Reload the page.
3. Watch the network panel. The live-updates socket opens, closes, opens
again, and the reads above repeat.
**Expected behavior**
Each read runs once. The socket opens once.
Related: #20398 (socket reconcile skips settings and preferences),
#20407 and #20419 (Mine reveal and its perf guard).
## What Changed
- `ui/src/context/LiveUpdatesProvider.tsx`: the socket auth key comes
from `nextSocketAuthScope`. When the previous scope has the same user
and no session id, the first known session id is adopted without a new
key. A different user, or a different session id once one is known,
still produces a new key and a new connection.
- `ui/src/context/LiveUpdatesProvider.recovery.test.tsx`: two tests. A
restored session (no id) verified for the same user keeps the socket and
invalidates nothing; a later replacement session still reconnects. A
verified session for another user reconnects.
- `tests/perf/collections/shell-read-waves.spec.ts` and
`returning-visit-fixture.ts`: browser checks on a production build with
every API response delayed 300 ms. With a saved cache, each of the eight
reads runs at most once and the socket opens once. Without a saved
cache, session and health run once, no read runs more than twice, and
the socket opens once.
- `tests/perf/collections/README.md`: documents the new spec and
fixture.
## Verification
- `cd ui && pnpm exec vitest run src/context/`: 16 files, 286 tests
pass. The new same-user test fails on `master` (socket count 2) and
passes with this change.
- Browser check on a disposable local instance (production UI build,
`local_trusted`, embedded PostgreSQL, Chromium headless, 1440×900, API
+300 ms):
`PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:<port> pnpm exec
playwright test --config tests/perf/collections/playwright.config.ts
shell-read-waves.spec.ts`
- `master` build (`99edcd28a7`): returning visit fails with
`{"auth/get-session":2,"health":1,"companies?scope=accessible":2,"agents":2,"inbox-dismissals":1,"user-directory":1,"approvals":1,"execution-workspaces":0}`.
- This branch: both tests pass; every count is 1 and one socket opens.
- Timing evidence (same instance, 5 fresh contexts per arm, API +300 ms,
host load average about 20; `mine-returning-visit.spec.ts` timing case
from the companion Mine PR). Duplicate shell reads are summed over the 5
loads:
| Build | Saved cache: time to rows, median (range) | Saved cache:
duplicate shell reads | Cleared cache: median (range) | Cleared cache:
duplicate shell reads |
| --- | --- | --- | --- | --- |
| `master` | 1028 ms (906–3011) | 5 (session ×2 each load) | 1502 ms
(1423–1592) | 5 (company list ×2, the catch-up) |
| This PR | 895 ms (880–930) | 0 | 1364 ms (1328–1408) | 5 (company list
×2, the catch-up) |
The time difference is small and inside host noise; the claim here is
the removed reads and the single socket. On the busier hosted instance
the second wave was larger (about eight reads), because more reads have
answered before the session read returns.
- Review follow-up (8e6e77dd4c): the scope is held in state instead of a
ref written during render, and the browser check requires exactly one
session read. Re-run after that commit: provider tests pass and
`shell-read-waves.spec.ts` passes twice.
- `pnpm verify` selected broader coverage (exit 2) because the perf
fixture is a global CI input. Required CI supplies that coverage.
- `pnpm check:token-gates`: clean.
- Not run: the full local Vitest suite, browser suites outside
`tests/perf/collections`, the hosted staging page.
## Risks
- Low risk. The socket keeps its connection only for the same user. The
cookie that opened it is the one the verified session read used.
Sign-out still drops the session, so the socket closes.
- If the cached copy and the verified session name different users, the
key changes as before, the socket reconnects, and the persisted cache
clears the old account's data as before.
- The initial catch-up read after the first socket open is unchanged. On
a first visit the company list can still be read twice, because the
socket can only subscribe after that list answers.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits, Playwright). Standard context window,
reasoning enabled.
## 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>
Tasks and Inbox cold-open checks
Run against a disposable local instance with production UI assets. The suite creates 220 unassigned backlog tasks and 110 board approvals. It does not invoke a model. The origin must be a loopback address.
pnpm --filter @paperclipai/ui build
PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:3219 \
pnpm exec playwright test --config tests/perf/collections/playwright.config.ts
Start the isolated instance with PAPERCLIP_UI_DEV_MIDDLEWARE=false to serve the
production build. The instance and its database must be disposable. These tests
retain and reuse their fixture in test-results/collections/fixture.json; they
only replace it when the previous company's API returns 404. Other errors fail.
The journeys check desktop and phone row budgets, incremental scrolling,
retained row identity and height, shared count-only navigation, the Coordinator
Inbox with Streamlined UI disabled, and the page-owned Needs You feed and Needs
attention task index. Screenshots and failure traces stay in test-results.
Request counts and row budgets are acceptance checks. They do not establish an
end-to-end latency improvement. Measure cold, warm, and Back timings separately
with the same fixture, assets, cache, viewport, and CPU/network settings.
parent-context.spec.ts holds the complete Mine response, including parent
metadata, then checks row geometry through deferred visible diagnostics. Mine
uses one assembled source read; it does not fetch parent or failed-task context
from the browser before reveal. Recent retains its separate index/context path.
startup-regressions.spec.ts covers session bootstrap and legacy fallback,
partial source errors, resolved failure context, scoped 429 recovery, and
archive/Undo persistence. Its authenticated session and failed-run responses are
simulated transport fixtures over a real local board. They do not prove hosted
login or model execution.
The embedded bootstrap case holds separate company/access responses until Mine
rows appear. Initial WebSocket reconciliation may request those endpoints in the
background; their responses must not block the first rows. Missing or mismatched
bootstrap data still requires the ordinary fallback reads.
The two 429 cases keep the existing automatic backoff and Retry-After policy.
They allow 45 seconds for its bounded retry window before exercising manual
Retry. Other cases keep the normal short assertion timeout. Timing samples do
not accelerate the browser clock.
mine-workspaces.spec.ts guards Mine against waiting on a company-wide
execution-workspace list. Its fixture (workspace-fixture.ts) adds a company
with 6,000 execution workspaces, 4,000 of them created for finished tasks, and
12 Mine tasks that each run in their own isolated workspace. The API cannot
create execution workspaces, so this fixture writes those rows to the instance
database. Set PAPERCLIP_CONFIG to the disposable instance's config.json
(embedded PostgreSQL), or PAPERCLIP_COLLECTION_PERF_DATABASE_URL to its
loopback database. The fixture is retained in
test-results/collections/workspace-fixture.json with the same 404 rule as the
main fixture. The spec routes isolated workspaces on for its own pages. It
checks that Mine requests only ids-filtered workspace summaries for the
workspaces its rows reference, that rows appear while those reads are held when
neither the Workspace column nor workspace grouping is active, and that the
Workspace column still shows each row's workspace name. Its timing case turns on
the real isolated-workspaces setting, restores it, and records cold time from
navigation start to the first Mine row (two frames after mount) over
PAPERCLIP_COLLECTION_PERF_TIMING_RUNS runs (default and minimum 5). It records
a native scenario without request interception and a separate diagnostic scenario that delays
workspace reads by 3 seconds. The timings are attached evidence, not budgets.
shell-read-waves.spec.ts hard loads Mine with every API response delayed
300 ms and counts the shell and inbox reads that used to repeat about 1.5–2.5 s
after load (session, health, company list, agents, inbox dismissals, user
directory, approvals, execution workspaces). With the saved query cache
(paperclip:query-cache:v1:<user>:<company>, primed by one earlier visit in
the same browser context) each read happens at most once and the live socket
opens once. Without it, the socket's catch-up read may repeat reads that
answered before the subscription, but never the session or health read. The
fixture (returning-visit-fixture.ts) is a company with 24 Mine tasks and
three pending board approvals, retained in
test-results/collections/mine-returning-visit-fixture.json.
recent-task-open.spec.ts covers opening a task from the sidebar's Recents.
It gives eight fixture tasks twelve saved comments each and seeds them as the
account's Recents. An idle Projects page must make exactly one
issues/chat-bootstrap request (at most ten tasks) and no per-task reads.
Clicking a preloaded task must show its latest comment without any of the
chat's first-frame reads (core issue, recent comments, comment input facts,
recent activity, recent runs, interactions, attachments, live and active run).
The full detail read and the task page's other side reads still follow the
first frame; the spec records them as an annotation. Its timing cases measure
click to the latest comment on screen over at least 5 fresh browser contexts
(empty HTTP cache and storage apart from Recents), natively and with 150 ms
added to every API response. They also record the idle page's API request
count. The timings are attached evidence, not budgets.
Run these focused browser checks before the full collection suite:
PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:<candidate-ui-port> \
pnpm exec playwright test --config tests/perf/collections/playwright.config.ts \
parent-context.spec.ts startup-regressions.spec.ts
To collect timings, build the pinned baseline production assets once and retain that output. Build candidate UI assets only when their inputs change. Serve both outputs from stable loopback origins. If server behavior changes, each origin must proxy its matching pinned API revision against the same disposable database. Using the candidate API for both arms proves only a UI comparison. Keep agents and external providers inactive. Neither arm may migrate or reseed the shared fixture during a comparison.
The harness checks the configured API against each UI proxy, records HTML and entry-asset SHA-256 receipts, and records both serving API revisions. Supply full source SHAs to label the client artifacts, then run:
INBOX_BASELINE_URL=http://127.0.0.1:<baseline-port> \
INBOX_CANDIDATE_URL=http://127.0.0.1:<candidate-port> \
INBOX_BASELINE_API_URL=http://127.0.0.1:<baseline-api-port> \
INBOX_CANDIDATE_API_URL=http://127.0.0.1:<candidate-api-port> \
INBOX_BASELINE_SOURCE_REVISION=<full-baseline-sha> \
INBOX_CANDIDATE_SOURCE_REVISION=<full-candidate-sha> \
node --import ./server/node_modules/tsx/dist/loader.mjs \
tests/perf/collections/measure-mine-context.ts
The script retains a four-parent, 30-child fixture, archives three completed
parents, and enables the personal Coordinator preference. Both APIs must expose
that same company. It runs five alternating pairs by default. INBOX_PAIRS,
INBOX_FIXTURE_FILE, and INBOX_OUTPUT override the count and evidence paths.
No request interception is used in timings.
INBOX_NETWORK_LATENCY_MS accepts an integer from 0 to 2000 and defaults to 0
(native loopback). A nonzero value uses Chromium CDP network emulation on every
page, with unlimited throughput and unchanged CPU. Record native and 100 ms
latency runs in separate INBOX_OUTPUT files; each sample labels its scenario.
CDP specifies minimum request-to-response-header latency. This controlled extra
round-trip scenario tests serial request dependencies; it does not prove hosted
latency or reproduce the full staging network.
By default, INBOX_HTTP_CACHE=warm warms each browser context once, then reloads
the document for each initial sample. This retains HTTP cache while clearing app
query state. INBOX_HTTP_CACHE=cold uses fresh browser contexts;
INBOX_HTTP_CACHE=both records these scenarios separately. Warm Recent-to-Mine
navigation and task-to-Mine Back retain query state. Use INBOX_HEADFUL=1 and
PAPERCLIP_PLAYWRIGHT_CHANNEL=chrome when installed Chrome is the intended browser.
Initial readiness requires visible Mine rows plus two animation frames. The
report retains every sample and failure, exact row membership/order, row geometry,
asset identities, full API resource timings, request statuses and primary-request
start. Health, session, board access, companies and preferences remain timing
controls. A faster initial total alone does not attribute a gain to its final
context response. The fixed post-reveal window defaults to two seconds;
INBOX_TAIL_MS changes it, up to 30 seconds. Counts retain 429s and unfinished
requests rather than treating them as successful work. Use the same immutable
asset cache policy on both origins and stop builds and suites during timing runs.
Startup cases also check that shared collection controls do not require the task-detail bundle before reveal, even when a different organization is remembered. Code warms after the collection paints, or on task-link intent. A successful immutable response allows module preloading to compile the cached chunk without executing it. A failed fetch leaves the collection usable and permits navigation without a document reload. Direct task URLs preload their static dependencies while identity is pending. These cases must run with production assets: development modules do not exercise the bundle boundaries.
The functional cases route feature settings and delayed responses. Routing
disables browser HTTP caching. For warm-cache timings, set the real local feature
settings and use fresh browser contexts without request interception. Keep normal
cache writes enabled so code warmed after paint can be used on the next task open.
Retain intercepted runs as separate diagnostic evidence.
Match the server's hashed asset cache policy (public, max-age=31536000, immutable);
Vite preview's default no-cache policy adds revalidation that the shipped server
does not require. Keep HTML uncached and return 404 for missing assets.