sbxloop 0.5.8__tar.gz → 0.5.10__tar.gz

{sbxloop-0.5.8 → sbxloop-0.5.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sbxloop
-Version: 0.5.8
+Version: 0.5.10
 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.8 → sbxloop-0.5.10}/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.8'
-__version_tuple__ = version_tuple = (0, 5, 8)
+__version__ = version = '0.5.10'
+__version_tuple__ = version_tuple = (0, 5, 10)
 
 __commit_id__ = commit_id = None

{sbxloop-0.5.8 → sbxloop-0.5.10}/src/sbxloop/cli/app.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import queue
 import threading
 import time
@@ -26,6 +27,16 @@ 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
+from sbxloop.sbx.secretstate import (
+    COPILOT_TOKEN_ENV,
+    SANDBOX_SCOPE_PREFIX,
+    assess,
+    inspect_custom_secret,
+    removal_ladder,
+    replace_registration,
+    tracked_custom_secrets,
+    verify_secret_visibility,
+)
 
 app = typer.Typer(
     name="sbxloop",
@@ -35,8 +46,12 @@ app = typer.Typer(
 )
 sandbox_app = typer.Typer(help="Manage sbxloop sandboxes.", no_args_is_help=True)
 config_app = typer.Typer(help="Inspect configuration.", no_args_is_help=True)
+secrets_app = typer.Typer(
+    help="Manage the sbx custom-secret registrations sbxloop owns.", no_args_is_help=True
+)
 app.add_typer(sandbox_app, name="sandbox")
 app.add_typer(config_app, name="config")
+app.add_typer(secrets_app, name="secrets")
 
 console = Console()
 
@@ -481,6 +496,210 @@ def sandbox_rm(
             console.print(f"[yellow]skip {target}:[/] {exc}")
 
 
+_STATUS_STYLES = {"ok": "[green]ok[/]", "warn": "[yellow]warn[/]", "unknown": "[dim]?[/]"}
+
+
+def _secrets_context() -> tuple[Config, SbxCLI, set[str]]:
+    """Config, an sbx handle, and the live sbxloop sandbox names (for
+    telling in-use registration scopes from stale ones)."""
+    config = load_config()
+    cli = SbxCLI(app_name=config.app_name or None)
+    live = {i.name for i in cli.ls() if i.name.startswith(SANDBOX_SCOPE_PREFIX)}
+    return config, cli, live
+
+
+@secrets_app.command("list")
+def secrets_list(
+    probe: Annotated[
+        bool,
+        typer.Option(
+            "--probe/--no-probe",
+            help="When `sbx secret ls` cannot answer, detect registrations by "
+            "transiently registering (and immediately removing) a sentinel — "
+            "the collision error names the real owner.",
+        ),
+    ] = True,
+) -> None:
+    """Show sbxloop's custom-secret registrations across scopes.
+
+    Flags registrations that no longer match what provisioning would
+    register (stale scopes, wrong host bindings) — the pre-collision
+    warnings. The built-in `github` service secret is sbx-managed and never
+    touched by these commands.
+    """
+    try:
+        config, cli, live = _secrets_context()
+        table = Table(title="sbxloop custom-secret registrations")
+        for column in ("env", "expected", "actual", "status", "note"):
+            table.add_column(column)
+        warned = False
+        for env, host in tracked_custom_secrets(config):
+            state = inspect_custom_secret(cli, env, host=host, probe=probe)
+            judgement = assess(state, canonical_host=host, live_sandboxes=live)
+            warned = warned or judgement.status == "warn"
+            if state.exists:
+                actual = f"scope {state.scope or '(unknown)'}"
+                if state.hosts:
+                    actual += f" @ {', '.join(state.hosts)}"
+            elif state.exists is None:
+                actual = "(undetermined)"
+            else:
+                actual = "not registered"
+            table.add_row(
+                env,
+                f"custom @ {host} (per-run scope)",
+                actual,
+                _STATUS_STYLES[judgement.status],
+                judgement.note,
+            )
+        console.print(table)
+        console.print(
+            "[dim]GH_TOKEN uses sbx's built-in `github` service secret; "
+            "it is never managed here.[/]"
+        )
+        if warned:
+            console.print(
+                "\n[yellow]warnings above are pre-collision state[/] — "
+                "`sbxloop secrets clean` removes the stale entries"
+            )
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+
+
+@secrets_app.command("clean")
+def secrets_clean(
+    apply: Annotated[
+        bool, typer.Option("--apply", help="Actually remove (default is a dry run).")
+    ] = False,
+    all_: Annotated[
+        bool,
+        typer.Option(
+            "--all",
+            help="Also remove healthy sbxloop-owned registrations (global with the "
+            "canonical binding, live-sandbox scopes), not just stale ones.",
+        ),
+    ] = False,
+) -> None:
+    """Remove stale sbxloop-owned custom-secret registrations (dry-run by default).
+
+    Only touches registrations sbxloop itself created (sbxloop-* sandbox
+    scopes and global entries for its tracked env vars) — never foreign
+    scopes and never the built-in `github` service secret.
+    """
+    try:
+        config, cli, live = _secrets_context()
+        failed = False
+        removed_any = False
+        for env, host in tracked_custom_secrets(config):
+            state = inspect_custom_secret(cli, env, host=host)
+            judgement = assess(state, canonical_host=host, live_sandboxes=live)
+            if not (judgement.stale or (all_ and judgement.owned)):
+                console.print(f"{env}: nothing to clean ({judgement.note})")
+                continue
+            where = f"scope {state.scope or '(unknown)'}"
+            if not apply:
+                console.print(f"{env}: would remove the registration in {where} — {judgement.note}")
+                removed_any = True
+                continue
+            if any(rm() for rm in removal_ladder(cli, state, host=host)):
+                console.print(f"[green]{env}: removed the registration in {where}[/]")
+                removed_any = True
+            else:
+                console.print(f"[bold red]{env}: sbx rejected every removal for {where}[/]")
+                failed = True
+        if not apply and removed_any:
+            console.print("\ndry run — re-run with [cyan]--apply[/] to remove")
+        if failed:
+            raise typer.Exit(1)
+    except SdxloopError as exc:
+        console.print(f"[bold red]{exc}[/]")
+        raise typer.Exit(2) from exc
+
+
+@secrets_app.command("rotate")
+def secrets_rotate(
+    prompt: Annotated[
+        bool,
+        typer.Option(
+            "--prompt",
+            help="Read the new token from a hidden interactive prompt instead of "
+            f"the {COPILOT_TOKEN_ENV} environment variable / ./.env.",
+        ),
+    ] = False,
+    verify: Annotated[
+        bool,
+        typer.Option(
+            "--verify/--no-verify",
+            help="Boot a throwaway sandbox to report which secret strategy "
+            "(proxy vs plain-env fallback) the next run will use.",
+        ),
+    ] = True,
+) -> None:
+    """Rotate the Copilot token's sbx registration in one step.
+
+    Replaces the existing registration (wherever its scope) with a global
+    one carrying the canonical host binding — the rm + set-custom dance
+    provisioning would otherwise perform mid-run. The token is read from
+    the environment/.env or an interactive prompt, never from argv.
+    """
+    if prompt:
+        token = typer.prompt(f"new {COPILOT_TOKEN_ENV}", hide_input=True)
+    else:
+        token = os.environ.get(COPILOT_TOKEN_ENV, "")
+        if not token:
+            console.print(
+                f"[bold red]{COPILOT_TOKEN_ENV} is not set.[/] Export the new token "
+                "(or put it in ./.env), or pass [cyan]--prompt[/] to type it — "
+                "it is never accepted as a command-line argument."
+            )
+            raise typer.Exit(2)
+    try:
+        config, cli, live = _secrets_context()
+        for env, host in tracked_custom_secrets(config):
+            replace_registration(cli, env=env, host=host, token=token)
+            console.print(f"[green]rotated:[/] {env} registered @ {host} (global scope)")
+        if live:
+            console.print(
+                f"[yellow]live sbxloop sandboxes exist ({', '.join(sorted(live))})[/] — "
+                "they may still hold the old token in their in-VM env file; "
+                "remove them with `sbxloop sandbox rm --all`"
+            )
+        if prompt:
+            console.print(
+                f"[yellow]runs read {COPILOT_TOKEN_ENV} from the environment at "
+                "provision time[/] — update your export / ./.env with the new value too"
+            )
+        if config.secret_strategy == "plain-env":
+            console.print(
+                "next run: [bold]plain-env[/] strategy (configured) — the token is "
+                "written to the in-VM env file from your environment"
+            )
+        elif verify:
+            workspace = config.state_dir / "secretcheck"
+            workspace.mkdir(parents=True, exist_ok=True)
+            visible = verify_secret_visibility(
+                cli,
+                env=COPILOT_TOKEN_ENV,
+                workspace=workspace,
+                template=config.sandbox.template,
+            )
+            if visible is True:
+                console.print(
+                    "next run: [bold green]proxy[/] strategy — the token stays out of the VM"
+                )
+            elif visible is False:
+                console.print(
+                    "next run: [bold yellow]plain-env fallback[/] — sbx's proxy secret is "
+                    "invisible to exec sessions, so provisioning will write the in-VM env file"
+                )
+            else:
+                console.print("[yellow]could not verify secret visibility[/] (see logs)")
+    except SdxloopError as exc:
+        console.print(f"[bold red]rotate failed:[/] {exc}")
+        raise typer.Exit(2) from exc
+
+
 @sandbox_app.command("prune")
 def sandbox_prune(
     force: Annotated[

{sbxloop-0.5.8 → sbxloop-0.5.10}/src/sbxloop/cli/doctor.py

@@ -13,12 +13,9 @@ 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 (
-    AGENT_TOKEN_HOSTS,
-    COPILOT_TOKEN_ENV,
-    GH_TOKEN_ENVS,
-)
+from sbxloop.sbx.provision import AGENT_TOKEN_HOSTS, GH_TOKEN_ENVS
 from sbxloop.sbx.prune import count_orphans
+from sbxloop.sbx.secretstate import COPILOT_TOKEN_ENV
 from sbxloop.worker.wheel import resolve_worker_wheel
 
 TESTED_SBX_SERIES = "0.35"

{sbxloop-0.5.8 → sbxloop-0.5.10}/src/sbxloop/errors.py

@@ -13,6 +13,10 @@ class ConfigError(SdxloopError):
     """Invalid or unloadable configuration."""
 
 
+class SecretStateError(SdxloopError):
+    """A secret registration could not be inspected or replaced."""
+
+
 class SbxError(SdxloopError):
     """An sbx CLI invocation failed."""
 

{sbxloop-0.5.8 → sbxloop-0.5.10}/src/sbxloop/sbx/cli.py

@@ -247,6 +247,12 @@ class SbxCLI:
             value,
         )
 
+    def secret_ls(self) -> ExecResult:
+        """``sbx secret ls``, never raising on failure: whether (and how) a
+        given sbx build enumerates secrets is unverified, so callers treat a
+        non-ok result as "listing unsupported" and fall back to probing."""
+        return self.run("secret", "ls", check=False)
+
     def secret_rm(
         self,
         *,

{sbxloop-0.5.8 → sbxloop-0.5.10}/src/sbxloop/sbx/provision.py

@@ -20,7 +20,6 @@ from __future__ import annotations
 
 import logging
 import os
-import re
 import secrets
 import shlex
 from collections.abc import Callable, Mapping
@@ -34,19 +33,18 @@ from sbxloop.sbx.cli import SbxCLI
 from sbxloop.sbx.models import SandboxRole, SandboxSpec, SecretSpec
 from sbxloop.sbx.pair import SandboxPair
 from sbxloop.sbx.sandbox import ENV_FILE, EVENTS_DIR, JOBS_DIR, RESULTS_DIR, WORK_DIR, Sandbox
+from sbxloop.sbx.secretstate import (
+    COPILOT_TOKEN_ENV,
+    COPILOT_TOKEN_HOST,
+    custom_rm_candidates,
+    service_rm_candidates,
+    set_secret_replacing,
+)
 
 logger = logging.getLogger(__name__)
 
-COPILOT_TOKEN_ENV = "COPILOT_GITHUB_TOKEN"
 GH_TOKEN_ENVS = ("GH_TOKEN", "GITHUB_TOKEN")
 
-# The PAT is exchanged for a Copilot API token at api.github.com; the
-# exchanged token lives in SDK process memory, so the copilot API hosts only
-# need network allows - never an env rewrite. One env var also cannot be
-# registered twice: sbx keys custom secrets by env name, so binding the same
-# env to two hosts fails with "already exists".
-COPILOT_TOKEN_HOST = "api.github.com"
-
 # Hosts the agent sandbox must be able to reach (doctor checks these).
 AGENT_TOKEN_HOSTS = ("api.githubcopilot.com", "api.github.com")
 
@@ -211,14 +209,14 @@ class Provisioner:
             if secret.kind == "service":
                 assert secret.service is not None
                 service = secret.service
-                self._set_secret_replacing(
+                set_secret_replacing(
                     f"service {service} ({spec.name})",
                     set_fn=partial(self.cli.secret_set, service, sandbox=spec.name, token=token),
-                    rm_candidates=partial(self._service_rm_candidates, service, spec.name),
+                    rm_candidates=partial(service_rm_candidates, self.cli, service, spec.name),
                 )
             else:
                 assert secret.host is not None and secret.env is not None
-                self._set_secret_replacing(
+                set_secret_replacing(
                     f"custom {secret.env}@{secret.host} ({spec.name})",
                     set_fn=partial(
                         self.cli.secret_set_custom,
@@ -228,106 +226,10 @@ class Provisioner:
                         sandbox=spec.name,
                     ),
                     rm_candidates=partial(
-                        self._custom_rm_candidates, secret.host, secret.env, spec.name
+                        custom_rm_candidates, self.cli, secret.host, secret.env, spec.name
                     ),
                 )
 
-    _SECRET_EXISTS_MARKERS = ("exist", "already")
-    # sbx reports the owner of a conflicting secret, e.g.
-    #   ERROR: custom secret env "X" already exists in scope NAME with placeholder ...
-    _SCOPE_RE = re.compile(r'in scope "?([A-Za-z0-9._-]+)"?')
-
-    @classmethod
-    def _parsed_scope(cls, stderr: str) -> str | None:
-        """The scope owning the conflicting secret, per sbx's error message.
-
-        Returns None when unparseable; the literal scopes "global"/"-g" map
-        to None-as-global in secret_rm terms via the callers below.
-        """
-        match = cls._SCOPE_RE.search(stderr)
-        return match.group(1) if match else None
-
-    def _service_rm_candidates(
-        self, service: str, sandbox: str, stderr: str
-    ) -> list[Callable[[], bool]]:
-        scopes: list[str | None] = []
-        parsed = self._parsed_scope(stderr)
-        if parsed:
-            scopes.append(None if parsed in ("global", "-g") else parsed)
-        scopes += [sandbox, None]
-        seen: list[str | None] = []
-        candidates: list[Callable[[], bool]] = []
-        for scope in scopes:
-            if scope in seen:
-                continue
-            seen.append(scope)
-            candidates.append(partial(self.cli.secret_rm, service=service, sandbox=scope))
-        return candidates
-
-    def _custom_rm_candidates(
-        self, host: str, env: str, sandbox: str, stderr: str
-    ) -> list[Callable[[], bool]]:
-        scopes: list[str | None] = []
-        parsed = self._parsed_scope(stderr)
-        if parsed:
-            scopes.append(None if parsed in ("global", "-g") else parsed)
-        scopes += [sandbox, None]
-        seen: list[str | None] = []
-        candidates: list[Callable[[], bool]] = []
-        for scope in scopes:
-            if scope in seen:
-                continue
-            seen.append(scope)
-            # env+host first, then env-only: sbx keys custom secrets by env
-            # name, so the conflicting entry may carry a different host.
-            candidates.append(partial(self.cli.secret_rm, host=host, env=env, sandbox=scope))
-            candidates.append(partial(self.cli.secret_rm, env=env, sandbox=scope))
-        return candidates
-
-    def _set_secret_replacing(
-        self,
-        describe: str,
-        *,
-        set_fn: Callable[[], None],
-        rm_candidates: Callable[[str], list[Callable[[], bool]]],
-    ) -> None:
-        """Set a secret, replacing a leftover one from a previous run.
-
-        sbx refuses to overwrite an existing secret and keys custom secrets
-        by env name, with the conflicting entry possibly owned by another
-        scope (a previous run's sandbox). On an exists-error we parse the
-        owning scope out of sbx's stderr and try removal candidates from
-        most to least specific, retrying the set after each successful
-        removal. An exists-conflict NEVER fails provisioning: if nothing
-        can be replaced, the existing value is kept with a warning (it may
-        be stale if the token was rotated). Non-exists errors raise.
-
-        Only sbx's stderr is matched for exists-markers: the full exception
-        string embeds argv, and arbitrary paths can contain words like
-        "exists" (a pytest tmp dir did exactly that).
-        """
-        try:
-            set_fn()
-            return
-        except SbxError as exc:
-            if not any(m in exc.stderr.lower() for m in self._SECRET_EXISTS_MARKERS):
-                raise
-            stderr = exc.stderr
-        for rm_fn in rm_candidates(stderr):
-            if not rm_fn():
-                continue
-            try:
-                set_fn()
-                return
-            except SbxError as exc:
-                if not any(m in exc.stderr.lower() for m in self._SECRET_EXISTS_MARKERS):
-                    raise
-        logger.warning(
-            "secret %s already exists and could not be replaced; keeping the "
-            "existing value (it may be stale if the token was rotated)",
-            describe,
-        )
-
     def _verify_secret_env(
         self, run_id: str, spec: SandboxSpec, sandbox: Sandbox, token: str
     ) -> None:

sbxloop-0.5.10/src/sbxloop/sbx/secretstate.py

@@ -0,0 +1,420 @@
+"""Custom-secret registration state, shared by provisioning and `sbxloop secrets`.
+
+Field-verified sbx behavior this module encodes (2026-07-23):
+
+- sbx keys custom secrets by ENV VAR NAME — one registration per env var,
+  whatever the scope. Registering the same env again fails with
+  ``custom secret env "X" already exists in scope <scope> with placeholder
+  <p>``; the error names the owning scope, which is parseable for targeted
+  removal.
+- sbx refuses to overwrite an existing secret; replacement is rm + set.
+- Removal syntax for custom secrets is not a stable documented API, so
+  removals are best-effort ladders from most- to least-specific scope.
+- ``sbx secret ls``-style enumeration is UNVERIFIED across sbx builds:
+  listing is attempted and parsed tolerantly, with the exists-error
+  collision probe as the authoritative fallback.
+
+Provisioning's replace-on-exists collision recovery and the `sbxloop secrets`
+command group both call into here, so the field-hardened logic has exactly
+one implementation.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Callable
+from functools import partial
+from pathlib import Path
+from secrets import token_hex
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from sbxloop.config import Config
+from sbxloop.errors import SbxError, SecretStateError
+from sbxloop.sbx.cli import SbxCLI
+from sbxloop.sbx.models import SandboxSpec
+
+logger = logging.getLogger(__name__)
+
+COPILOT_TOKEN_ENV = "COPILOT_GITHUB_TOKEN"
+
+# The PAT is exchanged for a Copilot API token at api.github.com; the
+# exchanged token lives in SDK process memory, so the copilot API hosts only
+# need network allows - never an env rewrite. One env var also cannot be
+# registered twice: sbx keys custom secrets by env name, so binding the same
+# env to two hosts fails with "already exists".
+COPILOT_TOKEN_HOST = "api.github.com"
+
+# Every sbxloop sandbox (and therefore every sandbox-scoped registration
+# sbxloop creates) is named with this prefix.
+SANDBOX_SCOPE_PREFIX = "sbxloop-"
+
+SECRET_EXISTS_MARKERS = ("exist", "already")
+# sbx reports the owner of a conflicting secret, e.g.
+#   ERROR: custom secret env "X" already exists in scope NAME with placeholder ...
+_SCOPE_RE = re.compile(r'in scope "?([A-Za-z0-9._-]+)"?')
+# Spellings sbx uses for the global scope in errors and listings.
+_GLOBAL_SCOPE_NAMES = ("global", "-g")
+
+_DOMAIN_RE = re.compile(r"(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}")
+
+Source = Literal["ls", "probe"]
+
+RmCandidates = Callable[[str], list[Callable[[], bool]]]
+
+
+def tracked_custom_secrets(config: Config) -> list[tuple[str, str]]:
+    """The (env, canonical host) custom secrets provisioning registers.
+
+    Today that is exactly the Copilot token; config declares no additional
+    custom secrets (the github sandbox uses sbx's built-in ``github``
+    service secret, which is never managed here).
+    """
+    del config
+    return [(COPILOT_TOKEN_ENV, COPILOT_TOKEN_HOST)]
+
+
+def parsed_scope(stderr: str) -> str | None:
+    """The scope owning the conflicting secret, per sbx's error message.
+
+    Returns None when unparseable; the literal global spellings
+    ("global"/"-g") map to None-as-global in secret_rm terms via the
+    candidate builders below.
+    """
+    match = _SCOPE_RE.search(stderr)
+    return match.group(1) if match else None
+
+
+def service_rm_candidates(
+    cli: SbxCLI, service: str, sandbox: str | None, stderr: str
+) -> list[Callable[[], bool]]:
+    scopes: list[str | None] = []
+    parsed = parsed_scope(stderr)
+    if parsed:
+        scopes.append(None if parsed in _GLOBAL_SCOPE_NAMES else parsed)
+    scopes += [sandbox, None]
+    seen: list[str | None] = []
+    candidates: list[Callable[[], bool]] = []
+    for scope in scopes:
+        if scope in seen:
+            continue
+        seen.append(scope)
+        candidates.append(partial(cli.secret_rm, service=service, sandbox=scope))
+    return candidates
+
+
+def custom_rm_candidates(
+    cli: SbxCLI, host: str, env: str, sandbox: str | None, stderr: str
+) -> list[Callable[[], bool]]:
+    scopes: list[str | None] = []
+    parsed = parsed_scope(stderr)
+    if parsed:
+        scopes.append(None if parsed in _GLOBAL_SCOPE_NAMES else parsed)
+    scopes += [sandbox, None]
+    seen: list[str | None] = []
+    candidates: list[Callable[[], bool]] = []
+    for scope in scopes:
+        if scope in seen:
+            continue
+        seen.append(scope)
+        # env+host first, then env-only: sbx keys custom secrets by env
+        # name, so the conflicting entry may carry a different host.
+        candidates.append(partial(cli.secret_rm, host=host, env=env, sandbox=scope))
+        candidates.append(partial(cli.secret_rm, env=env, sandbox=scope))
+    return candidates
+
+
+def set_secret_replacing(
+    describe: str,
+    *,
+    set_fn: Callable[[], None],
+    rm_candidates: RmCandidates,
+    strict: bool = False,
+) -> bool:
+    """Set a secret, replacing a leftover one from a previous run.
+
+    sbx refuses to overwrite an existing secret and keys custom secrets
+    by env name, with the conflicting entry possibly owned by another
+    scope (a previous run's sandbox). On an exists-error we parse the
+    owning scope out of sbx's stderr and try removal candidates from
+    most to least specific, retrying the set after each successful
+    removal. Returns True when the set succeeded (fresh or replaced).
+
+    By default an exists-conflict NEVER fails: if nothing can be replaced,
+    the existing value is kept with a warning (it may be stale if the
+    token was rotated) and False is returned — provisioning must not die
+    on a leftover registration. Under ``strict`` (rotation, where keeping
+    a stale value defeats the point) an irreplaceable secret raises
+    SecretStateError instead. Non-exists errors always raise.
+
+    Only sbx's stderr is matched for exists-markers: the full exception
+    string embeds argv, and arbitrary paths can contain words like
+    "exists" (a pytest tmp dir did exactly that).
+    """
+    try:
+        set_fn()
+        return True
+    except SbxError as exc:
+        if not any(m in exc.stderr.lower() for m in SECRET_EXISTS_MARKERS):
+            raise
+        stderr = exc.stderr
+    for rm_fn in rm_candidates(stderr):
+        if not rm_fn():
+            continue
+        try:
+            set_fn()
+            return True
+        except SbxError as exc:
+            if not any(m in exc.stderr.lower() for m in SECRET_EXISTS_MARKERS):
+                raise
+    if strict:
+        raise SecretStateError(
+            f"secret {describe} already exists and could not be replaced "
+            f"(sbx said: {' '.join(stderr.split())})"
+        )
+    logger.warning(
+        "secret %s already exists and could not be replaced; keeping the "
+        "existing value (it may be stale if the token was rotated)",
+        describe,
+    )
+    return False
+
+
+# -- inspection --------------------------------------------------------------
+
+
+class CustomSecretState(BaseModel):
+    """What sbx currently has registered for one custom-secret env var."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    env: str
+    # None: undetermined (listing unsupported and probing disabled/failed).
+    exists: bool | None = None
+    # "global", a sandbox-scope name, or None when the owner is unknown.
+    scope: str | None = None
+    # Host bindings, when a listing revealed them (a probe cannot).
+    hosts: list[str] = Field(default_factory=list)
+    source: Source | None = None
+    detail: str = ""
+
+
+def parse_secret_ls_entry(raw: str, env: str) -> tuple[str | None, list[str]] | None:
+    """Best-effort (scope, hosts) for ``env`` from ``sbx secret ls`` output.
+
+    The listing format is unverified across sbx builds, so parsing is
+    token-based on whichever line names the env var: domain-shaped tokens
+    are host bindings, a ``sbxloop-*`` token is the owning sandbox scope,
+    and a global spelling maps to "global". Returns None when no line
+    mentions the env (which is NOT proof of absence — the build's listing
+    may simply omit custom secrets; callers corroborate with the probe).
+    """
+    for line in raw.splitlines():
+        if not re.search(rf"(?<![A-Za-z0-9_]){re.escape(env)}(?![A-Za-z0-9_])", line):
+            continue
+        tokens = line.replace(",", " ").split()
+        hosts = [t for t in tokens if _DOMAIN_RE.fullmatch(t)]
+        scope = next((t for t in tokens if t.startswith(SANDBOX_SCOPE_PREFIX)), None)
+        if scope is None and any(t.lower() in _GLOBAL_SCOPE_NAMES for t in tokens):
+            scope = "global"
+        return scope, hosts
+    return None
+
+
+def probe_custom_secret(cli: SbxCLI, env: str, *, host: str) -> CustomSecretState:
+    """Detect a registration via the field-verified exists-error.
+
+    Attempts a global set-custom with a sentinel value: an exists-error
+    proves the registration (and names its owner scope); success proves
+    absence, and the sentinel is removed again immediately. A leftover
+    sentinel (removal rejected mid-probe) is harmless — provisioning
+    replaces on collision and never trusts a pre-existing value — but is
+    logged loudly.
+    """
+    sentinel = f"sbxloop-probe-{token_hex(4)}"
+    try:
+        cli.secret_set_custom(host=host, env=env, value=sentinel, sandbox=None)
+    except SbxError as exc:
+        if any(m in exc.stderr.lower() for m in SECRET_EXISTS_MARKERS):
+            scope = parsed_scope(exc.stderr)
+            if scope in _GLOBAL_SCOPE_NAMES:
+                scope = "global"
+            return CustomSecretState(
+                env=env,
+                exists=True,
+                scope=scope,
+                source="probe",
+                detail=exc.stderr.strip(),
+            )
+        return CustomSecretState(env=env, exists=None, detail=str(exc))
+    removed = cli.secret_rm(host=host, env=env, sandbox=None) or cli.secret_rm(
+        env=env, sandbox=None
+    )
+    if not removed:
+        logger.warning(
+            "probe: sbx rejected removing the transient sentinel registration for %s; "
+            "the next provisioning will replace it",
+            env,
+        )
+    return CustomSecretState(env=env, exists=False, source="probe")
+
+
+def inspect_custom_secret(
+    cli: SbxCLI, env: str, *, host: str, probe: bool = True
+) -> CustomSecretState:
+    """Current registration state for ``env``: listing first, probe fallback."""
+    listing = cli.secret_ls()
+    if listing.ok:
+        entry = parse_secret_ls_entry(listing.stdout, env)
+        if entry is not None:
+            scope, hosts = entry
+            return CustomSecretState(env=env, exists=True, scope=scope, hosts=hosts, source="ls")
+        # No line names the env. That usually means "not registered", but a
+        # build whose listing omits custom secrets would look identical, so
+        # the collision probe settles it when allowed.
+    if not probe:
+        return CustomSecretState(
+            env=env,
+            exists=None,
+            detail="not in `sbx secret ls` output and probing disabled (--no-probe)",
+        )
+    return probe_custom_secret(cli, env, host=host)
+
+
+# -- assessment --------------------------------------------------------------
+
+
+class Assessment(BaseModel):
+    """One tracked secret's registration state, judged against what current
+    provisioning would register — mismatches are pre-collision warnings."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: Literal["ok", "warn", "unknown"]
+    note: str
+    # Safe for `secrets clean` to remove: definitely sbxloop-owned and no
+    # longer what provisioning would produce.
+    stale: bool = False
+    # sbxloop-owned at all (stale or not) — what `clean --all` may remove.
+    owned: bool = False
+
+
+def assess(
+    state: CustomSecretState, *, canonical_host: str, live_sandboxes: set[str]
+) -> Assessment:
+    if state.exists is False:
+        return Assessment(status="ok", note="not registered — the next run registers it fresh")
+    if state.exists is None:
+        return Assessment(status="unknown", note=state.detail or "state undetermined")
+    host_mismatch = bool(state.hosts) and canonical_host not in state.hosts
+    if state.scope is not None and state.scope.startswith(SANDBOX_SCOPE_PREFIX):
+        if state.scope in live_sandboxes:
+            return Assessment(
+                status="warn" if host_mismatch else "ok",
+                note=(
+                    f"owned by live sandbox {state.scope}"
+                    + (
+                        f" but bound to {', '.join(state.hosts)} (expected {canonical_host})"
+                        if host_mismatch
+                        else ""
+                    )
+                ),
+                stale=host_mismatch,
+                owned=True,
+            )
+        return Assessment(
+            status="warn",
+            note=(
+                f"stale: owner scope {state.scope} no longer exists — the next run "
+                "will hit (and recover from) a set-custom collision"
+            ),
+            stale=True,
+            owned=True,
+        )
+    if state.scope == "global":
+        if host_mismatch:
+            return Assessment(
+                status="warn",
+                note=(
+                    f"global registration bound to {', '.join(state.hosts)}, expected "
+                    f"{canonical_host} — likely left by an older sbxloop version"
+                ),
+                stale=True,
+                owned=True,
+            )
+        return Assessment(
+            status="ok",
+            note="global registration with the canonical host binding",
+            owned=True,
+        )
+    if state.scope is None:
+        return Assessment(
+            status="warn",
+            note="registered but the owner scope could not be determined — "
+            "inspect with `sbx secret ls` or remove manually",
+        )
+    return Assessment(
+        status="warn",
+        note=(
+            f"owned by foreign scope {state.scope!r} — not sbxloop's to remove; the next "
+            "run will attempt collision recovery against it. Remove it yourself with "
+            "`sbx secret rm` if it is yours."
+        ),
+    )
+
+
+def removal_ladder(cli: SbxCLI, state: CustomSecretState, *, host: str) -> list[Callable[[], bool]]:
+    """rm candidates for a known registration, most- to least-specific.
+
+    ``state.detail`` may carry the probe's exists-error, whose parsed scope
+    then leads the ladder exactly as in provisioning's collision recovery.
+    """
+    scope = None if state.scope in (None, "global") else state.scope
+    return custom_rm_candidates(cli, host, state.env, scope, state.detail)
+
+
+# -- rotation ----------------------------------------------------------------
+
+
+def replace_registration(cli: SbxCLI, *, env: str, host: str, token: str) -> None:
+    """Atomically replace ``env``'s registration at global scope: the rm +
+    set-custom dance with the canonical host binding, failing loudly (unlike
+    provisioning's keep-on-conflict) when the old entry cannot be removed."""
+    set_secret_replacing(
+        f"custom {env}@{host} (global)",
+        set_fn=partial(cli.secret_set_custom, host=host, env=env, value=token, sandbox=None),
+        rm_candidates=partial(custom_rm_candidates, cli, host, env, None),
+        strict=True,
+    )
+
+
+def verify_secret_visibility(
+    cli: SbxCLI, *, env: str, workspace: Path, template: str | None = None
+) -> bool | None:
+    """Boot a throwaway sandbox and check whether the proxy-injected env is
+    visible to exec'd processes (the same probe provisioning runs per-run).
+
+    Returns True (proxy strategy will hold), False (runs will fall back to
+    the in-VM plain-env file), or None when the check could not run. The
+    sandbox is always removed.
+    """
+    name = f"sbxloop-secretcheck-{token_hex(4)}"
+    spec = SandboxSpec(name=name, role="agent", workspace=workspace, template=template)
+    try:
+        cli.create(spec)
+    except SbxError:
+        logger.warning("secret visibility check: could not create %s", name, exc_info=True)
+        return None
+    try:
+        result = cli.exec(name, ["sh", "-lc", f'test -n "${{{env}}}"'])
+        return result.ok
+    except SbxError:
+        logger.warning("secret visibility check failed in %s", name, exc_info=True)
+        return None
+    finally:
+        try:
+            cli.rm(name)
+        except SbxError:
+            logger.warning("secret visibility check: failed to remove %s", name, exc_info=True)