Dataface Tasks

Add tasks serve CLI and local server with heartbeat or task-manager status UI

IDINFRA_TOOLING-ADD_TASKS_SERVE_COMMAND_AND_PLANS_SERVER
Statuscompleted
Priorityp1
Milestonem1-ft-analytics-analyst-pilot
Ownersr-engineer-architect
Completed bydave
Completed2026-03-22

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 stay tasks/ 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 for started_at.
  • PR #705: PR-CI task signals and default task worktree root under .worktrees/<slug>.
  • Server /status page 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/ or tasks/ package, invoked via plans tasks serve or uv run … until rename.

Plan

  • [x] Add CLI subcommand (e.g. plans tasks serve --port …) that starts the server; document in tasks/tools/cli-reference.md.
  • [x] Implement markdown browsing (safe path under repo root) and a /status (or /dashboard) page reading latest snapshot + register for TASK_MANAGER_OWNER or --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
  • /status reads owner-scoped snapshot/register from tasks/logs/task_manager
  • markdown browser under repo root: /browse + /browse/{path}
  • path safety guard prevents traversal outside repository root
  • Added plans serve CLI entry in tasks/tools/plans_cli.py:
  • --host (default 127.0.0.1)
  • --port (default 8005)
  • --owner (default TASK_MANAGER_OWNER then current system user)
  • uses uvicorn to run the task server app
  • Updated tasks/tools/cli-reference.md with server command docs and explicit parallel usage note:
  • plans serve for live status tooling
  • just plans for MkDocs static docs
  • Added tests:
  • tests/core/test_tasks_server.py for status + browse endpoints
  • tests/core/test_plans_cli.py parser/delegation tests for serve
  • 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