agent-control-plane 0.1.13 → 0.1.16

package/SKILL.md

@@ -22,7 +22,7 @@ external profile registry, not inside this repository.
 - 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`
+- 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`

package/hooks/heartbeat-hooks.sh

@@ -95,6 +95,7 @@ heartbeat_open_agent_pr_issue_ids() {
   local pr_issue_ids_json=""
   pr_issue_ids_json="$(
     flow_github_pr_list_json "$REPO_SLUG" open 100 \
+      2>/dev/null \
       | jq --argjson agentPrPrefixes "${AGENT_PR_PREFIXES_JSON}" --arg handoffLabel "${AGENT_PR_HANDOFF_LABEL}" --arg branchIssueRegex "${AGENT_PR_ISSUE_CAPTURE_REGEX}" '
         map(
           . as $pr
@@ -119,7 +120,7 @@ heartbeat_open_agent_pr_issue_ids() {
           | select(. != null and . != "")
         )
         | unique
-      '
+      ' 2>/dev/null || true
   )"
 
   if [[ -z "${pr_issue_ids_json:-}" ]]; then
@@ -136,6 +137,7 @@ heartbeat_list_ready_issue_ids() {
 
   ready_issue_rows="$(
     flow_github_issue_list_json "$REPO_SLUG" open 100 \
+    2>/dev/null \
     | jq -r --argjson openAgentPrIssueIds "${open_agent_pr_issue_ids}" '
         map(select(
           (any(.labels[]?; .name == "agent-running") | not)
@@ -145,7 +147,7 @@ heartbeat_list_ready_issue_ids() {
         | .[]
         | [.number, (any(.labels[]?; .name == "agent-blocked"))]
         | @tsv
-      '
+      ' 2>/dev/null || true
   )"
 
   while IFS=$'\t' read -r issue_id is_blocked; do
@@ -170,6 +172,7 @@ heartbeat_list_blocked_recovery_issue_ids() {
 
   blocked_issue_rows="$(
     flow_github_issue_list_json "$REPO_SLUG" open 100 \
+    2>/dev/null \
     | jq -r --argjson openAgentPrIssueIds "${open_agent_pr_issue_ids}" '
         map(select(
           any(.labels[]?; .name == "agent-blocked")
@@ -178,7 +181,7 @@ heartbeat_list_blocked_recovery_issue_ids() {
         ))
         | sort_by(.createdAt, .number)
         | .[].number
-      '
+      ' 2>/dev/null || true
   )"
 
   while IFS= read -r issue_id; do
@@ -268,6 +271,7 @@ heartbeat_list_exclusive_issue_ids() {
   open_agent_pr_issue_ids="$(heartbeat_open_agent_pr_issue_ids)"
 
   flow_github_issue_list_json "$REPO_SLUG" open 100 \
+    2>/dev/null \
     | jq -r --arg exclusiveLabel "${AGENT_EXCLUSIVE_LABEL}" --argjson openAgentPrIssueIds "${open_agent_pr_issue_ids}" '
         map(select(
           any(.labels[]?; .name == $exclusiveLabel)
@@ -277,20 +281,22 @@ heartbeat_list_exclusive_issue_ids() {
         ))
         | sort_by(.createdAt, .number)
         | .[].number
-      '
+      ' 2>/dev/null || true
 }
 
 heartbeat_list_running_issue_ids() {
   flow_github_issue_list_json "$REPO_SLUG" open 100 \
+    2>/dev/null \
     | jq -r '
         map(select(any(.labels[]?; .name == "agent-running")))
         | sort_by(.createdAt, .number)
         | .[].number
-      '
+      ' 2>/dev/null || true
 }
 
 heartbeat_list_open_agent_pr_ids() {
   flow_github_pr_list_json "$REPO_SLUG" open 100 \
+    2>/dev/null \
     | jq -r --argjson agentPrPrefixes "${AGENT_PR_PREFIXES_JSON}" --arg handoffLabel "${AGENT_PR_HANDOFF_LABEL}" '
         map(select(
           . as $pr
@@ -302,11 +308,12 @@ heartbeat_list_open_agent_pr_ids() {
         ))
         | sort_by(.createdAt)
         | .[].number
-      '
+      ' 2>/dev/null || true
 }
 
 heartbeat_list_exclusive_pr_ids() {
   flow_github_pr_list_json "$REPO_SLUG" open 100 \
+    2>/dev/null \
     | jq -r --argjson agentPrPrefixes "${AGENT_PR_PREFIXES_JSON}" --arg handoffLabel "${AGENT_PR_HANDOFF_LABEL}" --arg exclusiveLabel "${AGENT_EXCLUSIVE_LABEL}" '
         map(select(
           . as $pr
@@ -319,7 +326,7 @@ heartbeat_list_exclusive_pr_ids() {
         ))
         | sort_by(.createdAt)
         | .[].number
-      '
+      ' 2>/dev/null || true
 }
 
 heartbeat_issue_is_heavy() {
@@ -438,9 +445,9 @@ heartbeat_mark_issue_running() {
   local issue_id="${1:?issue id required}"
   local is_heavy="${2:-no}"
   if [[ "$is_heavy" == "yes" ]]; then
-    bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$issue_id" --remove agent-ready --remove agent-blocked --add agent-running --add agent-e2e-heavy >/dev/null
+    bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$issue_id" --remove agent-ready --remove agent-blocked --add agent-running --add agent-e2e-heavy >/dev/null || true
   else
-    bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$issue_id" --remove agent-ready --remove agent-blocked --add agent-running >/dev/null
+    bash "${FLOW_TOOLS_DIR}/agent-github-update-labels" --repo-slug "$REPO_SLUG" --number "$issue_id" --remove agent-ready --remove agent-blocked --add agent-running >/dev/null || true
   fi
 }
 

package/npm/bin/agent-control-plane.js

@@ -22,6 +22,7 @@ Commands:
   help                 Show this help
   version              Print package version
   setup                Guided setup flow for one repo profile
+  onboard              Alias for setup
   sync                 Publish the packaged runtime into ~/.agent-runtime
   install              Alias for sync
   init                 Scaffold and adopt a project profile
@@ -503,6 +504,20 @@ function createPromptInterface() {
   });
 }
 
+function printWizardBanner() {
+  console.log("============================================================");
+  console.log("  Agent Control Plane — Setup Wizard");
+  console.log("============================================================");
+  console.log("");
+  console.log("This wizard will guide you through setting up one repo profile.");
+  console.log("Press Enter at any prompt to accept the value shown in [brackets].");
+  console.log("");
+}
+
+function printWizardStep(step, total, title) {
+  console.log(`\n[${step}/${total}] ${title}`);
+}
+
 function question(rl, prompt) {
   return new Promise((resolve) => rl.question(prompt, resolve));
 }
@@ -1341,7 +1356,9 @@ function printSetupDryRunPlan(context, config, plan) {
   }
   console.log(`- GitHub auth step: ${plan.githubAuthAction.status}${plan.githubAuthAction.reason ? ` (${plan.githubAuthAction.reason})` : ""}`);
   console.log(`- runtime start: ${plan.runtimeStartAction.status}${plan.runtimeStartAction.reason ? ` (${plan.runtimeStartAction.reason})` : ""}`);
-  console.log(`- launchd install: ${plan.launchdAction.status}${plan.launchdAction.reason ? ` (${plan.launchdAction.reason})` : ""}`);
+  if (process.platform === "darwin") {
+    console.log(`- launchd install: ${plan.launchdAction.status}${plan.launchdAction.reason ? ` (${plan.launchdAction.reason})` : ""}`);
+  }
 }
 
 function buildSetupResultPayload(params) {
@@ -1457,6 +1474,23 @@ async function maybeRunFinalSetupFixups(options, scopedContext, config, currentS
     console.log(`- ${issue}`);
   }
 
+  // Always show actionable hints so operators know what to fix,
+  // even when running non-interactively (--yes / --json / CI).
+  if (!currentState.prereq.coreToolsOk) {
+    const missing = currentState.prereq.missingRequired.join(", ");
+    console.log(`  Fix: install missing core tools (${missing})`);
+  }
+  if (!currentState.prereq.workerAvailable) {
+    const worker = currentState.prereq.workerCommand;
+    if (worker === "codex") console.log("  Fix: npm install -g @openai/codex && codex login");
+    else if (worker === "openclaw") console.log("  Fix: npm install -g openclaw && openclaw setup");
+    else if (worker === "claude") console.log("  Fix: npm install -g @anthropic-ai/claude-code && claude auth login");
+    else console.log(`  Fix: install ${worker} and add it to PATH`);
+  }
+  if (!currentState.prereq.ghAuthOk) {
+    console.log("  Fix: run gh auth login");
+  }
+
   if (!options.interactive) {
     return {
       status: "skipped",
@@ -1597,19 +1631,20 @@ async function collectSetupConfig(options, context) {
       throw new Error("setup could not detect --repo-slug automatically; pass --repo-slug <owner/repo> or run interactively inside a git checkout with origin set");
     }
   } else {
+    printWizardBanner();
     const rl = createPromptInterface();
     try {
-      console.log("ACP setup will guide one repo profile from install to operator-ready defaults.");
-      console.log("Press Enter to accept the suggested value shown in brackets.\n");
+      printWizardStep(1, 4, "Project details");
 
       repoRoot = path.resolve(await promptText(rl, "Local repo root", detectedRepoRoot));
       repoSlug = await promptText(rl, "GitHub repo slug", repoSlug || "");
       profileId = sanitizeProfileId(await promptText(rl, "Profile id", profileId));
-      codingWorker = await promptText(rl, "Coding worker (codex|claude|openclaw)", codingWorker);
 
-      if (!["codex", "claude", "openclaw"].includes(codingWorker)) {
-        throw new Error(`unsupported coding worker: ${codingWorker}`);
+      let workerInput = codingWorker;
+      while (!["codex", "claude", "openclaw"].includes(workerInput)) {
+        workerInput = await promptText(rl, "Coding worker (codex / claude / openclaw)", codingWorker || "openclaw");
       }
+      codingWorker = workerInput;
     } finally {
       rl.close();
     }
@@ -1630,6 +1665,9 @@ async function collectSetupConfig(options, context) {
     prereq
   };
 
+  if (options.interactive) {
+    printWizardStep(2, 4, "Review plan");
+  }
   renderSetupSummary(config);
 
   if (options.interactive) {
@@ -1641,7 +1679,7 @@ async function collectSetupConfig(options, context) {
       }
       const shouldContinue = await promptYesNo(rl, "Continue with these values", true);
       if (!shouldContinue) {
-        throw new Error("setup cancelled");
+        return null;
       }
       if (options.startRuntime === null) {
         options.startRuntime = await promptYesNo(rl, "Start the runtime after setup", true);
@@ -1733,6 +1771,10 @@ async function runSetupFlow(forwardedArgs) {
 
   try {
     const config = await collectSetupConfig(options, context);
+    if (config === null) {
+      console.log("\nSetup cancelled. Run again when you are ready.");
+      return 0;
+    }
     if (options.dryRun) {
       const plan = buildSetupDryRunPlan(options, context, config);
       printSetupDryRunPlan(context, config, plan);
@@ -1869,6 +1911,10 @@ async function runSetupFlow(forwardedArgs) {
       return 1;
     }
 
+    if (options.interactive) {
+      printWizardStep(3, 4, "Prerequisites");
+    }
+
     let prereq = config.prereq;
     let dependencyInstall = await maybeInstallMissingDependencies(options, prereq);
     if (dependencyInstall.status === "failed") {
@@ -1886,6 +1932,35 @@ async function runSetupFlow(forwardedArgs) {
     let workerSetupStep = await maybeShowWorkerSetupGuide(options, prereq);
     prereq = collectPrereqStatus(config.codingWorker);
 
+    // Check OpenRouter API key when openclaw is selected
+    if (config.codingWorker === "openclaw" && !process.env.OPENROUTER_API_KEY) {
+      console.log("\nOpenClaw requires an OpenRouter API key (OPENROUTER_API_KEY).");
+      console.log("- Get a free key at: https://openrouter.ai/keys");
+      if (options.interactive) {
+        const rl = createPromptInterface();
+        let apiKey = "";
+        try {
+          apiKey = (await promptText(rl, "OpenRouter API key (Enter to skip)", "")).trim();
+        } finally {
+          rl.close();
+        }
+        if (apiKey) {
+          process.env.OPENROUTER_API_KEY = apiKey;
+          console.log("API key set for this session.");
+          console.log("To persist it, add the following to your shell profile (~/.zshrc or ~/.bashrc):");
+          console.log(`  export OPENROUTER_API_KEY=${JSON.stringify(apiKey)}`);
+        } else {
+          console.log("Skipped. Set OPENROUTER_API_KEY before starting the runtime.");
+        }
+      } else {
+        console.log("Set OPENROUTER_API_KEY in your environment before starting the runtime.");
+      }
+    }
+
+    if (options.interactive) {
+      printWizardStep(4, 4, "Install");
+    }
+
     const scopedContext = buildScopedContext(context, config.profileId);
     const anchorSync = buildAnchorSyncDecision(options, config.paths.sourceRepoRoot);
 
@@ -2047,12 +2122,45 @@ async function runSetupFlow(forwardedArgs) {
 
     if (options.json) {
       emitSetupJsonPayload(runPayload);
+    } else if (options.interactive) {
+      // Human-friendly summary for interactive terminal runs
+      console.log("\n============================================================");
+      console.log("  Setup complete!");
+      console.log("============================================================");
+      console.log(`  Profile : ${config.profileId}`);
+      console.log(`  Repo    : ${config.repoSlug}`);
+      console.log(`  Worker  : ${config.codingWorker}`);
+      console.log(`  Runtime : ${context.runtimeHome}`);
+
+      const pendingItems = [];
+      if (!prereq.ghAuthOk) pendingItems.push("GitHub CLI not authenticated — run: gh auth login");
+      if (!prereq.workerAvailable) pendingItems.push(`${config.codingWorker} not found on PATH — install it before starting`);
+      if (config.codingWorker === "openclaw" && !process.env.OPENROUTER_API_KEY) {
+        pendingItems.push("OPENROUTER_API_KEY not set — required for openclaw workers");
+      }
+      if (anchorSync.status !== "ok") pendingItems.push(`Anchor repo sync deferred (${anchorSync.reason}) — fix git access and re-run setup`);
+      if ((doctorKv.DOCTOR_STATUS || "") !== "ok") pendingItems.push(`Doctor check flagged issues — run: npx agent-control-plane@latest doctor`);
+
+      if (pendingItems.length > 0) {
+        console.log("\n  Pending items before starting:");
+        for (const item of pendingItems) {
+          console.log(`    - ${item}`);
+        }
+      }
+
+      console.log("\n  Next commands:");
+      if (runtimeStartStatus !== "ok") {
+        console.log(`    npx agent-control-plane@latest runtime start --profile-id ${config.profileId}`);
+      }
+      console.log(`    npx agent-control-plane@latest runtime status --profile-id ${config.profileId}`);
+      console.log(`    npx agent-control-plane@latest doctor`);
+      console.log("");
     } else {
+      // Machine-readable KV output for non-interactive / scripted runs
       console.log("\nSetup complete.");
       console.log(`- profile: ${config.profileId}`);
       console.log(`- repo: ${config.repoSlug}`);
       console.log(`- runtime home: ${context.runtimeHome}`);
-      console.log(`- next status command: npx agent-control-plane@latest runtime status --profile-id ${config.profileId}`);
 
       console.log(`SETUP_STATUS=ok`);
       console.log(`PROFILE_ID=${config.profileId}`);
@@ -2170,6 +2278,7 @@ async function main() {
       console.log(packageJson.version);
       return 0;
     case "setup":
+    case "onboard":
       return runSetupFlow(forwardedArgs);
     case "sync":
     case "install":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {
@@ -32,12 +32,14 @@
     "tools/bin",
     "!tools/bin/audit-*.sh",
     "!tools/bin/check-skill-contracts.sh",
+    "!tools/bin/render-dashboard-snapshot.py",
     "tools/dashboard/app.js",
     "tools/dashboard/dashboard_snapshot.py",
     "tools/dashboard/index.html",
     "tools/dashboard/server.py",
     "tools/dashboard/styles.css",
     "tools/templates",
+    "!tools/templates/legacy/",
     "tools/vendor/codex-quota/LICENSE",
     "tools/vendor/codex-quota/codex-quota.js",
     "tools/vendor/codex-quota/lib",

package/references/commands.md

@@ -85,7 +85,7 @@ 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
+python3 tools/dashboard/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
 ```
@@ -97,7 +97,7 @@ prompts live under `tools/templates/`.
 ## Dashboard
 
 ```bash
-python3 tools/bin/render-dashboard-snapshot.py --pretty
+python3 tools/dashboard/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
 ```

package/references/control-plane-map.md

@@ -64,7 +64,7 @@ roots, labels, worker preferences, prompts, and project-specific guardrails.
   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`
+- `tools/dashboard/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`

package/tools/bin/agent-project-reconcile-issue-session

@@ -307,12 +307,14 @@ schedule_provider_quota_cooldown() {
   local reason="${1:-provider-quota-limit}"
   [[ "${reason}" == "provider-quota-limit" ]] || return 0
   [[ -x "${provider_cooldown_script}" ]] || return 0
+  [[ "${CODING_WORKER:-}" == "codex" ]] && return 0
 
   "${provider_cooldown_script}" schedule "${reason}" >/dev/null || true
 }
 
 clear_provider_quota_cooldown() {
   [[ -x "${provider_cooldown_script}" ]] || return 0
+  [[ "${CODING_WORKER:-}" == "codex" ]] && return 0
 
   "${provider_cooldown_script}" clear >/dev/null || true
 }
@@ -357,6 +359,16 @@ infer_issue_runtime_failure_from_log() {
     return 0
   fi
 
+  if grep -Eiq 'stale-run no-agent-output-before-stall-threshold|no-agent-output-before-stall-threshold' "${log_file}" 2>/dev/null; then
+    printf 'no-agent-output-before-stall-threshold\n'
+    return 0
+  fi
+
+  if grep -Eiq 'stale-run no-agent-progress-before-stall-threshold|no-agent-progress-before-stall-threshold' "${log_file}" 2>/dev/null; then
+    printf 'no-agent-progress-before-stall-threshold\n'
+    return 0
+  fi
+
   if grep -Eiq 'Ignoring invalid cwd .* No such file or directory|/tmp is absolute|Custom tool call output is missing' "${log_file}" 2>/dev/null; then
     printf 'worker-environment-blocked\n'
     return 0
@@ -985,6 +997,17 @@ if (explicitFailureReason) {
   reason = 'scope-guard-blocked';
 } else if (/^# Blocker: Provider quota is currently exhausted$/im.test(body)) {
   reason = 'provider-quota-limit';
+} else if (
+  /blocked on external network access/i.test(body) &&
+  (/What I ran:/i.test(body) ||
+    /`pnpm audit`/i.test(body) ||
+    /`gh issue view`/i.test(body)) &&
+  (/failed with `ENOTFOUND`/i.test(body) ||
+    /Exact failure:/i.test(body) ||
+    /registry\.npmjs\.org/i.test(body) ||
+    /api\.github\.com/i.test(body))
+) {
+  reason = 'worker-preflight-network-blocked';
 } else if (
   /blocked on external network access/i.test(body) ||
   /could not perform a safe offline bump/i.test(body) ||