supercode-harness 0.5.56

//! Live Claude Code peer sessions: registry discovery and inbound policy.
//!
//! Claude Code is the one supported harness whose *running* interactive
//! sessions are addressable. Each live process registers
//! `~/.claude/sessions/<pid>.json` and binds the Unix socket named in it. The
//! catalog ([`supercode_interchange::catalog`]) is deliberately about persisted state only, so
//! nothing there may claim liveness; this module is the separate, explicitly
//! process-checking half; it feeds session activity and the mail router's
//! `native` door, which reach clients as a discovered descriptor's `activity`
//! and `delivery`.
//!
//! Two rules earn their place here:
//!
//! 1. **A registry file is not a live session.** These files survive a crash,
//!    so every read re-checks the recorded pid with `kill(pid, 0)` and drops
//!    the record when the process is gone.
//!    A live pid is still not the session's holder when Claude Code itself
//!    says it is not: a window whose session was moved to the background keeps
//!    its record with `parkedJobId` set and the status it had at that moment
//!    (the background job registers its own record), and a pid the OS reused
//!    after the session died fails the recorded `procStart`. Claude Code skips
//!    both when it looks for a session's holder, and so do we.
//! 2. **Nothing here writes the socket.** The socket path is documented, but
//!    its wire frame is not, and a foreign process authenticating to it is not
//!    a supported case. Messages reach a live session through a Claude relay
//!    ([`crate::claude_relay`]), a headless Claude that sends with Claude's own
//!    `SendMessage`.

use std::path::{Path, PathBuf};
use std::{fs::OpenOptions, io::Write};

use serde::{Deserialize, Serialize};

use crate::HarnessHomes;

/// Activity a live Claude Code session reports for itself.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ClaudePeerStatus {
    /// A turn is running.
    Busy,
    /// The turn ended; the session waits for its user's next prompt.
    Idle,
    /// A turn is blocked on its user: a permission prompt or a question.
    Waiting,
}

impl ClaudePeerStatus {
    /// Stable wire spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Busy => "busy",
            Self::Idle => "idle",
            Self::Waiting => "waiting",
        }
    }

    /// Interpret Claude Code's registry spelling without making discovery
    /// brittle to a newer status value. `shell` is published after a turn has
    /// ended while a background shell the session started still runs: the
    /// transcript's last record is the turn's `turn_duration`, and the session
    /// waits at its prompt, so it is idle to a messenger.
    fn from_registry(value: &str) -> Option<Self> {
        match value {
            "busy" => Some(Self::Busy),
            "idle" | "shell" => Some(Self::Idle),
            "waiting" => Some(Self::Waiting),
            _ => None,
        }
    }
}

/// One live Claude Code session: a registry record whose pid answered
/// `kill(pid, 0)` during the read that produced this value.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ClaudePeerSession {
    /// Process holding the session.
    pub pid: u32,
    /// Claude-native session id, joinable to a discovered transcript.
    pub session_id: String,
    /// Working directory the session was started in.
    pub cwd: Option<PathBuf>,
    /// Registry display name; this is also the cross-session address.
    pub name: String,
    /// Unix socket the session binds for peer messaging.
    pub socket_path: PathBuf,
    /// Reported activity. Absent on sessions that never published one.
    pub status: Option<ClaudePeerStatus>,
    /// Registry update time in epoch milliseconds, when recorded.
    pub updated_at_ms: Option<u64>,
    /// Claude Code version that wrote the record.
    pub version: Option<String>,
    /// The tmux session and pane it runs in (`<session>:@<window>.%<pane>`),
    /// when it runs in tmux.
    pub tmux: Option<String>,
}

/// Directory holding the live-session registry for the configured Claude home.
///
/// [`HarnessHomes::claude_code`] points at `<claude home>/projects`, so the
/// registry is that directory's sibling. Deriving it keeps one configuration
/// knob (`CLAUDE_CONFIG_DIR`, through [`HarnessHomes`]) rather than adding a
/// second that could disagree with it.
pub fn registry_dir(homes: &HarnessHomes) -> PathBuf {
    homes
        .claude_code
        .parent()
        .unwrap_or(Path::new("."))
        .join("sessions")
}

/// User-level policy Claude Code applies to messages from other sessions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ClaudeCrossSessionInbound {
    /// Deliver messages without a separate inbound approval.
    Accept,
    /// Queue messages for an explicit approval.
    Hold,
    /// Drop messages without delivering them.
    Refuse,
}

impl ClaudeCrossSessionInbound {
    /// Stable Claude settings spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Accept => "accept",
            Self::Hold => "hold",
            Self::Refuse => "refuse",
        }
    }
}

/// The user-settings portion Supercode can inspect without pretending to know
/// a target process's complete managed/project/CLI precedence stack.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ClaudePeerSettings {
    /// Exact user settings file read or written.
    pub path: PathBuf,
    /// Hash of the exact native bytes observed. Configure calls may use this
    /// as an optimistic concurrency guard.
    pub revision: String,
    /// Explicit user value. `None` means Claude's permission-class default
    /// remains in effect and can hold a message.
    pub cross_session_inbound: Option<ClaudeCrossSessionInbound>,
}

impl ClaudePeerSettings {
    /// True only when this user setting explicitly opts into automatic
    /// delivery. A higher-precedence managed/project/CLI setting can still
    /// override it, so callers must label this as user-level evidence.
    pub fn user_allows_automatic_delivery(&self) -> bool {
        self.cross_session_inbound == Some(ClaudeCrossSessionInbound::Accept)
    }
}

/// Failure to read or safely update Claude Code's user settings.
#[derive(Debug, thiserror::Error)]
pub enum ClaudePeerSettingsError {
    /// Filesystem access failed.
    #[error("Claude Code settings I/O failed: {0}")]
    Io(#[from] std::io::Error),
    /// The existing settings file is not valid JSON.
    #[error("Claude Code settings JSON is invalid: {0}")]
    Json(#[from] serde_json::Error),
    /// The document shape or setting value is not one Supercode can preserve.
    #[error("{0}")]
    Invalid(String),
    /// Another process edited the file during Supercode's read-modify-write.
    #[error("Claude Code settings changed while Volter Harness was updating them; retry the explicit configuration action")]
    ChangedDuringWrite,
}

/// Claude Code's user settings file for the configured Claude home.
pub fn user_settings_path(homes: &HarnessHomes) -> PathBuf {
    homes
        .claude_code
        .parent()
        .unwrap_or(Path::new("."))
        .join("settings.json")
}

/// Inspect only the user-level inbound setting. The report deliberately does
/// not claim to be Claude's effective value because managed, project, and
/// command-line settings can have higher precedence in a particular target.
pub fn read_claude_peer_settings(
    homes: &HarnessHomes,
) -> Result<ClaudePeerSettings, ClaudePeerSettingsError> {
    let path = user_settings_path(homes);
    let bytes = match std::fs::read(&path) {
        Ok(bytes) => bytes,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Vec::new(),
        Err(error) => return Err(error.into()),
    };
    let value = if bytes.is_empty() {
        serde_json::Value::Object(serde_json::Map::new())
    } else {
        serde_json::from_slice(&bytes)?
    };
    let object = value.as_object().ok_or_else(|| {
        ClaudePeerSettingsError::Invalid(format!(
            "Claude Code settings at {} must be a JSON object",
            path.display()
        ))
    })?;
    let cross_session_inbound = match object.get("crossSessionInbound") {
        None => None,
        Some(serde_json::Value::String(value)) if value == "accept" => {
            Some(ClaudeCrossSessionInbound::Accept)
        }
        Some(serde_json::Value::String(value)) if value == "hold" => {
            Some(ClaudeCrossSessionInbound::Hold)
        }
        Some(serde_json::Value::String(value)) if value == "refuse" => {
            Some(ClaudeCrossSessionInbound::Refuse)
        }
        Some(value) => {
            return Err(ClaudePeerSettingsError::Invalid(format!(
                "Claude Code setting `crossSessionInbound` at {} must be `accept`, `hold`, or `refuse`, not {value}",
                path.display()
            )))
        }
    };
    Ok(ClaudePeerSettings {
        path,
        revision: blake3::hash(&bytes).to_hex().to_string(),
        cross_session_inbound,
    })
}

/// Explicitly update Claude Code's user-level inbound policy while preserving
/// every unrelated setting. The write is atomic, refuses symlinks, and aborts
/// when it observes an edit between its initial read and commit.
pub fn write_claude_peer_settings(
    homes: &HarnessHomes,
    cross_session_inbound: ClaudeCrossSessionInbound,
) -> Result<ClaudePeerSettings, ClaudePeerSettingsError> {
    update_claude_peer_settings(homes, Some(cross_session_inbound), None)
}

/// Set or reset Claude Code's user-level inbound policy. `expected_revision`
/// prevents an explicit UI action from overwriting settings inspected before
/// another process changed the file.
pub fn update_claude_peer_settings(
    homes: &HarnessHomes,
    cross_session_inbound: Option<ClaudeCrossSessionInbound>,
    expected_revision: Option<&str>,
) -> Result<ClaudePeerSettings, ClaudePeerSettingsError> {
    let path = user_settings_path(homes);
    if std::fs::symlink_metadata(&path)
        .map(|metadata| metadata.file_type().is_symlink())
        .unwrap_or(false)
    {
        return Err(ClaudePeerSettingsError::Invalid(format!(
            "refusing to replace symlinked Claude Code settings at {}",
            path.display()
        )));
    }
    let original = match std::fs::read(&path) {
        Ok(bytes) => bytes,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Vec::new(),
        Err(error) => return Err(error.into()),
    };
    let original_revision = blake3::hash(&original).to_hex().to_string();
    if expected_revision.is_some_and(|expected| expected != original_revision) {
        return Err(ClaudePeerSettingsError::ChangedDuringWrite);
    }
    let mut value = if original.is_empty() {
        serde_json::Value::Object(serde_json::Map::new())
    } else {
        serde_json::from_slice(&original)?
    };
    let object = value.as_object_mut().ok_or_else(|| {
        ClaudePeerSettingsError::Invalid(format!(
            "Claude Code settings at {} must be a JSON object",
            path.display()
        ))
    })?;
    let changed = match cross_session_inbound {
        Some(value) => {
            object.insert(
                "crossSessionInbound".into(),
                serde_json::Value::String(value.as_str().into()),
            ) != Some(serde_json::Value::String(value.as_str().into()))
        }
        None => object.remove("crossSessionInbound").is_some(),
    };
    if !changed {
        return read_claude_peer_settings(homes);
    }
    let mut encoded = serde_json::to_vec_pretty(&value)?;
    encoded.push(b'\n');

    let parent = path.parent().unwrap_or(Path::new("."));
    std::fs::create_dir_all(parent)?;
    let nonce = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default()
        .as_nanos();
    let temporary = parent.join(format!(
        ".settings.json.supercode-{}-{nonce}.tmp",
        std::process::id()
    ));
    let write_result = (|| -> Result<(), ClaudePeerSettingsError> {
        let mut options = OpenOptions::new();
        options.write(true).create_new(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt;
            options.mode(0o600);
        }
        let mut file = options.open(&temporary)?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::{MetadataExt, PermissionsExt};
            let mode = std::fs::metadata(&path)
                .map(|metadata| metadata.mode() & 0o777)
                .unwrap_or(0o600);
            file.set_permissions(std::fs::Permissions::from_mode(mode))?;
        }
        file.write_all(&encoded)?;
        file.sync_all()?;
        let current = match std::fs::read(&path) {
            Ok(bytes) => bytes,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Vec::new(),
            Err(error) => return Err(error.into()),
        };
        if current != original {
            return Err(ClaudePeerSettingsError::ChangedDuringWrite);
        }
        std::fs::rename(&temporary, &path)?;
        Ok(())
    })();
    if write_result.is_err() {
        std::fs::remove_file(&temporary).ok();
    }
    write_result?;
    read_claude_peer_settings(homes)
}

#[derive(Deserialize)]
struct RegistryRecord {
    pid: u32,
    #[serde(rename = "sessionId")]
    session_id: String,
    #[serde(default)]
    cwd: Option<PathBuf>,
    #[serde(default)]
    name: Option<String>,
    #[serde(rename = "messagingSocketPath", default)]
    messaging_socket_path: Option<PathBuf>,
    #[serde(default)]
    // Keep the vendor-owned value as text here. Deserializing it directly as
    // our closed enum made one newly introduced status discard the ENTIRE
    // live peer record, including its safe endpoint and process evidence.
    status: Option<String>,
    #[serde(rename = "updatedAt", default)]
    updated_at: Option<u64>,
    #[serde(default)]
    version: Option<String>,
    #[serde(default)]
    tmux: Option<String>,
    #[serde(rename = "parkedJobId", default)]
    parked_job_id: Option<String>,
    #[serde(rename = "procStart", default)]
    proc_start: Option<String>,
}

/// Read every LIVE session from a Claude registry directory.
///
/// Records are skipped, never fatal, when the file is malformed, when it names
/// no messaging socket, when its pid is gone or now belongs to another
/// process, or when its window parked the session into a background job — a
/// stale file left by a crashed session is exactly the case that must not be
/// reported as live, and a parked window's status froze when it let go.
pub fn read_registry(directory: &Path) -> Vec<ClaudePeerSession> {
    let Ok(entries) = std::fs::read_dir(directory) else {
        return Vec::new();
    };
    let mut sessions = Vec::new();
    for entry in entries.flatten() {
        let path = entry.path();
        if path.extension().and_then(|value| value.to_str()) != Some("json") {
            continue;
        }
        let Ok(bytes) = std::fs::read(&path) else {
            continue;
        };
        let Ok(record) = serde_json::from_slice::<RegistryRecord>(&bytes) else {
            continue;
        };
        let (Some(name), Some(socket_path)) = (record.name, record.messaging_socket_path) else {
            continue;
        };
        if record.session_id.is_empty()
            || name.is_empty()
            || record.parked_job_id.is_some()
            || !process_is_live(record.pid)
            || record
                .proc_start
                .as_deref()
                .is_some_and(|recorded| !same_process_start(record.pid, recorded))
        {
            continue;
        }
        sessions.push(ClaudePeerSession {
            pid: record.pid,
            session_id: record.session_id,
            cwd: record.cwd,
            name,
            socket_path,
            status: record
                .status
                .as_deref()
                .and_then(ClaudePeerStatus::from_registry),
            updated_at_ms: record.updated_at,
            version: record.version,
            tmux: record.tmux,
        });
    }
    sessions.sort_by_key(|session| session.pid);
    sessions
}

/// Whether `pid` is still the process that wrote `recorded` as its
/// `procStart`, in Claude Code's own spelling: `/proc/<pid>/stat`'s start
/// time in clock ticks on Linux, `ps -o lstart=` under `TZ=UTC LC_ALL=C` on
/// macOS. A start time this platform cannot read proves nothing and is not a
/// mismatch.
#[cfg(target_os = "linux")]
fn same_process_start(pid: u32, recorded: &str) -> bool {
    let Ok(stat) = std::fs::read_to_string(format!("/proc/{pid}/stat")) else {
        return true;
    };
    // `comm` may hold spaces and parentheses; fields resume after the last `)`.
    // `starttime` is field 22, the 20th after `comm`.
    let Some(start) = stat
        .rsplit_once(')')
        .and_then(|(_, rest)| rest.split_whitespace().nth(19))
    else {
        return true;
    };
    start == recorded.trim()
}

#[cfg(target_os = "macos")]
fn same_process_start(pid: u32, recorded: &str) -> bool {
    use std::mem::{size_of, MaybeUninit};
    let Ok(pid) = libc::c_int::try_from(pid) else {
        return true;
    };
    let mut info = MaybeUninit::<libc::proc_bsdinfo>::zeroed();
    let size = size_of::<libc::proc_bsdinfo>() as libc::c_int;
    // SAFETY: the buffer is exactly one `proc_bsdinfo`, the flavor's layout.
    let read = unsafe {
        libc::proc_pidinfo(
            pid,
            libc::PROC_PIDTBSDINFO,
            0,
            info.as_mut_ptr().cast(),
            size,
        )
    };
    if read != size {
        return true;
    }
    // SAFETY: `proc_pidinfo` filled all `size` bytes.
    let seconds = unsafe { info.assume_init() }.pbi_start_tvsec;
    let Ok(seconds) = libc::time_t::try_from(seconds) else {
        return true;
    };
    let mut tm = MaybeUninit::<libc::tm>::zeroed();
    let mut text = [0u8; 64];
    // SAFETY: `gmtime_r` writes one `tm`; `strftime` writes at most
    // `text.len()` bytes into `text` from a NUL-terminated format.
    let written = unsafe {
        if libc::gmtime_r(&seconds, tm.as_mut_ptr()).is_null() {
            return true;
        }
        libc::strftime(
            text.as_mut_ptr().cast(),
            text.len(),
            c"%a %b %e %H:%M:%S %Y".as_ptr(),
            tm.as_ptr(),
        )
    };
    if written == 0 {
        return true;
    }
    let actual = String::from_utf8_lossy(&text[..written]);
    // `ps` pads a one-digit day with a space; compare words, not spacing.
    actual.split_whitespace().eq(recorded.split_whitespace())
}

#[cfg(not(any(target_os = "linux", target_os = "macos")))]
fn same_process_start(_pid: u32, _recorded: &str) -> bool {
    true
}

#[cfg(unix)]
pub(crate) fn process_is_live(pid: u32) -> bool {
    // SAFETY: signal 0 performs only a liveness/permission check.
    let result = unsafe { libc::kill(pid as libc::pid_t, 0) };
    result == 0 || std::io::Error::last_os_error().raw_os_error() == Some(libc::EPERM)
}

#[cfg(windows)]
pub(crate) fn process_is_live(pid: u32) -> bool {
    use windows_sys::Win32::Foundation::{CloseHandle, STILL_ACTIVE};
    use windows_sys::Win32::System::Threading::{
        GetExitCodeProcess, OpenProcess, PROCESS_QUERY_LIMITED_INFORMATION,
    };

    let process = unsafe { OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid) };
    if process.is_null() {
        return false;
    }
    let mut code = 0u32;
    let read = unsafe { GetExitCodeProcess(process, &mut code) } != 0;
    unsafe {
        CloseHandle(process);
    }
    read && code == STILL_ACTIVE as u32
}

#[cfg(not(any(unix, windows)))]
pub(crate) fn process_is_live(_pid: u32) -> bool {
    false
}

/// Why a message could not be delivered into a live session.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ClaudePeerRefusal {
    /// No live process is running this session right now.
    NotLive,
    /// The registry name no longer resolves to the requested session.
    IdentityMismatch,
    /// The relay did not report the message as sent.
    DeliveryFailed,
}

impl ClaudePeerRefusal {
    /// Stable wire spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::NotLive => "not_live",
            Self::IdentityMismatch => "identity_mismatch",
            Self::DeliveryFailed => "delivery_failed",
        }
    }
}

/// A refusal paired with the detail that names it.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error("{message}")]
pub struct ClaudePeerRefusalError {
    /// Machine-readable reason.
    pub reason: ClaudePeerRefusal,
    /// Human-readable detail.
    pub message: String,
}

impl ClaudePeerRefusalError {
    fn new(reason: ClaudePeerRefusal, message: impl Into<String>) -> Self {
        Self {
            reason,
            message: message.into(),
        }
    }
}

/// Resolve `session_id` to the live Claude session running it.
///
/// The registry is re-read here rather than trusted from a discovery result,
/// and the resolved name is checked back against the requested session id: a
/// name that has moved to another live session must refuse, not deliver a
/// message to the wrong reader.
pub fn resolve_live_session(
    homes: &HarnessHomes,
    session_id: &str,
) -> Result<ClaudePeerSession, ClaudePeerRefusalError> {
    let registry = read_registry(&registry_dir(homes));
    let target = registry
        .iter()
        .find(|session| session.session_id == session_id)
        .cloned()
        .ok_or_else(|| {
            ClaudePeerRefusalError::new(
                ClaudePeerRefusal::NotLive,
                format!(
                    "no live Claude Code process is running session `{session_id}`; \
                     its transcript is persisted only"
                ),
            )
        })?;
    let by_name = registry
        .iter()
        .filter(|session| session.name == target.name)
        .collect::<Vec<_>>();
    if by_name.len() != 1 || by_name[0].session_id != target.session_id {
        return Err(ClaudePeerRefusalError::new(
            ClaudePeerRefusal::IdentityMismatch,
            format!(
                "the registry name `{}` no longer resolves to session `{session_id}` alone; \
                 refusing rather than delivering into another session",
                target.name
            ),
        ));
    }

    Ok(target)
}