[zach88]

What

The desktop side of live GFS subscriptions: previews and folders refresh in place when the resource changes on the server, through the GFS watch stream, and the per-user entity-change stream is removed from the app.

1. In-place preview reload: the preview body's remount key (uri:reloadToken:unavailable) is split from its content version.
   • Markdown keeps its source and scroll position while the new version downloads.
   • Image and video keep the visible object URL until the new one is committed, then revoke the old one (shared useInPlaceObjectUrl, which revokes each URL exactly once, StrictMode and unmount mid-download included).
   • A failed in-place download keeps the last version and shows a "could not update" banner. A 403/404 does not mark the file unavailable on its own; the authoritative resolve decides. A session-authority failure (401 or a session lifecycle code) drops the content.
   • Each body only renders content for the source it downloaded, so a URI swap without a remount never shows file A under file B. The plugin preview overlay gets the same split.
2. Watch client in main (createGfsWatchClient): one client per process for GET/PUT /api/v1/me/gfs/watch.
   • One link at a time (Idle / Backoff / Opening / Ready) with a per-attempt epoch, so a late result of an old attempt is dropped. closeLink releases state before running any effect, and every effect is best-effort.
   • The GET uses raw fetch with only the open deadline and refuses redirects; the PUT goes through requestJson with a timeout longer than the PUT deadline.
   • Total outcome tables for the open and the PUT, keyed on status plus x-watch-error; additive jitter that never fires before a server Retry-After; capped PUT retries per episode.
   • Session handling: its own token generation, binding decoded from the token claims (never used to authorize), terminal latch deferred during a team hop, /me check on session expiry, and 409/426 treated as "unsupported until a newer token".
   • Owner registry merged by rank and registration order, a 64-key cap, frame-token gating for renderer IPC. Server keys are re-validated before they reach renderers.
3. Wiring in main, IPC and preload: AppService feeds the client every session, team-hop and environment event. IPC gfsWatch:setSubscriptions / gfsWatch:stop and push channel gfsWatch:event accept trusted senders only and identify documents by the Electron main-frame token. The preload installs the event listener before the first invoke.
4. Renderer:
   • Each window derives the set of GFS resources it shows (active preview, plugin preview overlay, the Files location, expanded sidebar folders), caps it at 64 keys by priority and sends it to main with a 150 ms debounce.
   • Events are handled with a per-key single-flight plus one pending pass. File keys refresh the open preview; dir keys refetch the listing without cancelling an in-flight page; accessChanged refreshes roots and sharing dialogs and marks listings stale; sessionExpired purges previews, the GFS cache and every Files breadcrumb.
   • The entity-change stream is removed end to end: authClient stream and parser, AppService state, IPC, preload bridge, types and the renderer registry.
5. docs/architecture/live-entity-change-consumer-semantics.md describes the new consumer.

Why

Today the per-user stream sends a generic invalidation every 4 seconds by default, and each one makes the app re-resolve open previews and refetch active GFS queries, whether or not anything changed. Each reload remounts the body, so scroll and video position are lost and "Loading preview" flashes. With the watch, the desktop subscribes only to what is on screen and reacts only to what changed, and the preview updates without a remount.

How

• After an accessChanged caused by a reauthorize close, watched keys are not re-resolved immediately; they converge with the resync of the next ready. Re-resolving every key on every reopen would repeat reads that the resync already does.
• The renderer resets its dedupe on any session, identity, team or environment change, so main gets the list again after it cleared the owner lists. userId comes from auth.me.id.
• Leaving the desired set never bumps a preview's generation while its tab stays open.

Testing

• Model-based: watchClient.model.test.ts (fast-check commands, invariants at rest against an independent reference model; fixed seed, overridable with GFS_WATCH_MODEL_SEED / GFS_WATCH_MODEL_RUNS).
• watchClient.scenarios.test.ts: scenarios against a real HTTP server with the real fetch and requestJson on a virtual clock.
• appService.gfsWatch, ipc.gfsWatch, preload.gfsWatch: AppService through its real producers, real IPC and preload handlers.
• Native Electron fixture (npm run test:native:gfs-watch-ipc): frame tokens across reload, subframes, renderer crash and window close.
• Renderer: App.gfsWatch, in-place reload suites for each preview body, FilePreviewPage, plugin overlay, useGfsWatchSubscription, gfsWatchKeys, gfsWatchReaction, keyedSingleFlight.
• A vitest setup file gives watch clients an inert transport, so unrelated AppService suites no longer send requests to a real local port.
• At this head, on Node 24 with npm run verify:electron passing: tsc --noEmit clean; vitest run 485 of 488 files, 6011 of 6020 tests passed. The 9 failures are in 3 image-challenge suites this PR does not touch; they import @napi-rs/canvas, which desktop-app does not declare (only mcp-host does), and fail with Cannot find module.

Risks / follow-ups

• Merge together with feat(control-api): push authorization and session changes over the GFS watch and retire the per-user entity-change stream #1502, which retires the route this app used before.
• Only V1 sessions are supported by the watch. A V2 session gets 409 and the client stays in unsupported: no live updates, no pushed roots or dialogs, no revocation or session notice. V2 sessions cannot be issued today; this is a prerequisite before enabling them. Follow-up: GFS watch: support V2 sessions before enabling V2 issuance #1504.
• File budget: 83 files in one service plus one doc, about 43 of them tests or test support, 7 deletions. The client, its wiring and the renderer switch-over cannot be split without shipping the old and new streams side by side. The in-place reload (first commit) is independent of the transport and could be split off; it stays here because the watch is what drives it.

Stack

Live GFS subscriptions ship as a stack. The server half and the desktop half must reach dev together: the server PRs retire the route the current desktop uses, and the desktop PR needs the new watch route.

#	PR	Base	Scope
1	#1496	dev	gfs-controller: drive name validation, principal_denied reason
2	#1497	dev	host-context-controller: drive name validation (merge after 1)
3	#1498	dev	control-api: shared building blocks, per-resource change trigger
4	#1499	3	control-api: watch registry, listener, process runtime
5	#1500	4	control-api: GET/PUT /external/gfs/watch
6	#1501	5	external-rest-api: GET/PUT /api/v1/me/gfs/watch
7	#1502	6	control-api + ERA: authorization and session push, retire the per-user entity-change stream
8	#1503	7	desktop-app: watch client, live previews and folders

1 and 2 are independent of the chain and safe to merge on their own (1 before 2, since the controller check in 2 mirrors the one in 1).

3 to 8 are one unit and should not be deployed partially:

• 3 and 4 add groundwork; the only new runtime behavior is the gfs_resource_changed NOTIFY trigger, which nothing listens to yet.
• 5 and 6 expose the route, but until 7 lands an authorization or session change does not cut the changed events of a stream that is idle (no op in flight). Do not ship 5/6 without 7.
• 7 removes the per-user entity-change stream (ERA /api/v1/entity-changes/stream and control-api /external/entity-changes/stream), which the current desktop still uses. Do not ship 7 without 8.