acpmux new: one launcher for agents (worktree, prompt file, report-to, sidebar group, reuse)

Merged
TE
14d ago
+1187-94

Summary

One command starts an agent for a task, so nobody needs a hand-written spawn script (Leo, 2026-10-20: "acpmux and all the MCPs ... more unified, codified, operationalized, productionized, more obvious").

acpmux new -n gui/composer --worktree ~/Projects/cmux@origin/feat-cmux-next \
  --prompt-file briefs/composer.md --report-to cosmic-gray/claude-sr2 --group "GUI push" -d
  • --worktree REPO[@BASE]: the daemon makes or reuses ~/.cmux/worktrees/<project>/<name> on cmux/<name> (subsession_worktree::ensure_worktree, the same layout and fill code start_session worktrees use; the app's Apply/Remove find it). session/new takes it as _meta.acpmux.worktree {name, base}, over the local unix socket only, the same rule as session env and routes: peers and web clients are held to their folder roots.
  • --prompt-file F: read at call time from its absolute path; a missing or empty file fails before anything starts (spawn.sh started lanes without instructions on a relative path).
  • --report-to S: the first prompt says who started it and how to report back, plus where the worktree is.
  • Idempotent: running it again with the same name reuses the session and worktree and does not resend the prompt (--reuse, which --worktree implies); a create that loses a race to another launcher of the same name reuses the winner.
  • Names with / or spaces become valid session and branch names (gui/composer becomes gui-composer); the name as given stays the sidebar title.
  • --group G: shows the session in the app's sidebar group through cmux agent open with a stable workspace key (WIP: the app side of --group is the next commit).

WIP: the app agent open --group, the surface map doc and skill update, the MCP surface, and retiring spawn.sh.

Testing

  • cargo test -p acpmux --test session_new_worktree (new): made once, reused by the next start, refused for Web and Peer origins, bad base fails.
  • cargo test -p acpmux --lib -- launch:: subsession_worktree: name mapping, @ split, stable key, prompt file errors, ensure/reuse/branch-only cases.
  • End to end on a scratch daemon (huge-blue, fake agent): first run made the worktree and sent "You were started by ... / Your worktree ... / "; second run printed reused gui-lane ... and sent nothing; --prompt-file missing.md and --worktree --host failed before starting anything.

Observed / Not run

Observed: the commands above, plus clippy and the prepush gate, all clean. Not run: the app side (no Mac build yet).

Changelog

Added: acpmux new --worktree/--prompt-file/--report-to/--group/--reuse starts an agent in its own worktree with its brief in one idempotent command.

Agent session: huge-blue

🤖 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 new the one command for starting an agent for a task: a single call creates the session, its git worktree, and sends its instructions, so nobody needs a spawn script.

  • --worktree REPO[@BASE] makes or reuses ~/.cmux/worktrees/<project>/<name> on branch cmux/<name> through the daemon; only the local unix socket may request one, and a failed fill removes only the folder, never a branch that was already there.
  • --prompt-file FILE reads the brief at call time and fails before anything starts when it is missing, empty, or over 1 MiB.
  • --report-to SESSION starts the agent with who started it, how to report back, and where its worktree is.
  • --group GROUP shows the session in the app's sidebar via cmux agent open with a workspace key derived from the session id; the workspace joins the named group (made when missing), and a second run opens nothing because the key already names a listed row. It is this machine's sessions only: --group --host is refused, since the app cannot open another machine's session in a group yet. A failed sidebar step only warns; the prompt is still sent.
  • --reuse (implied by --worktree) reuses the running session and its worktree without resending the prompt, also after losing a create race to another launcher, which keeps the first prompt for itself; a rerun still queues the first prompt when a stopped launcher never sent it. A session that has ended, or works outside that worktree, is refused instead, as is a branch checked out in another worktree (that folder is named, not retried).
  • Misused launcher flags fail before anything starts: --worktree and --group refuse --host, --worktree replaces --cwd, --worktree/--group/--reuse need --name, and --report-to needs a prompt or --prompt-file.
  • The daemon holds one lock per worktree folder, so two launchers of one name never find a worktree half filled.
  • Names with / or spaces become valid session, worktree, and branch names (gui/composer becomes gui-composer); the name as given stays the sidebar title, and a plain acpmux new -n NAME keeps its name as given.

Follow-ups

  • The app side and surface map (cmux agent open --group, MCP app_agent_open {session, group}, docs/agent-surfaces.md) landed in this PR; only retiring spawn.sh remains.

Leo-ask: ask-c6c12eb823