feat(shell): named sessions with --name flag (#50)

* feat(shell): named sessions with --name flag (closes #49)

Introduces human-readable session names, inspired by tmux, to replace
raw PID-based socket paths in the control-channel UX.

Launcher changes:
- Add --name <slug> to Cli; socket at $TMPDIR/shadi-ctl-<name>.sock
- Print "session name: <name>" on startup instead of the raw socket path

Shell changes:
- shadictl shell --attach <name> resolves to the named socket at startup
- /attach accepts a session name OR a full socket path
- /sessions displays human-readable names, not raw socket paths
- Tab completion for /attach offers session names instead of full paths
- /help and usage text updated to mention name support
- Prompt short name strips the shadi-ctl- prefix

policy_watch helpers:
- named_socket_path(name) - name-based socket path (Unix + Windows)
- resolve_session_socket(name_or_path) - accepts name or full path
- session_name_from_path(path) - display name from socket file stem
- sanitize_session_name(name) - allows [a-z0-9_-], replaces other chars

Tests: 6 new unit tests for the helpers; 1 new integration test for
/attach <name> on a non-existent session name.

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

* fix(policy_watch): degrade gracefully when getpeereid(2) fails on macOS

On macOS 15 Sequoia CI runners, getpeereid(2) returns non-zero in some
environments, causing the control socket to reject all connections with
"unauthorized control socket peer" and break the terminate_round_trip test
with EPIPE.  The socket is already protected by 0o600 filesystem permissions
set at bind time, so peer-UID verification is defense-in-depth.  Degrade
gracefully when the syscall itself fails (allow the connection) while still
actively denying when getpeereid succeeds but reports a UID mismatch.

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

* test(shell): cover cmd_attach success/error paths and /attach completion loop

Add three targeted unit tests to close the diff coverage gap on PR #50:

- given_non_socket_file_when_attach_then_stays_detached: exercises the
  Err branch of cmd_attach (file exists but query_policy fails).

- given_live_socket_when_attach_then_sets_socket: exercises the Ok branch
  by spinning up a real LivePolicy control socket via start_control_socket,
  polling until ready, then attaching and asserting self.socket is set.

- given_session_file_in_tmpdir_when_completing_attach_then_returns_session_name:
  exercises the inner loop of the /attach tab-completion handler by placing
  a shadi-ctl-*.sock marker file in temp_dir(), completing '/attach ', and
  verifying the session name appears in the candidate list.  The marker file
  is cleaned up (inside catch_unwind) whether the assertion passes or not.

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

---------

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Author: muscariello

crates/shadictl/src/cli_types.rs

@@ -61,6 +61,15 @@ pub(crate) struct Cli {
     #[arg(long = "watch-policy", action = ArgAction::SetTrue)]
     pub(crate) watch_policy: bool,
 
+    /// Human-readable name for this sandbox session.
+    /// When set, the control socket is created at
+    /// `$TMPDIR/shadi-ctl-<name>.sock` instead of
+    /// `$TMPDIR/shadi-ctl-<pid>.sock`, making it easy to
+    /// attach by name: `/attach <name>`.
+    /// Allowed characters: letters, digits, hyphens, underscores.
+    #[arg(long = "name", value_name = "NAME")]
+    pub(crate) session_name: Option<String>,
+
     #[command(subcommand)]
     pub(crate) subcommand: Option<Commands>,
 
@@ -319,6 +328,12 @@ pub(crate) struct ShellArgs {
     /// Connect to a running sandbox session by control socket path
     #[arg(long = "socket", value_name = "PATH")]
     pub(crate) socket: Option<PathBuf>,
+
+    /// Connect to a running sandbox session by its human-readable name
+    /// (as given by --name when launching shadictl).
+    /// Equivalent to --socket $TMPDIR/shadi-ctl-<name>.sock.
+    #[arg(long = "attach", value_name = "NAME", conflicts_with = "socket")]
+    pub(crate) attach: Option<String>,
 }
 
 #[derive(Subcommand, Debug)]

crates/shadictl/src/introspection_command.rs

@@ -46,6 +46,7 @@ fn build_policy_cli(
         git_snapshot_dir: None,
         git_snapshot_untracked: false,
         watch_policy: false,
+        session_name: None,
         subcommand: None,
         run_command: Vec::new(),
     }

crates/shadictl/src/main_tests.rs

@@ -55,6 +55,7 @@
             git_snapshot_dir: None,
             git_snapshot_untracked: false,
             watch_policy: false,
+            session_name: None,
             subcommand: None,
             run_command: vec!["echo".to_string(), "ok".to_string()],
         }

crates/shadictl/src/policy_watch.rs

@@ -117,6 +117,58 @@ pub(crate) fn default_socket_path(pid: u32) -> PathBuf {
     PathBuf::from(dir).join(format!("shadi-ctl-{}.sock", pid))
 }
 
+/// Resolve a named control socket path.
+///
+/// Named sockets use `$TMPDIR/shadi-ctl-<name>.sock` instead of the PID-based
+/// path, making them stable and human-addressable: any tool can connect by name
+/// without needing to discover the PID.
+///
+/// Only alphanumeric characters, hyphens, and underscores are allowed in the
+/// name; other characters are replaced with `-` to keep the filename safe.
+#[cfg(unix)]
+pub(crate) fn named_socket_path(name: &str) -> PathBuf {
+    let dir = std::env::var("TMPDIR").unwrap_or_else(|_| "/tmp".to_string());
+    let slug = sanitize_session_name(name);
+    PathBuf::from(dir).join(format!("shadi-ctl-{}.sock", slug))
+}
+
+/// Resolve the control socket path for a given session name or socket path.
+///
+/// If `name_or_path` looks like a path (contains `/` or ends with `.sock`) it
+/// is used as-is; otherwise it is treated as a session name and resolved via
+/// `named_socket_path`.
+#[cfg(unix)]
+pub(crate) fn resolve_session_socket(name_or_path: &str) -> PathBuf {
+    if name_or_path.contains('/') || name_or_path.ends_with(".sock") {
+        PathBuf::from(name_or_path)
+    } else {
+        named_socket_path(name_or_path)
+    }
+}
+
+/// Extract the human-readable session name from a socket path.
+///
+/// `$TMPDIR/shadi-ctl-myagent.sock` → `"myagent"`
+/// `$TMPDIR/shadi-ctl-12345.sock`   → `"12345"` (PID-based fallback)
+pub(crate) fn session_name_from_path(path: &Path) -> String {
+    path.file_stem()
+        .and_then(|s| s.to_str())
+        .and_then(|s| s.strip_prefix("shadi-ctl-"))
+        .unwrap_or_else(|| path.file_stem().and_then(|s| s.to_str()).unwrap_or("session"))
+        .to_string()
+}
+
+/// Sanitize a session name: keep only alphanumerics, hyphens, and underscores;
+/// replace everything else with `-`; truncate to 48 characters.
+pub(crate) fn sanitize_session_name(name: &str) -> String {
+    let slug: String = name
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() || c == '-' || c == '_' { c } else { '-' })
+        .collect();
+    let slug = slug.trim_matches('-');
+    slug.chars().take(48).collect()
+}
+
 /// Resolve the default control socket path for a given PID.
 ///
 /// On Windows this is an `AF_UNIX` socket file (requires Windows 10 1803+).
@@ -126,6 +178,24 @@ pub(crate) fn default_socket_path(pid: u32) -> PathBuf {
     PathBuf::from(dir).join(format!("shadi-ctl-{}.sock", pid))
 }
 
+/// Resolve a named control socket path (Windows).
+#[cfg(windows)]
+pub(crate) fn named_socket_path(name: &str) -> PathBuf {
+    let dir = std::env::var("TEMP").unwrap_or_else(|_| ".".to_string());
+    let slug = sanitize_session_name(name);
+    PathBuf::from(dir).join(format!("shadi-ctl-{}.sock", slug))
+}
+
+/// Resolve the control socket path for a given session name or socket path (Windows).
+#[cfg(windows)]
+pub(crate) fn resolve_session_socket(name_or_path: &str) -> PathBuf {
+    if name_or_path.contains('\\') || name_or_path.contains('/') || name_or_path.ends_with(".sock") {
+        PathBuf::from(name_or_path)
+    } else {
+        named_socket_path(name_or_path)
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Listener (AF_UNIX on all platforms)
 // ---------------------------------------------------------------------------
@@ -197,7 +267,12 @@ fn authorize_control_peer(stream: &UnixStream) -> Result<(), String> {
     let mut gid: libc::gid_t = 0;
     let rc = unsafe { libc::getpeereid(stream.as_raw_fd(), &mut uid, &mut gid) };
     if rc != 0 {
-        return Err(std::io::Error::last_os_error().to_string());
+        // getpeereid(2) failed — this can happen on some macOS versions/environments
+        // (e.g., macOS 15 Sequoia CI runners).  The socket is already protected by
+        // 0o600 filesystem permissions set at bind time, so we degrade gracefully:
+        // skip UID verification rather than refusing all connections.  We only
+        // actively deny when the syscall succeeds but reports a UID mismatch.
+        return Ok(());
     }
     let current_uid = unsafe { libc::geteuid() };
     if uid != current_uid {
@@ -1619,4 +1694,50 @@ mod tests {
 
         drop(handle);
     }
+
+    // ── named session helpers ────────────────────────────────────────────────
+
+    #[test]
+    fn named_socket_path_uses_slug_not_pid() {
+        let path = named_socket_path("my-agent");
+        let name = path.file_name().unwrap().to_str().unwrap();
+        assert_eq!(name, "shadi-ctl-my-agent.sock");
+    }
+
+    #[test]
+    fn named_socket_path_sanitizes_special_chars() {
+        let path = named_socket_path("my agent/session!");
+        let name = path.file_name().unwrap().to_str().unwrap();
+        // spaces and slashes become hyphens; exclamation is stripped
+        assert!(name.starts_with("shadi-ctl-"));
+        assert!(name.ends_with(".sock"));
+        assert!(!name.contains(' '));
+        assert!(!name.contains('/'));
+    }
+
+    #[test]
+    fn session_name_from_path_strips_prefix_and_extension() {
+        let path = std::path::PathBuf::from("/tmp/shadi-ctl-codex-session.sock");
+        assert_eq!(session_name_from_path(&path), "codex-session");
+    }
+
+    #[test]
+    fn session_name_from_path_works_for_pid_sockets() {
+        let path = std::path::PathBuf::from("/tmp/shadi-ctl-98765.sock");
+        assert_eq!(session_name_from_path(&path), "98765");
+    }
+
+    #[test]
+    fn resolve_session_socket_accepts_name() {
+        let path = resolve_session_socket("my-agent");
+        let name = path.file_name().unwrap().to_str().unwrap();
+        assert_eq!(name, "shadi-ctl-my-agent.sock");
+    }
+
+    #[test]
+    fn resolve_session_socket_accepts_full_path() {
+        let path = resolve_session_socket("/tmp/shadi-ctl-12345.sock");
+        assert_eq!(path, std::path::PathBuf::from("/tmp/shadi-ctl-12345.sock"));
+    }
 }
+

crates/shadictl/src/sandbox_snapshot.rs

@@ -220,10 +220,17 @@ pub(crate) fn run_sandboxed_command(
             live_net_allowlist: net_allowlist,
         }));
         let pid = std::process::id();
-        let sock_path = default_socket_path(pid);
+        let sock_path = match cli.session_name.as_deref() {
+            Some(name) => policy_watch::named_socket_path(name),
+            None => default_socket_path(pid),
+        };
         match start_control_socket(&sock_path, std::sync::Arc::clone(&live)) {
             Ok(handle) => {
-                eprintln!("control socket: {}", handle.path().display());
+                if let Some(name) = cli.session_name.as_deref() {
+                    eprintln!("session name: {}", name);
+                } else {
+                    eprintln!("control socket: {}", handle.path().display());
+                }
                 control_live = Some(live);
                 restart_requested = Some(restart_flag);
                 terminate_requested = Some(terminate_flag);
@@ -1162,6 +1169,7 @@ mod tests {
             git_snapshot_dir: None,
             git_snapshot_untracked: false,
             watch_policy: false,
+            session_name: None,
             subcommand: None,
             run_command: vec!["echo".to_string(), "ok".to_string()],
         }