💡 Change Scope

• Small Change: Fast feedback, localized UI/logic, low-risk.
• Large Change: New feature, cross-boundary logic, runtime-risk (persistence, IPC, lifecycle, recovery).

📝 What Does This PR Do?

Fixes the Windows-native Agent/terminal regressions around real Agent startup, task/restart recovery, terminal sizing, and OpenCode WebGL rendering:

• Stabilizes Windows Agent launch/recovery paths so Codex, Claude Code, and OpenCode start through Windows-native commands instead of WSL/profile leakage.
• Restores task-launched Claude sessions after app restart without terminal overflow.
• Replaces competing viewport/node/canvas transform cleanup with a renderer-local WebGL render-surface alignment owner.
• Keeps OpenCode on WebGL and adds worker-to-renderer presentation convergence repair for stale glyph/side-residue cases after scroll/drag/zoom.
• Adds Windows repro/debug scripts and regression coverage for real pnpm dev Agent launch, restored Agent input, and OpenCode WebGL layout.

🏗️ Large Change Spec (Required if "Large Change" is checked)

1. Context & Business Logic

Windows terminal nodes had multiple overlapping failure modes: Agent providers could fail to start or restore, task-launched Claude could lose its session binding after restart, terminal content could diverge from node size, and OpenCode WebGL could leave stale side/scroll residue when React Flow transforms moved the node. The intended behavior is that restored/runtime Agent sessions keep their durable identity, terminal geometry is committed from the mounted terminal measurement when needed, and OpenCode remains WebGL-backed without stale local renderer frames.

2. State Ownership & Invariants

• Main/worker/PTTY owns runtime session identity, executable resolution, and PTY geometry truth; Renderer only projects mounted xterm geometry and local WebGL presentation state.
• React Flow owns viewport/node transforms; terminal code must not mutate React Flow transforms to fix WebGL clarity.
• OpenCode worker presentation snapshots remain authoritative; local xterm/WebGL may repair its own renderer buffer after writes settle, but must not rewrite PTY/session truth.
• Invariants: restored Agent nodes reattach to the original durable session binding; measured mounted geometry can override stale restore snapshots for non-live Agent reattach; OpenCode WebGL render canvas is aligned to device pixels without changing PTY cols/rows.

3. Verification Plan & Regression Layer

• Unit: WebGL render surface alignment, OpenCode presentation convergence repair, renderer health, preferred renderer, terminal geometry sync.
• E2E: Windows pre-commit suite includes task-launched Claude recovery after restart and terminal overflow assertions.
• Real Windows repro: pnpm dev Agent launch scripts for Codex, Claude Code, OpenCode; restored Agent cold-restart scripts for Codex/OpenCode; OpenCode WebGL visual layout script with screenshots.

✅ Delivery & Compliance Checklist

• My code passes the ultimate gatekeeper: pnpm pre-commit is completely green.
• I have signed the CLA if required (see CLA.md).
• I have included new tests to lock down the behavior (or explicitly stated why it's untestable).
• I have strictly adhered to the DEVELOPMENT.md architectural boundaries.
• I have attached a screenshot or screen recording (if this touches the UI).
• I have updated the documentation accordingly (if adding a feature or changing a contract).

📸 Screenshots / Visual Evidence

Generated locally by the Windows visual smoke scripts (not committed per repo policy):

• artifacts/debug-opencode-webgl-layout/2026-05-02T05-04-15-703Z/new-opencode-node-after-drag.png
• artifacts/debug-restored-agent-input/codex-run-01/restored-after-type-and-enter.png
• artifacts/debug-restored-agent-input/opencode-run-01/restored-after-type-and-enter.png

Validation run on Windows native PowerShell, not WSL:

• pnpm pre-commit
• pnpm check
• pnpm exec vitest run tests/unit/terminalNode/presentationConvergenceRepair.spec.ts tests/unit/terminalNode/webglRenderSurfaceAlignment.spec.ts tests/unit/contexts/terminalNode.webglRenderSurfaceAlignment.spec.ts tests/unit/terminalNode/runtimeRendererHealth.spec.ts tests/unit/terminalNode/webglSynchronousRedrawPatch.spec.ts tests/unit/contexts/terminalNode.preferred-renderer.spec.ts tests/unit/terminalNode/terminalGeometrySync.spec.ts
• $env:OPENCOVE_DEV_AGENT_PROVIDER='codex'; node scripts\debug-pnpm-dev-agent-launch.mjs
• $env:OPENCOVE_DEV_AGENT_PROVIDER='claude-code'; node scripts\debug-pnpm-dev-agent-launch.mjs
• $env:OPENCOVE_DEV_AGENT_PROVIDER='opencode'; node scripts\debug-pnpm-dev-agent-launch.mjs
• node scripts\debug-opencode-webgl-layout.mjs
• $env:ELECTRON_RUN_AS_NODE='1'; $env:OPENCOVE_REPRO_PROVIDER='codex'; $env:OPENCOVE_REPRO_ITERATIONS='1'; $env:OPENCOVE_REPRO_CLOSE_MODE='cold-restart'; .\node_modules\.bin\electron.cmd scripts\debug-repro-restored-agent-input.mjs
• $env:ELECTRON_RUN_AS_NODE='1'; $env:OPENCOVE_REPRO_PROVIDER='opencode'; $env:OPENCOVE_REPRO_ITERATIONS='1'; $env:OPENCOVE_REPRO_CLOSE_MODE='cold-restart'; .\node_modules\.bin\electron.cmd scripts\debug-repro-restored-agent-input.mjs