agent-control-plane 0.1.16 → 0.3.0

package/tools/bin/agent-project-catch-up-issue-pr-links

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-catch-up-issue-pr-links --repo-slug <owner/repo> --state-root <path> --hook-file <path> [--limit <n>]
+
+Clear stale issue retry state when an issue already has a linked PR comment and
+that PR still exists (open, closed, or merged).
+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"
+
+if ! declare -F issue_clear_retry >/dev/null 2>&1; then
+  issue_clear_retry() { :; }
+fi
+
+ledger_dir="${state_root}/linked-pr-issue-catchup"
+retry_dir="${state_root}/retries/issues"
+mkdir -p "$ledger_dir" "$retry_dir"
+
+extract_latest_linked_pr() {
+  local issue_json="${1:-}"
+  ISSUE_JSON="$issue_json" python3 - <<'PY'
+import json
+import os
+import re
+
+issue = json.loads(os.environ.get("ISSUE_JSON", "{}") or "{}")
+latest = ""
+latest_at = ""
+for comment in issue.get("comments", []) or []:
+    body = comment.get("body") or ""
+    match = None
+    for candidate in re.finditer(r"Opened PR #(\d+)", body):
+        match = candidate
+    if not match:
+        continue
+    created = comment.get("createdAt") or ""
+    pr_number = match.group(1)
+    if created >= latest_at:
+        latest_at = created
+        latest = pr_number
+
+print(latest)
+PY
+}
+
+pr_exists() {
+  local pr_number="${1:?pr number required}"
+  local pr_json=""
+  pr_json="$(flow_github_pr_view_json "$repo_slug" "$pr_number" 2>/dev/null || true)"
+  [[ -n "$pr_json" && "$pr_json" != "{}" ]]
+}
+
+for retry_file in "$retry_dir"/*.env; do
+  [[ -f "$retry_file" ]] || continue
+  issue_id="$(basename "${retry_file%.env}")"
+  [[ -n "$issue_id" ]] || continue
+
+  retry_reason="$(awk -F= '/^LAST_REASON=/{print $2; exit}' "$retry_file" 2>/dev/null | tr -d '\r' || true)"
+  if [[ "$retry_reason" != "host-publish-failed" ]]; then
+    continue
+  fi
+
+  ledger_file="${ledger_dir}/${issue_id}.env"
+  if [[ -f "$ledger_file" ]]; then
+    continue
+  fi
+
+  issue_json="$(flow_github_issue_view_json "$repo_slug" "$issue_id" 2>/dev/null || true)"
+  [[ -n "$issue_json" && "$issue_json" != "{}" ]] || continue
+
+  linked_pr="$(extract_latest_linked_pr "$issue_json")"
+  [[ -n "$linked_pr" ]] || continue
+  if ! pr_exists "$linked_pr"; then
+    continue
+  fi
+
+  ISSUE_ID="$issue_id" issue_clear_retry || true
+
+  {
+    printf 'ISSUE_ID=%s\n' "$issue_id"
+    printf 'LINKED_PR=%s\n' "$linked_pr"
+    printf 'PROCESSED_AT=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  } >"$ledger_file"
+
+  printf 'CATCHUP_LINKED_PR_ISSUE=%s\n' "$issue_id"
+done

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

@@ -46,6 +46,7 @@ optional_hooks=(
   pr_cleanup_merged_residue
   pr_linked_issue_should_close
   pr_after_merged
+  pr_after_closed
 )
 
 for hook_name in "${optional_hooks[@]}"; do
@@ -54,8 +55,9 @@ for hook_name in "${optional_hooks[@]}"; do
   fi
 done
 
-ledger_dir="${state_root}/merged-pr-catchup"
-mkdir -p "$ledger_dir"
+merged_ledger_dir="${state_root}/merged-pr-catchup"
+closed_ledger_dir="${state_root}/closed-pr-catchup"
+mkdir -p "$merged_ledger_dir" "$closed_ledger_dir"
 
 get_pr_risk_json() {
   local pr_number="${1:?pr number required}"
@@ -92,16 +94,68 @@ close_issue_if_needed() {
   fi
 }
 
-merged_prs_json="$(flow_github_pr_list_json "$repo_slug" merged "$limit")"
-
-while IFS= read -r pr_number; do
-  [[ -n "$pr_number" ]] || continue
+process_terminal_pr() {
+  local pr_number="${1:?pr number required}"
+  local linked_issue_id="${2:-}"
+  local merged_at="${3:-}"
+  local processed_state="${4:?processed state required}"
+  local ledger_dir=""
+  local ledger_file=""
+
+  case "$processed_state" in
+    merged) ledger_dir="$merged_ledger_dir" ;;
+    closed) ledger_dir="$closed_ledger_dir" ;;
+    *)
+      echo "unsupported terminal PR state: ${processed_state}" >&2
+      return 1
+      ;;
+  esac
 
   ledger_file="${ledger_dir}/${pr_number}.env"
   if [[ -f "$ledger_file" ]]; then
-    continue
+    return 0
+  fi
+
+  PR_NUMBER="$pr_number" pr_clear_retry || true
+  if [[ "$processed_state" == "merged" ]]; then
+    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
+      return 1
+    fi
+  else
+    if ! PR_NUMBER="$pr_number" pr_after_closed "$pr_number"; then
+      printf 'CATCHUP_FAILED_CLOSED_PR=%s\n' "$pr_number" >&2
+      return 1
+    fi
+  fi
+
+  if ! PR_NUMBER="$pr_number" pr_cleanup_merged_residue "$pr_number"; then
+    printf 'CATCHUP_FAILED_RESIDUE=%s\n' "$pr_number" >&2
+    return 1
   fi
 
+  {
+    printf 'PR_NUMBER=%s\n' "$pr_number"
+    printf 'ISSUE_ID=%s\n' "$linked_issue_id"
+    printf 'PR_STATE=%s\n' "$processed_state"
+    printf 'MERGED_AT=%s\n' "$merged_at"
+    printf 'PROCESSED_AT=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  } >"$ledger_file"
+
+  if [[ "$processed_state" == "merged" ]]; then
+    printf 'CATCHUP_MERGED_PR=%s\n' "$pr_number"
+  else
+    printf 'CATCHUP_CLOSED_PR=%s\n' "$pr_number"
+  fi
+}
+
+merged_prs_json="$(flow_github_pr_list_json "$repo_slug" merged "$limit")"
+closed_prs_json="$(flow_github_pr_list_json "$repo_slug" closed "$limit")"
+
+while IFS= read -r pr_number; do
+  [[ -n "$pr_number" ]] || continue
+
   risk_json="$(get_pr_risk_json "$pr_number" 2>/dev/null || true)"
   if [[ -z "$risk_json" ]]; then
     continue
@@ -114,24 +168,27 @@ while IFS= read -r pr_number; do
 
   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")"
+  process_terminal_pr "$pr_number" "$linked_issue_id" "$merged_at" merged || true
+done < <(jq -r 'sort_by(.mergedAt) | reverse | .[].number' <<<"$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
+while IFS= read -r pr_number; do
+  [[ -n "$pr_number" ]] || continue
+
+  merged_at="$(jq -r --arg pr "$pr_number" 'map(select((.number | tostring) == $pr)) | .[0].mergedAt // ""' <<<"$closed_prs_json")"
+  if [[ -n "$merged_at" ]]; then
     continue
   fi
-  if ! PR_NUMBER="$pr_number" pr_cleanup_merged_residue "$pr_number"; then
-    printf 'CATCHUP_FAILED_RESIDUE=%s\n' "$pr_number" >&2
+
+  risk_json="$(get_pr_risk_json "$pr_number" 2>/dev/null || true)"
+  if [[ -z "$risk_json" ]]; then
     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"
+  is_managed="$(jq -r '.isManagedByAgent // .isAgentBranch // false' <<<"$risk_json" 2>/dev/null || printf 'false\n')"
+  if [[ "$is_managed" != "true" ]]; then
+    continue
+  fi
 
-  printf 'CATCHUP_MERGED_PR=%s\n' "$pr_number"
-done < <(jq -r 'sort_by(.mergedAt) | reverse | .[].number' <<<"$merged_prs_json")
+  linked_issue_id="$(jq -r '.linkedIssueId // empty' <<<"$risk_json" 2>/dev/null || true)"
+  process_terminal_pr "$pr_number" "$linked_issue_id" "" closed || true
+done < <(jq -r 'sort_by(.createdAt) | reverse | .[].number' <<<"$closed_prs_json")

package/tools/bin/agent-project-catch-up-scheduled-issue-retries

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-catch-up-scheduled-issue-retries --repo-slug <owner/repo> --state-root <path> --hook-file <path> [--limit <n>]
+
+Clear stale retry state for recurring scheduled reporting issues once GitHub
+already reflects the latest terminal status via labels and the issue is not
+currently running.
+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"
+
+if ! declare -F issue_clear_retry >/dev/null 2>&1; then
+  issue_clear_retry() { :; }
+fi
+
+ledger_dir="${state_root}/scheduled-issue-retry-catchup"
+retry_dir="${state_root}/retries/issues"
+mkdir -p "$ledger_dir" "$retry_dir"
+
+issue_has_terminal_scheduled_status() {
+  local issue_json="${1:-}"
+  ISSUE_JSON="$issue_json" python3 - <<'PY'
+import json
+import os
+import re
+import sys
+
+issue = json.loads(os.environ.get("ISSUE_JSON", "{}") or "{}")
+state = (issue.get("state") or "").upper()
+labels = {str(item.get("name") or "") for item in (issue.get("labels") or [])}
+body = issue.get("body") or ""
+
+has_schedule = bool(re.search(r'^\s*(?:Agent schedule|Schedule|Cadence)\s*:\s*(?:every\s+)?\d+\s*[mhd]\s*$', body, re.I | re.M))
+if not has_schedule and "agent-scheduled" not in labels:
+    sys.exit(1)
+
+if state != "OPEN":
+    sys.exit(1)
+
+if "agent-running" in labels:
+    sys.exit(1)
+
+terminal_status_labels = {
+    "health-ok",
+    "health-not-ok",
+    "checks-ok",
+    "checks-not-ok",
+    "smoke-ok",
+    "smoke-not-ok",
+}
+if not (labels & terminal_status_labels):
+    sys.exit(1)
+
+sys.exit(0)
+PY
+}
+
+processed=0
+for retry_file in "$retry_dir"/*.env; do
+  [[ -f "$retry_file" ]] || continue
+  if [[ "$processed" -ge "$limit" ]]; then
+    break
+  fi
+
+  issue_id="$(basename "${retry_file%.env}")"
+  [[ -n "$issue_id" ]] || continue
+
+  ledger_file="${ledger_dir}/${issue_id}.env"
+  if [[ -f "$ledger_file" ]]; then
+    continue
+  fi
+
+  issue_json="$(flow_github_issue_view_json "$repo_slug" "$issue_id" 2>/dev/null || true)"
+  [[ -n "$issue_json" && "$issue_json" != "{}" ]] || continue
+
+  if ! issue_has_terminal_scheduled_status "$issue_json"; then
+    continue
+  fi
+
+  retry_reason="$(awk -F= '/^LAST_REASON=/{print $2; exit}' "$retry_file" 2>/dev/null | tr -d '\r' || true)"
+  ISSUE_ID="$issue_id" issue_clear_retry || true
+
+  {
+    printf 'ISSUE_ID=%s\n' "$issue_id"
+    printf 'LAST_REASON=%s\n' "$retry_reason"
+    printf 'PROCESSED_AT=%s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  } >"$ledger_file"
+
+  printf 'CATCHUP_SCHEDULED_ISSUE=%s\n' "$issue_id"
+  processed=$((processed + 1))
+done

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

@@ -95,6 +95,7 @@ cleanup_error=""
 cleanup_mode="noop"
 orphan_fallback_used="false"
 active_tmux_session="false"
+archived_dir=""
 
 if [[ -n "$session" ]]; then
   meta_file="${runs_root}/${session}/run.env"
@@ -131,6 +132,24 @@ canonicalize_existing_dir() {
   )
 }
 
+canonicalize_dir_or_parent_join() {
+  local target="${1:-}"
+  local resolved=""
+
+  [[ -n "${target}" ]] || return 1
+
+  resolved="$(canonicalize_existing_dir "${target}" || true)"
+  if [[ -n "${resolved}" ]]; then
+    printf '%s\n' "${resolved}"
+    return 0
+  fi
+
+  (
+    cd "$(dirname "${target}")" 2>/dev/null
+    printf '%s/%s\n' "$(pwd -P)" "$(basename "${target}")"
+  ) || return 1
+}
+
 path_is_within_root() {
   local target="${1:-}"
   local root="${2:-}"
@@ -169,6 +188,8 @@ resident_worktree_protected() {
   local resident_worktree=""
   local resident_realpath=""
   local resolved_resident=""
+  local resident_lane_kind=""
+  local resident_last_status=""
 
   [[ -n "${candidate_path}" && -d "${candidate_path}" ]] || return 1
   resolved_candidate="$(canonicalize_existing_dir "${candidate_path}" || true)"
@@ -181,12 +202,19 @@ resident_worktree_protected() {
     [[ -f "${metadata_file}" ]] || continue
     resident_worktree=""
     resident_realpath=""
+    resident_lane_kind=""
+    resident_last_status=""
     set +u
     set -a
     # shellcheck source=/dev/null
     source "${metadata_file}"
     set +a
     set -u
+    resident_lane_kind="${RESIDENT_LANE_KIND:-}"
+    resident_last_status="${LAST_STATUS:-}"
+    if [[ "${resident_lane_kind}" != "recurring" && "${resident_last_status}" != "running" ]]; then
+      continue
+    fi
     resident_worktree="${WORKTREE_REALPATH:-${WORKTREE:-}}"
     [[ -n "${resident_worktree}" && -d "${resident_worktree}" ]] || continue
     resolved_resident="$(canonicalize_existing_dir "${resident_worktree}" || true)"
@@ -268,6 +296,59 @@ active_resident_run_worktree_protected() {
   return 1
 }
 
+clear_resident_worktree_realpath_references() {
+  local removed_path="${1:-}"
+  local resolved_removed=""
+  local resolved_state_root=""
+  local metadata_file=""
+  local resident_realpath=""
+  local tmp_file=""
+  local metadata_worktree_realpath=""
+
+  [[ -n "${removed_path}" ]] || return 0
+
+  resolved_removed="$(canonicalize_dir_or_parent_join "${removed_path}" || true)"
+  [[ -n "${resolved_removed}" ]] || return 0
+
+  resolved_state_root="$(derive_state_root || true)"
+  [[ -n "${resolved_state_root}" && -d "${resolved_state_root}/resident-workers/issues" ]] || return 0
+
+  for metadata_file in "${resolved_state_root}"/resident-workers/issues/*/metadata.env; do
+    [[ -f "${metadata_file}" ]] || continue
+    metadata_worktree_realpath=""
+    set +u
+    set -a
+    # shellcheck source=/dev/null
+    source "${metadata_file}"
+    set +a
+    set -u
+    resident_realpath="${WORKTREE_REALPATH:-${metadata_worktree_realpath:-}}"
+    [[ -n "${resident_realpath}" ]] || continue
+    resident_realpath="$(canonicalize_dir_or_parent_join "${resident_realpath}" || true)"
+    [[ -n "${resident_realpath}" ]] || continue
+    if [[ "${resident_realpath}" != "${resolved_removed}" ]]; then
+      continue
+    fi
+
+    tmp_file="${metadata_file}.tmp.$$"
+    awk '
+      BEGIN { replaced = 0 }
+      /^WORKTREE_REALPATH=/ {
+        print "WORKTREE_REALPATH='\'''\''"
+        replaced = 1
+        next
+      }
+      { print }
+      END {
+        if (replaced == 0) {
+          print "WORKTREE_REALPATH='\'''\''"
+        }
+      }
+    ' "${metadata_file}" >"${tmp_file}"
+    mv "${tmp_file}" "${metadata_file}"
+  done
+}
+
 cleanup_with_branch_tool() {
   local include_path="${1:-yes}"
   local -a cleanup_args
@@ -310,6 +391,47 @@ cleanup_orphan_worktree_dir() {
   git -C "$repo_root" worktree prune >/dev/null 2>&1 || true
 }
 
+worktree_path_is_registered() {
+  local candidate_path="${1:-}"
+  [[ -n "${candidate_path}" ]] || return 1
+
+  git -C "$repo_root" worktree list --porcelain 2>/dev/null \
+    | grep -F -x -q -- "worktree ${candidate_path}"
+}
+
+write_cleanup_warning_artifact() {
+  local target_dir=""
+  local notice_file=""
+  local cleanup_error_line=""
+  local recorded_at=""
+
+  [[ "${cleanup_status}" != "0" ]] || return 0
+
+  if [[ -n "${archived_dir}" && -d "${archived_dir}" ]]; then
+    target_dir="${archived_dir}"
+  elif [[ -n "${session}" && -n "${runs_root}" && -d "${runs_root}/${session}" ]]; then
+    target_dir="${runs_root}/${session}"
+  fi
+
+  [[ -n "${target_dir}" && -d "${target_dir}" ]] || return 0
+
+  cleanup_error_line="$(printf '%s' "${cleanup_error}" | tr '\n' ' ' | sed 's/  */ /g')"
+  recorded_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  notice_file="${target_dir}/cleanup-warning.txt"
+  {
+    printf 'recorded_at=%s\n' "${recorded_at}"
+    printf 'session=%s\n' "${session}"
+    printf 'mode=%s\n' "${mode}"
+    printf 'worktree=%s\n' "${worktree_path}"
+    printf 'branch=%s\n' "${branch_name}"
+    printf 'cleanup_mode=%s\n' "${cleanup_mode}"
+    printf 'cleanup_status=%s\n' "${cleanup_status}"
+    if [[ -n "${cleanup_error_line}" ]]; then
+      printf 'cleanup_error=%s\n' "${cleanup_error_line}"
+    fi
+  } >"${notice_file}"
+}
+
 if [[ "$active_tmux_session" == "true" ]]; then
   cleanup_mode="deferred-active-session"
 elif [[ "$skip_worktree_cleanup" != "true" && -n "${worktree_path}" ]] \
@@ -333,7 +455,7 @@ elif [[ "$skip_worktree_cleanup" != "true" && -n "$branch_name" ]]; then
       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
+elif [[ "$skip_worktree_cleanup" != "true" && -n "$worktree_path" ]] && worktree_path_is_registered "$worktree_path"; then
   git -C "$repo_root" worktree remove "$worktree_path" --force || true
   git -C "$repo_root" worktree prune
   cleanup_mode="worktree"
@@ -353,13 +475,15 @@ if [[ -n "$session" && "$active_tmux_session" != "true" ]]; then
       --session "$session" \
       --remove-file "${remove_file:-}"
   )"
+  archived_dir="$(awk -F= '/^ARCHIVED_DIR=/{print substr($0, index($0, "=") + 1); exit}' <<<"${archive_output}")"
 fi
 
-if [[ "$cleanup_status" != "0" && -z "$session" ]]; then
-  [[ -n "$cleanup_error" ]] && printf '%s\n' "$cleanup_error" >&2
-  exit "$cleanup_status"
+if [[ "$skip_worktree_cleanup" != "true" && -n "$worktree_path" && ! -d "$worktree_path" ]]; then
+  clear_resident_worktree_realpath_references "$worktree_path"
 fi
 
+write_cleanup_warning_artifact
+
 printf 'SESSION=%s\n' "$session"
 printf 'MODE=%s\n' "$mode"
 printf 'WORKTREE=%s\n' "$worktree_path"
@@ -383,3 +507,7 @@ fi
 if [[ "$cleanup_status" != "0" && -n "$cleanup_error" ]]; then
   printf 'CLEANUP_ERROR=%s\n' "$(printf '%s' "$cleanup_error" | tr '\n' ' ' | sed 's/  */ /g')"
 fi
+
+if [[ "$cleanup_status" != "0" ]]; then
+  exit "$cleanup_status"
+fi