Queue Status Lite - alexherrero/agentm GitHub Wiki

Queue status lite

The /queue-status-lite command provides a read-only dashboard. It lists every active plan under a project's resolved state directory โ€” its vault directory's tasks/ on a synced backend, or a repo-local .harness/ for a project with no vault. Each entry shows the plan status and the head of the progress log. The command is deterministic. It makes no writes. It arbitrates no claims โ€” the human stays the arbiter. The reasoning lives in Named plans; this page is the lookup.

โšก Quick Reference

Property Value
Script (agentm-shipped) scripts/queue_status_lite.py
Invocation python3 scripts/queue_status_lite.py [--state-dir PATH] (--harness-dir accepted as an alias)
--state-dir PATH the project's vault directory, or a repo-local .harness/, to enumerate; omit to resolve from cwd via harness_memory.state_dir
Slash-command surface /queue-status-lite โ€” crickets-provided (development-lifecycle plugin), wraps this script
Reads on a synced backend, every task under tasks/ whose tracker is not done or dropped; with no vault, the repo-local PLAN.md plus every named PLAN-<name>.md (agentm-vault plan 15 retired the vault's _harness/ โ€” the two are no longer merged in one directory)
Per plan, reports plan name ยท its status (a task's tracker, else its Status: line) ยท the head (most-recent entry) of the matching progress log
Writes none โ€” read-only; the fixture is byte-identical before/after a run
Claim arbitration none โ€” informational dashboard only; the human arbitrates
Missing-progress placeholder (no progress file) (also (empty) / (unreadable))
Exit code 0 โ€” always, including an unresolved, missing, or empty state directory

What it lists

On a synced backend the script reads every active task under the project's tasks/ directory โ€” a finished (done or dropped) task is left out, since a dashboard of active work doesn't list closed tasks. With no vault it reads the repo-local .harness/'s flat pair: the singleton PLAN.md, then any named PLAN-<name>.md file, alphabetically. The two are never combined โ€” a project resolves to exactly one of them (agentm-vault plan 15):

Column Source
Plan name tasks/<name>/plan.md for a task, or the filename (PLAN.md / PLAN-<name>.md) for a repo-local pair
Status a task's tracker status, when its tracker.md exists and parses; otherwise the plan's Status: line (**Status:** and Status: both accepted; โ€” if absent)
Progress head the last non-empty line of the matching progress log โ€” progress.md beside the plan itself for a task, progress-<name>.md in the repo-local .harness/ otherwise โ€” truncated to 120 chars with a trailing โ€ฆ

Archived plans (PLAN.archive.*.md) and GDrive conflict copies (PLAN-foo (conflicted copy โ€ฆ).md) are excluded โ€” the former by the PLAN-* glob, the latter via hm._conflict_family.

Output shape

Active plans in <dir>:

  PLAN.md      [in-progress]
               last: <most-recent progress line, truncated to 120 chars with โ€ฆ>
  PLAN-foo.md  [planning]
               last: <โ€ฆ>

A plan with no matching progress file still lists, with the head shown as (no progress file). An unresolved or missing state directory prints No plan state directory to read (...); a resolved but empty one prints No plans found in <dir>. Both still exit 0.

Contract

  • Read-only. The command performs zero filesystem mutation. Its test asserts the fixture state directory is byte-identical before and after a run.
  • Deterministic. The script enumerates the resolved state directory โ€” no network, no transcript mining, no sub-agent dispatch. Output depends only on the directory contents.
  • No arbitration. It does not claim, lease, lock, or assign plans to workers. It surfaces state for a human coordinator to read; the design deliberately omits queue/lease machinery.
  • Always exit 0. Success exits 0; so does every graceful path โ€” no resolvable state directory, a missing directory, or an empty one. A status read never errors on absence.

Implementation

Surface Location
CLI entry ยท --state-dir flag (--harness-dir alias) ยท both paths return 0 scripts/queue_status_lite.py#L163
Dir resolution โ€” fall back to harness_memory.state_dir when flag omitted scripts/queue_status_lite.py#L156
list_plan_files โ€” every task not yet done or dropped under a vault project's tasks/, or a repo-local .harness/'s flat pair, singleton first (agentm-vault plans 09/15); local wrapper filters hm.list_plan_files's canonical enumeration by hm._task_is_finished scripts/harness_memory.py#L995 (canonical), scripts/queue_status_lite.py#L76 (local wrapper)
list-plans CLI verb โ€” enumerates active plan files + emits active-binding=<slug> when .harness/active-plan is set; used by both session-start hooks for plan discovery scripts/harness_memory.py#L2507 (dispatch), locked by TestListPlansCLI in scripts/test_harness_memory.py (7 tests)
_plan_label โ€” the dashboard name for a plan: tasks/foo/plan.md for a task, else PLAN.md / PLAN-foo.md (agentm-vault plan 09) scripts/queue_status_lite.py#L44
_tracker_status โ€” a task's status from the tracker beside its plan, when one exists and parses; the plan's own Status: line is the fallback scripts/queue_status_lite.py#L60
_extract_status โ€” bold + un-bold Status: scripts/queue_status_lite.py#L89
_progress_head โ€” (no progress file) / (empty) / (unreadable), 120-char truncation scripts/queue_status_lite.py#L99
collect_plan_statuses โ€” PlanStatus rows; reuses hm._normalize_plan_name / hm._plan_pair for a repo-local pair, a task's own progress.md beside its plan otherwise scripts/queue_status_lite.py#L116
harness_memory.state_dir โ€” the project's vault directory on a synced backend, else a repo-local .harness/ (renamed from harness_state_dir under agentm-vault plan 15, when the vault side stopped being _harness/) scripts/harness_memory.py#L946
Test suite (14 tests); the task-layout reading is covered together with plan_graph.py and machinery_doctor.py scripts/test_queue_status_lite.py, scripts/test_projects_layout_readers.py

Related

  • Named plans โ€” the naming contract (PLAN-<name>.md / progress-<name>.md) this command enumerates, and why the human is the arbiter.
  • Vault write protocol โ€” the write protocol named plans go through; this read-model takes no lock because it never writes.
  • CI gates โ€” check-multi-plan-naming (#13) locks the naming contract this command reads against.
  • Repo layout โ€” where scripts/ lives (test infra + read-model scripts; never propagated to target projects).
โš ๏ธ **GitHub.com Fallback** โš ๏ธ