agent-control-plane 0.1.16 → 0.2.0

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

@@ -57,7 +57,7 @@ Options:
   --retained-repo-root <path>  Manual checkout root to keep linked in the profile
   --vscode-workspace-file <path>
                                Workspace file path ACP should generate/use
-  --coding-worker <backend>    One of: codex, claude, openclaw
+  --coding-worker <backend>    One of: codex, claude, openclaw, ollama, pi, opencode, kilo
   --force                      Overwrite an existing profile
   --skip-anchor-sync           Skip profile-adopt anchor repo sync
   --skip-workspace-sync        Skip profile-adopt workspace sync
@@ -75,6 +75,11 @@ Options:
   --no-start-runtime           Do not start the runtime after setup
   --install-launchd            Install macOS autostart after a successful runtime start
   --no-install-launchd         Do not install macOS autostart
+  --start-dashboard            Start the dashboard in background after setup
+  --no-start-dashboard         Do not start the dashboard
+  --dashboard-port <port>      Dashboard port (default: 8765)
+  --create-starter-issues      Create recurring issues so ACP starts working immediately
+  --no-create-starter-issues   Skip starter issue creation
   --yes                        Accept detected defaults without prompting
   --non-interactive            Same as --yes
   --help                       Show this help
@@ -394,6 +399,9 @@ function parseSetupArgs(args) {
     json: false,
     startRuntime: null,
     installLaunchd: null,
+    startDashboard: null,
+    dashboardPort: 8765,
+    createStarterIssues: null,
     interactive: process.stdin.isTTY && process.stdout.isTTY,
     help: false
   };
@@ -481,6 +489,21 @@ function parseSetupArgs(args) {
       case "--no-install-launchd":
         options.installLaunchd = false;
         break;
+      case "--start-dashboard":
+        options.startDashboard = true;
+        break;
+      case "--no-start-dashboard":
+        options.startDashboard = false;
+        break;
+      case "--dashboard-port":
+        options.dashboardPort = parseInt(args[++index] || "8765", 10);
+        break;
+      case "--create-starter-issues":
+        options.createStarterIssues = true;
+        break;
+      case "--no-create-starter-issues":
+        options.createStarterIssues = false;
+        break;
       case "--yes":
       case "--non-interactive":
         options.interactive = false;
@@ -543,6 +566,179 @@ async function promptYesNo(rl, label, defaultValue) {
   return defaultValue;
 }
 
+const STARTER_ISSUE_CATALOG = [
+  {
+    key: "code-quality",
+    title: "Keep code quality high: fix lint warnings, type errors, and dead code",
+    body: `## Recurring: Code Quality Sweep
+
+Checklist:
+- [ ] Fix any TypeScript / ESLint / type-check errors in the codebase
+- [ ] Remove dead exports, unused imports, and unreachable code paths
+- [ ] Resolve any TODO/FIXME comments that are straightforward to address
+
+Agent schedule: every 4h
+
+- Run \`pnpm typecheck\` (or the repo-equivalent lint/typecheck) after code changes and record verification.
+`,
+    labels: ["agent-ready", "agent-keep-open"]
+  },
+  {
+    key: "test-coverage",
+    title: "Improve test coverage for critical and untested modules",
+    body: `## Recurring: Test Coverage Improvement
+
+Checklist:
+- [ ] Identify source files with zero or minimal test coverage
+- [ ] Add focused unit or integration tests for the most critical untested paths
+- [ ] Ensure new tests actually run and pass in the local test runner
+
+Agent schedule: every 6h
+
+- Run the narrowest relevant test command after code changes and record verification.
+`,
+    labels: ["agent-ready", "agent-keep-open"]
+  },
+  {
+    key: "documentation",
+    title: "Keep documentation accurate and up to date",
+    body: `## Recurring: Documentation Refresh
+
+Checklist:
+- [ ] Update README sections that are outdated or reference removed features
+- [ ] Add or fix JSDoc / inline comments for public APIs that lack them
+- [ ] Ensure setup instructions and examples still work on a clean checkout
+
+Agent schedule: every 8h
+
+- Run any doc-build or link-check command after changes and record verification.
+`,
+    labels: ["agent-ready", "agent-keep-open"]
+  },
+  {
+    key: "dependency-audit",
+    title: "Audit and update dependencies for security and freshness",
+    body: `## Recurring: Dependency Audit
+
+Checklist:
+- [ ] Run the package manager audit and fix any critical/high vulnerabilities
+- [ ] Update patch-level dependencies that have safe upgrades available
+- [ ] Verify the lockfile is consistent after changes
+
+Agent schedule: every 12h
+
+- Run \`pnpm audit\` and \`pnpm install --frozen-lockfile\` after changes and record verification.
+`,
+    labels: ["agent-ready", "agent-keep-open"]
+  },
+  {
+    key: "refactor",
+    title: "Refactor complex or duplicated code for maintainability",
+    body: `## Recurring: Refactoring Sweep
+
+Checklist:
+- [ ] Identify functions or modules with high complexity or duplication
+- [ ] Extract shared logic into well-named helpers or utilities
+- [ ] Ensure refactored code passes existing tests without behavior changes
+
+Agent schedule: every 8h
+
+- Run the narrowest relevant test command after refactoring and record verification.
+`,
+    labels: ["agent-ready", "agent-keep-open"]
+  }
+];
+
+async function maybeCreateStarterIssues(options, config, prereq) {
+  const result = { status: "skipped", created: [], reason: "not-requested" };
+
+  if (options.createStarterIssues === false) {
+    return result;
+  }
+
+  if (!prereq.ghAuthOk) {
+    result.reason = "gh-auth-not-ready";
+    return result;
+  }
+
+  let shouldCreate = options.createStarterIssues === true;
+  if (!shouldCreate && options.interactive) {
+    const rl0 = createPromptInterface();
+    try {
+      shouldCreate = await promptYesNo(rl0, "\nCreate starter issues so ACP starts working immediately", true);
+    } finally {
+      rl0.close();
+    }
+  }
+  if (!shouldCreate) {
+    return result;
+  }
+
+  let toCreate;
+  if (options.interactive) {
+    const rlSel = createPromptInterface();
+    try {
+      console.log("\nSelect which recurring issues to create (ACP will work on these continuously):\n");
+      const selections = [];
+      for (const issue of STARTER_ISSUE_CATALOG) {
+        const selected = await promptYesNo(rlSel, `  ${issue.title}`, true);
+        selections.push({ issue, selected });
+      }
+      toCreate = selections.filter((s) => s.selected);
+    } finally {
+      rlSel.close();
+    }
+  } else {
+    // Non-interactive: create all starter issues
+    toCreate = STARTER_ISSUE_CATALOG.map((issue) => ({ issue, selected: true }));
+  }
+
+  if (toCreate.length === 0) {
+    console.log("No issues selected.");
+    return result;
+  }
+
+  // Ensure labels exist
+  console.log("\nCreating labels and issues...");
+  const requiredLabels = [
+    { name: "agent-ready", color: "0E8A16", description: "Ready for agent automation" },
+    { name: "agent-keep-open", color: "D4C5F9", description: "Recurring issue — agent works on this continuously" }
+  ];
+  for (const label of requiredLabels) {
+    spawnSync("gh", ["label", "create", label.name, "--repo", config.repoSlug, "--description", label.description, "--color", label.color, "--force"], { stdio: "pipe", timeout: 15000 });
+  }
+
+  for (const { issue } of toCreate) {
+    const ghArgs = [
+      "issue", "create",
+      "--repo", config.repoSlug,
+      "--title", issue.title,
+      "--body", issue.body,
+      "--label", issue.labels.join(",")
+    ];
+    const ghResult = spawnSync("gh", ghArgs, { encoding: "utf8", stdio: "pipe", timeout: 30000 });
+    if (ghResult.status === 0) {
+      const url = (ghResult.stdout || "").trim();
+      result.created.push({ key: issue.key, title: issue.title, url });
+      console.log(`  Created: ${issue.title}`);
+      if (url) {
+        console.log(`           ${url}`);
+      }
+    } else {
+      console.log(`  Failed to create: ${issue.title}`);
+      const stderr = (ghResult.stderr || "").trim();
+      if (stderr) {
+        console.log(`           ${stderr.split("\n")[0]}`);
+      }
+    }
+  }
+
+  result.status = result.created.length > 0 ? "ok" : "failed";
+  result.reason = "";
+
+  return result;
+}
+
 function buildSetupPaths(platformHome, repoRoot, profileId, overrides) {
   const agentRoot = path.resolve(overrides.agentRoot || path.join(platformHome, "projects", profileId));
   const repoRootResolved = path.resolve(repoRoot);
@@ -590,6 +786,9 @@ function detectPackageManager() {
   if (commandExists("pacman")) {
     return { name: "pacman" };
   }
+  if (commandExists("zypper")) {
+    return { name: "zypper" };
+  }
   return null;
 }
 
@@ -680,6 +879,9 @@ function buildDependencyInstallPlan(missingTools) {
     case "pacman":
       commands.push([...prefix, "pacman", "-Sy", "--noconfirm", ...packages]);
       break;
+    case "zypper":
+      commands.push([...prefix, "zypper", "install", "-y", ...packages]);
+      break;
     default:
       return null;
   }
@@ -721,7 +923,7 @@ async function maybeInstallMissingDependencies(options, prereq) {
   if (!plan) {
     console.log("\nACP found missing core dependencies but cannot install them automatically on this machine.");
     console.log(`- missing tools: ${prereq.missingRequired.join(", ")}`);
-    console.log("- supported auto-install package managers today: brew, apt-get, dnf, yum, pacman");
+    console.log("- supported auto-install package managers today: brew, apt-get, dnf, yum, pacman, zypper");
     return {
       status: "unavailable",
       reason: "no-supported-package-manager",
@@ -1355,6 +1557,9 @@ function printSetupDryRunPlan(context, config, plan) {
     console.log(`  command preview: ${plan.workerInstallPlan.commands.map(formatCommand).join(" && ")}`);
   }
   console.log(`- GitHub auth step: ${plan.githubAuthAction.status}${plan.githubAuthAction.reason ? ` (${plan.githubAuthAction.reason})` : ""}`);
+  if (plan.githubAuthAction.status !== "not-needed") {
+    console.log(`  command preview: gh auth login`);
+  }
   console.log(`- runtime start: ${plan.runtimeStartAction.status}${plan.runtimeStartAction.reason ? ` (${plan.runtimeStartAction.reason})` : ""}`);
   if (process.platform === "darwin") {
     console.log(`- launchd install: ${plan.launchdAction.status}${plan.launchdAction.reason ? ` (${plan.launchdAction.reason})` : ""}`);
@@ -1641,8 +1846,8 @@ async function collectSetupConfig(options, context) {
       profileId = sanitizeProfileId(await promptText(rl, "Profile id", profileId));
 
       let workerInput = codingWorker;
-      while (!["codex", "claude", "openclaw"].includes(workerInput)) {
-        workerInput = await promptText(rl, "Coding worker (codex / claude / openclaw)", codingWorker || "openclaw");
+      while (!["codex", "claude", "openclaw", "ollama", "pi", "opencode", "kilo"].includes(workerInput)) {
+        workerInput = await promptText(rl, "Coding worker (codex / claude / openclaw / ollama / pi / opencode / kilo)", codingWorker || "openclaw");
       }
       codingWorker = workerInput;
     } finally {
@@ -1650,7 +1855,7 @@ async function collectSetupConfig(options, context) {
     }
   }
 
-  if (!["codex", "claude", "openclaw"].includes(codingWorker)) {
+  if (!["codex", "claude", "openclaw", "ollama", "pi", "opencode", "kilo"].includes(codingWorker)) {
     throw new Error(`unsupported coding worker: ${codingWorker}`);
   }
 
@@ -1687,6 +1892,9 @@ async function collectSetupConfig(options, context) {
       if (process.platform === "darwin" && options.installLaunchd === null && options.startRuntime) {
         options.installLaunchd = await promptYesNo(rl, "Install macOS autostart for this profile", false);
       }
+      if (options.startDashboard === null) {
+        options.startDashboard = await promptYesNo(rl, "Start the monitoring dashboard in background", true);
+      }
     } finally {
       rl.close();
     }
@@ -1698,11 +1906,16 @@ async function collectSetupConfig(options, context) {
   if (options.installLaunchd === null) {
     options.installLaunchd = false;
   }
+  if (options.startDashboard === null) {
+    options.startDashboard = false;
+  }
 
   return {
     ...config,
     startRuntime: Boolean(options.startRuntime),
-    installLaunchd: Boolean(options.installLaunchd)
+    installLaunchd: Boolean(options.installLaunchd),
+    startDashboard: Boolean(options.startDashboard),
+    dashboardPort: options.dashboardPort
   };
 }
 
@@ -1932,9 +2145,10 @@ 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).");
+    // Check OpenRouter API key when openclaw or pi is selected
+    if ((config.codingWorker === "openclaw" || config.codingWorker === "pi") && !process.env.OPENROUTER_API_KEY) {
+      const workerLabel = config.codingWorker === "openclaw" ? "OpenClaw" : "Pi";
+      console.log(`\n${workerLabel} 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();
@@ -1957,6 +2171,29 @@ async function runSetupFlow(forwardedArgs) {
       }
     }
 
+    // Check Ollama readiness when ollama is selected
+    if (config.codingWorker === "ollama") {
+      const ollamaRunning = spawnSync("curl", ["-sf", "http://localhost:11434/api/tags"], { timeout: 5000 });
+      if (ollamaRunning.status !== 0) {
+        console.log("\nOllama does not appear to be running at http://localhost:11434.");
+        console.log("- Install from: https://ollama.com");
+        console.log("- Start it with: ollama serve");
+      } else {
+        console.log("\nOllama is running. Checking available models...");
+        try {
+          const tagsJson = JSON.parse(ollamaRunning.stdout.toString());
+          const modelNames = (tagsJson.models || []).map((m) => m.name || m.model || "").filter(Boolean);
+          if (modelNames.length === 0) {
+            console.log("No models pulled yet. Pull one with: ollama pull qwen2.5-coder:7b");
+          } else {
+            console.log(`Available models: ${modelNames.slice(0, 5).join(", ")}${modelNames.length > 5 ? ` (+${modelNames.length - 5} more)` : ""}`);
+          }
+        } catch (_) {
+          console.log("Could not parse model list. Ensure a model is pulled: ollama pull qwen2.5-coder:7b");
+        }
+      }
+    }
+
     if (options.interactive) {
       printWizardStep(4, 4, "Install");
     }
@@ -2048,6 +2285,56 @@ async function runSetupFlow(forwardedArgs) {
       }
     }
 
+    let dashboardStatus = "skipped";
+    let dashboardReason = "not-requested";
+    let dashboardUrl = "";
+    if (config.startDashboard) {
+      const dashboardScript = path.join(scopedContext.stableSkillRoot || scopedContext.packageRoot, "tools", "bin", "serve-dashboard.sh");
+      const dashboardLogDir = path.join(config.paths.agentRoot || context.platformHome, "dashboard-logs");
+      fs.mkdirSync(dashboardLogDir, { recursive: true });
+      const dashboardLogFile = path.join(dashboardLogDir, "dashboard.log");
+      const dashboardPidFile = path.join(dashboardLogDir, "dashboard.pid");
+
+      // Kill any existing dashboard on the same port
+      try {
+        if (fs.existsSync(dashboardPidFile)) {
+          const oldPid = fs.readFileSync(dashboardPidFile, "utf8").trim();
+          if (oldPid && /^\d+$/.test(oldPid)) {
+            try { process.kill(Number(oldPid), "SIGTERM"); } catch (_) { /* already dead */ }
+          }
+        }
+      } catch (_) { /* ignore */ }
+
+      console.log(`\n== Start dashboard (background, port ${config.dashboardPort}) ==`);
+      syncRuntimeHome(context, { stdio: "pipe" });
+      const rtCtx = createRuntimeExecutionContext(context);
+      const rtDashboardScript = path.join(rtCtx.stableSkillRoot, "tools", "bin", "serve-dashboard.sh");
+      const { spawn } = require("child_process");
+      const logHandle = fs.openSync(dashboardLogFile, "a");
+      const dashboardProc = spawn("bash", [rtDashboardScript, "--host", "127.0.0.1", "--port", String(config.dashboardPort)], {
+        detached: true,
+        stdio: ["ignore", logHandle, logHandle],
+        env: { ...process.env, ACP_PROFILE_REGISTRY_ROOT: context.profileRegistryRoot }
+      });
+      dashboardProc.unref();
+      fs.closeSync(logHandle);
+
+      if (dashboardProc.pid) {
+        fs.writeFileSync(dashboardPidFile, `${dashboardProc.pid}\n`);
+        dashboardUrl = `http://127.0.0.1:${config.dashboardPort}`;
+        dashboardStatus = "ok";
+        dashboardReason = "";
+        console.log(`Dashboard running at ${dashboardUrl} (PID ${dashboardProc.pid})`);
+        console.log(`Log: ${dashboardLogFile}`);
+      } else {
+        dashboardStatus = "failed";
+        dashboardReason = "spawn-failed";
+        console.log("Dashboard failed to start.");
+      }
+    }
+
+    const starterIssues = await maybeCreateStarterIssues(options, config, prereq);
+
     const finalFixup = await maybeRunFinalSetupFixups(options, scopedContext, config, {
       anchorSync,
       prereq,
@@ -2148,12 +2435,38 @@ async function runSetupFlow(forwardedArgs) {
         }
       }
 
+      if (dashboardStatus === "ok" && dashboardUrl) {
+        console.log(`\n  Dashboard: ${dashboardUrl}`);
+      }
+
       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}`);
+      if (dashboardStatus !== "ok") {
+        console.log(`    npx agent-control-plane@latest dashboard`);
+      }
       console.log(`    npx agent-control-plane@latest doctor`);
+
+      if (starterIssues.created.length > 0) {
+        console.log("\n  Starter issues created (ACP will start working on these):");
+        for (const issue of starterIssues.created) {
+          console.log(`    - ${issue.title}`);
+          if (issue.url) {
+            console.log(`      ${issue.url}`);
+          }
+        }
+      } else {
+        console.log("\n  Getting started:");
+        console.log(`    1. Add the label 'agent-ready' to a GitHub issue in ${config.repoSlug}`);
+        console.log("    2. ACP picks it up automatically, assigns a worker, and opens a PR");
+        console.log("    3. Watch progress in the dashboard or with 'runtime status'");
+      }
+      if (config.codingWorker === "openclaw" || config.codingWorker === "pi") {
+        console.log(`\n  Tip: ${config.codingWorker} uses free-tier models by default.`);
+        console.log("  No API costs until you switch to a paid model in the profile YAML.");
+      }
       console.log("");
     } else {
       // Machine-readable KV output for non-interactive / scripted runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.1.16",
+  "version": "0.2.0",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {

package/references/architecture.md

@@ -41,10 +41,18 @@ flowchart LR
   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"]

package/references/control-plane-map.md

@@ -36,10 +36,14 @@ roots, labels, worker preferences, prompts, and project-specific guardrails.
   Launches Claude-backed worker sessions.
 - `tools/bin/agent-project-run-openclaw-session`
   Launches OpenClaw-backed worker sessions.
+- `tools/bin/agent-project-run-ollama-session`
+  Launches Ollama-backed worker sessions with a Node.js agentic loop.
+- `tools/bin/agent-project-run-pi-session`
+  Launches Pi-backed worker sessions in `--print --no-session` mode.
 - `tools/bin/agent-project-run-opencode-session`
-  Placeholder adapter stub for the planned `opencode` backend.
+  Launches Crush (formerly OpenCode) worker sessions via `crush run`.
 - `tools/bin/agent-project-run-kilo-session`
-  Placeholder adapter stub for the planned `kilo` backend.
+  Launches Kilo Code worker sessions via `kilo run --auto --format json`.
 - `tools/bin/project-init.sh`
   Runs scaffold + smoke + adopt + runtime sync for one installed profile.
 - `tools/bin/scaffold-profile.sh`

package/references/release-checklist.md

@@ -9,8 +9,6 @@ Maintainer checklist for shipping a new public package release of
 - confirm `package.json` version is intentional
 - review `CHANGELOG.md` and prepare release notes from
   `.github/release-template.md`
-- refresh README demo media if the dashboard UI changed:
-  `bash tools/bin/render-dashboard-demo-media.sh`
 - review `README.md`, `SECURITY.md`, `CONTRIBUTING.md`, and `CLA.md` for stale
   links or policy text
 - if a public GitHub repo now exists, set or verify the `homepage`,

package/tools/bin/agent-github-update-labels

@@ -48,7 +48,12 @@ if [[ -z "$repo_slug" || -z "$number" ]]; then
 fi
 
 resource="issues/${number}"
-current_json="$(flow_github_api_repo "${repo_slug}" "${resource}")"
+# Use caller-provided cached JSON if available to skip the GET call
+if [[ -n "${ACP_CACHED_ISSUE_JSON:-}" ]]; then
+  current_json="${ACP_CACHED_ISSUE_JSON}"
+else
+  current_json="$(flow_github_api_repo "${repo_slug}" "${resource}")"
+fi
 add_json="$(jq -R . <"$add_file" | jq -s .)"
 remove_json="$(jq -R . <"$remove_file" | jq -s .)"
 payload="$(

package/tools/bin/agent-project-catch-up-issue-pr-links

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-catch-up-issue-pr-links --repo-slug <owner/repo> --state-root <path> --hook-file <path> [--limit <n>]
+
+Clear stale issue retry state when an issue already has a linked PR comment and
+that PR still exists (open, closed, or merged).
+EOF
+}
+
+repo_slug=""
+state_root=""
+hook_file=""
+limit="100"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-slug) repo_slug="${2:-}"; shift 2 ;;
+    --state-root) state_root="${2:-}"; shift 2 ;;
+    --hook-file) hook_file="${2:-}"; shift 2 ;;
+    --limit) limit="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$repo_slug" || -z "$state_root" || -z "$hook_file" ]]; then
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -f "$hook_file" ]]; then
+  echo "missing hook file: $hook_file" >&2
+  exit 1
+fi
+
+# shellcheck source=/dev/null
+source "$hook_file"
+
+if ! declare -F issue_clear_retry >/dev/null 2>&1; then
+  issue_clear_retry() { :; }
+fi
+
+ledger_dir="${state_root}/linked-pr-issue-catchup"
+retry_dir="${state_root}/retries/issues"
+mkdir -p "$ledger_dir" "$retry_dir"
+
+extract_latest_linked_pr() {
+  local issue_json="${1:-}"
+  ISSUE_JSON="$issue_json" python3 - <<'PY'
+import json
+import os
+import re
+
+issue = json.loads(os.environ.get("ISSUE_JSON", "{}") or "{}")
+latest = ""
+latest_at = ""
+for comment in issue.get("comments", []) or []:
+    body = comment.get("body") or ""
+    match = None
+    for candidate in re.finditer(r"Opened PR #(\d+)", body):
+        match = candidate
+    if not match:
+        continue
+    created = comment.get("createdAt") or ""
+    pr_number = match.group(1)
+    if created >= latest_at:
+        latest_at = created
+        latest = pr_number
+
+print(latest)
+PY
+}
+
+pr_exists() {
+  local pr_number="${1:?pr number required}"
+  local pr_json=""
+  pr_json="$(flow_github_pr_view_json "$repo_slug" "$pr_number" 2>/dev/null || true)"
+  [[ -n "$pr_json" && "$pr_json" != "{}" ]]
+}
+
+for retry_file in "$retry_dir"/*.env; do
+  [[ -f "$retry_file" ]] || continue
+  issue_id="$(basename "${retry_file%.env}")"
+  [[ -n "$issue_id" ]] || continue
+
+  retry_reason="$(awk -F= '/^LAST_REASON=/{print $2; exit}' "$retry_file" 2>/dev/null | tr -d '\r' || true)"
+  if [[ "$retry_reason" != "host-publish-failed" ]]; then
+    continue
+  fi
+
+  ledger_file="${ledger_dir}/${issue_id}.env"
+  if [[ -f "$ledger_file" ]]; then
+    continue
+  fi
+
+  issue_json="$(flow_github_issue_view_json "$repo_slug" "$issue_id" 2>/dev/null || true)"
+  [[ -n "$issue_json" && "$issue_json" != "{}" ]] || continue
+
+  linked_pr="$(extract_latest_linked_pr "$issue_json")"
+  [[ -n "$linked_pr" ]] || continue
+  if ! pr_exists "$linked_pr"; then
+    continue
+  fi
+
+  ISSUE_ID="$issue_id" issue_clear_retry || true
+
+  {
+    printf 'ISSUE_ID=%s\n' "$issue_id"
+    printf 'LINKED_PR=%s\n' "$linked_pr"
+    printf 'PROCESSED_AT=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  } >"$ledger_file"
+
+  printf 'CATCHUP_LINKED_PR_ISSUE=%s\n' "$issue_id"
+done