agent-control-plane 0.3.0 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.3.0",
+  "version": "0.4.9",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {
@@ -27,11 +27,12 @@
     "bin/sync-pr-labels.sh",
     "hooks",
     "npm/bin",
-    "references",
     "tools/bin",
-    "!tools/bin/audit-*.sh",
-    "!tools/bin/check-skill-contracts.sh",
-    "!tools/bin/render-dashboard-snapshot.py",
+  "!tools/bin/audit-*.sh",
+  "!tools/bin/check-skill-contracts.sh",
+  "!tools/bin/split-retained-slice.sh",
+  "!tools/bin/render-dashboard-snapshot.py",
+  "!tools/bin/resident-issue-queue-status.py",
     "tools/dashboard/app.js",
     "tools/dashboard/dashboard_snapshot.py",
     "tools/dashboard/index.html",
@@ -47,7 +48,7 @@
   "scripts": {
     "doctor": "node ./npm/bin/agent-control-plane.js doctor",
     "smoke": "node ./npm/bin/agent-control-plane.js smoke",
-    "test": "bash tools/tests/test-agent-control-plane-npm-cli.sh && bash tools/tests/test-agent-project-detached-launch-stable-cwd.sh && bash tools/tests/test-agent-project-claude-session-wrapper-reaps-child-on-term.sh && bash tools/tests/test-agent-project-claude-session-wrapper-does-not-retry-provider-quota.sh && bash tools/tests/test-agent-project-run-codex-resilient-uses-path-python-and-gnu-stat.sh && bash tools/tests/test-heartbeat-safe-auto-uses-path-python.sh && bash tools/tests/test-heartbeat-safe-auto-skips-self-sync.sh && bash tools/tests/test-agent-project-catch-up-terminal-prs-defaults-closed-hook.sh && bash tools/tests/test-agent-project-codex-session-wrapper-prefers-path-codex.sh && bash tools/tests/test-agent-project-codex-session-wrapper-recovers-var-tmp-logged-artifacts.sh && bash tools/tests/test-agent-project-cleanup-session-removes-registered-worktree-without-rg.sh && bash tools/tests/test-agent-project-cleanup-session-propagates-failure-with-session.sh && bash tools/tests/test-cleanup-worktree-syncs-workspace-after-cleanup-failure.sh && bash tools/tests/test-resident-issue-queue-status-contract.sh && bash tools/tests/test-agent-project-reconcile-issue-provider-quota-schedules-provider-cooldown.sh && bash tools/tests/test-agent-project-reconcile-issue-session-warns-on-cleanup-failure.sh && bash tools/tests/test-agent-project-reconcile-pr-session-warns-on-cleanup-failure.sh && bash tools/tests/test-pr-reconcile-hooks-refreshes-recurring-issue-checklist.sh && bash tools/tests/test-issue-reconcile-hooks-kick-scheduler-uses-profile.sh && bash tools/tests/test-profile-adopt-skip-anchor-sync-creates-agent-repo-root.sh && bash tools/tests/test-vendored-codex-quota-claude-oauth-only.sh && bash tools/tests/test-package-smoke-command.sh"
+    "test": "node -e \"const { spawnSync } = require('node:child_process'); const result = spawnSync('bash', ['tools/tests/run-all.sh'], { stdio: 'inherit' }); if (result.error) throw result.error; process.exit(result.status ?? 1);\""
   },
   "publishConfig": {
     "access": "public",

package/tools/bin/agent-github-update-labels

@@ -20,6 +20,7 @@ number=""
 add_file="$(mktemp)"
 remove_file="$(mktemp)"
 trap 'rm -f "$add_file" "$remove_file"' EXIT
+github_outbox_script="${SCRIPT_DIR}/github-write-outbox.sh"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -47,12 +48,40 @@ if [[ -z "$repo_slug" || -z "$number" ]]; then
   exit 1
 fi
 
+enqueue_label_update() {
+  local -a args=()
+  local label=""
+
+  [[ "${ACP_GITHUB_OUTBOX_DISABLE_ENQUEUE:-0}" != "1" ]] || return 1
+  [[ -x "${github_outbox_script}" ]] || return 1
+
+  args=(enqueue-labels --repo-slug "${repo_slug}" --number "${number}")
+  while IFS= read -r label; do
+    [[ -n "${label}" ]] || continue
+    args+=(--add "${label}")
+  done <"${add_file}"
+  while IFS= read -r label; do
+    [[ -n "${label}" ]] || continue
+    args+=(--remove "${label}")
+  done <"${remove_file}"
+
+  "${github_outbox_script}" "${args[@]}" >/dev/null
+}
+
 resource="issues/${number}"
+if flow_github_core_rate_limit_active; then
+  enqueue_label_update && exit 0
+  exit 1
+fi
+
 # Use caller-provided cached JSON if available to skip the GET call
 if [[ -n "${ACP_CACHED_ISSUE_JSON:-}" ]]; then
   current_json="${ACP_CACHED_ISSUE_JSON}"
 else
-  current_json="$(flow_github_api_repo "${repo_slug}" "${resource}")"
+  if ! current_json="$(flow_github_api_repo "${repo_slug}" "${resource}")"; then
+    enqueue_label_update && exit 0
+    exit 1
+  fi
 fi
 add_json="$(jq -R . <"$add_file" | jq -s .)"
 remove_json="$(jq -R . <"$remove_file" | jq -s .)"
@@ -68,4 +97,9 @@ process.stdout.write(JSON.stringify({ labels: Array.from(labels).sort() }));
 EOF
 )"
 
-printf '%s' "$payload" | flow_github_api_repo "${repo_slug}" "${resource}" --method PATCH --input - >/dev/null
+if printf '%s' "$payload" | flow_github_api_repo "${repo_slug}" "${resource}" --method PATCH --input - >/dev/null; then
+  exit 0
+fi
+
+enqueue_label_update && exit 0
+exit 1

package/tools/bin/agent-project-catch-up-merged-prs

@@ -55,8 +55,9 @@ for hook_name in "${optional_hooks[@]}"; do
   fi
 done
 
-merged_ledger_dir="${state_root}/merged-pr-catchup"
-closed_ledger_dir="${state_root}/closed-pr-catchup"
+forge_scope="$(printf '%s' "${ACP_FORGE_PROVIDER:-${F_LOSNING_FORGE_PROVIDER:-github}}" | tr -c '[:alnum:]._-' '-')"
+merged_ledger_dir="${state_root}/merged-pr-catchup-${forge_scope}"
+closed_ledger_dir="${state_root}/closed-pr-catchup-${forge_scope}"
 mkdir -p "$merged_ledger_dir" "$closed_ledger_dir"
 
 get_pr_risk_json() {

package/tools/bin/agent-project-publish-issue-pr

@@ -186,9 +186,12 @@ fi
 resolve_actor_login() {
   local login=""
 
-  flow_export_github_cli_auth_env "${repo_slug}"
-  login="$(gh api user --jq .login 2>/dev/null || true)"
-  if [[ -z "${login}" ]]; then
+  login="$(flow_github_current_login 2>/dev/null || true)"
+  if [[ -z "${login}" && ! "$(flow_forge_provider)" =~ ^gitea$ ]]; then
+    flow_export_github_cli_auth_env "${repo_slug}"
+    login="$(gh api user --jq .login 2>/dev/null || true)"
+  fi
+  if [[ -z "${login}" && ! "$(flow_forge_provider)" =~ ^gitea$ ]]; then
     login="$(
       gh auth status 2>/dev/null \
         | sed -n 's/^  ✓ Logged in to github.com account \([^ ]*\) (.*/\1/p' \

package/tools/bin/agent-project-reconcile-issue-session

@@ -231,6 +231,7 @@ if [[ -n "$hook_file" && -f "$hook_file" ]]; then
 fi
 
 provider_cooldown_script="${shared_tools_dir}/provider-cooldown-state.sh"
+github_write_outbox_script="${shared_tools_dir}/github-write-outbox.sh"
 
 schedule_provider_quota_cooldown() {
   local reason="${1:-provider-quota-limit}"
@@ -335,7 +336,17 @@ post_issue_comment_if_present() {
   if issue_latest_comment_matches_artifact; then
     return 0
   fi
-  flow_github_api_repo "${repo_slug}" "issues/${issue_id}/comments" --method POST -f body="$(cat "$comment_file")" >/dev/null || true
+  if flow_github_api_repo "${repo_slug}" "issues/${issue_id}/comments" --method POST -f body="$(cat "$comment_file")" >/dev/null 2>&1; then
+    return 0
+  fi
+  if [[ -x "${github_write_outbox_script}" ]]; then
+    "${github_write_outbox_script}" enqueue-comment \
+      --repo-slug "${repo_slug}" \
+      --number "${issue_id}" \
+      --kind issue \
+      --body-file "${comment_file}" >/dev/null 2>&1 || true
+  fi
+  return 0
 }
 
 issue_latest_comment_matches_artifact() {

package/tools/bin/agent-project-reconcile-pr-session

@@ -151,6 +151,9 @@ if [[ -n "$hook_file" && -f "$hook_file" ]]; then
 fi
 
 provider_cooldown_script="${shared_tools_dir}/provider-cooldown-state.sh"
+github_core_rate_limit_script="${shared_tools_dir}/github-core-rate-limit-state.sh"
+github_write_outbox_script="${shared_tools_dir}/github-write-outbox.sh"
+automated_pr_approval_body="Automated final review passed. Safe low-risk scope, green checks, and host-side merge approved."
 
 schedule_provider_quota_cooldown() {
   local reason="${1:-provider-quota-limit}"
@@ -172,6 +175,26 @@ blocked_runtime_reason=""
 host_github_rate_limited="no"
 host_github_rate_limit_detail=""
 
+host_github_rate_limit_state_active() {
+  local state_out=""
+  local ready=""
+  local next_attempt_at=""
+
+  [[ -x "${github_core_rate_limit_script}" ]] || return 1
+  state_out="$("${github_core_rate_limit_script}" get 2>/dev/null || true)"
+  ready="$(awk -F= '/^READY=/{print $2; exit}' <<<"${state_out}")"
+  [[ "${ready}" == "no" ]] || return 1
+
+  next_attempt_at="$(awk -F= '/^NEXT_ATTEMPT_AT=/{print $2; exit}' <<<"${state_out}")"
+  host_github_rate_limited="yes"
+  if [[ -n "${next_attempt_at}" ]]; then
+    host_github_rate_limit_detail="GitHub core API rate limit cooldown is active and resets at ${next_attempt_at}."
+  else
+    host_github_rate_limit_detail="GitHub core API rate limit cooldown is active."
+  fi
+  return 0
+}
+
 owner="${repo_slug%%/*}"
 repo="${repo_slug#*/}"
 pr_view_json="$(flow_github_pr_view_json "$repo_slug" "$pr_number")"
@@ -365,9 +388,27 @@ post_pr_comment_if_present() {
   if pr_comment_already_posted; then
     return 0
   fi
-  if ! host_github_post_issue_comment "${pr_number}" "$(cat "$comment_file")"; then
-    return 1
+  if host_github_post_issue_comment "${pr_number}" "$(cat "$comment_file")"; then
+    return 0
+  fi
+  if [[ -x "${github_write_outbox_script}" ]]; then
+    if "${github_write_outbox_script}" enqueue-comment \
+      --repo-slug "${repo_slug}" \
+      --number "${pr_number}" \
+      --kind pr \
+      --body-file "${comment_file}" >/dev/null 2>&1; then
+      return 0
+    fi
   fi
+  return 1
+}
+
+enqueue_pr_approval_intent() {
+  [[ -x "${github_write_outbox_script}" ]] || return 1
+  "${github_write_outbox_script}" enqueue-approval \
+    --repo-slug "${repo_slug}" \
+    --number "${pr_number}" \
+    --body "${automated_pr_approval_body}" >/dev/null 2>&1
 }
 
 pr_comment_already_posted() {
@@ -390,6 +431,9 @@ record_host_github_rate_limit() {
   host_github_rate_limited="yes"
   host_github_rate_limit_detail="${output}"
   printf '%s\n' "${output}" >"${detail_file}"
+  if [[ -x "${github_core_rate_limit_script}" ]]; then
+    "${github_core_rate_limit_script}" schedule "github-api-rate-limit" >/dev/null 2>&1 || true
+  fi
 }
 
 host_github_post_issue_comment() {
@@ -397,9 +441,13 @@ host_github_post_issue_comment() {
   local body="${2:-}"
   local output=""
 
+  if host_github_rate_limit_state_active; then
+    return 1
+  fi
+
   flow_export_github_cli_auth_env "${repo_slug}"
   if output="$(
-    gh api "repos/${repo_slug}/issues/${issue_number}/comments" \
+    flow_github_api_repo "${repo_slug}" "issues/${issue_number}/comments" \
       --method POST \
       -f body="${body}" 2>&1
   )"; then
@@ -418,23 +466,25 @@ host_github_post_issue_comment() {
 host_github_submit_pr_approval() {
   local output=""
 
+  if host_github_rate_limit_state_active; then
+    enqueue_pr_approval_intent || true
+    return 1
+  fi
+
   flow_export_github_cli_auth_env "${repo_slug}"
   if output="$(
-    gh api "repos/${repo_slug}/pulls/${pr_number}/reviews" \
-      --method POST \
-      -f event=APPROVE \
-      -f body="Automated final review passed. Safe low-risk scope, green checks, and host-side merge approved." \
-      2>&1
+    flow_github_pr_review_approve "${repo_slug}" "${pr_number}" "${automated_pr_approval_body}" 2>&1
   )"; then
     return 0
   fi
 
-  if grep -q "Can not approve your own pull request" <<<"${output}"; then
+  if grep -q "Can not approve your own pull request" <<<"${output}" || grep -q "approve your own pull is not allowed" <<<"${output}"; then
     return 0
   fi
 
   if host_github_output_indicates_rate_limit "${output}"; then
     record_host_github_rate_limit "${output}"
+    enqueue_pr_approval_intent || true
     return 1
   fi
 
@@ -843,13 +893,21 @@ merge_state_prepared() {
 }
 
 current_github_login() {
+  if host_github_rate_limit_state_active; then
+    printf '\n'
+    return 0
+  fi
   flow_export_github_cli_auth_env "${repo_slug}"
-  gh api user --jq '.login // ""' 2>/dev/null || true
+  flow_github_current_login
 }
 
 pr_author_login() {
+  if host_github_rate_limit_state_active; then
+    printf '\n'
+    return 0
+  fi
   flow_export_github_cli_auth_env "${repo_slug}"
-  gh pr view "${pr_number}" -R "${repo_slug}" --json author --jq '.author.login // ""' 2>/dev/null || true
+  flow_github_pr_author_login "${repo_slug}" "${pr_number}"
 }
 
 pr_is_self_authored_for_current_actor() {
@@ -862,8 +920,12 @@ pr_is_self_authored_for_current_actor() {
 }
 
 pr_remote_head_oid() {
+  if host_github_rate_limit_state_active; then
+    printf '\n'
+    return 0
+  fi
   flow_export_github_cli_auth_env "${repo_slug}"
-  gh pr view "${pr_number}" -R "${repo_slug}" --json headRefOid --jq '.headRefOid // ""' 2>/dev/null || true
+  flow_github_pr_head_oid "${repo_slug}" "${pr_number}"
 }
 
 pr_remote_already_has_final_head() {
@@ -885,29 +947,25 @@ approve_and_merge() {
     fi
   fi
 
+  if host_github_rate_limit_state_active; then
+    return 2
+  fi
+
   flow_export_github_cli_auth_env "${repo_slug}"
-  if ! gh pr merge "${pr_number}" -R "${repo_slug}" --squash --delete-branch --admin >"${run_dir}/host-github-merge.out" 2>"${run_dir}/host-github-merge.err"; then
-    local merge_output=""
-    merge_output="$(cat "${run_dir}/host-github-merge.err" 2>/dev/null || true)"
-    if host_github_output_indicates_rate_limit "${merge_output}"; then
-      record_host_github_rate_limit "${merge_output}"
-      return 2
-    fi
-    if flow_github_pr_merge "$repo_slug" "$pr_number" "squash" "yes" 2>"${run_dir}/host-github-merge.err"; then
-      return 0
-    fi
-    merge_output="$(cat "${run_dir}/host-github-merge.err" 2>/dev/null || true)"
-    if host_github_output_indicates_rate_limit "${merge_output}"; then
-      record_host_github_rate_limit "${merge_output}"
-      return 2
-    fi
-    if [[ -n "${merge_output}" ]]; then
-      printf '%s\n' "${merge_output}" >&2
-    fi
-    return 1
+  if flow_github_pr_merge "$repo_slug" "$pr_number" "squash" "yes" >"${run_dir}/host-github-merge.out" 2>"${run_dir}/host-github-merge.err"; then
+    return 0
   fi
 
-  return 0
+  local merge_output=""
+  merge_output="$(cat "${run_dir}/host-github-merge.err" 2>/dev/null || true)"
+  if host_github_output_indicates_rate_limit "${merge_output}"; then
+    record_host_github_rate_limit "${merge_output}"
+    return 2
+  fi
+  if [[ -n "${merge_output}" ]]; then
+    printf '%s\n' "${merge_output}" >&2
+  fi
+  return 1
 }
 
 cleanup_pr_session() {

package/tools/bin/agent-project-retry-state

@@ -1,10 +1,14 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-shell-lib.sh"
+
 usage() {
   cat <<'EOF'
 Usage:
-  agent-project-retry-state --state-root <path> --kind issue|pr|provider --item-id <id> --action get|schedule|clear [--reason <text>] [--cooldowns <csv>]
+  agent-project-retry-state --state-root <path> --kind issue|pr|provider|github --item-id <id> --action get|schedule|clear [--reason <text>] [--cooldowns <csv>] [--next-at-epoch <unix-seconds>]
 
 Generic retry/cooldown state manager for project adapters.
 
@@ -12,6 +16,7 @@ Examples:
   agent-project-retry-state --state-root /tmp/state --kind issue --item-id 123 --action get
   agent-project-retry-state --state-root /tmp/state --kind pr --item-id 77 --action schedule --reason worker-exit-failed
   agent-project-retry-state --state-root /tmp/state --kind provider --item-id openclaw-stepfun-free --action schedule --reason provider-quota-limit
+  agent-project-retry-state --state-root /tmp/state --kind github --item-id core-api --action schedule --reason github-api-rate-limit --next-at-epoch 4102444800
 EOF
 }
 
@@ -21,6 +26,7 @@ item_id=""
 action=""
 reason=""
 cooldowns_csv="${AGENT_PROJECT_RETRY_COOLDOWNS:-300,900,1800,3600}"
+next_at_epoch_override=""
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -30,6 +36,7 @@ while [[ $# -gt 0 ]]; do
     --action) action="${2:-}"; shift 2 ;;
     --reason) reason="${2:-}"; shift 2 ;;
     --cooldowns) cooldowns_csv="${2:-}"; shift 2 ;;
+    --next-at-epoch) next_at_epoch_override="${2:-}"; shift 2 ;;
     --help|-h) usage; exit 0 ;;
     *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
   esac
@@ -41,8 +48,8 @@ if [[ -z "$state_root" || -z "$kind" || -z "$item_id" || -z "$action" ]]; then
 fi
 
 case "$kind" in
-  issue|pr|provider) ;;
-  *) echo "--kind must be issue, pr, or provider" >&2; exit 1 ;;
+  issue|pr|provider|github) ;;
+  *) echo "--kind must be issue, pr, provider, or github" >&2; exit 1 ;;
 esac
 
 case "$action" in
@@ -98,7 +105,7 @@ write_state() {
 
   new_updated_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
   if [[ "$new_next_epoch" != "0" ]]; then
-    new_next_at="$(date -u -r "$new_next_epoch" +"%Y-%m-%dT%H:%M:%SZ")"
+    new_next_at="$(flow_format_epoch_utc "$new_next_epoch")"
   fi
 
   cat >"$state_file" <<EOF
@@ -115,10 +122,14 @@ case "$action" in
     ;;
   schedule)
     attempts=$((attempts + 1))
-    cooldown_seconds="$(cooldown_seconds_for_attempt "$attempts")"
-    next_attempt_epoch=$((now_epoch + cooldown_seconds))
+    if [[ "${next_at_epoch_override}" =~ ^[0-9]+$ ]] && (( next_at_epoch_override > now_epoch )); then
+      next_attempt_epoch="${next_at_epoch_override}"
+    else
+      cooldown_seconds="$(cooldown_seconds_for_attempt "$attempts")"
+      next_attempt_epoch=$((now_epoch + cooldown_seconds))
+    fi
     write_state "$attempts" "$next_attempt_epoch" "$reason"
-    next_attempt_at="$(date -u -r "$next_attempt_epoch" +"%Y-%m-%dT%H:%M:%SZ")"
+    next_attempt_at="$(flow_format_epoch_utc "$next_attempt_epoch")"
     last_reason="$reason"
     updated_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
     ;;

package/tools/bin/agent-project-run-codex-resilient

@@ -136,6 +136,15 @@ config_yaml="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
 issue_session_prefix="$(flow_resolve_issue_session_prefix "${config_yaml}")"
 pr_session_prefix="$(flow_resolve_pr_session_prefix "${config_yaml}")"
 
+# Keep npm-backed verification steps isolated from any broken user-global cache state.
+npm_cache_dir="${NPM_CONFIG_CACHE:-${npm_config_cache:-}}"
+if [[ -z "${npm_cache_dir}" ]]; then
+  npm_cache_dir="${ACP_NPM_CACHE_DIR:-${F_LOSNING_NPM_CACHE_DIR:-${HOME}/.agent-runtime/npm-cache}}"
+fi
+export NPM_CONFIG_CACHE="${npm_cache_dir}"
+export npm_config_cache="${npm_cache_dir}"
+mkdir -p "${npm_cache_dir}" 2>/dev/null || true
+
 thread_id=""
 attempt=0
 resume_count=0
@@ -623,11 +632,10 @@ stream_codex_exec() {
   rm -f "$stream_fifo"
   rm -f "$progress_file"
 
-  if wait "$producer_pid"; then
-    last_exit_code="0"
-  else
-    last_exit_code="$?"
-  fi
+  set +e
+  wait "$producer_pid" 2>/dev/null
+  last_exit_code="$?"
+  set -e
 
   update_thread_id_from_output "$last_attempt_start_size"
 }

package/tools/bin/agent-project-sync-source-repo-main

@@ -0,0 +1,163 @@
+#!/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"
+
+CONFIG_YAML="${ACP_SOURCE_REPO_SYNC_CONFIG_YAML:-$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")}"
+REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+SOURCE_REPO_ROOT="$(flow_resolve_source_repo_root "${CONFIG_YAML}")"
+DEFAULT_BRANCH="$(flow_resolve_default_branch "${CONFIG_YAML}")"
+STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+SYNC_STATE_FILE="${STATE_ROOT}/source-repo-main-sync.env"
+FORGE_PROVIDER="$(flow_forge_provider)"
+REMOTE_OVERRIDE="${ACP_SOURCE_SYNC_REMOTE:-${F_LOSNING_SOURCE_SYNC_REMOTE:-}}"
+
+write_state() {
+  local status="${1:-}"
+  local remote_name="${2:-}"
+  local remote_sha="${3:-}"
+  local local_sha="${4:-}"
+  local detail="${5:-}"
+
+  mkdir -p "$(dirname "${SYNC_STATE_FILE}")"
+  {
+    printf 'STATUS=%s\n' "${status}"
+    printf 'UPDATED_AT=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+    printf 'SOURCE_REPO_ROOT=%s\n' "${SOURCE_REPO_ROOT}"
+    printf 'DEFAULT_BRANCH=%s\n' "${DEFAULT_BRANCH}"
+    printf 'REMOTE_NAME=%s\n' "${remote_name}"
+    printf 'REMOTE_SHA=%s\n' "${remote_sha}"
+    printf 'LOCAL_SHA=%s\n' "${local_sha}"
+    printf 'DETAIL=%s\n' "${detail}"
+  } >"${SYNC_STATE_FILE}"
+}
+
+git_ref_sha() {
+  local repo_root="${1:?repo root required}"
+  local ref_name="${2:?ref required}"
+  git -C "${repo_root}" rev-parse --verify --quiet "${ref_name}" 2>/dev/null || true
+}
+
+git_has_remote() {
+  local repo_root="${1:?repo root required}"
+  local remote_name="${2:?remote required}"
+  git -C "${repo_root}" remote get-url "${remote_name}" >/dev/null 2>&1
+}
+
+discover_remote_name() {
+  local remote_name=""
+
+  if [[ -n "${REMOTE_OVERRIDE}" ]] && git_has_remote "${SOURCE_REPO_ROOT}" "${REMOTE_OVERRIDE}"; then
+    printf '%s\n' "${REMOTE_OVERRIDE}"
+    return 0
+  fi
+
+  case "${FORGE_PROVIDER}" in
+    gitea)
+      if git_has_remote "${SOURCE_REPO_ROOT}" "gitea"; then
+        printf 'gitea\n'
+        return 0
+      fi
+      ;;
+    github)
+      if git_has_remote "${SOURCE_REPO_ROOT}" "origin"; then
+        printf 'origin\n'
+        return 0
+      fi
+      ;;
+  esac
+
+  while IFS= read -r remote_name; do
+    [[ -n "${remote_name}" ]] || continue
+    if [[ "$(flow_git_remote_repo_slug "${SOURCE_REPO_ROOT}" "${remote_name}" 2>/dev/null || true)" == "${REPO_SLUG}" ]]; then
+      printf '%s\n' "${remote_name}"
+      return 0
+    fi
+  done < <(git -C "${SOURCE_REPO_ROOT}" remote)
+
+  return 1
+}
+
+if [[ -z "${SOURCE_REPO_ROOT}" ]]; then
+  write_state "skipped" "" "" "" "source-repo-root-unset"
+  printf 'SOURCE_REPO_SYNC_STATUS=skipped\nSOURCE_REPO_SYNC_REASON=source-repo-root-unset\n'
+  exit 0
+fi
+
+if [[ ! -d "${SOURCE_REPO_ROOT}/.git" && ! -f "${SOURCE_REPO_ROOT}/.git" ]]; then
+  write_state "skipped" "" "" "" "source-repo-not-git"
+  printf 'SOURCE_REPO_SYNC_STATUS=skipped\nSOURCE_REPO_SYNC_REASON=source-repo-not-git\nSOURCE_REPO_ROOT=%s\n' "${SOURCE_REPO_ROOT}"
+  exit 0
+fi
+
+REMOTE_NAME="$(discover_remote_name || true)"
+if [[ -z "${REMOTE_NAME}" ]]; then
+  write_state "skipped" "" "" "" "remote-not-found"
+  printf 'SOURCE_REPO_SYNC_STATUS=skipped\nSOURCE_REPO_SYNC_REASON=remote-not-found\nSOURCE_REPO_ROOT=%s\n' "${SOURCE_REPO_ROOT}"
+  exit 0
+fi
+
+if ! git -C "${SOURCE_REPO_ROOT}" fetch "${REMOTE_NAME}" "+refs/heads/${DEFAULT_BRANCH}:refs/remotes/${REMOTE_NAME}/${DEFAULT_BRANCH}" --prune >/dev/null 2>&1; then
+  write_state "failed" "${REMOTE_NAME}" "" "" "fetch-failed"
+  printf 'SOURCE_REPO_SYNC_STATUS=failed\nSOURCE_REPO_SYNC_REASON=fetch-failed\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\n' "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}"
+  exit 1
+fi
+
+remote_sha="$(git_ref_sha "${SOURCE_REPO_ROOT}" "refs/remotes/${REMOTE_NAME}/${DEFAULT_BRANCH}")"
+local_branch_sha="$(git_ref_sha "${SOURCE_REPO_ROOT}" "refs/heads/${DEFAULT_BRANCH}")"
+current_branch="$(git -C "${SOURCE_REPO_ROOT}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)"
+
+if [[ -z "${remote_sha}" || -z "${local_branch_sha}" ]]; then
+  write_state "failed" "${REMOTE_NAME}" "${remote_sha}" "${local_branch_sha}" "missing-branch-ref"
+  printf 'SOURCE_REPO_SYNC_STATUS=failed\nSOURCE_REPO_SYNC_REASON=missing-branch-ref\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\n' "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}"
+  exit 1
+fi
+
+if [[ "${remote_sha}" == "${local_branch_sha}" ]]; then
+  write_state "unchanged" "${REMOTE_NAME}" "${remote_sha}" "${local_branch_sha}" "already-current"
+  printf 'SOURCE_REPO_SYNC_STATUS=unchanged\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\nSOURCE_REPO_SYNC_SHA=%s\n' "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}" "${remote_sha}"
+  exit 0
+fi
+
+if [[ "${current_branch}" == "${DEFAULT_BRANCH}" ]]; then
+  if [[ -n "$(git -C "${SOURCE_REPO_ROOT}" status --porcelain 2>/dev/null || true)" ]]; then
+    write_state "blocked" "${REMOTE_NAME}" "${remote_sha}" "${local_branch_sha}" "working-tree-dirty"
+    printf 'SOURCE_REPO_SYNC_STATUS=blocked\nSOURCE_REPO_SYNC_REASON=working-tree-dirty\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\nLOCAL_SHA=%s\nREMOTE_SHA=%s\n' \
+      "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}" "${local_branch_sha}" "${remote_sha}"
+    exit 0
+  fi
+
+  if git -C "${SOURCE_REPO_ROOT}" merge-base --is-ancestor "${local_branch_sha}" "${remote_sha}" >/dev/null 2>&1; then
+    git -C "${SOURCE_REPO_ROOT}" merge --ff-only "refs/remotes/${REMOTE_NAME}/${DEFAULT_BRANCH}" >/dev/null
+    updated_sha="$(git_ref_sha "${SOURCE_REPO_ROOT}" "refs/heads/${DEFAULT_BRANCH}")"
+    write_state "updated" "${REMOTE_NAME}" "${remote_sha}" "${updated_sha}" "fast-forward-checked-out-branch"
+    printf 'SOURCE_REPO_SYNC_STATUS=updated\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\nSOURCE_REPO_SYNC_SHA=%s\n' "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}" "${updated_sha}"
+    exit 0
+  fi
+
+  if git -C "${SOURCE_REPO_ROOT}" merge --no-edit "refs/remotes/${REMOTE_NAME}/${DEFAULT_BRANCH}" >/dev/null 2>&1; then
+    updated_sha="$(git_ref_sha "${SOURCE_REPO_ROOT}" "refs/heads/${DEFAULT_BRANCH}")"
+    write_state "updated" "${REMOTE_NAME}" "${remote_sha}" "${updated_sha}" "merge-checked-out-branch"
+    printf 'SOURCE_REPO_SYNC_STATUS=updated\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\nSOURCE_REPO_SYNC_SHA=%s\n' "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}" "${updated_sha}"
+    exit 0
+  fi
+
+  git -C "${SOURCE_REPO_ROOT}" merge --abort >/dev/null 2>&1 || true
+  write_state "blocked" "${REMOTE_NAME}" "${remote_sha}" "${local_branch_sha}" "merge-conflict"
+  printf 'SOURCE_REPO_SYNC_STATUS=blocked\nSOURCE_REPO_SYNC_REASON=merge-conflict\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\nLOCAL_SHA=%s\nREMOTE_SHA=%s\n' \
+    "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}" "${local_branch_sha}" "${remote_sha}"
+  exit 0
+fi
+
+if ! git -C "${SOURCE_REPO_ROOT}" merge-base --is-ancestor "${local_branch_sha}" "${remote_sha}" >/dev/null 2>&1; then
+  write_state "blocked" "${REMOTE_NAME}" "${remote_sha}" "${local_branch_sha}" "local-main-diverged"
+  printf 'SOURCE_REPO_SYNC_STATUS=blocked\nSOURCE_REPO_SYNC_REASON=local-main-diverged\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\nLOCAL_SHA=%s\nREMOTE_SHA=%s\n' \
+    "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}" "${local_branch_sha}" "${remote_sha}"
+  exit 0
+fi
+
+git -C "${SOURCE_REPO_ROOT}" update-ref "refs/heads/${DEFAULT_BRANCH}" "${remote_sha}" "${local_branch_sha}"
+write_state "updated" "${REMOTE_NAME}" "${remote_sha}" "${remote_sha}" "fast-forward-local-ref"
+printf 'SOURCE_REPO_SYNC_STATUS=updated\nSOURCE_REPO_ROOT=%s\nREMOTE_NAME=%s\nSOURCE_REPO_SYNC_SHA=%s\n' "${SOURCE_REPO_ROOT}" "${REMOTE_NAME}" "${remote_sha}"