agent-control-plane 0.1.9 → 0.1.12

package/hooks/heartbeat-hooks.sh

@@ -15,15 +15,40 @@ 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}")"
+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_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 +73,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() {
@@ -124,7 +156,7 @@ heartbeat_issue_blocked_recovery_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 +195,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 +282,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 +293,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 +316,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 +355,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 +413,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 +535,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 +628,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "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