perf(ipc): forward session:screen only to a renderer that leased it

[Juliusolsson05]

Fixes #762

The plan is the first commit: docs/plans/2026-09-25-screen-ipc-interest.md.

Why

session:screen was 93% of recorded IPC bytes. Recording g00000190 has 16,728 frames of about 8.8 KB over 123 minutes, and the committed fixture worktree-live-attribution/codex-live-channel-gap.json has 2,358 screen frames among about 12,600 events. Every frame was structured-cloned and committed into the renderer runtime map.

A full consumer map (below) shows that nothing live needs these frames.

Consumer map (why each is safe)

Consumer	Where	Disposition
Prompt delivery, paste confirm, readiness	main, session.snapshotScreen() (providers/*/runtime/promptDelivery.ts)	Unaffected; reads main's screen
Raw snapshot cache and spinner gate	sessionManager.ts lastScreenSnapshot, ScreenFrameGate	Unchanged
Composer slash picker	applyConditionSnapshot (claude.slash-picker)	Already owned by conditions; the screen handler's second write is removed
latestScreenRef Enter baseline	useComposerKeybinds.ts → getScreen	Dead; no composerSubmit read it (#855). Deleted
claudePaste.ts helpers	TileLeaf	Dead; no callers. Deleted (CLAUDE_PASTE_THRESHOLD now imported from @shared/claude/pasteConfirm)
ReaderView		No screen fallback since #855
DebugPanel; Conditions, HeadlessSnapshotProbe and ClaudePasteDetection dev modules	debug	Hold a lease while open (useScreenLease)
Debug bundles (manual and 60 s autosave)	saveDebugBundle.ts	Read session:get-screen-debug: main's latest raw screen plus the tail history
Screen-tail trace	was renderTrace.recordScreenTailSnapshot	Recorded in main from every frame (shared/debug/screenTail.ts); same bundle files
Phone	RemoteServer taps main	Unaffected
Recover and resync seeds	ipc/session.ts, ipc/sessionRouting.ts	Unchanged; still sent directly

Lease contract

• Acquire: session:screen-lease acquires a lease and seeds the current screen as one ordinary session:screen event, so an idle backend still shows a correct panel.
• Release: session:screen-release releases it. A release the owner does not hold is ignored.
• Ownership: a lease belongs to the calling webContents. A main-frame navigation (reload) or destroyed drops all of that owner's leases, because a dying renderer never runs its cleanup. A leaked lease costs bytes, never correctness.

Evidence

• Fail-first on the real path. Using the recorded Claude 2.1.278 screen (image-absorption/wrapped-image-pill-2026-09-21.json), the "unleased frame is not forwarded" assertion fails on a clean origin/main (expected [ Array(1) ] to deeply equal []) and passes here.
• Mutations killed:
  • removing the gate;
  • recording the history only for leased frames;
  • dropping leases on a sub-frame navigation;
  • removing the acquire seed;
  • restoring the picker write from screen frames.
• New tests: screenInterest.test.ts (counting across owners, foreign release, dropOwner), screenTail.test.ts, useScreenLease.renderer.test.tsx, the forwarder recorded-frame test, and the IPC lease seed plus reload/destroy test.
• Updated tests:
  • The routing composition tests now hold a lease explicitly, because an unleased session would make "nothing sent" true for the wrong reason.
  • The dimension-ownership test mocks the lease bridge.
  • The screen renderer test pins "no picker from screen".
• Suites: Node 24, tsc -b clean. Full suite: 6,740 of 6,742 pass. The one failure, workflows/control.system.test.ts (a 5 s timeout), fails identically on clean origin/main locally, while main's CI is green; it is local environment.

Not verified

The live app (house rule). The IPC byte reduction is inferred from the gate, not re-measured in a running app.

🤖 Generated with Claude Code

[Juliusolsson05]

Review disposition (2 rounds: Codex A, Claude B, Pi C; plus steering)

Finding	Disposition
C1: debug-bundle consumer seam untested	Fixed. Real assembleAndSaveDebugBundle with only window.api mocked; get-screen-debug and tail files tested. Mutants M1, M2 and M20 fail.
C2: same-document navigation dropped leases	Superseded by document-keyed leases (below).
C3/C4/C5: history recorded plain; recent-only frames; loose seed	Fixed. Mutants M18, M15 and M19 fail.
C6: dead awaitClaudePastePlaceholder chain	Removed end to end.
A1/A2: picker colour-only selection never republishes	Pre-existing. Filed #1253.
B round-1 suspicion: a blocked will-navigate still fires did-start-navigation and dropped every lease	Fixed. Leases are keyed to a per-load document id minted in preload; no navigation event is used.
B round-2 survivors J, A, E	Pinned. Cross-owner release, release acts for its caller, no empty seed frame.
q15 (steering): a reload that takes no new lease kept forwarding forever	Fixed. The preload announces its document on every load (session:screen-document), retiring the old document's leases at once. Host-path test plus mutant.

All round-2 verdicts are MERGE. CI is green on c08201f2, which contains origin/main.