Merge pull request #138 from pelazas/feat/ctl

ctl: drive a session from the CLI

Author: pelazas

CHANGELOG.md

@@ -11,6 +11,19 @@ enrolment token — and a peer on the wrong side of it is refused rather than ha
 v0.1.10 that refusal says so in as many words, naming both protocol numbers and which machine is the
 old one; older peers still report it as a host they could not reach.
 
+## Unreleased
+
+**`p2pmux ctl` drives a live session from the CLI, without taking the TUI seat.** Six verbs
+(`machines`, `agents`, `spawn`, `send`, `focus`, `events`) speak JSON on stdout to the session
+node. Ctl has its own pin, currently 1. The peer wire pin is still 12: a ctl client and a session
+peer are different sockets, and moving one does not move the other. A pin mismatch names both
+numbers and which end is old. A node that does not know ctl yet is told to upgrade it rather than
+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.
+
 ## v0.1.15 — 2026-09-01
 
 Ten fixes and a shorter first-run telemetry ask, and no protocol change that costs anything: one field is added to the agent roster,

USAGE.md

@@ -77,6 +77,40 @@ Terminal 2: cargo run -- join <the code from Ctrl+S>
 Its PTY grid is fixed from the terminal size at startup: larger windows leave extra cells blank
 and smaller windows crop the upper-left fixed viewport.
 
+## Driving a session from a script
+
+`p2pmux ctl` talks to a live session without taking the TUI seat, so a fleet-agent node with
+nobody attached still answers. It does not start a session: if none is running, start `p2pmux`
+first. `--session` names one as `p2pmux list` prints it; omit it for the fleet session when this
+machine is paired, otherwise the newest live one.
+
+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] 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.
+
+`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.
+
+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
+says so after a short wait rather than hanging.
+
 ## Inviting someone
 
 `Ctrl+S` shows the line your guest runs. Enter copies it; send it as-is:

src/cli.rs

@@ -208,13 +208,47 @@ enum Command {
     },
     /// Report whether each agent's hooks are wired up.
     Doctor,
+    /// Drive a live session from a script, without taking the TUI seat.
+    Ctl {
+        /// Session name as `p2pmux list` prints it. Omit it for the fleet
+        /// session when this machine is paired, otherwise the newest live one.
+        #[arg(long)]
+        session: Option<String>,
+        #[command(subcommand)]
+        action: CtlCommand,
+    },
     #[command(name = "__node", hide = true)]
     Node {
         #[arg(long)]
         bootstrap: std::path::PathBuf,
     },
 }
 
+#[derive(Debug, Subcommand)]
+enum CtlCommand {
+    /// Pairing-owned machines this session can start work on.
+    Machines,
+    /// The same agent list Ctrl+O would show.
+    Agents,
+    /// Start an allowlisted command on a machine you own.
+    Spawn {
+        #[arg(long)]
+        machine: String,
+        #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
+        command: Vec<String>,
+    },
+    /// Write bytes into a pane as if they were typed.
+    Send {
+        pane: String,
+        #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
+        keys: Vec<String>,
+    },
+    /// Move this node's focus to an agent that already has a pane.
+    Focus { agent: String },
+    /// Stream needs_you / done / error as JSON lines.
+    Events,
+}
+
 #[derive(Debug, Subcommand)]
 enum SetupAgent {
     /// Claude Code, via marker-owned entries in ~/.claude/settings.json.
@@ -411,6 +445,7 @@ pub fn run_without_runtime(cli: &Cli) -> Option<Result<(), Box<dyn Error>>> {
             None => crate::agent_setup::setup_all(false, false),
         }),
         Some(Command::Doctor) => Some(crate::agent_setup::doctor()),
+        Some(Command::Ctl { session, action }) => Some(run_ctl(session.as_deref(), action)),
         // Reading and writing one small file. A user asking what is being sent
         // about them wants the answer now, not after a thread pool starts.
         Some(Command::Telemetry { command }) => Some(run_telemetry(command.as_ref())),
@@ -461,6 +496,52 @@ fn run_telemetry(command: Option<&TelemetryCommand>) -> Result<(), Box<dyn Error
     Ok(())
 }
 
+/// Talk to a live node without taking its TUI seat, and without starting one.
+fn run_ctl(session: Option<&str>, action: &CtlCommand) -> Result<(), Box<dyn Error>> {
+    let descriptor = resolve_ctl_session(session)?;
+    let action = match action {
+        CtlCommand::Machines => crate::ctl::CtlAction::Machines,
+        CtlCommand::Agents => crate::ctl::CtlAction::Agents,
+        CtlCommand::Spawn { machine, command } => crate::ctl::CtlAction::Spawn {
+            machine: machine.clone(),
+            command: command.clone(),
+        },
+        CtlCommand::Send { pane, keys } => {
+            let pane_id = pane
+                .parse::<u64>()
+                .map_err(|_| crate::ctl::CtlError(String::from("pane id must be a number")))?;
+            let keys = match keys.split_first() {
+                Some((first, rest)) if first == "--" => rest.join(" "),
+                _ => keys.join(" "),
+            };
+            crate::ctl::CtlAction::Send { pane_id, keys }
+        }
+        CtlCommand::Focus { agent } => crate::ctl::CtlAction::Focus {
+            agent: agent.clone(),
+        },
+        CtlCommand::Events => crate::ctl::CtlAction::Events,
+    };
+    crate::ctl::run(&descriptor.socket_path, action)
+}
+
+fn resolve_ctl_session(
+    name: Option<&str>,
+) -> Result<crate::session_store::SessionDescriptor, Box<dyn Error>> {
+    if let Some(name) = name {
+        return find_live(name);
+    }
+    let live = crate::session_store::SessionStore::for_current_user()?.list_live()?;
+    let pairing = crate::pairing::load_or_empty();
+    let candidates = if pairing.can_rejoin() {
+        hosting_the_fleet(&live, pairing.ticket.as_deref())
+    } else {
+        live
+    };
+    newest_live(&candidates).ok_or_else(|| {
+        CliError("no live session here; start p2pmux first, then ctl talks to it").into()
+    })
+}
+
 /// The live sessions on this machine, as `ticket`, `code`, `attach`, `kill` and `rename` name them.
 ///
 /// Those five commands all take a session name and every one of them documented `p2pmux list` as
@@ -569,7 +650,8 @@ pub async fn run(cli: Cli) -> Result<(), Box<dyn Error>> {
         | Some(Command::List)
         | Some(Command::Setup { .. })
         | Some(Command::Telemetry { .. })
-        | Some(Command::Doctor) => Ok(()),
+        | Some(Command::Doctor)
+        | Some(Command::Ctl { .. }) => Ok(()),
         Some(Command::Local) => crate::tui::run_local(),
         Some(Command::Config { command }) => match command {
             ConfigCommand::Init => {