@tiens.nguyen/gu-cli 1.0.832 → 1.0.834

package/gu_test_digest.py

@@ -0,0 +1,352 @@
+"""Test-result digest for run_command (task #362, GitHub #142) — PURE.
+
+THE MODEL READ TEST OUTPUT THROUGH `| tail` AND `| grep`. Measured 2026-09-23 → 10-14 in local
+Mongo: 84 of 397 turns ran tests, 32 of them spent 4+ steps doing it, and test output was piped
+into tail/head/grep to find the result — the pipe that hid `No module named pytest` and let a
+commit go in untested (#140 review). The answer is not a smaller window onto the output; it is
+the result first: the counts, then each failing test with its message and file:line, computed
+from the WHOLE output (the observation itself is capped, a digest never is).
+
+One parser per runner, each recognising its own summary line, so a line that runs two runners
+(`python3 -m unittest … && node --test`, this repo's npm test) gets both. Nothing recognised →
+"" and the output is shown exactly as before. Names are the ones the runner prints, which are the
+ones its run-one-test form takes (unittest's dotted id, pytest's node id, go's TestName…).
+"""
+from __future__ import annotations
+
+import os
+import re
+
+MAX_FAILURES = 10      # per runner; the rest are counted
+MAX_MESSAGE = 220      # chars of one failure's message
+
+
+def _clip(text: str, n: int = MAX_MESSAGE) -> str:
+    # Line breaks become one space; runs of spaces INSIDE a line stay — 'GU  AGENT' vs 'GU AGENT'
+    # is the whole failure, and collapsing it printed two identical strings.
+    text = re.sub(r"[ \t]*\n[ \t]*", " ", (text or "").strip())
+    return text if len(text) <= n else text[: n - 1] + "…"
+
+
+def _rel(path: str, cwd: str) -> str:
+    path = (path or "").strip().strip("'\"")
+    if path.startswith("file://"):
+        path = path[7:]
+    if cwd:
+        for base in {cwd, os.path.realpath(cwd)}:
+            if base and path.startswith(base.rstrip("/") + "/"):
+                return path[len(base.rstrip("/")) + 1:]
+    return path
+
+
+def _fail(name, message="", where="") -> dict:
+    return {"name": _clip(name, 160), "message": _clip(message), "where": where}
+
+
+# ---- node --test, spec reporter (the default) ---------------------------------------------------
+_NODE_SPEC_SUM = re.compile(r"^ℹ (tests|pass|fail|skipped|todo|cancelled) (\d+)\s*$", re.M)
+
+
+def _node_spec(out: str, cwd: str):
+    counts = {}
+    for k, v in _NODE_SPEC_SUM.findall(out):
+        counts[k] = counts.get(k, 0) + int(v)
+    if "tests" not in counts:
+        return None
+    fails = []
+    block = out.split("✖ failing tests:", 1)
+    if len(block) == 2:
+        # "test at FILE:L:C" / "✖ name (ms)" / indented message lines, until the next "test at".
+        for m in re.finditer(r"^test at (\S+?):(\d+):\d+\n✖ (.+?) \([\d.]+m?s\)[^\n]*\n((?:[ \t].*\n?|\n)*)",
+                             block[1], re.M):
+            body = [ln.strip() for ln in m.group(4).splitlines()]
+            msg = []
+            for ln in body:
+                if ln.startswith("at ") or ln.startswith("{") or ln.startswith("generatedMessage"):
+                    break
+                if ln and ln not in ("+ actual - expected", "^"):
+                    msg.append(ln)
+            text = " ".join(msg[:5])
+            if text.strip("'\"") == "test failed":
+                # A FILE that failed to load: the runner only says 'test failed'; the cause
+                # (ERR_MODULE_NOT_FOUND, a SyntaxError) was printed above the summary.
+                err = re.search(r"^(\w*Error\b[^\n]*)$", out, re.M)
+                text = _rel_in(err.group(1), cwd) if err else text
+            fails.append(_fail(m.group(3), text, f"{_rel(m.group(1), cwd)}:{m.group(2)}"))
+    else:
+        # A file that crashed before any test ran: "✖ tests/c.test.mjs (78ms)", the error above it.
+        err = re.search(r"^(\w*Error\b[^\n]*)$", out, re.M)
+        for m in re.finditer(r"^✖ (.+?) \([\d.]+m?s\)", out, re.M):
+            fails.append(_fail(m.group(1), _rel_in(err.group(1), cwd) if err else ""))
+    return {"runner": "node --test", "passed": counts.get("pass", 0), "failed": counts.get("fail", 0),
+            "skipped": counts.get("skipped", 0) + counts.get("todo", 0), "errors": counts.get("cancelled", 0),
+            "failures": fails}
+
+
+def _rel_in(text: str, cwd: str) -> str:
+    """Absolute paths under cwd inside a message, shortened."""
+    if not cwd:
+        return text
+    for base in {cwd.rstrip("/"), os.path.realpath(cwd).rstrip("/")}:
+        text = text.replace("file://" + base + "/", "").replace(base + "/", "")
+    return text
+
+
+# ---- node --test / anything TAP ------------------------------------------------------------------
+_TAP_SUM = re.compile(r"^# (tests|pass|fail|skipped|todo|cancelled) (\d+)\s*$", re.M)
+
+
+def _tap(out: str, cwd: str):
+    counts = {}
+    for k, v in _TAP_SUM.findall(out):
+        counts[k] = counts.get(k, 0) + int(v)
+    if "tests" not in counts or "TAP version" not in out and "# Subtest" not in out:
+        return None
+    fails = []
+    for m in re.finditer(r"^[ \t]*not ok \d+ - (.+?)(?: # .*)?\n((?:[ \t]{2,}.*\n?|[ \t]*\n)*)", out, re.M):
+        yaml = m.group(2)
+        loc = re.search(r"location: '([^']+?):(\d+):\d+'", yaml)
+        err = re.search(r"error: \|-?\n((?:[ \t]{4,}.*\n?|[ \t]*\n)+)", yaml) or re.search(r"error: '([^']*)'", yaml)
+        msg = ""
+        if err:
+            msg = " ".join(ln.strip() for ln in err.group(1).splitlines()
+                           if ln.strip() and ln.strip() not in ("+ actual - expected", "^"))
+        fails.append(_fail(m.group(1), msg, f"{_rel(loc.group(1), cwd)}:{loc.group(2)}" if loc else ""))
+    return {"runner": "node --test (TAP)", "passed": counts.get("pass", 0), "failed": counts.get("fail", 0),
+            "skipped": counts.get("skipped", 0) + counts.get("todo", 0), "errors": counts.get("cancelled", 0),
+            "failures": fails}
+
+
+# ---- python unittest ------------------------------------------------------------------------------
+def _unittest(out: str, cwd: str):
+    ran = re.findall(r"^Ran (\d+) tests? in [\d.]+s\s*$", out, re.M)
+    if not ran:
+        return None
+    total = sum(int(x) for x in ran)
+    failures = errors = skipped = 0
+    for line in re.findall(r"^(?:OK|FAILED)(?: \((.*)\))?\s*$", out, re.M):
+        for k, v in re.findall(r"(\w[\w ]*?)=(\d+)", line or ""):
+            k = k.strip()
+            if k == "failures":
+                failures += int(v)
+            elif k == "errors":
+                errors += int(v)
+            elif k == "skipped":
+                skipped += int(v)
+    fails = []
+    for m in re.finditer(r"^(FAIL|ERROR): (\S+) \((\S+?)\)[^\n]*\n-{20,}\n(.*?)(?=^={20,}|^-{20,}\nRan |\Z)",
+                         out, re.M | re.S):
+        kind, short, dotted, body = m.groups()
+        lines = [ln for ln in body.rstrip().splitlines() if ln.strip()]
+        msg = lines[-1].strip() if lines else kind
+        locs = [(f, ln) for f, ln in re.findall(r'File "([^"]+)", line (\d+)', body)
+                if "/lib/python" not in f and "unittest/" not in f]
+        where = f"{_rel(locs[-1][0], cwd)}:{locs[-1][1]}" if locs else ""
+        fails.append(_fail(dotted if "." in dotted else short, msg, where))
+    return {"runner": "unittest", "passed": max(0, total - failures - errors - skipped), "failed": failures,
+            "skipped": skipped, "errors": errors, "failures": fails}
+
+
+# ---- pytest ---------------------------------------------------------------------------------------
+_PYTEST_SUM = re.compile(r"^=+ ((?:\d+ \w+(?:, )?)+) in [\d.]+s(?: \([^)]*\))? =+\s*$", re.M)
+
+
+def _pytest(out: str, cwd: str):
+    sums = _PYTEST_SUM.findall(out)
+    if not sums:
+        return None
+    c = {}
+    for k_v in ", ".join(sums).split(", "):
+        m = re.match(r"(\d+) (\w+)", k_v.strip())
+        if m:
+            c[m.group(2)] = c.get(m.group(2), 0) + int(m.group(1))
+    fails = []
+    for m in re.finditer(r"^(FAILED|ERROR) (\S+?)(?: - (.*))?$", out, re.M):
+        nodeid = m.group(2)
+        loc = re.search(rf"^({re.escape(nodeid.split('::')[0])}):(\d+): ", out, re.M)
+        fails.append(_fail(nodeid, m.group(3) or m.group(1), f"{loc.group(1)}:{loc.group(2)}" if loc else ""))
+    return {"runner": "pytest", "passed": c.get("passed", 0), "failed": c.get("failed", 0),
+            "skipped": c.get("skipped", 0) + c.get("xfailed", 0), "errors": c.get("error", 0) + c.get("errors", 0),
+            "failures": fails}
+
+
+# ---- jest / vitest --------------------------------------------------------------------------------
+def _jest(out: str, cwd: str):
+    m = re.search(r"^Tests:\s+(.*\d+ total)\s*$", out, re.M)
+    if not m:
+        return None
+    c = {k: int(v) for v, k in re.findall(r"(\d+) (\w+)", m.group(1))}
+    fails = []
+    for f in re.finditer(r"^\s*● (.+?)\n\n((?:.*\n){1,6})", out, re.M):
+        if f.group(1).startswith("Console"):
+            continue
+        msg = next((ln.strip() for ln in f.group(2).splitlines() if ln.strip()), "")
+        loc = re.search(r"\(([^()\s]+?):(\d+):\d+\)", f.group(2)) or re.search(r"at .*?([\w./-]+\.\w+):(\d+):\d+", out)
+        fails.append(_fail(f.group(1).replace(" › ", " > "), msg, f"{_rel(loc.group(1), cwd)}:{loc.group(2)}" if loc else ""))
+    return {"runner": "jest", "passed": c.get("passed", 0), "failed": c.get("failed", 0),
+            "skipped": c.get("skipped", 0) + c.get("todo", 0), "errors": 0, "failures": fails}
+
+
+def _vitest(out: str, cwd: str):
+    m = re.search(r"^\s*Tests\s+(.*?)\s*\((\d+)\)\s*$", out, re.M)
+    if not m or "|" not in m.group(1) and not re.search(r"\d+ (passed|failed)", m.group(1)):
+        return None
+    c = {k: int(v) for v, k in re.findall(r"(\d+) (\w+)", m.group(1))}
+    fails = []
+    for f in re.finditer(r"^[ \t]*FAIL[ \t]+(\S+) > (.+?)\n((?:.*\n){0,4})", out, re.M):
+        msg = next((ln.strip() for ln in f.group(3).splitlines() if re.search(r"Error|expected", ln)), "")
+        loc = re.search(r"❯ (\S+?):(\d+):\d+", f.group(3))
+        fails.append(_fail(f"{f.group(1)} > {f.group(2).strip()}", msg,
+                           f"{loc.group(1)}:{loc.group(2)}" if loc else f.group(1)))
+    if not fails:  # no "Failed Tests" section (a reporter without it): the × lines
+        for f in re.finditer(r"^[ \t]*× (.+?)(?:[ \t]+\d+ms)?\n[ \t]*→ (.*)$", out, re.M):
+            fails.append(_fail(f.group(1), f.group(2)))
+    return {"runner": "vitest", "passed": c.get("passed", 0), "failed": c.get("failed", 0),
+            "skipped": c.get("skipped", 0) + c.get("todo", 0), "errors": 0, "failures": fails}
+
+
+# ---- go test ---------------------------------------------------------------------------------------
+def _gotest(out: str, cwd: str):
+    pkgs = re.findall(r"^(ok|FAIL|---? FAIL)\s+(\S+)\s+(?:[\d.]+s|\(cached\)|\[)", out, re.M)
+    fails_raw = list(re.finditer(r"^[ \t]*--- FAIL: (\S+) \([\d.]+s\)", out, re.M))
+    if not pkgs and not fails_raw:
+        return None
+    passed = len(re.findall(r"^\s*--- PASS: ", out, re.M))
+    skipped = len(re.findall(r"^\s*--- SKIP: ", out, re.M))
+    fails = []
+    for f in fails_raw:
+        # Since Go 1.14 a test's t.Error lines are printed between its "=== RUN" and "--- FAIL".
+        run = re.search(rf"^=== RUN\s+{re.escape(f.group(1))}\n((?:[ \t]{{4,}}.*\n)*)", out, re.M)
+        first = next((ln.strip() for ln in (run.group(1) if run else "").splitlines() if ln.strip()), "")
+        loc = re.match(r"([\w./-]+\.go):(\d+): (.*)", first)
+        fails.append(_fail(f.group(1), loc.group(3) if loc else first, f"{loc.group(1)}:{loc.group(2)}" if loc else ""))
+    ok_pkgs = sum(1 for k, _ in pkgs if k == "ok")
+    bad_pkgs = sum(1 for k, _ in pkgs if k == "FAIL")
+    return {"runner": "go test", "passed": passed, "failed": len(fails_raw) or bad_pkgs, "skipped": skipped,
+            "errors": 0, "failures": fails,
+            "note": f"{ok_pkgs} package(s) ok, {bad_pkgs} FAIL" if pkgs else ""}
+
+
+# ---- cargo test ------------------------------------------------------------------------------------
+def _cargo(out: str, cwd: str):
+    res = re.findall(r"^test result: (?:ok|FAILED)\. (\d+) passed; (\d+) failed; (\d+) ignored", out, re.M)
+    if not res:
+        return None
+    p = sum(int(a) for a, _, _ in res)
+    f = sum(int(b) for _, b, _ in res)
+    s = sum(int(c) for _, _, c in res)
+    fails = []
+    for m in re.finditer(r"^---- (\S+) stdout ----\n((?:.*\n){1,4})", out, re.M):
+        body = m.group(2)
+        loc = re.search(r"panicked at ([^\s:]+):(\d+):\d+", body)
+        msg = [ln.strip() for ln in body.splitlines() if ln.strip() and "panicked at" not in ln]
+        fails.append(_fail(m.group(1), msg[0] if msg else "panicked", f"{loc.group(1)}:{loc.group(2)}" if loc else ""))
+    return {"runner": "cargo test", "passed": p, "failed": f, "skipped": s, "errors": 0, "failures": fails}
+
+
+# ---- tsc / eslint (checks, not tests — same shape: count, then the first problems) ----------------
+def _tsc(out: str, cwd: str):
+    errs = re.findall(r"^(.+?)\((\d+),\d+\): error (TS\d+): (.+)$", out, re.M)
+    if not errs:
+        return None
+    fails = [_fail(code, msg, f"{_rel(f, cwd)}:{ln}") for f, ln, code, msg in errs]
+    return {"runner": "tsc", "check": True, "errors": len(errs),
+            "files": len({e[0] for e in errs}), "failures": fails}
+
+
+def _eslint(out: str, cwd: str):
+    m = re.search(r"^✖ (\d+) problems? \((\d+) errors?, (\d+) warnings?\)", out, re.M)
+    if not m:
+        return None
+    fails, cur = [], ""
+    for ln in out.splitlines():
+        if ln and not ln.startswith(" ") and not ln.startswith("✖"):
+            cur = _rel(ln.strip(), cwd)
+            continue
+        e = re.match(r"^\s+(\d+):\d+\s+error\s+(.+?)\s{2,}(\S+)\s*$", ln)
+        if e and cur:
+            fails.append(_fail(e.group(3), e.group(2), f"{cur}:{e.group(1)}"))
+    return {"runner": "eslint", "check": True, "errors": int(m.group(2)), "warnings": int(m.group(3)),
+            "failures": fails}
+
+
+_PARSERS = (_unittest, _pytest, _node_spec, _tap, _jest, _vitest, _gotest, _cargo, _tsc, _eslint)
+
+
+def parse(output: str, cwd: str = "") -> list[dict]:
+    """Every runner whose summary appears in `output`, in that order. Never raises."""
+    found = []
+    for p in _PARSERS:
+        try:
+            r = p(output or "", cwd)
+        except Exception:  # noqa: BLE001 — a digest must never break a command result
+            r = None
+        if r:
+            found.append(r)
+    return found
+
+
+def _counts(r: dict) -> str:
+    if r.get("check"):
+        bits = [f"{r['errors']} error{'s' if r['errors'] != 1 else ''}"]
+        if r.get("warnings"):
+            bits.append(f"{r['warnings']} warning{'s' if r['warnings'] != 1 else ''}")
+        return " · ".join(bits)
+    bits = [f"{r['passed']} passed"]
+    if r["failed"]:
+        bits.append(f"{r['failed']} failed")
+    if r.get("errors"):
+        bits.append(f"{r['errors']} error{'s' if r['errors'] != 1 else ''}")
+    if r.get("skipped"):
+        bits.append(f"{r['skipped']} skipped")
+    if r.get("note"):
+        bits.append(r["note"])
+    return " · ".join(bits)
+
+
+def digest(output: str, cwd: str = "") -> str:
+    """The block run_command puts ABOVE the output: counts per runner, then each failure as
+    `✗ name — message (file:line)`. "" when no runner was recognised."""
+    runs = parse(output, cwd)
+    if not runs:
+        return ""
+    bad = [r for r in runs if r.get("failed") or r.get("errors") or r.get("failures")]
+    if not bad:
+        return "TEST SUMMARY: " + " · ".join(f"{r['runner']} {_counts(r)}" for r in runs) + " — all passed."
+    lines = ["TEST SUMMARY (from the whole output — read this before the log below):"]
+    for r in runs:
+        lines.append(f"  {r['runner']}: {_counts(r)}")
+        for f in r["failures"][:MAX_FAILURES]:
+            tail = f" ({f['where']})" if f["where"] else ""
+            lines.append(f"    ✗ {f['name']}" + (f" — {f['message']}" if f["message"] else "") + tail)
+        if len(r["failures"]) > MAX_FAILURES:
+            lines.append(f"    … and {len(r['failures']) - MAX_FAILURES} more")
+    return "\n".join(lines)
+
+
+# ---- running ONE test ------------------------------------------------------------------------------
+# Per runner, the form that runs a single test — what the model needs after the first full run, so
+# a fix is checked in seconds and the suite runs once at the end. Keyed on what the project's own
+# test command contains.
+ONE_TEST = (
+    (r"\bnode --test\b", "node --test --test-name-pattern='<name>' <file>"),
+    (r"\bunittest\b", "python3 -m unittest <module>.<Class>.<test_name>"),
+    (r"\bpytest\b", "python3 -m pytest '<file>::<test>' -x"),
+    (r"\bvitest\b", "npx vitest run <file> -t '<name>'"),
+    (r"\bjest\b", "npx jest <file> -t '<name>'"),
+    (r"\bgo test\b", "go test -run '^<TestName>$' ./<pkg>"),
+    (r"\bcargo test\b", "cargo test <name>"),
+    (r"\bmvn\b.*\btest\b", "mvn test -Dtest=<Class>#<method>"),
+    (r"\bgradlew?\b.*\btest\b", "./gradlew test --tests '<Class.method>'"),
+    (r"\brspec\b", "bundle exec rspec <file>:<line>"),
+)
+
+
+def one_test_forms(commands) -> list[str]:
+    """Distinct run-one-test forms for the runners named in these test commands."""
+    seen = []
+    for cmd in commands or []:
+        for pat, form in ONE_TEST:
+            if re.search(pat, cmd or "") and form not in seen:
+                seen.append(form)
+    return seen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.832",
+  "version": "1.0.834",
   "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",
@@ -125,6 +125,13 @@
     "skills.mjs",
     "skill-source.mjs",
     "shell-details.mjs",
+    "browser-command.mjs",
+    "browser-bridge.mjs",
+    "browser-extension/manifest.json",
+    "browser-extension/background.js",
+    "browser-extension/popup.html",
+    "browser-extension/popup.js",
+    "browser-extension/icons/",
     "step-group.mjs",
     "mcp-config.mjs",
     "mcp-command.mjs",
@@ -135,6 +142,8 @@
     "gonext_agent_chat.py",
     "gu_mcp.py",
     "gu_skills.py",
+    "gu_test_digest.py",
+    "gu_browser.py",
     "gu_hooks.py",
     "prompt_scaffold_check.py",
     "gonext_transcribe.py",

package/shell-details.mjs

@@ -11,9 +11,9 @@
 // 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 { existsSync, openSync, readSync, closeSync, fstatSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, join, normalize } from "node:path";
+import { basename, dirname, isAbsolute, join, normalize } from "node:path";
 import { spawnSync } from "node:child_process";
 
 export const shellsPath = (home = homedir()) => join(home, ".gonext", "shells.json");
@@ -63,7 +63,7 @@ export function shellState(rec, { alive, exit, now = Date.now() / 1000 } = {}) {
   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 };
+  return { state, code: ex ? ex.code : null, runtime: Math.max(0, ended - started), ended, by: String(rec?.killed_by ?? "") };
 }
 
 /** 7m 2s — Claude Code's spelling. */
@@ -79,7 +79,10 @@ export function fmtRuntime(seconds) {
 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)";
+  // Who stopped it (#362/#143): a bare "killed" read as a crash when the agent had stopped its own
+  // search on purpose.
+  if (st.state === "killed") return st.by ? `killed — stopped by ${st.by}` : "killed";
+  return "ended (exit code unknown)";
 }
 
 /**
@@ -250,8 +253,59 @@ export async function killShell(rec, { path = shellsPath(), platform = process.p
   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.killed_by = "you (Stop it in Shell details)";
+  mine.announced = true; // you stopped it — no recap turn for it
   mine.ended = Date.now() / 1000;
   const tmp = `${path}.${process.pid}.tmp`;
   writeFileSync(tmp, JSON.stringify({ shells }, null, 2));
   renameSync(tmp, path);
 }
+
+/**
+ * Shells whose ending the agent has not heard about (#362) — Claude Code tells its model when a
+ * background command completes; gu's terminal starts a short recap turn for these. Only this
+ * folder's shells (shells.json is shared by every project), only ones that ended while this
+ * terminal was open, never one the agent already read (`seen`) or was told about (`announced`),
+ * and never one you stopped yourself.
+ */
+export function shellsToRecap(entries, { cwd = process.cwd(), since = 0 } = {}) {
+  // The nearest folder that still exists, resolved (macOS: /var → /private/var), plus the rest —
+  // a build may have deleted the folder it ran in.
+  const real = (p) => {
+    const raw = String(p ?? "");
+    if (!raw) return raw;
+    try { return realpathSync(raw); } catch { /* gone */ }
+    const up = dirname(raw);
+    return up === raw ? raw : join(real(up), basename(raw));
+  };
+  const base = real(cwd).replace(/\/+$/, "");
+  const under = (wd) => {
+    const w = real(wd);
+    return w === base || w.startsWith(base + "/");
+  };
+  return entries
+    .filter(({ rec, st }) => st.state !== "running" && st.state !== "killed" && !rec.seen && !rec.announced
+      && st.ended >= since && under(rec.workdir))
+    .map((e) => e.rec);
+}
+
+/** Mark these shells announced in shells.json, so neither the agent nor another terminal repeats it. */
+export function markAnnounced(ids, { path = shellsPath() } = {}) {
+  const shells = readShells(path);
+  let n = 0;
+  for (const s of shells) if (ids.includes(String(s.id)) && !s.announced) { s.announced = true; n++; }
+  if (!n) return 0;
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ shells }, null, 2));
+  renameSync(tmp, path);
+  return n;
+}
+
+/** The recap question the terminal asks for finished shells. */
+export function recapQuestion(entries) {
+  const parts = entries.map(({ rec, st }) =>
+    `shell ${rec.id} ${statusText(st)} after ${fmtRuntime(st.runtime)} (${String(rec.command ?? "").replace(/\s+/g, " ").trim().slice(0, 120)})`);
+  const ids = entries.map(({ rec }) => `shell_output('${rec.id}')`).join(", ");
+  return `[gu: background ${entries.length === 1 ? "shell" : "shells"} finished — ${parts.join("; ")}] `
+    + `Read the result with ${ids}, tell me briefly what happened, and continue with the next step if the task needs one.`;
+}