@pheem49/mint 1.15.0 → 1.17.0

package/crates/mint-core/src/system/bg_shell.rs

@@ -8,8 +8,9 @@
 //! tools wired up in `orchestration.rs`.
 
 use std::{
+    cell::RefCell,
     collections::HashMap,
-    io::Read,
+    io::{Read, Write},
     path::{Path, PathBuf},
     process::{Child, Command, Stdio},
     sync::{Arc, LazyLock, Mutex},
@@ -29,6 +30,7 @@ const MAX_BUF_BYTES: usize = 256 * 1024;
 #[derive(Debug, Clone)]
 pub enum JobStatus {
     Running,
+    Stopping,
     Exited(i32),
     Killed,
     Failed(String),
@@ -37,14 +39,14 @@ pub enum JobStatus {
 /// Growable buffer that tracks how much of itself has already been handed
 /// back by [`JobRecord`] polling, and caps total retained size so a chatty
 /// background process can't grow memory unbounded.
-struct CappedBuf {
-    data: String,
+pub(crate) struct CappedBuf {
+    pub(crate) data: String,
     read_offset: usize,
     truncated: bool,
 }
 
 impl CappedBuf {
-    fn new() -> Self {
+    pub(crate) fn new() -> Self {
         Self {
             data: String::new(),
             read_offset: 0,
@@ -52,7 +54,7 @@ impl CappedBuf {
         }
     }
 
-    fn push(&mut self, chunk: &str) {
+    pub(crate) fn push(&mut self, chunk: &str) {
         self.data.push_str(chunk);
         if self.data.len() > MAX_BUF_BYTES {
             let mut cut = self.data.len() - MAX_BUF_BYTES;
@@ -80,9 +82,18 @@ pub struct JobRecord {
     cwd: PathBuf,
     pid: Option<u32>,
     status: Mutex<JobStatus>,
-    stdout: Mutex<CappedBuf>,
-    stderr: Mutex<CappedBuf>,
+    stdout: Arc<Mutex<CappedBuf>>,
+    stderr: Arc<Mutex<CappedBuf>>,
     started_at: Instant,
+    started_ms: i64,
+    ended_ms: Mutex<Option<i64>>,
+    context: JobContext,
+    server_url: Mutex<Option<String>>,
+    stop_complete: std::sync::atomic::AtomicBool,
+    stop_error: Mutex<Option<String>>,
+    managed_stop: Option<Arc<std::sync::atomic::AtomicBool>>,
+    // Held by the backend, so the owned child observes EOF when its owner dies.
+    owner_stdin: Mutex<Option<std::process::ChildStdin>>,
 }
 
 pub struct StartedJob {
@@ -99,6 +110,9 @@ pub struct JobSummary {
     pub status: JobStatus,
     pub pid: Option<u32>,
     pub elapsed_secs: u64,
+    pub cwd: PathBuf,
+    pub workspace: PathBuf,
+    pub server_url: Option<String>,
 }
 
 /// Full accumulated stdout/stderr for one job, for `/shells show <id>`.
@@ -113,6 +127,9 @@ pub struct JobSnapshot {
     pub pid: Option<u32>,
     pub stdout: String,
     pub stderr: String,
+    pub truncated: bool,
+    pub elapsed_secs: u64,
+    pub server_url: Option<String>,
 }
 
 static BG_SHELL_JOBS: LazyLock<Mutex<HashMap<String, Arc<JobRecord>>>> =
@@ -123,7 +140,182 @@ static NEXT_JOB_ID: LazyLock<Mutex<u32>> = LazyLock::new(|| Mutex::new(0));
 fn next_job_id() -> String {
     let mut n = NEXT_JOB_ID.lock().unwrap();
     *n += 1;
-    format!("bg-{n}")
+    format!("bg-{}-{n}", &BACKEND_ID[..8])
+}
+
+static SHUTTING_DOWN: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
+pub struct ShutdownGuard;
+impl Drop for ShutdownGuard {
+    fn drop(&mut self) {
+        shutdown();
+    }
+}
+pub fn is_shutting_down() -> bool {
+    SHUTTING_DOWN.load(std::sync::atomic::Ordering::Acquire)
+}
+static BACKEND_ID: LazyLock<String> = LazyLock::new(|| uuid::Uuid::new_v4().to_string());
+static CHAT_OWNERS: LazyLock<Mutex<HashMap<String, Option<String>>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+#[derive(Clone, Default)]
+pub struct JobContext {
+    pub workspace: PathBuf,
+    pub chat_id: Option<String>,
+    pub owner: Option<String>,
+}
+thread_local! { static JOB_CONTEXT: RefCell<JobContext> = RefCell::new(JobContext::default()); }
+pub fn with_context<T>(context: JobContext, run: impl FnOnce() -> T) -> T {
+    struct Restore(JobContext);
+    impl Drop for Restore {
+        fn drop(&mut self) {
+            JOB_CONTEXT.with(|c| c.replace(self.0.clone()));
+        }
+    }
+    let previous = JOB_CONTEXT.with(|c| c.replace(context));
+    let _restore = Restore(previous);
+    run()
+}
+fn normalized_chat(chat: &str) -> &str {
+    let chat = chat.trim();
+    if chat.is_empty() {
+        crate::DEFAULT_CONVERSATION_ID
+    } else {
+        chat
+    }
+}
+pub fn bind_chat_owner(chat: &str, owner: Option<String>) -> bool {
+    let chat = normalized_chat(chat);
+    let mut owners = CHAT_OWNERS.lock().unwrap();
+    let parent = chat.split("::subagent::").next().unwrap_or(chat);
+    if let Some(existing) = owners.get(parent).or_else(|| owners.get(chat)) {
+        return existing == &owner;
+    }
+    owners.insert(chat.to_owned(), owner);
+    true
+}
+pub fn chat_context(root: &Path, chat: &str) -> JobContext {
+    let chat = normalized_chat(chat);
+    let owners = CHAT_OWNERS.lock().unwrap();
+    let parent = chat.split("::subagent::").next().unwrap_or(chat);
+    let owner = owners
+        .get(parent)
+        .or_else(|| owners.get(chat))
+        .cloned()
+        .flatten();
+    JobContext {
+        workspace: root.to_path_buf(),
+        chat_id: Some(chat.to_owned()),
+        owner,
+    }
+}
+pub fn accessible(job_id: &str, owner: &Option<String>) -> bool {
+    BG_SHELL_JOBS
+        .lock()
+        .unwrap()
+        .get(job_id)
+        .is_some_and(|job| &job.context.owner == owner)
+}
+fn context_for(cwd: &Path) -> JobContext {
+    let mut context = JOB_CONTEXT.with(|c| c.borrow().clone());
+    if context.workspace.as_os_str().is_empty() {
+        context.workspace = cwd.to_path_buf();
+    }
+    context
+}
+fn register(job: Arc<JobRecord>) {
+    let mut jobs = BG_SHELL_JOBS.lock().unwrap();
+    jobs.insert(job.id.clone(), job);
+    let mut finished: Vec<_> = jobs
+        .values()
+        .filter(|j| {
+            !matches!(
+                *j.status.lock().unwrap(),
+                JobStatus::Running | JobStatus::Stopping
+            )
+        })
+        .map(|j| (j.started_at, j.id.clone()))
+        .collect();
+    finished.sort();
+    let remove = finished.len().saturating_sub(100);
+    for (_, id) in finished.into_iter().take(remove) {
+        jobs.remove(&id);
+    }
+}
+/// Immutable metadata and output for clients; never consumes the agent's cursor.
+pub fn job_json(id: &str, include_output: bool) -> Result<serde_json::Value, ShellError> {
+    let job = BG_SHELL_JOBS
+        .lock()
+        .unwrap()
+        .get(id)
+        .cloned()
+        .ok_or_else(|| ShellError::JobNotFound(id.into()))?;
+    let status = job.status.lock().unwrap().clone();
+    let (state, code, error) = match status {
+        JobStatus::Running => ("running", None, None),
+        JobStatus::Stopping => ("stopping", None, None),
+        JobStatus::Exited(0) => ("completed", Some(0), None),
+        JobStatus::Exited(code) => ("failed", Some(code), None),
+        JobStatus::Killed => ("stopped", None, None),
+        JobStatus::Failed(error) => ("failed", None, Some(error)),
+    };
+    let ended = *job.ended_ms.lock().unwrap();
+    let mut value = serde_json::json!({ "id": job.id, "managedService": job.managed_stop.is_some(), "command": job.command, "cwd": job.cwd, "workspacePath": job.context.workspace, "chatId": job.context.chat_id, "pid": job.pid, "status": state, "exitCode": code, "error": error, "startedAt": job.started_ms, "endedAt": ended, "elapsedSeconds": (ended.unwrap_or_else(|| chrono::Utc::now().timestamp_millis()) - job.started_ms).max(0) / 1000, "serverUrl": if state == "running" { job.server_url.lock().unwrap().clone() } else { None } });
+    if include_output {
+        let stdout = job.stdout.lock().unwrap();
+        let stderr = job.stderr.lock().unwrap();
+        value["stdout"] = serde_json::json!(stdout.data);
+        value["stderr"] = serde_json::json!(stderr.data);
+        value["truncated"] = serde_json::json!(stdout.truncated || stderr.truncated);
+    }
+    Ok(value)
+}
+pub fn list_json(owner: &Option<String>, workspace: Option<&Path>) -> Vec<serde_json::Value> {
+    let ids: Vec<_> = BG_SHELL_JOBS
+        .lock()
+        .unwrap()
+        .values()
+        .filter(|j| &j.context.owner == owner && workspace.is_none_or(|w| j.context.workspace == w))
+        .map(|j| j.id.clone())
+        .collect();
+    let mut jobs: Vec<_> = ids
+        .iter()
+        .filter_map(|id| job_json(id, false).ok())
+        .collect();
+    jobs.sort_by_key(|j| {
+        (
+            j["startedAt"].as_i64().unwrap_or(0),
+            j["id"]
+                .as_str()
+                .and_then(|id| id.rsplit('-').next())
+                .and_then(|n| n.parse::<u64>().ok())
+                .unwrap_or(0),
+        )
+    });
+    jobs
+}
+pub fn running_count_for(workspace: &Path) -> usize {
+    BG_SHELL_JOBS
+        .lock()
+        .unwrap()
+        .values()
+        .filter(|j| {
+            j.context.workspace == workspace
+                && matches!(
+                    *j.status.lock().unwrap(),
+                    JobStatus::Running | JobStatus::Stopping
+                )
+        })
+        .count()
+}
+pub fn shutdown() {
+    SHUTTING_DOWN.store(true, std::sync::atomic::Ordering::Release);
+    let ids: Vec<_> = BG_SHELL_JOBS.lock().unwrap().keys().cloned().collect();
+    for id in &ids {
+        let _ = kill_job(id);
+    }
+    let deadline = Instant::now() + Duration::from_secs(3);
+    while running_count() > 0 && Instant::now() < deadline {
+        std::thread::sleep(Duration::from_millis(25));
+    }
 }
 
 /// Plain-text notices ("job X exited with code 0") a UI surface can drain,
@@ -146,7 +338,7 @@ fn push_finished_notice(job: &JobRecord, status: &JobStatus) {
         ),
         // Killed jobs were stopped intentionally (via kill_shell), and
         // Running is not a terminal state — neither needs a surprise notice.
-        JobStatus::Killed | JobStatus::Running => return,
+        JobStatus::Killed | JobStatus::Running | JobStatus::Stopping => return,
     };
     FINISHED_NOTICES.lock().unwrap().push(message);
 }
@@ -156,22 +348,169 @@ enum StreamKind {
     Stderr,
 }
 
-fn spawn_pump(mut pipe: impl Read + Send + 'static, job: Arc<JobRecord>, kind: StreamKind) {
+pub(crate) fn read_stream(mut pipe: impl Read, buffer: &Arc<Mutex<CappedBuf>>) {
+    let mut chunk = [0u8; 4096];
+    let mut pending = Vec::new();
+    loop {
+        match pipe.read(&mut chunk) {
+            Ok(0) | Err(_) => break,
+            Ok(n) => pending.extend_from_slice(&chunk[..n]),
+        }
+        loop {
+            match std::str::from_utf8(&pending) {
+                Ok(text) => {
+                    buffer.lock().unwrap().push(text);
+                    pending.clear();
+                    break;
+                }
+                Err(error) => {
+                    let valid = error.valid_up_to();
+                    buffer
+                        .lock()
+                        .unwrap()
+                        .push(std::str::from_utf8(&pending[..valid]).unwrap());
+                    pending.drain(..valid);
+                    if let Some(invalid) = error.error_len() {
+                        buffer.lock().unwrap().push("�");
+                        pending.drain(..invalid);
+                    } else {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    if !pending.is_empty() {
+        buffer
+            .lock()
+            .unwrap()
+            .push(&String::from_utf8_lossy(&pending));
+    }
+}
+fn spawn_pump(pipe: impl Read + Send + 'static, job: Arc<JobRecord>, kind: StreamKind) {
+    std::thread::spawn(move || {
+        let buffer = match kind {
+            StreamKind::Stdout => &job.stdout,
+            StreamKind::Stderr => &job.stderr,
+        };
+        read_stream(pipe, buffer);
+    });
+}
+
+/// Track a built-in local service using the same lifetime and Stop controls as shell jobs.
+pub(crate) fn start_local_service(
+    root: PathBuf,
+    owner: Option<String>,
+    url: String,
+    run: impl FnOnce(Arc<std::sync::atomic::AtomicBool>) -> Result<(), String> + Send + 'static,
+) -> Result<String, String> {
+    if is_shutting_down() {
+        return Err("Mint backend is shutting down".into());
+    }
+    let stop = Arc::new(std::sync::atomic::AtomicBool::new(false));
+    let job = Arc::new(JobRecord {
+        id: next_job_id(),
+        command: format!("HTML preview server · {}", root.display()),
+        cwd: root.clone(),
+        pid: None,
+        status: Mutex::new(JobStatus::Running),
+        stdout: Arc::new(Mutex::new(CappedBuf::new())),
+        stderr: Arc::new(Mutex::new(CappedBuf::new())),
+        started_at: Instant::now(),
+        started_ms: chrono::Utc::now().timestamp_millis(),
+        ended_ms: Mutex::new(None),
+        context: JobContext {
+            workspace: root,
+            chat_id: None,
+            owner,
+        },
+        server_url: Mutex::new(Some(url.clone())),
+        stop_complete: std::sync::atomic::AtomicBool::new(false),
+        stop_error: Mutex::new(None),
+        managed_stop: Some(Arc::clone(&stop)),
+        owner_stdin: Mutex::new(None),
+    });
+    job.stdout
+        .lock()
+        .unwrap()
+        .push(&format!("Serving HTML preview at {url}\n"));
+    let id = job.id.clone();
+    register(Arc::clone(&job));
+    if is_shutting_down() {
+        stop.store(true, std::sync::atomic::Ordering::Release);
+    }
     std::thread::spawn(move || {
-        let mut chunk = [0u8; 4096];
+        let result =
+            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| run(Arc::clone(&stop))))
+                .unwrap_or_else(|_| Err("HTML preview server panicked".into()));
+        let final_status = if stop.load(std::sync::atomic::Ordering::Acquire) {
+            JobStatus::Killed
+        } else {
+            result.map_or_else(JobStatus::Failed, |_| JobStatus::Exited(0))
+        };
+        *job.status.lock().unwrap() = final_status.clone();
+        *job.ended_ms.lock().unwrap() = Some(chrono::Utc::now().timestamp_millis());
+        job.stop_complete
+            .store(true, std::sync::atomic::Ordering::Release);
+        push_finished_notice(&job, &final_status);
+        register(job);
+    });
+    Ok(id)
+}
+
+/// Start an application-owned program with a lifetime pipe on stdin.
+pub(crate) fn start_owned_background(
+    cwd: &Path,
+    config: &MintConfig,
+    command: &str,
+    mut program: Command,
+) -> Result<StartedJob, ShellError> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        program.process_group(0);
+    }
+    program.env("MINT_WEB_LIFETIME_PIPE", "1");
+    spawn_tracked(cwd, config, command, program, true)
+}
+
+/// Launch Mint's known frontend scripts as tracked children of the web backend.
+pub fn start_web_frontend(
+    cwd: &Path,
+    config: &MintConfig,
+    script: &str,
+) -> Result<StartedJob, ShellError> {
+    if !matches!(script, "dev:web" | "preview:web") {
+        return Err(ShellError::Execute(std::io::Error::other(
+            "Unknown Mint Web frontend script",
+        )));
+    }
+    let mut program = Command::new(if cfg!(windows) { "npm.cmd" } else { "npm" });
+    program.args(["run", script]);
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        program.process_group(0);
+    }
+    spawn_tracked(cwd, config, &format!("npm run {script}"), program, false)
+}
+
+/// Called by the owned Mint Web child. EOF also covers abrupt owner termination.
+pub fn watch_web_owner() {
+    if std::env::var_os("MINT_WEB_LIFETIME_PIPE").is_none() {
+        return;
+    }
+    std::thread::spawn(|| {
+        let mut byte = [0u8; 1];
+        let mut stdin = std::io::stdin().lock();
         loop {
-            match pipe.read(&mut chunk) {
+            match stdin.read(&mut byte) {
                 Ok(0) | Err(_) => break,
-                Ok(n) => {
-                    let text = String::from_utf8_lossy(&chunk[..n]);
-                    let mut buf = match kind {
-                        StreamKind::Stdout => job.stdout.lock().unwrap(),
-                        StreamKind::Stderr => job.stderr.lock().unwrap(),
-                    };
-                    buf.push(&text);
-                }
+                Ok(_) => {}
             }
         }
+        shutdown();
+        std::process::exit(0);
     });
 }
 
@@ -185,6 +524,11 @@ pub fn start_background(
     config: &MintConfig,
     command: &str,
 ) -> Result<StartedJob, ShellError> {
+    if is_shutting_down() {
+        return Err(ShellError::Execute(std::io::Error::other(
+            "Mint backend is shutting down",
+        )));
+    }
     let classification = classify_shell_command(command);
     if classification.tier == SafetyTier::Blocked {
         return Err(ShellError::Blocked {
@@ -199,19 +543,39 @@ pub fn start_background(
         });
     }
 
+    spawn_tracked(
+        cwd,
+        config,
+        command,
+        crate::shell::shell_command(command),
+        false,
+    )
+}
+
+fn spawn_tracked(
+    cwd: &Path,
+    config: &MintConfig,
+    command: &str,
+    mut cmd: Command,
+    owned: bool,
+) -> Result<StartedJob, ShellError> {
+    if is_shutting_down() {
+        return Err(ShellError::Execute(std::io::Error::other(
+            "Mint backend is shutting down",
+        )));
+    }
     let cwd = assert_path_capability(cwd, Capability::Write, config)?;
     if !cwd.is_dir() {
         return Err(ShellError::InvalidWorkingDirectory(cwd));
     }
-
-    let mut cmd = crate::shell::shell_command(command);
     cmd.current_dir(&cwd)
-        .stdin(Stdio::null())
+        .stdin(if owned { Stdio::piped() } else { Stdio::null() })
         .stdout(Stdio::piped())
         .stderr(Stdio::piped());
 
     let mut child = cmd.spawn()?;
     let pid = child.id();
+    let owner_stdin = child.stdin.take();
     let stdout = child.stdout.take().expect("stdout was piped");
     let stderr = child.stderr.take().expect("stderr was piped");
 
@@ -221,9 +585,17 @@ pub fn start_background(
         cwd: cwd.clone(),
         pid: Some(pid),
         status: Mutex::new(JobStatus::Running),
-        stdout: Mutex::new(CappedBuf::new()),
-        stderr: Mutex::new(CappedBuf::new()),
+        stdout: Arc::new(Mutex::new(CappedBuf::new())),
+        stderr: Arc::new(Mutex::new(CappedBuf::new())),
         started_at: Instant::now(),
+        started_ms: chrono::Utc::now().timestamp_millis(),
+        ended_ms: Mutex::new(None),
+        context: context_for(&cwd),
+        server_url: Mutex::new(None),
+        stop_complete: std::sync::atomic::AtomicBool::new(false),
+        stop_error: Mutex::new(None),
+        managed_stop: None,
+        owner_stdin: Mutex::new(owner_stdin),
     });
 
     spawn_pump(stdout, Arc::clone(&job), StreamKind::Stdout);
@@ -242,25 +614,37 @@ pub fn start_background(
                 // Always wait, even if `kill_job` already marked this Killed —
                 // otherwise the child becomes a zombie.
                 let exit_status = child.wait();
+                wait_stop_completion(&job_for_wait);
                 let mut status = job_for_wait.status.lock().unwrap();
-                let was_running = matches!(*status, JobStatus::Running);
+                let was_running = matches!(*status, JobStatus::Running | JobStatus::Stopping);
+                let stopping = matches!(*status, JobStatus::Stopping);
                 if was_running {
                     *status = match exit_status {
+                        Ok(_) if stopping => job_for_wait
+                            .stop_error
+                            .lock()
+                            .unwrap()
+                            .clone()
+                            .map_or(JobStatus::Killed, JobStatus::Failed),
                         Ok(code) => JobStatus::Exited(code.code().unwrap_or(-1)),
                         Err(e) => JobStatus::Failed(e.to_string()),
                     };
                 }
+                *job_for_wait.ended_ms.lock().unwrap() =
+                    Some(chrono::Utc::now().timestamp_millis());
                 let final_status = status.clone();
                 drop(status);
                 if was_running {
                     push_finished_notice(&job_for_wait, &final_status);
+                    register(Arc::clone(&job_for_wait));
                 }
             }));
             if let Err(payload) = result {
                 let message = crate::channels::panic_payload_message(&payload);
                 eprintln!("[mint] bg_shell job reaper thread panicked: {message}");
                 let mut status = job.status.lock().unwrap();
-                if matches!(*status, JobStatus::Running) {
+                if matches!(*status, JobStatus::Running | JobStatus::Stopping) {
+                    *job.ended_ms.lock().unwrap() = Some(chrono::Utc::now().timestamp_millis());
                     *status = JobStatus::Failed(format!("reaper thread panicked: {message}"));
                 }
             }
@@ -272,10 +656,11 @@ pub fn start_background(
         pid: job.pid,
         cwd,
     };
-    BG_SHELL_JOBS
-        .lock()
-        .unwrap()
-        .insert(started.id.clone(), job);
+    spawn_readiness(Arc::clone(&job));
+    register(job);
+    if is_shutting_down() {
+        let _ = kill_job(&started.id);
+    }
     Ok(started)
 }
 
@@ -289,12 +674,14 @@ pub fn start_background(
 /// via `start_background`, there is no live streaming during this handoff.
 /// The job is registered as `Running` immediately regardless, so it's never
 /// invisible to `/shells` or the status bar even before that happens.
-pub fn promote_timed_out(
+pub(crate) fn promote_timed_out(
     command: &str,
     cwd: PathBuf,
     mut child: Child,
     stdout_handle: std::thread::JoinHandle<Vec<u8>>,
     stderr_handle: std::thread::JoinHandle<Vec<u8>>,
+    stdout_buffer: Arc<Mutex<CappedBuf>>,
+    stderr_buffer: Arc<Mutex<CappedBuf>>,
 ) -> StartedJob {
     let pid = child.id();
     let job = Arc::new(JobRecord {
@@ -303,9 +690,17 @@ pub fn promote_timed_out(
         cwd: cwd.clone(),
         pid: Some(pid),
         status: Mutex::new(JobStatus::Running),
-        stdout: Mutex::new(CappedBuf::new()),
-        stderr: Mutex::new(CappedBuf::new()),
+        stdout: stdout_buffer,
+        stderr: stderr_buffer,
         started_at: Instant::now(),
+        started_ms: chrono::Utc::now().timestamp_millis(),
+        ended_ms: Mutex::new(None),
+        context: context_for(&cwd),
+        server_url: Mutex::new(None),
+        stop_complete: std::sync::atomic::AtomicBool::new(false),
+        stop_error: Mutex::new(None),
+        managed_stop: None,
+        owner_stdin: Mutex::new(None),
     });
 
     {
@@ -316,41 +711,42 @@ pub fn promote_timed_out(
             // panic here marks the job Failed instead of leaving it stuck as
             // `Running` forever with a zombie child left un-`wait()`-ed.
             let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(move || {
-                let stdout = stdout_handle.join().unwrap_or_default();
-                let stderr = stderr_handle.join().unwrap_or_default();
-                job_for_wait
-                    .stdout
-                    .lock()
-                    .unwrap()
-                    .push(&String::from_utf8_lossy(&stdout));
-                job_for_wait
-                    .stderr
-                    .lock()
-                    .unwrap()
-                    .push(&String::from_utf8_lossy(&stderr));
-
                 // Always wait, even if `kill_job` already marked this Killed —
                 // otherwise the child becomes a zombie.
                 let exit_status = child.wait();
+                wait_stop_completion(&job_for_wait);
+                let _ = stdout_handle.join();
+                let _ = stderr_handle.join();
                 let mut status = job_for_wait.status.lock().unwrap();
-                let was_running = matches!(*status, JobStatus::Running);
+                let was_running = matches!(*status, JobStatus::Running | JobStatus::Stopping);
+                let stopping = matches!(*status, JobStatus::Stopping);
                 if was_running {
                     *status = match exit_status {
+                        Ok(_) if stopping => job_for_wait
+                            .stop_error
+                            .lock()
+                            .unwrap()
+                            .clone()
+                            .map_or(JobStatus::Killed, JobStatus::Failed),
                         Ok(code) => JobStatus::Exited(code.code().unwrap_or(-1)),
                         Err(e) => JobStatus::Failed(e.to_string()),
                     };
                 }
+                *job_for_wait.ended_ms.lock().unwrap() =
+                    Some(chrono::Utc::now().timestamp_millis());
                 let final_status = status.clone();
                 drop(status);
                 if was_running {
                     push_finished_notice(&job_for_wait, &final_status);
+                    register(Arc::clone(&job_for_wait));
                 }
             }));
             if let Err(payload) = result {
                 let message = crate::channels::panic_payload_message(&payload);
                 eprintln!("[mint] bg_shell job reaper thread panicked: {message}");
                 let mut status = job.status.lock().unwrap();
-                if matches!(*status, JobStatus::Running) {
+                if matches!(*status, JobStatus::Running | JobStatus::Stopping) {
+                    *job.ended_ms.lock().unwrap() = Some(chrono::Utc::now().timestamp_millis());
                     *status = JobStatus::Failed(format!("reaper thread panicked: {message}"));
                 }
             }
@@ -362,10 +758,11 @@ pub fn promote_timed_out(
         pid: job.pid,
         cwd,
     };
-    BG_SHELL_JOBS
-        .lock()
-        .unwrap()
-        .insert(started.id.clone(), job);
+    spawn_readiness(Arc::clone(&job));
+    register(job);
+    if is_shutting_down() {
+        let _ = kill_job(&started.id);
+    }
     started
 }
 
@@ -389,6 +786,10 @@ pub fn poll_output(job_id: &str) -> Result<String, ShellError> {
     };
 
     Ok(match status {
+        JobStatus::Stopping => format!(
+            "job_id: {}\nstatus: stopping\nstdout (new):\n{}\nstderr (new):\n{}{}",
+            job.id, stdout_new, stderr_new, truncated_note
+        ),
         JobStatus::Running => format!(
             "job_id: {}\nstatus: running (elapsed {}s)\ncwd: {}\nstdout (new):\n{}\nstderr (new):\n{}{}",
             job.id,
@@ -420,15 +821,38 @@ pub fn list_jobs() -> Vec<JobSummary> {
         .lock()
         .unwrap()
         .values()
-        .map(|job| JobSummary {
-            id: job.id.clone(),
-            command: job.command.clone(),
-            status: job.status.lock().unwrap().clone(),
-            pid: job.pid,
-            elapsed_secs: job.started_at.elapsed().as_secs(),
+        .map(|job| {
+            let status = job.status.lock().unwrap().clone();
+            JobSummary {
+                id: job.id.clone(),
+                command: job.command.clone(),
+                status: status.clone(),
+                pid: job.pid,
+                elapsed_secs: (job
+                    .ended_ms
+                    .lock()
+                    .unwrap()
+                    .unwrap_or_else(|| chrono::Utc::now().timestamp_millis())
+                    - job.started_ms)
+                    .max(0) as u64
+                    / 1000,
+                cwd: job.cwd.clone(),
+                workspace: job.context.workspace.clone(),
+                server_url: if matches!(status, JobStatus::Running) {
+                    job.server_url.lock().unwrap().clone()
+                } else {
+                    None
+                },
+            }
         })
         .collect();
-    jobs.sort_by(|a, b| a.id.cmp(&b.id));
+    jobs.sort_by_key(|job| {
+        job.id
+            .rsplit('-')
+            .next()
+            .and_then(|n| n.parse::<u64>().ok())
+            .unwrap_or(0)
+    });
     jobs
 }
 
@@ -439,7 +863,12 @@ pub fn running_count() -> usize {
         .lock()
         .unwrap()
         .values()
-        .filter(|job| matches!(*job.status.lock().unwrap(), JobStatus::Running))
+        .filter(|job| {
+            matches!(
+                *job.status.lock().unwrap(),
+                JobStatus::Running | JobStatus::Stopping
+            )
+        })
         .count()
 }
 
@@ -454,35 +883,200 @@ pub fn snapshot(job_id: &str) -> Result<JobSnapshot, ShellError> {
         .cloned()
         .ok_or_else(|| ShellError::JobNotFound(job_id.to_owned()))?;
 
+    let status = job.status.lock().unwrap().clone();
+    let stdout = job.stdout.lock().unwrap();
+    let stderr = job.stderr.lock().unwrap();
     Ok(JobSnapshot {
         id: job.id.clone(),
         command: job.command.clone(),
         cwd: job.cwd.clone(),
-        status: job.status.lock().unwrap().clone(),
+        status: status.clone(),
         pid: job.pid,
-        stdout: job.stdout.lock().unwrap().data.clone(),
-        stderr: job.stderr.lock().unwrap().data.clone(),
+        stdout: stdout.data.clone(),
+        stderr: stderr.data.clone(),
+        truncated: stdout.truncated || stderr.truncated,
+        elapsed_secs: (job
+            .ended_ms
+            .lock()
+            .unwrap()
+            .unwrap_or_else(|| chrono::Utc::now().timestamp_millis())
+            - job.started_ms)
+            .max(0) as u64
+            / 1000,
+        server_url: if matches!(status, JobStatus::Running) {
+            job.server_url.lock().unwrap().clone()
+        } else {
+            None
+        },
     })
 }
 
-#[cfg(not(target_os = "windows"))]
-pub(crate) fn terminate_process_group(pid: u32) {
-    let _ = Command::new("kill")
-        .args(["-TERM", &format!("-{pid}")])
-        .status();
+/// Verify a listening socket belongs to the tracked process group before probing it.
+#[cfg(target_os = "linux")]
+fn owns_port(pid: u32, port: u16) -> bool {
+    let mut sockets = std::collections::HashSet::new();
+    for table in ["/proc/net/tcp", "/proc/net/tcp6"] {
+        for line in std::fs::read_to_string(table)
+            .unwrap_or_default()
+            .lines()
+            .skip(1)
+        {
+            let fields: Vec<_> = line.split_whitespace().collect();
+            if fields.len() > 9
+                && fields[3] == "0A"
+                && fields[1]
+                    .rsplit(':')
+                    .next()
+                    .is_some_and(|p| u16::from_str_radix(p, 16).ok() == Some(port))
+            {
+                sockets.insert(format!("socket:[{}]", fields[9]));
+            }
+        }
+    }
+    if sockets.is_empty() {
+        return false;
+    }
+    for entry in std::fs::read_dir("/proc").into_iter().flatten().flatten() {
+        if entry.file_name().to_string_lossy().parse::<u32>().is_err() {
+            continue;
+        }
+        let stat = std::fs::read_to_string(entry.path().join("stat")).unwrap_or_default();
+        // After the parenthesized command: state, parent pid, process group.
+        if !stat.rsplit_once(')').is_some_and(|(_, rest)| {
+            rest.split_whitespace()
+                .nth(2)
+                .and_then(|g| g.parse::<u32>().ok())
+                == Some(pid)
+        }) {
+            continue;
+        }
+        for fd in std::fs::read_dir(entry.path().join("fd"))
+            .into_iter()
+            .flatten()
+            .flatten()
+        {
+            if std::fs::read_link(fd.path())
+                .ok()
+                .is_some_and(|target| sockets.contains(target.to_string_lossy().as_ref()))
+            {
+                return true;
+            }
+        }
+    }
+    false
+}
+#[cfg(target_os = "macos")]
+fn owns_port(pid: u32, port: u16) -> bool {
+    Command::new("lsof")
+        .args([
+            "-a",
+            "-g",
+            &pid.to_string(),
+            &format!("-iTCP:{port}"),
+            "-sTCP:LISTEN",
+            "-t",
+        ])
+        .output()
+        .is_ok_and(|r| r.status.success() && !r.stdout.is_empty())
+}
+#[cfg(target_os = "windows")]
+fn owns_port(pid: u32, port: u16) -> bool {
+    let script = format!(
+        "$ids=@({pid}); $processes=Get-CimInstance Win32_Process; do {{ $previous=$ids.Count; $ids+=@($processes | Where-Object {{ $ids -contains $_.ParentProcessId -and $ids -notcontains $_.ProcessId }} | ForEach-Object {{ $_.ProcessId }}); }} while ($ids.Count -gt $previous); if (Get-NetTCPConnection -LocalPort {port} -State Listen -ErrorAction SilentlyContinue | Where-Object {{ $ids -contains $_.OwningProcess }}) {{ 'owned' }}"
+    );
+    Command::new("powershell")
+        .args(["-NoProfile", "-NonInteractive", "-Command", &script])
+        .output()
+        .is_ok_and(|r| r.status.success() && String::from_utf8_lossy(&r.stdout).contains("owned"))
+}
+#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+fn owns_port(_pid: u32, _port: u16) -> bool {
+    false
+}
+
+static HTTP_URL_PATTERN: LazyLock<regex::Regex> = LazyLock::new(|| {
+    regex::Regex::new(r"http://(?:localhost|127\.0\.0\.1|0\.0\.0\.0):([0-9]{1,5})").unwrap()
+});
+static PYTHON_SERVER_PATTERN: LazyLock<regex::Regex> =
+    LazyLock::new(|| regex::Regex::new(r"-m\s+http\.server(?:\s+(\d+))?").unwrap());
+static SERVING_PATTERN: LazyLock<regex::Regex> =
+    LazyLock::new(|| regex::Regex::new(r"Serving HTTP on .* port (\d+)").unwrap());
+
+fn spawn_readiness(job: Arc<JobRecord>) {
     std::thread::spawn(move || {
-        std::thread::sleep(Duration::from_millis(500));
-        let _ = Command::new("kill")
-            .args(["-KILL", &format!("-{pid}")])
-            .status();
+        let command_port = PYTHON_SERVER_PATTERN.captures(&job.command).and_then(|c| {
+            c.get(1)
+                .map_or(Some(8000), |p| p.as_str().parse::<u16>().ok())
+        });
+        loop {
+            std::thread::sleep(Duration::from_secs(1));
+            if !matches!(*job.status.lock().unwrap(), JobStatus::Running) {
+                return;
+            }
+            let text = format!(
+                "{}\n{}",
+                job.stdout.lock().unwrap().data,
+                job.stderr.lock().unwrap().data
+            );
+            let port = HTTP_URL_PATTERN
+                .captures(&text)
+                .and_then(|c| c[1].parse::<u16>().ok())
+                .or_else(|| {
+                    SERVING_PATTERN
+                        .captures(&text)
+                        .and_then(|c| c[1].parse::<u16>().ok())
+                })
+                .or(command_port);
+            let Some(port) = port.filter(|p| *p > 0) else {
+                continue;
+            };
+            let owned = job.pid.is_some_and(|pid| owns_port(pid, port));
+            let mut verified = false;
+            if owned {
+                let addr = std::net::SocketAddr::from(([127, 0, 0, 1], port));
+                if let Ok(mut stream) =
+                    std::net::TcpStream::connect_timeout(&addr, Duration::from_millis(300))
+                {
+                    let _ = stream.set_read_timeout(Some(Duration::from_millis(300)));
+                    let _ = stream.set_write_timeout(Some(Duration::from_millis(300)));
+                    if stream
+                        .write_all(b"HEAD / HTTP/1.0\r\nHost: localhost\r\n\r\n")
+                        .is_ok()
+                    {
+                        let mut response = [0; 128];
+                        verified = stream
+                            .read(&mut response)
+                            .is_ok_and(|n| response[..n].starts_with(b"HTTP/"));
+                    }
+                }
+            }
+            *job.server_url.lock().unwrap() = verified.then(|| format!("http://127.0.0.1:{port}"));
+        }
     });
 }
 
-#[cfg(target_os = "windows")]
-pub(crate) fn terminate_process_group(pid: u32) {
-    let _ = Command::new("taskkill")
-        .args(["/F", "/T", "/PID", &pid.to_string()])
-        .status();
+fn wait_stop_completion(job: &JobRecord) {
+    if matches!(*job.status.lock().unwrap(), JobStatus::Stopping) {
+        while !job.stop_complete.load(std::sync::atomic::Ordering::Acquire) {
+            std::thread::sleep(Duration::from_millis(10));
+        }
+    }
+}
+
+/// Remove a finished job and its buffered output from the registry.
+pub fn remove_job(job_id: &str) -> Result<(), ShellError> {
+    let mut jobs = BG_SHELL_JOBS.lock().unwrap();
+    let job = jobs
+        .get(job_id)
+        .ok_or_else(|| ShellError::JobNotFound(job_id.to_owned()))?;
+    if matches!(
+        *job.status.lock().unwrap(),
+        JobStatus::Running | JobStatus::Stopping
+    ) {
+        return Err(ShellError::JobStillRunning(job_id.to_owned()));
+    }
+    jobs.remove(job_id);
+    Ok(())
 }
 
 /// Sends a termination signal to a running job's whole process group
@@ -498,28 +1092,84 @@ pub fn kill_job(job_id: &str) -> Result<String, ShellError> {
         .cloned()
         .ok_or_else(|| ShellError::JobNotFound(job_id.to_owned()))?;
 
-    let current = job.status.lock().unwrap().clone();
-    if !matches!(current, JobStatus::Running) {
+    let mut status = job.status.lock().unwrap();
+    if !matches!(*status, JobStatus::Running) {
         return Ok(format!(
-            "job_id: {} is already {:?}, nothing to kill",
-            job.id, current
+            "job_id: {} is already {:?}, nothing to stop",
+            job.id, *status
         ));
     }
-
+    if let Some(stop) = &job.managed_stop {
+        *status = JobStatus::Stopping;
+        stop.store(true, std::sync::atomic::Ordering::Release);
+        return Ok(format!("job_id: {job_id} stop requested"));
+    }
     let Some(pid) = job.pid else {
-        return Ok(format!("job_id: {} has no known pid to kill", job.id));
+        return Err(ShellError::JobNotFound(job_id.into()));
     };
-
-    terminate_process_group(pid);
-
-    {
-        let mut status = job.status.lock().unwrap();
-        if matches!(*status, JobStatus::Running) {
-            *status = JobStatus::Killed;
-        }
+    // Closing the lifetime pipe lets owned Mint Web shut down its own tracked
+    // frontend before it exits. Keep forceful group cleanup as a fallback.
+    if job.owner_stdin.lock().unwrap().take().is_some() {
+        *status = JobStatus::Stopping;
+        drop(status);
+        job.stop_complete
+            .store(true, std::sync::atomic::Ordering::Release);
+        std::thread::spawn(move || {
+            std::thread::sleep(Duration::from_secs(2));
+            if !matches!(*job.status.lock().unwrap(), JobStatus::Stopping) {
+                return;
+            }
+            #[cfg(not(target_os = "windows"))]
+            let _ = Command::new("kill")
+                .args(["-KILL", "--", &format!("-{pid}")])
+                .output();
+            #[cfg(target_os = "windows")]
+            let _ = Command::new("taskkill")
+                .args(["/T", "/F", "/PID", &pid.to_string()])
+                .output();
+        });
+        return Ok(format!("job_id: {job_id} stop requested (pid {pid})"));
     }
-
-    Ok(format!("job_id: {} kill signal sent (pid {pid})", job.id))
+    #[cfg(not(target_os = "windows"))]
+    let result = Command::new("kill")
+        .args(["-TERM", "--", &format!("-{pid}")])
+        .output();
+    #[cfg(target_os = "windows")]
+    let result = Command::new("taskkill")
+        .args(["/T", "/F", "/PID", &pid.to_string()])
+        .output();
+    let result = result?;
+    if !result.status.success() {
+        return Err(ShellError::Execute(std::io::Error::other(
+            String::from_utf8_lossy(&result.stderr).to_string(),
+        )));
+    }
+    *status = JobStatus::Stopping;
+    drop(status);
+    #[cfg(target_os = "windows")]
+    job.stop_complete
+        .store(true, std::sync::atomic::Ordering::Release);
+    #[cfg(not(target_os = "windows"))]
+    std::thread::spawn(move || {
+        std::thread::sleep(Duration::from_millis(500));
+        // The shell may already have exited while a child ignores TERM.
+        // Escalate the original process group before the reaper reports Stopped.
+        let result = Command::new("kill")
+            .args(["-KILL", "--", &format!("-{pid}")])
+            .output();
+        if result.as_ref().map_or(true, |r| !r.status.success())
+            && Command::new("kill")
+                .args(["-0", "--", &format!("-{pid}")])
+                .output()
+                .is_ok_and(|r| r.status.success())
+        {
+            *job.stop_error.lock().unwrap() =
+                Some("Unable to terminate the background process group".into());
+        }
+        job.stop_complete
+            .store(true, std::sync::atomic::Ordering::Release);
+    });
+    Ok(format!("job_id: {job_id} stop requested (pid {pid})"))
 }
 
 #[cfg(test)]
@@ -549,6 +1199,123 @@ mod tests {
         }
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn owned_background_keeps_stdin_open_and_stop_kills_the_program() {
+        let mut program = Command::new("bash");
+        program.args(["-c", "echo ready; cat; echo eof"]);
+        let job = start_owned_background(Path::new("."), &local_config(), "owned fixture", program)
+            .unwrap();
+        let _cleanup = StopOnDrop(job.id.clone());
+        let ready = wait_json(&job.id, |v| {
+            v["stdout"].as_str().is_some_and(|s| s.contains("ready"))
+        });
+        assert_eq!(ready["status"], "running");
+        assert!(!ready["stdout"].as_str().unwrap().contains("eof"));
+        kill_job(&job.id).unwrap();
+        let stopped = wait_json(&job.id, |v| v["status"] == "stopped");
+        assert!(stopped["stdout"].as_str().unwrap().contains("eof"));
+    }
+
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn owned_web_stops_frontend_when_owner_is_killed() {
+        const TEST: &str = "system::bg_shell::tests::owned_web_stops_frontend_when_owner_is_killed";
+        let fixture = |role: &str| {
+            let mut p = Command::new(std::env::current_exe().unwrap());
+            p.args(["--exact", TEST, "--nocapture"])
+                .env("MINT_WEB_FIXTURE_ROLE", role);
+            p
+        };
+        match std::env::var("MINT_WEB_FIXTURE_ROLE").as_deref() {
+            Ok("web") => {
+                let frontend =
+                    start_background(Path::new("."), &local_config(), "sleep 30").unwrap();
+                println!("frontend:{}", frontend.pid.unwrap());
+                std::io::stdout().flush().unwrap();
+                watch_web_owner();
+                loop {
+                    std::thread::sleep(Duration::from_millis(100));
+                }
+            }
+            Ok("owner") => {
+                let web = start_owned_background(
+                    Path::new("."),
+                    &local_config(),
+                    "web fixture",
+                    fixture("web"),
+                )
+                .unwrap();
+                println!("web:{}", web.pid.unwrap());
+                let ready = wait_json(&web.id, |v| {
+                    v["stdout"]
+                        .as_str()
+                        .is_some_and(|s| s.contains("frontend:"))
+                });
+                println!("{}", ready["stdout"].as_str().unwrap());
+                std::io::stdout().flush().unwrap();
+                loop {
+                    std::thread::sleep(Duration::from_millis(100));
+                }
+            }
+            _ => {}
+        }
+        struct Cleanup {
+            owner: Child,
+            groups: Vec<u32>,
+        }
+        impl Drop for Cleanup {
+            fn drop(&mut self) {
+                let _ = self.owner.kill();
+                let _ = self.owner.wait();
+                for pid in &self.groups {
+                    let _ = Command::new("kill")
+                        .args(["-KILL", "--", &format!("-{pid}")])
+                        .output();
+                }
+            }
+        }
+        use std::io::{BufRead, BufReader};
+        let mut owner = fixture("owner").stdout(Stdio::piped()).spawn().unwrap();
+        let stdout = owner.stdout.take().unwrap();
+        let mut cleanup = Cleanup {
+            owner,
+            groups: vec![],
+        };
+        for line in BufReader::new(stdout).lines() {
+            let line = line.unwrap();
+            if let Some(pid) = line
+                .strip_prefix("web:")
+                .or_else(|| line.strip_prefix("frontend:"))
+            {
+                cleanup.groups.push(pid.parse().unwrap());
+                if cleanup.groups.len() == 2 {
+                    break;
+                }
+            }
+        }
+        assert_eq!(cleanup.groups.len(), 2);
+        cleanup.owner.kill().unwrap();
+        cleanup.owner.wait().unwrap();
+        let deadline = Instant::now() + Duration::from_secs(5);
+        for pid in &cleanup.groups {
+            loop {
+                let live = std::fs::read_to_string(format!("/proc/{pid}/stat")).is_ok_and(|stat| {
+                    stat.rsplit_once(')')
+                        .is_some_and(|(_, rest)| !rest.trim_start().starts_with('Z'))
+                });
+                if !live {
+                    break;
+                }
+                assert!(
+                    Instant::now() < deadline,
+                    "owned process {pid} survived its owner"
+                );
+                std::thread::sleep(Duration::from_millis(20));
+            }
+        }
+    }
+
     #[test]
     fn background_job_reports_running_then_exit() {
         let config = local_config();
@@ -568,7 +1335,7 @@ mod tests {
         let started = start_background(Path::new("."), &config, "sleep 30").unwrap();
 
         let result = kill_job(&started.id).unwrap();
-        assert!(result.contains("kill signal sent"));
+        assert!(result.contains("stop requested"));
 
         let after = poll_until(&started.id, Duration::from_secs(10), |out| {
             out.contains("status: killed") || out.contains("status: exited")
@@ -576,6 +1343,243 @@ mod tests {
         assert!(after.contains("status: killed") || after.contains("status: exited"));
     }
 
+    struct TestDir(PathBuf);
+    impl TestDir {
+        fn new() -> Self {
+            let path = std::env::temp_dir().join(format!("mint-bg-test-{}", uuid::Uuid::new_v4()));
+            std::fs::create_dir(&path).unwrap();
+            Self(path)
+        }
+        fn path(&self) -> &Path {
+            &self.0
+        }
+    }
+    impl Drop for TestDir {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.0);
+        }
+    }
+    struct StopOnDrop(String);
+    impl Drop for StopOnDrop {
+        fn drop(&mut self) {
+            let _ = kill_job(&self.0);
+        }
+    }
+    fn wait_json(id: &str, predicate: impl Fn(&serde_json::Value) -> bool) -> serde_json::Value {
+        let deadline = Instant::now() + Duration::from_secs(8);
+        loop {
+            let value = job_json(id, true).unwrap();
+            if predicate(&value) {
+                return value;
+            }
+            assert!(
+                Instant::now() < deadline,
+                "job did not reach expected state: {value}"
+            );
+            std::thread::sleep(Duration::from_millis(25));
+        }
+    }
+    #[test]
+    fn normalized_and_subagent_chats_keep_parent_ownership() {
+        let chat = uuid::Uuid::new_v4().to_string();
+        let owner = Some("parent-owner".to_owned());
+        assert!(bind_chat_owner(&format!("  {chat}  "), owner.clone()));
+        let child = format!("{chat}::subagent::helper");
+        assert_eq!(chat_context(Path::new("."), &child).owner, owner);
+        assert!(!bind_chat_owner(&child, Some("other-owner".into())));
+        assert_eq!(
+            chat_context(Path::new("."), &format!(" {chat} ")).chat_id,
+            Some(chat)
+        );
+    }
+
+    #[test]
+    fn counts_and_context_are_workspace_and_owner_scoped() {
+        let root = TestDir::new();
+        let other = TestDir::new();
+        let chat = uuid::Uuid::new_v4().to_string();
+        assert!(bind_chat_owner(&chat, Some("owner-test".into())));
+        assert!(!bind_chat_owner(&chat, Some("different-owner".into())));
+        let start = Instant::now();
+        let job = with_context(chat_context(root.path(), &chat), || {
+            start_background(other.path(), &local_config(), "sleep 30")
+        })
+        .unwrap();
+        let _cleanup = StopOnDrop(job.id.clone());
+        assert!(start.elapsed() < Duration::from_secs(2));
+        assert_eq!(running_count_for(root.path()), 1);
+        assert_eq!(running_count_for(other.path()), 0);
+        assert!(accessible(&job.id, &Some("owner-test".into())));
+        assert!(!accessible(&job.id, &None));
+        assert_eq!(
+            list_json(&Some("owner-test".into()), Some(root.path())).len(),
+            1
+        );
+        let info = job_json(&job.id, false).unwrap();
+        assert_eq!(info["cwd"], other.path().to_string_lossy().as_ref());
+        assert_eq!(info["chatId"], chat);
+        assert_eq!(info["id"].as_str().unwrap().split('-').count(), 3);
+        kill_job(&job.id).unwrap();
+        kill_job(&job.id).unwrap();
+        let value = wait_json(&job.id, |v| v["status"] == "stopped");
+        assert!(value["endedAt"].is_i64());
+        assert_eq!(running_count_for(root.path()), 0);
+    }
+    #[test]
+    fn snapshots_never_consume_incremental_output_and_exit_codes_are_retained() {
+        let job = start_background(
+            Path::new("."),
+            &local_config(),
+            "printf hello; printf problem >&2; exit 7",
+        )
+        .unwrap();
+        let value = wait_json(&job.id, |v| {
+            v["status"] == "failed" && v["stdout"] == "hello" && v["stderr"] == "problem"
+        });
+        assert_eq!(value["exitCode"], 7);
+        assert_eq!(snapshot(&job.id).unwrap().stdout, "hello");
+        assert!(poll_output(&job.id).unwrap().contains("hello"));
+        assert!(!poll_output(&job.id).unwrap().contains("hello"));
+        assert_eq!(job_json(&job.id, true).unwrap()["stdout"], "hello");
+    }
+    #[test]
+    fn capped_output_preserves_utf8_and_reports_truncation() {
+        let mut buffer = CappedBuf::new();
+        buffer.push(&"ก".repeat(MAX_BUF_BYTES));
+        assert!(buffer.data.len() <= MAX_BUF_BYTES);
+        assert!(buffer.truncated);
+        assert!(buffer.drain_new().1);
+    }
+    #[test]
+    fn promoted_output_streams_before_exit_and_retains_context() {
+        let root = TestDir::new();
+        let command = "printf promoted-ready; sleep 30";
+        let context = JobContext {
+            workspace: root.path().into(),
+            chat_id: Some("promoted-test".into()),
+            owner: Some("promotion-owner".into()),
+        };
+        let result = with_context(context, || {
+            crate::shell::run_with_timeout(
+                crate::shell::shell_command(command),
+                Duration::from_millis(100),
+                command,
+                root.path(),
+            )
+        })
+        .unwrap();
+        assert!(result.status_code.is_none());
+        let job = list_json(&Some("promotion-owner".into()), Some(root.path()))
+            .pop()
+            .unwrap();
+        let id = job["id"].as_str().unwrap();
+        let _cleanup = StopOnDrop(id.to_string());
+        let value = wait_json(id, |v| v["stdout"] == "promoted-ready");
+        assert_eq!(value["status"], "running");
+    }
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn stop_terminates_children_in_the_job_group() {
+        let job = start_background(
+            Path::new("."),
+            &local_config(),
+            "sh -c 'trap \"\" TERM; echo $$; sleep 30' & wait",
+        )
+        .unwrap();
+        let _cleanup = StopOnDrop(job.id.clone());
+        let value = wait_json(&job.id, |v| {
+            v["stdout"].as_str().is_some_and(|s| !s.trim().is_empty())
+        });
+        let pid: u32 = value["stdout"].as_str().unwrap().trim().parse().unwrap();
+        kill_job(&job.id).unwrap();
+        wait_json(&job.id, |v| v["status"] == "stopped");
+        let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).unwrap_or_default();
+        assert!(
+            stat.is_empty()
+                || stat
+                    .rsplit_once(')')
+                    .unwrap()
+                    .1
+                    .trim_start()
+                    .starts_with('Z')
+        );
+    }
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn local_server_readiness_is_verified_and_occupied_ports_are_rejected() {
+        if !crate::config::which("python3") {
+            return;
+        }
+        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+        let port = listener.local_addr().unwrap().port();
+        let job = start_background(
+            Path::new("."),
+            &local_config(),
+            &format!("python3 -u -m http.server {port} --bind 127.0.0.1"),
+        )
+        .unwrap();
+        let failed = wait_json(&job.id, |v| v["status"] == "failed");
+        assert!(failed["serverUrl"].is_null());
+        drop(listener);
+        let job = start_background(
+            Path::new("."),
+            &local_config(),
+            &format!("sleep 0.2; python3 -u -m http.server {port} --bind 127.0.0.1"),
+        )
+        .unwrap();
+        let _cleanup = StopOnDrop(job.id.clone());
+        let ready = wait_json(&job.id, |v| v["serverUrl"].is_string());
+        assert_eq!(ready["serverUrl"], format!("http://127.0.0.1:{port}"));
+        kill_job(&job.id).unwrap();
+        let stopped = wait_json(&job.id, |v| v["status"] == "stopped");
+        assert!(stopped["serverUrl"].is_null());
+    }
+
+    #[test]
+    fn shells_stop_without_id_stops_all_owned_running_jobs() {
+        let dir = TestDir::new();
+        let other_dir = TestDir::new();
+        let config = local_config();
+        let owner = Some(uuid::Uuid::new_v4().to_string());
+        let start = |workspace: &Path, job_owner: Option<String>| {
+            with_context(
+                JobContext {
+                    workspace: workspace.to_path_buf(),
+                    owner: job_owner,
+                    ..JobContext::default()
+                },
+                || start_background(workspace, &config, "sleep 30").unwrap(),
+            )
+        };
+        let empty = shells_command("stop", dir.path(), &owner, &config).unwrap();
+        assert!(empty.contains("No running"), "{empty}");
+        let first = start(dir.path(), owner.clone());
+        let _first_cleanup = StopOnDrop(first.id.clone());
+        let second = start(other_dir.path(), owner.clone());
+        let _second_cleanup = StopOnDrop(second.id.clone());
+        let third = start(dir.path(), owner.clone());
+        let _third_cleanup = StopOnDrop(third.id.clone());
+        let foreign = start(dir.path(), Some(uuid::Uuid::new_v4().to_string()));
+        let _foreign_cleanup = StopOnDrop(foreign.id.clone());
+        shells_command(&format!("stop {}", third.id), dir.path(), &owner, &config).unwrap();
+        wait_json(&third.id, |v| v["status"] == "stopped");
+        assert_eq!(job_json(&first.id, false).unwrap()["status"], "running");
+        assert_eq!(job_json(&second.id, false).unwrap()["status"], "running");
+        let stopped = shells_command("stop", dir.path(), &owner, &config).unwrap();
+        assert!(
+            stopped.contains(&first.id) && stopped.contains(&second.id),
+            "{stopped}"
+        );
+        wait_json(&first.id, |v| v["status"] == "stopped");
+        wait_json(&second.id, |v| v["status"] == "stopped");
+        assert_eq!(job_json(&foreign.id, false).unwrap()["status"], "running");
+        assert!(
+            shells_command("stop", dir.path(), &owner, &config)
+                .unwrap()
+                .contains("No running")
+        );
+    }
+
     #[test]
     fn poll_unknown_job_errors() {
         assert!(matches!(
@@ -584,3 +1588,101 @@ mod tests {
         ));
     }
 }
+
+/// Human-facing slash output shared by Desktop and Web; CLI keeps its styled renderer.
+pub fn shells_command(
+    rest: &str,
+    workspace: &Path,
+    owner: &Option<String>,
+    config: &MintConfig,
+) -> Result<String, ShellError> {
+    if rest.is_empty() || rest == "all" {
+        assert_path_capability(workspace, Capability::Read, config)?;
+        let jobs = list_json(owner, if rest == "all" { None } else { Some(workspace) });
+        let mut lines = vec!["Background terminals".to_string()];
+        for job in jobs {
+            let path = job["workspacePath"].as_str().unwrap_or("");
+            if assert_path_capability(Path::new(path), Capability::Read, config).is_err() {
+                continue;
+            }
+            lines.push(format!(
+                "{} · {} · {}s · {}\n{}",
+                job["id"].as_str().unwrap_or(""),
+                job["status"].as_str().unwrap_or(""),
+                job["elapsedSeconds"],
+                path,
+                job["command"].as_str().unwrap_or("")
+            ));
+            if let Some(url) = job["serverUrl"].as_str() {
+                lines.push(format!("Ready URL: {url}"));
+            }
+        }
+        if lines.len() == 1 {
+            lines.push("No background terminals in this workspace.".into());
+        }
+        return Ok(lines.join("\n\n"));
+    }
+    if rest == "stop" {
+        let jobs: Vec<_> = list_json(owner, None)
+            .into_iter()
+            .filter(|job| job["status"] == "running")
+            .collect();
+        if jobs.is_empty() {
+            return Ok("No running background terminals.".into());
+        }
+        let mut results = Vec::new();
+        for job in jobs {
+            let id = job["id"].as_str().unwrap_or("");
+            // Reuse the explicit-ID path so ownership and capability checks
+            // also apply to each job in the batch. Keep going on failures.
+            results.push(
+                shells_command(&format!("stop {id}"), workspace, owner, config)
+                    .unwrap_or_else(|error| format!("{id}: {error}")),
+            );
+        }
+        return Ok(results.join("\n"));
+    }
+    let (action, id) = rest
+        .split_once(char::is_whitespace)
+        .map(|(a, i)| (a, i.trim()))
+        .unwrap_or((rest, ""));
+    if !matches!(action, "show" | "stop" | "kill") || id.is_empty() {
+        return Ok("Usage: /shells [all|show <id>|stop [<id>]|kill <id>]".into());
+    }
+    if !accessible(id, owner) {
+        return Err(ShellError::JobNotFound(id.into()));
+    }
+    let job = job_json(id, action == "show")?;
+    let path = Path::new(job["workspacePath"].as_str().unwrap_or(""));
+    assert_path_capability(
+        path,
+        if action == "show" || job["managedService"] == true {
+            Capability::Read
+        } else {
+            Capability::Write
+        },
+        config,
+    )?;
+    if action != "show" {
+        return kill_job(id);
+    }
+    let readiness = job["serverUrl"]
+        .as_str()
+        .map(|url| format!("Ready URL: {url}\n"))
+        .unwrap_or_default();
+    Ok(format!(
+        "{readiness}{} · {} · {}s\nWorkspace: {}\nCommand: {}\n{}\nstdout:\n{}\nstderr:\n{}",
+        id,
+        job["status"].as_str().unwrap_or(""),
+        job["elapsedSeconds"],
+        path.display(),
+        job["command"].as_str().unwrap_or(""),
+        if job["truncated"] == true {
+            "[Older output truncated]"
+        } else {
+            ""
+        },
+        job["stdout"].as_str().unwrap_or(""),
+        job["stderr"].as_str().unwrap_or("")
+    ))
+}