skills/docs/requirements/001-agent-orchestrator.md

001 - Agent Orchestrator

User Story

As the operator of many parallel agents, I want one simple Agent Orchestrator surface and a radio that only interrupts for urgent calls, so that agents spend few tokens on talk, urgent news reaches them at once, and I can drill from three views down to any agent, branch or artefact.

Decisions (operator-confirmed 2026-11-06; do not re-litigate)

1. One document: radio model, surface, pkgmgr branch tree and views live in this one requirement as phases. Rejected: one document per feature (the operator wants the whole picture in one place).
2. Location: docs/requirements/NNN-slug.md, numbered per repository. Rejected: a file next to the code (no index, no numbering).
3. Radio classes: post, call, newsletter, broadcast, mayday, pan-pan, security. Rejected: broadcast only as the umbrella of the three alarms (the operator wants an immediate call to all without alarm).
4. Mailbox: post (one agent) and newsletter (all agents) are delivered only when the agent ends its turn and goes idle, batched; an agent already idle is not woken and sees its mailbox at the end of its next turn. Rejected: next prompt, next tool step (interrupts work), batched wake-ups (one turn per wake).
5. Immediate classes: call, broadcast, pan-pan, mayday and security reach the agent at its next tool step and wake an idle agent.
6. Call receipt: the caller gets a delivered/read receipt and does not wait; an answer is a call of its own. Rejected: the caller blocks until the answer (costs the caller), delivery without feedback.
7. Mayday pause: while a mayday holds, a PreToolUse hook blocks every writing action until radio.py clear; reading, the radio and teardown stay allowed. The sender and every agent that joins with radio.py assist to help keep working. Rejected: an instruction only (not enforced), heavy jobs only (today's behaviour, too weak), a full blockade that also stops the helpers.
8. Radio and post: two channels. radio.py send is the radio and always immediate (call, broadcast, pan-pan, mayday, security); radio.py post is mail and always delayed (post with --to, newsletter without). send direct stays as an alias so running peers keep working: with --wake it becomes call, without it post. Rows stored before the change carry no version mark and are read as before: direct as post, broadcast as newsletter. Rejected: send broadcast as an alias of newsletter (makes the immediate broadcast unreachable).
9. Name: kvb-hub is renamed in full, with a one-time migration: visible "Agent Orchestrator", technical kvb-orchestrator / kvb_orchestrator (directory, module, container, systemd unit, MCP server, environment KVB_ORCHESTRATOR_*, make targets). Rejected: visible name only (two names for one thing).
10. Navigation: Stream (sub-items Inbox and Regeln) · Agents (ex Graph) · Artifacts (ex Tree). Agents and Artifacts each offer Orbit, Chord, Swimlane, Tree and 3D.
11. Header: title · ⌘K · ⚙ only. The status pills become navigation badges (Inbox: waiting items, Agents: active agents, Artifacts: runner jobs); Mayday shows only as a red banner with "aufheben" while active; the background shows day and night. Rejected: one status dot with a popover (an extra click), a status block in a side bar, a "Lage" screen (effort), no header at all.
12. Tools: Steuerung (Funk an alle, Mayday aufheben, Priorität, Tag/Nacht) moves to the Agents toolbar, Regeln under Inbox, Himmel, Musik, Leitstand and Benachrichtigungen to ⚙ "Ambiente"; ⌘K reaches every one. Rejected: one ⋯ menu (hides instead of ordering).
13. Stream: four category chips Für dich · Funk · Arbeit · Transkripte; one search line with agent:, art:, seit:; sub-filters, saved views and a custom range under "Filter ▾"; the time bar becomes "24 h ▾" with the replay inside; transcripts are off by default. Rejected: a self-grouping stream, a Kibana-like query language (effort), preset chips only.
14. 3D: 3d-force-graph 1.80.1 on three 0.186.1, vendored as in meta.infinito.nexus; the Canvas depth axes Zeit and Spawn-Tiefe become 3D options. Rejected: keeping the Orbit-only Canvas depth.
15. Artifacts scope: git (repositories → branches → worktrees with their agents and reviews) plus the kvb-org-rasci register artefacts (images, volumes, logs) as leaves of the task or worktree that owns them. Rejected: git only.
16. Artifacts views: Orbit: repository sun, branch planets (size = commits ahead), worktree moons, agent satellites. Chord: branch overlap (same files touched, merges) as conflict risk. Swimlane: one lane per branch with commits, reviews, gates and pushes. Tree: the pkgmgr branch tree.
17. Tree data: the scan moves from hub/kvb_hub/tree.py into pkgmgr as pkgmgr branch tree --format json|yaml --output FILE, rewritten by a systemd user timer every minute and after every pkgmgr branch action; the orchestrator only reads the file, no git runs in its container. Rejected: the hub keeps scanning (pkgmgr is not the single source, git runs in the container), a live websocket daemon (effort). Hardened through kvb-think-dialectic before it is built.
18. Order: 1 radio → 2 surface and rename → 3 pkgmgr branch tree → 4 views and 3D; one bundle per phase, each change set through kvb-code-refactor.
19. Icons over text: every HTML surface a skill renders (the orchestrator, the review pages, the meditation page) shows Bootstrap Icons instead of text labels wherever an icon carries the meaning, each with a tooltip and an aria-label; terminal output and SKILL.md keep emoji. Rejected: Font Awesome Free (icons under CC BY 4.0, core loads it from a kit CDN), emoji in HTML (look differs per platform).
20. Branch state: pkgmgr branch tree covers every repository pkgmgr manages and gives each branch and worktree the classification of pkgmgr branch gc (one implementation, no second copy): merged and by what, clean or uncommitted changes, unpushed commits, gone upstream, locked, stale, protected and the gc skip reason. The Artifacts Tree shows it as icons. Phase 3 builds the data, phase 4 the icons.
21. Delete from the tree: merged, orphaned branches are deleted by click in the Artifacts Tree (phase 4), per item and as "Alle gemergten löschen":
    • Credentials: only while KeePassXC is unlocked; it hands pkgmgr the GitHub token through the Secret Service and the SSH key through its SSH agent, and no secret passes the orchestrator container. Rejected: the master password typed into the dialog (secret crosses container and browser), a token-only, local-only delete.
    • Scope: exactly what pkgmgr branch gc --apply deletes for a merged-clean item (worktree, local and remote branch, compose stack, images); a gc skip reason locks the button. Rejected: local only.
    • Confirmation: the click shows the gc dry-run lines of the chosen items, and "Löschen" needs the operator signature (/api/sign). Rejected: a second click without signature, one click without preview.
    • Execution: the orchestrator writes a signed job into a host directory; a systemd user path unit runs pkgmgr branch gc --apply for exactly those items and writes the result back. Rejected: an operator.py row (not direct).
22. Organisation update: a new skill kvb-org-update tells every agent and client which skills changed and how to use them, as one newsletter per update; phase 1 announces the radio change through it.

Approach

flowchart TD
    subgraph P["🧭 0 · Preparation"]
        P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
        P2 -- "✏️ corrections" --> P1
    end
    P2 -- "🤖 yes" --> R1
    subgraph R["📻 1 · Radio model"]
        R1["🔴 Red tests: classes, mailbox, receipt, mayday block"] --> R2["🛠️ radio.py, Stop mailbox hook, PreToolUse mayday hook, SKILL.md"]
        R2 --> R3{"🧪 Tests and make test green?"}
        R3 -- "🔴 no: fix" --> R2
        R3 -- "🟢 yes" --> R4["🧹 kvb-code-refactor"]
        R4 --> RF{"💬 Operator feedback?"}
        RF -- "✏️ changes" --> R2
    end
    RF -- "👍 commit word" --> S0
    subgraph S["🧭 2 · Surface and rename"]
        S0["🔀 Rebase feature/kvb-hub onto origin/master"] --> S1["🔴 Red tests: nav, header, badges, stream, migration"]
        S1 --> S2["🛠️ Nav, header, badges, banner, stream, inbox, tools, rename + migration"]
        S2 --> S3{"🧪 Tests green?"}
        S3 -- "🔴 no: fix" --> S2
        S3 -- "🟢 yes" --> S4["📸 Screenshots 1920 / 1366 / 390 px"]
        S4 --> SF{"💬 Operator feedback?"}
        SF -- "✏️ changes" --> S2
    end
    SF -- "👍 commit word" --> T0
    subgraph T["🌳 3 · pkgmgr branch tree"]
        T0["⚖️ kvb-think-dialectic on the data path"] --> T1["🔴 Red tests on fixture repositories"]
        T1 --> T2["🛠️ pkgmgr branch tree with gc states, timer, orchestrator reads the file"]
        T2 --> T3{"🧪 Tests green, no git in the container?"}
        T3 -- "🔴 no: fix" --> T2
        T3 -- "🟢 yes" --> TF{"💬 Operator feedback?"}
        TF -- "✏️ changes" --> T2
    end
    TF -- "👍 commit word" --> V1
    subgraph V["🪐 4 · Agents and Artifacts views"]
        V1["🔴 Red tests: five views per tab, artefact leaves, delete job"] --> V2["🛠️ Orbit, Chord, Swimlane, Tree with state icons and delete, 3D (3d-force-graph), host gc unit"]
        V2 --> V3{"🧪 Tests green?"}
        V3 -- "🔴 no: fix" --> V2
        V3 -- "🟢 yes" --> V4["📸 Screenshots of every view"]
        V4 --> VF{"💬 Operator feedback?"}
        VF -- "✏️ changes" --> V2
    end
    VF -- "👍 fits" --> D1["🏁 Full gate, commit with operator OK, push hand-over"]

Acceptance Criteria

Radio model

• radio.py send accepts exactly call, broadcast, pan-pan, mayday, security and the alias direct; post, newsletter and any other class exit 2.
• radio.py post --to X stores post; radio.py post without --to stores newsletter.
• call and send direct require --to; broadcast, pan-pan, mayday and security exit 2 with --to.
• send direct --wake is stored as call, send direct as post.
• New rows carry a version mark; rows without it are read as before: direct as post (as call when it woke), broadcast as newsletter.
• The UserPromptSubmit hook (radio.py hook) and the PostToolBatch hook (radio.py tool) never print a post or newsletter row.
• A new Stop hook radio.py mailbox, registered in scripts/enable-plugins.js, prints the unseen post and newsletter rows of the session at most 10 at a time with a "N more" line, marks them seen and exits 2; with nothing unseen it exits 0 and prints nothing.
• radio.py listen wakes an idle session only for call, broadcast, pan-pan, mayday and security, never for post or newsletter.
• radio.py tool delivers call (to its addressee), broadcast, pan-pan, mayday and security at the next tool step.
• When a call reaches the callee's context, a receipt row (callee, call time, read time) is stored; the caller's mailbox shows "CALL read ". The receipt never wakes the caller.
• While radio-silence.json holds an active mayday, a PreToolUse hook (matcher Edit|Write|MultiEdit|NotebookEdit|Bash) exits 2 for Edit, Write, MultiEdit and NotebookEdit and for every Bash command that matches neither the config's never_block nor its new mayday_allow regexes nor a plain call of radio.py.
• The mayday's sender passes; radio.py assist adds the caller to the mayday's helpers, who pass too, and the mayday line names them.
• After radio.py clear the same calls pass again.
• skills/kvb-org-radio/SKILL.md separates the radio (send, immediate) and the post (post, delayed), each class with when to use it and how it is delivered; post is the default; markdownlint stays green.

Organisation update

• A skill kvb-org-update with scripts/update.py exists.
• update.py --repo <skills repo> --dry-run prints every skill whose files changed between the last announced revision (kept in the council directory) and HEAD, with the subjects of the commits that touched it.
• Without --dry-run it sends one newsletter through radio.py post that names each changed skill and tells every agent to re-read its SKILL.md before the next use, then records HEAD as announced; a second run without new commits sends nothing.
• The radio change of phase 1 is announced through it.

Orchestrator surface and rename

• The page title and heading read "Agent Orchestrator".
• grep -rnE 'kvb-hub|kvb_hub|KVB_HUB' over the repository finds only the migration code and its tests.
• The install migrates ~/.local/share/kvb-hub, ~/.config/kvb-hub, ~/.local/state/kvb-hub-approvals, the kvb-hub MCP registration, the settings hook entries, the systemd unit and the container to the kvb-orchestrator names. A second run changes nothing (scratch-HOME test).
• The navigation has exactly three top-level entries Stream, Agents and Artifacts; Stream has the sub-items Inbox and Regeln.
• Every agent appears once under its current name: a register worker such as "Stage (this session)" or "infinito-nexus-core-c8 (Production)" maps to the agent named before the bracket.
• The keys 1 to 3 switch the top-level entries.
• The hashes #stream, #stream/inbox, #stream/rules, #agents/<view> and #artifacts/<view> route; #graph… and #tree redirect to their successors.
• Agents and Artifacts show a switch with Orbit, Chord, Swimlane, Tree and 3D in this order, and each view has its own hash.
• The header holds exactly the title, the ⌘K button and the ⚙ button.
• Badges:
  • Inbox shows the waiting items that are not snoozed.
  • Agents shows the agents with a heartbeat in the last 900 s.
  • Artifacts shows the runner jobs that are queued or running.
  • A badge at 0 is hidden.
• A red Mayday banner with "aufheben" exists if and only if a mayday is active; "aufheben" runs radio.py clear.
• The Agents toolbar holds:
  • Funk an alle, with the class choice Newsletter, Broadcast, Pan-Pan, Security, Mayday and Newsletter preselected.
  • Mayday aufheben, Priorität and Tag/Nacht.
• The agent panel sends with the choice Post (preselected) or Call.
• ⚙ "Ambiente" holds Himmel, Musik, Leitstand and Benachrichtigungen; ⌘K lists every former header tool.
• The Stream shows exactly four category chips Für dich, Funk, Arbeit and Transkripte, and one search line that filters by agent:, art: and seit:.
• "Filter ▾" holds the kind sub-filters, the transcript parts, the saved views and the custom range.
• The time control reads "24 h ▾" and holds the replay.
• Transcripts are off by default.
• The Inbox renders in the main area under #stream/inbox; the right rail #rail no longer exists, at any width.
• The read-aloud class choice lists exactly the seven classes of decision 3; Mayday stays checked and locked.

pkgmgr branch tree

• The kvb-think-dialectic result on the data path is recorded in the phase 3 commit body before any code of phase 3 is written.
• pkgmgr branch tree --format json prints, for every repository pkgmgr knows and every worktree under <repo>/.worktrees and ~/.local/share/worktrees, these fields:
  • the repository's path, remote and default branch;
  • per branch: upstream, ahead, behind and gone;
  • per worktree: path, HEAD and its state, one of clean, changed or missing;
  • detached worktrees, and generated_at.
• It lists every repository pkgmgr list names, also one without extra branches or worktrees.
• Per branch and worktree it carries the gc state (merged-clean, unmerged, dirty, protected, stale), what merged it (ancestor, pr#N, line:X), the counts of staged, unstaged and untracked files, ahead, behind, gone, locked and the gc skip reason.
• Tree and gc share one classification function; on a fixture pkgmgr branch tree --format json and pkgmgr branch gc --json agree on every item's state.
• Forge facts (open and merged pull requests) are fetched at most once per 10 min per repository, only with a token from the Secret Service; without one the file says forge: unavailable and "merged by" falls back to ancestor and line.
• delete_ready is true only while the token resolves through the Secret Service and the KeePassXC SSH agent holds a key; otherwise it is false with the reason.
• --format yaml prints the same data.
• --output FILE writes it atomically.
• The scan starts no hook, filter, fsmonitor, pager or external diff of a scanned repository and never lazy-fetches (fixture test with a planted core.fsmonitor).
• pkgmgr branch open|close|drop|gc rewrite the file when it exists.
• The orchestrator install enables a systemd user timer that writes it every 60 s.
• The orchestrator mounts the file read-only and reads only it.
• hub/kvb_hub/tree.py's git scan is gone and no module of the orchestrator starts git.

Agents and Artifacts views

• Artifacts:
  • Orbit, Chord, Swimlane and Tree draw what decision 16 names, from the pkgmgr tree file.
  • Register artefacts (images, volumes, logs) appear as leaves of their task or worktree.
• Agents:
  • Orbit, Chord and Swimlane keep today's content.
  • Tree shows the operator → chair → sessions → subagents spawn tree with running and finished states.
• 3D in both tabs runs on the vendored 3d-force-graph 1.80.1 and three 0.186.1, with their MIT licence texts beside them and no CDN request (CSP unchanged).
• 3D offers the layouts Kraft, Zeit and Spawn-Tiefe.
• A click on a 3D node opens the same panel as in 2D.
• 3D respects prefers-reduced-motion.

Delete merged branches

• The Artifacts Tree marks every branch and worktree with icons for merged (with what merged it), clean, uncommitted changes (with counts), unpushed commits, gone upstream, locked, stale and protected.
• A merged-clean item without a gc skip reason shows a delete button, and the Tree header shows "Alle gemergten löschen"; both are disabled, with the reason as tooltip, while delete_ready is false.
• A click shows the gc dry-run lines of exactly the chosen items; "Löschen" requires the operator signature through /api/sign.
• The orchestrator writes the signed job (repository, branch, worktree and tip sha per item, no command) into a host-mounted job directory and holds no git, token or key.
• A systemd user path unit verifies the signature on the host and runs pkgmgr branch gc --apply for exactly the signed items, matched exactly, never as a pattern.
• The unit refuses, and changes nothing for, an item whose tip or state differs from the signed one, an unknown repository, a non-merged-clean item and a job with a bad or missing signature, and reports why.
• The unit writes each item's result back and rewrites the tree file; the Tree shows the result.

Icons

• Bootstrap Icons 1.13.1 is vendored once as an SVG sprite with its MIT licence text beside it; no page loads it from a CDN.
• The navigation, the header, the view switches, the toolbars, the Stream chips and the Inbox actions of the orchestrator show icons instead of text labels.
• The review pages and the meditation page show icons instead of text labels on their buttons.
• Every icon element has a title and an aria-label that carry the former text (DOM test over every page).

Tests

• Unit
  • Radio: class mapping, --to rules, the mailbox Stop hook, the receipt and the mayday block hook, each red before and green after.
  • Organisation update on a fixture repository: changed skills with their subjects, nothing new sends nothing.
  • pkgmgr branch tree on fixture repositories: ahead, behind, gone, detached and missing worktree, JSON and YAML, the planted fsmonitor, staged, unstaged and untracked counts, tree and gc states agreeing.
  • Delete job: a bad signature, a changed tip, a non-merged-clean item and a branch name with pattern characters are each refused.
  • Orchestrator: the scratch-HOME migration, routing including old hashes, badge counts.
• Integration
  • Two scratch sessions exchange post and call through the real hook entry points (JSON on stdin): the post appears only on the callee's Stop and the call at its next tool step with a receipt to the caller.
  • A mayday blocks an Edit until clear.
  • The orchestrator's /api/tree serves a pkgmgr-written file.
  • On a fixture repository with a file remote and a test token source, a signed job through the path unit removes the merged worktree, the local and the remote branch, and the rewritten tree no longer lists them.
  • make test green on the commit of each phase.
• E2E
  • A headless Chromium and Firefox run opens Stream, Inbox, Regeln and every view of Agents and Artifacts at 1920, 1366 and 390 px wide and saves the screenshots shown at each operator checkpoint.
  • It sends a Call from the agent panel and sees its receipt in the Stream.
  • On fixture data it shows the state icons in the Artifacts Tree and runs the delete flow: dry-run dialog, signature, result.