## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Mine inbox is the board's main list of work for one person; the
app saves its query cache in `localStorage` so a returning visit can
paint from it
> - On a hard load the saved cache gave no benefit: Mine restored its
rows but still held them until the first approvals, join-request and
dismissal reads answered, because those items sort in among task rows by
time and a late one would push rows down (#20407)
> - Those three reads were not saved, so every returning visit waited on
the network for items it showed a minute before
> - This pull request saves what Mine showed from those reads, as one
record per user and company, and lets it answer the wait on a returning
visit while every read refreshes in the background
> - The benefit is that a returning visit shows its rows with no API
response at all; the first visit keeps its bounded wait unchanged
## Linked Issues or Issue Description
**What happened?**
A returning hard load of `/:companyPrefix/issues?view=mine` with the
saved cache present (`paperclip:query-cache:v1:<user>:<company>`) showed
rows no sooner than with the cache cleared. On the hosted staging
instance, rows appeared about 40 ms after `GET
/companies/:id/join-requests?status=pending_approval` returned in 7 of
10 runs.
**Steps to reproduce**
1. Open Mine once so the app saves its query cache.
2. Delay API responses (for example 300 ms) and reload.
3. Rows appear only after the approvals and join-request reads answer.
**Expected behavior**
Rows show from the saved cache at once. The reads refresh in the
background.
Related: #20407 (kept approvals and join requests in the reveal gate),
#20408 and #20419 (Mine snapshot and its perf guard), #20591 (removes
the second wave of reads; merged), #20592 (task chat preload; merged).
## What Changed
- `ui/src/lib/inbox-mine-reveal-sources.ts` (new): the record `["inbox",
companyId, "mine-reveal-sources", userId]` holds the approvals visible
in Mine, the pending join requests, and the dismissals of those items
and of Mine's failed runs. A record over 256 KB is replaced by an empty
`incomplete` record that never answers the wait. `readMineRevealSources`
accepts a record only for the same user and company.
- `ui/src/lib/persisted-query-cache.ts`: the saved cache keeps that
record per user and company, only when its data names the same user and
company as its key.
- `ui/src/pages/Inbox.tsx`:
- Mine writes the record once approvals, join requests and dismissals
all have server answers.
- On a returning visit with a restored Mine snapshot, the saved
approvals, join requests and dismissals stand in while their reads are
pending, and after a transient failure. A refusal (401/403/404) or a
server answer replaces them. The first-attempt wait is skipped only when
saved values stand in; the first visit is unchanged.
- Selection fix: the selected row's key is recorded only when the
selection moves. Before, every list change recorded the row now at the
old index before the re-anchor ran, so a row inserted above the
selection (a late approval, or any live insert) moved the selection to
another row.
- `ui/src/hooks/useInboxBadge.ts`: `useInboxDismissals` takes an
optional saved `fallback` and returns `hasServerData`. Other callers are
unchanged.
- Tests:
- `Inbox.test.tsx`: a returning visit reveals rows and the saved
approval while the reads are pending, then keeps selection on the same
row when a newer approval arrives above it; a transient failure keeps
the saved approval and a 403 drops it; a record stamped for another user
is ignored and the page waits as a first visit does.
- `inbox-mine-reveal-sources.test.ts`: projection, size limit,
user/company checks, persistence scope.
- `persisted-query-cache.test.ts`: the record round-trips for the same
user, restores as invalidated, and another user's record is not saved.
- `useInboxDismissals.test.tsx`: fallback while pending, after a
transient failure, dropped after a refusal, and no fallback.
- `tests/perf/collections/mine-returning-visit.spec.ts` +
`returning-visit-fixture.ts`: production-build browser checks and the
timing case; README updated.
## Verification
- `cd ui && pnpm exec vitest run src/pages src/lib src/hooks
src/components/coordinator`: 453 files, 5574 tests pass.
- Browser checks on a disposable local instance (production UI build,
`local_trusted`, embedded PostgreSQL, Chromium headless, 1440×900):
`PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:<port> pnpm exec
playwright test --config tests/perf/collections/playwright.config.ts
mine-returning-visit.spec.ts`
- With every read of the company held, task rows and saved approvals
show and no company read has answered. Fails on `master`, passes here.
- An approval dismissed after the cache was saved stands in, then leaves
when the reads answer. Fails on `master` (no saved approvals), passes
here.
- Another company's Mine never shows the saved company's rows. Passes on
both.
- Timing (5 fresh contexts per arm, alternating saved/cleared, every API
response +300 ms, same instance and fixture, host load average about
20). "Responses before rows" counts API responses that finished before
the first row:
| Build | Saved cache: median (range) | Responses before rows | Cleared
cache: median (range) |
| --- | --- | --- | --- |
| `master` (`99edcd28a7`) | 1028 ms (906–3011) | 16–19 | 1502 ms
(1423–1592) |
| This PR | 625 ms (589–672) | 0 | 1632 ms (1359–1692) |
| This PR + #20591 | 625 ms (604–671) | 0 | 1495 ms (1398–1585) |
Saved cache: difference of medians 403 ms. The remaining 625 ms is
JavaScript download and route-chunk loading in a fresh browser context;
no API response precedes the rows. Cleared cache: no change is claimed;
the spread overlaps.
- Existing collection specs on this build: `parent-context.spec.ts`
passes; `startup-regressions.spec.ts` has 4 failures (partial
failure/context error and two 429 cases) that fail the same way on the
`master` build. `mine-workspaces.spec.ts` was not run (needs a database
URL for its fixture).
- Review follow-up (9da56b5515), each with a red/green test that fails
on the previous head:
- Once a saved record exists, each source's answer replaces its part at
once and a refusal (401/403/404) empties it, without waiting for the
other reads, so a reload never shows refused join requests or approvals.
- The selected row's key is also recorded when the recorded row has left
the list, so a new item arriving above the fallback row never becomes
the selection or the archive target.
- An optimistic dismissal and its rollback start from the saved
dismissals that stand in, not from an empty list.
After the rebase onto `origin/master`: `cd ui && pnpm exec vitest run
src/pages src/lib src/hooks src/context src/components/coordinator`
passes (a first run under host load average ~35 had 4 timeouts and two
files missing new dependencies; after `agent-preflight` the affected
files pass, 223 tests).
- `pnpm check:token-gates`: clean. `pnpm verify` selected broader
coverage (exit 2, perf fixture is a global CI input); required CI
supplies it.
- Not run: the hosted staging page, the full local Vitest suite.
## Risks
- Saved approvals can be stale until the read answers (or after a
transient failure). A stale approval shows briefly and its actions go to
the server, which answers with the current state. A 401/403/404 drops
the saved values.
- The record holds approval payloads and join requests for the signed-in
user's company in `localStorage`. It uses the saved cache's existing
projection (secret-like fields removed), the same per-user revocation on
sign-out, and a 256 KB limit.
- #20591 is merged, so this branch (rebased on it) gets one read of each
shell request. Without it, a returning visit still reconnects the live
socket when the session is verified; because rows now reveal sooner,
that reconnect refetches more reads (here: session, health, company list
and agents twice). With both, every shell read runs once.
- Relation to #20592 (task chat preload): both edit
`ui/src/pages/Inbox.tsx` in different places and merge cleanly in either
order (checked with `git merge-tree`). This PR does not preload
anything. #20592 starts its chat preload when `allLoaded` turns true;
with this PR that happens sooner on a returning visit, while the reads
still refresh in the background, so its preload overlaps that refresh.
#20592 is merged and this branch is rebased on it with no conflicts.
- The selection change affects every Inbox tab: the key is recorded when
the selection moves, not on every list change. Archive and removal still
clamp as before.
## 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.
mine-returning-visit.spec.ts hard loads Mine with the saved query cache
(paperclip:query-cache:v1:<user>:<company>, primed by one earlier visit in
the same browser context). Its 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. With every read
of that company held, Mine must show its task rows and saved approvals before
any of those reads answers. An approval dismissed after the cache was saved
stands in until the reads answer and then leaves. Another company's Mine never
shows the saved company's rows. Its timing case records time from navigation
start to the first Mine row with the saved cache and with it cleared, with
every API response delayed PAPERCLIP_COLLECTION_PERF_API_DELAY_MS (default
300 ms), over PAPERCLIP_COLLECTION_PERF_TIMING_RUNS alternating runs (default
and minimum 5). Each sample names the last API response before the rows and
counts the load's requests; PAPERCLIP_COLLECTION_PERF_OUTPUT writes the
report to a file. 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.