agent-control-plane 0.1.16 → 0.3.0

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

@@ -0,0 +1,319 @@
+#!/usr/bin/env bash
+# heartbeat-loop-worker-lib.sh — tmux session queries, worker enumeration, and cache helpers
+
+all_tmux_sessions() {
+  ensure_tmux_sessions_cache
+  printf '%s\n' "$tmux_sessions_cache"
+}
+
+session_matches_prefix() {
+  local session="${1:?session required}"
+  [[ "$session" == "${issue_prefix}"* || "$session" == "${pr_prefix}"* ]]
+}
+
+session_runner_state() {
+  local session="${1:?session required}"
+  local runner_state_file="${runs_root}/${session}/runner.env"
+  if [[ ! -f "$runner_state_file" ]]; then
+    return 1
+  fi
+  awk -F= '/^RUNNER_STATE=/{print $2; exit}' "$runner_state_file"
+}
+
+session_is_auth_waiting() {
+  local session="${1:?session required}"
+  local runner_state=""
+  runner_state="$(session_runner_state "$session" || true)"
+  [[ "$runner_state" == "waiting-auth-refresh" || "$runner_state" == "switching-account" ]]
+}
+
+all_running_workers() {
+  ensure_all_running_workers_cache
+  printf '%s\n' "$all_running_workers_cache"
+}
+
+running_issue_workers() {
+  ensure_running_issue_workers_cache
+  printf '%s\n' "$running_issue_workers_cache"
+}
+
+running_pr_workers() {
+  ensure_running_pr_workers_cache
+  printf '%s\n' "$running_pr_workers_cache"
+}
+
+auth_wait_workers() {
+  ensure_auth_wait_workers_cache
+  printf '%s\n' "$auth_wait_workers_cache"
+}
+
+pending_launch_pid() {
+  local kind="${1:?kind required}"
+  local item_id="${2:?item id required}"
+  local pending_file pid
+
+  pending_file="${pending_launch_dir}/${kind}-${item_id}.pid"
+  if [[ ! -f "$pending_file" ]]; then
+    return 1
+  fi
+
+  pid="$(tr -d '[:space:]' <"$pending_file" 2>/dev/null || true)"
+  if [[ -z "$pid" ]]; then
+    rm -f "$pending_file"
+    return 1
+  fi
+
+  if kill -0 "$pid" 2>/dev/null; then
+    printf '%s\n' "$pid"
+    return 0
+  fi
+
+  rm -f "$pending_file"
+  return 1
+}
+
+pending_issue_launch_active() {
+  local issue_id="${1:?issue id required}"
+  if tmux has-session -t "${issue_prefix}${issue_id}" 2>/dev/null; then
+    rm -f "${pending_launch_dir}/issue-${issue_id}.pid" 2>/dev/null || true
+    return 1
+  fi
+  pending_launch_pid issue "$issue_id" >/dev/null
+}
+
+pending_pr_launch_active() {
+  local pr_id="${1:?pr id required}"
+  if tmux has-session -t "${pr_prefix}${pr_id}" 2>/dev/null; then
+    rm -f "${pending_launch_dir}/pr-${pr_id}.pid" 2>/dev/null || true
+    return 1
+  fi
+  pending_launch_pid pr "$pr_id" >/dev/null
+}
+
+pending_issue_launch_counts_toward_capacity() {
+  local issue_id="${1:?issue id required}"
+  local controller_state=""
+
+  if ! pending_issue_launch_active "${issue_id}"; then
+    return 1
+  fi
+
+  controller_state="$(resident_issue_controller_state "${issue_id}" || true)"
+  if [[ -n "${controller_state}" ]]; then
+    case "${controller_state}" in
+      idle|sleeping|waiting-due|waiting-open-pr|waiting-provider)
+        return 1
+        ;;
+    esac
+  fi
+
+  return 0
+}
+
+resident_issue_controller_file() {
+  local issue_id="${1:?issue id required}"
+  printf '%s/resident-workers/issues/%s/controller.env\n' "${state_root}" "${issue_id}"
+}
+
+resident_issue_controller_state() {
+  local issue_id="${1:?issue id required}"
+  local controller_file state=""
+
+  controller_file="$(resident_issue_controller_file "$issue_id")"
+  [[ -f "${controller_file}" ]] || return 1
+
+  state="$(awk -F= '/^CONTROLLER_STATE=/{print $2; exit}' "${controller_file}" 2>/dev/null | tr -d '"' || true)"
+  [[ -n "${state}" ]] || return 1
+  printf '%s\n' "${state}"
+}
+
+issue_id_from_session() {
+  local session="${1:?session required}"
+  local issue_id=""
+  if [[ "$session" == "${issue_prefix}"* ]]; then
+    issue_id="${session#${issue_prefix}}"
+  fi
+  if [[ "$issue_id" =~ ^[0-9]+$ ]]; then
+    printf '%s\n' "$issue_id"
+    return 0
+  fi
+  return 1
+}
+
+pr_id_from_session() {
+  local session="${1:?session required}"
+  local pr_id=""
+  if [[ "$session" == "${pr_prefix}"* ]]; then
+    pr_id="${session#${pr_prefix}}"
+  fi
+  if [[ "$pr_id" =~ ^[0-9]+$ ]]; then
+    printf '%s\n' "$pr_id"
+    return 0
+  fi
+  return 1
+}
+
+worker_count() {
+  local workers="${1:-}"
+  if [[ -z "$workers" ]]; then
+    printf '0\n'
+    return
+  fi
+  printf '%s\n' "$workers" | sed '/^$/d' | wc -l | tr -d ' '
+}
+
+retry_ready() {
+  local kind="${1:?kind required}"
+  local item_id="${2:?item id required}"
+  local retry_out ready
+
+  retry_out="$(
+    "${shared_agent_home}/tools/bin/agent-project-retry-state" \
+      --state-root "$state_root" \
+      --kind "$kind" \
+      --item-id "$item_id" \
+      --action get
+  )"
+  ready="$(awk -F= '/^READY=/{print $2}' <<<"$retry_out")"
+  [[ "$ready" == "yes" ]]
+}
+
+provider_cooldown_state() {
+  "${shared_agent_home}/tools/bin/provider-cooldown-state.sh" get
+}
+
+completed_workers() {
+  ensure_completed_workers_cache
+  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_tmux_sessions_cache() {
+  if [[ "$tmux_sessions_cache_loaded" != "yes" ]]; then
+    tmux_sessions_cache="$(tmux list-sessions -F '#S' 2>/dev/null || true)"
+    tmux_sessions_cache_loaded="yes"
+  fi
+}
+
+ensure_all_running_workers_cache() {
+  local session
+  if [[ "$all_running_workers_cache_loaded" == "yes" ]]; then
+    return 0
+  fi
+  ensure_tmux_sessions_cache
+  all_running_workers_cache=""
+  while IFS= read -r session; do
+    [[ -n "$session" ]] || continue
+    if session_matches_prefix "$session"; then
+      all_running_workers_cache+="${session}"$'\n'
+    fi
+  done <<<"$tmux_sessions_cache"
+  all_running_workers_cache="${all_running_workers_cache%$'\n'}"
+  all_running_workers_cache_loaded="yes"
+}
+
+ensure_auth_wait_workers_cache() {
+  local session
+  if [[ "$auth_wait_workers_cache_loaded" == "yes" ]]; then
+    return 0
+  fi
+  ensure_tmux_sessions_cache
+  auth_wait_workers_cache=""
+  while IFS= read -r session; do
+    [[ -n "$session" ]] || continue
+    session_matches_prefix "$session" || continue
+    if session_is_auth_waiting "$session"; then
+      auth_wait_workers_cache+="${session}"$'\n'
+    fi
+  done <<<"$tmux_sessions_cache"
+  auth_wait_workers_cache="${auth_wait_workers_cache%$'\n'}"
+  auth_wait_workers_cache_loaded="yes"
+}
+
+ensure_running_issue_workers_cache() {
+  local session
+  if [[ "$running_issue_workers_cache_loaded" == "yes" ]]; then
+    return 0
+  fi
+  ensure_tmux_sessions_cache
+  running_issue_workers_cache=""
+  while IFS= read -r session; do
+    [[ -n "$session" ]] || continue
+    if [[ "$session" == "${issue_prefix}"* ]]; then
+      if session_is_auth_waiting "$session"; then
+        continue
+      fi
+      running_issue_workers_cache+="${session}"$'\n'
+    fi
+  done <<<"$tmux_sessions_cache"
+  running_issue_workers_cache="${running_issue_workers_cache%$'\n'}"
+  running_issue_workers_cache_loaded="yes"
+}
+
+ensure_running_pr_workers_cache() {
+  local session
+  if [[ "$running_pr_workers_cache_loaded" == "yes" ]]; then
+    return 0
+  fi
+  ensure_tmux_sessions_cache
+  running_pr_workers_cache=""
+  while IFS= read -r session; do
+    [[ -n "$session" ]] || continue
+    if [[ "$session" == "${pr_prefix}"* ]]; then
+      if session_is_auth_waiting "$session"; then
+        continue
+      fi
+      running_pr_workers_cache+="${session}"$'\n'
+    fi
+  done <<<"$tmux_sessions_cache"
+  running_pr_workers_cache="${running_pr_workers_cache%$'\n'}"
+  running_pr_workers_cache_loaded="yes"
+}
+
+ensure_completed_workers_cache() {
+  local dir session issue_id status_line status
+  if [[ "$completed_workers_cache_loaded" == "yes" ]]; then
+    return 0
+  fi
+  completed_workers_cache=""
+  for dir in "$runs_root"/*; do
+    [[ -d "$dir" ]] || continue
+    session="${dir##*/}"
+    session_matches_prefix "$session" || 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
+        continue
+      fi
+    fi
+    status_line="$(
+      "${shared_agent_home}/tools/bin/agent-project-worker-status" \
+        --runs-root "$runs_root" \
+        --session "$session" \
+        | awk -F= '/^STATUS=/{print $2}' || true
+    )"
+    status="${status_line:-UNKNOWN}"
+    if [[ "$status" == "SUCCEEDED" || "$status" == "FAILED" ]]; then
+      completed_workers_cache+="${session}"$'\n'
+    fi
+  done
+  completed_workers_cache="${completed_workers_cache%$'\n'}"
+  completed_workers_cache_loaded="yes"
+}

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

@@ -2,14 +2,25 @@
 set -euo pipefail
 
 FLOW_TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FLOW_SHELL_LIB="${FLOW_TOOLS_DIR}/flow-shell-lib.sh"
 TEST_DIR="${FLOW_TOOLS_DIR%/bin}/tests"
 TEST_TIMEOUT_SECONDS="${F_LOSNING_HEARTBEAT_PREFLIGHT_TEST_TIMEOUT_SECONDS:-120}"
+python_bin=""
+
+# shellcheck source=/dev/null
+source "${FLOW_SHELL_LIB}"
+
+python_bin="$(flow_resolve_python_bin || true)"
+if [[ -z "${python_bin}" || ! -x "${python_bin}" ]]; then
+  echo "unable to resolve a runnable python interpreter for heartbeat-recovery-preflight.sh" >&2
+  exit 1
+fi
 
 run_with_timeout() {
   local timeout_seconds="${1:?timeout seconds required}"
   shift
 
-  /opt/homebrew/bin/python3 - "$timeout_seconds" "$@" <<'PY'
+  "${python_bin}" - "$timeout_seconds" "$@" <<'PY'
 import os
 import signal
 import subprocess
@@ -80,6 +91,7 @@ run_preflight_test "heartbeat-no-tmux-sessions" "${TEST_DIR}/test-heartbeat-safe
 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-issue-terminal-sync" "${TEST_DIR}/test-heartbeat-sync-open-agent-issues-terminal-clears-running.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"

package/tools/bin/heartbeat-safe-auto.sh

@@ -17,6 +17,8 @@ flow_export_execution_env "${CONFIG_YAML}"
 AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
 RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
 STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+HISTORY_ROOT="$(flow_resolve_history_root "${CONFIG_YAML}")"
+WORKTREE_ROOT="$(flow_resolve_worktree_root "${CONFIG_YAML}")"
 MEMORY_DIR="${ACP_MEMORY_DIR:-${F_LOSNING_MEMORY_DIR:-${AGENT_CONTROL_PLANE_WORKSPACE:-$HOME/.agent-runtime/control-plane/workspace}/memory}}"
 REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
 MAX_CONCURRENT_WORKERS="${ACP_MAX_CONCURRENT_WORKERS:-${F_LOSNING_MAX_CONCURRENT_WORKERS:-20}}"
@@ -29,13 +31,14 @@ MAX_CONCURRENT_BLOCKED_RECOVERY_ISSUE_WORKERS="${ACP_MAX_CONCURRENT_BLOCKED_RECO
 BLOCKED_RECOVERY_COOLDOWN_SECONDS="${ACP_BLOCKED_RECOVERY_COOLDOWN_SECONDS:-${F_LOSNING_BLOCKED_RECOVERY_COOLDOWN_SECONDS:-900}}"
 MAX_OPEN_AGENT_PRS_FOR_RECURRING="${ACP_MAX_OPEN_AGENT_PRS_FOR_RECURRING:-${F_LOSNING_MAX_OPEN_AGENT_PRS_FOR_RECURRING:-12}}"
 MAX_LAUNCHES_PER_HEARTBEAT="${ACP_MAX_LAUNCHES_PER_HEARTBEAT:-${F_LOSNING_MAX_LAUNCHES_PER_HEARTBEAT:-$MAX_CONCURRENT_WORKERS}}"
-CODING_WORKER="${ACP_CODING_WORKER:-${F_LOSNING_CODING_WORKER:-codex}}"
+CODING_WORKER="${ACP_CODING_WORKER:-codex}"
 # The catchup and shared heartbeat passes can legitimately take a few minutes
 # once they reconcile stale sessions, sync labels, and launch multiple workers.
 CATCHUP_TIMEOUT_SECONDS="${ACP_CATCHUP_TIMEOUT_SECONDS:-${F_LOSNING_CATCHUP_TIMEOUT_SECONDS:-180}}"
 HEARTBEAT_LOOP_TIMEOUT_SECONDS="${ACP_HEARTBEAT_LOOP_TIMEOUT_SECONDS:-${F_LOSNING_HEARTBEAT_LOOP_TIMEOUT_SECONDS:-720}}"
 CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
 SHARED_AGENT_HOME="$(resolve_shared_agent_home "${FLOW_SKILL_DIR}")"
+RUNTIME_HOME_DIR="$(resolve_runtime_home)"
 FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
 ISSUE_SESSION_PREFIX="$(flow_resolve_issue_session_prefix "${CONFIG_YAML}")"
 PR_SESSION_PREFIX="$(flow_resolve_pr_session_prefix "${CONFIG_YAML}")"
@@ -67,8 +70,17 @@ AGENT_WORKTREE_AUDIT_TIMEOUT_SECONDS="${ACP_AGENT_WORKTREE_AUDIT_TIMEOUT_SECONDS
 LOCK_DIR="${STATE_ROOT}/heartbeat-loop.lock"
 PID_FILE="${LOCK_DIR}/pid"
 SHARED_LOOP_PID_FILE="${STATE_ROOT}/shared-heartbeat-loop.pid"
+SHARED_LOOP_STATUS_FILE="${STATE_ROOT}/shared-heartbeat-loop.env"
 QUOTA_LOCK_DIR="${STATE_ROOT}/quota-preflight.lock"
 QUOTA_PID_FILE="${QUOTA_LOCK_DIR}/pid"
+python_bin="$(flow_resolve_python_bin || true)"
+
+mkdir -p "${AGENT_ROOT}" "${RUNS_ROOT}" "${STATE_ROOT}" "${HISTORY_ROOT}" "${WORKTREE_ROOT}" "${MEMORY_DIR}"
+
+if [[ -z "${python_bin}" || ! -x "${python_bin}" ]]; then
+  echo "unable to resolve a runnable python interpreter for heartbeat-safe-auto.sh" >&2
+  exit 1
+fi
 
 acquire_lock() {
   mkdir -p "${STATE_ROOT}"
@@ -124,11 +136,34 @@ release_quota_lock() {
   rm -rf "${QUOTA_LOCK_DIR}"
 }
 
+write_shared_loop_status() {
+  local state="${1:-}"
+  local status="${2:-}"
+  local timestamp=""
+  local tmp_file=""
+
+  timestamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  mkdir -p "${STATE_ROOT}"
+  tmp_file="$(mktemp)"
+  if [[ -f "${SHARED_LOOP_STATUS_FILE}" ]]; then
+    grep -Ev '^(STATE|STATUS|STARTED_AT|UPDATED_AT)=' "${SHARED_LOOP_STATUS_FILE}" >"${tmp_file}" || true
+  fi
+  printf 'STATE=%s\n' "${state}" >>"${tmp_file}"
+  if [[ -n "${status}" ]]; then
+    printf 'STATUS=%s\n' "${status}" >>"${tmp_file}"
+  fi
+  if [[ "${state}" == "running" ]]; then
+    printf 'STARTED_AT=%s\n' "${timestamp}" >>"${tmp_file}"
+  fi
+  printf 'UPDATED_AT=%s\n' "${timestamp}" >>"${tmp_file}"
+  mv "${tmp_file}" "${SHARED_LOOP_STATUS_FILE}"
+}
+
 run_with_timeout() {
   local timeout_seconds="${1:?timeout seconds required}"
   shift
 
-  /opt/homebrew/bin/python3 - "${timeout_seconds}" "$@" <<'PY'
+  "${python_bin}" - "${timeout_seconds}" "$@" <<'PY'
 import os
 from pathlib import Path
 import signal
@@ -302,7 +337,7 @@ EFFECTIVE_QUOTA_POOLS=""
 
   local quota_cache_age_seconds=""
   quota_cache_age_seconds="$(
-    /opt/homebrew/bin/python3 - "${CODEX_QUOTA_FULL_CACHE_FILE}" <<'PY' 2>/dev/null || true
+    "${python_bin}" - "${CODEX_QUOTA_FULL_CACHE_FILE}" <<'PY' 2>/dev/null || true
 import os
 import sys
 import time
@@ -478,7 +513,11 @@ run_codex_quota_preflight
 # Sync skill files to runtime-home if source has changed since last sync.
 # This ensures start-issue-worker.sh and other scripts are always up to date.
 if [[ -x "${FLOW_TOOLS_DIR}/ensure-runtime-sync.sh" ]]; then
-  "${FLOW_TOOLS_DIR}/ensure-runtime-sync.sh" --quiet 2>/dev/null || true
+  if [[ "${FLOW_SKILL_DIR}" == "${RUNTIME_HOME_DIR}"/* ]]; then
+    printf 'RUNTIME_SYNC_SKIPPED=active-runtime-home\n'
+  else
+    "${FLOW_TOOLS_DIR}/ensure-runtime-sync.sh" --quiet 2>/dev/null || true
+  fi
 fi
 
 acquire_lock
@@ -530,6 +569,7 @@ fi
 derive_dynamic_limits
 
 printf '[%s] shared heartbeat loop start\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+write_shared_loop_status "running" ""
   if ACP_TIMEOUT_CHILD_PID_FILE="${SHARED_LOOP_PID_FILE}" \
   F_LOSNING_TIMEOUT_CHILD_PID_FILE="${SHARED_LOOP_PID_FILE}" \
   run_with_timeout "${HEARTBEAT_LOOP_TIMEOUT_SECONDS}" \
@@ -563,9 +603,11 @@ printf '[%s] shared heartbeat loop start\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
       --heavy-running-label "E2E_ISSUE" \
       --heavy-deferred-key "E2E_DEFERRED" \
       --heavy-deferred-message "E2E-heavy issues remain queued until the single e2e slot is free."; then
+  write_shared_loop_status "idle" "0"
   printf '[%s] shared heartbeat loop end status=0\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
 else
   loop_status=$?
+  write_shared_loop_status "idle" "${loop_status}"
   if [[ "${loop_status}" -eq 124 ]]; then
     printf 'HEARTBEAT_LOOP_TIMEOUT=yes\n'
   fi
@@ -573,21 +615,78 @@ else
   exit "${loop_status}"
 fi
 
-printf '[%s] merged-pr catchup start\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
-if run_with_timeout "${CATCHUP_TIMEOUT_SECONDS}" \
-  env \
-    ACP_RUNS_ROOT="$RUNS_ROOT" \
-    F_LOSNING_RUNS_ROOT="$RUNS_ROOT" \
-    bash "${FLOW_TOOLS_DIR}/agent-project-catch-up-merged-prs" \
-      --repo-slug "$REPO_SLUG" \
-      --state-root "$STATE_ROOT" \
-      --hook-file "$HOOK_FILE" \
-      --limit 100; then
-  printf '[%s] merged-pr catchup end status=0\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
-else
-  catchup_status=$?
-  if [[ "${catchup_status}" -eq 124 ]]; then
-    printf 'CATCHUP_TIMEOUT=yes\n'
+# ── Throttled catch-up passes ──────────────────────────────────────────────────
+# These scripts fetch merged/closed PRs and linked issues which change rarely.
+# Run them at most once every CATCHUP_INTERVAL_SECONDS (default 300 = 5 min)
+# to avoid burning API quota on every heartbeat cycle.
+CATCHUP_INTERVAL_SECONDS="${ACP_CATCHUP_INTERVAL_SECONDS:-${F_LOSNING_CATCHUP_INTERVAL_SECONDS:-300}}"
+CATCHUP_STAMP_FILE="${STATE_ROOT}/last-catchup-timestamp"
+_catchup_now="$(date +%s)"
+_catchup_last="0"
+if [[ -f "${CATCHUP_STAMP_FILE}" ]]; then
+  _catchup_last="$(cat "${CATCHUP_STAMP_FILE}" 2>/dev/null || echo 0)"
+fi
+_catchup_age=$(( _catchup_now - _catchup_last ))
+
+if [[ "${_catchup_age}" -ge "${CATCHUP_INTERVAL_SECONDS}" ]]; then
+  printf '[%s] merged-pr catchup start\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  if run_with_timeout "${CATCHUP_TIMEOUT_SECONDS}" \
+    env \
+      ACP_RUNS_ROOT="$RUNS_ROOT" \
+      F_LOSNING_RUNS_ROOT="$RUNS_ROOT" \
+      bash "${FLOW_TOOLS_DIR}/agent-project-catch-up-merged-prs" \
+        --repo-slug "$REPO_SLUG" \
+        --state-root "$STATE_ROOT" \
+        --hook-file "$HOOK_FILE" \
+        --limit 100; then
+    printf '[%s] merged-pr catchup end status=0\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  else
+    catchup_status=$?
+    if [[ "${catchup_status}" -eq 124 ]]; then
+      printf 'CATCHUP_TIMEOUT=yes\n'
+    fi
+    printf '[%s] merged-pr catchup end status=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${catchup_status}"
+  fi
+
+  printf '[%s] linked-pr issue catchup start\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  if run_with_timeout "${CATCHUP_TIMEOUT_SECONDS}" \
+    env \
+      ACP_RUNS_ROOT="$RUNS_ROOT" \
+      F_LOSNING_RUNS_ROOT="$RUNS_ROOT" \
+      bash "${FLOW_TOOLS_DIR}/agent-project-catch-up-issue-pr-links" \
+        --repo-slug "$REPO_SLUG" \
+        --state-root "$STATE_ROOT" \
+        --hook-file "$HOOK_FILE" \
+        --limit 100; then
+    printf '[%s] linked-pr issue catchup end status=0\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  else
+    linked_issue_catchup_status=$?
+    if [[ "${linked_issue_catchup_status}" -eq 124 ]]; then
+      printf 'LINKED_ISSUE_CATCHUP_TIMEOUT=yes\n'
+    fi
+    printf '[%s] linked-pr issue catchup end status=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${linked_issue_catchup_status}"
+  fi
+
+  printf '[%s] scheduled-issue retry catchup start\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  if run_with_timeout "${CATCHUP_TIMEOUT_SECONDS}" \
+    env \
+      ACP_RUNS_ROOT="$RUNS_ROOT" \
+      F_LOSNING_RUNS_ROOT="$RUNS_ROOT" \
+      bash "${FLOW_TOOLS_DIR}/agent-project-catch-up-scheduled-issue-retries" \
+        --repo-slug "$REPO_SLUG" \
+        --state-root "$STATE_ROOT" \
+        --hook-file "$HOOK_FILE" \
+        --limit 100; then
+    printf '[%s] scheduled-issue retry catchup end status=0\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  else
+    scheduled_issue_catchup_status=$?
+    if [[ "${scheduled_issue_catchup_status}" -eq 124 ]]; then
+      printf 'SCHEDULED_ISSUE_CATCHUP_TIMEOUT=yes\n'
+    fi
+    printf '[%s] scheduled-issue retry catchup end status=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${scheduled_issue_catchup_status}"
   fi
-  printf '[%s] merged-pr catchup end status=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${catchup_status}"
+
+  printf '%s' "${_catchup_now}" >"${CATCHUP_STAMP_FILE}"
+else
+  printf '[%s] catchup skipped (age=%ss, interval=%ss)\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${_catchup_age}" "${CATCHUP_INTERVAL_SECONDS}"
 fi

package/tools/bin/install-project-launchd.sh

@@ -54,7 +54,7 @@ build_launchd_base_path() {
   local tool_name=""
   local tool_dir=""
 
-  for tool_name in node gh git python3 openclaw codex claude; do
+  for tool_name in node gh git python3 openclaw codex claude ollama pi crush kilo; do
     tool_dir="$(resolved_tool_dir "${tool_name}" || true)"
     append_path_dir path_value "${tool_dir}"
   done
@@ -112,7 +112,14 @@ fi
 PROFILE_ID="$(flow_resolve_adapter_id "${CONFIG_YAML}")"
 profile_slug="$(printf '%s' "${PROFILE_ID}" | tr -c 'A-Za-z0-9._-' '-')"
 HOME_DIR="${ACP_PROJECT_RUNTIME_HOME_DIR:-${HOME:-}}"
-SOURCE_HOME="${ACP_PROJECT_RUNTIME_SOURCE_HOME:-$(cd "${FLOW_SKILL_DIR}/../../.." && pwd)}"
+SOURCE_HOME="${ACP_PROJECT_RUNTIME_SOURCE_HOME:-}"
+if [[ -z "${SOURCE_HOME}" ]]; then
+  if flow_is_skill_root "${FLOW_SKILL_DIR}"; then
+    SOURCE_HOME="${FLOW_SKILL_DIR}"
+  else
+    SOURCE_HOME="$(cd "${FLOW_SKILL_DIR}/../../.." && pwd)"
+  fi
+fi
 RUNTIME_HOME="${ACP_PROJECT_RUNTIME_RUNTIME_HOME:-${HOME_DIR}/.agent-runtime/runtime-home}"
 WORKSPACE_DIR="${ACP_PROJECT_RUNTIME_WORKSPACE_DIR:-${HOME_DIR}/.agent-runtime/control-plane/workspace}"
 PROFILE_REGISTRY_ROOT="${ACP_PROJECT_RUNTIME_PROFILE_REGISTRY_ROOT:-${ACP_PROFILE_REGISTRY_ROOT:-${HOME_DIR}/.agent-runtime/control-plane/profiles}}"
@@ -120,6 +127,7 @@ LAUNCH_AGENTS_DIR="${ACP_PROJECT_RUNTIME_LAUNCH_AGENTS_DIR:-${HOME_DIR}/Library/
 LOG_DIR="${ACP_PROJECT_RUNTIME_LOG_DIR:-${HOME_DIR}/.agent-runtime/logs}"
 LABEL="${label_override:-${ACP_PROJECT_RUNTIME_LAUNCHD_LABEL:-ai.agent.project.${profile_slug}}}"
 BASE_PATH="$(build_launchd_base_path)"
+CODING_WORKER_OVERRIDE="${ACP_PROJECT_RUNTIME_CODING_WORKER:-${ACP_CODING_WORKER:-}}"
 SYNC_SCRIPT="${ACP_PROJECT_RUNTIME_SYNC_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/sync-shared-agent-home.sh}"
 BOOTSTRAP_SCRIPT="${ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/project-launchd-bootstrap.sh}"
 SUPERVISOR_SCRIPT="${ACP_PROJECT_RUNTIME_SUPERVISOR_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/project-runtime-supervisor.sh}"
@@ -152,6 +160,15 @@ export AGENT_PROJECT_ID='${PROFILE_ID}'
 export ACP_PROJECT_RUNTIME_PATH='${BASE_PATH}'
 export ACP_PROJECT_RUNTIME_SYNC_SCRIPT='${SYNC_SCRIPT}'
 export ACP_PROFILE_REGISTRY_ROOT='${PROFILE_REGISTRY_ROOT}'
+EOF
+
+if [[ -n "${CODING_WORKER_OVERRIDE}" ]]; then
+  cat >>"${WRAPPER_PATH}" <<EOF
+export ACP_CODING_WORKER='${CODING_WORKER_OVERRIDE}'
+EOF
+fi
+
+cat >>"${WRAPPER_PATH}" <<EOF
 exec bash '${SUPERVISOR_SCRIPT}' --bootstrap-script '${BOOTSTRAP_SCRIPT}' --pid-file '${SUPERVISOR_PID_FILE}' --delay-seconds '${delay_seconds}' --interval-seconds '${interval_seconds}'
 EOF
 chmod +x "${WRAPPER_PATH}"

package/tools/bin/prepare-worktree.sh

@@ -9,10 +9,10 @@ CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
 AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
 CANONICAL_REPO_ROOT="$(flow_resolve_repo_root "${CONFIG_YAML}")"
 DEFAULT_DEPENDENCY_SOURCE_ROOT="$CANONICAL_REPO_ROOT"
-DEPENDENCY_SOURCE_ROOT="${ACP_DEPENDENCY_SOURCE_ROOT:-${F_LOSNING_DEPENDENCY_SOURCE_ROOT:-$DEFAULT_DEPENDENCY_SOURCE_ROOT}}"
-SYNC_DEPENDENCY_BASELINE_SCRIPT="${ACP_SYNC_DEPENDENCY_BASELINE_SCRIPT:-${F_LOSNING_SYNC_DEPENDENCY_BASELINE_SCRIPT:-${SCRIPT_DIR}/sync-dependency-baseline.sh}}"
-PACKAGE_MANAGER_BIN="${ACP_PACKAGE_MANAGER_BIN:-${F_LOSNING_PACKAGE_MANAGER_BIN:-pnpm}}"
-LOCAL_WORKSPACE_INSTALL="${ACP_WORKTREE_LOCAL_INSTALL:-${F_LOSNING_WORKTREE_LOCAL_INSTALL:-false}}"
+DEPENDENCY_SOURCE_ROOT="${ACP_DEPENDENCY_SOURCE_ROOT:-$DEFAULT_DEPENDENCY_SOURCE_ROOT}"
+SYNC_DEPENDENCY_BASELINE_SCRIPT="${ACP_SYNC_DEPENDENCY_BASELINE_SCRIPT:-${SCRIPT_DIR}/sync-dependency-baseline.sh}"
+PACKAGE_MANAGER_BIN="${ACP_PACKAGE_MANAGER_BIN:-pnpm}"
+LOCAL_WORKSPACE_INSTALL="${ACP_WORKTREE_LOCAL_INSTALL:-false}"
 WORKTREE="${1:?usage: prepare-worktree.sh WORKTREE}"
 
 realpath_safe() {

package/tools/bin/profile-activate.sh

@@ -56,8 +56,8 @@ AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
 WORKTREE_ROOT="$(flow_resolve_worktree_root "${CONFIG_YAML}")"
 RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
 STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
-CODING_WORKER="${ACP_CODING_WORKER:-${F_LOSNING_CODING_WORKER:-codex}}"
-ACTIVE_PROVIDER_POOL_NAME="${ACP_ACTIVE_PROVIDER_POOL_NAME:-${F_LOSNING_ACTIVE_PROVIDER_POOL_NAME:-}}"
+CODING_WORKER="${ACP_CODING_WORKER:-codex}"
+ACTIVE_PROVIDER_POOL_NAME="${ACP_ACTIVE_PROVIDER_POOL_NAME:-}"
 
 if [[ "${exports_only}" == "1" ]]; then
   printf 'export ACP_PROJECT_ID=%q

package/tools/bin/profile-adopt.sh

@@ -69,8 +69,8 @@ HISTORY_ROOT="$(flow_resolve_history_root "${CONFIG_YAML}")"
 WORKTREE_ROOT="$(flow_resolve_worktree_root "${CONFIG_YAML}")"
 RETAINED_REPO_ROOT="$(flow_resolve_retained_repo_root "${CONFIG_YAML}")"
 VSCODE_WORKSPACE_FILE="$(flow_resolve_vscode_workspace_file "${CONFIG_YAML}")"
-REMOTE_NAME="${ACP_REMOTE_NAME:-${F_LOSNING_REMOTE_NAME:-origin}}"
-SOURCE_REPO_ROOT="${source_repo_root_override:-${ACP_SOURCE_REPO_ROOT:-${F_LOSNING_SOURCE_REPO_ROOT:-${RETAINED_REPO_ROOT}}}}"
+REMOTE_NAME="${ACP_REMOTE_NAME:-origin}"
+SOURCE_REPO_ROOT="${source_repo_root_override:-${ACP_SOURCE_REPO_ROOT:-${RETAINED_REPO_ROOT}}}"
 PROFILE_LINK="${AGENT_ROOT}/control-plane.yaml"
 WORKSPACE_LINK="${AGENT_ROOT}/workspace.code-workspace"
 INSTALLED_PROFILE_DIR="$(dirname "${CONFIG_YAML}")"

package/tools/bin/project-init.sh

@@ -42,7 +42,7 @@ Common options:
   --worktree-root <path>             Worktree parent root
   --retained-repo-root <path>        Retained/manual checkout root
   --vscode-workspace-file <path>     VS Code workspace file
-  --coding-worker <codex|openclaw|claude>
+  --coding-worker <codex|openclaw|claude|ollama|pi|opencode|kilo>
   --claude-model <model>
   --claude-permission-mode <mode>
   --claude-effort <level>