acpmux ls: --live, --name, --host; the plain view is the live sessions

Closed
TE
7d ago
+535-249

Leo, 2026-10-29: "are the tools/commands/docs/etc clear and good enough for you guys? i feel like they could be better"

What was wrong

On a busy host acpmux ls --json lists 4,800+ sessions, mostly closed, which is far too much for an agent to read. The plain text acpmux ls printed every one of them too. An agent looking for "my live lanes" or "the sessions on host X" had to pull everything and filter it with jq.

What changes

  • New filters on acpmux ls. Each one narrows both the text and the --json output, and they combine with the existing --status, --pending, --tag, --since, --limit and --fields:
    • --live: any status but closed. It is also sent to the daemon as excludeStatus: ["closed"], so closed rows never cross the socket.
    • --name REGEX: matches the session name (HOST/NAME for a peer's). A bad pattern is a usage error (exit 2).
    • --host HOST: a peer's sessions, or this machine's (local or the machine name).
  • Compact default for the text view only. With no filter, acpmux ls prints the live sessions, newest first, at most 40, then one line that says what it left out and how to see it:
    2660 more live and 300 closed not shown: --all lists every session; --live, --name REGEX, --host HOST, --status S or --limit N narrow it.
    --all gives the old full table. Any filter prints every row it keeps.
  • --fields a,b,c already existed. The docs now point agents at acpmux ls --json --live --fields name,status,peer.
  • Unflagged acpmux ls --json is unchanged and still returns the full list. I checked the callers that read it: in this repo the acpmux integration tests; in our workspace tooling lane-place, pr-owner, orphan-sweep, lane-failover, the keep-going, stale-PR and sidebar reconcilers, review-report, the review-box reaper and acpmux_sessions. All of them use --json and several need every row. I found no caller that parses the text table.
  • Command::Ls's flags and handler moved to cli/run/ls.rs (LsArgs), so command.rs and run/standard.rs shrink instead of growing. Both are already over the god-file ceiling on base.
  • README and the acpmux skill document the new flags.

Tests

  • cli::run::ls::tests: --live/--name/--host row filtering (peer, own machine name, local), bad regex as a usage error, and the compact view's rows plus its hidden-count note (including "no live sessions").
  • tests/ls_selection.rs against a real daemon with a 3,000-session store, every tenth one closed: --json --live returns 2,700 rows and none closed; --name with --live; --host local and an unknown host; a bad --name exits 2; a filtered text view lists every match; the plain ls is a header, 40 live rows and the note; --all is all 3,000. The existing checks still hold: unflagged --json returns all 3,000 rows, and --limit/--fields/--since work as before.

Observed / Not run

  • Observed: cargo check -p acpmux --tests and cargo clippy -p acpmux --tests are clean here, and the god-file check with --base origin/feat-cmux-next reports no growth.
  • The test run is on CI (cmux-ci test), linked in a comment below.

Agent session: agent session

šŸ¤– Generated with Claude Code

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

Summary by cubic

Makes acpmux ls readable on a busy host: the plain text view now shows live sessions only, and new --live, --name, and --host flags narrow both text and JSON output.

  • With no filter, acpmux ls prints at most 40 live sessions, newest first, and a note saying what it hid and how to see it; --all restores every session.
  • The new flags combine with the existing --status, --pending, --tag, --since, --limit, and --fields; a bad --name pattern is a usage error (exit 2).
  • Unflagged acpmux ls --json is unchanged and still returns the full list; no caller in this repo parses the text table.
  • Command::Ls's flags and handler moved to cli/run/ls.rs, keeping command.rs and run/standard.rs from growing further.

Tests

  • cli::run::ls::tests covers row filtering, a bad regex as a usage error, and the compact view's rows plus its hidden-count note.
  • tests/ls_selection.rs runs against a real daemon with a 3,000-session store, every tenth one closed, including a fix so closed fixture sessions keep an event log (without one, the daemon treats them as purged and drops them at startup).