@tiens.nguyen/gu-cli 1.0.833 → 1.0.835

package/gonext_agent_chat.py

@@ -8052,6 +8052,30 @@ def _run_command_prompt_line(shell, windows=None):
         "RUNNING — stop_server closes it. " + _BG_LINE)
 
 
+# THE BROWSER (task #363, GitHub #144): a real Chrome the agent drives through the gu extension.
+# Offered only where commands may run (the terminal's own folders, never the web app's scratch one)
+# and node can start the bridge. GU_BROWSER=0 turns it off.
+def _browser_on() -> bool:
+    if os.environ.get("GU_BROWSER", "1").strip() == "0":
+        return False
+    if not any(w.get("allowRun") for w in _WS_ROOTS):
+        return False
+    import shutil as _sh
+    return bool(os.environ.get("GU_NODE") or _sh.which("node"))
+
+
+_BROWSER_LINE = (
+    "    UI CHECKS — THE BROWSER: to see, test or operate a web page (does the page render, does "
+    "the button work, does the form submit, what does the user see), use browser(...): a REAL "
+    "Chrome with a real mouse and keyboard. Loop: browser(\"open\", url=…) → browser(\"read\") "
+    "(text + numbered elements) or browser(\"screenshot\") → browser(\"click\", ref=n) / "
+    "browser(\"type\", ref=n, text=…) → read again to check the result; browser(\"console\") shows "
+    "page errors. A local app needs its server running first (run_command background=True). "
+    "Never report a UI as working without looking at it. The first browser call asks the user's "
+    "permission (nothing to install: without the gu extension it opens gu's own Chrome window). "
+    "If the user says no, or it answers BROWSER NOT AVAILABLE, stop and tell the user.\n")
+
+
 # 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 "
@@ -8701,6 +8725,8 @@ def _ws_request_approval(api_base, worker_key, job_id, command, reason, deadline
         _emit({"type": "step", "text": "Awaiting your choice: compact the context?"})
     elif command.startswith("__S3SETUP__::"):
         _emit({"type": "step", "text": "Awaiting your choice: set up S3, or save on this computer?"})
+    elif command.startswith("__BROWSER__::"):
+        _emit({"type": "step", "text": "Awaiting your approval: use a web browser"})
     elif command.startswith("__MCPTOOL__::"):
         _srv, _, _rest = command[len("__MCPTOOL__::"):].partition("\t")
         _emit({"type": "step", "text": f"Awaiting your approval: MCP tool {_srv}/{_rest.split(chr(9))[0]}"})
@@ -8918,6 +8944,90 @@ def _ws_pgroup_pids(pgid: int) -> list:
         return []
 
 
+# A SAVED PGID IS ONLY OURS WHILE ITS LEADER IS THE PROCESS WE STARTED (task #373, GitHub #154).
+# shells.json / servers.json outlive their commands. After a reboot, a crash or a closed terminal
+# the id is free, and the OS hands it to the next program — an Electron app such as VS Code is its
+# own group leader — so "a group with that id exists" said "running" and a stop SIGTERMed that
+# app. The record's own start time is the proof: a process whose pid == the pgid must have started
+# when the record says (± _WS_START_SLACK). The leader gone but members left is still ours: an id
+# is never reused while a process group of that id exists.
+_WS_START_SLACK = 5.0
+
+
+def _ws_proc_start(pid: int):
+    """When process `pid` started (epoch seconds), None when there is no such process, or "" when
+    it cannot be told (no ps). POSIX ps lstart: the same spelling on macOS and procps."""
+    import subprocess
+    import time as _t
+    try:
+        out = subprocess.run(["ps", "-o", "lstart=", "-p", str(int(pid))], stdout=subprocess.PIPE,
+                             stderr=subprocess.DEVNULL, text=True, timeout=5,
+                             env={**os.environ, "LC_ALL": "C", "LANG": "C"})
+    except Exception:  # noqa: BLE001
+        return ""
+    raw = " ".join(out.stdout.split())
+    if not raw:
+        return None
+    try:
+        return _t.mktime(_t.strptime(raw, "%a %b %d %H:%M:%S %Y"))
+    except ValueError:
+        return ""
+
+
+def _ws_record_started(rec: dict):
+    """The record's start time (epoch), from `started`, else the older `started_at` string."""
+    import time as _t
+    try:
+        if rec.get("started") is not None:
+            return float(rec["started"])
+    except (TypeError, ValueError):
+        pass
+    try:
+        return _t.mktime(_t.strptime(str(rec.get("started_at")), "%Y-%m-%d %H:%M:%S"))
+    except (ValueError, OverflowError):
+        return None
+
+
+def _ws_group_owner(rec: dict, proc_start=None) -> str:
+    """Whose is the group a shell/server record names now?
+      "ours"    — its leader is the process the record started;
+      "leader-gone" — no process has that id; any group members left are still ours;
+      "other"   — that id now belongs to a process started at another time: NOT ours;
+      "unknown" — nothing to compare (no start time recorded, or ps could not say).
+    Windows has no process groups; its records are taken as they are."""
+    if _IS_WINDOWS:
+        return "ours"
+    pgid = int(rec.get("pgid") or rec.get("pid") or 0)
+    if pgid <= 0:
+        return "unknown"
+    leader = (proc_start or _ws_proc_start)(pgid)
+    if leader is None:
+        return "leader-gone"
+    started = _ws_record_started(rec)
+    if leader == "" or started is None:
+        return "unknown"
+    return "ours" if abs(float(leader) - started) <= _WS_START_SLACK else "other"
+
+
+def _ws_record_pids(rec: dict) -> list:
+    """Live pids of a record's group — none when the id has passed to another program."""
+    if _ws_group_owner(rec) == "other":
+        return []
+    return _ws_pgroup_pids(int(rec.get("pgid") or rec.get("pid") or 0))
+
+
+def _ws_stop_record(rec: dict, force: bool = False) -> bool:
+    """Signal a record's group ONLY when it is provably ours. False = nothing was signalled."""
+    owner = _ws_group_owner(rec)
+    pgid = int(rec.get("pgid") or rec.get("pid") or 0)
+    if owner not in ("ours", "leader-gone") or pgid <= 0:
+        _log(f"not stopping pgid={pgid} ('{str(rec.get('command'))[:40]}'): {owner} — the id is no "
+             "longer the process gu started")
+        return False
+    _ws_kill_tree(pgid, force=force)
+    return True
+
+
 def _ws_parse_netstat_ports(stdout: str, pids: set) -> list:
     """LISTENING ports owned by `pids`, from `netstat -ano` output. Pure, so it is testable
     on a Mac against recorded Windows output — running netstat here is not."""
@@ -9030,7 +9140,7 @@ def _ws_load_servers(prune: bool = True) -> list:
     except Exception:  # noqa: BLE001
         return []
     if prune:
-        servers = [s for s in servers if _ws_pgroup_pids(int(s.get("pgid", 0)))]
+        servers = [s for s in servers if _ws_record_pids(s)]
     return servers
 
 
@@ -9056,10 +9166,8 @@ def _ws_cap_servers(max_live: int = 3) -> list:
     if len(servers) > max_live:
         for s in servers[:-max_live]:  # registry is append-ordered → oldest first
             try:
-                pgid = int(s.get("pgid", 0))
-                if pgid <= 0:
+                if not _ws_stop_record(s):
                     continue
-                _ws_kill_tree(pgid)
                 _log(f"server lifecycle: stopped old background server pid={s.get('pid')} "
                      f"ports={s.get('ports')} ('{str(s.get('command'))[:40]}')")
             except (OSError, ValueError) as e:  # already gone / no permission
@@ -9145,7 +9253,7 @@ def _shell_state(s: dict, alive=None, now=None) -> dict:
     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)))
+        alive = code is None and bool(_ws_record_pids(s))
     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)
@@ -9155,7 +9263,8 @@ def _shell_state(s: dict, alive=None, now=None) -> dict:
         state = "ended"
     else:
         state = "exited" if code == 0 else "failed"
-    return {"state": state, "code": code, "runtime": max(0.0, ended - started), "ended": ended}
+    return {"state": state, "code": code, "runtime": max(0.0, ended - started), "ended": ended,
+            "by": s.get("killed_by") or ""}
 
 
 def _fmt_runtime(seconds: float) -> str:
@@ -9171,7 +9280,11 @@ def _shell_status_text(st: dict) -> str:
         return "running"
     if st["state"] in ("exited", "failed"):
         return f"exited {st['code']}"
-    return "killed" if st["state"] == "killed" else "ended (exit code unknown)"
+    # WHO STOPPED IT (#362/#143). A bare "killed" read as a crash — "shell got status killed why?"
+    # — when the agent had stopped its own search on purpose. Every stop says who did it.
+    if st["state"] == "killed":
+        return f"killed — stopped by {st['by']}" if st.get("by") else "killed"
+    return "ended (exit code unknown)"
 
 
 def _shell_find(shells: list, key: str):
@@ -9298,22 +9411,65 @@ def _file_tail(path: str, max_chars: int = 4000) -> str:
         return ""
 
 
-def _shell_kill(s: dict) -> None:
+def _shell_kill(s: dict, by: str = "the agent (stop_server)") -> 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)
+        if _ws_stop_record(s):
+            _t.sleep(1.0)
+            if _ws_record_pids(s):
+                _ws_stop_record(s, force=True)
     except (OSError, ValueError):
         pass
     s["killed"] = True
+    s["killed_by"] = by
     s["ended"] = _t.time()
 
 
+# A SHELL THAT FINISHES IS NEWS (#362), the way Claude Code tells its model "background command X
+# completed". During a turn the note rides on the next observation (append-only — no cache
+# break); after the turn the terminal starts a short recap turn (gu-repl.mjs, wakeForShells).
+# `announced` stops both from telling twice; `seen` means the agent already read the final state.
+def _shells_in_scope(shells: list, roots=None) -> list:
+    """The shells started inside these folders (default: the registered workspaces) — shells.json
+    is one file for every project, and another project's build is not this turn's news."""
+    paths = [os.path.realpath(r["path"]) for r in (_WS_ROOTS if roots is None else roots)
+             if isinstance(r, dict) and r.get("path")]
+    out = []
+    for s in shells:
+        wd = os.path.realpath(str(s.get("workdir") or ""))
+        if any(wd == p or wd.startswith(p.rstrip(os.sep) + os.sep) for p in paths):
+            out.append(s)
+    return out
+
+
+def _shells_finished_note(shells: list, now=None) -> str:
+    """Notes for shells that finished and were neither read nor announced; marks them announced
+    in `shells` (the caller saves). "" when there is nothing new."""
+    notes = []
+    for s in shells:
+        if s.get("seen") or s.get("announced"):
+            continue
+        st = _shell_state(s, now=now)
+        if st["state"] == "running":
+            continue
+        s["announced"] = True
+        note = (f"[background shell {s.get('id')} finished: {_shell_status_text(st)} after "
+                f"{_fmt_runtime(st['runtime'])} — '{_clip(str(s.get('command')), 120)}'. "
+                f"shell_output('{s.get('id')}') has its output.]")
+        try:
+            with open(s.get("log") or "", encoding="utf-8", errors="replace") as fh:
+                dg = _test_digest(fh.read(), str(s.get("workdir") or ""))
+            if dg:
+                note += "\n" + dg
+        except OSError:
+            pass
+        notes.append(note)
+    return "\n\n".join(notes)
+
+
 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."""
@@ -10725,7 +10881,7 @@ def run_agent_chat(cfg):
         except Exception as _e:  # noqa: BLE001
             _log(f"server context skip: {_e}")
         try:
-            _ws_servers_line += _shells_context_line(_shells_load())
+            _ws_servers_line += _shells_context_line(_shells_in_scope(_shells_load()))
         except Exception as _e:  # noqa: BLE001
             _log(f"shell context skip: {_e}")
     _ws_tests_line = ""
@@ -10792,7 +10948,8 @@ def run_agent_chat(cfg):
         "and reads do not pile up here and are not re-sent on every later step. Then read only "
         "the exact ranges you will edit. Use grep_repo/read_file_lines directly when you already "
         "know the file or the exact string.\n"
-        + _run_command_prompt_line(bool(_run_shell_bin())) +
+        + _run_command_prompt_line(bool(_run_shell_bin()))
+        + (_BROWSER_LINE if _browser_on() else "") +
         "    DEPLOY: prefer deploy_web(local_dir, host, user, remote_path, domain) over "
         "hand-written scp/ssh/rsync (it rsyncs over your SSH key and finishes nginx when it "
         "can, else writes deploy.sh and returns the exact commands). KEY auth ONLY "
@@ -11871,9 +12028,38 @@ def run_agent_chat(cfg):
             saved += _trim_tool_call_args(_st, 120)
         return saved
 
+    _browser_shot = {"img": None}  # the browser tool's newest screenshot, for this step (#363)
+
     def step_callback(step_log):
         step_num = getattr(step_log, "step_number", "?")
 
+        # A browser screenshot taken in this step goes to the model as an image with the step's
+        # observation (#363). Only the newest two stay in memory: every image is re-sent on every
+        # later step, and an old view of a page that has since changed only misleads.
+        try:
+            if _browser_shot.get("img") is not None:
+                step_log.observations_images = [_browser_shot["img"]]
+                _browser_shot["img"] = None
+                _with = [s for s in (getattr(getattr(_agent_ref.get("a"), "memory", None), "steps", None) or [])
+                         if getattr(s, "observations_images", None) and s is not step_log]
+                for _old in _with[:-1]:
+                    _old.observations_images = None
+        except Exception as e:  # noqa: BLE001
+            _log(f"browser screenshot attach skip: {e}")
+
+        # A background shell that finished during this step is told to the model now (#362).
+        try:
+            _obs_now = getattr(step_log, "observations", None)
+            if isinstance(_obs_now, str):
+                _shs = _shells_load()
+                _fin = _shells_finished_note(_shells_in_scope(_shs))
+                if _fin:
+                    step_log.observations = _obs_now + "\n\n" + _fin
+                    _shells_save(_shs)
+                    _log(f"step {step_num}: told the model a background shell finished")
+        except Exception as e:  # noqa: BLE001
+            _log(f"shell-finished note skip: {e}")
+
         # Task #74: an executor-timeout error means whatever the step's tool call
         # achieved was NEVER reported to the model (a create_pdf may have finished —
         # or may still be finishing — in the background). Flag it so a repeat
@@ -15255,12 +15441,11 @@ def run_agent_chat(cfg):
                         return msg
                 else:
                     target = servers[-1]
-                pgid = int(target["pgid"])
                 try:
-                    _ws_kill_tree(pgid)
-                    _t.sleep(1.5)
-                    if _ws_pgroup_pids(pgid):
-                        _ws_kill_tree(pgid, force=True)
+                    if _ws_stop_record(target):
+                        _t.sleep(1.5)
+                        if _ws_record_pids(target):
+                            _ws_stop_record(target, force=True)
                 except OSError:
                     pass
                 _ws_save_servers([s for s in servers if s is not target])
@@ -15476,6 +15661,125 @@ def run_agent_chat(cfg):
                 _last_obs["text"] = msg
                 return msg
 
+        # ASK FIRST (#150), the way Claude Code does: the first browser call of a turn asks the user
+        # (Allow once / Always in this folder / No), unless this folder is on the "always" list in
+        # ~/.gonext/browser-allow.json. A "No" holds for the rest of the turn.
+        _browser_consent = {"ok": False, "no": False, "where": ""}
+
+        def _browser_ask(what: str):
+            """→ "" when the browser may be used, else the message for the model."""
+            import gu_browser as _gb
+            if _browser_consent["ok"]:
+                return ""
+            if _browser_consent["no"]:
+                return ("The user did not allow the browser in this turn. Do not call browser again; "
+                        "carry on without it, or ask the user.")
+            folder = _WS_ACTIVE or _default_ws_root()
+            if _gb.allowed_in(folder):
+                _browser_consent["ok"] = True
+                return ""
+            if not (_interactive_approval and _job_id and worker_api_base and worker_api_key):
+                return ("The browser needs the user's permission and this session cannot ask. Tell the "
+                        "user to allow it (/browser allow in the gu terminal), then carry on without it.")
+            if _ws_request_approval(worker_api_base, worker_api_key, _job_id,
+                                    f"__BROWSER__::{folder}\t{what}", "", deadline_s=180):
+                _browser_consent["ok"] = True
+                return ""
+            _browser_consent["no"] = True
+            return ("The user did not allow the browser. Do not call browser again this turn; carry on "
+                    "without it, or ask the user.")
+
+        @tool
+        def browser(action: str, url: str = "", ref: int = 0, x: int = -1, y: int = -1,
+                    text: str = "", clear: bool = False, submit: bool = False,
+                    direction: str = "", amount: int = 0, seconds: int = 0, tab: str = "",
+                    new_tab: bool = False) -> str:
+            """Use a REAL Chrome browser like a person does — open a page, see it, click with the mouse, type with the keyboard — to test a UI flow, check a page renders, fill a form or click through an app. The first call asks the user's permission. It uses the user's Chrome through the gu extension when that is installed, otherwise gu's own Chrome window (a separate profile: not logged in to the user's accounts). Loop: open → read (or screenshot) → click / type → read again to check what happened. Only gu's own tabs, and tabs the user shared, are used. If the answer starts BROWSER NOT AVAILABLE, stop and tell the user (the answer says what to do).
+
+            Args:
+                action: one of: open (url) · read (page text + visible interactive elements numbered [n] with x,y) · screenshot (an image of the page; pixels = click x,y) · click / double_click / right_click / hover (ref, or x and y) · type (text into the focused field; with ref it clicks that field first) · key (text: "Enter", "Tab", "Escape", "ctrl+a", "shift+Tab"… several separated by spaces) · scroll (direction, amount) · back · reload · wait (seconds) · js (text = a JavaScript expression run in the page; returns its value) · console (the page's console messages since the last call) · tabs · switch (tab) · close
+                url: for open — a full http(s):// or file:// url (localhost:3000 is taken as http://localhost:3000)
+                ref: an element's [n] from the last read, for click/hover/type
+                x: page x coordinate for click/hover (from read's @x,y or the screenshot), when no ref
+                y: page y coordinate, with x
+                text: what to type (type), the key(s) to press (key), or the JavaScript expression (js)
+                clear: type only — replace the field's current value instead of adding to it
+                submit: type only — press Enter after typing
+                direction: scroll only — down (default), up, left or right
+                amount: scroll only — pixels (default most of a screen)
+                seconds: wait only — 1 to 30
+                tab: switch only — a tab id from tabs (a number, or an id like "8F3A…" in gu's own window)
+                new_tab: open only — open in a new tab instead of the current gu tab
+            """
+            import gu_browser as _gb
+            a = (action or "").strip().lower().replace(" ", "_").replace("-", "_")
+            try:
+                cmd = {"action": a}
+                if url:
+                    u = url.strip()
+                    if re.match(r"^(localhost|127\.0\.0\.1|0\.0\.0\.0)(:\d+)?(/|$)", u):
+                        u = "http://" + u
+                    elif u.startswith("/") and os.path.exists(u):
+                        u = "file://" + u
+                    cmd["url"] = u
+                if ref:
+                    cmd["ref"] = int(ref)
+                if x is not None and y is not None and int(x) >= 0 and int(y) >= 0:
+                    cmd["x"], cmd["y"] = float(x), float(y)
+                if text:
+                    cmd["text"] = str(text)
+                for k, v in (("clear", clear), ("submit", submit), ("new_tab", new_tab)):
+                    if v:
+                        cmd[k] = True
+                if direction:
+                    cmd["direction"] = direction
+                if amount:
+                    cmd["amount"] = int(amount)
+                if seconds:
+                    cmd["seconds"] = int(seconds)
+                if tab:
+                    cmd["tab"] = int(tab) if str(tab).strip().isdigit() else str(tab).strip()
+                shot_ok = a == "screenshot" and (
+                    _is_anthropic_url(coding_base_url) or _coder_takes_images(coding_base_url, coding_model_id))
+                if a == "screenshot" and not shot_ok:
+                    cmd["action"] = "read"  # this model is not sent images: it gets the page as text
+                what = cmd.get("url") or (f"[{ref}]" if ref else f"{int(x)},{int(y)}" if "x" in cmd else
+                                          _clip(str(text), 50) if text else "")
+                _emit({"type": "step", "text": f"Browser {a}" + (f" → {what}" if what else "")})
+                refused = _browser_ask(f"{a} {what}".strip())
+                if refused:
+                    _last_obs["text"] = refused
+                    return refused
+                ok, res, not_connected = _gb.command(
+                    cmd, log=_log, own=True,
+                    on_wait=lambda: _emit({"type": "step", "text": "Waiting for Chrome to connect…"}))
+                where = res.pop("_backend", "") if ok and isinstance(res, dict) else ""
+                if where and where != _browser_consent["where"]:
+                    _browser_consent["where"] = where
+                    _emit({"type": "step", "text": "Using gu's own Chrome window" if where == "chrome"
+                           else "Using your Chrome (gu extension)"})
+                if not_connected:
+                    _emit({"type": "step", "text": "⚠ No browser gu can use — /browser shows why"})
+                    msg = _gb.install_text(str(res))
+                elif not ok:
+                    msg = f"Error: browser {a} failed: {res}"
+                elif a == "screenshot" and shot_ok:
+                    im, note = _gb.decode_screenshot(res, _IMAGE_MAX_EDGE)
+                    _browser_shot["img"] = im
+                    msg = _gb.format_result("screenshot", res) + "\n" + note + " The image is attached to this observation."
+                elif a == "screenshot":
+                    msg = ("(This coding model is not sent images, so here is the page as text.)\n"
+                           + _gb.format_result("read", res))
+                else:
+                    msg = _gb.format_result(a, res)
+                if ok and where == "chrome" and a == "open":
+                    msg = ("(gu's own Chrome window — a separate profile, not signed in to the user's "
+                           "accounts.)\n" + msg)
+            except Exception as ex:  # noqa: BLE001
+                msg = f"Error: browser {a} failed: {type(ex).__name__}: {ex}"
+            _last_obs["text"] = msg
+            return msg
+
         agent_tools = [http_request, web_search, fetch_url, calculate,
                        get_current_datetime, create_pdf, create_download]
         # Only register the PDF reader / email / RAG tools when available — the model
@@ -15496,6 +15800,8 @@ def run_agent_chat(cfg):
             agent_tools += [symbol_context, grep_repo, read_file_lines, edit_lines, edit_file,
                             create_file, create_folder, run_command, stop_server,
                             shell_output, deploy_web]
+            if _browser_on():
+                agent_tools.append(browser)
             # 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-cli.mjs

@@ -74,6 +74,9 @@ function skillsAndMcpForJob(cwd) {
 }
 
 const WORKER_DIR = dirname(fileURLToPath(import.meta.url));
+// The agent's browser tool starts browser-bridge.mjs with THIS node (#363): a launchd/systemd worker
+// often has no node on PATH.
+process.env.GU_NODE ||= process.execPath;
 
 // Running worker version, read from the package's own package.json (single source of
 // truth) so the startup banner shows exactly which build a box is running (task #105).
@@ -851,8 +854,9 @@ const currentApiVersion = async () => {
     }
     // RESTART LAST, and only after the new version can actually run — currentVersion() now
     // refuses a deps-less directory, so a failed install above leaves the old one serving.
-    const pid = Number((await readFile(ce.API_PID_FILE, "utf8").catch(() => "")).trim());
-    if (Number.isFinite(pid) && pid > 0) {
+    // Only while the pid on record is still the local API (#373): a stale file's id may be another program's.
+    const { pid } = await ce.apiPidToStop();
+    if (pid) {
       try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
       // WAIT FOR THE PORT, not just for the signal. SIGTERM returns immediately and the old
       // server keeps the socket for a moment; starting the new one into that gap fails as
@@ -880,9 +884,9 @@ const currentApiVersion = async () => {
   }
 
   if (sub === "stop") {
-    const pid = Number((await readFile(ce.API_PID_FILE, "utf8").catch(() => "")).trim());
-    if (!Number.isFinite(pid) || pid <= 0) {
-      console.log("\n  No local API pid on record.\n");
+    const { pid, why } = await ce.apiPidToStop();
+    if (!pid) {
+      console.log(`\n  Nothing stopped: ${why}.\n`);
       process.exit(0);
     }
     try {
@@ -943,9 +947,9 @@ const currentApiVersion = async () => {
    * ANSWERING before starting the new one.
    */
   if (sub === "restart") {
-    const pid = Number((await readFile(ce.API_PID_FILE, "utf8").catch(() => "")).trim());
+    const { pid } = await ce.apiPidToStop();
     const before = await ce.probeLocalApi();
-    if (Number.isFinite(pid) && pid > 0) {
+    if (pid) {
       try {
         process.kill(pid, "SIGTERM");
         console.log(`\n  Stopping the local API (pid ${pid})…`);
@@ -961,7 +965,7 @@ const currentApiVersion = async () => {
       // Answering, but we have no pid to signal — started by hand, or the file was lost. Say so
       // rather than starting a SECOND one on the same port and reporting success.
       console.log(
-        `\n  The API is answering on ${ce.LOCAL_API_BASE} but there is no pid on record,` +
+        `\n  The API is answering on ${ce.LOCAL_API_BASE} but no pid on record is still it,` +
           "\n  so it cannot be stopped from here. Stop it yourself, then: gu-cli api start\n"
       );
       process.exit(1);
@@ -1289,10 +1293,8 @@ if (args[0] === "clear" || args[0] === "reset") {
   // nothing on the machine any longer knows about.
   if (groups.includes("identity")) {
     const ce = await import("./client-expert-api.mjs");
-    const pid = Number(
-      (await readFile(ce.API_PID_FILE, "utf8").catch(() => "")).trim()
-    );
-    if (Number.isFinite(pid) && pid > 0) {
+    const { pid } = await ce.apiPidToStop();
+    if (pid) {
       try {
         process.kill(pid, "SIGTERM");
         console.log(`stopped the local API (pid ${pid})`);