feat(bottle): random-suffix identity + cli.py resume <identity>

Replaces the cwd-hash identity with a random 5-char base36 suffix
per launch, so two simultaneous `start <agent>` invocations against
the same cwd no longer collide on container names. Each launch is
its own bottle.

State carries metadata: every prepare step writes
~/.claude-bottle/state/<identity>/metadata.json with the
(agent_name, cwd, copy_cwd, started_at) the bottle was launched
with. The new `cli.py resume <identity>` reads this metadata and
re-launches a bottle pinned to the same identity — picking up the
per-bottle Dockerfile (from a prior capability-block apply) and
the transcript snapshot under the same state dir.

- bottle_state.py: bottle_identity(agent_name) drops the cwd param
  and gains a random suffix; BottleMetadata dataclass +
  read/write/metadata_path helpers.
- BottleSpec gains an optional identity field — resume sets it to
  pin the identity; start leaves it empty so prepare mints fresh.
- prepare.py: writes metadata at launch time; uses spec.identity if
  provided (resume) else bottle_identity(agent_name) (fresh start).
- start.py: extracted _launch_bottle from cmd_start so resume can
  share the launch core; prints `./cli.py resume <identity>` hint
  at session end.
- cli/resume.py (new): reads metadata, reconstructs BottleSpec
  with the recorded identity + cwd, delegates to _launch_bottle.
  Errors clearly when no state exists for the given identity.
- cli/__init__.py: registers `resume` in COMMANDS + usage.
- dashboard.py: capability-block approval status line now appends
  the `resume <identity>` hint so the operator can copy-paste the
  rebuild command without leaving the TUI.

Closes the rebuild loop in PRD 0016: agent calls capability-block →
operator approves → bottle torn down with state preserved → status
line shows resume command → operator runs it → replacement bottle
boots with the new Dockerfile and prior transcript.

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

claude_bottle/cli/__init__.py

@@ -1,6 +1,6 @@
 """Main CLI dispatcher.
 
-Commands: cleanup, dashboard, edit, info, init, list, start
+Commands: cleanup, dashboard, edit, info, init, list, resume, start
 """
 
 from __future__ import annotations
@@ -15,6 +15,7 @@ from .dashboard import cmd_dashboard
 from .edit import cmd_edit
 from .info import cmd_info
 from .init import cmd_init
+from .resume import cmd_resume
 from .start import cmd_start
 
 cmd_list = _list_mod.cmd_list
@@ -26,6 +27,7 @@ COMMANDS = {
     "info": cmd_info,
     "init": cmd_init,
     "list": cmd_list,
+    "resume": cmd_resume,
     "start": cmd_start,
 }
 
@@ -39,6 +41,7 @@ def usage() -> None:
     sys.stderr.write("  info      print env, skills, and prompt details for a named agent\n")
     sys.stderr.write("  init      interactively create a new agent and add it to claude-bottle.json\n")
     sys.stderr.write("  list      list available agents or active containers\n")
+    sys.stderr.write("  resume    re-launch a bottle by its identity (continues state from PRD 0016)\n")
     sys.stderr.write("  start     boot a container for a named agent and attach an interactive session\n\n")
     sys.stderr.write(f"Run '{PROG} <command> --help' for command-specific usage.\n")
 

claude_bottle/cli/dashboard.py

@@ -112,6 +112,16 @@ def discover_pipelock_slugs() -> list[str]:
     return _discover_sidecar_slugs("claude-bottle-pipelock-")
 
 
+def _approval_status(qp: QueuedProposal, verb: str) -> str:
+    """Status-line text after a successful approval. For capability-
+    block, append the `resume <identity>` hint so the operator can
+    bring the rebuilt bottle back up with one copy-paste."""
+    base = f"{verb} {qp.proposal.tool} for [{qp.proposal.bottle_slug}]"
+    if qp.proposal.tool == TOOL_CAPABILITY_BLOCK:
+        return f"{base}; resume: ./cli.py resume {qp.proposal.bottle_slug}"
+    return base
+
+
 def discover_pending() -> list[QueuedProposal]:
     """Walk ~/.claude-bottle/queue/* and collect pending proposals
     from every bottle's queue. Sorted by arrival time across the
@@ -371,7 +381,7 @@ def _main_loop(stdscr: "curses._CursesWindow") -> None:
         elif key == ord("a"):
             try:
                 approve(qp)
-                status_line = f"approved {qp.proposal.tool} for [{qp.proposal.bottle_slug}]"
+                status_line = _approval_status(qp, "approved")
             except ApplyError as e:
                 status_line = f"apply failed: {e}"
         elif key == ord("m"):
@@ -381,7 +391,7 @@ def _main_loop(stdscr: "curses._CursesWindow") -> None:
             else:
                 try:
                     approve(qp, final_file=edited, notes="operator modified before approving")
-                    status_line = f"modified+approved {qp.proposal.tool} for [{qp.proposal.bottle_slug}]"
+                    status_line = _approval_status(qp, "modified+approved")
                 except ApplyError as e:
                     status_line = f"apply failed: {e}"
         elif key == ord("r"):

claude_bottle/cli/resume.py

@@ -0,0 +1,66 @@
+"""resume: re-launch a bottle by its identity.
+
+Reads ~/.claude-bottle/state/<identity>/metadata.json to recover the
+(agent_name, cwd, copy_cwd) the bottle was originally started with,
+then runs the same launch core as `start` — but pinned to the
+recorded identity so the new bottle picks up any per-bottle Dockerfile
+(from capability-block apply) and transcript snapshot under the same
+state dir.
+
+Use case: an agent calls capability-block, the dashboard approves
+and tears down the bottle, the operator runs
+    ./cli.py resume <identity>
+to bring up the replacement with the new capabilities baked in.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ..backend import BottleSpec
+from ..backend.docker.bottle_state import read_metadata
+from ..log import die
+from ..manifest import Manifest
+from ._common import PROG, USER_CWD
+from .start import _launch_bottle
+
+
+def cmd_resume(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog=f"{PROG} resume", add_help=True)
+    parser.add_argument("--dry-run", action="store_true")
+    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(
+        "identity",
+        help="bottle identity from a prior `start` (see its session-end output)",
+    )
+    args = parser.parse_args(argv)
+
+    metadata = read_metadata(args.identity)
+    if metadata is None:
+        die(
+            f"no state recorded for identity {args.identity!r}; "
+            f"check ~/.claude-bottle/state/ or run `cli.py start` to create a new bottle"
+        )
+
+    manifest = Manifest.resolve(USER_CWD)
+    manifest.require_agent(metadata.agent_name)
+
+    spec = BottleSpec(
+        manifest=manifest,
+        agent_name=metadata.agent_name,
+        copy_cwd=metadata.copy_cwd,
+        user_cwd=metadata.cwd or USER_CWD,
+        identity=metadata.identity,
+    )
+    return _launch_bottle(
+        spec,
+        dry_run=args.dry_run,
+        output_format=args.format,
+        remote_control=args.remote_control,
+    )

claude_bottle/cli/start.py

@@ -1,6 +1,10 @@
 """start: boot a sandboxed container for a named agent and attach an
 interactive claude-code session. The container is torn down when the
-session ends."""
+session ends.
+
+The launch core is shared with `cli.py resume <identity>`: see
+_launch_bottle below.
+"""
 
 from __future__ import annotations
 
@@ -43,18 +47,35 @@ def cmd_start(argv: list[str]) -> int:
         copy_cwd=args.cwd,
         user_cwd=USER_CWD,
     )
+    return _launch_bottle(
+        spec,
+        dry_run=dry_run,
+        output_format=args.format,
+        remote_control=args.remote_control,
+    )
 
+
+def _launch_bottle(
+    spec: BottleSpec,
+    *,
+    dry_run: bool,
+    output_format: str,
+    remote_control: bool,
+) -> int:
+    """Shared launch core for `start` and `resume`. Builds the plan,
+    prints / dry-runs / prompts as appropriate, brings the bottle up,
+    attaches claude, and prints the resume hint on session end."""
     stage_dir = Path(tempfile.mkdtemp(prefix="claude-bottle-stage."))
     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)
+        if output_format == "json":
+            json.dump(plan.to_dict(remote_control=remote_control), sys.stdout, indent=2)
             sys.stdout.write("\n")
             return 0
 
-        plan.print(remote_control=args.remote_control)
+        plan.print(remote_control=remote_control)
 
         if dry_run:
             info("dry-run requested; not starting container.")
@@ -67,16 +88,27 @@ def cmd_start(argv: list[str]) -> int:
             info("aborted by user")
             return 0
 
+        identity = _identity_from_plan(plan)
         with backend.launch(plan) as bottle:
             info(
                 "attaching interactive claude session "
                 "(Ctrl-D or 'exit' to leave; container will be removed)"
             )
             claude_args = ["--dangerously-skip-permissions"]
-            if args.remote_control:
+            if remote_control:
                 claude_args.append("--remote-control")
             bottle.exec_claude(claude_args, tty=True)
             info(f"session ended; container {bottle.name} will be removed")
+            if identity:
+                info(f"to resume this bottle: ./cli.py resume {identity}")
             return 0
     finally:
         shutil.rmtree(stage_dir, ignore_errors=True)
+
+
+def _identity_from_plan(plan: object) -> str:
+    """Backend-specific: the docker plan exposes the identity as
+    `.slug`. Other backends in the future would expose their own
+    identity attribute; for now we duck-type to keep this layer
+    backend-agnostic."""
+    return getattr(plan, "slug", "")