@imdeadpool/guardex 7.0.41 → 7.1.0

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

@@ -9,13 +9,19 @@ WORKTREE_ROOT_REL=""
 WORKTREE_ROOT_EXPLICIT=0
 NODE_BIN="${GUARDEX_NODE_BIN:-node}"
 CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
-OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
+OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-true}"
 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/**:.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=()
 
@@ -36,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
@@ -67,6 +105,18 @@ while [[ $# -gt 0 ]]; do
       REUSE_EXISTING_RAW="false"
       shift
       ;;
+    --no-transfer)
+      AUTO_TRANSFER_ENABLED_RAW="false"
+      shift
+      ;;
+    --transfer)
+      AUTO_TRANSFER_ENABLED_RAW="true"
+      shift
+      ;;
+    --transfer-exclude)
+      AUTO_TRANSFER_EXCLUDE_RAW="${2:-}"
+      shift 2
+      ;;
     --in-place|--allow-in-place)
       echo "[agent-branch-start] In-place branch mode is disabled." >&2
       echo "[agent-branch-start] This command always creates an isolated worktree to keep your active checkout unchanged." >&2
@@ -277,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
@@ -389,11 +439,41 @@ print_reused_agent_worktree() {
   echo "[agent-branch-start] OpenSpec tier: ${OPENSPEC_TIER}"
   echo "[agent-branch-start] OpenSpec change: existing worktree"
   echo "[agent-branch-start] OpenSpec plan: existing worktree"
-  echo "[agent-branch-start] Next steps:"
-  echo "  cd \"${worktree_path}\""
-  echo "  gx locks claim --branch \"${branch_name}\" <file...>"
-  echo "  # continue work in this existing sandbox"
-  echo "  gx branch finish --branch \"${branch_name}\" --via-pr --wait-for-merge"
+  print_agent_next_steps "$branch_name" "$worktree_path" "continue work in this existing sandbox" "$BASE_BRANCH"
+}
+
+print_agent_next_steps() {
+  local branch_name="$1"
+  local worktree_path="$2"
+  local work_step="$3"
+  local base_branch="${4:-main}"
+
+  if [[ -z "$base_branch" ]]; then
+    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}"
+  echo "  next:"
+  echo "    cd \"${worktree_path}\""
+  echo "    gx locks claim --branch \"${branch_name}\" <file...>"
+  echo "    # ${work_step}"
+  echo "    gx branch finish --branch \"${branch_name}\" --base ${base_branch} --via-pr --wait-for-merge --cleanup"
 }
 
 has_local_changes() {
@@ -419,7 +499,7 @@ meaningful_slug_tokens() {
     | awk '
       length($0) < 4 { next }
       $0 ~ /^[0-9]+$/ { next }
-      $0 ~ /^(agent|agents|branch|codex|claude|continue|dirty|existing|fix|from|implement|make|matching|reuse|start|task|that|this|update|with|worktree|worktrees)$/ { next }
+      $0 ~ /^(agent|agents|branch|codex|claude|continue|dirty|existing|fix|from|implement|make|matching|openspec|reuse|start|task|that|this|update|with|worktree|worktrees)$/ { next }
       !seen[$0]++ { print }
     '
 }
@@ -463,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"
@@ -483,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")"
@@ -774,18 +880,54 @@ restore_auto_transfer_stash_on_failure() {
 
 trap 'restore_auto_transfer_stash_on_failure "$?"' EXIT
 
+auto_transfer_enabled_lc="$(printf '%s' "$AUTO_TRANSFER_ENABLED_RAW" | tr '[:upper:]' '[:lower:]')"
+case "$auto_transfer_enabled_lc" in
+  0|false|no|off) AUTO_TRANSFER_ENABLED=0 ;;
+  *) AUTO_TRANSFER_ENABLED=1 ;;
+esac
+
+build_auto_transfer_stash_argv() {
+  # Emit NUL-separated argv: --include-untracked --message <msg> [-- :/ :(exclude,glob)PAT ...]
+  local msg="$1"
+  printf '%s\0' --include-untracked --message "$msg"
+  if [[ -z "${AUTO_TRANSFER_EXCLUDE_RAW:-}" ]]; then
+    return 0
+  fi
+  printf '%s\0' '--' ':/'
+  local -a patterns=()
+  IFS=':' read -ra patterns <<< "$AUTO_TRANSFER_EXCLUDE_RAW"
+  local pattern
+  for pattern in "${patterns[@]}"; do
+    [[ -z "$pattern" ]] && continue
+    printf '%s\0' ":(exclude,glob)${pattern}"
+  done
+}
+
 current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
 protected_branches_raw="$(resolve_protected_branches "$repo_root")"
 if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_branch_name "$current_branch" "$protected_branches_raw"; then
   if has_local_changes "$repo_root"; then
-    auto_transfer_message="guardex-auto-transfer-${timestamp}-${agent_slug}-${task_slug}"
-    if git -C "$repo_root" stash push --include-untracked --message "$auto_transfer_message" >/dev/null 2>&1; then
-      auto_transfer_stash_ref="$(resolve_stash_ref_by_message "$repo_root" "$auto_transfer_message")"
-      if [[ -n "$auto_transfer_stash_ref" ]]; then
-        auto_transfer_source_branch="$current_branch"
-        echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'. Moving them to '${branch_name}'..."
-        if ! maybe_fail_after_auto_transfer_stash; then
-          exit 1
+    if [[ "$AUTO_TRANSFER_ENABLED" -eq 0 ]]; then
+      echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'; --no-transfer set, leaving them in place." >&2
+      echo "[agent-branch-start] If you intended those changes for '${branch_name}', stash them manually and apply inside the worktree." >&2
+    else
+      auto_transfer_message="guardex-auto-transfer-${timestamp}-${agent_slug}-${task_slug}"
+      stash_argv=()
+      while IFS= read -r -d '' arg; do
+        stash_argv+=("$arg")
+      done < <(build_auto_transfer_stash_argv "$auto_transfer_message")
+      if git -C "$repo_root" stash push "${stash_argv[@]}" >/dev/null 2>&1; then
+        auto_transfer_stash_ref="$(resolve_stash_ref_by_message "$repo_root" "$auto_transfer_message")"
+        if [[ -n "$auto_transfer_stash_ref" ]]; then
+          auto_transfer_source_branch="$current_branch"
+          echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'. Moving them to '${branch_name}' (state-file globs excluded)..."
+          if ! maybe_fail_after_auto_transfer_stash; then
+            exit 1
+          fi
+        else
+          if has_local_changes "$repo_root"; then
+            echo "[agent-branch-start] Local changes on '${current_branch}' all match the auto-transfer exclude list; leaving them in place on '${current_branch}'." >&2
+          fi
         fi
       fi
     fi
@@ -797,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.
@@ -832,18 +981,21 @@ 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_SKIP_CHANGE" -eq 1 ]]; then
+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
   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
+if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  echo "[agent-branch-start] OpenSpec plan: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)"
+elif [[ "$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...>"
-echo "  # implement + commit"
-echo "  gx branch finish --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge"
+print_agent_next_steps "$branch_name" "$worktree_path" "implement + commit" "$BASE_BRANCH"

package/templates/scripts/agent-preflight.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Pre-flight verification gate for gitguardex-managed projects.
+#
+# Runs in the agent's worktree from `gx branch finish` BEFORE the push
+# happens. Returns non-zero to refuse the push so a broken commit
+# never reaches the PR / CI / merge funnel.
+#
+# Auto-detects the project's stack and runs conventional verification:
+#   - Node/pnpm:   pnpm typecheck && pnpm lint && pnpm test (each only
+#                  if the script exists in package.json)
+#   - Node/npm:    npm test (only if defined)
+#   - Rust:        cargo check
+#   - Python:      ruff check (only if ruff is installed)
+#
+# Override per-project by replacing this file (delete the symlink under
+# scripts/agent-preflight.sh and write your own).
+#
+# Skip a single run with `gx branch finish --no-preflight`.
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$repo_root"
+
+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"
+  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 ($(printf '%s\n' "$out" | wc -l | tr -d ' ') lines suppressed; GUARDEX_PREFLIGHT_VERBOSE=1 to show)"
+  else
+    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
+}
+
+has_package_script() {
+  local script_name="$1"
+  [[ -f package.json ]] || return 1
+  grep -E "\"${script_name}\"\\s*:" package.json >/dev/null 2>&1
+}
+
+# Node detection
+if [[ -f package.json ]]; then
+  pkg_manager=""
+  if command -v pnpm >/dev/null 2>&1 && [[ -f pnpm-lock.yaml ]]; then
+    pkg_manager="pnpm"
+  elif command -v npm >/dev/null 2>&1 && [[ -f package-lock.json ]]; then
+    pkg_manager="npm"
+  fi
+
+  case "$pkg_manager" in
+    pnpm)
+      has_package_script typecheck && run_step "pnpm typecheck" pnpm typecheck
+      has_package_script lint && run_step "pnpm lint" pnpm lint
+      has_package_script test && run_step "pnpm test" pnpm test
+      ;;
+    npm)
+      has_package_script test && run_step "npm test" npm test
+      ;;
+  esac
+fi
+
+# Rust detection
+if [[ -f Cargo.toml ]] && command -v cargo >/dev/null 2>&1; then
+  run_step "cargo check" cargo check --quiet
+fi
+
+# Python detection (ruff if available; pytest is too project-specific to default)
+if [[ -f pyproject.toml ]] && command -v ruff >/dev/null 2>&1; then
+  run_step "ruff check" ruff check .
+fi
+
+if [[ "$attempted" -eq 0 ]]; then
+  echo "[agent-preflight] No recognized project stack detected; skipping checks." >&2
+  exit 0
+fi
+
+if [[ "$fail" -ne 0 ]]; then
+  echo "[agent-preflight] Verification failed; refusing push." >&2
+  echo "[agent-preflight] Fix the issues, or re-run with: gx branch finish --no-preflight ..." >&2
+  exit 1
+fi
+
+echo "[agent-preflight] ${ran} step(s) passed."
+exit 0

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

@@ -82,7 +82,12 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
 fi
 
 repo_root="$(git rev-parse --show-toplevel)"
-current_pwd="$(pwd -P)"
+current_pwd="${GUARDEX_PRUNE_ACTIVE_CWD:-$(pwd -P)}"
+if [[ -d "$current_pwd" ]]; then
+  current_pwd="$(cd "$current_pwd" && pwd -P)"
+else
+  current_pwd=""
+fi
 repo_common_dir="$(
   git -C "$repo_root" rev-parse --git-common-dir \
     | awk -v root="$repo_root" '{ if ($0 ~ /^\//) { print $0 } else { print root "/" $0 } }'
@@ -244,11 +249,71 @@ branch_has_worktree() {
   git -C "$repo_root" worktree list --porcelain | grep -q "^branch refs/heads/${branch}$"
 }
 
+# Globs treated as agent state, not real work. Worktrees whose only "dirty"
+# 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/**:.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() {
+  # Emit one ':(exclude,glob)<pat>' arg per non-empty pattern.
+  if [[ -z "$WORKTREE_STATE_EXCLUDE_GLOBS_RAW" ]]; then
+    return 0
+  fi
+  local -a globs=()
+  IFS=':' read -ra globs <<< "$WORKTREE_STATE_EXCLUDE_GLOBS_RAW"
+  local pattern
+  for pattern in "${globs[@]}"; do
+    [[ -z "$pattern" ]] && continue
+    printf '%s\0' ":(exclude,glob)${pattern}"
+  done
+}
+
+# Capture the state-exclude pathspecs once; reused by is_clean_worktree and
+# the dirt-summary logger below.
+STATE_EXCLUDE_PATHSPEC_ARGS=()
+while IFS= read -r -d '' arg; do
+  STATE_EXCLUDE_PATHSPEC_ARGS+=("$arg")
+done < <(build_state_exclude_pathspec_args)
+
 is_clean_worktree() {
   local wt="$1"
-  git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
-    && git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
-    && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard)" ]]
+  git -C "$wt" diff --quiet -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" \
+    && git -C "$wt" diff --cached --quiet -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" \
+    && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}")" ]]
+}
+
+# Returns a short, human-readable summary of why a worktree is considered dirty:
+# up to 3 modified-tracked paths + up to 3 untracked paths + a "(+N more)" tail.
+# Used to surface actionable context next to "Skipping dirty worktree" log lines
+# (previously gave no clue what was actually dirty).
+summarize_worktree_dirt() {
+  local wt="$1"
+  local modified_paths untracked_paths
+  modified_paths="$(git -C "$wt" diff --name-only --diff-filter=AMDR -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" 2>/dev/null | head -3)"
+  local modified_count
+  modified_count="$(git -C "$wt" diff --name-only --diff-filter=AMDR -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" 2>/dev/null | wc -l | tr -d ' ')"
+  untracked_paths="$(git -C "$wt" ls-files --others --exclude-standard -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" 2>/dev/null | head -3)"
+  local untracked_count
+  untracked_count="$(git -C "$wt" ls-files --others --exclude-standard -- . "${STATE_EXCLUDE_PATHSPEC_ARGS[@]}" 2>/dev/null | wc -l | tr -d ' ')"
+
+  if [[ -n "$modified_paths" ]]; then
+    while IFS= read -r p; do
+      [[ -n "$p" ]] && echo "    modified: ${p}"
+    done <<< "$modified_paths"
+    if [[ "$modified_count" -gt 3 ]]; then
+      echo "    modified: (+$((modified_count - 3)) more)"
+    fi
+  fi
+  if [[ -n "$untracked_paths" ]]; then
+    while IFS= read -r p; do
+      [[ -n "$p" ]] && echo "    untracked: ${p}"
+    done <<< "$untracked_paths"
+    if [[ "$untracked_count" -gt 3 ]]; then
+      echo "    untracked: (+$((untracked_count - 3)) more)"
+    fi
+  fi
 }
 
 resolve_worktree_common_dir() {
@@ -317,6 +382,26 @@ read_branch_activity_epoch() {
 
 skipped_recent=0
 
+has_live_process_in_worktree() {
+  local wt="$1"
+  local proc_cwd=""
+
+  [[ -d /proc ]] || return 1
+
+  for proc_cwd in /proc/[0-9]*/cwd; do
+    [[ -e "$proc_cwd" ]] || continue
+    local live_cwd=""
+    live_cwd="$(readlink "$proc_cwd" 2>/dev/null || true)"
+    [[ -n "$live_cwd" ]] || continue
+    live_cwd="${live_cwd% (deleted)}"
+    if [[ "$live_cwd" == "$wt" || "$live_cwd" == "${wt}"/* ]]; then
+      return 0
+    fi
+  done
+
+  return 1
+}
+
 branch_idle_gate() {
   local branch="$1"
   local wt="$2"
@@ -431,11 +516,16 @@ process_entry() {
     return
   fi
 
-  if [[ "$wt" == "$current_pwd" ]]; then
+  if [[ -n "$current_pwd" && ( "$wt" == "$current_pwd" || "$current_pwd" == "${wt}"/* ) ]]; then
     skipped_active=$((skipped_active + 1))
     echo "[agent-worktree-prune] Skipping active cwd worktree: ${wt}"
     return
   fi
+  if has_live_process_in_worktree "$wt"; then
+    skipped_active=$((skipped_active + 1))
+    echo "[agent-worktree-prune] Skipping live process worktree: ${wt}"
+    return
+  fi
 
   local remove_reason=""
   local branch_delete_mode="safe"
@@ -477,6 +567,7 @@ process_entry() {
   if [[ "$FORCE_DIRTY" -ne 1 ]] && ! is_clean_worktree "$wt"; then
     skipped_dirty=$((skipped_dirty + 1))
     echo "[agent-worktree-prune] Skipping dirty worktree (${remove_reason}): ${wt}"
+    summarize_worktree_dirt "$wt"
     return
   fi