agent-control-plane 0.1.0

package/tools/bin/agent-project-run-opencode-session

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-run-opencode-session [shared session-wrapper options]
+
+Placeholder adapter for the roadmap. The public package ships this command so
+ACP can expose and test worker routing for `opencode`, but live session
+execution is not implemented yet.
+
+Use `codex`, `claude`, or `openclaw` for real runs today. See ROADMAP.md for
+current backend maturity.
+EOF
+}
+
+case "${1:-}" in
+  --help|-h)
+    usage
+    exit 0
+    ;;
+esac
+
+echo "agent-project-run-opencode-session: opencode support is scaffolded, but execution is not implemented yet" >&2
+echo "Choose codex, claude, or openclaw for live runs today." >&2
+exit 1

package/tools/bin/agent-project-sync-anchor-repo

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-sync-anchor-repo --canonical-root <path> --anchor-root <path> [--remote <name>] [--default-branch <name>]
+
+Initialize or refresh a local agent-owned anchor repository that is safe to use
+as the Git parent for per-task worktrees. The canonical checkout is only used to
+discover the authoritative remote URL.
+EOF
+}
+
+canonical_root=""
+anchor_root=""
+remote_name="origin"
+default_branch="main"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --canonical-root) canonical_root="${2:-}"; shift 2 ;;
+    --anchor-root) anchor_root="${2:-}"; shift 2 ;;
+    --remote) remote_name="${2:-}"; shift 2 ;;
+    --default-branch) default_branch="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$canonical_root" || -z "$anchor_root" ]]; then
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -d "$canonical_root/.git" && ! -f "$canonical_root/.git" ]]; then
+  echo "[agent-sync-anchor] canonical root is not a Git checkout: $canonical_root" >&2
+  exit 1
+fi
+
+origin_url="$(git -C "$canonical_root" remote get-url "$remote_name" 2>/dev/null || true)"
+if [[ -z "$origin_url" ]]; then
+  echo "[agent-sync-anchor] missing remote '$remote_name' in canonical repo: $canonical_root" >&2
+  exit 1
+fi
+
+anchor_parent="$(dirname "$anchor_root")"
+lock_dir="${anchor_root}.sync.lock"
+pid_file="${lock_dir}/pid"
+
+mkdir -p "$anchor_parent"
+
+acquire_lock() {
+  local attempts=0
+  while ! mkdir "$lock_dir" 2>/dev/null; do
+    if [[ -f "$pid_file" ]]; then
+      local existing_pid
+      existing_pid="$(cat "$pid_file" 2>/dev/null || true)"
+      if [[ -n "$existing_pid" ]] && ! kill -0 "$existing_pid" 2>/dev/null; then
+        rm -rf "$lock_dir"
+        continue
+      fi
+    else
+      rm -rf "$lock_dir"
+      continue
+    fi
+
+    attempts=$((attempts + 1))
+    if (( attempts >= 60 )); then
+      echo "[agent-sync-anchor] timed out waiting for anchor lock: $lock_dir" >&2
+      exit 1
+    fi
+    sleep 1
+  done
+  printf '%s\n' "$$" >"$pid_file"
+}
+
+cleanup() {
+  rm -rf "$lock_dir"
+}
+
+trap cleanup EXIT
+acquire_lock
+
+if [[ -e "$anchor_root" && ! -d "$anchor_root/.git" && ! -f "$anchor_root/.git" ]]; then
+  echo "[agent-sync-anchor] anchor root exists but is not a Git checkout: $anchor_root" >&2
+  exit 1
+fi
+
+if [[ ! -d "$anchor_root/.git" && ! -f "$anchor_root/.git" ]]; then
+  git clone \
+    --origin "$remote_name" \
+    --branch "$default_branch" \
+    --single-branch \
+    --no-tags \
+    "$origin_url" \
+    "$anchor_root" >/dev/null
+fi
+
+git -C "$anchor_root" remote set-url "$remote_name" "$origin_url"
+git -C "$anchor_root" config "remote.${remote_name}.prune" true
+git -C "$anchor_root" fetch "$remote_name" --prune >/dev/null
+git -C "$anchor_root" worktree prune >/dev/null 2>&1 || true
+
+if [[ -n "$(git -C "$anchor_root" status --porcelain --untracked-files=no)" ]]; then
+  echo "[agent-sync-anchor] anchor repo is dirty; refuse to reset: $anchor_root" >&2
+  exit 1
+fi
+
+default_ref="${remote_name}/${default_branch}"
+if git -C "$anchor_root" show-ref --verify --quiet "refs/remotes/${default_ref}"; then
+  current_branch="$(git -C "$anchor_root" symbolic-ref --quiet --short HEAD 2>/dev/null || true)"
+  if [[ "$current_branch" != "$default_branch" ]]; then
+    if git -C "$anchor_root" show-ref --verify --quiet "refs/heads/${default_branch}"; then
+      git -C "$anchor_root" checkout "$default_branch" >/dev/null
+    else
+      git -C "$anchor_root" checkout -b "$default_branch" "$default_ref" >/dev/null
+    fi
+  fi
+  git -C "$anchor_root" reset --hard "$default_ref" >/dev/null
+  git -C "$anchor_root" branch --set-upstream-to="$default_ref" "$default_branch" >/dev/null 2>&1 || true
+fi
+
+printf 'CANONICAL_ROOT=%s\n' "$canonical_root"
+printf 'ANCHOR_ROOT=%s\n' "$anchor_root"
+printf 'REMOTE=%s\n' "$remote_name"
+printf 'DEFAULT_BRANCH=%s\n' "$default_branch"
+printf 'ORIGIN_URL=%s\n' "$origin_url"

package/tools/bin/agent-project-worker-status

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  agent-project-worker-status --runs-root <path> --session <id> [--exit-marker <marker>]
+
+Reads a project-lane run directory and reports session status using tmux plus the
+worker log exit marker.
+EOF
+}
+
+runs_root="${AGENT_PROJECT_RUNS_ROOT:-}"
+session=""
+exit_marker="__CODEX_EXIT__:"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --runs-root) runs_root="${2:-}"; shift 2 ;;
+    --session) session="${2:-}"; shift 2 ;;
+    --exit-marker) exit_marker="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$runs_root" || -z "$session" ]]; then
+  usage >&2
+  exit 1
+fi
+
+run_dir="${runs_root}/${session}"
+meta_file="${run_dir}/run.env"
+result_file="${run_dir}/result.env"
+runner_state_file="${run_dir}/runner.env"
+output_file="${run_dir}/${session}.log"
+
+status="UNKNOWN"
+exit_code=""
+result_only_completion="no"
+failure_reason=""
+runner_state=""
+thread_id=""
+last_exit_code=""
+
+if tmux has-session -t "$session" 2>/dev/null; then
+  status="RUNNING"
+fi
+
+if [[ -f "$runner_state_file" ]]; then
+  set -a
+  # shellcheck source=/dev/null
+  source "$runner_state_file"
+  set +a
+  runner_state="${RUNNER_STATE:-}"
+  thread_id="${THREAD_ID:-}"
+  last_exit_code="${LAST_EXIT_CODE:-}"
+  if [[ -z "$failure_reason" ]]; then
+    failure_reason="${LAST_FAILURE_REASON:-}"
+  fi
+fi
+
+if [[ "$status" == "UNKNOWN" ]]; then
+  case "$runner_state" in
+    succeeded)
+      status="SUCCEEDED"
+      ;;
+    failed)
+      status="FAILED"
+      if [[ -z "$exit_code" && -n "$last_exit_code" ]]; then
+        exit_code="$last_exit_code"
+      fi
+      ;;
+  esac
+fi
+
+if [[ "$status" == "UNKNOWN" && -f "$output_file" ]]; then
+  exit_match="$(rg -o "${exit_marker}[0-9]+" "$output_file" | tail -n 1 || true)"
+  if [[ -n "$exit_match" ]]; then
+    exit_code="${exit_match##*:}"
+    if [[ "$exit_code" == "0" ]]; then
+      status="SUCCEEDED"
+    else
+      status="FAILED"
+    fi
+  fi
+fi
+
+if [[ "$status" == "UNKNOWN" && -f "$result_file" ]]; then
+  # A worker that managed to persist result.env already completed its contract,
+  # even if the tmux session disappeared before the exit marker was flushed.
+  status="SUCCEEDED"
+  result_only_completion="yes"
+fi
+
+if [[ "$status" == "UNKNOWN" && -f "$output_file" ]]; then
+  if rg -qi "You've hit your usage limit|You have reached your Codex usage limits|visit https://chatgpt.com/codex/settings/usage|Upgrade to Pro|rate limit exceeded|quota exceeded|usage cap (reached|exceeded)|usage quota (reached|exceeded)" "$output_file"; then
+    status="FAILED"
+    failure_reason="usage-limit"
+  fi
+fi
+
+if [[ "$status" == "UNKNOWN" && -n "$runner_state" ]]; then
+  case "$runner_state" in
+    running|waiting-auth-refresh|switching-account)
+      status="FAILED"
+      if [[ -z "$failure_reason" ]]; then
+        failure_reason="runner-aborted-before-completion"
+      fi
+      if [[ -z "$exit_code" && -n "$last_exit_code" ]]; then
+        exit_code="$last_exit_code"
+      fi
+      ;;
+  esac
+fi
+
+printf 'SESSION=%s\n' "$session"
+printf 'STATUS=%s\n' "$status"
+if [[ -f "$meta_file" ]]; then
+  cat "$meta_file"
+  printf 'META_FILE=%s\n' "$meta_file"
+fi
+if [[ -f "$runner_state_file" ]]; then
+  cat "$runner_state_file"
+  printf 'RUNNER_STATE_FILE=%s\n' "$runner_state_file"
+fi
+if [[ -f "$result_file" ]]; then
+  cat "$result_file"
+  printf 'RESULT_FILE=%s\n' "$result_file"
+fi
+if [[ "$result_only_completion" == "yes" ]]; then
+  printf 'RESULT_ONLY_COMPLETION=yes\n'
+fi
+if [[ -n "$exit_code" ]]; then
+  printf 'EXIT_CODE=%s\n' "$exit_code"
+fi
+if [[ -n "$failure_reason" ]]; then
+  printf 'FAILURE_REASON=%s\n' "$failure_reason"
+fi
+if [[ -n "$thread_id" ]]; then
+  printf 'THREAD_ID=%s\n' "$thread_id"
+fi

package/tools/bin/audit-agent-worktrees.sh

@@ -0,0 +1,310 @@
+#!/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"
+
+WORKER_STATUS_TOOL="${BASH_SOURCE[0]%/*}/agent-project-worker-status"
+WORKTREE_CLEANUP_TOOL="${BASH_SOURCE[0]%/*}/agent-cleanup-worktree"
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
+WORKTREE_ROOT="$(flow_resolve_worktree_root "${CONFIG_YAML}")"
+AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
+RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
+PENDING_LAUNCH_DIR="${ACP_PENDING_LAUNCH_DIR:-${F_LOSNING_PENDING_LAUNCH_DIR:-$(flow_resolve_state_root "${CONFIG_YAML}")/pending-launches}}"
+ISSUE_SESSION_PREFIX="$(flow_resolve_issue_session_prefix "${CONFIG_YAML}")"
+PR_SESSION_PREFIX="$(flow_resolve_pr_session_prefix "${CONFIG_YAML}")"
+ISSUE_BRANCH_PREFIX="$(flow_resolve_issue_branch_prefix "${CONFIG_YAML}")"
+PR_WORKTREE_BRANCH_PREFIX="$(flow_resolve_pr_worktree_branch_prefix "${CONFIG_YAML}")"
+MANAGED_PR_BRANCH_GLOBS="$(flow_resolve_managed_pr_branch_globs "${CONFIG_YAML}")"
+ISSUE_BRANCH_PREFIX_REGEX="$(flow_escape_regex "${ISSUE_BRANCH_PREFIX}")"
+PR_WORKTREE_BRANCH_PREFIX_REGEX="$(flow_escape_regex "${PR_WORKTREE_BRANCH_PREFIX}")"
+
+cleanup="false"
+strict="false"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  audit-agent-worktrees.sh [--cleanup] [--strict]
+
+Audits agent-managed worktrees attached to the anchor repo and removes stale
+ones when they no longer have a running owner and only contain generated
+artifacts such as node_modules symlinks or .openclaw-artifacts.
+
+Options:
+  --cleanup  Remove clean/orphaned agent worktrees automatically.
+  --strict   Exit non-zero when any stale agent worktree is found.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cleanup) cleanup="true"; shift ;;
+    --strict) strict="true"; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+if [[ ! -d "$AGENT_REPO_ROOT/.git" && ! -f "$AGENT_REPO_ROOT/.git" ]]; then
+  echo "agent repo root is not a Git checkout: $AGENT_REPO_ROOT" >&2
+  exit 1
+fi
+
+session_for_worktree() {
+  local worktree_path="${1:-}"
+  local branch_ref="${2:-}"
+  local base
+
+  base="$(basename "$worktree_path")"
+  if [[ "$base" =~ ^pr-([0-9]+)- ]]; then
+    printf '%s%s\n' "${PR_SESSION_PREFIX}" "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  if [[ "$base" =~ ^issue-([0-9]+)- ]]; then
+    printf '%s%s\n' "${ISSUE_SESSION_PREFIX}" "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  if [[ "$branch_ref" =~ ^refs/heads/${PR_WORKTREE_BRANCH_PREFIX_REGEX}-([0-9]+)- ]]; then
+    printf '%s%s\n' "${PR_SESSION_PREFIX}" "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  if [[ "$branch_ref" =~ ^refs/heads/${ISSUE_BRANCH_PREFIX_REGEX}-([0-9]+)- ]]; then
+    printf '%s%s\n' "${ISSUE_SESSION_PREFIX}" "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  return 1
+}
+
+branch_name_is_managed() {
+  local branch_name="${1:-}"
+  local branch_glob=""
+
+  for branch_glob in ${MANAGED_PR_BRANCH_GLOBS}; do
+    case "$branch_name" in
+      ${branch_glob}) return 0 ;;
+    esac
+  done
+
+  return 1
+}
+
+is_agent_managed_worktree() {
+  local worktree_path="${1:-}"
+  local branch_ref="${2:-}"
+  local branch_name=""
+
+  [[ "$worktree_path" == "$WORKTREE_ROOT/"* ]] || return 1
+  if [[ "$branch_ref" == refs/heads/* ]]; then
+    branch_name="${branch_ref#refs/heads/}"
+    if branch_name_is_managed "$branch_name"; then
+      return 0
+    fi
+  fi
+  case "$(basename "$worktree_path")" in
+    pr-*|issue-*|shared-*) return 0 ;;
+  esac
+  return 1
+}
+
+worktree_effectively_dirty() {
+  local worktree_path="${1:?worktree path required}"
+  local filtered=""
+
+  if ! git -C "$worktree_path" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    return 1
+  fi
+
+  filtered="$(
+    git -C "$worktree_path" status --short --untracked-files=normal \
+      | awk '
+          /^\?\? node_modules$/ {next}
+          /^\?\? .+\/node_modules$/ {next}
+          /^\?\? \.openclaw-artifacts$/ {next}
+          /^\?\? \.openclaw-artifacts\// {next}
+          {print}
+        '
+  )"
+  [[ -n "$filtered" ]]
+}
+
+worktree_is_broken() {
+  local worktree_path="${1:?worktree path required}"
+  [[ -d "$worktree_path" ]] || return 0
+  git -C "$worktree_path" rev-parse --is-inside-work-tree >/dev/null 2>&1 && return 1
+  return 0
+}
+
+worktree_has_active_owner() {
+  local session_name="${1:-}"
+  local run_dir=""
+  local status_output=""
+  local status=""
+
+  [[ -n "$session_name" ]] || return 1
+
+  if tmux has-session -t "$session_name" 2>/dev/null; then
+    return 0
+  fi
+
+  run_dir="${RUNS_ROOT}/${session_name}"
+  if [[ ! -d "$run_dir" ]]; then
+    return 1
+  fi
+
+  # Completed workers still own their worktree until host-side reconcile
+  # archives the run or writes reconciled.ok. Otherwise audit can delete the
+  # worktree before publish/retry transitions consume it.
+  if [[ ! -f "${run_dir}/reconciled.ok" ]]; then
+    return 0
+  fi
+
+  status_output="$(
+    "$WORKER_STATUS_TOOL" \
+      --runs-root "$RUNS_ROOT" \
+      --session "$session_name" 2>/dev/null || true
+  )"
+  status="$(awk -F= '/^STATUS=/{print $2}' <<<"$status_output" | tail -n 1)"
+  [[ "$status" == "RUNNING" ]]
+}
+
+worktree_has_active_launch() {
+  local session_name="${1:-}"
+  local pending_file=""
+  local pending_pid=""
+
+  [[ -n "$session_name" ]] || return 1
+
+  case "$session_name" in
+    "${ISSUE_SESSION_PREFIX}"*)
+      pending_file="${PENDING_LAUNCH_DIR}/issue-${session_name#${ISSUE_SESSION_PREFIX}}.pid"
+      ;;
+    "${PR_SESSION_PREFIX}"*)
+      pending_file="${PENDING_LAUNCH_DIR}/pr-${session_name#${PR_SESSION_PREFIX}}.pid"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+
+  [[ -f "$pending_file" ]] || return 1
+  pending_pid="$(tr -d '[:space:]' <"$pending_file" 2>/dev/null || true)"
+  [[ -n "$pending_pid" ]] || return 1
+  kill -0 "$pending_pid" 2>/dev/null
+}
+
+remove_agent_worktree() {
+  local worktree_path="${1:-}"
+  local branch_ref="${2:-}"
+  local branch_name=""
+  local cleanup_args=()
+  local cleanup_failed="false"
+
+  if [[ "$branch_ref" == refs/heads/* ]]; then
+    branch_name="${branch_ref#refs/heads/}"
+    cleanup_args=(--branch "$branch_name" --path "$worktree_path" --allow-unmerged)
+    if [[ "$branch_name" == "${ISSUE_BRANCH_PREFIX}"-* ]]; then
+      cleanup_args+=(--keep-remote)
+    fi
+    if ! (
+      cd "$AGENT_REPO_ROOT"
+      "$WORKTREE_CLEANUP_TOOL" "${cleanup_args[@]}"
+    ) >/dev/null 2>&1; then
+      cleanup_failed="true"
+    fi
+  else
+    git -C "$AGENT_REPO_ROOT" worktree remove "$worktree_path" --force || true
+    git -C "$AGENT_REPO_ROOT" worktree prune
+    return 0
+  fi
+
+  if [[ "$cleanup_failed" == "true" ]]; then
+    rm -rf "$worktree_path"
+    if [[ -n "$branch_name" ]]; then
+      git -C "$AGENT_REPO_ROOT" branch -D "$branch_name" >/dev/null 2>&1 || true
+    fi
+  fi
+
+  git -C "$AGENT_REPO_ROOT" worktree prune >/dev/null 2>&1 || true
+}
+
+issue_count=0
+cleaned_count=0
+
+current_worktree=""
+current_branch_ref=""
+current_head=""
+
+while IFS= read -r line || [[ -n "$line" ]]; do
+  if [[ -z "$line" ]]; then
+    if [[ -n "$current_worktree" ]]; then
+      if [[ "$current_worktree" != "$AGENT_REPO_ROOT" ]] && is_agent_managed_worktree "$current_worktree" "$current_branch_ref"; then
+        session_name="$(session_for_worktree "$current_worktree" "$current_branch_ref" || true)"
+        active_owner="no"
+        if worktree_has_active_owner "$session_name"; then
+          active_owner="yes"
+        fi
+        active_launch="no"
+        if worktree_has_active_launch "$session_name"; then
+          active_launch="yes"
+        fi
+
+        if [[ "$active_owner" == "yes" || "$active_launch" == "yes" ]]; then
+          current_worktree=""
+          current_branch_ref=""
+          current_head=""
+          continue
+        fi
+
+        broken_worktree="no"
+        if worktree_is_broken "$current_worktree"; then
+          broken_worktree="yes"
+        fi
+        dirty="no"
+        if [[ "$broken_worktree" == "no" ]] && worktree_effectively_dirty "$current_worktree"; then
+          dirty="yes"
+        fi
+
+        issue_count=$((issue_count + 1))
+
+        printf 'AGENT_WORKTREE=%s\n' "$current_worktree"
+        printf 'BRANCH_REF=%s\n' "${current_branch_ref:-<detached>}"
+        printf 'HEAD=%s\n' "${current_head:-<unknown>}"
+        printf 'SESSION=%s\n' "${session_name:-<none>}"
+        printf 'BROKEN_WORKTREE=%s\n' "$broken_worktree"
+        printf 'DIRTY=%s\n' "$dirty"
+        printf 'ACTIVE_OWNER=%s\n' "$active_owner"
+        printf 'ACTIVE_LAUNCH=%s\n' "$active_launch"
+
+        if [[ "$cleanup" == "true" && "$dirty" == "no" && "$active_owner" == "no" && "$active_launch" == "no" ]]; then
+          remove_agent_worktree "$current_worktree" "$current_branch_ref"
+          cleaned_count=$((cleaned_count + 1))
+          printf 'CLEANUP=removed\n'
+        else
+          printf 'CLEANUP=skipped\n'
+        fi
+        printf '\n'
+      fi
+
+      current_worktree=""
+      current_branch_ref=""
+      current_head=""
+    fi
+    continue
+  fi
+
+  case "$line" in
+    worktree\ *) current_worktree="${line#worktree }" ;;
+    HEAD\ *) current_head="${line#HEAD }" ;;
+    branch\ *) current_branch_ref="${line#branch }" ;;
+  esac
+done < <(git -C "$AGENT_REPO_ROOT" worktree list --porcelain; printf '\n')
+
+printf 'LEGACY_AGENT_WORKTREE_COUNT=%s\n' "$issue_count"
+printf 'LEGACY_AGENT_WORKTREE_CLEANED=%s\n' "$cleaned_count"
+
+if [[ "$strict" == "true" && "$issue_count" -gt 0 ]]; then
+  exit 2
+fi

package/tools/bin/audit-issue-routing.sh

@@ -0,0 +1,11 @@
+#!/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"
+
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+ADAPTER_BIN_DIR="${FLOW_SKILL_DIR}/bin"
+
+exec "${ADAPTER_BIN_DIR}/audit-issue-routing.sh" "$@"

package/tools/bin/audit-retained-layout.sh

@@ -0,0 +1,58 @@
+#!/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]}")"
+RETAINED_ROOT="$(flow_resolve_retained_repo_root "${CONFIG_YAML}")"
+ADAPTER_ID="$(flow_resolve_adapter_id "${CONFIG_YAML}")"
+
+classify_worktree() {
+  local path="${1:-}"
+  case "$path" in
+    */${ADAPTER_ID}-pr-*|*/${ADAPTER_ID}-issue-*|*/${ADAPTER_ID}-main-clean)
+      printf 'legacy-automation\n'
+      ;;
+    "$RETAINED_ROOT")
+      printf 'retained-main\n'
+      ;;
+    *)
+      printf 'retained-manual\n'
+      ;;
+  esac
+}
+
+count_dirty_paths() {
+  local path="${1:?path required}"
+  git -C "$path" status --porcelain 2>/dev/null | wc -l | tr -d ' '
+}
+
+current_branch() {
+  local path="${1:?path required}"
+  git -C "$path" rev-parse --abbrev-ref HEAD 2>/dev/null || printf 'unknown\n'
+}
+
+current_head() {
+  local path="${1:?path required}"
+  git -C "$path" rev-parse --short HEAD 2>/dev/null || printf 'unknown\n'
+}
+
+worktree_list="$(
+  git -C "$RETAINED_ROOT" worktree list --porcelain |
+    awk '/^worktree /{print substr($0,10)}'
+)"
+
+printf 'RETAINED_ROOT=%s\n' "$RETAINED_ROOT"
+printf 'RETAINED_WORKTREE_COUNT=%s\n' "$(printf '%s\n' "$worktree_list" | sed '/^$/d' | wc -l | tr -d ' ')"
+
+while IFS= read -r worktree; do
+  [[ -n "$worktree" ]] || continue
+  printf '\n[worktree]\n'
+  printf 'path=%s\n' "$worktree"
+  printf 'class=%s\n' "$(classify_worktree "$worktree")"
+  printf 'branch=%s\n' "$(current_branch "$worktree")"
+  printf 'head=%s\n' "$(current_head "$worktree")"
+  printf 'dirty_paths=%s\n' "$(count_dirty_paths "$worktree")"
+done <<<"$worktree_list"