agent-control-plane 0.1.0

package/SKILL.md

@@ -0,0 +1,149 @@
+---
+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 launchers in `tools/bin/render-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/assets/workflow-catalog.json

@@ -0,0 +1,57 @@
+{
+  "version": 1,
+  "control_plane": "agent-control-plane",
+  "default_profile": null,
+  "profile_selection": "explicit",
+  "workflows": [
+    {
+      "id": "issue-implementation",
+      "kind": "issue",
+      "trigger": "Open issue with agent-ready and without agent-running/agent-blocked",
+      "entrypoint": "tools/bin/start-issue-worker.sh",
+      "summary": "Primary implementation loop for focused issues that should end in a PR or a blocked report."
+    },
+    {
+      "id": "issue-blocked-recovery",
+      "kind": "issue",
+      "trigger": "Open issue with agent-blocked plus retry-state reason after cooldown",
+      "entrypoint": "tools/bin/start-issue-worker.sh",
+      "summary": "Retries previously blocked issue sessions in a controlled lane without mixing them with fresh intake."
+    },
+    {
+      "id": "issue-scheduled-check",
+      "kind": "issue",
+      "trigger": "Issue body contains Agent schedule/ Schedule/ Cadence metadata",
+      "entrypoint": "tools/bin/start-issue-worker.sh",
+      "summary": "Runs recurring health, checks, or smoke-style verification and updates status labels instead of shipping product changes."
+    },
+    {
+      "id": "pr-review",
+      "kind": "pull_request",
+      "trigger": "Agent-managed PR becomes eligible for double-check, human-review, or automerge decisioning",
+      "entrypoint": "tools/bin/start-pr-review-worker.sh",
+      "summary": "Evaluates final-review state and advances merge, double-check, or human-review lanes."
+    },
+    {
+      "id": "pr-fix",
+      "kind": "pull_request",
+      "trigger": "Agent-managed PR has actionable review feedback, host blocker, broad scope, or failing branch-local checks",
+      "entrypoint": "tools/bin/start-pr-fix-worker.sh",
+      "summary": "Launches a repair pass for PRs that still need code changes on the current head."
+    },
+    {
+      "id": "pr-merge-repair",
+      "kind": "pull_request",
+      "trigger": "Agent-managed PR has mergeStateStatus DIRTY",
+      "entrypoint": "tools/bin/start-pr-merge-repair-worker.sh",
+      "summary": "Handles merge-only repair when the PR needs branch reconciliation rather than a normal review fix."
+    },
+    {
+      "id": "follow-up-splitting",
+      "kind": "issue",
+      "trigger": "Issue implementation determines scope should be split into narrower follow-up issues",
+      "entrypoint": "tools/bin/create-follow-up-issue.sh",
+      "summary": "Creates focused follow-up issues and optionally closes the umbrella issue as superseded."
+    }
+  ]
+}

package/bin/audit-issue-routing.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/../tools/bin/flow-config-lib.sh"
+
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+AGENT_PR_PREFIXES_JSON="$(flow_managed_pr_prefixes_json "${CONFIG_YAML}")"
+AGENT_PR_ISSUE_CAPTURE_REGEX="$(flow_managed_issue_branch_regex "${CONFIG_YAML}")"
+MIN_AGE_MINUTES="${1:-30}"
+
+open_agent_pr_issue_ids="$(
+  gh pr list -R "$REPO_SLUG" --state open --limit 100 --json headRefName,body,labels,comments \
+    | jq --argjson agentPrPrefixes "${AGENT_PR_PREFIXES_JSON}" --arg branchIssueRegex "${AGENT_PR_ISSUE_CAPTURE_REGEX}" '
+        map(
+          . as $pr
+          | select(
+              any($agentPrPrefixes[]; (($pr.headRefName // "") | startswith(.)))
+              or any(($pr.labels // [])[]?; .name == "agent-handoff")
+              or any(($pr.comments // [])[]?; ((.body // "") | test("^## PR (final review blocker|repair worker summary|repair summary|repair update)"; "i")))
+            )
+          | [
+              (
+                $pr.headRefName
+                | capture($branchIssueRegex)?
+                | .id
+              ),
+              (
+                ($pr.body // "")
+                | capture("(?i)\\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s+#(?<id>[0-9]+)\\b")?
+                | .id
+              )
+            ]
+          | .[]
+          | select(. != null and . != "")
+        )
+        | unique
+      '
+)"
+
+gh issue list -R "$REPO_SLUG" --state open --limit 100 --json number,title,createdAt,updatedAt,labels \
+  | jq -r --argjson openAgentPrIssueIds "$open_agent_pr_issue_ids" --argjson minAgeMinutes "$MIN_AGE_MINUTES" '
+      def label_names: [.labels[]?.name];
+      def age_minutes:
+        ((now - ((.createdAt | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601))) / 60);
+      def has_open_agent_pr:
+        ((.number | tostring) as $issueId | ($openAgentPrIssueIds | index($issueId)) != null);
+      map(
+        . + {
+          reason:
+            (if any(label_names[]?; . == "agent-running") and (has_open_agent_pr | not) then
+              "stale-agent-running"
+            elif any(label_names[]?; . == "agent-blocked") then
+              "blocked-manual-review"
+            else
+              ""
+            end)
+        }
+      )
+      | map(select(.reason != "" and (age_minutes >= $minAgeMinutes)))
+      | sort_by(.createdAt, .number)
+      | .[]
+      | [
+          (.number | tostring),
+          .reason,
+          .createdAt,
+          .updatedAt,
+          (label_names | join(",")),
+          .title
+        ]
+      | @tsv
+    '

package/bin/issue-resource-class.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/../tools/bin/flow-config-lib.sh"
+
+ISSUE_ID="${1:?usage: issue-resource-class.sh ISSUE_ID}"
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+
+ISSUE_JSON="$(gh issue view "$ISSUE_ID" -R "$REPO_SLUG" --json number,title,body,labels)"
+
+CLASS_OUT="$(
+  ISSUE_JSON="$ISSUE_JSON" python3 <<'PY'
+import json
+import os
+import re
+
+issue = json.loads(os.environ["ISSUE_JSON"])
+labels = {str(label.get("name", "")).strip().lower() for label in issue.get("labels", [])}
+title = str(issue.get("title", "") or "")
+body = str(issue.get("body", "") or "")
+
+explicit_e2e_labels = {
+    "agent-e2e-heavy",
+    "e2e",
+    "playwright",
+    "detox",
+    "maestro",
+}
+title_pattern = re.compile(
+    r"(^|[^a-z0-9])(e2e|end-to-end|end to end|playwright|detox|maestro)([^a-z0-9]|$)",
+    re.IGNORECASE,
+)
+body_pattern = re.compile(
+    r"(^|[^a-z0-9])("
+    r"playwright|detox|maestro|"
+    r"e2e([ -]+(test|tests|smoke|suite|run|runs|flaky|flake|spec))|"
+    r"end-to-end([ -]+(test|tests|smoke|suite|run|runs|flaky|flake|spec))"
+    r")([^a-z0-9]|$)",
+    re.IGNORECASE,
+)
+
+is_e2e = (
+    bool(labels.intersection(explicit_e2e_labels))
+    or bool(title_pattern.search(title))
+    or bool(body_pattern.search(body))
+)
+issue_class = "e2e-heavy" if is_e2e else "standard"
+
+print(f"CLASS={issue_class}")
+print(f"IS_E2E={'yes' if is_e2e else 'no'}")
+PY
+)"
+
+printf 'ISSUE_ID=%s\n' "$ISSUE_ID"
+printf '%s\n' "$CLASS_OUT"

package/bin/label-follow-up-issues.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SESSION="${1:?usage: label-follow-up-issues.sh SESSION}"
+ADAPTER_BIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FLOW_SKILL_DIR="$(cd "${ADAPTER_BIN_DIR}/.." && pwd)"
+FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
+# shellcheck source=/dev/null
+source "${FLOW_TOOLS_DIR}/flow-config-lib.sh"
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+flow_export_execution_env "${CONFIG_YAML}"
+flow_export_project_env_aliases
+REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
+RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
+HISTORY_ROOT="$(flow_resolve_history_root "${CONFIG_YAML}")"
+
+find_archived_session_dir() {
+  local root="${1:-}"
+  local target_session="${2:-}"
+  [[ -n "$root" && -d "$root" && -n "$target_session" ]] || return 1
+
+  find "$root" -mindepth 1 -maxdepth 1 -type d -name "${target_session}-*" ! -name "${target_session}-stale-*" 2>/dev/null \
+    | sort -r \
+    | head -n 1
+}
+
+status_out="$(
+  bash "${FLOW_TOOLS_DIR}/agent-project-worker-status" \
+    --runs-root "$RUNS_ROOT" \
+    --session "$SESSION"
+)"
+meta_file="$(awk -F= '/^META_FILE=/{print $2}' <<<"$status_out")"
+if [[ -z "$meta_file" || ! -f "$meta_file" ]]; then
+  archived_run_dir="$(find_archived_session_dir "$HISTORY_ROOT" "$SESSION" || true)"
+  if [[ -n "$archived_run_dir" && -f "${archived_run_dir}/run.env" ]]; then
+    meta_file="${archived_run_dir}/run.env"
+  fi
+fi
+if [[ -z "$meta_file" || ! -f "$meta_file" ]]; then
+  echo "missing metadata for session $SESSION" >&2
+  exit 1
+fi
+
+set -a
+# shellcheck source=/dev/null
+source "$meta_file"
+set +a
+
+if [[ -z "${ISSUE_ID:-}" ]]; then
+  echo "session $SESSION is missing ISSUE_ID" >&2
+  exit 1
+fi
+if [[ -z "${STARTED_AT:-}" ]]; then
+  echo "session $SESSION is missing STARTED_AT" >&2
+  exit 1
+fi
+
+actor_login="${GITHUB_ACTOR:-$(gh api user --jq .login)}"
+
+issue_numbers=()
+while IFS= read -r number; do
+  [[ -n "$number" ]] || continue
+  issue_numbers+=("$number")
+done < <(
+  flow_github_api_repo "${REPO_SLUG}" "issues/${ISSUE_ID}/comments?per_page=100" --paginate --slurp 2>/dev/null \
+    | jq -r --arg actor "$actor_login" --arg started "$STARTED_AT" '
+        .[]?
+        | if type == "array" then .[] else . end
+        | select(.user.login == $actor)
+        | select(.created_at >= $started)
+        | .body // ""
+      ' \
+    | rg -o '#[0-9]+' \
+    | tr -d '#' \
+    | sort -n \
+    | uniq
+)
+
+count=0
+if [[ ${#issue_numbers[@]} -eq 0 ]]; then
+  printf 'COUNT=%s\n' "$count"
+  exit 0
+fi
+
+for number in "${issue_numbers[@]}"; do
+  [[ "$number" == "$ISSUE_ID" ]] && continue
+
+  issue_json="$(flow_github_issue_view_json "${REPO_SLUG}" "${number}" 2>/dev/null || true)"
+  [[ -z "$issue_json" ]] && continue
+
+  if jq -e 'has("pull_request")' >/dev/null <<<"$issue_json"; then
+    continue
+  fi
+
+  state="$(jq -r '.state // "" | ascii_downcase' <<<"$issue_json")"
+  [[ "$state" == "open" ]] || continue
+
+  if jq -e 'any(.labels[]?; .name == "agent-running" or .name == "agent-blocked")' >/dev/null <<<"$issue_json"; then
+    continue
+  fi
+
+  class_out="$("${ADAPTER_BIN_DIR}/issue-resource-class.sh" "$number")"
+  is_e2e="$(awk -F= '/^IS_E2E=/{print $2}' <<<"$class_out")"
+
+  if [[ "$is_e2e" == "yes" ]]; then
+    bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$number" --add agent-e2e-heavy >/dev/null
+  fi
+
+  printf 'LABELED=%s\n' "$number"
+  count=$((count + 1))
+done
+
+printf 'COUNT=%s\n' "$count"