@tiens.nguyen/gu-cli 1.0.825 → 1.0.827

package/gonext_agent_chat.py

@@ -7426,7 +7426,7 @@ def _shell_syntax_error(command, argv):
 # same checks an argv command gets (privilege, deny/allow lists, delete outside the project), plus
 # the two things only a shell can do: write outside the project with a redirect, and pipe text into
 # an interpreter. A command with no shell syntax still runs as argv, exactly as before.
-# Windows keeps the argv path (no bash to rely on there yet).
+# Windows uses Git Bash when Git for Windows is installed (as Claude Code does), else argv.
 _SHELL_OPS = ("&&", "||", ";;", "|&", "<<<", "<<-", "<<", "&>>", "&>", ">>", ">&", "<&", "<>",
               ">|", ";", "|", "&", "(", ")", ">", "<")
 _SHELL_SEPARATORS = {"&&", "||", ";", ";;", "|", "|&", "&", "\n", "(", ")"}
@@ -7434,7 +7434,7 @@ _SHELL_WRITE_REDIRECTS = {">", ">>", ">|", "&>", "&>>", "<>"}
 # Runners that execute TEXT as code. Piping into one with no script argument (`curl … | sh`) is the
 # shape a prompt injection takes, so it is blocked when nobody can be asked.
 _SHELL_INTERPRETERS = {"sh", "bash", "zsh", "dash", "ksh", "fish", "python", "python3", "node",
-                       "perl", "ruby", "php", "pwsh", "powershell"}
+                       "perl", "ruby", "php", "pwsh", "powershell", "py", "pythonw", "cmd"}
 _SHELL_EVAL_RUNNERS = {"eval", "source", "."}
 _SHELL_HARMLESS_TARGETS = {"/dev/null", "/dev/stdout", "/dev/stderr", "/dev/tty"}
 
@@ -7713,7 +7713,8 @@ def _shell_background_error(scan):
     if any(t[0] == "op" and t[1] == "&" for t in scan["tokens"]):
         return ("Error: that command did NOT run. Do not use `&` to background it — run_command "
                 "already leaves a server or app RUNNING when it starts listening or opens a window, "
-                "and reports its URL. Send the same command without the `&`.")
+                "and reports its URL; for a long job pass background=True. Send the same command "
+                "without the `&`.")
     return None
 
 
@@ -7728,6 +7729,28 @@ def _shell_priv_reason(scan):
     return None
 
 
+def _shell_prog_name(prog):
+    """`C:/Python/python.exe` / `/usr/bin/python3` → "python" / "python3" (Git Bash runs .exe)."""
+    b = re.split(r"[\\/]", prog or "")[-1].lower()
+    return b[:-4] if b.endswith(".exe") else b
+
+
+def _shell_path_to_native(p, windows=None):
+    """A path as Git Bash writes it → the Windows path it means, so the outside-the-project checks
+    measure the right place: `/c/Users/x` → `C:\\Users\\x`, `/tmp/x` → the temp folder. On Windows
+    os.path reads `/c/Users/x` as `<current drive>:\\c\\Users\\x`. Elsewhere `p` comes back as is."""
+    if not (os.name == "nt" if windows is None else windows) or not p:
+        return p
+    m = re.match(r"^/([a-zA-Z])(?=/|$)(.*)$", p)
+    if m:
+        return m.group(1).upper() + ":" + (m.group(2) or "/").replace("/", "\\")
+    m = re.match(r"^/tmp(?=/|$)(.*)$", p)
+    if m:
+        import tempfile
+        return tempfile.gettempdir() + m.group(1).replace("/", "\\")
+    return p
+
+
 def _ws_write_outside_reason(redirects, wd, roots=None):
     """Why a redirect needs the user's yes: it writes a file OUTSIDE every workspace and the temp
     folder. The shell's counterpart of _ws_delete_outside_reason."""
@@ -7743,7 +7766,7 @@ def _ws_write_outside_reason(redirects, wd, roots=None):
     temp = [os.path.realpath(p) for p in {tempfile.gettempdir(), "/tmp", "/var/tmp"} if p]
     outside = []
     for t in targets:
-        p = os.path.expanduser(t)
+        p = os.path.expanduser(_shell_path_to_native(t))
         p = os.path.realpath(p if os.path.isabs(p) else os.path.join(wd or os.getcwd(), p))
         if not (_ws_is_inside(p, ws) or _ws_is_inside(p, temp)):
             outside.append(t)
@@ -7779,7 +7802,8 @@ def _ws_shell_command_risk(scan, denyset, wd="", allowset=None, roots=None):
     for c in top:
         a = c["argv"]
         if a and a[0] == "cd" and len(a) >= 2 and c["sep"] not in ("|", "|&"):
-            cur = os.path.normpath(os.path.join(cur or os.getcwd(), os.path.expanduser(a[1])))
+            cur = os.path.normpath(os.path.join(cur or os.getcwd(),
+                                                os.path.expanduser(_shell_path_to_native(a[1]))))
             continue
         why = (_ws_delete_outside_reason(a, cur, roots)
                or _ws_write_outside_reason(c["redirects"], cur, roots))
@@ -7791,7 +7815,7 @@ def _ws_shell_command_risk(scan, denyset, wd="", allowset=None, roots=None):
             return (None, why, why)
     for c in top:
         a = c["argv"]
-        r = os.path.basename(a[0]).lower() if a else ""
+        r = _shell_prog_name(a[0]) if a else ""
         if c["sep"] in ("|", "|&") and r in _SHELL_INTERPRETERS \
                 and all(x.startswith("-") for x in a[1:]):
             msg = f"it pipes text into {r}, which runs that text as code"
@@ -7838,22 +7862,59 @@ def _with_attribution_text(command, scan, settings):
 _RUN_SHELL_BIN = None
 
 
+def _git_bash_path(env=None, which=None, isfile=None):
+    """Git for Windows' bash.exe, or "". PURE given its three lookups (tested off Windows).
+
+    GU_GIT_BASH_PATH first, then the Git that owns `git` on PATH (…\\Git\\cmd|bin|mingw64\\bin →
+    …\\Git\\bin\\bash.exe), then the usual install folders. Never WSL's bash (System32,
+    WindowsApps): that runs in a separate Linux with its own files, not on the user's Windows."""
+    import ntpath
+    import shutil as _sh
+    env = os.environ if env is None else env
+    which = which or _sh.which
+    isfile = isfile or os.path.isfile
+    cands = [env.get("GU_GIT_BASH_PATH") or ""]
+    git = which("git") or ""
+    if git:
+        d = ntpath.dirname(git)
+        for _ in range(3):  # cmd\git.exe, bin\git.exe, mingw64\bin\git.exe
+            cands.append(ntpath.join(d, "bin", "bash.exe"))
+            d = ntpath.dirname(d)
+    for var, sub in (("ProgramFiles", "Git"), ("ProgramW6432", "Git"),
+                     ("ProgramFiles(x86)", "Git"), ("LOCALAPPDATA", ntpath.join("Programs", "Git"))):
+        if env.get(var):
+            cands.append(ntpath.join(env[var], sub, "bin", "bash.exe"))
+    for c in cands:
+        low = c.lower()
+        if c and "\\system32\\" not in low and "\\windowsapps\\" not in low and isfile(c):
+            return c
+    return ""
+
+
 def _run_shell_bin():
-    """bash (else sh) for run_command's shell lines, or "" for the argv-only path: Windows, or
-    GU_RUN_NO_SHELL=1 (the way back if a shell line ever misbehaves for a user)."""
+    """The shell for run_command's shell lines: bash (else sh), Git Bash on Windows — or "" for
+    the argv-only path (Windows without Git for Windows, or GU_RUN_NO_SHELL=1, the way back if a
+    shell line ever misbehaves for a user)."""
     global _RUN_SHELL_BIN
-    if os.name == "nt" or os.environ.get("GU_RUN_NO_SHELL") == "1":
+    if os.environ.get("GU_RUN_NO_SHELL") == "1":
         return ""
     if _RUN_SHELL_BIN is None:
-        import shutil as _sh
-        _RUN_SHELL_BIN = next((p for p in (_sh.which("bash"), "/bin/bash", "/bin/sh")
-                               if p and os.path.exists(p)), "")
+        if os.name == "nt":
+            _RUN_SHELL_BIN = _git_bash_path()
+            _log("run_command shell: " + ("Git Bash" if _RUN_SHELL_BIN else
+                 "none (Git for Windows not found) — commands run without a shell"))
+        else:
+            import shutil as _sh
+            _RUN_SHELL_BIN = next((p for p in (_sh.which("bash"), "/bin/bash", "/bin/sh")
+                                   if p and os.path.exists(p)), "")
     return _RUN_SHELL_BIN
 
 
-def _run_command_prompt_line(shell):
+def _run_command_prompt_line(shell, windows=None):
     """The system prompt's run_command rule. With a shell it carries the git and GitHub recipes,
-    the way Claude Code's Bash tool description does: told how to batch, the model does (#359)."""
+    the way Claude Code's Bash tool description does: told how to batch, the model does (#359).
+    On Windows the shell is Git Bash, and the line says what differs there."""
+    windows = (os.name == "nt") if windows is None else windows
     if not shell:
         return (
             "    run_command CHAINS: put dependent commands in ONE call with && — e.g. "
@@ -7862,12 +7923,16 @@ def _run_command_prompt_line(shell):
             "chain. There is NO shell otherwise: pipes `|`, redirects `>`, `;`, `||` and backticks do "
             "NOT work (use python3 for anything that composes). `sudo`/`su` are blocked; an "
             "interactive input() CLI fails with EOFError. A server or GUI app is left RUNNING — "
-            "stop_server closes it.\n")
+            "stop_server closes it. " + _BG_LINE)
     return (
         "    run_command IS A SHELL (bash): pipes, redirects, `;`, `||`, `$( )`, globs and heredocs "
         "work, so put a whole sequence in ONE call — dependent steps with &&, independent ones with "
         "`;` (e.g. `cd app && npm test 2>&1 | tail -40`); a multi-line command goes in a "
         "triple-quoted string.\n"
+        + ("    WINDOWS: the shell is Git Bash. Write paths with forward slashes (`C:/Users/x` or "
+           "`/c/Users/x`, never `C:\\Users`); Windows programs (npm, node, git, gh, py) run as usual; "
+           "Python is `py -3` or `python`, not python3; cmd built-ins need `cmd //c dir`.\n"
+           if windows else "") +
         "    GIT in one call each: look (`git status -sb; git diff --stat; git log --oneline -5`), "
         "commit (`git add a.py b.py && git commit -m \"msg\" && git log --oneline -1`).\n"
         "    GITHUB: use `gh`. Multi-line text goes as a heredoc on stdin — "
@@ -7876,7 +7941,13 @@ def _run_command_prompt_line(shell):
         "    Read and search FILES with read_file_lines / grep_repo, not cat/grep/sed. `sudo`/`su` "
         "are blocked; piping into sh/python and writing or deleting outside the project ask the "
         "user first; an interactive input() CLI fails with EOFError. A server or GUI app is left "
-        "RUNNING — stop_server closes it.\n")
+        "RUNNING — stop_server closes it. " + _BG_LINE)
+
+
+# Background shells (task #360). Never `&` (refused) — background=True is the way to say it.
+_BG_LINE = ("A LONG job (build, deploy, big test run) → run_command(…, background=True), then "
+            "shell_output(<id>, wait_seconds=…) to wait for it; a command still running at its "
+            "timeout moves to the background by itself instead of being killed.\n")
 
 
 _RUN_DOC_ARGV = ("No other shell syntax (no pipes/redirects/;). sudo/su are blocked.")
@@ -8214,7 +8285,7 @@ def _ws_delete_outside_reason(argv, wd, roots=None):
     temp = [os.path.realpath(p) for p in {tempfile.gettempdir(), "/tmp", "/var/tmp"} if p]
     outside = []
     for t in targets:
-        p = os.path.expanduser(t)
+        p = os.path.expanduser(_shell_path_to_native(t))
         p = os.path.realpath(p if os.path.isabs(p) else os.path.join(wd or os.getcwd(), p))
         if not (_ws_is_inside(p, ws) or _ws_is_inside(p, temp)):
             outside.append(t)
@@ -8754,6 +8825,153 @@ def _ws_cap_servers(max_live: int = 3) -> list:
     return servers
 
 
+# ---- BACKGROUND SHELLS (task #360, GitHub #140) ------------------------------------------------
+# A long build (`fastlane ios beta`, 7+ minutes) is neither a server nor a GUI app, so run_command
+# used to KILL it at its deadline — the one outcome that is never what anyone wanted. Now it is
+# handed off instead: it keeps running in its own process group, and its record lives here, in a
+# file of its own rather than servers.json, because shells must not count toward the 3-server cap
+# (that would kill a build to make room for a dev server) and a FINISHED one stays listed so the
+# user and the model can read how it ended. The terminal reads the same file for its "shell
+# running" link and the Shell details view (shell-details.mjs).
+#
+# THE EXIT CODE OUTLIVES THE AGENT. The agent is one process per turn; a build that ends after the
+# turn has no parent left to wait() on it. So a shell line runs as `"$0" -c "$1"; rc=$?; echo $rc
+# > "$2"; exit $rc` — the command text untouched, its exit code written to `exit_file` AND passed
+# on (without the `exit $rc` every failure read as EXITED 0). The argv-only path (Windows)
+# has no such wrapper and says "exit code unknown" instead of guessing.
+_SHELLS_KEEP = 20            # newest records kept, running or not
+_SHELLS_KEEP_DONE_S = 86400  # a finished shell is listed for a day
+
+
+def _shells_path() -> str:
+    import os
+    base = os.path.join(os.path.expanduser("~"), ".gonext")
+    os.makedirs(base, exist_ok=True)
+    return os.path.join(base, "shells.json")
+
+
+def _shells_load() -> list:
+    import json as _json
+    try:
+        with open(_shells_path(), encoding="utf-8") as fh:
+            shells = _json.load(fh).get("shells", [])
+    except Exception:  # noqa: BLE001
+        return []
+    return [s for s in shells if isinstance(s, dict) and s.get("pid")]
+
+
+def _shells_save(shells: list) -> None:
+    import json as _json
+    import os
+    import time as _t
+    now = _t.time()
+    kept = []
+    for s in shells:
+        st = _shell_state(s, now=now)
+        if st["state"] != "running" and now - st["ended"] > _SHELLS_KEEP_DONE_S:
+            continue
+        kept.append(s)
+    path = _shells_path()
+    tmp = f"{path}.{os.getpid()}.tmp"
+    try:
+        with open(tmp, "w", encoding="utf-8") as fh:
+            _json.dump({"shells": kept[-_SHELLS_KEEP:]}, fh, indent=2)
+        os.replace(tmp, path)  # the terminal polls this file — never let it read half of it
+    except OSError as e:
+        _log(f"shells.json write failed: {e}")
+
+
+def _shell_exit_code(s: dict):
+    """(code, mtime) from the shell's exit file, or (None, None) when it has not written one."""
+    import os
+    path = s.get("exit_file") or ""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            raw = fh.read().strip()
+        return (int(raw), os.path.getmtime(path)) if raw.lstrip("-").isdigit() else (None, None)
+    except (OSError, ValueError):
+        return (None, None)
+
+
+def _shell_state(s: dict, alive=None, now=None) -> dict:
+    """{state, code, runtime, ended} for a shell record. state: running | exited (0) | failed |
+    killed | ended (gone, exit code unknown). `alive` is injectable so tests need no process."""
+    import time as _t
+    now = now if now is not None else _t.time()
+    started = float(s.get("started") or now)
+    code, code_at = _shell_exit_code(s)
+    if alive is None:
+        alive = code is None and bool(_ws_pgroup_pids(int(s.get("pgid") or 0)))
+    if alive and code is None and not s.get("killed"):
+        return {"state": "running", "code": None, "runtime": max(0.0, now - started), "ended": now}
+    ended = float(s.get("ended") or code_at or now)
+    if s.get("killed"):
+        state = "killed"
+    elif code is None:
+        state = "ended"
+    else:
+        state = "exited" if code == 0 else "failed"
+    return {"state": state, "code": code, "runtime": max(0.0, ended - started), "ended": ended}
+
+
+def _fmt_runtime(seconds: float) -> str:
+    """7m 2s — the way the Shell details view writes it."""
+    s = int(seconds)
+    h, s = divmod(s, 3600)
+    m, s = divmod(s, 60)
+    return f"{h}h {m}m" if h else (f"{m}m {s}s" if m else f"{s}s")
+
+
+def _shell_status_text(st: dict) -> str:
+    if st["state"] == "running":
+        return "running"
+    if st["state"] in ("exited", "failed"):
+        return f"exited {st['code']}"
+    return "killed" if st["state"] == "killed" else "ended (exit code unknown)"
+
+
+def _shell_find(shells: list, key: str):
+    """A shell by its id/pid, or the newest one for an empty key."""
+    key = (key or "").strip().lstrip("#")
+    if not key:
+        return shells[-1] if shells else None
+    for s in reversed(shells):
+        if key in (str(s.get("id")), str(s.get("pid"))):
+            return s
+    return None
+
+
+def _shell_kill(s: dict) -> None:
+    """Stop a shell's whole process group and mark it killed (unless it already finished)."""
+    import time as _t
+    if _shell_state(s)["state"] != "running":
+        return
+    try:
+        _ws_kill_tree(int(s.get("pgid") or 0))
+        _t.sleep(1.0)
+        if _ws_pgroup_pids(int(s.get("pgid") or 0)):
+            _ws_kill_tree(int(s.get("pgid") or 0), force=True)
+    except (OSError, ValueError):
+        pass
+    s["killed"] = True
+    s["ended"] = _t.time()
+
+
+def _shells_context_line(shells: list, now=None) -> str:
+    """The turn's line about shells: what is still running, and what finished since the model
+    last looked — a build that ended between turns is news the model has not seen."""
+    bits = []
+    for s in shells:
+        st = _shell_state(s, now=now)
+        if st["state"] == "running" or not s.get("seen"):
+            bits.append(f"shell {s.get('id')} {_shell_status_text(st)} after "
+                        f"{_fmt_runtime(st['runtime'])}: '{_clip(str(s.get('command')), 60)}'")
+    if not bits:
+        return ""
+    return ("  Background shells YOU started: " + "; ".join(bits)
+            + ". Read one with shell_output(<id>); stop one with stop_server(<id>).\n")
+
+
 def _ws_scrubbed_env() -> dict:
     """Minimal child env for run_command. The worker process env holds secrets
     (GONEXT_WORKER_KEY etc. via worker.env) — a repo's test script must NEVER see
@@ -8764,6 +8982,13 @@ def _ws_scrubbed_env() -> dict:
             # SSH agent socket so ssh/scp/rsync can authenticate with the user's KEY
             # (no password in the model's context) for deploys (task #57).
             "SSH_AUTH_SOCK", "SSH_AGENT_PID")
+    if os.name == "nt":
+        # Not secrets — what Windows programs need to start at all: without SYSTEMROOT Python's
+        # sockets fail, npm needs APPDATA, Git Bash needs USERPROFILE/HOMEDRIVE to find home.
+        keep += ("SYSTEMROOT", "SystemDrive", "WINDIR", "COMSPEC", "PATHEXT", "USERPROFILE",
+                 "HOMEDRIVE", "HOMEPATH", "USERNAME", "APPDATA", "LOCALAPPDATA", "TEMP", "TMP",
+                 "ProgramFiles", "ProgramFiles(x86)", "ProgramW6432", "ProgramData",
+                 "CommonProgramFiles", "NUMBER_OF_PROCESSORS", "PROCESSOR_ARCHITECTURE")
     env = {k: os.environ[k] for k in keep if k in os.environ}
     # CI=1 makes watch-mode test runners (CRA's `npm test`, jest --watch) run ONCE and
     # exit instead of sitting in interactive watch mode until the timeout kills them.
@@ -10060,6 +10285,10 @@ def run_agent_chat(cfg):
                     "are TAKEN, so never start a duplicate on one of them.\n")
         except Exception as _e:  # noqa: BLE001
             _log(f"server context skip: {_e}")
+        try:
+            _ws_servers_line += _shells_context_line(_shells_load())
+        except Exception as _e:  # noqa: BLE001
+            _log(f"shell context skip: {_e}")
     _ws_context_block = (
         _ws_current_line
         + f"  Other registered workspaces (use only if the user names them): {_ws_names}\n"
@@ -14070,13 +14299,15 @@ def run_agent_chat(cfg):
                 _last_obs["text"] = msg
                 return msg
 
-        def run_command(command: str, workdir: str = "", timeout_seconds: int = 180) -> str:
+        def run_command(command: str, workdir: str = "", timeout_seconds: int = 180,
+                        background: bool = False) -> str:
             """Run a command inside a workspace that has run permission (e.g. 'npm test', 'npm run build', 'npm start', 'mvn test', 'python3 app.py'). One-shot commands return their output when they exit. If the command turns out to be a SERVER (keeps running and listens on a port), it is left RUNNING and its URL is reported. If it is a DESKTOP/GUI app (opens a window — tkinter, pygame, PyQt…), it is LAUNCHED and left running: its window appears on the user's Mac; tell them it's open. Both are stoppable via stop_server. Also allows DEPLOY commands (ssh/scp/rsync) — use non-interactive KEY auth (-o BatchMode=yes); never put a password in the command (there is no stdin). Note: an interactive CLI that reads stdin (input()) cannot be driven here — it will fail with EOFError; make it non-interactive or give the user the command to run themselves.
 
             Args:
                 command: the command line. Chain dependent steps with && in ONE call ("cd app && npm ci && npm test"): they run in order, cd sets the folder, the first failure stops the rest. No other shell syntax (no pipes/redirects/;). sudo/su are blocked.
                 workdir: directory to run in. Empty = first registered workspace.
-                timeout_seconds: give up after this many seconds if the command neither exits nor starts a server (max 600).
+                timeout_seconds: wait this many seconds (max 600); a command still running then is NOT killed — it moves to the background as a shell, read later with shell_output.
+                background: True for a long job you do not need to watch (a build, deploy, long test run): it starts, returns its shell id after ~3s, and keeps running. Check it with shell_output(<id>, wait_seconds=…).
             """
             proc = None  # read by the `finally` below, which runs even if Popen never did
             try:
@@ -14177,7 +14408,7 @@ def run_agent_chat(cfg):
                             break
                         _res = str(run_command(_part, _cur_wd, int(min(timeout_seconds or 180, 600, _left))))
                         _outs.append(f"{_hdr}\n{_res}")
-                        if _res.startswith(("FAILED", "Error")):
+                        if _res.startswith(("FAILED", "Error", "BACKGROUND")):
                             _stopped = _part
                             break
                     _rest = _chain[len(_outs):]
@@ -14296,12 +14527,18 @@ def run_agent_chat(cfg):
                 os.makedirs(logs_dir, exist_ok=True)
                 log_path = os.path.join(logs_dir, f"{_t.strftime('%Y%m%d-%H%M%S')}-{os.getpid()}.log")
                 log_fh = open(log_path, "wb")
+                exit_path = log_path[:-4] + ".exit"
                 # gu as a co-author on the commits it makes (task #289) — after every check
                 # above, which judged the command as the model wrote it.
                 if _use_shell:
                     _cmd_text, _attrib_note = _with_attribution_text(
                         command, _scan, _attribution_settings(wd))
-                    argv = [_shell_bin, "-c", _cmd_text]
+                    # The exit code is written to a file so it outlives this turn's process —
+                    # the line itself runs untouched as $1 (see BACKGROUND SHELLS).
+                    # Git Bash reads C:/x, not C:\x, inside the line it runs.
+                    _fs = (lambda x: x.replace("\\", "/")) if _IS_WINDOWS else (lambda x: x)
+                    argv = [_shell_bin, "-c", '"$0" -c "$1"; rc=$?; echo $rc > "$2"; exit $rc',
+                            _fs(_shell_bin), _cmd_text, _fs(exit_path)]
                 else:
                     argv, _attrib_note = _with_attribution(argv, _attribution_settings(wd))
                 if _attrib_note:
@@ -14318,6 +14555,25 @@ def run_agent_chat(cfg):
                 _INFLIGHT_CMDS.add(proc.pid)  # killed with the agent until it is classified
                 start = _t.time()
 
+                def _to_background(why: str) -> str:
+                    """Leave the command running as a background shell; say so to the model."""
+                    shells = _shells_load()
+                    shells.append({
+                        "id": str(proc.pid), "pid": proc.pid, "pgid": proc.pid,
+                        "command": command, "workdir": wd, "log": log_path,
+                        "exit_file": exit_path if _use_shell else "",
+                        "started": start, "started_at": _t.strftime("%Y-%m-%d %H:%M:%S"),
+                    })
+                    _shells_save(shells)
+                    _emit({"type": "step", "text":
+                           f"Running in background → {_trim_words(command)} (shell {proc.pid})"})
+                    tail = _ws_distill_output(_read_log())
+                    return (f"BACKGROUND: '{_clip(command, 200)}' is {why} and keeps running as "
+                            f"shell {proc.pid} (log {log_path}). Do NOT start it again. Check it "
+                            f"with shell_output('{proc.pid}', wait_seconds=…); stop it with "
+                            f"stop_server('{proc.pid}').\nOutput so far:\n"
+                            + (tail if tail.strip() else "(none yet)"))
+
                 def _read_log() -> str:
                     log_fh.flush()
                     try:
@@ -14413,17 +14669,20 @@ def run_agent_chat(cfg):
                                       + (f"\nStartup output:\n{tail}" if tail.strip() else ""))
                             _last_obs["text"] = result
                             return result
+                    # A job sent to the background on purpose, once it has had its 3s to show
+                    # it is neither a server nor an app.
+                    if background and _t.time() - start >= 3:
+                        msg = _to_background("started")
+                        _last_obs["text"] = msg
+                        return msg
+                    # THE DEADLINE HANDS OFF, IT NO LONGER KILLS (task #360): a 7-minute build
+                    # is the command doing its job, not a hang. The 1h turn budget and
+                    # stop_server still bound it.
                     if _t.time() - start >= t:
-                        try:
-                            _ws_kill_tree(proc.pid, force=True)
-                        except OSError:
-                            pass
-                        tail = _ws_distill_output(_read_log())
-                        msg = (f"Error: command neither exited nor started a server within "
-                               f"{t}s — killed. Output so far:\n{tail}")
+                        msg = _to_background(f"still running after {t}s")
                         _last_obs["text"] = msg
                         return msg
-                    _t.sleep(2)
+                    _t.sleep(1 if background else 2)
             except Exception as ex:  # noqa: BLE001
                 msg = f"Error: run_command failed: {type(ex).__name__}: {ex}"
                 _last_obs["text"] = msg
@@ -14439,22 +14698,44 @@ def run_agent_chat(cfg):
                     pass
 
         # The description says what the command line may contain, which depends on the machine:
-        # bash here, argv only on Windows (#359). Set before tool() reads the docstring.
+        # bash here (Git Bash on Windows), argv when there is none (#359). Set before tool() reads
+        # the docstring.
         if _run_shell_bin():
             run_command.__doc__ = run_command.__doc__.replace(_RUN_DOC_ARGV, _RUN_DOC_SHELL)
         run_command = tool(run_command)
 
         @tool
         def stop_server(port_or_pid: str = "") -> str:
-            """Stop a background server OR desktop app previously started by run_command (closes its window). Use when the user asks to stop/kill/close it.
+            """Stop a background server, desktop app (closes its window) or background shell previously started by run_command. Use when the user asks to stop/kill/close it.
 
             Args:
-                port_or_pid: the server's port or pid (empty = the most recently started one).
+                port_or_pid: the server's port or pid, or a shell id (empty = the most recently started server).
             """
             try:
                 import os
                 import signal
                 import time as _t
+                key = (port_or_pid or "").strip()
+                shells = _shells_load()
+                if key:
+                    sh = _shell_find(shells, key)
+                elif not _ws_load_servers():
+                    # Nothing else to stop: the newest shell still running.
+                    sh = next((x for x in reversed(shells)
+                               if _shell_state(x)["state"] == "running"), None)
+                else:
+                    sh = None
+                if sh is not None:
+                    was = _shell_status_text(_shell_state(sh))
+                    _shell_kill(sh)
+                    sh["seen"] = True
+                    _shells_save(shells)
+                    _emit({"type": "step", "text": f"Shell stopped → {_trim_words(str(sh.get('command')))}"})
+                    out = (f"Stopped shell {sh.get('id')} ('{_clip(str(sh.get('command')), 120)}')."
+                           if was == "running" else
+                           f"Shell {sh.get('id')} had already finished: {was}.")
+                    _last_obs["text"] = out
+                    return out
                 servers = _ws_load_servers()
                 if not servers:
                     msg = "No background servers are running."
@@ -14493,6 +14774,60 @@ def run_agent_chat(cfg):
                 _last_obs["text"] = msg
                 return msg
 
+        @tool
+        def shell_output(shell_id: str = "", wait_seconds: int = 0) -> str:
+            """Read a background shell started by run_command (a long build, deploy or test run): its status (running / exited N / killed), runtime, and the output it printed SINCE YOUR LAST READ. To wait for it to finish, pass wait_seconds (max 540) — one call that waits is cheaper than many that poll.
+
+            Args:
+                shell_id: the shell id run_command gave you (empty = the newest shell).
+                wait_seconds: wait up to this long for the shell to finish before answering (0 = answer now).
+            """
+            try:
+                import time as _t
+                shells = _shells_load()
+                sh = _shell_find(shells, shell_id)
+                if sh is None:
+                    msg = ("No background shell matches '" + (shell_id or "") + "'. "
+                           + ("Shells: " + ", ".join(str(x.get("id")) for x in shells) if shells
+                              else "No background shells were started."))
+                    _last_obs["text"] = msg
+                    return msg
+                deadline = _t.time() + max(0, min(int(wait_seconds or 0), 540))
+                st = _shell_state(sh)
+                while st["state"] == "running" and _t.time() < deadline:
+                    _t.sleep(2)
+                    st = _shell_state(sh)
+                try:
+                    with open(sh.get("log") or "", "rb") as fh:
+                        fh.seek(int(sh.get("read_offset") or 0))
+                        chunk = fh.read()
+                except OSError:
+                    chunk = b""
+                # Re-read the file before writing: the terminal may have killed it meanwhile.
+                shells = _shells_load()
+                cur = _shell_find(shells, str(sh.get("id"))) or sh
+                cur["read_offset"] = int(sh.get("read_offset") or 0) + len(chunk)
+                if st["state"] != "running":
+                    cur["seen"] = True
+                _shells_save(shells)
+                new = _ws_distill_output(chunk.decode("utf-8", errors="replace"))
+                head = (f"shell {sh.get('id')}: {_shell_status_text(st).upper()} after "
+                        f"{_fmt_runtime(st['runtime'])} — '{_clip(str(sh.get('command')), 200)}' "
+                        f"(log {sh.get('log')})")
+                if st["state"] == "exited":
+                    head += ("\nexit 0 alone does NOT prove the intended effect happened — check "
+                             "the output and VERIFY.")
+                msg = head + "\n" + (f"New output:\n{new}" if new.strip()
+                                     else "No new output since the last read.")
+                _emit({"type": "step", "text":
+                       f"Shell {sh.get('id')} {_shell_status_text(st)} → {_trim_words(str(sh.get('command')))}"})
+                _last_obs["text"] = msg
+                return msg
+            except Exception as ex:  # noqa: BLE001
+                msg = f"Error: shell_output failed: {type(ex).__name__}: {ex}"
+                _last_obs["text"] = msg
+                return msg
+
         @tool
         def deploy_web(local_dir: str, host: str, user: str, remote_path: str,
                        domain: str = "") -> str:
@@ -14636,7 +14971,7 @@ def run_agent_chat(cfg):
             # tools below it is always available wherever a workspace is (task #221).
             agent_tools += [symbol_context, grep_repo, read_file_lines, edit_lines, edit_file,
                             create_file, create_folder, run_command, stop_server,
-                            deploy_web]
+                            shell_output, deploy_web]
             # Workspace RAG (task #133): semantic search over the PROJECT itself, not just a
             # ZIP-at-URL. Needs both a workspace to index and a working embedder, so it's
             # registered only when RAG is actually available — the model never sees a tool it

package/gu-repl.mjs

@@ -139,6 +139,7 @@ import {
 import { completedFlush, splitLiveStream } from "./completed-flush.mjs";
 import { isScaffoldStep, isGroupableStep, stepGroupRows, relativizePaths } from "./step-group.mjs";
 import { clearLogsNoticeText } from "./clear-logs.mjs";
+import { killShell, logTail, readShells, renderShellDetails, shellPickerLabel, shellState, shellsNotice } from "./shell-details.mjs";
 import { discoverSkills, matchSkillCommand } from "./skills.mjs";
 import { appendNew, archivePathFor, archivedWorkspaceKey, markReset, seedArchive } from "./conversation-archive.mjs";
 import { addAllowRule, listServers as listMcpServers } from "./mcp-config.mjs";
@@ -947,6 +948,7 @@ const COMMANDS = [
   { name: "/open-presets", usage: "/open-presets [name]", desc: "your whole setup now, keys included, read-only in your editor — to copy to another computer; with a name, edit that preset" },
   { name: "/use-presets", usage: "/use-presets [name]", desc: "pick a saved preset and apply it — shows what changes, backs up your setup, asks first" },
   { name: "/doctor", desc: "check every configured model ANSWERS — especially the embedder, which a turn only reaches after several steps" },
+  { name: "/shells", desc: "long commands the agent left running in the background — status, runtime, command, output; stop one" },
   { name: "/tokens", desc: "break down the last prompt sent to the coding model — how much of it was RAG" },
   { name: "/clear-logs", desc: "show what gu's logs, RAG indexes and old API versions take on disk, then ask what to clear — the logs first" },
   { name: "/prices", usage: "/prices [update]", desc: "the price table and the cache table, and what the last turn and this session cost — \"update\" applies gu's newest published tables" },
@@ -1544,6 +1546,11 @@ function applyClick({ row, col }) {
     void showOtherAgents(); // async now — it offers stop / switch-to (task #211)
     return;
   }
+  if (shellsRowTarget && row === updateRowAbs &&
+      col - 1 >= shellsRowTarget.from && col - 1 < shellsRowTarget.to) {
+    void showShells();
+    return;
+  }
   // The input line has a KNOWN absolute row now (it is frozen), so a click on it maps straight
   // to a text offset — no \x1b[6n probe, no anchor to go stale (task #141).
   if (barPinned()) {
@@ -2957,6 +2964,8 @@ function zoneNotice(width) {
   if (tokenNotice?.text) items.push({ key: "token", paint: tokenNotice.urgent ? yellow : dim, text: tokenNotice.text });
   const agents = agentsIndicator(otherAgents);
   if (agents) items.push({ key: "agents", clickable: true, paint: accent, text: `${agents} running (click)` });
+  const shells = shellsNotice(shellEntries, { viewed: shellsViewed, since: SHELLS_SINCE });
+  if (shells) items.push({ key: "shells", clickable: true, paint: shells.tone === "warn" ? yellow : accent, text: shells.text });
   // LAST, so it is the first to give way on a narrow window: housekeeping, never urgent (#329).
   const logs = clearLogsNoticeText(logsBytes);
   if (logs) items.push({ key: "logs", clickable: true, paint: dim, text: logs });
@@ -3042,6 +3051,7 @@ function frozenZone() {
   pricesRowTarget = notice?.spans.prices ?? null;
   limitsRowTarget = notice?.spans.limits ?? null;
   logsRowTarget = notice?.spans.logs ?? null;
+  shellsRowTarget = notice?.spans.shells ?? null;
   jumpSpan = notice?.spans.jump ?? null;
   return { ...zone, rows, statusRows: sep, noticeRow: Boolean(notice) };
 }
@@ -3111,7 +3121,7 @@ function paintBar() {
   // THE NOTICE ROW is the one directly above the separator (#318) — never the separator itself.
   const noticeAbs = zone.noticeRow ? sepAbs - 1 : 0;
   jumpRowTarget = scrolledBack() && jumpSpan ? { row: noticeAbs, ...jumpSpan } : null;
-  updateRowAbs = updateRowTarget || agentsRowTarget || pricesRowTarget || limitsRowTarget || logsRowTarget ? noticeAbs : 0;
+  updateRowAbs = updateRowTarget || agentsRowTarget || pricesRowTarget || limitsRowTarget || logsRowTarget || shellsRowTarget ? noticeAbs : 0;
   // preserveCaret:false — the save slot holds the OUTPUT position (see regionUi), and the caret
   // is parked on the input line right after, so there is nothing to preserve here.
   ui(
@@ -3277,6 +3287,8 @@ let pricesRowTarget = null;
 let limitsRowTarget = null;
 // …and "clear logs · 175 MB" (#329), shown only once the logs are worth a row.
 let logsRowTarget = null;
+// …and "1 shell running (click)" (#360) — a long command the agent left running in the background.
+let shellsRowTarget = null;
 // A terminal left with a scrolling region is a broken shell — a hard guarantee, like the
 // bracketed-paste and mouse-reporting teardowns.
 process.on("exit", () => {
@@ -9470,6 +9482,83 @@ async function chooseServer() {
  */
 let otherAgents = [];
 const OTHER_AGENTS_MS = 20000;
+
+/**
+ * BACKGROUND SHELLS (task #360, GitHub #140). The agent leaves a long command — a 7-minute build —
+ * running instead of killing it at its deadline, and records it in ~/.gonext/shells.json. Read
+ * here once a second (a local file, no API), so the notice row can say it is still running and
+ * a click can show it. Repaints only when the row's text changes.
+ */
+let shellEntries = [];
+const shellsViewed = new Set();
+const SHELLS_SINCE = Date.now() / 1000; // a shell that ended before this terminal opened is old news
+const SHELLS_MS = 1000;
+function refreshShells() {
+  const before = shellsNotice(shellEntries, { viewed: shellsViewed, since: SHELLS_SINCE })?.text ?? "";
+  shellEntries = readShells().map((rec) => ({ rec, st: shellState(rec) }));
+  const after = shellsNotice(shellEntries, { viewed: shellsViewed, since: SHELLS_SINCE })?.text ?? "";
+  if (after !== before) paintBar();
+}
+
+/** The Shell details block for one shell, printed into the transcript. */
+function printShellDetails(rec) {
+  const width = Math.max(20, process.stdout.columns || 80);
+  const st = shellState(rec);
+  shellsViewed.add(String(rec.id));
+  const rows = renderShellDetails({
+    rec, st, output: logTail(rec.log), width: width - 1, gutter: GUTTER,
+    style: { title: (t) => bold(accent(t)), label: bold, running: accent, ok: accent, bad: red, dim },
+  });
+  console.log("\n" + GUTTER + accent("─".repeat(Math.max(10, width - 1 - GUTTER.length))));
+  console.log(rows.join("\n") + "\n");
+  return st;
+}
+
+/**
+ * Click on the shell control, or /shells: pick a shell (when there is more than one), see its
+ * details, then refresh / stop it / close. During a turn it only prints the details — a picker
+ * would fight the turn for the keyboard, as showOtherAgents explains.
+ */
+async function showShells() {
+  if (listPickerActive || approvalActive) return;
+  const width = Math.max(20, process.stdout.columns || 80);
+  refreshShells();
+  const entries = [...shellEntries].reverse(); // newest first
+  if (!entries.length) {
+    console.log("\n" + GUTTER + dim("No background shells. A long command the agent runs moves here instead of being stopped.\n"));
+    paintBar();
+    return;
+  }
+  let pick = 0;
+  if (entries.length > 1 && !following) {
+    console.log("");
+    console.log(dim(`   Background shells — pick one  (${PICK_HINT}):`));
+    pick = await pickFromList(entries.map((e) => shellPickerLabel(e.rec, e.st, width)), 0);
+    if (pick < 0) {
+      console.log(dim("   (cancelled)\n"));
+      paintBar();
+      return;
+    }
+  }
+  const rec = entries[pick].rec;
+  for (;;) {
+    const st = printShellDetails(rec);
+    if (following) break;
+    const actions = [{ id: "refresh", label: "Refresh" }];
+    if (st.state === "running") actions.push({ id: "kill", label: "Stop it", note: "kills the command and everything it started" });
+    actions.push({ id: "close", label: "Close" });
+    const act = await pickFromList(actions.map((a) => a.label + (a.note ? dim(`  · ${a.note}`) : "")), 0);
+    const id = act < 0 ? "close" : actions[act].id;
+    if (id === "refresh") continue;
+    if (id === "kill") {
+      await killShell(rec);
+      console.log(GUTTER + accent("✓ stopped") + dim(" — the agent sees it as killed next turn.\n"));
+    }
+    break;
+  }
+  refreshShells();
+  paintBar();
+}
 async function refreshOtherAgents() {
   if (!barPinned() || following) return;
   try {
@@ -13719,6 +13808,9 @@ async function main() {
   // a turn runs; unref'd so a pending timer is never the reason gu refuses to exit.
   void refreshOtherAgents();
   setInterval(() => void refreshOtherAgents(), OTHER_AGENTS_MS).unref();
+  // …and the background shells (#360): a local file, so cheap enough to read every second.
+  refreshShells();
+  setInterval(refreshShells, SHELLS_MS).unref();
 
   const cwd = resolve(process.cwd());
   const history = await loadSession(cwd);
@@ -14035,6 +14127,10 @@ async function main() {
       await runModelDoctor();
       continue;
     }
+    if (line === "/shells") {
+      await showShells();
+      continue;
+    }
     if (line === "/model") {
       await chooseModel();
       continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.825",
+  "version": "1.0.827",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -124,6 +124,7 @@
     "update-verify.mjs",
     "skills.mjs",
     "skill-source.mjs",
+    "shell-details.mjs",
     "step-group.mjs",
     "mcp-config.mjs",
     "mcp-command.mjs",

package/shell-details.mjs

@@ -0,0 +1,224 @@
+// BACKGROUND SHELLS IN THE TERMINAL (task #360, GitHub #140) — Claude Code's "Shell details".
+//
+// The agent hands a long command (a 7-minute `fastlane ios beta`) off to the background instead
+// of killing it at its deadline, and records it in ~/.gonext/shells.json (gonext_agent_chat.py,
+// BACKGROUND SHELLS). This module is the terminal's half: it reads that file, says on the bottom
+// notice row that something is still running (a click target, like the other notice controls),
+// and renders the details view — Status, Runtime, Command, Output — the way Claude Code does.
+//
+// Pure except for the small fs/process probes, which take their inputs as arguments where a test
+// needs to fake them. The agent process is gone by the time a shell is looked at, so the state is
+// read from the same two facts the agent uses: is the process group alive, and has the shell
+// written its exit file.
+
+import { existsSync, openSync, readSync, closeSync, fstatSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const shellsPath = (home = homedir()) => join(home, ".gonext", "shells.json");
+
+export function readShells(path = shellsPath()) {
+  try {
+    const shells = JSON.parse(readFileSync(path, "utf8"))?.shells;
+    return Array.isArray(shells) ? shells.filter((s) => s && s.pid) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** {code, at} from the exit file, or null while the shell has not written one. */
+export function readExit(rec) {
+  const path = rec?.exit_file;
+  if (!path) return null;
+  try {
+    const raw = readFileSync(path, "utf8").trim();
+    if (!/^-?\d+$/.test(raw)) return null;
+    return { code: Number(raw), at: statSync(path).mtimeMs / 1000 };
+  } catch {
+    return null;
+  }
+}
+
+/** Is the shell's process group (POSIX) or process (Windows) still there? */
+export function isAlive(rec, platform = process.platform) {
+  const pid = Number(rec?.pgid || rec?.pid || 0);
+  if (!pid) return false;
+  try {
+    process.kill(platform === "win32" ? pid : -pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM"; // exists, just not ours to signal
+  }
+}
+
+/**
+ * {state, code, runtime, ended}. state: running | exited | failed | killed | ended (gone, exit
+ * code unknown). The same rules as the agent's _shell_state, so both sides tell the same story.
+ */
+export function shellState(rec, { alive, exit, now = Date.now() / 1000 } = {}) {
+  const started = rec?.started != null ? Number(rec.started) : now;
+  const ex = exit === undefined ? readExit(rec) : exit;
+  const live = alive === undefined ? !ex && isAlive(rec) : alive;
+  if (live && !ex && !rec?.killed) return { state: "running", code: null, runtime: Math.max(0, now - started), ended: now };
+  const ended = Number(rec?.ended) || ex?.at || now;
+  const state = rec?.killed ? "killed" : !ex ? "ended" : ex.code === 0 ? "exited" : "failed";
+  return { state, code: ex ? ex.code : null, runtime: Math.max(0, ended - started), ended };
+}
+
+/** 7m 2s — Claude Code's spelling. */
+export function fmtRuntime(seconds) {
+  let s = Math.max(0, Math.floor(Number(seconds) || 0));
+  const h = Math.floor(s / 3600);
+  s -= h * 3600;
+  const m = Math.floor(s / 60);
+  s -= m * 60;
+  return h ? `${h}h ${m}m` : m ? `${m}m ${s}s` : `${s}s`;
+}
+
+export function statusText(st) {
+  if (st.state === "running") return "running";
+  if (st.state === "exited" || st.state === "failed") return `exited ${st.code}`;
+  return st.state === "killed" ? "killed" : "ended (exit code unknown)";
+}
+
+/**
+ * The bottom notice row's shell control, or null. Running shells first — that is the thing worth
+ * a row. Otherwise the newest one that finished while this terminal was open and that the user
+ * has not opened yet, so a build that ends between questions is not missed.
+ */
+export function shellsNotice(entries, { viewed = new Set(), since = 0 } = {}) {
+  const running = entries.filter((e) => e.st.state === "running");
+  if (running.length) {
+    const one = running.length === 1;
+    // No runtime here: it would change the row every second, and the bar repaints on change.
+    return { tone: "accent", text: `${running.length} shell${one ? "" : "s"} running (click)` };
+  }
+  const done = entries.filter((e) => !viewed.has(String(e.rec.id)) && e.st.ended >= since);
+  if (!done.length) return null;
+  const last = done[done.length - 1];
+  const ok = last.st.state === "exited";
+  return { tone: ok ? "accent" : "warn", text: `shell ${statusText(last.st)} (click)` };
+}
+
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
+
+/**
+ * The last `lines` lines of a log, as they would read on a terminal: colour codes stripped, and a
+ * progress bar redrawn with \r collapsed to its final state (a build log is mostly those).
+ */
+export function logTail(path, { lines = 15, maxBytes = 64 * 1024 } = {}) {
+  let text = "";
+  try {
+    const fd = openSync(path, "r");
+    try {
+      const size = fstatSync(fd).size;
+      const len = Math.min(size, maxBytes);
+      const buf = Buffer.alloc(len);
+      readSync(fd, buf, 0, len, size - len);
+      text = buf.toString("utf8");
+      if (size > len) text = text.slice(text.indexOf("\n") + 1); // drop the cut first line
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return [];
+  }
+  const out = text
+    .replace(ANSI_RE, "")
+    .split("\n")
+    .map((l) => {
+      const parts = l.split("\r").filter((p) => p.length);
+      return (parts[parts.length - 1] ?? "").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "").trimEnd();
+    });
+  while (out.length && !out[out.length - 1]) out.pop();
+  return out.slice(-lines);
+}
+
+/** Word-wrap `text` to `width`; at most `maxRows`, the last ending in "…" when cut. */
+export function wrapClip(text, width, maxRows = 4) {
+  const w = Math.max(10, width);
+  const words = String(text ?? "").replace(/\s+/g, " ").trim().split(" ");
+  const rows = [];
+  let cur = "";
+  for (let word of words) {
+    while (word.length > w) {
+      if (cur) { rows.push(cur); cur = ""; }
+      rows.push(word.slice(0, w));
+      word = word.slice(w);
+    }
+    if (!cur) cur = word;
+    else if (cur.length + 1 + word.length <= w) cur += " " + word;
+    else { rows.push(cur); cur = word; }
+  }
+  if (cur) rows.push(cur);
+  if (rows.length <= maxRows) return rows;
+  const kept = rows.slice(0, maxRows);
+  const last = kept[maxRows - 1];
+  kept[maxRows - 1] = (last.length + 2 > w ? last.slice(0, w - 2) : last) + " …";
+  return kept;
+}
+
+const LABEL_W = 10; // "Command:  " — the value column, as in Claude Code's view
+const plain = (s) => s;
+
+/**
+ * The Shell details block, one string per row, no row wider than `width`.
+ * `style`: {title, label, running, ok, bad, dim} paint functions (identity in tests).
+ */
+export function renderShellDetails({ rec, st, output = [], width = 80, gutter = "  ", style = {} }) {
+  const p = { title: plain, label: plain, running: plain, ok: plain, bad: plain, dim: plain, ...style };
+  const inner = Math.max(20, width - gutter.length);
+  const valW = inner - LABEL_W;
+  const pad = " ".repeat(LABEL_W);
+  const row = (label, value) => gutter + p.label(label.padEnd(LABEL_W)) + value;
+  const tone = st.state === "running" ? p.running : st.state === "exited" ? p.ok : st.state === "failed" ? p.bad : p.dim;
+  const cmd = wrapClip(rec?.command ?? "", valW, 4);
+  const rows = [
+    gutter + p.title("Shell details"),
+    "",
+    row("Status:", tone(statusText(st))),
+    row("Runtime:", fmtRuntime(st.runtime)),
+    row("Command:", cmd[0] ?? ""),
+    ...cmd.slice(1).map((c) => gutter + pad + c),
+  ];
+  if (rec?.workdir) rows.push(row("Folder:", p.dim(wrapClip(rec.workdir, valW, 1)[0])));
+  rows.push("", gutter + p.label("Output:"));
+  if (!output.length) rows.push(gutter + p.dim("No output available"));
+  else for (const l of output) rows.push(gutter + (l.length > inner ? l.slice(0, inner - 1) + "…" : l));
+  return rows;
+}
+
+/** A picker row for one shell: status · runtime · command, clipped to `width`. */
+export function shellPickerLabel(rec, st, width = 80) {
+  const head = `${statusText(st)} · ${fmtRuntime(st.runtime)} · `;
+  const room = Math.max(10, width - head.length - 8);
+  const cmd = String(rec?.command ?? "").replace(/\s+/g, " ");
+  return head + (cmd.length > room ? cmd.slice(0, room - 1) + "…" : cmd);
+}
+
+/**
+ * Stop a shell's whole group and record that it was killed — the record is what the agent reads
+ * next turn, so "killed" must not later read as "ended (exit code unknown)".
+ */
+export async function killShell(rec, { path = shellsPath(), platform = process.platform } = {}) {
+  const pid = Number(rec?.pgid || rec?.pid || 0);
+  if (pid && isAlive(rec, platform)) {
+    if (platform === "win32") {
+      spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+    } else {
+      try { process.kill(-pid, "SIGTERM"); } catch { /* gone already */ }
+      for (let i = 0; i < 10 && isAlive(rec, platform); i++) await new Promise((r) => setTimeout(r, 100));
+      if (isAlive(rec, platform)) try { process.kill(-pid, "SIGKILL"); } catch { /* gone */ }
+    }
+  }
+  if (!existsSync(path)) return;
+  const shells = readShells(path);
+  const mine = shells.find((s) => String(s.id) === String(rec.id));
+  if (!mine || readExit(mine)) return; // it finished on its own first: keep the real exit code
+  mine.killed = true;
+  mine.ended = Date.now() / 1000;
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ shells }, null, 2));
+  renameSync(tmp, path);
+}