agent-control-plane 0.3.0 → 0.4.9

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

@@ -29,6 +29,38 @@ flow_resolve_python_bin() {
   return 1
 }
 
+flow_format_epoch_utc() {
+  local epoch="${1:-}"
+  local python_bin=""
+
+  if ! [[ "${epoch}" =~ ^[0-9]+$ ]] || [[ "${epoch}" == "0" ]]; then
+    return 1
+  fi
+
+  if date -u -r "${epoch}" +"%Y-%m-%dT%H:%M:%SZ" >/dev/null 2>&1; then
+    date -u -r "${epoch}" +"%Y-%m-%dT%H:%M:%SZ"
+    return 0
+  fi
+
+  if date -u -d "@${epoch}" +"%Y-%m-%dT%H:%M:%SZ" >/dev/null 2>&1; then
+    date -u -d "@${epoch}" +"%Y-%m-%dT%H:%M:%SZ"
+    return 0
+  fi
+
+  python_bin="$(flow_resolve_python_bin 2>/dev/null || true)"
+  if [[ -n "${python_bin}" ]]; then
+    "${python_bin}" - "${epoch}" <<'PY'
+import datetime
+import sys
+
+print(datetime.datetime.fromtimestamp(int(sys.argv[1]), datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"))
+PY
+    return 0
+  fi
+
+  return 1
+}
+
 flow_compat_skill_alias() {
   printf '%s\n' "${AGENT_CONTROL_PLANE_COMPAT_ALIAS:-}"
 }

package/tools/bin/github-core-rate-limit-state.sh

@@ -0,0 +1,77 @@
+#!/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"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  github-core-rate-limit-state.sh get
+  github-core-rate-limit-state.sh schedule [reason] [--next-at-epoch <unix-seconds>]
+  github-core-rate-limit-state.sh clear
+EOF
+}
+
+action="${1:-}"
+reason="${2:-github-api-rate-limit}"
+next_at_epoch=""
+
+if [[ $# -lt 1 ]]; then
+  usage >&2
+  exit 1
+fi
+
+shift || true
+if [[ $# -gt 0 ]]; then
+  reason="${1:-github-api-rate-limit}"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --next-at-epoch)
+      next_at_epoch="${2:-}"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+case "${action}" in
+  get|schedule|clear) ;;
+  *)
+    usage >&2
+    exit 1
+    ;;
+esac
+
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+COOLDOWNS="$(flow_resolve_retry_cooldowns "${CONFIG_YAML}")"
+
+exec_args=(
+  --state-root "${STATE_ROOT}"
+  --kind github
+  --item-id core-api
+  --action "${action}"
+  --reason "${reason}"
+  --cooldowns "${COOLDOWNS}"
+)
+
+if [[ "${action}" == "schedule" && "${next_at_epoch}" =~ ^[0-9]+$ ]]; then
+  exec_args+=(--next-at-epoch "${next_at_epoch}")
+fi
+
+ACP_STATE_ROOT="${STATE_ROOT}" \
+ACP_RETRY_COOLDOWNS="${COOLDOWNS}" \
+exec bash "${SCRIPT_DIR}/agent-project-retry-state" "${exec_args[@]}"

package/tools/bin/github-write-outbox.sh

@@ -0,0 +1,470 @@
+#!/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"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  github-write-outbox.sh enqueue-labels --repo-slug <owner/repo> --number <id> [--add LABEL]... [--remove LABEL]...
+  github-write-outbox.sh enqueue-comment --repo-slug <owner/repo> --number <id> --kind issue|pr --body-file <path>
+  github-write-outbox.sh enqueue-approval --repo-slug <owner/repo> --number <id> [--body <text>]
+  github-write-outbox.sh flush [--limit <n>]
+
+Persist GitHub write intents locally so ACP can continue operating while GitHub
+is unavailable or rate-limited.
+EOF
+}
+
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+OUTBOX_ROOT="${ACP_GITHUB_OUTBOX_ROOT:-${STATE_ROOT}/github-outbox}"
+PENDING_DIR="${OUTBOX_ROOT}/pending"
+SENT_DIR="${OUTBOX_ROOT}/sent"
+FAILED_DIR="${OUTBOX_ROOT}/failed"
+PYTHON_BIN="$(flow_resolve_python_bin || true)"
+ACTION="${1:-}"
+DEFAULT_APPROVAL_BODY="Automated final review passed. Safe low-risk scope, green checks, and host-side merge approved."
+
+mkdir -p "${PENDING_DIR}" "${SENT_DIR}" "${FAILED_DIR}"
+
+json_hash() {
+  local payload="${1:-}"
+
+  if command -v shasum >/dev/null 2>&1; then
+    printf '%s' "${payload}" | shasum -a 256 | awk '{print $1}'
+    return 0
+  fi
+
+  if command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "${payload}" | sha256sum | awk '{print $1}'
+    return 0
+  fi
+
+  if [[ -n "${PYTHON_BIN:-}" ]]; then
+    PAYLOAD="${payload}" "${PYTHON_BIN}" - <<'PY'
+import hashlib
+import os
+
+print(hashlib.sha256((os.environ.get("PAYLOAD", "")).encode("utf-8")).hexdigest())
+PY
+    return 0
+  fi
+
+  return 1
+}
+
+outbox_move_sent() {
+  local intent_file="${1:?intent file required}"
+  mv "${intent_file}" "${SENT_DIR}/$(basename "${intent_file}")"
+}
+
+outbox_move_failed() {
+  local intent_file="${1:?intent file required}"
+  mv "${intent_file}" "${FAILED_DIR}/$(basename "${intent_file}")"
+}
+
+enqueue_labels() {
+  local repo_slug=""
+  local number=""
+  local add_file=""
+  local remove_file=""
+  local add_json="[]"
+  local remove_json="[]"
+  local created_at=""
+  local payload=""
+  local digest=""
+  local intent_file=""
+
+  add_file="$(mktemp)"
+  remove_file="$(mktemp)"
+  trap 'rm -f "${add_file}" "${remove_file}"' RETURN
+
+  shift
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --repo-slug) repo_slug="${2:-}"; shift 2 ;;
+      --number) number="${2:-}"; shift 2 ;;
+      --add)
+        printf '%s\n' "${2:?missing label after --add}" >>"${add_file}"
+        shift 2
+        ;;
+      --remove)
+        printf '%s\n' "${2:?missing label after --remove}" >>"${remove_file}"
+        shift 2
+        ;;
+      --help|-h) usage; exit 0 ;;
+      *)
+        echo "unknown argument: $1" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  [[ -n "${repo_slug}" && -n "${number}" ]] || {
+    usage >&2
+    exit 1
+  }
+
+  add_json="$(jq -R . <"${add_file}" | jq -s 'map(select(length > 0)) | unique')"
+  remove_json="$(jq -R . <"${remove_file}" | jq -s 'map(select(length > 0)) | unique')"
+  created_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  payload="$(
+    jq -cn \
+      --arg type "labels" \
+      --arg repo_slug "${repo_slug}" \
+      --arg number "${number}" \
+      --arg created_at "${created_at}" \
+      --argjson add "${add_json}" \
+      --argjson remove "${remove_json}" \
+      '{
+        type: $type,
+        repo_slug: $repo_slug,
+        number: $number,
+        created_at: $created_at,
+        add: $add,
+        remove: $remove
+      }'
+  )"
+  digest="$(json_hash "${payload}")"
+  intent_file="${PENDING_DIR}/labels-${number}-${digest}.json"
+  if [[ ! -f "${intent_file}" ]]; then
+    printf '%s\n' "${payload}" >"${intent_file}"
+  fi
+  printf 'OUTBOX_FILE=%s\n' "${intent_file}"
+}
+
+enqueue_comment() {
+  local repo_slug=""
+  local number=""
+  local kind=""
+  local body_file=""
+  local body=""
+  local body_sha=""
+  local created_at=""
+  local payload=""
+  local intent_file=""
+
+  shift
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --repo-slug) repo_slug="${2:-}"; shift 2 ;;
+      --number) number="${2:-}"; shift 2 ;;
+      --kind) kind="${2:-}"; shift 2 ;;
+      --body-file) body_file="${2:-}"; shift 2 ;;
+      --help|-h) usage; exit 0 ;;
+      *)
+        echo "unknown argument: $1" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  [[ -n "${repo_slug}" && -n "${number}" && -n "${kind}" && -n "${body_file}" ]] || {
+    usage >&2
+    exit 1
+  }
+  [[ "${kind}" == "issue" || "${kind}" == "pr" ]] || {
+    echo "unsupported comment kind: ${kind}" >&2
+    exit 1
+  }
+  [[ -f "${body_file}" ]] || {
+    echo "missing comment body file: ${body_file}" >&2
+    exit 1
+  }
+
+  body="$(cat "${body_file}")"
+  [[ -n "${body}" ]] || {
+    echo "empty comment body" >&2
+    exit 1
+  }
+
+  body_sha="$(json_hash "${body}")"
+  created_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  payload="$(
+    jq -cn \
+      --arg type "comment" \
+      --arg repo_slug "${repo_slug}" \
+      --arg number "${number}" \
+      --arg kind "${kind}" \
+      --arg body "${body}" \
+      --arg body_sha "${body_sha}" \
+      --arg created_at "${created_at}" \
+      '{
+        type: $type,
+        repo_slug: $repo_slug,
+        number: $number,
+        kind: $kind,
+        body: $body,
+        body_sha: $body_sha,
+        created_at: $created_at
+      }'
+  )"
+  intent_file="${PENDING_DIR}/comment-${kind}-${number}-${body_sha}.json"
+  if [[ ! -f "${intent_file}" ]]; then
+    printf '%s\n' "${payload}" >"${intent_file}"
+  fi
+  printf 'OUTBOX_FILE=%s\n' "${intent_file}"
+}
+
+enqueue_approval() {
+  local repo_slug=""
+  local number=""
+  local body="${DEFAULT_APPROVAL_BODY}"
+  local body_sha=""
+  local created_at=""
+  local payload=""
+  local intent_file=""
+
+  shift
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --repo-slug) repo_slug="${2:-}"; shift 2 ;;
+      --number) number="${2:-}"; shift 2 ;;
+      --body) body="${2:-}"; shift 2 ;;
+      --help|-h) usage; exit 0 ;;
+      *)
+        echo "unknown argument: $1" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  [[ -n "${repo_slug}" && -n "${number}" && -n "${body}" ]] || {
+    usage >&2
+    exit 1
+  }
+
+  body_sha="$(json_hash "${body}")"
+  created_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  payload="$(
+    jq -cn \
+      --arg type "approval" \
+      --arg repo_slug "${repo_slug}" \
+      --arg number "${number}" \
+      --arg body "${body}" \
+      --arg body_sha "${body_sha}" \
+      --arg created_at "${created_at}" \
+      '{
+        type: $type,
+        repo_slug: $repo_slug,
+        number: $number,
+        body: $body,
+        body_sha: $body_sha,
+        created_at: $created_at
+      }'
+  )"
+  intent_file="${PENDING_DIR}/approval-${number}-${body_sha}.json"
+  if [[ ! -f "${intent_file}" ]]; then
+    printf '%s\n' "${payload}" >"${intent_file}"
+  fi
+  printf 'OUTBOX_FILE=%s\n' "${intent_file}"
+}
+
+flush_comment_intent() {
+  local intent_file="${1:?intent file required}"
+  local repo_slug=""
+  local number=""
+  local kind=""
+  local body=""
+  local existing_json=""
+  local post_payload=""
+
+  repo_slug="$(jq -r '.repo_slug // ""' "${intent_file}")"
+  number="$(jq -r '.number // ""' "${intent_file}")"
+  kind="$(jq -r '.kind // ""' "${intent_file}")"
+  body="$(jq -r '.body // ""' "${intent_file}")"
+
+  [[ -n "${repo_slug}" && -n "${number}" && -n "${kind}" && -n "${body}" ]] || return 65
+
+  if [[ "${kind}" == "pr" ]]; then
+    existing_json="$(flow_github_pr_view_json "${repo_slug}" "${number}" 2>/dev/null || true)"
+  else
+    existing_json="$(flow_github_issue_view_json "${repo_slug}" "${number}" 2>/dev/null || true)"
+  fi
+
+  if [[ -n "${existing_json}" ]] && jq -e --arg body "${body}" 'any(.comments[]?; .body == $body)' >/dev/null <<<"${existing_json}" 2>/dev/null; then
+    return 0
+  fi
+
+  post_payload="$(jq -cn --arg body "${body}" '{body: $body}')"
+  if printf '%s' "${post_payload}" | flow_github_api_repo "${repo_slug}" "issues/${number}/comments" --method POST --input - >/dev/null 2>&1; then
+    return 0
+  fi
+
+  if flow_github_core_rate_limit_active; then
+    return 75
+  fi
+
+  return 1
+}
+
+flush_labels_intent() {
+  local intent_file="${1:?intent file required}"
+  local repo_slug=""
+  local number=""
+  local -a args=()
+  local label=""
+
+  repo_slug="$(jq -r '.repo_slug // ""' "${intent_file}")"
+  number="$(jq -r '.number // ""' "${intent_file}")"
+  [[ -n "${repo_slug}" && -n "${number}" ]] || return 65
+
+  args=(--repo-slug "${repo_slug}" --number "${number}")
+  while IFS= read -r label; do
+    [[ -n "${label}" ]] || continue
+    args+=(--add "${label}")
+  done < <(jq -r '.add[]? // empty' "${intent_file}")
+  while IFS= read -r label; do
+    [[ -n "${label}" ]] || continue
+    args+=(--remove "${label}")
+  done < <(jq -r '.remove[]? // empty' "${intent_file}")
+
+  if ACP_GITHUB_OUTBOX_DISABLE_ENQUEUE=1 bash "${SCRIPT_DIR}/agent-github-update-labels" "${args[@]}" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  if flow_github_core_rate_limit_active; then
+    return 75
+  fi
+
+  return 1
+}
+
+flush_approval_intent() {
+  local intent_file="${1:?intent file required}"
+  local repo_slug=""
+  local number=""
+  local body=""
+  local reviews_json="[]"
+  local post_payload=""
+
+  repo_slug="$(jq -r '.repo_slug // ""' "${intent_file}")"
+  number="$(jq -r '.number // ""' "${intent_file}")"
+  body="$(jq -r '.body // ""' "${intent_file}")"
+
+  [[ -n "${repo_slug}" && -n "${number}" && -n "${body}" ]] || return 65
+
+  if reviews_json="$(flow_github_api_repo "${repo_slug}" "pulls/${number}/reviews?per_page=100" 2>/dev/null)"; then
+    reviews_json="$(flow_json_or_default "${reviews_json}" '[]')"
+    if jq -e --arg body "${body}" 'any(.[]?; (.state // "") == "APPROVED" and (.body // "") == $body)' >/dev/null <<<"${reviews_json}" 2>/dev/null; then
+      return 0
+    fi
+  elif flow_github_core_rate_limit_active; then
+    return 75
+  fi
+
+  post_payload="$(jq -cn --arg event "APPROVE" --arg body "${body}" '{event: $event, body: $body}')"
+  if printf '%s' "${post_payload}" | flow_github_api_repo "${repo_slug}" "pulls/${number}/reviews" --method POST --input - >/dev/null 2>&1; then
+    return 0
+  fi
+
+  if flow_github_core_rate_limit_active; then
+    return 75
+  fi
+
+  return 1
+}
+
+flush_outbox() {
+  local limit="25"
+  local processed="0"
+  local intent_file=""
+  local intent_type=""
+  local status="0"
+
+  shift
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --limit) limit="${2:-25}"; shift 2 ;;
+      --help|-h) usage; exit 0 ;;
+      *)
+        echo "unknown argument: $1" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  [[ -d "${PENDING_DIR}" ]] || exit 0
+  flow_github_core_rate_limit_active && exit 0
+
+  while IFS= read -r intent_file; do
+    [[ -n "${intent_file}" ]] || continue
+    if (( processed >= limit )); then
+      break
+    fi
+
+    intent_type="$(jq -r '.type // ""' "${intent_file}" 2>/dev/null || true)"
+    case "${intent_type}" in
+      labels)
+        if flush_labels_intent "${intent_file}"; then
+          status="0"
+        else
+          status="$?"
+        fi
+        ;;
+      comment)
+        if flush_comment_intent "${intent_file}"; then
+          status="0"
+        else
+          status="$?"
+        fi
+        ;;
+      approval)
+        if flush_approval_intent "${intent_file}"; then
+          status="0"
+        else
+          status="$?"
+        fi
+        ;;
+      *)
+        status="65"
+        ;;
+    esac
+
+    case "${status}" in
+      0)
+        outbox_move_sent "${intent_file}"
+        ;;
+      65)
+        outbox_move_failed "${intent_file}"
+        ;;
+      75)
+        break
+        ;;
+      *)
+        break
+        ;;
+    esac
+
+    processed=$((processed + 1))
+  done < <(find "${PENDING_DIR}" -mindepth 1 -maxdepth 1 -type f -name '*.json' 2>/dev/null | sort)
+
+  printf 'OUTBOX_FLUSHED=%s\n' "${processed}"
+}
+
+case "${ACTION}" in
+  enqueue-labels)
+    enqueue_labels "$@"
+    ;;
+  enqueue-comment)
+    enqueue_comment "$@"
+    ;;
+  enqueue-approval)
+    enqueue_approval "$@"
+    ;;
+  flush)
+    flush_outbox "$@"
+    ;;
+  --help|-h|"")
+    usage
+    exit 0
+    ;;
+  *)
+    echo "unknown action: ${ACTION}" >&2
+    usage >&2
+    exit 1
+    ;;
+esac

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

@@ -268,9 +268,9 @@ record_scheduled_issue_launch() {
   cat >"$state_file" <<EOF
 INTERVAL_SECONDS=${interval_seconds}
 LAST_STARTED_EPOCH=${now_epoch}
-LAST_STARTED_AT=$(date -u -r "$now_epoch" +"%Y-%m-%dT%H:%M:%SZ")
+LAST_STARTED_AT=$(flow_format_epoch_utc "$now_epoch")
 NEXT_DUE_EPOCH=${next_due_epoch}
-NEXT_DUE_AT=$(date -u -r "$next_due_epoch" +"%Y-%m-%dT%H:%M:%SZ")
+NEXT_DUE_AT=$(flow_format_epoch_utc "$next_due_epoch")
 UPDATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 EOF
 }
@@ -299,12 +299,12 @@ record_scheduled_issue_result() {
   cat >"$state_file" <<EOF
 INTERVAL_SECONDS=${interval_seconds}
 LAST_STARTED_EPOCH=${last_started_epoch}
-LAST_STARTED_AT=$(if [[ "$last_started_epoch" =~ ^[0-9]+$ ]] && (( last_started_epoch > 0 )); then date -u -r "$last_started_epoch" +"%Y-%m-%dT%H:%M:%SZ"; fi)
+LAST_STARTED_AT=$(if [[ "$last_started_epoch" =~ ^[0-9]+$ ]] && (( last_started_epoch > 0 )); then flow_format_epoch_utc "$last_started_epoch"; fi)
 LAST_RESULT_STATUS=${result_status}
 LAST_RESULT_EPOCH=${now_epoch}
-LAST_RESULT_AT=$(date -u -r "$now_epoch" +"%Y-%m-%dT%H:%M:%SZ")
+LAST_RESULT_AT=$(flow_format_epoch_utc "$now_epoch")
 NEXT_DUE_EPOCH=${next_due_epoch}
-NEXT_DUE_AT=$(if [[ "$next_due_epoch" =~ ^[0-9]+$ ]] && (( next_due_epoch > 0 )); then date -u -r "$next_due_epoch" +"%Y-%m-%dT%H:%M:%SZ"; fi)
+NEXT_DUE_AT=$(if [[ "$next_due_epoch" =~ ^[0-9]+$ ]] && (( next_due_epoch > 0 )); then flow_format_epoch_utc "$next_due_epoch"; fi)
 UPDATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 EOF
 }
@@ -361,14 +361,14 @@ record_blocked_recovery_issue_launch() {
   next_due_at=""
   if [[ "${blocked_recovery_cooldown_seconds:-}" =~ ^[1-9][0-9]*$ ]]; then
     next_due_epoch=$((now_epoch + blocked_recovery_cooldown_seconds))
-    next_due_at="$(date -u -r "$next_due_epoch" +"%Y-%m-%dT%H:%M:%SZ")"
+    next_due_at="$(flow_format_epoch_utc "$next_due_epoch")"
   fi
 
   state_file="$(blocked_recovery_state_file "$issue_id")"
   cat >"$state_file" <<EOF
 LANE=blocked-recovery
 LAST_STARTED_EPOCH=${now_epoch}
-LAST_STARTED_AT=$(date -u -r "$now_epoch" +"%Y-%m-%dT%H:%M:%SZ")
+LAST_STARTED_AT=$(flow_format_epoch_utc "$now_epoch")
 NEXT_DUE_EPOCH=${next_due_epoch}
 NEXT_DUE_AT=${next_due_at}
 UPDATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

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

@@ -615,12 +615,35 @@ else
   exit "${loop_status}"
 fi
 
+# ── Flush local GitHub write outbox ────────────────────────────────────────────
+GITHUB_OUTBOX_FLUSH_LIMIT="${ACP_GITHUB_OUTBOX_FLUSH_LIMIT:-${F_LOSNING_GITHUB_OUTBOX_FLUSH_LIMIT:-25}}"
+GITHUB_OUTBOX_FLUSH_TIMEOUT_SECONDS="${ACP_GITHUB_OUTBOX_FLUSH_TIMEOUT_SECONDS:-${F_LOSNING_GITHUB_OUTBOX_FLUSH_TIMEOUT_SECONDS:-30}}"
+if [[ -x "${FLOW_TOOLS_DIR}/github-write-outbox.sh" ]]; then
+  printf '[%s] github-outbox flush start\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  if run_with_timeout "${GITHUB_OUTBOX_FLUSH_TIMEOUT_SECONDS}" \
+    env \
+      ACP_STATE_ROOT="$STATE_ROOT" \
+      F_LOSNING_STATE_ROOT="$STATE_ROOT" \
+      ACP_RUNS_ROOT="$RUNS_ROOT" \
+      F_LOSNING_RUNS_ROOT="$RUNS_ROOT" \
+      bash "${FLOW_TOOLS_DIR}/github-write-outbox.sh" flush --limit "${GITHUB_OUTBOX_FLUSH_LIMIT}"; then
+    printf '[%s] github-outbox flush end status=0\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  else
+    github_outbox_status=$?
+    if [[ "${github_outbox_status}" -eq 124 ]]; then
+      printf 'GITHUB_OUTBOX_FLUSH_TIMEOUT=yes\n'
+    fi
+    printf '[%s] github-outbox flush end status=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${github_outbox_status}"
+  fi
+fi
+
 # ── 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"
+SOURCE_REPO_SYNC_TIMEOUT_SECONDS="${ACP_SOURCE_REPO_SYNC_TIMEOUT_SECONDS:-${F_LOSNING_SOURCE_REPO_SYNC_TIMEOUT_SECONDS:-45}}"
 _catchup_now="$(date +%s)"
 _catchup_last="0"
 if [[ -f "${CATCHUP_STAMP_FILE}" ]]; then
@@ -648,6 +671,25 @@ if [[ "${_catchup_age}" -ge "${CATCHUP_INTERVAL_SECONDS}" ]]; then
     printf '[%s] merged-pr catchup end status=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${catchup_status}"
   fi
 
+  if [[ -x "${FLOW_TOOLS_DIR}/agent-project-sync-source-repo-main" ]]; then
+    printf '[%s] source-repo main sync start\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+    if run_with_timeout "${SOURCE_REPO_SYNC_TIMEOUT_SECONDS}" \
+      env \
+        ACP_RUNS_ROOT="$RUNS_ROOT" \
+        F_LOSNING_RUNS_ROOT="$RUNS_ROOT" \
+        ACP_STATE_ROOT="$STATE_ROOT" \
+        F_LOSNING_STATE_ROOT="$STATE_ROOT" \
+        bash "${FLOW_TOOLS_DIR}/agent-project-sync-source-repo-main"; then
+      printf '[%s] source-repo main sync end status=0\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+    else
+      source_repo_sync_status=$?
+      if [[ "${source_repo_sync_status}" -eq 124 ]]; then
+        printf 'SOURCE_REPO_SYNC_TIMEOUT=yes\n'
+      fi
+      printf '[%s] source-repo main sync end status=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "${source_repo_sync_status}"
+    fi
+  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 \