agent-control-plane 0.1.9 → 0.1.13

package/hooks/heartbeat-hooks.sh

@@ -15,15 +15,87 @@ FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
 DETACHED_LAUNCH_BIN="${FLOW_TOOLS_DIR}/agent-project-detached-launch"
 RESIDENT_ISSUE_LOOP_BIN="${FLOW_TOOLS_DIR}/start-resident-issue-loop.sh"
 REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
+DEFAULT_BRANCH="$(flow_resolve_default_branch "${CONFIG_YAML}")"
+STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+PENDING_LAUNCH_DIR="${ACP_PENDING_LAUNCH_DIR:-${F_LOSNING_PENDING_LAUNCH_DIR:-${STATE_ROOT}/pending-launches}}"
 AGENT_PR_PREFIXES_JSON="$(flow_managed_pr_prefixes_json "${CONFIG_YAML}")"
 AGENT_PR_ISSUE_CAPTURE_REGEX="$(flow_managed_issue_branch_regex "${CONFIG_YAML}")"
 AGENT_PR_HANDOFF_LABEL="${AGENT_PR_HANDOFF_LABEL:-agent-handoff}"
 AGENT_EXCLUSIVE_LABEL="${AGENT_EXCLUSIVE_LABEL:-agent-exclusive}"
 CODING_WORKER="${ACP_CODING_WORKER:-${F_LOSNING_CODING_WORKER:-codex}}"
+HEARTBEAT_ISSUE_JSON_CACHE_DIR="${TMPDIR:-/tmp}/heartbeat-issue-json.$$"
+
+heartbeat_issue_retry_state_file() {
+  local issue_id="${1:?issue id required}"
+  printf '%s/retries/issues/%s.env\n' "${STATE_ROOT}" "${issue_id}"
+}
+
+heartbeat_reason_requires_baseline_change() {
+  local reason="${1:-}"
+  case "${reason}" in
+    verification-guard-blocked|no-publishable-commits|no-publishable-delta)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+heartbeat_current_baseline_head_sha() {
+  local head_sha=""
+  if [[ -d "${AGENT_REPO_ROOT}" ]]; then
+    head_sha="$(git -C "${AGENT_REPO_ROOT}" rev-parse --verify --quiet "origin/${DEFAULT_BRANCH}" 2>/dev/null || true)"
+    if [[ -z "${head_sha}" ]]; then
+      head_sha="$(git -C "${AGENT_REPO_ROOT}" rev-parse --verify --quiet "${DEFAULT_BRANCH}" 2>/dev/null || true)"
+    fi
+  fi
+  printf '%s\n' "${head_sha}"
+}
+
+heartbeat_retry_reason_is_baseline_blocked() {
+  local issue_id="${1:?issue id required}"
+  local reason="${2:-}"
+  local state_file baseline_head current_head
+
+  heartbeat_reason_requires_baseline_change "${reason}" || return 1
+  state_file="$(heartbeat_issue_retry_state_file "${issue_id}")"
+  [[ -f "${state_file}" ]] || return 1
+
+  baseline_head="$(awk -F= '/^BASELINE_HEAD_SHA=/{print substr($0, index($0, "=") + 1); exit}' "${state_file}" 2>/dev/null | tr -d '\r' || true)"
+  [[ -n "${baseline_head}" ]] || return 1
+  current_head="$(heartbeat_current_baseline_head_sha)"
+  [[ -n "${current_head}" ]] || return 1
+
+  [[ "${baseline_head}" == "${current_head}" ]]
+}
+
+heartbeat_issue_json_cached() {
+  local issue_id="${1:?issue id required}"
+  local cache_file=""
+  local issue_json=""
+
+  if [[ ! -d "${HEARTBEAT_ISSUE_JSON_CACHE_DIR}" ]]; then
+    mkdir -p "${HEARTBEAT_ISSUE_JSON_CACHE_DIR}"
+  fi
+
+  cache_file="${HEARTBEAT_ISSUE_JSON_CACHE_DIR}/${issue_id}.json"
+  if [[ -f "${cache_file}" ]]; then
+    cat "${cache_file}"
+    return 0
+  fi
+
+  issue_json="$(flow_github_issue_view_json "$REPO_SLUG" "$issue_id" 2>/dev/null || true)"
+  printf '%s' "${issue_json}" >"${cache_file}"
+  printf '%s\n' "${issue_json}"
+}
 
 heartbeat_open_agent_pr_issue_ids() {
-  flow_github_pr_list_json "$REPO_SLUG" open 100 \
-    | jq --argjson agentPrPrefixes "${AGENT_PR_PREFIXES_JSON}" --arg handoffLabel "${AGENT_PR_HANDOFF_LABEL}" --arg branchIssueRegex "${AGENT_PR_ISSUE_CAPTURE_REGEX}" '
+  local pr_issue_ids_json=""
+  pr_issue_ids_json="$(
+    flow_github_pr_list_json "$REPO_SLUG" open 100 \
+      | jq --argjson agentPrPrefixes "${AGENT_PR_PREFIXES_JSON}" --arg handoffLabel "${AGENT_PR_HANDOFF_LABEL}" --arg branchIssueRegex "${AGENT_PR_ISSUE_CAPTURE_REGEX}" '
         map(
           . as $pr
           | select(
@@ -48,6 +120,13 @@ heartbeat_open_agent_pr_issue_ids() {
         )
         | unique
       '
+  )"
+
+  if [[ -z "${pr_issue_ids_json:-}" ]]; then
+    printf '[]\n'
+  else
+    printf '%s\n' "${pr_issue_ids_json}"
+  fi
 }
 
 heartbeat_list_ready_issue_ids() {
@@ -120,11 +199,14 @@ heartbeat_issue_blocked_recovery_reason() {
   retry_out="$("${FLOW_TOOLS_DIR}/retry-state.sh" issue "$issue_id" get 2>/dev/null || true)"
   retry_reason="$(awk -F= '/^LAST_REASON=/{print $2}' <<<"${retry_out:-}")"
   if [[ -n "${retry_reason:-}" && "${retry_reason}" != "issue-worker-blocked" ]]; then
+    if heartbeat_retry_reason_is_baseline_blocked "${issue_id}" "${retry_reason}"; then
+      return 0
+    fi
     printf '%s\n' "$retry_reason"
     return 0
   fi
 
-  issue_json="$(flow_github_issue_view_json "$REPO_SLUG" "$issue_id" 2>/dev/null || true)"
+  issue_json="$(heartbeat_issue_json_cached "$issue_id")"
   if [[ -z "${issue_json:-}" ]]; then
     return 0
   fi
@@ -163,6 +245,8 @@ if (explicitFailureReason) {
   reason = 'scope-guard-blocked';
 } else if (/verification guard/i.test(body)) {
   reason = 'verification-guard-blocked';
+} else if (/localization guard/i.test(body) || /^# Blocker: Localization requirements were not satisfied$/im.test(body)) {
+  reason = 'localization-guard-blocked';
 } else if (/missing referenced OpenSpec paths/i.test(body)) {
   reason = 'missing-openspec-paths';
 } else if (/superseded by focused follow-up issues/i.test(body)) {
@@ -248,7 +332,7 @@ heartbeat_issue_is_heavy() {
 heartbeat_issue_is_recurring() {
   local issue_id="${1:?issue id required}"
   local issue_json
-  issue_json="$(flow_github_issue_view_json "$REPO_SLUG" "$issue_id" 2>/dev/null || true)"
+  issue_json="$(heartbeat_issue_json_cached "$issue_id")"
   if [[ -n "$issue_json" ]] && jq -e 'any(.labels[]?; .name == "agent-keep-open")' >/dev/null <<<"$issue_json"; then
     printf 'yes\n'
   else
@@ -259,7 +343,7 @@ heartbeat_issue_is_recurring() {
 heartbeat_issue_schedule_interval_seconds() {
   local issue_id="${1:?issue id required}"
   local issue_json issue_body
-  issue_json="$(flow_github_issue_view_json "$REPO_SLUG" "$issue_id" 2>/dev/null || true)"
+  issue_json="$(heartbeat_issue_json_cached "$issue_id")"
   if [[ -z "$issue_json" ]]; then
     issue_json='{}'
   fi
@@ -282,7 +366,7 @@ EOF
 heartbeat_issue_schedule_token() {
   local issue_id="${1:?issue id required}"
   local issue_json issue_body
-  issue_json="$(flow_github_issue_view_json "$REPO_SLUG" "$issue_id" 2>/dev/null || true)"
+  issue_json="$(heartbeat_issue_json_cached "$issue_id")"
   if [[ -z "$issue_json" ]]; then
     issue_json='{}'
   fi
@@ -321,7 +405,7 @@ heartbeat_issue_is_scheduled() {
 heartbeat_issue_is_exclusive() {
   local issue_id="${1:?issue id required}"
   local issue_json
-  issue_json="$(flow_github_issue_view_json "$REPO_SLUG" "$issue_id" 2>/dev/null || true)"
+  issue_json="$(heartbeat_issue_json_cached "$issue_id")"
   if [[ -n "$issue_json" ]] && jq -e --arg exclusiveLabel "${AGENT_EXCLUSIVE_LABEL}" 'any(.labels[]?; .name == $exclusiveLabel)' >/dev/null <<<"$issue_json"; then
     printf 'yes\n'
   else
@@ -379,7 +463,7 @@ heartbeat_sync_issue_labels() {
   local -a add_args=()
   local -a update_args=()
 
-  issue_json="$(flow_github_issue_view_json "$REPO_SLUG" "$issue_id" 2>/dev/null || true)"
+  issue_json="$(heartbeat_issue_json_cached "$issue_id")"
   if [[ -z "$issue_json" ]]; then
     return 0
   fi
@@ -501,6 +585,52 @@ heartbeat_issue_resident_worker_key() {
   flow_resident_issue_lane_key "${CODING_WORKER}" "safe" "${lane_kind}" "${lane_value}"
 }
 
+heartbeat_pending_issue_launch_pid() {
+  local issue_id="${1:?issue id required}"
+  local pending_file pid=""
+
+  pending_file="${PENDING_LAUNCH_DIR}/issue-${issue_id}.pid"
+  [[ -f "${pending_file}" ]] || return 1
+
+  pid="$(tr -d '[:space:]' <"${pending_file}" 2>/dev/null || true)"
+  [[ "${pid}" =~ ^[0-9]+$ ]] || return 1
+  kill -0 "${pid}" 2>/dev/null || return 1
+
+  printf '%s\n' "${pid}"
+}
+
+heartbeat_pending_resident_lane_launch_issue_id() {
+  local issue_id="${1:?issue id required}"
+  local worker_key=""
+  local pending_file=""
+  local candidate_issue_id=""
+  local candidate_worker_key=""
+
+  worker_key="$(heartbeat_issue_resident_worker_key "${issue_id}")"
+  [[ -n "${worker_key}" ]] || return 1
+  [[ -d "${PENDING_LAUNCH_DIR}" ]] || return 1
+
+  for pending_file in "${PENDING_LAUNCH_DIR}"/issue-*.pid; do
+    [[ -f "${pending_file}" ]] || continue
+    candidate_issue_id="${pending_file##*/issue-}"
+    candidate_issue_id="${candidate_issue_id%.pid}"
+    [[ -n "${candidate_issue_id}" ]] || continue
+    if ! heartbeat_pending_issue_launch_pid "${candidate_issue_id}" >/dev/null 2>&1; then
+      rm -f "${pending_file}" 2>/dev/null || true
+      continue
+    fi
+    if [[ "$(heartbeat_issue_uses_resident_loop "${candidate_issue_id}")" != "yes" ]]; then
+      continue
+    fi
+    candidate_worker_key="$(heartbeat_issue_resident_worker_key "${candidate_issue_id}")"
+    [[ -n "${candidate_worker_key}" && "${candidate_worker_key}" == "${worker_key}" ]] || continue
+    printf '%s\n' "${candidate_issue_id}"
+    return 0
+  done
+
+  return 1
+}
+
 heartbeat_live_issue_controller_for_lane() {
   local issue_id="${1:?issue id required}"
   local worker_key=""
@@ -548,11 +678,20 @@ heartbeat_enqueue_issue_for_resident_controller() {
 
 heartbeat_start_issue_worker() {
   local issue_id="${1:?issue id required}"
+  local pending_lane_issue_id=""
   if [[ "$(heartbeat_issue_uses_resident_loop "${issue_id}")" == "yes" ]]; then
     if heartbeat_enqueue_issue_for_live_resident_lane "${issue_id}"; then
       printf 'LAUNCH_MODE=resident-lease\n'
       return 0
     fi
+    pending_lane_issue_id="$(heartbeat_pending_resident_lane_launch_issue_id "${issue_id}" || true)"
+    if [[ -n "${pending_lane_issue_id}" ]]; then
+      if [[ "${pending_lane_issue_id}" != "${issue_id}" ]]; then
+        flow_resident_issue_enqueue "${CONFIG_YAML}" "${issue_id}" "heartbeat-pending-lane" >/dev/null
+      fi
+      printf 'LAUNCH_MODE=resident-pending-lane\n'
+      return 0
+    fi
     if heartbeat_enqueue_issue_for_resident_controller "${issue_id}"; then
       printf 'LAUNCH_MODE=resident-lease\n'
       return 0

package/hooks/issue-reconcile-hooks.sh

@@ -12,7 +12,9 @@ ADAPTER_BIN_DIR="${FLOW_SKILL_DIR}/bin"
 FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
 REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
 AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
 STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+DEFAULT_BRANCH="$(flow_resolve_default_branch "${CONFIG_YAML}")"
 RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
 BLOCKED_RECOVERY_STATE_DIR="${STATE_ROOT}/blocked-recovery-issues"
 
@@ -26,6 +28,49 @@ issue_clear_blocked_recovery_state() {
   rm -f "${BLOCKED_RECOVERY_STATE_DIR}/${ISSUE_ID}.env" 2>/dev/null || true
 }
 
+issue_retry_state_file() {
+  printf '%s/retries/issues/%s.env\n' "${STATE_ROOT}" "${ISSUE_ID}"
+}
+
+issue_reason_requires_baseline_change() {
+  local reason="${1:-}"
+  case "${reason}" in
+    verification-guard-blocked|no-publishable-commits|no-publishable-delta)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+issue_current_baseline_head_sha() {
+  local head_sha=""
+  if [[ -d "${AGENT_REPO_ROOT}" ]]; then
+    head_sha="$(git -C "${AGENT_REPO_ROOT}" rev-parse --verify --quiet "origin/${DEFAULT_BRANCH}" 2>/dev/null || true)"
+    if [[ -z "${head_sha}" ]]; then
+      head_sha="$(git -C "${AGENT_REPO_ROOT}" rev-parse --verify --quiet "${DEFAULT_BRANCH}" 2>/dev/null || true)"
+    fi
+  fi
+  printf '%s\n' "${head_sha}"
+}
+
+issue_record_retry_baseline_gate() {
+  local reason="${1:-}"
+  local state_file head_sha tmp_file
+
+  issue_reason_requires_baseline_change "${reason}" || return 0
+  state_file="$(issue_retry_state_file)"
+  [[ -f "${state_file}" ]] || return 0
+  head_sha="$(issue_current_baseline_head_sha)"
+  [[ -n "${head_sha}" ]] || return 0
+
+  tmp_file="$(mktemp)"
+  grep -v '^BASELINE_HEAD_SHA=' "${state_file}" >"${tmp_file}" || true
+  printf 'BASELINE_HEAD_SHA=%s\n' "${head_sha}" >>"${tmp_file}"
+  mv "${tmp_file}" "${state_file}"
+}
+
 issue_has_schedule_cadence() {
   local issue_json issue_body
   issue_json="$(flow_github_issue_view_json "${REPO_SLUG}" "${ISSUE_ID}" 2>/dev/null || true)"
@@ -155,6 +200,7 @@ issue_schedule_retry() {
     return 0
   fi
   "${FLOW_TOOLS_DIR}/retry-state.sh" issue "$ISSUE_ID" schedule "$reason" >/dev/null || true
+  issue_record_retry_baseline_gate "${reason}"
 }
 
 issue_mark_ready() {

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

@@ -156,7 +156,7 @@ function createExecutionContext(stage) {
 }
 
 function runScriptWithContext(context, scriptRelativePath, forwardedArgs, options = {}) {
-  const scriptPath = path.join(packageRoot, scriptRelativePath);
+  const scriptPath = options.scriptPath || path.join(packageRoot, scriptRelativePath);
   const stdio = options.stdio || "inherit";
   const result = spawnSync("bash", [scriptPath, ...forwardedArgs], {
     stdio,
@@ -175,11 +175,78 @@ function runScriptWithContext(context, scriptRelativePath, forwardedArgs, option
   };
 }
 
+function resolvePersistentSourceHome(context) {
+  if (process.env.ACP_PROJECT_RUNTIME_SOURCE_HOME) {
+    return process.env.ACP_PROJECT_RUNTIME_SOURCE_HOME;
+  }
+  if (fs.existsSync(path.join(packageRoot, ".git"))) {
+    return packageRoot;
+  }
+  return context.runtimeHome;
+}
+
+function runtimeSkillRoot(context) {
+  return path.join(context.runtimeHome, "skills", "openclaw", skillName);
+}
+
+function createRuntimeExecutionContext(context) {
+  const stableSkillRoot = runtimeSkillRoot(context);
+  const persistentSourceHome = resolvePersistentSourceHome(context);
+  const runtimeScriptEnv = {
+    ACP_PROJECT_RUNTIME_SYNC_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_SYNC_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "sync-shared-agent-home.sh"),
+    ACP_PROJECT_RUNTIME_ENSURE_SYNC_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_ENSURE_SYNC_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "ensure-runtime-sync.sh"),
+    ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "project-launchd-bootstrap.sh"),
+    ACP_PROJECT_RUNTIME_SUPERVISOR_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_SUPERVISOR_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "project-runtime-supervisor.sh"),
+    ACP_PROJECT_RUNTIME_KICK_SCRIPT:
+      context.env.ACP_PROJECT_RUNTIME_KICK_SCRIPT || path.join(stableSkillRoot, "tools", "bin", "kick-scheduler.sh")
+  };
+  return {
+    ...context,
+    stableSkillRoot,
+    persistentSourceHome,
+    env: {
+      ...context.env,
+      SHARED_AGENT_HOME: context.runtimeHome,
+      AGENT_CONTROL_PLANE_ROOT: stableSkillRoot,
+      ACP_ROOT: stableSkillRoot,
+      AGENT_FLOW_SOURCE_ROOT: stableSkillRoot,
+      ACP_PROJECT_INIT_SOURCE_HOME: persistentSourceHome,
+      ACP_PROJECT_RUNTIME_SOURCE_HOME: persistentSourceHome,
+      ACP_DASHBOARD_SOURCE_HOME: persistentSourceHome,
+      ...runtimeScriptEnv
+    }
+  };
+}
+
+function syncRuntimeHome(context, options = {}) {
+  const result = runScriptWithContext(context, "tools/bin/sync-shared-agent-home.sh", [], {
+    stdio: options.stdio || "inherit"
+  });
+  if (result.status !== 0) {
+    throw new Error("failed to sync runtime home before command execution");
+  }
+}
+
 function runCommand(scriptRelativePath, forwardedArgs) {
   const stage = stageSharedHome();
   const context = createExecutionContext(stage);
 
   try {
+    if (scriptRelativePath !== "tools/bin/sync-shared-agent-home.sh") {
+      syncRuntimeHome(context, { stdio: "inherit" });
+      const runtimeContext = createRuntimeExecutionContext(context);
+      const runtimeScriptPath = path.join(runtimeContext.stableSkillRoot, scriptRelativePath);
+      const result = runScriptWithContext(runtimeContext, scriptRelativePath, forwardedArgs, {
+        stdio: "inherit",
+        scriptPath: runtimeScriptPath
+      });
+      return result.status;
+    }
+
     const result = runScriptWithContext(context, scriptRelativePath, forwardedArgs, { stdio: "inherit" });
     return result.status;
   } finally {
@@ -1470,8 +1537,8 @@ async function maybeRunFinalSetupFixups(options, scopedContext, config, currentS
       runtimeStartReason = `doctor-${doctorKv.DOCTOR_STATUS || "not-ok"}`;
     } else {
       actions.push("runtime-start");
-      runSetupStep(scopedContext, "Start the runtime", "tools/bin/project-runtimectl.sh", ["start", "--profile-id", config.profileId]);
-      const runtimeStatusOutput = runSetupStep(scopedContext, "Read back runtime status", "tools/bin/project-runtimectl.sh", ["status", "--profile-id", config.profileId]);
+      runSetupStep(scopedContext, "Start the runtime", "tools/bin/project-runtimectl.sh", ["start", "--profile-id", config.profileId], { useRuntimeCopy: true });
+      const runtimeStatusOutput = runSetupStep(scopedContext, "Read back runtime status", "tools/bin/project-runtimectl.sh", ["status", "--profile-id", config.profileId], { useRuntimeCopy: true });
       runtimeStatusKv = parseKvOutput(runtimeStatusOutput);
       runtimeStartStatus = "ok";
       runtimeStartReason = "";
@@ -1480,7 +1547,7 @@ async function maybeRunFinalSetupFixups(options, scopedContext, config, currentS
 
   if (config.installLaunchd && process.platform === "darwin" && launchdInstallStatus !== "ok" && runtimeStartStatus === "ok") {
     actions.push("launchd-install");
-    runSetupStep(scopedContext, "Install macOS autostart", "tools/bin/install-project-launchd.sh", ["--profile-id", config.profileId]);
+    runSetupStep(scopedContext, "Install macOS autostart", "tools/bin/install-project-launchd.sh", ["--profile-id", config.profileId], { useRuntimeCopy: true });
     launchdInstallStatus = "ok";
     launchdInstallReason = "";
   }
@@ -1603,7 +1670,21 @@ async function collectSetupConfig(options, context) {
 
 function runSetupStep(context, title, scriptRelativePath, args, options = {}) {
   console.log(`\n== ${title} ==`);
-  const result = runScriptWithContext(context, scriptRelativePath, args, { stdio: "pipe", env: options.env, cwd: options.cwd });
+  let executionContext = context;
+  let scriptPath = undefined;
+
+  if (options.useRuntimeCopy) {
+    syncRuntimeHome(context, { stdio: "pipe" });
+    executionContext = createRuntimeExecutionContext(context);
+    scriptPath = path.join(executionContext.stableSkillRoot, scriptRelativePath);
+  }
+
+  const result = runScriptWithContext(executionContext, scriptRelativePath, args, {
+    stdio: "pipe",
+    env: options.env,
+    cwd: options.cwd,
+    scriptPath
+  });
   if (result.status !== 0) {
     printFailureDetails(result);
     throw new Error(`${title} failed`);
@@ -1868,8 +1949,8 @@ async function runSetupFlow(forwardedArgs) {
         runtimeStartReason = "gh-auth-not-ready";
         console.log("runtime start skipped: GitHub CLI is not authenticated yet. Run `gh auth login` and start the runtime afterwards.");
       } else {
-        runSetupStep(scopedContext, "Start the runtime", "tools/bin/project-runtimectl.sh", ["start", "--profile-id", config.profileId]);
-        const runtimeStatusOutput = runSetupStep(scopedContext, "Read back runtime status", "tools/bin/project-runtimectl.sh", ["status", "--profile-id", config.profileId]);
+        runSetupStep(scopedContext, "Start the runtime", "tools/bin/project-runtimectl.sh", ["start", "--profile-id", config.profileId], { useRuntimeCopy: true });
+        const runtimeStatusOutput = runSetupStep(scopedContext, "Read back runtime status", "tools/bin/project-runtimectl.sh", ["status", "--profile-id", config.profileId], { useRuntimeCopy: true });
         runtimeStatusKv = parseKvOutput(runtimeStatusOutput);
         runtimeStartStatus = "ok";
         runtimeStartReason = "";
@@ -1886,7 +1967,7 @@ async function runSetupFlow(forwardedArgs) {
         launchdInstallReason = "runtime-not-started";
         console.log("launchd install skipped: runtime was not started successfully in this setup run.");
       } else {
-        runSetupStep(scopedContext, "Install macOS autostart", "tools/bin/install-project-launchd.sh", ["--profile-id", config.profileId]);
+        runSetupStep(scopedContext, "Install macOS autostart", "tools/bin/install-project-launchd.sh", ["--profile-id", config.profileId], { useRuntimeCopy: true });
         launchdInstallStatus = "ok";
         launchdInstallReason = "";
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.1.9",
+  "version": "0.1.13",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {
@@ -21,11 +21,17 @@
     "README.md",
     "SKILL.md",
     "assets/workflow-catalog.json",
-    "bin",
+    "bin/agent-control-plane",
+    "bin/issue-resource-class.sh",
+    "bin/label-follow-up-issues.sh",
+    "bin/pr-risk.sh",
+    "bin/sync-pr-labels.sh",
     "hooks",
     "npm/bin",
     "references",
     "tools/bin",
+    "!tools/bin/audit-*.sh",
+    "!tools/bin/check-skill-contracts.sh",
     "tools/dashboard/app.js",
     "tools/dashboard/dashboard_snapshot.py",
     "tools/dashboard/index.html",

package/references/commands.md

@@ -76,6 +76,7 @@ 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 sync --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>

package/tools/bin/agent-project-cleanup-session

@@ -15,6 +15,7 @@ shared_agent_home="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 repo_root="${AGENT_PROJECT_REPO_ROOT:-}"
 runs_root="${AGENT_PROJECT_RUNS_ROOT:-}"
 history_root="${AGENT_PROJECT_HISTORY_ROOT:-}"
+state_root="${AGENT_PROJECT_STATE_ROOT:-${F_LOSNING_STATE_ROOT:-}}"
 session=""
 worktree_path=""
 mode="generic"
@@ -30,6 +31,7 @@ while [[ $# -gt 0 ]]; do
     --repo-root) repo_root="${2:-}"; shift 2 ;;
     --runs-root) runs_root="${2:-}"; shift 2 ;;
     --history-root) history_root="${2:-}"; shift 2 ;;
+    --state-root) state_root="${2:-}"; shift 2 ;;
     --session) session="${2:-}"; shift 2 ;;
     --worktree) worktree_path="${2:-}"; shift 2 ;;
     --mode) mode="${2:-}"; shift 2 ;;
@@ -141,6 +143,131 @@ path_is_within_root() {
   [[ "$target_canonical" == "$root_canonical" || "$target_canonical" == "$root_canonical"/* ]]
 }
 
+derive_state_root() {
+  if [[ -n "${state_root}" && -d "${state_root}" ]]; then
+    printf '%s\n' "${state_root}"
+    return 0
+  fi
+
+  if [[ -n "${runs_root}" && -d "${runs_root}" ]]; then
+    local candidate_root=""
+    candidate_root="$(cd "${runs_root}/.." 2>/dev/null && pwd -P || true)"
+    if [[ -n "${candidate_root}" && -d "${candidate_root}/state" ]]; then
+      printf '%s/state\n' "${candidate_root}"
+      return 0
+    fi
+  fi
+
+  return 1
+}
+
+resident_worktree_protected() {
+  local candidate_path="${1:-}"
+  local resolved_candidate=""
+  local resolved_state_root=""
+  local metadata_file=""
+  local resident_worktree=""
+  local resident_realpath=""
+  local resolved_resident=""
+
+  [[ -n "${candidate_path}" && -d "${candidate_path}" ]] || return 1
+  resolved_candidate="$(canonicalize_existing_dir "${candidate_path}" || true)"
+  [[ -n "${resolved_candidate}" ]] || return 1
+
+  resolved_state_root="$(derive_state_root || true)"
+  [[ -n "${resolved_state_root}" && -d "${resolved_state_root}/resident-workers/issues" ]] || return 1
+
+  for metadata_file in "${resolved_state_root}"/resident-workers/issues/*/metadata.env; do
+    [[ -f "${metadata_file}" ]] || continue
+    resident_worktree=""
+    resident_realpath=""
+    set +u
+    set -a
+    # shellcheck source=/dev/null
+    source "${metadata_file}"
+    set +a
+    set -u
+    resident_worktree="${WORKTREE_REALPATH:-${WORKTREE:-}}"
+    [[ -n "${resident_worktree}" && -d "${resident_worktree}" ]] || continue
+    resolved_resident="$(canonicalize_existing_dir "${resident_worktree}" || true)"
+    [[ -n "${resolved_resident}" ]] || continue
+    if [[ "${resolved_candidate}" == "${resolved_resident}" ]]; then
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+active_resident_run_worktree_protected() {
+  local candidate_path="${1:-}"
+  local resolved_candidate=""
+  local run_meta=""
+  local run_dir=""
+  local session_name=""
+  local resident_enabled=""
+  local resident_worktree=""
+  local runner_state_file=""
+  local runner_state=""
+  local active_session="false"
+  local resolved_resident=""
+
+  [[ -n "${candidate_path}" && -d "${candidate_path}" ]] || return 1
+  [[ -n "${runs_root}" && -d "${runs_root}" ]] || return 1
+
+  resolved_candidate="$(canonicalize_existing_dir "${candidate_path}" || true)"
+  [[ -n "${resolved_candidate}" ]] || return 1
+
+  for run_meta in "${runs_root}"/*/run.env; do
+    [[ -f "${run_meta}" ]] || continue
+
+    session_name=""
+    resident_enabled=""
+    resident_worktree=""
+    runner_state=""
+    active_session="false"
+
+    set +u
+    set -a
+    # shellcheck source=/dev/null
+    source "${run_meta}"
+    set +a
+    set -u
+
+    resident_enabled="${RESIDENT_WORKER_ENABLED:-no}"
+    [[ "${resident_enabled}" == "yes" ]] || continue
+
+    resident_worktree="${WORKTREE_REALPATH:-${WORKTREE:-}}"
+    [[ -n "${resident_worktree}" && -d "${resident_worktree}" ]] || continue
+    resolved_resident="$(canonicalize_existing_dir "${resident_worktree}" || true)"
+    [[ -n "${resolved_resident}" ]] || continue
+    [[ "${resolved_candidate}" == "${resolved_resident}" ]] || continue
+
+    run_dir="$(dirname "${run_meta}")"
+    runner_state_file="${run_dir}/runner.env"
+    if [[ -f "${runner_state_file}" ]]; then
+      set +u
+      set -a
+      # shellcheck source=/dev/null
+      source "${runner_state_file}"
+      set +a
+      set -u
+      runner_state="${RUNNER_STATE:-}"
+    fi
+
+    session_name="${SESSION:-}"
+    if [[ -n "${session_name}" ]] && tmux has-session -t "${session_name}" 2>/dev/null; then
+      active_session="true"
+    fi
+
+    if [[ "${runner_state}" == "running" || "${active_session}" == "true" ]]; then
+      return 0
+    fi
+  done
+
+  return 1
+}
+
 cleanup_with_branch_tool() {
   local include_path="${1:-yes}"
   local -a cleanup_args
@@ -185,6 +312,9 @@ cleanup_orphan_worktree_dir() {
 
 if [[ "$active_tmux_session" == "true" ]]; then
   cleanup_mode="deferred-active-session"
+elif [[ "$skip_worktree_cleanup" != "true" && -n "${worktree_path}" ]] \
+  && { resident_worktree_protected "${worktree_path}" || active_resident_run_worktree_protected "${worktree_path}"; }; then
+  cleanup_mode="protected-resident-worktree"
 elif [[ "$skip_worktree_cleanup" != "true" && -n "$branch_name" ]]; then
   if cleanup_output="$(cleanup_with_branch_tool yes 2>&1)"; then
     cleanup_mode="branch"
@@ -207,6 +337,9 @@ elif [[ "$skip_worktree_cleanup" != "true" && -n "$worktree_path" ]] && git -C "
   git -C "$repo_root" worktree remove "$worktree_path" --force || true
   git -C "$repo_root" worktree prune
   cleanup_mode="worktree"
+elif [[ "$skip_worktree_cleanup" != "true" ]] && cleanup_orphan_worktree_dir; then
+  orphan_fallback_used="true"
+  cleanup_mode="orphan-worktree"
 elif [[ "$skip_worktree_cleanup" == "true" ]]; then
   cleanup_mode="archived-only"
 fi