Release the PTY renderer-delivery queue on every teardown path; guard the synthetic-kill window (STA-1397)

[brennanb2025]

Summary

Completes the STA-1397 main-process memory-creep fix on top of #7630 (merged), which independently landed the same 2 MB pendingData cap + droppedBacklog snapshot-restore flag this branch originally carried. After rebasing onto that work, this PR keeps the two failure modes #7630 does not cover — both proven by heap-snapshot forensics on the profiling rig (details on Linear STA-1397):

1. Stranded delivery state on teardown. pendingData and rendererInFlightCharsByPty are closure-local to registerPtyHandlers; only sendPtyExitToRenderer released them. Teardown paths that skip it — SSH connection shutdown (clearPtyOwnershipForConnection) and the synthetic-kill dedup early-return — stranded up to a full cap's worth of queue per PTY for the process lifetime, and, worse, left the PTY's in-flight chars counted against the global 8 MB ACK budget forever, silently throttling delivery for all terminals until app restart. In the rig repro, 3 of 17 terminals stranded ~36 MB each through a plain worktree removal (pre-cap; still 2 MB + wedged budget each post-#7630). Fix: a clearPtyRendererDeliveryState hook that clearProviderPtyState now calls on every teardown path — it flushes the queued tail first (preserving the "last ≤8 ms of output" guarantee regardless of call order relative to sendPtyExitToRenderer), then releases the queue and the in-flight budget.

2. Repopulation inside the synthetic-kill window. pty:kill sends a synthetic exit that flushes and deletes the entry, but onData had no kill-window guard: the daemon's socket backlog keeps draining output for seconds after the kill, repopulating pendingData, and the real exit is then swallowed by consumeSyntheticKillExit — so nothing ever cleans the entry again. Fix: drop renderer delivery for ids inside the dedup window (runtime/status consumers above still see every byte).

Also extends the #7630 platform analysis: the never-ACK wedge is not Windows/Linux-only. A window that has never mounted a terminal pane never attaches the renderer PTY dispatcher at all (ensurePtyDispatcher is transport-created), so nothing ACKs regardless of background-throttling — reproduced on macOS with CLI-created terminals in background worktrees (141 → 568 MB heapUsed in 3 min, zero recession).

Diff after reconciliation

src/main/ipc/pty.ts + src/main/ipc/pty.test.ts only. The cap, flag, preload/dispatcher/renderer threading are #7630's as merged; this branch's duplicate implementation and duplicate cap test were dropped in the merge commit.

Screenshots

No visual change.

Testing

• pnpm lint (oxlint clean on changed files)
• pnpm typecheck (node + web)
• pnpm test — full src/main/ipc/pty.test.ts suite (227 tests incl. #7630's cap tests) + 419 renderer terminal-pane tests
• 2 regression tests added: provider-state teardown flushes the tail and zeroes queue + in-flight budget; synthetic-kill-window output cannot repopulate the queue
• Rig-validated end-to-end before the rebase (17 hidden terminals, ~1 MB/s each, 3 min): burn heapUsed floor ~90 MB vs 250–400 MB rising; post-close heapUsed returns to the 49 MB idle baseline vs 160 MB with 108 MB stranded

AI Review Report

Checked the merge reconciliation specifically: no remnants of the superseded dropped flag or 1 MB cap constants remain (grep-verified); the teardown hook uses #7630's makePtyDataPayload signature and passes droppedBacklog through the exit flush; hook is assigned before any teardown can run (module-level no-op default otherwise); flush-then-clear ordering analyzed against both clearProviderPtyState-before-sendPtyExitToRenderer (daemon/SSH exits) and the reverse (kill paths) — no double-send, no tail loss. Cross-platform: pure IPC/queue bookkeeping, no platform branches; original evidence spans Windows (#7375 profiling) and macOS (rig).

Security Audit

No new input handling, command execution, path handling, auth, or secrets. Changes are cleanup/bookkeeping on existing pty:data delivery structures; the kill-window guard only drops renderer-bound delivery for a PTY already being torn down.

Notes

• Follow-ups tracked on Linear STA-1397: daemon-side unbounded socket write buffering to a slow main (1.9 GB RSS during the rig burn) deserves its own ticket; the bounded main-side headless emulators (~8 MB/terminal) could take an idle-eviction cap.
• The merge commit intentionally adopts #7630's naming/mechanism wholesale to avoid two flags meaning the same thing; a small follow-up commit restores main's exact formatting on 7 unrelated files that the local pre-commit hook had rewrapped during the merge.

[coderabbitai]

📝 Walkthrough

Walkthrough

PTY provider cleanup now flushes remaining renderer data and releases pending and in-flight delivery bookkeeping. PTY output received during the synthetic-kill deduplication window is ignored. Tests cover both teardown under backpressure and late output after a synthetic kill.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main PTY teardown and synthetic-kill guard changes.
Description check	✅ Passed	The description includes all required template sections and provides concrete testing, review, security, and notes details.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}