docs(acpmux): background-process registry design (list, tail, kill)

Merged
TE
23d ago
+173-0

Summary

Design for first-class background processes in acpmux: list, tail and kill the dev servers, watchers and long test runs an agent starts, and keep them running past the turn and past a closed chat. The NEXT GUI (op-next-launch) builds on the wire contract here.

ACP has nothing for this. Its client-side terminal/* methods are going away in v2, and no RFD or PR covers listing or killing processes, so it's an _acpmux/* extension that we'll offer upstream as an RFD once it works for us. The decision to stay on ACP rather than fork it is in cmuxterm-hq#2014.

Doc: cmux-tui/crates/acpmux/docs/background-processes.md. It covers:

  • Process record: one per process, kept with the session.
  • Sources: Claude Code's task events and output file; Codex's commandExecution items and thread/backgroundTerminals/*.
  • Wire: _acpmux/process/{list,tail,watch,kill} and a process_update notification that replaces background_task_update.
  • Lifetime: what happens at turn end, chat close, over budget, daemon restart and harness exit.
  • Client contract for the GUI.
  • Planned behavior tests.

Part of it is built: #20585 (lifted limits, running updates, the idle reaper fix) and #20724 (the registry for Claude Code's shells: process/list, process/kill, process_update). The doc marks what is built. Still to build: tail/watch, Codex, and the per-session resource valve, which comes back without process scanning in cx-v9s8g.

Testing

Docs only; nothing to run.

Changelog

none

Proof

Docs only.

šŸ¤– 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

Adds a design doc for first-class background processes in acpmux: listing, tailing, and killing the dev servers, watchers, and long test runs an agent starts, and keeping them running past the turn and past a closed chat.

  • Introduces a per-process record kept with the session, fed by Claude Code's task events and Codex's background terminals.
  • Defines the _acpmux/process/{list,tail,watch,kill} wire contract and a process_update notification replacing the non-spec background_task_update; list, kill, and process_update are built, the rest is pending.
  • Covers lifetime rules at turn end, chat close, harness exit, and daemon restart; over-budget killing is deferred to cx-v9s8g without ps//proc scans, and the client contract for the NEXT GUI is included.
  • Regenerates schemas/defaults/cmux-next.json, which adds setting.freeModel.enabled; unrelated to the doc.

Docs only; nothing to run.