ctl C1: opt-in control plane — channel + spawn/list, spawn tree, caps

[JSBtechnologies]

What & why

First milestone of the amux ctl control plane (design — roadmap/amux-ctl-control-plane.md): turn amux from a viewer of agents into a runtime for a controllable, observable hierarchy. An agent (or the human) in one pane can spawn and list other agent panes over a tiny local control channel — every worker a normal, visible, killable pane.

Severe/critical per charter §3 (a hosted agent gains process-spawn power) → PR + review. The C0 spike already proved the two load-bearing unknowns (zero-dep named-pipe IPC + non-blocking drain); this builds the real thing on that.

Surface (all behind --allow-ctl, off by default)

amux --allow-ctl [--max-depth <N>] [command…]     # bind the channel
amux ctl spawn [--role R] -- <cmd>                 # open a visible worker → {ok,pane,session,role}
amux ctl list                                      # the org chart → {ok,tree:[{id,parent,role,depth,status}]}

How it's built

• ipc.rs — zero-dep channel: Windows named pipe (PIPE_NOWAIT, the C0-verified design, in the same kernel32-FFI house style as pty/cred) / unix socket. Non-blocking Listener::poll/respond, drained from the run loop with no thread.
• ctl.rs — the amux ctl client + protocol. evaluate_spawn() is the pure safety guard (allowlist + depth), unit-tested in isolation.
• main.rs — --allow-ctl/--max-depth; every pane gets a global agent_id and is born with AMUX_CTL/AMUX_PANE in its env (merged with identity secrets, which stay per-spawn and unlogged); apply_ctl applies requests as pane ops.

Safety model (design §5) — the heart of the review

• Opt-in, off by default. No --allow-ctl ⇒ no pipe, amux ctl refuses, behavior byte-identical to 0.6.1.
• Agents-only allowlist ({claude}), extensible per session by the human via AMUX_CTL_ALLOW — never weakens a session that didn't ask.
• --max-depth (default 6, 0=unlimited) bounds recursion, not width — a fork-bomb circuit-breaker; a designed fleet of any size still runs.
• Visibility = safety. Every ctl-spawned agent is a normal pane: in the bar, in ctl list, killable.
• Identity secrets are merged into the child env for one spawn only, never cached/logged; only names surface.

Verification

python dev.py check green — 112 lib + 43 integration tests, dep-guard OK, fmt + clippy clean. New coverage:

• pure guard (allowlist / depth / AMUX_CTL_ALLOW), request build↔parse roundtrip, flag parsing;
• the ipc roundtrip (C0 spike promoted to a permanent Windows test);
• three live e2e tests driving a real amux over the pipe: list roundtrip, spawn opens a visible worker window, off-allowlist refusal returns a clean JSON error.

Not in C1 (C2–C3)

ctl send / status / kill, credential delegation scoping, --here splits. --here currently returns a clear "lands in C2" error rather than silently opening a new window.