@imdeadpool/guardex 7.0.43 → 7.1.0

package/templates/scripts/agent-branch-finish.sh

@@ -17,16 +17,11 @@ WAIT_TIMEOUT_SECONDS_RAW="${GUARDEX_FINISH_WAIT_TIMEOUT_SECONDS:-1800}"
 WAIT_POLL_SECONDS_RAW="${GUARDEX_FINISH_WAIT_POLL_SECONDS:-10}"
 PARENT_GITLINK_AUTO_COMMIT_RAW="${GUARDEX_FINISH_PARENT_GITLINK_AUTO_COMMIT:-true}"
 AUTO_RESOLVE_MODE_RAW="${GUARDEX_FINISH_AUTO_RESOLVE:-none}"
-AUTO_RESOLVE_SAFE_GLOBS_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.agents/settings.local.json:.codex/state/**:.claude/state/**'
+AUTO_RESOLVE_SAFE_GLOBS_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.codex/settings.local.json:.claude/settings.local.json:.codex/state/**:.claude/state/**'
 AUTO_RESOLVE_SAFE_GLOBS_RAW="${GUARDEX_FINISH_AUTO_RESOLVE_SAFE_GLOBS-$AUTO_RESOLVE_SAFE_GLOBS_DEFAULT}"
 PREFLIGHT_ENABLED_RAW="${GUARDEX_FINISH_PREFLIGHT:-true}"
 PREFLIGHT_SCRIPT_RAW="${GUARDEX_FINISH_PREFLIGHT_SCRIPT:-scripts/agent-preflight.sh}"
 AUTO_PROMOTE_DRAFT_RAW="${GUARDEX_FINISH_AUTO_PROMOTE:-true}"
-# --skip-checks (or GUARDEX_FINISH_SKIP_CHECKS=1): append `--admin` to every
-# `gh pr merge` invocation, bypassing required status checks. Requires admin
-# permission on the target repo. Use when CI is wedged (e.g. runner billing,
-# infrastructure outage) and the operator has accepted the risk.
-SKIP_CHECKS_RAW="${GUARDEX_FINISH_SKIP_CHECKS:-false}"
 
 run_guardex_cli() {
   if [[ -n "$CLI_ENTRY" ]]; then
@@ -152,10 +147,13 @@ WAIT_POLL_SECONDS="$(normalize_int "$WAIT_POLL_SECONDS_RAW" "10" "0")"
 PARENT_GITLINK_AUTO_COMMIT="$(normalize_bool "$PARENT_GITLINK_AUTO_COMMIT_RAW" "1")"
 PREFLIGHT_ENABLED="$(normalize_bool "$PREFLIGHT_ENABLED_RAW" "1")"
 AUTO_PROMOTE_DRAFT="$(normalize_bool "$AUTO_PROMOTE_DRAFT_RAW" "1")"
-SKIP_CHECKS="$(normalize_bool "$SKIP_CHECKS_RAW" "0")"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    -h|--help)
+      echo "Usage: $0 [--base <branch>] [--branch <branch>] [--no-push] [--cleanup|--no-cleanup] [--wait-for-merge|--no-wait-for-merge] [--wait-timeout-seconds <n>] [--wait-poll-seconds <n>] [--parent-gitlink-commit|--no-parent-gitlink-commit] [--keep-remote-branch|--delete-remote-branch] [--mode auto|direct|pr|--via-pr|--direct-only] [--auto-resolve[=none|safe|full]|--no-auto-resolve] [--no-preflight|--preflight] [--preflight-script <path>] [--no-auto-promote|--auto-promote]"
+      exit 0
+      ;;
     --base)
       BASE_BRANCH="${2:-}"
       BASE_BRANCH_EXPLICIT=1
@@ -252,14 +250,6 @@ while [[ $# -gt 0 ]]; do
       PREFLIGHT_SCRIPT_RAW="${2:-}"
       shift 2
       ;;
-    --skip-checks)
-      SKIP_CHECKS=1
-      shift
-      ;;
-    --no-skip-checks)
-      SKIP_CHECKS=0
-      shift
-      ;;
     --no-auto-promote)
       AUTO_PROMOTE_DRAFT_RAW="false"
       shift
@@ -1161,13 +1151,9 @@ wait_for_pr_merge() {
   deadline=$(( $(date +%s) + WAIT_TIMEOUT_SECONDS ))
   local wait_notice_printed=0
   local merge_output=""
-  local -a merge_flags=(--squash --delete-branch)
-  if [[ "$SKIP_CHECKS" -eq 1 ]]; then
-    merge_flags+=(--admin)
-  fi
 
   while true; do
-    if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" "${merge_flags[@]}" 2>&1)"; then
+    if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" --squash --delete-branch 2>&1)"; then
       return 0
     fi
     if is_local_branch_delete_error "$merge_output"; then
@@ -1273,11 +1259,7 @@ run_pr_flow() {
   maybe_auto_promote_pr "$pr_url"
 
   merge_output=""
-  local -a merge_flags=(--squash --delete-branch)
-  if [[ "$SKIP_CHECKS" -eq 1 ]]; then
-    merge_flags+=(--admin)
-  fi
-  if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" "${merge_flags[@]}" 2>&1)"; then
+  if merge_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" --squash --delete-branch 2>&1)"; then
     return 0
   fi
   if is_local_branch_delete_error "$merge_output"; then
@@ -1291,11 +1273,7 @@ run_pr_flow() {
   fi
 
   auto_output=""
-  local -a auto_flags=(--squash --delete-branch --auto)
-  if [[ "$SKIP_CHECKS" -eq 1 ]]; then
-    auto_flags+=(--admin)
-  fi
-  if auto_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" "${auto_flags[@]}" 2>&1)"; then
+  if auto_output="$("$GH_BIN" pr merge "$SOURCE_BRANCH" --squash --delete-branch --auto 2>&1)"; then
     echo "[agent-branch-finish] PR auto-merge enabled; waiting for required checks/reviews." >&2
     return 2
   fi

package/templates/scripts/agent-branch-merge.sh

@@ -281,7 +281,10 @@ if [[ -z "$TARGET_BRANCH" ]]; then
   start_output=""
   if ! start_output="$(
     cd "$repo_root"
-    GUARDEX_OPENSPEC_AUTO_INIT=1 run_guardex_cli branch start "$TASK_NAME" "$AGENT_NAME" "$BASE_BRANCH" 2>&1
+    # An integration lane is inherently cross-cutting, so pin it to T3 (full
+    # change + plan workspace) regardless of the branch-start default (now T1).
+    GUARDEX_OPENSPEC_AUTO_INIT=1 GUARDEX_OPENSPEC_TIER="${GUARDEX_OPENSPEC_TIER:-T3}" \
+      run_guardex_cli branch start "$TASK_NAME" "$AGENT_NAME" "$BASE_BRANCH" 2>&1
   )"; then
     printf '%s\n' "$start_output" >&2
     exit 1

package/templates/scripts/agent-branch-start.sh

@@ -14,10 +14,13 @@ OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
 OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
-OPENSPEC_TIER_RAW="${GUARDEX_OPENSPEC_TIER:-T3}"
+# Default tier is T1 (notes.md only, minimal scaffold): most tasks are small,
+# and a full T3 plan workspace costs thousands of tokens an agent never reads.
+# Escalate explicitly with --tier T2 (behavior change) or T3 (plan-driven).
+OPENSPEC_TIER_RAW="${GUARDEX_OPENSPEC_TIER:-T1}"
 REUSE_EXISTING_RAW="${GUARDEX_BRANCH_START_REUSE_EXISTING:-true}"
 AUTO_TRANSFER_ENABLED_RAW="${GUARDEX_AUTO_TRANSFER:-true}"
-AUTO_TRANSFER_EXCLUDE_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.agents/settings.local.json:.codex/state/**:.claude/state/**'
+AUTO_TRANSFER_EXCLUDE_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.codex/settings.local.json:.claude/settings.local.json:.codex/state/**:.claude/state/**'
 AUTO_TRANSFER_EXCLUDE_RAW="${GUARDEX_AUTO_TRANSFER_EXCLUDE-$AUTO_TRANSFER_EXCLUDE_DEFAULT}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
@@ -39,8 +42,40 @@ run_guardex_cli() {
   return 127
 }
 
+print_usage() {
+  cat <<'USAGE'
+Usage: agent-branch-start [task] [agent] [base] [options]
+
+Start an isolated agent/* branch + worktree for a task.
+
+Positional:
+  task                 Task name/slug (default: "task")
+  agent                Agent name (default: "agent")
+  base                 Base branch to fork from (default: repo default)
+
+Options:
+  --task <name>        Task name/slug
+  --agent <name>       Agent name
+  --base <branch>      Base branch to fork from
+  --worktree-root <p>  Worktree root dir (default: .omx/agent-worktrees)
+  --reuse-existing     Reuse an existing matching worktree (default)
+  --new                Force a fresh worktree instead of reusing
+  --tier <T1|T2|T3>    OpenSpec tier for scaffolding (default T1; T2 for a
+                       behavior change, T3 for plan-driven work)
+  --transfer           Auto-transfer uncommitted changes into the worktree (default)
+  --no-transfer        Do not auto-transfer uncommitted changes
+  --transfer-exclude <globs>  Colon-separated globs to exclude from transfer
+  --print-name-only    Print the computed branch name and exit
+  -h, --help           Show this help and exit
+USAGE
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    -h|--help)
+      print_usage
+      exit 0
+      ;;
     --task)
       TASK_NAME="${2:-task}"
       shift 2
@@ -292,7 +327,7 @@ normalize_tier() {
   esac
 }
 
-if ! OPENSPEC_TIER="$(normalize_tier "$OPENSPEC_TIER_RAW" "T3")"; then
+if ! OPENSPEC_TIER="$(normalize_tier "$OPENSPEC_TIER_RAW" "T1")"; then
   echo "[agent-branch-start] Unsupported OpenSpec tier: ${OPENSPEC_TIER_RAW}" >&2
   exit 1
 fi
@@ -417,6 +452,20 @@ print_agent_next_steps() {
     base_branch="main"
   fi
 
+  # Pre-`Ready:` post-condition check. `git worktree add` has been observed
+  # to return 0 with the worktree dir still missing on disk (race condition
+  # during the OpenSpec / dependency-symlink phase between `worktree add`
+  # and now). If we print `Ready:` in that state, callers cd into a
+  # vanished directory and lose subsequent edits silently. Surface it as
+  # an exit-1 error instead — operator can retry + `git worktree prune`.
+  if [[ ! -d "$worktree_path" || ! -e "$worktree_path/.git" ]]; then
+    printf '[agent-branch-start] ERROR: worktree did not materialize on disk before Ready:\n' >&2
+    printf '[agent-branch-start]   branch:   %s\n' "$branch_name" >&2
+    printf '[agent-branch-start]   expected: %s\n' "$worktree_path" >&2
+    printf '[agent-branch-start] Run `git worktree prune` to clear ghost entries, then retry.\n' >&2
+    exit 1
+  fi
+
   echo "[agent-branch-start] Ready:"
   echo "  branch:   ${branch_name}"
   echo "  worktree: ${worktree_path}"
@@ -494,6 +543,25 @@ managed_worktree_roots() {
   done
 }
 
+branch_published_then_remote_pruned() {
+  # Detect the post-`gx branch finish --via-pr --cleanup` state: the agent
+  # branch was published (so upstream config is set), but the remote-tracking
+  # ref no longer exists (because `push origin --delete` ran during cleanup).
+  # That combination only arises after a finish that successfully merged the
+  # PR and pruned the remote branch — a freshly-created agent branch never
+  # has an upstream until publish, so this never false-positives on the
+  # "started, dirty, no commits yet" case that we want to keep reusable.
+  local repo="$1"
+  local branch="$2"
+  local upstream
+  upstream="$(git -C "$repo" config --get "branch.${branch}.remote" 2>/dev/null || true)"
+  [[ -n "$upstream" ]] || return 1
+  if git -C "$repo" show-ref --verify --quiet "refs/remotes/${upstream}/${branch}"; then
+    return 1
+  fi
+  return 0
+}
+
 find_matching_dirty_agent_worktree() {
   local repo="$1"
   local worktree_root_rel="$2"
@@ -514,6 +582,13 @@ find_matching_dirty_agent_worktree() {
       fi
       [[ "$branch" == "agent/${agent_slug}/"* ]] || continue
       has_local_changes "$entry" || continue
+      # Skip merged-and-cleaned worktrees that happen to still be on disk
+      # (e.g. operator's shell is cwd'd inside; cleanup deferred). Reusing
+      # such a worktree would silently hand the next agent a stale HEAD.
+      if branch_published_then_remote_pruned "$repo" "$branch"; then
+        echo "[agent-branch-start] Skipping merged-and-cleaned worktree: ${entry} (branch ${branch} has no remote tracking ref)" >&2
+        continue
+      fi
 
       descriptor="${branch#agent/${agent_slug}/}"
       score="$(token_match_score "$task_slug" "$descriptor")"
@@ -864,6 +939,13 @@ if ! worktree_add_output="$(git -C "$repo_root" worktree add -b "$branch_name" "
   printf '%s\n' "$worktree_add_output" >&2
   exit 1
 fi
+# git worktree add has been observed to exit 0 while the target dir is
+# missing — verify before downstream init runs against a phantom path.
+if [[ ! -d "$worktree_path" || ! -e "$worktree_path/.git" ]]; then
+  printf '[agent-branch-start] ERROR: git worktree add reported success but %s is not a valid worktree.\n' "$worktree_path" >&2
+  printf '%s\n' "$worktree_add_output" >&2
+  exit 1
+fi
 git -C "$repo_root" config "branch.${branch_name}.guardexBase" "$BASE_BRANCH" >/dev/null 2>&1 || true
 git -C "$repo_root" config "branch.${branch_name}.guardexWorktreeRoot" "$WORKTREE_ROOT_REL" >/dev/null 2>&1 || true
 # Fresh agent branches should start unpublished; clear any inherited base-branch tracking.
@@ -899,6 +981,9 @@ fi
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
 echo "[agent-branch-start] OpenSpec tier: ${OPENSPEC_TIER}"
+if [[ "$OPENSPEC_TIER" == "T1" ]]; then
+  echo "[agent-branch-start] T1 minimal scaffold (notes.md). Escalate: --tier T2 for a behavior change, T3 for plan-driven work."
+fi
 if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
   echo "[agent-branch-start] OpenSpec change: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)"
 elif [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then

package/templates/scripts/agent-preflight.sh

@@ -22,17 +22,43 @@ set -euo pipefail
 repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 cd "$repo_root"
 
-ran=0
+ran=0        # steps that PASSED
+attempted=0  # steps that RAN (pass or fail) — drives stack detection
 fail=0
+# Quiet by default: a green `npm test` run can be hundreds of lines of TAP that
+# floods the agent's context on every `gx branch finish`. Capture each step's
+# output, print a one-line summary on success, and surface only the tail on
+# failure (where it is actually useful). Stream full output live with
+# GUARDEX_PREFLIGHT_VERBOSE=1.
+GUARDEX_PREFLIGHT_FAIL_TAIL="${GUARDEX_PREFLIGHT_FAIL_TAIL:-40}"
 run_step() {
   local label="$1"
   shift
   echo "[agent-preflight] -> $label"
-  if "$@"; then
+  attempted=$((attempted + 1))
+  if [[ "${GUARDEX_PREFLIGHT_VERBOSE:-0}" == "1" ]]; then
+    if "$@"; then
+      ran=$((ran + 1))
+      echo "[agent-preflight]    ok"
+    else
+      echo "[agent-preflight] FAIL: $label" >&2
+      fail=1
+    fi
+    return 0
+  fi
+  local out rc
+  # `if` keeps `set -e` from aborting on a failing step before we capture rc.
+  if out="$("$@" 2>&1)"; then
+    rc=0
+  else
+    rc=$?
+  fi
+  if [[ "$rc" -eq 0 ]]; then
     ran=$((ran + 1))
-    echo "[agent-preflight]    ok"
+    echo "[agent-preflight]    ok ($(printf '%s\n' "$out" | wc -l | tr -d ' ') lines suppressed; GUARDEX_PREFLIGHT_VERBOSE=1 to show)"
   else
-    echo "[agent-preflight] FAIL: $label" >&2
+    echo "[agent-preflight] FAIL: $label (exit $rc) — last ${GUARDEX_PREFLIGHT_FAIL_TAIL} lines:" >&2
+    printf '%s\n' "$out" | tail -n "$GUARDEX_PREFLIGHT_FAIL_TAIL" >&2
     fail=1
   fi
 }
@@ -74,7 +100,7 @@ if [[ -f pyproject.toml ]] && command -v ruff >/dev/null 2>&1; then
   run_step "ruff check" ruff check .
 fi
 
-if [[ "$ran" -eq 0 ]]; then
+if [[ "$attempted" -eq 0 ]]; then
   echo "[agent-preflight] No recognized project stack detected; skipping checks." >&2
   exit 0
 fi

package/templates/scripts/agent-worktree-prune.sh

@@ -253,7 +253,7 @@ branch_has_worktree() {
 # content matches these are considered clean for prune purposes. Mirrors the
 # auto-transfer + auto-resolve allowlist from PRs #546/#547 (state-file globs
 # never carry authoritative content out of an agent branch).
-WORKTREE_STATE_EXCLUDE_GLOBS_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.agents/settings.local.json:.codex/state/**:.claude/state/**'
+WORKTREE_STATE_EXCLUDE_GLOBS_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.codex/settings.local.json:.claude/settings.local.json:.codex/state/**:.claude/state/**'
 WORKTREE_STATE_EXCLUDE_GLOBS_RAW="${GUARDEX_PRUNE_STATE_EXCLUDE_GLOBS-$WORKTREE_STATE_EXCLUDE_GLOBS_DEFAULT}"
 
 build_state_exclude_pathspec_args() {

package/templates/scripts/codex-agent.sh

@@ -324,7 +324,6 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   exit 1
 fi
 repo_root="$(git rev-parse --show-toplevel)"
-active_session_state_script="${repo_root}/scripts/agent-session-state.js"
 
 guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
 if [[ -f "$guardex_env_helper" ]]; then
@@ -638,78 +637,6 @@ has_origin_remote() {
   git -C "$repo_root" remote get-url origin >/dev/null 2>&1
 }
 
-run_active_session_state() {
-  local action="$1"
-  shift
-
-  if [[ ! -f "$active_session_state_script" ]]; then
-    return 0
-  fi
-  if ! command -v "$NODE_BIN" >/dev/null 2>&1; then
-    return 0
-  fi
-
-  "$NODE_BIN" "$active_session_state_script" "$action" "$@" >/dev/null 2>&1 || true
-}
-
-record_active_session_state() {
-  local wt="$1"
-  local branch="$2"
-
-  run_active_session_state \
-    start \
-    --repo "$repo_root" \
-    --branch "$branch" \
-    --task "$TASK_NAME" \
-    --agent "$AGENT_NAME" \
-    --worktree "$wt" \
-    --pid "$$" \
-    --cli "$CODEX_BIN" \
-    --task-mode "$TASK_MODE" \
-    --openspec-tier "$OPENSPEC_TIER" \
-    --routing-reason "$TASK_ROUTING_REASON"
-}
-
-clear_active_session_state() {
-  local branch="$1"
-  run_active_session_state stop --repo "$repo_root" --branch "$branch"
-}
-
-heartbeat_active_session_state() {
-  local branch="$1"
-  run_active_session_state heartbeat --repo "$repo_root" --branch "$branch" --state working
-}
-
-normalize_heartbeat_interval_seconds() {
-  local raw="${GUARDEX_ACTIVE_SESSION_HEARTBEAT_INTERVAL_SECONDS:-15}"
-  if [[ "$raw" =~ ^[0-9]+$ ]] && [[ "$raw" -ge 1 ]]; then
-    printf '%s' "$raw"
-    return 0
-  fi
-  printf '15'
-}
-
-start_active_session_heartbeat() {
-  local branch="$1"
-  local interval
-  interval="$(normalize_heartbeat_interval_seconds)"
-  (
-    while true; do
-      sleep "$interval" || break
-      heartbeat_active_session_state "$branch"
-    done
-  ) &
-  active_session_heartbeat_pid="$!"
-}
-
-stop_active_session_heartbeat() {
-  if [[ -n "${active_session_heartbeat_pid:-}" ]]; then
-    kill "$active_session_heartbeat_pid" >/dev/null 2>&1 || true
-    wait "$active_session_heartbeat_pid" >/dev/null 2>&1 || true
-    active_session_heartbeat_pid=""
-  fi
-}
-
 origin_remote_supports_pr_finish() {
   local origin_url
   origin_url="$(git -C "$repo_root" remote get-url origin 2>/dev/null || true)"
@@ -1103,22 +1030,6 @@ fi
 
 echo "[codex-agent] Task routing: $(describe_task_routing) (${TASK_ROUTING_REASON})"
 
-active_session_recorded=0
-active_session_heartbeat_pid=""
-cleanup_active_session_state_on_exit() {
-  set +e
-  if [[ "${active_session_recorded:-0}" -eq 1 && -n "${worktree_branch:-}" && "${worktree_branch:-}" != "HEAD" ]]; then
-    stop_active_session_heartbeat
-    clear_active_session_state "$worktree_branch"
-    active_session_recorded=0
-  fi
-}
-
-record_active_session_state "$worktree_path" "$worktree_branch"
-active_session_recorded=1
-start_active_session_heartbeat "$worktree_branch"
-trap cleanup_active_session_state_on_exit EXIT INT TERM
-
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"
 cd "$worktree_path"
 set +e
@@ -1131,8 +1042,6 @@ codex_exit="$?"
 set -e
 
 cd "$repo_root"
-cleanup_active_session_state_on_exit
-trap - EXIT INT TERM
 final_exit="$codex_exit"
 auto_finish_completed=0
 

package/src/agents/detect.js

@@ -1,160 +0,0 @@
-const registry = require('./registry');
-const { run } = require('../core/runtime');
-
-function registryEntries() {
-  if (typeof registry.getAgentDefinitions === 'function') {
-    const definitions = registry.getAgentDefinitions();
-    if (Array.isArray(definitions)) {
-      return definitions;
-    }
-  }
-
-  if (Array.isArray(registry.AGENT_IDS) && typeof registry.getAgentDefinition === 'function') {
-    return registry.AGENT_IDS
-      .map((agentId) => registry.getAgentDefinition(agentId))
-      .filter((entry) => entry && typeof entry === 'object');
-  }
-
-  const source =
-    registry.agents ||
-    registry.AGENTS ||
-    registry.registry ||
-    registry.entries ||
-    registry.default ||
-    registry;
-
-  if (Array.isArray(source)) {
-    return source;
-  }
-
-  if (source && typeof source === 'object') {
-    return Object.entries(source)
-      .filter(([, entry]) => entry && typeof entry === 'object')
-      .map(([id, entry]) => ({ id, ...entry }));
-  }
-
-  return [];
-}
-
-function findAgent(agentId) {
-  if (typeof registry.getAgentDefinition === 'function') {
-    const entry = registry.getAgentDefinition(agentId);
-    if (entry) return entry;
-  }
-
-  if (typeof registry.resolveAgent === 'function') {
-    try {
-      const entry = registry.resolveAgent(agentId);
-      if (entry) return entry;
-    } catch (_error) {
-      return null;
-    }
-  }
-
-  if (typeof registry.getAgent === 'function') {
-    const entry = registry.getAgent(agentId);
-    if (entry) return entry;
-  }
-
-  return registryEntries().find((entry) => entry.id === agentId);
-}
-
-function registryAgentIds() {
-  if (Array.isArray(registry.AGENT_IDS)) {
-    return [...registry.AGENT_IDS];
-  }
-
-  if (typeof registry.getAgentDefinitions === 'function') {
-    const definitions = registry.getAgentDefinitions();
-    if (Array.isArray(definitions)) {
-      return definitions.map((entry) => entry && entry.id).filter(Boolean);
-    }
-  }
-
-  return registryEntries().map((entry) => entry.id).filter(Boolean);
-}
-
-function normalizeDetectCommand(detectCommand) {
-  if (Array.isArray(detectCommand)) {
-    const [cmd, ...args] = detectCommand;
-    return { cmd, args, command: detectCommand.join(' ') };
-  }
-
-  if (typeof detectCommand === 'string') {
-    const [cmd, ...args] = detectCommand.trim().split(/\s+/).filter(Boolean);
-    return { cmd, args, command: detectCommand.trim() };
-  }
-
-  if (detectCommand && typeof detectCommand === 'object') {
-    const cmd = detectCommand.cmd || detectCommand.command || detectCommand.bin;
-    const args = Array.isArray(detectCommand.args) ? detectCommand.args : [];
-    return {
-      cmd,
-      args,
-      command: [cmd, ...args].filter(Boolean).join(' '),
-    };
-  }
-
-  return { cmd: null, args: [], command: null };
-}
-
-function resultError(result) {
-  if (result.error) {
-    return result.error.message || String(result.error);
-  }
-
-  const output = `${result.stderr || ''}${result.stdout || ''}`.trim();
-  if (output) return output;
-
-  if (typeof result.status === 'number') {
-    return `detect command exited with status ${result.status}`;
-  }
-
-  return 'detect command failed';
-}
-
-function detectionResult(entry, available, command, error = null) {
-  return {
-    id: entry.id,
-    label: entry.label || entry.id,
-    available,
-    command,
-    error,
-  };
-}
-
-function detectAgent(agentId) {
-  const entry = findAgent(agentId);
-  if (!entry) {
-    const known = registryAgentIds();
-    const suffix = known.length > 0 ? ` (known agents: ${known.join(', ')})` : '';
-    return detectionResult({ id: agentId, label: agentId }, false, null, `unknown agent: ${agentId}${suffix}`);
-  }
-
-  const { cmd, args, command } = normalizeDetectCommand(entry.detectCommand);
-  if (!cmd) {
-    return detectionResult(entry, false, command, 'missing detectCommand');
-  }
-
-  const result = run(cmd, args, { stdio: 'pipe' });
-  if (!result.error && result.status === 0) {
-    return detectionResult(entry, true, command, null);
-  }
-
-  return detectionResult(entry, false, command, resultError(result));
-}
-
-function detectAgents(agentIds) {
-  const ids = Array.isArray(agentIds) ? agentIds : registryAgentIds();
-  return ids.map((agentId) => detectAgent(agentId));
-}
-
-function detectAvailableAgents() {
-  return detectAgents().filter((agent) => agent.available);
-}
-
-module.exports = {
-  detectAgent,
-  detectAgents,
-  detectAvailableAgents,
-};