agent-control-plane 0.2.0 → 0.3.0

package/tools/bin/agent-project-run-openclaw-session

@@ -283,6 +283,16 @@ EOF
   done
 fi
 
+# Always collect result.env from sandbox to artifact_dir
+collect_copy_snippet+=$(
+  cat <<EOF
+if [[ -f ${sandbox_run_dir_q}/result.env ]]; then
+  cp ${sandbox_run_dir_q}/result.env ${artifact_dir_q}/result.env
+fi
+EOF
+)
+collect_copy_snippet+=$'\n'
+
 reconcile_snippet=""
 if [[ -n "$reconcile_command" ]]; then
   printf -v delayed_reconcile_q '%q' "export ACP_EXPECTED_RUN_STARTED_AT=${started_at_q}; export F_LOSNING_EXPECTED_RUN_STARTED_AT=${started_at_q}; while tmux has-session -t ${session_q} 2>/dev/null; do sleep 1; done; sleep 2; $reconcile_command"

package/tools/bin/agent-project-run-opencode-session

@@ -240,6 +240,16 @@ EOF
   done
 fi
 
+# Always collect result.env from sandbox to artifact_dir
+collect_copy_snippet+=$(
+  cat <<EOF
+if [[ -f ${sandbox_run_dir_q}/result.env ]]; then
+  cp ${sandbox_run_dir_q}/result.env ${artifact_dir_q}/result.env
+fi
+EOF
+)
+collect_copy_snippet+=$'\n'
+
 reconcile_snippet=""
 if [[ -n "$reconcile_command" ]]; then
   printf -v delayed_reconcile_q '%q' "export ACP_EXPECTED_RUN_STARTED_AT=${started_at_q}; export F_LOSNING_EXPECTED_RUN_STARTED_AT=${started_at_q}; while tmux has-session -t ${session_q} 2>/dev/null; do sleep 1; done; sleep 2; $reconcile_command"

package/tools/bin/agent-project-worker-status

@@ -117,13 +117,6 @@ if [[ "$status" == "UNKNOWN" && -f "$output_file" ]]; then
   fi
 fi
 
-if [[ "$status" == "UNKNOWN" && -z "$failure_reason" ]]; then
-  failure_reason="$(failure_reason_from_output || true)"
-  if [[ -n "$failure_reason" ]]; then
-    status="FAILED"
-  fi
-fi
-
 if [[ "$status" == "UNKNOWN" && -n "$runner_state" ]]; then
   case "$runner_state" in
     running|waiting-auth-refresh|switching-account)
@@ -133,6 +126,7 @@ if [[ "$status" == "UNKNOWN" && -n "$runner_state" ]]; then
       # Check BEFORE stale result.env to avoid false SUCCEEDED when a prior
       # cycle's result.env happens to exist.
       status="FAILED"
+      failure_reason="$(failure_reason_from_output || true)"
       if [[ -z "$failure_reason" ]]; then
         failure_reason="runner-aborted-before-completion"
       fi
@@ -146,10 +140,19 @@ fi
 if [[ "$status" == "UNKNOWN" && -f "$result_file" ]]; then
   # A worker that managed to persist result.env already completed its contract,
   # even if the tmux session disappeared before the exit marker was flushed.
+  # Check BEFORE failure_reason_from_output so that a completed result.env
+  # is not overridden by transient failure text in the log.
   status="SUCCEEDED"
   result_only_completion="yes"
 fi
 
+if [[ "$status" == "UNKNOWN" && -z "$failure_reason" ]]; then
+  failure_reason="$(failure_reason_from_output || true)"
+  if [[ -n "$failure_reason" ]]; then
+    status="FAILED"
+  fi
+fi
+
 if [[ "$status" == "UNKNOWN" && -f "$output_file" ]]; then
   if rg -qi "You've hit your usage limit|You have reached your Codex usage limits|visit https://chatgpt.com/codex/settings/usage|Upgrade to Pro|rate limit exceeded|quota exceeded|usage cap (reached|exceeded)|usage quota (reached|exceeded)" "$output_file"; then
     status="FAILED"

package/tools/bin/cleanup-worktree.sh

@@ -37,11 +37,16 @@ if [[ -n "$SESSION" ]]; then
   ARGS+=(--session "$SESSION")
 fi
 
+cleanup_exit=0
 AGENT_PROJECT_WORKTREE_ROOT="$WORKTREE_ROOT" \
 F_LOSNING_WORKTREE_ROOT="$WORKTREE_ROOT" \
-  bash "${FLOW_TOOLS_DIR}/agent-project-cleanup-session" "${ARGS[@]}" >/dev/null
+  bash "${FLOW_TOOLS_DIR}/agent-project-cleanup-session" "${ARGS[@]}" >/dev/null || cleanup_exit=$?
 
 F_LOSNING_AGENT_REPO_ROOT="$AGENT_REPO_ROOT" \
 F_LOSNING_RETAINED_REPO_ROOT="$RETAINED_REPO_ROOT" \
 F_LOSNING_VSCODE_WORKSPACE_FILE="$VSCODE_WORKSPACE_FILE" \
   "${FLOW_TOOLS_DIR}/sync-vscode-workspace.sh" >/dev/null 2>&1 || true
+
+if [[ "$cleanup_exit" -ne 0 ]]; then
+  exit "$cleanup_exit"
+fi

package/tools/bin/flow-config-lib.sh

@@ -1741,6 +1741,34 @@ flow_provider_pool_pi_timeout_seconds() {
   flow_provider_pool_value "${config_file}" "${pool_name}" "pi.timeout_seconds"
 }
 
+flow_provider_pool_opencode_model() {
+  local config_file="${1:?config file required}"
+  local pool_name="${2:?pool name required}"
+
+  flow_provider_pool_value "${config_file}" "${pool_name}" "opencode.model"
+}
+
+flow_provider_pool_opencode_timeout_seconds() {
+  local config_file="${1:?config file required}"
+  local pool_name="${2:?pool name required}"
+
+  flow_provider_pool_value "${config_file}" "${pool_name}" "opencode.timeout_seconds"
+}
+
+flow_provider_pool_kilo_model() {
+  local config_file="${1:?config file required}"
+  local pool_name="${2:?pool name required}"
+
+  flow_provider_pool_value "${config_file}" "${pool_name}" "kilo.model"
+}
+
+flow_provider_pool_kilo_timeout_seconds() {
+  local config_file="${1:?config file required}"
+  local pool_name="${2:?pool name required}"
+
+  flow_provider_pool_value "${config_file}" "${pool_name}" "kilo.timeout_seconds"
+}
+
 flow_sanitize_provider_key() {
   local raw_key="${1:?raw key required}"
 
@@ -1771,6 +1799,12 @@ flow_provider_pool_model_identity() {
     pi)
       flow_provider_pool_pi_model "${config_file}" "${pool_name}"
       ;;
+    opencode)
+      flow_provider_pool_opencode_model "${config_file}" "${pool_name}"
+      ;;
+    kilo)
+      flow_provider_pool_kilo_model "${config_file}" "${pool_name}"
+      ;;
     *)
       printf '\n'
       ;;
@@ -1810,6 +1844,10 @@ flow_provider_pool_state_get() {
   local pi_model=""
   local pi_thinking=""
   local pi_timeout_seconds=""
+  local opencode_model=""
+  local opencode_timeout_seconds=""
+  local kilo_model=""
+  local kilo_timeout_seconds=""
 
   backend="$(flow_provider_pool_backend "${config_file}" "${pool_name}")"
   safe_profile="$(flow_provider_pool_safe_profile "${config_file}" "${pool_name}")"
@@ -1829,6 +1867,10 @@ flow_provider_pool_state_get() {
   pi_model="$(flow_provider_pool_pi_model "${config_file}" "${pool_name}")"
   pi_thinking="$(flow_provider_pool_pi_thinking "${config_file}" "${pool_name}")"
   pi_timeout_seconds="$(flow_provider_pool_pi_timeout_seconds "${config_file}" "${pool_name}")"
+  opencode_model="$(flow_provider_pool_opencode_model "${config_file}" "${pool_name}")"
+  opencode_timeout_seconds="$(flow_provider_pool_opencode_timeout_seconds "${config_file}" "${pool_name}")"
+  kilo_model="$(flow_provider_pool_kilo_model "${config_file}" "${pool_name}")"
+  kilo_timeout_seconds="$(flow_provider_pool_kilo_timeout_seconds "${config_file}" "${pool_name}")"
   model="$(flow_provider_pool_model_identity "${config_file}" "${pool_name}")"
 
   case "${backend}" in
@@ -1847,6 +1889,12 @@ flow_provider_pool_state_get() {
     pi)
       [[ -n "${pi_model}" ]] || valid="no"
       ;;
+    opencode)
+      [[ -n "${opencode_model}" && -n "${opencode_timeout_seconds}" ]] || valid="no"
+      ;;
+    kilo)
+      [[ -n "${kilo_model}" && -n "${kilo_timeout_seconds}" ]] || valid="no"
+      ;;
     *)
       valid="no"
       ;;
@@ -1905,6 +1953,10 @@ flow_provider_pool_state_get() {
   printf 'PI_MODEL=%s\n' "${pi_model}"
   printf 'PI_THINKING=%s\n' "${pi_thinking}"
   printf 'PI_TIMEOUT_SECONDS=%s\n' "${pi_timeout_seconds}"
+  printf 'OPENCODE_MODEL=%s\n' "${opencode_model}"
+  printf 'OPENCODE_TIMEOUT_SECONDS=%s\n' "${opencode_timeout_seconds}"
+  printf 'KILO_MODEL=%s\n' "${kilo_model}"
+  printf 'KILO_TIMEOUT_SECONDS=%s\n' "${kilo_timeout_seconds}"
 }
 
 flow_selected_provider_pool_env() {
@@ -2118,6 +2170,10 @@ flow_export_execution_env() {
   local pi_model=""
   local pi_thinking=""
   local pi_timeout=""
+  local opencode_model=""
+  local opencode_timeout=""
+  local kilo_model=""
+  local kilo_timeout=""
 
   repo_id="$(flow_resolve_repo_id "${config_file}")"
   provider_quota_cooldowns="$(flow_resolve_provider_quota_cooldowns "${config_file}")"
@@ -2157,6 +2213,10 @@ flow_export_execution_env() {
     pi_model="$(flow_kv_get "${provider_pool_selection}" "PI_MODEL")"
     pi_thinking="$(flow_kv_get "${provider_pool_selection}" "PI_THINKING")"
     pi_timeout="$(flow_kv_get "${provider_pool_selection}" "PI_TIMEOUT_SECONDS")"
+    opencode_model="$(flow_kv_get "${provider_pool_selection}" "OPENCODE_MODEL")"
+    opencode_timeout="$(flow_kv_get "${provider_pool_selection}" "OPENCODE_TIMEOUT_SECONDS")"
+    kilo_model="$(flow_kv_get "${provider_pool_selection}" "KILO_MODEL")"
+    kilo_timeout="$(flow_kv_get "${provider_pool_selection}" "KILO_TIMEOUT_SECONDS")"
   else
     if [[ -n "${explicit_coding_worker}" ]]; then
       active_provider_selection_reason="env-override"
@@ -2180,6 +2240,10 @@ flow_export_execution_env() {
     pi_model="$(flow_env_or_config "${config_file}" "ACP_PI_MODEL F_LOSNING_PI_MODEL" "execution.pi.model" "")"
     pi_thinking="$(flow_env_or_config "${config_file}" "ACP_PI_THINKING F_LOSNING_PI_THINKING" "execution.pi.thinking" "")"
     pi_timeout="$(flow_env_or_config "${config_file}" "ACP_PI_TIMEOUT_SECONDS F_LOSNING_PI_TIMEOUT_SECONDS" "execution.pi.timeout_seconds" "")"
+    opencode_model="$(flow_env_or_config "${config_file}" "ACP_OPENCODE_MODEL F_LOSNING_OPENCODE_MODEL" "execution.opencode.model" "")"
+    opencode_timeout="$(flow_env_or_config "${config_file}" "ACP_OPENCODE_TIMEOUT_SECONDS F_LOSNING_OPENCODE_TIMEOUT_SECONDS" "execution.opencode.timeout_seconds" "")"
+    kilo_model="$(flow_env_or_config "${config_file}" "ACP_KILO_MODEL F_LOSNING_KILO_MODEL" "execution.kilo.model" "")"
+    kilo_timeout="$(flow_env_or_config "${config_file}" "ACP_KILO_TIMEOUT_SECONDS F_LOSNING_KILO_TIMEOUT_SECONDS" "execution.kilo.timeout_seconds" "")"
   fi
 
   if [[ -n "${coding_worker}" ]]; then
@@ -2287,6 +2351,22 @@ flow_export_execution_env() {
     export F_LOSNING_PI_TIMEOUT_SECONDS="${pi_timeout}"
     export ACP_PI_TIMEOUT_SECONDS="${pi_timeout}"
   fi
+  if [[ -n "${opencode_model}" ]]; then
+    export F_LOSNING_OPENCODE_MODEL="${opencode_model}"
+    export ACP_OPENCODE_MODEL="${opencode_model}"
+  fi
+  if [[ -n "${opencode_timeout}" ]]; then
+    export F_LOSNING_OPENCODE_TIMEOUT_SECONDS="${opencode_timeout}"
+    export ACP_OPENCODE_TIMEOUT_SECONDS="${opencode_timeout}"
+  fi
+  if [[ -n "${kilo_model}" ]]; then
+    export F_LOSNING_KILO_MODEL="${kilo_model}"
+    export ACP_KILO_MODEL="${kilo_model}"
+  fi
+  if [[ -n "${kilo_timeout}" ]]; then
+    export F_LOSNING_KILO_TIMEOUT_SECONDS="${kilo_timeout}"
+    export ACP_KILO_TIMEOUT_SECONDS="${kilo_timeout}"
+  fi
 
   flow_export_github_cli_auth_env "$(flow_resolve_repo_slug "${config_file}")"
   flow_export_project_env_aliases

package/tools/bin/flow-resident-worker-lib.sh

@@ -285,6 +285,22 @@ flow_resident_issue_queue_file() {
   printf '%s/issue-%s.env\n' "$(flow_resident_issue_queue_pending_dir "${config_file}")" "${issue_id}"
 }
 
+flow_resident_issue_claim_file() {
+  local config_file="${1:-}"
+  local issue_id="${2:?issue id required}"
+  local claimer_key="${3:?claimer key required}"
+
+  if [[ -z "${config_file}" ]]; then
+    config_file="$(resolve_flow_config_yaml "${BASH_SOURCE[1]:-${BASH_SOURCE[0]}}")"
+  fi
+
+  printf '%s/issue-%s.%s.%s.env\n' \
+    "$(flow_resident_issue_queue_claims_dir "${config_file}")" \
+    "${issue_id}" \
+    "${claimer_key}" \
+    "$$"
+}
+
 flow_resident_issue_controller_file() {
   local config_file="${1:-}"
   local issue_id="${2:?issue id required}"
@@ -342,8 +358,11 @@ flow_resident_issue_enqueue() {
 
   tmp_file="${queue_file}.tmp.$$"
   flow_resident_write_metadata "${tmp_file}" \
+    "STATE_FORMAT_VERSION=1" \
+    "STATE_KIND=pending" \
     "ISSUE_ID=${issue_id}" \
     "QUEUED_BY=${queued_by}" \
+    "UPDATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
     "QUEUED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
   mv "${tmp_file}" "${queue_file}"
 
@@ -361,6 +380,9 @@ flow_resident_issue_claim_next() {
   local issue_id=""
   local claim_file=""
   local claim_key=""
+  local queued_by=""
+  local queued_at=""
+  local claimed_at=""
 
   if [[ -z "${config_file}" ]]; then
     config_file="$(resolve_flow_config_yaml "${BASH_SOURCE[1]:-${BASH_SOURCE[0]}}")"
@@ -378,8 +400,22 @@ flow_resident_issue_claim_next() {
     [[ -n "${issue_id}" ]] || continue
     [[ "${issue_id}" != "${skip_issue_id}" ]] || continue
 
-    claim_file="${claims_dir}/issue-${issue_id}.${claim_key}.$$"
+    queued_by="$(flow_resident_metadata_value "${queue_file}" "QUEUED_BY" || true)"
+    queued_at="$(flow_resident_metadata_value "${queue_file}" "QUEUED_AT" || true)"
+    claimed_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+    claim_file="$(flow_resident_issue_claim_file "${config_file}" "${issue_id}" "${claim_key}")"
     if mv "${queue_file}" "${claim_file}" 2>/dev/null; then
+      flow_resident_write_metadata "${claim_file}" \
+        "STATE_FORMAT_VERSION=1" \
+        "STATE_KIND=claim" \
+        "ISSUE_ID=${issue_id}" \
+        "QUEUED_BY=${queued_by}" \
+        "QUEUED_AT=${queued_at}" \
+        "SESSION=${claimer_key}" \
+        "CLAIMED_BY=${claim_key}" \
+        "CLAIMED_AT=${claimed_at}" \
+        "UPDATED_AT=${claimed_at}" \
+        "CLAIM_FILE=${claim_file}"
       printf 'ISSUE_ID=%s\n' "${issue_id}"
       printf 'CLAIM_FILE=%s\n' "${claim_file}"
       return 0
@@ -441,6 +477,87 @@ flow_resident_issue_controller_reap_file() {
   return 0
 }
 
+flow_resident_issue_reap_stale_claims() {
+  local config_file="${1:-}"
+  local claims_dir=""
+  local claim_file=""
+  local claim_token=""
+  local claim_pid=""
+  local issue_id=""
+  local queued_by=""
+  local queued_at=""
+  local claimed_at=""
+  local existing_pending_file=""
+  local other_claim=""
+  local other_token=""
+  local other_pid=""
+
+  if [[ -z "${config_file}" ]]; then
+    config_file="$(resolve_flow_config_yaml "${BASH_SOURCE[1]:-${BASH_SOURCE[0]}}")"
+  fi
+
+  claims_dir="$(flow_resident_issue_queue_claims_dir "${config_file}")"
+  mkdir -p "${claims_dir}"
+
+  for claim_file in "${claims_dir}"/issue-*.env; do
+    [[ -f "${claim_file}" ]] || continue
+
+    claim_token="${claim_file##*/}"
+    claim_token="${claim_token%.env}"
+    claim_pid="${claim_token##*.}"
+    [[ "${claim_pid}" =~ ^[0-9]+$ ]] || continue
+
+    if flow_resident_controller_pid_live "${claim_pid}" "start-resident-issue-loop.sh"; then
+      continue
+    fi
+
+    issue_id="$(flow_resident_metadata_value "${claim_file}" "ISSUE_ID" || true)"
+    [[ -n "${issue_id}" ]] || issue_id="${claim_token#issue-}"
+    issue_id="${issue_id%%.*}"
+    [[ -n "${issue_id}" ]] || continue
+
+    # If another live claim exists for the same issue, do not re-queue this one.
+    for other_claim in "${claims_dir}/issue-${issue_id}."*; do
+      [[ -f "${other_claim}" ]] || continue
+      other_token="${other_claim##*/}"
+      other_token="${other_token%.env}"
+      other_pid="${other_token##*.}"
+      [[ "${other_pid}" =~ ^[0-9]+$ ]] || continue
+      if [[ "${other_pid}" == "${claim_pid}" ]]; then
+        continue
+      fi
+      if flow_resident_controller_pid_live "${other_pid}" "start-resident-issue-loop.sh"; then
+        issue_id=""
+        break
+      fi
+    done
+    [[ -n "${issue_id}" ]] || continue
+
+    existing_pending_file="$(flow_resident_issue_queue_file "${config_file}" "${issue_id}")"
+    if [[ -f "${existing_pending_file}" ]]; then
+      rm -f "${claim_file}"
+      continue
+    fi
+
+    queued_by="$(flow_resident_metadata_value "${claim_file}" "QUEUED_BY" || true)"
+    queued_at="$(flow_resident_metadata_value "${claim_file}" "QUEUED_AT" || true)"
+    claimed_at="$(flow_resident_metadata_value "${claim_file}" "CLAIMED_AT" || true)"
+
+    [[ -n "${queued_by}" ]] || queued_by="heartbeat"
+    [[ -n "${queued_at}" ]] || queued_at="${claimed_at:-$(date -u +"%Y-%m-%dT%H:%M:%SZ")}"
+
+    flow_resident_write_metadata "${existing_pending_file}" \
+      "STATE_FORMAT_VERSION=1" \
+      "STATE_KIND=pending" \
+      "ISSUE_ID=${issue_id}" \
+      "QUEUED_BY=${queued_by}" \
+      "QUEUED_AT=${queued_at}" \
+      "UPDATED_AT=${claimed_at:-${queued_at}}"
+    rm -f "${claim_file}"
+
+  done
+}
+
 flow_resident_issue_reap_stale_state() {
   local config_file="${1:-}"
   local resident_root=""
@@ -458,6 +575,7 @@ flow_resident_issue_reap_stale_state() {
       reaped=$((reaped + 1))
     fi
   done
+  flow_resident_issue_reap_stale_claims "${config_file}" || true
 
   printf '%s\n' "${reaped}"
 }

package/tools/bin/flow-shell-lib.sh

@@ -5,6 +5,30 @@ flow_canonical_skill_name() {
   printf '%s\n' "${AGENT_CONTROL_PLANE_SKILL_NAME:-agent-control-plane}"
 }
 
+flow_resolve_python_bin() {
+  if [[ -n "${PYTHON_BIN:-}" && -x "${PYTHON_BIN:-}" ]]; then
+    printf '%s\n' "${PYTHON_BIN}"
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    command -v python3
+    return 0
+  fi
+
+  if [[ -x /opt/homebrew/bin/python3 ]]; then
+    printf '%s\n' "/opt/homebrew/bin/python3"
+    return 0
+  fi
+
+  if command -v python >/dev/null 2>&1; then
+    command -v python
+    return 0
+  fi
+
+  return 1
+}
+
 flow_compat_skill_alias() {
   printf '%s\n' "${AGENT_CONTROL_PLANE_COMPAT_ALIAS:-}"
 }

package/tools/bin/heartbeat-loop-cache-lib.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# heartbeat-loop-cache-lib.sh — scheduler cache management and attribute caching
+
+cleanup_scheduler_caches() {
+  tmux_sessions_cache=""
+  tmux_sessions_cache_loaded="no"
+  all_running_workers_cache=""
+  all_running_workers_cache_loaded="no"
+  running_issue_workers_cache=""
+  running_issue_workers_cache_loaded="no"
+  running_pr_workers_cache=""
+  running_pr_workers_cache_loaded="no"
+  completed_workers_cache=""
+  completed_workers_cache_loaded="no"
+  ready_issue_ids_cache=""
+  ready_issue_ids_cache_loaded="no"
+  open_agent_pr_ids_cache=""
+  open_agent_pr_ids_cache_loaded="no"
+  running_issue_ids_cache=""
+  running_issue_ids_cache_loaded="no"
+  exclusive_issue_ids_cache=""
+  exclusive_issue_ids_cache_loaded="no"
+  exclusive_pr_ids_cache=""
+  exclusive_pr_ids_cache_loaded="no"
+  blocked_recovery_issue_ids_cache=""
+  blocked_recovery_issue_ids_cache_loaded="no"
+  ordered_ready_issue_ids_cache=""
+  ordered_ready_issue_ids_cache_loaded="no"
+  due_scheduled_issue_ids_cache=""
+  due_scheduled_issue_ids_cache_loaded="no"
+  due_blocked_recovery_issue_ids_cache=""
+  due_blocked_recovery_issue_ids_cache_loaded="no"
+  if [[ -n "${issue_attr_cache_dir:-}" && -d "${issue_attr_cache_dir}" ]]; then
+    rm -rf "${issue_attr_cache_dir}" || true
+  fi
+  if [[ -n "${pr_attr_cache_dir:-}" && -d "${pr_attr_cache_dir}" ]]; then
+    rm -rf "${pr_attr_cache_dir}" || true
+  fi
+  if [[ -n "${pr_risk_cache_dir:-}" && -d "${pr_risk_cache_dir}" ]]; then
+    rm -rf "${pr_risk_cache_dir}" || true
+  fi
+  if declare -F heartbeat_invalidate_snapshot_cache >/dev/null 2>&1; then
+    heartbeat_invalidate_snapshot_cache
+  fi
+}
+
+cache_prefix() {
+  local raw_prefix="${issue_prefix:-${pr_prefix:-agent-control-plane}}"
+  local sanitized=""
+
+  sanitized="$(printf '%s' "${raw_prefix}" | tr '/[:space:]' '-' | tr -cd '[:alnum:]_.-')"
+  if [[ -z "${sanitized}" ]]; then
+    sanitized="agent-control-plane"
+  fi
+
+  printf '%s\n' "${sanitized}"
+}
+
+ensure_issue_attr_cache_dir() {
+  if [[ -z "${issue_attr_cache_dir:-}" || ! -d "${issue_attr_cache_dir:-}" ]]; then
+    issue_attr_cache_dir="$(mktemp -d "${TMPDIR:-/tmp}/$(cache_prefix)-issue-attrs.XXXXXX")"
+  fi
+}
+
+ensure_pr_attr_cache_dir() {
+  if [[ -z "${pr_attr_cache_dir:-}" || ! -d "${pr_attr_cache_dir:-}" ]]; then
+    pr_attr_cache_dir="$(mktemp -d "${TMPDIR:-/tmp}/$(cache_prefix)-pr-attrs.XXXXXX")"
+  fi
+}
+
+ensure_pr_risk_cache_dir() {
+  if [[ -z "${pr_risk_cache_dir:-}" || ! -d "${pr_risk_cache_dir:-}" ]]; then
+    pr_risk_cache_dir="$(mktemp -d "${TMPDIR:-/tmp}/$(cache_prefix)-pr-risk.XXXXXX")"
+  fi
+}
+
+pr_risk_runtime_cache_fresh() {
+  local cache_file="${1:?cache file required}"
+  local modified_at now age
+  [[ -f "$cache_file" ]] || return 1
+  modified_at="$(stat -f '%m' "$cache_file" 2>/dev/null || true)"
+  [[ "$modified_at" =~ ^[0-9]+$ ]] || return 1
+  now="$(date +%s)"
+  age=$((now - modified_at))
+  (( age >= 0 && age <= pr_risk_runtime_cache_ttl_seconds ))
+}
+
+cached_issue_attr() {
+  local attr_name="${1:?attr name required}"
+  local issue_id="${2:?issue id required}"
+  local cache_file attr_value
+
+  ensure_issue_attr_cache_dir
+  cache_file="${issue_attr_cache_dir}/${issue_id}.${attr_name}"
+  if [[ -f "${cache_file}" ]]; then
+    cat "${cache_file}"
+    return 0
+  fi
+
+  case "${attr_name}" in
+    heavy)
+      attr_value="$(heartbeat_issue_is_heavy "${issue_id}")"
+      ;;
+    recurring)
+      attr_value="$(heartbeat_issue_is_recurring "${issue_id}")"
+      ;;
+    scheduled)
+      attr_value="$(heartbeat_issue_is_scheduled "${issue_id}")"
+      ;;
+    schedule_interval_seconds)
+      attr_value="$(heartbeat_issue_schedule_interval_seconds "${issue_id}")"
+      ;;
+    exclusive)
+      attr_value="$(heartbeat_issue_is_exclusive "${issue_id}")"
+      ;;
+    *)
+      echo "unsupported issue cache attr: ${attr_name}" >&2
+      return 1
+      ;;
+  esac
+
+  printf '%s\n' "${attr_value}" >"${cache_file}"
+  printf '%s\n' "${attr_value}"
+}
+
+cached_pr_is_exclusive() {
+  local pr_number="${1:?pr number required}"
+  local cache_file attr_value
+
+  ensure_pr_attr_cache_dir
+  cache_file="${pr_attr_cache_dir}/${pr_number}.exclusive"
+  if [[ -f "${cache_file}" ]]; then
+    cat "${cache_file}"
+    return 0
+  fi
+
+  attr_value="$(heartbeat_pr_is_exclusive "${pr_number}")"
+  printf '%s\n' "${attr_value}" >"${cache_file}"
+  printf '%s\n' "${attr_value}"
+}
+
+cached_pr_risk_json() {
+  local pr_number="${1:?pr number required}"
+  local cache_file runtime_cache_file risk_json
+
+  ensure_pr_risk_cache_dir
+  cache_file="${pr_risk_cache_dir}/${pr_number}.json"
+  runtime_cache_file="${pr_risk_runtime_cache_dir}/${pr_number}.json"
+  if [[ -f "${cache_file}" ]]; then
+    cat "${cache_file}"
+    return 0
+  fi
+
+  if pr_risk_runtime_cache_fresh "${runtime_cache_file}"; then
+    cp "${runtime_cache_file}" "${cache_file}"
+    cat "${cache_file}"
+    return 0
+  fi
+
+  risk_json="$(heartbeat_pr_risk_json "${pr_number}")"
+  printf '%s\n' "${risk_json}" >"${cache_file}"
+  printf '%s\n' "${risk_json}" >"${runtime_cache_file}"
+  printf '%s\n' "${risk_json}"
+}