feat(pages): tell readers comments reach an agent, and badge workspaces waiting on one
feat(pages): tell readers comments reach an agent, and badge workspaces waiting on one
Links
- Linear: SUPER-2187 — Pages need onboarding
- Predecessor: #7729 (items 1-3 of the same parity study)
Summary
Items 4.1 and 4.2 of the SUPER-2187 follow-up. The Pages comment loop works end to end — a teammate pins a comment, it routes to an agent, the agent republishes — and is invisible from both ends.
- The reader now gets a one-time hint under the page header telling them clicking is what starts a comment, and what happens next. The copy branches on live watch state.
- The publisher now gets a count badge on the workspace row in the desktop sidebar when page comments are waiting on an agent there, backed by a new per-workspace read model.
Both surfaces make a claim about where a comment goes, so both are gated on the same fact: is an agent watching this page right now. Nothing in the product notifies anyone about a page comment — there is no notification router, and page-comment.ts fires no email, push or inbox entry. A comment is a database row. The only things that surface one are the live watcher and this badge, and neither exists when nobody is watching.
Item 4.1 — the reader hint
packages/ui/src/components/PageComments/components/PageCommentHint is the banner (same chassis as PagePublicBanner: h-9, border-b, bg-muted/40, ghost dismiss button). apps/web/src/app/page/[slug]/components/PageCommentHintBar is the container that decides whether to show it and feeds it watch state. It renders between PageHeaderBar and the frame, and not at all while previewing an older version (comment mode is already pinned off there).
Two messages, one per branch:
| Watch state | Copy |
|---|---|
| An agent is watching | Click anything on this page to comment on it. An agent is watching, and will pick your comment up and republish the page. |
| No watcher | Click anything on this page to comment on it. No agent is watching right now, so your comment is saved on the page. |
The neutral copy is also the fallback for every unknown state, because the asymmetry matters: a hint that promises an agent when nothing is listening is worse than no hint, while a hint that under-promises costs nothing.
Why two branches and not three
An earlier revision had a third branch that named the watching agent ("claude is watching, and will…"). It is gone. The reader cannot act on the agent's name — they do not pick it, cannot address it, and a session id like claude means nothing to a teammate reading a report. It bought a message id in all seventeen catalogs and a second interpolation path for no reader-visible gain. The header's own watch badge still names the agent for the publisher, which is where that detail belongs.
Why the no-watcher copy stops at "saved"
It used to read "…so your comment is recorded for whoever published the page." That over-promised. Nothing routes the comment to the publisher: no notification of any kind exists on page comments. The comment is a row that someone sees the next time they open the page. "Saved on the page" is the whole truth, and it is a clean truncation of wording already present in every locale — every catalog already had its own verb for recorded/saved, so the retranslation reuses vocabulary rather than introducing any.
The watch-state freshness decision
The hint subscribes; it does not read once at mount.
WATCH_STALE_MS is 90 seconds, so a server-rendered watch value can already be a minute and a half stale before first paint, and a reader sits on a page far longer than one render. Reading once would let the hint promise a republish from an agent that stopped heartbeating before the page even loaded.
It reads the same polled page.get query PageWatchBadge already drives, extracted into apps/web/src/app/page/[slug]/hooks/usePageWatch. Both components observe one query key with one refetchInterval (30s while watching, 5min idle, paused in the background), so the hint costs zero extra requests and the badge and the hint can never disagree.
Item 4.2 — the sidebar badge
New read model pageComment.waitingByWorkspace (packages/trpc/src/router/page-comment/). It joins page_comment_threads → pages → workspace_pages, scoped to the caller's active org and filtered to pages the caller can read (just_me pages belonging to someone else are excluded, matching assertPageReadable). The waiting predicate and the rollup are a separate pure module, waiting.ts, tested without a database — the same split watch.ts and agent-access.ts already use, and for the same reason.
"Waiting" is: agent-activated, unresolved, newest undeleted comment authored by a human, and the page is currently watched.
The first three clauses are about the conversation. The brief said no agent reply yet; I used last word is human, because "no agent reply yet" is permanently false from the agent's first reply onward, so the workspace silently stops flagging exactly when the conversation is still going. A human follow-up puts the ball back in the agent's court as much as the first comment did, and page_comments.author_kind says so without a new column.
The fourth clause is the watch gate, and it is new. The badge's tooltip reads "waiting on an agent here". With no live watcher there is no agent, so the claim was false — the same over-promise the hint had, in a different surface. The gate runs the page's watchedByAgent / watchHeartbeatAt through the existing watchState() helper from packages/trpc/src/router/page/watch.ts rather than restating the 90-second rule, so the hint and the badge cannot drift on what "watching" means.
The vanishing badge — decided, not defaulted
Gating on watch makes the badge time-dependent: two comments wait, the session ends, the heartbeat goes stale, the badge disappears, and nothing was resolved. A badge that vanishes reads as "handled" when the truth is "nobody is listening any more".
Chosen: let it vanish, and treat the gap as the thing to fix. The alternative considered in detail was keeping the count and rendering it muted when unwatched.
The badge is a call to action on a workspace row, and its action is "open this workspace, an agent there owes a reply". When nobody is watching, there is no action it can prompt that helps — opening the workspace does not deliver the comment to anyone. A muted "outstanding but unheard" variant would be a permanent, un-actionable marker on every workspace that ever received a page comment, clearable only by resolving threads the viewer may not own. That accumulates into wallpaper, and a badge everyone learns to ignore is worse than one that is merely absent. The misread is also bounded: the badge is not the system of record, and the thread is still sitting unresolved on the page.
The honest answer to "nobody is listening" is to make someone listen, not to render a sadder badge. That is a wake-an-agent path, which is explicitly out of scope here.
So, plainly: a comment left on a page nobody is watching now surfaces nowhere. It is saved, the hint says exactly that and promises nothing more, and no badge claims otherwise. That is a deliberate call by the user for this PR, and it is the gap a future wake-an-agent change would close.
Delivery follows the DashboardSidebarPortsProvider precedent: DashboardSidebarPageCommentsProvider mounted once in the dashboard layout, rows read one number via useWorkspacePageCommentsWaiting(workspaceId). One query for the whole sidebar (60s poll, 30s stale), and pageComment is already in CLOUD_TRPC_ROUTER_ROOTS, so the org-switch cache purge covers it — see the org-switch fix below, which is what makes that sentence true for a provider that stays mounted.
The badge sits in the row's right-hand cell beside the diff stats. The diff stats hide themselves on hover and focus, to clear the way for the row's hover actions; the badge does not. It stays put while the row is hovered or focused, because that is exactly when someone is reaching for its tooltip. The cell is a right-aligned flex row, [status][badge][actions]: hidden flex items take no space and collapse their own gaps, so the resting rendering is identical to a row with no badge logic at all, and on hover the actions simply appear to the badge's right instead of on top of it.
The org-switch purge did not actually reach a mounted provider
Raised in review, and it is a cross-tenant display bug rather than a staleness annoyance, so it is worth writing down. Cloud procedures take no organizationId input — the server scopes by the header this window sends — so their React Query keys do not encode the org, and CollectionsProvider drops every cloud query on a switch. It dropped them with removeQueries.
QueryCache.remove() destroys the query and notifies cache listeners; a QueryObserver subscribes to the query, not the cache, so nothing touches its current result. Every existing cloud reader got away with this by unmounting across a switch. This provider is mounted once in the dashboard layout and stays mounted, so it kept publishing the previous organization's counts into the sidebar until something else forced a re-render or the 60s poll came round.
resetQueries instead of invalidateQueries: invalidation keeps the old rows on screen while the refetch is in flight, which is the one thing the original comment on that code said not to do. resetQueries clears the data and notifies the mounted observers, then refetches the active ones, and the org header is already set during render before the effect runs. The function moved out of CollectionsProvider.tsx into its own co-located module so it could be tested; the first two tests in dropCloudQueriesForOrgSwitch.test.ts fail on removeQueries and pass on resetQueries.
Screenshots
Both reader-hint shots were recaptured for the two-state copy against a dev stack in this worktree (web :3820, API :3821), signed in as the seeded local dev account, on a page published through the real page.assets.upload + page.publish procedures with two real pinned comments on it.
Reader hint — an agent is watching (1180x780; the header's own badge reads claude is watching, corroborating the live state that the hint deliberately does not name)

Reader hint — no watcher (same page, watch cleared; the header badge is correctly absent, and the copy promises only that the comment is saved)

Sidebar badge — not recaptured, and here is why. The image below is from an earlier revision. It is a resting-state capture, and the badge's resting appearance is unchanged by this PR; what changed is when it appears. The review fix described above changed the badge's hover and focus behaviour, which this shot does not show either before or after, so it is not a picture that has gone stale. I did not capture a new hover-state shot: doing it honestly needs the whole stack below (Electron build, seeded host database, MinIO stand-in for R2, forced feature flag) rebuilt to reach a workspace row that actually has waiting comments, and I was not willing to substitute a mock-up for it. The structural claim is verified in code and in DashboardSidebarPageCommentsBadge.test.tsx instead. Re-shooting it would mean building and running the Electron app against a seeded host database, and the picture would be pixel-identical. Instead I verified the gate where it actually lives — against the real API and database, with the page linked to a real workspace row:
workspaceId: 2ffb72ea-a631-49a9-843c-225329d995aa
WATCHED -> waitingByWorkspace: [{"workspaceId":"2ffb72ea-…","waitingCount":2}]
UNWATCHED -> waitingByWorkspace: []
REWATCHED -> waitingByWorkspace: [{"workspaceId":"2ffb72ea-…","waitingCount":2}]
STALE 120s -> waitingByWorkspace: []
Two threads, nothing resolved, nothing edited between lines except watch state — and the last line ages the heartbeat past WATCH_STALE_MS rather than clearing the watcher, so it exercises the staleness rule and not just the null case.

Three things about that dev stack, stated plainly because none of them are visible in the images:
- The local stack cannot publish or serve page bytes on its own.
.env.local.examplesays so outright. I ran a throwaway MinIO on:9000for the API's presigned PUT — the page, its version row, its manifest and its comments are all real records written by the real procedures, and the bytes in the screenshots are the ones that round-tripped through it. Serving the frame back is a second problem: the usercontent Worker reads an R2 binding out of wrangler's local simulator, and on wrangler 4.118wrangler r2 object put --localwrites a different on-disk layout thanwrangler devreads (r2/<bucket>/blobsvsr2/miniflare-R2BucketObject/<hash>.sqlite), so mirroring into it does not work. For the capture I served the same bytes from a stand-in origin on the usercontent port — the same kind of local substitution MinIO is for R2, and the document in the frame is byte-identical to what was published. FEATURE_FLAGS.PAGESis server-gated on the web viewer (getPagesAccessasks PostHog), and it is off locally, so the route 404s. I forced it on with a temporary local edit for the capture and reverted it; that edit is not in this diff.- The workspace behind the gate verification was seeded (a
projectsrow and aworkspacesrow plus theworkspace_pageslink), because the desktop's own "Create new project" flow does not complete in this stack. The link, the rollup and the numbers above are all the app's own code paths reading real rows.
Testing
bun run lint:fix— cleanbun run typecheck— pass (42/42 tasks)bunx sherif— no issues foundbun run check:i18n— pass, 5605 translated / 0 missing in every locale. Removing the named-agent branch deleted one message id; changing the no-watcher copy re-keyed another. One new message, hand-translated into all 16 non-English catalogs and committed; catalogs regenerated from a clean tree so the diff is only those lines. The review round changed onlymsgstrvalues (nl, vi, zh-TW), so no message was re-keyed and regeneration produced no further churn.bun run test— every turbo task passes except@superset/desktop, below.apps/desktop— 7558 pass, 36 fail. Baselined again after the review round: the same suite on a detachedorigin/maincheckout in this same worktree, sorted failing-test names diffed against this branch's. The sets are identical, 36 and 36 — all git-worktree, shell-env and terminal-transport suites this branch does not touch.
New and updated tests:
apps/desktop/.../CollectionsProvider/dropCloudQueriesForOrgSwitch.test.ts(3) — a still-mounted observer loses the previous org's rows and refetches; the flat["cloud", …]key shape is covered too; non-cloud queries are left alone. The first two are the regression test for the bug above.apps/desktop/.../DashboardSidebarPageCommentsBadge.test.tsx(3) — nothing at zero, the capped99+numeral alongside an uncapped spoken description, and the accessible description itself.
One unrelated-looking test fix rode along, and it is worth explaining rather than hiding. Adding those two files changed nothing about the terminal transport, but it did change bun's test file order, which is not alphabetical and shifts whenever a file is added anywhere in the app. LanguageAwareI18nProvider.test.tsx stubs auth-client, electron-trpc and posthog with mock.module, which rewrites live bindings process-wide and was never undone; it had simply been landing after terminal-ws-transport.test.ts by luck. Once it landed before, five transport tests died on posthog.capture is not a function. That file now snapshots the real modules and puts them back in afterAll, the same pattern terminal-ws-transport.test.ts already documents for its own relay-socket stub.
packages/trpc/src/router/page-comment/waiting.test.ts(14) — every clause of the waiting predicate independently, including the human-follow-up case and the watched→unwatched transition: one thread assertedtruethenfalseacross a heartbeat crossingWATCH_STALE_MS, and one workspace asserted to drop out of the rollup entirely when its watcher stops.packages/ui/.../PageCommentHint.test.tsx(5) — both states, the assertion that the non-watching branch never contains the republish promise, a new assertion that it claims no delivery of any kind (no "recorded for", "published the page", "sent to", "notified"), and one that the watching branch never names an agent.
Out of scope, deliberately
- the in-workspace published-pages strip or chip (item 5)
- the page → workspace backlink
- any wake-an-agent / spawn-on-comment path — the gap named above
- the collapsed sidebar rail has no badge; only the expanded row does