ctrlrelay 0.10.0__py3-none-any.whl

ctrlrelay/cli.py

@@ -0,0 +1,3138 @@
+"""CLI entry point for ctrlrelay."""
+
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markup import escape as rich_escape
+from rich.table import Table
+
+from ctrlrelay import __version__
+from ctrlrelay.core.config import ConfigError, load_config, resolve_config_path
+from ctrlrelay.core.github import GitHubCLI, GitHubError
+from ctrlrelay.core.pr_verifier import PRVerifier
+from ctrlrelay.core.question_expiry import expire_stale_questions
+
+# Startup probe cap. `GitHubCLI` uses 60s for ordinary calls; this one
+# gates daemon startup, so a hung gh must not wedge it indefinitely.
+_GH_PROBE_TIMEOUT_SECONDS = 60
+
+app = typer.Typer(
+    name="ctrlrelay",
+    help="Local-first orchestrator for Claude Code across multiple GitHub repos.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        console.print(f"ctrlrelay version {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """ctrlrelay orchestrator CLI."""
+
+
+def _resolve_config_or_exit(config_path: str | None) -> Path:
+    """Resolve --config (or auto-discover) and exit with a friendly error if missing."""
+    try:
+        return resolve_config_path(config_path)
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+
+# Subcommand groups
+config_app = typer.Typer(help="Configuration commands.")
+app.add_typer(config_app, name="config")
+
+
+@config_app.command("validate")
+def config_validate(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Validate orchestrator.yaml configuration."""
+    path = _resolve_config_or_exit(config_path)
+
+    if not path.exists():
+        console.print(f"[red]Error:[/red] Config file not found: {path}")
+        raise typer.Exit(1)
+
+    try:
+        config = load_config(path)
+    except ConfigError as e:
+        console.print(f"[red]Validation failed:[/red] {e}")
+        raise typer.Exit(1)
+
+    console.print(f"[green]✓[/green] Config valid: {path}")
+    console.print(f"  Node ID: {config.node_id}")
+    console.print(f"  Timezone: {config.timezone}")
+    console.print(f"  Transport: {config.transport.type.value}")
+    console.print(f"  Repos: {len(config.repos)}")
+
+
+@config_app.command("repos")
+def config_repos(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """List configured repositories."""
+    path = _resolve_config_or_exit(config_path)
+
+    try:
+        config = load_config(path)
+    except ConfigError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not config.repos:
+        console.print("[yellow]No repositories configured.[/yellow]")
+        return
+
+    table = Table(title="Configured Repositories")
+    table.add_column("Name", style="cyan")
+    table.add_column("Path", style="dim")
+    table.add_column("Deploy", style="green")
+
+    for repo in config.repos:
+        deploy = repo.deploy.provider if repo.deploy else "-"
+        table.add_row(repo.name, str(repo.local_path), deploy)
+
+    console.print(table)
+
+
+# Skills subcommand group
+skills_app = typer.Typer(help="Skill management commands.")
+app.add_typer(skills_app, name="skills")
+
+
+def _resolve_skills_dir(skills_path: str | None, config_path: str | None) -> Path:
+    """Resolve skills directory from flag or config."""
+    if skills_path is not None:
+        skills_dir = Path(skills_path).expanduser().resolve()
+    else:
+        try:
+            config = load_config(resolve_config_path(config_path))
+            skills_dir = config.paths.skills.expanduser().resolve()
+        except ConfigError as e:
+            console.print(f"[red]Error loading config:[/red] {e}")
+            console.print("Use --path to specify skills directory directly.")
+            raise typer.Exit(1)
+
+    if not skills_dir.exists():
+        console.print(f"[red]Skills directory not found:[/red] {skills_dir}")
+        raise typer.Exit(1)
+
+    return skills_dir
+
+
+@skills_app.command("audit")
+def skills_audit(
+    skills_path: str = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Path to skills directory (default: from config)",
+    ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Audit skills for orchestrator readiness."""
+    from ctrlrelay.core.audit import audit_all, format_report
+
+    skills_dir = _resolve_skills_dir(skills_path, config_path)
+
+    console.print(f"Auditing skills in: {skills_dir}\n")
+
+    audits = audit_all(skills_dir)
+
+    if not audits:
+        console.print("[yellow]No skills found.[/yellow]")
+        return
+
+    report = format_report(audits)
+    console.print(report)
+
+    # Exit with error if any skills not ready
+    if not all(a.passed for a in audits):
+        raise typer.Exit(1)
+
+
+@skills_app.command("list")
+def skills_list(
+    skills_path: str = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Path to skills directory (default: from config)",
+    ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """List available skills."""
+    from ctrlrelay.core.audit import discover_skills
+
+    skills_dir = _resolve_skills_dir(skills_path, config_path)
+
+    skills = discover_skills(skills_dir)
+
+    if not skills:
+        console.print("[yellow]No skills found.[/yellow]")
+        return
+
+    table = Table(title="Available Skills")
+    table.add_column("Name", style="cyan")
+    table.add_column("Path", style="dim")
+
+    for skill in skills:
+        table.add_row(skill.name, str(skill.path))
+
+    console.print(table)
+
+
+# Bridge subcommand group
+bridge_app = typer.Typer(help="Telegram bridge commands.")
+app.add_typer(bridge_app, name="bridge")
+
+
+def _get_socket_path(config_path: str | None) -> Path:
+    """Get socket path from config."""
+    try:
+        config = load_config(resolve_config_path(config_path))
+        if config.transport.telegram:
+            return config.transport.telegram.socket_path.expanduser().resolve()
+    except ConfigError:
+        pass
+    return Path("~/.ctrlrelay/ctrlrelay.sock").expanduser().resolve()
+
+
+def _get_bridge_pid_file(socket_path: Path) -> Path:
+    """Get PID file path for bridge process."""
+    return socket_path.with_suffix(".pid")
+
+
+@bridge_app.command("start")
+def bridge_start(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    foreground: bool = typer.Option(
+        False,
+        "--foreground",
+        "-F",
+        help="Run in the foreground (for launchd/systemd/debugging). Default is to daemonize.",
+    ),
+) -> None:
+    """Start the Telegram bridge.
+
+    Daemonizes by default so the terminal returns to you. Pass --foreground
+    under a process supervisor (launchd Type=simple, systemd Type=simple) or
+    when debugging interactively.
+    """
+    import os
+    import subprocess
+    import sys
+
+    try:
+        config = load_config(resolve_config_path(config_path))
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+    if config.transport.type.value != "telegram":
+        console.print("[yellow]Transport is not set to 'telegram' in config.[/yellow]")
+        console.print("Set transport.type: telegram to use the bridge.")
+        raise typer.Exit(1)
+
+    telegram_config = config.transport.telegram
+    if not telegram_config:
+        console.print("[red]Telegram config not found.[/red]")
+        raise typer.Exit(1)
+
+    socket_path = telegram_config.socket_path.expanduser().resolve()
+    pid_file = _get_bridge_pid_file(socket_path)
+
+    if pid_file.exists():
+        try:
+            pid = int(pid_file.read_text().strip())
+            os.kill(pid, 0)
+            console.print(f"[yellow]Bridge already running (PID {pid})[/yellow]")
+            raise typer.Exit(1)
+        except (ProcessLookupError, ValueError):
+            pid_file.unlink(missing_ok=True)
+
+    bot_token = os.environ.get(telegram_config.bot_token_env)
+    if not bot_token:
+        env_var = telegram_config.bot_token_env
+        console.print(f"[red]Bot token not found.[/red] Set {env_var} environment variable.")
+        raise typer.Exit(1)
+
+    pid_file.parent.mkdir(parents=True, exist_ok=True)
+
+    if foreground:
+        import asyncio
+        import signal
+
+        from ctrlrelay.bridge import BridgeServer
+
+        # Install early SIGTERM/SIGINT handlers so a supervisor stop between
+        # now and loop.add_signal_handler below still runs the `finally`
+        # that unlinks the PID file. loop.add_signal_handler replaces them
+        # once the asyncio loop is running.
+        def _raise_systemexit_on_signal(sig: int, _frame: object) -> None:
+            raise SystemExit(0)
+
+        for _sig in (signal.SIGTERM, signal.SIGINT):
+            signal.signal(_sig, _raise_systemexit_on_signal)
+
+        pid_file.write_text(str(os.getpid()))
+        console.print(f"Starting bridge on {socket_path}")
+        console.print("Press Ctrl+C to stop")
+
+        # Open the state DB so the bridge can route orphan Telegram replies
+        # to persisted BLOCKED sessions in pending_resumes. Both daemons
+        # share ~/.ctrlrelay/state.db — SQLite's WAL mode handles concurrent
+        # readers/writers for the low contention we see here.
+        from ctrlrelay.core.state import StateDB
+        state_db = StateDB(config.paths.state_db)
+
+        server = BridgeServer(
+            socket_path=socket_path,
+            bot_token=bot_token,
+            chat_id=telegram_config.chat_id,
+            state_db=state_db,
+        )
+
+        loop = asyncio.new_event_loop()
+        try:
+            asyncio.set_event_loop(loop)
+
+            async def _run_server() -> None:
+                # Wrap start() in a finally that awaits stop() so the loop
+                # can't close before _telegram.close() and the socket unlink
+                # have actually completed. Scheduling stop() as a bare task
+                # in the signal handler would not guarantee that ordering.
+                try:
+                    await server.start()
+                finally:
+                    await server.stop()
+
+            main_task = loop.create_task(_run_server())
+
+            def _handle_stop(sig: int) -> None:
+                main_task.cancel()
+
+            for sig in (signal.SIGTERM, signal.SIGINT):
+                loop.add_signal_handler(sig, _handle_stop, sig)
+
+            try:
+                loop.run_until_complete(main_task)
+            except asyncio.CancelledError:
+                pass
+        finally:
+            loop.close()
+            try:
+                state_db.close()
+            except Exception:
+                pass
+            pid_file.unlink(missing_ok=True)
+    else:
+        # Pass the token via environment, never argv. Putting it on the command
+        # line would expose it to anyone who can read `ps` / /proc/*/cmdline.
+        cmd = [
+            sys.executable,
+            "-m",
+            "ctrlrelay.bridge",
+            "--socket-path",
+            str(socket_path),
+            "--bot-token-env",
+            telegram_config.bot_token_env,
+            "--chat-id",
+            str(telegram_config.chat_id),
+            "--state-db",
+            str(config.paths.state_db),
+        ]
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+        # Claim the PID file BEFORE the liveness probe; a second concurrent
+        # `bridge start` in the 1-second window would otherwise see no PID
+        # file, spawn its own child, and both would rebind the shared socket.
+        pid_file.write_text(str(proc.pid))
+        try:
+            proc.wait(timeout=1.0)
+        except subprocess.TimeoutExpired:
+            console.print(f"[green]Bridge started (PID {proc.pid})[/green]")
+            return
+        # Child exited within 1s. Zero = clean no-op; non-zero = crash.
+        pid_file.unlink(missing_ok=True)
+        if proc.returncode == 0:
+            console.print(
+                "[yellow]Bridge exited immediately with no work to do.[/yellow]"
+            )
+            return
+        console.print(
+            f"[red]Bridge failed to start[/red] "
+            f"(child exited with code {proc.returncode})"
+        )
+        raise typer.Exit(1)
+
+
+@bridge_app.command("stop")
+def bridge_stop(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Stop the Telegram bridge."""
+    import os
+    import signal
+
+    socket_path = _get_socket_path(config_path)
+    pid_file = _get_bridge_pid_file(socket_path)
+
+    if not pid_file.exists():
+        console.print("[yellow]Bridge not running (no PID file)[/yellow]")
+        return
+
+    try:
+        pid = int(pid_file.read_text().strip())
+        os.kill(pid, signal.SIGTERM)
+        console.print(f"[green]Stopped bridge (PID {pid})[/green]")
+        pid_file.unlink(missing_ok=True)
+    except ProcessLookupError:
+        console.print("[yellow]Bridge process not found[/yellow]")
+        pid_file.unlink(missing_ok=True)
+    except ValueError:
+        console.print("[red]Invalid PID file[/red]")
+        pid_file.unlink(missing_ok=True)
+
+
+@bridge_app.command("status")
+def bridge_status(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Check bridge status."""
+    import os
+
+    socket_path = _get_socket_path(config_path)
+    pid_file = _get_bridge_pid_file(socket_path)
+
+    if pid_file.exists():
+        try:
+            pid = int(pid_file.read_text().strip())
+            os.kill(pid, 0)
+            console.print(f"[green]Bridge running (PID {pid})[/green]")
+            console.print(f"Socket: {socket_path}")
+            return
+        except (ProcessLookupError, ValueError):
+            pass
+
+    if socket_path.exists():
+        console.print("[yellow]Socket exists but no PID file[/yellow]")
+        console.print(
+            "[dim]The bridge may be running under a supervisor that pre-dates "
+            "the PID-file change — restart it to refresh state.[/dim]"
+        )
+        console.print(f"Socket: {socket_path}")
+        raise typer.Exit(1)
+
+    console.print("[dim]Bridge not running[/dim]")
+    raise typer.Exit(1)
+
+
+@bridge_app.command("test")
+def bridge_test(
+    message: str = typer.Option(
+        "Test message from ctrlrelay bridge",
+        "--message",
+        "-m",
+        help="Message to send",
+    ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Send a test message to verify bridge is working."""
+    import asyncio
+
+    socket_path = _get_socket_path(config_path)
+
+    if not socket_path.exists():
+        console.print("[red]Bridge not running.[/red] Start it with: ctrlrelay bridge start")
+        raise typer.Exit(1)
+
+    async def send_test():
+        from ctrlrelay.transports import SocketTransport
+
+        # Send-only helper: never calls ask(), so the operator's
+        # ask_timeout_seconds is irrelevant here.
+        transport = SocketTransport(socket_path)
+        try:
+            await transport.connect()
+            await transport.send(message)
+            console.print("[green]Message sent successfully![/green]")
+        finally:
+            await transport.close()
+
+    try:
+        asyncio.run(send_test())
+    except Exception as e:
+        console.print(f"[red]Failed to send message:[/red] {e}")
+        raise typer.Exit(1)
+
+
+# Run subcommand group
+run_app = typer.Typer(help="Pipeline execution commands.")
+app.add_typer(run_app, name="run")
+
+
+@run_app.command("secops")
+def run_secops(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    repo: str = typer.Option(
+        None,
+        "--repo",
+        "-r",
+        help="Run on specific repo only",
+    ),
+) -> None:
+    """Run secops pipeline on configured repos."""
+    import asyncio
+
+    from ctrlrelay.core.dispatcher import make_agent_dispatcher
+    from ctrlrelay.core.github import GitHubCLI
+    from ctrlrelay.core.state import StateDB
+    from ctrlrelay.core.worktree import WorktreeManager
+    from ctrlrelay.dashboard.client import DashboardClient
+    from ctrlrelay.pipelines.secops import run_secops_all
+
+    path = _resolve_config_or_exit(config_path)
+
+    try:
+        config = load_config(path)
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+    repos = config.repos
+    if repo:
+        repos = [r for r in repos if r.name == repo]
+        if not repos:
+            console.print(f"[red]Repo not found:[/red] {repo}")
+            raise typer.Exit(1)
+
+    if not repos:
+        console.print("[yellow]No repos configured.[/yellow]")
+        return
+
+    db = StateDB(config.paths.state_db)
+    dispatcher = make_agent_dispatcher(config.agent)
+    github = GitHubCLI()
+    worktree = WorktreeManager(
+        worktrees_dir=config.paths.worktrees,
+        bare_repos_dir=config.paths.bare_repos,
+    )
+
+    dashboard = None
+    if config.dashboard.enabled and config.dashboard.url:
+        import os
+        token = os.environ.get(config.dashboard.auth_token_env, "")
+        if token:
+            dashboard = DashboardClient(
+                url=config.dashboard.url,
+                auth_token=token,
+                node_id=config.node_id,
+                queue_dir=config.paths.state_db.parent / "event_queue",
+            )
+
+    console.print(f"Running secops on {len(repos)} repo(s)...")
+
+    async def _run():
+        # Build a transport so secops blocked questions reach Telegram.
+        # Without this, agents that end BLOCKED_NEEDS_INPUT silently land
+        # in the DB+pending_resumes and the operator never sees the
+        # question (mirror of the wiring in the scheduled path).
+        transport = None
+        if (
+            config.transport.type.value == "telegram"
+            and config.transport.telegram
+        ):
+            from ctrlrelay.transports import SocketTransport
+            sock = config.transport.telegram.socket_path.expanduser().resolve()
+            if sock.exists():
+                try:
+                    candidate = SocketTransport(
+                        sock,
+                        ask_timeout_seconds=(
+                            config.transport.telegram.ask_timeout_seconds
+                        ),
+                    )
+                    await candidate.connect()
+                    transport = candidate
+                except Exception as e:
+                    console.print(
+                        f"[yellow]Bridge transport connect failed ({e}) — "
+                        f"running without notifications. Blocked sessions "
+                        f"will land in pending_resumes for later resume.[/yellow]"
+                    )
+
+        return await run_secops_all(
+            repos=repos,
+            dispatcher=dispatcher,
+            github=github,
+            worktree=worktree,
+            dashboard=dashboard,
+            state_db=db,
+            transport=transport,
+            contexts_dir=config.paths.contexts,
+        )
+
+    try:
+        results = asyncio.run(_run())
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+    finally:
+        db.close()
+
+    success_count = sum(1 for r in results if r.success)
+    console.print(f"\n[bold]Results:[/bold] {success_count}/{len(results)} succeeded")
+
+    for result in results:
+        status = "[green]OK[/green]" if result.success else "[red]FAIL[/red]"
+        console.print(f"  {status} {result.summary}")
+        # Surface the blocking question / error text so an operator
+        # running secops at the CLI doesn't have to dig into state.db
+        # to see what the agent was asking. The scheduler closure
+        # already relays these via Telegram; this is the manual path.
+        if result.blocked and result.question:
+            console.print(f"    [yellow]Question:[/yellow] {result.question}")
+        elif not result.success and result.error:
+            console.print(f"    [red]Error:[/red] {result.error}")
+
+    if not all(r.success for r in results):
+        raise typer.Exit(1)
+
+
+@run_app.command("dev")
+def run_dev(
+    issue: int = typer.Option(
+        ...,
+        "--issue",
+        "-i",
+        help="GitHub issue number to implement",
+    ),
+    repo: str = typer.Option(
+        None,
+        "--repo",
+        "-r",
+        help="Run on specific repo only",
+    ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Run dev pipeline for a GitHub issue."""
+    import asyncio
+
+    from ctrlrelay.core.dispatcher import make_agent_dispatcher
+    from ctrlrelay.core.github import GitHubCLI
+    from ctrlrelay.core.state import StateDB
+    from ctrlrelay.core.worktree import WorktreeManager
+    from ctrlrelay.pipelines.dev import run_dev_issue
+
+    path = _resolve_config_or_exit(config_path)
+
+    try:
+        config = load_config(path)
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+    repos = config.repos
+    if repo:
+        repos = [r for r in repos if r.name == repo]
+        if not repos:
+            console.print(f"[red]Repo not found:[/red] {repo}")
+            raise typer.Exit(1)
+
+    if not repos:
+        console.print("[yellow]No repos configured.[/yellow]")
+        return
+
+    if len(repos) > 1 and not repo:
+        console.print(
+            "[red]Error:[/red] Multiple repos configured. "
+            "Use --repo to specify which one."
+        )
+        raise typer.Exit(1)
+
+    repo_config = repos[0]
+    branch_template = repo_config.dev_branch_template
+
+    db = StateDB(config.paths.state_db)
+    dispatcher = make_agent_dispatcher(config.agent)
+    github = GitHubCLI()
+    worktree = WorktreeManager(
+        worktrees_dir=config.paths.worktrees,
+        bare_repos_dir=config.paths.bare_repos,
+    )
+
+    dashboard = None
+    if config.dashboard.enabled and config.dashboard.url:
+        import os
+        token = os.environ.get(config.dashboard.auth_token_env, "")
+        if token:
+            from ctrlrelay.dashboard.client import DashboardClient
+            dashboard = DashboardClient(
+                url=config.dashboard.url,
+                auth_token=token,
+                node_id=config.node_id,
+                queue_dir=config.paths.state_db.parent / "event_queue",
+            )
+
+    console.print(f"Running dev pipeline for issue #{issue} on {repo_config.name}...")
+
+    async def _run():
+        return await run_dev_issue(
+            repo=repo_config.name,
+            issue_number=issue,
+            branch_template=branch_template,
+            dispatcher=dispatcher,
+            github=github,
+            worktree=worktree,
+            dashboard=dashboard,
+            state_db=db,
+            transport=None,
+            contexts_dir=config.paths.contexts,
+            ci_wait_timeout_seconds=repo_config.automation.ci_wait_timeout_seconds,
+        )
+
+    try:
+        result = asyncio.run(_run())
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+    finally:
+        db.close()
+
+    if result.success:
+        pr_url = result.outputs.get("pr_url", "") if result.outputs else ""
+        console.print(f"[green]Success:[/green] {result.summary}")
+        if pr_url:
+            console.print(f"  PR: {pr_url}")
+    elif result.blocked:
+        console.print(f"[blue]Blocked:[/blue] {result.summary}")
+        if result.question:
+            console.print(f"  Question: {result.question}")
+        raise typer.Exit(1)
+    else:
+        console.print(f"[red]Failed:[/red] {result.summary}")
+        if result.error:
+            console.print(f"  Error: {result.error}")
+        raise typer.Exit(1)
+
+
+# CI subcommand group
+# Exists so the dev pipeline has a correct, exit-code-driven helper to wait
+# on PR checks. Claude used to improvise bash `until gh pr checks` loops that
+# were inverted-semantics and swallowed exit codes (see issue #85), burning
+# the whole session timeout on PRs that had already gone green.
+ci_app = typer.Typer(help="CI helpers.")
+app.add_typer(ci_app, name="ci")
+
+
+@ci_app.command("wait")
+def ci_wait(
+    pr: int = typer.Option(..., "--pr", "-p", help="PR number to wait on"),
+    repo: str = typer.Option(..., "--repo", "-r", help="Repository as owner/name"),
+    timeout: int = typer.Option(
+        600,
+        "--timeout",
+        "-t",
+        help="Hard timeout in seconds before giving up (exit 2).",
+    ),
+    interval: int = typer.Option(
+        15,
+        "--interval",
+        "-i",
+        help="Poll interval in seconds.",
+    ),
+) -> None:
+    """Wait for a PR's CI checks to finish.
+
+    Exit codes:
+      0 — all checks passed (or no CI configured)
+      1 — at least one check failed / cancelled / timed_out
+      2 — hard timeout hit while checks were still pending
+    """
+    import asyncio
+
+    github = GitHubCLI()
+    verifier = PRVerifier(
+        github=github,
+        poll_interval=interval,
+        check_timeout=timeout,
+    )
+
+    try:
+        checks = asyncio.run(
+            verifier.wait_for_checks(repo, pr, timeout=timeout)
+        )
+    except (GitHubError, asyncio.TimeoutError) as e:
+        # wait_for_checks already retries transient errors internally;
+        # this except is defense-in-depth for any leak past the retry
+        # window (e.g. repeated timeouts that exhaust the deadline
+        # mid-call). Surface a clean message instead of a traceback.
+        console.print(
+            f"[red]gh error ({type(e).__name__}):[/red] {e}"
+        )
+        raise typer.Exit(1) from e
+
+    pending = [c for c in checks if c.get("bucket") == "pending"]
+    failing = [
+        c for c in checks
+        if c.get("bucket") not in ("pending", "pass", "skipping")
+    ]
+
+    if failing:
+        names = ", ".join(
+            f"{c.get('name', '?')}={c.get('state') or c.get('bucket')}"
+            for c in failing
+        )
+        console.print(f"[red]CI failing:[/red] {names}")
+        raise typer.Exit(1)
+
+    if pending:
+        names = ", ".join(c.get("name", "?") for c in pending)
+        console.print(
+            f"[yellow]CI still running after {timeout}s:[/yellow] {names}"
+        )
+        raise typer.Exit(2)
+
+    if checks:
+        console.print(f"[green]All {len(checks)} check(s) passed.[/green]")
+    else:
+        console.print("[green]No CI checks configured — treating as pass.[/green]")
+
+
+# Poller subcommand group
+poller_app = typer.Typer(help="Issue poller commands.")
+app.add_typer(poller_app, name="poller")
+
+
+def _get_poller_pid_file(config_path: str | None) -> Path:
+    """Get PID file path for poller process."""
+    try:
+        config = load_config(resolve_config_path(config_path))
+        return config.paths.state_db.parent / "poller.pid"
+    except ConfigError:
+        pass
+    return Path("~/.ctrlrelay/poller.pid").expanduser().resolve()
+
+
+@poller_app.command("start")
+def poller_start(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    foreground: bool = typer.Option(
+        False,
+        "--foreground",
+        "-F",
+        help="Run in the foreground (for launchd/systemd/debugging). Default is to daemonize.",
+    ),
+    interval: int = typer.Option(
+        300,
+        "--interval",
+        "-i",
+        help="Polling interval in seconds",
+    ),
+) -> None:
+    """Start the issue poller.
+
+    Daemonizes by default so the terminal returns to you. Pass --foreground
+    under a process supervisor (launchd Type=simple, systemd Type=simple) or
+    when debugging interactively.
+    """
+    import asyncio
+    import os
+    import signal
+    import subprocess
+    import sys
+
+    resolved_config = _resolve_config_or_exit(config_path)
+
+    try:
+        config = load_config(resolved_config)
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+    pid_file = _get_poller_pid_file(str(resolved_config))
+    if pid_file.exists():
+        try:
+            pid = int(pid_file.read_text().strip())
+            if pid == os.getpid():
+                # The daemon parent wrote our own PID here before spawning us
+                # as the `--foreground` child. Don't treat it as a conflict.
+                pass
+            else:
+                os.kill(pid, 0)
+                console.print(f"[yellow]Poller already running (PID {pid})[/yellow]")
+                raise typer.Exit(1)
+        except (ProcessLookupError, ValueError):
+            pid_file.unlink(missing_ok=True)
+    pid_file.parent.mkdir(parents=True, exist_ok=True)
+
+    if not foreground:
+        cmd = [
+            sys.executable,
+            "-m",
+            "ctrlrelay.cli",
+            "poller",
+            "start",
+            "--config",
+            str(resolved_config),
+            "--interval",
+            str(interval),
+            "--foreground",
+        ]
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+        # Claim the PID file BEFORE the liveness probe; otherwise a second
+        # concurrent `start` in the 1-second window would see no PID file and
+        # spawn a duplicate poller.
+        pid_file.write_text(str(proc.pid))
+        try:
+            proc.wait(timeout=1.0)
+        except subprocess.TimeoutExpired:
+            console.print(f"[green]Poller started (PID {proc.pid})[/green]")
+            return
+        # Child exited. Zero = clean no-op (e.g. `repos: []`); non-zero = crash.
+        pid_file.unlink(missing_ok=True)
+        if proc.returncode == 0:
+            console.print(
+                "[yellow]Poller exited immediately with no work to do "
+                "(check `repos:` in your config).[/yellow]"
+            )
+            return
+        console.print(
+            f"[red]Poller failed to start[/red] "
+            f"(child exited with code {proc.returncode})"
+        )
+        raise typer.Exit(1)
+
+    # Install SIGTERM/SIGINT handlers BEFORE any startup work so a supervisor
+    # stop during `gh api user` / `seed_current()` still unwinds through the
+    # `finally` that unlinks poller.pid. Converting the signal into SystemExit
+    # lets Python's normal unwind run `finally` blocks. Once the asyncio loop
+    # is up below, `loop.add_signal_handler` overrides these to drive a
+    # graceful cancel of the poll loop.
+    def _raise_systemexit_on_signal(sig: int, _frame: object) -> None:
+        raise SystemExit(0)
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        signal.signal(sig, _raise_systemexit_on_signal)
+
+    pid_file.write_text(str(os.getpid()))
+    try:
+        from ctrlrelay.core.dispatcher import make_agent_dispatcher
+        from ctrlrelay.core.github import GitHubCLI
+        from ctrlrelay.core.poller import IssuePoller, run_poll_loop
+        from ctrlrelay.core.scheduler import make_scheduler
+        from ctrlrelay.core.state import StateDB
+        from ctrlrelay.core.worktree import WorktreeManager
+        from ctrlrelay.pipelines.dev import run_dev_issue
+        from ctrlrelay.pipelines.post_merge import (
+            DEFAULT_PR_WATCH_TIMEOUT,
+            pr_watch_task,
+        )
+        from ctrlrelay.pipelines.secops import run_secops_all
+
+        # Build a DashboardClient if configured BEFORE the gh probe runs,
+        # so even if gh fails the user gets clear failure ordering and so
+        # tests can short-circuit at gh while still observing this wiring.
+        # Mirrors what `ctrlrelay run secops` does for the manual path.
+        scheduled_dashboard = None
+        if config.dashboard.enabled and config.dashboard.url:
+            token = os.environ.get(config.dashboard.auth_token_env, "")
+            if token:
+                from ctrlrelay.dashboard.client import DashboardClient
+                scheduled_dashboard = DashboardClient(
+                    url=config.dashboard.url,
+                    auth_token=token,
+                    node_id=config.node_id,
+                    queue_dir=config.paths.state_db.parent / "event_queue",
+                )
+
+        github = GitHubCLI()
+
+        # Get GitHub username
+        try:
+            from ctrlrelay.core.github import _find_gh
+            gh_bin = _find_gh()
+            result = subprocess.run(
+                [gh_bin, "api", "user", "--jq", ".login"],
+                capture_output=True,
+                text=True,
+                check=True,
+                # Without this a hung gh hangs `poller start` forever, and
+                # the TimeoutExpired branch of the classifier — the one
+                # case that really does mean connectivity — can never fire.
+                timeout=_GH_PROBE_TIMEOUT_SECONDS,
+            )
+            username = result.stdout.strip()
+        except (subprocess.SubprocessError, OSError) as e:
+            # `gh` exits 1 for offline, expired-token and API-error alike,
+            # so classify from its stderr — otherwise operators debug auth
+            # when the laptop is simply offline (#32).
+            from ctrlrelay.core.network import gh_failure_from_exception
+
+            failure = gh_failure_from_exception(e)
+            color = "yellow" if failure.is_transient else "red"
+            console.print(
+                f"[{color}]Could not determine GitHub username:[/{color}] "
+                f"{failure.message}"
+            )
+            if failure.stderr:
+                # gh's stderr is arbitrary text and Rich parses [...] as
+                # markup: a stderr containing something like "[/docs]"
+                # raises MarkupError, which replaces the diagnostic with a
+                # traceback and skips the exit — losing exactly the detail
+                # this line exists to show.
+                console.print(
+                    f"[dim]gh: {rich_escape(failure.stderr)}[/dim]"
+                )
+            raise typer.Exit(1)
+
+        if not username:
+            console.print("[red]Could not determine GitHub username.[/red]")
+            raise typer.Exit(1)
+
+        repo_names = [r.name for r in config.repos]
+        if not repo_names:
+            console.print("[yellow]No repos configured.[/yellow]")
+            return
+
+        accept_foreign = {
+            r.name for r in config.repos if r.automation.accept_foreign_assignments
+        }
+
+        state_file = config.paths.state_db.parent / "poller_state.json"
+
+        first_run = not state_file.exists()
+
+        exclude_labels_by_repo = {
+            r.name: list(r.automation.exclude_labels) for r in config.repos
+        }
+        include_labels_by_repo = {
+            r.name: list(r.automation.include_labels) for r in config.repos
+        }
+        require_labels_by_repo = {
+            r.name: list(r.automation.require_labels) for r in config.repos
+        }
+
+        poller = IssuePoller(
+            github=github,
+            username=username,
+            repos=repo_names,
+            state_file=state_file,
+            accept_foreign_assignments=accept_foreign,
+            exclude_labels_by_repo=exclude_labels_by_repo,
+            include_labels_by_repo=include_labels_by_repo,
+            require_labels_by_repo=require_labels_by_repo,
+        )
+
+        # NOTE: first-run seeding moved into `_main()` so the APScheduler
+        # cron is registered + running BEFORE the slow seed_current() pass
+        # (one GitHub API call per repo) takes place. Otherwise the 6am
+        # scheduled fire can pass during startup and APScheduler's misfire
+        # grace only catches up on fires that happened AFTER registration.
+
+        state_db = StateDB(config.paths.state_db)
+        dispatcher = make_agent_dispatcher(config.agent)
+        worktree = WorktreeManager(
+            worktrees_dir=config.paths.worktrees,
+            bare_repos_dir=config.paths.bare_repos,
+        )
+
+        # Set up transport for notifications
+        transport = None
+        if config.transport.type.value == "telegram" and config.transport.telegram:
+            from ctrlrelay.transports import SocketTransport
+            socket_path = config.transport.telegram.socket_path.expanduser().resolve()
+            if socket_path.exists():
+                transport = SocketTransport(
+                    socket_path,
+                    ask_timeout_seconds=(
+                        config.transport.telegram.ask_timeout_seconds
+                    ),
+                )
+                console.print(f"[dim]Telegram transport enabled via {socket_path}[/dim]")
+            else:
+                console.print(f"[yellow]Telegram socket not found at {socket_path}[/yellow]")
+                console.print(
+                    "[yellow]Run 'ctrlrelay bridge start' to enable notifications[/yellow]"
+                )
+
+        # Track in-flight PR-watch background tasks so they outlive
+        # handle_issue and aren't garbage-collected. Cleared via
+        # done_callback as each task terminates.
+        pr_watch_tasks: set[asyncio.Task] = set()
+        # Dedup key: only ONE watcher may run for a given (repo, pr_number)
+        # at a time. Without this, two spawn paths (rehydration + a
+        # handle_issue re-run after corrupted poller state) can race
+        # through _handle_merge_with_retry and duplicate the close
+        # comment / notification. Entries removed via done_callback
+        # below, paired with the task's removal from pr_watch_tasks.
+        active_pr_watches: set[tuple[str, int]] = set()
+
+        def _spawn_pr_watch(
+            *,
+            repo: str,
+            issue_number: int,
+            pr_url: str,
+            pr_number: int,
+            session_id: str | None,
+            timeout: int | None = None,
+            skip_initial_persist: bool = False,
+        ) -> asyncio.Task | None:
+            """Start a pr_watch_task for (repo, pr_number) unless one is
+            already running for the same key. Returns the task on spawn,
+            None if a duplicate was suppressed.
+
+            The pr_watches row is persisted SYNCHRONOUSLY before the
+            coroutine is scheduled. asyncio.create_task only queues the
+            coroutine — its body doesn't execute until the loop next
+            yields, so a shutdown between create_task and the first
+            await inside pr_watch_task would otherwise lose the row
+            entirely (no rehydrate after restart). Writing first closes
+            that gap.
+
+            ``skip_initial_persist`` is for rehydration: the row
+            already exists in pr_watches (that's how we know to spawn),
+            and re-writing it would be harmless but wasteful.
+            """
+            key = (repo, pr_number)
+            if key in active_pr_watches:
+                return None
+            if state_db is not None and not skip_initial_persist:
+                try:
+                    state_db.add_pr_watch(
+                        repo=repo, pr_number=pr_number,
+                        issue_number=issue_number,
+                        session_id=session_id,
+                        pr_url=pr_url,
+                    )
+                except Exception:
+                    # Persist failure is logged inside pr_watch_task on
+                    # its own attempt; don't abort the spawn here, the
+                    # watcher can still run in-memory like the legacy
+                    # pre-persistence code did.
+                    pass
+            active_pr_watches.add(key)
+            kwargs: dict = dict(
+                repo=repo,
+                issue_number=issue_number,
+                pr_url=pr_url,
+                pr_number=pr_number,
+                session_id=session_id,
+                github=github,
+                transport_factory=_watch_transport_factory,
+                state_db=state_db,
+            )
+            if timeout is not None:
+                kwargs["timeout"] = timeout
+            task = asyncio.create_task(pr_watch_task(**kwargs))
+            pr_watch_tasks.add(task)
+
+            def _on_done(t: asyncio.Task) -> None:
+                pr_watch_tasks.discard(t)
+                active_pr_watches.discard(key)
+
+            task.add_done_callback(_on_done)
+            return task
+
+        async def _watch_transport_factory():
+            """Build a fresh connected SocketTransport for a single watcher,
+            independent of the transport used in handle_issue (which is
+            closed on exit).
+
+            Return None ONLY when Telegram notifications aren't
+            configured at all — that's a legitimate "no channel" signal
+            and the retry loop treats it as clean success. A configured-
+            but-currently-missing socket is a transient outage (bridge
+            restart, daemon crash mid-merge), so RAISE to trigger the
+            retry path; the next attempt will reach the socket once the
+            bridge is back.
+            """
+            if config.transport.type.value != "telegram" or not config.transport.telegram:
+                return None
+            from ctrlrelay.transports import SocketTransport
+            socket_path = config.transport.telegram.socket_path.expanduser().resolve()
+            if not socket_path.exists():
+                raise FileNotFoundError(
+                    f"Telegram bridge socket missing at {socket_path}; "
+                    "retryable — bridge may be restarting"
+                )
+            watch_transport = SocketTransport(
+                socket_path,
+                ask_timeout_seconds=(
+                    config.transport.telegram.ask_timeout_seconds
+                ),
+            )
+            await watch_transport.connect()
+            return watch_transport
+
+        async def handle_issue(repo: str, issue: dict) -> None:
+            issue_number = issue["number"]
+            title = issue.get("title", "")
+            console.print(
+                f"[green]New issue detected:[/green] #{issue_number} in {repo} — {title}"
+            )
+
+            # Connect transport for notifications
+            connected_transport = None
+            if transport:
+                try:
+                    await transport.connect()
+                    connected_transport = transport
+                    await transport.send(f"🔔 New issue #{issue_number} in {repo}: {title}")
+                except Exception as e:
+                    console.print(f"[yellow]Transport error: {e}[/yellow]")
+
+            # Find matching repo config
+            repo_configs = [r for r in config.repos if r.name == repo]
+            if not repo_configs:
+                console.print(f"[yellow]No config found for repo {repo}, skipping.[/yellow]")
+                if connected_transport:
+                    await transport.close()
+                return
+
+            repo_config = repo_configs[0]
+
+            # Route by label: task_labels → task pipeline (report-only,
+            # no PR), otherwise dev pipeline. Case-insensitive match on
+            # the issue's label names. exclude_labels was already
+            # applied in poller.poll() so any issue reaching
+            # handle_issue is a candidate.
+            issue_labels = {
+                (lbl.get("name") or "").lower()
+                for lbl in (issue.get("labels") or [])
+            }
+            task_labels_lower = {
+                lbl.lower() for lbl in repo_config.automation.task_labels
+            }
+            is_task = bool(issue_labels & task_labels_lower)
+
+            try:
+                if is_task:
+                    from ctrlrelay.pipelines.task import run_task_issue
+                    console.print(
+                        f"[dim]#{issue_number} routed to task "
+                        f"pipeline (matched labels: "
+                        f"{sorted(issue_labels & task_labels_lower)})[/dim]"
+                    )
+                    result = await run_task_issue(
+                        repo=repo,
+                        issue_number=issue_number,
+                        dispatcher=dispatcher,
+                        github=github,
+                        worktree=worktree,
+                        dashboard=None,
+                        state_db=state_db,
+                        transport=connected_transport,
+                        contexts_dir=config.paths.contexts,
+                    )
+                else:
+                    result = await run_dev_issue(
+                        repo=repo,
+                        issue_number=issue_number,
+                        branch_template=repo_config.dev_branch_template,
+                        dispatcher=dispatcher,
+                        github=github,
+                        worktree=worktree,
+                        dashboard=None,
+                        state_db=state_db,
+                        transport=connected_transport,
+                        contexts_dir=config.paths.contexts,
+                        ci_wait_timeout_seconds=repo_config.automation.ci_wait_timeout_seconds,
+                    )
+
+                # Lock-conflict retry hook. The poller marks issues seen
+                # BEFORE handle_issue runs, so a failed attempt would
+                # permanently drop the issue. If run_dev_issue couldn't
+                # acquire the per-repo lock up front (common when a
+                # scheduled secops sweep is mid-run on the same repo),
+                # un-mark the issue so the next poll picks it up. Any
+                # other failure still stays seen — those aren't transient.
+                if (
+                    not result.success
+                    and not result.blocked
+                    and result.error
+                    and "locked by another session" in result.error.lower()
+                ):
+                    poller.unmark_seen(repo, issue_number)
+                    console.print(
+                        f"[yellow]#{issue_number} in {repo}: repo locked "
+                        "(secops running?) — un-marked for retry next "
+                        "poll.[/yellow]"
+                    )
+                    if connected_transport:
+                        try:
+                            await transport.send(
+                                f"⏳ #{issue_number} in {repo} "
+                                "deferred (repo busy); will retry."
+                            )
+                        except Exception:
+                            pass
+                    return
+
+                # Lock-contended DURING PR verification (issue #29): the
+                # PR already exists AND verification decided it wasn't
+                # ready (_verify_and_fix_pr only returns this error from
+                # the "need to run request_fix but couldn't reacquire"
+                # path). Two sub-cases based on whether run_dev_issue's
+                # cleanup reacquire succeeded:
+                #
+                # (a) Cleanup clean (lock reclaimed, worktree torn down):
+                #     un-mark the issue so the next poll retries the fix.
+                #     run_dev_issue's branch-reuse path handles
+                #     "issue already has a branch / PR" (#51, #52).
+                #
+                # (b) Cleanup deferred (peer still holds lock; worktree
+                #     NOT removed): un-marking would make the next poll
+                #     call create_worktree_with_new_branch and fail
+                #     with "already checked out" because the abandoned
+                #     worktree metadata is still registered. Leave the
+                #     issue seen and log an operator-actionable warning;
+                #     a poller restart (or `git worktree prune`) will
+                #     clear the stale entry.
+                #
+                # Either way the merge watcher still spawns below so
+                # the existing PR's auto-close works if a human merges.
+                if (
+                    not result.success
+                    and not result.blocked
+                    and result.error
+                    and "reacquire contended during pr verification"
+                    in result.error.lower()
+                ):
+                    pr_num_str = result.outputs.get("pr_number", "?")
+                    cleanup_deferred = bool(
+                        result.outputs.get("cleanup_deferred")
+                    )
+                    if cleanup_deferred:
+                        console.print(
+                            f"[red]#{issue_number} in {repo}: lock "
+                            "contention during PR verification AND "
+                            "cleanup could not reclaim the lock after "
+                            "the full fix budget (~1 hour). A peer "
+                            "session is wedged. Operator action: "
+                            "identify the peer holding the lock on "
+                            f"repo_locks for {repo} (via `sqlite3 "
+                            "state.db 'SELECT * FROM repo_locks'`), "
+                            "investigate/kill it, then `git worktree "
+                            "remove --force` on the session's "
+                            "worktree directory before re-assigning "
+                            f"issue #{issue_number}. "
+                            f"PR #{pr_num_str} already exists on "
+                            "GitHub and is being watched for merge."
+                            "[/red]"
+                        )
+                    else:
+                        poller.unmark_seen(repo, issue_number)
+                        console.print(
+                            f"[yellow]#{issue_number} in {repo}: lock "
+                            "contention during PR verification — "
+                            f"un-marking for retry (PR #{pr_num_str} "
+                            "needs another fix round). Merge watcher "
+                            "still spawns.[/yellow]"
+                        )
+
+                # Spawn the PR watcher FIRST, before any best-effort
+                # notification. The poller has already marked this issue
+                # as seen in poller_state.json, so if a transient
+                # transport.send failure below raised through the outer
+                # finally, we'd permanently lose the watcher and the
+                # issue would never auto-close on merge.
+                pr_number_raw = result.outputs.get("pr_number")
+                pr_url_str = result.outputs.get("pr_url", "")
+                if pr_number_raw is not None:
+                    try:
+                        pr_number = int(pr_number_raw)
+                    except (TypeError, ValueError):
+                        pr_number = None
+                    if pr_number is not None:
+                        _spawn_pr_watch(
+                            repo=repo,
+                            issue_number=issue_number,
+                            pr_url=pr_url_str,
+                            pr_number=pr_number,
+                            session_id=result.session_id,
+                        )
+
+                # Send result notification — best-effort. A failed send
+                # must NOT prevent the merge watcher (spawned above)
+                # from running, so swallow transport errors here.
+                if connected_transport:
+                    try:
+                        if result.success:
+                            if is_task:
+                                await transport.send(
+                                    f"✅ Task done on #{issue_number} "
+                                    f"({repo}): {result.summary}"
+                                )
+                            else:
+                                pr_url = result.outputs.get("pr_url", "")
+                                await transport.send(
+                                    f"✅ PR ready: {pr_url}"
+                                )
+                        elif result.blocked:
+                            await transport.send(
+                                f"⏸️ Blocked on #{issue_number}: {result.question}"
+                            )
+                        else:
+                            await transport.send(
+                                f"❌ Failed on #{issue_number}: "
+                                f"{result.error or result.summary}"
+                            )
+                    except Exception as e:
+                        console.print(
+                            f"[yellow]Transport error sending result: {e}[/yellow]"
+                        )
+            finally:
+                if connected_transport:
+                    await transport.close()
+
+        console.print(f"[green]Starting poller[/green] for {len(repo_names)} repo(s) as {username}")
+        console.print(f"  Interval: {interval}s | Press Ctrl+C to stop")
+
+        async def _run_scheduled_secops() -> None:
+            """Scheduler callback: run the secops sweep across all repos.
+
+            Shares the poller's open state_db, github, dispatcher, and
+            worktree. Per-repo locks in the state DB prevent collisions
+            with an in-flight dev pipeline (and the dev handler now
+            retries on lock-conflict so issues aren't silently dropped).
+
+            Builds a fresh SocketTransport per run so blocked/failed
+            results notify Telegram — the dashboard only pushes for
+            successful runs, so without a transport here operators would
+            lose visibility into scheduled failures.
+            """
+            if not config.repos:
+                return
+            n_repos = len(config.repos)
+            console.print(
+                f"[dim]Scheduled secops: starting across {n_repos} repo(s)[/dim]"
+            )
+
+            secops_transport = None
+            if config.transport.type.value == "telegram" and config.transport.telegram:
+                from ctrlrelay.transports import SocketTransport
+                sock = config.transport.telegram.socket_path.expanduser().resolve()
+                if sock.exists():
+                    try:
+                        candidate = SocketTransport(
+                            sock,
+                            ask_timeout_seconds=(
+                                config.transport.telegram
+                                .ask_timeout_seconds
+                            ),
+                        )
+                        await candidate.connect()
+                        secops_transport = candidate
+                    except Exception as e:
+                        console.print(
+                            f"[yellow]Scheduled secops: transport connect "
+                            f"failed ({e}) — running without notifications[/yellow]"
+                        )
+
+            # Tell the operator the sweep started so a long run isn't
+            # silent. Without this, a 10-min sweep that ends with a
+            # blocked-on-input result looks like "out of nowhere" pings.
+            if secops_transport:
+                try:
+                    await secops_transport.send(
+                        f"🔄 Scheduled secops: starting sweep across "
+                        f"{n_repos} repo(s)"
+                    )
+                except Exception as e:
+                    console.print(
+                        f"[yellow]Scheduled secops: start-notify failed: "
+                        f"{e}[/yellow]"
+                    )
+
+            try:
+                results = await run_secops_all(
+                    repos=config.repos,
+                    dispatcher=dispatcher,
+                    github=github,
+                    worktree=worktree,
+                    dashboard=scheduled_dashboard,
+                    state_db=state_db,
+                    transport=secops_transport,
+                    contexts_dir=config.paths.contexts,
+                )
+                ok = sum(1 for r in results if r.success)
+                console.print(
+                    f"[dim]Scheduled secops: {ok}/{len(results)} succeeded[/dim]"
+                )
+
+                # Per-repo notifications for the cases an operator must
+                # act on. The aggregate "N blocked" message we used to
+                # send was useless on its own — it didn't say which
+                # repos blocked or what the question was. Fan out one
+                # message per blocked or failed result with the actual
+                # question/error and session id so the operator can
+                # respond directly via the bridge.
+                #
+                # `run_secops_all` returns results in the same order as
+                # the input `repos` list, so zip is safe — only repos
+                # with successful lock-acquisition produce results.
+                if secops_transport:
+                    try:
+                        for repo_cfg, result in zip(
+                            config.repos, results, strict=False
+                        ):
+                            if result.blocked:
+                                question = (
+                                    result.question or "(no question text)"
+                                )
+                                # session_id makes this message
+                                # reply-to-able: the bridge records it, so
+                                # answering the fan-out resolves the same
+                                # pending_resumes row as answering the
+                                # original question would have.
+                                await secops_transport.send(
+                                    f"⏸️ Scheduled secops blocked on "
+                                    f"{repo_cfg.name}\n"
+                                    f"Session: {result.session_id}\n"
+                                    f"\nReply to this message to answer."
+                                    f"\n\n{question}",
+                                    session_id=result.session_id,
+                                    repo=repo_cfg.name,
+                                )
+                            elif not result.success:
+                                err = result.error or result.summary
+                                await secops_transport.send(
+                                    f"❌ Scheduled secops failed on "
+                                    f"{repo_cfg.name}\n"
+                                    f"Session: `{result.session_id}`\n"
+                                    f"\n{err}"
+                                )
+                        # Final at-a-glance summary — kept because it's
+                        # the single message the operator scans first.
+                        blocked_n = sum(1 for r in results if r.blocked)
+                        failed_n = sum(
+                            1 for r in results
+                            if not r.success and not r.blocked
+                        )
+                        if blocked_n or failed_n:
+                            parts = []
+                            if blocked_n:
+                                parts.append(f"{blocked_n} blocked")
+                            if failed_n:
+                                parts.append(f"{failed_n} failed")
+                            await secops_transport.send(
+                                f"📋 Scheduled secops sweep done: "
+                                f"{ok}/{len(results)} ok, "
+                                f"{', '.join(parts)}"
+                            )
+                        else:
+                            await secops_transport.send(
+                                f"✅ Scheduled secops sweep done: "
+                                f"{ok}/{len(results)} ok"
+                            )
+                    except Exception as e:
+                        console.print(
+                            f"[yellow]Scheduled secops: notify failed: {e}[/yellow]"
+                        )
+            finally:
+                if secops_transport:
+                    try:
+                        await secops_transport.close()
+                    except Exception:
+                        pass
+
+        async def _run_question_expiry_sweeper() -> None:
+            """Retire BLOCKED questions the operator can no longer
+            usefully answer: aged past the TTL, or whose cited PRs and
+            issues have all been closed or merged outside ctrlrelay.
+
+            Hourly, not per-minute: expiry is never urgent, and the
+            resolved-elsewhere pass costs one `gh api` read per cited
+            number. TTL runs first and needs no network, so a GitHub
+            outage still lets the age-based sweep make progress.
+            """
+            ttl = getattr(
+                getattr(config.transport, "telegram", None),
+                "question_ttl_seconds",
+                None,
+            )
+            if not ttl:
+                return
+            try:
+                expired = await expire_stale_questions(
+                    state_db, github, ttl_seconds=ttl,
+                )
+            except Exception as e:
+                console.print(
+                    f"[yellow]question_expiry_sweeper: failed ({e})[/yellow]"
+                )
+                return
+            for row in expired:
+                console.print(
+                    f"[dim]question_expiry: retired "
+                    f"{row['session_id']} ({row['expired_reason']})[/dim]"
+                )
+
+        async def _run_pending_resume_sweeper() -> None:
+            """Drain pending_resumes rows that an operator answered via
+            Telegram while the original BLOCKED session had already torn
+            down.
+
+            Runs every minute inside the poller. For each answered row
+            it acquires the repo lock, re-creates a worktree, calls
+            ``SecopsPipeline.resume(ctx, answer)`` via the shared
+            ``resume_secops_from_pending`` helper, then marks the row
+            resumed and fans out a Telegram notification with the result
+            so the operator knows whether the resume landed.
+            """
+            try:
+                pending = state_db.list_pending_resumes_to_execute()
+            except Exception as e:
+                console.print(
+                    f"[yellow]pending_resume_sweeper: list failed ({e})"
+                    f"[/yellow]"
+                )
+                return
+            if not pending:
+                return
+
+            from ctrlrelay.pipelines.dev import resume_dev_from_pending
+            from ctrlrelay.pipelines.secops import resume_secops_from_pending
+            from ctrlrelay.pipelines.task import resume_task_from_pending
+
+            sweeper_transport = None
+            if config.transport.type.value == "telegram" and config.transport.telegram:
+                from ctrlrelay.transports import SocketTransport
+                sock = config.transport.telegram.socket_path.expanduser().resolve()
+                if sock.exists():
+                    try:
+                        candidate = SocketTransport(
+                            sock,
+                            ask_timeout_seconds=(
+                                config.transport.telegram
+                                .ask_timeout_seconds
+                            ),
+                        )
+                        await candidate.connect()
+                        sweeper_transport = candidate
+                    except Exception:
+                        sweeper_transport = None
+
+            repo_cfg_by_name = {r.name: r for r in config.repos}
+
+            try:
+                for row in pending:
+                    session_id = row["session_id"]
+                    repo = row["repo"]
+                    pipeline_name = row["pipeline"]
+                    answer = row["answer"] or ""
+
+                    if sweeper_transport:
+                        try:
+                            await sweeper_transport.send(
+                                f"🔁 Resuming BLOCKED session "
+                                f"`{session_id}` on {repo} with your "
+                                f"answer..."
+                            )
+                        except Exception:
+                            pass
+
+                    try:
+                        if pipeline_name == "secops":
+                            sweep_repo_cfg = repo_cfg_by_name.get(repo)
+                            result = await resume_secops_from_pending(
+                                session_id=session_id,
+                                repo=repo,
+                                answer=answer,
+                                dispatcher=dispatcher,
+                                github=github,
+                                worktree=worktree,
+                                dashboard=scheduled_dashboard,
+                                state_db=state_db,
+                                transport=sweeper_transport,
+                                contexts_dir=config.paths.contexts,
+                                automation=(
+                                    sweep_repo_cfg.automation
+                                    if sweep_repo_cfg is not None
+                                    else None
+                                ),
+                                question=row.get("question"),
+                            )
+                        elif pipeline_name == "dev":
+                            # Dev resume needs the repo's branch template
+                            # to reconstruct the session's existing branch
+                            # name (fix/issue-<n> by default). If the
+                            # repo fell out of config (rename, removal),
+                            # we can't safely resume — mark resumed so
+                            # the row doesn't hot-loop and log it.
+                            repo_cfg = repo_cfg_by_name.get(repo)
+                            if repo_cfg is None:
+                                console.print(
+                                    "[yellow]pending_resume_sweeper: "
+                                    f"dev resume for {repo} skipped — "
+                                    "repo not in current config. "
+                                    f"Session={session_id}[/yellow]"
+                                )
+                                try:
+                                    state_db.mark_pending_resume_resumed(
+                                        session_id
+                                    )
+                                except Exception:
+                                    pass
+                                continue
+                            result = await resume_dev_from_pending(
+                                session_id=session_id,
+                                repo=repo,
+                                answer=answer,
+                                branch_template=repo_cfg.dev_branch_template,
+                                dispatcher=dispatcher,
+                                github=github,
+                                worktree=worktree,
+                                dashboard=scheduled_dashboard,
+                                state_db=state_db,
+                                transport=sweeper_transport,
+                                contexts_dir=config.paths.contexts,
+                            )
+                        elif pipeline_name == "task":
+                            result = await resume_task_from_pending(
+                                session_id=session_id,
+                                repo=repo,
+                                answer=answer,
+                                dispatcher=dispatcher,
+                                github=github,
+                                worktree=worktree,
+                                dashboard=scheduled_dashboard,
+                                state_db=state_db,
+                                transport=sweeper_transport,
+                                contexts_dir=config.paths.contexts,
+                            )
+                        else:
+                            console.print(
+                                "[yellow]pending_resume_sweeper: "
+                                f"unknown pipeline '{pipeline_name}' "
+                                f"for session {session_id} — marking "
+                                "resumed to avoid hot-loop[/yellow]"
+                            )
+                            try:
+                                state_db.mark_pending_resume_resumed(
+                                    session_id
+                                )
+                            except Exception:
+                                pass
+                            continue
+                    except Exception as e:
+                        if sweeper_transport:
+                            try:
+                                await sweeper_transport.send(
+                                    f"❌ Resume of `{session_id}` on "
+                                    f"{repo} crashed: {e}"
+                                )
+                            except Exception:
+                                pass
+                        # Mark resumed so the sweeper doesn't hot-loop the
+                        # same broken row. Operator can inspect via the
+                        # sessions table.
+                        try:
+                            state_db.mark_pending_resume_resumed(session_id)
+                        except Exception:
+                            pass
+                        continue
+
+                    # Lock-contention at the INITIAL acquire step is
+                    # retryable: the 6am secops cron or an in-flight
+                    # dev session holds the repo lock, we never got
+                    # to pipeline.resume so the operator's answer is
+                    # still intact. Leave the pending_resumes row and
+                    # let the next sweeper tick try again.
+                    if not result.success and result.error == (
+                        "Repository locked by another session"
+                    ):
+                        console.print(
+                            "[dim]pending_resume_sweeper: "
+                            f"lock contention on {repo}, will retry "
+                            f"next tick (session={session_id})[/dim]"
+                        )
+                        continue
+
+                    # The OTHER lock-contended error fires only AFTER
+                    # pipeline.resume consumed the operator's answer
+                    # and advanced the agent session to DONE: replaying
+                    # the same answer would double-apply side effects
+                    # on the PR or fail because the agent session is
+                    # already finalized. BUT just marking the row
+                    # consumed strands the workflow — the PR needs
+                    # another fix round and nothing would trigger it.
+                    # Re-insert a fresh pending_resumes row with a
+                    # synthetic prompt so a new operator reply can
+                    # attach via the bridge and drive the next round.
+                    if not result.success and result.error == (
+                        "Repo lock reacquire contended during PR verification"
+                    ):
+                        pr_num = result.outputs.get("pr_number", "?")
+                        synthetic_question = (
+                            f"Post-verify lock contention on {repo} "
+                            f"while resuming session {session_id} "
+                            f"(PR #{pr_num}). The prior answer was "
+                            "consumed; reply with new guidance to "
+                            "retry the fix round once the peer "
+                            "session releases."
+                        )
+                        try:
+                            state_db.add_pending_resume(
+                                session_id=session_id,
+                                pipeline=pipeline_name,
+                                repo=repo,
+                                question=synthetic_question,
+                            )
+                        except Exception:
+                            pass
+                        console.print(
+                            f"[yellow]pending_resume_sweeper: "
+                            f"verify contention on {repo} (session="
+                            f"{session_id}); prior answer consumed, "
+                            "fresh pending_resumes row inserted so a "
+                            "new operator reply can drive the retry."
+                            "[/yellow]"
+                        )
+                        continue
+
+                    try:
+                        state_db.mark_pending_resume_resumed(session_id)
+                    except Exception:
+                        pass
+
+                    if sweeper_transport:
+                        try:
+                            if result.success:
+                                await sweeper_transport.send(
+                                    f"✅ Resume succeeded on {repo}\n"
+                                    f"Session: `{session_id}`\n"
+                                    f"\n{result.summary}"
+                                )
+                            elif result.blocked:
+                                q = result.question or "(no question text)"
+                                await sweeper_transport.send(
+                                    f"⏸️ Resume re-blocked on {repo}\n"
+                                    f"Session: `{session_id}`\n"
+                                    f"\n{q}"
+                                )
+                            else:
+                                err = result.error or result.summary
+                                await sweeper_transport.send(
+                                    f"❌ Resume failed on {repo}\n"
+                                    f"Session: `{session_id}`\n"
+                                    f"\n{err}"
+                                )
+                        except Exception:
+                            pass
+            finally:
+                if sweeper_transport:
+                    try:
+                        await sweeper_transport.close()
+                    except Exception:
+                        pass
+
+        async def _main() -> None:
+            async def _run_scheduled_personalization_pull() -> None:
+                """Cron-driven auto-pull of the personalization repo.
+
+                Runs at ``schedules.personalization_cron``. Skips when
+                the working tree is dirty so unsaved operator edits
+                aren't disturbed by the rebase. Conflicts during the
+                rebase abort and are logged; operator must intervene
+                via ``ctrlrelay personalization pull`` to surface the
+                conflict files. Auto-push is intentionally NOT done
+                here — a daemon committing on the operator's behalf
+                without explicit intent is the kind of thing that
+                surprises people; commits stay manual.
+
+                ``auto_pull`` runs synchronous ``git fetch``/``rebase``
+                subprocesses; dispatch to a worker thread so a slow
+                or stuck remote can't stall the poller's event loop
+                (Telegram dispatch, pending-resume sweeper, secops
+                cron). Codex pass 3 caught this.
+                """
+                if config.personalization is None:
+                    return
+                import asyncio
+
+                from ctrlrelay.personalization import PersonalizationManager
+                from ctrlrelay.personalization.manager import (
+                    PersonalizationError,
+                )
+
+                try:
+                    mgr = PersonalizationManager(config)
+                    result = await asyncio.to_thread(mgr.auto_pull)
+                except PersonalizationError as e:
+                    console.print(
+                        f"[yellow]Auto-pull failed: {e}[/yellow]"
+                    )
+                    return
+                if result.success:
+                    console.print(f"[dim]Auto-pull: {result.summary}[/dim]")
+                else:
+                    console.print(
+                        f"[yellow]Auto-pull: {result.summary}[/yellow]"
+                    )
+                    if result.conflict_files:
+                        for f in result.conflict_files:
+                            console.print(f"[yellow]  conflict: {f}[/yellow]")
+
+            # Register + start the scheduler FIRST, before any potentially
+            # slow startup work. Otherwise a 6am fire that lands during
+            # seed_current's per-repo GitHub calls would be lost —
+            # APScheduler's misfire_grace_time only rescues fires that
+            # happened AFTER the job was registered.
+            scheduler = make_scheduler(timezone=config.timezone)
+            scheduler.add_cron_job(
+                name="secops",
+                cron_expr=config.schedules.secops_cron,
+                func=_run_scheduled_secops,
+            )
+            # Drain answered pending_resumes every minute so a Telegram
+            # reply to a BLOCKED session turns into an actual pipeline
+            # resume within ~60s, not 24h (the next scheduled secops
+            # cron). Cheap: no-ops when the pending_resumes table is empty.
+            scheduler.add_cron_job(
+                name="pending_resume_sweeper",
+                cron_expr="* * * * *",
+                func=_run_pending_resume_sweeper,
+            )
+            # Retire questions nobody can act on any more. Without
+            # this the pending_resumes table only grows: unanswered
+            # rows stay live targets for orphan reply routing and get
+            # re-posted every sweep, including ones whose PR was
+            # merged by hand days earlier.
+            scheduler.add_cron_job(
+                name="question_expiry_sweeper",
+                cron_expr="0 * * * *",
+                func=_run_question_expiry_sweeper,
+            )
+            # Register the personalization auto-pull only when the
+            # operator has both configured the personalization block
+            # AND set a cron expression. Either alone is intentional
+            # (config without cron = manual sync only; cron without
+            # config = invalid in load_config).
+            personalization_cron_summary = ""
+            if (
+                config.personalization is not None
+                and config.schedules.personalization_cron is not None
+            ):
+                scheduler.add_cron_job(
+                    name="personalization_auto_pull",
+                    cron_expr=config.schedules.personalization_cron,
+                    func=_run_scheduled_personalization_pull,
+                )
+                personalization_cron_summary = (
+                    f" | personalization_auto_pull cron="
+                    f"{config.schedules.personalization_cron}"
+                )
+            scheduler.start()
+            console.print(
+                f"[dim]Scheduler: secops cron={config.schedules.secops_cron} "
+                f"tz={config.timezone} | "
+                f"pending_resume_sweeper=every 1m | "
+                f"question_expiry_sweeper=hourly"
+                f"{personalization_cron_summary}[/dim]"
+            )
+
+            # Now the slow startup: first-run seeding (one gh call per
+            # repo). Done inside _main so the scheduler is already up.
+            if first_run:
+                console.print(
+                    "[dim]First run: seeding with current assignments..."
+                    "[/dim]"
+                )
+                await poller.seed_current()
+
+            # Rehydrate PR watchers that survived the previous shutdown.
+            # A launchd kickstart / crash / redeploy cancels in-memory
+            # asyncio tasks; without this step, any PR sitting in review
+            # across a restart would silently lose its post-merge
+            # automation for the remainder of its 7-day watch window.
+            # Runs BEFORE run_poll_loop so watchers are live before the
+            # first poll interval elapses.
+            try:
+                surviving = state_db.list_pr_watches()
+            except Exception as e:
+                console.print(
+                    f"[yellow]pr_watches rehydrate: list failed ({e}) — "
+                    "skipping[/yellow]"
+                )
+                surviving = []
+            if surviving:
+                import time as _time
+                # Respect the operator's current config: if a repo was
+                # removed from `repos:`, skip respawning its watchers
+                # even if old rows linger in pr_watches. Treating the
+                # config as the source of truth matches how the rest
+                # of the poller behaves; silently driving close/notify
+                # on a now-unconfigured repo would be surprising.
+                configured_repos = {r.name for r in config.repos}
+                orphaned = [
+                    r for r in surviving if r["repo"] not in configured_repos
+                ]
+                if orphaned:
+                    console.print(
+                        f"[yellow]pr_watches: {len(orphaned)} row(s) "
+                        "for repos no longer in config — leaving "
+                        "dormant[/yellow]"
+                    )
+                active = [
+                    r for r in surviving if r["repo"] in configured_repos
+                ]
+                console.print(
+                    f"[dim]Rehydrating {len(active)} PR watcher(s) "
+                    "from state.db[/dim]"
+                )
+                now = int(_time.time())
+                # Always spawn with enough headroom for SEVERAL poll
+                # attempts even on rows past the 7-day window. A
+                # single-poll window (grace == poll_interval) would
+                # expire the instant the first gh call has a transient
+                # failure, logging watch_timeout and permanently
+                # dropping the row. 5 minutes against the default 60s
+                # poll_interval lets wait_for_merge retry through a
+                # handful of hiccups and still covers a PR that merges
+                # right after the restart. Abandoned-row cost is 5 min
+                # of extra polling, which is negligible.
+                # (Rehydrated rows with cleanup_phase set bypass
+                # wait_for_merge entirely — see pr_watch_task — so
+                # this headroom only affects phase=NULL rehydrates.)
+                rehydrate_min_timeout = 300
+                for row in active:
+                    # Honor the original watch deadline: subtract time
+                    # already spent watching from the default 7-day
+                    # timeout. Without this, every restart resets the
+                    # clock and abandoned PRs never time out.
+                    elapsed = max(0, now - int(row["started_at"]))
+                    remaining = max(
+                        DEFAULT_PR_WATCH_TIMEOUT - elapsed,
+                        rehydrate_min_timeout,
+                    )
+                    _spawn_pr_watch(
+                        repo=row["repo"],
+                        issue_number=row["issue_number"],
+                        pr_url=row["pr_url"] or "",
+                        pr_number=row["pr_number"],
+                        session_id=row.get("session_id"),
+                        timeout=remaining,
+                        skip_initial_persist=True,
+                    )
+
+            try:
+                await run_poll_loop(
+                    poller=poller, handler=handle_issue, interval=interval,
+                )
+            finally:
+                # Scheduler shutdown is async so it can cancel + await any
+                # in-flight job tasks (e.g. a scheduled secops sweep that was
+                # running when SIGTERM arrived). Without awaiting here the
+                # loop closes before jobs finalize — state_db locks stay
+                # held and worktrees stay dirty.
+                await scheduler.shutdown()
+                # Cancel any in-flight PR watchers so a poller stop/restart
+                # doesn't leak asyncio tasks. Their handlers log
+                # dev.pr.watch_cancelled and close their transport via the
+                # finally block.
+                if pr_watch_tasks:
+                    for t in list(pr_watch_tasks):
+                        t.cancel()
+                    await asyncio.gather(*list(pr_watch_tasks), return_exceptions=True)
+
+        loop = asyncio.new_event_loop()
+        try:
+            asyncio.set_event_loop(loop)
+            main_task = loop.create_task(_main())
+
+            def _handle_stop(sig: int) -> None:
+                main_task.cancel()
+
+            for sig in (signal.SIGTERM, signal.SIGINT):
+                loop.add_signal_handler(sig, _handle_stop, sig)
+
+            try:
+                loop.run_until_complete(main_task)
+            except asyncio.CancelledError:
+                console.print("\n[yellow]Poller stopped.[/yellow]")
+        finally:
+            loop.close()
+            state_db.close()
+    finally:
+        pid_file.unlink(missing_ok=True)
+
+
+@poller_app.command("stop")
+def poller_stop(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Stop the issue poller."""
+    import os
+    import signal
+
+    pid_file = _get_poller_pid_file(config_path)
+
+    if not pid_file.exists():
+        console.print("[yellow]Poller not running (no PID file)[/yellow]")
+        return
+
+    try:
+        pid = int(pid_file.read_text().strip())
+        os.kill(pid, signal.SIGTERM)
+        console.print(f"[green]Stopped poller (PID {pid})[/green]")
+        pid_file.unlink(missing_ok=True)
+    except ProcessLookupError:
+        console.print("[yellow]Poller process not found[/yellow]")
+        pid_file.unlink(missing_ok=True)
+    except ValueError:
+        console.print("[red]Invalid PID file[/red]")
+        pid_file.unlink(missing_ok=True)
+
+
+@poller_app.command("status")
+def poller_status(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Check poller status."""
+    import os
+
+    pid_file = _get_poller_pid_file(config_path)
+
+    if pid_file.exists():
+        try:
+            pid = int(pid_file.read_text().strip())
+            os.kill(pid, 0)
+            console.print(f"[green]Poller running (PID {pid})[/green]")
+            return
+        except (ProcessLookupError, ValueError):
+            pass
+
+    console.print("[dim]Poller not running[/dim]")
+    raise typer.Exit(1)
+
+
+personalization_app = typer.Typer(help="Personalization sync (cross-machine operator state).")
+app.add_typer(personalization_app, name="personalization")
+
+
+def _load_config_or_exit(config_path: str | None):
+    """Resolve --config and load it, mapping ConfigError to a typer.Exit."""
+    path = _resolve_config_or_exit(config_path)
+    try:
+        return load_config(path)
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+
+def _make_personalization_manager(config_path: str | None):
+    """Return a configured PersonalizationManager or exit with a helpful error."""
+    from ctrlrelay.personalization import PersonalizationManager
+    from ctrlrelay.personalization.manager import PersonalizationError
+
+    config = _load_config_or_exit(config_path)
+    if config.personalization is None:
+        console.print(
+            "[red]Error:[/red] No personalization config in orchestrator.yaml. "
+            "Add a `personalization:` section (see config/orchestrator.yaml.example) "
+            "and re-run."
+        )
+        raise typer.Exit(1)
+    try:
+        return PersonalizationManager(config)
+    except PersonalizationError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@personalization_app.command("init")
+def personalization_init(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    no_adopt: bool = typer.Option(
+        False,
+        "--no-adopt",
+        help=(
+            "Refuse to adopt pre-existing real files at target paths. "
+            "Default: adopt (move target into checkout, then symlink). "
+            "Use --no-adopt for the conservative Slice 1 behavior of "
+            "skipping such targets with a back-up-and-remove instruction."
+        ),
+    ),
+) -> None:
+    """Clone the personalization repo and wire symlinks.
+
+    Idempotent: re-running on a machine that already cloned the repo
+    converges branch + symlinks rather than failing.
+    """
+    from ctrlrelay.personalization.manager import PersonalizationError
+
+    mgr = _make_personalization_manager(config_path)
+    try:
+        summary = mgr.init(adopt=not no_adopt)
+    except PersonalizationError as e:
+        console.print(f"[red]Init failed:[/red] {e}")
+        raise typer.Exit(1)
+    console.print(summary)
+
+
+@personalization_app.command("status")
+def personalization_status(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Show working-tree state and per-symlink correctness. Read-only."""
+    mgr = _make_personalization_manager(config_path)
+    console.print(mgr.status())
+
+
+@personalization_app.command("push")
+def personalization_push(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    message: str | None = typer.Option(
+        None,
+        "--message",
+        "-m",
+        help="Commit message override (default: auto-generated from branch name).",
+    ),
+) -> None:
+    """Commit, rebase onto main, and push. Aborts the rebase on conflict.
+
+    On conflict the working tree is restored to its pre-rebase state and
+    the conflicting files are listed; resolve them in the checkout (the
+    target of any symlinked path), commit manually, and re-run push.
+    """
+    from ctrlrelay.personalization.manager import PersonalizationError
+
+    mgr = _make_personalization_manager(config_path)
+    try:
+        result = mgr.push(message=message)
+    except PersonalizationError as e:
+        console.print(f"[red]Push failed:[/red] {e}")
+        raise typer.Exit(1)
+    console.print(result.summary)
+    if result.conflict_files:
+        console.print("[yellow]conflicts:[/yellow]")
+        for f in result.conflict_files:
+            console.print(f"  {f}")
+    if not result.success:
+        raise typer.Exit(1)
+
+
+@personalization_app.command("pull")
+def personalization_pull(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Fetch + rebase the local working branch and re-wire symlinks."""
+    from ctrlrelay.personalization.manager import PersonalizationError
+
+    mgr = _make_personalization_manager(config_path)
+    try:
+        result = mgr.pull()
+    except PersonalizationError as e:
+        console.print(f"[red]Pull failed:[/red] {e}")
+        raise typer.Exit(1)
+    console.print(result.summary)
+    if result.conflict_files:
+        console.print("[yellow]conflicts:[/yellow]")
+        for f in result.conflict_files:
+            console.print(f"  {f}")
+    if not result.success:
+        raise typer.Exit(1)
+
+
+@app.command("setup")
+def setup(
+    owner: list[str] = typer.Option(
+        [],
+        "--owner",
+        help=(
+            "GitHub owner to include (repeat for multiple). When omitted, "
+            "the command prompts to pick from your accessible owners."
+        ),
+    ),
+    repo_root: Path = typer.Option(
+        Path("~/Projects").expanduser(),
+        "--repo-root",
+        help="Folder under which repos will be cloned (one subdir per owner).",
+    ),
+    config_out: Path = typer.Option(
+        Path("~/.config/ctrlrelay/orchestrator.yaml").expanduser(),
+        "--config-out",
+        help="Where to write the generated orchestrator.yaml.",
+    ),
+    timezone: str = typer.Option(
+        "UTC",
+        "--timezone",
+        help="IANA timezone for scheduled jobs (e.g. 'America/Santiago').",
+    ),
+    transport: str = typer.Option(
+        "file_mock",
+        "--transport",
+        help="Transport for operator notifications: 'file_mock' or 'telegram'.",
+    ),
+    telegram_chat_id: int | None = typer.Option(
+        None,
+        "--telegram-chat-id",
+        help="Telegram chat ID. Only used when --transport=telegram.",
+    ),
+    personalization_repo: str | None = typer.Option(
+        None,
+        "--personalization-repo",
+        help=(
+            "owner/repo for cross-machine sync (e.g. 'alice/dotclaude'). "
+            "Adds a personalization block to the config."
+        ),
+    ),
+    no_personalization: bool = typer.Option(
+        False,
+        "--no-personalization",
+        help="Skip the personalization prompt entirely (non-interactive mode).",
+    ),
+    wire_skills: bool = typer.Option(
+        True,
+        "--wire-skills/--no-wire-skills",
+        help=(
+            "When the personalization repo already contains "
+            "global/skills/<name>/ directories, add a paths: entry per "
+            "skill so they sync to ~/.claude/skills/<name>/. Default: on."
+        ),
+    ),
+    install_daemons: bool = typer.Option(
+        False,
+        "--install-daemons",
+        help=(
+            "Render and write launchd (macOS) / systemd (Linux) unit files. "
+            "Requires --transport=telegram + token in $CTRLRELAY_TELEGRAM_TOKEN "
+            "for the rendered plist to be usable."
+        ),
+    ),
+    skip_archived: bool = typer.Option(
+        True, "--skip-archived/--include-archived"
+    ),
+    skip_forks: bool = typer.Option(True, "--skip-forks/--include-forks"),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Accept all interactive defaults; never prompt.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help=(
+            "Overwrite an existing orchestrator.yaml (and existing daemon "
+            "plists when --install-daemons)."
+        ),
+    ),
+) -> None:
+    """First-run setup: detect orgs, enumerate repos, write config, clone, optional daemon install.
+
+    The interactive flow asks one question at a time and accepts every
+    answer with a sensible default. Pass --yes to skip prompts and
+    take all defaults. Provide --owner repeatedly to lock the owner
+    list non-interactively.
+    """
+    from ctrlrelay.setup import (
+        GhAuthError,
+        SetupOptions,
+        assert_gh_auth,
+        detect_owners,
+        run_setup,
+    )
+
+    try:
+        assert_gh_auth()
+    except GhAuthError as e:
+        console.print(f"[red]Setup blocked:[/red] {e}")
+        raise typer.Exit(1)
+
+    # ----- owners --------------------------------------------------------
+    chosen_owners: list[str] = list(owner)
+    if not chosen_owners:
+        try:
+            available = detect_owners()
+        except RuntimeError as e:
+            console.print(f"[red]Setup blocked:[/red] could not list owners: {e}")
+            raise typer.Exit(1)
+        if yes:
+            chosen_owners = available  # take everything
+        else:
+            console.print(
+                "Available owners on this machine's gh login:\n  "
+                + "\n  ".join(f"{i + 1}. {o}" for i, o in enumerate(available))
+            )
+            picked_raw = typer.prompt(
+                "Which to monitor? Enter numbers separated by space "
+                "(or 'all' for everything)",
+                default="all",
+            ).strip()
+            if picked_raw.lower() == "all":
+                chosen_owners = available
+            else:
+                try:
+                    indexes = [int(x) - 1 for x in picked_raw.split()]
+                    chosen_owners = [available[i] for i in indexes]
+                except (ValueError, IndexError):
+                    console.print(f"[red]Invalid selection:[/red] {picked_raw}")
+                    raise typer.Exit(2)
+    if not chosen_owners:
+        console.print("[red]Setup blocked:[/red] no owners chosen")
+        raise typer.Exit(2)
+
+    # ----- personalization ----------------------------------------------
+    chosen_personalization = personalization_repo
+    if (
+        chosen_personalization is None
+        and not no_personalization
+        and not yes
+    ):
+        if typer.confirm(
+            "Configure cross-machine personalization sync (CLAUDE.md, skills, memory)?",
+            default=False,
+        ):
+            chosen_personalization = typer.prompt(
+                "Personalization repo (owner/repo)"
+            ).strip() or None
+
+    # ----- telegram chat_id (required for telegram transport) ------------
+    # ``chat_id: 0`` is a footgun (the bridge would happily try to send
+    # there), so we force the operator to supply a real value before
+    # writing the config — interactively or via --telegram-chat-id.
+    if transport == "telegram":
+        if telegram_chat_id is None:
+            if yes:
+                console.print(
+                    "[red]Setup blocked:[/red] --transport telegram "
+                    "requires --telegram-chat-id (non-interactive mode)."
+                )
+                raise typer.Exit(2)
+            chat_raw = typer.prompt("Telegram chat ID").strip()
+            try:
+                telegram_chat_id = int(chat_raw)
+            except ValueError:
+                console.print(f"[red]Invalid chat ID:[/red] {chat_raw!r}")
+                raise typer.Exit(2)
+        if telegram_chat_id == 0:
+            console.print(
+                "[red]Setup blocked:[/red] telegram chat_id must be non-zero "
+                "for the bridge to deliver messages."
+            )
+            raise typer.Exit(2)
+
+    # ----- daemons -------------------------------------------------------
+    chosen_install_daemons = install_daemons
+    if not chosen_install_daemons and not yes:
+        chosen_install_daemons = typer.confirm(
+            "Render launchd/systemd unit files for the bridge and poller?",
+            default=transport == "telegram",
+        )
+
+    # ----- telegram token (only relevant for plist rendering) ------------
+    # The token is only baked into a rendered plist *if* we're also
+    # installing daemons in this same setup run. Missing token is NOT
+    # a reason to flip the transport: the config only stores
+    # ``bot_token_env``; the literal value can be exported later before
+    # bootstrapping the bridge.
+    token: str | None = None
+    if transport == "telegram" and chosen_install_daemons:
+        token = os.environ.get("CTRLRELAY_TELEGRAM_TOKEN")
+        if token is None and not yes:
+            token = typer.prompt(
+                "Telegram bot token (input hidden, used only to render plists)",
+                hide_input=True,
+            ).strip() or None
+        if token is None:
+            console.print(
+                "[yellow]Warning:[/yellow] no Telegram token in env or prompt. "
+                "Rendered plist will carry the ${CTRLRELAY_TELEGRAM_TOKEN} "
+                "placeholder; export the token before bootstrapping the bridge."
+            )
+
+    options = SetupOptions(
+        owners=chosen_owners,
+        repo_root=repo_root.expanduser(),
+        config_out=config_out.expanduser(),
+        timezone=timezone,
+        transport=transport,
+        telegram_chat_id=telegram_chat_id,
+        telegram_token=token,
+        personalization_repo=chosen_personalization,
+        wire_skills=wire_skills,
+        install_daemons=chosen_install_daemons,
+        skip_archived=skip_archived,
+        skip_forks=skip_forks,
+        force=force,
+    )
+
+    console.print(
+        f"\n[bold]Running setup[/bold]\n"
+        f"  owners: {', '.join(options.owners)}\n"
+        f"  repo_root: {options.repo_root}\n"
+        f"  config_out: {options.config_out}\n"
+        f"  transport: {options.transport}\n"
+        f"  personalization: {options.personalization_repo or '(skipped)'}\n"
+        f"  install_daemons: {options.install_daemons}\n"
+    )
+    try:
+        result = run_setup(options)
+    except FileExistsError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+    except (ValueError, RuntimeError) as e:
+        console.print(f"[red]Setup failed:[/red] {e}")
+        raise typer.Exit(1)
+
+    console.print(
+        f"\n[green]✓ Wrote {result.config_out} ({result.n_repos} repos across "
+        f"{len(result.owners)} owners)[/green]"
+    )
+    console.print(
+        f"  clone results: [green]{result.cloned} cloned[/green], "
+        f"[dim]{result.skipped} skipped[/dim], "
+        f"[red]{result.failed} failed[/red]"
+    )
+    if result.personalization_summary:
+        console.print(f"  personalization: {result.personalization_summary}")
+    if result.personalization_failed:
+        console.print(
+            "\n[bold red]ACTION NEEDED[/bold red] — personalization repo "
+            "sync failed; the rest of setup completed but your "
+            "personalization config/skills were not cloned. Check your "
+            "git auth (`gh auth status`, `gh config get git_protocol`) "
+            "and re-run `ctrlrelay personalization init` once it's fixed."
+        )
+    if result.daemon_units:
+        console.print("  daemon unit files:")
+        for p in result.daemon_units:
+            console.print(f"    - {p}")
+        console.print(
+            "\n[bold]Next:[/bold] bootstrap the daemons via:\n"
+            "  launchctl bootstrap gui/$(id -u) <plist>"
+            "    # macOS, one per file above\n"
+            "  systemctl --user daemon-reload && systemctl --user enable --now <unit>"
+            "    # Linux"
+        )
+    # Clone and personalization-sync failures must surface as a
+    # non-zero exit even when daemon units were rendered — automation
+    # watching exit code shouldn't mistake a partial setup for success.
+    if result.failed or result.personalization_failed:
+        raise typer.Exit(1)
+
+
+@app.command("version")
+def version() -> None:
+    """Print the package version."""
+    console.print(__version__)
+
+
+@app.command("status")
+def status(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+) -> None:
+    """Show orchestrator status and active sessions."""
+    from ctrlrelay.core.state import StateDB
+
+    try:
+        config = load_config(resolve_config_path(config_path))
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+    db_path = config.paths.state_db
+    if not db_path.exists():
+        console.print(f"[yellow]State database not found at {db_path}[/yellow]")
+        console.print("Run a pipeline first to initialize the database.")
+        return
+
+    import sqlite3
+
+    try:
+        db = StateDB(db_path)
+    except sqlite3.Error as e:
+        console.print(f"[red]Error opening database:[/red] {e}")
+        raise typer.Exit(1)
+
+    try:
+        # Show locks
+        locks = db.list_locks()
+        if locks:
+            console.print("\n[bold]Active Locks:[/bold]")
+            for lock in locks:
+                console.print(f"  • {lock['repo']} → session {lock['session_id']}")
+        else:
+            console.print("\n[dim]No active locks[/dim]")
+
+        # Show recent sessions
+        rows = db.execute(
+            "SELECT * FROM sessions ORDER BY started_at DESC LIMIT 5"
+        ).fetchall()
+
+        if rows:
+            console.print("\n[bold]Recent Sessions:[/bold]")
+            table = Table()
+            table.add_column("ID", style="dim", max_width=12)
+            table.add_column("Pipeline")
+            table.add_column("Repo")
+            table.add_column("Status")
+
+            for row in rows:
+                status_style = {
+                    "done": "green",
+                    "failed": "red",
+                    "running": "yellow",
+                    "blocked": "blue",
+                }.get(row["status"], "white")
+
+                table.add_row(
+                    row["id"][:12],
+                    row["pipeline"],
+                    row["repo"],
+                    f"[{status_style}]{row['status']}[/{status_style}]",
+                )
+            console.print(table)
+        else:
+            console.print("\n[dim]No sessions recorded yet[/dim]")
+    except sqlite3.Error as e:
+        console.print(f"[red]Database error:[/red] {e}")
+        raise typer.Exit(1)
+    finally:
+        db.close()
+
+
+repos_app = typer.Typer(help="Bulk repo operations across the orchestrator manifest.")
+app.add_typer(repos_app, name="repos")
+
+
+def _iter_repos(config_path: str | None, filter_str: str | None):
+    """Yield (name, org, repo, remote, local_path) tuples for repos in
+    the orchestrator config.
+
+    ``local_path`` is the fully-resolved path the dev pipeline expects,
+    so callers (clone-all, pull-all, repos status) land repos in the
+    same place every other ctrlrelay command operates on. Before 0.4.0
+    these handlers ignored ``local_path`` and computed ``DEST/org/repo``
+    from the raw owner — which broke when ``paths.owner_aliases`` was
+    in play. The resolved value comes from the config validator so
+    legacy aliases, lowercase-owner derivation, and per-repo overrides
+    all collapse into one source of truth here.
+    """
+    try:
+        config = load_config(resolve_config_path(config_path))
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+    needle = filter_str.lower() if filter_str else None
+    for r in config.repos:
+        if needle and needle not in r.name.lower():
+            continue
+        if "/" not in r.name:
+            console.print(
+                f"[yellow]skip[/yellow] {r.name} — name must be 'org/repo'"
+            )
+            continue
+        org, repo = r.name.split("/", 1)
+        remote = f"git@github.com:{r.name}.git"
+        # ``local_path`` is always populated by the time we reach here:
+        # either the operator declared it explicitly OR the model
+        # validator filled it in from ``paths.repo_root + owner.lower()``.
+        # If neither path was taken the validator would have raised at
+        # config load, never letting us get this far.
+        local_path = Path(str(r.local_path)).expanduser()
+        yield r.name, org, repo, remote, local_path
+
+
+def _resolve_target(
+    dest: Path | None,
+    org: str,
+    repo: str,
+    config_local_path: Path,
+) -> Path:
+    """Return where a repo should land on disk.
+
+    Without ``dest``, use the config-resolved ``local_path`` so
+    clone-all/pull-all/status agree with the dev pipeline. With
+    ``dest``, override to ``dest/<owner.lower()>/<repo>`` (the new
+    convention since 0.4.0). Pre-0.4.0 the dest-provided form used
+    the raw owner with mixed casing — that was the source of the
+    clone-all/local_path mismatch bug. See #128.
+    """
+    if dest is None:
+        return config_local_path
+    return Path(dest).expanduser().resolve() / org.lower() / repo
+
+
+@repos_app.command("clone-all")
+def repos_clone_all(
+    dest: Path | None = typer.Argument(
+        None,
+        help=(
+            "Workspace root override (e.g. ~/code/sandbox). When omitted, "
+            "each repo lands at its resolved local_path from the config."
+        ),
+    ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    filter_str: str | None = typer.Option(
+        None, "--filter", "-f", help="Substring filter on repo name (e.g. 'AInvirion')"
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", "-n", help="Show actions without running"),
+) -> None:
+    """Clone every configured repo to its resolved local_path
+    (or DEST/<owner.lower()>/<repo> when DEST is given)."""
+    import subprocess
+
+    cloned = skipped = failed = 0
+
+    for name, org, repo, remote, local_path in _iter_repos(config_path, filter_str):
+        target = _resolve_target(dest, org, repo, local_path)
+        if (target / ".git").exists():
+            console.print(f"[dim]✓ {name} (already cloned)[/dim]")
+            skipped += 1
+            continue
+        if target.exists() and any(target.iterdir()):
+            console.print(f"[yellow]skip[/yellow] {name} — {target} exists and is not empty")
+            skipped += 1
+            continue
+        if dry_run:
+            console.print(f"[blue]would clone[/blue] {remote} → {target}")
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        result = subprocess.run(
+            ["git", "clone", "--quiet", remote, str(target)],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            console.print(f"[green]cloned[/green] {name}")
+            cloned += 1
+        else:
+            console.print(f"[red]failed[/red] {name}: {result.stderr.strip()}")
+            failed += 1
+
+    if not dry_run:
+        console.print(
+            f"\n[bold]{cloned} cloned, {skipped} skipped, {failed} failed[/bold]"
+        )
+    if failed:
+        raise typer.Exit(1)
+
+
+@repos_app.command("pull-all")
+def repos_pull_all(
+    dest: Path | None = typer.Argument(
+        None,
+        help=(
+            "Workspace root override. When omitted, pulls each repo at "
+            "its resolved local_path from the config."
+        ),
+    ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    filter_str: str | None = typer.Option(
+        None, "--filter", "-f", help="Substring filter on repo name"
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", "-n", help="Show actions without running"),
+) -> None:
+    """Fast-forward pull every cloned repo at its resolved local_path
+    (or DEST/<owner.lower()>/<repo> when DEST is given)."""
+    import subprocess
+
+    pulled = skipped = dirty = failed = 0
+
+    for name, org, repo, _remote, local_path in _iter_repos(config_path, filter_str):
+        target = _resolve_target(dest, org, repo, local_path)
+        if not (target / ".git").exists():
+            console.print(f"[dim]– {name} (not cloned)[/dim]")
+            skipped += 1
+            continue
+        if dry_run:
+            console.print(f"[blue]would pull[/blue] {target}")
+            continue
+        # Refuse to pull a dirty tree — fetch only.
+        porcelain = subprocess.run(
+            ["git", "-C", str(target), "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+        )
+        if porcelain.returncode != 0:
+            console.print(
+                f"[red]failed[/red] {name}: git status — {porcelain.stderr.strip()}"
+            )
+            failed += 1
+            continue
+        if porcelain.stdout.strip():
+            fetched = subprocess.run(
+                ["git", "-C", str(target), "fetch", "--quiet"],
+                capture_output=True,
+                text=True,
+            )
+            if fetched.returncode != 0:
+                console.print(
+                    f"[red]failed[/red] {name}: fetch — {fetched.stderr.strip()}"
+                )
+                failed += 1
+            else:
+                console.print(f"[yellow]dirty[/yellow] {name} — fetched only")
+                dirty += 1
+            continue
+        result = subprocess.run(
+            ["git", "-C", str(target), "pull", "--ff-only", "--quiet"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            console.print(f"[green]pulled[/green] {name}")
+            pulled += 1
+        else:
+            console.print(f"[red]failed[/red] {name}: {result.stderr.strip()}")
+            failed += 1
+
+    if not dry_run:
+        console.print(
+            f"\n[bold]{pulled} pulled, {dirty} dirty, {skipped} skipped, "
+            f"{failed} failed[/bold]"
+        )
+    if failed:
+        raise typer.Exit(1)
+
+
+@repos_app.command("status")
+def repos_status(
+    dest: Path | None = typer.Argument(
+        None,
+        help=(
+            "Workspace root override. When omitted, inspects each repo "
+            "at its resolved local_path from the config."
+        ),
+    ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    filter_str: str | None = typer.Option(
+        None, "--filter", "-f", help="Substring filter on repo name"
+    ),
+) -> None:
+    """Show clean/dirty/ahead/behind for every repo at its resolved
+    local_path (or DEST/<owner.lower()>/<repo> when DEST is given)."""
+    import subprocess
+
+    title = "Repo status" if dest is None else f"Repo status — {Path(dest).expanduser().resolve()}"
+    table = Table(title=title)
+    table.add_column("Repo", style="cyan")
+    table.add_column("Branch", style="blue")
+    table.add_column("State")
+    table.add_column("Ahead/Behind", justify="right")
+
+    for name, org, repo, _remote, local_path in _iter_repos(config_path, filter_str):
+        target = _resolve_target(dest, org, repo, local_path)
+        if not (target / ".git").exists():
+            table.add_row(name, "-", "[red]not cloned[/red]", "")
+            continue
+        branch = subprocess.run(
+            ["git", "-C", str(target), "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        porcelain = subprocess.run(
+            ["git", "-C", str(target), "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        state = "[yellow]dirty[/yellow]" if porcelain else "[green]clean[/green]"
+
+        upstream = subprocess.run(
+            ["git", "-C", str(target), "rev-parse", "--abbrev-ref", "@{upstream}"],
+            capture_output=True,
+            text=True,
+        )
+        ahead_behind = ""
+        if upstream.returncode == 0:
+            def _count(spec: str) -> int:
+                proc = subprocess.run(
+                    ["git", "-C", str(target), "rev-list", "--count", spec],
+                    capture_output=True,
+                    text=True,
+                )
+                if proc.returncode != 0:
+                    return 0
+                try:
+                    return int(proc.stdout.strip() or "0")
+                except ValueError:
+                    return 0
+
+            ahead_n = _count("@{upstream}..HEAD")
+            behind_n = _count("HEAD..@{upstream}")
+            parts = []
+            if ahead_n > 0:
+                parts.append(f"[green]+{ahead_n}[/green]")
+            if behind_n > 0:
+                parts.append(f"[red]-{behind_n}[/red]")
+            ahead_behind = " ".join(parts)
+
+        table.add_row(name, branch or "-", state, ahead_behind)
+
+    console.print(table)
+
+
+install_app = typer.Typer(
+    help="Generate launchd / systemd unit files from in-package templates."
+)
+app.add_typer(install_app, name="install")
+
+
+def _print_install_summary(
+    units: list, written: list, dry_run: bool
+) -> None:
+    from ctrlrelay.install import RenderedUnit  # local to avoid CLI import cost
+
+    for unit in units:
+        assert isinstance(unit, RenderedUnit)
+        marker = "would write" if dry_run else "wrote"
+        path_str = (
+            f"[green]{marker}[/green] {unit.target_path}"
+            if not dry_run or unit.target_path in written
+            else f"[yellow]{marker}[/yellow] {unit.target_path}"
+        )
+        console.print(path_str)
+        if unit.unresolved:
+            console.print(
+                f"  [yellow]warning:[/yellow] unresolved template variables: "
+                f"{', '.join('${'+v+'}' for v in unit.unresolved)}"
+            )
+            if "CTRLRELAY_TELEGRAM_TOKEN" in unit.unresolved:
+                console.print(
+                    "  [dim]hint: export CTRLRELAY_TELEGRAM_TOKEN before "
+                    "re-running, or edit the file by hand.[/dim]"
+                )
+
+
+@install_app.command("launchd")
+def install_launchd(
+    workdir: Path = typer.Option(
+        Path.cwd(),
+        "--workdir",
+        "-w",
+        help="Service WorkingDirectory (defaults to current directory).",
+    ),
+    label_prefix: str = typer.Option(
+        "com.ctrlrelay",
+        "--label-prefix",
+        help="Reverse-DNS prefix for the launchd Label and filename.",
+    ),
+    poller_interval: int = typer.Option(
+        300, "--poller-interval", help="Poller --interval seconds."
+    ),
+    target_dir: Path | None = typer.Option(
+        None,
+        "--target-dir",
+        help="Where to write plists (default: ~/Library/LaunchAgents).",
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="Overwrite existing plists if present."
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print what would be written without touching the filesystem.",
+    ),
+) -> None:
+    """Render and install bridge + poller plists for macOS launchd.
+
+    After running, load the agents with:
+      launchctl bootstrap gui/$(id -u) <plist-path>
+    """
+    from ctrlrelay.install import render_launchd, write_units
+
+    units = render_launchd(
+        workdir=workdir,
+        label_prefix=label_prefix,
+        poller_interval=poller_interval,
+        target_dir=target_dir,
+    )
+    written: list[Path] = []
+    if not dry_run:
+        try:
+            written = write_units(units, overwrite=force)
+        except FileExistsError as e:
+            console.print(f"[red]error:[/red] {e}")
+            raise typer.Exit(1)
+    _print_install_summary(units, written, dry_run)
+
+
+@install_app.command("systemd")
+def install_systemd(
+    workdir: Path = typer.Option(
+        Path.cwd(),
+        "--workdir",
+        "-w",
+        help="Service WorkingDirectory (defaults to current directory).",
+    ),
+    poller_interval: int = typer.Option(
+        300, "--poller-interval", help="Poller --interval seconds."
+    ),
+    target_dir: Path | None = typer.Option(
+        None,
+        "--target-dir",
+        help="Where to write units (default: ~/.config/systemd/user).",
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="Overwrite existing unit files if present."
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print what would be written without touching the filesystem.",
+    ),
+) -> None:
+    """Render and install bridge + poller systemd user units (Linux).
+
+    After running, enable with:
+      systemctl --user daemon-reload
+      systemctl --user enable --now ctrlrelay-bridge.service
+      systemctl --user enable --now ctrlrelay-poller.service
+    """
+    from ctrlrelay.install import render_systemd, write_units
+
+    units = render_systemd(
+        workdir=workdir,
+        poller_interval=poller_interval,
+        target_dir=target_dir,
+    )
+    written: list[Path] = []
+    if not dry_run:
+        try:
+            written = write_units(units, overwrite=force)
+        except FileExistsError as e:
+            console.print(f"[red]error:[/red] {e}")
+            raise typer.Exit(1)
+    _print_install_summary(units, written, dry_run)
+
+
+if __name__ == "__main__":
+    app()