navig-agentctl 0.2.0__tar.gz

navig_agentctl-0.2.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: navig-agentctl
+Version: 0.2.0
+Summary: Agent Control Center (devops section): sessions, worktrees & tasks — one read-only view, then a controller.
+Author-email: NAVIG Development Team <opensource@navig.run>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://navig.run
+Project-URL: Documentation, https://navig.run/docs
+Keywords: navig,cli,agent,orchestration,plugin,devops,worktrees,sessions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: navig>=0.1.0
+Requires-Dist: typer>=0.14.0
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# navig-agentctl
+
+<!-- navig:plugin-card:start -->
+<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->
+
+> Agent Control Center (devops section): sessions, worktrees & tasks — one read-only view, then a controller.
+
+**A navig extension** — installing it pulls in navig and adds the commands below · v0.2.0 · not on PyPI yet (install from source below)
+
+**Install**
+
+```bash
+pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-agentctl"
+navig agentctl --help
+```
+
+It is not a separate program: it needs navig, and installing it installs navig for you.
+
+<details><summary>Commands</summary>
+
+| Command | What it does |
+|---|---|
+| `navig agentctl sessions` | Live agent sessions (who is working where, idle or active). |
+| `navig agentctl status` | One-line overview: sessions, worktrees (cwd repo), tasks. |
+| `navig agentctl tasks` | Unified tasks from the board and the work queue. |
+| `navig agentctl worktrees` | Git worktrees of a repo: branch, ahead/behind, dirty, last commit. |
+
+</details>
+
+<!-- navig:plugin-card:end -->
+
+**Agent Control Center** — the devops section for managing AI coding agents across
+sessions, git worktrees and task records. Local-first, provider-agnostic, read-only
+in Phase 1.
+
+## Phases
+
+| Phase | Name | What it does |
+|---|---|---|
+| 1 | Observer | Discover live agent sessions · list worktrees + conflict radar · unified task read-model (board + work queue). **Changes nothing.** |
+| **2a (this)** | Heartbeat | `POST /api/deck/agents/heartbeat` — the extension annotates workspace/editor/roster context; daemon-owned `state`/`pid`/`reason` are never written. |
+| 2b | Controller | Launch CLI agents into worktrees, assign task specs, pause/terminate owned processes, collect handoff reports, detect ownership conflicts. |
+| 3 | Orchestrator | Schedule by dependency, allocate by capacity, trigger reviews, recover interrupted work — production deploys always ask a human first. |
+
+## CLI
+
+```
+navig agentctl sessions [--project P] [--json]
+navig agentctl worktrees [--project PATH] [--conflicts] [--json]
+navig agentctl tasks [--source board|work] [--json]
+navig agentctl status [--json]
+```
+
+## Deck routes (the contract)
+
+All under `/api/deck/agents`, gated on the `agentctl` module. GET-only in Phase 1:
+
+- `GET /api/deck/agents/sessions` — live sessions (from `navig procs` semantics) merged with the persistent registry.
+- `GET /api/deck/agents/worktrees?project=&conflicts=` — worktrees + pairwise conflict radar.
+- `GET /api/deck/agents/tasks` — board cards + work items, one normalised shape.
+
+The OS app (Control Center tile) and navig-dev (VS Code tree views) are both
+consumers of this one contract.
+
+## Store
+
+`~/.navig/data/store/agentctl.db` — session ledger (who was active where, with
+state-change history) and task bindings (which session owns which task). Task
+truth stays in `board.db` / `work.db`; this ledger only answers ownership.
+
+## Non-negotiables
+
+Local-first · provider-agnostic adapters · explicit process ownership · safe git
+handling · no duplicate task execution · **no automatic merge or deployment**.

navig_agentctl-0.2.0/README.md

@@ -0,0 +1,74 @@
+# navig-agentctl
+
+<!-- navig:plugin-card:start -->
+<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->
+
+> Agent Control Center (devops section): sessions, worktrees & tasks — one read-only view, then a controller.
+
+**A navig extension** — installing it pulls in navig and adds the commands below · v0.2.0 · not on PyPI yet (install from source below)
+
+**Install**
+
+```bash
+pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-agentctl"
+navig agentctl --help
+```
+
+It is not a separate program: it needs navig, and installing it installs navig for you.
+
+<details><summary>Commands</summary>
+
+| Command | What it does |
+|---|---|
+| `navig agentctl sessions` | Live agent sessions (who is working where, idle or active). |
+| `navig agentctl status` | One-line overview: sessions, worktrees (cwd repo), tasks. |
+| `navig agentctl tasks` | Unified tasks from the board and the work queue. |
+| `navig agentctl worktrees` | Git worktrees of a repo: branch, ahead/behind, dirty, last commit. |
+
+</details>
+
+<!-- navig:plugin-card:end -->
+
+**Agent Control Center** — the devops section for managing AI coding agents across
+sessions, git worktrees and task records. Local-first, provider-agnostic, read-only
+in Phase 1.
+
+## Phases
+
+| Phase | Name | What it does |
+|---|---|---|
+| 1 | Observer | Discover live agent sessions · list worktrees + conflict radar · unified task read-model (board + work queue). **Changes nothing.** |
+| **2a (this)** | Heartbeat | `POST /api/deck/agents/heartbeat` — the extension annotates workspace/editor/roster context; daemon-owned `state`/`pid`/`reason` are never written. |
+| 2b | Controller | Launch CLI agents into worktrees, assign task specs, pause/terminate owned processes, collect handoff reports, detect ownership conflicts. |
+| 3 | Orchestrator | Schedule by dependency, allocate by capacity, trigger reviews, recover interrupted work — production deploys always ask a human first. |
+
+## CLI
+
+```
+navig agentctl sessions [--project P] [--json]
+navig agentctl worktrees [--project PATH] [--conflicts] [--json]
+navig agentctl tasks [--source board|work] [--json]
+navig agentctl status [--json]
+```
+
+## Deck routes (the contract)
+
+All under `/api/deck/agents`, gated on the `agentctl` module. GET-only in Phase 1:
+
+- `GET /api/deck/agents/sessions` — live sessions (from `navig procs` semantics) merged with the persistent registry.
+- `GET /api/deck/agents/worktrees?project=&conflicts=` — worktrees + pairwise conflict radar.
+- `GET /api/deck/agents/tasks` — board cards + work items, one normalised shape.
+
+The OS app (Control Center tile) and navig-dev (VS Code tree views) are both
+consumers of this one contract.
+
+## Store
+
+`~/.navig/data/store/agentctl.db` — session ledger (who was active where, with
+state-change history) and task bindings (which session owns which task). Task
+truth stays in `board.db` / `work.db`; this ledger only answers ownership.
+
+## Non-negotiables
+
+Local-first · provider-agnostic adapters · explicit process ownership · safe git
+handling · no duplicate task execution · **no automatic merge or deployment**.

navig_agentctl-0.2.0/navig_agentctl/__init__.py

@@ -0,0 +1,9 @@
+"""navig-agentctl — the Agent Control Center (devops section).
+
+Phase 1 (Observer): a read-only view over what is already true — live agent
+sessions, git worktrees and task records — exposed as deck routes, a CLI
+(``navig agentctl``) and the Control Center OS tile. It never launches,
+stops or merges anything; that is Phase 2+.
+"""
+
+__version__ = "0.2.0"

navig_agentctl-0.2.0/navig_agentctl/commands.py

@@ -0,0 +1,203 @@
+"""``navig agentctl`` — the Agent Control Center from the terminal.
+
+Read-only Observer verbs mirroring the deck routes. Tables follow the house
+style (Rich, one wrappable column, semantic glyphs); anything a script might
+parse also offers ``--json``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+agentctl_app = typer.Typer(
+    name="agentctl",
+    help="Agent Control Center: sessions, worktrees & tasks (read-only).",
+    no_args_is_help=True,
+)
+
+
+def _print_json(data: Any) -> None:
+    typer.echo(json.dumps(data, indent=2, default=str))
+
+
+def _table(headers: list[str], rows: list[list[str]], no_wrap: set[int] | None = None):
+    from navig.console_helper import Table, console
+
+    table = Table(box=None, show_header=True, padding=(0, 2))
+    nw = no_wrap or set()
+    for i, h in enumerate(headers):
+        table.add_column(h, no_wrap=i in nw)
+    for row in rows:
+        table.add_row(*row)
+    console.print(table)
+
+
+def _state_glyph(state: str) -> str:
+    return {
+        "active": "[green]● active[/green]",
+        "idle": "[dim]○ idle[/dim]",
+        "young": "[cyan]◐ young[/cyan]",
+        "stale": "[red]✗ stale[/red]",
+    }.get(state, f"[dim]? {state or 'unknown'}[/dim]")
+
+
+@agentctl_app.command("sessions")
+def sessions_cmd(
+    project: str = typer.Option("", "--project", "-p", help="Filter by project label substring."),
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON."),
+):
+    """Live agent sessions (who is working where, idle or active)."""
+    from navig_agentctl.snapshots import session_snapshot
+
+    rows = session_snapshot()
+    if project:
+        rows = [r for r in rows if project.lower() in (r.get("project") or "").lower()]
+    if json_out:
+        _print_json(rows)
+        return
+    if not rows:
+        typer.echo("No agent sessions found.")
+        return
+    _table(
+        ["State", "Session", "Project", "Owner", "Mem", "Reason"],
+        [
+            [
+                _state_glyph(r["state"]),
+                (r["session_id"] or "")[:12],
+                (r.get("project") or "")[:28],
+                (r.get("owner") or "")[:16],
+                f"{r.get('mem_mb') or 0:.0f}MB",
+                (r.get("reason") or "")[:40],
+            ]
+            for r in rows
+        ],
+        no_wrap={0, 1, 4},
+    )
+    typer.echo(f"\n{len(rows)} session(s). Next: navig agentctl worktrees --project <path>")
+
+
+@agentctl_app.command("worktrees")
+def worktrees_cmd(
+    project: str = typer.Option(".", "--project", "-p", help="Repo path (default: current directory)."),
+    conflicts: bool = typer.Option(False, "--conflicts", help="Also run the pairwise conflict radar."),
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON."),
+):
+    """Git worktrees of a repo: branch, ahead/behind, dirty, last commit."""
+    from navig_agentctl.snapshots import conflict_pairs, worktree_snapshot
+
+    # Typed paths follow the operator: resolve against the invocation cwd, never
+    # the process cwd (navig chdirs into the active space).
+    from navig.platform.paths import resolve_user_path
+
+    root = resolve_user_path(project)
+    if not root.exists():
+        typer.echo(f"Path not found: {root}")
+        raise typer.Exit(1)
+    wts = worktree_snapshot(root)
+    pairs = conflict_pairs(root) if conflicts else []
+    if json_out:
+        _print_json({"project": str(root), "worktrees": wts, "conflicts": pairs})
+        return
+    if not wts:
+        typer.echo(f"No worktrees found under {root}")
+        return
+    _table(
+        ["Worktree", "Branch", "±", "Dirty", "Last commit"],
+        [
+            [
+                w["name"][:28],
+                (w["branch"] or "detached")[:24],
+                f"+{w['ahead']}/-{w['behind']}",
+                "[yellow]●[/yellow]" if w["dirty"] else "[dim]○[/dim]",
+                (w["last_commit"]["subject"] or "")[:36],
+            ]
+            for w in wts
+        ],
+        no_wrap={2, 3},
+    )
+    if conflicts:
+        if not pairs:
+            typer.echo("\n[green]No merge conflicts across worktrees.[/green]")
+        else:
+            _table(
+                ["A", "B", "Status"],
+                [
+                    [p.get("a", "")[:18], p.get("b", "")[:18], p.get("status", "")[:20]]
+                    for p in pairs
+                ],
+                no_wrap={2},
+            )
+    typer.echo(f"\n{len(wts)} worktree(s). Next: navig agentctl tasks")
+
+
+@agentctl_app.command("tasks")
+def tasks_cmd(
+    source: str = typer.Option("", "--source", "-s", help="Filter: board | work."),
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON."),
+):
+    """Unified tasks from the board and the work queue."""
+    from navig_agentctl.snapshots import task_snapshot
+
+    rows = task_snapshot()
+    if source:
+        rows = [r for r in rows if r.get("source") == source]
+    if json_out:
+        _print_json(rows)
+        return
+    if not rows:
+        typer.echo("No task records found.")
+        return
+    _table(
+        ["Ref", "Source", "Status", "Title", "Owner"],
+        [
+            [
+                r["ref"][:26],
+                r["source"],
+                (r["status"] or "")[:10],
+                (r["title"] or "")[:40],
+                (r["owner"] or "")[:16],
+            ]
+            for r in rows
+        ],
+        no_wrap={0, 1, 2},
+    )
+    typer.echo(f"\n{len(rows)} task(s). Next: navig agentctl sessions")
+
+
+@agentctl_app.command("status")
+def status_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Output as JSON."),
+):
+    """One-line overview: sessions, worktrees (cwd repo), tasks."""
+    from navig_agentctl.snapshots import session_snapshot, task_snapshot, worktree_snapshot
+
+    from navig.platform.paths import invocation_cwd
+
+    sessions = session_snapshot()
+    tasks = task_snapshot()
+    wts = worktree_snapshot(invocation_cwd())
+    active = sum(1 for s in sessions if s["state"] == "active")
+    blocked = sum(1 for t in tasks if t.get("gate") == "waiting")
+    summary = {
+        "sessions_total": len(sessions),
+        "sessions_active": active,
+        "worktrees": len(wts),
+        "tasks_total": len(tasks),
+        "tasks_waiting": blocked,
+    }
+    if json_out:
+        _print_json(summary)
+        return
+    _table(
+        ["Metric", "Value"],
+        [
+            ["Sessions (active / total)", f"{active} / {len(sessions)}"],
+            ["Worktrees (this repo)", str(len(wts))],
+            ["Tasks (waiting / total)", f"{blocked} / {len(tasks)}"],
+        ],
+        no_wrap={1},
+    )
+    typer.echo("\nNext: navig agentctl sessions  ·  worktrees --project <path>  ·  tasks")

navig_agentctl-0.2.0/navig_agentctl/deck_routes.py

@@ -0,0 +1,229 @@
+"""Agent Control Center deck routes — the read-only Observer API.
+
+AUTHORITATIVE CONTRACT FIXTURE: ``plugins/navig-agentctl/tests/fixtures/agents-contract.json``.
+The OS Control Center app and tools/forge/navig-dev both validate against it —
+one fixture, two consumers; a shape change updates the fixture in the same
+commit as the route change. (navig-dev's drift-alarm walks
+``plugins/navig-agentctl/**`` for it — the routes are a PLUGIN, not core.)
+
+Gated on the ``agentctl`` module being enabled. Phase 1 is GET-only; the ONE
+write is the Phase-2 annotation heartbeat (no process control):
+
+  GET  /api/deck/agents/sessions           → {sessions: [...], generated_at}
+  GET  /api/deck/agents/worktrees?project= → {worktrees: [...], conflicts: [...]}
+  GET  /api/deck/agents/tasks              → {tasks: [...], generated_at}
+  POST /api/deck/agents/heartbeat          → {ok, session_id}   annotation-only
+
+Heartbeat semantics (contract): payload carries ONLY annotation fields
+(``session_id`` + optional ``project_root, worktree, agent_kind, editor,
+owner, last_activity_at``); unknown/daemon fields in the body are ignored,
+never written. Daemon-derived state always wins — the route cannot change
+``state``/``pid``/``reason`` of a session the process table owns.
+
+Future local-only mutations (launch/assign/pause/terminate) need BOTH guards
+(is_local_request in the brain AND the OS server's refuseRemoteManagement
+list); the heartbeat is annotation, not control, so it rides normal deck auth.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any
+
+try:
+    from aiohttp import web
+except ImportError:  # pragma: no cover — gateway always has aiohttp
+    web = None  # type: ignore[assignment]
+
+logger = logging.getLogger(__name__)
+
+_BASE = "/api/deck/agents"
+
+
+def _json(data: dict[str, Any], status: int = 200):
+    return web.json_response(data, status=status)
+
+
+def _resolve_root(request) -> Path | None:
+    """Project root from ?project= (a path), else the primary checkout of cwd.
+
+    Typed paths follow the operator: a path the user typed goes through
+    resolve_user_path — never Path.cwd() guessing for user input.
+    """
+    raw = (request.query.get("project") or "").strip()
+    if not raw:
+        from navig.platform.paths import invocation_cwd
+
+        raw = str(invocation_cwd())
+    try:
+        from navig.platform.paths import resolve_user_path
+
+        root = resolve_user_path(raw)
+    except Exception:  # noqa: BLE001
+        root = Path(raw)
+    if not root.exists():
+        return None
+    return root
+
+
+async def handle_sessions(request):
+    """Live sessions (procs-derived) merged with the registry ledger."""
+    from navig_agentctl.registry import get_agentctl_store
+    from navig_agentctl.snapshots import record_snapshot, session_snapshot
+
+    try:
+        # to_thread: psutil process scans take seconds — run on the loop would
+        # freeze EVERY other gateway request (deck, telegram) behind this one.
+        rows = await asyncio.to_thread(session_snapshot)
+    except Exception as exc:  # noqa: BLE001 — observer must never 500 the app
+        logger.warning("agentctl sessions snapshot failed: %r", exc)
+        rows = []
+    try:
+        def _ingest() -> dict:
+            store = get_agentctl_store()
+            record_snapshot(rows, store)
+            store.mark_stale()
+            return {r["session_id"]: r for r in store.list_sessions()}
+
+        ledger = await asyncio.to_thread(_ingest)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("agentctl registry unavailable: %r", exc)
+        ledger = {}
+
+    # Live rows win; registry-only rows surface as their last known state
+    # (stale included — the recovery breadcrumb Phase 3 needs).
+    seen = {r["session_id"] for r in rows}
+    merged = list(rows)
+    for sid, r in ledger.items():
+        if sid not in seen:
+            merged.append(
+                {
+                    "session_id": sid,
+                    "pid": r.get("pid"),
+                    "project_root": r.get("project_root") or "",
+                    "project": r.get("project") or "",
+                    "worktree": r.get("worktree") or "",
+                    "agent_kind": r.get("agent_kind") or "",
+                    "editor": r.get("editor") or "",
+                    "state": r.get("state") or "stale",
+                    "reason": r.get("reason") or "not seen in the latest snapshot",
+                    "last_activity_at": r.get("last_activity_at"),
+                    "owner": r.get("owner") or "",
+                    "mem_mb": 0.0,
+                }
+            )
+    return _json({"sessions": merged, "generated_at": _now()})
+
+
+async def handle_worktrees(request):
+    """Worktrees of one repo + the pairwise conflict radar."""
+    from navig_agentctl.snapshots import conflict_pairs, worktree_snapshot
+
+    root = _resolve_root(request)
+    if root is None:
+        return _json({"error": "project path not found"}, status=404)
+    try:
+        # to_thread: N worktrees × 3 git subprocesses measured 36-150s on the
+        # live box — on the loop it froze the whole gateway (reproduced: a
+        # 14ms route took 147s while this ran).
+        wts = await asyncio.to_thread(worktree_snapshot, root)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("agentctl worktree snapshot failed: %r", exc)
+        return _json({"error": f"worktree snapshot failed: {exc}"}, status=500)
+    # Conflict radar is opt-in: pairwise merge-tree is O(n²) git calls — a
+    # 31-worktree repo is ~450 pairs and the scan runs off-loop (to_thread),
+    # so the rest of the gateway stays live while it grinds. The CLI mirrors
+    # the opt-in (`--conflicts` is a flag, never the default).
+    with_conflicts = (request.query.get("conflicts") or "0").lower() in ("1", "true", "yes")
+    pairs = await asyncio.to_thread(conflict_pairs, root) if with_conflicts else []
+    return _json(
+        {"project": str(root), "worktrees": wts, "conflicts": pairs, "generated_at": _now()}
+    )
+
+
+async def handle_tasks(request):
+    """Unified task read-model: board cards + work items."""
+    from navig_agentctl.snapshots import task_snapshot
+
+    try:
+        tasks = await asyncio.to_thread(task_snapshot)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("agentctl task snapshot failed: %r", exc)
+        return _json({"error": f"task snapshot failed: {exc}"}, status=500)
+    return _json({"tasks": tasks, "generated_at": _now()})
+
+
+def _reject(msg: str):
+    """Heartbeat 400s must be VISIBLE: a silent rejection is a client that
+    retries forever with a payload nobody ever sees fail (the forge client's
+    404-standdown made exactly this class of drift undetectable before)."""
+    logger.warning("agentctl heartbeat rejected: %s", msg)
+    return _json({"error": msg}, status=400)
+
+
+async def handle_heartbeat(request):
+    """POST — annotation-only session heartbeat (the ONE write in Phase 1/2a).
+
+    Adds editor context the daemon cannot derive (workspace, editor, roster
+    owner) to the registry. Never changes state/pid/reason — see the module
+    docstring for the contract. Validation is fail-closed: a malformed body
+    is 400, never a partial write.
+    """
+    from navig_agentctl.registry import get_agentctl_store
+
+    try:
+        payload = await request.json()
+    except Exception:  # noqa: BLE001 — non-JSON body
+        return _reject("body must be a JSON object")
+    if not isinstance(payload, dict):
+        return _reject("body must be a JSON object")
+
+    sid = payload.get("session_id")
+    if not isinstance(sid, str) or not sid.strip() or len(sid) > 200:
+        return _reject("session_id is required (non-empty string, ≤200 chars)")
+    if any(ord(c) < 32 for c in sid):  # control chars never reach the store
+        return _reject("session_id contains control characters")
+
+    annotations: dict[str, str] = {}
+    for key in ("project_root", "worktree", "agent_kind", "editor", "owner"):
+        val = payload.get(key)
+        if val is None:
+            annotations[key] = ""
+            continue
+        if not isinstance(val, str) or len(val) > 1024:
+            return _reject(f"{key} must be a string of at most 1024 chars")
+        annotations[key] = val
+    last_activity = payload.get("last_activity_at")
+    if last_activity is not None and (
+        not isinstance(last_activity, str) or len(last_activity) > 64
+    ):
+        return _reject("last_activity_at must be a string of at most 64 chars")
+
+    try:
+        store = get_agentctl_store()
+        store.annotate_session(
+            {"session_id": sid.strip(), **annotations, "last_activity_at": last_activity}
+        )
+    except Exception as exc:  # noqa: BLE001 — store down is a 500, not a 200
+        logger.warning("agentctl heartbeat store failed: %r", exc)
+        return _json({"error": f"heartbeat store failed: {exc}"}, status=500)
+    return _json({"ok": True, "session_id": sid.strip()})
+
+
+def _now() -> str:
+    from datetime import datetime, timezone
+
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def register(app: "web.Application") -> None:
+    from navig.modules.gate import requires_module
+
+    g = requires_module("agentctl")
+    app.router.add_get(f"{_BASE}/sessions", g(handle_sessions))
+    app.router.add_get(f"{_BASE}/worktrees", g(handle_worktrees))
+    app.router.add_get(f"{_BASE}/tasks", g(handle_tasks))
+    app.router.add_post(f"{_BASE}/heartbeat", g(handle_heartbeat))
+    logger.debug("navig-agentctl: Observer routes + heartbeat mounted under %s", _BASE)