@imdeadpool/guardex 7.0.18 → 7.0.20

package/templates/scripts/agent-file-locks.py

@@ -2,11 +2,11 @@
 """Per-file lock registry for concurrent agent branches.
 
 Usage examples:
-  python3 scripts/agent-file-locks.py claim --branch agent/a path/to/file1 path/to/file2
-  python3 scripts/agent-file-locks.py claim --branch agent/a --allow-delete path/to/obsolete-file
-  python3 scripts/agent-file-locks.py allow-delete --branch agent/a path/to/obsolete-file
-  python3 scripts/agent-file-locks.py validate --branch agent/a --staged
-  python3 scripts/agent-file-locks.py release --branch agent/a
+  gx locks claim --branch agent/a path/to/file1 path/to/file2
+  gx locks claim --branch agent/a --allow-delete path/to/obsolete-file
+  gx locks allow-delete --branch agent/a path/to/obsolete-file
+  gx locks validate --branch agent/a --staged
+  gx locks release --branch agent/a
 """
 
 from __future__ import annotations
@@ -27,9 +27,9 @@ CRITICAL_GUARDRAIL_PATHS = {
     'AGENTS.md',
     '.githooks/pre-commit',
     '.githooks/pre-push',
-    'scripts/agent-branch-start.sh',
-    'scripts/agent-branch-finish.sh',
-    'scripts/agent-file-locks.py',
+    '.githooks/post-merge',
+    '.githooks/post-checkout',
+    'scripts/guardex-env.sh',
 }
 ALLOW_GUARDRAIL_DELETE_ENV = 'AGENT_ALLOW_GUARDRAIL_DELETE'
 
@@ -326,11 +326,11 @@ def cmd_validate(args: argparse.Namespace, repo_root: Path) -> int:
             print(f'    - {file_path}', file=sys.stderr)
         print('    Approve explicit deletions with one of:', file=sys.stderr)
         print(
-            f'      python3 scripts/agent-file-locks.py claim --branch "{args.branch}" --allow-delete <file...>',
+            f'      gx locks claim --branch "{args.branch}" --allow-delete <file...>',
             file=sys.stderr,
         )
         print(
-            f'      python3 scripts/agent-file-locks.py allow-delete --branch "{args.branch}" <file...>',
+            f'      gx locks allow-delete --branch "{args.branch}" <file...>',
             file=sys.stderr,
         )
     if guardrail_delete_blocked:
@@ -343,7 +343,7 @@ def cmd_validate(args: argparse.Namespace, repo_root: Path) -> int:
         )
 
     print('\nClaim files with:', file=sys.stderr)
-    print(f'  python3 scripts/agent-file-locks.py claim --branch "{args.branch}" <file...>', file=sys.stderr)
+    print(f'  gx locks claim --branch "{args.branch}" <file...>', file=sys.stderr)
     return 1
 
 

package/templates/scripts/codex-agent.sh

@@ -7,6 +7,7 @@ BASE_BRANCH="${GUARDEX_BASE_BRANCH:-}"
 BASE_BRANCH_EXPLICIT=0
 CODEX_BIN="${GUARDEX_CODEX_BIN:-codex}"
 NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 AUTO_FINISH_RAW="${GUARDEX_CODEX_AUTO_FINISH:-true}"
 AUTO_REVIEW_ON_CONFLICT_RAW="${GUARDEX_CODEX_AUTO_REVIEW_ON_CONFLICT:-true}"
 AUTO_CLEANUP_RAW="${GUARDEX_CODEX_AUTO_CLEANUP:-true}"
@@ -16,6 +17,30 @@ 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:-}"
+OPENSPEC_TIER=""
+OPENSPEC_SKIP_CHANGE=0
+OPENSPEC_SKIP_PLAN=0
+OPENSPEC_MINIMAL=0
+TASK_MODE=""
+TASK_ROUTING_REASON=""
+
+run_guardex_cli() {
+  if [[ -n "$CLI_ENTRY" ]]; then
+    "$NODE_BIN" "$CLI_ENTRY" "$@"
+    return $?
+  fi
+  if command -v gx >/dev/null 2>&1; then
+    gx "$@"
+    return $?
+  fi
+  if command -v gitguardex >/dev/null 2>&1; then
+    gitguardex "$@"
+    return $?
+  fi
+  echo "[codex-agent] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
 
 normalize_bool() {
   local raw="${1:-}"
@@ -30,6 +55,117 @@ normalize_bool() {
   esac
 }
 
+normalize_tier() {
+  local raw="${1:-}"
+  local fallback="${2:-T2}"
+  local upper
+  upper="$(printf '%s' "$raw" | tr '[:lower:]' '[:upper:]')"
+  case "$upper" in
+    T0|T1|T2|T3) printf '%s' "$upper" ;;
+    '') printf '%s' "$fallback" ;;
+    *) return 1 ;;
+  esac
+}
+
+string_contains_any() {
+  local haystack="$1"
+  shift
+  local needle
+  for needle in "$@"; do
+    if [[ "$haystack" == *"$needle"* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+string_has_lightweight_prefix() {
+  local text="$1"
+  local prefix
+  for prefix in "quick:" "simple:" "tiny:" "minor:" "small:" "just:" "only:"; do
+    if [[ "$text" == "$prefix"* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+derive_task_mode_from_tier() {
+  case "$1" in
+    T0|T1) printf 'caveman' ;;
+    T2|T3) printf 'omx' ;;
+    *) return 1 ;;
+  esac
+}
+
+apply_openspec_tier() {
+  OPENSPEC_SKIP_CHANGE=0
+  OPENSPEC_SKIP_PLAN=0
+  OPENSPEC_MINIMAL=0
+  case "$1" in
+    T0)
+      OPENSPEC_SKIP_CHANGE=1
+      OPENSPEC_SKIP_PLAN=1
+      ;;
+    T1)
+      OPENSPEC_SKIP_PLAN=1
+      OPENSPEC_MINIMAL=1
+      ;;
+    T2)
+      OPENSPEC_SKIP_PLAN=1
+      ;;
+  esac
+}
+
+decide_task_routing() {
+  local task_lower
+  task_lower="$(printf '%s' "$TASK_NAME" | tr '[:upper:]' '[:lower:]')"
+
+  if [[ -n "$OPENSPEC_TIER_RAW" ]]; then
+    if ! OPENSPEC_TIER="$(normalize_tier "$OPENSPEC_TIER_RAW" "T2")"; then
+      echo "[codex-agent] Unsupported OpenSpec tier: ${OPENSPEC_TIER_RAW}" >&2
+      return 1
+    fi
+    TASK_ROUTING_REASON="explicit tier override"
+  elif string_has_lightweight_prefix "$task_lower"; then
+    OPENSPEC_TIER="T1"
+    TASK_ROUTING_REASON="explicit lightweight prefix"
+  elif string_contains_any "$task_lower" \
+    "ralph" "autopilot" "ultrawork" "ultraqa" "ralplan" "deep interview" "ouroboros" \
+    "migration" "refactor" "architecture" "re-architect" "cross-cutting" "multi-agent" \
+    "multiagent" "parallel" "orchestr" "release" "zero-copy" "install surface" "workflow"
+  then
+    OPENSPEC_TIER="T3"
+    TASK_ROUTING_REASON="plan-heavy or orchestration-heavy task wording"
+  elif string_contains_any "$task_lower" \
+    "typo" "spelling" "comment-only" "comment only" "format-only" "format only" \
+    "whitespace" "one-liner" "one liner" "version bump" "bump version" \
+    "single-file" "single file"
+  then
+    OPENSPEC_TIER="T1"
+    TASK_ROUTING_REASON="small bounded maintenance wording"
+  else
+    OPENSPEC_TIER="T2"
+    TASK_ROUTING_REASON="default behavior-change route"
+  fi
+
+  if ! TASK_MODE="$(derive_task_mode_from_tier "$OPENSPEC_TIER")"; then
+    echo "[codex-agent] Unsupported task mode tier: ${OPENSPEC_TIER}" >&2
+    return 1
+  fi
+  apply_openspec_tier "$OPENSPEC_TIER"
+}
+
+describe_task_routing() {
+  case "$OPENSPEC_TIER" in
+    T0) printf 'caveman / T0 (no OpenSpec scaffold)' ;;
+    T1) printf 'caveman / T1 (notes-only OpenSpec)' ;;
+    T2) printf 'omx / T2 (change workspace only)' ;;
+    T3) printf 'omx / T3 (change plus plan workspace)' ;;
+    *) printf 'unknown / %s' "${OPENSPEC_TIER:-unset}" ;;
+  esac
+}
+
 AUTO_FINISH="$(normalize_bool "$AUTO_FINISH_RAW" "1")"
 AUTO_REVIEW_ON_CONFLICT="$(normalize_bool "$AUTO_REVIEW_ON_CONFLICT_RAW" "1")"
 AUTO_CLEANUP="$(normalize_bool "$AUTO_CLEANUP_RAW" "1")"
@@ -40,7 +176,7 @@ resolve_openspec_masterplan_label() {
   local raw="${OPENSPEC_MASTERPLAN_LABEL_RAW:-}"
   local label
 
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ -z "$raw" ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]] || [[ -z "$raw" ]]; then
     printf ''
     return 0
   fi
@@ -68,6 +204,10 @@ while [[ $# -gt 0 ]]; do
       BASE_BRANCH_EXPLICIT=1
       shift 2
       ;;
+    --tier)
+      OPENSPEC_TIER_RAW="${2:-$OPENSPEC_TIER_RAW}"
+      shift 2
+      ;;
     --codex-bin)
       CODEX_BIN="${2:-$CODEX_BIN}"
       shift 2
@@ -133,6 +273,10 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   exit 1
 fi
 
+if ! decide_task_routing; then
+  exit 1
+fi
+
 if ! command -v "$CODEX_BIN" >/dev/null 2>&1; then
   echo "[codex-agent] Missing Codex CLI command: $CODEX_BIN" >&2
   echo "[codex-agent] Install Codex first, then retry." >&2
@@ -375,12 +519,7 @@ start_sandbox_fallback() {
   printf '[agent-branch-start] Worktree: %s\n' "$worktree_path"
 }
 
-if [[ ! -x "${repo_root}/scripts/agent-branch-start.sh" ]]; then
-  echo "[codex-agent] Missing scripts/agent-branch-start.sh. Run: gx setup" >&2
-  exit 1
-fi
-
-start_args=("$TASK_NAME" "$AGENT_NAME")
+start_args=(--tier "$OPENSPEC_TIER" "$TASK_NAME" "$AGENT_NAME")
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
   start_args+=("$BASE_BRANCH")
 fi
@@ -392,7 +531,7 @@ set +e
 start_output="$(
   GUARDEX_OPENSPEC_AUTO_INIT="$OPENSPEC_AUTO_INIT" \
   GUARDEX_OPENSPEC_MASTERPLAN_LABEL="$OPENSPEC_MASTERPLAN_LABEL_RAW" \
-  bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1
+  run_guardex_cli branch start "${start_args[@]}" 2>&1
 )"
 start_status=$?
 set -e
@@ -474,7 +613,10 @@ record_active_session_state() {
     --agent "$AGENT_NAME" \
     --worktree "$wt" \
     --pid "$$" \
-    --cli "$CODEX_BIN"
+    --cli "$CODEX_BIN" \
+    --task-mode "$TASK_MODE" \
+    --openspec-tier "$OPENSPEC_TIER" \
+    --routing-reason "$TASK_ROUTING_REASON"
 }
 
 clear_active_session_state() {
@@ -529,9 +671,10 @@ print_takeover_prompt() {
     change_artifact="openspec/changes/${change_slug}/"
   fi
 
-  finish_cmd="bash scripts/agent-branch-finish.sh --branch \"${branch}\" --base ${base_branch} --via-pr --wait-for-merge --cleanup"
+  finish_cmd="gx branch finish --branch \"${branch}\" --base ${base_branch} --via-pr --wait-for-merge --cleanup"
 
   echo "[codex-agent] Takeover sandbox: ${wt}"
+  echo "[codex-agent] Takeover routing: $(describe_task_routing) (${TASK_ROUTING_REASON})"
   echo "[codex-agent] Takeover prompt: Continue \`${change_slug}\` on branch \`${branch}\`. Work inside \`${wt}\`, review \`${change_artifact}\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`${finish_cmd}\`."
 }
 
@@ -581,28 +724,16 @@ ensure_openspec_plan_workspace() {
   local wt="$1"
   local branch="$2"
 
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
     return 0
   fi
 
-  hydrate_local_helper_in_worktree "$wt" "scripts/openspec/init-plan-workspace.sh"
-
-  local openspec_script="${wt}/scripts/openspec/init-plan-workspace.sh"
-  if [[ ! -f "$openspec_script" ]]; then
-    echo "[codex-agent] Missing OpenSpec init script in sandbox: ${openspec_script}" >&2
-    echo "[codex-agent] Run 'gx setup --target ${repo_root}' and retry." >&2
-    return 1
-  fi
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
   local plan_slug
   plan_slug="$(resolve_openspec_plan_slug "$branch")"
   local init_output=""
   if ! init_output="$(
     cd "$wt"
-    bash "scripts/openspec/init-plan-workspace.sh" "$plan_slug" 2>&1
+    run_guardex_cli internal run-shell planInit "$plan_slug" 2>&1
   )"; then
     printf '%s\n' "$init_output" >&2
     echo "[codex-agent] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2
@@ -618,28 +749,17 @@ ensure_openspec_change_workspace() {
   local wt="$1"
   local branch="$2"
 
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
     return 0
   fi
 
-  hydrate_local_helper_in_worktree "$wt" "scripts/openspec/init-change-workspace.sh"
-
-  local openspec_script="${wt}/scripts/openspec/init-change-workspace.sh"
-  if [[ ! -f "$openspec_script" ]]; then
-    echo "[codex-agent] Missing OpenSpec change init script in sandbox: ${openspec_script}" >&2
-    echo "[codex-agent] Run 'gx setup --target ${repo_root}' and retry." >&2
-    return 1
-  fi
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
   local change_slug capability_slug init_output=""
   change_slug="$(resolve_openspec_change_slug "$branch")"
   capability_slug="$(resolve_openspec_capability_slug)"
   if ! init_output="$(
     cd "$wt"
-    bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1
+    GUARDEX_OPENSPEC_MINIMAL="$OPENSPEC_MINIMAL" \
+      run_guardex_cli internal run-shell changeInit "$change_slug" "$capability_slug" 2>&1
   )"; then
     printf '%s\n' "$init_output" >&2
     echo "[codex-agent] OpenSpec workspace initialization failed for change '${change_slug}'." >&2
@@ -668,11 +788,6 @@ worktree_has_changes() {
 claim_changed_files() {
   local wt="$1"
   local branch="$2"
-  local lock_script="${repo_root}/scripts/agent-file-locks.py"
-
-  if [[ ! -x "$lock_script" ]]; then
-    return 0
-  fi
 
   local changed_raw deleted_raw
   changed_raw="$({
@@ -683,7 +798,7 @@ claim_changed_files() {
 
   if [[ -n "$changed_raw" ]]; then
     mapfile -t changed_files < <(printf '%s\n' "$changed_raw")
-    python3 "$lock_script" claim --branch "$branch" "${changed_files[@]}" >/dev/null 2>&1 || true
+    run_guardex_cli locks claim --branch "$branch" "${changed_files[@]}" >/dev/null 2>&1 || true
   fi
 
   deleted_raw="$({
@@ -693,7 +808,7 @@ claim_changed_files() {
 
   if [[ -n "$deleted_raw" ]]; then
     mapfile -t deleted_files < <(printf '%s\n' "$deleted_raw")
-    python3 "$lock_script" allow-delete --branch "$branch" "${deleted_files[@]}" >/dev/null 2>&1 || true
+    run_guardex_cli locks allow-delete --branch "$branch" "${deleted_files[@]}" >/dev/null 2>&1 || true
   fi
 }
 
@@ -842,7 +957,7 @@ run_finish_flow() {
     return 2
   fi
 
-  if finish_output="$(bash "${repo_root}/scripts/agent-branch-finish.sh" "${finish_args[@]}" 2>&1)"; then
+  if finish_output="$(run_guardex_cli branch finish "${finish_args[@]}" 2>&1)"; then
     printf '%s\n' "$finish_output"
     return 0
   fi
@@ -865,7 +980,7 @@ run_finish_flow() {
       fi
     )
 
-    if finish_output="$(bash "${repo_root}/scripts/agent-branch-finish.sh" "${finish_args[@]}" 2>&1)"; then
+    if finish_output="$(run_guardex_cli branch finish "${finish_args[@]}" 2>&1)"; then
       printf '%s\n' "$finish_output"
       return 0
     fi
@@ -894,6 +1009,8 @@ if ! ensure_openspec_plan_workspace "$worktree_path" "$worktree_branch"; then
   exit 1
 fi
 
+echo "[codex-agent] Task routing: $(describe_task_routing) (${TASK_ROUTING_REASON})"
+
 active_session_recorded=0
 cleanup_active_session_state_on_exit() {
   set +e
@@ -910,7 +1027,10 @@ 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
-"$CODEX_BIN" "$@"
+GUARDEX_TASK_MODE="$TASK_MODE" \
+GUARDEX_OPENSPEC_TIER="$OPENSPEC_TIER" \
+GUARDEX_TASK_ROUTING_REASON="$TASK_ROUTING_REASON" \
+  "$CODEX_BIN" "$@"
 codex_exit="$?"
 set -e
 
@@ -954,18 +1074,16 @@ if [[ "$AUTO_FINISH" -eq 1 && -n "$worktree_branch" && "$worktree_branch" != "HE
   fi
 fi
 
-if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-  echo "[codex-agent] Session ended (exit=${codex_exit}). Running worktree cleanup..."
-  prune_args=()
-  if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
-    prune_args+=(--base "$BASE_BRANCH")
-  fi
-  if [[ "$AUTO_CLEANUP" -eq 1 && "$auto_finish_completed" -eq 1 ]]; then
-    prune_args+=(--only-dirty-worktrees --delete-branches --delete-remote-branches)
-  fi
-  if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" "${prune_args[@]}"; then
-    echo "[codex-agent] Warning: automatic worktree cleanup failed." >&2
-  fi
+echo "[codex-agent] Session ended (exit=${codex_exit}). Running worktree cleanup..."
+prune_args=()
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
+  prune_args+=(--base "$BASE_BRANCH")
+fi
+if [[ "$AUTO_CLEANUP" -eq 1 && "$auto_finish_completed" -eq 1 ]]; then
+  prune_args+=(--only-dirty-worktrees --delete-branches --delete-remote-branches)
+fi
+if ! run_guardex_cli worktree prune "${prune_args[@]}"; then
+  echo "[codex-agent] Warning: automatic worktree cleanup failed." >&2
 fi
 
 if [[ ! -d "$worktree_path" ]]; then
@@ -978,7 +1096,7 @@ else
       echo "[codex-agent] Branch kept intentionally. Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     else
       print_takeover_prompt "$worktree_path" "$worktree_branch"
-      echo "[codex-agent] If finished, merge with: bash scripts/agent-branch-finish.sh --branch \"${worktree_branch}\" --base dev --via-pr --wait-for-merge"
+      echo "[codex-agent] If finished, merge with: gx branch finish --branch \"${worktree_branch}\" --base dev --via-pr --wait-for-merge"
       echo "[codex-agent] Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     fi
   fi

package/templates/scripts/review-bot-watch.sh

@@ -9,10 +9,12 @@ BASE_BRANCH="${GUARDEX_REVIEW_BOT_BASE_BRANCH:-}"
 ONLY_PR="${GUARDEX_REVIEW_BOT_ONLY_PR:-}"
 RETRY_FAILED_RAW="${GUARDEX_REVIEW_BOT_RETRY_FAILED:-false}"
 INCLUDE_DRAFT_RAW="${GUARDEX_REVIEW_BOT_INCLUDE_DRAFT:-false}"
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 
 usage() {
   cat <<'USAGE'
-Usage: bash scripts/review-bot-watch.sh [options]
+Usage: gx review [options]
 
 Continuously monitor GitHub pull requests targeting a base branch and dispatch
 one Codex-agent task per newly opened/updated PR.
@@ -34,6 +36,23 @@ Environment overrides:
 USAGE
 }
 
+run_guardex_cli() {
+  if [[ -n "$CLI_ENTRY" ]]; then
+    "$NODE_BIN" "$CLI_ENTRY" "$@"
+    return $?
+  fi
+  if command -v gx >/dev/null 2>&1; then
+    gx "$@"
+    return $?
+  fi
+  if command -v gitguardex >/dev/null 2>&1; then
+    gitguardex "$@"
+    return $?
+  fi
+  echo "[review-bot-watch] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 normalize_bool() {
   local raw="${1:-}"
   local fallback="${2:-0}"
@@ -134,16 +153,20 @@ if ! command -v codex >/dev/null 2>&1; then
   exit 127
 fi
 
-if [[ ! -x "$repo_root/scripts/codex-agent.sh" ]]; then
-  echo "[review-bot-watch] Missing scripts/codex-agent.sh. Run: gx setup" >&2
-  exit 1
-fi
-
 if ! gh auth status >/dev/null 2>&1; then
   echo "[review-bot-watch] gh is not authenticated. Run: gh auth login" >&2
   exit 1
 fi
 
+run_codex_agent() {
+  local local_script="$repo_root/scripts/codex-agent.sh"
+  if [[ -x "$local_script" ]]; then
+    bash "$local_script" "$@"
+    return $?
+  fi
+  run_guardex_cli internal run-shell codexAgent --target "$repo_root" "$@"
+}
+
 sanitize_slug() {
   local raw="$1"
   local fallback="$2"
@@ -262,7 +285,7 @@ process_one_pr() {
 
   echo "[review-bot-watch] Dispatching Codex agent for PR #${pr} (${head_branch})"
   set +e
-  bash "$repo_root/scripts/codex-agent.sh" \
+  run_codex_agent \
     --task "$task_name" \
     --agent "$AGENT_NAME" \
     --base "$BASE_BRANCH" \

package/templates/vscode/guardex-active-agents/README.md

@@ -2,20 +2,26 @@
 
 Local VS Code companion for Guardex-managed repos.
 
-What it does:
+## Quick Start
 
-- Adds an `Active Agents` view to the Source Control container.
-- Renders one repo node per live Guardex workspace with grouped `ACTIVE AGENTS` and `CHANGES` sections.
-- Shows one row per live Guardex sandbox session inside the repo's `ACTIVE AGENTS` section.
-- Shows repo-root git changes in a sibling `CHANGES` section when the guarded repo itself is dirty.
-- Derives `thinking` versus `working` from the live sandbox worktree and shows changed-file counts for active edits.
-- Uses VS Code's native animated `loading~spin` icon for the running-state affordance.
-- Reads repo-local presence files from `.omx/state/active-sessions/`.
+Use the welcome view in Source Control to create or inspect Guardex sandboxes quickly.
 
-Install from a Guardex-wired repo:
+1. Install from a Guardex-wired repo:
 
 ```sh
 node scripts/install-vscode-active-agents-extension.js
 ```
 
-Then reload the VS Code window.
+2. Reload the VS Code window.
+3. In Source Control -> `Active Agents`, use `Start agent` to enter a task + agent name and run `gx branch start`.
+
+What it does:
+
+- Adds an `Active Agents` view to the Source Control container.
+- Renders one repo node per live Guardex workspace with grouped `ACTIVE AGENTS` and `CHANGES` sections.
+- Splits live sessions inside `ACTIVE AGENTS` into `BLOCKED`, `WORKING NOW`, `IDLE`, `STALLED`, and `DEAD` groups so stuck, active, and inactive lanes stand out immediately.
+- Shows one row per live Guardex sandbox session inside those activity groups.
+- Shows repo-root git changes in a sibling `CHANGES` section when the guarded repo itself is dirty.
+- Derives session state from dirty worktree status, git conflict markers, PID liveness, and recent file mtimes, surfaces working/dead counts in the repo/header summary, and shows changed-file counts for active edits.
+- Uses distinct VS Code codicons for each session state: `warning`, `edit`, `loading~spin`, `clock`, and `error`.
+- Reads repo-local presence files from `.omx/state/active-sessions/`.