Dataface Tasks

Add just tasks serve composing heartbeat loop and plans server

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

Problem

Operators should not juggle three terminals (heartbeat, tasks server, optional manager). One recipe should start background heartbeat + tasks server with sane defaults and documented ports.

Context

  • Heartbeat already runs detached after task-manager-start changes (background task-manager-run).
  • This recipe may ensure heartbeat is running (e.g. call task-manager-ensure or document prerequisite) and start the server from add-tasks-serve-command-and-plans-server.
  • Target UX: just tasks serve (alias acceptable during transition).
  • Downstream assumptions from merged prerequisites:
  • task-manager-heartbeat --dispatch-ready never mutates task frontmatter. Runtime state (started_at, claim) lives in the manager registry.
  • Worktree conventions now default to .worktrees/<task-slug> rather than sibling directories.
  • Snapshot status should surface escalation + PR-CI indicators for operator triage.

Possible Solutions

  • A — Compose in justfile only: Shell orchestration; no new Python.
  • B — Small Python launcher: Cross-platform process supervision; more moving parts.
  • Recommended: A with clear logs and just tasks serve --help style comment block.

Plan

  • [x] Add tasks serve recipe to justfile (and document conflict-free ports vs just plan serve / cloud).
  • [x] Ensure idempotent behavior: second run attaches or no-ops with message (define explicitly).
  • [x] Update AGENTS.md / task-manager skill with the one-liner operator path.

Implementation Progress

  • Added tasks *ARGS recipe in Justfile:
  • just tasks serve starts/ensures background heartbeat loop and then launches tasks server
  • default tasks-server port 8005 (separate from just plans MkDocs at 8004)
  • Idempotent heartbeat behavior:
  • reuses existing tasks/logs/task_manager/task-manager-<owner>.heartbeat.pid when live
  • stale pid file is cleaned up automatically
  • second run prints heartbeat already running and only starts the server
  • Follow-up robustness pass:
  • recipe now accepts *ARGS parsing so just tasks serve owner=<owner> port=<port> interval=<seconds> works reliably
  • heartbeat launch uses detached nohup + disown so Ctrl-C on server does not kill the background heartbeat
  • just tasks now requires explicit serve action and defaults owner from TASK_MANAGER_OWNER or current user
  • Updated operator docs:
  • AGENTS.md one-liner path
  • .codex/skills/task-manager/SKILL.md quick command list

QA Exploration

  • N/A (operator tooling orchestration; validated with command smoke tests)
  • [x] QA exploration completed (or N/A for non-UI tasks)

Review Feedback

  • [x] Review cleared