agent-control-plane 0.1.0

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

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-catch-up-merged-prs --repo-slug <owner/repo> --state-root <path> --hook-file <path> [--limit <n>]
+
+Catch up merge-cleanup for managed PRs that were merged manually after their
+worker session had already been reconciled and cleaned up.
+EOF
+}
+
+repo_slug=""
+state_root=""
+hook_file=""
+limit="100"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-slug) repo_slug="${2:-}"; shift 2 ;;
+    --state-root) state_root="${2:-}"; shift 2 ;;
+    --hook-file) hook_file="${2:-}"; shift 2 ;;
+    --limit) limit="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$repo_slug" || -z "$state_root" || -z "$hook_file" ]]; then
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -f "$hook_file" ]]; then
+  echo "missing hook file: $hook_file" >&2
+  exit 1
+fi
+
+# shellcheck source=/dev/null
+source "$hook_file"
+
+optional_hooks=(
+  pr_clear_retry
+  pr_cleanup_linked_issue_session
+  pr_cleanup_merged_residue
+  pr_linked_issue_should_close
+  pr_after_merged
+)
+
+for hook_name in "${optional_hooks[@]}"; do
+  if ! declare -F "$hook_name" >/dev/null 2>&1; then
+    eval "${hook_name}() { :; }"
+  fi
+done
+
+ledger_dir="${state_root}/merged-pr-catchup"
+mkdir -p "$ledger_dir"
+
+get_pr_risk_json() {
+  local pr_number="${1:?pr number required}"
+  if declare -F heartbeat_pr_risk_json >/dev/null 2>&1; then
+    heartbeat_pr_risk_json "$pr_number"
+    return 0
+  fi
+  if [[ -n "${ADAPTER_BIN_DIR:-}" && -x "${ADAPTER_BIN_DIR}/pr-risk.sh" ]]; then
+    "${ADAPTER_BIN_DIR}/pr-risk.sh" "$pr_number"
+    return 0
+  fi
+  echo "missing PR risk provider for catch-up" >&2
+  return 1
+}
+
+close_issue_if_needed() {
+  local pr_number="${1:?pr number required}"
+  local issue_id="${2:-}"
+  [[ -n "$issue_id" ]] || return 0
+
+  local should_close="yes"
+  should_close="$(pr_linked_issue_should_close "$issue_id" || printf 'yes\n')"
+  if [[ "$should_close" != "yes" ]]; then
+    return 0
+  fi
+
+  pr_cleanup_linked_issue_session "$issue_id" || true
+
+  local issue_state=""
+  issue_state="$(flow_github_issue_view_json "$repo_slug" "$issue_id" 2>/dev/null | jq -r '.state // empty' || true)"
+  if [[ "$issue_state" == "OPEN" ]]; then
+    flow_github_issue_close "$repo_slug" "$issue_id" "Closed automatically after PR #${pr_number} merged." >/dev/null 2>&1 || true
+    printf 'CATCHUP_CLOSED_ISSUE=%s\n' "$issue_id"
+  fi
+}
+
+merged_prs_json="$(flow_github_pr_list_json "$repo_slug" merged "$limit")"
+
+while IFS= read -r pr_number; do
+  [[ -n "$pr_number" ]] || continue
+
+  ledger_file="${ledger_dir}/${pr_number}.env"
+  if [[ -f "$ledger_file" ]]; then
+    continue
+  fi
+
+  risk_json="$(get_pr_risk_json "$pr_number" 2>/dev/null || true)"
+  if [[ -z "$risk_json" ]]; then
+    continue
+  fi
+
+  is_managed="$(jq -r '.isManagedByAgent // .isAgentBranch // false' <<<"$risk_json" 2>/dev/null || printf 'false\n')"
+  if [[ "$is_managed" != "true" ]]; then
+    continue
+  fi
+
+  linked_issue_id="$(jq -r '.linkedIssueId // empty' <<<"$risk_json" 2>/dev/null || true)"
+  merged_at="$(jq -r --arg pr "$pr_number" 'map(select((.number | tostring) == $pr)) | .[0].mergedAt // ""' <<<"$merged_prs_json")"
+
+  PR_NUMBER="$pr_number" pr_clear_retry || true
+  close_issue_if_needed "$pr_number" "$linked_issue_id"
+  if ! PR_NUMBER="$pr_number" pr_after_merged "$pr_number"; then
+    printf 'CATCHUP_FAILED_PR=%s\n' "$pr_number" >&2
+    continue
+  fi
+  if ! PR_NUMBER="$pr_number" pr_cleanup_merged_residue "$pr_number"; then
+    printf 'CATCHUP_FAILED_RESIDUE=%s\n' "$pr_number" >&2
+    continue
+  fi
+
+  {
+    printf 'PR_NUMBER=%s\n' "$pr_number"
+    printf 'ISSUE_ID=%s\n' "$linked_issue_id"
+    printf 'MERGED_AT=%s\n' "$merged_at"
+    printf 'PROCESSED_AT=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  } >"$ledger_file"
+
+  printf 'CATCHUP_MERGED_PR=%s\n' "$pr_number"
+done < <(jq -r 'sort_by(.mergedAt) | reverse | .[].number' <<<"$merged_prs_json")

package/tools/bin/agent-project-cleanup-session

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-cleanup-session --repo-root <path> [--runs-root <path> --history-root <path> --session <id>] [--worktree <path>] [--mode generic|issue|pr] [--remote <name>] [--remove-file <path>] [--keep-remote] [--allow-unmerged] [--skip-worktree-cleanup]
+
+Cleanup a project-lane worktree/branch using shared agent helpers, then archive
+the session run directory when one is provided.
+EOF
+}
+
+shared_agent_home="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+repo_root="${AGENT_PROJECT_REPO_ROOT:-}"
+runs_root="${AGENT_PROJECT_RUNS_ROOT:-}"
+history_root="${AGENT_PROJECT_HISTORY_ROOT:-}"
+session=""
+worktree_path=""
+mode="generic"
+remote_name="origin"
+remove_file=""
+keep_remote="auto"
+allow_unmerged="auto"
+merged_base=""
+skip_worktree_cleanup="false"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root) repo_root="${2:-}"; shift 2 ;;
+    --runs-root) runs_root="${2:-}"; shift 2 ;;
+    --history-root) history_root="${2:-}"; shift 2 ;;
+    --session) session="${2:-}"; shift 2 ;;
+    --worktree) worktree_path="${2:-}"; shift 2 ;;
+    --mode) mode="${2:-}"; shift 2 ;;
+    --remote) remote_name="${2:-}"; shift 2 ;;
+    --remove-file) remove_file="${2:-}"; shift 2 ;;
+    --merged-base) merged_base="${2:-}"; shift 2 ;;
+    --keep-remote) keep_remote="true"; shift ;;
+    --allow-unmerged) allow_unmerged="true"; shift ;;
+    --skip-worktree-cleanup) skip_worktree_cleanup="true"; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$repo_root" ]]; then
+  echo "--repo-root is required" >&2
+  usage >&2
+  exit 1
+fi
+
+case "$mode" in
+  generic|issue|pr) ;;
+  *)
+    echo "--mode must be generic, issue, or pr" >&2
+    exit 1
+    ;;
+esac
+
+if [[ -z "$worktree_path" && -z "$session" ]]; then
+  echo "Provide at least one of --worktree or --session" >&2
+  usage >&2
+  exit 1
+fi
+
+if [[ -n "$session" && ( -z "$runs_root" || -z "$history_root" ) ]]; then
+  echo "--runs-root and --history-root are required when --session is set" >&2
+  usage >&2
+  exit 1
+fi
+
+if [[ "$keep_remote" == "auto" ]]; then
+  case "$mode" in
+    issue) keep_remote="true" ;;
+    *) keep_remote="false" ;;
+  esac
+fi
+
+if [[ "$allow_unmerged" == "auto" ]]; then
+  case "$mode" in
+    issue|pr) allow_unmerged="true" ;;
+    *) allow_unmerged="false" ;;
+  esac
+fi
+
+meta_file=""
+branch_name=""
+result_file=""
+cleanup_warning=""
+cleanup_status="0"
+cleanup_error=""
+cleanup_mode="noop"
+orphan_fallback_used="false"
+
+if [[ -n "$session" ]]; then
+  meta_file="${runs_root}/${session}/run.env"
+  if [[ -f "$meta_file" ]]; then
+    set -a
+    # shellcheck source=/dev/null
+    source "$meta_file"
+    set +a
+    branch_name="${BRANCH:-}"
+    result_file="${RESULT_FILE:-}"
+    if [[ -z "$worktree_path" ]]; then
+      worktree_path="${WORKTREE:-}"
+    fi
+  fi
+fi
+
+if [[ -z "$remove_file" ]]; then
+  remove_file="$result_file"
+fi
+
+cleanup_tool="${shared_agent_home}/tools/bin/agent-cleanup-worktree"
+archive_tool="${shared_agent_home}/tools/bin/agent-project-archive-run"
+
+canonicalize_existing_dir() {
+  local target="${1:-}"
+  [[ -n "$target" && -d "$target" ]] || return 1
+  (
+    cd "$target"
+    pwd -P
+  )
+}
+
+path_is_within_root() {
+  local target="${1:-}"
+  local root="${2:-}"
+  local target_canonical=""
+  local root_canonical=""
+
+  target_canonical="$(canonicalize_existing_dir "$target" || true)"
+  root_canonical="$(canonicalize_existing_dir "$root" || true)"
+  [[ -n "$target_canonical" && -n "$root_canonical" ]] || return 1
+  [[ "$target_canonical" == "$root_canonical" || "$target_canonical" == "$root_canonical"/* ]]
+}
+
+cleanup_with_branch_tool() {
+  local include_path="${1:-yes}"
+  local -a cleanup_args
+
+  cleanup_args=(--branch "$branch_name")
+  if [[ -n "$remote_name" ]]; then
+    cleanup_args+=(--remote "$remote_name")
+  fi
+  if [[ -n "$merged_base" ]]; then
+    cleanup_args+=(--merged-base "$merged_base")
+  fi
+  if [[ "$include_path" == "yes" && -n "$worktree_path" && -d "$worktree_path" ]]; then
+    cleanup_args+=(--path "$worktree_path")
+  fi
+  if [[ "$keep_remote" == "true" ]]; then
+    cleanup_args+=(--keep-remote)
+  fi
+  if [[ "$allow_unmerged" == "true" ]]; then
+    cleanup_args+=(--allow-unmerged)
+  fi
+
+  (
+    cd "$repo_root"
+    "$cleanup_tool" "${cleanup_args[@]}"
+  )
+}
+
+cleanup_orphan_worktree_dir() {
+  local worktree_root="${AGENT_PROJECT_WORKTREE_ROOT:-${F_LOSNING_WORKTREE_ROOT:-}}"
+  local worktree_canonical=""
+
+  [[ -n "$worktree_path" && -d "$worktree_path" ]] || return 1
+  [[ ! -e "$worktree_path/.git" ]] || return 1
+  [[ -n "$worktree_root" ]] || return 1
+  path_is_within_root "$worktree_path" "$worktree_root" || return 1
+
+  worktree_canonical="$(canonicalize_existing_dir "$worktree_path" || true)"
+  [[ -n "$worktree_canonical" ]] || return 1
+  rm -rf "$worktree_canonical"
+  git -C "$repo_root" worktree prune >/dev/null 2>&1 || true
+}
+
+if [[ "$skip_worktree_cleanup" != "true" && -n "$branch_name" ]]; then
+  if cleanup_output="$(cleanup_with_branch_tool yes 2>&1)"; then
+    cleanup_mode="branch"
+  else
+    cleanup_status="$?"
+    cleanup_error="${cleanup_output}"
+    if cleanup_orphan_worktree_dir; then
+      orphan_fallback_used="true"
+      if cleanup_retry_output="$(cleanup_with_branch_tool no 2>&1)"; then
+        cleanup_mode="orphan-worktree"
+        cleanup_status="0"
+        cleanup_warning="${cleanup_error}"
+      else
+        cleanup_status="$?"
+        cleanup_error="${cleanup_error}"$'\n'"${cleanup_retry_output}"
+      fi
+    fi
+  fi
+elif [[ "$skip_worktree_cleanup" != "true" && -n "$worktree_path" ]] && git -C "$repo_root" worktree list --porcelain | rg -F -q "worktree $worktree_path"; then
+  git -C "$repo_root" worktree remove "$worktree_path" --force || true
+  git -C "$repo_root" worktree prune
+  cleanup_mode="worktree"
+elif [[ "$skip_worktree_cleanup" == "true" ]]; then
+  cleanup_mode="archived-only"
+fi
+
+archive_output=""
+if [[ -n "$session" ]]; then
+  archive_output="$(
+    "$archive_tool" \
+      --runs-root "$runs_root" \
+      --history-root "$history_root" \
+      --session "$session" \
+      --remove-file "${remove_file:-}"
+  )"
+fi
+
+if [[ "$cleanup_status" != "0" && -z "$session" ]]; then
+  [[ -n "$cleanup_error" ]] && printf '%s\n' "$cleanup_error" >&2
+  exit "$cleanup_status"
+fi
+
+printf 'SESSION=%s\n' "$session"
+printf 'MODE=%s\n' "$mode"
+printf 'WORKTREE=%s\n' "$worktree_path"
+printf 'BRANCH=%s\n' "$branch_name"
+printf 'KEEP_REMOTE=%s\n' "$keep_remote"
+printf 'ALLOW_UNMERGED=%s\n' "$allow_unmerged"
+printf 'SKIP_WORKTREE_CLEANUP=%s\n' "$skip_worktree_cleanup"
+printf 'CLEANUP_MODE=%s\n' "$cleanup_mode"
+printf 'ORPHAN_FALLBACK_USED=%s\n' "$orphan_fallback_used"
+printf 'CLEANUP_STATUS=%s\n' "$cleanup_status"
+if [[ -n "$meta_file" ]]; then
+  printf 'META_FILE=%s\n' "$meta_file"
+fi
+if [[ -n "$archive_output" ]]; then
+  printf '%s\n' "$archive_output"
+fi
+if [[ -n "$cleanup_warning" ]]; then
+  printf 'CLEANUP_WARNING=%s\n' "$(printf '%s' "$cleanup_warning" | tr '\n' ' ' | sed 's/  */ /g')"
+fi
+if [[ "$cleanup_status" != "0" && -n "$cleanup_error" ]]; then
+  printf 'CLEANUP_ERROR=%s\n' "$(printf '%s' "$cleanup_error" | tr '\n' ' ' | sed 's/  */ /g')"
+fi

package/tools/bin/agent-project-detached-launch

@@ -0,0 +1,107 @@
+#!/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="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-detached-launch [--pending-key <kind-id>] <name> <command> [args...]
+
+Detach a worker bootstrap command from the current heartbeat process so the
+heartbeat can keep launching additional workers without waiting for expensive
+worktree/bootstrap/setup steps to finish.
+EOF
+}
+
+pending_key=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --pending-key)
+      pending_key="${2:-}"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+if [[ $# -lt 2 ]]; then
+  usage >&2
+  exit 1
+fi
+
+launch_name="${1:-}"
+shift
+
+if [[ -z "${launch_name}" ]]; then
+  usage >&2
+  exit 1
+fi
+
+log_root="${ACP_LAUNCHER_LOG_ROOT:-${F_LOSNING_LAUNCHER_LOG_ROOT:-${STATE_ROOT}/launcher-logs}}"
+mkdir -p "${log_root}"
+
+safe_name="$(printf '%s' "${launch_name}" | tr '/[:space:]' '__' | tr -cd '[:alnum:]_.-')"
+if [[ -z "${safe_name}" ]]; then
+  safe_name="launch"
+fi
+
+timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
+log_file="${log_root}/${timestamp}-${safe_name}.log"
+pending_file=""
+pending_dir="${ACP_PENDING_LAUNCH_DIR:-${F_LOSNING_PENDING_LAUNCH_DIR:-${STATE_ROOT}/pending-launches}}"
+if [[ -n "${pending_key}" ]]; then
+  mkdir -p "${pending_dir}"
+  pending_file="${pending_dir}/${pending_key}.pid"
+fi
+
+python_bin="${PYTHON_BIN:-$(command -v python3 || true)}"
+if [[ -z "${python_bin}" ]]; then
+  echo "python3 is required for detached launch" >&2
+  exit 1
+fi
+
+launch_pid="$(
+  "${python_bin}" - "${log_file}" "${pending_file}" "$@" <<'PY'
+import subprocess
+import sys
+from pathlib import Path
+
+log_file = Path(sys.argv[1])
+pending_file = sys.argv[2]
+argv = sys.argv[3:]
+
+with log_file.open("ab", buffering=0) as log_handle:
+    proc = subprocess.Popen(
+        argv,
+        stdin=subprocess.DEVNULL,
+        stdout=log_handle,
+        stderr=subprocess.STDOUT,
+        start_new_session=True,
+    )
+
+if pending_file:
+    Path(pending_file).write_text(f"{proc.pid}\n", encoding="utf-8")
+
+print(proc.pid)
+PY
+)"
+
+printf 'LAUNCH_MODE=detached\n'
+printf 'LAUNCH_NAME=%s\n' "${launch_name}"
+printf 'LAUNCH_PID=%s\n' "${launch_pid}"
+printf 'LAUNCH_LOG=%s\n' "${log_file}"
+if [[ -n "${pending_file}" ]]; then
+  printf 'LAUNCH_PENDING_FILE=%s\n' "${pending_file}"
+fi