agent-control-plane 0.1.8 → 0.1.12

package/bin/pr-risk.sh

@@ -22,11 +22,32 @@ if [[ -f "${PR_LANE_OVERRIDE_FILE}" ]]; then
   source "${PR_LANE_OVERRIDE_FILE}" || true
 fi
 
-PR_JSON="$(gh pr view "$PR_NUMBER" -R "$REPO_SLUG" --json number,title,url,body,isDraft,headRefName,baseRefName,labels,files,mergeStateStatus,reviewDecision,reviewRequests,statusCheckRollup,comments)"
-PR_HEAD_SHA="$(gh api "repos/${REPO_SLUG}/pulls/${PR_NUMBER}" --jq .head.sha)"
-PR_HEAD_COMMITTED_AT="$(gh api "repos/${REPO_SLUG}/commits/${PR_HEAD_SHA}" --jq .commit.committer.date 2>/dev/null || true)"
-REVIEW_COMMENTS_JSON="$(gh api "repos/${REPO_SLUG}/pulls/${PR_NUMBER}/comments")"
-CHECK_RUNS_JSON="$(gh api "repos/${REPO_SLUG}/commits/${PR_HEAD_SHA}/check-runs" 2>/dev/null || printf '{"check_runs":[]}')"
+gh_api_json_matching_or_fallback() {
+  local fallback="${1:?fallback required}"
+  local jq_filter="${2:?jq filter required}"
+  shift 2
+  local output=""
+
+  output="$(gh api "$@" 2>/dev/null || true)"
+  if jq -e "${jq_filter}" >/dev/null 2>&1 <<<"${output}"; then
+    printf '%s\n' "${output}"
+    return 0
+  fi
+
+  printf '%s\n' "${fallback}"
+}
+
+PR_JSON="$(gh pr view "$PR_NUMBER" -R "$REPO_SLUG" --json number,title,url,body,isDraft,headRefName,headRefOid,baseRefName,labels,files,mergeStateStatus,reviewDecision,reviewRequests,statusCheckRollup,comments)"
+PR_HEAD_SHA="$(jq -r '.headRefOid // ""' <<<"$PR_JSON")"
+PR_HEAD_COMMITTED_AT=""
+if [[ -n "${PR_HEAD_SHA}" ]]; then
+  PR_HEAD_COMMITTED_AT="$(gh api "repos/${REPO_SLUG}/commits/${PR_HEAD_SHA}" --jq .commit.committer.date 2>/dev/null || true)"
+fi
+REVIEW_COMMENTS_JSON="$(gh_api_json_matching_or_fallback '[]' 'type == "array"' "repos/${REPO_SLUG}/pulls/${PR_NUMBER}/comments")"
+CHECK_RUNS_JSON='{"check_runs":[]}'
+if [[ -n "${PR_HEAD_SHA}" ]]; then
+  CHECK_RUNS_JSON="$(gh_api_json_matching_or_fallback '{"check_runs":[]}' 'type == "object" and ((.check_runs // []) | type == "array")' "repos/${REPO_SLUG}/commits/${PR_HEAD_SHA}/check-runs")"
+fi
 
 PR_JSON="$PR_JSON" PR_HEAD_SHA="$PR_HEAD_SHA" PR_HEAD_COMMITTED_AT="$PR_HEAD_COMMITTED_AT" REVIEW_COMMENTS_JSON="$REVIEW_COMMENTS_JSON" CHECK_RUNS_JSON="$CHECK_RUNS_JSON" PR_LANE_OVERRIDE="${PR_LANE_OVERRIDE:-}" MANAGED_PR_PREFIXES_JSON="$MANAGED_PR_PREFIXES_JSON" MANAGED_PR_ISSUE_CAPTURE_REGEX="$MANAGED_PR_ISSUE_CAPTURE_REGEX" ALLOW_INFRA_CI_BYPASS="$ALLOW_INFRA_CI_BYPASS" LOCAL_FIRST_PR_POLICY="$LOCAL_FIRST_PR_POLICY" node <<'EOF'
 const { execFileSync } = require('node:child_process');
@@ -251,16 +272,39 @@ const riskReason =
         ? `paths-within-critical-app-allowlist:${criticalAppFiles.join(',')}`
         : `paths-outside-low-risk-allowlist:${disallowed.join(',')}`;
 
+const normalizeRollupCheck = (check) => {
+  const typename = String(check?.__typename || '');
+  if (typename === 'StatusContext') {
+    const name = String(check?.context || 'status-context');
+    const state = String(check?.state || '').toUpperCase();
+    return {
+      name,
+      status: state === 'SUCCESS' || state === 'FAILURE' || state === 'ERROR' ? 'COMPLETED' : state,
+      conclusion: state === 'SUCCESS' ? 'SUCCESS' : state === 'FAILURE' || state === 'ERROR' ? 'FAILURE' : '',
+      reasonField: 'state',
+      rawStatus: String(check?.state || '').toLowerCase() || 'unknown',
+    };
+  }
+
+  return {
+    name: String(check?.name || check?.workflowName || 'check-run'),
+    status: String(check?.status || '').toUpperCase(),
+    conclusion: String(check?.conclusion || '').toUpperCase(),
+    reasonField: 'status',
+    rawStatus: String(check?.status || '').toLowerCase() || 'unknown',
+  };
+};
+
 const pendingChecks = [];
 const checkFailures = [];
-for (const check of checks) {
+for (const rawCheck of checks) {
+  const check = normalizeRollupCheck(rawCheck);
   if (check.status !== 'COMPLETED') {
-    pendingChecks.push(`${check.name}:status-${String(check.status || '').toLowerCase()}`);
+    pendingChecks.push(`${check.name}:${check.reasonField}-${check.rawStatus}`);
     continue;
   }
-  const conclusion = String(check.conclusion || '').toUpperCase();
-  if (conclusion !== 'SUCCESS' && conclusion !== 'SKIPPED') {
-    checkFailures.push(`${check.name}:conclusion-${String(check.conclusion || '').toLowerCase()}`);
+  if (check.conclusion !== 'SUCCESS' && check.conclusion !== 'SKIPPED') {
+    checkFailures.push(`${check.name}:conclusion-${String(check.conclusion || '').toLowerCase() || 'unknown'}`);
   }
 }
 

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,11 +73,18 @@ 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() {
   local open_agent_pr_issue_ids
-  local ready_issue_rows issue_id is_blocked retry_out retry_reason
+  local ready_issue_rows issue_id is_blocked retry_reason
   open_agent_pr_issue_ids="$(heartbeat_open_agent_pr_issue_ids)"
 
   ready_issue_rows="$(
@@ -73,8 +105,7 @@ heartbeat_list_ready_issue_ids() {
     [[ -n "${issue_id:-}" ]] || continue
 
     if [[ "${is_blocked:-false}" == "true" ]]; then
-      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:-}")"
+      retry_reason="$(heartbeat_issue_blocked_recovery_reason "$issue_id")"
       if [[ -z "${retry_reason:-}" ]]; then
         continue
       fi
@@ -87,7 +118,7 @@ heartbeat_list_ready_issue_ids() {
 
 heartbeat_list_blocked_recovery_issue_ids() {
   local open_agent_pr_issue_ids
-  local blocked_issue_rows issue_id retry_out retry_reason
+  local blocked_issue_rows issue_id retry_reason
   open_agent_pr_issue_ids="$(heartbeat_open_agent_pr_issue_ids)"
 
   blocked_issue_rows="$(
@@ -105,8 +136,7 @@ heartbeat_list_blocked_recovery_issue_ids() {
 
   while IFS= read -r issue_id; do
     [[ -n "${issue_id:-}" ]] || continue
-    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:-}")"
+    retry_reason="$(heartbeat_issue_blocked_recovery_reason "$issue_id")"
     if [[ -z "${retry_reason:-}" ]]; then
       continue
     fi
@@ -115,6 +145,74 @@ heartbeat_list_blocked_recovery_issue_ids() {
   done <<<"$blocked_issue_rows"
 }
 
+heartbeat_issue_blocked_recovery_reason() {
+  local issue_id="${1:?issue id required}"
+  local retry_out retry_reason issue_json
+
+  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
+    printf '%s\n' "$retry_reason"
+    return 0
+  fi
+
+  issue_json="$(heartbeat_issue_json_cached "$issue_id")"
+  if [[ -z "${issue_json:-}" ]]; then
+    return 0
+  fi
+
+  ISSUE_JSON="${issue_json}" RETRY_REASON="${retry_reason:-}" node <<'EOF'
+const issue = JSON.parse(process.env.ISSUE_JSON || '{}');
+const labels = new Set((issue.labels || []).map((label) => label?.name).filter(Boolean));
+
+if (!labels.has('agent-blocked')) {
+  process.exit(0);
+}
+
+const blockerComment = [...(issue.comments || [])]
+  .reverse()
+  .find((comment) =>
+    /Host-side publish blocked for session|Host-side publish failed for session|Blocked on missing referenced OpenSpec paths for issue|Superseded by focused follow-up issues:|Why it was blocked:|^# Blocker:/i.test(
+      comment?.body || '',
+    ),
+  );
+
+if (!blockerComment || !blockerComment.body) {
+  process.exit(0);
+}
+
+const body = String(blockerComment.body);
+let reason = '';
+
+const explicitFailureReason = body.match(/Failure reason:\s*[\r\n]+-\s*`([^`]+)`/i);
+if (explicitFailureReason) {
+  reason = explicitFailureReason[1];
+} else if (/provider quota is currently exhausted|provider-side rate limit|quota window/i.test(body)) {
+  reason = 'provider-quota-limit';
+} else if (/no publishable delta|no commits ahead of `?origin\/main`?/i.test(body)) {
+  reason = 'no-publishable-delta';
+} else if (/scope guard/i.test(body)) {
+  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)) {
+  reason = 'superseded-by-follow-ups';
+} else if (/^# Blocker:/im.test(body)) {
+  reason = 'comment-blocked-recovery';
+}
+
+  if (reason) {
+    process.stdout.write(`${reason}\n`);
+  } else if ((process.env.RETRY_REASON || '').trim()) {
+    process.stdout.write(`${String(process.env.RETRY_REASON).trim()}\n`);
+  }
+EOF
+}
+
 heartbeat_list_exclusive_issue_ids() {
   local open_agent_pr_issue_ids
   open_agent_pr_issue_ids="$(heartbeat_open_agent_pr_issue_ids)"
@@ -184,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
@@ -195,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
@@ -218,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
@@ -257,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
@@ -315,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
@@ -437,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=""
@@ -484,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.8",
+  "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 ;;
@@ -92,6 +94,7 @@ cleanup_status="0"
 cleanup_error=""
 cleanup_mode="noop"
 orphan_fallback_used="false"
+active_tmux_session="false"
 
 if [[ -n "$session" ]]; then
   meta_file="${runs_root}/${session}/run.env"
@@ -112,6 +115,10 @@ if [[ -z "$remove_file" ]]; then
   remove_file="$result_file"
 fi
 
+if [[ -n "$session" ]] && tmux has-session -t "$session" 2>/dev/null; then
+  active_tmux_session="true"
+fi
+
 cleanup_tool="${shared_agent_home}/tools/bin/agent-cleanup-worktree"
 archive_tool="${shared_agent_home}/tools/bin/agent-project-archive-run"
 
@@ -136,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
@@ -178,7 +310,12 @@ cleanup_orphan_worktree_dir() {
   git -C "$repo_root" worktree prune >/dev/null 2>&1 || true
 }
 
-if [[ "$skip_worktree_cleanup" != "true" && -n "$branch_name" ]]; then
+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"
   else
@@ -200,12 +337,15 @@ 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
 
 archive_output=""
-if [[ -n "$session" ]]; then
+if [[ -n "$session" && "$active_tmux_session" != "true" ]]; then
   archive_output="$(
     "$archive_tool" \
       --runs-root "$runs_root" \
@@ -227,6 +367,7 @@ printf 'BRANCH=%s\n' "$branch_name"
 printf 'KEEP_REMOTE=%s\n' "$keep_remote"
 printf 'ALLOW_UNMERGED=%s\n' "$allow_unmerged"
 printf 'SKIP_WORKTREE_CLEANUP=%s\n' "$skip_worktree_cleanup"
+printf 'ACTIVE_TMUX_SESSION=%s\n' "$active_tmux_session"
 printf 'CLEANUP_MODE=%s\n' "$cleanup_mode"
 printf 'ORPHAN_FALLBACK_USED=%s\n' "$orphan_fallback_used"
 printf 'CLEANUP_STATUS=%s\n' "$cleanup_status"

package/tools/bin/agent-project-heartbeat-loop

@@ -929,6 +929,9 @@ running_recurring_issue_workers() {
       count=$((count + 1))
     fi
   done <<<"$running_issue_workers_cache"
+  # Also count pending recurring launches that are still in progress
+  # (prevents infinite respawning when workers die before creating tmux sessions)
+  count=$((count + $(pending_recurring_issue_launch_count)))
   printf '%s\n' "$count"
 }
 
@@ -1120,9 +1123,11 @@ build_ordered_ready_issue_ids_cache() {
 
   last_recurring_issue="$(last_launched_recurring_issue_id || true)"
   if [[ -n "$last_recurring_issue" ]]; then
+    local emitted_after_last=0
     for issue_id in "${recurring_ids[@]}"; do
       if [[ "$seen_last" == "yes" ]]; then
         printf '%s\n' "$issue_id"
+        emitted_after_last=$((emitted_after_last + 1))
       fi
       if [[ "$issue_id" == "$last_recurring_issue" ]]; then
         seen_last="yes"
@@ -1131,7 +1136,12 @@ build_ordered_ready_issue_ids_cache() {
   fi
 
   for issue_id in "${recurring_ids[@]}"; do
-    if [[ -n "$last_recurring_issue" && "$seen_last" == "yes" && "$issue_id" == "$last_recurring_issue" ]]; then
+    # Stop the wrap-around once we reach the last-launched issue, but only
+    # when the first loop already emitted at least one issue after it.
+    # When there is exactly one recurring issue (or the last-launched issue
+    # is the final element), emitted_after_last is 0, so we must still
+    # include it here to avoid producing an empty list.
+    if [[ -n "$last_recurring_issue" && "$seen_last" == "yes" && "$issue_id" == "$last_recurring_issue" && "$emitted_after_last" -gt 0 ]]; then
       break
     fi
     printf '%s\n' "$issue_id"
@@ -1143,6 +1153,21 @@ completed_workers() {
   printf '%s\n' "$completed_workers_cache"
 }
 
+reconciled_marker_matches_run() {
+  local run_dir="${1:?run dir required}"
+  local marker_file="${run_dir}/reconciled.ok"
+  local run_env="${run_dir}/run.env"
+  local marker_started_at=""
+  local run_started_at=""
+
+  [[ -f "${marker_file}" && -f "${run_env}" ]] || return 1
+
+  marker_started_at="$(awk -F= '/^STARTED_AT=/{print $2}' "${marker_file}" 2>/dev/null | tr -d '"' | tail -n 1 || true)"
+  run_started_at="$(awk -F= '/^STARTED_AT=/{print $2}' "${run_env}" 2>/dev/null | tr -d '"' | tail -n 1 || true)"
+
+  [[ -n "${marker_started_at}" && -n "${run_started_at}" && "${marker_started_at}" == "${run_started_at}" ]]
+}
+
 ensure_completed_workers_cache() {
   local dir session issue_id status_line status
   if [[ "$completed_workers_cache_loaded" == "yes" ]]; then
@@ -1153,7 +1178,9 @@ ensure_completed_workers_cache() {
     [[ -d "$dir" ]] || continue
     session="${dir##*/}"
     session_matches_prefix "$session" || continue
-    [[ -f "$dir/reconciled.ok" ]] && continue
+    if reconciled_marker_matches_run "$dir"; then
+      continue
+    fi
     if [[ "$session" == "${issue_prefix}"* ]]; then
       issue_id="$(issue_id_from_session "$session" || true)"
       if [[ -n "${issue_id}" ]] && pending_issue_launch_active "${issue_id}"; then