Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

86.0 KB
Raw Blame
"""CLI commands for remote devbox management.

Provides hogli devbox:* commands for managing Coder-based remote dev environments.
"""

from __future__ import annotations

import os
import sys
import errno
import shlex
import shutil
import socket
import tempfile
import functools
import subprocess
import urllib.parse
from collections.abc import Callable
from dataclasses import dataclass
from pathlib import Path
from typing import Any

import click
from hogli import telemetry
from hogli.manifest import get_manifest

from ..git_signing import DEVBOX_FEEDBACK_HINT, DEVBOX_SIGNING_NOTE, signs_with_secure_enclave_key
from . import (
    herdr as herdr_app,
    mutagen,
)
from .coder import (
    CLAUDE_CODE_OAUTH_ENV,
    DEFAULT_PRESET,
    DEFAULT_REGION,
    DEFAULT_TEMPLATE,
    EXPECTED_TAILNET,
    GIT_SIGNING_KEY_SECRET,
    REGIONS,
    REMOTE_REPO_PATH,
    _diagnose_unreachable_coder,
    _fail,
    _ssh_host_alias,
    clone_workspace,
    coder_authenticated,
    coder_installed,
    coder_reachable,
    coder_ssh_alias_configured,
    create_workspace,
    delete_user_secret,
    delete_workspace,
    ensure_coder_authenticated,
    ensure_coder_installed,
    ensure_coder_on_path,
    ensure_coder_reachable,
    ensure_runtime_ready,
    exec_replace,
    extract_workspace_label,
    get_coder_url,
    get_coder_user_info,
    get_default_git_identity,
    get_shared_users,
    get_sharing_status,
    get_source_instance_id,
    get_username,
    get_workspace,
    get_workspace_disk_size,
    get_workspace_name,
    get_workspace_region,
    get_workspace_status,
    has_claude_oauth_secret,
    list_coder_users,
    list_shared_workspaces,
    list_user_secrets,
    list_user_workspaces,
    logs_replace,
    maybe_configure_ssh,
    open_cursor,
    open_in_browser,
    open_vscode,
    open_web_ide,
    parse_workspace_target,
    port_forward_replace,
    print_setup_summary,
    region_from_workspace_name,
    restart_workspace,
    run_with_capacity_fallback,
    server_supports_user_secrets,
    share_workspace,
    ssh_replace,
    start_workspace,
    stop_workspace,
    tailscale_state,
    unshare_workspace,
    update_workspace,
    upsert_user_secret,
    user_secret_exists,
    wait_for_agent_ready,
)
from .config import (
    DevboxConfig,
    clear_dotfiles_uri,
    clear_git_identity,
    clear_region,
    clear_worktree_auto_sources,
    clear_worktree_box_cleanup,
    clear_worktree_provider,
    load_config,
    load_worktree_boxes,
    save_dotfiles_uri,
    save_git_identity,
    save_region,
)

_LEGACY_KEYCHAIN_SERVICE = "posthog-claude-oauth-token"
_POSTHOG_COMMIT_SIGNING_HANDBOOK_URL = "https://posthog.com/handbook/engineering/security#commit-signing"

# Reaching a devbox requires a Tailscale ACL grant. The cloud-infra tailnet
# policy grants group:employees the remote-dev VPC (10.70.0.0/16) that hosts the
# Coder control plane; without it every devbox command fails at the
# reachability check.
_TAILNET_ACCESS_PREREQ = (
    f"Devbox access needs you on the `{EXPECTED_TAILNET}` tailnet. The dev, "
    "prod-us, prod-eu and internal tailnets are for CI runners and subnet "
    "routers and don't reach devboxes. Every PostHog employee has access "
    "through `group:employees` in posthog-cloud-infra/tailnet-policy.hujson.\n"
    "    Still blocked on the right tailnet? Ask Team DevEx."
)

WORKSPACE_STATUS_COLORS = {
    "running": "green",
    "stopped": "yellow",
    "starting": "cyan",
    "stopping": "yellow",
    "failed": "red",
    "deleting": "red",
}
PENDING_WORKSPACE_STATES = {"starting", "stopping", "deleting"}

# The Coder CLI resolves a mutable parameter to its last-build value even when
# `--parameter` passes a new one, so hogli can only set parameters at creation.
_CHANGE_PARAMETER_HINT = "To change it on an existing devbox, edit the devbox's parameters in the Coder dashboard."


def resolve_workspace_name(
    workspace: str | None, *, region: str | None = None
) -> tuple[str, list[dict[str, Any]] | None]:
    """Resolve a workspace target into a full workspace name.

    Supports:
    - ``None`` -> user's default workspace (auto-selects when only one exists)
    - ``"@user"`` -> another user's default workspace
    - ``"@user/label"`` -> another user's labeled workspace
    - ``"label"`` -> current user's labeled workspace

    Returns (name, workspaces) where workspaces is the already-fetched list
    when available, so callers can skip a second ``_list_workspaces`` call.

    ``region`` controls the region suffix used when constructing names for
    workspaces that don't exist yet (a bare ``devbox:start --region`` bypasses
    this resolver and targets the region's default name directly). When
    resolving an OWN label against the user's actual workspaces, the region
    suffix is treated as a preference, not a constraint: if the preferred
    name doesn't exist but a workspace with the same label exists in another
    region, that one is returned. The same fallback applies to the default
    workspace in the multi-box case. This keeps a saved region pref from
    silently masking existing workspaces created before the pref was set.
    """
    effective_region = region if region is not None else _preferred_region()
    if workspace is not None:
        target_name = parse_workspace_target(workspace, region=effective_region)
        # Shared workspace targets (`@user[/label]`) are looked up against the
        # remote owner, so cross-region label fallback is the owner's
        # responsibility -- skip it here.
        if workspace.startswith("@"):
            return target_name, None
        return _resolve_own_label(target_name)

    workspaces = list_user_workspaces()

    if len(workspaces) == 0:
        return get_workspace_name(region=effective_region), workspaces

    if len(workspaces) == 1:
        return workspaces[0]["name"], workspaces

    # Multiple workspaces -- prefer the effective region's default, then
    # defaults in other regions (a region pref should not mask the box the
    # user actually has -- same philosophy as the label fallback above).
    existing_names = {ws.get("name") for ws in workspaces}
    for candidate_region in (effective_region, *(r for r in REGIONS if r != effective_region)):
        default_name = get_workspace_name(region=candidate_region)
        if default_name in existing_names:
            return default_name, workspaces

    # No default among multiple -- require explicit workspace argument
    labels = [extract_workspace_label(ws["name"]) or "(default)" for ws in workspaces]
    _fail("Multiple workspaces found. Specify which one:\n" + "".join(f"  {lbl}\n" for lbl in labels))
    raise SystemExit(1)  # unreachable; helps ty see the function doesn't fall through


def _resolve_own_label(target_name: str) -> tuple[str, list[dict[str, Any]] | None]:
    """Return ``(name, workspaces)`` for an own-label target, falling back across regions.

    If ``target_name`` matches an existing workspace, return it directly.
    Otherwise look for any of the user's workspaces with the same label and
    return that. When no candidate exists, return ``target_name`` so the
    downstream "not found" path runs with a stable name.
    """
    workspaces = list_user_workspaces()
    if any(ws.get("name") == target_name for ws in workspaces):
        return target_name, workspaces
    label = extract_workspace_label(target_name)
    if label is not None:
        for ws in workspaces:
            if extract_workspace_label(ws.get("name", "")) == label:
                return ws["name"], workspaces
    return target_name, workspaces


def _local_port_is_available(port: int) -> bool:
    """Return whether the given localhost TCP port can be bound."""
    for host in ("127.0.0.1", "::1"):
        family = socket.AF_INET6 if ":" in host else socket.AF_INET
        try:
            with socket.socket(family, socket.SOCK_STREAM) as sock:
                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
                sock.bind((host, port))
        except OSError as err:
            if err.errno in (errno.EAFNOSUPPORT, errno.EADDRNOTAVAIL):
                continue
            return False
    return True


def workspace_argument(fn: Callable[..., Any]) -> Callable[..., Any]:
    """Shared Click decorator adding an optional ``WORKSPACE`` positional argument.

    Accepts a label for the current user's workspace, or ``@user[/label]``
    for another user's shared workspace.  ``--name`` / ``-n`` is accepted as
    an explicit alternative (e.g. ``--name api`` instead of just ``api``).
    """

    @click.argument("workspace", required=False, default=None)
    @click.option("--name", "-n", "workspace_name", default=None, help="Workspace label or @user[/label] target")
    @functools.wraps(fn)
    def wrapper(*args: Any, workspace: str | None = None, workspace_name: str | None = None, **kwargs: Any) -> Any:
        if workspace and workspace_name:
            raise click.UsageError("Pass WORKSPACE or --name, not both.")
        return fn(*args, workspace=workspace_name or workspace, **kwargs)

    return wrapper


def _print_connection_info(name: str) -> None:
    """Print connection commands after workspace is ready."""
    suffix = _workspace_arg_suffix(name)
    commands = [
        ("SSH", "devbox:ssh"),
        ("Open", "devbox:open"),
        ("VS Code", "devbox:open --vscode"),
        ("Cursor", "devbox:open --cursor"),
        ("Web IDE", "devbox:open --web"),
        ("Forward", "devbox:forward"),
        ("Logs", "devbox:logs -f"),
        ("Status", "devbox:status"),
        ("Stop", "devbox:stop"),
    ]

    click.echo()
    for label, command in commands:
        click.echo(f"  {label:<8} hogli {command}{suffix}")

    if not mutagen.sync_list(label_selector=mutagen.workspace_label_selector(name)):
        click.echo()
        click.echo(f"  Tip: run `hogli devbox:sync{suffix}` to mirror your local checkout to this devbox.")


def _workspace_arg_suffix(name: str) -> str:
    """Return the optional CLI suffix for a named workspace."""
    label = extract_workspace_label(name)
    return f" {label}" if label else ""


_NOT_READY_REASONS = {
    "start_error": "A startup script failed, so some setup may be missing.",
    "start_timeout": "A startup script ran past its time limit, so some setup may be missing.",
    "wait_timeout": "Its startup scripts are still running.",
    "build_failed": "Its latest build failed.",
    "stopped": "It stopped before its startup scripts finished.",
    "agent_timeout": "Its agent did not connect to Coder.",
    "unavailable": "hogli could not read its status from Coder.",
}


def _wait_until_ready(name: str) -> None:
    """Hold the command until startup scripts finish, warning if they did not."""
    click.echo("Waiting for startup scripts...")
    state = wait_for_agent_ready(name)
    telemetry.add_command_properties(devbox_agent_lifecycle=state)
    if state == "ready":
        return
    click.echo(
        click.style(
            f"Devbox '{name}' may not be ready. {_NOT_READY_REASONS[state]} "
            f"Check `hogli devbox:logs{_workspace_arg_suffix(name)}`.",
            fg="yellow",
        )
    )


def _get_workspace_or_fail(name: str, workspaces: list[dict[str, Any]] | None = None) -> dict[str, Any]:
    """Return a workspace or exit with a consistent message when missing."""
    workspace = get_workspace(name, workspaces)
    if workspace is not None:
        return workspace
    _fail("No devbox found. Run 'hogli devbox:start' to create one.")
    raise SystemExit(1)  # unreachable; helps ty see the function doesn't fall through


def _workspace_status_color(status: str) -> str:
    """Return the display color for a workspace status."""
    return WORKSPACE_STATUS_COLORS.get(status, "white")


def _ljust_styled(text: str, width: int) -> str:
    """Left-justify a click-styled string to ``width`` *visible* columns.

    A plain ``f"{text:<width}"`` counts the invisible ANSI escape codes toward
    the width and under-pads colored cells; measure off the unstyled text so
    columns line up with their (unstyled) headers.
    """
    return text + " " * max(0, width - len(click.unstyle(text)))


def _render_sync_status(workspace_name: str) -> str:
    """Return a single-line summary of the mutagen sync state for a workspace.

    Reads the first session matching the workspace label. If multiple sessions
    happen to share the label (shouldn't happen via hogli, but possible via
    direct mutagen use), only the first is rendered -- intentionally simple.
    """
    sessions = mutagen.sync_list(label_selector=mutagen.workspace_label_selector(workspace_name))
    if not sessions:
        return click.style("○ not configured", fg="white")
    session = sessions[0]
    if session.get("paused"):
        return click.style("⚠ paused", fg="yellow")
    conflicts = mutagen.conflict_count(session)
    if conflicts:
        return click.style(f"⚠ {conflicts} conflict{'s' if conflicts != 1 else ''}", fg="red")
    status = str(session.get("status", "")).strip() or "running"
    # mutagen reports a stalled sync (box stopped, remote root gone) as a
    # `disconnected`/`halted-*` status; a green dot there would read as healthy.
    if status == "disconnected" or status.startswith("halted"):
        return click.style(f"✗ {status}", fg="red")
    return click.style(f"● {status}", fg="green")


def _pause_sync(name: str) -> bool:
    """Pause the devbox's running sync session while the box is stopped, and return whether it did.

    mutagen redials a lost box forever. Paused, it leaves the box and Coder
    alone until `devbox:start` resumes it. A failed pause only warns: stopping
    the box matters more, and the SSH shim already stops the sync from
    starting it again.
    """
    selector = mutagen.workspace_label_selector(name)
    if all(session.get("paused") for session in mutagen.sync_list(label_selector=selector)):
        return False
    try:
        mutagen.sync_pause(selector)
    except SystemExit:
        click.echo(click.style(f"Could not pause the sync to '{name}'. Stopping the box anyway.", fg="yellow"))
        return False
    click.echo(f"Paused the sync to '{name}'. `hogli devbox:start` resumes it.")
    return True


def _resume_sync(name: str) -> None:
    """Resume the devbox's sync session if `devbox:stop` paused it."""
    selector = mutagen.workspace_label_selector(name)
    if any(session.get("paused") for session in mutagen.sync_list(label_selector=selector)):
        mutagen.sync_resume(selector)
        click.echo(f"Resumed the sync to '{name}'.")


def _start_existing_workspace(
    name: str, workspace: dict[str, Any], *, start_app: bool | None = None, verbose: bool
) -> None:
    """Handle `devbox:start` when the workspace already exists."""
    if start_app is not None:
        _fail(
            f"--start-app and --no-start-app only apply when a devbox is created. {_CHANGE_PARAMETER_HINT}",
            cause="start_app_on_existing",
        )

    status = get_workspace_status(workspace)
    if status == "running":
        click.echo(f"Devbox '{name}' is already running.")
        _print_connection_info(name)
        return

    if status in PENDING_WORKSPACE_STATES:
        click.echo(f"Devbox '{name}' is in state: {status}")
        click.echo("Wait for the current operation to complete.")
        return

    if status == "stopped":
        if workspace.get("outdated"):
            click.echo(f"Starting devbox '{name}' on the latest template...")
            run_with_capacity_fallback(name, lambda: update_workspace(name, verbose=verbose))
        else:
            click.echo(f"Starting devbox '{name}'...")
            run_with_capacity_fallback(name, lambda: start_workspace(name, verbose=verbose))
        _wait_until_ready(name)
        click.echo("Started.")
        _resume_sync(name)
        _print_connection_info(name)
        return

    click.echo(f"Devbox '{name}' is in state: {status}")
    click.echo("Attempting to start...")
    run_with_capacity_fallback(name, lambda: start_workspace(name, verbose=verbose))
    _wait_until_ready(name)
    _resume_sync(name)
    _print_connection_info(name)


def _read_legacy_keychain_token() -> str | None:
    """Read the legacy macOS Keychain Claude token, if present.

    Used during migration only. Older hogli versions stashed the token under
    a generic-password entry; the new flow stores it as a Coder user secret,
    so this read happens once and the entry is then deleted.
    """
    if sys.platform != "darwin":
        return None
    result = subprocess.run(
        [
            "security",
            "find-generic-password",
            "-a",
            os.environ.get("USER", "posthog"),
            "-s",
            _LEGACY_KEYCHAIN_SERVICE,
            "-w",
        ],
        capture_output=True,
        text=True,
    )
    if result.returncode != 0:
        return None
    value = result.stdout.strip()
    return value or None


def _delete_legacy_keychain_token() -> bool:
    """Best-effort delete of the legacy macOS Keychain Claude token entry."""
    if sys.platform != "darwin":
        return False
    result = subprocess.run(
        [
            "security",
            "delete-generic-password",
            "-a",
            os.environ.get("USER", "posthog"),
            "-s",
            _LEGACY_KEYCHAIN_SERVICE,
        ],
        capture_output=True,
    )
    return result.returncode == 0


def _prompt_for_claude_token() -> str | None:
    """Prompt for a Claude OAuth token interactively.

    Returns the trimmed token, or ``None`` if the user accepts the empty default.
    """
    click.echo("Run `claude setup-token` in another terminal to generate a token.")
    click.pause("Press Enter when you have the token ready...")
    token = click.prompt(
        "Claude OAuth token (Enter to skip)",
        default="",
        hide_input=True,
        show_default=False,
    ).strip()
    return token or None


def maybe_configure_git_identity(configure_git_identity: bool | None) -> None:
    """Optionally persist Git identity defaults for new workspaces."""
    config = load_config()
    existing_git_name = config.get("git_name")
    existing_git_email = config.get("git_email")

    if configure_git_identity is False:
        if not (existing_git_name and existing_git_email):
            click.echo("Skipping Git identity setup.")
        return

    if configure_git_identity is None and existing_git_name and existing_git_email:
        return

    # Show prompts with best available defaults (saved > coder profile > empty)
    coder_git_name, coder_git_email = get_default_git_identity()
    default_git_name = existing_git_name or coder_git_name or ""
    default_git_email = existing_git_email or coder_git_email or ""

    click.echo()
    click.echo(click.style("Git identity", bold=True))
    click.echo("  Set the name and email used for Git commits inside your workspace.")
    click.echo("  These will be saved and reused for future workspaces.")
    click.echo()

    git_name = click.prompt(
        "Git name",
        default=default_git_name,
        show_default=bool(default_git_name),
    ).strip()
    git_email = click.prompt(
        "Git email",
        default=default_git_email,
        show_default=bool(default_git_email),
    ).strip()
    if not git_name or not git_email:
        _fail("Git name and Git email are both required when configuring workspace Git identity.")

    save_git_identity(git_name, git_email)
    click.echo(f"Saved Git identity for new workspaces: {git_name} <{git_email}>")


def _ssh_config_without_coder_block() -> str | None:
    """Return ``~/.ssh/config`` with coder's managed block cut out, or ``None`` when there is nothing to cut.

    The deployment hostname matches the ``Host coder.*`` block that
    ``coder config-ssh`` writes, so resolving ``IdentityAgent`` against it
    reads back whatever the previous run wrote. An engineer who started
    without one therefore never acquires one, however many times they
    re-run setup.
    """
    try:
        content = (Path.home() / ".ssh" / "config").read_text()
    except OSError:
        return None
    lines = content.splitlines(keepends=True)
    start = next((i for i, line in enumerate(lines) if "START-CODER" in line), None)
    end = next((i for i, line in enumerate(lines) if "END-CODER" in line), None)
    if start is None or end is None or end < start:
        return None
    return "".join(lines[:start] + lines[end + 1 :])


def _resolve_local_identity_agent_for_coder() -> str | None:
    """Return the IdentityAgent ssh would use to connect to Coder workspaces, or ``None``.

    Resolves against the deployment hostname so the engineer's existing
    ``Host *`` / ``Host *.posthog.dev`` / specific blocks all flow through,
    reading their config with coder's block removed so a value coder wrote
    on an earlier run cannot outrank the one they have set today.

    Falls back to the plain lookup, which sees coder's block, so a machine
    whose only ``IdentityAgent`` is the one coder wrote keeps it.
    """
    coder_host = urllib.parse.urlparse(get_coder_url()).hostname
    if not coder_host:
        return None
    stripped = _ssh_config_without_coder_block()
    if stripped is None:
        return _resolve_local_identity_agent(coder_host)
    with tempfile.NamedTemporaryFile("w", suffix="-ssh-config", delete=False) as probe:
        probe.write(stripped)
    try:
        own = _resolve_local_identity_agent(coder_host, config_path=probe.name)
    finally:
        os.unlink(probe.name)
    return own or _resolve_local_identity_agent(coder_host)


def _resolve_local_signing_key() -> str | None:
    """Return the engineer's ``git config user.signingkey``, normalized to a literal SSH public key string.

    Git accepts three formats: a literal ``ssh-... / ecdsa-... / sk-...``
    string, the same with a ``key::`` prefix (used by tools like Secretive),
    or a path to a key file. All are normalized here. Returns ``None``
    when the value is unset or the referenced file can't be read.
    """
    result = subprocess.run(
        ["git", "config", "--global", "--get", "user.signingkey"],
        capture_output=True,
        text=True,
    )
    if result.returncode != 0:
        return None
    value = result.stdout.strip()
    if not value:
        return None
    if value.startswith("key::"):
        value = value.removeprefix("key::")
    if value.startswith(("ssh-", "ecdsa-", "sk-")):
        return value
    key_path = Path(os.path.expanduser(value))
    # git also accepts a private key path. The returned value goes into a Coder secret, so
    # only public key content is returned, and a private key path falls back to its .pub file.
    for candidate in (key_path, key_path.with_name(f"{key_path.name}.pub")):
        try:
            content = candidate.read_text().strip()
        except OSError:
            continue
        if content.startswith(("ssh-", "ecdsa-", "sk-")):
            return content
    return None


def _read_identity_agent(host: str, *, config_path: str | None = None) -> str | None:
    """Return the raw ``identityagent`` value ``ssh -G <host>`` resolves, or ``None`` when ssh fails.

    The raw value carries three meanings the normalized form collapses:
    a socket path, ``none`` (use no agent at all), and the placeholder
    ``SSH_AUTH_SOCK`` (fall back to the env var).
    """
    args = ["ssh", "-G", host] if config_path is None else ["ssh", "-F", config_path, "-G", host]
    result = subprocess.run(args, capture_output=True, text=True)
    if result.returncode != 0:
        return None
    for line in result.stdout.splitlines():
        if line.startswith("identityagent "):
            return line[len("identityagent ") :].strip()
    return None


def _resolve_local_identity_agent(host: str, *, config_path: str | None = None) -> str | None:
    """Return the SSH agent socket ``ssh -G <host>`` would use to authenticate, or ``None`` when no specific agent is configured.

    Treats ``none`` (signaling "no agent") and the literal placeholder
    ``SSH_AUTH_SOCK`` (signaling "fall back to the env var") as "no specific
    agent" so callers can decide their own fallback.
    """
    value = _read_identity_agent(host, config_path=config_path)
    if value and value.lower() not in ("none", "ssh_auth_sock"):
        return value
    return None


@dataclass(frozen=True)
class SigningAgentStatus:
    """Whether the agent ssh forwards into devboxes can sign commits, and why not when it can't."""

    ok: bool
    detail: str


def _key_fingerprint(public_key: str) -> str | None:
    """Return the ``SHA256:...`` fingerprint of an SSH public key, or ``None`` when it will not parse."""
    result = subprocess.run(["ssh-keygen", "-lf", "-"], input=public_key, capture_output=True, text=True)
    if result.returncode != 0:
        return None
    fields = result.stdout.split()
    return next((field for field in fields if field.startswith("SHA256:")), None)


def _forwarded_agent_socket() -> str | None:
    """Return the agent socket ssh forwards to devboxes, or ``None`` when it forwards nothing.

    Mirrors what ``ssh`` itself does: ``IdentityAgent`` wins over the
    environment, ``none`` means no agent at all, and everything else falls
    back to ``$SSH_AUTH_SOCK``.
    """
    value = _read_identity_agent(_ssh_host_alias("probe"))
    if value and value.lower() != "ssh_auth_sock":
        return None if value.lower() == "none" else value
    return os.environ.get("SSH_AUTH_SOCK") or None


def _diagnose_signing_agent() -> SigningAgentStatus:
    """Report whether the agent reaching Coder hosts holds the commit-signing key.

    Devbox signing is ``ssh-keygen -Y sign`` against a forwarded agent.
    Forwarding a socket that holds nothing -- or forwarding none at all --
    is not an ssh error, so the only symptom is a commit that fails to sign
    inside the workspace, hours later and far from the cause.
    """
    public_key = _resolve_local_signing_key()
    if not public_key:
        return SigningAgentStatus(False, "`git config --global user.signingkey` is empty")

    fingerprint = _key_fingerprint(public_key)
    if not fingerprint:
        return SigningAgentStatus(False, "`git config --global user.signingkey` is not a readable public key")

    socket_path = _forwarded_agent_socket()
    if not socket_path:
        return SigningAgentStatus(
            False, "ssh forwards no agent to Coder hosts (IdentityAgent none, or $SSH_AUTH_SOCK unset)"
        )

    listed = subprocess.run(
        ["ssh-add", "-l"],
        env={**os.environ, "SSH_AUTH_SOCK": socket_path},
        capture_output=True,
        text=True,
    )
    if listed.returncode != 0:
        return SigningAgentStatus(False, f"no agent responding at {socket_path}")
    if fingerprint not in listed.stdout:
        return SigningAgentStatus(False, f"agent at {socket_path} does not hold {fingerprint}")
    return SigningAgentStatus(True, f"{fingerprint} via {socket_path}")


def maybe_configure_git_signing(
    configure_git_signing: bool | None, *, known_secret_names: set[str] | None = None
) -> None:
    """Propagate the engineer's existing local commit-signing config into devboxes.

    Reads ``git config user.signingkey`` (the public key the engineer already
    signs locally with) and ``ssh -G <coder-host>``'s ``identityagent`` (the
    SSH agent ssh would use for the connection, which is the agent that gets
    forwarded). Pushes the public key to a Coder user secret and pins the
    agent socket as the local IdentityAgent for Coder hosts. No menus, no
    probing -- whatever the engineer has set up locally per the handbook is
    what propagates.
    """
    already_set = (
        GIT_SIGNING_KEY_SECRET in known_secret_names
        if known_secret_names is not None
        else user_secret_exists(GIT_SIGNING_KEY_SECRET)
    )

    if configure_git_signing is False:
        if not already_set:
            click.echo("Skipping Git commit signing setup.")
        return

    if configure_git_signing is None and already_set:
        return

    # Pushing this public key would make the devbox ask the forwarded agent for a key it can't hold.
    if signs_with_secure_enclave_key():
        click.echo()
        click.echo(click.style("Git commit signing (Secure Enclave keys not supported yet)", bold=True))
        if already_set:
            lines = DEVBOX_SIGNING_NOTE
        else:
            lines = (
                "Devbox commits won't be signed, because the forwarded SSH agent can't hold a Secure Enclave key.",
            )
        for line in (*lines, DEVBOX_FEEDBACK_HINT):
            click.echo(f"  {line}")
        return

    public_key = _resolve_local_signing_key()
    if not public_key:
        click.echo()
        click.echo(click.style("Git commit signing (skipped)", bold=True))
        click.echo("  `git config --global user.signingkey` is empty.")
        click.echo(f"  Set up commit signing per the handbook: {_POSTHOG_COMMIT_SIGNING_HANDBOOK_URL}")
        click.echo("  Then re-run `hogli devbox:setup --configure-git-signing`.")
        return

    if public_key.startswith("ssh-rsa "):
        click.echo()
        click.echo(click.style("RSA signing keys are not allowed.", fg="red"))
        click.echo(f"  Use ECDSA or Ed25519 per the handbook: {_POSTHOG_COMMIT_SIGNING_HANDBOOK_URL}")
        return

    upsert_user_secret(GIT_SIGNING_KEY_SECRET, public_key, env_name=GIT_SIGNING_KEY_SECRET)

    click.echo()
    click.echo(click.style("Git commit signing", bold=True))
    click.echo(f"  Pushed signing key from `git config user.signingkey`: {public_key}")
    signing_agent = _diagnose_signing_agent()
    if signing_agent.ok:
        click.echo(f"  Agent forwarded to Coder hosts holds the key: {signing_agent.detail}")
    else:
        click.echo(click.style(f"  Commits will not sign inside devboxes: {signing_agent.detail}", fg="yellow"))
        click.echo(f"  Configure per: {_POSTHOG_COMMIT_SIGNING_HANDBOOK_URL}")
    click.echo()
    click.echo(click.style("If you haven't already:", bold=True))
    click.echo("  1. Open https://github.com/settings/ssh/new")
    click.echo("  2. Set 'Key type' to 'Signing Key' (auth keys do not sign).")
    click.echo("  3. Paste the key above.")
    click.echo()
    click.echo("Restart any running devbox (`hogli devbox:restart`) to pick up the new gitconfig.")


def _saved_region() -> str | None:
    """Return the saved region preference, or ``None`` when absent or invalid.

    A persisted value that's no longer in ``REGIONS`` (e.g. a stale entry
    from a hand-edited config) reads as unset instead of poisoning every
    downstream lookup.
    """
    saved = load_config().get("region")
    return saved if saved in REGIONS else None


def _preferred_region() -> str:
    """Return the saved preferred region, falling back to ``DEFAULT_REGION``.

    Centralized so every command path that needs the user's region
    preference reads the same value -- and so the fallback to the built-in
    default lives in one place.
    """
    return _saved_region() or DEFAULT_REGION


def maybe_configure_region(configure_region: bool | None) -> None:
    """Optionally persist the preferred region for new devboxes.

    The region is create-only on a workspace, so saving it locally just
    pre-fills ``devbox:start --region`` and determines the default
    workspace name (eu-central-1 boxes carry an ``-eu`` suffix). Existing
    workspaces are untouched.
    """
    config = load_config()
    existing_region = config.get("region")

    if configure_region is False:
        if not existing_region:
            click.echo("Skipping region preference setup.")
        return

    if configure_region is None and existing_region:
        return

    click.echo()
    click.echo(click.style("Preferred region", bold=True))
    click.echo("  Choose which region new devboxes should land in.")
    click.echo("  This is saved locally and used as the default for `hogli devbox:start`.")
    if existing_region:
        click.echo(f"  Current: {existing_region}")
    click.echo()

    default_region = existing_region or DEFAULT_REGION
    region = click.prompt(
        "Preferred region",
        default=default_region,
        type=click.Choice(REGIONS),
        show_choices=True,
        show_default=True,
    ).strip()

    save_region(region)
    click.echo(f"Saved preferred region: {region}")


def maybe_configure_dotfiles(configure_dotfiles: bool | None) -> None:
    """Optionally persist a dotfiles repo URL for new workspaces."""
    config = load_config()
    existing_uri = config.get("dotfiles_uri")

    if configure_dotfiles is False:
        if not existing_uri:
            click.echo("Skipping dotfiles setup.")
        return

    if configure_dotfiles is None and existing_uri:
        return

    click.echo()
    click.echo(click.style("Dotfiles (optional)", bold=True))
    click.echo("  Personalize your workspace with a dotfiles repository.")
    click.echo("  The repo will be cloned and applied on every workspace start.")
    click.echo("  This will be saved and reused for future workspaces.")
    if existing_uri:
        click.echo("  Press Enter to keep the current URL, or type a new one.")
        click.echo("  To remove dotfiles entirely, run `hogli devbox:config:rm dotfiles`.")
    click.echo()

    dotfiles_uri = click.prompt(
        "Dotfiles repo URL",
        default=existing_uri or "",
        show_default=bool(existing_uri),
    ).strip()

    if dotfiles_uri:
        save_dotfiles_uri(dotfiles_uri)
        click.echo(f"Saved dotfiles repo for new workspaces: {dotfiles_uri}")
    else:
        click.echo("No dotfiles repo configured.")


def _doctor_check(label: str, ok: bool) -> None:
    """Print one read-only doctor check line."""
    mark = click.style("ok", fg="green") if ok else click.style("missing", fg="red")
    click.echo(f"  [{mark}] {label}")


def _doctor_footer() -> None:
    """Point at the deterministic fix and the guided (agentic) one."""
    click.echo()
    click.echo("  Fix setup:    hogli devbox:setup")
    click.echo("  Guided setup: run the `setting-up-devbox` skill in your coding agent")


@click.command(name="devbox:doctor", help="Diagnose devbox prerequisites and setup (read-only).")
def devbox_doctor() -> None:
    """Read-only health check: tailnet access, Coder reachability, auth, saved setup.

    Safe for an agent to run as a probe -- it never prompts or mutates host
    config the way `devbox:setup` does. Run it first when a devbox command
    fails, and as step zero of the `setting-up-devbox` skill. The wrong tailnet
    is the prerequisite people most often miss, so the access prerequisite is
    surfaced explicitly whenever the control plane is unreachable.
    """
    click.echo(click.style("Devbox doctor", bold=True))
    click.echo(f"  Coder URL: {get_coder_url()}")
    click.echo()

    connected, tailnet = tailscale_state()
    _doctor_check("Tailscale connected", connected)

    # Being on a per-environment tailnet looks identical to "connected" but
    # routes nowhere near a devbox, and nothing prompts you about it after the
    # first sign-in — so name the active tailnet on its own line.
    _doctor_check(f"Tailnet: {tailnet or 'unknown'} (need {EXPECTED_TAILNET})", tailnet == EXPECTED_TAILNET)

    reachable = coder_reachable()
    _doctor_check("Coder control plane reachable", reachable)

    if not reachable:
        diagnosis = _diagnose_unreachable_coder()
        # doctor exits 0 while reporting a broken tailnet, so a failure count
        # off this property has to filter on command or exit_code.
        telemetry.add_command_properties(devbox_failure_cause=diagnosis.code)
        click.echo()
        click.echo(click.style(f"  Cause: {diagnosis.cause}", fg="yellow"))
        click.echo(f"  Next:  {diagnosis.next_step}")
        for fact in diagnosis.facts:
            click.echo(f"    - {fact}")
        click.echo()
        click.echo(click.style("  Prerequisite:", bold=True))
        click.echo(f"    {_TAILNET_ACCESS_PREREQ}")
        _doctor_footer()
        return

    installed = coder_installed()
    _doctor_check("coder CLI installed", installed)
    authenticated = installed and coder_authenticated()
    _doctor_check("Coder authenticated", authenticated)
    # The Host coder.* block is a wildcard, so any name probes whether
    # `coder config-ssh` has run -- the prerequisite for devbox:ssh/exec.
    _doctor_check("SSH access configured (devbox:ssh/exec)", coder_ssh_alias_configured("probe"))

    signing_agent = _diagnose_signing_agent()
    _doctor_check(f"Commit signing agent: {signing_agent.detail}", signing_agent.ok)

    if not authenticated:
        _doctor_footer()
        return

    # _print_setup_status emits its own "Currently configured:" header when
    # anything is set; only print a fallback line when it stays silent.
    if not _print_setup_status(_collect_setup_status()):
        click.echo()
        click.echo("Nothing configured yet.")
    _doctor_footer()


@click.command(name="devbox", help="Show available devbox commands")
def devbox_help() -> None:
    """Show the available `hogli devbox:*` commands."""
    manifest_obj = get_manifest()
    commands = sorted(
        (name, (manifest_obj.get_command_config(name) or {}).get("description", ""))
        for name in manifest_obj.get_all_commands()
        if name.startswith("devbox:") and not manifest_obj.is_command_hidden(name)
    )
    click.echo("Available devbox commands:")
    click.echo()
    for name, help_text in commands:
        click.echo(f"  hogli {name:<20} {help_text}")
    click.echo()
    click.echo("Run `hogli <command> --help` for command-specific options.")


def maybe_configure_claude_secret(configure_claude: bool | None, *, known_secret_names: set[str] | None = None) -> None:
    """Manage the ``CLAUDE_CODE_OAUTH_TOKEN`` Coder user secret for this user.

    Resolution order:

    1. Server unsupported (< 2.33) -- skip with a one-line note.
    2. Secret already exists and the user did not pass --configure-claude -- skip.
    3. Legacy macOS Keychain entry exists -- offer to migrate, then delete it.
    4. Otherwise -- prompt for a fresh token and create the secret.
    """
    if not server_supports_user_secrets():
        click.echo("Claude token: skipping (Coder server is older than 2.33; user secrets unavailable).")
        return

    if configure_claude is False:
        click.echo("Skipping Claude token setup.")
        return

    secret_exists = (
        CLAUDE_CODE_OAUTH_ENV in known_secret_names if known_secret_names is not None else has_claude_oauth_secret()
    )

    if secret_exists and configure_claude is not True:
        return

    legacy_token = _read_legacy_keychain_token()

    if legacy_token and not secret_exists and configure_claude is not True:
        click.echo()
        click.echo(click.style("Claude Code: migrating Keychain token to a Coder user secret", bold=True))
        click.echo("  hogli now stores the Claude OAuth token as a Coder user secret so that")
        click.echo("  workspaces pick it up automatically.")
        if click.confirm("Migrate the existing Keychain entry now?", default=True):
            upsert_user_secret(
                CLAUDE_CODE_OAUTH_ENV,
                legacy_token,
                env_name=CLAUDE_CODE_OAUTH_ENV,
                description="Claude Code OAuth token (managed by hogli)",
            )
            if _delete_legacy_keychain_token():
                click.echo("Migrated to Coder user secret. Removed the legacy Keychain entry.")
            else:
                click.echo("Migrated to Coder user secret. (Could not remove the legacy Keychain entry.)")
            return

    click.echo()
    click.echo(click.style("Claude Code (optional)", bold=True))
    click.echo("  Workspaces can use Claude Code if you provide an OAuth token.")
    click.echo("  The token will be stored as a Coder user secret and injected as")
    click.echo(f"  ${CLAUDE_CODE_OAUTH_ENV} into every workspace you start.")
    click.echo("  To generate one, run `claude setup-token` in another terminal.")
    click.echo()

    token = _prompt_for_claude_token()
    if not token:
        click.echo("No token provided. Skipping.")
        return

    upsert_user_secret(
        CLAUDE_CODE_OAUTH_ENV,
        token,
        env_name=CLAUDE_CODE_OAUTH_ENV,
        description="Claude Code OAuth token (managed by hogli)",
    )
    click.echo(f"Saved Claude token as Coder user secret '{CLAUDE_CODE_OAUTH_ENV}'.")


def _reset_user_secret(secret_name: str) -> bool:
    """Delete a Coder user secret. Returns True iff something was actually removed."""
    if delete_user_secret(secret_name).returncode == 0:
        click.echo(f"Deleted Coder user secret '{secret_name}'.")
        return True
    click.echo(f"Nothing to delete: '{secret_name}' was not set.")
    return False


def _reset_git_identity() -> bool:
    """Drop the saved Git name/email. Returns True iff something was cleared."""
    config = load_config()
    if not (config.get("git_name") or config.get("git_email")):
        click.echo("Nothing to clear: Git identity was not set.")
        return False
    clear_git_identity(config)
    click.echo("Cleared saved Git identity. New workspaces will prompt for one.")
    return True


def _reset_region() -> bool:
    """Drop the saved region preference. Returns True iff something was cleared."""
    config = load_config()
    if not config.get("region"):
        click.echo("Nothing to clear: region preference was not set.")
        return False
    clear_region(config)
    click.echo("Cleared saved region preference. New workspaces will use the built-in default.")
    return True


def _reset_dotfiles() -> bool:
    """Drop the saved dotfiles URI. Returns True iff something was cleared."""
    config = load_config()
    if not config.get("dotfiles_uri"):
        click.echo("Nothing to clear: dotfiles was not set.")
        return False
    clear_dotfiles_uri(config)
    click.echo(f"Cleared saved dotfiles repo. New devboxes won't clone it. {_CHANGE_PARAMETER_HINT}")
    return True


def _reset_worktree_box_cleanup() -> bool:
    config = load_config()
    if not config.get("worktree_box_cleanup"):
        click.echo("Nothing to clear: worktree box cleanup was not set.")
        return False
    clear_worktree_box_cleanup(config)
    click.echo("Cleared worktree box cleanup. `hogli worktrees:clean` now leaves devboxes alone by default.")
    return True


def _reset_worktree_auto_sources() -> bool:
    config = load_config()
    if not config.get("worktree_auto_box"):
        click.echo("Nothing to clear: automatic worktree boxes were off.")
        return False
    clear_worktree_auto_sources(config)
    click.echo("Turned off automatic worktree boxes. New worktrees no longer get a devbox.")
    return True


def _reset_worktree_provider() -> bool:
    config = load_config()
    if not config.get("worktree_provider"):
        click.echo("Nothing to clear: worktree boxes already run on coder.")
        return False
    clear_worktree_provider(config)
    click.echo("Worktree boxes run on coder again.")
    return True


def _git_identity_status(config: DevboxConfig, _: set[str]) -> str | None:
    name = config.get("git_name")
    email = config.get("git_email")
    return f"{name} <{email}>" if name and email else None


def _field_status(field: str) -> Callable[[DevboxConfig, set[str]], str | None]:
    """Status reader that returns a single config field's value (or ``None``)."""
    return lambda config, _: config.get(field)


def _secret_status(secret_name: str) -> Callable[[DevboxConfig, set[str]], str | None]:
    return lambda _config, secret_names: "configured" if secret_name in secret_names else None


@dataclass(frozen=True)
class _ConfigItem:
    """One row in the devbox setup status / reset table.

    Each item carries everything the status, show, and rm paths need:
    the CLI key (``devbox:config:rm <key>``), the human label
    (``devbox:config:show`` and the setup wizard's "Currently configured:"
    block), how to derive the current value from local config plus the
    set of Coder secret names, how to clear it, and whether clearing
    touches Coder user secrets (so the server-version check fires only
    when needed). New configurables land as one entry below.
    """

    cli_key: str
    label: str
    needs_secrets: bool
    status: Callable[[DevboxConfig, set[str]], str | None]
    reset: Callable[[], bool]


_CONFIG_ITEMS: tuple[_ConfigItem, ...] = (
    _ConfigItem(
        cli_key="git-identity",
        label="Git identity",
        needs_secrets=False,
        status=_git_identity_status,
        reset=_reset_git_identity,
    ),
    _ConfigItem(
        cli_key="git-signing",
        label="Git signing",
        needs_secrets=True,
        status=_secret_status(GIT_SIGNING_KEY_SECRET),
        reset=lambda: _reset_user_secret(GIT_SIGNING_KEY_SECRET),
    ),
    _ConfigItem(
        cli_key="region",
        label="Region",
        needs_secrets=False,
        status=_field_status("region"),
        reset=_reset_region,
    ),
    _ConfigItem(
        cli_key="dotfiles",
        label="Dotfiles",
        needs_secrets=False,
        status=_field_status("dotfiles_uri"),
        reset=_reset_dotfiles,
    ),
    _ConfigItem(
        cli_key="claude",
        label="Claude token",
        needs_secrets=True,
        status=_secret_status(CLAUDE_CODE_OAUTH_ENV),
        reset=lambda: _reset_user_secret(CLAUDE_CODE_OAUTH_ENV),
    ),
    _ConfigItem(
        cli_key="worktree-boxes",
        label="Worktree box cleanup",
        needs_secrets=False,
        status=_field_status("worktree_box_cleanup"),
        reset=_reset_worktree_box_cleanup,
    ),
    _ConfigItem(
        cli_key="worktree-auto",
        label="Automatic worktree boxes",
        needs_secrets=False,
        status=_field_status("worktree_auto_box"),
        reset=_reset_worktree_auto_sources,
    ),
    _ConfigItem(
        cli_key="worktree-provider",
        label="Worktree box provider",
        needs_secrets=False,
        status=_field_status("worktree_provider"),
        reset=_reset_worktree_provider,
    ),
)


def _config_items_by_key() -> dict[str, _ConfigItem]:
    return {item.cli_key: item for item in _CONFIG_ITEMS}


def _fetch_secret_names() -> set[str]:
    """Bulk-fetch user-secret names in a single ``coder secret list`` round trip.

    ``None`` (older servers without user-secret support) maps to an empty set,
    matching the "no secrets" path. The result is safe to share across status
    rows and configure helpers within one CLI invocation.
    """
    secrets = list_user_secrets() or []
    return {name for s in secrets if isinstance(s, dict) and (name := s.get("name"))}


def _collect_setup_status(secret_names: set[str] | None = None) -> list[tuple[str, str | None]]:
    """Return one ``(label, value)`` tuple per configurable item.

    Pass ``secret_names`` to reuse a pre-fetched set when the caller already
    has one (the setup wizard does); otherwise we make our own ``coder secret
    list`` call so single-shot uses like ``devbox:config:show`` stay self-contained.
    """
    config = load_config()
    secrets = _fetch_secret_names() if secret_names is None else secret_names
    return [(item.label, item.status(config, secrets)) for item in _CONFIG_ITEMS]


def _print_setup_status(status: list[tuple[str, str | None]]) -> bool:
    """Render the compact status block. Returns True iff anything was printed.

    Stays silent when nothing is set yet so the wizard's first-run output
    isn't padded with "not set" lines; ``devbox:config:show`` uses the
    return value to choose between the block and a "Nothing configured yet"
    hint instead.
    """
    if not any(value for _, value in status):
        return False
    width = max(len(label) for label, _ in status) + 1
    click.echo()
    click.echo("Currently configured:")
    for label, value in status:
        rendered = value if value else click.style("not set", fg="yellow")
        click.echo(f"  {label:<{width}} {rendered}")
    return True


def _explicit_option_flag_passed(configure_flags: list[bool | None]) -> bool:
    """Return whether the user passed any explicit --configure-* / --skip-configure-* flag."""
    return any(flag is not None for flag in configure_flags)


def _confirm_run_setup() -> bool:
    """Show a Y/n gate explaining what setup will do. ``True`` means proceed.

    Skipped for non-interactive stdin so CI / piped invocations never block.
    """
    if not sys.stdin.isatty():
        return True
    click.echo()
    click.echo("hogli devbox:setup will check or configure:")
    click.echo("  - Tailscale + Coder reachability")
    click.echo("  - Local SSH config for Coder hosts")
    click.echo("  - File sync tooling (mutagen) for devbox:sync")
    click.echo("  - Git identity (name/email) for new workspaces")
    click.echo("  - Git commit signing key propagation")
    click.echo("  - Preferred region for new workspaces (optional)")
    click.echo("  - Dotfiles repo for new workspaces (optional)")
    click.echo("  - Claude OAuth token as a Coder user secret (optional)")
    click.echo()
    return click.confirm("Proceed?", default=True)


@click.command(name="devbox:setup", help="Install and configure local access to Coder devboxes")
@click.option(
    "--configure-ssh/--skip-configure-ssh",
    default=None,
    help="Configure local SSH host entries for Coder workspaces during setup",
)
@click.option(
    "--configure-git-identity/--skip-configure-git-identity",
    default=None,
    help="Prompt for Git name/email defaults for new Coder workspaces",
)
@click.option(
    "--configure-git-signing/--skip-configure-git-signing",
    default=None,
    help="Propagate your local git signing key into Coder devboxes (reads git config user.signingkey)",
)
@click.option(
    "--configure-region/--skip-configure-region",
    default=None,
    help="Prompt for the preferred region (us-east-1 or eu-central-1) for new devboxes",
)
@click.option(
    "--configure-dotfiles/--skip-configure-dotfiles",
    default=None,
    help="Prompt for a dotfiles repo URL for new Coder workspaces",
)
@click.option(
    "--configure-claude/--skip-configure-claude",
    "configure_claude_setup",
    default=None,
    help="Manage the CLAUDE_CODE_OAUTH_TOKEN Coder user secret for this user",
)
@click.option("-v", "--verbose", is_flag=True, help="Show full Coder/Terraform build output")
def devbox_setup(
    configure_ssh: bool | None,
    configure_git_identity: bool | None,
    configure_git_signing: bool | None,
    configure_region: bool | None,
    configure_dotfiles: bool | None,
    configure_claude_setup: bool | None,
    verbose: bool,
) -> None:
    """Prepare this machine for Coder workspaces."""
    explicit = _explicit_option_flag_passed(
        [
            configure_ssh,
            configure_git_identity,
            configure_git_signing,
            configure_region,
            configure_dotfiles,
            configure_claude_setup,
        ],
    )

    click.echo(click.style("Configuring devbox CLI access...", bold=True))
    ensure_coder_reachable("rerun `hogli devbox:setup`.")
    ensure_coder_installed(verbose=verbose)
    ensure_coder_on_path()
    ensure_coder_authenticated()

    # One `coder secret list` round trip fuels the status block and both
    # secret-aware configure helpers. None of the upcoming steps mutate a
    # secret the *other* steps' checks care about, so the snapshot stays
    # valid for the duration of this invocation.
    secret_names = _fetch_secret_names()

    status = _collect_setup_status(secret_names)
    _print_setup_status(status)

    if not explicit and not _confirm_run_setup():
        click.echo("Aborted. Re-run `hogli devbox:setup` when ready.")
        return

    mutagen.ensure_mutagen_installed(verbose=verbose)
    mutagen.ensure_daemon_with_shim()
    click.echo(
        "  Note: the mutagen daemon is left unregistered from login auto-start so devbox "
        "sync can apply its ssh keepalive fix; it starts on demand the next time you sync."
    )
    mutagen.ensure_user_mutagen_config()
    maybe_configure_ssh(
        configure_ssh=configure_ssh,
        identity_agent_socket=_resolve_local_identity_agent_for_coder(),
        verbose=verbose,
    )
    maybe_configure_git_identity(configure_git_identity)
    maybe_configure_git_signing(configure_git_signing, known_secret_names=secret_names)
    maybe_configure_region(configure_region)
    maybe_configure_dotfiles(configure_dotfiles)
    maybe_configure_claude_secret(configure_claude_setup, known_secret_names=secret_names)
    print_setup_summary()


@click.command(name="devbox:list", help="List your devboxes")
def devbox_list() -> None:
    """List all workspaces belonging to the current user, plus shared workspaces."""
    ensure_runtime_ready()
    workspaces = list_user_workspaces()

    if not workspaces:
        click.echo("No devboxes found. Run 'hogli devbox:start' to create one.")
    else:
        click.echo(f"{'LABEL':<16} {'STATUS':<12} {'REGION':<14} {'SYNC':<18} {'NAME'}")
        for ws in workspaces:
            ws_name = ws.get("name", "")
            label = extract_workspace_label(ws_name) or "(default)"
            status = get_workspace_status(ws)
            region = get_workspace_region(ws) or "unknown"
            styled_status = click.style(status, fg=_workspace_status_color(status))
            sync_state = _render_sync_status(ws_name)
            click.echo(
                f"  {label:<14} {_ljust_styled(styled_status, 12)} "
                f"{region:<14} {_ljust_styled(sync_state, 18)} {ws_name}"
            )

    shared = list_shared_workspaces()
    if shared:
        click.echo()
        click.echo("Shared with you:")
        for ws in shared:
            ws_name = ws.get("name", "")
            status = get_workspace_status(ws)
            owner = ws.get("owner_name", "unknown")
            click.echo(f"  {ws_name:<30} {click.style(status, fg=_workspace_status_color(status)):<20} (from {owner})")

    shared_out: list[tuple[str, list[str]]] = []
    for ws in workspaces:
        ws_name = ws.get("name", "")
        users = get_shared_users(ws_name)
        if users:
            shared_out.append((ws_name, users))
    if shared_out:
        click.echo()
        click.echo("Shared with others:")
        for ws_name, users in shared_out:
            label = extract_workspace_label(ws_name) or "(default)"
            click.echo(f"  {label:<16} {', '.join(users)}")


@click.command(name="devbox:users", help="List Coder users (for devbox sharing)")
def devbox_users() -> None:
    """List all active Coder users so you know who to share with."""
    ensure_runtime_ready()

    current_user = get_coder_user_info()
    current_username = current_user.get("username", "")

    users = list_coder_users()
    if not users:
        _fail("Could not fetch users. Check your Coder authentication.")

    users.sort(key=lambda u: u.get("username", ""))

    click.echo(f"  {'USERNAME':<16} {'NAME':<30} {'EMAIL'}")
    for user in users:
        username = user.get("username", "")
        name = user.get("name", "")
        email = user.get("email", "")
        is_you = username == current_username
        name_col = f"{'(you)' if is_you else name:<30}"
        if is_you:
            name_col = click.style(name_col, fg="green")
        click.echo(f"  {username:<16} {name_col} {email}")


def _hint_if_positional_looks_like_username(
    command: str, workspace: str | None, users: tuple[str, ...], list_sharing: bool = False
) -> None:
    """Warn when the positional arg is almost certainly meant as a target username.

    The positional slot on every `devbox:*` command selects a workspace label,
    not a user. Share/unshare take `--user` for the target, so this case is a
    common footgun.
    """
    if workspace and not users and not list_sharing:
        raise click.UsageError(
            f"Pass the target user with --user (e.g. `hogli {command} --user {workspace}`).\n"
            "The positional argument selects one of YOUR workspaces. Run 'hogli devbox:users' to find usernames."
        )


@click.command(name="devbox:share", help="Share your devbox with other users")
@workspace_argument
@click.option("--user", "users", multiple=True, help="Coder username(s) to share with")
@click.option("--role", type=click.Choice(["use", "admin"]), default="use", help="Access role to grant")
@click.option("--list", "list_sharing", is_flag=True, help="Show who has access")
def devbox_share(
    workspace: str | None,
    users: tuple[str, ...],
    role: str,
    list_sharing: bool,
) -> None:
    """Share your devbox with other Coder users."""
    ensure_runtime_ready()
    _hint_if_positional_looks_like_username("devbox:share", workspace, users, list_sharing)

    name, workspaces = resolve_workspace_name(workspace)
    _get_workspace_or_fail(name, workspaces)

    if list_sharing:
        result = get_sharing_status(name)
        if result.returncode != 0:
            raise SystemExit(result.returncode)
        click.echo(result.stdout)
        return

    if not users:
        raise click.UsageError("Specify at least one --user. Run 'hogli devbox:users' to find usernames.")

    share_workspace(name, list(users), role)
    click.echo(f"Shared '{name}' with {', '.join(users)} (role: {role}).")


@click.command(name="devbox:unshare", help="Revoke access to your devbox from other users")
@workspace_argument
@click.option("--user", "users", multiple=True, help="Coder username(s) to revoke access from")
def devbox_unshare(workspace: str | None, users: tuple[str, ...]) -> None:
    """Revoke access to your devbox from one or more Coder users."""
    ensure_runtime_ready()
    _hint_if_positional_looks_like_username("devbox:unshare", workspace, users)

    name, workspaces = resolve_workspace_name(workspace)
    _get_workspace_or_fail(name, workspaces)

    if not users:
        raise click.UsageError("Specify at least one --user. Run 'hogli devbox:share --list' to see current access.")

    user_list = list(users)
    unshare_workspace(name, user_list)
    click.echo(f"Revoked access for: {', '.join(user_list)}")
    click.echo(click.style("Restart your devbox for this to take effect.", fg="yellow"))


def _maybe_hint_region_mismatch(name: str) -> None:
    """On resuming a default box outside the saved region pref, say how to get one there.

    Quiet for labeled boxes -- the pref only governs the default box. Callers
    gate on a bare invocation (a label or ``--region`` is already a deliberate
    choice).
    """
    saved = _saved_region()
    if saved is None or extract_workspace_label(name) is not None:
        return
    box_region = region_from_workspace_name(name)
    if box_region != saved:
        click.echo(
            f"Your devbox '{name}' is in {box_region}, but your saved region is {saved}. "
            f"Create a {saved} devbox with `hogli devbox:start --region {saved}`."
        )


@click.command(name="devbox:start", help="Start or create your remote devbox")
@workspace_argument
@click.option(
    "--disk",
    type=int,
    help="Disk size in GiB (default: set by the template)",
)
@click.option(
    "-t",
    "--template",
    default=DEFAULT_TEMPLATE,
    show_default=True,
    help="Coder workspace template to use when creating a new devbox",
)
@click.option(
    "-p",
    "--preset",
    default=DEFAULT_PRESET,
    show_default=True,
    help="Coder template preset to apply (use 'none' to opt out)",
)
@click.option(
    "--region",
    type=click.Choice(REGIONS),
    default=None,
    help=(
        "Region whose default devbox to start, creating it if needed (a devbox's region is "
        "set at creation and cannot change). Defaults to the value saved by "
        "`devbox:setup --configure-region`, then us-east-1."
    ),
)
@click.option(
    "--start-app/--no-start-app",
    "start_app",
    default=None,
    help=("Bring the PostHog app up in the background on every workspace start. Applies when the devbox is created."),
)
@click.option("-v", "--verbose", is_flag=True, help="Show full Coder/Terraform build output")
def devbox_start(
    workspace: str | None,
    disk: int | None,
    template: str,
    preset: str,
    region: str | None,
    start_app: bool | None,
    verbose: bool,
) -> None:
    """Start or create the remote devbox."""
    ensure_runtime_ready()
    effective_region = region or _preferred_region()
    if workspace is None and region is not None:
        # An explicit --region targets that region's default directly, so it
        # can be created (or resumed) regardless of boxes in other regions.
        name = get_workspace_name(region=effective_region)
        workspaces: list[dict[str, Any]] | None = list_user_workspaces()
    else:
        # Resolution prefers the effective region's default but falls back to
        # the box the user already has -- a saved pref alone never abandons it.
        name, workspaces = resolve_workspace_name(workspace, region=effective_region)
    ws = get_workspace(name, workspaces)

    if ws is not None:
        if workspace is None and region is None:
            _maybe_hint_region_mismatch(name)
        _start_existing_workspace(name, ws, start_app=start_app, verbose=verbose)
        return

    config = load_config()

    click.echo(f"Creating devbox '{name}' (template={template}, preset={preset}, region={effective_region})...")
    run_with_capacity_fallback(
        name,
        lambda: create_workspace(
            name,
            disk,
            git_name=config.get("git_name"),
            git_email=config.get("git_email"),
            dotfiles_uri=config.get("dotfiles_uri"),
            region=effective_region,
            template=template,
            preset=preset,
            start_app=start_app,
            verbose=verbose,
        ),
    )
    _wait_until_ready(name)
    click.echo("Created.")
    _print_connection_info(name)


@click.command(
    name="devbox:clone",
    help="Clone a running devbox into a new one, carrying its full disk state",
)
@workspace_argument
@click.option(
    "--as",
    "new_label",
    default="clone",
    show_default=True,
    help="Label for the new devbox (becomes devbox-<you>-<label>)",
)
@click.option("-y", "--yes", is_flag=True, help="Skip the confirmation prompt")
@click.option("-v", "--verbose", is_flag=True, help="Show full Coder/Terraform build output")
def devbox_clone(workspace: str | None, new_label: str, yes: bool, verbose: bool) -> None:
    """Duplicate a running devbox, disk and all.

    Captures the source box's root volume into a private, short-lived AMI and
    boots a new devbox from it, so the clone comes up with the source's full
    disk state -- uncommitted work, local databases, installed tooling -- not
    just the settings that dotfiles and user secrets already carry. The source
    must be running; quiesce its dev stack first for an application-consistent
    copy. The capture image is private to you and auto-expires.
    """
    ensure_runtime_ready()
    source_name, workspaces = resolve_workspace_name(workspace)
    ws = _get_workspace_or_fail(source_name, workspaces)

    owner = get_username()
    if str(ws.get("owner_name") or "").lower() not in ("", owner):
        _fail("You can only clone your own devbox.")

    template = ws.get("template_name") or DEFAULT_TEMPLATE
    if template != DEFAULT_TEMPLATE:
        _fail(f"Clone supports the '{DEFAULT_TEMPLATE}' template only (this devbox uses '{template}').")

    # The clone lands in the source's region -- a per-clone AMI is region-scoped,
    # so the template images and boots within that same region.
    region = region_from_workspace_name(source_name)

    status = get_workspace_status(ws)
    if status != "running":
        suffix = _workspace_arg_suffix(source_name)
        _fail(
            f"The source devbox must be running to clone it (status: {status}). Start it: `hogli devbox:start{suffix}`."
        )

    target_name = get_workspace_name(new_label, region=region)
    if get_workspace(target_name, workspaces) is not None:
        _fail(f"A devbox named '{target_name}' already exists. Pass `--as <label>` to pick another name.")

    if not yes:
        click.echo(f"Clone '{source_name}' -> '{target_name}'.")
        click.echo(
            "This images the source box's entire disk (including any on-disk secrets) into a\n"
            "private AMI and boots the new box from it. The image auto-expires after a few days."
        )
        if not click.confirm("Proceed?"):
            click.echo("Cancelled.")
            return

    disk_size = get_workspace_disk_size(ws)
    if disk_size is None:
        _fail("Could not determine the source devbox's disk size. Rebuild it on the latest template and retry.")

    source_instance_id = get_source_instance_id(source_name)
    click.echo(
        f"Cloning '{source_name}' ({source_instance_id}) -> '{target_name}'. "
        "The template captures its disk into a private image (a few minutes) and boots the clone from it."
    )
    clone_workspace(
        target_name,
        source_instance_id=source_instance_id,
        disk_size=disk_size,
        region=region,
        template=template,
        verbose=verbose,
    )
    _wait_until_ready(target_name)
    click.echo("Cloned.")
    _print_connection_info(target_name)


@click.command(name="devbox:stop", help="Stop your devbox (preserves disk, stops billing)")
@workspace_argument
@click.option("-v", "--verbose", is_flag=True, help="Show full Coder/Terraform build output")
def devbox_stop(workspace: str | None, verbose: bool) -> None:
    """Stop the devbox. State is preserved on the EBS volume."""
    ensure_runtime_ready()
    name, workspaces = resolve_workspace_name(workspace)
    ws = _get_workspace_or_fail(name, workspaces)

    # Also for a box that Coder stopped on its schedule, whose sync still redials it.
    paused = _pause_sync(name)

    status = get_workspace_status(ws)
    if status == "stopped":
        click.echo(f"Devbox '{name}' is already stopped.")
        return

    click.echo(f"Stopping '{name}'...")
    try:
        stop_workspace(name, verbose=verbose)
    except (Exception, SystemExit):
        if paused:
            mutagen.sync_resume(mutagen.workspace_label_selector(name))
            click.echo(f"The box still runs, so the sync to '{name}' is resumed.")
        raise
    start_command = f"hogli devbox:start {workspace}" if workspace else "hogli devbox:start"
    click.echo("Stopped. Billing for the box stops now.")
    click.echo(f"The disk and your files stay until you destroy the box. Run '{start_command}' to resume it.")


@click.command(name="devbox:restart", help="Restart your devbox")
@workspace_argument
@click.option("-v", "--verbose", is_flag=True, help="Show full Coder/Terraform build output")
def devbox_restart(workspace: str | None, verbose: bool) -> None:
    """Stop and start the devbox in one step."""
    ensure_runtime_ready()
    name, workspaces = resolve_workspace_name(workspace)
    _get_workspace_or_fail(name, workspaces)
    click.echo(f"Restarting '{name}'...")
    run_with_capacity_fallback(name, lambda: restart_workspace(name, verbose=verbose))
    _wait_until_ready(name)
    click.echo("Restarted.")
    _print_connection_info(name)


@click.command(name="devbox:update", help="Update devbox to the latest template")
@workspace_argument
@click.option("-v", "--verbose", is_flag=True, help="Show full Coder/Terraform build output")
def devbox_update(workspace: str | None, verbose: bool) -> None:
    """Apply the latest template to the devbox."""
    ensure_runtime_ready()
    name, workspaces = resolve_workspace_name(workspace)
    ws = _get_workspace_or_fail(name, workspaces)
    if not ws.get("outdated"):
        click.echo(f"Devbox '{name}' is already up to date.")
        return
    click.echo(f"Updating '{name}' to the latest template...")
    run_with_capacity_fallback(name, lambda: update_workspace(name, verbose=verbose))
    _wait_until_ready(name)
    click.echo("Updated.")
    click.echo(
        "Note: if your local lockfiles differ from the new AMI's baked versions, "
        "expect a one-time dep re-install on next workspace start (2-5 min)."
    )
    _print_connection_info(name)


@click.command(name="devbox:ssh", help="SSH into your devbox")
@workspace_argument
def devbox_ssh(workspace: str | None) -> None:
    """Open an SSH session to the devbox."""
    ensure_runtime_ready()
    name, _ = resolve_workspace_name(workspace)
    ssh_replace(name)


@click.command(
    name="devbox:exec",
    help="Run a command inside your devbox (non-interactive).",
    context_settings={"ignore_unknown_options": True},
)
@click.option("--name", "-n", "workspace_name", default=None, help="Workspace label or @user[/label] target")
@click.argument("command", nargs=-1, type=click.UNPROCESSED, required=True)
def devbox_remote_exec(workspace_name: str | None, command: tuple[str, ...]) -> None:
    """Run COMMAND in the devbox over `coder ssh` and propagate its exit code.

    Unlike `devbox:ssh`, this runs a single command instead of opening an
    interactive shell, so agents and scripts can drive a devbox remotely:

        hogli devbox:exec -- gh auth status
        hogli devbox:exec -n api -- bash -lc 'cd ~/posthog && git status'

    Use `--` to separate hogli's flags from the command's own flags.
    """
    ensure_runtime_ready()
    name, _ = resolve_workspace_name(workspace_name)
    if not coder_ssh_alias_configured(name):
        _fail(
            "SSH access for devboxes isn't configured. Run `hogli devbox:setup` (it runs `coder config-ssh`), then retry."
        )
    exec_replace(name, list(command))


def _sync_warning(name: str, editor: str) -> str:
    worktree = next((path for path, record in load_worktree_boxes().items() if record.workspace == name), None)
    if worktree is None:
        return f"⚠ Sync is active for '{name}'. Editing in {editor} can conflict with the local source of truth."
    return (
        f"⚠ '{name}' mirrors the worktree at {worktree}. Edit files in that worktree, "
        f"and use {editor} to run the stack and tests. Files edited on the devbox conflict with the mirror."
    )


def _open_in_herdr(name: str, workspaces: list[dict[str, Any]] | None) -> None:
    ws = _get_workspace_or_fail(name, workspaces)
    status = get_workspace_status(ws)
    if status != "running":
        _fail(
            f"Devbox '{name}' is {status}. Start it with `hogli devbox:start{_workspace_arg_suffix(name)}`, then retry.",
            cause="herdr_workspace_not_running",
        )
    if not coder_ssh_alias_configured(name):
        _fail(
            "SSH access for devboxes isn't configured. Run `hogli devbox:setup` (it runs `coder config-ssh`), then retry.",
            cause="herdr_ssh_not_configured",
        )
    herdr_app.open_in_herdr(name, folder=REMOTE_REPO_PATH)


@click.command(name="devbox:open", help="Open devbox in browser, VS Code, Cursor, or Herdr")
@workspace_argument
@click.option("--vscode", is_flag=True, help="Open in VS Code Desktop via SSH")
@click.option("--cursor", is_flag=True, help="Open in Cursor via SSH")
@click.option("--web", is_flag=True, help="Open code-server (VS Code in browser)")
@click.option("--herdr", is_flag=True, help="Add the devbox to Herdr as a machine and open a space on it")
def devbox_open(workspace: str | None, vscode: bool, cursor: bool, web: bool, herdr: bool) -> None:
    """Open the devbox in a browser or editor."""
    chosen = sum([vscode, cursor, web, herdr])
    if chosen > 1:
        raise click.UsageError("Choose one of `--vscode`, `--cursor`, `--web`, or `--herdr`.")

    ensure_runtime_ready()
    name, workspaces = resolve_workspace_name(workspace)

    if (vscode or cursor or herdr) and mutagen.sync_list(label_selector=mutagen.workspace_label_selector(name)):
        editor = "VS Code Remote" if vscode else "Cursor Remote" if cursor else "Herdr terminals on the devbox"
        click.echo(click.style(_sync_warning(name, editor), fg="yellow"))

    target = "vscode" if vscode else "cursor" if cursor else "web" if web else "herdr" if herdr else "browser"
    telemetry.add_command_properties(devbox_open_target=target)
    if herdr:
        _open_in_herdr(name, workspaces)
    elif vscode:
        click.echo(f"Opening '{name}' in VS Code...")
        open_vscode(name)
    elif cursor:
        click.echo(f"Opening '{name}' in Cursor...")
        open_cursor(name)
    elif web:
        click.echo(f"Opening code-server for '{name}'...")
        open_web_ide(name)
    else:
        click.echo(f"Opening '{name}' in browser...")
        open_in_browser(name)


@click.command(name="devbox:logs", help="Tail devbox build and agent logs")
@workspace_argument
@click.option("-f", "--follow", is_flag=True, help="Follow log output")
def devbox_logs(workspace: str | None, follow: bool) -> None:
    """Tail workspace build and agent logs."""
    ensure_runtime_ready()
    name, _ = resolve_workspace_name(workspace)
    logs_replace(name, follow)


def _ensure_user_secrets_supported() -> None:
    """Fail fast when the Coder server does not support user secrets."""
    if server_supports_user_secrets():
        return
    _fail("Coder server does not support user secrets (requires >= 2.33). Update the deployment first.")


@click.command(name="devbox:secret:list", help="List your Coder user secrets")
def devbox_secret_list() -> None:
    """List the user secrets attached to your Coder account."""
    ensure_runtime_ready()
    _ensure_user_secrets_supported()

    secrets = list_user_secrets()
    if secrets is None:
        _fail("Could not list user secrets. Check `coder secret list` directly for details.")
    if not secrets:
        click.echo("No user secrets configured. Run `hogli devbox:secret:set NAME` to add one.")
        return

    click.echo(f"  {'NAME':<32} {'ENV':<32} DESCRIPTION")
    for secret in secrets:
        name = str(secret.get("name", ""))
        env = str(secret.get("env_name") or secret.get("env") or "")
        description = str(secret.get("description", ""))
        click.echo(f"  {name:<32} {env:<32} {description}")


@click.command(name="devbox:secret:set", help="Create or replace a Coder user secret")
@click.argument("name")
@click.option(
    "--file",
    "file_path",
    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=Path),
    default=None,
    help="Read the secret value from this file instead of prompting for it",
)
@click.option(
    "--env",
    "env_name",
    default=None,
    help="Environment variable name to inject in the workspace (defaults to NAME)",
)
@click.option("--description", default=None, help="Optional description")
def devbox_secret_set(name: str, file_path: Path | None, env_name: str | None, description: str | None) -> None:
    """Set a Coder user secret. Replaces any existing secret with the same name."""
    ensure_runtime_ready()
    _ensure_user_secrets_supported()

    target_env = env_name or name

    if file_path is not None:
        value = file_path.read_text().rstrip("\n")
    else:
        value = click.prompt(f"Value for {name}", hide_input=True, confirmation_prompt=True)
    if not value:
        _fail("Empty value rejected. Pass --file PATH or enter a non-empty value.")

    upsert_user_secret(name, value, env_name=target_env, description=description)
    click.echo(f"Set user secret '{name}' (env: {target_env}). Restart workspaces to pick up the change.")


@click.command(name="devbox:secret:rm", help="Delete a Coder user secret")
@click.argument("name")
def devbox_secret_rm(name: str) -> None:
    """Delete a Coder user secret by name."""
    ensure_runtime_ready()
    _ensure_user_secrets_supported()

    result = delete_user_secret(name)
    if result.returncode != 0:
        if result.stderr:
            click.echo(result.stderr.strip(), err=True)
        _fail(f"Failed to delete user secret '{name}'.")
    click.echo(f"Deleted user secret '{name}'.")


@click.command(name="devbox:config:show", help="Show saved devbox setup configuration")
def devbox_config_show() -> None:
    """Print the local devbox configuration saved by ``devbox:setup``."""
    ensure_runtime_ready()
    if not _print_setup_status(_collect_setup_status()):
        click.echo("Nothing configured yet. Run `hogli devbox:setup`.")


@click.command(name="devbox:config:rm", help="Clear saved devbox configuration items")
@click.argument("keys", nargs=-1)
@click.option("--all", "reset_all", is_flag=True, help="Clear every saved item")
def devbox_config_rm(keys: tuple[str, ...], reset_all: bool) -> None:
    """Remove one or more saved devbox configuration items.

    Valid keys mirror the matching ``--configure-*`` flags on ``devbox:setup``:
    ``git-identity``, ``git-signing``, ``region``, ``dotfiles``, ``claude``, ``worktree-boxes``,
    ``worktree-auto``, ``worktree-provider``.
    """
    by_key = _config_items_by_key()
    valid_keys = tuple(by_key)

    if reset_all and keys:
        _fail("Pass --all or one or more keys, not both. Valid keys: " + ", ".join(valid_keys))
    if not reset_all and not keys:
        _fail("Pass at least one key, or --all. Valid keys: " + ", ".join(valid_keys))

    unknown = [k for k in keys if k not in by_key]
    if unknown:
        suffix = "s" if len(unknown) > 1 else ""
        _fail(f"Unknown key{suffix}: {', '.join(unknown)}. Valid keys: {', '.join(valid_keys)}")

    ensure_runtime_ready()
    targets = [by_key[k] for k in (valid_keys if reset_all else keys)]
    if any(item.needs_secrets for item in targets):
        _ensure_user_secrets_supported()

    # Materialize results so every handler runs even when only some clear anything.
    fired = [item.reset() for item in targets]
    if any(fired):
        click.echo()
        click.echo("Restart any running devbox (`hogli devbox:restart`) to pick up the resets.")


@click.command(name="devbox:destroy", help="Destroy your devbox and its data")
@workspace_argument
@click.option("-v", "--verbose", is_flag=True, help="Show full Coder/Terraform build output")
def devbox_destroy(workspace: str | None, verbose: bool) -> None:
    """Destroy the devbox completely."""
    ensure_runtime_ready()
    name, workspaces = resolve_workspace_name(workspace)

    ws = get_workspace(name, workspaces)
    if ws is None:
        click.echo("No devbox found.")
        return

    if not click.confirm(f"Destroy '{name}'? This deletes the VM and its data"):
        click.echo("Cancelled.")
        return

    label = mutagen.workspace_label_selector(name)
    if mutagen.sync_list(label_selector=label):
        try:
            mutagen.sync_terminate(label)
            click.echo("Sync session terminated.")
        except SystemExit:
            # Best-effort: a stuck mutagen daemon should not block the user
            # from destroying their devbox. The session ends with the remote.
            click.echo(click.style("Warning: failed to terminate sync session; continuing.", fg="yellow"))

    delete_workspace(name, verbose=verbose)
    herdr_app.forget_machine(name)
    click.echo("Destroyed.")


@click.command(name="devbox:status", help="Show devbox status")
@workspace_argument
def devbox_status(workspace: str | None) -> None:
    """Show the current state of the devbox."""
    ensure_runtime_ready()
    name, workspaces = resolve_workspace_name(workspace)

    ws = get_workspace(name, workspaces)
    if ws is None:
        click.echo("No devbox found. Run 'hogli devbox:start' to create one.")
        return

    status = get_workspace_status(ws)

    click.echo(f"  Name:    {name}")
    click.echo(f"  Status:  {click.style(status, fg=_workspace_status_color(status))}")
    click.echo(f"  Region:  {get_workspace_region(ws) or 'unknown'}")
    click.echo(f"  Sync:    {_render_sync_status(name)}")

    if ws.get("outdated"):
        click.echo(click.style("  Update:  template update available", fg="yellow"))
        click.echo("           Run `hogli devbox:update` to apply it.")

    # Show agent status if available
    resources = ws.get("latest_build", {}).get("resources", [])
    for resource in resources:
        for agent in resource.get("agents", []):
            agent_status = agent.get("status", "unknown")
            click.echo(f"  Agent:   {agent_status}")

    if status == "running":
        _print_connection_info(name)


@click.command(name="devbox:forward", help="Forward PostHog UI to localhost")
@workspace_argument
@click.option("--port", default=8010, type=int, help="Local port to forward to")
def devbox_forward(workspace: str | None, port: int) -> None:
    """Forward the PostHog UI port to localhost."""
    ensure_runtime_ready()
    name, _ = resolve_workspace_name(workspace)
    if not _local_port_is_available(port):
        _fail(
            f"Local port {port} is already in use.\n"
            f"Stop the process using that port or rerun with `hogli devbox:forward --port {port + 1}`."
        )

    click.echo(f"Forwarding {name}:8010 -> localhost:{port}")
    click.echo(f"PostHog UI at http://localhost:{port}")
    click.echo("Ctrl+C to stop")
    click.echo()
    port_forward_replace(name, port, 8010)


def _gib(nbytes: int) -> str:
    return f"{nbytes / 1024**3:.1f}G"


def _snapshot_free(paths: list[Path]) -> dict[int, int]:
    """Return free bytes keyed by device ID, deduplicating paths on the same filesystem."""
    seen: dict[int, int] = {}
    for path in paths:
        try:
            dev = path.stat().st_dev
            if dev not in seen:
                seen[dev] = shutil.disk_usage(path).free
        except OSError:
            pass
    return seen


def _sum_freed(before: dict[int, int], after: dict[int, int]) -> int:
    """Sum free-space gains across all watched devices."""
    return sum(max(0, after[dev] - before[dev]) for dev in after if dev in before)


def _run_cleanup_step(label: str, cmd: list[str]) -> None:
    """Run a cleanup command and print its label."""
    click.echo(f"  {label}...", nl=False)
    try:
        subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)  # noqa: S603
        click.echo(" done")
    except FileNotFoundError:
        click.echo(" skipped (command unavailable)")
    except subprocess.CalledProcessError as e:
        click.echo(f" warning: exited with code {e.returncode}")


def _rm_dir(label: str, path: Path) -> None:
    """Delete a directory and print its label."""
    if not path.exists():
        click.echo(f"  {label}... skipped (not found)")
        return
    click.echo(f"  {label}...", nl=False)
    try:
        shutil.rmtree(path)
        click.echo(" done")
    except OSError as e:
        click.echo(f" warning: partial deletion ({e})")


@click.command(name="devbox:cleanup:disk", help="Free disk space by cleaning caches and build artifacts")
@workspace_argument
@click.option("--docker", "prune_docker", is_flag=True, help="Also prune stopped Docker containers")
@click.option(
    "--cargo",
    "prune_cargo",
    is_flag=True,
    help="Also remove Cargo build artifacts (forces full Rust recompile on next build)",
)
def devbox_cleanup_disk(workspace: str | None, prune_docker: bool, prune_cargo: bool) -> None:
    """Free disk space by removing caches and build artifacts that are safe to delete.

    The default run is safe: it only removes orphaned packages, download caches,
    and old Nix generations — none of which force a full rebuild on next use.
    Use --cargo to also remove Cargo build artifacts (forces full Rust recompile).
    Use --docker to also prune stopped containers.

    Runs locally by default. Pass a WORKSPACE (or --name/-n) to run it remotely
    on that devbox over ssh instead.
    """
    if workspace:
        ensure_runtime_ready()
        # Cleanup is destructive (removes caches and build artifacts), so refuse
        # to run it against someone else's shared `@user[/label]` devbox.
        if workspace.startswith("@"):
            _fail("devbox:cleanup:disk only runs against your own devboxes, not a shared '@user' workspace.")
        name, workspaces = resolve_workspace_name(workspace)
        _get_workspace_or_fail(name, workspaces)
        if not coder_ssh_alias_configured(name):
            _fail(
                "SSH access for devboxes isn't configured. Run `hogli devbox:setup` (it runs `coder config-ssh`), then retry."
            )
        remote_cmd = ["./bin/hogli", "devbox:cleanup:disk"]
        if prune_docker:
            remote_cmd.append("--docker")
        if prune_cargo:
            remote_cmd.append("--cargo")
        # `hogli` is not on the devbox PATH, even in a login shell, so run the
        # checkout's copy from inside the repo.
        exec_replace(name, ["bash", "-lc", f"cd ~/posthog && {shlex.join(remote_cmd)}"])
        return  # unreachable; exec_replace replaces the process

    home = Path.home()
    # Watch distinct filesystems: home covers uv/sccache/cargo; /nix covers Nix store
    # (may be a separate volume); / covers Docker storage and anything else.
    watch_paths = [p for p in [home, Path("/nix"), Path("/")] if p.exists()]
    before = _snapshot_free(watch_paths)

    click.echo("Cleaning caches and build artifacts...")
    click.echo()

    # uv wheel/sdist cache
    _run_cleanup_step("uv cache (~/.cache/uv)", ["uv", "cache", "clean"])

    # sccache compiler cache
    _rm_dir("sccache (~/.cache/sccache)", home / ".cache" / "sccache")

    # pnpm orphaned store entries
    _run_cleanup_step("pnpm store (orphaned packages)", ["pnpm", "store", "prune"])

    click.echo("  Nix garbage collection (old generations)...", nl=False)
    try:
        subprocess.run(["nix-collect-garbage", "-d"], check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)  # noqa: S603
        click.echo(" done")
    except FileNotFoundError:
        click.echo(" skipped (nix-collect-garbage unavailable)")
    except subprocess.CalledProcessError as e:
        click.echo(f" warning: exited with code {e.returncode}")

    # Cargo build artifacts — opt-in because removing them forces a full Rust recompile
    if prune_cargo:
        _rm_dir("Cargo build artifacts (~/.cargo/target)", home / ".cargo" / "target")

    if prune_docker:
        click.echo("  Docker stopped containers...", nl=False)
        try:
            subprocess.run(
                ["docker", "container", "prune", "-f"], check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
            )  # noqa: S603
            click.echo(" done")
        except FileNotFoundError:
            click.echo(" skipped (docker unavailable)")
        except subprocess.CalledProcessError as e:
            click.echo(f" warning: exited with code {e.returncode}")

    actually_freed = _sum_freed(before, _snapshot_free(watch_paths))

    click.echo()
    if actually_freed > 0:
        click.echo(click.style(f"Freed {_gib(actually_freed)} of disk space.", fg="green"))
    else:
        click.echo("Nothing significant was freed (caches may already be empty).")

    tips = []
    if not prune_cargo:
        tips.append("  hogli devbox:cleanup:disk --cargo  (rm ~/.cargo/target, forces recompile)")
    if not prune_docker:
        tips.append("  hogli devbox:cleanup:disk --docker  (prune stopped containers)")
    if tips:
        click.echo()
        click.echo("Tips for more space:")
        for tip in tips:
            click.echo(tip)