treebox 0.1.0__py3-none-any.whl

treebox/cli.py

@@ -0,0 +1,1061 @@
+"""Typer CLI: create / enter / list / teardown / doctor.
+
+Conventions: data to stdout, diagnostics to stderr, exit 0 on success. ``--json``
+gives machine output; ``--print`` emits the copy-pasteable launch command; both
+provision without launching the agent (handy over SSH / for scripting).
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import signal
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from . import __version__, git, locking, names, provision, resolve, state, system
+from .config import VALID_RUNNERS, VALID_TOOLS, Config, load_config
+from .models import (
+    Worktree,
+    derive_name,
+    is_placeholder,
+    is_slug,
+    placeholder_branch,
+    worktree_path,
+    worktree_root,
+)
+from .output import Reporter, StepError, format_elapsed
+from .runners import PreflightError, Runner, get_runner
+
+# Stable, documented exit codes (see the epilog on `--help`). Agents branch on these.
+EXIT_OK = 0
+EXIT_ERROR = 1  # generic / unexpected failure
+EXIT_USAGE = 2  # bad invocation (invalid name/branch, ambiguous ref, bad option)
+EXIT_NOTFOUND = 3  # the worktree/branch the command needs does not exist
+EXIT_PERMISSION = 4  # auth / fetch / credential problem
+EXIT_CONFLICT = 5  # already exists / uncommitted changes / lock held
+
+# Current JSON schema version. Payloads only gain fields after this (porcelain
+# discipline); bumps are reserved for breaking changes. v2: branchless create —
+# create/enter/list gained "name"; teardown became variadic and its payload is
+# now a "worktrees" array instead of one flat record.
+SCHEMA_VERSION = 2
+
+_EPILOG = (
+    "Exit codes: 0 ok · 2 usage · 3 not-found · 4 auth/permission "
+    "· 5 conflict (exists/locked/dirty)."
+)
+
+app = typer.Typer(
+    add_completion=True,
+    no_args_is_help=True,
+    help="Isolated, ready-to-run git worktrees for AI coding agents "
+    "— host-native or docker-sandboxed.",
+    epilog=_EPILOG,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+# --- shared helpers ----------------------------------------------------------
+
+
+def _emit_json(payload: dict, *, stream=None) -> None:
+    """The one place --json serialization is defined: pretty-printed, trailing
+    newline — identical for success payloads (stdout) and error payloads (stderr)."""
+    (stream or sys.stdout).write(json.dumps(payload, indent=2) + "\n")
+
+
+def _die(
+    reporter: Reporter,
+    message: str,
+    *,
+    code: int = EXIT_ERROR,
+    error_code: str = "ERROR",
+    hint: str | None = None,
+    path: str | None = None,
+    json_out: bool = False,
+) -> typer.Exit:
+    """Report a failure and return a typer.Exit carrying the right exit code.
+
+    In ``--json`` mode the error is emitted as a structured object on stderr so
+    agents can branch on ``error.code``; otherwise it's a styled message (+ hint).
+    """
+    if json_out:
+        error: dict[str, str] = {"code": error_code, "message": message}
+        if hint:
+            error["hint"] = hint
+        if path:
+            error["path"] = path
+        payload = {"schemaVersion": SCHEMA_VERSION, "error": error}
+        _emit_json(payload, stream=sys.stderr)
+    else:
+        reporter.error(message)
+        if hint:
+            reporter.hint(hint)
+    return typer.Exit(code)
+
+
+def _resolve_config(
+    reporter: Reporter,
+    *,
+    runner: str | None,
+    tool: str | None,
+    base: str | None,
+    root: str | None,
+    firewall: bool | None,
+    template: str | None = None,
+    json_out: bool = False,
+) -> Config:
+    try:
+        cfg = load_config()
+    except ValueError as exc:
+        # A malformed/invalid user config.toml is a usage problem, not a crash:
+        # exit 2 with a styled message — or a structured error in --json mode.
+        raise _die(
+            reporter,
+            str(exc),
+            code=EXIT_USAGE,
+            error_code="INVALID_CONFIG",
+            hint="Fix the config file (or unset $TREEBOX_CONFIG).",
+            json_out=json_out,
+        ) from exc
+    return cfg.with_overrides(
+        runner=runner,
+        tool=tool,
+        base=base,
+        root=root,
+        firewall=firewall,
+        template=template,
+    )
+
+
+def _runner_from_state(
+    reporter: Reporter,
+    cfg: Config,
+    st: state.WorktreeState | None,
+    *,
+    explicit: str | None,
+    json_out: bool = False,
+) -> Config:
+    """Prefer the runner this worktree was provisioned with.
+
+    The sandbox/no-sandbox decision is recorded at create time; falling back to
+    the config default would silently enter a docker-sandboxed worktree on the
+    host (or leak its container on teardown). An explicit ``--runner`` that
+    disagrees with the recorded one is a conflict, not an override.
+    """
+    recorded = st.runner if st else ""
+    if not recorded:
+        return cfg
+    if recorded not in VALID_RUNNERS:
+        raise _die(
+            reporter,
+            f"Worktree was provisioned with unknown runner '{recorded}'.",
+            code=EXIT_CONFLICT,
+            error_code="UNKNOWN_RUNNER",
+            hint="This worktree predates the current runners. Remove it manually "
+            "(git worktree remove; docker rm any leftover container) and re-create it.",
+            json_out=json_out,
+        )
+    if explicit is None:
+        return cfg.with_overrides(runner=recorded)
+    if explicit != recorded:
+        raise _die(
+            reporter,
+            f"Worktree was provisioned with the '{recorded}' runner, "
+            f"but --runner {explicit} was given.",
+            code=EXIT_CONFLICT,
+            error_code="RUNNER_MISMATCH",
+            hint=f"Drop --runner to use the recorded '{recorded}' runner, or tear "
+            "down and re-create the worktree with the new one.",
+            json_out=json_out,
+        )
+    return cfg
+
+
+def _repo_root(reporter: Reporter, repo: str, *, json_out: bool = False) -> str:
+    try:
+        return git.repo_root(repo)
+    except git.GitError as exc:
+        raise _die(
+            reporter,
+            str(exc),
+            code=EXIT_USAGE,
+            error_code="NOT_A_REPO",
+            hint="Run inside a git repo, or pass --repo <path>.",
+            json_out=json_out,
+        ) from exc
+
+
+def _validate_branch(reporter: Reporter, branch: str, *, json_out: bool = False) -> None:
+    if not git.check_ref_format(branch):
+        raise _die(
+            reporter,
+            f"Invalid branch name '{branch}'.",
+            code=EXIT_USAGE,
+            error_code="INVALID_BRANCH",
+            json_out=json_out,
+        )
+
+
+def _validate_name(reporter: Reporter, name: str, *, json_out: bool = False) -> None:
+    if not is_slug(name):
+        raise _die(
+            reporter,
+            f"Invalid worktree name '{name}'.",
+            code=EXIT_USAGE,
+            error_code="INVALID_NAME",
+            hint="One lowercase slug token (letters, digits, hyphens), e.g. fix-auth — "
+            "or omit it for a generated name.",
+            json_out=json_out,
+        )
+
+
+def _name_taken(repo_path: str, root: str, name: str) -> bool:
+    """Whether a *generated* name is unusable: its directory or its placeholder
+    branch (local or on origin) already exists."""
+    if worktree_path(repo_path, root, name).exists():
+        return True
+    ph = placeholder_branch(name)
+    return git.local_branch_exists(repo_path, ph) or git.remote_branch_exists(repo_path, ph)
+
+
+# Exceptions provisioning can raise, mapped to exit codes by _handle().
+_PROVISION_ERRORS = (
+    provision.ProvisionError,
+    locking.LockError,
+    git.GitError,
+    StepError,
+    RuntimeError,
+)
+
+
+def _classify(exc: Exception) -> tuple[int, str, str | None]:
+    """Map a provisioning exception to (exit_code, error_code, hint)."""
+    if isinstance(exc, locking.LockError):
+        return (
+            EXIT_CONFLICT,
+            "LOCK_HELD",
+            "Another run holds this worktree — wait, then retry.",
+        )
+    if isinstance(exc, git.FetchError):
+        msg = str(exc).lower()
+        if "publickey" in msg or "permission denied" in msg:
+            hint = (
+                "Git auth failed. Authenticate once and re-run: `gh auth login` "
+                "(GitHub), `glab auth login` (GitLab), or a git credential helper / "
+                "HTTPS token (Bitbucket, Azure, others). Or load an SSH key "
+                '(eval "$(ssh-agent -s)"; ssh-add), or pass --no-fetch for stale refs.'
+            )
+        else:
+            hint = (
+                "Make origin reachable: authenticate once (`gh auth login`, "
+                "`glab auth login`, or a git credential helper), or pass --no-fetch."
+            )
+        return EXIT_PERMISSION, "FETCH_FAILED", hint
+    if isinstance(exc, provision.SlugConflictError):
+        return EXIT_CONFLICT, "SLUG_CONFLICT", exc.hint
+    if isinstance(exc, resolve.AmbiguousRefError):
+        return EXIT_USAGE, "AMBIGUOUS_REF", exc.hint
+    if isinstance(exc, provision.NotFoundError):
+        return EXIT_NOTFOUND, "NOT_FOUND", exc.hint
+    if isinstance(exc, PreflightError):
+        # Runner dependency problems keep exit 1 (codes are stable; agents
+        # branch on error.code instead: MISSING_DEPENDENCY, DOCKER_UNAVAILABLE).
+        return EXIT_ERROR, exc.error_code, exc.hint
+    return EXIT_ERROR, "ERROR", None
+
+
+def _handle(reporter: Reporter, exc: Exception, *, json_out: bool) -> typer.Exit:
+    reporter.restore_terminal()
+    code, error_code, hint = _classify(exc)
+    return _die(
+        reporter,
+        str(exc),
+        code=code,
+        error_code=error_code,
+        hint=hint,
+        json_out=json_out,
+    )
+
+
+def _short_path(path: Path | str, repo: str) -> str:
+    """A compact, readable path: relative to the repo when possible, else
+    home-collapsed — so status rows stay on one tidy line."""
+    p = Path(path)
+    try:
+        return str(p.relative_to(repo))
+    except ValueError:
+        pass
+    try:
+        return "~/" + str(p.relative_to(Path.home()))
+    except ValueError:
+        return str(p)
+
+
+def _emit_result(outcome: provision.Outcome, *, json_out: bool, print_only: bool) -> None:
+    """Write the machine/script-facing result to stdout."""
+    if json_out:
+        payload = {
+            "schemaVersion": SCHEMA_VERSION,
+            "name": outcome.worktree.name,
+            "worktree_path": str(outcome.worktree.path),
+            "branch": outcome.worktree.branch,
+            "base": outcome.worktree.base,
+            "entry_command": outcome.entry_command,
+            "created": outcome.created,
+        }
+        _emit_json(payload)
+    elif print_only:
+        sys.stdout.write(" ".join(shlex.quote(p) for p in outcome.entry_command) + "\n")
+
+
+def _dry_run(
+    reporter: Reporter,
+    cfg: Config,
+    run: Runner,
+    repo_path: str,
+    name: str,
+    branch: str,
+    *,
+    fetch: bool,
+    json_out: bool,
+) -> None:
+    """Render what ``create`` would do, executing nothing."""
+    try:
+        wt, cmds = provision.dry_run_plan(
+            cfg, run, repo=repo_path, name=name, branch=branch, base=cfg.base, fetch=fetch
+        )
+    except _PROVISION_ERRORS as exc:
+        raise _handle(reporter, exc, json_out=json_out) from exc
+
+    if json_out:
+        _emit_json(
+            {
+                "schemaVersion": SCHEMA_VERSION,
+                "dry_run": True,
+                "name": name,
+                "worktree_path": str(wt.path),
+                "branch": branch,
+                "commands": cmds,
+            }
+        )
+        return
+
+    reporter.heading("create", f"{name}  ·  dry run")
+    reporter.summary("worktree", _short_path(wt.path, repo_path))
+    reporter.summary("branch", branch)
+    reporter.summary("runner", f"{cfg.runner}  →  {cfg.tool}")
+    reporter.blank()
+    for cmd in cmds:
+        reporter.command(cmd)
+    reporter.blank()
+
+
+# --- create ------------------------------------------------------------------
+
+
+@app.command()
+def create(
+    name: str | None = typer.Argument(
+        None,
+        help=(
+            "Worktree name: one slug token (lowercase letters, digits, hyphens). "
+            "Omitted: a generated petname."
+        ),
+    ),
+    branch: str | None = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Check out this exact existing branch (local or origin) — the only "
+        "path that skips the treebox/ placeholder.",
+    ),
+    repo: str = typer.Option(".", "--repo", help="Git repo to create from. Default: current repo."),
+    root: str | None = typer.Option(None, "--root", help="Worktree root dir."),
+    base: str | None = typer.Option(
+        None, "--base", help="Base branch for the new branch (resolved as origin/<base>)."
+    ),
+    runner: str | None = typer.Option(
+        None, "--runner", help=f"Run seam: {'|'.join(VALID_RUNNERS)}."
+    ),
+    tool: str | None = typer.Option(
+        None, "--tool", help=f"Agent to launch: {'|'.join(VALID_TOOLS)}."
+    ),
+    cold: bool = typer.Option(
+        False, "--cold", help="Bypass shared caches for a from-source build."
+    ),
+    no_fetch: bool = typer.Option(
+        False,
+        "--no-fetch",
+        help="Opt out of the required origin fetch and accept (possibly stale) local refs.",
+    ),
+    firewall: bool = typer.Option(
+        False, "--firewall", help="Enable the container firewall (docker runner)."
+    ),
+    template: str | None = typer.Option(
+        None,
+        "--template",
+        help="Operator-owned sandbox template name (docker runner). "
+        "Resolved from $TREEBOX_TEMPLATE_DIR or ~/.config/treebox/templates/<name>.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the git/runner commands that would run; change nothing.",
+    ),
+    print_only: bool = typer.Option(
+        False, "--print", help="Provision, then print the launch command (no launch)."
+    ),
+    json_out: bool = typer.Option(
+        False, "--json", help="Provision, then print a JSON result (no launch)."
+    ),
+    quiet: bool = typer.Option(False, "--quiet", help="Suppress progress."),
+    verbose: bool = typer.Option(False, "--verbose", help="Stream raw command output."),
+) -> None:
+    """Provision a worktree and hand it to the runner.
+
+    Without -b the worktree starts on a treebox/<name> placeholder branch that a
+    pre-push guard keeps un-pushable: name the work when it takes shape
+    (git branch -m <type>/<short-name>, e.g. feature/user-auth, fix/login-race,
+    chore/bump-deps), then push.
+    """
+    reporter = Reporter(quiet=quiet, verbose=verbose, silent=json_out)
+    cfg = _resolve_config(
+        reporter,
+        runner=runner,
+        tool=tool,
+        base=base,
+        root=root,
+        firewall=firewall or None,
+        template=template,
+        json_out=json_out,
+    )
+    if name is not None:
+        _validate_name(reporter, name, json_out=json_out)
+    if branch is not None:
+        _validate_branch(reporter, branch, json_out=json_out)
+    repo_path = _repo_root(reporter, repo, json_out=json_out)
+
+    if branch is not None:
+        wt_name = name or derive_name(branch)
+        target_branch = branch
+    else:
+        wt_name = name or names.petname(lambda n: _name_taken(repo_path, cfg.root, n))
+        target_branch = placeholder_branch(wt_name)
+
+    run = get_runner(cfg)
+
+    if dry_run:
+        _dry_run(
+            reporter,
+            cfg,
+            run,
+            repo_path,
+            wt_name,
+            target_branch,
+            fetch=not no_fetch,
+            json_out=json_out,
+        )
+        return
+
+    reporter.heading("create", wt_name)
+    if branch is not None:
+        reporter.summary("branch", target_branch)
+    else:
+        reporter.summary("branch", f"{target_branch}  ·  placeholder — rename before push")
+        reporter.summary("base", cfg.base)
+    reporter.summary("runner", f"{cfg.runner}  →  {cfg.tool}")
+    if cold:
+        reporter.summary("cache", "cold (from source)")
+    reporter.blank()
+
+    started = time.monotonic()
+    try:
+        # Runner-specific preconditions (a no-op for the host runner); fail
+        # before touching git state rather than mid-provision.
+        run.preflight(reporter)
+        with locking.worktree_lock(repo_path, cfg.root, wt_name):
+            outcome = provision.create(
+                cfg,
+                run,
+                repo=repo_path,
+                name=wt_name,
+                branch=target_branch,
+                base=cfg.base,
+                tool=cfg.tool,
+                cold=cold,
+                fetch=not no_fetch,
+                # Prompt for git credentials whenever a terminal is attached —
+                # like `git pull`. ssh's passphrase prompt uses the tty/stderr,
+                # so it stays out of the way of --json's stdout.
+                interactive=sys.stdin.isatty(),
+                reporter=reporter,
+                existing_branch=branch is not None,
+            )
+    except _PROVISION_ERRORS as exc:
+        raise _handle(reporter, exc, json_out=json_out) from exc
+
+    _finish(
+        reporter,
+        run,
+        cfg,
+        outcome,
+        json_out=json_out,
+        print_only=print_only,
+        args=[],
+        started=started,
+    )
+
+
+# --- enter -------------------------------------------------------------------
+
+
+@app.command()
+def enter(
+    ref: str = typer.Argument(..., help="Worktree name, branch, or a unique substring of either."),
+    repo: str = typer.Option(".", "--repo", help="Git repo. Default: current repo."),
+    root: str | None = typer.Option(None, "--root", help="Worktree root dir."),
+    runner: str | None = typer.Option(
+        None, "--runner", help=f"Run seam: {'|'.join(VALID_RUNNERS)}."
+    ),
+    tool: str | None = typer.Option(
+        None, "--tool", help=f"Agent to launch: {'|'.join(VALID_TOOLS)}."
+    ),
+    template: str | None = typer.Option(
+        None, "--template", help="Operator-owned sandbox template name (docker runner)."
+    ),
+    cold: bool = typer.Option(False, "--cold", help="Bypass shared caches when re-syncing."),
+    print_only: bool = typer.Option(
+        False, "--print", help="Prepare, then print the launch command (no launch)."
+    ),
+    json_out: bool = typer.Option(
+        False, "--json", help="Prepare, then print a JSON result (no launch)."
+    ),
+    quiet: bool = typer.Option(False, "--quiet", help="Suppress progress."),
+    verbose: bool = typer.Option(False, "--verbose", help="Stream raw command output."),
+    args: list[str] | None = typer.Argument(
+        None, help="Extra args passed to the agent (after --)."
+    ),
+) -> None:
+    """Re-launch the agent in an existing worktree; refresh .env and re-sync deps if changed."""
+    reporter = Reporter(quiet=quiet, verbose=verbose, silent=json_out)
+    cfg = _resolve_config(
+        reporter,
+        runner=runner,
+        tool=tool,
+        base=None,
+        root=root,
+        firewall=None,
+        template=template,
+        json_out=json_out,
+    )
+    repo_path = _repo_root(reporter, repo, json_out=json_out)
+    try:
+        cand = resolve.resolve_ref(repo_path, cfg.root, ref)
+    except _PROVISION_ERRORS as exc:
+        raise _handle(reporter, exc, json_out=json_out) from exc
+    st = state.load(cand.path)
+    cfg = _runner_from_state(reporter, cfg, st, explicit=runner, json_out=json_out)
+    run = get_runner(cfg)
+
+    subtitle = cand.name if cand.branch in (None, cand.name) else f"{cand.name}  ·  {cand.branch}"
+    reporter.heading("enter", subtitle)
+    reporter.summary("runner", f"{cfg.runner}  →  {cfg.tool}")
+    reporter.blank()
+
+    started = time.monotonic()
+    try:
+        with locking.worktree_lock(repo_path, cfg.root, cand.name):
+            outcome = provision.enter(
+                cfg,
+                run,
+                repo=repo_path,
+                name=cand.name,
+                tool=cfg.tool,
+                cold=cold,
+                args=args or [],
+                reporter=reporter,
+            )
+    except _PROVISION_ERRORS as exc:
+        raise _handle(reporter, exc, json_out=json_out) from exc
+
+    _finish(
+        reporter,
+        run,
+        cfg,
+        outcome,
+        json_out=json_out,
+        print_only=print_only,
+        args=args or [],
+        started=started,
+    )
+
+
+def _finish(
+    reporter: Reporter,
+    run: Runner,
+    cfg: Config,
+    outcome: provision.Outcome,
+    *,
+    json_out: bool,
+    print_only: bool,
+    args: list[str],
+    started: float,
+) -> None:
+    if json_out or print_only:
+        _emit_result(outcome, json_out=json_out, print_only=print_only)
+        return
+    reporter.blank()
+    # Style-A closing line: green "Ready", dim "in <total> — launching <tool>".
+    reporter.ready(format_elapsed(time.monotonic() - started), cfg.tool)
+    reporter.blank()
+    reporter.restore_terminal()
+    try:
+        code = run.launch(outcome.worktree, tool=cfg.tool, args=args)
+    except RuntimeError as exc:
+        raise _die(reporter, str(exc)) from exc
+    raise typer.Exit(code)
+
+
+# --- list --------------------------------------------------------------------
+
+
+@app.command(name="list")
+def list_cmd(
+    repo: str = typer.Option(".", "--repo", help="Git repo. Default: current repo."),
+    root: str | None = typer.Option(None, "--root", help="Worktree root dir."),
+    json_out: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """List worktrees by name with live branch, last commit, age, and dep/.env freshness."""
+    reporter = Reporter(silent=json_out)
+    cfg = _resolve_config(
+        reporter,
+        runner=None,
+        tool=None,
+        base=None,
+        root=root,
+        firewall=None,
+        json_out=json_out,
+    )
+    repo_path = _repo_root(reporter, repo, json_out=json_out)
+    base_dir = worktree_root(repo_path, cfg.root)
+
+    from . import ecosystems
+
+    rows: list[dict[str, Any]] = []
+    for rec in git.worktree_list(repo_path):
+        if not Path(rec.path).is_relative_to(base_dir):
+            continue
+        st = state.load(rec.path)
+        wt_path = Path(rec.path)
+        env_present = (wt_path / ".env").is_file()
+        if st and st.lockfile_hash:
+            deps = "fresh" if st.lockfile_hash == ecosystems.lockfile_hash(wt_path) else "stale"
+        else:
+            deps = "unknown"
+        subject, epoch = git.last_commit(wt_path)
+        rows.append(
+            {
+                "name": wt_path.name,
+                "branch": rec.branch or "detached",
+                "unnamed": is_placeholder(rec.branch),
+                "last_commit": subject,
+                "commit_epoch": epoch,
+                "path": rec.path,
+                "base": st.base if st else "",
+                "runner": st.runner if st else "",
+                "tool": st.tool if st else "",
+                "deps": deps,
+                "env": "present" if env_present else "absent",
+            }
+        )
+
+    # Most recently touched first: the worktree you're looking for is almost
+    # always the one you (or an agent) just committed in.
+    rows.sort(key=lambda r: r["commit_epoch"], reverse=True)
+
+    if json_out:
+        payload = {"schemaVersion": SCHEMA_VERSION, "worktrees": rows}
+        _emit_json(payload)
+        return
+
+    reporter.render_list(rows, repo_path)
+
+
+# --- teardown ----------------------------------------------------------------
+
+
+@app.command()
+def teardown(
+    refs: list[str] = typer.Argument(
+        ..., help="Worktrees to remove: name, branch, or a unique substring of either."
+    ),
+    repo: str = typer.Option(".", "--repo", help="Git repo. Default: current repo."),
+    root: str | None = typer.Option(None, "--root", help="Worktree root dir."),
+    runner: str | None = typer.Option(
+        None, "--runner", help=f"Run seam: {'|'.join(VALID_RUNNERS)}."
+    ),
+    delete_branch: bool = typer.Option(
+        False, "--delete-branch", help="Also delete the local branch."
+    ),
+    remove_volumes: bool = typer.Option(
+        False, "--remove-volumes", help="Also remove treebox volumes."
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="Remove even with uncommitted changes / no prompt."
+    ),
+    skip_container: bool = typer.Option(
+        False, "--skip-container", help="Do not touch containers/images."
+    ),
+    json_out: bool = typer.Option(False, "--json", help="Print a JSON record of what was removed."),
+    quiet: bool = typer.Option(False, "--quiet", help="Suppress progress."),
+    verbose: bool = typer.Option(False, "--verbose", help="Stream raw command output."),
+) -> None:
+    """Remove worktree directories (and optionally their branches); caches are left intact."""
+    reporter = Reporter(quiet=quiet, verbose=verbose, silent=json_out)
+    cfg = _resolve_config(
+        reporter,
+        runner=runner,
+        tool=None,
+        base=None,
+        root=root,
+        firewall=None,
+        json_out=json_out,
+    )
+    repo_path = _repo_root(reporter, repo, json_out=json_out)
+
+    # Resolve every ref before touching anything: a typo among three targets
+    # must not leave the first two half-removed.
+    targets: list[resolve.Candidate] = []
+    seen: set[str] = set()
+    for ref in refs:
+        try:
+            cand = resolve.resolve_ref(repo_path, cfg.root, ref)
+        except resolve.AmbiguousRefError as exc:
+            raise _handle(reporter, exc, json_out=json_out) from exc
+        except provision.NotFoundError as exc:
+            # The worktree may be gone while its branch lingers (manual rm):
+            # an exact local-branch match still gets pruned/cleaned up.
+            if git.local_branch_exists(repo_path, ref):
+                gone = worktree_path(repo_path, cfg.root, derive_name(ref))
+                cand = resolve.Candidate(name=derive_name(ref), branch=ref, path=str(gone))
+            else:
+                raise _handle(reporter, exc, json_out=json_out) from exc
+        if cand.path not in seen:
+            seen.add(cand.path)
+            targets.append(cand)
+
+    # Same all-or-nothing rule for safety gates: refuse up front.
+    for cand in targets:
+        if Path(cand.path).is_dir() and not force and git.is_dirty(cand.path):
+            raise _die(
+                reporter,
+                f"Worktree '{cand.name}' has uncommitted changes.",
+                code=EXIT_CONFLICT,
+                error_code="DIRTY_WORKTREE",
+                hint="Commit/stash the changes, or pass --force to remove anyway.",
+                path=cand.path,
+                json_out=json_out,
+            )
+
+    if not force and any(Path(c.path).is_dir() for c in targets):
+        # --json is a scripting contract: never block on a prompt (and never
+        # let one leak into stdout) — require --force instead.
+        if sys.stdin.isatty() and not json_out:
+            listed = ", ".join(c.name for c in targets)
+            plural = "s" if len(targets) != 1 else ""
+            typer.confirm(f"Remove worktree{plural} {listed}?", abort=True)
+        else:
+            raise _die(
+                reporter,
+                "Refusing to remove non-interactively without confirmation.",
+                code=EXIT_CONFLICT,
+                error_code="NEEDS_CONFIRMATION",
+                hint="Pass --force for non-interactive teardown.",
+                json_out=json_out,
+            )
+
+    reporter.heading("teardown", ", ".join(c.name for c in targets))
+
+    records = [
+        _teardown_one(
+            reporter,
+            cfg,
+            cand,
+            repo_path,
+            explicit_runner=runner,
+            delete_branch=delete_branch,
+            remove_volumes=remove_volumes,
+            force=force,
+            skip_container=skip_container,
+            json_out=json_out,
+        )
+        for cand in targets
+    ]
+
+    if json_out:
+        _emit_json({"schemaVersion": SCHEMA_VERSION, "worktrees": records})
+
+
+def _teardown_one(
+    reporter: Reporter,
+    cfg: Config,
+    cand: resolve.Candidate,
+    repo_path: str,
+    *,
+    explicit_runner: str | None,
+    delete_branch: bool,
+    remove_volumes: bool,
+    force: bool,
+    skip_container: bool,
+    json_out: bool,
+) -> dict:
+    """Tear down one resolved worktree; returns its --json record."""
+    wt = Worktree.locate(repo_path, cfg.root, cand.name, cand.branch or "")
+    exists = wt.path.is_dir()
+    st = state.load(wt.path) if exists else None
+    run = get_runner(
+        _runner_from_state(reporter, cfg, st, explicit=explicit_runner, json_out=json_out)
+    )
+
+    branch_name = (
+        cand.branch
+        if cand.branch and (exists or git.local_branch_exists(repo_path, cand.branch))
+        else None
+    )
+
+    container = "skipped"
+    if not skip_container:
+        try:
+            run.teardown(wt, reporter=reporter, remove_volumes=remove_volumes)
+            container = "cleaned"
+        except Exception as exc:  # teardown is best-effort
+            container = "failed"
+            reporter.warn(f"runner teardown: {exc}")
+    else:
+        reporter.note("container", "skipped")
+
+    if exists:
+        try:
+            git.worktree_remove(repo_path, wt.path, force=force)
+        except git.GitError:
+            import shutil as _sh
+
+            _sh.rmtree(wt.path, ignore_errors=True)
+            git.worktree_prune(repo_path)
+        reporter.ok("worktree", f"removed {_short_path(wt.path, repo_path)}")
+    else:
+        git.worktree_prune(repo_path)
+        reporter.note("worktree", f"already gone · {_short_path(wt.path, repo_path)}")
+
+    branch_deleted = False
+    if delete_branch and branch_name:
+        try:
+            git.delete_branch(repo_path, branch_name)
+            branch_deleted = True
+            reporter.ok("branch", f"deleted {branch_name}")
+        except git.GitError as exc:
+            reporter.warn(f"could not delete branch: {exc}")
+    elif branch_name:
+        reporter.note("branch", f"kept {branch_name}")
+
+    return {
+        "name": cand.name,
+        "branch": branch_name,
+        "worktree_path": str(wt.path),
+        "removed": exists,  # False: it was already gone (still exit 0)
+        "branch_deleted": branch_deleted,
+        "container": container,  # "cleaned" | "skipped" | "failed"
+        "volumes_removed": remove_volumes and container == "cleaned",
+    }
+
+
+# --- doctor ------------------------------------------------------------------
+
+
+@app.command()
+def doctor(
+    repo: str = typer.Option(".", "--repo", help="Git repo. Default: current repo."),
+    runner: str | None = typer.Option(
+        None, "--runner", help=f"Runner to check: {'|'.join(VALID_RUNNERS)}."
+    ),
+    json_out: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Check git, login credentials, UID/GID, and runner-specific dependencies."""
+    reporter = Reporter(silent=json_out)
+    cfg = _resolve_config(
+        reporter,
+        runner=runner,
+        tool=None,
+        base=None,
+        root=None,
+        firewall=None,
+        json_out=json_out,
+    )
+    run = get_runner(cfg)
+
+    # Instant checks: no I/O worth spinning on, so they print immediately.
+    checks: list[tuple[str, bool, str]] = []
+
+    git_ok = git.have_git()
+    git_ver = git.version_str() if git_ok else "missing"
+    checks.append(("git", git_ok, git_ver))
+
+    repo_path = ""
+    try:
+        repo_path = git.repo_root(repo)
+        checks.append(("repo", True, repo_path))
+    except git.GitError as exc:
+        checks.append(("repo", False, str(exc)))
+
+    ident = system.identity()
+    checks.append(("uid/gid", True, f"{ident.uid}:{ident.gid}"))
+
+    for toolname in ("claude", "codex"):
+        present = system.credential_present(toolname)
+        checks.append((f"login: {toolname}", present, str(system.credential_dir(toolname))))
+
+    # Same resolver copy_env uses, so doctor reports the exact secrets source
+    # provisioning will copy.
+    env_file = (
+        provision.resolve_env_file(repo_path, cfg.env_file) if repo_path else Path(cfg.env_file)
+    )
+    checks.append((".env", env_file.is_file(), str(env_file)))
+
+    # Slow checks hit the network / Docker daemon — the source of doctor's "dead
+    # pause". Deferred as thunks returning a row plus an optional advisory, so the
+    # human path can wrap each in a spinner while --json runs them inline.
+    def _check_git_auth() -> tuple[str, bool, str, str | None]:
+        # `create` REQUIRES a fresh fetch, so validate up front that git can
+        # authenticate to origin — exercising the same silent paths create uses
+        # (ssh-agent, then the HTTPS host-CLI/helper/token fallback).
+        reachable = git.origin_reachable(repo_path) if repo_path else None
+        if reachable is None:
+            return ("git auth", True, "no remote (local-only; freshness N/A)", None)
+        if reachable:
+            return ("git auth", True, "authenticated · fresh fetch will succeed", None)
+        return (
+            "git auth",
+            False,
+            "no working credential for origin",
+            "git can't authenticate to origin without a prompt — `create` requires a "
+            "fresh fetch. In a terminal it will prompt for your SSH key passphrase / "
+            "credentials and continue; headless (no TTY) it fails (exit 4) unless you "
+            "pass --no-fetch. Authenticate once to avoid prompts: `gh auth login` "
+            "(GitHub), `glab auth login` (GitLab), a git credential helper / HTTPS "
+            "token (others), or load an ssh-agent.",
+        )
+
+    def _check_runner() -> tuple[str, bool, str, str | None]:
+        name = f"runner: {run.name}"
+        try:
+            return (name, True, run.preflight(reporter), None)
+        except PreflightError as exc:
+            # Surface the remediation hint as a doctor advisory so the human
+            # checklist says how to fix it, not just what is broken.
+            return (name, False, str(exc), exc.hint)
+        except RuntimeError as exc:
+            return (name, False, str(exc), None)
+
+    slow = [("checking git auth", _check_git_auth), ("checking runner", _check_runner)]
+    advisories: list[str] = []
+
+    if json_out:
+        for _, check in slow:
+            name, ok, detail, advisory = check()
+            checks.append((name, ok, detail))
+            if advisory:
+                advisories.append(advisory)
+        # Credentials are the only hard gate for the host runner: at least one login.
+        has_login = any(ok for name, ok, _ in checks if name.startswith("login:"))
+        payload = {
+            "schemaVersion": SCHEMA_VERSION,
+            "ok": git_ok and bool(repo_path) and (has_login or not run.login_required),
+            "runner": cfg.runner,
+            "checks": [{"name": n, "ok": ok, "detail": d} for n, ok, d in checks],
+            "advisories": advisories,
+        }
+        _emit_json(payload)
+        # Same exit-code contract as the human path: hard checks (git, repo,
+        # runner) failing mean exit 1, so `doctor --json && create` in CI can
+        # branch on $? instead of parsing `ok`.
+        if _doctor_problems(checks):
+            raise typer.Exit(1)
+        return
+
+    # The label column is padded to the widest name; every name is known up front
+    # (the slow checks' names are fixed), so we can align without buffering rows.
+    names_ = [name for name, _, _ in checks] + ["git auth", f"runner: {run.name}"]
+    width = max(len(name) for name in names_)
+
+    checks, advisories = reporter.render_doctor(checks, slow, cfg.runner, width)
+    has_login = any(ok for name, ok, _ in checks if name.startswith("login:"))
+    problems = _doctor_problems(checks)
+    reporter.render_doctor_verdict(problems=problems, has_login=has_login, advisories=advisories)
+    if problems:
+        raise typer.Exit(1)
+
+
+def _doctor_problems(checks: list[tuple[str, bool, str]]) -> list[str]:
+    """The hard-check failures (git, repo, runner) that make doctor exit 1 —
+    one definition so the human and --json paths share an exit-code contract."""
+    return [n for n, ok, _ in checks if not ok and (n.startswith("runner") or n in ("git", "repo"))]
+
+
+# --- version -----------------------------------------------------------------
+
+
+def _resolve_version() -> str:
+    """The installed distribution version, falling back to the package constant."""
+    try:
+        from importlib.metadata import version as _dist_version
+
+        return _dist_version("treebox")
+    except Exception:
+        return __version__
+
+
+@app.command()
+def version() -> None:
+    """Print the version."""
+    sys.stdout.write(f"{_resolve_version()}\n")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        sys.stdout.write(f"{_resolve_version()}\n")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    # Restore default SIGPIPE handling on POSIX so piping output into `head` /
+    # `grep -m1` ends the process quietly (SIGPIPE, exit 141) instead of
+    # surfacing "BrokenPipeError ignored" noise or a traceback at shutdown.
+    # Python starts with SIGPIPE ignored, which is wrong for a piped CLI.
+    if hasattr(signal, "SIGPIPE"):
+        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+
+    # Pretty, secret-safe tracebacks for genuinely unexpected crashes (handled
+    # errors already exit cleanly via _die). Framework frames are suppressed.
+    from rich.traceback import install
+
+    install(show_locals=False, suppress=[typer], width=100)
+
+
+if __name__ == "__main__":
+    app()