Merge pull request #142 from pelazas/feat/ctl-spawn-new

ctl: spawn --new and name guest-visible panes

Author: pelazas

CHANGELOG.md

@@ -27,8 +27,10 @@ numbers and which end is old. A node that does not know ctl yet is told to upgra
 left hanging.
 
 `spawn` reuses a live inbox pane (`chat: {command}`) on that machine, waits until the pane exists,
-and will not nest `p2pmux`. `send` is raw PTY bytes and fails out loud when another member holds
-the input lease.
+and will not nest `p2pmux`. `spawn --new` always starts a pane. The reply includes
+`visible_to_guests` when someone unpaired is in the session. `send` is raw PTY bytes and fails out
+loud when another member holds the input lease. A ctl client that hangs up is dropped rather than
+held until the cap.
 
 ## v0.1.15 — 2026-09-01
 

USAGE.md

@@ -89,23 +89,32 @@ Stdout is JSON. Failures are one sentence on stderr. The six verbs:
 ```text
 p2pmux ctl [--session NAME] machines
 p2pmux ctl [--session NAME] agents
-p2pmux ctl [--session NAME] spawn --machine NAME -- <command...>
+p2pmux ctl [--session NAME] spawn [--new] --machine NAME -- <command...>
 p2pmux ctl [--session NAME] send <pane-id> [--] <keys>
 p2pmux ctl [--session NAME] focus <agent>
 p2pmux ctl [--session NAME] events
 ```
 
 `machines` is the pairing-owned list, including this machine. `agents` is the same roster Ctrl+O
 shows. `spawn` starts an allowlisted command on a machine you own, or a login shell when the
-command is empty. A live pane already titled `chat: {command}` on that host is reused; a pane
-that has exited or finished is not. Nested `p2pmux` is refused. The command waits until the pane
-exists.
+command is empty. Nested `p2pmux` is refused. The command waits until the pane exists.
+
+Without `--new`, a live pane already titled `chat: {command}` on that host is reused; a pane that
+has exited or finished is not. `--new` always starts a pane, which is what two jobs on one
+machine need. The JSON includes `visible_to_guests` when someone unpaired is in the session: the
+pane still opens, and anyone holding the join code can see it. Omit `--session` so ctl talks to
+the fleet session; a runner that wanted a private fleet skips the spawn when that flag is true.
 
 `send` writes the keys as PTY bytes, with no extra newline and no key names. It fails if someone
-else holds the pane's input lease. `focus` only moves to an agent that already has a pane —
-`p2pmux ctl spawn` is how one gets there. `events` prints `needs_you` / `done` / `error` as JSON
-lines: a snapshot first, then each change. The `message` field is present only when this node
-already has it.
+else holds the pane's input lease. It is typing, not a way to hand work from one agent to
+another. `focus` only moves to an agent that already has a pane — `p2pmux ctl spawn` is how one
+gets there. `events` prints `needs_you` / `done` / `error` as JSON lines: a snapshot first, then
+each change. The `message` field is present only when this node already has it, so a laptop
+watching a droplet sees the state and not the sentence.
+
+One agent finishing so another can start: wait on `events` until that `pane_id` is `done`, then
+`spawn --new` with the next command. The payload belongs on the command line (`claude -p …`),
+not in `send`.
 
 Ctl has its own pin, currently 1, independent of the peer wire pin. A client and a node that do
 not share it are told both numbers and which end to upgrade. A node too old to speak ctl at all

src/cli.rs

@@ -234,6 +234,9 @@ enum CtlCommand {
     Spawn {
         #[arg(long)]
         machine: String,
+        /// Do not reuse a live pane titled `chat: {command}` on that machine.
+        #[arg(long)]
+        new: bool,
         #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
         command: Vec<String>,
     },
@@ -502,9 +505,14 @@ fn run_ctl(session: Option<&str>, action: &CtlCommand) -> Result<(), Box<dyn Err
     let action = match action {
         CtlCommand::Machines => crate::ctl::CtlAction::Machines,
         CtlCommand::Agents => crate::ctl::CtlAction::Agents,
-        CtlCommand::Spawn { machine, command } => crate::ctl::CtlAction::Spawn {
+        CtlCommand::Spawn {
+            machine,
+            command,
+            new,
+        } => crate::ctl::CtlAction::Spawn {
             machine: machine.clone(),
             command: command.clone(),
+            new: *new,
         },
         CtlCommand::Send { pane, keys } => {
             let pane_id = pane

src/ctl.rs

@@ -38,6 +38,10 @@ pub enum CtlFromClient {
         machine: String,
         #[serde(default)]
         command: Vec<String>,
+        /// Skip reuse of a live `chat: {command}` pane. Omitted by older
+        /// clients, which keep the inbox behaviour.
+        #[serde(default)]
+        new: bool,
     },
     Send {
         pane_id: u64,
@@ -69,6 +73,8 @@ pub enum CtlToClient {
     Spawned {
         pane_id: u64,
         reused: bool,
+        #[serde(default)]
+        visible_to_guests: bool,
     },
     Sent {
         pane_id: u64,
@@ -122,6 +128,7 @@ pub enum CtlAction {
     Spawn {
         machine: String,
         command: Vec<String>,
+        new: bool,
     },
     Send {
         pane_id: u64,
@@ -246,9 +253,14 @@ pub fn run(socket: &Path, action: CtlAction) -> Result<(), Box<dyn Error>> {
     let request = match &action {
         CtlAction::Machines => CtlFromClient::Machines,
         CtlAction::Agents => CtlFromClient::Agents,
-        CtlAction::Spawn { machine, command } => CtlFromClient::Spawn {
+        CtlAction::Spawn {
+            machine,
+            command,
+            new,
+        } => CtlFromClient::Spawn {
             machine: machine.clone(),
             command: command.clone(),
+            new: *new,
         },
         CtlAction::Send { pane_id, keys } => CtlFromClient::Send {
             pane_id: *pane_id,
@@ -264,13 +276,14 @@ pub fn run(socket: &Path, action: CtlAction) -> Result<(), Box<dyn Error>> {
     if matches!(action, CtlAction::Events) {
         reader.get_mut().set_read_timeout(None)?;
         loop {
-            match receive_json::<CtlToClient>(&mut reader)? {
-                Some(event @ CtlToClient::Event { .. }) => {
+            match receive_json::<CtlToClient>(&mut reader) {
+                Ok(Some(event @ CtlToClient::Event { .. })) => {
                     println!("{}", serde_json::to_string(&event)?);
                 }
-                Some(CtlToClient::Error { message }) => return Err(CtlError(message).into()),
-                Some(_) => {}
-                None => return Ok(()),
+                Ok(Some(CtlToClient::Error { message })) => return Err(CtlError(message).into()),
+                Ok(Some(_)) | Ok(None) => {}
+                Err(error) if error.kind() == io::ErrorKind::UnexpectedEof => return Ok(()),
+                Err(error) => return Err(error.into()),
             }
         }
     }
@@ -291,12 +304,18 @@ pub fn run(socket: &Path, action: CtlAction) -> Result<(), Box<dyn Error>> {
                 serde_json::to_string(&serde_json::json!({ "agents": agents }))?
             );
         }
-        Some(CtlToClient::Spawned { pane_id, reused }) => {
+        Some(CtlToClient::Spawned {
+            pane_id,
+            reused,
+            visible_to_guests,
+        }) => {
             println!(
                 "{}",
-                serde_json::to_string(
-                    &serde_json::json!({ "pane_id": pane_id, "reused": reused })
-                )?
+                serde_json::to_string(&serde_json::json!({
+                    "pane_id": pane_id,
+                    "reused": reused,
+                    "visible_to_guests": visible_to_guests,
+                }))?
             );
         }
         Some(CtlToClient::Sent { pane_id }) => {
@@ -354,7 +373,10 @@ pub fn receive_json<T: for<'de> Deserialize<'de>>(
         Err(error) => return Err(error),
     };
     if count == 0 {
-        return Ok(None);
+        return Err(io::Error::new(
+            io::ErrorKind::UnexpectedEof,
+            "ctl connection closed",
+        ));
     }
     if count > MAX_FRAME {
         return Err(io::Error::new(
@@ -417,6 +439,50 @@ mod tests {
         assert!(!is_nested_p2pmux(&[]));
     }
 
+    #[test]
+    fn spawn_without_new_keeps_reusing() {
+        let spawn: CtlFromClient = serde_json::from_value(serde_json::json!({
+            "type": "spawn",
+            "machine": "droplet",
+            "command": ["claude"]
+        }))
+        .unwrap();
+        assert_eq!(
+            spawn,
+            CtlFromClient::Spawn {
+                machine: String::from("droplet"),
+                command: vec![String::from("claude")],
+                new: false,
+            }
+        );
+
+        let forced = serde_json::to_value(CtlFromClient::Spawn {
+            machine: String::from("droplet"),
+            command: vec![String::from("claude")],
+            new: true,
+        })
+        .unwrap();
+        assert_eq!(forced["new"], true);
+    }
+
+    #[test]
+    fn spawned_without_visible_to_guests_defaults_false() {
+        let spawned: CtlToClient = serde_json::from_value(serde_json::json!({
+            "type": "spawned",
+            "pane_id": 3,
+            "reused": true
+        }))
+        .unwrap();
+        assert_eq!(
+            spawned,
+            CtlToClient::Spawned {
+                pane_id: 3,
+                reused: true,
+                visible_to_guests: false,
+            }
+        );
+    }
+
     #[test]
     fn ctl_pin_does_not_move_the_wire_pin() {
         assert_eq!(CTL_PROTOCOL_PIN, 1);

src/node.rs

@@ -1264,7 +1264,7 @@ struct CtlClient {
     events: bool,
     seen_events: BTreeSet<(String, String)>,
     spawn_wait: Option<u64>,
-    spawn_retry: Option<(String, Vec<String>)>,
+    spawn_retry: Option<(String, Vec<String>, bool)>,
 }
 
 fn accept_ctl_hello(mut reader: BufReader<UnixStream>, pin: u32, clients: &mut Vec<CtlClient>) {
@@ -1323,8 +1323,8 @@ fn poll_ctl_clients(clients: &mut Vec<CtlClient>, node: &mut SharedLayoutNode) -
 
 fn poll_one_ctl(client: &mut CtlClient, node: &mut SharedLayoutNode) -> io::Result<bool> {
     let mut did_work = false;
-    if let Some((machine, command)) = client.spawn_retry.clone() {
-        match dispatch_ctl_spawn(node, client, machine, command) {
+    if let Some((machine, command, new)) = client.spawn_retry.clone() {
+        match dispatch_ctl_spawn(node, client, machine, command, new) {
             Ok(true) => {
                 client.spawn_retry = None;
                 did_work = true;
@@ -1342,13 +1342,9 @@ fn poll_one_ctl(client: &mut CtlClient, node: &mut SharedLayoutNode) -> io::Resu
     {
         client.spawn_wait = None;
         match result {
-            Ok(pane_id) => ctl::write_json(
-                client.reader.get_mut(),
-                &CtlToClient::Spawned {
-                    pane_id,
-                    reused: false,
-                },
-            )?,
+            Ok(pane_id) => {
+                ctl::write_json(client.reader.get_mut(), &ctl_spawned(node, pane_id, false))?
+            }
             Err(message) => {
                 ctl::write_json(client.reader.get_mut(), &CtlToClient::Error { message })?
             }
@@ -1386,8 +1382,12 @@ fn poll_one_ctl(client: &mut CtlClient, node: &mut SharedLayoutNode) -> io::Resu
             )?;
             did_work = true;
         }
-        Ok(Some(CtlFromClient::Spawn { machine, command })) => {
-            match dispatch_ctl_spawn(node, client, machine, command) {
+        Ok(Some(CtlFromClient::Spawn {
+            machine,
+            command,
+            new,
+        })) => {
+            match dispatch_ctl_spawn(node, client, machine, command, new) {
                 Ok(_) => {}
                 Err(message) => {
                     ctl::write_json(client.reader.get_mut(), &CtlToClient::Error { message })?
@@ -1432,7 +1432,9 @@ fn poll_one_ctl(client: &mut CtlClient, node: &mut SharedLayoutNode) -> io::Resu
         Err(error)
             if matches!(
                 error.kind(),
-                io::ErrorKind::ConnectionReset | io::ErrorKind::BrokenPipe
+                io::ErrorKind::ConnectionReset
+                    | io::ErrorKind::BrokenPipe
+                    | io::ErrorKind::UnexpectedEof
             ) =>
         {
             return Err(error);
@@ -1447,35 +1449,26 @@ fn dispatch_ctl_spawn(
     client: &mut CtlClient,
     machine: String,
     command: Vec<String>,
+    new: bool,
 ) -> Result<bool, String> {
-    match node.runtime.ctl_try_spawn(&machine, command.clone()) {
+    match node.runtime.ctl_try_spawn(&machine, command.clone(), new) {
         Ok(crate::ctl::CtlSpawn::Reused(pane_id)) => {
-            ctl::write_json(
-                client.reader.get_mut(),
-                &CtlToClient::Spawned {
-                    pane_id,
-                    reused: true,
-                },
-            )
-            .map_err(|error| error.to_string())?;
+            ctl::write_json(client.reader.get_mut(), &ctl_spawned(node, pane_id, true))
+                .map_err(|error| error.to_string())?;
             Ok(true)
         }
         Ok(crate::ctl::CtlSpawn::Busy) => {
-            client.spawn_retry = Some((machine, command));
+            client.spawn_retry = Some((machine, command, new));
             Ok(false)
         }
         Ok(crate::ctl::CtlSpawn::Started(request_id)) => {
             let _ = node.drain();
             if let Some(result) = node.runtime.ctl_take_result(request_id) {
                 match result {
-                    Ok(pane_id) => ctl::write_json(
-                        client.reader.get_mut(),
-                        &CtlToClient::Spawned {
-                            pane_id,
-                            reused: false,
-                        },
-                    )
-                    .map_err(|error| error.to_string())?,
+                    Ok(pane_id) => {
+                        ctl::write_json(client.reader.get_mut(), &ctl_spawned(node, pane_id, false))
+                            .map_err(|error| error.to_string())?
+                    }
                     Err(message) => {
                         return Err(message);
                     }
@@ -1489,6 +1482,14 @@ fn dispatch_ctl_spawn(
     }
 }
 
+fn ctl_spawned(node: &mut SharedLayoutNode, pane_id: u64, reused: bool) -> CtlToClient {
+    CtlToClient::Spawned {
+        pane_id,
+        reused,
+        visible_to_guests: node.runtime.ctl_visible_to_guests(),
+    }
+}
+
 fn publish_ctl_events(client: &mut CtlClient, node: &mut SharedLayoutNode) -> io::Result<bool> {
     let mut wrote = false;
     let mut seen = BTreeSet::new();