fix(desktop): preview downloads skip Save dialogs and dark-mode pages stay visible

[rynfar]

Agent-driven preview downloads now save to browser artifacts without opening native Save dialogs. Human takeover and URL-bar navigation restore normal download behavior. Preview webviews also receive an opaque base background so dark-mode Markdown/plain-text pages remain visible across webview replacements.

Sources:

• Adapted 5cc99e1c23980d7995a13c47f969b47cb68ed1be: ported download handling and takeover regression coverage while preserving Pylon’s preview partition identity.
• Adopted 3e60fecf39f37faaca9bdf37e64b7a58229ea547: ported opaque background initialization and webview replacement coverage.

Pylon recording and screenshot code is preserved. No helpers were deleted.

Verification:

• env -u CLAUDE_CODE_ENABLE_TODO_TOOLS vp test run apps/desktop/src/preview/Manager.test.ts apps/desktop/src/preview/BrowserSession.test.ts apps/desktop/src/ipc/methods/preview.test.ts apps/desktop/src/window/DesktopWindow.test.ts
  Passed: 4 files, 144 tests; final run took 3.49 seconds.
• vp run -F @t3tools/desktop typecheck
  Passed, exit 0, after dependency installation completed. Base and ported files produced identical advisory diagnostics.
• vp lint apps/desktop/src/preview/Manager.ts apps/desktop/src/preview/Manager.test.ts
  Passed, exit 0.
• vp fmt --check apps/desktop/src/preview/Manager.ts apps/desktop/src/preview/Manager.test.ts
  Passed: both files correctly formatted.
• git diff --check
  Passed.

Remaining verification: no live Electron download/dialog or visual dark-mode check was performed. Local, remote, and tunnel desktop sessions were not exercised interactively.

Part of upstream cycle #981. Ported with Codex (relay); pushed and opened by Claude Opus 5.5 (Claude Code).

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Review rounds

Six adversarial review rounds (Codex via relay). The original port only redirected agent downloads. Review hardened it in five ways:

• Download limits: agent-captured downloads are capped at 200 MiB and five files, expire after 24 hours, and time out after five minutes. They live in their own agent-downloads directory and are pruned there; recordings and screenshots are never touched. A symlinked download directory is refused.
• Who navigated: every navigate, back, forward and reload call is explicitly marked human or agent. Anything unmarked counts as human, so it is never captured silently. Human navigation stops capture.
• New agent tabs open blank and then navigate as the agent, so their downloads are captured too.
• Agent requests that end in a captured download now report success with a "started" receipt instead of failing on Electron's ERR_ABORTED. A download only counts if it comes from the main frame, its URL chain matches the navigation, and the navigation is still the current request. A one-second window covers a rejection that arrives before the capture.
• Known P3 limits, accepted: the origin label comes from the renderer and isn't authenticated; the directory check has a race (TOCTOU) between checking the folder and writing to it; and two overlapping requests for the same URL can't be told apart.

Final review at 3a9cb8de8d: MERGE. Not exercised in a running Electron app: live downloads and Save dialogs.

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	14.0 KiB	14.0 KiB	+8 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.3 KiB	7.3 KiB	+8 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.7 KiB	6.7 KiB	0 B (0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	58.0 KiB	58.0 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	9	9	0 (0.0%)	21	✅
Claude	Total thread wire	14.0 KiB	14.0 KiB	+40 B (+0.3%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.3 KiB	7.3 KiB	+14 B (+0.2%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.7 KiB	6.7 KiB	+26 B (+0.4%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	58.8 KiB	58.9 KiB	+44 B (+0.1%)	66.4 KiB	✅
Claude	Live turn messages	8	9	+1 (+12.5%)	21	✅

Baseline: 0088440 · PR result: 3a9cb8d · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 115.7 KiB
• Claude decoded thread snapshot: 116.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.