agent-control-plane 0.1.0

package/tools/bin/flow-runtime-doctor.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+SHARED_AGENT_HOME="$(resolve_shared_agent_home "${FLOW_SKILL_DIR}")"
+PROFILE_REGISTRY_ROOT="$(resolve_flow_profile_registry_root)"
+CONTROL_PLANE_NAME="$(flow_canonical_skill_name)"
+COMPAT_SKILL_ALIAS="$(flow_compat_skill_alias)"
+SOURCE_CANONICAL_SKILL_DIR="$(resolve_source_canonical_skill_dir "${SHARED_AGENT_HOME}")"
+SOURCE_COMPAT_SKILL_DIR="$(resolve_source_compat_skill_dir "${SHARED_AGENT_HOME}")"
+RUNTIME_HOME="$(resolve_runtime_home)"
+RUNTIME_CANONICAL_SKILL_DIR="$(resolve_runtime_canonical_skill_dir)"
+RUNTIME_COMPAT_SKILL_DIR="$(resolve_runtime_compat_skill_dir)"
+CATALOG_FILE="${FLOW_SKILL_DIR}/assets/workflow-catalog.json"
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+SYNC_SCRIPT="${FLOW_SKILL_DIR}/tools/bin/sync-shared-agent-home.sh"
+PROFILE_ID="$(flow_resolve_adapter_id "${CONFIG_YAML}")"
+AVAILABLE_PROFILES="$(flow_list_profile_ids "${FLOW_SKILL_DIR}" | paste -sd, -)"
+INSTALLED_PROFILES="$(flow_list_installed_profile_ids | paste -sd, -)"
+PROFILE_SELECTION_MODE="$(flow_profile_selection_mode "${FLOW_SKILL_DIR}")"
+PROFILE_SELECTION_HINT="$(flow_profile_selection_hint "${FLOW_SKILL_DIR}")"
+PROFILE_NOTES="$(flow_resolve_profile_notes_file "${CONFIG_YAML}")"
+
+exists_flag() {
+  local candidate="${1:-}"
+  if [[ -e "${candidate}" ]]; then
+    printf 'yes\n'
+  else
+    printf 'no\n'
+  fi
+}
+
+source_canonical_exists="$(exists_flag "${SOURCE_CANONICAL_SKILL_DIR}")"
+source_compat_exists="$(exists_flag "${SOURCE_COMPAT_SKILL_DIR}")"
+runtime_canonical_exists="$(exists_flag "${RUNTIME_CANONICAL_SKILL_DIR}")"
+runtime_compat_exists="$(exists_flag "${RUNTIME_COMPAT_SKILL_DIR}")"
+catalog_exists="$(exists_flag "${CATALOG_FILE}")"
+profile_exists="$(exists_flag "${CONFIG_YAML}")"
+active_checkout_is_canonical="no"
+source_ready="${source_canonical_exists}"
+
+if [[ "$(basename "${FLOW_SKILL_DIR}")" == "${CONTROL_PLANE_NAME}" ]]; then
+  active_checkout_is_canonical="yes"
+  source_ready="yes"
+fi
+
+status="ok"
+if [[ "${source_ready}" != "yes" || "${runtime_canonical_exists}" != "yes" || "${profile_exists}" != "yes" ]]; then
+  status="needs-sync"
+fi
+
+printf 'CONTROL_PLANE_NAME=%s\n' "${CONTROL_PLANE_NAME}"
+printf 'COMPAT_SKILL_ALIAS=%s\n' "${COMPAT_SKILL_ALIAS}"
+printf 'FLOW_SKILL_DIR=%s\n' "${FLOW_SKILL_DIR}"
+printf 'PROFILE_REGISTRY_ROOT=%s\n' "${PROFILE_REGISTRY_ROOT}"
+printf 'CONFIG_YAML=%s\n' "${CONFIG_YAML}"
+printf 'PROFILE_ID=%s\n' "${PROFILE_ID}"
+printf 'PROFILE_SELECTION_MODE=%s\n' "${PROFILE_SELECTION_MODE}"
+if [[ -n "${PROFILE_SELECTION_HINT}" ]]; then
+  printf 'PROFILE_SELECTION_HINT=%s\n' "${PROFILE_SELECTION_HINT}"
+fi
+printf 'PROFILE_NOTES=%s\n' "${PROFILE_NOTES}"
+if [[ -f "${PROFILE_NOTES}" ]]; then
+  printf 'PROFILE_NOTES_EXISTS=yes\n'
+else
+  printf 'PROFILE_NOTES_EXISTS=no\n'
+fi
+printf 'PROFILE_EXISTS=%s\n' "${profile_exists}"
+printf 'AVAILABLE_PROFILES=%s\n' "${AVAILABLE_PROFILES}"
+printf 'INSTALLED_PROFILES=%s\n' "${INSTALLED_PROFILES}"
+printf 'SHARED_AGENT_HOME=%s\n' "${SHARED_AGENT_HOME}"
+printf 'SOURCE_CANONICAL_SKILL_DIR=%s\n' "${SOURCE_CANONICAL_SKILL_DIR}"
+printf 'SOURCE_CANONICAL_EXISTS=%s\n' "${source_canonical_exists}"
+printf 'ACTIVE_CHECKOUT_IS_CANONICAL=%s\n' "${active_checkout_is_canonical}"
+printf 'SOURCE_READY=%s\n' "${source_ready}"
+printf 'SOURCE_COMPAT_SKILL_DIR=%s\n' "${SOURCE_COMPAT_SKILL_DIR}"
+printf 'SOURCE_COMPAT_EXISTS=%s\n' "${source_compat_exists}"
+printf 'RUNTIME_HOME=%s\n' "${RUNTIME_HOME}"
+printf 'RUNTIME_CANONICAL_SKILL_DIR=%s\n' "${RUNTIME_CANONICAL_SKILL_DIR}"
+printf 'RUNTIME_CANONICAL_EXISTS=%s\n' "${runtime_canonical_exists}"
+printf 'RUNTIME_COMPAT_SKILL_DIR=%s\n' "${RUNTIME_COMPAT_SKILL_DIR}"
+printf 'RUNTIME_COMPAT_EXISTS=%s\n' "${runtime_compat_exists}"
+printf 'WORKFLOW_CATALOG=%s\n' "${CATALOG_FILE}"
+printf 'WORKFLOW_CATALOG_EXISTS=%s\n' "${catalog_exists}"
+printf 'DOCTOR_STATUS=%s\n' "${status}"
+
+if [[ -n "${PROFILE_SELECTION_HINT}" ]]; then
+  printf 'PROFILE_SELECTION_NEXT_STEP=ACP_PROJECT_ID=<id> bash %s/tools/bin/render-flow-config.sh\n' "${FLOW_SKILL_DIR}"
+fi
+
+if [[ "${status}" != "ok" ]]; then
+  printf 'NEXT_STEP=bash %q %q %q\n' "${SYNC_SCRIPT}" "${SHARED_AGENT_HOME}" "${RUNTIME_HOME}"
+fi

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

@@ -0,0 +1,266 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+flow_canonical_skill_name() {
+  printf '%s\n' "${AGENT_CONTROL_PLANE_SKILL_NAME:-agent-control-plane}"
+}
+
+flow_compat_skill_alias() {
+  printf '%s\n' "${AGENT_CONTROL_PLANE_COMPAT_ALIAS:-}"
+}
+
+flow_export_env_alias_if_unset() {
+  local target_name="${1:?target name required}"
+  local source_name="${2:?source name required}"
+  local source_value="${!source_name:-}"
+
+  if [[ -n "${source_value}" && -z "${!target_name:-}" ]]; then
+    export "${target_name}=${source_value}"
+  fi
+}
+
+flow_export_compat_env_aliases() {
+  flow_export_env_alias_if_unset F_LOSNING_FLOW_ROOT AGENT_CONTROL_PLANE_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_FLOW_ROOT ACP_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_REPO_SLUG ACP_REPO_SLUG
+  flow_export_env_alias_if_unset F_LOSNING_REPO_ID ACP_REPO_ID
+  flow_export_env_alias_if_unset F_LOSNING_GITHUB_REPOSITORY_ID ACP_GITHUB_REPOSITORY_ID
+  flow_export_env_alias_if_unset F_LOSNING_REPO_ROOT ACP_REPO_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_AGENT_ROOT ACP_AGENT_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_AGENT_REPO_ROOT ACP_AGENT_REPO_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_WORKTREE_ROOT ACP_WORKTREE_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_RUNS_ROOT ACP_RUNS_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_STATE_ROOT ACP_STATE_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_HISTORY_ROOT ACP_HISTORY_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_MEMORY_DIR ACP_MEMORY_DIR
+  flow_export_env_alias_if_unset F_LOSNING_RETAINED_REPO_ROOT ACP_RETAINED_REPO_ROOT
+  flow_export_env_alias_if_unset F_LOSNING_VSCODE_WORKSPACE_FILE ACP_VSCODE_WORKSPACE_FILE
+  flow_export_env_alias_if_unset F_LOSNING_CODING_WORKER ACP_CODING_WORKER
+  flow_export_env_alias_if_unset F_LOSNING_CODEX_PROFILE_SAFE ACP_CODEX_PROFILE_SAFE
+  flow_export_env_alias_if_unset F_LOSNING_CODEX_PROFILE_BYPASS ACP_CODEX_PROFILE_BYPASS
+  flow_export_env_alias_if_unset F_LOSNING_CLAUDE_MODEL ACP_CLAUDE_MODEL
+  flow_export_env_alias_if_unset F_LOSNING_CLAUDE_PERMISSION_MODE ACP_CLAUDE_PERMISSION_MODE
+  flow_export_env_alias_if_unset F_LOSNING_CLAUDE_EFFORT ACP_CLAUDE_EFFORT
+  flow_export_env_alias_if_unset F_LOSNING_CLAUDE_TIMEOUT_SECONDS ACP_CLAUDE_TIMEOUT_SECONDS
+  flow_export_env_alias_if_unset F_LOSNING_CLAUDE_MAX_ATTEMPTS ACP_CLAUDE_MAX_ATTEMPTS
+  flow_export_env_alias_if_unset F_LOSNING_CLAUDE_RETRY_BACKOFF_SECONDS ACP_CLAUDE_RETRY_BACKOFF_SECONDS
+  flow_export_env_alias_if_unset F_LOSNING_ISSUE_SESSION_PREFIX ACP_ISSUE_SESSION_PREFIX
+  flow_export_env_alias_if_unset F_LOSNING_PR_SESSION_PREFIX ACP_PR_SESSION_PREFIX
+  flow_export_env_alias_if_unset F_LOSNING_ISSUE_BRANCH_PREFIX ACP_ISSUE_BRANCH_PREFIX
+  flow_export_env_alias_if_unset F_LOSNING_PR_WORKTREE_BRANCH_PREFIX ACP_PR_WORKTREE_BRANCH_PREFIX
+  flow_export_env_alias_if_unset F_LOSNING_MANAGED_PR_BRANCH_GLOBS ACP_MANAGED_PR_BRANCH_GLOBS
+  flow_export_env_alias_if_unset F_LOSNING_OPENCLAW_MODEL ACP_OPENCLAW_MODEL
+  flow_export_env_alias_if_unset F_LOSNING_OPENCLAW_THINKING ACP_OPENCLAW_THINKING
+  flow_export_env_alias_if_unset F_LOSNING_OPENCLAW_TIMEOUT_SECONDS ACP_OPENCLAW_TIMEOUT_SECONDS
+  flow_export_env_alias_if_unset F_LOSNING_ALLOW_INFRA_CI_BYPASS ACP_ALLOW_INFRA_CI_BYPASS
+  flow_export_env_alias_if_unset F_LOSNING_LOCAL_FIRST_PR_POLICY ACP_LOCAL_FIRST_PR_POLICY
+  flow_export_env_alias_if_unset F_LOSNING_PR_RISK_CACHE_TTL_SECONDS ACP_PR_RISK_CACHE_TTL_SECONDS
+  flow_export_env_alias_if_unset F_LOSNING_RETRY_COOLDOWNS ACP_RETRY_COOLDOWNS
+  flow_export_env_alias_if_unset F_LOSNING_WORKTREE_LOCAL_INSTALL ACP_WORKTREE_LOCAL_INSTALL
+  flow_export_env_alias_if_unset F_LOSNING_BOOTSTRAP_SCRIPT ACP_BOOTSTRAP_SCRIPT
+  flow_export_env_alias_if_unset F_LOSNING_FLOW_HEARTBEAT_SCRIPT ACP_FLOW_HEARTBEAT_SCRIPT
+  flow_export_env_alias_if_unset F_LOSNING_TIMEOUT_CHILD_PID_FILE ACP_TIMEOUT_CHILD_PID_FILE
+  flow_export_env_alias_if_unset F_LOSNING_ISSUE_ID ACP_ISSUE_ID
+  flow_export_env_alias_if_unset F_LOSNING_ISSUE_URL ACP_ISSUE_URL
+  flow_export_env_alias_if_unset F_LOSNING_ISSUE_AUTOMERGE ACP_ISSUE_AUTOMERGE
+  flow_export_env_alias_if_unset F_LOSNING_PR_NUMBER ACP_PR_NUMBER
+  flow_export_env_alias_if_unset F_LOSNING_PR_URL ACP_PR_URL
+  flow_export_env_alias_if_unset F_LOSNING_PR_HEAD_REF ACP_PR_HEAD_REF
+}
+
+flow_export_canonical_env_aliases() {
+  flow_export_env_alias_if_unset ACP_ROOT F_LOSNING_FLOW_ROOT
+  flow_export_env_alias_if_unset ACP_REPO_SLUG F_LOSNING_REPO_SLUG
+  flow_export_env_alias_if_unset ACP_REPO_ID F_LOSNING_REPO_ID
+  flow_export_env_alias_if_unset ACP_GITHUB_REPOSITORY_ID F_LOSNING_GITHUB_REPOSITORY_ID
+  flow_export_env_alias_if_unset ACP_REPO_ROOT F_LOSNING_REPO_ROOT
+  flow_export_env_alias_if_unset ACP_AGENT_ROOT F_LOSNING_AGENT_ROOT
+  flow_export_env_alias_if_unset ACP_AGENT_REPO_ROOT F_LOSNING_AGENT_REPO_ROOT
+  flow_export_env_alias_if_unset ACP_WORKTREE_ROOT F_LOSNING_WORKTREE_ROOT
+  flow_export_env_alias_if_unset ACP_RUNS_ROOT F_LOSNING_RUNS_ROOT
+  flow_export_env_alias_if_unset ACP_STATE_ROOT F_LOSNING_STATE_ROOT
+  flow_export_env_alias_if_unset ACP_HISTORY_ROOT F_LOSNING_HISTORY_ROOT
+  flow_export_env_alias_if_unset ACP_MEMORY_DIR F_LOSNING_MEMORY_DIR
+  flow_export_env_alias_if_unset ACP_RETAINED_REPO_ROOT F_LOSNING_RETAINED_REPO_ROOT
+  flow_export_env_alias_if_unset ACP_VSCODE_WORKSPACE_FILE F_LOSNING_VSCODE_WORKSPACE_FILE
+  flow_export_env_alias_if_unset ACP_CODING_WORKER F_LOSNING_CODING_WORKER
+  flow_export_env_alias_if_unset ACP_CODEX_PROFILE_SAFE F_LOSNING_CODEX_PROFILE_SAFE
+  flow_export_env_alias_if_unset ACP_CODEX_PROFILE_BYPASS F_LOSNING_CODEX_PROFILE_BYPASS
+  flow_export_env_alias_if_unset ACP_CLAUDE_MODEL F_LOSNING_CLAUDE_MODEL
+  flow_export_env_alias_if_unset ACP_CLAUDE_PERMISSION_MODE F_LOSNING_CLAUDE_PERMISSION_MODE
+  flow_export_env_alias_if_unset ACP_CLAUDE_EFFORT F_LOSNING_CLAUDE_EFFORT
+  flow_export_env_alias_if_unset ACP_CLAUDE_TIMEOUT_SECONDS F_LOSNING_CLAUDE_TIMEOUT_SECONDS
+  flow_export_env_alias_if_unset ACP_CLAUDE_MAX_ATTEMPTS F_LOSNING_CLAUDE_MAX_ATTEMPTS
+  flow_export_env_alias_if_unset ACP_CLAUDE_RETRY_BACKOFF_SECONDS F_LOSNING_CLAUDE_RETRY_BACKOFF_SECONDS
+  flow_export_env_alias_if_unset ACP_ISSUE_SESSION_PREFIX F_LOSNING_ISSUE_SESSION_PREFIX
+  flow_export_env_alias_if_unset ACP_PR_SESSION_PREFIX F_LOSNING_PR_SESSION_PREFIX
+  flow_export_env_alias_if_unset ACP_ISSUE_BRANCH_PREFIX F_LOSNING_ISSUE_BRANCH_PREFIX
+  flow_export_env_alias_if_unset ACP_PR_WORKTREE_BRANCH_PREFIX F_LOSNING_PR_WORKTREE_BRANCH_PREFIX
+  flow_export_env_alias_if_unset ACP_MANAGED_PR_BRANCH_GLOBS F_LOSNING_MANAGED_PR_BRANCH_GLOBS
+  flow_export_env_alias_if_unset ACP_OPENCLAW_MODEL F_LOSNING_OPENCLAW_MODEL
+  flow_export_env_alias_if_unset ACP_OPENCLAW_THINKING F_LOSNING_OPENCLAW_THINKING
+  flow_export_env_alias_if_unset ACP_OPENCLAW_TIMEOUT_SECONDS F_LOSNING_OPENCLAW_TIMEOUT_SECONDS
+  flow_export_env_alias_if_unset ACP_ALLOW_INFRA_CI_BYPASS F_LOSNING_ALLOW_INFRA_CI_BYPASS
+  flow_export_env_alias_if_unset ACP_LOCAL_FIRST_PR_POLICY F_LOSNING_LOCAL_FIRST_PR_POLICY
+  flow_export_env_alias_if_unset ACP_PR_RISK_CACHE_TTL_SECONDS F_LOSNING_PR_RISK_CACHE_TTL_SECONDS
+  flow_export_env_alias_if_unset ACP_RETRY_COOLDOWNS F_LOSNING_RETRY_COOLDOWNS
+  flow_export_env_alias_if_unset ACP_WORKTREE_LOCAL_INSTALL F_LOSNING_WORKTREE_LOCAL_INSTALL
+  flow_export_env_alias_if_unset ACP_BOOTSTRAP_SCRIPT F_LOSNING_BOOTSTRAP_SCRIPT
+  flow_export_env_alias_if_unset ACP_FLOW_HEARTBEAT_SCRIPT F_LOSNING_FLOW_HEARTBEAT_SCRIPT
+  flow_export_env_alias_if_unset ACP_TIMEOUT_CHILD_PID_FILE F_LOSNING_TIMEOUT_CHILD_PID_FILE
+  flow_export_env_alias_if_unset ACP_ISSUE_ID F_LOSNING_ISSUE_ID
+  flow_export_env_alias_if_unset ACP_ISSUE_URL F_LOSNING_ISSUE_URL
+  flow_export_env_alias_if_unset ACP_ISSUE_AUTOMERGE F_LOSNING_ISSUE_AUTOMERGE
+  flow_export_env_alias_if_unset ACP_PR_NUMBER F_LOSNING_PR_NUMBER
+  flow_export_env_alias_if_unset ACP_PR_URL F_LOSNING_PR_URL
+  flow_export_env_alias_if_unset ACP_PR_HEAD_REF F_LOSNING_PR_HEAD_REF
+}
+
+flow_export_project_env_aliases() {
+  flow_export_compat_env_aliases
+  flow_export_canonical_env_aliases
+}
+
+flow_is_skill_root() {
+  local candidate="${1:-}"
+  [[ -n "${candidate}" ]] || return 1
+  [[ -d "${candidate}" ]] || return 1
+  [[ -d "${candidate}/tools/bin" ]] || return 1
+
+  if [[ -f "${candidate}/SKILL.md" \
+    || -f "${candidate}/assets/workflow-catalog.json" ]]; then
+    return 0
+  fi
+
+  [[ -d "${candidate}/bin" || -d "${candidate}/hooks" ]]
+}
+
+flow_print_dir() {
+  local candidate="${1:-}"
+  [[ -n "${candidate}" ]] || return 1
+  (cd "${candidate}" && pwd -P)
+}
+
+resolve_flow_skill_dir() {
+  local script_path="${1:-}"
+  local candidate=""
+  local skill_name=""
+
+  for candidate in \
+    "${AGENT_CONTROL_PLANE_ROOT:-}" \
+    "${ACP_ROOT:-}" \
+    "${F_LOSNING_FLOW_ROOT:-}" \
+    "${AGENT_FLOW_SKILL_ROOT:-}"; do
+    if flow_is_skill_root "${candidate}"; then
+      flow_print_dir "${candidate}"
+      return 0
+    fi
+  done
+
+  if [[ -n "${script_path}" ]]; then
+    candidate="$(
+      cd "$(dirname "${script_path}")/../.." 2>/dev/null && pwd -P
+    )" || candidate=""
+    if flow_is_skill_root "${candidate}"; then
+      printf '%s\n' "${candidate}"
+      return 0
+    fi
+  fi
+
+  if [[ -n "${SHARED_AGENT_HOME:-}" ]]; then
+    for skill_name in "$(flow_canonical_skill_name)" "$(flow_compat_skill_alias)"; do
+      candidate="${SHARED_AGENT_HOME}/skills/openclaw/${skill_name}"
+      if flow_is_skill_root "${candidate}"; then
+        flow_print_dir "${candidate}"
+        return 0
+      fi
+    done
+  fi
+
+  for skill_name in "$(flow_canonical_skill_name)" "$(flow_compat_skill_alias)"; do
+    candidate="${AGENT_PLATFORM_HOME:-${HOME}/.agent-runtime}/runtime-home/skills/openclaw/${skill_name}"
+    if flow_is_skill_root "${candidate}"; then
+      flow_print_dir "${candidate}"
+      return 0
+    fi
+  done
+
+  echo "unable to resolve agent control plane root" >&2
+  return 1
+}
+
+resolve_shared_agent_home() {
+  local flow_root="${1:-}"
+
+  if [[ -n "${SHARED_AGENT_HOME:-}" ]]; then
+    flow_print_dir "${SHARED_AGENT_HOME}"
+    return 0
+  fi
+
+  if [[ -z "${flow_root}" ]]; then
+    flow_root="$(resolve_flow_skill_dir "${BASH_SOURCE[1]:-${BASH_SOURCE[0]}}")"
+  fi
+
+  flow_print_dir "${flow_root}/../../.."
+}
+
+resolve_runtime_home() {
+  flow_print_dir "${AGENT_PLATFORM_HOME:-${HOME}/.agent-runtime}/runtime-home"
+}
+
+resolve_runtime_canonical_skill_dir() {
+  local runtime_home
+  runtime_home="$(resolve_runtime_home)"
+  printf '%s/skills/openclaw/%s\n' "${runtime_home}" "$(flow_canonical_skill_name)"
+}
+
+resolve_runtime_compat_skill_dir() {
+  local runtime_home
+  local compat_alias=""
+  runtime_home="$(resolve_runtime_home)"
+  compat_alias="$(flow_compat_skill_alias)"
+  if [[ -z "${compat_alias}" ]]; then
+    printf '\n'
+    return 0
+  fi
+  printf '%s/skills/openclaw/%s\n' "${runtime_home}" "${compat_alias}"
+}
+
+resolve_runtime_skill_dir() {
+  local candidate=""
+
+  for candidate in \
+    "$(resolve_runtime_canonical_skill_dir)" \
+    "$(resolve_runtime_compat_skill_dir)"; do
+    if [[ -e "${candidate}" ]]; then
+      printf '%s\n' "${candidate}"
+      return 0
+    fi
+  done
+
+  resolve_runtime_compat_skill_dir
+}
+
+resolve_source_canonical_skill_dir() {
+  local shared_home="${1:-}"
+  if [[ -z "${shared_home}" ]]; then
+    shared_home="$(resolve_shared_agent_home)"
+  fi
+  printf '%s/skills/openclaw/%s\n' "${shared_home}" "$(flow_canonical_skill_name)"
+}
+
+resolve_source_compat_skill_dir() {
+  local shared_home="${1:-}"
+  local compat_alias=""
+  if [[ -z "${shared_home}" ]]; then
+    shared_home="$(resolve_shared_agent_home)"
+  fi
+  compat_alias="$(flow_compat_skill_alias)"
+  if [[ -z "${compat_alias}" ]]; then
+    printf '\n'
+    return 0
+  fi
+  printf '%s/skills/openclaw/%s\n' "${shared_home}" "${compat_alias}"
+}
+
+flow_export_project_env_aliases

package/tools/bin/heartbeat-recovery-preflight.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FLOW_TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_DIR="${FLOW_TOOLS_DIR%/bin}/tests"
+TEST_TIMEOUT_SECONDS="${F_LOSNING_HEARTBEAT_PREFLIGHT_TEST_TIMEOUT_SECONDS:-120}"
+
+run_with_timeout() {
+  local timeout_seconds="${1:?timeout seconds required}"
+  shift
+
+  /opt/homebrew/bin/python3 - "$timeout_seconds" "$@" <<'PY'
+import os
+import signal
+import subprocess
+import sys
+
+timeout_seconds = float(sys.argv[1])
+argv = sys.argv[2:]
+
+if not argv:
+    sys.exit(64)
+
+proc = subprocess.Popen(argv, start_new_session=True)
+try:
+    sys.exit(proc.wait(timeout=timeout_seconds))
+except subprocess.TimeoutExpired:
+    try:
+        os.killpg(proc.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        pass
+    try:
+        proc.wait(timeout=2)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        proc.wait()
+    sys.exit(124)
+PY
+}
+
+run_preflight_test() {
+  local label="${1:?label required}"
+  local script_path="${2:?script path required}"
+  local started_at
+
+  started_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  printf '[%s] heartbeat preflight start name=%s\n' "$started_at" "$label"
+
+  if run_with_timeout "$TEST_TIMEOUT_SECONDS" bash "$script_path"; then
+    printf '[%s] heartbeat preflight end name=%s status=0\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$label"
+    return 0
+  fi
+
+  local test_status=$?
+  if [[ "$test_status" == "124" ]]; then
+    printf 'HEARTBEAT_PREFLIGHT_TIMEOUT=%s\n' "$label"
+  fi
+  printf '[%s] heartbeat preflight end name=%s status=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$label" "$test_status"
+  return "$test_status"
+}
+
+run_preflight_test "codex-recovery" "${TEST_DIR}/test-agent-project-codex-recovery.sh"
+run_preflight_test "codex-quota-manager-failure-driven-rotation" "${TEST_DIR}/test-codex-quota-manager-failure-driven-rotation.sh"
+run_preflight_test "codex-quota-wrapper" "${TEST_DIR}/test-codex-quota-wrapper.sh"
+run_preflight_test "codex-quota-resolvers" "${TEST_DIR}/test-flow-resolve-codex-quota-tools.sh"
+run_preflight_test "codex-live-thread-persist" "${TEST_DIR}/test-agent-project-codex-live-thread-persist.sh"
+run_preflight_test "reconcile-failure-reason" "${TEST_DIR}/test-agent-project-reconcile-failure-reason.sh"
+run_preflight_test "reconcile-pr-updated-branch-noop" "${TEST_DIR}/test-agent-project-reconcile-pr-updated-branch-noop.sh"
+run_preflight_test "reconcile-pr-guard-blocked-no-commit" "${TEST_DIR}/test-agent-project-reconcile-pr-guard-blocked-no-commit.sh"
+run_preflight_test "reconcile-pr-blocked-host-recovery" "${TEST_DIR}/test-agent-project-reconcile-pr-blocked-host-recovery.sh"
+run_preflight_test "branch-verification-guard-targeted-coverage" "${TEST_DIR}/test-branch-verification-guard-targeted-coverage.sh"
+run_preflight_test "branch-verification-guard-generated-artifacts" "${TEST_DIR}/test-branch-verification-guard-generated-artifacts.sh"
+run_preflight_test "codex-session-wrapper" "${TEST_DIR}/test-agent-project-codex-session-wrapper.sh"
+run_preflight_test "openclaw-session-wrapper" "${TEST_DIR}/test-agent-project-openclaw-session-wrapper.sh"
+run_preflight_test "cleanup-session-orphan-fallback" "${TEST_DIR}/test-agent-project-cleanup-session-orphan-fallback.sh"
+run_preflight_test "heartbeat-no-tmux-sessions" "${TEST_DIR}/test-heartbeat-safe-auto-no-tmux-sessions.sh"
+run_preflight_test "heartbeat-static-capacity-without-quota-cache" "${TEST_DIR}/test-heartbeat-safe-auto-static-capacity-without-quota-cache.sh"
+run_preflight_test "heartbeat-openclaw-skips-codex-quota" "${TEST_DIR}/test-heartbeat-safe-auto-openclaw-skips-codex-quota.sh"
+run_preflight_test "heartbeat-empty-schedule-label-sync" "${TEST_DIR}/test-heartbeat-sync-issue-labels-empty-schedule.sh"
+run_preflight_test "heartbeat-open-pr-terminal-sync" "${TEST_DIR}/test-heartbeat-sync-open-agent-prs-terminal-clears-running.sh"
+run_preflight_test "heartbeat-pr-launch-dedup" "${TEST_DIR}/test-heartbeat-loop-pr-launch-dedup.sh"
+run_preflight_test "heartbeat-auth-wait-capacity" "${TEST_DIR}/test-heartbeat-loop-auth-wait-does-not-consume-capacity.sh"
+run_preflight_test "heartbeat-blocked-recovery-ready" "${TEST_DIR}/test-heartbeat-ready-issues-blocked-recovery.sh"
+run_preflight_test "heartbeat-blocked-recovery-lane" "${TEST_DIR}/test-heartbeat-loop-blocked-recovery-lane.sh"
+run_preflight_test "heartbeat-blocked-recovery-vs-pr-reservation" "${TEST_DIR}/test-heartbeat-loop-blocked-recovery-vs-pr-reservation.sh"
+run_preflight_test "heartbeat-codex-pr-linked-issue-exclusion" "${TEST_DIR}/test-heartbeat-codex-pr-linked-issue-exclusion.sh"
+run_preflight_test "create-follow-up-issue" "${TEST_DIR}/test-create-follow-up-issue.sh"
+run_preflight_test "issue-local-workspace-install-policy" "${TEST_DIR}/test-issue-local-workspace-install-policy.sh"
+run_preflight_test "issue-publish-scope-guard-docs-signal" "${TEST_DIR}/test-issue-publish-scope-guard-docs-signal.sh"
+run_preflight_test "issue-before-blocked-hook" "${TEST_DIR}/test-agent-project-reconcile-issue-before-blocked.sh"
+run_preflight_test "start-issue-worker-local-install-routing" "${TEST_DIR}/test-start-issue-worker-local-install-routing.sh"
+run_preflight_test "start-issue-worker-blocked-context" "${TEST_DIR}/test-start-issue-worker-blocked-context.sh"
+run_preflight_test "start-pr-fix-worker-host-blocker-context" "${TEST_DIR}/test-start-pr-fix-worker-host-blocker-context.sh"
+run_preflight_test "run-codex-task-openclaw-routing" "${TEST_DIR}/test-run-codex-task-openclaw-routing.sh"
+run_preflight_test "pr-risk-local-first-no-checks" "${TEST_DIR}/test-pr-risk-local-first-no-checks.sh"
+run_preflight_test "pr-risk-fix-label-semantics" "${TEST_DIR}/test-pr-risk-fix-label-semantics.sh"
+run_preflight_test "sync-pr-labels-fix-lane-uses-repair-queued" "${TEST_DIR}/test-sync-pr-labels-fix-lane-uses-repair-queued.sh"
+run_preflight_test "audit-broken-worktree-cleanup" "${TEST_DIR}/test-audit-agent-worktrees-broken-worktree.sh"
+run_preflight_test "audit-active-launch-skip" "${TEST_DIR}/test-audit-agent-worktrees-active-launch-skips-git-inspection.sh"
+run_preflight_test "audit-pending-launch-owner" "${TEST_DIR}/test-audit-agent-worktrees-pending-launch-owner.sh"
+run_preflight_test "audit-unreconciled-owner" "${TEST_DIR}/test-audit-agent-worktrees-unreconciled-owner.sh"
+
+printf 'HEARTBEAT_PREFLIGHT_OK\n'