bumblebee-cli 0.1.1 → 0.2.0

package/python/bb_cli/commands/agent.py

@@ -1,1030 +1,2287 @@
-import json
-import os
-import shutil
-import subprocess
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from pathlib import Path
-
-import typer
-from rich import print as rprint
-from rich.markdown import Markdown
-from rich.panel import Panel
-from rich.table import Table
-
-from ..api_client import api_get, api_post, api_put
-from ..config import CONFIG_DIR, get_api_url, get_current_project, get_project_path, get_token
-from .item import _resolve_item
-
-app = typer.Typer(help="Agent session management")
-
-WORKTREES_DIR = CONFIG_DIR / "worktrees"
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _require_project() -> str:
-    slug = get_current_project()
-    if not slug:
-        rprint("[red]No project selected. Run [bold]bb project switch <slug>[/bold] first.[/red]")
-        raise typer.Exit(1)
-    return slug
-
-
-def _require_project_path(slug: str) -> str:
-    path = get_project_path(slug)
-    if not path:
-        rprint("[red]No source code directory linked to this project.[/red]")
-        rprint("[yellow]Run [bold]bb project link <path>[/bold] to set it.[/yellow]")
-        raise typer.Exit(1)
-    if not Path(path).is_dir():
-        rprint(f"[red]Linked directory not found: {path}[/red]")
-        raise typer.Exit(1)
-    return path
-
-
-def _read_knowledge(project_path: str) -> str:
-    """Read knowledge base files from the project directory."""
-    candidates = [
-        "CLAUDE.md",
-        "docs/knowledge.md",
-        ".claude/lessons-learned.md",
-    ]
-    parts = []
-    for rel in candidates:
-        fp = Path(project_path) / rel
-        if fp.exists():
-            try:
-                text = fp.read_text(encoding="utf-8", errors="replace").strip()
-                if text:
-                    parts.append(f"### {rel}\n\n{text}")
-            except Exception:
-                pass
-    return "\n\n---\n\n".join(parts)
-
-
-def _get_item_comments(item_id: str) -> list[dict]:
-    try:
-        return api_get(f"/api/work-items/{item_id}/comments")
-    except Exception:
-        return []
-
-
-def _claude_env() -> dict[str, str]:
-    """Return env dict with CLAUDECODE unset so we can spawn a new Claude session."""
-    env = os.environ.copy()
-    env.pop("CLAUDECODE", None)
-    return env
-
-
-def _format_comments_context(comments: list[dict]) -> str:
-    if not comments:
-        return ""
-    parts = ["## Previous Comments / Progress"]
-    for c in comments:
-        author = c.get("author", "unknown")
-        ctype = c.get("type", "discussion")
-        tag = f" [{ctype}]" if ctype != "discussion" else ""
-        body = c.get("body", "")
-        created = c.get("created_at", "")
-        parts.append(f"\n### {author}{tag} -- {created}\n{body}")
-    return "\n".join(parts)
-
-
-# ---------------------------------------------------------------------------
-# Prompt builders
-# ---------------------------------------------------------------------------
-
-
-def _build_suggest_prompt(item: dict, knowledge: str, comments_ctx: str) -> str:
-    """Phase 1 prompt -- analyse only, no code changes."""
-    key = item.get("key") or f"#{item['number']}"
-    parts = [
-        f"You are analysing {item['type']} {key}: {item['title']}",
-        "",
-        f"Type: {item['type']}  |  Priority: {item['priority']}  |  Status: {item['status']}",
-    ]
-    if item.get("description"):
-        parts.extend(["", "## Description", item["description"]])
-    if item.get("acceptance_criteria"):
-        parts.extend(["", "## Acceptance Criteria", item["acceptance_criteria"]])
-    if item.get("plan"):
-        parts.extend(["", "## Existing Plan", item["plan"]])
-    if comments_ctx:
-        parts.extend(["", comments_ctx])
-    if knowledge:
-        parts.extend(["", "## Project Knowledge Base", knowledge])
-    parts.extend([
-        "",
-        "## Your Task",
-        "",
-        "Analyse this work item **and** the project source code. Return a Markdown plan:",
-        "",
-        "1. **Root Cause / Analysis** -- what needs to change and why",
-        "2. **Files to Modify** -- list every file with a short description of the change",
-        "3. **Implementation Steps** -- numbered, concrete steps",
-        "4. **Testing Strategy** -- how to verify the changes",
-        "5. **Risks & Considerations** -- edge cases, breaking changes",
-        "",
-        "IMPORTANT: Do NOT modify any files. Only analyse and produce the plan.",
-    ])
-    return "\n".join(parts)
-
-
-def _build_execute_prompt(item: dict, knowledge: str, comments_ctx: str) -> str:
-    """Phase 2 prompt -- implement the changes."""
-    key = item.get("key") or f"#{item['number']}"
-    parts = [
-        f"You are implementing {item['type']} {key}: {item['title']}",
-        "",
-        f"Type: {item['type']}  |  Priority: {item['priority']}",
-    ]
-    if item.get("description"):
-        parts.extend(["", "## Description", item["description"]])
-    if item.get("acceptance_criteria"):
-        parts.extend(["", "## Acceptance Criteria", item["acceptance_criteria"]])
-    if item.get("plan"):
-        parts.extend(["", "## Implementation Plan", item["plan"]])
-    if comments_ctx:
-        parts.extend(["", comments_ctx])
-    if knowledge:
-        parts.extend(["", "## Project Knowledge Base", knowledge])
-    parts.extend([
-        "",
-        "## Instructions",
-        "",
-        "Implement the changes described in the plan / comments above.",
-        "",
-        "1. Follow the project's existing coding conventions and patterns",
-        "2. Work through changes one file at a time",
-        "3. Run existing tests after your changes and fix any failures",
-        "4. Add new tests where appropriate",
-        "5. Commit your work with a clear, descriptive commit message",
-        "6. If you hit a blocker, document it clearly so the next run can continue",
-    ])
-    return "\n".join(parts)
-
-
-# ---------------------------------------------------------------------------
-# Git worktree utilities
-# ---------------------------------------------------------------------------
-
-
-def _worktree_path(slug: str, item_number: int) -> Path:
-    return WORKTREES_DIR / slug / f"item-{item_number}"
-
-
-def _create_worktree(project_path: str, slug: str, item_number: int) -> tuple[str, str]:
-    """Create (or reuse) a git worktree. Returns (worktree_path, branch_name)."""
-    branch = f"bb/item-{item_number}"
-    wt = _worktree_path(slug, item_number)
-    wt.parent.mkdir(parents=True, exist_ok=True)
-
-    # Already exists and valid?
-    if wt.exists():
-        probe = subprocess.run(
-            ["git", "worktree", "list", "--porcelain"],
-            cwd=project_path, capture_output=True, text=True,
-        )
-        # Normalise to forward-slash for reliable comparison
-        wt_norm = str(wt).replace("\\", "/")
-        if any(wt_norm in ln.replace("\\", "/") for ln in probe.stdout.splitlines()):
-            return str(wt), branch
-        # Stale -- clean up
-        subprocess.run(["git", "worktree", "prune"], cwd=project_path, capture_output=True)
-        if wt.exists():
-            shutil.rmtree(wt)
-
-    # Does branch already exist?
-    check = subprocess.run(
-        ["git", "rev-parse", "--verify", branch],
-        cwd=project_path, capture_output=True, text=True,
-    )
-
-    if check.returncode == 0:
-        subprocess.run(
-            ["git", "worktree", "add", str(wt), branch],
-            cwd=project_path, check=True, capture_output=True, text=True,
-        )
-    else:
-        subprocess.run(
-            ["git", "worktree", "add", "-b", branch, str(wt)],
-            cwd=project_path, check=True, capture_output=True, text=True,
-        )
-
-    return str(wt), branch
-
-
-def _remove_worktree(project_path: str, wt_path: str):
-    subprocess.run(
-        ["git", "worktree", "remove", "--force", wt_path],
-        cwd=project_path, capture_output=True,
-    )
-    subprocess.run(["git", "worktree", "prune"], cwd=project_path, capture_output=True)
-
-
-# ---------------------------------------------------------------------------
-# Batch internal helpers (thread-safe, no rich print inside workers)
-# ---------------------------------------------------------------------------
-
-
-def _suggest_one(slug: str, project_path: str, id_or_number: str) -> dict:
-    """Run suggest for a single item. Thread-safe — returns result dict."""
-    try:
-        item = _resolve_item(slug, id_or_number)
-    except Exception as e:
-        return {"key": id_or_number, "status": "failed", "error": f"Resolve failed: {e}"}
-
-    item_id = item["id"]
-    key = item.get("key") or f"#{item['number']}"
-
-    knowledge = _read_knowledge(project_path)
-    comments = _get_item_comments(item_id)
-    comments_ctx = _format_comments_context(comments)
-    prompt = _build_suggest_prompt(item, knowledge, comments_ctx)
-
-    try:
-        result = subprocess.run(
-            ["claude", "-p", prompt, "--output-format", "text"],
-            cwd=project_path,
-            capture_output=True,
-            text=True,
-            timeout=600,
-            env=_claude_env(),
-        )
-    except FileNotFoundError:
-        return {"key": key, "status": "failed", "error": "'claude' CLI not found"}
-    except subprocess.TimeoutExpired:
-        return {"key": key, "status": "failed", "error": "Timed out (10 min)"}
-
-    if result.returncode != 0:
-        return {"key": key, "status": "failed", "error": result.stderr[:200]}
-
-    suggestion = result.stdout.strip()
-    if not suggestion:
-        return {"key": key, "status": "failed", "error": "Empty response"}
-
-    # Post comment
-    api_post(f"/api/work-items/{item_id}/comments", json={
-        "body": suggestion,
-        "author": "bb-agent",
-        "type": "proposal",
-    })
-
-    # Advance status
-    if item["status"] == "open":
-        api_put(f"/api/work-items/{item_id}", json={"status": "confirmed"})
-
-    return {"key": key, "status": "ok", "suggestion": suggestion[:200]}
-
-
-def _execute_one(slug: str, project_path: str, id_or_number: str) -> dict:
-    """Run execute for a single item in its own worktree. Thread-safe."""
-    try:
-        item = _resolve_item(slug, id_or_number)
-    except Exception as e:
-        return {"key": id_or_number, "status": "failed", "error": f"Resolve failed: {e}"}
-
-    item_id = item["id"]
-    item_number = item["number"]
-    key = item.get("key") or f"#{item_number}"
-    knowledge = _read_knowledge(project_path)
-    comments = _get_item_comments(item_id)
-    comments_ctx = _format_comments_context(comments)
-    prompt = _build_execute_prompt(item, knowledge, comments_ctx)
-
-    # Create worktree
-    try:
-        work_dir, branch_name = _create_worktree(project_path, slug, item_number)
-    except subprocess.CalledProcessError as e:
-        return {"key": key, "status": "failed", "error": f"Worktree failed: {e.stderr or e}"}
-
-    # Agent session
-    try:
-        session = api_post(
-            "/api/agent-sessions/start",
-            json={"work_item_id": item_id, "origin": "cli"},
-            params={"project_slug": slug},
-        )
-        session_id = session["id"]
-    except Exception as e:
-        return {"key": key, "status": "failed", "error": f"Session start failed: {e}", "branch": branch_name}
-
-    # Status -> in_progress
-    if item["status"] in ("open", "confirmed", "approved"):
-        api_put(f"/api/work-items/{item_id}", json={"status": "in_progress"})
-
-    # MCP config
-    api_url = get_api_url()
-    token = get_token()
-    mcp_cfg = json.dumps({
-        "mcpServers": {
-            "bumblebee": {
-                "url": f"{api_url}/mcp",
-                "headers": {"Authorization": f"Bearer {token}"} if token else {},
-            }
-        }
-    })
-
-    try:
-        proc = subprocess.Popen(
-            [
-                "claude",
-                "--output-format", "stream-json",
-                "--verbose",
-                "--permission-mode", "bypassPermissions",
-                "--mcp-config", "-",
-                "-p", prompt,
-            ],
-            cwd=work_dir,
-            stdin=subprocess.PIPE,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=True,
-            env=_claude_env(),
-        )
-
-        proc.stdin.write(mcp_cfg)
-        proc.stdin.close()
-
-        text_blocks: list[str] = []
-        for line in proc.stdout:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                payload = json.loads(line)
-                if payload.get("type") == "assistant":
-                    for block in payload.get("content", []):
-                        if block.get("type") == "text":
-                            text_blocks.append(block["text"])
-                try:
-                    api_post(f"/api/agent-sessions/{session_id}/relay", json=payload)
-                except Exception:
-                    pass
-            except json.JSONDecodeError:
-                pass
-
-        proc.wait()
-
-        # Post completion comment
-        tail = "\n\n".join(text_blocks[-3:]) if text_blocks else "No text output captured."
-        body_lines = [
-            "## Agent Execution Report\n",
-            f"**Branch**: `{branch_name}`\n",
-            f"**Exit code**: `{proc.returncode}`\n",
-            f"\n### Output (last messages)\n\n{tail}",
-        ]
-        api_post(f"/api/work-items/{item_id}/comments", json={
-            "body": "\n".join(body_lines),
-            "author": "bb-agent",
-            "type": "agent_output",
-        })
-
-        if proc.returncode == 0:
-            api_put(f"/api/work-items/{item_id}", json={"status": "in_review"})
-            return {"key": key, "status": "ok", "branch": branch_name, "worktree": work_dir}
-        else:
-            return {"key": key, "status": "failed", "error": f"Exit code {proc.returncode}", "branch": branch_name}
-
-    except FileNotFoundError:
-        return {"key": key, "status": "failed", "error": "'claude' CLI not found"}
-
-
-# ---------------------------------------------------------------------------
-# Commands
-# ---------------------------------------------------------------------------
-
-
-@app.command()
-def suggest(
-    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to analyse"),
-):
-    """Phase 1: Analyse a work item and post a solution plan as a comment."""
-    slug = _require_project()
-    project_path = _require_project_path(slug)
-
-    rprint(f"[cyan]Fetching work item {id_or_number}...[/cyan]")
-    item = _resolve_item(slug, id_or_number)
-    item_id = item["id"]
-    knowledge = _read_knowledge(project_path)
-    comments = _get_item_comments(item_id)
-    comments_ctx = _format_comments_context(comments)
-    prompt = _build_suggest_prompt(item, knowledge, comments_ctx)
-
-    rprint(f"[cyan]Running Claude Code analysis in {project_path}...[/cyan]")
-
-    try:
-        result = subprocess.run(
-            ["claude", "-p", prompt, "--output-format", "text"],
-            cwd=project_path,
-            capture_output=True,
-            text=True,
-            timeout=600,
-            env=_claude_env(),
-        )
-
-        if result.returncode != 0:
-            rprint(f"[red]Claude analysis failed:[/red]\n{result.stderr}")
-            raise typer.Exit(1)
-
-        suggestion = result.stdout.strip()
-        if not suggestion:
-            rprint("[red]Claude returned an empty response.[/red]")
-            raise typer.Exit(1)
-
-        rprint()
-        key = item.get("key") or f"#{item['number']}"
-        rprint(Panel(
-            Markdown(suggestion),
-            title=f"Suggested Solution -- {key}",
-            border_style="green",
-        ))
-
-        # Post as agent comment
-        api_post(f"/api/work-items/{item_id}/comments", json={
-            "body": suggestion,
-            "author": "bb-agent",
-            "type": "proposal",
-        })
-        rprint("[green]Suggestion posted as comment on the work item.[/green]")
-
-        # Advance status open -> confirmed
-        if item["status"] == "open":
-            api_put(f"/api/work-items/{item_id}", json={"status": "confirmed"})
-            rprint("[dim]Status -> confirmed[/dim]")
-
-    except FileNotFoundError:
-        rprint("[red]'claude' CLI not found. Install Claude Code first.[/red]")
-        raise typer.Exit(1)
-    except subprocess.TimeoutExpired:
-        rprint("[red]Analysis timed out (10 min limit).[/red]")
-        raise typer.Exit(1)
-
-
-@app.command()
-def execute(
-    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to implement"),
-    no_worktree: bool = typer.Option(False, "--no-worktree", help="Work in main directory (skip worktree)"),
-    cleanup: bool = typer.Option(False, "--cleanup", help="Remove worktree after completion"),
-):
-    """Phase 2: Create a worktree and implement the work item with Claude Code."""
-    slug = _require_project()
-    project_path = _require_project_path(slug)
-
-    # Context
-    item = _resolve_item(slug, id_or_number)
-    item_id = item["id"]
-    item_number = item["number"]
-    knowledge = _read_knowledge(project_path)
-    comments = _get_item_comments(item_id)
-    comments_ctx = _format_comments_context(comments)
-    prompt = _build_execute_prompt(item, knowledge, comments_ctx)
-
-    # Worktree
-    work_dir = project_path
-    branch_name = None
-
-    if not no_worktree:
-        try:
-            key = item.get("key") or f"#{item_number}"
-            rprint(f"[cyan]Creating worktree for {key}...[/cyan]")
-            work_dir, branch_name = _create_worktree(project_path, slug, item_number)
-            rprint(f"[green]Worktree: {work_dir}[/green]")
-            rprint(f"[green]Branch:   {branch_name}[/green]")
-        except subprocess.CalledProcessError as e:
-            rprint(f"[red]Worktree failed: {e.stderr or e}[/red]")
-            rprint("[yellow]Falling back to main directory.[/yellow]")
-
-    # Agent session
-    session = api_post(
-        "/api/agent-sessions/start",
-        json={"work_item_id": item_id, "origin": "cli"},
-        params={"project_slug": slug},
-    )
-    session_id = session["id"]
-    rprint(f"[green]Session:  {session_id}[/green]")
-
-    # Status -> in_progress
-    if item["status"] in ("open", "confirmed", "approved"):
-        api_put(f"/api/work-items/{item_id}", json={"status": "in_progress"})
-        rprint("[dim]Status -> in_progress[/dim]")
-
-    # MCP config (Bumblebee tools for Claude)
-    api_url = get_api_url()
-    token = get_token()
-    mcp_cfg = json.dumps({
-        "mcpServers": {
-            "bumblebee": {
-                "url": f"{api_url}/mcp",
-                "headers": {"Authorization": f"Bearer {token}"} if token else {},
-            }
-        }
-    })
-
-    rprint(f"\n[cyan]Spawning Claude Code agent in {work_dir}...[/cyan]\n")
-
-    try:
-        proc = subprocess.Popen(
-            [
-                "claude",
-                "--output-format", "stream-json",
-                "--verbose",
-                "--permission-mode", "bypassPermissions",
-                "--mcp-config", "-",
-                "-p", prompt,
-            ],
-            cwd=work_dir,
-            stdin=subprocess.PIPE,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=True,
-            env=_claude_env(),
-        )
-
-        proc.stdin.write(mcp_cfg)
-        proc.stdin.close()
-
-        # Stream output -> terminal + API relay
-        text_blocks: list[str] = []
-        for line in proc.stdout:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                payload = json.loads(line)
-                if payload.get("type") == "assistant":
-                    for block in payload.get("content", []):
-                        if block.get("type") == "text":
-                            rprint(block["text"])
-                            text_blocks.append(block["text"])
-                try:
-                    api_post(f"/api/agent-sessions/{session_id}/relay", json=payload)
-                except Exception:
-                    pass
-            except json.JSONDecodeError:
-                rprint(f"[dim]{line}[/dim]")
-
-        proc.wait()
-
-        # Completion comment
-        tail = "\n\n".join(text_blocks[-3:]) if text_blocks else "No text output captured."
-        body_lines = ["## Agent Execution Report\n"]
-        if branch_name:
-            body_lines.append(f"**Branch**: `{branch_name}`\n")
-        body_lines.append(f"**Exit code**: `{proc.returncode}`\n")
-        body_lines.append(f"\n### Output (last messages)\n\n{tail}")
-
-        api_post(f"/api/work-items/{item_id}/comments", json={
-            "body": "\n".join(body_lines),
-            "author": "bb-agent",
-            "type": "agent_output",
-        })
-
-        if proc.returncode == 0:
-            rprint("\n[green]Agent completed successfully.[/green]")
-            api_put(f"/api/work-items/{item_id}", json={"status": "in_review"})
-            rprint("[dim]Status -> in_review[/dim]")
-        else:
-            rprint(f"\n[yellow]Agent exited with code {proc.returncode}.[/yellow]")
-
-        # Worktree post-run
-        if branch_name and work_dir != project_path:
-            if cleanup:
-                _remove_worktree(project_path, work_dir)
-                rprint("[dim]Worktree removed.[/dim]")
-            else:
-                rprint(f"\n[dim]Worktree: {work_dir}[/dim]")
-                rprint(f"[dim]Merge:    cd {project_path} && git merge {branch_name}[/dim]")
-                rprint(f"[dim]Cleanup:  bb agent cleanup {item_number}[/dim]")
-
-    except FileNotFoundError:
-        rprint("[red]'claude' CLI not found. Install Claude Code first.[/red]")
-        raise typer.Exit(1)
-    except KeyboardInterrupt:
-        rprint("\n[yellow]Agent interrupted.[/yellow]")
-        api_post(f"/api/agent-sessions/{session_id}/abort")
-        api_post(f"/api/work-items/{item_id}/comments", json={
-            "body": "## Agent Interrupted\n\nManually stopped by user.",
-            "author": "bb-agent",
-            "type": "agent_output",
-        })
-
-
-@app.command()
-def run(
-    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number"),
-    skip_suggest: bool = typer.Option(False, "--skip-suggest", help="Skip the analysis phase"),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Auto-confirm the suggestion"),
-    no_worktree: bool = typer.Option(False, "--no-worktree", help="Skip worktree creation"),
-):
-    """Full loop: analyse -> confirm -> implement."""
-    _require_project()
-
-    if not skip_suggest:
-        suggest(id_or_number)
-        if not yes:
-            rprint()
-            if not typer.confirm("Proceed with implementation?"):
-                rprint(f"[yellow]Aborted. Run [bold]bb agent execute {id_or_number}[/bold] when ready.[/yellow]")
-                raise typer.Exit()
-
-    execute(id_or_number, no_worktree=no_worktree, cleanup=False)
-
-
-@app.command(name="continue")
-def continue_work(
-    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to continue"),
-):
-    """Continue a previous agent run (reads prior comments for context)."""
-    execute(id_or_number, no_worktree=False, cleanup=False)
-
-
-@app.command(name="status")
-def agent_status():
-    """Show agent sessions for the current project."""
-    slug = _require_project()
-    sessions = api_get("/api/agent-sessions", params={"project_slug": slug})
-    if not sessions:
-        rprint("[dim]No agent sessions.[/dim]")
-        return
-    for s in sessions:
-        color = {"running": "yellow", "completed": "green", "failed": "red"}.get(
-            s["status"], "white"
-        )
-        rprint(
-            f"  [{color}]{s['status']:>10}[/{color}]  "
-            f"{s['id'][:8]}  item: {s.get('work_item_id', '--')}"
-        )
-
-
-@app.command()
-def abort(session_id: str = typer.Argument(...)):
-    """Abort a running agent session."""
-    api_post(f"/api/agent-sessions/{session_id}/abort")
-    rprint(f"[yellow]Session {session_id[:8]} aborted.[/yellow]")
-
-
-@app.command(name="cleanup")
-def cleanup_worktree(
-    item_number: int = typer.Argument(..., help="Work item number whose worktree to remove"),
-    delete_branch: bool = typer.Option(False, "--delete-branch", "-D", help="Also delete the git branch"),
-):
-    """Remove the worktree created for a work item."""
-    slug = _require_project()
-    project_path = _require_project_path(slug)
-
-    wt = _worktree_path(slug, item_number)
-    branch = f"bb/item-{item_number}"
-
-    if not wt.exists():
-        rprint(f"[yellow]No worktree found for item #{item_number}.[/yellow]")
-        raise typer.Exit()
-
-    _remove_worktree(project_path, str(wt))
-    rprint(f"[green]Worktree removed: {wt}[/green]")
-
-    if delete_branch:
-        subprocess.run(
-            ["git", "branch", "-D", branch],
-            cwd=project_path, capture_output=True,
-        )
-        rprint(f"[green]Branch deleted: {branch}[/green]")
-    else:
-        rprint(f"[dim]Branch '{branch}' kept. Delete with: git branch -D {branch}[/dim]")
-
-
-@app.command(name="worktrees")
-def list_worktrees():
-    """List active agent worktrees for the current project."""
-    slug = _require_project()
-    project_path = _require_project_path(slug)
-
-    result = subprocess.run(
-        ["git", "worktree", "list"],
-        cwd=project_path, capture_output=True, text=True,
-    )
-    if result.returncode != 0:
-        rprint("[red]Failed to list worktrees.[/red]")
-        raise typer.Exit(1)
-
-    lines = result.stdout.strip().splitlines()
-    bb_lines = [ln for ln in lines if "bb/item-" in ln]
-
-    if not bb_lines:
-        rprint("[dim]No agent worktrees.[/dim]")
-        return
-
-    rprint("[bold]Agent worktrees:[/bold]")
-    for ln in bb_lines:
-        rprint(f"  {ln}")
-
-
-# ---------------------------------------------------------------------------
-# Batch (parallel) commands
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="batch-suggest")
-def batch_suggest(
-    items: list[str] = typer.Argument(..., help="Work item IDs/numbers to analyse (e.g. BD-2 BD-3 BD-4)"),
-    max_parallel: int = typer.Option(3, "--parallel", "-P", help="Max parallel Claude analyses"),
-):
-    """Analyse multiple work items in parallel. Each gets a proposal comment."""
-    slug = _require_project()
-    project_path = _require_project_path(slug)
-
-    rprint(f"[cyan]Suggesting {len(items)} items (max {max_parallel} parallel)...[/cyan]\n")
-
-    results: list[dict] = []
-    with ThreadPoolExecutor(max_workers=max_parallel) as pool:
-        futures = {
-            pool.submit(_suggest_one, slug, project_path, item): item
-            for item in items
-        }
-        for future in as_completed(futures):
-            item_ref = futures[future]
-            try:
-                r = future.result()
-                results.append(r)
-                color = "green" if r["status"] == "ok" else "red"
-                rprint(f"  [{color}]{r['key']:>8} -- {r['status']}[/{color}]"
-                       + (f" ({r.get('error', '')})" if r["status"] != "ok" else ""))
-            except Exception as e:
-                results.append({"key": item_ref, "status": "error", "error": str(e)})
-                rprint(f"  [red]{item_ref:>8} -- error: {e}[/red]")
-
-    ok = sum(1 for r in results if r["status"] == "ok")
-    rprint(f"\n[bold]Done: {ok}/{len(items)} succeeded.[/bold]")
-
-    if ok > 0:
-        rprint("\n[dim]Review suggestions, then run:[/dim]")
-        suggested = [r["key"] for r in results if r["status"] == "ok"]
-        rprint(f"[dim]  bb agent batch-execute {' '.join(suggested)}[/dim]")
-
-
-@app.command(name="batch-execute")
-def batch_execute(
-    items: list[str] = typer.Argument(..., help="Work item IDs/numbers to implement (e.g. BD-2 BD-3 BD-4)"),
-    max_parallel: int = typer.Option(2, "--parallel", "-P", help="Max parallel Claude agents"),
-):
-    """Implement multiple work items in parallel. Each gets its own git worktree."""
-    slug = _require_project()
-    project_path = _require_project_path(slug)
-
-    rprint(f"[cyan]Executing {len(items)} items (max {max_parallel} parallel, each in own worktree)...[/cyan]\n")
-
-    results: list[dict] = []
-    with ThreadPoolExecutor(max_workers=max_parallel) as pool:
-        futures = {
-            pool.submit(_execute_one, slug, project_path, item): item
-            for item in items
-        }
-        for future in as_completed(futures):
-            item_ref = futures[future]
-            try:
-                r = future.result()
-                results.append(r)
-                if r["status"] == "ok":
-                    rprint(f"  [green]{r['key']:>8} -- ok  branch: {r.get('branch', '?')}[/green]")
-                else:
-                    rprint(f"  [red]{r['key']:>8} -- {r.get('error', 'unknown error')}[/red]")
-            except Exception as e:
-                results.append({"key": item_ref, "status": "error", "error": str(e)})
-                rprint(f"  [red]{item_ref:>8} -- error: {e}[/red]")
-
-    ok = sum(1 for r in results if r["status"] == "ok")
-    rprint(f"\n[bold]Done: {ok}/{len(items)} succeeded.[/bold]")
-
-    branches = [r["branch"] for r in results if r.get("branch")]
-    if branches:
-        table = Table(title="Branches Created", show_header=True)
-        table.add_column("Item")
-        table.add_column("Branch")
-        table.add_column("Status")
-        for r in results:
-            if r.get("branch"):
-                color = "green" if r["status"] == "ok" else "red"
-                table.add_row(r["key"], r["branch"], f"[{color}]{r['status']}[/{color}]")
-        rprint(table)
-        rprint(f"\n[dim]Merge all with: bb agent merge --target release/dev[/dim]")
-
-
-@app.command(name="batch-run")
-def batch_run(
-    items: list[str] = typer.Argument(..., help="Work item IDs/numbers for full loop"),
-    max_parallel: int = typer.Option(2, "--parallel", "-P", help="Max parallel agents"),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Auto-confirm after suggest phase"),
-):
-    """Full loop for multiple items: suggest all -> review -> execute all."""
-    slug = _require_project()
-    project_path = _require_project_path(slug)
-
-    # Phase 1: parallel suggest
-    rprint("[bold cyan]Phase 1: Analysing...[/bold cyan]\n")
-    suggest_results: list[dict] = []
-    with ThreadPoolExecutor(max_workers=max_parallel) as pool:
-        futures = {
-            pool.submit(_suggest_one, slug, project_path, item): item
-            for item in items
-        }
-        for future in as_completed(futures):
-            item_ref = futures[future]
-            try:
-                r = future.result()
-                suggest_results.append(r)
-                color = "green" if r["status"] == "ok" else "red"
-                rprint(f"  [{color}]{r['key']:>8} -- {r['status']}[/{color}]")
-            except Exception as e:
-                suggest_results.append({"key": item_ref, "status": "error"})
-                rprint(f"  [red]{item_ref:>8} -- error: {e}[/red]")
-
-    succeeded = [r["key"] for r in suggest_results if r["status"] == "ok"]
-    if not succeeded:
-        rprint("\n[red]No items analysed successfully. Aborting.[/red]")
-        raise typer.Exit(1)
-
-    rprint(f"\n[bold]Suggest done: {len(succeeded)}/{len(items)} ready.[/bold]")
-
-    # Confirmation gate
-    if not yes:
-        rprint("\n[yellow]Review the suggestions in the web UI or via 'bb comment list <item>'.[/yellow]")
-        if not typer.confirm(f"Proceed to execute {len(succeeded)} items?"):
-            rprint("[yellow]Aborted. Run 'bb agent batch-execute' when ready.[/yellow]")
-            raise typer.Exit()
-
-    # Phase 2: parallel execute
-    rprint("\n[bold cyan]Phase 2: Implementing...[/bold cyan]\n")
-    exec_results: list[dict] = []
-    with ThreadPoolExecutor(max_workers=max_parallel) as pool:
-        futures = {
-            pool.submit(_execute_one, slug, project_path, item): item
-            for item in succeeded
-        }
-        for future in as_completed(futures):
-            item_ref = futures[future]
-            try:
-                r = future.result()
-                exec_results.append(r)
-                if r["status"] == "ok":
-                    rprint(f"  [green]{r['key']:>8} -- ok  branch: {r.get('branch', '?')}[/green]")
-                else:
-                    rprint(f"  [red]{r['key']:>8} -- {r.get('error', '?')}[/red]")
-            except Exception as e:
-                rprint(f"  [red]{item_ref:>8} -- error: {e}[/red]")
-
-    ok = sum(1 for r in exec_results if r["status"] == "ok")
-    rprint(f"\n[bold]Execute done: {ok}/{len(succeeded)} succeeded.[/bold]")
-    if ok > 0:
-        rprint("[dim]Merge with: bb agent merge --target release/dev[/dim]")
-
-
-# ---------------------------------------------------------------------------
-# Merge command
-# ---------------------------------------------------------------------------
-
-
-@app.command(name="merge")
-def merge_branches(
-    target: str = typer.Option("release/dev", "--target", "-t", help="Target branch to merge into"),
-    items: list[str] = typer.Argument(None, help="Specific item numbers (default: all bb/item-* branches)"),
-    cleanup_after: bool = typer.Option(False, "--cleanup", help="Remove worktrees + branches after successful merge"),
-    use_agent: bool = typer.Option(False, "--agent", help="Use Claude to resolve merge conflicts"),
-):
-    """Merge agent branches into a target branch (e.g. release/dev)."""
-    slug = _require_project()
-    project_path = _require_project_path(slug)
-
-    # Remember current branch
-    current = subprocess.run(
-        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-        cwd=project_path, capture_output=True, text=True,
-    ).stdout.strip()
-
-    # List all bb/item-* branches
-    result = subprocess.run(
-        ["git", "branch", "--list", "bb/item-*"],
-        cwd=project_path, capture_output=True, text=True,
-    )
-    all_branches = [b.strip().lstrip("* ") for b in result.stdout.strip().splitlines() if b.strip()]
-
-    if items:
-        wanted = {f"bb/item-{n}" for n in items}
-        branches = [b for b in all_branches if b in wanted]
-    else:
-        branches = all_branches
-
-    if not branches:
-        rprint("[yellow]No agent branches found to merge.[/yellow]")
-        return
-
-    rprint(f"[cyan]Merging {len(branches)} branches into {target}...[/cyan]\n")
-    for b in branches:
-        rprint(f"  {b}")
-    rprint()
-
-    # Ensure target branch exists
-    check = subprocess.run(
-        ["git", "rev-parse", "--verify", target],
-        cwd=project_path, capture_output=True, text=True,
-    )
-    if check.returncode != 0:
-        rprint(f"[yellow]Branch '{target}' does not exist. Creating from HEAD...[/yellow]")
-        subprocess.run(
-            ["git", "branch", target],
-            cwd=project_path, check=True, capture_output=True,
-        )
-
-    # Prune stale worktrees
-    subprocess.run(["git", "worktree", "prune"], cwd=project_path, capture_output=True)
-
-    # Checkout target branch
-    co = subprocess.run(
-        ["git", "checkout", target],
-        cwd=project_path, capture_output=True, text=True,
-    )
-    if co.returncode != 0:
-        rprint(f"[red]Failed to checkout {target}: {co.stderr}[/red]")
-        return
-
-    merged: list[str] = []
-    failed: list[tuple[str, str]] = []
-
-    for branch in branches:
-        rprint(f"  Merging {branch}...", end=" ")
-        merge_result = subprocess.run(
-            ["git", "merge", branch, "--no-ff", "-m", f"Merge {branch} into {target}"],
-            cwd=project_path, capture_output=True, text=True,
-        )
-        if merge_result.returncode == 0:
-            rprint("[green]ok[/green]")
-            merged.append(branch)
-        else:
-            if use_agent:
-                rprint("[yellow]conflict -> resolving with Claude...[/yellow]")
-                resolve = subprocess.run(
-                    ["claude", "-p",
-                     f"Resolve all merge conflicts in this git repo. The merge of '{branch}' into '{target}' has conflicts. "
-                     f"Use 'git diff' to find conflicts, resolve them keeping both sets of changes where possible, "
-                     f"then stage and commit. Do NOT abort the merge.",
-                     "--output-format", "text",
-                     "--permission-mode", "bypassPermissions"],
-                    cwd=project_path, capture_output=True, text=True,
-                    timeout=300, env=_claude_env(),
-                )
-                # Check if conflicts are resolved
-                status_check = subprocess.run(
-                    ["git", "diff", "--name-only", "--diff-filter=U"],
-                    cwd=project_path, capture_output=True, text=True,
-                )
-                if status_check.stdout.strip() == "":
-                    rprint(f"    [green]Conflict resolved by agent[/green]")
-                    merged.append(branch)
-                else:
-                    rprint(f"    [red]Agent could not resolve all conflicts[/red]")
-                    subprocess.run(["git", "merge", "--abort"], cwd=project_path, capture_output=True)
-                    failed.append((branch, "conflict (agent failed)"))
-            else:
-                rprint("[red]CONFLICT[/red]")
-                subprocess.run(["git", "merge", "--abort"], cwd=project_path, capture_output=True)
-                failed.append((branch, "conflict"))
-
-    # Summary
-    rprint()
-    table = Table(title=f"Merge Results -> {target}", show_header=True)
-    table.add_column("Branch")
-    table.add_column("Status")
-    for b in merged:
-        table.add_row(b, "[green]merged[/green]")
-    for b, reason in failed:
-        table.add_row(b, f"[red]{reason}[/red]")
-    rprint(table)
-
-    # Cleanup if requested
-    if cleanup_after and merged:
-        for branch in merged:
-            num_str = branch.replace("bb/item-", "")
-            try:
-                wt = _worktree_path(slug, int(num_str))
-                if wt.exists():
-                    _remove_worktree(project_path, str(wt))
-                subprocess.run(
-                    ["git", "branch", "-D", branch],
-                    cwd=project_path, capture_output=True,
-                )
-            except (ValueError, Exception):
-                pass
-        rprint("[dim]Cleaned up merged worktrees and branches.[/dim]")
-
-    if failed:
-        rprint("\n[yellow]Failed branches can be retried:[/yellow]")
-        rprint("[dim]  bb agent merge --agent  (use Claude to resolve conflicts)[/dim]")
-        rprint("[dim]  or resolve manually: git checkout {target} && git merge {branch}[/dim]")
-
-    # Return to original branch
-    subprocess.run(
-        ["git", "checkout", current],
-        cwd=project_path, capture_output=True,
-    )
+import json
+import os
+import re
+import shutil
+import subprocess
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+import typer
+from rich import print as rprint
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+
+from ..api_client import api_get, api_post, api_put
+from ..config import CONFIG_DIR, get_api_url, get_current_project, get_project_path, get_token
+from ..progress import AgentProgressTracker
+from ..streaming import AgentStreamer, complete_session, update_phase
+from .item import _resolve_item
+
+from . import daemon as _daemon_module
+
+app = typer.Typer(help="Agent session management")
+app.add_typer(_daemon_module.app, name="daemon")
+
+WORKTREES_DIR = CONFIG_DIR / "worktrees"
+
+# Maps work item type to git branch prefix.
+TYPE_BRANCH_PREFIX: dict[str, str] = {
+    "epic": "epic",
+    "story": "feat",
+    "task": "task",
+    "bug": "fix",
+    "feature": "feat",
+    "chore": "chore",
+    "spike": "spike",
+}
+
+
+def _slugify(text: str, max_len: int = 48) -> str:
+    """Turn a title into a branch-safe slug: lowercase, hyphens, no specials."""
+    slug = text.lower().strip()
+    slug = re.sub(r"[^a-z0-9]+", "-", slug)  # replace non-alnum with hyphen
+    slug = slug.strip("-")
+    if len(slug) > max_len:
+        slug = slug[:max_len].rsplit("-", 1)[0]  # cut at last hyphen
+    return slug
+
+
+def _build_branch_name(item: dict) -> str:
+    """Build a descriptive branch name from a work item.
+
+    Format: {type_prefix}/{key}_{slugified_title}
+    Example: feat/bb-42_authentication-by-google
+    """
+    prefix = TYPE_BRANCH_PREFIX.get(item["type"], "task")
+    key = (item.get("key") or f"item-{item['number']}").lower()
+    title_slug = _slugify(item["title"])
+    return f"{prefix}/{key}_{title_slug}"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _require_project() -> str:
+    slug = get_current_project()
+    if not slug:
+        rprint("[red]No project selected. Run [bold]bb project switch <slug>[/bold] first.[/red]")
+        raise typer.Exit(1)
+    return slug
+
+
+def _require_project_path(slug: str) -> str:
+    path = get_project_path(slug)
+    if not path:
+        rprint("[red]No source code directory linked to this project.[/red]")
+        rprint("[yellow]Run [bold]bb project link <path>[/bold] to set it.[/yellow]")
+        raise typer.Exit(1)
+    if not Path(path).is_dir():
+        rprint(f"[red]Linked directory not found: {path}[/red]")
+        raise typer.Exit(1)
+    return path
+
+
+def _read_knowledge(project_path: str) -> str:
+    """Read knowledge base files from the project directory."""
+    candidates = [
+        "CLAUDE.md",
+        "docs/knowledge.md",
+        ".claude/lessons-learned.md",
+    ]
+    parts = []
+    for rel in candidates:
+        fp = Path(project_path) / rel
+        if fp.exists():
+            try:
+                text = fp.read_text(encoding="utf-8", errors="replace").strip()
+                if text:
+                    parts.append(f"### {rel}\n\n{text}")
+            except Exception:
+                pass
+    return "\n\n---\n\n".join(parts)
+
+
+def _get_item_comments(item_id: str) -> list[dict]:
+    try:
+        return api_get(f"/api/work-items/{item_id}/comments")
+    except Exception:
+        return []
+
+
+def _claude_env() -> dict[str, str]:
+    """Return env dict with CLAUDECODE unset so we can spawn a new Claude session."""
+    env = os.environ.copy()
+    env.pop("CLAUDECODE", None)
+    return env
+
+
+# ---------------------------------------------------------------------------
+# Docker verification helpers
+# ---------------------------------------------------------------------------
+
+COMPOSE_FILES = ["docker-compose.test.yml", "Dockerfile.api-test", "Dockerfile.web-test"]
+
+
+def _truncate_output(output: str, max_chars: int = 4000) -> str:
+    """Keep the last *max_chars* characters of output for posting as a comment."""
+    if len(output) <= max_chars:
+        return output
+    return f"... (truncated, showing last {max_chars} chars)\n" + output[-max_chars:]
+
+
+def _ensure_compose_files(work_dir: str, project_path: str):
+    """Copy Docker test files into the worktree if they are missing."""
+    for name in COMPOSE_FILES:
+        src = Path(project_path) / name
+        dst = Path(work_dir) / name
+        if src.exists() and not dst.exists():
+            shutil.copy2(str(src), str(dst))
+
+
+def _run_docker_tests(work_dir: str, timeout: int = 600) -> tuple[bool, str, str]:
+    """Run Docker Compose test pipeline.
+
+    Returns (success, raw_output, details_summary).
+    Always tears down containers afterwards.
+    """
+    compose_cmd = ["docker", "compose", "-f", "docker-compose.test.yml"]
+
+    try:
+        result = subprocess.run(
+            compose_cmd + ["up", "--build", "--abort-on-container-exit"],
+            cwd=work_dir,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        raw = result.stdout + "\n" + result.stderr
+        exit_code = result.returncode
+
+        # Gather per-service exit codes
+        ps_result = subprocess.run(
+            compose_cmd + ["ps", "-a", "--format", "{{.Service}}\t{{.ExitCode}}"],
+            cwd=work_dir,
+            capture_output=True,
+            text=True,
+        )
+
+        service_results: dict[str, int] = {}
+        for line in ps_result.stdout.strip().splitlines():
+            parts = line.split("\t")
+            if len(parts) == 2:
+                svc, code = parts
+                try:
+                    service_results[svc] = int(code)
+                except ValueError:
+                    service_results[svc] = -1
+
+        # Build summary
+        lines = []
+        all_pass = True
+        for svc in ["api-test", "web-build"]:
+            code = service_results.get(svc)
+            if code is None:
+                lines.append(f"- **{svc}**: unknown (container not found)")
+                all_pass = False
+            elif code == 0:
+                lines.append(f"- **{svc}**: passed")
+            else:
+                lines.append(f"- **{svc}**: FAILED (exit code {code})")
+                all_pass = False
+
+        success = exit_code == 0 and all_pass
+        details = "\n".join(lines)
+        return success, raw, details
+
+    except subprocess.TimeoutExpired:
+        return False, "", f"- Docker tests timed out after {timeout}s"
+    except FileNotFoundError:
+        return False, "", "- `docker` command not found. Is Docker installed?"
+    finally:
+        # Always clean up
+        subprocess.run(
+            compose_cmd + ["down", "-v", "--remove-orphans"],
+            cwd=work_dir,
+            capture_output=True,
+            timeout=60,
+        )
+
+
+def _do_single_merge(project_path: str, branch: str, target: str) -> bool:
+    """Merge a single branch into target. Returns True on success."""
+    # Remember current branch
+    current = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        cwd=project_path, capture_output=True, text=True,
+    ).stdout.strip()
+
+    # Ensure target exists
+    check = subprocess.run(
+        ["git", "rev-parse", "--verify", target],
+        cwd=project_path, capture_output=True, text=True,
+    )
+    if check.returncode != 0:
+        subprocess.run(
+            ["git", "branch", target],
+            cwd=project_path, capture_output=True,
+        )
+
+    # Prune stale worktrees so checkout succeeds
+    subprocess.run(["git", "worktree", "prune"], cwd=project_path, capture_output=True)
+
+    # Checkout target
+    co = subprocess.run(
+        ["git", "checkout", target],
+        cwd=project_path, capture_output=True, text=True,
+    )
+    if co.returncode != 0:
+        return False
+
+    # Merge
+    merge_result = subprocess.run(
+        ["git", "merge", branch, "--no-ff", "-m", f"Merge {branch} into {target}"],
+        cwd=project_path, capture_output=True, text=True,
+    )
+    ok = merge_result.returncode == 0
+
+    if not ok:
+        subprocess.run(["git", "merge", "--abort"], cwd=project_path, capture_output=True)
+
+    # Return to original branch
+    subprocess.run(
+        ["git", "checkout", current],
+        cwd=project_path, capture_output=True,
+    )
+
+    return ok
+
+
+def _format_comments_context(comments: list[dict]) -> str:
+    if not comments:
+        return ""
+    parts = ["## Previous Comments / Progress"]
+    for c in comments:
+        author = c.get("author", "unknown")
+        ctype = c.get("type", "discussion")
+        tag = f" [{ctype}]" if ctype != "discussion" else ""
+        body = c.get("body", "")
+        created = c.get("created_at", "")
+        parts.append(f"\n### {author}{tag} -- {created}\n{body}")
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Prompt builders
+# ---------------------------------------------------------------------------
+
+
+def _build_suggest_prompt(item: dict, knowledge: str, comments_ctx: str) -> str:
+    """Phase 1 prompt -- analyse only, no code changes."""
+    key = item.get("key") or f"#{item['number']}"
+    parts = [
+        f"You are analysing {item['type']} {key}: {item['title']}",
+        "",
+        f"Type: {item['type']}  |  Priority: {item['priority']}  |  Status: {item['status']}",
+    ]
+    if item.get("description"):
+        parts.extend(["", "## Description", item["description"]])
+    if item.get("acceptance_criteria"):
+        parts.extend(["", "## Acceptance Criteria", item["acceptance_criteria"]])
+    if item.get("plan"):
+        parts.extend(["", "## Existing Plan", item["plan"]])
+    if comments_ctx:
+        parts.extend(["", comments_ctx])
+    if knowledge:
+        parts.extend(["", "## Project Knowledge Base", knowledge])
+    parts.extend([
+        "",
+        "## Your Task",
+        "",
+        "Analyse this work item **and** the project source code. Return a Markdown plan:",
+        "",
+        "1. **Root Cause / Analysis** -- what needs to change and why",
+        "2. **Files to Modify** -- list every file with a short description of the change",
+        "3. **Implementation Steps** -- numbered, concrete steps",
+        "4. **Testing Strategy** -- how to verify the changes",
+        "5. **Risks & Considerations** -- edge cases, breaking changes",
+        "",
+        "IMPORTANT: Do NOT modify any files. Only analyse and produce the plan.",
+    ])
+    return "\n".join(parts)
+
+
+def _build_execute_prompt(item: dict, knowledge: str, comments_ctx: str) -> str:
+    """Phase 2 prompt -- implement the changes."""
+    key = item.get("key") or f"#{item['number']}"
+    parts = [
+        f"You are implementing {item['type']} {key}: {item['title']}",
+        "",
+        f"Type: {item['type']}  |  Priority: {item['priority']}",
+    ]
+    if item.get("description"):
+        parts.extend(["", "## Description", item["description"]])
+    if item.get("acceptance_criteria"):
+        parts.extend(["", "## Acceptance Criteria", item["acceptance_criteria"]])
+    if item.get("plan"):
+        parts.extend(["", "## Implementation Plan", item["plan"]])
+    if comments_ctx:
+        parts.extend(["", comments_ctx])
+    if knowledge:
+        parts.extend(["", "## Project Knowledge Base", knowledge])
+    parts.extend([
+        "",
+        "## Instructions",
+        "",
+        "Implement the changes described in the plan / comments above.",
+        "",
+        "1. Follow the project's existing coding conventions and patterns",
+        "2. Work through changes one file at a time",
+        "3. Run existing tests after your changes and fix any failures",
+        "4. Add new tests where appropriate",
+        "5. Commit your work with a clear, descriptive commit message",
+        "6. If you hit a blocker, document it clearly so the next run can continue",
+    ])
+    return "\n".join(parts)
+
+
+def _build_test_prompt(item: dict, knowledge: str, comments_ctx: str) -> str:
+    """Phase 3 prompt -- run tests and verify implementation."""
+    key = item.get("key") or f"#{item['number']}"
+    parts = [
+        f"You are verifying the implementation of {item['type']} {key}: {item['title']}",
+        "",
+        f"Type: {item['type']}  |  Priority: {item['priority']}",
+    ]
+    if item.get("description"):
+        parts.extend(["", "## Description", item["description"]])
+    if item.get("acceptance_criteria"):
+        parts.extend(["", "## Acceptance Criteria", item["acceptance_criteria"]])
+    if comments_ctx:
+        parts.extend(["", comments_ctx])
+    if knowledge:
+        parts.extend(["", "## Project Knowledge Base", knowledge])
+    parts.extend([
+        "",
+        "## Your Task",
+        "",
+        "Run ALL relevant tests and verify the implementation. Follow these steps:",
+        "",
+        "1. Identify test commands from CLAUDE.md or project config (pytest, vitest, npm test, etc.)",
+        "2. Run all relevant test suites",
+        "3. Check acceptance criteria from the work item (if any)",
+        "4. Review the git diff for obvious issues",
+        "",
+        "Return a structured test report in this format:",
+        "",
+        "## Test Report",
+        "",
+        "### Results",
+        "- **Status**: PASS or FAIL",
+        "- **Tests run**: <count>",
+        "- **Passed**: <count>",
+        "- **Failed**: <count>",
+        "",
+        "### Failing Tests (if any)",
+        "- Test name: reason for failure",
+        "",
+        "### Acceptance Criteria Check",
+        "- [x] or [ ] for each criterion",
+        "",
+        "### Root Cause Analysis (if failures)",
+        "Brief analysis of why tests are failing.",
+        "",
+        "IMPORTANT: Do NOT fix any code. Only run tests and report results.",
+    ])
+    return "\n".join(parts)
+
+
+def _build_reimplement_prompt(item: dict, knowledge: str, comments_ctx: str, docker_output: str = "") -> str:
+    """Re-implementation prompt -- reads previous failure reasons and tries again."""
+    key = item.get("key") or f"#{item['number']}"
+    parts = [
+        f"You are RE-IMPLEMENTING {item['type']} {key}: {item['title']}",
+        "",
+        f"Type: {item['type']}  |  Priority: {item['priority']}",
+        "",
+        "**IMPORTANT: A previous implementation attempt had test failures.**",
+        "Read the comments below carefully — they contain the original plan,",
+        "execution report, and test failure details. Fix the issues identified",
+        "in the test report.",
+    ]
+    if item.get("description"):
+        parts.extend(["", "## Description", item["description"]])
+    if item.get("acceptance_criteria"):
+        parts.extend(["", "## Acceptance Criteria", item["acceptance_criteria"]])
+    if item.get("plan"):
+        parts.extend(["", "## Implementation Plan", item["plan"]])
+    if comments_ctx:
+        parts.extend(["", comments_ctx])
+    if knowledge:
+        parts.extend(["", "## Project Knowledge Base", knowledge])
+    if docker_output:
+        truncated = _truncate_output(docker_output, 3000)
+        parts.extend([
+            "",
+            "## Docker Test Output (from last run)",
+            "",
+            "The following is the raw Docker test output. Use this to identify exact failures:",
+            "",
+            f"```\n{truncated}\n```",
+        ])
+    parts.extend([
+        "",
+        "## Instructions",
+        "",
+        "1. Read the test report and failure reasons from previous comments AND the Docker output above",
+        "2. Identify what went wrong in the previous implementation",
+        "3. Fix the issues — focus on the root causes identified in the test report",
+        "4. Ensure all tests pass after your changes",
+        "5. Run the full test suite to verify no regressions",
+        "6. Commit your fixes with a clear message referencing the re-implementation",
+        "7. If you hit a blocker, document it clearly",
+    ])
+    return "\n".join(parts)
+
+
+def _build_verify_prompt(item: dict, knowledge: str, comments_ctx: str) -> str:
+    """Verify prompt -- analyse requirements feasibility, return READY or NEEDS_INFO verdict."""
+    key = item.get("key") or f"#{item['number']}"
+    parts = [
+        f"You are verifying requirements for {item['type']} {key}: {item['title']}",
+        "",
+        f"Type: {item['type']}  |  Priority: {item['priority']}  |  Status: {item['status']}",
+    ]
+    if item.get("description"):
+        parts.extend(["", "## Description", item["description"]])
+    if item.get("acceptance_criteria"):
+        parts.extend(["", "## Acceptance Criteria", item["acceptance_criteria"]])
+    if item.get("plan"):
+        parts.extend(["", "## Existing Plan", item["plan"]])
+    if comments_ctx:
+        parts.extend(["", comments_ctx])
+    if knowledge:
+        parts.extend(["", "## Project Knowledge Base", knowledge])
+    parts.extend([
+        "",
+        "## Your Task",
+        "",
+        "Analyse this work item's requirements AND the project source code. Determine if the item is ready for implementation.",
+        "",
+        "Check the following:",
+        "1. Are the requirements clear and specific enough to implement?",
+        "2. Do acceptance criteria exist and are they testable?",
+        "3. Is the requested change feasible given the current codebase?",
+        "4. Are there any blockers, missing dependencies, or unclear areas?",
+        "",
+        "Return a structured analysis:",
+        "",
+        "## Requirement Analysis",
+        "",
+        "### Clarity",
+        "- Are requirements clear? What's ambiguous?",
+        "",
+        "### Feasibility",
+        "- What files need to change?",
+        "- Is the architecture compatible?",
+        "- Any technical blockers?",
+        "",
+        "### Solution Approach",
+        "- Proposed approach (high-level)",
+        "- Files to modify with brief description",
+        "- Estimated complexity (low/medium/high)",
+        "",
+        "### Blockers & Missing Information",
+        "- List anything that would prevent implementation",
+        "",
+        "### VERDICT: READY",
+        "or",
+        "### VERDICT: NEEDS_INFO",
+        "- If NEEDS_INFO, list exactly what information is missing",
+        "",
+        "IMPORTANT:",
+        "- You MUST include exactly one verdict line: `VERDICT: READY` or `VERDICT: NEEDS_INFO`",
+        "- Do NOT modify any files. Only analyse and produce the assessment.",
+    ])
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Git worktree utilities
+# ---------------------------------------------------------------------------
+
+
+def _worktree_path(slug: str, item_number: int, title: str | None = None) -> Path:
+    """Return the worktree directory path for an item.
+
+    New format:  item-{number}-{title-slug}   (e.g. item-2-enhance-users-table)
+    Legacy format: item-{number}              (still discovered by _find_worktree)
+    """
+    if title:
+        short_slug = _slugify(title, max_len=40)
+        return WORKTREES_DIR / slug / f"item-{item_number}-{short_slug}"
+    return WORKTREES_DIR / slug / f"item-{item_number}"
+
+
+def _find_worktree(slug: str, item_number: int) -> Path:
+    """Find an existing worktree for an item (handles both old and new naming)."""
+    parent = WORKTREES_DIR / slug
+    if parent.exists():
+        # Match item-{number}-* (new) or item-{number} (legacy)
+        for entry in sorted(parent.iterdir(), reverse=True):
+            if entry.is_dir() and (
+                entry.name == f"item-{item_number}"
+                or entry.name.startswith(f"item-{item_number}-")
+            ):
+                return entry
+    # Fallback: return the legacy path (caller checks .exists())
+    return WORKTREES_DIR / slug / f"item-{item_number}"
+
+
+def _create_worktree(project_path: str, slug: str, item: dict) -> tuple[str, str]:
+    """Create (or reuse) a git worktree. Returns (worktree_path, branch_name).
+
+    Branch format: {type_prefix}/{key}_{slugified_title}
+    e.g. feat/bb-42_authentication-by-google
+    """
+    item_number = item["number"]
+    branch = _build_branch_name(item)
+
+    # Check for any existing worktree (legacy or new naming) first
+    existing = _find_worktree(slug, item_number)
+    if existing.exists():
+        wt = existing
+    else:
+        wt = _worktree_path(slug, item_number, title=item.get("title"))
+    wt.parent.mkdir(parents=True, exist_ok=True)
+
+    # Already exists and valid?
+    if wt.exists():
+        probe = subprocess.run(
+            ["git", "worktree", "list", "--porcelain"],
+            cwd=project_path, capture_output=True, text=True,
+        )
+        # Normalise to forward-slash for reliable comparison
+        wt_norm = str(wt).replace("\\", "/")
+        if any(wt_norm in ln.replace("\\", "/") for ln in probe.stdout.splitlines()):
+            return str(wt), branch
+        # Stale -- clean up
+        subprocess.run(["git", "worktree", "prune"], cwd=project_path, capture_output=True)
+        if wt.exists():
+            shutil.rmtree(wt)
+
+    # Does branch already exist?
+    check = subprocess.run(
+        ["git", "rev-parse", "--verify", branch],
+        cwd=project_path, capture_output=True, text=True,
+    )
+
+    if check.returncode == 0:
+        subprocess.run(
+            ["git", "worktree", "add", str(wt), branch],
+            cwd=project_path, check=True, capture_output=True, text=True,
+        )
+    else:
+        subprocess.run(
+            ["git", "worktree", "add", "-b", branch, str(wt)],
+            cwd=project_path, check=True, capture_output=True, text=True,
+        )
+
+    return str(wt), branch
+
+
+def _remove_worktree(project_path: str, wt_path: str):
+    subprocess.run(
+        ["git", "worktree", "remove", "--force", wt_path],
+        cwd=project_path, capture_output=True,
+    )
+    subprocess.run(["git", "worktree", "prune"], cwd=project_path, capture_output=True)
+
+
+# ---------------------------------------------------------------------------
+# Batch internal helpers (thread-safe, no rich print inside workers)
+# ---------------------------------------------------------------------------
+
+
+def _suggest_one(slug: str, project_path: str, id_or_number: str, tracker=None) -> dict:
+    """Run suggest for a single item. Thread-safe — returns result dict."""
+    try:
+        item = _resolve_item(slug, id_or_number)
+    except Exception as e:
+        return {"key": id_or_number, "status": "failed", "error": f"Resolve failed: {e}"}
+
+    item_id = item["id"]
+    key = item.get("key") or f"#{item['number']}"
+
+    # Start agent session for streaming
+    try:
+        session = api_post(
+            "/api/agent-sessions/start",
+            json={"work_item_id": item_id, "origin": "cli", "phase": "suggest"},
+            params={"project_slug": slug},
+        )
+        session_id = session["id"]
+    except Exception:
+        session_id = None
+
+    if tracker and session_id:
+        tracker.update(key, "suggest", "running", "Starting analysis...")
+
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_suggest_prompt(item, knowledge, comments_ctx)
+
+    streamer = None
+    if session_id:
+        streamer = AgentStreamer(session_id)
+        if tracker:
+            streamer.set_callback(lambda p, t: tracker.update(key, "suggest", "running", (t or "")[:60]) if t else None)
+        streamer.start()
+        update_phase(session_id, "suggest")
+
+    try:
+        proc = subprocess.Popen(
+            ["claude", "-p", prompt, "--output-format", "stream-json"],
+            cwd=project_path,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=_claude_env(),
+        )
+
+        for line in proc.stdout:
+            if streamer:
+                streamer.feed(line)
+
+        proc.wait()
+    except FileNotFoundError:
+        if streamer:
+            streamer.stop()
+        return {"key": key, "status": "failed", "error": "'claude' CLI not found"}
+
+    text_blocks = streamer.stop() if streamer else []
+
+    if proc.returncode != 0:
+        if session_id:
+            complete_session(session_id, "failed", error=f"Exit code {proc.returncode}")
+        return {"key": key, "status": "failed", "error": proc.stderr.read()[:200] if proc.stderr else "Non-zero exit"}
+
+    suggestion = "\n\n".join(text_blocks) if text_blocks else ""
+    if not suggestion:
+        if session_id:
+            complete_session(session_id, "failed", error="Empty response")
+        return {"key": key, "status": "failed", "error": "Empty response"}
+
+    # Post comment
+    api_post(f"/api/work-items/{item_id}/comments", json={
+        "body": suggestion,
+        "author": "bb-agent",
+        "type": "proposal",
+    })
+
+    # Advance status
+    if item["status"] == "open":
+        api_put(f"/api/work-items/{item_id}", json={"status": "confirmed"})
+
+    if session_id:
+        complete_session(session_id, "completed")
+
+    return {"key": key, "status": "ok", "suggestion": suggestion[:200]}
+
+
+def _execute_one(slug: str, project_path: str, id_or_number: str, tracker=None) -> dict:
+    """Run execute for a single item in its own worktree. Thread-safe."""
+    try:
+        item = _resolve_item(slug, id_or_number)
+    except Exception as e:
+        return {"key": id_or_number, "status": "failed", "error": f"Resolve failed: {e}"}
+
+    item_id = item["id"]
+    item_number = item["number"]
+    key = item.get("key") or f"#{item_number}"
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_execute_prompt(item, knowledge, comments_ctx)
+
+    # Create worktree
+    try:
+        work_dir, branch_name = _create_worktree(project_path, slug, item)
+    except subprocess.CalledProcessError as e:
+        return {"key": key, "status": "failed", "error": f"Worktree failed: {e.stderr or e}"}
+
+    # Agent session
+    try:
+        session = api_post(
+            "/api/agent-sessions/start",
+            json={"work_item_id": item_id, "origin": "cli", "phase": "execute"},
+            params={"project_slug": slug},
+        )
+        session_id = session["id"]
+    except Exception as e:
+        return {"key": key, "status": "failed", "error": f"Session start failed: {e}", "branch": branch_name}
+
+    # Update session with branch/worktree info
+    update_phase(session_id, "execute", branch_name=branch_name, worktree_path=work_dir)
+
+    # Status -> in_progress
+    if item["status"] in ("open", "confirmed", "approved"):
+        api_put(f"/api/work-items/{item_id}", json={"status": "in_progress"})
+
+    if tracker:
+        tracker.update(key, "execute", "running", "Starting implementation...")
+
+    # Streamer for buffered relay
+    streamer = AgentStreamer(session_id)
+    if tracker:
+        streamer.set_callback(lambda p, t: tracker.update(key, "execute", "running", (t or "")[:60]) if t else None)
+    streamer.start()
+
+    # MCP config
+    api_url = get_api_url()
+    token = get_token()
+    mcp_cfg = json.dumps({
+        "mcpServers": {
+            "bumblebee": {
+                "url": f"{api_url}/mcp",
+                "headers": {"Authorization": f"Bearer {token}"} if token else {},
+            }
+        }
+    })
+
+    try:
+        proc = subprocess.Popen(
+            [
+                "claude",
+                "--output-format", "stream-json",
+                "--verbose",
+                "--permission-mode", "bypassPermissions",
+                "--mcp-config", "-",
+                "-p", prompt,
+            ],
+            cwd=work_dir,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=_claude_env(),
+        )
+
+        proc.stdin.write(mcp_cfg)
+        proc.stdin.close()
+
+        for line in proc.stdout:
+            streamer.feed(line)
+
+        proc.wait()
+
+        text_blocks = streamer.stop()
+
+        # Post completion comment
+        tail = "\n\n".join(text_blocks[-3:]) if text_blocks else "No text output captured."
+        body_lines = [
+            "## Agent Execution Report\n",
+            f"**Branch**: `{branch_name}`\n",
+            f"**Exit code**: `{proc.returncode}`\n",
+            f"\n### Output (last messages)\n\n{tail}",
+        ]
+        api_post(f"/api/work-items/{item_id}/comments", json={
+            "body": "\n".join(body_lines),
+            "author": "bb-agent",
+            "type": "agent_output",
+        })
+
+        if proc.returncode == 0:
+            api_put(f"/api/work-items/{item_id}", json={"status": "in_review"})
+            complete_session(session_id, "completed")
+            return {"key": key, "status": "ok", "branch": branch_name, "worktree": work_dir}
+        else:
+            complete_session(session_id, "failed", error=f"Exit code {proc.returncode}")
+            return {"key": key, "status": "failed", "error": f"Exit code {proc.returncode}", "branch": branch_name}
+
+    except FileNotFoundError:
+        streamer.stop()
+        return {"key": key, "status": "failed", "error": "'claude' CLI not found"}
+
+
+def _test_one(slug: str, project_path: str, id_or_number: str, tracker=None) -> dict:
+    """Run test phase for a single item. Thread-safe — returns result dict."""
+    try:
+        item = _resolve_item(slug, id_or_number)
+    except Exception as e:
+        return {"key": id_or_number, "status": "failed", "error": f"Resolve failed: {e}"}
+
+    item_id = item["id"]
+    item_number = item["number"]
+    key = item.get("key") or f"#{item_number}"
+
+    # Worktree must already exist
+    wt = _find_worktree(slug, item_number)
+    if not wt.exists():
+        return {"key": key, "status": "failed", "error": "No worktree found (execute first)"}
+
+    work_dir = str(wt)
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_test_prompt(item, knowledge, comments_ctx)
+
+    if tracker:
+        tracker.update(key, "test", "running", "Starting tests...")
+
+    # Create a session for streaming
+    session_id = None
+    try:
+        session = api_post(
+            "/api/agent-sessions/start",
+            json={"work_item_id": item_id, "origin": "cli", "phase": "test"},
+            params={"project_slug": slug},
+        )
+        session_id = session["id"]
+    except Exception:
+        pass
+
+    streamer = None
+    if session_id:
+        streamer = AgentStreamer(session_id)
+        if tracker:
+            streamer.set_callback(lambda p, t: tracker.update(key, "test", "running", (t or "")[:60]) if t else None)
+        streamer.start()
+        update_phase(session_id, "test")
+
+    try:
+        proc = subprocess.Popen(
+            ["claude", "-p", prompt, "--output-format", "stream-json"],
+            cwd=work_dir,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=_claude_env(),
+        )
+
+        for line in proc.stdout:
+            if streamer:
+                streamer.feed(line)
+
+        proc.wait()
+    except FileNotFoundError:
+        if streamer:
+            streamer.stop()
+        return {"key": key, "status": "failed", "error": "'claude' CLI not found"}
+
+    text_blocks = streamer.stop() if streamer else []
+
+    if proc.returncode != 0:
+        if session_id:
+            complete_session(session_id, "failed", error=f"Exit code {proc.returncode}")
+        return {"key": key, "status": "failed", "error": (proc.stderr.read() if proc.stderr else "")[:200]}
+
+    report = "\n\n".join(text_blocks) if text_blocks else ""
+    if not report:
+        if session_id:
+            complete_session(session_id, "failed", error="Empty test report")
+        return {"key": key, "status": "failed", "error": "Empty test report"}
+
+    # Determine pass/fail from the report
+    report_lower = report.lower()
+    tests_passed = (
+        "**status**: pass" in report_lower
+        or "status: pass" in report_lower
+        or ("all tests pass" in report_lower and "fail" not in report_lower.split("all tests pass")[0][-50:])
+    )
+
+    # Post test report comment
+    api_post(f"/api/work-items/{item_id}/comments", json={
+        "body": report,
+        "author": "bb-agent",
+        "type": "test_report",
+    })
+
+    if tests_passed:
+        if session_id:
+            complete_session(session_id, "completed")
+        return {"key": key, "status": "ok", "report": report[:200]}
+    else:
+        api_put(f"/api/work-items/{item_id}", json={"status": "failed"})
+        if session_id:
+            complete_session(session_id, "failed", error="Tests failed")
+        return {"key": key, "status": "failed", "error": "Tests failed", "report": report[:200]}
+
+
+def _reimplement_one(slug: str, project_path: str, id_or_number: str, docker_output: str = "", tracker=None) -> dict:
+    """Re-implement a failed item. Thread-safe — returns result dict."""
+    try:
+        item = _resolve_item(slug, id_or_number)
+    except Exception as e:
+        return {"key": id_or_number, "status": "failed", "error": f"Resolve failed: {e}"}
+
+    item_id = item["id"]
+    item_number = item["number"]
+    key = item.get("key") or f"#{item_number}"
+
+    # Reuse existing worktree
+    wt = _find_worktree(slug, item_number)
+    if not wt.exists():
+        return {"key": key, "status": "failed", "error": "No worktree found (execute first)"}
+
+    work_dir = str(wt)
+    branch_name = _detect_worktree_branch(project_path, wt)
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_reimplement_prompt(item, knowledge, comments_ctx, docker_output=docker_output)
+
+    # Status -> in_progress
+    api_put(f"/api/work-items/{item_id}", json={"status": "in_progress"})
+
+    if tracker:
+        tracker.update(key, "reimplement", "running", "Re-implementing...")
+
+    # Agent session for streaming
+    session_id = None
+    try:
+        session = api_post(
+            "/api/agent-sessions/start",
+            json={"work_item_id": item_id, "origin": "cli", "phase": "reimplement"},
+            params={"project_slug": slug},
+        )
+        session_id = session["id"]
+    except Exception:
+        pass
+
+    streamer = None
+    if session_id:
+        streamer = AgentStreamer(session_id)
+        if tracker:
+            streamer.set_callback(lambda p, t: tracker.update(key, "reimplement", "running", (t or "")[:60]) if t else None)
+        streamer.start()
+        update_phase(session_id, "reimplement", branch_name=branch_name or "", worktree_path=work_dir)
+
+    # MCP config
+    api_url = get_api_url()
+    token = get_token()
+    mcp_cfg = json.dumps({
+        "mcpServers": {
+            "bumblebee": {
+                "url": f"{api_url}/mcp",
+                "headers": {"Authorization": f"Bearer {token}"} if token else {},
+            }
+        }
+    })
+
+    try:
+        proc = subprocess.Popen(
+            [
+                "claude",
+                "--output-format", "stream-json",
+                "--verbose",
+                "--permission-mode", "bypassPermissions",
+                "--mcp-config", "-",
+                "-p", prompt,
+            ],
+            cwd=work_dir,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=_claude_env(),
+        )
+
+        proc.stdin.write(mcp_cfg)
+        proc.stdin.close()
+
+        for line in proc.stdout:
+            if streamer:
+                streamer.feed(line)
+
+        proc.wait()
+
+        text_blocks = streamer.stop() if streamer else []
+
+        # Post re-implementation report
+        tail = "\n\n".join(text_blocks[-3:]) if text_blocks else "No text output captured."
+        body_lines = [
+            "## Re-implementation Report\n",
+            f"**Branch**: `{branch_name or 'unknown'}`\n",
+            f"**Exit code**: `{proc.returncode}`\n",
+            f"\n### Output (last messages)\n\n{tail}",
+        ]
+        api_post(f"/api/work-items/{item_id}/comments", json={
+            "body": "\n".join(body_lines),
+            "author": "bb-agent",
+            "type": "agent_output",
+        })
+
+        if proc.returncode == 0:
+            if session_id:
+                complete_session(session_id, "completed")
+            return {"key": key, "status": "ok", "branch": branch_name, "worktree": work_dir}
+        else:
+            if session_id:
+                complete_session(session_id, "failed", error=f"Exit code {proc.returncode}")
+            return {"key": key, "status": "failed", "error": f"Exit code {proc.returncode}", "branch": branch_name}
+
+    except FileNotFoundError:
+        if streamer:
+            streamer.stop()
+        return {"key": key, "status": "failed", "error": "'claude' CLI not found"}
+
+
+def _docker_test_one(slug: str, project_path: str, id_or_number: str, timeout: int = 600) -> dict:
+    """Run Docker-based tests for a single item. Thread-safe — returns result dict."""
+    try:
+        item = _resolve_item(slug, id_or_number)
+    except Exception as e:
+        return {"key": id_or_number, "status": "failed", "output": "", "details": f"Resolve failed: {e}"}
+
+    item_id = item["id"]
+    item_number = item["number"]
+    key = item.get("key") or f"#{item_number}"
+
+    # Worktree must already exist
+    wt = _find_worktree(slug, item_number)
+    if not wt.exists():
+        return {"key": key, "status": "failed", "output": "", "details": "No worktree found (execute first)"}
+
+    work_dir = str(wt)
+
+    # Ensure Docker files exist in worktree
+    _ensure_compose_files(work_dir, project_path)
+
+    # Run Docker tests
+    success, raw_output, details = _run_docker_tests(work_dir, timeout)
+
+    # Post test results as comment
+    if success:
+        body = f"## Docker Test Report\n\n**Status**: PASS\n\n{details}"
+        comment_type = "test_report"
+    else:
+        truncated = _truncate_output(raw_output, 4000)
+        body = f"## Docker Test Report\n\n**Status**: FAIL\n\n{details}\n\n### Docker Output\n\n```\n{truncated}\n```"
+        comment_type = "test_failure"
+
+    api_post(f"/api/work-items/{item_id}/comments", json={
+        "body": body,
+        "author": "bb-agent",
+        "type": comment_type,
+    })
+
+    status = "ok" if success else "failed"
+    return {"key": key, "status": status, "output": raw_output, "details": details}
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def suggest(
+    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to analyse"),
+):
+    """Phase 1: Analyse a work item and post a solution plan as a comment."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    rprint(f"[cyan]Fetching work item {id_or_number}...[/cyan]")
+    item = _resolve_item(slug, id_or_number)
+    item_id = item["id"]
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_suggest_prompt(item, knowledge, comments_ctx)
+
+    rprint(f"[cyan]Running Claude Code analysis in {project_path}...[/cyan]")
+
+    try:
+        result = subprocess.run(
+            ["claude", "-p", prompt, "--output-format", "text"],
+            cwd=project_path,
+            capture_output=True,
+            text=True,
+            timeout=600,
+            env=_claude_env(),
+        )
+
+        if result.returncode != 0:
+            rprint(f"[red]Claude analysis failed:[/red]\n{result.stderr}")
+            raise typer.Exit(1)
+
+        suggestion = result.stdout.strip()
+        if not suggestion:
+            rprint("[red]Claude returned an empty response.[/red]")
+            raise typer.Exit(1)
+
+        rprint()
+        key = item.get("key") or f"#{item['number']}"
+        rprint(Panel(
+            Markdown(suggestion),
+            title=f"Suggested Solution -- {key}",
+            border_style="green",
+        ))
+
+        # Post as agent comment
+        api_post(f"/api/work-items/{item_id}/comments", json={
+            "body": suggestion,
+            "author": "bb-agent",
+            "type": "proposal",
+        })
+        rprint("[green]Suggestion posted as comment on the work item.[/green]")
+
+        # Save plan to work item
+        api_put(f"/api/work-items/{item_id}", json={"plan": suggestion})
+        rprint("[green]Plan saved to work item.[/green]")
+
+        # Advance status open -> confirmed
+        if item["status"] == "open":
+            api_put(f"/api/work-items/{item_id}", json={"status": "confirmed"})
+            rprint("[dim]Status -> confirmed[/dim]")
+
+    except FileNotFoundError:
+        rprint("[red]'claude' CLI not found. Install Claude Code first.[/red]")
+        raise typer.Exit(1)
+    except subprocess.TimeoutExpired:
+        rprint("[red]Analysis timed out (10 min limit).[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def execute(
+    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to implement"),
+    no_worktree: bool = typer.Option(False, "--no-worktree", help="Work in main directory (skip worktree)"),
+    cleanup: bool = typer.Option(False, "--cleanup", help="Remove worktree after completion"),
+):
+    """Phase 2: Create a worktree and implement the work item with Claude Code."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    # Context
+    item = _resolve_item(slug, id_or_number)
+    item_id = item["id"]
+    item_number = item["number"]
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_execute_prompt(item, knowledge, comments_ctx)
+
+    # Worktree
+    work_dir = project_path
+    branch_name = None
+
+    if not no_worktree:
+        try:
+            key = item.get("key") or f"#{item_number}"
+            rprint(f"[cyan]Creating worktree for {key}...[/cyan]")
+            work_dir, branch_name = _create_worktree(project_path, slug, item)
+            rprint(f"[green]Worktree: {work_dir}[/green]")
+            rprint(f"[green]Branch:   {branch_name}[/green]")
+        except subprocess.CalledProcessError as e:
+            rprint(f"[red]Worktree failed: {e.stderr or e}[/red]")
+            rprint("[yellow]Falling back to main directory.[/yellow]")
+
+    # Agent session
+    session = api_post(
+        "/api/agent-sessions/start",
+        json={"work_item_id": item_id, "origin": "cli"},
+        params={"project_slug": slug},
+    )
+    session_id = session["id"]
+    rprint(f"[green]Session:  {session_id}[/green]")
+
+    # Status -> in_progress
+    if item["status"] in ("open", "confirmed", "approved"):
+        api_put(f"/api/work-items/{item_id}", json={"status": "in_progress"})
+        rprint("[dim]Status -> in_progress[/dim]")
+
+    # MCP config (Bumblebee tools for Claude)
+    api_url = get_api_url()
+    token = get_token()
+    mcp_cfg = json.dumps({
+        "mcpServers": {
+            "bumblebee": {
+                "url": f"{api_url}/mcp",
+                "headers": {"Authorization": f"Bearer {token}"} if token else {},
+            }
+        }
+    })
+
+    rprint(f"\n[cyan]Spawning Claude Code agent in {work_dir}...[/cyan]\n")
+
+    try:
+        proc = subprocess.Popen(
+            [
+                "claude",
+                "--output-format", "stream-json",
+                "--verbose",
+                "--permission-mode", "bypassPermissions",
+                "--mcp-config", "-",
+                "-p", prompt,
+            ],
+            cwd=work_dir,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=_claude_env(),
+        )
+
+        proc.stdin.write(mcp_cfg)
+        proc.stdin.close()
+
+        # Stream output -> terminal + API relay
+        text_blocks: list[str] = []
+        for line in proc.stdout:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                payload = json.loads(line)
+                if payload.get("type") == "assistant":
+                    for block in payload.get("content", []):
+                        if block.get("type") == "text":
+                            rprint(block["text"])
+                            text_blocks.append(block["text"])
+                try:
+                    api_post(f"/api/agent-sessions/{session_id}/relay", json=payload)
+                except Exception:
+                    pass
+            except json.JSONDecodeError:
+                rprint(f"[dim]{line}[/dim]")
+
+        proc.wait()
+
+        # Completion comment
+        tail = "\n\n".join(text_blocks[-3:]) if text_blocks else "No text output captured."
+        body_lines = ["## Agent Execution Report\n"]
+        if branch_name:
+            body_lines.append(f"**Branch**: `{branch_name}`\n")
+        body_lines.append(f"**Exit code**: `{proc.returncode}`\n")
+        body_lines.append(f"\n### Output (last messages)\n\n{tail}")
+
+        api_post(f"/api/work-items/{item_id}/comments", json={
+            "body": "\n".join(body_lines),
+            "author": "bb-agent",
+            "type": "agent_output",
+        })
+
+        if proc.returncode == 0:
+            rprint("\n[green]Agent completed successfully.[/green]")
+            api_put(f"/api/work-items/{item_id}", json={"status": "in_review"})
+            rprint("[dim]Status -> in_review[/dim]")
+        else:
+            rprint(f"\n[yellow]Agent exited with code {proc.returncode}.[/yellow]")
+
+        # Worktree post-run
+        if branch_name and work_dir != project_path:
+            if cleanup:
+                _remove_worktree(project_path, work_dir)
+                rprint("[dim]Worktree removed.[/dim]")
+            else:
+                rprint(f"\n[dim]Worktree: {work_dir}[/dim]")
+                rprint(f"[dim]Merge:    cd {project_path} && git merge {branch_name}[/dim]")
+                rprint(f"[dim]Cleanup:  bb agent cleanup {item_number}[/dim]")
+
+    except FileNotFoundError:
+        rprint("[red]'claude' CLI not found. Install Claude Code first.[/red]")
+        raise typer.Exit(1)
+    except KeyboardInterrupt:
+        rprint("\n[yellow]Agent interrupted.[/yellow]")
+        api_post(f"/api/agent-sessions/{session_id}/abort")
+        api_post(f"/api/work-items/{item_id}/comments", json={
+            "body": "## Agent Interrupted\n\nManually stopped by user.",
+            "author": "bb-agent",
+            "type": "agent_output",
+        })
+
+
+@app.command(name="test")
+def test_item(
+    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to test"),
+):
+    """Phase 3: Run tests in the worktree and report results."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    rprint(f"[cyan]Fetching work item {id_or_number}...[/cyan]")
+    item = _resolve_item(slug, id_or_number)
+    item_id = item["id"]
+    item_number = item["number"]
+    key = item.get("key") or f"#{item_number}"
+
+    # Worktree must already exist
+    wt = _find_worktree(slug, item_number)
+    if not wt.exists():
+        rprint(f"[red]No worktree found for {key}. Run 'bb agent execute {id_or_number}' first.[/red]")
+        raise typer.Exit(1)
+
+    work_dir = str(wt)
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_test_prompt(item, knowledge, comments_ctx)
+
+    rprint(f"[cyan]Running tests in {work_dir}...[/cyan]")
+
+    try:
+        result = subprocess.run(
+            ["claude", "-p", prompt, "--output-format", "text"],
+            cwd=work_dir,
+            capture_output=True,
+            text=True,
+            timeout=600,
+            env=_claude_env(),
+        )
+
+        if result.returncode != 0:
+            rprint(f"[red]Claude test runner failed:[/red]\n{result.stderr}")
+            raise typer.Exit(1)
+
+        report = result.stdout.strip()
+        if not report:
+            rprint("[red]Empty test report.[/red]")
+            raise typer.Exit(1)
+
+        rprint()
+        rprint(Panel(
+            Markdown(report),
+            title=f"Test Report -- {key}",
+            border_style="cyan",
+        ))
+
+        # Post test report comment
+        api_post(f"/api/work-items/{item_id}/comments", json={
+            "body": report,
+            "author": "bb-agent",
+            "type": "test_report",
+        })
+        rprint("[green]Test report posted as comment.[/green]")
+
+        # Determine pass/fail
+        report_lower = report.lower()
+        tests_passed = (
+            "**status**: pass" in report_lower
+            or "status: pass" in report_lower
+            or ("all tests pass" in report_lower and "fail" not in report_lower.split("all tests pass")[0][-50:])
+        )
+
+        if tests_passed:
+            rprint("[green]All tests passed![/green]")
+        else:
+            api_put(f"/api/work-items/{item_id}", json={"status": "failed"})
+            rprint("[red]Tests failed. Status -> failed[/red]")
+            rprint(f"[dim]Fix with: bb agent reimplement {id_or_number}[/dim]")
+            raise typer.Exit(1)
+
+    except FileNotFoundError:
+        rprint("[red]'claude' CLI not found. Install Claude Code first.[/red]")
+        raise typer.Exit(1)
+    except subprocess.TimeoutExpired:
+        rprint("[red]Test run timed out (10 min limit).[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def reimplement(
+    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to re-implement"),
+    run_tests: bool = typer.Option(True, "--test/--no-test", help="Run tests after re-implementation"),
+    auto_merge: bool = typer.Option(False, "--auto-merge", help="Auto-merge to target on test pass"),
+    target: str = typer.Option("release/dev", "--target", "-t", help="Target branch for auto-merge"),
+):
+    """Re-implement a failed work item using previous feedback."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    rprint(f"[cyan]Fetching work item {id_or_number}...[/cyan]")
+    item = _resolve_item(slug, id_or_number)
+    item_id = item["id"]
+    item_number = item["number"]
+    key = item.get("key") or f"#{item_number}"
+
+    # Worktree must already exist
+    wt = _find_worktree(slug, item_number)
+    if not wt.exists():
+        rprint(f"[red]No worktree found for {key}. Run 'bb agent execute {id_or_number}' first.[/red]")
+        raise typer.Exit(1)
+
+    work_dir = str(wt)
+    branch_name = _detect_worktree_branch(project_path, wt)
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_reimplement_prompt(item, knowledge, comments_ctx)
+
+    # Status -> in_progress
+    api_put(f"/api/work-items/{item_id}", json={"status": "in_progress"})
+    rprint("[dim]Status -> in_progress[/dim]")
+
+    # Agent session
+    session = api_post(
+        "/api/agent-sessions/start",
+        json={"work_item_id": item_id, "origin": "cli"},
+        params={"project_slug": slug},
+    )
+    session_id = session["id"]
+    rprint(f"[green]Session:  {session_id}[/green]")
+
+    # MCP config
+    api_url = get_api_url()
+    token = get_token()
+    mcp_cfg = json.dumps({
+        "mcpServers": {
+            "bumblebee": {
+                "url": f"{api_url}/mcp",
+                "headers": {"Authorization": f"Bearer {token}"} if token else {},
+            }
+        }
+    })
+
+    rprint(f"\n[cyan]Re-implementing in {work_dir}...[/cyan]\n")
+
+    try:
+        proc = subprocess.Popen(
+            [
+                "claude",
+                "--output-format", "stream-json",
+                "--verbose",
+                "--permission-mode", "bypassPermissions",
+                "--mcp-config", "-",
+                "-p", prompt,
+            ],
+            cwd=work_dir,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=_claude_env(),
+        )
+
+        proc.stdin.write(mcp_cfg)
+        proc.stdin.close()
+
+        text_blocks: list[str] = []
+        for line in proc.stdout:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                payload = json.loads(line)
+                if payload.get("type") == "assistant":
+                    for block in payload.get("content", []):
+                        if block.get("type") == "text":
+                            rprint(block["text"])
+                            text_blocks.append(block["text"])
+                try:
+                    api_post(f"/api/agent-sessions/{session_id}/relay", json=payload)
+                except Exception:
+                    pass
+            except json.JSONDecodeError:
+                rprint(f"[dim]{line}[/dim]")
+
+        proc.wait()
+
+        # Post re-implementation report
+        tail = "\n\n".join(text_blocks[-3:]) if text_blocks else "No text output captured."
+        body_lines = ["## Re-implementation Report\n"]
+        if branch_name:
+            body_lines.append(f"**Branch**: `{branch_name}`\n")
+        body_lines.append(f"**Exit code**: `{proc.returncode}`\n")
+        body_lines.append(f"\n### Output (last messages)\n\n{tail}")
+
+        api_post(f"/api/work-items/{item_id}/comments", json={
+            "body": "\n".join(body_lines),
+            "author": "bb-agent",
+            "type": "agent_output",
+        })
+
+        if proc.returncode != 0:
+            rprint(f"\n[yellow]Agent exited with code {proc.returncode}.[/yellow]")
+            return
+
+        rprint("\n[green]Re-implementation completed.[/green]")
+
+        # Auto-test after re-implementation
+        if run_tests:
+            rprint("\n[cyan]Running tests...[/cyan]")
+            test_result = _test_one(slug, project_path, id_or_number)
+            if test_result["status"] == "ok":
+                rprint("[green]All tests passed![/green]")
+                if auto_merge and branch_name:
+                    rprint(f"\n[cyan]Merging {branch_name} into {target}...[/cyan]")
+                    merge_ok = _do_single_merge(project_path, branch_name, target)
+                    if merge_ok:
+                        rprint(f"[green]Merged into {target}.[/green]")
+                        api_put(f"/api/work-items/{item_id}", json={"status": "resolved"})
+                        rprint("[dim]Status -> resolved[/dim]")
+                    else:
+                        rprint("[red]Merge failed. Resolve conflicts manually.[/red]")
+                        api_put(f"/api/work-items/{item_id}", json={"status": "in_review"})
+                else:
+                    api_put(f"/api/work-items/{item_id}", json={"status": "in_review"})
+                    rprint("[dim]Status -> in_review[/dim]")
+            else:
+                rprint("[red]Tests still failing after re-implementation.[/red]")
+                rprint(f"[dim]Try again: bb agent reimplement {id_or_number}[/dim]")
+        else:
+            api_put(f"/api/work-items/{item_id}", json={"status": "in_review"})
+            rprint("[dim]Status -> in_review[/dim]")
+
+    except FileNotFoundError:
+        rprint("[red]'claude' CLI not found. Install Claude Code first.[/red]")
+        raise typer.Exit(1)
+    except KeyboardInterrupt:
+        rprint("\n[yellow]Agent interrupted.[/yellow]")
+        api_post(f"/api/agent-sessions/{session_id}/abort")
+
+
+@app.command()
+def run(
+    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number"),
+    skip_verify: bool = typer.Option(False, "--skip-verify", help="Skip the requirement verification phase"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Auto-confirm after verification"),
+    no_worktree: bool = typer.Option(False, "--no-worktree", help="Skip worktree creation"),
+    auto_merge: bool = typer.Option(True, "--auto-merge/--no-auto-merge", help="Auto-merge to target branch on test pass"),
+    target: str = typer.Option("release/dev", "--target", "-t", help="Target branch for auto-merge"),
+    max_retries: int = typer.Option(3, "--max-retries", help="Max re-implementation attempts on test failure"),
+    timeout: int = typer.Option(600, "--timeout", help="Docker test timeout in seconds"),
+):
+    """Full autonomous loop: verify -> execute -> Docker test -> reimplement retry -> merge."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    # Phase 1: Verify requirements
+    if not skip_verify:
+        rprint("[bold cyan]Phase 1: Verifying requirements...[/bold cyan]\n")
+        try:
+            verify(id_or_number)
+        except SystemExit as e:
+            if e.code:
+                # verify() exited with error (NEEDS_INFO or failure)
+                rprint("\n[red]Verification failed — aborting run.[/red]")
+                raise typer.Exit(1)
+        if not yes:
+            rprint()
+            if not typer.confirm("Proceed with implementation?"):
+                rprint(f"[yellow]Aborted. Run [bold]bb agent execute {id_or_number}[/bold] when ready.[/yellow]")
+                raise typer.Exit()
+    else:
+        rprint("[dim]Skipping verification phase.[/dim]")
+
+    # Phase 2: Execute
+    rprint("\n[bold cyan]Phase 2: Implementing...[/bold cyan]\n")
+    execute(id_or_number, no_worktree=no_worktree, cleanup=False)
+
+    # Phase 3: Docker test
+    rprint("\n[bold cyan]Phase 3: Docker testing...[/bold cyan]")
+    docker_result = _docker_test_one(slug, project_path, id_or_number, timeout=timeout)
+
+    if docker_result["status"] == "ok":
+        rprint("[green]Docker tests passed![/green]")
+    else:
+        # Tests failed — retry loop
+        rprint("[red]Docker tests failed.[/red]")
+        docker_output = docker_result.get("output", "")
+        retries_done = 0
+        while retries_done < max_retries:
+            retries_done += 1
+            rprint(f"\n[bold cyan]Retry {retries_done}/{max_retries}: Re-implementing...[/bold cyan]")
+
+            reimpl_result = _reimplement_one(slug, project_path, id_or_number, docker_output=docker_output)
+            if reimpl_result["status"] != "ok":
+                rprint(f"[red]Re-implementation failed: {reimpl_result.get('error', '?')}[/red]")
+                continue
+
+            rprint("[cyan]Re-testing with Docker...[/cyan]")
+            docker_result = _docker_test_one(slug, project_path, id_or_number, timeout=timeout)
+            if docker_result["status"] == "ok":
+                rprint("[green]Docker tests passed after re-implementation![/green]")
+                break
+            docker_output = docker_result.get("output", "")
+        else:
+            # All retries exhausted
+            item = _resolve_item(slug, id_or_number)
+            item_id = item["id"]
+            api_put(f"/api/work-items/{item_id}", json={"status": "failed"})
+            rprint("[dim]Status -> failed[/dim]")
+
+            # Post failure summary
+            api_post(f"/api/work-items/{item_id}/comments", json={
+                "body": (
+                    f"## Agent Run Failed\n\n"
+                    f"All {max_retries} re-implementation retries exhausted.\n\n"
+                    f"### Last Docker Output\n\n{docker_result.get('details', 'No details')}\n\n"
+                    f"Manual intervention required."
+                ),
+                "author": "bb-agent",
+                "type": "test_failure",
+            })
+
+            rprint(f"\n[red]All {max_retries} retries exhausted.[/red]")
+            rprint(f"[dim]Status -> failed. Manual fix: bb agent continue {id_or_number}[/dim]")
+            return
+
+    # Phase 4: Merge (only reached if Docker tests passed)
+    if auto_merge:
+        item = _resolve_item(slug, id_or_number)
+        item_id = item["id"]
+        item_number = item["number"]
+        branch_name = _detect_worktree_branch(project_path, _find_worktree(slug, item_number))
+        if branch_name:
+            rprint(f"\n[bold cyan]Phase 4: Merging {branch_name} into {target}...[/bold cyan]")
+            merge_ok = _do_single_merge(project_path, branch_name, target)
+            if merge_ok:
+                rprint(f"[green]Merged into {target}.[/green]")
+                api_put(f"/api/work-items/{item_id}", json={"status": "resolved"})
+                rprint("[dim]Status -> resolved[/dim]")
+                wt = _find_worktree(slug, item_number)
+                _remove_worktree(project_path, str(wt))
+                rprint("[dim]Worktree cleaned up.[/dim]")
+            else:
+                rprint("[red]Merge failed — conflicts detected.[/red]")
+                api_put(f"/api/work-items/{item_id}", json={"status": "in_review"})
+                rprint("[dim]Status -> in_review (manual merge needed)[/dim]")
+        else:
+            rprint("[yellow]Could not detect branch — skipping merge.[/yellow]")
+    else:
+        rprint("[dim]Auto-merge disabled. Merge manually when ready.[/dim]")
+
+
+@app.command(name="continue")
+def continue_work(
+    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to continue"),
+):
+    """Continue a previous agent run (reads prior comments for context)."""
+    execute(id_or_number, no_worktree=False, cleanup=False)
+
+
+@app.command()
+def verify(
+    id_or_number: str = typer.Argument(..., help="Work item ID, number, or KEY-number to verify"),
+):
+    """Phase 0: Verify requirements — analyse feasibility and return READY or NEEDS_INFO verdict."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    rprint(f"[cyan]Fetching work item {id_or_number}...[/cyan]")
+    item = _resolve_item(slug, id_or_number)
+    item_id = item["id"]
+    key = item.get("key") or f"#{item['number']}"
+    knowledge = _read_knowledge(project_path)
+    comments = _get_item_comments(item_id)
+    comments_ctx = _format_comments_context(comments)
+    prompt = _build_verify_prompt(item, knowledge, comments_ctx)
+
+    rprint(f"[cyan]Running requirement analysis for {key}...[/cyan]")
+
+    # Create session for streaming
+    session_id = None
+    try:
+        session = api_post(
+            "/api/agent-sessions/start",
+            json={"work_item_id": item_id, "origin": "cli", "phase": "verify"},
+            params={"project_slug": slug},
+        )
+        session_id = session["id"]
+    except Exception:
+        pass
+
+    streamer = None
+    if session_id:
+        streamer = AgentStreamer(session_id)
+        streamer.start()
+        update_phase(session_id, "verify")
+
+    try:
+        proc = subprocess.Popen(
+            ["claude", "-p", prompt, "--output-format", "stream-json"],
+            cwd=project_path,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=_claude_env(),
+        )
+
+        for line in proc.stdout:
+            if streamer:
+                streamer.feed(line)
+
+        proc.wait()
+
+        text_blocks = streamer.stop() if streamer else []
+
+        if proc.returncode != 0:
+            stderr_out = proc.stderr.read() if proc.stderr else ""
+            rprint(f"[red]Claude analysis failed:[/red]\n{stderr_out}")
+            if session_id:
+                complete_session(session_id, "failed", error=f"Exit code {proc.returncode}")
+            raise typer.Exit(1)
+
+        analysis = "\n\n".join(text_blocks) if text_blocks else ""
+        if not analysis:
+            rprint("[red]Claude returned an empty response.[/red]")
+            if session_id:
+                complete_session(session_id, "failed", error="Empty response")
+            raise typer.Exit(1)
+
+        rprint()
+        rprint(Panel(
+            Markdown(analysis),
+            title=f"Requirement Analysis -- {key}",
+            border_style="cyan",
+        ))
+
+        # Parse verdict from output
+        analysis_upper = analysis.upper()
+        if "VERDICT: READY" in analysis_upper:
+            verdict = "ready"
+        elif "VERDICT: NEEDS_INFO" in analysis_upper:
+            verdict = "needs_info"
+        else:
+            rprint("[yellow]No explicit verdict found in analysis. Defaulting to READY.[/yellow]")
+            verdict = "ready"
+
+        if verdict == "ready":
+            # Post as proposal comment and save plan
+            api_post(f"/api/work-items/{item_id}/comments", json={
+                "body": analysis,
+                "author": "bb-agent",
+                "type": "proposal",
+            })
+            rprint("[green]Analysis posted as proposal comment.[/green]")
+
+            api_put(f"/api/work-items/{item_id}", json={"plan": analysis})
+            rprint("[green]Plan saved to work item.[/green]")
+
+            if item["status"] == "open":
+                api_put(f"/api/work-items/{item_id}", json={"status": "confirmed"})
+                rprint("[dim]Status -> confirmed[/dim]")
+
+            if session_id:
+                complete_session(session_id, "completed")
+            rprint(f"\n[green]VERDICT: READY — {key} is ready for implementation.[/green]")
+        else:
+            # Post as analysis comment, set needs_info
+            api_post(f"/api/work-items/{item_id}/comments", json={
+                "body": analysis,
+                "author": "bb-agent",
+                "type": "analysis",
+            })
+            rprint("[yellow]Analysis posted as comment.[/yellow]")
+
+            api_put(f"/api/work-items/{item_id}", json={"status": "needs_info"})
+            rprint("[dim]Status -> needs_info[/dim]")
+
+            if session_id:
+                complete_session(session_id, "failed", error="NEEDS_INFO")
+            rprint(f"\n[yellow]VERDICT: NEEDS_INFO — {key} requires clarification before implementation.[/yellow]")
+            raise typer.Exit(1)
+
+    except FileNotFoundError:
+        if streamer:
+            streamer.stop()
+        rprint("[red]'claude' CLI not found. Install Claude Code first.[/red]")
+        raise typer.Exit(1)
+
+
+@app.command(name="status")
+def agent_status():
+    """Show agent sessions for the current project."""
+    slug = _require_project()
+    sessions = api_get("/api/agent-sessions", params={"project_slug": slug})
+    if not sessions:
+        rprint("[dim]No agent sessions.[/dim]")
+        return
+    for s in sessions:
+        color = {"running": "yellow", "completed": "green", "failed": "red"}.get(
+            s["status"], "white"
+        )
+        rprint(
+            f"  [{color}]{s['status']:>10}[/{color}]  "
+            f"{s['id'][:8]}  item: {s.get('work_item_id', '--')}"
+        )
+
+
+@app.command()
+def abort(session_id: str = typer.Argument(...)):
+    """Abort a running agent session."""
+    api_post(f"/api/agent-sessions/{session_id}/abort")
+    rprint(f"[yellow]Session {session_id[:8]} aborted.[/yellow]")
+
+
+def _detect_worktree_branch(project_path: str, wt_path: Path) -> str | None:
+    """Detect the branch name for a worktree directory from git metadata."""
+    probe = subprocess.run(
+        ["git", "worktree", "list", "--porcelain"],
+        cwd=project_path, capture_output=True, text=True,
+    )
+    wt_norm = str(wt_path).replace("\\", "/")
+    lines = probe.stdout.splitlines()
+    for i, ln in enumerate(lines):
+        if wt_norm in ln.replace("\\", "/"):
+            # Next line with "branch" has the ref
+            for j in range(i + 1, min(i + 5, len(lines))):
+                if lines[j].startswith("branch "):
+                    return lines[j].replace("branch refs/heads/", "")
+            break
+    return None
+
+
+@app.command(name="cleanup")
+def cleanup_worktree(
+    item_number: int = typer.Argument(..., help="Work item number whose worktree to remove"),
+    delete_branch: bool = typer.Option(False, "--delete-branch", "-D", help="Also delete the git branch"),
+):
+    """Remove the worktree created for a work item."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    wt = _find_worktree(slug, item_number)
+
+    if not wt.exists():
+        rprint(f"[yellow]No worktree found for item #{item_number}.[/yellow]")
+        raise typer.Exit()
+
+    # Detect branch before removing worktree
+    branch = _detect_worktree_branch(project_path, wt)
+
+    _remove_worktree(project_path, str(wt))
+    rprint(f"[green]Worktree removed: {wt}[/green]")
+
+    if delete_branch and branch:
+        subprocess.run(
+            ["git", "branch", "-D", branch],
+            cwd=project_path, capture_output=True,
+        )
+        rprint(f"[green]Branch deleted: {branch}[/green]")
+    elif branch:
+        rprint(f"[dim]Branch '{branch}' kept. Delete with: git branch -D {branch}[/dim]")
+    else:
+        rprint("[dim]Could not detect branch name (worktree may have been stale).[/dim]")
+
+
+@app.command(name="worktrees")
+def list_worktrees():
+    """List active agent worktrees for the current project."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    result = subprocess.run(
+        ["git", "worktree", "list"],
+        cwd=project_path, capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        rprint("[red]Failed to list worktrees.[/red]")
+        raise typer.Exit(1)
+
+    # Filter to worktrees under our managed directory
+    wt_dir = str(WORKTREES_DIR / slug).replace("\\", "/")
+    lines = result.stdout.strip().splitlines()
+    bb_lines = [ln for ln in lines if wt_dir in ln.replace("\\", "/")]
+
+    if not bb_lines:
+        rprint("[dim]No agent worktrees.[/dim]")
+        return
+
+    rprint("[bold]Agent worktrees:[/bold]")
+    for ln in bb_lines:
+        rprint(f"  {ln}")
+
+
+# ---------------------------------------------------------------------------
+# Batch (parallel) commands
+# ---------------------------------------------------------------------------
+
+
+@app.command(name="batch-suggest")
+def batch_suggest(
+    items: list[str] = typer.Argument(None, help="Work item IDs/numbers to analyse (e.g. BD-2 BD-3 BD-4)"),
+    all_open: bool = typer.Option(False, "--all", "-A", help="Suggest all open items in the project"),
+    max_parallel: int = typer.Option(3, "--parallel", "-P", help="Max parallel Claude analyses"),
+):
+    """Analyse multiple work items in parallel. Each gets a proposal comment."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    if all_open:
+        open_items = api_get(f"/api/projects/{slug}/work-items", params={"status": "open"})
+        # Exclude epics — they contain children, not implementable directly
+        open_items = [i for i in open_items if i.get("type") != "epic"]
+        if not open_items:
+            rprint("[yellow]No open items found.[/yellow]")
+            return
+        items = [i.get("key") or str(i["number"]) for i in open_items]
+        rprint(f"[cyan]Found {len(items)} open items: {', '.join(items)}[/cyan]")
+    elif not items:
+        rprint("[red]Provide item IDs or use --all flag.[/red]")
+        raise typer.Exit(1)
+
+    rprint(f"[cyan]Suggesting {len(items)} items (max {max_parallel} parallel)...[/cyan]\n")
+
+    results: list[dict] = []
+    with AgentProgressTracker() as tracker:
+        for item_ref in items:
+            tracker.register(item_ref)
+
+        with ThreadPoolExecutor(max_workers=max_parallel) as pool:
+            futures = {
+                pool.submit(_suggest_one, slug, project_path, item, tracker=tracker): item
+                for item in items
+            }
+            for future in as_completed(futures):
+                item_ref = futures[future]
+                try:
+                    r = future.result()
+                    results.append(r)
+                    tracker.complete(item_ref, r["status"] == "ok",
+                                     r.get("error", "Done") if r["status"] != "ok" else "Done")
+                except Exception as e:
+                    results.append({"key": item_ref, "status": "error", "error": str(e)})
+                    tracker.complete(item_ref, False, str(e)[:60])
+
+    ok = sum(1 for r in results if r["status"] == "ok")
+    rprint(f"\n[bold]Done: {ok}/{len(items)} succeeded.[/bold]")
+
+    if ok > 0:
+        rprint("\n[dim]Review suggestions, then run:[/dim]")
+        suggested = [r["key"] for r in results if r["status"] == "ok"]
+        rprint(f"[dim]  bb agent batch-execute {' '.join(suggested)}[/dim]")
+
+
+@app.command(name="batch-execute")
+def batch_execute(
+    items: list[str] = typer.Argument(..., help="Work item IDs/numbers to implement (e.g. BD-2 BD-3 BD-4)"),
+    max_parallel: int = typer.Option(2, "--parallel", "-P", help="Max parallel Claude agents"),
+):
+    """Implement multiple work items in parallel. Each gets its own git worktree."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    rprint(f"[cyan]Executing {len(items)} items (max {max_parallel} parallel, each in own worktree)...[/cyan]\n")
+
+    results: list[dict] = []
+    with AgentProgressTracker() as tracker:
+        for item_ref in items:
+            tracker.register(item_ref)
+
+        with ThreadPoolExecutor(max_workers=max_parallel) as pool:
+            futures = {
+                pool.submit(_execute_one, slug, project_path, item, tracker=tracker): item
+                for item in items
+            }
+            for future in as_completed(futures):
+                item_ref = futures[future]
+                try:
+                    r = future.result()
+                    results.append(r)
+                    tracker.complete(item_ref, r["status"] == "ok",
+                                     r.get("branch", r.get("error", "Done"))[:60])
+                except Exception as e:
+                    results.append({"key": item_ref, "status": "error", "error": str(e)})
+                    tracker.complete(item_ref, False, str(e)[:60])
+
+    ok = sum(1 for r in results if r["status"] == "ok")
+    rprint(f"\n[bold]Done: {ok}/{len(items)} succeeded.[/bold]")
+
+    branches = [r["branch"] for r in results if r.get("branch")]
+    if branches:
+        table = Table(title="Branches Created", show_header=True)
+        table.add_column("Item")
+        table.add_column("Branch")
+        table.add_column("Status")
+        for r in results:
+            if r.get("branch"):
+                color = "green" if r["status"] == "ok" else "red"
+                table.add_row(r["key"], r["branch"], f"[{color}]{r['status']}[/{color}]")
+        rprint(table)
+        rprint(f"\n[dim]Merge all with: bb agent merge --target release/dev[/dim]")
+
+
+@app.command(name="batch-run")
+def batch_run(
+    items: list[str] = typer.Argument(..., help="Work item IDs/numbers for full loop"),
+    max_parallel: int = typer.Option(2, "--parallel", "-P", help="Max parallel agents"),
+    auto_merge: bool = typer.Option(False, "--auto-merge", help="Auto-merge passing items to target"),
+    target: str = typer.Option("release/dev", "--target", "-t", help="Target branch for auto-merge"),
+):
+    """Execute -> test -> merge for multiple items. Run 'bb agent batch-suggest' separately first."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    # Phase 1: parallel execute
+    rprint(f"[bold cyan]Phase 1: Implementing {len(items)} items (max {max_parallel} parallel)...[/bold cyan]\n")
+    exec_results: list[dict] = []
+    with AgentProgressTracker() as tracker:
+        for item_ref in items:
+            tracker.register(item_ref)
+
+        with ThreadPoolExecutor(max_workers=max_parallel) as pool:
+            futures = {
+                pool.submit(_execute_one, slug, project_path, item, tracker=tracker): item
+                for item in items
+            }
+            for future in as_completed(futures):
+                item_ref = futures[future]
+                try:
+                    r = future.result()
+                    exec_results.append(r)
+                    tracker.complete(item_ref, r["status"] == "ok",
+                                     r.get("branch", r.get("error", ""))[:60])
+                except Exception as e:
+                    exec_results.append({"key": item_ref, "status": "error", "error": str(e)})
+                    tracker.complete(item_ref, False, str(e)[:60])
+
+    executed = [r["key"] for r in exec_results if r["status"] == "ok"]
+    ok = len(executed)
+    rprint(f"\n[bold]Execute done: {ok}/{len(items)} succeeded.[/bold]")
+
+    if not executed:
+        return
+
+    # Phase 2: parallel Docker test
+    rprint("\n[bold cyan]Phase 2: Docker testing...[/bold cyan]\n")
+    test_results: list[dict] = []
+    with AgentProgressTracker() as tracker:
+        for item_ref in executed:
+            tracker.register(item_ref)
+
+        with ThreadPoolExecutor(max_workers=max_parallel) as pool:
+            futures = {
+                pool.submit(_docker_test_one, slug, project_path, item): item
+                for item in executed
+            }
+            for future in as_completed(futures):
+                item_ref = futures[future]
+                try:
+                    r = future.result()
+                    test_results.append(r)
+                    tracker.complete(item_ref, r["status"] == "ok",
+                                     r.get("details", "")[:60])
+                except Exception as e:
+                    test_results.append({"key": item_ref, "status": "error", "details": str(e)})
+                    tracker.complete(item_ref, False, str(e)[:60])
+
+    passed = [r["key"] for r in test_results if r["status"] == "ok"]
+    failed = [r["key"] for r in test_results if r["status"] != "ok"]
+    rprint(f"\n[bold]Test done: {len(passed)}/{len(executed)} passed.[/bold]")
+
+    # Phase 3: merge passing items
+    if auto_merge and passed:
+        rprint(f"\n[bold cyan]Phase 3: Merging to {target}...[/bold cyan]\n")
+        for item_key in passed:
+            try:
+                item = _resolve_item(slug, item_key)
+                item_number = item["number"]
+                wt = _find_worktree(slug, item_number)
+                branch_name = _detect_worktree_branch(project_path, wt)
+                if branch_name:
+                    merge_ok = _do_single_merge(project_path, branch_name, target)
+                    if merge_ok:
+                        rprint(f"  [green]{item_key:>8} -- merged[/green]")
+                        api_put(f"/api/work-items/{item['id']}", json={"status": "resolved"})
+                        _remove_worktree(project_path, str(wt))
+                    else:
+                        rprint(f"  [red]{item_key:>8} -- merge conflict[/red]")
+            except Exception as e:
+                rprint(f"  [red]{item_key:>8} -- merge error: {e}[/red]")
+    elif not auto_merge and passed:
+        rprint("[dim]Merge with: bb agent merge --target release/dev[/dim]")
+
+    if failed:
+        rprint(f"\n[yellow]Failed items: {' '.join(failed)}[/yellow]")
+        rprint(f"[dim]Re-implement: bb agent reimplement <item>[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# Merge command
+# ---------------------------------------------------------------------------
+
+
+def _list_agent_branches(project_path: str) -> list[str]:
+    """List all agent branches (both new and legacy naming conventions)."""
+    # New convention: {prefix}/{key}_{slug} — we look for known prefixes
+    prefixes = list(set(TYPE_BRANCH_PREFIX.values()))  # feat, fix, task, epic, chore, spike
+    all_branches: list[str] = []
+
+    for prefix in prefixes:
+        result = subprocess.run(
+            ["git", "branch", "--list", f"{prefix}/*"],
+            cwd=project_path, capture_output=True, text=True,
+        )
+        all_branches.extend(
+            b.strip().lstrip("* ") for b in result.stdout.strip().splitlines() if b.strip()
+        )
+
+    # Legacy convention: bb/item-*
+    result = subprocess.run(
+        ["git", "branch", "--list", "bb/item-*"],
+        cwd=project_path, capture_output=True, text=True,
+    )
+    all_branches.extend(
+        b.strip().lstrip("* ") for b in result.stdout.strip().splitlines() if b.strip()
+    )
+
+    return sorted(set(all_branches))
+
+
+def _extract_item_number_from_branch(branch: str) -> int | None:
+    """Extract item number from branch name (supports both conventions).
+
+    New:    feat/bb-42_some-title  -> 42
+    Legacy: bb/item-42             -> 42
+    """
+    # Legacy: bb/item-{N}
+    if branch.startswith("bb/item-"):
+        try:
+            return int(branch.replace("bb/item-", ""))
+        except ValueError:
+            return None
+    # New: {prefix}/{key}_{slug} where key is like bb-42 or item-42
+    m = re.search(r"/(?:[a-z]+-)?(\d+)", branch)
+    if m:
+        return int(m.group(1))
+    return None
+
+
+@app.command(name="merge")
+def merge_branches(
+    target: str = typer.Option("release/dev", "--target", "-t", help="Target branch to merge into"),
+    items: list[str] = typer.Argument(None, help="Specific item numbers (default: all agent branches)"),
+    cleanup_after: bool = typer.Option(False, "--cleanup", help="Remove worktrees + branches after successful merge"),
+    use_agent: bool = typer.Option(False, "--agent", help="Use Claude to resolve merge conflicts"),
+):
+    """Merge agent branches into a target branch (e.g. release/dev)."""
+    slug = _require_project()
+    project_path = _require_project_path(slug)
+
+    # Remember current branch
+    current = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        cwd=project_path, capture_output=True, text=True,
+    ).stdout.strip()
+
+    all_branches = _list_agent_branches(project_path)
+
+    if items:
+        wanted_nums = {int(n) for n in items}
+        branches = [
+            b for b in all_branches
+            if _extract_item_number_from_branch(b) in wanted_nums
+        ]
+    else:
+        branches = all_branches
+
+    if not branches:
+        rprint("[yellow]No agent branches found to merge.[/yellow]")
+        return
+
+    rprint(f"[cyan]Merging {len(branches)} branches into {target}...[/cyan]\n")
+    for b in branches:
+        rprint(f"  {b}")
+    rprint()
+
+    # Ensure target branch exists
+    check = subprocess.run(
+        ["git", "rev-parse", "--verify", target],
+        cwd=project_path, capture_output=True, text=True,
+    )
+    if check.returncode != 0:
+        rprint(f"[yellow]Branch '{target}' does not exist. Creating from HEAD...[/yellow]")
+        subprocess.run(
+            ["git", "branch", target],
+            cwd=project_path, check=True, capture_output=True,
+        )
+
+    # Prune stale worktrees
+    subprocess.run(["git", "worktree", "prune"], cwd=project_path, capture_output=True)
+
+    # Checkout target branch
+    co = subprocess.run(
+        ["git", "checkout", target],
+        cwd=project_path, capture_output=True, text=True,
+    )
+    if co.returncode != 0:
+        rprint(f"[red]Failed to checkout {target}: {co.stderr}[/red]")
+        return
+
+    merged: list[str] = []
+    failed: list[tuple[str, str]] = []
+
+    for branch in branches:
+        rprint(f"  Merging {branch}...", end=" ")
+        merge_result = subprocess.run(
+            ["git", "merge", branch, "--no-ff", "-m", f"Merge {branch} into {target}"],
+            cwd=project_path, capture_output=True, text=True,
+        )
+        if merge_result.returncode == 0:
+            rprint("[green]ok[/green]")
+            merged.append(branch)
+        else:
+            if use_agent:
+                rprint("[yellow]conflict -> resolving with Claude...[/yellow]")
+                subprocess.run(
+                    ["claude", "-p",
+                     f"Resolve all merge conflicts in this git repo. The merge of '{branch}' into '{target}' has conflicts. "
+                     f"Use 'git diff' to find conflicts, resolve them keeping both sets of changes where possible, "
+                     f"then stage and commit. Do NOT abort the merge.",
+                     "--output-format", "text",
+                     "--permission-mode", "bypassPermissions"],
+                    cwd=project_path, capture_output=True, text=True,
+                    timeout=300, env=_claude_env(),
+                )
+                # Check if conflicts are resolved
+                status_check = subprocess.run(
+                    ["git", "diff", "--name-only", "--diff-filter=U"],
+                    cwd=project_path, capture_output=True, text=True,
+                )
+                if status_check.stdout.strip() == "":
+                    rprint(f"    [green]Conflict resolved by agent[/green]")
+                    merged.append(branch)
+                else:
+                    rprint(f"    [red]Agent could not resolve all conflicts[/red]")
+                    subprocess.run(["git", "merge", "--abort"], cwd=project_path, capture_output=True)
+                    failed.append((branch, "conflict (agent failed)"))
+            else:
+                rprint("[red]CONFLICT[/red]")
+                subprocess.run(["git", "merge", "--abort"], cwd=project_path, capture_output=True)
+                failed.append((branch, "conflict"))
+
+    # Summary
+    rprint()
+    table = Table(title=f"Merge Results -> {target}", show_header=True)
+    table.add_column("Branch")
+    table.add_column("Status")
+    for b in merged:
+        table.add_row(b, "[green]merged[/green]")
+    for b, reason in failed:
+        table.add_row(b, f"[red]{reason}[/red]")
+    rprint(table)
+
+    # Cleanup if requested
+    if cleanup_after and merged:
+        for branch in merged:
+            num = _extract_item_number_from_branch(branch)
+            if num is not None:
+                try:
+                    wt = _find_worktree(slug, num)
+                    if wt.exists():
+                        _remove_worktree(project_path, str(wt))
+                except Exception:
+                    pass
+            subprocess.run(
+                ["git", "branch", "-D", branch],
+                cwd=project_path, capture_output=True,
+            )
+        rprint("[dim]Cleaned up merged worktrees and branches.[/dim]")
+
+    if failed:
+        rprint("\n[yellow]Failed branches can be retried:[/yellow]")
+        rprint("[dim]  bb agent merge --agent  (use Claude to resolve conflicts)[/dim]")
+        rprint("[dim]  or resolve manually: git checkout {target} && git merge {branch}[/dim]")
+
+    # Return to original branch
+    subprocess.run(
+        ["git", "checkout", current],
+        cwd=project_path, capture_output=True,
+    )