@imdeadpool/guardex 7.0.19 → 7.0.20

package/src/toolchain/index.js

@@ -0,0 +1,223 @@
+function createToolchainApi(deps) {
+  const {
+    TOOL_NAME,
+    NPM_BIN,
+    NPX_BIN,
+    packageJson,
+    OPENSPEC_PACKAGE,
+    OPENSPEC_BIN,
+    GLOBAL_TOOLCHAIN_PACKAGES,
+    parseAutoApproval,
+    isInteractiveTerminal,
+    promptYesNoStrict,
+    run,
+    checkForGuardexUpdate,
+    printUpdateAvailableBanner,
+    readInstalledGuardexVersion,
+    restartIntoUpdatedGuardex,
+    checkForOpenSpecPackageUpdate,
+    printOpenSpecUpdateAvailableBanner,
+    resolveGlobalInstallApproval,
+    detectGlobalToolchainPackages,
+    detectOptionalLocalCompanionTools,
+    formatGlobalToolchainServiceName,
+    askGlobalInstallForMissing,
+  } = deps;
+
+  function maybeSelfUpdateBeforeStatus() {
+    const check = checkForGuardexUpdate();
+    if (!check.checked || !check.updateAvailable) {
+      return;
+    }
+
+    printUpdateAvailableBanner(check.current, check.latest);
+
+    const autoApproval = parseAutoApproval('GUARDEX_AUTO_UPDATE_APPROVAL');
+    const interactive = isInteractiveTerminal();
+
+    if (!interactive && autoApproval == null) {
+      console.log(`[${TOOL_NAME}] Non-interactive shell; skipping auto-update prompt.`);
+      return;
+    }
+
+    const shouldUpdate = interactive
+      ? promptYesNoStrict(
+        `Update now? (${NPM_BIN} i -g ${packageJson.name}@latest)`,
+      )
+      : autoApproval;
+
+    if (!shouldUpdate) {
+      console.log(`[${TOOL_NAME}] Skipped update.`);
+      return;
+    }
+
+    const installResult = run(NPM_BIN, ['i', '-g', `${packageJson.name}@latest`], { stdio: 'inherit' });
+    if (installResult.status !== 0) {
+      console.log(`[${TOOL_NAME}] ⚠️ Update failed. You can retry manually.`);
+      return;
+    }
+
+    const postInstallVersion = readInstalledGuardexVersion();
+    if (postInstallVersion != null && postInstallVersion !== check.latest) {
+      console.log(
+        `[${TOOL_NAME}] Installed version is still ${postInstallVersion} (expected ${check.latest}). ` +
+          `Retrying with pinned version ${check.latest}…`,
+      );
+      const pinnedResult = run(
+        NPM_BIN,
+        ['i', '-g', `${packageJson.name}@${check.latest}`],
+        { stdio: 'inherit' },
+      );
+      if (pinnedResult.status !== 0) {
+        console.log(
+          `[${TOOL_NAME}] ⚠️ Pinned retry failed. Run manually: ${NPM_BIN} i -g ${packageJson.name}@${check.latest}`,
+        );
+        return;
+      }
+      const pinnedVersion = readInstalledGuardexVersion();
+      if (pinnedVersion != null && pinnedVersion !== check.latest) {
+        console.log(
+          `[${TOOL_NAME}] ⚠️ On-disk version still ${pinnedVersion} after pinned retry. ` +
+            `Investigate: ${NPM_BIN} root -g && ${NPM_BIN} cache verify`,
+        );
+        return;
+      }
+    }
+
+    console.log(`[${TOOL_NAME}] ✅ Updated to latest published version.`);
+    restartIntoUpdatedGuardex(check.latest);
+  }
+
+  function maybeOpenSpecUpdateBeforeStatus() {
+    const check = checkForOpenSpecPackageUpdate();
+    if (!check.checked || !check.updateAvailable) {
+      return;
+    }
+
+    printOpenSpecUpdateAvailableBanner(check.current, check.latest);
+
+    const autoApproval = parseAutoApproval('GUARDEX_AUTO_OPENSPEC_UPDATE_APPROVAL');
+    const interactive = isInteractiveTerminal();
+
+    if (!interactive && autoApproval == null) {
+      console.log(`[${TOOL_NAME}] Non-interactive shell; skipping OpenSpec update prompt.`);
+      return;
+    }
+
+    const shouldUpdate = interactive
+      ? promptYesNoStrict(
+        `Update OpenSpec now? (${NPM_BIN} i -g ${OPENSPEC_PACKAGE}@latest && ${OPENSPEC_BIN} update)`,
+      )
+      : autoApproval;
+
+    if (!shouldUpdate) {
+      console.log(`[${TOOL_NAME}] Skipped OpenSpec update.`);
+      return;
+    }
+
+    const installResult = run(NPM_BIN, ['i', '-g', `${OPENSPEC_PACKAGE}@latest`], { stdio: 'inherit' });
+    if (installResult.status !== 0) {
+      console.log(`[${TOOL_NAME}] ⚠️ OpenSpec npm install failed. You can retry manually.`);
+      return;
+    }
+
+    const toolUpdateResult = run(OPENSPEC_BIN, ['update'], { stdio: 'inherit' });
+    if (toolUpdateResult.status !== 0) {
+      console.log(`[${TOOL_NAME}] ⚠️ OpenSpec tool update failed. Run '${OPENSPEC_BIN} update' manually.`);
+      return;
+    }
+
+    console.log(`[${TOOL_NAME}] ✅ OpenSpec updated to latest package and tool plugins refreshed.`);
+  }
+
+  function installGlobalToolchain(options) {
+    const approval = resolveGlobalInstallApproval(options);
+    if (approval.source === 'flag' && !approval.approved) {
+      return {
+        status: 'skipped',
+        reason: approval.source,
+        missingPackages: [],
+        missingLocalTools: [],
+      };
+    }
+
+    if (options.dryRun) {
+      return { status: 'dry-run-skip' };
+    }
+
+    const detection = detectGlobalToolchainPackages();
+    const localCompanionTools = detectOptionalLocalCompanionTools();
+    if (!detection.ok) {
+      console.log(`[${TOOL_NAME}] ⚠️ Could not detect global packages: ${detection.error}`);
+    } else {
+      if (detection.installed.length > 0) {
+        console.log(
+          `[${TOOL_NAME}] Already installed globally: ` +
+          `${detection.installed.map((pkg) => formatGlobalToolchainServiceName(pkg)).join(', ')}`,
+        );
+      }
+      const installedLocalTools = localCompanionTools
+        .filter((tool) => tool.status === 'active')
+        .map((tool) => tool.name);
+      if (installedLocalTools.length > 0) {
+        console.log(`[${TOOL_NAME}] Already installed locally: ${installedLocalTools.join(', ')}`);
+      }
+      if (detection.missing.length === 0 && localCompanionTools.every((tool) => tool.status === 'active')) {
+        return { status: 'already-installed' };
+      }
+    }
+
+    const missingPackages = detection.ok ? detection.missing : [...GLOBAL_TOOLCHAIN_PACKAGES];
+    const missingLocalTools = localCompanionTools.filter((tool) => tool.status !== 'active');
+    const installApproval = askGlobalInstallForMissing(options, missingPackages, missingLocalTools);
+    if (!installApproval.approved) {
+      return {
+        status: 'skipped',
+        reason: installApproval.source,
+        missingPackages,
+        missingLocalTools,
+      };
+    }
+
+    const installed = [];
+    if (missingPackages.length > 0) {
+      console.log(
+        `[${TOOL_NAME}] Installing global toolchain: npm i -g ${missingPackages.join(' ')}`,
+      );
+      const result = run(NPM_BIN, ['i', '-g', ...missingPackages], { stdio: 'inherit' });
+      if (result.status !== 0) {
+        const stderr = (result.stderr || '').trim();
+        return {
+          status: 'failed',
+          reason: stderr || 'npm global install failed',
+        };
+      }
+      installed.push(...missingPackages);
+    }
+
+    for (const tool of missingLocalTools) {
+      console.log(`[${TOOL_NAME}] Installing local companion tool: ${tool.installCommand}`);
+      const result = run(NPX_BIN, tool.installArgs, { stdio: 'inherit' });
+      if (result.status !== 0) {
+        const stderr = (result.stderr || '').trim();
+        return {
+          status: 'failed',
+          reason: stderr || `${tool.name} install failed`,
+        };
+      }
+      installed.push(tool.name);
+    }
+
+    return { status: 'installed', packages: installed };
+  }
+
+  return {
+    maybeSelfUpdateBeforeStatus,
+    maybeOpenSpecUpdateBeforeStatus,
+    installGlobalToolchain,
+  };
+}
+
+module.exports = {
+  createToolchainApi,
+};

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

@@ -14,6 +14,7 @@ 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}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
@@ -54,8 +55,7 @@ while [[ $# -gt 0 ]]; do
       shift
       ;;
     --tier)
-      # Accepted for CLAUDE.md compatibility; scaffold size is not yet wired
-      # through this script. Consume the value so callers can pass it.
+      OPENSPEC_TIER_RAW="${2:-$OPENSPEC_TIER_RAW}"
       shift 2
       ;;
     --in-place|--allow-in-place)
@@ -246,11 +246,45 @@ normalize_bool() {
 
 OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
 
+normalize_tier() {
+  local raw="${1:-}"
+  local fallback="${2:-T3}"
+  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
+}
+
+if ! OPENSPEC_TIER="$(normalize_tier "$OPENSPEC_TIER_RAW" "T3")"; then
+  echo "[agent-branch-start] Unsupported OpenSpec tier: ${OPENSPEC_TIER_RAW}" >&2
+  exit 1
+fi
+
+OPENSPEC_SKIP_CHANGE=0
+OPENSPEC_SKIP_PLAN=0
+OPENSPEC_MINIMAL=0
+case "$OPENSPEC_TIER" in
+  T0)
+    OPENSPEC_SKIP_CHANGE=1
+    OPENSPEC_SKIP_PLAN=1
+    ;;
+  T1)
+    OPENSPEC_SKIP_PLAN=1
+    OPENSPEC_MINIMAL=1
+    ;;
+  T2)
+    OPENSPEC_SKIP_PLAN=1
+    ;;
+esac
+
 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
@@ -404,7 +438,7 @@ initialize_openspec_plan_workspace() {
   local worktree="$2"
   local plan_slug="$3"
 
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
     return 0
   fi
 
@@ -430,14 +464,15 @@ initialize_openspec_change_workspace() {
   local change_slug="$3"
   local capability_slug="$4"
 
-  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
     return 0
   fi
 
   local init_output=""
   if ! init_output="$(
     cd "$worktree"
-    run_guardex_cli internal run-shell changeInit "$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 "[agent-branch-start] OpenSpec workspace initialization failed for change '${change_slug}'." >&2
@@ -599,8 +634,17 @@ fi
 
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
-echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
-echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
+echo "[agent-branch-start] OpenSpec tier: ${OPENSPEC_TIER}"
+if [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
+  echo "[agent-branch-start] OpenSpec change: skipped by tier ${OPENSPEC_TIER}"
+else
+  echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
+fi
+if [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
+  echo "[agent-branch-start] OpenSpec plan: skipped by tier ${OPENSPEC_TIER}"
+else
+  echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
+fi
 echo "[agent-branch-start] Next steps:"
 echo "  cd \"${worktree_path}\""
 echo "  gx locks claim --branch \"${branch_name}\" <file...>"

package/templates/scripts/codex-agent.sh

@@ -17,6 +17,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:-}"
+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
@@ -48,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")"
@@ -58,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
@@ -86,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
@@ -151,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
@@ -393,7 +519,7 @@ start_sandbox_fallback() {
   printf '[agent-branch-start] Worktree: %s\n' "$worktree_path"
 }
 
-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
@@ -487,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() {
@@ -545,6 +674,7 @@ print_takeover_prompt() {
   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}\`."
 }
 
@@ -594,7 +724,7 @@ 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
 
@@ -619,7 +749,7 @@ 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
 
@@ -628,7 +758,8 @@ ensure_openspec_change_workspace() {
   capability_slug="$(resolve_openspec_capability_slug)"
   if ! init_output="$(
     cd "$wt"
-    run_guardex_cli internal run-shell changeInit "$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
@@ -878,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
@@ -894,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
 

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

@@ -2,21 +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.
-- Splits live sessions inside `ACTIVE AGENTS` into `WORKING NOW` and `THINKING` groups so active edit 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 `thinking` versus `working` from the live sandbox worktree, surfaces working counts in the repo/header summary, 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/`.