[teamleaderleo]

Leo, 2026-10-30: "that visibility into [one agent host's] guys was (and is?) pretty bad i feel like we can make more improvements to acpmux/cmux-next"

Leo, on acpmux ls: "and acpmux ls should probably not be overly... verbose? i guess" / "to keep everything efficient... tho idk"

Part of HQ#1920, HQ#5226 and the HQ#5123 telemetry lane (row d: "Show unknown, never a synthesized zero. A metric must trigger an action."). Related: HQ#5266 (a revived session keeps its autocompact cap); this PR never warns on such a session's unknown cap.

A usage audit found four long-running Claude sessions with no autocompact cap carrying 290-330k of context per call and starting 67-90 Opus subagents. Nothing in acpmux or cmux NEXT showed it; finding it took a hand audit of ps lines and transcripts. This PR is the visible warning: a person sees a mark, not a log line.

What changes

• acpmux decides the warnings, once. A session summary gets usageWarnings: [{rule, value, limit, text}], computed when the summary is read from its usageStats (the fields from the companion acpmux usage-stats PR) and the thresholds:

  • noAutocompactCap: a Claude session (family claude) whose usageStats.autocompact is none.
  • contextTokens: usageStats.contextTokens is above the limit.
  • subagentsPerHour: usageStats.subagents1h is above the limit.

  The warning list is empty for a closed session or one with no usageStats yet, so until the usage-stats PR lands nothing shows.

• Unknown stays unknown. A count acpmux could not read is null, never 0. An autocompact of unknown (an adopted or revived chat whose launch acpmux never saw, or a setting it could not read) never raises or clears a warning. A value it lacks shows as ?, never 0.

• Each warning names the action that answers it (action: {label, command, available}). The tooltip line ends with it, and nothing runs automatically:

  rule	action	command
  no autocompact cap	Rotate onto a capped profile	lane-place rotate NAME (coming: session restart keeps the launch settings, so it adds no cap)
  context above 400k	Compact it	acpmux send NAME /compact (Claude Code's own command; the Claude adapter already runs it as a prompt, see compact_ends_its_prompt_and_reports_the_compaction)
  subagents above 40/h	Open the session to see what it starts; cancel its turn to stop it	acpmux session cancel NAME

• One declared place for the thresholds: the new usageWarnings section of acpmux config.json, {"contextTokens": 400000, "subagentsPerHour": 40, "autocompactCap": true}. Those are the defaults (config/usage_warnings.rs), and 0 or false turns a rule off. Documented in the acpmux README and docs/acpmux-schema.json.

• acpmux ls stays compact. Default ls gets a WARN column holding the single word warn per flagged row, shown only while some row has one; with no warnings the output is unchanged. The reasons and commands (ctx 412k: acpmux send NAME /compact; 90 sub/h: acpmux session cancel NAME) go to --wide, which the companion usage-stats PR adds. --json rows carry the whole usageWarnings. Computing the warning reads only the already-cached usageStats on the summary, and no transcript is read for it.

• The cmux NEXT sidebar row gets a small warning triangle (exclamationmark.triangle.fill, theme attention color) in the trailing cluster beside the muted bell. It is its own view, not the working-state spinner. Its tooltip lists each warning's text, e.g. "90 subagents started in the last hour, above 40", and the row's accessibility label includes them. It is on for everyone: it does not depend on the sidebar.laneStatus / rowStatus / nowLine toggles. The Debug sidebar.laneFixture working sample now carries warnings, so captures show the badge.

How N was chosen (subagents per hour)

The rate is the peak count of Agent/Task tool calls in any sliding 60-minute window, measured per main transcript across every Claude transcript on this agent host (63 sessions, the last ~3 days):

peak subagents in any 60 min	sessions
0	47
1-4	13
5-9	2
10-30	1 (the area coordinator, 27, which is intended fan-out)
> 30	0
the runaway deputies (audit)	67-90

N = 40 sits above every ordinary session, with headroom over the busiest coordinator (27), and well below the runaway deputies. It is a config value, so it can move without a release.

The context limit of 400k is about where sr2's managed --autocompact window sits (380k-420k), so a session that compacts normally never reaches it. Five of the 63 sessions here peaked above 400k; all five are long-lived coordinators with no cap, which is the case this warning is for.

Tests

• Rust hub/usage_warnings_tests.rs covers:
  • a runaway session breaks all three rules, with its numbers and text;
  • a capped ordinary lane breaks none;
  • the limits are exclusive;
  • only Claude is held to a cap;
  • a closed session, or one with no stats, gets no warnings;
  • a session with no cap but no context read yet still warns;
  • config overrides and 0/false turn rules off, and an all-default config writes nothing.
• Rust cli/ls_table_tests.rs: warn_is_one_word_and_shows_only_while_a_row_has_one. The default ls shows one warn word; --wide shows each rule's short form and its commands.
• Swift SidebarUsageWarningTests covers:
  • the lane parses usageWarnings;
  • the row carries its chats' warnings with laneStatus on and off;
  • duplicate lines show once;
  • the badge shows, with the tooltip and accessibility text;
  • a hovered row keeps the badge, at full opacity and left of its ⋯/× controls (theBadgeStaysBesideTheHoverControls). This test was committed red first, in 527848c, and the fix is 84e7b01. The first fleet capture showed the hover controls covering it.
  • a row with no warnings shows no badge.
• Gallery AAUsageWarningGalleryTests (CMUX_TEST_REQUIRE_GUI=1, artifact usage-warning-gallery.tar): the real sidebar list drawn light and dark, before (no warnings) and after (the working chat breaks all three rules). Each still is also printed base64 to the log.
• The sidebar owner's note (plans/cmux-next/sidebar-owner.md) logs the look change, and the commit carries a Sidebar-Look: trailer.

Observed / Not run

• Observed:
  • The subagent-rate distribution above, from this host's transcripts.
  • Rust at 46be2bf (the acpmux code has not changed since): cargo clippy -p acpmux --all-targets --locked -- -D warnings is clean, and cargo test -p acpmux --lib -- usage_warn ls_table protocol_ir_is_current catalog_reload a_cell_without remote_summary peer_cache passes 32/32.
  • Independent Codex reviews (gpt-6-astra, high):
    • BLOCK at 70d34d2: reload dropped the section. Fixed.
    • BLOCK at 8cb0b7a: a peer row's commands lacked the peer prefix. Fixed.
    • SHIP at 413c6f8, then SHIP at 46be2bf.
    • SHIP at 891176a (gpt-6.1-sol, high), after the hover fix and the Debug hover hook fix, with no findings.
  • scripts/cmux-next/prepush-gate.py passes at the head.
  • Reds that fail the same way on base, per test (PR comments): the Rust panic ratchet (indexing_slicing 700 > 693, string_slice 98 > 94, the same at merge base e863077) and cmux-next checks. The latter's one counted red is String tables, with check-l10n.sh output the same at e863077; its sidebar-trailer annotation names three base commits, and this PR's range has 0.
  • The defaults guard's five "defaults changed" entries are fingerprints of functions that read Debug tunables. No default value changes, and the review receipt cleared it.
• Not run: the Swift suites (SidebarUsageWarningTests, the gallery AAUsageWarningGalleryTests). CI's cmux-next swift test job waits on a fast-tier runner label that has started nothing, and this lane VM cannot build Swift.

Captures

Fleet captures from a build of the head, driven on a capture mini, checked by eye. The stills will be linked here once pr-media uploads work again.

• (A) Rows, light, job 77c9fa09, head 84e7b01 against base e863077. It ends on the frame with three workspaces and the Debug lane fixture on:
  • head: perf-sweep shows the red failed mark, flaky-ci the orange needs-you dot, and fleet-coordinator its working spinner with the warning triangle just left of it;
  • base: the same marks and no triangle.
• (B) Tooltip on hover, dark, head 891176a. It matches.
  • The row is hovered with ⋯/∨/× showing; the triangle stays at full opacity just left of ⋯, the pointer rests on it (⋯ is not highlighted), and no row card opens.
  • The tooltip lists all three lines with their commands.
  • In the still, the first 1-4 characters of each line are cut off at the left. That is only the capture cropping to the app window. The themed tooltip is its own borderless window (TooltipPanel), centered under the badge and clamped to the screen's visible frame (TooltipPresenter.origin, covered by ThemedTooltipTests). So a person sees it whole, and the crop is the roughly 700 pt wide tooltip running past the window's left edge.
  • An earlier run of B, job 8adf1a57 at 84e7b01, showed no tooltip, because the Debug hover hook aimed at the badge's resting place, under ⋯. Fixed in 891176a.
• Both runs were checked by eye by the capture lane. The stills are kept on the capture host (A: ~/.cache/pr-capture/84e7b01d/steps-ac9b6932cf/, B: ~/.cache/pr-capture/891176a8/steps-87a9bbecf9/) until pr-media uploads work.

No capture: the stills above exist (A at 84e7b01, B at 891176a, both matched by eye), but pr-media uploads are blocked for now; the image links will replace this line.

Performance

_acpmux/sessions latency (what acpmux ls calls), from the companion usage-stats PR's bench ls_latency: 30 fake-Claude chats that each ran a turn, 50 timed calls per mode, each on a new connection, on one 32-vCPU CI runner. Before is the companion branch b9c165d; after is the same tree plus this PR's daemon and config changes, so usageStats is present and every row's warnings are computed. Both were built once and run alternately (before, after, before, after); each figure is the mean of the two rounds. Command: cargo test -p acpmux --test hub_integration ls_latency -- --ignored --nocapture.

metric	before	after	delta	harness or run link
acpmux ls (no usage read) p50	21.8 ms	21.6 ms	-0.2 ms (-1%)	run 41012923271
acpmux ls (no usage read) p95	28.0 ms	27.9 ms	-0.1 ms (-0%)	run 41012923271
acpmux ls --wide / --json (usage read) p50	21.1 ms	21.3 ms	+0.1 ms (+1%)	run 41012923271
acpmux ls --wide / --json (usage read) p95	26.6 ms	27.2 ms	+0.6 ms (+2%)	run 41012923271

The deltas are within the spread between the two "before" rounds (p50 21.7 vs 22.0 ms; p95 25.9 vs 27.2 ms). Computing the warnings reads only the usageStats already on the summary: no transcript read, no new timer, no lock wait.

Changelog

• Added: agent chats that run with no autocompact cap, a context over 400k tokens, or more than 40 subagents an hour show a warning badge on their sidebar row, whose tooltip says what to do, and a warn mark in acpmux ls.

Agent session: agent session

🤖 Generated with Claude Code

[github-actions]

Default changes

This pull request changes 6 defaults at 722f4ad27e58 (what everyone gets without configuring anything):

• tunable-source.CmuxNextAgentLanes/SidebarLaneFixture.swift:lanes: "e5bf82d452ec08a462990a7e27655972db1325c2d0f791424796c03803185d6b" -> "3afa5d94e3950f7d21494720723162fc7074d98a0d536bb5623e8efe8cf35658"
• tunable-source.CmuxNextAgentLanes/SidebarLaneFixture.swift:usageWarnings: (none) -> "203d3bc547d85ce87026b5b36ae8de2a7b17801189edfa1272847da45fd696f3"
• tunable-source.CmuxNextAgentLanes/SidebarLaneStatus.swift:applying: "5d6c8d2675ba6d9fe643848718932d19684190ef866bffd313b6ce603fa9f58b" -> "e1795e53a3bdb92a5c6fa11df2d57908d1dec0bd0096c8a8c861f684c49b07f7"
• tunable-source.CmuxNextAgentLanes/SidebarLaneStatus.swift:usageWarnings: (none) -> "0f968becda26988217a84e686b5ca14e62a3561dcf73b497c4479b9cc31c3672"
• tunable-source.CmuxNextApp/Control/DebugPointerHover.swift:move: (none) -> "01571277e7e1b946f8a327405986371df256e999262b1347095a2746bd70e262"
• tunable-source.CmuxNextApp/Control/DebugPointerHover.swift:run: "706a3f27283be5e36c52d3bcce3f4d7509ceeb2e24f47a65b35956b9bbfd1fd8" -> "909cb40e193d33baee810d65dfaf5f421acc99c163694781ca77bd9c9b961324"

Signed off on this commit by review (codex gpt-6.1-sol high, review-router).

Merge receipt: merged as 5842663a31ac with these defaults changed, signed off by review (codex gpt-6.1-sol high, review-router).

Regenerate the snapshot with python3 scripts/ci/defaults_guard.py snapshot.

[blacksmith-sh]

Found 4 test failures on Blacksmith runners:

Failures

Test	View Logs
main.DeveloperIdAppTests.test_download_prints_the_active_profile_only/ test_download_prints_the_active_profile_only	View Logs
stubs: /System/Library/Frameworks/Security.framework/Versions/A/Security has no stub/ Security has no stub	View Logs
stubs: CoreFoundation.tbd: install-name /System/Library/Frameworks/ CoreFoundation.framework/Versions/A/CoreFoundation, missing 1: ['_CFRetain']/ CoreFoundation, missing 1: ['_CFRetain']	View Logs
stubs: CoreFoundation.tbd: install-name /System/Library/Frameworks/ CoreFoundation.framework/Versions/A/CoreFoundation, missing 1: ['_log2']/ CoreFoundation, missing 1: ['_log2']	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[teamleaderleo]

Review (codex-review-box/gpt-6-astra high, lane-place): BLOCK at 70d34d2

BLOCK

1. [P2] cmux-tui/crates/acpmux/src/config.rs:1006 — Reload drops the new configuration. reload_catalog() never copies next.usage_warnings into the live config. Editing thresholds and running acpmux daemon reload leaves the old limits active; a subsequent preset/policy save overwrites the edited section with those old values. Copy the section during reload and test that it survives a subsequent save.

2. [P2] cmux-tui/crates/acpmux/src/hub/views.rs:471 — Lock contention changes the warning policy. While a config writer holds the lock, unwrap_or_default() silently substitutes enabled default rules, even when the user disabled them or configured different thresholds. Such summaries can reach watchers and peer caches. Read a retained snapshot of the configured limits instead of substituting defaults when the lock is busy.

Rust/Swift toolchains were unavailable, so compilation was assessed statically.

BLOCK at 70d34d2: warning configuration is omitted from reload and replaced by defaults during lock contention

[github-actions]

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

Review 722f4ad: 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=pr27899 -f ref=lane/ao-vis-warn -f platform=macos -f backend_mode=local

web and size checks: green

[teamleaderleo]

Reds at 46be2bf, classified (no rerun):

• cmux-next checks (god files, concurrency, crash safety, l10n): base. Its one counted red is String tables (21 languages). scripts/cmux-next/check-l10n.sh prints the same output at this head and at the merge base e863077: 112 errors, CmuxHome.xcstrings missing languages. The Sidebar look owner annotation names three base commits: 4367c16, 6c1a5ab, eb8105b. The same sweep over this PR's commits (e863077..46be2bf) finds 0, and the check is warn-only.
• nightly-guards release-notary / Guard status: base.
• Rust panic ratchet: base, identical at e863077 (comment above).
• pr-capture-check: this PR's own red. The captures are pending from a fleet capture mini.
• cmux-next swift test: has been queued since ~03:45Z and has not run, so the Swift side has not compiled in CI yet.

[teamleaderleo]

Review (codex gpt-6.1-sol high, review-router): SHIP at 891176a

No correctness or compile findings. This replaces the receipt at 46be2bf. The diff reviewed was the PR from the merge base (git diff e8630779176c...891176a87966), with the three new commits since 46be2bf read closely:

• 527848c: the red test theBadgeStaysBesideTheHoverControls.
• 84e7b01: a hovered row keeps the warning badge, left of its hover controls.
• 891176a: debug.pointer_hover {usageWarning} aims at the badge after the hover layout.

Reviewer's notes:

• WorkspaceRowView+Rendering.swift:205-211: the badge shifts left of the hover controls, and the layout at rest is unchanged.
• :249-261: coverStart drives the occlusion and fades, and the badge is exempt.
• SidebarUsageWarningTests.swift:77-91: the fixture row is closable, so the close control shows; the test fails before the fix and passes after it.
• DebugPointerHover.swift:35-49: explicit-point, rail and null-point behavior is intact.

Astra (gpt-6-astra) through the router timed out twice on reconnects with no verdict, so this review ran on Sol, as acpmux-owner directed.

[teamleaderleo]

Review (codex gpt-6.1-sol high, review-router): SHIP at 722f4ad

No findings. This replaces the receipt at 891176a. The new head merges feat-cmux-next at 214b514 into the branch, bringing in #28015, so usageStats is now real data. Only docs conflicted: the schema JSON (usageWarnings placed in base's new SessionSummary line) and sidebar-owner.md (both entries kept). The diff reviewed was the whole PR against the new merge base, plus the merge's remerge-diff.

Reviewer's notes:

• views.rs:362,505,513,521-524: family and usage_stats are set before the warnings are computed.
• usage_view.rs:154-176 and usage_stats.rs:274-292: the serialized fields and their null and enum values match what usage_warnings.rs reads.
• peers.rs:457-480,609,685: remote summaries keep the usage fields, and the warning commands are rewritten with the peer-qualified name.
• ls_table.rs:293-329: WARN and the seven usage columns have matching headers and cells, with no duplicate column.
• acpmux-schema.json:149-150: parses, and keeps both usageStats/UsageStats and usageWarnings.

[github-actions]

Shipped in:

• cmux NEXT nightly 1.0.0-nightly.4112891057101 (ac6b39be7f)
• cmux NEXT nightly 1.0.0-nightly.4112983685701 (81085d9646)
• cmux NEXT nightly 1.0.0-nightly.4113159963901 (9408230f7a)
• cmux NEXT nightly 1.0.0-nightly.4113304608001 (567d1434e3)