[lawrencecchen]

Summary

SWITCH FRAMES SF-5 (part C). After #32384 and #32380, with 8 warm hidden terminals each printing 20 lines/s the app's main thread was quiet (wakes near baseline), but the whole app still woke about 115 times a second (24 busy hidden: 114/s; 0 busy: 4/s; cmux24, 2x display). Cause: each warm hidden terminal has its own attach connection, and the daemon's snapshot attach worker sent every output frame at once. Each frame woke the app's reader thread, its event consumer, its output lane and Ghostty's renderer thread.

Fix, as Chrome throttles a background page's timers (aligned to 1 s), never by delaying anything the person sees:

• cmux-tui: new raw command set-attach-visibility {surface, visible} (capability attach-visibility-v1). While a snapshot viewer is hidden, its attach worker keeps the output in one batch and sends it as one output event on the next whole wall-clock second. Every hidden viewer of the daemon uses the same second, so the app's wakeups coalesce.
  • The batch goes out at once: past 256 KiB (a hidden yes stays bounded), before any snapshot, READY or other frame (stream order), at the end of the stream, and when the viewer is shown again (the command pokes the worker's wait).
  • Offsets stay contiguous and no byte is dropped. A digest never names a position past bytes still in the batch.
  • Spec (commands.md), inventory, SDK schema, generated bindings and the api-compat surface are updated.
• cmux-tui (review): while a viewer is hidden, the attach's notification thread holds scroll-changed (the newest replaces the older) and sends the newest when the viewer is shown. The app applies no scroll-changed from an attach, so these were pure wakeups, once per daemon frame of a printing terminal. Notifications on the attach are never held. The idle digest is re-armed after every batch flush.
• App: TerminalAttachment.sendHidden (conceal/reveal of a tab, and a re-attach while hidden) also sends set-attach-visibility when the daemon has the capability: after the view stops counting toward the grid when it hides, and before it counts again when it shows. DaemonCapability.attachVisibility (optional); the export is updated.

What still arrives while hidden (lead's constraint 1)

• The sidebar and tab state the daemon publishes on its event subscription (titles, bells, notifications, agent status, unread marks) does not go through this attach path, so nothing changes there.
• State the app parses from the terminal's own bytes (an OSC title, a bell, progress) arrives within one batch window: the Rust test checks that a title written while hidden reaches the viewer within 1.3 s.

Showing a hidden terminal (lead's constraint 3)

The app sends visible: true before it counts toward the grid again, and the daemon sends the waiting output at once (the test: within 250 ms of the show, in practice one local round trip). Until that output is parsed, the pane shows the state as of the last batch, at most 1 s old. Because a batch is one output event, it parses in one step and never draws half. Limit: the waiting bytes are still in the daemon at the show, so they are not parsed in the same main-actor turn as the show.

Testing

• Rust a_hidden_snapshot_viewer_gets_no_scroll_changed_until_shown (review): red at 428a6bb (step 2b751734): "4 scroll-changed events reached a hidden viewer".
• At the head 6bd5627 (merged with feat): Rust green of both tests 2/2 (step 5a2ac8ca), clippy pass (step 2f15824d), Swift compile passed.
• Rust server::terminal_snapshot::socket_tests::a_hidden_snapshot_viewer_gets_output_once_a_second_and_at_once_when_shown (Linux, cargo nextest):
  • Red at 27ea0f6 (command recorded, worker not using it; step 97bee5fe): "21 output events for 21 writes in 2 s to a hidden viewer".
  • Green at a0249db (step f0a94c58): 1 of 1 passed. Clippy at a0249db: pass (step 67184ac2).
• Swift TerminalAttachHiddenBatchTests (the order of sizing and visibility commands on hide and show, with and without the capability): red 5/5 at d484d49 (step 588f0c77, 3 asserts), green 5/5 at 6f71e0f (step cda860c4). Compiles of both passed.
• Spec checks: check-spec-inventory.py and check-sdk-schema.py pass; bindings/codegen/generate.py --check passes; the api-compat surface is the one api-compat-check --write produced (step cc256ad6).
• Busy-terminal A/B on one mini (cmux24, bench builds), 24 busy hidden terminals, all-thread app wakeups:
  • Round 1 (first version, without the scroll hold): 127.8 -> 88.8 /s; 8 busy: 140.7 -> 70.5 /s; CPU 2.18 -> 1.41 %. Not at the target. The fix arm's main thread was at baseline; the rest was the attach scroll-changed events the review found.
  • Round 2 (this head, same feat base dc06451, which has terminal: a hidden terminal's output costs the launch-frame keeper no wakes (SWITCH FRAMES SF-5 A) #32384 and cmux-tui + app: hidden terminals' scroll events no longer wake the app's event pump (SWITCH FRAMES SF-5 B) #32380): result added when it ends.

Observed / Not run

• Observed: the wakeup ledger and thread sample that named the cause (rounds sw-sf5-busy-ledger, sw-sf5c-sample), the red and green runs above.
• Not run: the full cmux-tui suite (hosted --full), a switch video on this head.

Changelog

• Changed: terminals in hidden workspaces that print a lot no longer wake cmux many times a second; their output reaches the app once a second until they are shown.

Proof

No capture: no visible change.

[cursor]

Bugbot needs on-demand usage enabled

Bugbot uses usage-based billing for this team and requires on-demand usage to be enabled.

A team admin can enable on-demand usage in the Cursor dashboard.

[github-actions]

cmux status _{(one comment, edited in place; each line is updated by the job that owns it)}

Review 6bd5627: HQ feed card · gallery before/after runs · checks

App of this head (app.zip, kept 1 day)

gh workflow run reload-build.yml -R manaflow-ai/cmux --ref feat-cmux-next -f tag=pr32446 -f ref=fix/switch-hidden-attach-batch -f platform=macos -f backend_mode=local

Shipped in:

• cmux NEXT nightly 1.0.0-nightly.4149439773601 (6ad4953200)
• cmux NEXT nightly 1.0.0-nightly.4149622662301 (72e65a53e0)
• cmux NEXT nightly 1.0.0-nightly.4149719270001 (ccb777fdde)
• cmux NEXT nightly 1.0.0-nightly.4149824422001 (f6b340f97a)
• cmux NEXT nightly 1.0.0-nightly.4150011005501 (fbf9260854)
• cmux NEXT nightly 1.0.0-nightly.4150109776501 (ae802cfe75)
• cmux NEXT nightly 1.0.0-nightly.4150231832001 (9b07402606)

[lawrencecchen]

Review (subagent, correctness first): SHIP at 6bd5627

An independent review agent read the full diff (read only; it built and ran nothing), in three rounds.

• Round 1 at 3c1af19: SHIP, no must-fix. Offsets stay contiguous across batch flushes and every other event; a snapshot or overflow while bytes are batched gives the batch, then a correct READY; no busy loop and no lost wake (poke under the queue lock); memory is bounded (256 KiB per viewer on top of the queue cap); the Swift command order on hide and show is right, including a re-attach while hidden; older daemons and remote native owners are unchanged. Should-fixes: scroll-changed on the attach still woke the app while hidden; the idle digest was not re-armed after some flushes; a wrong test comment.
• Round 2 at 4e57f1c: those three fixed; FIX FIRST on a probable clippy collapsible_if, which the fleet confirmed (with a type_complexity).
• Round 3 at 6bd5627: SHIP. Both clippy items fixed (fleet clippy pass, step 2f15824d); the feat merge changes no file of this PR.
• Known: when a hidden terminal is shown, its first frame can show content up to 1 s old until the waiting output arrives (one local round trip); stated in the body for the lead. Cosmetic: the VisibilityWaker alias sits between the gate's doc comment and the struct.

ready-to-land waits for the busy-terminal A/B round 2 on one mini (lead's gate).