agent-control-plane 0.1.6 → 0.1.8

package/hooks/issue-reconcile-hooks.sh

@@ -7,6 +7,7 @@ source "${HOOK_SCRIPT_DIR}/../tools/bin/flow-config-lib.sh"
 
 FLOW_SKILL_DIR="$(cd "${HOOK_SCRIPT_DIR}/.." && pwd)"
 CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+PROFILE_ID="$(flow_resolve_adapter_id "${CONFIG_YAML}")"
 ADAPTER_BIN_DIR="${FLOW_SKILL_DIR}/bin"
 FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
 REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
@@ -15,6 +16,12 @@ STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
 RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
 BLOCKED_RECOVERY_STATE_DIR="${STATE_ROOT}/blocked-recovery-issues"
 
+issue_kick_scheduler() {
+  ACP_PROJECT_ID="${PROFILE_ID}" \
+  AGENT_PROJECT_ID="${PROFILE_ID}" \
+    "${FLOW_TOOLS_DIR}/kick-scheduler.sh" "${1:-2}" >/dev/null || true
+}
+
 issue_clear_blocked_recovery_state() {
   rm -f "${BLOCKED_RECOVERY_STATE_DIR}/${ISSUE_ID}.env" 2>/dev/null || true
 }
@@ -194,7 +201,7 @@ issue_after_pr_created() {
   if [[ "$(jq -r '.eligibleForAutoMerge' <<<"$risk_json")" == "true" ]]; then
     bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "${REPO_SLUG}" --number "$pr_number" --add agent-automerge >/dev/null || true
   fi
-  "${FLOW_TOOLS_DIR}/kick-scheduler.sh" 5 >/dev/null || true
+  issue_kick_scheduler 5
 }
 
 issue_after_reconciled() {
@@ -213,5 +220,5 @@ issue_after_reconciled() {
     esac
   fi
 
-  "${FLOW_TOOLS_DIR}/kick-scheduler.sh" 2 >/dev/null || true
+  issue_kick_scheduler 2
 }

package/hooks/pr-reconcile-hooks.sh

@@ -7,6 +7,7 @@ source "${HOOK_SCRIPT_DIR}/../tools/bin/flow-config-lib.sh"
 
 FLOW_SKILL_DIR="$(cd "${HOOK_SCRIPT_DIR}/.." && pwd)"
 CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+PROFILE_ID="$(flow_resolve_adapter_id "${CONFIG_YAML}")"
 ADAPTER_BIN_DIR="${FLOW_SKILL_DIR}/bin"
 FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
 RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
@@ -19,6 +20,12 @@ ISSUE_SESSION_PREFIX="$(flow_resolve_issue_session_prefix "${CONFIG_YAML}")"
 PR_WORKTREE_BRANCH_PREFIX="$(flow_resolve_pr_worktree_branch_prefix "${CONFIG_YAML}")"
 PR_LANE_OVERRIDE_DIR="${STATE_ROOT}/pr-lane-overrides"
 
+pr_kick_scheduler() {
+  ACP_PROJECT_ID="${PROFILE_ID}" \
+  AGENT_PROJECT_ID="${PROFILE_ID}" \
+    "${FLOW_TOOLS_DIR}/kick-scheduler.sh" "${1:-2}" >/dev/null || true
+}
+
 pr_best_effort_update_labels() {
   bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" "$@" >/dev/null 2>&1 || true
 }
@@ -131,14 +138,14 @@ pr_after_merged() {
   pr_clear_lane_override "$pr_number"
   pr_best_effort_update_labels --repo-slug "${REPO_SLUG}" --number "$pr_number" --remove agent-running --remove agent-automerge --remove agent-repair-queued --remove agent-fix-needed --remove agent-manual-fix-override --remove agent-ci-refresh --remove agent-ci-bypassed --remove agent-double-check-1/2 --remove agent-double-check-2/2 --remove agent-human-review --remove agent-human-approved --remove agent-blocked --remove agent-handoff --remove agent-exclusive
   pr_refresh_linked_issue_checklist "$pr_number"
-  "${FLOW_TOOLS_DIR}/kick-scheduler.sh" 5 >/dev/null || true
+  pr_kick_scheduler 5
 }
 
 pr_after_closed() {
   local pr_number="${1:?pr number required}"
   pr_clear_lane_override "$pr_number"
   pr_best_effort_update_labels --repo-slug "${REPO_SLUG}" --number "$pr_number" --remove agent-running --remove agent-automerge --remove agent-repair-queued --remove agent-fix-needed --remove agent-manual-fix-override --remove agent-ci-refresh --remove agent-ci-bypassed --remove agent-double-check-1/2 --remove agent-double-check-2/2 --remove agent-human-review --remove agent-human-approved --remove agent-blocked --remove agent-handoff --remove agent-exclusive
-  "${FLOW_TOOLS_DIR}/kick-scheduler.sh" 5 >/dev/null || true
+  pr_kick_scheduler 5
 }
 
 pr_automerge_allowed() {
@@ -189,7 +196,7 @@ pr_after_double_check_advanced() {
   pr_set_lane_override "$pr_number" "double-check-${next_stage}"
   pr_best_effort_update_labels --repo-slug "${REPO_SLUG}" --number "$pr_number" --remove agent-running --remove agent-automerge --remove agent-repair-queued --remove agent-fix-needed --remove agent-manual-fix-override --remove agent-ci-refresh --remove agent-human-review --remove agent-human-approved --remove agent-double-check-1/2 --remove agent-double-check-2/2 --add "$next_label"
   pr_best_effort_sync_pr_labels "$pr_number"
-  "${FLOW_TOOLS_DIR}/kick-scheduler.sh" 5 >/dev/null || true
+  pr_kick_scheduler 5
 }
 
 pr_after_updated_branch() {
@@ -221,5 +228,5 @@ pr_after_failed() {
 }
 
 pr_after_reconciled() {
-  "${FLOW_TOOLS_DIR}/kick-scheduler.sh" 2 >/dev/null || true
+  pr_kick_scheduler 2
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {
@@ -24,6 +24,7 @@
     "bin",
     "hooks",
     "npm/bin",
+    "references",
     "tools/bin",
     "tools/dashboard/app.js",
     "tools/dashboard/dashboard_snapshot.py",
@@ -39,7 +40,7 @@
   "scripts": {
     "doctor": "node ./npm/bin/agent-control-plane.js doctor",
     "smoke": "node ./npm/bin/agent-control-plane.js smoke",
-    "test": "bash tools/tests/test-agent-control-plane-npm-cli.sh && bash tools/tests/test-profile-adopt-skip-anchor-sync-creates-agent-repo-root.sh && bash tools/tests/test-vendored-codex-quota-claude-oauth-only.sh"
+    "test": "bash tools/tests/test-agent-control-plane-npm-cli.sh && bash tools/tests/test-agent-project-detached-launch-stable-cwd.sh && bash tools/tests/test-agent-project-claude-session-wrapper-reaps-child-on-term.sh && bash tools/tests/test-agent-project-claude-session-wrapper-does-not-retry-provider-quota.sh && bash tools/tests/test-agent-project-reconcile-issue-provider-quota-schedules-provider-cooldown.sh && bash tools/tests/test-pr-reconcile-hooks-refreshes-recurring-issue-checklist.sh && bash tools/tests/test-issue-reconcile-hooks-kick-scheduler-uses-profile.sh && bash tools/tests/test-profile-adopt-skip-anchor-sync-creates-agent-repo-root.sh && bash tools/tests/test-vendored-codex-quota-claude-oauth-only.sh && bash tools/tests/test-package-smoke-command.sh"
   },
   "keywords": [
     "agents",

package/references/architecture.md

@@ -0,0 +1,209 @@
+# 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"]
+
+  Codex --> Artifacts["run.env / runner.env /\nresult.env / verification.jsonl"]
+  Claude --> Artifacts
+  OpenClaw --> 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).

package/references/commands.md

@@ -0,0 +1,127 @@
+# Command Map
+
+Run commands from the current isolated checkout for the task.
+
+Profile-specific repo roots and repo-local dev/test commands belong in
+`~/.agent-runtime/control-plane/profiles/<id>/README.md`. Resolve the active
+profile first, then use the selected profile's notes for product-repo commands.
+
+## Profile Resolution
+
+```bash
+bash tools/bin/workflow-catalog.sh profiles
+tools/bin/workflow-catalog.sh context
+bash tools/bin/profile-activate.sh --profile-id <id>
+ACP_PROJECT_ID=<id> bash tools/bin/render-flow-config.sh
+```
+
+Use `render-flow-config.sh` when you need the effective repo root, worktree
+root, runtime root, worker backend, or profile-specific script bindings.
+When multiple available profiles exist, set `ACP_PROJECT_ID=<id>` first or use
+`profile-activate.sh --profile-id <id>` before running manual operator
+commands.
+
+## Dependency bootstrap
+
+Run dependency bootstrap only from the clean automation baseline for the
+selected profile when you explicitly need to refresh shared dependencies. Do not
+repair shared `node_modules` from inside a worker worktree.
+
+For control-plane changes in this repo, prefer focused shell tests over broad
+bootstrap unless the task actually changes dependency behavior.
+
+## Control-Plane Verification
+
+```bash
+bash tools/bin/check-skill-contracts.sh
+bash tools/bin/flow-runtime-doctor.sh
+bash tools/bin/profile-smoke.sh
+bash tools/bin/test-smoke.sh
+bash tools/tests/test-project-init.sh
+bash tools/tests/test-project-init-force-and-skip-sync.sh
+bash tools/tests/test-project-remove.sh
+bash tools/tests/test-project-runtimectl.sh
+bash tools/tests/test-project-runtimectl-missing-profile.sh
+bash tools/tests/test-project-runtimectl-stop-cancels-pending-kick.sh
+bash tools/tests/test-project-runtimectl-start-falls-back-to-bootstrap.sh
+bash tools/tests/test-project-runtimectl-status-supervisor-running.sh
+bash tools/tests/test-project-launchd-bootstrap.sh
+bash tools/tests/test-install-project-launchd.sh
+bash tools/tests/test-uninstall-project-launchd.sh
+bash tools/tests/test-project-runtimectl-launchd.sh
+bash tools/tests/test-dashboard-launchd-bootstrap.sh
+bash tools/tests/test-install-dashboard-launchd.sh
+bash tools/tests/test-render-dashboard-snapshot.sh
+bash tools/tests/test-serve-dashboard.sh
+bash tools/tests/test-control-plane-dashboard-runtime-smoke.sh
+bash tools/tests/test-workflow-catalog.sh
+bash tools/tests/test-render-flow-config.sh
+```
+
+Add or run targeted tests in `tools/tests/` for the changed surface.
+
+## Flow maintenance
+
+```bash
+tools/bin/flow-runtime-doctor.sh
+tools/bin/workflow-catalog.sh list
+tools/bin/workflow-catalog.sh show pr-review
+tools/bin/workflow-catalog.sh profiles
+tools/bin/workflow-catalog.sh context
+tools/bin/profile-activate.sh --profile-id <id>
+tools/bin/project-init.sh --profile-id <id> --repo-slug <owner/repo>
+tools/bin/render-flow-config.sh
+tools/bin/scaffold-profile.sh --profile-id <id> --repo-slug <owner/repo>
+tools/bin/profile-smoke.sh
+tools/bin/test-smoke.sh
+tools/bin/profile-adopt.sh --profile-id <id>
+tools/bin/project-runtimectl.sh status --profile-id <id>
+tools/bin/project-runtimectl.sh stop --profile-id <id>
+tools/bin/project-runtimectl.sh start --profile-id <id>
+tools/bin/project-runtimectl.sh restart --profile-id <id>
+tools/bin/install-project-launchd.sh --profile-id <id>
+tools/bin/uninstall-project-launchd.sh --profile-id <id>
+tools/bin/project-remove.sh --profile-id <id>
+tools/bin/project-remove.sh --profile-id <id> --purge-paths
+tools/bin/sync-shared-agent-home.sh
+python3 tools/bin/render-dashboard-snapshot.py --pretty
+bash tools/bin/serve-dashboard.sh --host 127.0.0.1 --port 8765
+bash tools/bin/install-dashboard-launchd.sh --host 127.0.0.1 --port 8765
+```
+
+Installed profile prompts should live under
+`~/.agent-runtime/control-plane/profiles/<id>/templates/`; generic fallback
+prompts live under `tools/templates/`.
+
+## Dashboard
+
+```bash
+python3 tools/bin/render-dashboard-snapshot.py --pretty
+bash tools/bin/serve-dashboard.sh --host 127.0.0.1 --port 8765
+bash tools/bin/install-dashboard-launchd.sh --host 127.0.0.1 --port 8765
+```
+
+Use the snapshot command for CLI/debug output and the HTTP server for the live
+dashboard at `http://127.0.0.1:8765`. Use the LaunchAgent installer when you
+want the dashboard to come back automatically after macOS restart/login.
+
+## Project Autostart
+
+```bash
+bash tools/bin/install-project-launchd.sh --profile-id <id>
+bash tools/bin/uninstall-project-launchd.sh --profile-id <id>
+```
+
+Use the project installer when one profile should come back automatically after
+macOS restart/login. `project-runtimectl.sh start|stop|status` will detect that
+per-project LaunchAgent automatically once it is installed.
+
+## Repo-Specific Commands
+
+After choosing a profile, read `~/.agent-runtime/control-plane/profiles/<id>/README.md` for:
+
+- clean automation baseline and retained checkout roots
+- repo-local startup docs such as `AGENTS.md` and OpenSpec paths
+- app/package-specific dev commands
+- isolated smoke and release-rehearsal commands
+- project-specific operator runbooks

package/references/control-plane-map.md

@@ -0,0 +1,120 @@
+# Agent Control Plane Map
+
+This repository is the shared `agent-control-plane` package. It provides a
+generic engine that can host multiple installed profiles, each with its own repo
+roots, labels, worker preferences, prompts, and project-specific guardrails.
+
+## What Lives Here
+
+- `SKILL.md`
+  Canonical operating manual for the shared control plane.
+- `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`
+  Canonical installed project profile for repo paths, queue labels, limits,
+  and script bindings.
+- `~/.agent-runtime/control-plane/profiles/<id>/README.md`
+  Repo-specific operator notes, startup docs, and command references for the
+  selected profile.
+- `~/.agent-runtime/control-plane/profiles/<id>/templates/`
+  Optional installed profile-specific prompt overrides.
+- `assets/workflow-catalog.json`
+  Declarative catalog of the workflow lanes this control plane exposes.
+- `bin/`
+  Queue, label, and risk logic shared by installed profiles.
+- `hooks/`
+  Heartbeat and reconcile hooks shared by installed profiles.
+- `tools/bin/flow-runtime-doctor.sh`
+  Reports whether the published source copy and runtime-home copy are in sync.
+- `tools/bin/workflow-catalog.sh`
+  Lists workflows, shows workflow details, or prints available profile ids.
+- `tools/bin/render-flow-config.sh`
+  Prints the effective operator/runtime config after environment overrides.
+- `tools/bin/run-codex-task.sh`
+  Routes the shared worker contract into the backend-specific session wrapper.
+- `tools/bin/agent-project-run-codex-session`
+  Launches Codex-backed worker sessions.
+- `tools/bin/agent-project-run-claude-session`
+  Launches Claude-backed worker sessions.
+- `tools/bin/agent-project-run-openclaw-session`
+  Launches OpenClaw-backed worker sessions.
+- `tools/bin/agent-project-run-opencode-session`
+  Placeholder adapter stub for the planned `opencode` backend.
+- `tools/bin/agent-project-run-kilo-session`
+  Placeholder adapter stub for the planned `kilo` backend.
+- `tools/bin/project-init.sh`
+  Runs scaffold + smoke + adopt + runtime sync for one installed profile.
+- `tools/bin/scaffold-profile.sh`
+  Scaffolds a new installed profile, profile notes, and prompt templates in the
+  local profile registry.
+- `tools/bin/project-runtimectl.sh`
+  Provides `status`, `start`, `stop`, and `restart` for one installed profile.
+- `tools/bin/project-launchd-bootstrap.sh`
+  Syncs the runtime copy and runs one profile-scoped heartbeat pass in a
+  launchd-safe foreground process for the runtime supervisor.
+- `tools/bin/install-project-launchd.sh`
+  Installs a per-user LaunchAgent for one installed profile so its runtime can
+  come back automatically after reboot/login.
+- `tools/bin/uninstall-project-launchd.sh`
+  Removes the per-project LaunchAgent wrapper and plist for one installed
+  profile.
+- `tools/bin/project-remove.sh`
+  Removes one installed profile plus ACP-owned runtime state, with optional
+  purge of ACP-managed repo/worktree/workspace paths.
+- `tools/bin/profile-smoke.sh`
+  Validates available profiles and catches session/branch prefix collisions
+  before scheduler use.
+- `tools/bin/test-smoke.sh`
+  Runs the main shared-package smoke gates in one operator-facing command.
+- `tools/bin/render-dashboard-snapshot.py`
+  Emits a JSON snapshot of active runs, resident controllers, cooldown state,
+  queue depth, and scheduled issues across installed profiles.
+- `tools/bin/serve-dashboard.sh`
+  Serves the live worker dashboard and `/api/snapshot.json` endpoint for local
+  browser-based monitoring.
+- `tools/bin/dashboard-launchd-bootstrap.sh`
+  Syncs the runtime copy and launches the dashboard server in a launchd-safe
+  foreground process.
+- `tools/bin/install-dashboard-launchd.sh`
+  Installs and bootstraps a per-user LaunchAgent so the dashboard returns after
+  reboot/login.
+- `tools/bin/profile-adopt.sh`
+  Creates runtime roots, installs the selected profile into the local profile
+  registry when needed, and syncs the anchor repo plus VS Code workspace for
+  live scheduler adoption.
+- `references/`
+  Control-plane docs, operator commands, and repository maps.
+
+## What Does Not Live Here
+
+- Repo-specific product code.
+- Local scheduler bootstrap and operator docs that belong to a particular
+  workstation. Those now live under:
+  `~/.agent-runtime/control-plane/workspace`
+
+## Vendored Runtime
+
+- Runtime engines are resolved from the current skill root first, then the
+  shared/runtime canonical copies when present, while active project profiles
+  are resolved from `~/.agent-runtime/control-plane/profiles/`.
+- Project-specific instructions should be loaded from the active profile's
+  `README.md` and templates instead of being hardcoded into the shared engine.
+
+## Published Artifacts
+
+- Source canonical package copy:
+  `$SHARED_AGENT_HOME/skills/openclaw/agent-control-plane`
+- Runtime canonical package copy:
+  `~/.agent-runtime/runtime-home/skills/openclaw/agent-control-plane`
+
+Published artifacts are rebuilt by `tools/bin/sync-shared-agent-home.sh` as
+concrete copied files, not symlink aliases. Canonical profile configs now live
+outside the repo in `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`.
+
+## Operational Rule
+
+When updating the control plane:
+
+1. Change the generic engine in this repo or the selected installed profile in the external registry.
+2. Keep workstation wrappers thin.
+3. Repair shared/runtime published copies with `tools/bin/sync-shared-agent-home.sh`.
+4. Prefer explicit profile docs and copied artifacts over hidden defaults and
+   symlink aliases.

package/references/docs-map.md

@@ -0,0 +1,73 @@
+# Docs Map
+
+Canonical documentation sources inside `agent-control-plane`:
+
+## Shared Control-Plane Docs
+
+- `SKILL.md`
+  Shared operating rules and startup sequence.
+- `README.md`
+  Public-facing install, usage, funding, contributing, and security entrypoint.
+- `CHANGELOG.md`
+  Public release history for the package and repository.
+- `ROADMAP.md`
+  Public product and backend-support roadmap, including current and planned
+  worker integrations.
+- `references/architecture.md`
+  Architecture walkthrough with system, runtime, worker, and dashboard diagrams.
+- `CONTRIBUTING.md`
+  Contributor workflow, legal model, and maintainer expectations.
+- `CLA.md`
+  Contributor license agreement used for incoming changes.
+- `CODE_OF_CONDUCT.md`
+  Community behavior and moderation expectations.
+- `SECURITY.md`
+  Security reporting path and disclosure expectations.
+- `references/control-plane-map.md`
+  Ownership map for profiles, scripts, publication copies, and operator tools.
+- `references/commands.md`
+  Control-plane operator commands and profile-management entrypoints.
+- `references/release-checklist.md`
+  Maintainer release checklist for public package publishing.
+- `.github/release-template.md`
+  Reusable markdown template for GitHub release notes.
+- `.github/workflows/ci.yml`
+  Public CI workflow used for the README status badge.
+- `.github/workflows/publish.yml`
+  Trusted npm publishing workflow used for tag-driven releases with provenance.
+- `references/repo-map.md`
+  Layout of the control-plane repository itself.
+
+## Profile-Scoped Docs
+
+- `~/.agent-runtime/control-plane/profiles/<id>/README.md`
+  Canonical repo-specific startup docs, repo roots, command map, and
+  high-risk notes.
+- `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`
+  Canonical machine-readable installed profile config.
+- `~/.agent-runtime/control-plane/profiles/<id>/templates/*.md`
+  Canonical prompt overrides for issue, PR fix, PR review, or scheduled issue flows.
+
+## Runtime and Publication Docs
+
+- `tools/bin/flow-runtime-doctor.sh`
+  Sync health for source and runtime copies.
+- `tools/bin/profile-smoke.sh`
+  Installed-profile validation before scheduler use.
+- `tools/bin/profile-adopt.sh`
+  Local workstation adoption helper.
+- `tools/bin/sync-shared-agent-home.sh`
+  Publication repair for shared/runtime copies.
+- `tools/bin/render-dashboard-demo-media.sh`
+  Regenerates the README dashboard screenshot and animated walkthrough from a
+  real local demo fixture.
+- `tools/bin/render-architecture-infographics.sh`
+  Regenerates the architecture infographic PNGs and PDF deck from the local
+  HTML source in `tools/architecture/`.
+
+## Rule of Thumb
+
+If a piece of guidance is specific to one repo, keep it in
+`~/.agent-runtime/control-plane/profiles/<id>/README.md` or
+`~/.agent-runtime/control-plane/profiles/<id>/templates/` instead of the shared
+control-plane docs.