Add tasks serve CLI and local server with heartbeat or task-manager status UI
Problem
MkDocs is strong for static narrative docs but weak for live task-queue and heartbeat visibility. Operators need a small local server that browses plan markdown and shows task-manager snapshot / register (and later escalation flags) without opening raw JSON.
Context
- Entry today:
just plan …→tasks/tools/plans_cli.py; docs:just plan serve(MkDocs). - Snapshot path pattern:
tasks/logs/task_manager/task-manager-<owner>.snapshot.json(gitignored); register alongside. - Naming goal: converge on tasks as the user-facing umbrella (
tasks serve); repo path may staytasks/until rename-master-plans-tree-to-tasks. - Already landed prerequisites on
main: - PR #711: structured escalation payload (
escalation.required,escalation.signals[]) and default no-mutate dispatch behavior forstarted_at. - PR #705: PR-CI task signals and default task worktree root under
.worktrees/<slug>. - Server
/statuspage should consume both escalation and PR-CI fields from the snapshot without assuming legacy sibling worktree paths.
Possible Solutions
- A — Flask/FastAPI + markdown render: Single process, Jinja or htmx, read files from disk; poll snapshot mtime or SSE later.
- B — Extend existing playground patterns: Reuse repo conventions if a tiny app already fits.
- Recommended: A minimal FastAPI or Starlette app colocated under
tasks/tools/ortasks/package, invoked viaplans tasks serveoruv run …until rename.
Plan
- [x] Add CLI subcommand (e.g.
plans tasks serve --port …) that starts the server; document intasks/tools/cli-reference.md. - [x] Implement markdown browsing (safe path under repo root) and a /status (or
/dashboard) page reading latest snapshot + register forTASK_MANAGER_OWNERor--owner. - [x] Phase 1: keep MkDocs as parallel option; README/AGENTS note “MkDocs vs tasks serve”.
- [x] Tests: lightweight handler tests or subprocess smoke for CLI entrypoint.
Implementation Progress
- Added
tasks/tools/tasks_server.py: - FastAPI app with
/healthz,/status,/status.json /statusreads owner-scoped snapshot/register fromtasks/logs/task_manager- markdown browser under repo root:
/browse+/browse/{path} - path safety guard prevents traversal outside repository root
- Added
plans serveCLI entry intasks/tools/plans_cli.py: --host(default127.0.0.1)--port(default8005)--owner(defaultTASK_MANAGER_OWNERthen current system user)- uses
uvicornto run the task server app - Updated
tasks/tools/cli-reference.mdwith server command docs and explicit parallel usage note: plans servefor live status toolingjust plansfor MkDocs static docs- Added tests:
tests/core/test_tasks_server.pyfor status + browse endpointstests/core/test_plans_cli.pyparser/delegation tests forserve- Validation run:
uv run pytest tests/core/test_plans_cli.py tests/core/test_tasks_server.py -q(47 passed)
QA Exploration
- N/A (internal local tooling server page, validated via endpoint/unit tests)
- [x] QA exploration completed (or N/A for non-UI tasks)
Review Feedback
- [ ] Review cleared