sbxloop 0.5.4__tar.gz → 0.5.6__tar.gz

{sbxloop-0.5.4 → sbxloop-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sbxloop
-Version: 0.5.4
+Version: 0.5.6
 Summary: Agentic loop orchestration on Docker Sandboxes (sbx) with isolated credential domains
 Project-URL: Homepage, https://github.com/brettbergin/sbxloop
 Project-URL: Repository, https://github.com/brettbergin/sbxloop

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.4'
-__version_tuple__ = version_tuple = (0, 5, 4)
+__version__ = version = '0.5.6'
+__version_tuple__ = version_tuple = (0, 5, 6)
 
 __commit_id__ = commit_id = None

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/cli/app.py

@@ -25,6 +25,7 @@ from sbxloop.errors import SdxloopError
 from sbxloop.events import Event
 from sbxloop.sbx.cli import SbxCLI
 from sbxloop.sbx.provision import sandbox_name
+from sbxloop.sbx.prune import classify_sandboxes, format_age, remove_sandbox
 
 app = typer.Typer(
     name="sbxloop",
@@ -168,6 +169,10 @@ def _finish(result: RunResult, config: Config) -> None:
     for task in result.tasks:
         console.print(f"  {task.spec.id}: {task.state}  ({task.spec.title})")
     _print_artifacts_summary(result, config)
+    if result.kept_sandboxes:
+        console.print(f"\n[bold yellow]sandboxes kept:[/] {', '.join(result.kept_sandboxes)}")
+        console.print(f"  inspect: [cyan]sbxloop shell {result.run_id}[/] (--role github)")
+        console.print(f"  remove:  [cyan]sbxloop sandbox rm --run {result.run_id}[/]")
     raise typer.Exit(0 if result.succeeded else 1)
 
 
@@ -192,10 +197,21 @@ def run(
     keep_sandboxes: Annotated[
         bool, typer.Option("--keep-sandboxes", help="Do not remove sandboxes at the end.")
     ] = False,
+    keep_on_failure: Annotated[
+        bool | None,
+        typer.Option(
+            "--keep-on-failure/--no-keep-on-failure",
+            help="Keep the sandbox pair alive when the run fails (inspect with `sbxloop shell`).",
+        ),
+    ] = None,
     tui: Annotated[bool, typer.Option("--tui/--no-tui", help="Live dashboard.")] = True,
 ) -> None:
     """Run an agentic loop for OUTCOME in a fresh sandbox pair."""
-    config = _config_with_overrides(model=model, keep_sandboxes=keep_sandboxes or None)
+    config = _config_with_overrides(
+        model=model,
+        keep_sandboxes=keep_sandboxes or None,
+        keep_on_failure=keep_on_failure,
+    )
     if report is not None:
         config = config.model_copy(
             update={"github": config.github.model_copy(update={"report": report})}
@@ -330,6 +346,57 @@ def logs(
         time.sleep(0.5)
 
 
+# Prefer bash when the template has it, fall back to POSIX sh. `sbx exec`
+# has no documented -it flags; terminal attachment is inherited stdio.
+_INTERACTIVE_SHELL = ("sh", "-c", "command -v bash >/dev/null && exec bash -l; exec sh -l")
+
+
+@app.command()
+def shell(
+    run_id: Annotated[str, typer.Argument(help="Run id.")],
+    role: Annotated[
+        str, typer.Option("--role", help="Which sandbox of the pair: agent or github.")
+    ] = "agent",
+    command: Annotated[
+        str | None,
+        typer.Option(
+            "--command", "-c", help="Run one shell command instead of an interactive shell."
+        ),
+    ] = None,
+) -> None:
+    """Open a shell inside a run's sandbox (kept, in-flight, or leaked).
+
+    Attaching to an in-flight run is meant as observation: the worker owns
+    its env files and workspace, so avoid mutating them mid-phase.
+    """
+    if role not in ("agent", "github"):
+        console.print(f"[bold red]invalid --role {role!r}:[/] must be agent or github")
+        raise typer.Exit(2)
+    config = load_config()
+    store = _store(config)
+    try:
+        store.get_run(run_id)
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+    cli = SbxCLI(app_name=config.app_name or None)
+    name = sandbox_name(run_id, "agent" if role == "agent" else "github")
+    try:
+        live = any(info.name == name for info in cli.ls())
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+    if not live:
+        console.print(
+            f"[bold red]sandbox {name} is not running.[/] Sandboxes are removed at run end "
+            "unless kept (keep_on_failure, --keep-sandboxes), and kept ones may have been "
+            "pruned since."
+        )
+        raise typer.Exit(2)
+    argv = ("sh", "-lc", command) if command else _INTERACTIVE_SHELL
+    raise typer.Exit(cli.exec_interactive(name, argv))
+
+
 @app.command()
 def artifacts(
     run_id: Annotated[str, typer.Argument(help="Run id.")],
@@ -414,6 +481,84 @@ def sandbox_rm(
             console.print(f"[yellow]skip {target}:[/] {exc}")
 
 
+@sandbox_app.command("prune")
+def sandbox_prune(
+    force: Annotated[
+        bool,
+        typer.Option("--force", "--yes", help="Actually remove (default is a dry run)."),
+    ] = False,
+    min_age: Annotated[
+        float,
+        typer.Option(
+            "--min-age",
+            help="Hours a run must be inactive before its sandboxes count as orphaned.",
+        ),
+    ] = 1.0,
+    include_kept: Annotated[
+        bool,
+        typer.Option("--include-kept", help="Also prune kept-for-debugging sandboxes."),
+    ] = False,
+) -> None:
+    """Garbage-collect orphaned sbxloop sandboxes (crashed hosts, killed runs).
+
+    Cross-references `sbx ls` against this working copy's state DB. Dry-run
+    by default: prints the classification and removes nothing without
+    --force.
+    """
+    config = load_config()
+    store = _store(config)
+    cli = SbxCLI(app_name=config.app_name or None)
+    try:
+        verdicts = classify_sandboxes(
+            cli.ls(), store, min_age_s=min_age * 3600.0, include_kept=include_kept
+        )
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+    if not verdicts:
+        console.print("no sbxloop sandboxes found")
+        return
+
+    table = Table(title="sbxloop sandbox prune")
+    for column in ("sandbox", "run", "run state", "age", "verdict"):
+        table.add_column(column)
+    for v in verdicts:
+        table.add_row(
+            v.name,
+            v.run_id or "",
+            v.run_state or "[dim]unknown[/]",
+            format_age(v.age_s),
+            ("[red]orphan[/] — " if v.orphan else "[green]keep[/] — ") + v.reason,
+        )
+    console.print(table)
+    console.print(
+        "[dim]note: the state DB is per working copy — 'unknown' sandboxes may "
+        "belong to another checkout's runs on this sbx host[/]"
+    )
+
+    orphans = [v for v in verdicts if v.orphan]
+    if not orphans:
+        console.print("nothing to prune")
+        return
+    if not force:
+        console.print(f"dry run: {len(orphans)} orphan candidate(s); re-run with --force to remove")
+        return
+    failures = 0
+    for v in orphans:
+        try:
+            remove_sandbox(cli, v.name)
+        except SdxloopError as exc:
+            failures += 1
+            console.print(f"[yellow]skip {v.name}:[/] {exc}")
+            continue
+        console.print(f"removed {v.name}")
+        # A pruned kept run is no longer kept; keep the DB marker honest.
+        if v.kept_reason is not None and v.run_id is not None:
+            store.set_run_kept(v.run_id, None)
+    if failures:
+        raise typer.Exit(1)
+
+
 @config_app.command("show")
 def config_show() -> None:
     """Show the resolved configuration and where each value came from."""
@@ -477,6 +622,8 @@ app_name = ""
 state_dir = ".sbxloop"
 # Keep sandboxes around after a run (for debugging).
 keep_sandboxes = false
+# Keep the pair alive only when a run fails; inspect with `sbxloop shell <run>`.
+keep_on_failure = false
 # Worker transport: "stream" (default) or "poll".
 worker_transport = "stream"
 # Secret injection: "proxy" (sbx keychain proxy; recommended) or "plain-env".

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/cli/doctor.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import sqlite3
 from collections.abc import Callable
 from dataclasses import dataclass
 
@@ -9,6 +10,7 @@ from rich.console import Console
 from rich.table import Table
 
 from sbxloop.config import load_config
+from sbxloop.engine.store import StateStore
 from sbxloop.errors import SbxError, SbxNotFoundError
 from sbxloop.sbx.cli import SbxCLI
 from sbxloop.sbx.provision import (
@@ -16,6 +18,7 @@ from sbxloop.sbx.provision import (
     COPILOT_TOKEN_ENV,
     GH_TOKEN_ENVS,
 )
+from sbxloop.sbx.prune import count_orphans
 from sbxloop.worker.wheel import resolve_worker_wheel
 
 TESTED_SBX_SERIES = "0.35"
@@ -67,8 +70,10 @@ def collect_checks(
     if version is not None:
         # login / daemon reachable
         report("checking sbx login")
+        logged_in = False
         try:
             cli.ls()
+            logged_in = True
             checks.append(Check("sbx login", True, "sbx ls succeeded"))
         except SbxError as exc:
             login_cmd = (
@@ -76,6 +81,25 @@ def collect_checks(
             )
             checks.append(Check("sbx login", False, f"sbx ls failed ({exc}); run `{login_cmd}`"))
 
+        # orphaned sandboxes (leaked pairs from crashed/killed runs)
+        if logged_in:
+            report("checking for orphaned sandboxes")
+            try:
+                orphans = count_orphans(cli, StateStore(config.state_dir / "state.db"))
+            except (SbxError, OSError, sqlite3.Error):
+                orphans = None
+            if orphans is not None:
+                checks.append(
+                    Check(
+                        "orphaned sandboxes",
+                        orphans == 0,
+                        "none found"
+                        if orphans == 0
+                        else f"{orphans} orphan candidate(s) — run `sbxloop sandbox prune`",
+                        hard=False,
+                    )
+                )
+
         # network policy reachable for the copilot hosts
         for host in AGENT_TOKEN_HOSTS:
             report(f"checking network policy for {host}")

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/config.py

@@ -85,6 +85,11 @@ class Config(_ConfigModel):
     app_name: str = ""
     state_dir: Path = Path(".sbxloop")
     keep_sandboxes: bool = False
+    # Keep the pair alive only when a run fails, so the evidence (worker
+    # stderr, install leftovers, workspace state) survives for
+    # `sbxloop shell <run>`. Kept runs are marked in the state DB and
+    # eventually collectable via `sbxloop sandbox prune --include-kept`.
+    keep_on_failure: bool = False
     worker_transport: WorkerTransport = "stream"
     secret_strategy: SecretStrategy = "proxy"
     # Advanced: in-sandbox interpreter for the worker, and whether to run the

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/engine/engine.py

@@ -113,49 +113,60 @@ class LoopEngine:
         pair = provisioner.ensure_pair(run_id)
         assert pair.workspace is not None
         self.store.set_run_workspace(run_id, pair.workspace, pair.mounted)
+        if pair.keep:
+            # keep_sandboxes: mark up front so `sandbox prune` respects it.
+            self.store.set_run_kept(run_id, "manual")
         try:
             with pair:
-                agent = WorkerClient(
-                    pair.agent,
-                    self.bus,
-                    transport=self.config.worker_transport,
-                    python=self.worker_python,
-                )
-                github = (
-                    WorkerClient(
-                        pair.github,
+                try:
+                    agent = WorkerClient(
+                        pair.agent,
                         self.bus,
                         transport=self.config.worker_transport,
                         python=self.worker_python,
                     )
-                    if pair.github is not None
-                    else None
-                )
-                if self.install_workers:
-                    # ensure_dev_tools: the agent builds projects in this VM
-                    # (venvs, pip) — the github sandbox only runs API ops.
-                    agent.install(extras="copilot", ensure_dev_tools=True)
-                    if github is not None:
-                        github.install(extras="")
-                reporter, detach = self._attach_reporter(github, run_id, outcome)
-                try:
-                    phases = PhaseRunner(
-                        agent, self.config, run_id, outcome, workdir=pair.agent_workdir
+                    github = (
+                        WorkerClient(
+                            pair.github,
+                            self.bus,
+                            transport=self.config.worker_transport,
+                            python=self.worker_python,
+                        )
+                        if pair.github is not None
+                        else None
                     )
-                    state = self._run_phases(run_id, phases, deadline, pair)
-                    # Summary must post while the github sandbox is alive;
-                    # on an infra exception the run is resumable and the
-                    # resumed run reopens the same tracking issue.
-                    if reporter is not None:
-                        reporter.close_run(run_id, state)
-                finally:
-                    detach()
-                    # Harvest even when a phase raised: the sandbox is still
-                    # alive here, and partial artifacts beat none.
-                    self._harvest(run_id, pair)
-                    self._report_artifacts(run_id, pair)
+                    if self.install_workers:
+                        # ensure_dev_tools: the agent builds projects in this VM
+                        # (venvs, pip) — the github sandbox only runs API ops.
+                        agent.install(extras="copilot", ensure_dev_tools=True)
+                        if github is not None:
+                            github.install(extras="")
+                    reporter, detach = self._attach_reporter(github, run_id, outcome)
+                    try:
+                        phases = PhaseRunner(
+                            agent, self.config, run_id, outcome, workdir=pair.agent_workdir
+                        )
+                        state = self._run_phases(run_id, phases, deadline, pair)
+                        # Summary must post while the github sandbox is alive;
+                        # on an infra exception the run is resumable and the
+                        # resumed run reopens the same tracking issue.
+                        if reporter is not None:
+                            reporter.close_run(run_id, state)
+                    finally:
+                        detach()
+                        # Harvest even when a phase raised: the sandbox is still
+                        # alive here, and partial artifacts beat none.
+                        self._harvest(run_id, pair)
+                        self._report_artifacts(run_id, pair)
+                except SdxloopError:
+                    # Infra failures (install, worker, sbx) are exactly what
+                    # gets diagnosed in-sandbox; decide keep before pair exit.
+                    self._keep_on_failure(run_id, pair)
+                    raise
                 if state == "completed":
                     self._deliver(run_id, outcome, pair, github)
+                else:
+                    self._keep_on_failure(run_id, pair)
         except SdxloopError:
             # State is already persisted; the exception is the kill signal.
             raise
@@ -168,6 +179,30 @@ class LoopEngine:
             tasks=tasks,
             workspace=pair.workspace,
             mounted=pair.mounted,
+            kept_sandboxes=self._pair_names(pair) if pair.keep else [],
+        )
+
+    @staticmethod
+    def _pair_names(pair: SandboxPair) -> list[str]:
+        return [s.name for s in (pair.agent, pair.github) if s is not None]
+
+    def _keep_on_failure(self, run_id: str, pair: SandboxPair) -> None:
+        """Flip the pair to kept when configured, so a failed run's evidence
+        survives for `sbxloop shell`. Marked in the DB for `sandbox prune`."""
+        if not self.config.keep_on_failure or pair.keep:
+            return
+        pair.keep = True
+        self.store.set_run_kept(run_id, "debug")
+        names = self._pair_names(pair)
+        self.bus.emit(
+            HostEventTypes.RUN_KEEP,
+            run_id,
+            sandboxes=names,
+            reason="debug",
+            message=(
+                f"sandboxes kept for debugging: {', '.join(names)} — "
+                f"inspect with `sbxloop shell {run_id}`"
+            ),
         )
 
     def _attach_reporter(

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/engine/model.py

@@ -142,6 +142,10 @@ class RunRecord(_Model):
     # agent VM (False → artifacts are harvested to runs/<run>/artifacts).
     workspace: Path | None = None
     mounted: bool = False
+    # Why this run's sandboxes were deliberately left alive ("debug",
+    # "manual"); None means normal teardown applied. `sandbox prune`
+    # excludes kept runs unless asked to include them.
+    kept_reason: str | None = None
 
 
 class RunResult(_Model):
@@ -152,6 +156,9 @@ class RunResult(_Model):
     tasks: list[TaskRecord] = Field(default_factory=list)
     workspace: Path | None = None
     mounted: bool = False
+    # Sandbox names deliberately left alive (keep_sandboxes/keep_on_failure),
+    # so callers can point the user at `sbxloop shell`.
+    kept_sandboxes: list[str] = Field(default_factory=list)
 
     @property
     def succeeded(self) -> bool:

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/engine/store.py

@@ -33,7 +33,8 @@ CREATE TABLE IF NOT EXISTS runs (
     created_at REAL NOT NULL,
     updated_at REAL NOT NULL,
     workspace  TEXT,
-    mounted    INTEGER NOT NULL DEFAULT 0
+    mounted    INTEGER NOT NULL DEFAULT 0,
+    kept_reason TEXT
 );
 CREATE TABLE IF NOT EXISTS tasks (
     run_id     TEXT NOT NULL,
@@ -75,6 +76,7 @@ CREATE INDEX IF NOT EXISTS idx_events_run ON events (run_id, seq);
 _RUNS_MIGRATIONS = (
     ("workspace", "ALTER TABLE runs ADD COLUMN workspace TEXT"),
     ("mounted", "ALTER TABLE runs ADD COLUMN mounted INTEGER NOT NULL DEFAULT 0"),
+    ("kept_reason", "ALTER TABLE runs ADD COLUMN kept_reason TEXT"),
 )
 
 
@@ -130,6 +132,18 @@ class StateStore:
             raise StateError(f"unknown run {run_id}")
         self._conn.commit()
 
+    def set_run_kept(self, run_id: str, reason: str | None) -> None:
+        """Mark a run's sandboxes as deliberately kept (``"debug"``,
+        ``"manual"``), or clear the marker with None. ``sandbox prune``
+        excludes kept runs unless explicitly told otherwise."""
+        cursor = self._conn.execute(
+            "UPDATE runs SET kept_reason = ? WHERE run_id = ?",
+            (reason, run_id),
+        )
+        if cursor.rowcount == 0:
+            raise StateError(f"unknown run {run_id}")
+        self._conn.commit()
+
     @staticmethod
     def _run_record(row: sqlite3.Row) -> RunRecord:
         return RunRecord(
@@ -140,6 +154,7 @@ class StateStore:
             updated_at=row["updated_at"],
             workspace=Path(row["workspace"]) if row["workspace"] else None,
             mounted=bool(row["mounted"]),
+            kept_reason=row["kept_reason"],
         )
 
     def get_run(self, run_id: str) -> RunRecord:
@@ -243,6 +258,18 @@ class StateStore:
 
     # -- events ------------------------------------------------------------
 
+    def last_event_ts(self, run_id: str) -> float | None:
+        """Timestamp of the run's most recent persisted event, if any.
+
+        Every bus event (heartbeats included) is persisted, so this is the
+        best liveness signal available for a run whose recorded state says
+        non-terminal but whose process may be long dead.
+        """
+        row = self._conn.execute(
+            "SELECT MAX(ts) AS ts FROM events WHERE run_id = ?", (run_id,)
+        ).fetchone()
+        return row["ts"] if row and row["ts"] is not None else None
+
     def append_event(self, event: Event) -> None:
         self._conn.execute(
             "INSERT INTO events (run_id, ts, type, job_id, data_json) VALUES (?, ?, ?, ?, ?)",

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/events.py

@@ -75,6 +75,7 @@ class HostEventTypes:
     RUN_STATE = "run.state"
     RUN_ARTIFACTS = "run.artifacts"
     RUN_DELIVER = "run.deliver"
+    RUN_KEEP = "run.keep"
     RUN_END = "run.end"
     TASK_START = "task.start"
     TASK_STATE = "task.state"

{sbxloop-0.5.4 → sbxloop-0.5.6}/src/sbxloop/sbx/cli.py

@@ -155,6 +155,22 @@ class SbxCLI:
                 raise self._error_for(result)
         return result
 
+    def exec_interactive(self, name: str, cmd: Sequence[str]) -> int:
+        """Run a command in a sandbox with the caller's terminal attached
+        (stdin/stdout/stderr inherited); returns the command's exit code.
+
+        `sbx exec` documents no -it-style flags; terminal attachment is
+        simply inheriting the caller's stdio.
+        """
+        argv = self.argv("exec", name, *cmd)
+        try:
+            return subprocess.run(argv, check=False).returncode
+        except FileNotFoundError as exc:
+            raise SbxNotFoundError(
+                f"sbx binary {self.binary!r} not found on PATH",
+                argv=argv,
+            ) from exc
+
     def cp(self, src: str, dst: str, *, timeout: float | None = None) -> None:
         self.run("cp", src, dst, timeout=timeout)
 

sbxloop-0.5.6/src/sbxloop/sbx/prune.py

@@ -0,0 +1,191 @@
+"""Orphaned-sandbox classification for ``sbxloop sandbox prune`` and doctor.
+
+The in-process cleanup registry only protects against failures inside a live
+sbxloop process; a host crash, OOM-kill, or ``kill -9`` leaves the run's
+sandbox pair running indefinitely. This module cross-references ``sbx ls``
+against the state DB to find such leaks safely.
+
+Honesty caveat: the state DB is per working copy, but sandboxes live on the
+sbx machine, which may serve several working copies. A sandbox "unknown to
+this state DB" may simply belong to another checkout's runs — verdicts say
+so explicitly, and nothing is ever removed without ``--force``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+import time
+
+from pydantic import BaseModel, ConfigDict
+
+from sbxloop.engine.store import StateStore
+from sbxloop.errors import SbxError, StateError
+from sbxloop.ids import is_run_id
+from sbxloop.sbx.cli import SbxCLI
+from sbxloop.sbx.models import SandboxInfo
+
+# A run in one of these states has already had (or never needed) its
+# teardown: any of its sandboxes still present are leaked. "failed" is safe
+# to include even though it is resumable — resume re-provisions a fresh pair.
+TERMINAL_RUN_STATES = frozenset({"completed", "failed", "cancelled"})
+
+# Age a run must be inactive before its sandboxes count as orphaned. Guards
+# against racing a run that another terminal just started or is mid-phase.
+DEFAULT_MIN_AGE_S = 3600.0
+
+_NAME_RE = re.compile(r"^sbxloop-(?P<run>[^-]+)-(?P<role>agent|github)$")
+
+
+class SandboxVerdict(BaseModel):
+    """One sandbox's classification: what we know and whether it is prunable."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    run_id: str | None = None  # parsed from the name; None → unrecognized
+    role: str | None = None
+    run_state: str | None = None  # None → unknown to this state DB
+    kept_reason: str | None = None
+    age_s: float | None = None  # since last DB activity; None → no signal
+    orphan: bool = False
+    reason: str
+
+
+def format_age(age_s: float | None) -> str:
+    if age_s is None:
+        return "?"
+    if age_s < 3600:
+        return f"{age_s / 60:.0f}m"
+    if age_s < 48 * 3600:
+        return f"{age_s / 3600:.1f}h"
+    return f"{age_s / 86400:.1f}d"
+
+
+def classify_sandboxes(
+    infos: list[SandboxInfo],
+    store: StateStore,
+    *,
+    min_age_s: float = DEFAULT_MIN_AGE_S,
+    include_kept: bool = False,
+    now: float | None = None,
+) -> list[SandboxVerdict]:
+    """Classify every ``sbxloop-*`` sandbox against the state DB.
+
+    Non-sbxloop sandboxes are never considered. Names that carry the prefix
+    but do not match the ``sbxloop-<run>-<role>`` scheme (future taxonomies:
+    warm-pool standby, etc.) are reported but never marked orphaned.
+    """
+    now = time.time() if now is None else now
+    verdicts: list[SandboxVerdict] = []
+    for info in infos:
+        if not info.name.startswith("sbxloop-"):
+            continue
+        verdicts.append(
+            _classify_one(info.name, store, min_age_s=min_age_s, include_kept=include_kept, now=now)
+        )
+    return verdicts
+
+
+def _classify_one(
+    name: str,
+    store: StateStore,
+    *,
+    min_age_s: float,
+    include_kept: bool,
+    now: float,
+) -> SandboxVerdict:
+    match = _NAME_RE.match(name)
+    if match is None or not is_run_id(match.group("run")):
+        return SandboxVerdict(
+            name=name,
+            reason="unrecognized sbxloop naming scheme; not touched",
+        )
+    run_id, role = match.group("run"), match.group("role")
+
+    try:
+        run = store.get_run(run_id)
+    except StateError:
+        return SandboxVerdict(
+            name=name,
+            run_id=run_id,
+            role=role,
+            orphan=True,
+            reason="unknown to this state DB (may belong to another working copy)",
+        )
+
+    if run.kept_reason is not None and not include_kept:
+        return SandboxVerdict(
+            name=name,
+            run_id=run_id,
+            role=role,
+            run_state=run.state,
+            kept_reason=run.kept_reason,
+            age_s=now - run.updated_at,
+            reason=f"kept ({run.kept_reason}); use --include-kept to prune",
+        )
+
+    # Liveness = the newest thing the run ever wrote: state transitions bump
+    # updated_at, and every bus event (heartbeats included) is persisted.
+    last_activity = max(run.updated_at, store.last_event_ts(run_id) or 0.0)
+    age_s = now - last_activity
+    kept_note = f", kept ({run.kept_reason})" if run.kept_reason is not None else ""
+
+    if run.state in TERMINAL_RUN_STATES:
+        if age_s >= min_age_s:
+            return SandboxVerdict(
+                name=name,
+                run_id=run_id,
+                role=role,
+                run_state=run.state,
+                kept_reason=run.kept_reason,
+                age_s=age_s,
+                orphan=True,
+                reason=f"run {run.state} {format_age(age_s)} ago{kept_note}",
+            )
+        return SandboxVerdict(
+            name=name,
+            run_id=run_id,
+            role=role,
+            run_state=run.state,
+            kept_reason=run.kept_reason,
+            age_s=age_s,
+            reason=f"run {run.state} only {format_age(age_s)} ago (younger than --min-age)",
+        )
+
+    if age_s >= min_age_s:
+        return SandboxVerdict(
+            name=name,
+            run_id=run_id,
+            role=role,
+            run_state=run.state,
+            kept_reason=run.kept_reason,
+            age_s=age_s,
+            orphan=True,
+            reason=f"run {run.state} but silent for {format_age(age_s)}{kept_note}",
+        )
+    return SandboxVerdict(
+        name=name,
+        run_id=run_id,
+        role=role,
+        run_state=run.state,
+        kept_reason=run.kept_reason,
+        age_s=age_s,
+        reason=f"run {run.state}, active {format_age(age_s)} ago (possibly live)",
+    )
+
+
+def remove_sandbox(cli: SbxCLI, name: str) -> None:
+    """Stop (best-effort) then force-remove one sandbox.
+
+    ``stop`` failing is expected for already-stopped sandboxes; ``rm``
+    failing propagates so callers can report it.
+    """
+    with contextlib.suppress(SbxError):
+        cli.stop(name)
+    cli.rm(name, force=True)
+
+
+def count_orphans(cli: SbxCLI, store: StateStore) -> int:
+    """Orphan-candidate count with default thresholds (doctor's view)."""
+    return sum(1 for v in classify_sandboxes(cli.ls(), store) if v.orphan)