codex-autorunner 1.1.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

codex_autorunner/surfaces/cli/cli.py

@@ -28,12 +28,39 @@ from ...core.config import (
     load_hub_config,
     load_repo_config,
 )
-from ...core.engine import DoctorReport, Engine, LockError, clear_stale_lock, doctor
+from ...core.flows import FlowController, FlowStore
+from ...core.flows.models import FlowRunRecord, FlowRunStatus
+from ...core.flows.ux_helpers import build_flow_status_snapshot, ensure_worker
+from ...core.flows.worker_process import (
+    check_worker_health,
+    clear_worker_metadata,
+    register_worker_metadata,
+)
 from ...core.git_utils import GitError, run_git
 from ...core.hub import HubSupervisor
+from ...core.locks import file_lock
 from ...core.logging_utils import log_event, setup_rotating_logger
 from ...core.optional_dependencies import require_optional_dependencies
+from ...core.runtime import (
+    DoctorReport,
+    RuntimeContext,
+    clear_stale_lock,
+    doctor,
+    hub_worktree_doctor_checks,
+    pma_doctor_checks,
+)
 from ...core.state import RunnerState, load_state, now_iso, save_state, state_lock
+from ...core.templates import (
+    NetworkUnavailableError,
+    RefNotFoundError,
+    RepoNotConfiguredError,
+    TemplateNotFoundError,
+    fetch_template,
+    get_scan_record,
+    inject_provenance,
+    parse_template_ref,
+    scan_lock,
+)
 from ...core.usage import (
     UsageError,
     default_codex_home,
@@ -41,7 +68,9 @@ from ...core.usage import (
     summarize_hub_usage,
     summarize_repo_usage,
 )
-from ...core.utils import RepoNotFoundError, default_editor, find_repo_root
+from ...core.utils import RepoNotFoundError, default_editor, find_repo_root, is_within
+from ...flows.ticket_flow import build_ticket_flow_definition
+from ...integrations.agents import build_backend_orchestrator
 from ...integrations.agents.wiring import (
     build_agent_backend_factory,
     build_app_server_supervisor_factory,
@@ -55,15 +84,39 @@ from ...integrations.telegram.service import (
     TelegramBotService,
 )
 from ...integrations.telegram.state import TelegramStateStore
+from ...integrations.templates.scan_agent import (
+    TemplateScanError,
+    TemplateScanRejectedError,
+    format_template_scan_rejection,
+    run_template_scan,
+)
 from ...manifest import load_manifest
+from ...tickets import AgentPool
+from ...tickets.files import (
+    list_ticket_paths,
+    read_ticket,
+    safe_relpath,
+    ticket_is_done,
+)
+from ...tickets.frontmatter import split_markdown_frontmatter
+from ...tickets.lint import (
+    lint_ticket_directory,
+    parse_ticket_index,
+)
 from ...voice import VoiceConfig
 from ..web.app import create_hub_app
+from .pma_cli import pma_app as pma_cli_app
 
 logger = logging.getLogger("codex_autorunner.cli")
 
 app = typer.Typer(add_completion=False)
 hub_app = typer.Typer(add_completion=False)
 telegram_app = typer.Typer(add_completion=False)
+templates_app = typer.Typer(add_completion=False)
+repos_app = typer.Typer(add_completion=False)
+worktree_app = typer.Typer(add_completion=False)
+flow_app = typer.Typer(add_completion=False)
+ticket_flow_app = typer.Typer(add_completion=False)
 
 
 def main() -> None:
@@ -78,20 +131,18 @@ def _raise_exit(message: str, *, cause: Optional[BaseException] = None) -> NoRet
     raise typer.Exit(code=1)
 
 
-def _require_repo_config(repo: Optional[Path], hub: Optional[Path]) -> Engine:
+def _require_repo_config(repo: Optional[Path], hub: Optional[Path]) -> RuntimeContext:
     try:
         repo_root = find_repo_root(repo or Path.cwd())
     except RepoNotFoundError as exc:
         _raise_exit("No .git directory found for repo commands.", cause=exc)
     try:
         config = load_repo_config(repo_root, hub_path=hub)
-        return Engine(
+        backend_orchestrator = build_backend_orchestrator(repo_root, config)
+        return RuntimeContext(
             repo_root,
             config=config,
-            hub_path=hub,
-            backend_factory=build_agent_backend_factory(repo_root, config),
-            app_server_supervisor_factory=build_app_server_supervisor_factory(config),
-            agent_id_validator=validate_agent_id,
+            backend_orchestrator=backend_orchestrator,
         )
     except ConfigError as exc:
         _raise_exit(str(exc), cause=exc)
@@ -104,6 +155,161 @@ def _require_hub_config(path: Optional[Path]) -> HubConfig:
         _raise_exit(str(exc), cause=exc)
 
 
+def _load_hub_config_yaml(path: Path) -> dict:
+    if not path.exists():
+        _raise_exit(f"Hub config file not found: {path}")
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            _raise_exit(f"Hub config must be a YAML mapping: {path}")
+        return data
+    except yaml.YAMLError as exc:
+        _raise_exit(f"Invalid YAML in hub config: {exc}", cause=exc)
+    except OSError as exc:
+        _raise_exit(f"Failed to read hub config: {exc}", cause=exc)
+
+
+def _write_hub_config_yaml(path: Path, data: dict) -> None:
+    lock_path = path.parent / (path.name + ".lock")
+    with file_lock(lock_path):
+        path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+
+
+def _require_templates_enabled(config: RepoConfig) -> None:
+    if not config.templates.enabled:
+        _raise_exit(
+            "Templates are disabled. Set templates.enabled=true in the hub config to enable."
+        )
+
+
+def _find_template_repo(config: RepoConfig, repo_id: str):
+    for repo in config.templates.repos:
+        if repo.id == repo_id:
+            return repo
+    return None
+
+
+def _fetch_template_with_scan(template: str, ctx: RuntimeContext, hub: Optional[Path]):
+    try:
+        parsed = parse_template_ref(template)
+    except ValueError as exc:
+        _raise_exit(str(exc), cause=exc)
+
+    repo_cfg = _find_template_repo(ctx.config, parsed.repo_id)
+    if repo_cfg is None:
+        _raise_exit(f"Template repo not configured: {parsed.repo_id}")
+
+    hub_config_path = _resolve_hub_config_path_for_cli(ctx.repo_root, hub)
+    if hub_config_path is None:
+        try:
+            hub_config = load_hub_config(ctx.repo_root)
+            hub_root = hub_config.root
+        except ConfigError as exc:
+            _raise_exit(str(exc), cause=exc)
+    else:
+        hub_root = hub_config_path.parent.parent.resolve()
+
+    try:
+        fetched = fetch_template(
+            repo=repo_cfg, hub_root=hub_root, template_ref=template
+        )
+    except NetworkUnavailableError as exc:
+        _raise_exit(
+            f"{str(exc)}\n"
+            "Hint: Fetch once while online to seed the cache. "
+            "If this template is untrusted, scanning may also require a working agent backend."
+        )
+    except (
+        RepoNotConfiguredError,
+        RefNotFoundError,
+        TemplateNotFoundError,
+        GitError,
+    ) as exc:
+        _raise_exit(str(exc), cause=exc)
+
+    scan_record = None
+    if not fetched.trusted:
+        with scan_lock(hub_root, fetched.blob_sha):
+            scan_record = get_scan_record(hub_root, fetched.blob_sha)
+            if scan_record is None:
+                try:
+                    scan_record = asyncio.run(
+                        run_template_scan(ctx=ctx, template=fetched)
+                    )
+                except TemplateScanRejectedError as exc:
+                    _raise_exit(str(exc), cause=exc)
+                except TemplateScanError as exc:
+                    _raise_exit(str(exc), cause=exc)
+            elif scan_record.decision != "approve":
+                _raise_exit(format_template_scan_rejection(scan_record))
+
+    return fetched, scan_record, hub_root
+
+
+def _resolve_ticket_dir(repo_root: Path, ticket_dir: Optional[Path]) -> Path:
+    if ticket_dir is None:
+        return repo_root / ".codex-autorunner" / "tickets"
+    if ticket_dir.is_absolute():
+        return ticket_dir
+    return repo_root / ticket_dir
+
+
+def _collect_ticket_indices(ticket_dir: Path) -> list[int]:
+    indices: list[int] = []
+    if not ticket_dir.exists() or not ticket_dir.is_dir():
+        return indices
+    for path in ticket_dir.iterdir():
+        if not path.is_file():
+            continue
+        idx = parse_ticket_index(path.name)
+        if idx is None:
+            continue
+        indices.append(idx)
+    return indices
+
+
+def _next_available_ticket_index(existing: list[int]) -> int:
+    if not existing:
+        return 1
+    seen = set(existing)
+    candidate = 1
+    while candidate in seen:
+        candidate += 1
+    return candidate
+
+
+def _ticket_filename(index: int, *, suffix: str, width: int) -> str:
+    return f"TICKET-{index:0{width}d}{suffix}.md"
+
+
+def _normalize_ticket_suffix(suffix: Optional[str]) -> str:
+    if not suffix:
+        return ""
+    cleaned = suffix.strip()
+    if not cleaned:
+        return ""
+    if "/" in cleaned or "\\" in cleaned:
+        _raise_exit("Ticket suffix may not include path separators.")
+    if not cleaned.startswith("-"):
+        return f"-{cleaned}"
+    return cleaned
+
+
+def _apply_agent_override(content: str, agent: str) -> str:
+    fm_yaml, body = split_markdown_frontmatter(content)
+    if fm_yaml is None:
+        _raise_exit("Template is missing YAML frontmatter; cannot set agent.")
+    try:
+        data = yaml.safe_load(fm_yaml)
+    except yaml.YAMLError as exc:
+        _raise_exit(f"Template frontmatter is invalid YAML: {exc}")
+    if not isinstance(data, dict):
+        _raise_exit("Template frontmatter must be a YAML mapping to set agent.")
+    data["agent"] = agent
+    rendered = yaml.safe_dump(data, sort_keys=False).rstrip()
+    return f"---\n{rendered}\n---{body}"
+
+
 def _build_server_url(config, path: str) -> str:
     base_path = config.server_base_path or ""
     if base_path.endswith("/") and path.startswith("/"):
@@ -122,6 +328,39 @@ def _resolve_hub_config_path_for_cli(
     return find_nearest_hub_config_path(repo_root)
 
 
+def _guard_unregistered_hub_repo(repo_root: Path, hub: Optional[Path]) -> None:
+    hub_config_path = _resolve_hub_config_path_for_cli(repo_root, hub)
+    if hub_config_path is None:
+        return
+    try:
+        hub_config = load_hub_config(hub_config_path)
+    except ConfigError as exc:
+        _raise_exit(str(exc), cause=exc)
+
+    repo_root = repo_root.resolve()
+    under_repos = is_within(hub_config.repos_root, repo_root)
+    under_worktrees = is_within(hub_config.worktrees_root, repo_root)
+    if not (under_repos or under_worktrees):
+        return
+
+    manifest = load_manifest(hub_config.manifest_path, hub_config.root)
+    if manifest.get_by_path(hub_config.root, repo_root) is not None:
+        return
+
+    lines = [
+        "Repo not registered in hub manifest. Run car hub scan or create via car hub worktree create.",
+        f"Detected hub root: {hub_config.root}",
+        f"Repo path: {repo_root}",
+        "Runs won't show up in the hub UI until registered.",
+    ]
+    if under_worktrees:
+        lines.append(
+            "Hint: Worktree names should look like <base_repo_id>--<branch> under "
+            f"{hub_config.worktrees_root}"
+        )
+    _raise_exit("\n".join(lines))
+
+
 def _resolve_repo_api_path(repo_root: Path, hub: Optional[Path], path: str) -> str:
     if not path.startswith("/"):
         path = f"/{path}"
@@ -223,7 +462,14 @@ def _require_optional_feature(
 
 
 app.add_typer(hub_app, name="hub")
+hub_app.add_typer(worktree_app, name="worktree")
 app.add_typer(telegram_app, name="telegram")
+app.add_typer(templates_app, name="templates")
+templates_app.add_typer(repos_app, name="repos")
+app.add_typer(flow_app, name="flow")
+app.add_typer(ticket_flow_app, name="ticket-flow")
+flow_app.add_typer(ticket_flow_app, name="ticket_flow")
+app.add_typer(pma_cli_app, name="pma")
 
 
 def _has_nested_git(path: Path) -> bool:
@@ -317,7 +563,6 @@ def status(
     """Show autorunner status."""
     engine = _require_repo_config(repo, hub)
     state = load_state(engine.state_path)
-    outstanding, _ = engine.docs.todos()
     repo_key = str(engine.repo_root)
     session_id = state.repo_to_session.get(repo_key) or state.repo_to_session.get(
         f"{repo_key}:codex"
@@ -367,7 +612,6 @@ def status(
                 if opencode_record
                 else None
             ),
-            "outstanding_todos": len(outstanding),
         }
         typer.echo(json.dumps(payload, indent=2))
         return
@@ -391,7 +635,340 @@ def status(
         if opencode_record:
             detail = f" (status={opencode_record.status}, last_seen={opencode_record.last_seen_at})"
         typer.echo(f"Terminal session (opencode): {opencode_session_id}{detail}")
-    typer.echo(f"Outstanding TODO items: {len(outstanding)}")
+
+
+@templates_app.command("fetch")
+def templates_fetch(
+    template: str = typer.Argument(
+        ..., help="Template ref formatted as REPO_ID:PATH[@REF]"
+    ),
+    out: Optional[Path] = typer.Option(
+        None, "--out", help="Write template content to a file"
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output"),
+    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+):
+    """Fetch a template from a configured templates repo."""
+    ctx = _require_repo_config(repo, hub)
+    _require_templates_enabled(ctx.config)
+    fetched, scan_record, _hub_root = _fetch_template_with_scan(template, ctx, hub)
+
+    if out is not None:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(fetched.content, encoding="utf-8")
+        typer.echo(f"Wrote template to {out}", err=True)
+
+    if output_json:
+        payload = {
+            "content": fetched.content,
+            "repo_id": fetched.repo_id,
+            "path": fetched.path,
+            "ref": fetched.ref,
+            "commit_sha": fetched.commit_sha,
+            "blob_sha": fetched.blob_sha,
+            "trusted": fetched.trusted,
+            "scan_decision": scan_record.to_dict() if scan_record else None,
+        }
+        typer.echo(json.dumps(payload, indent=2))
+        return
+
+    if out is None:
+        typer.echo(fetched.content, nl=False)
+
+
+@templates_app.command("apply")
+def templates_apply(
+    template: str = typer.Argument(
+        ..., help="Template ref formatted as REPO_ID:PATH[@REF]"
+    ),
+    ticket_dir: Optional[Path] = typer.Option(
+        None,
+        "--ticket-dir",
+        help="Ticket directory (default .codex-autorunner/tickets)",
+    ),
+    at: Optional[int] = typer.Option(None, "--at", help="Explicit ticket index"),
+    next_index: bool = typer.Option(
+        True, "--next/--no-next", help="Use next available index (default)"
+    ),
+    suffix: Optional[str] = typer.Option(
+        None, "--suffix", help="Optional filename suffix (e.g. -foo)"
+    ),
+    set_agent: Optional[str] = typer.Option(
+        None, "--set-agent", help="Override frontmatter agent"
+    ),
+    provenance: bool = typer.Option(
+        False,
+        "--provenance/--no-provenance",
+        help="Embed template provenance in ticket",
+    ),
+    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+):
+    """Apply a template by writing it into the ticket directory."""
+    ctx = _require_repo_config(repo, hub)
+    _require_templates_enabled(ctx.config)
+
+    fetched, scan_record, _hub_root = _fetch_template_with_scan(template, ctx, hub)
+
+    resolved_dir = _resolve_ticket_dir(ctx.repo_root, ticket_dir)
+    if resolved_dir.exists() and not resolved_dir.is_dir():
+        _raise_exit(f"Ticket dir is not a directory: {resolved_dir}")
+    try:
+        resolved_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        _raise_exit(f"Unable to create ticket dir: {exc}")
+
+    if at is None and not next_index:
+        _raise_exit("Specify --at or leave --next enabled to pick an index.")
+    if at is not None and at < 1:
+        _raise_exit("Ticket index must be >= 1.")
+
+    existing_indices = _collect_ticket_indices(resolved_dir)
+    if at is None:
+        index = _next_available_ticket_index(existing_indices)
+    else:
+        index = at
+        if index in existing_indices:
+            _raise_exit(
+                f"Ticket index {index} already exists. Choose another index or open a gap."
+            )
+
+    normalized_suffix = _normalize_ticket_suffix(suffix)
+    width = max(3, max([len(str(i)) for i in existing_indices + [index]]))
+    filename = _ticket_filename(index, suffix=normalized_suffix, width=width)
+    path = resolved_dir / filename
+    if path.exists():
+        _raise_exit(f"Ticket already exists: {path}")
+
+    content = fetched.content
+    if set_agent:
+        if set_agent != "user":
+            try:
+                validate_agent_id(set_agent)
+            except ValueError as exc:
+                _raise_exit(str(exc), cause=exc)
+        content = _apply_agent_override(content, set_agent)
+
+    if provenance:
+        content = inject_provenance(content, fetched, scan_record)
+
+    try:
+        path.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        _raise_exit(f"Failed to write ticket: {exc}")
+
+    metadata = {
+        "repo_id": fetched.repo_id,
+        "path": fetched.path,
+        "ref": fetched.ref,
+        "commit_sha": fetched.commit_sha,
+        "blob_sha": fetched.blob_sha,
+        "trusted": fetched.trusted,
+        "scan": scan_record.to_dict() if scan_record else None,
+    }
+    typer.echo(
+        "Created ticket "
+        f"{path} (index={index}, template={fetched.repo_id}:{fetched.path}@{fetched.ref})"
+    )
+    typer.echo(json.dumps(metadata, indent=2))
+
+
+@repos_app.command("list")
+def repos_list(
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output"),
+):
+    """List configured template repos."""
+    config = _require_hub_config(hub)
+    hub_config_path = config.root / CONFIG_FILENAME
+    data = _load_hub_config_yaml(hub_config_path)
+
+    templates_config = data.get("templates", {})
+    if not isinstance(templates_config, dict):
+        templates_config = {}
+    repos = templates_config.get("repos", [])
+    if not isinstance(repos, list):
+        repos = []
+
+    if output_json:
+        payload = {"repos": repos}
+        typer.echo(json.dumps(payload, indent=2))
+        return
+
+    if not repos:
+        typer.echo("No template repos configured.")
+        return
+
+    typer.echo(f"Template repos ({len(repos)}):")
+    for repo in repos:
+        if not isinstance(repo, dict):
+            continue
+        repo_id = repo.get("id", "")
+        url = repo.get("url", "")
+        trusted = repo.get("trusted", False)
+        default_ref = repo.get("default_ref", "main")
+        trusted_text = "trusted" if trusted else "untrusted"
+        typer.echo(f"  - {repo_id}: {url} [{trusted_text}] (default_ref={default_ref})")
+
+
+@repos_app.command("add")
+def repos_add(
+    repo_id: str = typer.Argument(..., help="Unique repo ID"),
+    url: str = typer.Argument(..., help="Git repo URL or path"),
+    trusted: Optional[bool] = typer.Option(
+        None, "--trusted/--untrusted", help="Trust level (default: untrusted)"
+    ),
+    default_ref: str = typer.Option("main", "--default-ref", help="Default git ref"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+):
+    """Add a template repo to the hub config."""
+    config = _require_hub_config(hub)
+    hub_config_path = config.root / CONFIG_FILENAME
+    data = _load_hub_config_yaml(hub_config_path)
+
+    templates_config = data.get("templates", {})
+    if not isinstance(templates_config, dict):
+        templates_config = {}
+    enabled = templates_config.get("enabled", True)
+    if enabled is False:
+        _raise_exit(
+            "Templates are disabled. Set templates.enabled=true in the hub config to enable."
+        )
+
+    templates_config = data.setdefault("templates", {})
+    if not isinstance(templates_config, dict):
+        _raise_exit("Invalid templates config in hub config")
+    templates_config.setdefault("enabled", True)
+    repos = templates_config.setdefault("repos", [])
+    if not isinstance(repos, list):
+        _raise_exit("Invalid repos config in hub config")
+
+    existing_ids = {repo.get("id") for repo in repos if isinstance(repo, dict)}
+    if repo_id in existing_ids:
+        _raise_exit(f"Repo ID '{repo_id}' already exists. Use a unique ID.")
+
+    new_repo = {
+        "id": repo_id,
+        "url": url,
+        "default_ref": default_ref,
+    }
+    if trusted is not None:
+        new_repo["trusted"] = trusted
+
+    repos.append(new_repo)
+
+    try:
+        _write_hub_config_yaml(hub_config_path, data)
+    except OSError as exc:
+        _raise_exit(f"Failed to write hub config: {exc}", cause=exc)
+
+    typer.echo(f"Added template repo '{repo_id}' to hub config.")
+
+
+@repos_app.command("remove")
+def repos_remove(
+    repo_id: str = typer.Argument(..., help="Repo ID to remove"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+):
+    """Remove a template repo from the hub config."""
+    config = _require_hub_config(hub)
+    hub_config_path = config.root / CONFIG_FILENAME
+    data = _load_hub_config_yaml(hub_config_path)
+
+    templates_config = data.get("templates", {})
+    if not isinstance(templates_config, dict):
+        templates_config = {}
+    repos = templates_config.get("repos", [])
+    if not isinstance(repos, list):
+        repos = []
+
+    original_count = len(repos)
+    filtered_repos = [
+        repo for repo in repos if isinstance(repo, dict) and repo.get("id") != repo_id
+    ]
+
+    if len(filtered_repos) == original_count:
+        _raise_exit(f"Repo ID '{repo_id}' not found in config.")
+
+    templates_config["repos"] = filtered_repos
+
+    try:
+        _write_hub_config_yaml(hub_config_path, data)
+    except OSError as exc:
+        _raise_exit(f"Failed to write hub config: {exc}", cause=exc)
+
+    typer.echo(f"Removed template repo '{repo_id}' from hub config.")
+
+
+@repos_app.command("trust")
+def repos_trust(
+    repo_id: str = typer.Argument(..., help="Repo ID to trust"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+):
+    """Mark a template repo as trusted (skip scanning)."""
+    config = _require_hub_config(hub)
+    hub_config_path = config.root / CONFIG_FILENAME
+    data = _load_hub_config_yaml(hub_config_path)
+
+    templates_config = data.get("templates", {})
+    if not isinstance(templates_config, dict):
+        templates_config = {}
+    repos = templates_config.get("repos", [])
+    if not isinstance(repos, list):
+        repos = []
+
+    found = False
+    for repo in repos:
+        if isinstance(repo, dict) and repo.get("id") == repo_id:
+            repo["trusted"] = True
+            found = True
+            break
+
+    if not found:
+        _raise_exit(f"Repo ID '{repo_id}' not found in config.")
+
+    try:
+        _write_hub_config_yaml(hub_config_path, data)
+    except OSError as exc:
+        _raise_exit(f"Failed to write hub config: {exc}", cause=exc)
+
+    typer.echo(f"Marked repo '{repo_id}' as trusted.")
+
+
+@repos_app.command("untrust")
+def repos_untrust(
+    repo_id: str = typer.Argument(..., help="Repo ID to untrust"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+):
+    """Mark a template repo as untrusted (require scanning)."""
+    config = _require_hub_config(hub)
+    hub_config_path = config.root / CONFIG_FILENAME
+    data = _load_hub_config_yaml(hub_config_path)
+
+    templates_config = data.get("templates", {})
+    if not isinstance(templates_config, dict):
+        templates_config = {}
+    repos = templates_config.get("repos", [])
+    if not isinstance(repos, list):
+        repos = []
+
+    found = False
+    for repo in repos:
+        if isinstance(repo, dict) and repo.get("id") == repo_id:
+            repo["trusted"] = False
+            found = True
+            break
+
+    if not found:
+        _raise_exit(f"Repo ID '{repo_id}' not found in config.")
+
+    try:
+        _write_hub_config_yaml(hub_config_path, data)
+    except OSError as exc:
+        _raise_exit(f"Failed to write hub config: {exc}", cause=exc)
+
+    typer.echo(f"Marked repo '{repo_id}' as untrusted.")
 
 
 @app.command()
@@ -635,52 +1212,6 @@ def usage(
         )
 
 
-@app.command()
-def run(
-    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
-    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
-    force: bool = typer.Option(False, "--force", help="Ignore existing lock"),
-):
-    """Run the autorunner loop."""
-    engine: Optional[Engine] = None
-    try:
-        engine = _require_repo_config(repo, hub)
-        engine.clear_stop_request()
-        engine.acquire_lock(force=force)
-        engine.run_loop()
-    except (ConfigError, LockError) as exc:
-        _raise_exit(str(exc), cause=exc)
-    finally:
-        if engine:
-            try:
-                engine.release_lock()
-            except OSError as exc:
-                logger.debug("Failed to release lock in run command: %s", exc)
-
-
-@app.command()
-def once(
-    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
-    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
-    force: bool = typer.Option(False, "--force", help="Ignore existing lock"),
-):
-    """Execute a single Codex run."""
-    engine: Optional[Engine] = None
-    try:
-        engine = _require_repo_config(repo, hub)
-        engine.clear_stop_request()
-        engine.acquire_lock(force=force)
-        engine.run_once()
-    except (ConfigError, LockError) as exc:
-        _raise_exit(str(exc), cause=exc)
-    finally:
-        if engine:
-            try:
-                engine.release_lock()
-            except OSError as exc:
-                logger.debug("Failed to release lock in once command: %s", exc)
-
-
 @app.command()
 def kill(
     repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
@@ -719,25 +1250,17 @@ def kill(
 def resume(
     repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
     hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
-    once: bool = typer.Option(False, "--once", help="Resume with a single run"),
-    force: bool = typer.Option(False, "--force", help="Override active lock"),
 ):
-    """Resume a stopped/errored autorunner, clearing stale locks if needed."""
-    engine: Optional[Engine] = None
-    try:
-        engine = _require_repo_config(repo, hub)
-        engine.clear_stop_request()
-        clear_stale_lock(engine.lock_path)
-        engine.acquire_lock(force=force)
-        engine.run_loop(stop_after_runs=1 if once else None)
-    except (ConfigError, LockError) as exc:
-        _raise_exit(str(exc), cause=exc)
-    finally:
-        if engine:
-            try:
-                engine.release_lock()
-            except OSError as exc:
-                logger.debug("Failed to release lock in resume command: %s", exc)
+    """Resume a paused/running ticket flow (now uses ticket_flow).
+
+    This command now uses ticket_flow for execution. For full control over
+    flows, use 'car flow' commands instead.
+    """
+    # Note: Resume is now handled by 'car flow ticket_flow/start' which
+    # will reuse an active/paused run automatically.
+    typer.echo("The 'resume' command has been deprecated in favor of ticket_flow.")
+    typer.echo("Use 'car flow ticket_flow/start' to resume existing flows.")
+    raise typer.Exit(code=0)
 
 
 @app.command()
@@ -816,14 +1339,22 @@ def doctor_cmd(
 
         hub_config = load_hub_config(start_path)
         repo_config: Optional[RepoConfig] = None
+        repo_root: Optional[Path] = None
         try:
             repo_root = find_repo_root(start_path)
             repo_config = derive_repo_config(hub_config, repo_root)
         except RepoNotFoundError:
             repo_config = None
 
-        telegram_checks = telegram_doctor_checks(repo_config or hub_config)
-        report = DoctorReport(checks=report.checks + telegram_checks)
+        telegram_checks = telegram_doctor_checks(
+            repo_config or hub_config, repo_root=repo_root
+        )
+        pma_checks = pma_doctor_checks(hub_config, repo_root=repo_root)
+        hub_worktree_checks = hub_worktree_doctor_checks(hub_config)
+
+        report = DoctorReport(
+            checks=report.checks + telegram_checks + pma_checks + hub_worktree_checks
+        )
     except ConfigError as exc:
         _raise_exit(str(exc), cause=exc)
     if json_output:
@@ -875,7 +1406,7 @@ def serve(
 
 @hub_app.command("create")
 def hub_create(
-    repo_id: str = typer.Argument(..., help="Repo id to create and initialize"),
+    repo_id: str = typer.Argument(..., help="Base repo id to create and initialize"),
     repo_path: Optional[Path] = typer.Option(
         None,
         "--repo-path",
@@ -887,12 +1418,16 @@ def hub_create(
         True, "--git-init/--no-git-init", help="Run git init in the new repo"
     ),
 ):
-    """Create a new git repo under the hub and initialize codex-autorunner files."""
+    """Create a new base git repo under the hub and initialize codex-autorunner files.
+
+    For worktrees, use `car hub worktree create`.
+    """
     config = _require_hub_config(path)
     supervisor = HubSupervisor(
         config,
         backend_factory_builder=build_agent_backend_factory,
         app_server_supervisor_factory_builder=build_app_server_supervisor_factory,
+        backend_orchestrator_builder=build_backend_orchestrator,
         agent_id_validator=validate_agent_id,
     )
     try:
@@ -939,6 +1474,157 @@ def hub_clone(
     )
 
 
+def _worktree_snapshot_payload(snapshot) -> dict:
+    return {
+        "id": snapshot.id,
+        "worktree_of": snapshot.worktree_of,
+        "branch": snapshot.branch,
+        "path": str(snapshot.path),
+        "initialized": snapshot.initialized,
+        "exists_on_disk": snapshot.exists_on_disk,
+        "status": snapshot.status.value,
+    }
+
+
+@worktree_app.command("create")
+def hub_worktree_create(
+    base_repo_id: str = typer.Argument(..., help="Base repo id to branch from"),
+    branch: str = typer.Argument(..., help="Branch name for the new worktree"),
+    hub: Optional[Path] = typer.Option(None, "--path", "--hub", help="Hub root path"),
+    force: bool = typer.Option(False, "--force", help="Allow existing directory"),
+    start_point: Optional[str] = typer.Option(
+        None, "--start-point", help="Optional git ref to branch from"
+    ),
+):
+    """Create a new hub-managed worktree."""
+    config = _require_hub_config(hub)
+    supervisor = HubSupervisor(
+        config,
+        backend_factory_builder=build_agent_backend_factory,
+        app_server_supervisor_factory_builder=build_app_server_supervisor_factory,
+        backend_orchestrator_builder=build_backend_orchestrator,
+        agent_id_validator=validate_agent_id,
+    )
+    try:
+        snapshot = supervisor.create_worktree(
+            base_repo_id=base_repo_id,
+            branch=branch,
+            force=force,
+            start_point=start_point,
+        )
+    except Exception as exc:
+        _raise_exit(str(exc), cause=exc)
+    typer.echo(
+        f"Created worktree {snapshot.id} (branch={snapshot.branch}) at {snapshot.path}"
+    )
+
+
+@worktree_app.command("list")
+def hub_worktree_list(
+    hub: Optional[Path] = typer.Option(None, "--path", "--hub", help="Hub root path"),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output"),
+):
+    """List hub-managed worktrees."""
+    config = _require_hub_config(hub)
+    supervisor = HubSupervisor(
+        config,
+        backend_factory_builder=build_agent_backend_factory,
+        app_server_supervisor_factory_builder=build_app_server_supervisor_factory,
+        agent_id_validator=validate_agent_id,
+    )
+    snapshots = [
+        snapshot
+        for snapshot in supervisor.list_repos(use_cache=False)
+        if snapshot.kind == "worktree"
+    ]
+    payload = [_worktree_snapshot_payload(snapshot) for snapshot in snapshots]
+    if output_json:
+        typer.echo(json.dumps({"worktrees": payload}, indent=2))
+        return
+    if not payload:
+        typer.echo("No worktrees found.")
+        return
+    typer.echo(f"Worktrees ({len(payload)}):")
+    for item in payload:
+        typer.echo(
+            "  - {id} (base={worktree_of}, branch={branch}, status={status}, initialized={initialized}, exists={exists_on_disk}, path={path})".format(
+                **item
+            )
+        )
+
+
+@worktree_app.command("scan")
+def hub_worktree_scan(
+    hub: Optional[Path] = typer.Option(None, "--path", "--hub", help="Hub root path"),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output"),
+):
+    """Scan hub root and list discovered worktrees."""
+    config = _require_hub_config(hub)
+    supervisor = HubSupervisor(
+        config,
+        backend_factory_builder=build_agent_backend_factory,
+        app_server_supervisor_factory_builder=build_app_server_supervisor_factory,
+        agent_id_validator=validate_agent_id,
+    )
+    snapshots = [snap for snap in supervisor.scan() if snap.kind == "worktree"]
+    payload = [_worktree_snapshot_payload(snapshot) for snapshot in snapshots]
+    if output_json:
+        typer.echo(json.dumps({"worktrees": payload}, indent=2))
+        return
+    if not payload:
+        typer.echo("No worktrees found.")
+        return
+    typer.echo(f"Worktrees ({len(payload)}):")
+    for item in payload:
+        typer.echo(
+            "  - {id} (base={worktree_of}, branch={branch}, status={status}, initialized={initialized}, exists={exists_on_disk}, path={path})".format(
+                **item
+            )
+        )
+
+
+@worktree_app.command("cleanup")
+def hub_worktree_cleanup(
+    worktree_repo_id: str = typer.Argument(..., help="Worktree repo id to remove"),
+    hub: Optional[Path] = typer.Option(None, "--path", "--hub", help="Hub root path"),
+    delete_branch: bool = typer.Option(
+        False, "--delete-branch", help="Delete the local branch"
+    ),
+    delete_remote: bool = typer.Option(
+        False, "--delete-remote", help="Delete the remote branch"
+    ),
+    archive: bool = typer.Option(
+        True, "--archive/--no-archive", help="Archive worktree snapshot"
+    ),
+    force_archive: bool = typer.Option(
+        False, "--force-archive", help="Continue cleanup if archive fails"
+    ),
+    archive_note: Optional[str] = typer.Option(
+        None, "--archive-note", help="Optional archive note"
+    ),
+):
+    """Cleanup a hub-managed worktree."""
+    config = _require_hub_config(hub)
+    supervisor = HubSupervisor(
+        config,
+        backend_factory_builder=build_agent_backend_factory,
+        app_server_supervisor_factory_builder=build_app_server_supervisor_factory,
+        agent_id_validator=validate_agent_id,
+    )
+    try:
+        supervisor.cleanup_worktree(
+            worktree_repo_id=worktree_repo_id,
+            delete_branch=delete_branch,
+            delete_remote=delete_remote,
+            archive=archive,
+            force_archive=force_archive,
+            archive_note=archive_note,
+        )
+    except Exception as exc:
+        _raise_exit(str(exc), cause=exc)
+    typer.echo("ok")
+
+
 @hub_app.command("serve")
 def hub_serve(
     path: Optional[Path] = typer.Option(None, "--path", help="Hub root path"),
@@ -986,6 +1672,117 @@ def hub_scan(path: Optional[Path] = typer.Option(None, "--path", help="Hub root
         )
 
 
+@hub_app.command("snapshot")
+def hub_snapshot(
+    path: Optional[Path] = typer.Option(None, "--path", help="Hub root path"),
+    output_json: bool = typer.Option(
+        True, "--json/--no-json", help="Emit JSON output (default: true)"
+    ),
+    pretty: bool = typer.Option(False, "--pretty", help="Pretty-print JSON output"),
+):
+    """Return a compact hub snapshot (repos + inbox items)."""
+    config = _require_hub_config(path)
+    repos_url = _build_server_url(config, "/hub/repos")
+    messages_url = _build_server_url(config, "/hub/messages?limit=50")
+
+    try:
+        repos_response = _request_json(
+            "GET", repos_url, token_env=config.server_auth_token_env
+        )
+        messages_response = _request_json(
+            "GET", messages_url, token_env=config.server_auth_token_env
+        )
+    except (
+        httpx.HTTPError,
+        httpx.ConnectError,
+        httpx.TimeoutException,
+        OSError,
+    ) as exc:
+        logger.debug("Failed to fetch hub snapshot from server: %s", exc)
+        _raise_exit(
+            "Failed to connect to hub server. Ensure 'car hub serve' is running.",
+            cause=exc,
+        )
+
+    repos_payload = repos_response if isinstance(repos_response, dict) else {}
+    messages_payload = messages_response if isinstance(messages_response, dict) else {}
+
+    repos = repos_payload.get("repos", []) if isinstance(repos_payload, dict) else []
+    messages_items = (
+        messages_payload.get("items", []) if isinstance(messages_payload, dict) else []
+    )
+
+    def _summarize_repo(repo: dict) -> dict:
+        if not isinstance(repo, dict):
+            return {}
+        return {
+            "id": repo.get("id"),
+            "display_name": repo.get("display_name"),
+            "status": repo.get("status"),
+            "initialized": repo.get("initialized"),
+            "exists_on_disk": repo.get("exists_on_disk"),
+            "last_run_id": repo.get("last_run_id"),
+            "last_run_started_at": repo.get("last_run_started_at"),
+            "last_run_finished_at": repo.get("last_run_finished_at"),
+        }
+
+    def _summarize_message(msg: dict) -> dict:
+        if not isinstance(msg, dict):
+            return {}
+        dispatch = msg.get("dispatch", {})
+        if not isinstance(dispatch, dict):
+            dispatch = {}
+        body = dispatch.get("body", "")
+        title = dispatch.get("title", "")
+        truncated_body = (body[:200] + "...") if len(body) > 200 else body
+        return {
+            "repo_id": msg.get("repo_id"),
+            "repo_display_name": msg.get("repo_display_name"),
+            "run_id": msg.get("run_id"),
+            "run_created_at": msg.get("run_created_at"),
+            "status": msg.get("status"),
+            "seq": msg.get("seq"),
+            "dispatch": {
+                "mode": dispatch.get("mode"),
+                "title": title,
+                "body": truncated_body,
+                "is_handoff": dispatch.get("is_handoff"),
+            },
+            "files_count": (
+                len(msg.get("files", [])) if isinstance(msg.get("files"), list) else 0
+            ),
+        }
+
+    snapshot = {
+        "last_scan_at": (
+            repos_payload.get("last_scan_at")
+            if isinstance(repos_payload, dict)
+            else None
+        ),
+        "repos": [_summarize_repo(repo) for repo in repos],
+        "inbox_items": [_summarize_message(msg) for msg in messages_items],
+    }
+
+    if not output_json:
+        typer.echo(
+            f"Hub Snapshot (repos={len(snapshot['repos'])}, inbox={len(snapshot['inbox_items'])})"
+        )
+        for repo in snapshot["repos"]:
+            typer.echo(
+                f"- {repo.get('id')}: status={repo.get('status')}, "
+                f"initialized={repo.get('initialized')}, exists={repo.get('exists_on_disk')}"
+            )
+        for msg in snapshot["inbox_items"]:
+            typer.echo(
+                f"- Inbox: repo={msg.get('repo_id')}, run_id={msg.get('run_id')}, "
+                f"title={msg.get('dispatch', {}).get('title')}"
+            )
+        return
+
+    indent = 2 if pretty else None
+    typer.echo(json.dumps(snapshot, indent=indent))
+
+
 @telegram_app.command("start")
 def telegram_start(
     path: Optional[Path] = typer.Option(None, "--path", help="Repo or hub root path"),
@@ -1116,108 +1913,621 @@ def telegram_state_check(
         _raise_exit(f"Telegram state check failed: {exc}", cause=exc)
 
 
-@app.command()
-def flow(
-    action: str = typer.Argument(..., help="worker"),
+def _normalize_flow_run_id(run_id: Optional[str]) -> Optional[str]:
+    if run_id is None:
+        return None
+    try:
+        return str(uuid.UUID(str(run_id)))
+    except ValueError:
+        _raise_exit("Invalid run_id format; must be a UUID")
+
+
+def _ticket_flow_paths(engine: RuntimeContext) -> tuple[Path, Path, Path]:
+    db_path = engine.repo_root / ".codex-autorunner" / "flows.db"
+    artifacts_root = engine.repo_root / ".codex-autorunner" / "flows"
+    ticket_dir = engine.repo_root / ".codex-autorunner" / "tickets"
+    return db_path, artifacts_root, ticket_dir
+
+
+def _validate_tickets(ticket_dir: Path) -> list[str]:
+    """Validate all tickets in the directory and return a list of error messages."""
+    errors: list[str] = []
+
+    if not ticket_dir.exists():
+        return errors
+
+    ticket_root = ticket_dir.parent
+    for path in sorted(ticket_dir.iterdir()):
+        if not path.is_file():
+            continue
+        if path.name == "AGENTS.md":
+            continue
+        if parse_ticket_index(path.name) is None:
+            rel_path = safe_relpath(path, ticket_root)
+            errors.append(
+                f"{rel_path}: Invalid ticket filename; expected TICKET-<number>[suffix].md (e.g. TICKET-001-foo.md)"
+            )
+
+    # Check for directory-level errors (duplicate indices)
+    dir_errors = lint_ticket_directory(ticket_dir)
+    errors.extend(dir_errors)
+
+    # Check each ticket file for frontmatter errors
+    ticket_paths = list_ticket_paths(ticket_dir)
+    for path in ticket_paths:
+        _, ticket_errors = read_ticket(path)
+        for err in ticket_errors:
+            errors.append(f"{path.relative_to(path.parent.parent)}: {err}")
+
+    return errors
+
+
+def _open_flow_store(engine: RuntimeContext) -> FlowStore:
+    db_path, _, _ = _ticket_flow_paths(engine)
+    store = FlowStore(db_path, durable=engine.config.durable_writes)
+    store.initialize()
+    return store
+
+
+def _active_or_paused_run(records: list[FlowRunRecord]) -> Optional[FlowRunRecord]:
+    if not records:
+        return None
+    latest = records[0]
+    if latest.status in (FlowRunStatus.RUNNING, FlowRunStatus.PAUSED):
+        return latest
+    return None
+
+
+def _resumable_run(records: list[FlowRunRecord]) -> tuple[Optional[FlowRunRecord], str]:
+    """Return a resumable run and the reason.
+
+    Returns (run, reason) where run may be None.
+    Reason is one of: 'active', 'completed_pending', 'force_new', 'new_run'.
+    """
+    if not records:
+        return None, "new_run"
+    latest = records[0]
+    if latest.status in (FlowRunStatus.RUNNING, FlowRunStatus.PAUSED):
+        return latest, "active"
+    if latest.status == FlowRunStatus.COMPLETED:
+        return latest, "completed_pending"
+    return None, "new_run"
+
+
+def _ticket_flow_status_payload(
+    engine: RuntimeContext, record: FlowRunRecord, store: Optional[FlowStore]
+) -> dict:
+    snapshot = build_flow_status_snapshot(engine.repo_root, record, store)
+    health = snapshot.get("worker_health")
+    effective_ticket = snapshot.get("effective_current_ticket")
+    return {
+        "run_id": record.id,
+        "flow_type": record.flow_type,
+        "status": record.status.value,
+        "current_step": record.current_step,
+        "created_at": record.created_at,
+        "started_at": record.started_at,
+        "finished_at": record.finished_at,
+        "last_event_seq": snapshot.get("last_event_seq"),
+        "last_event_at": snapshot.get("last_event_at"),
+        "current_ticket": effective_ticket,
+        "ticket_progress": snapshot.get("ticket_progress"),
+        "worker": (
+            {
+                "status": health.status,
+                "pid": health.pid,
+                "message": health.message,
+            }
+            if health
+            else None
+        ),
+    }
+
+
+def _print_ticket_flow_status(payload: dict) -> None:
+    typer.echo(f"Run id: {payload.get('run_id')}")
+    typer.echo(f"Status: {payload.get('status')}")
+    progress = payload.get("ticket_progress") or {}
+    if isinstance(progress, dict):
+        done = progress.get("done")
+        total = progress.get("total")
+        if isinstance(done, int) and isinstance(total, int):
+            typer.echo(f"Tickets: {done}/{total}")
+    typer.echo(f"Current step: {payload.get('current_step')}")
+    typer.echo(f"Current ticket: {payload.get('current_ticket') or 'n/a'}")
+    typer.echo(f"Created at: {payload.get('created_at')}")
+    typer.echo(f"Started at: {payload.get('started_at')}")
+    typer.echo(f"Finished at: {payload.get('finished_at')}")
+    typer.echo(
+        f"Last event: {payload.get('last_event_at')} (seq={payload.get('last_event_seq')})"
+    )
+    worker = payload.get("worker") or {}
+    status = payload.get("status") or ""
+    # Only show worker details for non-terminal states
+    if worker and status not in {"completed", "failed", "stopped"}:
+        typer.echo(
+            f"Worker: {worker.get('status')} pid={worker.get('pid')} {worker.get('message') or ''}".rstrip()
+        )
+    elif worker and status in {"completed", "failed", "stopped"}:
+        # For terminal runs, show minimal worker info or clarify state
+        worker_status = worker.get("status") or ""
+        worker_pid = worker.get("pid")
+        worker_msg = worker.get("message") or ""
+        if worker_status == "absent" or "missing" in worker_msg.lower():
+            typer.echo("Worker: exited")
+        elif worker_status == "dead" or "not running" in worker_msg.lower():
+            typer.echo(f"Worker: exited (pid={worker_pid})")
+        else:
+            typer.echo(
+                f"Worker: {worker.get('status')} pid={worker.get('pid')} {worker.get('message') or ''}".rstrip()
+            )
+
+
+def _start_ticket_flow_worker(
+    repo_root: Path, run_id: str, is_terminal: bool = False
+) -> None:
+    result = ensure_worker(repo_root, run_id, is_terminal=is_terminal)
+    if result["status"] == "reused":
+        return
+
+
+def _stop_ticket_flow_worker(repo_root: Path, run_id: str) -> None:
+    health = check_worker_health(repo_root, run_id)
+    if health.status in {"dead", "mismatch", "invalid"}:
+        try:
+            clear_worker_metadata(health.artifact_path.parent)
+        except Exception:
+            pass
+    if not health.pid:
+        return
+    try:
+        subprocess.run(["kill", str(health.pid)], check=False)
+    except Exception:
+        pass
+
+
+def _ticket_flow_controller(
+    engine: RuntimeContext,
+) -> tuple[FlowController, AgentPool]:
+    db_path, artifacts_root, _ = _ticket_flow_paths(engine)
+    agent_pool = AgentPool(engine.config)
+    definition = build_ticket_flow_definition(agent_pool=agent_pool)
+    definition.validate()
+    controller = FlowController(
+        definition=definition,
+        db_path=db_path,
+        artifacts_root=artifacts_root,
+        durable=engine.config.durable_writes,
+    )
+    controller.initialize()
+    return controller, agent_pool
+
+
+@flow_app.command("worker")
+def flow_worker(
     repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
     hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
     run_id: Optional[str] = typer.Option(
-        None, "--run-id", help="Flow run ID (for worker)"
+        None, "--run-id", help="Flow run ID (required)"
     ),
 ):
-    """Flow runtime commands."""
+    """Start a flow worker process for an existing run."""
     engine = _require_repo_config(repo, hub)
+    normalized_run_id = _normalize_flow_run_id(run_id)
+    if not normalized_run_id:
+        _raise_exit("--run-id is required for worker command")
 
-    if action == "worker":
-        if not run_id:
-            _raise_exit("--run-id is required for worker command")
-        try:
-            run_id = str(uuid.UUID(str(run_id)))
-        except ValueError:
-            _raise_exit("Invalid run_id format; must be a UUID")
-
-        from ...core.flows import FlowController, FlowStore
-        from ...core.flows.models import FlowRunStatus
-        from ...flows.ticket_flow.definition import build_ticket_flow_definition
-        from ...tickets import AgentPool
+    db_path, artifacts_root, ticket_dir = _ticket_flow_paths(engine)
 
-        db_path = engine.repo_root / ".codex-autorunner" / "flows.db"
-        artifacts_root = engine.repo_root / ".codex-autorunner" / "flows"
+    typer.echo(f"Starting flow worker for run {normalized_run_id}")
 
-        typer.echo(f"Starting flow worker for run {run_id}")
+    async def _run_worker():
+        typer.echo(f"Flow worker started for {normalized_run_id}")
+        typer.echo(f"DB path: {db_path}")
+        typer.echo(f"Artifacts root: {artifacts_root}")
 
-        async def _run_worker():
-            typer.echo(f"Flow worker started for {run_id}")
-            typer.echo(f"DB path: {db_path}")
-            typer.echo(f"Artifacts root: {artifacts_root}")
+        store = FlowStore(db_path, durable=engine.config.durable_writes)
+        store.initialize()
 
-            store = FlowStore(db_path)
-            store.initialize()
+        record = store.get_flow_run(normalized_run_id)
+        if not record:
+            typer.echo(f"Flow run {normalized_run_id} not found", err=True)
+            store.close()
+            raise typer.Exit(code=1)
 
-            record = store.get_flow_run(run_id)
-            if not record:
-                typer.echo(f"Flow run {run_id} not found", err=True)
+        if record.flow_type == "ticket_flow":
+            lint_errors = _validate_tickets(ticket_dir)
+            if lint_errors:
+                typer.echo("Ticket validation failed:", err=True)
+                for err in lint_errors:
+                    typer.echo(f"  - {err}", err=True)
+                typer.echo("", err=True)
+                typer.echo(
+                    "Fix the above errors before starting the ticket flow.",
+                    err=True,
+                )
                 store.close()
                 raise typer.Exit(code=1)
-            store.close()
+            ticket_paths = list_ticket_paths(ticket_dir)
+            if not ticket_paths:
+                typer.echo(
+                    "No tickets found. Create tickets or run ticket_flow bootstrap to get started."
+                )
+                typer.echo(
+                    f"  Ticket directory: {ticket_dir.relative_to(engine.repo_root)}"
+                )
+                typer.echo("  To bootstrap: car flow ticket_flow bootstrap")
+                store.close()
+                raise typer.Exit(code=0)
 
-            agent_pool: AgentPool | None = None
+        store.close()
 
-            def _build_definition(flow_type: str):
-                nonlocal agent_pool
-                if flow_type == "pr_flow":
-                    _raise_exit(
-                        "PR flow is no longer supported. Use ticket_flow instead."
-                    )
-                if flow_type == "ticket_flow":
-                    agent_pool = AgentPool(engine.config)
-                    return build_ticket_flow_definition(agent_pool=agent_pool)
-                _raise_exit(f"Unknown flow type for run {run_id}: {flow_type}")
-                return None
-
-            definition = _build_definition(record.flow_type)
-            definition.validate()
-
-            controller = FlowController(
-                definition=definition,
-                db_path=db_path,
+        try:
+            register_worker_metadata(
+                engine.repo_root,
+                normalized_run_id,
                 artifacts_root=artifacts_root,
             )
-            controller.initialize()
+        except Exception as exc:
+            typer.echo(f"Failed to register worker metadata: {exc}", err=True)
+
+        agent_pool: AgentPool | None = None
+
+        def _build_definition(flow_type: str):
+            nonlocal agent_pool
+            if flow_type == "pr_flow":
+                _raise_exit("PR flow is no longer supported. Use ticket_flow instead.")
+            if flow_type == "ticket_flow":
+                agent_pool = AgentPool(engine.config)
+                return build_ticket_flow_definition(agent_pool=agent_pool)
+            _raise_exit(f"Unknown flow type for run {normalized_run_id}: {flow_type}")
+            return None
+
+        definition = _build_definition(record.flow_type)
+        definition.validate()
+
+        controller = FlowController(
+            definition=definition,
+            db_path=db_path,
+            artifacts_root=artifacts_root,
+            durable=engine.config.durable_writes,
+        )
+        controller.initialize()
 
-            record = controller.get_status(run_id)
-            if not record:
-                typer.echo(f"Flow run {run_id} not found", err=True)
-                raise typer.Exit(code=1)
+        record = controller.get_status(normalized_run_id)
+        if not record:
+            typer.echo(f"Flow run {normalized_run_id} not found", err=True)
+            raise typer.Exit(code=1)
 
-            if record.status.is_terminal() and record.status not in {
-                FlowRunStatus.STOPPED,
-                FlowRunStatus.FAILED,
-            }:
+        if record.status.is_terminal() and record.status not in {
+            FlowRunStatus.STOPPED,
+            FlowRunStatus.FAILED,
+        }:
+            typer.echo(
+                f"Flow run {normalized_run_id} already completed (status={record.status})"
+            )
+            return
+
+        action = "Resuming" if record.status != FlowRunStatus.PENDING else "Starting"
+        typer.echo(
+            f"{action} flow run {normalized_run_id} from step: {record.current_step}"
+        )
+        try:
+            final_record = await controller.run_flow(normalized_run_id)
+            typer.echo(
+                f"Flow run {normalized_run_id} finished with status {final_record.status}"
+            )
+        finally:
+            if agent_pool is not None:
+                try:
+                    await agent_pool.close()
+                except Exception:
+                    typer.echo("Failed to close agent pool cleanly", err=True)
+
+    asyncio.run(_run_worker())
+
+
+@ticket_flow_app.command("bootstrap")
+def ticket_flow_bootstrap(
+    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+    force_new: bool = typer.Option(
+        False, "--force-new", help="Always create a new run"
+    ),
+):
+    """Bootstrap ticket_flow (seed TICKET-001 if needed) and start a run.
+
+    If latest run is COMPLETED and new tickets are added, a new run is created
+    (use --force-new to force a new run regardless of state)."""
+    engine = _require_repo_config(repo, hub)
+    _guard_unregistered_hub_repo(engine.repo_root, hub)
+    db_path, artifacts_root, ticket_dir = _ticket_flow_paths(engine)
+    ticket_dir.mkdir(parents=True, exist_ok=True)
+    ticket_path = ticket_dir / "TICKET-001.md"
+
+    store = _open_flow_store(engine)
+    try:
+        if not force_new:
+            records = store.list_flow_runs(flow_type="ticket_flow")
+            existing_run, reason = _resumable_run(records)
+            if existing_run and reason == "active":
+                _start_ticket_flow_worker(
+                    engine.repo_root, existing_run.id, is_terminal=False
+                )
+                typer.echo(f"Reused active run: {existing_run.id}")
                 typer.echo(
-                    f"Flow run {run_id} already completed (status={record.status})"
+                    f"Next: car flow ticket_flow status --repo {engine.repo_root} --run-id {existing_run.id}"
                 )
                 return
-
-            action = (
-                "Resuming" if record.status != FlowRunStatus.PENDING else "Starting"
+            elif existing_run and reason == "completed_pending":
+                existing_tickets = list_ticket_paths(ticket_dir)
+                pending_count = len(
+                    [t for t in existing_tickets if not ticket_is_done(t)]
+                )
+                if pending_count > 0:
+                    typer.echo(
+                        f"Warning: Latest run {existing_run.id} is COMPLETED with {pending_count} pending ticket(s)."
+                    )
+                    typer.echo(
+                        "Use --force-new to start a fresh run (dispatch history will be reset)."
+                    )
+                    _raise_exit("Add --force-new to create a new run.")
+    finally:
+        store.close()
+
+    existing_tickets = list_ticket_paths(ticket_dir)
+    seeded = False
+    if not existing_tickets and not ticket_path.exists():
+        template = """---
+agent: codex
+done: false
+title: Bootstrap ticket plan
+goal: Capture scope and seed follow-up tickets
+---
+
+You are the first ticket in a new ticket_flow run.
+
+- Read `.codex-autorunner/ISSUE.md`. If it is missing:
+  - If GitHub is available, ask the user for the issue/PR URL or number and create `.codex-autorunner/ISSUE.md` from it.
+  - If GitHub is not available, write `DISPATCH.md` with `mode: pause` asking the user to describe the work (or share a doc). After the reply, create `.codex-autorunner/ISSUE.md` with their input.
+- If helpful, create or update workspace docs under `.codex-autorunner/workspace/`:
+  - `active_context.md` for current context and links
+  - `decisions.md` for decisions/rationale
+  - `spec.md` for requirements and constraints
+- Break the work into additional `TICKET-00X.md` files with clear owners/goals; keep this ticket open until they exist.
+- Place any supporting artifacts in `.codex-autorunner/runs/<run_id>/dispatch/` if needed.
+- Write `DISPATCH.md` to dispatch a message to the user:
+  - Use `mode: pause` (handoff) to wait for user response. This pauses execution.
+  - Use `mode: notify` (informational) to message the user but keep running.
+"""
+        ticket_path.write_text(template, encoding="utf-8")
+        seeded = True
+
+    controller, agent_pool = _ticket_flow_controller(engine)
+    try:
+        run_id = str(uuid.uuid4())
+        record = asyncio.run(
+            controller.start_flow(
+                input_data={},
+                run_id=run_id,
+                metadata={"seeded_ticket": seeded},
             )
-            typer.echo(f"{action} flow run {run_id} from step: {record.current_step}")
-            try:
-                final_record = await controller.run_flow(run_id)
+        )
+        _start_ticket_flow_worker(engine.repo_root, record.id, is_terminal=False)
+    finally:
+        controller.shutdown()
+        asyncio.run(agent_pool.close())
+
+    typer.echo(f"Started ticket_flow run: {run_id}")
+    typer.echo(
+        f"Next: car flow ticket_flow status --repo {engine.repo_root} --run-id {run_id}"
+    )
+
+
+@ticket_flow_app.command("start")
+def ticket_flow_start(
+    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+    force_new: bool = typer.Option(
+        False, "--force-new", help="Always create a new run"
+    ),
+):
+    """Start or resume the latest ticket_flow run.
+
+    If latest run is COMPLETED and new tickets are added, a new run is created
+    (use --force-new to force a new run regardless of state)."""
+    engine = _require_repo_config(repo, hub)
+    _guard_unregistered_hub_repo(engine.repo_root, hub)
+    _, _, ticket_dir = _ticket_flow_paths(engine)
+    ticket_dir.mkdir(parents=True, exist_ok=True)
+
+    store = _open_flow_store(engine)
+    try:
+        if not force_new:
+            records = store.list_flow_runs(flow_type="ticket_flow")
+            existing_run, reason = _resumable_run(records)
+            if existing_run and reason == "active":
+                # Validate tickets before reusing active run
+                lint_errors = _validate_tickets(ticket_dir)
+                if lint_errors:
+                    typer.echo("Ticket validation failed:", err=True)
+                    for err in lint_errors:
+                        typer.echo(f"  - {err}", err=True)
+                    typer.echo("", err=True)
+                    typer.echo(
+                        "Fix the above errors before starting the ticket flow.",
+                        err=True,
+                    )
+                    _raise_exit("")
+                _start_ticket_flow_worker(
+                    engine.repo_root, existing_run.id, is_terminal=False
+                )
+                typer.echo(f"Reused active run: {existing_run.id}")
                 typer.echo(
-                    f"Flow run {run_id} finished with status {final_record.status}"
+                    f"Next: car flow ticket_flow status --repo {engine.repo_root} --run-id {existing_run.id}"
                 )
-            finally:
-                if agent_pool is not None:
-                    try:
-                        await agent_pool.close()
-                    except Exception:
-                        typer.echo("Failed to close agent pool cleanly", err=True)
-
-        asyncio.run(_run_worker())
-    else:
-        _raise_exit(f"Unknown action: {action}")
+                return
+            elif existing_run and reason == "completed_pending":
+                existing_tickets = list_ticket_paths(ticket_dir)
+                pending_count = len(
+                    [t for t in existing_tickets if not ticket_is_done(t)]
+                )
+                if pending_count > 0:
+                    typer.echo(
+                        f"Warning: Latest run {existing_run.id} is COMPLETED with {pending_count} pending ticket(s)."
+                    )
+                    typer.echo(
+                        "Use --force-new to start a fresh run (dispatch history will be reset)."
+                    )
+                    _raise_exit("Add --force-new to create a new run.")
+
+    finally:
+        store.close()
+
+    lint_errors = _validate_tickets(ticket_dir)
+    if lint_errors:
+        typer.echo("Ticket validation failed:", err=True)
+        for err in lint_errors:
+            typer.echo(f"  - {err}", err=True)
+        typer.echo("", err=True)
+        typer.echo("Fix the above errors before starting the ticket flow.", err=True)
+        _raise_exit("")
+    if not list_ticket_paths(ticket_dir):
+        _raise_exit(
+            "No tickets found under .codex-autorunner/tickets. Use bootstrap first."
+        )
+
+    controller, agent_pool = _ticket_flow_controller(engine)
+    try:
+        run_id = str(uuid.uuid4())
+        record = asyncio.run(controller.start_flow(input_data={}, run_id=run_id))
+        _start_ticket_flow_worker(engine.repo_root, record.id, is_terminal=False)
+    finally:
+        controller.shutdown()
+        asyncio.run(agent_pool.close())
+
+    typer.echo(f"Started ticket_flow run: {run_id}")
+    typer.echo(
+        f"Next: car flow ticket_flow status --repo {engine.repo_root} --run-id {run_id}"
+    )
+
+
+@ticket_flow_app.command("status")
+def ticket_flow_status(
+    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help="Flow run ID"),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output"),
+):
+    """Show status for a ticket_flow run."""
+    engine = _require_repo_config(repo, hub)
+    normalized_run_id = _normalize_flow_run_id(run_id)
+
+    store = _open_flow_store(engine)
+    try:
+        record = None
+        if normalized_run_id:
+            record = store.get_flow_run(normalized_run_id)
+        else:
+            records = store.list_flow_runs(flow_type="ticket_flow")
+            record = records[0] if records else None
+        if not record:
+            _raise_exit("No ticket_flow runs found.")
+        payload = _ticket_flow_status_payload(engine, record, store)
+    finally:
+        store.close()
+
+    if output_json:
+        typer.echo(json.dumps(payload, indent=2))
+        return
+    _print_ticket_flow_status(payload)
+
+
+@ticket_flow_app.command("resume")
+def ticket_flow_resume(
+    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help="Flow run ID"),
+):
+    """Resume a paused ticket_flow run."""
+    engine = _require_repo_config(repo, hub)
+    _guard_unregistered_hub_repo(engine.repo_root, hub)
+    normalized_run_id = _normalize_flow_run_id(run_id)
+
+    store = _open_flow_store(engine)
+    try:
+        record = None
+        if normalized_run_id:
+            record = store.get_flow_run(normalized_run_id)
+        else:
+            records = store.list_flow_runs(flow_type="ticket_flow")
+            record = records[0] if records else None
+        if not record:
+            _raise_exit("No ticket_flow runs found.")
+        normalized_run_id = record.id
+    finally:
+        store.close()
+
+    _, _, ticket_dir = _ticket_flow_paths(engine)
+    lint_errors = _validate_tickets(ticket_dir)
+    if lint_errors:
+        typer.echo("Ticket validation failed:", err=True)
+        for err in lint_errors:
+            typer.echo(f"  - {err}", err=True)
+        typer.echo("", err=True)
+        typer.echo("Fix the above errors before resuming the ticket flow.", err=True)
+        _raise_exit("")
+
+    controller, agent_pool = _ticket_flow_controller(engine)
+    try:
+        try:
+            updated = asyncio.run(controller.resume_flow(normalized_run_id))
+        except ValueError as exc:
+            _raise_exit(str(exc), cause=exc)
+        _start_ticket_flow_worker(engine.repo_root, normalized_run_id)
+    finally:
+        controller.shutdown()
+        asyncio.run(agent_pool.close())
+
+    typer.echo(f"Resumed ticket_flow run: {updated.id}")
+    typer.echo(
+        f"Next: car flow ticket_flow status --repo {engine.repo_root} --run-id {updated.id}"
+    )
+
+
+@ticket_flow_app.command("stop")
+def ticket_flow_stop(
+    repo: Optional[Path] = typer.Option(None, "--repo", help="Repo path"),
+    hub: Optional[Path] = typer.Option(None, "--hub", help="Hub root path"),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help="Flow run ID"),
+):
+    """Stop a ticket_flow run."""
+    engine = _require_repo_config(repo, hub)
+    normalized_run_id = _normalize_flow_run_id(run_id)
+
+    store = _open_flow_store(engine)
+    try:
+        record = None
+        if normalized_run_id:
+            record = store.get_flow_run(normalized_run_id)
+        else:
+            records = store.list_flow_runs(flow_type="ticket_flow")
+            record = records[0] if records else None
+        if not record:
+            _raise_exit("No ticket_flow runs found.")
+        normalized_run_id = record.id
+    finally:
+        store.close()
+
+    controller, agent_pool = _ticket_flow_controller(engine)
+    try:
+        _stop_ticket_flow_worker(engine.repo_root, normalized_run_id)
+        updated = asyncio.run(controller.stop_flow(normalized_run_id))
+    finally:
+        controller.shutdown()
+        asyncio.run(agent_pool.close())
+
+    typer.echo(f"Stop requested for run: {updated.id} (status={updated.status.value})")
 
 
 if __name__ == "__main__":