fix(server): prevent busy terminals from starving history persistence

[StiensWout]

A continuously busy terminal can keep the history worker on its own pending batches, delaying persistence for every other terminal.

Return pending keys to the queue tail after each batch, with an atomic handoff that preserves coalescing and drain behavior. Successful and failed batches use the same completion path. This is our implementation of the problem described in #8966.

In the deterministic workload, the quiet terminal now runs second instead of fifth. New behavior tests fail against main; all 92 focused worker and TerminalManager tests pass, along with shared typecheck and scoped lint/format checks. Two independent reviews found no blockers.

Close, clear, and restart can wait behind batches already queued for other terminals; immediate requests still skip their own debounce.

Implemented with GPT-6.1 through the Codex harness in T3 Code.

[macroscopeapp]

Approvability

Verdict: Approved at d10f20a

Macroscope's review found this PR approvable — This focused fix changes an existing history worker so pending terminal batches yield fairly instead of allowing a busy terminal to starve others. The implementation is confined to the worker, preserves coalescing and draining, and adds targeted tests for fairness, merging, and failures.

^{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: 0b4aea3a-7f72-4e51-9fd7-9bb4cbd9ad6e

📥 Commits

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

📒 Files selected for processing (2)

• packages/shared/src/KeyedCoalescingWorker.test.ts
• packages/shared/src/KeyedCoalescingWorker.ts

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

---

📝 Walkthrough

Walkthrough

KeyedCoalescingWorker now processes one item per batch and requeues keys with pending work. Tests check scheduling order, merged updates, drainKey() completion, and processing failure.

Changes

Keyed worker scheduling

Layer / File(s)	Summary
Batch completion and requeueing packages/shared/src/KeyedCoalescingWorker.ts, packages/shared/src/KeyedCoalescingWorker.test.ts	Each item is processed once, and completion requeues the key when pending work remains. The tests check that other keys run between batches, queued updates merge, drainKey() waits for the merged batch, and pending work runs after a processor failure.

Priority: ⬇️ Low

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

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant KeyedCoalescingWorker
  participant Processor
  participant Queue
  Queue->>KeyedCoalescingWorker: Dequeue a key
  KeyedCoalescingWorker->>Processor: Process one item
  KeyedCoalescingWorker->>Queue: Offer key when pending work remains

Loading

Merge Risk: ⚪ Minimal · up to d10f2

No merge-blocking issue was identified with the scheduling change; it is ready for normal merge checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to d10f2

The change improves fairness between terminal histories without changing persistence destinations or access authority. No introduced security concern was established, but interruption and shutdown behavior remains incompletely verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The observed scheduling blast radius is the terminal histories sharing one manager's sequential persistence worker. Cross-key delays remain possible within that worker; authentication, tenant mapping and deployment-wide exposure were not established by this inspection.

Trust Boundaries and Controls

• observed — Terminal output is sanitized before visible text is appended and queued for persistence. Enqueue and drain use the same thread/terminal session-key derivation, while filesystem destinations encode identifiers beneath logsDir. These source-to-sink controls are unchanged in the full PR comparison.

Resilience and Maintainability Implications

• inferred — Yielding removes recursive same-key monopolization and improves containment of a continuously updated terminal's scheduling load. It does not preempt a slow active processor or eliminate shared-worker coupling; those limitations already existed.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: preventing busy terminals from delaying history persistence.
Description check	✅ Passed	The description explains the problem, implementation, affected behavior, issue reference, verification results, and agent attribution. It is mostly complete, although it does not include an explicit m…
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.

✨ 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.}