feat(orchestrator): overlay the queue order on the Tasks board

queue_order.py parses queue.py list --json into positions and reasons; the Tasks board overlays each card with its queue position, wait and reason, and falls back to Order only when the queue cannot be read. Tests run once on unify/skills-20261114 after the merge (operator order 2026-11-14).

🎯 Fix: 80 %
💥 Break: 10 %
💸 Tokens: 20 %
⏱️ Velocity: 20 %
🛡️ Security: 100 %
🏆 Score: 100
🚦 Gate: ⛔ fix 80 % < 90, break 10 % > 5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-14 21:32:48 +00:00
1 parent 48f26b678a
commit e1de1ee0e6
15 files changed
+975 -20

No files matched your search

+3
View File
@@ -31,6 +31,7 @@ from .messaging import Messaging
from .names import Names
from .offices import Offices
from .presence import SNAPSHOT
from .queue_order import QUEUE_SCRIPT, QueueOrder
from .receipts import (
NAMES,
READS,
@@ -127,6 +128,7 @@ class Hub(Mcp, Reviewing, Asking, Messaging, Choosing, Approving, Denying, Reque
voice_notes: VoiceNotes
replay: Path
history: History
queue_order: QueueOrder
view_store: ViewStore
def hosts(self) -> tuple[str, str]:
@@ -193,6 +195,7 @@ def open_hub(council: Path, pages: Path, public_port: int, state: Path, host_sta
kept=places.kept,
council=council,
history=History(council / queue_live.HISTORY),
queue_order=QueueOrder(script=scripts.skills / QUEUE_SCRIPT, council=council, home=state),
pages=pages,
public_port=public_port,
reviews=reviews,
@@ -0,0 +1,193 @@
from __future__ import annotations
import json
import math
import subprocess
import sys
import threading
from dataclasses import dataclass, field
from pathlib import Path
from .crons import outcome_of
from .records import shown
from .skill_scripts import script_env
from .tasks import QUEUE_SHOWN, TEXT_SHOWN, prio_of
QUEUE_SCRIPT = "kvb-org-queue/scripts/queue.py"
ORDER_ARGS = ("list", "--json")
ORDER_SECONDS = 20
ORDER_TIMEOUT = 10
ORDER_LIMIT = 1 << 20
TRACE_SHOWN = 20
POSITION_SHOWN = 32
CLASSES = ("hotfix", "fix", "feature", "main")
def amount(value: object) -> float | None:
if isinstance(value, bool) or not isinstance(value, int | float) or not math.isfinite(value) or value < 0:
return None
return float(value)
def text(value: object) -> str:
return value[:TEXT_SHOWN] if isinstance(value, str) else ""
def position_of(value: object) -> int | str | None:
if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
return value
return value[:POSITION_SHOWN] if isinstance(value, str) and value else None
def steps_of(value: object) -> list[str]:
return [step[:TEXT_SHOWN] for step in value[:TRACE_SHOWN] if isinstance(step, str)] if isinstance(value, list) else []
def bounded(value: object) -> str | None:
return value if isinstance(value, str) and len(value) <= TEXT_SHOWN else None
def score_of(value: object) -> float | None:
return amount(value.get("score") if isinstance(value, dict) else value)
def queue_job(raw: object) -> dict | None:
"""Args:
raw: one row of `queue.py list --json`.
Returns:
The row as the board shows it, each field of one type and bounded:
position an int or a word such as run, class one of CLASSES, prio an
int, wsjf (a number or {"score"}), waited_s and eta_s non-negative
numbers, each else None; trace at most TRACE_SHOWN strings; agent
falls back to name. None for a row without a string id.
"""
if not isinstance(raw, dict) or not isinstance(raw.get("id"), str) or not raw["id"]:
return None
klass = bounded(raw.get("class"))
return {
"position": position_of(raw.get("position")),
"id": raw["id"][:TEXT_SHOWN],
"kind": text(raw.get("kind")),
"task": bounded(raw.get("task")),
"session": text(raw.get("session")),
"agent": text(raw.get("agent", raw.get("name"))),
"class": klass if klass in CLASSES else None,
"prio": prio_of(raw),
"wsjf": score_of(raw.get("wsjf")),
"waited_s": amount(raw.get("waited_s")),
"eta_s": amount(raw.get("eta_s")),
"reason": text(raw.get("reason")),
"trace": steps_of(raw.get("trace")),
}
def lines_of(stdout: str) -> list | None:
try:
return [json.loads(line) for line in stdout.splitlines() if line.strip()] or None
except (ValueError, RecursionError):
return None
def parsed(stdout: str) -> object:
try:
return json.loads(stdout)
except (ValueError, RecursionError):
return lines_of(stdout)
def rows_of(stdout: str) -> list | None:
data = parsed(stdout)
if isinstance(data, dict):
data = data.get("entries") if "entries" in data else [data] if "id" in data else None
return data if isinstance(data, list) else None
def queue_jobs(stdout: str) -> list[dict] | None:
"""Args:
stdout: what `queue.py list --json` printed: a JSON list of rows,
an object holding them under entries, or one row object per
line.
Returns:
queue_job() of each row in grant order, each id once, at most
QUEUE_SHOWN; None when the output holds no such rows.
"""
rows = rows_of(stdout)
if rows is None:
return None
found: dict[str, dict] = {}
for job in map(queue_job, rows):
if job is not None and job["id"] not in found:
found[job["id"]] = job
return list(found.values())[:QUEUE_SHOWN]
def live_ids(queue: list[tuple[dict, float]]) -> frozenset[str]:
return frozenset(shown(entry.get("id")) for entry, _ in queue if outcome_of(entry) is None)
def grant_order(chain: list[tuple[str, bool]], jobs: list[dict] | None) -> list[tuple[str, bool]]:
"""Args:
chain: queue_chain(), the hub's own grant order.
jobs: queue_jobs() of the installed queue.py, None without them.
Returns:
The chain in queue.py's order: the ids jobs lists in its order, the
others after them in the chain's; the chain itself without jobs.
"""
if jobs is None:
return chain
place = {job["id"]: index for index, job in enumerate(jobs)}
return sorted(chain, key=lambda pair: place.get(pair[0], len(place)))
@dataclass
class QueueOrder:
script: Path
council: Path
home: Path
lock: threading.Lock = field(default_factory=threading.Lock)
cached: list[dict] | None = None
live: frozenset[str] | None = None
at: float = 0.0
def run(self) -> list[dict] | None:
try:
done = subprocess.run(
[sys.executable, str(self.script), *ORDER_ARGS],
capture_output=True,
timeout=ORDER_TIMEOUT,
env=script_env(self.home, self.council),
stdin=subprocess.DEVNULL,
check=False,
)
except (OSError, subprocess.TimeoutExpired):
return None
if done.returncode != 0 or len(done.stdout) > ORDER_LIMIT:
return None
return queue_jobs(done.stdout.decode("utf-8", errors="replace"))
def get(self, live: frozenset[str], now: float) -> list[dict] | None:
"""Args:
live: live_ids() of the queue entries the hub reads.
now: epoch seconds.
Returns:
[] while no entry is live, without a run. Else queue_jobs() of a
`queue.py list --json` run, run again once ORDER_SECONDS passed
or the live ids changed; while another request runs it, the rows
read before. None while the installed queue.py lists no JSON,
fails or overruns ORDER_TIMEOUT, so the board keeps the hub's own
order and the page says why.
"""
if not live:
return []
if not self.lock.acquire(blocking=False):
return self.cached
try:
if live != self.live or now - self.at >= ORDER_SECONDS:
self.cached, self.live, self.at = self.run(), live, now
return self.cached
finally:
self.lock.release()
@@ -34,6 +34,10 @@ def bounded(stdout: str) -> str:
return "\n".join([first if len(first) <= FIRST_LINE_LIMIT else "", ELIDED, rest[-OUTPUT_LIMIT:]])
def script_env(home: Path, council: Path) -> dict[str, str]:
return {"PATH": SAFE_PATH, "HOME": str(home), "AGENTS_COUNCIL_ROOT": str(council), "PYTHONDONTWRITEBYTECODE": "1"}
def script_module(script: Path) -> ModuleType | None:
"""Returns:
The installed script as a module, loaded again after an install
@@ -73,7 +77,7 @@ class Scripts:
def run(self, script: str, args: list[str]) -> dict:
command = " ".join([Path(script).name, *args])
env = {"PATH": SAFE_PATH, "HOME": str(self.home), "AGENTS_COUNCIL_ROOT": str(self.council), "PYTHONDONTWRITEBYTECODE": "1"}
env = script_env(self.home, self.council)
try:
done = subprocess.run(
[sys.executable, str(self.skills / script), *args],
+4 -1
View File
@@ -24,6 +24,7 @@ from .messaging import message_row
from .orbits import TRACK_STEPS, track
from .phrasing import joined, phrase_parts
from .presence import presence, read_snapshot
from .queue_order import grant_order, live_ids
from .receipts import inline, read_of
from .records import epoch, iso_epoch, read_jsonl
from .register import (
@@ -120,9 +121,10 @@ class View:
settings = self.settings.get()
inbox = self.inbox(now, tasks, directory)
queue = queue_entries(self.council, self.history.rows)
jobs = self.queue_order.get(live_ids(queue), now)
order = stored_order(self.council / AGENT_ORDER)
rows = task_rows(tasks, queue, self.tree.get())
chain = queue_chain(queue, tasks, order, now)
chain = grant_order(queue_chain(queue, tasks, order, now), jobs)
return {
"settings": settings,
"media": media_origins(settings),
@@ -151,6 +153,7 @@ class View:
"tasks": rows,
"task_edges": task_edges(rows, chain),
"queue_line": queue_line(chain, queue),
"queue_jobs": jobs,
"agent_order": agent_order(tasks, claims, order),
"radio": radio,
"claims": claims,
+20 -5
View File
@@ -17,6 +17,7 @@ VIEW = {
"resources": {"hidden": [], "tokens": "interval", "combined": False, "combinedHidden": []},
"burn": {"overlays": []},
"home": {"pins": []},
"kanban": {"hidden": []},
}
VIEW_PATH = re.compile(r"[A-Za-z]{1,32}(?:\.[A-Za-z]{1,32})?")
SERIES_ID = re.compile(r"[A-Za-z0-9:_./-]{1,200}")
@@ -24,6 +25,7 @@ PIN_KIND = re.compile(r"[A-Za-z0-9:_./-]{1,32}")
IDS_LIMIT = 500
TOKEN_MODES = ("interval", "accumulated")
OVERLAYS = ("fix", "break", "tokens", "velocity", "security", "score")
KANBAN_LAYERS = ("line", "jobs")
PINS_LIMIT = 64
SPAN = (1, 12)
METRIC = "metric"
@@ -41,6 +43,12 @@ def series_ids(value: object, name: str) -> list[str]:
return list(value)
def members(value: object, name: str, what: str, allowed: tuple[str, ...]) -> list[str]:
if not isinstance(value, list) or not all(isinstance(item, str) and item in allowed for item in value) or len(set(value)) != len(value):
raise ToolError(f"{name} must list distinct {what} of {', '.join(allowed)}")
return list(value)
def span(value: object, name: str) -> int:
low, high = SPAN
if isinstance(value, bool) or not isinstance(value, int) or not low <= value <= high:
@@ -140,11 +148,9 @@ def valid_view(raw: object) -> dict:
resources = section(data["resources"], "resources", tuple(VIEW["resources"]))
burn = section(data["burn"], "burn", tuple(VIEW["burn"]))
home = section(data["home"], "home", tuple(VIEW["home"]))
kanban = section(data["kanban"], "kanban", tuple(VIEW["kanban"]))
if not isinstance(resources["tokens"], str) or resources["tokens"] not in TOKEN_MODES:
raise ToolError(f"resources.tokens must be one of {', '.join(TOKEN_MODES)}")
overlays = burn["overlays"]
if not isinstance(overlays, list) or not all(isinstance(item, str) and item in OVERLAYS for item in overlays) or len(set(overlays)) != len(overlays):
raise ToolError(f"burn.overlays must list distinct metrics of {', '.join(OVERLAYS)}")
return {
"resources": {
"hidden": series_ids(resources["hidden"], "resources.hidden"),
@@ -152,11 +158,20 @@ def valid_view(raw: object) -> dict:
"combined": flag(resources["combined"], "resources.combined"),
"combinedHidden": series_ids(resources["combinedHidden"], "resources.combinedHidden"),
},
"burn": {"overlays": list(overlays)},
"burn": {"overlays": members(burn["overlays"], "burn.overlays", "metrics", OVERLAYS)},
"home": {"pins": pins(home["pins"])},
"kanban": {"hidden": members(kanban["hidden"], "kanban.hidden", "layers", KANBAN_LAYERS)},
}
def upgraded(raw: object) -> object:
"""Returns:
A stored document of an older hub with each VIEW section it lacks
at its default; anything else as it is.
"""
return {**copy.deepcopy(VIEW), **raw} if isinstance(raw, dict) else raw
def slot(view: dict, path: object) -> tuple[dict, str]:
"""Args:
view: a document of the shape of VIEW.
@@ -188,7 +203,7 @@ class ViewStore:
self.file = file
self.lock = threading.Lock()
try:
self.current = valid_view(read_json(file))
self.current = valid_view(upgraded(read_json(file)))
except ToolError:
self.current = copy.deepcopy(VIEW)