agent-control-plane 0.2.0 → 0.4.9

package/tools/dashboard/dashboard_snapshot.py

@@ -13,9 +13,15 @@ from typing import Any
 
 ROOT_DIR = Path(__file__).resolve().parents[2]
 TOOLS_BIN_DIR = ROOT_DIR / "tools" / "bin"
+DASHBOARD_DIR = ROOT_DIR / "tools" / "dashboard"
 RENDER_FLOW_CONFIG = TOOLS_BIN_DIR / "render-flow-config.sh"
 WORKER_STATUS_TOOL = TOOLS_BIN_DIR / "agent-project-worker-status"
 
+if str(DASHBOARD_DIR) not in sys.path:
+    sys.path.insert(0, str(DASHBOARD_DIR))
+
+from issue_queue_state import collect_issue_queue
+
 
 def utc_now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -493,6 +499,13 @@ def collect_resident_workers(state_root: Path) -> list[dict[str, Any]]:
                 "last_action": env.get("LAST_ACTION", ""),
                 "last_failure_reason": env.get("LAST_FAILURE_REASON", ""),
                 "worktree": env.get("WORKTREE", ""),
+                "resident_lane_kind": env.get("RESIDENT_LANE_KIND", ""),
+                "resident_lane_value": env.get("RESIDENT_LANE_VALUE", ""),
+                "resident_lane": (
+                    f"{env.get('RESIDENT_LANE_KIND', '')}/{env.get('RESIDENT_LANE_VALUE', '')}"
+                    if env.get("RESIDENT_LANE_KIND", "") and env.get("RESIDENT_LANE_VALUE", "")
+                    else ""
+                ),
                 "metadata_file": str(path),
             }
         )
@@ -684,46 +697,68 @@ def collect_pr_retries(state_root: Path) -> list[dict[str, Any]]:
     return items
 
 
-def resolve_history_root(render_env: dict[str, str], yaml_env: dict[str, str], runs_root: Path) -> Path:
-    configured = (
-        render_env.get("EFFECTIVE_HISTORY_ROOT", "").strip()
-        or yaml_env.get("runtime.history_root", "").strip()
-    )
-    if configured and configured != ".":
-        return Path(configured)
-    if runs_root.name == "runs":
-        return runs_root.parent / "history"
-    return Path(".")
+def collect_github_outbox(state_root: Path) -> dict[str, Any]:
+    outbox_root = state_root / "github-outbox"
+    pending_root = outbox_root / "pending"
+    sent_root = outbox_root / "sent"
+    failed_root = outbox_root / "failed"
 
-
-def collect_issue_queue(state_root: Path) -> dict[str, list[dict[str, Any]]]:
-    queue_root = state_root / "resident-workers" / "issue-queue"
-    pending_root = queue_root / "pending"
-    claims_root = queue_root / "claims"
-
-    def collect_files(root: Path) -> list[dict[str, Any]]:
+    def list_items(root: Path, limit: int | None = None) -> list[dict[str, Any]]:
         if not root.is_dir():
             return []
+
         items: list[dict[str, Any]] = []
-        for path in sorted(root.glob("*.env"), key=lambda item: item.stat().st_mtime, reverse=True):
-            env = read_env_file(path)
+        for path in sorted(root.glob("*.json"), key=lambda item: item.stat().st_mtime, reverse=True):
+            payload = read_json_file(path)
             items.append(
                 {
-                    "issue_id": env.get("ISSUE_ID", path.stem.removeprefix("issue-")),
-                    "session": env.get("SESSION", ""),
-                    "claim_file": env.get("CLAIM_FILE", ""),
-                    "updated_at": env.get("UPDATED_AT", "") or file_mtime_iso(path),
-                    "state_file": str(path),
+                    "type": str(payload.get("type", "")),
+                    "repo_slug": str(payload.get("repo_slug", "")),
+                    "number": str(payload.get("number", "")),
+                    "kind": str(payload.get("kind", "")),
+                    "created_at": str(payload.get("created_at", "")),
+                    "updated_at": file_mtime_iso(path),
+                    "file": str(path),
+                    "add_count": len(payload.get("add", []) or []),
+                    "remove_count": len(payload.get("remove", []) or []),
+                    "body_preview": summarize_whitespace(str(payload.get("body", "")))[:120],
                 }
             )
+            if limit is not None and len(items) >= limit:
+                break
         return items
 
+    all_pending_items = list_items(pending_root)
+    pending_items = all_pending_items[:20]
+    sent_items = list_items(sent_root, limit=5)
+    failed_items = list_items(failed_root, limit=5)
+
     return {
-        "pending": collect_files(pending_root),
-        "claims": collect_files(claims_root),
+        "pending": pending_items,
+        "sent_recent": sent_items,
+        "failed_recent": failed_items,
+        "counts": {
+            "pending": len(all_pending_items),
+            "sent": len(list(sent_root.glob("*.json"))) if sent_root.is_dir() else 0,
+            "failed": len(list(failed_root.glob("*.json"))) if failed_root.is_dir() else 0,
+            "pending_comments": sum(1 for item in all_pending_items if item["type"] == "comment"),
+            "pending_approvals": sum(1 for item in all_pending_items if item["type"] == "approval"),
+            "pending_label_updates": sum(1 for item in all_pending_items if item["type"] == "labels"),
+        },
     }
 
 
+def resolve_history_root(render_env: dict[str, str], yaml_env: dict[str, str], runs_root: Path) -> Path:
+    configured = (
+        render_env.get("EFFECTIVE_HISTORY_ROOT", "").strip()
+        or yaml_env.get("runtime.history_root", "").strip()
+    )
+    if configured and configured != ".":
+        return Path(configured)
+    if runs_root.name == "runs":
+        return runs_root.parent / "history"
+    return Path(".")
+
 def build_profile_snapshot(profile_id: str, registry_root: Path) -> dict[str, Any]:
     env = env_with_profile(profile_id, registry_root)
     render_env = run_key_value_script(RENDER_FLOW_CONFIG, env)
@@ -742,6 +777,7 @@ def build_profile_snapshot(profile_id: str, registry_root: Path) -> dict[str, An
     retries = collect_issue_retries(state_root)
     pr_retries = collect_pr_retries(state_root)
     queue = collect_issue_queue(state_root)
+    github_outbox = collect_github_outbox(state_root)
     alerts = [alert for run in (runs + recent_history) for alert in run.get("alerts", [])]
     codex_rotation = collect_codex_rotation(render_env)
 
@@ -789,6 +825,8 @@ def build_profile_snapshot(profile_id: str, registry_root: Path) -> dict[str, An
             "active_retries": sum(1 for item in retries if not item.get("ready", True)),
             "scheduled_issues": len(scheduled),
             "alerts": len(alerts),
+            "pending_github_writes": github_outbox["counts"]["pending"],
+            "failed_github_writes": github_outbox["counts"]["failed"],
         },
         "runs": runs,
         "recent_history": recent_history,
@@ -800,6 +838,7 @@ def build_profile_snapshot(profile_id: str, registry_root: Path) -> dict[str, An
         "issue_retries": retries,
         "pr_retries": pr_retries,
         "issue_queue": queue,
+        "github_outbox": github_outbox,
     }
 
 

package/tools/templates/pr-fix-template.md

@@ -11,6 +11,7 @@ PR metadata:
 - PR: {PR_NUMBER} - {PR_TITLE}
 - URL: {PR_URL}
 - Base branch: {PR_BASE_REF}
+- Base tracking ref: {PR_BASE_TRACKING_REF}
 - Head branch: {PR_HEAD_REF}
 - Linked issue: {PR_LINKED_ISSUE_ID}
 - Risk classification: {PR_RISK}
@@ -55,7 +56,7 @@ Required flow:
 
 1. Inspect the current diff and the failing/pending CI signals first:
    - `openspec list` if the repo uses OpenSpec
-   - `git diff --stat origin/main...HEAD`
+   - `git diff --stat {PR_BASE_TRACKING_REF}...HEAD`
    - `git status --short`
    - if `Merge state` is not `CLEAN` or `Mergeable` is `FALSE`, treat branch drift/conflicts as the concrete blocker first
    - if `Actionable current-head review findings` is not `- none`, treat those findings as the concrete blockers to address first
@@ -68,6 +69,7 @@ Required flow:
    - do not run `git fetch`, `git merge`, `git rebase`, `git commit`, `git push`, or other Git metadata-writing commands from inside this worker; host-side wrappers own those steps
 3. If the blocker is branch drift or a merge conflict, use the already-prepared local refs and make the smallest branch-local source update needed to restore mergeability on this PR branch. Keep the resolution scoped to the PR intent; do not rewrite unrelated code.
    - Treat `Current local merge-conflict paths` as the authoritative conflict list to clear.
+   - Treat `{PR_BASE_TRACKING_REF}` as the authoritative base ref for any read-only diff or merge-base inspection.
    - Do not stop after fixing only one file if other conflict paths remain.
    - Before you declare success, rerun local merge simulation and confirm there are no remaining conflict paths for this branch against `{PR_BASE_REF}`.
 4. Make the smallest change that fixes the concrete PR blockers on this existing branch.

package/tools/templates/pr-merge-repair-template.md

@@ -11,6 +11,7 @@ PR metadata:
 - PR: {PR_NUMBER} - {PR_TITLE}
 - URL: {PR_URL}
 - Base branch: {PR_BASE_REF}
+- Base tracking ref: {PR_BASE_TRACKING_REF}
 - Head branch: {PR_HEAD_REF}
 - Linked issue: {PR_LINKED_ISSUE_ID}
 - Risk classification: {PR_RISK}
@@ -43,7 +44,7 @@ PR body:
 Required flow:
 
 1. Treat this worktree as an already-prepared merge repair state from host control-plane.
-   - `origin/{PR_BASE_REF}` has already been merged into this worktree locally.
+   - `{PR_BASE_TRACKING_REF}` has already been merged into this worktree locally.
    - if `Current unresolved merge-conflict paths` is not `- none detected after host merge preparation`, resolve those files first.
 2. Never run Git control commands from inside the worker:
    - do not run `git fetch`, `git pull`, `git merge`, `git rebase`, `git commit`, `git push`, or any command that writes Git metadata

package/SKILL.md

@@ -1,149 +0,0 @@
----
-name: agent-control-plane
-description: Use when working on the shared multi-project agent control plane, including scheduler/runtime orchestration, worktree and worker lifecycle, profile onboarding, and cross-project automation flows.
----
-
-# Agent Control Plane
-
-This repository is the canonical `agent-control-plane` package. It owns the
-generic scheduler/runtime, worktree lifecycle, profile onboarding, queue/risk
-automation, and profile-scoped prompt/template resolution used across multiple
-projects.
-
-Installed project profiles live under
-`~/.agent-runtime/control-plane/profiles/<id>/`. Treat the control plane itself
-as generic, then load the selected profile's local guidance only when the task
-is truly about that project. Integrated project data should stay in that
-external profile registry, not inside this repository.
-
-## What Lives Here
-
-- core operating manual in this `SKILL.md`
-- installed project profiles in `~/.agent-runtime/control-plane/profiles/*/control-plane.yaml`
-- installed profile notes in `~/.agent-runtime/control-plane/profiles/*/README.md`
-- workflow catalog in `assets/workflow-catalog.json`
-- worker dashboard in `tools/dashboard/` with launcher at `tools/dashboard/dashboard_snapshot.py`
-  and `tools/bin/serve-dashboard.sh`
-- dashboard autostart helpers in `tools/bin/dashboard-launchd-bootstrap.sh` and
-  `tools/bin/install-dashboard-launchd.sh`
-- project autostart helpers in `tools/bin/project-launchd-bootstrap.sh`,
-  `tools/bin/install-project-launchd.sh`, and
-  `tools/bin/uninstall-project-launchd.sh`
-- queue/label/risk scripts in `bin/`
-- heartbeat and reconcile hooks in `hooks/`
-- shared runtime wrappers, onboarding tools, and tests in `tools/bin/` and
-  `tools/tests/`
-
-The vendored runtime entrypoints used by live schedulers are published from this
-checkout into the shared canonical skill copy under
-`skills/openclaw/agent-control-plane`, then copied into
-`~/.agent-runtime/runtime-home/skills/openclaw/agent-control-plane` by
-`tools/bin/sync-shared-agent-home.sh`.
-
-## Required Startup Sequence
-
-Before doing non-trivial work in this repository or on an integrated project:
-
-1. Determine the active profile with `AGENT_PROJECT_ID`, `ACP_PROJECT_ID`, or
-   `tools/bin/render-flow-config.sh`.
-2. Read the selected profile notes in
-   `~/.agent-runtime/control-plane/profiles/<id>/README.md` when they exist.
-3. Read the selected repo's local startup docs before changing behavior:
-   `AGENTS.md`, `openspec/AGENT_RULES.md`, `openspec/AGENTS.md`,
-   `openspec/project.md`, and `openspec/CONVENTIONS.md`.
-4. Use a clean read-only inspection checkout first; move to an isolated
-   worktree or agent-owned checkout before making non-trivial edits.
-5. If the task changes product behavior, inspect the active OpenSpec changes
-   before implementation.
-
-For onboarding a new repository onto the shared control plane:
-
-1. Prefer `tools/bin/project-init.sh --profile-id <id> --repo-slug <owner/repo>`
-2. Fill in `~/.agent-runtime/control-plane/profiles/<id>/README.md`
-3. If you need manual control, the underlying steps remain:
-   `tools/bin/scaffold-profile.sh`, `tools/bin/profile-smoke.sh`,
-   `tools/bin/profile-adopt.sh`, and `tools/bin/sync-shared-agent-home.sh`
-
-For runtime control of one installed profile:
-
-1. Check state with `tools/bin/project-runtimectl.sh status --profile-id <id>`
-2. Start or ensure runtime with `tools/bin/project-runtimectl.sh start --profile-id <id>`
-3. Stop or recycle runtime with `tools/bin/project-runtimectl.sh stop --profile-id <id>`
-4. Use `tools/bin/project-runtimectl.sh restart --profile-id <id>` for a clean bounce
-5. Use `tools/bin/install-project-launchd.sh --profile-id <id>` when one
-   profile should survive reboot/login via a per-project LaunchAgent
-6. Remove per-project autostart with
-   `tools/bin/uninstall-project-launchd.sh --profile-id <id>`
-7. Remove an installed profile with `tools/bin/project-remove.sh --profile-id <id>`
-
-## Task Routing
-
-Pick the smallest matching path and load only the relevant references:
-
-- Control-plane layout, publication model, and profile ownership:
-  `references/control-plane-map.md`
-- Control-plane operator commands and profile-management entrypoints:
-  `references/commands.md`
-- Control-plane repository layout:
-  `references/repo-map.md`
-- Control-plane docs and profile guidance locations:
-  `references/docs-map.md`
-- Project-specific rules and repo commands:
-  `~/.agent-runtime/control-plane/profiles/<id>/README.md`
-
-## Repo Rules That Matter Most
-
-- Keep the core engine generic. Put repo-specific behavior behind a profile,
-  profile templates, or profile-scoped docs instead of hardcoding it into the
-  shared runtime.
-- Follow OpenSpec and the selected repo's local rules before implementing
-  product behavior changes.
-- Do not simplify or change approach without explicit user approval.
-- Prefer deterministic wrappers and config-driven routing over special-case
-  conditionals.
-- For any non-trivial write task, use a dedicated agent worktree or another
-  isolated clean checkout.
-- Preserve dirty retained checkouts; continue from a fresh isolated worktree
-  instead of layering more edits there.
-- Prefer canonical docs and profile-local notes over stale audits or incidental
-  markdown snapshots.
-- When updating the control plane itself, repair published copies after the
-  source change so runtime and source do not drift.
-
-## Common Operating Patterns
-
-### Analysis and Planning
-
-- Resolve the active profile first.
-- Read `~/.agent-runtime/control-plane/profiles/<id>/README.md` for repo-local context.
-- Use `references/docs-map.md` to find the canonical control-plane or
-  profile-local source instead of scanning random files.
-
-### Implementation
-
-- Keep generic scheduler/runtime changes in the shared engine.
-- Put repo-specific prompts, commands, or heuristics in the installed profile
-  directory under `~/.agent-runtime/control-plane/profiles/<id>/`.
-- Keep changes reversible and tightly scoped.
-
-### Testing
-
-- Use `references/commands.md` for control-plane checks.
-- Use the selected profile's README for repo-specific dev/test commands.
-- Re-run `tools/bin/profile-smoke.sh`, `tools/bin/check-skill-contracts.sh`,
-  dashboard tests, and targeted shell tests after meaningful control-plane
-  changes.
-
-### Publishing and Runtime Health
-
-- Use `tools/bin/flow-runtime-doctor.sh` to confirm source/runtime sync.
-- Use `tools/bin/sync-shared-agent-home.sh` after changing runtime-facing files.
-- Prefer copied published artifacts over symlink aliases.
-
-## References
-
-- `references/control-plane-map.md`
-- `references/commands.md`
-- `references/repo-map.md`
-- `references/docs-map.md`
-- `~/.agent-runtime/control-plane/profiles/<id>/README.md`

package/references/architecture.md

@@ -1,217 +0,0 @@
-# Architecture Guide
-
-This document explains how `agent-control-plane` is put together as an
-operator-facing system, not just a collection of scripts.
-
-ACP has five practical layers:
-
-1. package entrypoint and staging
-2. profile installation and publication
-3. runtime supervision and heartbeat scheduling
-4. worker execution and reconcile
-5. dashboard and operator visibility
-
-If you are reading the repo for the first time, start with the system overview
-diagram below, then jump to the flow you care about most.
-
-## System Overview
-
-```mermaid
-flowchart LR
-  User[Operator] --> CLI["npm/bin/agent-control-plane.js"]
-
-  CLI --> Init["project-init.sh"]
-  CLI --> Sync["sync-shared-agent-home.sh"]
-  CLI --> RuntimeCtl["project-runtimectl.sh"]
-  CLI --> DashboardCmd["serve-dashboard.sh"]
-
-  Init --> Profiles["Profile registry\n~/.agent-runtime/control-plane/profiles/<id>"]
-  Sync --> RuntimeHome["Runtime home\n~/.agent-runtime/runtime-home"]
-
-  RuntimeCtl --> Supervisor["project-runtime-supervisor.sh"]
-  Supervisor --> Bootstrap["project-launchd-bootstrap.sh"]
-  Bootstrap --> Heartbeat["heartbeat-safe-auto.sh"]
-  Heartbeat --> Scheduler["agent-project-heartbeat-loop"]
-
-  Scheduler --> IssueWorkers["start-issue-worker.sh"]
-  Scheduler --> PRWorkers["start-pr-review-worker.sh\nstart-pr-fix-worker.sh\nstart-pr-merge-repair-worker.sh"]
-  IssueWorkers --> Router["run-codex-task.sh"]
-  PRWorkers --> Router
-
-  Router --> Codex["agent-project-run-codex-session"]
-  Router --> Claude["agent-project-run-claude-session"]
-  Router --> OpenClaw["agent-project-run-openclaw-session"]
-  Router --> Ollama["agent-project-run-ollama-session"]
-  Router --> Pi["agent-project-run-pi-session"]
-  Router --> OpenCode["agent-project-run-opencode-session"]
-  Router --> Kilo["agent-project-run-kilo-session"]
-
-  Codex --> Artifacts["run.env / runner.env /\nresult.env / verification.jsonl"]
-  Claude --> Artifacts
-  OpenClaw --> Artifacts
-  Ollama --> Artifacts
-  Pi --> Artifacts
-  OpenCode --> Artifacts
-  Kilo --> Artifacts
-
-  Artifacts --> Reconcile["reconcile-issue-worker.sh\nreconcile-pr-worker.sh"]
-  Reconcile --> GitHub["GitHub issues / PRs / labels / comments"]
-  Reconcile --> History["runs/ + history/ + state/"]
-
-  DashboardCmd --> Snapshot["dashboard_snapshot.py"]
-  Snapshot --> Profiles
-  Snapshot --> History
-  Snapshot --> Browser["Local dashboard browser"]
-```
-
-The important architectural choice is that ACP separates:
-
-- package distribution from runtime execution
-- shared engine logic from per-profile config
-- worker execution from reconcile and GitHub side effects
-- operator visibility from the worker CLIs themselves
-
-## Install and Publication Flow
-
-This is the path from `npx agent-control-plane ...` to a usable runtime on disk.
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant CLI as agent-control-plane.js
-  participant Stage as staged shared-home
-  participant Init as project-init.sh
-  participant Scaffold as scaffold-profile.sh
-  participant Smoke as profile-smoke.sh
-  participant Adopt as profile-adopt.sh
-  participant Sync as sync-shared-agent-home.sh
-
-  User->>CLI: npx agent-control-plane init ...
-  CLI->>Stage: copy packaged skill into temp shared-home
-  CLI->>Init: forward command with staged env
-  Init->>Scaffold: write control-plane.yaml + profile docs
-  Init->>Smoke: validate profile contract
-  Init->>Adopt: create runtime roots / sync anchor repo / workspace
-  Init->>Sync: publish shared runtime into ~/.agent-runtime/runtime-home
-```
-
-Why this split exists:
-
-- the npm package is treated as a distribution artifact
-- the real runtime is copied into `~/.agent-runtime/runtime-home`
-- installed profiles live outside the package in
-  `~/.agent-runtime/control-plane/profiles/<id>`
-- upgrades are therefore explicit and repeatable instead of depending on a temp
-  `npx` cache directory
-
-## Runtime Scheduler Loop
-
-This is the heartbeat path ACP follows after `runtime start`.
-
-```mermaid
-flowchart TD
-  Start["runtime start"] --> RuntimeCtl["project-runtimectl.sh"]
-  RuntimeCtl --> Supervisor["project-runtime-supervisor.sh"]
-  Supervisor --> Bootstrap["project-launchd-bootstrap.sh"]
-  Bootstrap --> SyncCheck["sync runtime copy if needed"]
-  SyncCheck --> Heartbeat["heartbeat-safe-auto.sh"]
-  Heartbeat --> Preflight["locks / quota preflight /\nretained-worktree audit"]
-  Preflight --> SharedLoop["agent-project-heartbeat-loop"]
-
-  SharedLoop --> ReconcileCompleted["reconcile completed sessions"]
-  SharedLoop --> Capacity["compute capacity / cooldown / pending launches"]
-  SharedLoop --> Workflows["select workflow lane from issue + PR state"]
-
-  Workflows --> IssueImplementation["issue implementation"]
-  Workflows --> IssueScheduled["scheduled issue checks"]
-  Workflows --> IssueRecovery["blocked recovery"]
-  Workflows --> PRReview["PR review"]
-  Workflows --> PRFix["PR fix"]
-  Workflows --> PRMergeRepair["merge repair"]
-```
-
-Key detail: the shared scheduler owns the control logic around workers:
-
-- concurrency and heavy-worker limits
-- cooldown and retry gating
-- resident recurring and scheduled issue lanes
-- launch ordering
-- summary output and queue visibility
-
-That is why workers do not need to be "smart" about the entire system. The
-workflow around them carries a lot of the operational burden.
-
-## Worker Session Lifecycle
-
-This is the path from one chosen issue or PR to a reconciled outcome.
-
-```mermaid
-flowchart LR
-  Pick["heartbeat selects issue or PR"] --> Launch["start-issue-worker.sh\nor start-pr-*.sh"]
-  Launch --> Worktree["open or reuse managed worktree"]
-  Worktree --> Prompt["render prompt + context files"]
-  Prompt --> Route["run-codex-task.sh"]
-
-  Route --> Backend["Codex / Claude / OpenClaw adapter"]
-  Backend --> Session["backend session wrapper"]
-  Session --> Output["result.env / comments /\nverification.jsonl / runner.env"]
-
-  Output --> Reconcile["agent-project-reconcile-issue-session\nor agent-project-reconcile-pr-session"]
-  Reconcile --> Labels["update labels / retry state /\nresident metadata / cooldown"]
-  Reconcile --> Publish["comment on issue, open PR,\nor leave blocked report"]
-  Reconcile --> Archive["archive run into history root"]
-```
-
-The contract here is deliberate:
-
-- worker backends focus on producing work and result artifacts
-- reconcile scripts own the final interpretation and GitHub-facing outcome
-- resident metadata and history are updated by the host workflow, not by the
-  worker trying to infer the entire system state
-
-## Dashboard Snapshot Pipeline
-
-The dashboard is a read-only window into ACP state. It does not own scheduling.
-
-```mermaid
-flowchart LR
-  Browser["browser"] --> Server["tools/dashboard/server.py"]
-  Server --> API["GET /api/snapshot.json"]
-  API --> Snapshot["dashboard_snapshot.py"]
-
-  Snapshot --> Registry["profile registry"]
-  Snapshot --> Config["render-flow-config.sh"]
-  Snapshot --> WorkerStatus["agent-project-worker-status"]
-  Snapshot --> Runs["runs/ history/ state/"]
-
-  Registry --> JSON["snapshot payload"]
-  Config --> JSON
-  WorkerStatus --> JSON
-  Runs --> JSON
-
-  JSON --> UI["dashboard app.js + index.html"]
-```
-
-This means the dashboard reflects the current state of:
-
-- installed profiles
-- live and recent runs
-- resident controller metadata
-- provider cooldowns
-- scheduled issue state
-- runtime process status
-
-without introducing a second control path that could drift away from the real
-scheduler state.
-
-## Reading Order
-
-If you want the shortest path through the architecture:
-
-1. [System Overview](#system-overview)
-2. [Runtime Scheduler Loop](#runtime-scheduler-loop)
-3. [Worker Session Lifecycle](#worker-session-lifecycle)
-4. [Dashboard Snapshot Pipeline](#dashboard-snapshot-pipeline)
-
-If you are changing packaging or onboarding, also read
-[Install and Publication Flow](#install-and-publication-flow).