cloudagent-daemon 0.2.1__py3-none-any.whl

cloudagent_daemon/cli.py

@@ -0,0 +1,833 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+
+import typer
+
+
+# 1i Bug D — daemon connects directly to its WAN backend; macOS / corporate
+# system-wide SOCKS / HTTP proxy settings would otherwise be inherited via
+# urllib defaults and cause WSClient to fail with
+# "connecting through a SOCKS proxy requires python-socks" when the user
+# has macOS System Preferences → Network → Proxies enabled.
+#
+# Users who genuinely need to route the daemon through a corporate proxy
+# can opt back in via env vars BEFORE invoking the CLI; this helper only
+# applies the bypass when no override is already present.
+_DEFAULT_NO_PROXY = "*"
+_PROXY_VARS = (
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+)
+
+
+def _bypass_system_proxy_by_default() -> None:
+    """Default the daemon to NO proxy. Idempotent — safe to call multiple times."""
+    os.environ.setdefault("NO_PROXY", _DEFAULT_NO_PROXY)
+    os.environ.setdefault("no_proxy", _DEFAULT_NO_PROXY)
+    for var in _PROXY_VARS:
+        # Only clear vars; honour an explicit user opt-in by checking
+        # CLOUDAGENT_USE_SYSTEM_PROXY=1 first.
+        if os.environ.get("CLOUDAGENT_USE_SYSTEM_PROXY") == "1":
+            return
+        if var in os.environ:
+            del os.environ[var]
+
+app = typer.Typer(
+    name="cloudagent-daemon",
+    help="Local daemon for cloudagent — runs on user's machine and bridges claude subprocesses to the cloudagent backend.",
+    no_args_is_help=True,
+)
+agent_app = typer.Typer(no_args_is_help=True, help="Manage local agent workspaces.")
+app.add_typer(agent_app, name="agent")
+
+
+# M6 multi-profile (2026-05-18) — every stateful command takes
+# ``--profile <name>``; default ``"default"`` is byte-for-byte identical
+# to the pre-multi-profile behaviour. ``CLOUDAGENT_DAEMON_PROFILE`` env
+# is the cross-process fallback (set in plist/unit so spawned children
+# inherit the active profile without an explicit flag).
+_PROFILE_HELP = (
+    "Profile name (default 'default'). Run multiple daemons against "
+    "different backends by giving each a unique profile."
+)
+
+
+def _resolve_cli_profile(profile: str | None) -> str:
+    """Validate + resolve a CLI ``--profile`` value with friendly errors."""
+    from .paths import resolve_profile
+
+    try:
+        return resolve_profile(profile)
+    except ValueError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2)
+
+
+@app.command()
+def login(
+    server: str = typer.Option(..., "--server", help="Backend server URL."),
+    api_key: str = typer.Option(
+        ...,
+        "--api-key",
+        prompt=True,
+        hide_input=True,
+        help="Machine API key (sk_machine_***).",
+    ),
+    insecure: bool = typer.Option(
+        False,
+        "--insecure",
+        help="Skip TLS certificate verification (for self-signed servers).",
+    ),
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Authorize this machine and store sk_machine_*** locally."""
+    _bypass_system_proxy_by_default()
+    from .login import normalize_server_url, verify_and_capture_host_id
+    from .config import DaemonConfig
+
+    profile_name = _resolve_cli_profile(profile)
+
+    try:
+        server = normalize_server_url(server)
+    except ValueError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2)
+
+    if not api_key.startswith("sk_machine_"):
+        typer.echo("Error: api_key must start with sk_machine_", err=True)
+        raise typer.Exit(2)
+
+    if insecure:
+        typer.secho(
+            "⚠️  Insecure: TLS certificate verification disabled.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+
+    try:
+        host_id = asyncio.run(
+            verify_and_capture_host_id(server, api_key, insecure=insecure)
+        )
+    except Exception as exc:
+        typer.echo(f"Login failed: {exc}", err=True)
+        raise typer.Exit(1)
+
+    cfg = DaemonConfig(server_url=server, machine_api_key=api_key, host_id=host_id)
+    cfg.save_default(profile_name)
+    typer.echo(
+        f"Logged in. host_id={host_id} profile={profile_name}"
+    )
+
+
+@app.command()
+def start(
+    server_url: str | None = typer.Option(
+        None,
+        "--server-url",
+        help="Backend URL for one-shot mode (pair with --api-key; bypasses config.json).",
+    ),
+    api_key: str | None = typer.Option(
+        None,
+        "--api-key",
+        help="Machine API key for one-shot mode (pair with --server-url).",
+    ),
+    insecure: bool = typer.Option(
+        False,
+        "--insecure",
+        help="Skip TLS certificate verification (for self-signed servers).",
+    ),
+    transport: str = typer.Option(
+        "auto",
+        "--transport",
+        help=(
+            "Transport: 'sse' (SSE+POST, default), 'ws' (legacy WebSocket), "
+            "or 'auto' (alias for 'sse' in v0.2.0)."
+        ),
+    ),
+    workspace_root: Path | None = typer.Option(
+        None,
+        "--workspace-root",
+        "-w",
+        help=(
+            "Root directory for all agent workspaces. Default: "
+            "~/.cloudagent/agents/ (or agents-<profile>/ for named "
+            "profiles). The chosen path is persisted to state.json "
+            "so subsequent runs without the flag reuse it."
+        ),
+    ),
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Connect to the server and run the daemon main loop.
+
+    Default: SSE+POST transport (works behind Clash/proxy/middleboxes).
+    Pass ``--transport ws`` to use the legacy WebSocket path.
+
+    Default config: loads ``~/.cloudagent/daemon/config.json`` (run
+    ``login`` first). One-shot: pass ``--server-url`` + ``--api-key``
+    together to run without persisting any config — slock-equivalent
+    UX for ephemeral / CI use.
+    """
+    _bypass_system_proxy_by_default()
+    from .config import DaemonConfig, DaemonState
+    from .login import normalize_server_url, verify_and_capture_host_id
+    from .main_loop import run_daemon
+    from .runtime_detect import detect_runtimes
+
+    profile_name = _resolve_cli_profile(profile)
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    # Wave C #3 — opt-in JSONL formatter (env-gated; default off
+    # preserves grep workflow over launchd.err.log).
+    from .jsonl_logging import configure_logging as _configure_jsonl_logging
+    _configure_jsonl_logging()
+
+    transport = (transport or "auto").lower()
+    if transport not in ("auto", "sse", "ws"):
+        typer.echo(
+            f"Error: --transport must be 'auto', 'sse', or 'ws' (got {transport!r})",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    if insecure:
+        typer.secho(
+            "⚠️  Insecure: TLS certificate verification disabled.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+
+    if server_url is not None and api_key is not None:
+        # One-shot mode: skip config persistence entirely.
+        if not api_key.startswith("sk_machine_"):
+            typer.echo(
+                "Error: --api-key must start with sk_machine_",
+                err=True,
+            )
+            raise typer.Exit(2)
+        try:
+            server_url = normalize_server_url(server_url)
+        except ValueError as exc:
+            typer.echo(f"Error: {exc}", err=True)
+            raise typer.Exit(2)
+        try:
+            host_id = asyncio.run(
+                verify_and_capture_host_id(
+                    server_url, api_key, insecure=insecure
+                )
+            )
+        except Exception as exc:
+            typer.echo(
+                f"Failed to verify key with server: {exc}", err=True
+            )
+            raise typer.Exit(1)
+        cfg = DaemonConfig(
+            server_url=server_url,
+            machine_api_key=api_key,
+            host_id=host_id,
+        )
+    elif server_url is not None or api_key is not None:
+        typer.echo(
+            "Error: --server-url and --api-key must be used together",
+            err=True,
+        )
+        raise typer.Exit(2)
+    else:
+        try:
+            cfg = DaemonConfig.load_default(profile_name)
+        except FileNotFoundError:
+            from .paths import DEFAULT_PROFILE
+
+            extra = (
+                ""
+                if profile_name == DEFAULT_PROFILE
+                else f" --profile {profile_name}"
+            )
+            typer.echo(
+                f"Error: not logged in for profile {profile_name!r}. "
+                f"Run `cloudagent-daemon login{extra} --server ... "
+                f"--api-key sk_machine_...` first, or pass --server-url "
+                f"+ --api-key for one-shot mode.",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+    state = (
+        DaemonState.load_default(profile_name)
+        if DaemonState.default_path(profile_name).exists()
+        else DaemonState()
+    )
+
+    # Task #113 (2026-05-12) — resolve --workspace-root, with fallback
+    # to whatever was persisted on the last start. If the user passes
+    # the flag we tilde-expand + resolve to abspath + mkdir(parents=
+    # True, exist_ok=True) and persist it back to state.json so the
+    # next launchctl restart picks it up without re-passing the flag.
+    # If the user doesn't pass the flag we honour the persisted
+    # value; if state.json doesn't have one either we leave it None
+    # and ``Workspace`` falls back to its compiled-in default.
+    if workspace_root is not None:
+        workspace_root = Path(
+            os.path.expanduser(str(workspace_root))
+        ).resolve()
+        workspace_root.mkdir(parents=True, exist_ok=True)
+        state.workspace_root = str(workspace_root)
+        state.save_default(profile_name)
+    elif state.workspace_root:
+        workspace_root = Path(state.workspace_root)
+
+    # Print detected runtimes for user feedback (slock-equivalent UX).
+    runtimes = detect_runtimes()
+    if runtimes:
+        typer.echo("Detected runtimes:")
+        for r in runtimes:
+            typer.echo(f"  ✓ {r.name} {r.version}  ({r.binary})")
+    else:
+        typer.echo("No AI coding runtimes detected on PATH.")
+    from .paths import DEFAULT_PROFILE as _DEFAULT_PROFILE
+
+    profile_suffix = (
+        ""
+        if profile_name == _DEFAULT_PROFILE
+        else f" [profile={profile_name}]"
+    )
+    typer.echo(
+        f"Connecting to {cfg.server_url} as host {cfg.host_id}{profile_suffix}..."
+    )
+    # Belt-and-suspenders flush — the plist/systemd unit also sets
+    # PYTHONUNBUFFERED=1, but if a future deploy ships without that env
+    # var the detect lines would otherwise sit in stdout's 8 KB block
+    # buffer forever (long-running process never exits to flush). Users
+    # tailing launchd.out.log would see stale or empty output and assume
+    # detection failed (incident 2026-05-11).
+    sys.stdout.flush()
+    sys.stderr.flush()
+
+    # Test/override hooks via environment variables (used by E2E tests to
+    # inject a fake claude binary and a short-path unix socket).
+    claude_binary: str = os.environ.get("CLOUDAGENT_DAEMON_CLAUDE_BINARY", "claude")
+    socket_path_override: Path | None = (
+        Path(os.environ["CLOUDAGENT_DAEMON_SOCKET_PATH"])
+        if "CLOUDAGENT_DAEMON_SOCKET_PATH" in os.environ
+        else None
+    )
+
+    from .paths import profile_pid_path, profile_lock_path
+
+    pid_path = profile_pid_path(profile_name)
+    pid_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # M6 multi-profile (proposal §3.5) — best-effort exclusive lock so
+    # ``cloudagent-daemon start --profile fr`` rejects fast when launchd
+    # is already running an fr daemon. fcntl.flock is advisory + per-
+    # process-table; fine for this single-user, single-host scope.
+    lock_path = profile_lock_path(profile_name)
+    lock_fd: int | None = None
+    try:
+        import fcntl
+
+        lock_fd = os.open(
+            str(lock_path), os.O_RDWR | os.O_CREAT | os.O_CLOEXEC, 0o600
+        )
+        try:
+            fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            # Surface the holder's PID if recoverable.
+            existing_pid: str = ""
+            if pid_path.exists():
+                try:
+                    existing_pid = pid_path.read_text().strip()
+                except OSError:
+                    existing_pid = ""
+            os.close(lock_fd)
+            lock_fd = None
+            hint = (
+                f"running pid={existing_pid}"
+                if existing_pid
+                else "another process holds the lock"
+            )
+            typer.echo(
+                f"Error: profile {profile_name!r} already has a daemon "
+                f"running ({hint}). Stop it via "
+                f"`cloudagent-daemon stop "
+                f"{'' if profile_name == _DEFAULT_PROFILE else f'--profile {profile_name} '}`"
+                f"or `uninstall-service "
+                f"{'' if profile_name == _DEFAULT_PROFILE else f'--profile {profile_name}'}`"
+                f" before starting another.",
+                err=True,
+            )
+            raise typer.Exit(1)
+    except ImportError:
+        # fcntl missing (extremely rare on Unix; guards against weird
+        # static-builds). Skip locking rather than crash — single-host
+        # multi-profile is best-effort safety, not a hard invariant.
+        lock_fd = None
+
+    pid_path.write_text(str(os.getpid()))
+
+    # Pin profile in env so any subprocess we spawn (mcp_bridge, claude
+    # children) inherits it without needing an explicit --profile flag.
+    from .paths import ENV_VAR as _PROFILE_ENV_VAR
+
+    os.environ[_PROFILE_ENV_VAR] = profile_name
+
+    def _install_sigterm_handler(loop: asyncio.AbstractEventLoop) -> None:
+        """Convert SIGTERM into a graceful asyncio cancellation.
+
+        Without this, SIGTERM kills the process immediately (SIG_DFL) so the
+        ``finally: pid_path.unlink()`` block never runs. We install a handler
+        that cancels the main daemon task, letting asyncio unwind cleanly.
+        """
+        main_task = asyncio.current_task()
+        if main_task is None:
+            return  # pragma: no cover — shouldn't happen inside asyncio.run
+        loop.remove_signal_handler(signal.SIGTERM)
+        loop.add_signal_handler(
+            signal.SIGTERM,
+            lambda: main_task.cancel("SIGTERM"),
+        )
+
+    # M6 — derive per-profile socket + state paths so non-default
+    # profiles get their own bridge.sock under
+    # ``~/.cloudagent/daemon/profiles/<name>/``. The env-var override
+    # still wins (used by E2E tests to inject a short-path socket).
+    from .paths import profile_socket_path, profile_state_path
+
+    effective_socket_path = (
+        socket_path_override
+        if socket_path_override is not None
+        else profile_socket_path(profile_name)
+    )
+    effective_state_path = profile_state_path(profile_name)
+
+    async def _start_with_sigterm() -> None:
+        _install_sigterm_handler(asyncio.get_running_loop())
+        await run_daemon(
+            cfg,
+            state,
+            claude_binary=claude_binary,
+            socket_path=effective_socket_path,
+            state_path=effective_state_path,
+            insecure=insecure,
+            transport=transport,
+            workspace_root=workspace_root,
+            profile=profile_name,
+        )
+
+    try:
+        asyncio.run(_start_with_sigterm())
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        # Ctrl-C or SIGTERM (via cancel) are the expected shutdown paths.
+        pass
+    finally:
+        pid_path.unlink(missing_ok=True)
+        if lock_fd is not None:
+            try:
+                os.close(lock_fd)
+            except OSError:
+                pass
+
+
+@app.command()
+def status(
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Show daemon connection status and bound agents."""
+    from .config import DaemonConfig
+    from .paths import profile_pid_path
+
+    profile_name = _resolve_cli_profile(profile)
+    pid_file = profile_pid_path(profile_name)
+    if not pid_file.exists():
+        typer.echo(f"● daemon not running for profile {profile_name!r} (no PID file)")
+        raise typer.Exit(1)
+    try:
+        pid = int(pid_file.read_text().strip())
+    except (ValueError, OSError):
+        typer.echo(f"● daemon stale PID file (corrupt) profile={profile_name!r}")
+        raise typer.Exit(1)
+    if not _pid_alive(pid):
+        typer.echo(
+            f"● daemon stale PID file (pid={pid} not alive) profile={profile_name!r}"
+        )
+        raise typer.Exit(1)
+    try:
+        cfg = DaemonConfig.load_default(profile_name)
+    except FileNotFoundError:
+        typer.echo(
+            f"● daemon running (pid={pid}, profile={profile_name!r}) but no config "
+            f"— login first"
+        )
+        return
+    typer.echo(f"● daemon running (pid={pid})")
+    typer.echo(f"  profile: {profile_name}")
+    typer.echo(f"  server: {cfg.server_url}")
+    typer.echo(f"  host_id: {cfg.host_id}")
+
+
+@app.command()
+def doctor(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the full report as a single JSON object instead of "
+        "the human-readable text rendering.",
+    ),
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Run a daemon health self-check and print a status report.
+
+    Wave C #3. Reads ``~/.cloudagent/daemon/state.json``,
+    ``~/.cloudagent/agents/<id>/.meta/`` files, and scrapes the running
+    daemon's ``/metrics`` unix socket (best-effort — falls back to
+    on-disk-only signals when the daemon is down).
+
+    Exit codes:
+      * 0 — all checks passed
+      * 1 — at least one signal returned ALERT (daemon down, SSE
+        silent past 180s, outbox has stuck spawns, or > 20% wake
+        failure rate)
+    """
+    from dataclasses import asdict
+    import json as _json
+
+    from .doctor import collect_report, render_report
+
+    profile_name = _resolve_cli_profile(profile)
+    report = collect_report(profile=profile_name)
+    if json_output:
+        typer.echo(_json.dumps(asdict(report), default=str, indent=2))
+    else:
+        typer.echo(render_report(report))
+    alert = any(status == "ALERT" for _, status, _ in report.health_signals())
+    raise typer.Exit(1 if alert else 0)
+
+
+@app.command()
+def stop(
+    timeout: float = typer.Option(10.0, "--timeout", help="Seconds to wait for clean exit"),
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Gracefully stop the daemon (SIGTERM via PID file)."""
+    from .paths import profile_pid_path
+
+    profile_name = _resolve_cli_profile(profile)
+    pid_file = profile_pid_path(profile_name)
+    if not pid_file.exists():
+        typer.echo(f"daemon not running for profile {profile_name!r} (no PID file)")
+        raise typer.Exit(0)
+    try:
+        pid = int(pid_file.read_text().strip())
+    except (ValueError, OSError):
+        typer.echo("stale PID file — removing")
+        pid_file.unlink(missing_ok=True)
+        raise typer.Exit(0)
+    if not _pid_alive(pid):
+        typer.echo(f"daemon already stopped (pid={pid} not alive); cleaning up PID file")
+        pid_file.unlink(missing_ok=True)
+        raise typer.Exit(0)
+    typer.echo(f"sending SIGTERM to pid={pid}...")
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        pid_file.unlink(missing_ok=True)
+        typer.echo("process already gone")
+        raise typer.Exit(0)
+    # Wait up to `timeout` seconds for clean exit
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if not _pid_alive(pid):
+            typer.echo("✓ daemon stopped cleanly")
+            return
+        time.sleep(0.1)
+    typer.echo(f"daemon did not exit within {timeout}s; sending SIGKILL")
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    raise typer.Exit(1)
+
+
+def _pid_alive(pid: int) -> bool:
+    """Return True if a process with this PID exists.
+
+    Uses os.kill(pid, 0) which sends signal 0 — does nothing but checks
+    permission/existence."""
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Process exists, owned by another user
+        return True
+    return True
+
+
+@app.command("install-service")
+def install_service_cmd(
+    server_url: str | None = typer.Option(
+        None,
+        "--server-url",
+        help="Persisted in service unit (else uses ~/.cloudagent/daemon/config.json).",
+    ),
+    api_key: str | None = typer.Option(
+        None,
+        "--api-key",
+        help="Persisted in service unit (else uses ~/.cloudagent/daemon/config.json).",
+    ),
+    insecure: bool = typer.Option(
+        False,
+        "--insecure",
+        help="Pass --insecure on each spawn (skip TLS verification).",
+    ),
+    workspace_root: Path | None = typer.Option(
+        None,
+        "--workspace-root",
+        "-w",
+        help=(
+            "Root directory for all agent workspaces, baked into the "
+            "service unit (default: ~/.cloudagent/agents/ or "
+            "~/.cloudagent/agents-<profile>/ for named profiles). "
+            "Tilde-expanded + resolved to an absolute path before "
+            "being written to the plist / systemd unit."
+        ),
+    ),
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Install daemon as a launchd (macOS) or systemd (Linux) user service.
+
+    Service auto-starts at login, auto-restarts on crash. Use uninstall-service
+    to remove. View logs:
+
+      macOS (default profile):  tail -F ~/.cloudagent/daemon/logs/launchd.{out,err}.log
+      macOS (named profile fr): tail -F ~/.cloudagent/daemon/profiles/fr/logs/launchd.{out,err}.log
+      Linux:                    journalctl --user -u cloudagent-daemon[-<profile>] -f
+    """
+    from .config import DaemonState
+    from .paths import (
+        DEFAULT_PROFILE,
+        profile_state_path,
+        profile_launchd_label,
+        profile_systemd_unit_name,
+    )
+    from .service import detect_platform, install_service
+
+    profile_name = _resolve_cli_profile(profile)
+
+    # Task #115 (2026-05-12) — same resolve sequence the ``start``
+    # command uses (tilde-expand → resolve → mkdir). We also persist
+    # to state.json so a later ``cloudagent-daemon start`` (no flag)
+    # picks up the same root.
+    resolved_workspace_root: str | None = None
+    if workspace_root is not None:
+        resolved = Path(
+            os.path.expanduser(str(workspace_root))
+        ).resolve()
+        resolved.mkdir(parents=True, exist_ok=True)
+        resolved_workspace_root = str(resolved)
+        state = (
+            DaemonState.load_default(profile_name)
+            if profile_state_path(profile_name).exists()
+            else DaemonState()
+        )
+        state.workspace_root = resolved_workspace_root
+        state.save_default(profile_name)
+
+    # Surface "this is an update" rather than silently overwriting an
+    # existing plist/unit — proposal §2.1 step 5 commercial-grade ask.
+    existing_label = profile_launchd_label(profile_name)
+    existing_unit = profile_systemd_unit_name(profile_name)
+    plat_now = None
+    try:
+        plat_now = detect_platform()
+    except RuntimeError:
+        pass
+    if plat_now == "macos":
+        existing_path = (
+            Path.home() / "Library" / "LaunchAgents" / f"{existing_label}.plist"
+        )
+        if existing_path.exists():
+            typer.echo(
+                f"(updating existing profile {profile_name!r} — plist will be replaced)"
+            )
+    elif plat_now == "linux":
+        existing_path = Path.home() / ".config" / "systemd" / "user" / existing_unit
+        if existing_path.exists():
+            typer.echo(
+                f"(updating existing profile {profile_name!r} — unit file will be replaced)"
+            )
+
+    try:
+        plat = detect_platform()
+        path = install_service(
+            server_url=server_url,
+            api_key=api_key,
+            insecure=insecure,
+            workspace_root=resolved_workspace_root,
+            profile=profile_name,
+        )
+    except RuntimeError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"✓ Installed {plat} service unit: {path}")
+    if profile_name != DEFAULT_PROFILE:
+        typer.echo(f"  profile: {profile_name}")
+    typer.echo("Daemon will auto-restart on crash and start at login.")
+
+
+@app.command("uninstall-service")
+def uninstall_service_cmd(
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Stop + remove the launchd / systemd service unit for *profile*."""
+    from .service import detect_platform, uninstall_service
+
+    profile_name = _resolve_cli_profile(profile)
+
+    try:
+        plat = detect_platform()
+        removed = uninstall_service(profile=profile_name)
+    except RuntimeError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(1)
+    if removed:
+        typer.echo(f"✓ Uninstalled {plat} service (profile={profile_name!r})")
+    else:
+        typer.echo(
+            f"({plat} service for profile {profile_name!r} was not installed)",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+
+@app.command("list-profiles")
+def list_profiles_cmd() -> None:
+    """List installed daemon profiles with their server URLs and live status."""
+    from .config import DaemonConfig
+    from .paths import (
+        list_installed_profiles,
+        profile_pid_path,
+    )
+
+    profiles = list_installed_profiles()
+    if not profiles:
+        typer.echo("No profiles installed. Run `cloudagent-daemon login ...` first.")
+        return
+
+    for name in profiles:
+        try:
+            cfg = DaemonConfig.load_default(name)
+            server = cfg.server_url
+            host_id = cfg.host_id
+        except (FileNotFoundError, ValueError, OSError) as exc:
+            server = f"<unreadable: {exc.__class__.__name__}>"
+            host_id = "?"
+        pid_file = profile_pid_path(name)
+        running = "—"
+        pid_str = ""
+        if pid_file.exists():
+            try:
+                pid = int(pid_file.read_text().strip())
+            except (ValueError, OSError):
+                running = "stale-pid"
+            else:
+                running = "running" if _pid_alive(pid) else "stopped"
+                pid_str = f" pid={pid}"
+        typer.echo(f"● {name}")
+        typer.echo(f"    server:  {server}")
+        typer.echo(f"    host_id: {host_id}")
+        typer.echo(f"    status:  {running}{pid_str}")
+
+
+@app.command("mcp-bridge", hidden=True)
+def mcp_bridge(
+    agent_id: str = typer.Option(..., "--agent-id", help="Agent ID this bridge serves."),
+    token_file: Path | None = typer.Option(
+        None,
+        "--token-file",
+        help=(
+            "Path to per-spawn token file (Phase 1: optional; tolerated "
+            "when missing — see 1i Bug B). Will be enforced once the "
+            "spec §6.6 per-spawn token scheme is fully wired."
+        ),
+    ),
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """[internal] stdio MCP server invoked by claude subprocess."""
+    from .mcp_bridge import run_bridge
+
+    profile_name = _resolve_cli_profile(profile)
+    asyncio.run(
+        run_bridge(agent_id=agent_id, token_file=token_file, profile=profile_name)
+    )
+
+
+@agent_app.command("register")
+def agent_register(
+    agent_id: str = typer.Option(..., "--agent-id", help="Agent ID already bound on the server."),
+    role: str = typer.Option("staff", "--role", help="Agent role (staff or chief)."),
+    is_chief: bool = typer.Option(False, "--chief", help="Mark agent as chief."),
+    name: str | None = typer.Option(None, "--name", help="Human-readable agent name."),
+    workspace: str | None = typer.Option(None, "--workspace-slug", help="Workspace slug."),
+    reports_to: str | None = typer.Option(None, "--reports-to", help="Superior agent ID."),
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Create local workspace for an agent already bound on server."""
+    from .workspace import Workspace
+
+    from .paths import DEFAULT_PROFILE
+
+    profile_name = _resolve_cli_profile(profile)
+    identity = {
+        "agent_id": agent_id,
+        "role": role,
+        "is_chief": is_chief,
+        "agent_name": name or agent_id,
+        "workspace_slug": workspace or "default",
+        "reports_to": reports_to or ("self" if is_chief else "(unset)"),
+    }
+    # Backward-compat: default profile uses the old single-arg ctor so
+    # tests / downstream code that monkeypatches ``Workspace`` with a
+    # narrower stub keep working byte-for-byte.
+    ws_obj = (
+        Workspace()
+        if profile_name == DEFAULT_PROFILE
+        else Workspace(profile=profile_name)
+    )
+    ws = ws_obj.ensure(agent_id, identity)
+    suffix = "" if profile_name == DEFAULT_PROFILE else f" (profile={profile_name!r})"
+    typer.echo(f"✓ Registered {agent_id} at {ws.path}{suffix}")
+
+
+@agent_app.command("unregister")
+def agent_unregister(
+    agent_id: str = typer.Option(..., "--agent-id", help="Agent ID to remove locally."),
+    profile: str | None = typer.Option(None, "--profile", help=_PROFILE_HELP),
+) -> None:
+    """Mark local workspace as archived (30-day retention)."""
+    from .workspace import Workspace
+
+    from .paths import DEFAULT_PROFILE
+
+    profile_name = _resolve_cli_profile(profile)
+    ws_obj = (
+        Workspace()
+        if profile_name == DEFAULT_PROFILE
+        else Workspace(profile=profile_name)
+    )
+    ws_obj.archive(agent_id)
+    suffix = "" if profile_name == DEFAULT_PROFILE else f" (profile={profile_name!r})"
+    typer.echo(f"✓ Archived {agent_id}{suffix}")