perf(server): batch terminal history writes every 250 ms

[StiensWout]

Problem

Sustained terminal output rewrites retained history after every 40 ms batch, even when the transcript approaches its size cap.

Change

Batch live history writes every 250 ms. Terminal close, clear, and restart retain their immediate persistence requests and drains. This lowers the nominal write ceiling from 25 to 4 batches per second; actual disk and CPU savings were not measured.

Scope and approval

Requested by Wout in T3 Code as part of the terminal-performance PRs. Scope is the live history-write cadence and its focused behavior test. This changes a product default. The longer delay increases exposure to transcript loss on abrupt server termination; filesystem and queue delays can extend persistence and lifecycle waits beyond 250 ms. Public maintainer approval is pending. Wout will share these PRs with the maintainers in Discord after CI and code review are green.

Verification

The new test fails against main and verifies output coalescing plus final history after close/reopen. All 89 TerminalManager tests, server typecheck, and scoped lint/format checks pass. Independent review found no blockers.

_{Prepared for Wout by gpt-6.1-sol in the Codex harness through T3 Code.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This changes the server’s default terminal-history write cadence from 40 ms to 250 ms, reducing write frequency while increasing the time live output remains unpersisted; lifecycle operations retain immediate flushing. The behavioral tradeoff of this product-default change should receive human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 04464cf0-fcbd-436c-ac2c-e4eaa7a31a82

📥 Commits

Reviewing files that changed from the base of the PR and between a4c9494 and 97fe155.

📒 Files selected for processing (2)

• apps/server/src/terminal/Manager.test.ts
• apps/server/src/terminal/Manager.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

Terminal history persistence now uses a 250 ms debounce instead of 40 ms. A new test checks delayed, coalesced writes and verifies that closing during a pending write preserves all output in history.

Changes

Terminal history persistence

Layer / File(s)	Summary
Debounced persistence and close-time history apps/server/src/terminal/Manager.ts, apps/server/src/terminal/Manager.test.ts	The persistence delay changes from 40 ms to 250 ms. The test checks write timing, coalesced output, and history preservation when closing during a pending write.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 97fe1

Live terminal history may remain unwritten for longer if the server stops abruptly, but closing a terminal still preserves pending history. No actionable merge blocker is established.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 97fe1

Saving terminal output less frequently increases the amount that may be lost on abrupt shutdown. Normal close, clear, and restart still request persistence and wait for pending work. No new access or privilege boundary was identified, but shutdown and concurrent deletion behavior remain partially verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The timing change affects terminal histories sharing a server manager and its serialized persistence worker. This establishes shared queue-delay exposure, not expansion into another service, tenant boundary, credential authority, or data store.

Trust Boundaries and Controls

• observed — Output enqueueing rejects events whose process identity or running state no longer matches. Stopping a process removes subscriptions and pending events. Lifecycle persistence uses the same thread/terminal key, whose drain waits until queued, pending, and active work is absent; these controls are unchanged.

Resilience and Maintainability Implications

• observed — History-write failures are caught and logged inside the persistence operation, so drain completion does not guarantee a successful write. This failure policy predates the PR; the new test exercises successful coalescing and orderly close rather than failure recovery.

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the problem, change, scope, risks, and verification. However, the required scope and approval information is incomplete because explicit maintainer approval is still pending.	Add a link to the triaged issue or approval discussion and include the maintainer's explicit approval comment. Update the description after approval is obtained.

✅ Passed checks (3 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 and concisely describes the main change: batching server terminal history writes every 250 ms.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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