aisc-cli 0.1.0__py3-none-any.whl

aisc/cli/commands/container.py

@@ -0,0 +1,787 @@
+"""``aisc status | stop | restart | shell | switch`` — container lifecycle commands.
+
+All container operations go through an injected ``DockerExecutor``.
+Container discovery: ``--name`` override → state file → structured error.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from aisc.adapters.container_registry import resolve_target
+from aisc.adapters.docker_ import DockerExecutor, RealDockerExecutor
+from aisc.domain.models import CliError, ProcessResult
+
+
+# ---------------------------------------------------------------------------
+# Shared helper — classify process errors
+# ---------------------------------------------------------------------------
+
+def _classify_process_error(proc: ProcessResult, name: str, action: str) -> CliError:
+    """Map a failed ProcessResult to a controlled CliError with stable codes."""
+    if proc.command_not_found:
+        return CliError(
+            message="Docker CLI not found",
+            exit_code=3, error_code="AISC_ERR_DOCKER_UNAVAILABLE",
+        )
+    if proc.timed_out:
+        return CliError(
+            message=f"docker {action} timed out for container '{name}'",
+            exit_code=1, error_code="AISC_ERR_GENERAL",
+        )
+    stderr_lower = (proc.stderr or "").lower()
+    if "permission denied" in stderr_lower:
+        return CliError(
+            message=f"Permission denied accessing container '{name}'",
+            exit_code=9, error_code="AISC_ERR_PERMISSION_DENIED",
+        )
+    if any(kw in stderr_lower for kw in (
+        "cannot connect", "is the docker daemon running",
+        "connection refused", "error during connect",
+    )):
+        return CliError(
+            message="Docker daemon unreachable",
+            exit_code=3, error_code="AISC_ERR_DOCKER_UNAVAILABLE",
+        )
+    return CliError(
+        message=f"docker {action} failed for container '{name}' (exit {proc.exit_code}): "
+                f"{(proc.stderr or '').strip()[:200]}",
+        exit_code=1, error_code="AISC_ERR_GENERAL",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Container discovery
+# ---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------
+# Container discovery — delegates to container_registry.resolve_target
+# ---------------------------------------------------------------------------
+
+def discover_container(
+    name_override: Optional[str] = None,
+    explicit_root: Optional[str] = None,
+    label_override: Optional[str] = None,
+    executor: Optional[DockerExecutor] = None,
+) -> str:
+    """Discover the target container name via the registry.
+
+    Priority (handled in :func:`container_registry.resolve_target`):
+    1. ``name_override``
+    2. ``label_override`` (unique match)
+    3. ``default`` pointer (last ``run``)
+    4. single registered container
+    5. multiple → ``CliError`` listing candidates
+
+    A lazy GC prunes registry entries whose container no longer exists.
+
+    Returns:
+        Container name string.
+
+    Raises:
+        CliError: If no container can be discovered.
+    """
+    return resolve_target(
+        root=None,
+        name_override=name_override,
+        label_override=label_override,
+        executor=executor,
+        explicit_root=explicit_root,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Status result
+# ---------------------------------------------------------------------------
+
+@dataclass
+class StatusResult:
+    """Structured result of container status query."""
+    name: str = ""
+    exists: bool = False
+    running: bool = False
+    status: str = ""
+    image: str = ""
+    container_id: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "exists": self.exists,
+            "running": self.running,
+            "status": self.status,
+            "image": self.image,
+            "container_id": self.container_id,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Status command
+# ---------------------------------------------------------------------------
+
+def cmd_status(
+    name_override: Optional[str] = None,
+    explicit_root: Optional[str] = None,
+    executor: Optional[DockerExecutor] = None,
+    label_override: Optional[str] = None,
+) -> StatusResult:
+    """Query container status via ``docker inspect``.
+
+    A missing container returns ``exists=False`` (success), while daemon /
+    permission failures raise CliError.
+    """
+    exec_ = executor or RealDockerExecutor()
+    root = _active_registry_root(explicit_root) if not (name_override or label_override) else explicit_root
+    name = discover_container(name_override=name_override,
+                              explicit_root=root,
+                              label_override=label_override,
+                              executor=exec_)
+
+    # Use docker inspect with Go template for structured output
+    fmt = '{{.Name}}\t{{.State.Running}}\t{{.State.Status}}\t{{.Config.Image}}\t{{.Id}}'
+    argv = ["inspect", "--format", fmt, name]
+
+    proc = exec_.run_captured(argv, timeout=10.0)
+
+    if proc.command_not_found or proc.timed_out:
+        raise _classify_process_error(proc, name, "inspect")
+
+    stderr_lower = (proc.stderr or "").lower()
+    if proc.exit_code != 0:
+        # "No such object" / "not found" → container doesn't exist (success)
+        if any(kw in stderr_lower for kw in (
+            "no such object", "no such container", "not found",
+        )):
+            return StatusResult(name=name, exists=False)
+        # Delegate other errors to classifier
+        raise _classify_process_error(proc, name, "inspect")
+
+    # Parse tab-separated output
+    stdout = proc.stdout.strip()
+    if not stdout:
+        return StatusResult(name=name, exists=False)
+
+    parts = stdout.split("\t")
+    running = parts[1].lower() == "true" if len(parts) > 1 else False
+    status = parts[2] if len(parts) > 2 else ""
+    image = parts[3] if len(parts) > 3 else ""
+    cid = parts[4][:12] if len(parts) > 4 else ""
+
+    return StatusResult(
+        name=name,
+        exists=True,
+        running=running,
+        status=status,
+        image=image,
+        container_id=cid,
+    )
+
+
+def print_status_text(result: StatusResult) -> None:
+    """Print status in human-readable format."""
+    if not result.exists:
+        print(f"Container '{result.name}' not found.")
+        return
+
+    running_str = "running" if result.running else "stopped"
+    print(f"Container:  {result.name}")
+    print(f"Exists:     yes")
+    print(f"Running:    {running_str}")
+    print(f"Status:     {result.status}")
+    print(f"Image:      {result.image}")
+    if result.container_id:
+        print(f"ID:         {result.container_id}")
+
+
+# ---------------------------------------------------------------------------
+# Stop command
+# ---------------------------------------------------------------------------
+
+def cmd_stop(
+    name_override: Optional[str] = None,
+    explicit_root: Optional[str] = None,
+    executor: Optional[DockerExecutor] = None,
+    label_override: Optional[str] = None,
+    remove: bool = True,
+) -> Dict[str, Any]:
+    """Stop the discovered container via ``docker stop`` (F2-C: then REMOVE).
+
+    Requires the container to exist. Idempotent: stopping an already-stopped
+    container returns success. The container is unregistered from the index
+    after stop (it is no longer an active target) and — since F2-C runs are
+    detached keep-alives — removed by default, else every stop litters.
+    """
+    exec_ = executor or RealDockerExecutor()
+    root = _active_registry_root(explicit_root) if not (name_override or label_override) else explicit_root
+    name = discover_container(name_override=name_override,
+                              explicit_root=root,
+                              label_override=label_override,
+                              executor=exec_)
+
+    # First check if container exists (same derived registry root)
+    status = cmd_status(name_override=name, explicit_root=root,
+                         executor=executor)
+
+    if not status.exists:
+        raise CliError(
+            message=f"容器 '{name}' 不存在——无可停止。",
+            exit_code=1, error_code="AISC_ERR_CONTAINER_NOT_FOUND",
+        )
+
+    if status.running:
+        proc = exec_.run_captured(["stop", name], timeout=30.0)
+        if proc.exit_code != 0:
+            raise _classify_process_error(proc, name, "stop")
+    if remove:
+        # An already-stopped keep-alive container still needs its cleanup.
+        rm = exec_.run_captured(["rm", "-f", name], timeout=30.0)
+        if rm.exit_code != 0:
+            raise _classify_process_error(rm, name, "remove")
+
+    # Unregister from the multi-container index (no longer an active
+    # target). The registry root must go through _resolve_root — writing at
+    # the raw explicit_root would CREATE an empty containers.json there and
+    # shadow the real (.aisc / state-dir) one for every later lookup.
+    try:
+        from aisc.adapters.container_registry import unregister, _resolve_root
+        reg = None
+        if root:
+            reg = _resolve_root(None, root)
+        if reg is None:
+            # name/label override legs keep the legacy root resolution
+            from aisc.application.resources import locate_aisc_root
+            try:
+                reg = locate_aisc_root(explicit_root=explicit_root)
+            except Exception:
+                reg = None
+        if reg is not None:
+            unregister(reg, name)
+    except Exception:
+        pass
+
+    return {"name": name, "stopped": status.running,
+            "already_stopped": not status.running, "removed": remove}
+
+
+def cmd_stop_all(
+    explicit_root: Optional[str] = None,
+    executor: Optional[DockerExecutor] = None,
+) -> Dict[str, Any]:
+    """F2-C ``aisc stop --all``: stop + remove every CLI-owned container.
+
+    Workbench-managed runtimes (owner=workbench) are deliberately untouched —
+    the GUI owns their lifecycle (leases, reconcile); the CLI's blast radius
+    stays on its own one-shot activations.
+    """
+    exec_ = executor or RealDockerExecutor()
+    from aisc.adapters.container_registry import list_containers, unregister
+    from aisc.application.data_root import DataRootResolver
+
+    # Every workspace registry under the data root (the family's registries
+    # are workspace-scoped; the CLI's blast radius excludes Workbench-owned
+    # runtimes wherever they live).
+    shared_workspaces = DataRootResolver().resolve_shared_root() / "workspaces"
+    stopped: List[Dict[str, Any]] = []
+    skipped = 0
+    registry_dirs = [
+        p / "runtime" for p in shared_workspaces.glob("*") if (p / "runtime" / "containers.json").is_file()
+    ] if shared_workspaces.is_dir() else []
+    for reg_dir in registry_dirs:
+        for cname, meta in list_containers(reg_dir).items():
+            meta = meta or {}
+            if meta.get("owner") == "workbench":
+                skipped += 1
+                continue
+            name = str(cname)
+            if not name:
+                continue
+            stop = exec_.run_captured(["stop", name], timeout=30.0)
+            rm = exec_.run_captured(["rm", "-f", name], timeout=30.0)
+            try:
+                unregister(reg_dir, name)
+            except Exception:
+                pass
+            stopped.append({
+                "name": name,
+                "workspace": meta.get("workspace", ""),
+                "exit_code": rm.exit_code if rm.exit_code != 0 else stop.exit_code,
+            })
+    return {"stopped": stopped, "skipped": skipped}
+
+
+def print_stop_text(data: Dict[str, Any]) -> None:
+    """Print stop result in human-readable format.
+
+    F2-C stop = stop + REMOVE (detached keep-alives would otherwise litter);
+    the wording says both — English phrasing that only said "stopped" hid
+    the removal (manual test r2 note).
+    """
+    if data.get("already_stopped"):
+        print(f"容器 '{data['name']}' 此前已停止，现已移除。")
+    else:
+        print(f"容器 '{data['name']}' 已停止并移除。")
+
+
+# ---------------------------------------------------------------------------
+# Restart command
+# ---------------------------------------------------------------------------
+
+def cmd_restart(
+    name_override: Optional[str] = None,
+    explicit_root: Optional[str] = None,
+    executor: Optional[DockerExecutor] = None,
+    label_override: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Restart the discovered container via ``docker restart``.
+
+    Requires the container to exist.
+    """
+    exec_ = executor or RealDockerExecutor()
+    root = _active_registry_root(explicit_root) if not (name_override or label_override) else explicit_root
+    name = discover_container(name_override=name_override,
+                              explicit_root=root,
+                              label_override=label_override,
+                              executor=exec_)
+
+    # First check if container exists
+    status = cmd_status(name_override=name, explicit_root=explicit_root,
+                         executor=executor)
+
+    if not status.exists:
+        raise CliError(
+            message=f"Container '{name}' not found — cannot restart.",
+            exit_code=1, error_code="AISC_ERR_CONTAINER_NOT_FOUND",
+        )
+
+    argv = ["restart", name]
+    proc = exec_.run_captured(argv, timeout=30.0)
+
+    if proc.exit_code != 0:
+        raise _classify_process_error(proc, name, "restart")
+
+    return {"name": name, "restarted": True}
+
+
+def print_restart_text(data: Dict[str, Any]) -> None:
+    """Print restart result in human-readable format."""
+    print(f"Container '{data['name']}' restarted.")
+
+
+# ---------------------------------------------------------------------------
+# Shell command
+# ---------------------------------------------------------------------------
+
+def _active_registry_root(explicit_root: Optional[str]) -> Optional[str]:
+    """F2-C default leg: the ACTIVE workspace's registry root (never cwd —
+    the cwd anchor trips the data-root guard from $HOME and reads the
+    wrong registry). Shared by the no-override paths of stop/shell/
+    status/restart/switch."""
+    if explicit_root:
+        return explicit_root
+    from aisc.cli.commands import runs as cli_runs
+
+    try:
+        active = cli_runs.get_active()
+    except Exception:
+        active = None
+    if active:
+        from aisc.application.data_root import workspace_state_dir
+
+        try:
+            return str(workspace_state_dir(Path(active)))
+        except Exception:
+            return None
+    return None
+
+
+def cmd_shell(
+    name_override: Optional[str] = None,
+    explicit_root: Optional[str] = None,
+    executor: Optional[DockerExecutor] = None,
+    label_override: Optional[str] = None,
+    rest: Optional[List[str]] = None,
+) -> ProcessResult:
+    """Open an interactive shell via ``docker exec -it NAME bash``.
+
+    r2 #I: args after ``--`` pass through verbatim (``aisc shell -- ls -la``)
+    like the agent sugar — a non-interactive one-shot exec (no ``-it``).
+    Uses streaming executor for interactive terminal.  Text-only.
+    Returns ProcessResult so caller can inspect exit_code / errors.
+    """
+    exec_ = executor or RealDockerExecutor()
+    root = _active_registry_root(explicit_root) if not (name_override or label_override) else explicit_root
+    name = discover_container(name_override=name_override,
+                              explicit_root=root,
+                              label_override=label_override,
+                              executor=exec_)
+
+    # Verify container exists and is running
+    status = cmd_status(name_override=name, explicit_root=root,
+                         executor=executor)
+
+    if not status.exists:
+        raise CliError(
+            message=f"容器 '{name}' 不存在——无法打开 shell。",
+            exit_code=1, error_code="AISC_ERR_CONTAINER_NOT_FOUND",
+        )
+    if not status.running:
+        raise CliError(
+            message=f"容器 '{name}' 未在运行——无法打开 shell。",
+            exit_code=1, error_code="AISC_ERR_CONTAINER_NOT_FOUND",
+        )
+
+    passthrough = [a for a in (rest or []) if a != "--"]
+    if passthrough:
+        # one-shot, non-interactive: no -it (docker exec -t without a TTY
+        # dies), stream like the interactive case
+        argv = ["exec", name, *passthrough]
+        proc = exec_.run_streaming(argv)
+        if proc.command_not_found:
+            raise CliError(message="Docker CLI 不可用",
+                           exit_code=3, error_code="AISC_ERR_DOCKER_UNAVAILABLE")
+        return proc
+
+    # v2.1.7 S6 (Gate-S6/D10): interactive shells get the tutorial `help`
+    # via the exec environment (BASH_FUNC_* re-import) — see
+    # aisc.cli.tutorial.help_function_env. The plain `bash` argv is
+    # unchanged; nothing is written to the image or any profile.
+    argv = ["exec", "-it", name, "bash"]
+    proc = exec_.run_streaming(argv)
+
+    # Map transport errors — nonzero exit from docker exec is returned to caller
+    if proc.command_not_found or proc.timed_out:
+        raise _classify_process_error(proc, name, "exec")
+
+    return proc
+
+
+# ---------------------------------------------------------------------------
+# Switch command — scope-preserving Bash wrapper
+# ---------------------------------------------------------------------------
+#
+# ``docker exec`` starts a new process that does **not** inherit
+# ``entrypoint.sh`` dynamically exports runtime paths for PID 1.  This
+# wrapper reads the NUL-delimited /proc/1/environ
+# **without eval** using a ``while IFS= read -r -d ''`` loop and a ``case``
+# statement, so literal special characters (spaces, ``$``, ``;``, quotes,
+# backticks, glob chars) in the values survive exactly.
+#
+# The environ source path is passed as the first positional argument
+# (``$1``).  In production this is always ``/proc/1/environ``; tests may
+# substitute a temp file.  The wrapper shifts past the source and the
+# ``--`` guard, then ``exec "$@"`` with the target command.  The provider
+# / subcommand is always positional — never shell-interpolated.
+#
+# Fail-closed: if the source cannot be read or a required runtime path is
+# absent or empty the wrapper exits 101.  No home-directory fallback.
+#
+# .. code-block:: text
+#
+#    docker exec -it NAME bash -c '
+#      while IFS= read -r -d """" entry; do
+#        case "$entry" in
+#          CLAUDE_CONFIG_DIR=*) ... ;;
+#          CC_SWITCH_CONFIG_DIR=*) ... ;;
+#        esac
+#      done < "$1"
+#      shift; shift   # past source, past --
+#      [ -n "${CLAUDE_CONFIG_DIR:-}" ] && [ -n "${CC_SWITCH_CONFIG_DIR:-}" ] || exit 101
+#      export CLAUDE_CONFIG_DIR CC_SWITCH_CONFIG_DIR CODEX_CONFIG_DIR CODEX_HOME
+#      exec "$@"
+#    ' aisc-scope /proc/1/environ -- cc-switch
+_SCOPE_WRAPPER = "\n".join([
+    'if [ ! -r "$1" ]; then',
+    "  echo 'Error: Cannot read scope environment from PID 1' >&2",
+    '  exit 101',
+    'fi',
+    'unset CLAUDE_CONFIG_DIR CC_SWITCH_CONFIG_DIR CODEX_CONFIG_DIR CODEX_HOME',
+    "while IFS= read -r -d '' entry; do",
+    '  case "$entry" in',
+    '    CLAUDE_CONFIG_DIR=*) CLAUDE_CONFIG_DIR=${entry#*=} ;;',
+    '    CC_SWITCH_CONFIG_DIR=*) CC_SWITCH_CONFIG_DIR=${entry#*=} ;;',
+    '    CODEX_CONFIG_DIR=*)     CODEX_CONFIG_DIR=${entry#*=}     ;;',
+    '    CODEX_HOME=*)           CODEX_HOME=${entry#*=}           ;;',
+    '  esac',
+    'done < "$1"',
+    'shift',
+    'shift',
+    'if [ -z "${CLAUDE_CONFIG_DIR:-}" ] || [ -z "${CC_SWITCH_CONFIG_DIR:-}" ]; then',
+    "  echo 'Error: Cannot read scope environment from PID 1' >&2",
+    '  exit 101',
+    'fi',
+    'export CLAUDE_CONFIG_DIR CC_SWITCH_CONFIG_DIR CODEX_CONFIG_DIR CODEX_HOME',
+    'exec "$@"',
+    '',  # trailing newline
+])
+
+# Production environ source — always /proc/1/environ.
+_SCOPE_ENV_SOURCE = "/proc/1/environ"
+
+
+def _build_switch_argv(name: str, quick: Optional[str]) -> list:
+    """Build the ``docker exec`` argv for switch.
+
+    Wraps the target command in a Bash snippet that reads the AISC and
+    cc-switch runtime paths from PID 1's ``_SCOPE_ENV_SOURCE``
+    (a NUL-delimited environ file, normally ``/proc/1/environ``).
+
+    The source path and the ``--`` guard are passed as positional
+    arguments.  The provider / subcommand follows as positional argv,
+    **never** shell-interpolated.
+
+    Returns a list suitable for ``DockerExecutor.run_streaming``.
+    """
+    if quick:
+        return ["exec", "-it", name, "bash", "-c", _SCOPE_WRAPPER,
+                "aisc-scope", _SCOPE_ENV_SOURCE, "--",
+                "cc-switch", "-a", "claude", "provider", "switch", quick]
+    else:
+        return ["exec", "-it", name, "bash", "-c", _SCOPE_WRAPPER,
+                "aisc-scope", _SCOPE_ENV_SOURCE, "--", "cc-switch"]
+
+
+def _validate_provider_id(provider: str) -> None:
+    """Validate that *provider* is a non-empty positional token."""
+    if not provider or not provider.strip():
+        raise CliError(
+            message="Provider name required for --quick switch",
+            exit_code=2, error_code="AISC_ERR_USAGE",
+        )
+
+
+def cmd_switch(
+    name_override: Optional[str] = None,
+    explicit_root: Optional[str] = None,
+    quick: Optional[str] = None,
+    executor: Optional[DockerExecutor] = None,
+    label_override: Optional[str] = None,
+) -> ProcessResult:
+    """Switch AI provider inside the container.
+
+    Default (no --quick): ``docker exec -it NAME cc-switch`` (full TUI).
+    Quick mode uses ``cc-switch -a claude provider switch PROVIDER``.
+
+    Uses streaming executor for interactive terminal.  Text-only.
+    Returns ProcessResult so caller can inspect exit_code / errors.
+    """
+    exec_ = executor or RealDockerExecutor()
+
+    # Validate --quick provider early (before any Docker interaction)
+    if quick is not None:
+        _validate_provider_id(quick)
+        if not quick:
+            raise CliError(
+                message="Provider name required for --quick switch",
+                exit_code=2, error_code="AISC_ERR_USAGE",
+            )
+
+    root = _active_registry_root(explicit_root) if not (name_override or label_override) else explicit_root
+    name = discover_container(name_override=name_override,
+                              explicit_root=root,
+                              label_override=label_override,
+                              executor=exec_)
+
+    # Verify container exists and is running
+    status = cmd_status(name_override=name, explicit_root=root,
+                         executor=executor)
+
+    if not status.exists:
+        raise CliError(
+            message=f"Container '{name}' not found — cannot switch provider.",
+            exit_code=1, error_code="AISC_ERR_CONTAINER_NOT_FOUND",
+        )
+    if not status.running:
+        raise CliError(
+            message=f"Container '{name}' is not running — cannot switch provider.",
+            exit_code=1, error_code="AISC_ERR_CONTAINER_NOT_FOUND",
+        )
+
+    # Build argv via the scope-preserving wrapper
+    argv = _build_switch_argv(name, quick)
+
+    proc = exec_.run_streaming(argv)
+
+    if proc.command_not_found or proc.timed_out:
+        raise _classify_process_error(proc, name, "exec")
+
+    return proc
+
+
+def cmd_provider_set_key(
+    name_override: Optional[str] = None,
+    explicit_root: Optional[str] = None,
+    provider_id: Optional[str] = None,
+    agent: str = "claude",
+    executor: Optional[DockerExecutor] = None,
+    label_override: Optional[str] = None,
+) -> ProcessResult:
+    """Open cc-switch's interactive editor for a provider.
+
+    The compatibility-facing command remains ``aisc provider set-key``, but
+    credentials are entered only through ``cc-switch provider edit`` so they
+    never appear in shell history or process arguments.
+
+    Uses streaming executor for interactive terminal.  Text-only.
+    Returns ProcessResult so caller can inspect exit_code / errors.
+    """
+    exec_ = executor or RealDockerExecutor()
+
+    # Validate provider_id
+    if not provider_id or not provider_id.strip():
+        raise CliError(
+            message="Provider ID required",
+            exit_code=2, error_code="AISC_ERR_USAGE",
+        )
+
+    root = _active_registry_root(explicit_root) if not (name_override or label_override) else explicit_root
+    name = discover_container(name_override=name_override,
+                              explicit_root=root,
+                              label_override=label_override,
+                              executor=exec_)
+
+    # Verify container exists and is running
+    status = cmd_status(name_override=name, explicit_root=root,
+                         executor=executor)
+
+    if not status.exists:
+        raise CliError(
+            message=f"Container '{name}' not found — cannot set API key.",
+            exit_code=1, error_code="AISC_ERR_CONTAINER_NOT_FOUND",
+        )
+    if not status.running:
+        raise CliError(
+            message=f"Container '{name}' is not running — cannot set API key.",
+            exit_code=1, error_code="AISC_ERR_CONTAINER_NOT_FOUND",
+        )
+
+    # Build argv via the scope-preserving wrapper
+    argv = _build_provider_edit_argv(name, agent, provider_id)
+
+    proc = exec_.run_streaming(argv)
+
+    if proc.command_not_found or proc.timed_out:
+        raise _classify_process_error(proc, name, "exec")
+
+    return proc
+
+
+def _build_provider_edit_argv(
+    name: str,
+    agent: str,
+    provider_id: str,
+) -> list:
+    """Build the ``docker exec`` argv for interactive provider editing.
+
+    Wraps the target command in the same scope-preserving Bash wrapper
+    used by switch. No credential value is accepted by this function.
+
+    Returns a list suitable for ``DockerExecutor.run_streaming``.
+    """
+    return ["exec", "-it", name, "bash", "-c", _SCOPE_WRAPPER,
+            "aisc-scope", _SCOPE_ENV_SOURCE, "--",
+            "cc-switch", "-a", agent, "provider", "edit", provider_id]
+
+
+def print_switch_text(data: Dict[str, Any]) -> None:
+    """Print switch result summary."""
+    name = data.get("name", "")
+    provider = data.get("provider", "")
+    quick = data.get("quick", False)
+    if quick and provider:
+        print(f"Switched container '{name}' to provider '{provider}'.")
+    elif provider:
+        print(f"Switched container '{name}' to provider '{provider}'.")
+    else:
+        print(f"Provider switch completed for container '{name}'.")
+
+
+# ---------------------------------------------------------------------------
+# Ps command — list all registered containers
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PsRow:
+    """One row of the ``aisc ps`` table."""
+    name: str = ""
+    label: str = ""
+    status: str = ""
+    running: bool = False
+    image: str = ""
+    workspace: str = ""
+    active: bool = False
+
+
+def cmd_ps(
+    name_override: Optional[str] = None,
+    explicit_root: Optional[str] = None,
+    executor: Optional[DockerExecutor] = None,
+) -> List[PsRow]:
+    """List every registered container machine-wide, with live docker status.
+
+    Manual test r1 #1 (F2-C): activations register under the WORKSPACE's
+    state dir (data-root ``workspaces/<h>/runtime``), so the old
+    cwd-anchored single registry never saw them — scan every workspace
+    registry instead (the same data face as ``aisc workspaces``). One
+    ``docker ps -a`` round trip carries status; a registered name docker
+    does not know reads as ``gone`` (stale entry — orphan hygiene). When
+    docker is unreachable nothing is guessed: every row shows ``?``.
+
+    *explicit_root* now means the DATA ROOT override (a dir containing
+    ``workspaces/``), matching the registry anchor; the machine-global
+    ACTIVE workspace (last ``aisc run``) gets ``active=True``.
+    """
+    from aisc.cli.commands.workspaces import docker_states, registry_entries
+
+    exec_ = executor or RealDockerExecutor()
+
+    entries, defaults = registry_entries(exec_, data_root=explicit_root)
+    states, docker_ok = docker_states(exec_)
+
+    rows: List[PsRow] = []
+    for nm, meta in entries:
+        meta = meta if isinstance(meta, dict) else {}
+        name = str(nm)
+        if not name:
+            continue
+        if not docker_ok:
+            status, running = "?", False
+        elif name not in states:
+            status, running = "gone", False
+        else:
+            status = states[name]
+            running = status.startswith("Up")
+        ws = str(meta.get("workspace", ""))
+        rows.append(PsRow(
+            name=name,
+            label=str(meta.get("label", "")),
+            image=str(meta.get("image", "")),
+            workspace=ws,
+            status=status,
+            running=running,
+            # r2 #B: star the registry DEFAULT pointer — what a bare
+            # `aisc claude` actually lands in — not "any container of the
+            # active workspace" (label slots live there too).
+            active=name in defaults,
+        ))
+
+    # active first, then running, then name — glanceable and stable
+    rows.sort(key=lambda r: (not r.active, not r.running, r.name))
+    return rows
+
+
+def print_ps_text(rows: List[PsRow]) -> None:
+    """Print the ``aisc ps`` table (dead/gone rows get a cleanup hint)."""
+    if not rows:
+        print("尚无已注册容器——先 aisc run <路径> 激活工作区。")
+        return
+    print(f"{'NAME':<36} {'ACTIVE':<6} {'LABEL':<10} {'STATUS':<10} {'IMAGE':<24} WORKSPACE")
+    for r in rows:
+        label = r.label or "-"
+        star = "*" if r.active else ""
+        print(f"{r.name:<36} {star:<6} {label:<10} {r.status:<10} {r.image:<24} {r.workspace}")
+    # r2 #G: orphan hygiene — dead/gone rows exist, tell the user what to do
+    if any(not r.running for r in rows):
+        print("提示: 已停止(gone/Exited)的容器可 aisc stop --name <名> 清除，"
+              "或 aisc run --resume <别名|序号|路径> 重建。")