feat(cli): add --format=json to start --dry-run for machine-readable plan

BottlePlan gains a to_dict method (abstract on the base, implemented
on DockerBottlePlan) returning a JSON-serializable view of the resolved
plan. `cli.py start --dry-run --format=json` prints it to stdout and
exits zero. --format=json without --dry-run is rejected — emitting JSON
during a real launch would race the y/N prompt.

The dry-run integration test now parses the JSON and asserts on
structured fields (agent, bottle, runtime, hosts sorted+deduped, etc.)
instead of regex-matching the human-readable preflight stdout. That
kills the magic-"8 hosts allowed" coupling — adding a new baked
default doesn't break the test.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

claude_bottle/backend/__init__.py

@@ -66,6 +66,13 @@ class BottlePlan(ABC):
     def print(self, *, remote_control: bool) -> None:
         """Render the y/N preflight summary to stderr."""
 
+    @abstractmethod
+    def to_dict(self, *, remote_control: bool) -> dict[str, object]:
+        """Return the plan as a JSON-serializable dict for machine
+        consumption (used by `start --dry-run --format=json`). The key
+        set is part of the CLI's user-facing contract — adding fields
+        is fine, renaming or removing is a breaking change."""
+
 
 @dataclass(frozen=True)
 class BottleCleanupPlan(ABC):

claude_bottle/backend/docker/bottle_plan.py

@@ -12,7 +12,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from ...log import info
-from ...pipelock import PipelockProxyPlan
+from ...pipelock import PipelockProxyPlan, pipelock_effective_allowlist
 from .. import BottlePlan
 
 
@@ -75,3 +75,36 @@ class DockerBottlePlan(BottlePlan):
         )
         info("remote-control  : " + ("enabled" if remote_control else "disabled"))
         print(file=sys.stderr)
+
+    def to_dict(self, *, remote_control: bool) -> dict[str, object]:
+        spec = self.spec
+        manifest = spec.manifest
+        agent = manifest.agents[spec.agent_name]
+        bottle = manifest.bottle_for(spec.agent_name)
+
+        env_names = list(bottle.env.keys())
+        if spec.forward_oauth_token:
+            env_names.append("CLAUDE_CODE_OAUTH_TOKEN")
+
+        hosts = pipelock_effective_allowlist(bottle)
+        return {
+            "agent": spec.agent_name,
+            "bottle": agent.bottle,
+            "container_name": self.container_name,
+            "image": self.image,
+            "derived_image": self.derived_image,
+            "stage_dir": str(self.stage_dir),
+            "runtime": "runsc" if self.use_runsc else "runc",
+            "env_names": env_names,
+            "skills": list(agent.skills),
+            "ssh_hosts": [e.Host for e in bottle.ssh],
+            "egress": {
+                "host_count": len(hosts),
+                "hosts": hosts,
+            },
+            "prompt": {
+                "length": len(agent.prompt),
+                "first_line": agent.prompt.splitlines()[0] if agent.prompt else "",
+            },
+            "remote_control": remote_control,
+        }

claude_bottle/cli/start.py

@@ -5,6 +5,7 @@ session ends."""
 from __future__ import annotations
 
 import argparse
+import json
 import os
 import shutil
 import sys
@@ -12,7 +13,7 @@ import tempfile
 from pathlib import Path
 
 from ..backend import BottleSpec, get_bottle_backend
-from ..log import info
+from ..log import die, info
 from ..manifest import Manifest
 from ._common import PROG, USER_CWD, read_tty_line
 
@@ -22,10 +23,18 @@ def cmd_start(argv: list[str]) -> int:
     parser.add_argument("--dry-run", action="store_true")
     parser.add_argument("--cwd", action="store_true", help="copy host cwd into a derived image")
     parser.add_argument("--remote-control", action="store_true")
+    parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        default="text",
+        help="preflight output format; --format=json requires --dry-run",
+    )
     parser.add_argument("name", help="agent name defined in claude-bottle.json")
     args = parser.parse_args(argv)
 
     dry_run = args.dry_run or os.environ.get("CLAUDE_BOTTLE_DRY_RUN") == "1"
+    if args.format == "json" and not dry_run:
+        die("--format=json requires --dry-run")
 
     manifest = Manifest.resolve(USER_CWD)
     spec = BottleSpec(
@@ -40,6 +49,12 @@ def cmd_start(argv: list[str]) -> int:
     try:
         backend = get_bottle_backend()
         plan = backend.prepare(spec, stage_dir=stage_dir)
+
+        if args.format == "json":
+            json.dump(plan.to_dict(remote_control=args.remote_control), sys.stdout, indent=2)
+            sys.stdout.write("\n")
+            return 0
+
         plan.print(remote_control=args.remote_control)
 
         if dry_run: