@imdeadpool/guardex 7.0.1 → 7.0.3

package/README.md

@@ -373,6 +373,23 @@ npm pack --dry-run
 
 ## Release notes
 
+### v7.0.3
+
+- **Branch/worktree naming refactor.** `agent-branch-start.sh` now produces `agent/<role>/<task>-<YYYY-MM-DD>-<HH-MM>` instead of `agent/<role+account-email>/<snapshot-slug>-<task>-<cksum6>`. Codex account names (e.g. `Zeus Edix Hu`) and 6-hex checksums no longer leak into branch or worktree paths.
+- **Role normalization.** `AGENT_NAME` is collapsed to `{claude, codex, <explicit>}` via (in order) the `GUARDEX_AGENT_TYPE` env override, a substring match against `claude`/`codex`, the `CLAUDECODE=1` sentinel, or a fallback to `codex`. Other roles (`integrator`, `executor`, etc.) pass through when set via `GUARDEX_AGENT_TYPE`.
+- **New `--print-name-only` flag** on `agent-branch-start.sh` for deterministic tests; honours `GUARDEX_BRANCH_TIMESTAMP` for reproducible output.
+- **`--tier` flag accepted silently** for CLAUDE.md compatibility (scaffold sizing not wired through yet).
+- Tests `install.test.js` covering the old snapshot-slug format were rewritten to assert the new role-datetime shape.
+
+### v7.0.2
+
+- **Fix: `__source-probe-*` worktree leak on conflict exit.** `agent-branch-finish.sh` was registering its `cleanup()` trap *after* the sync-guard rebase block, so when that rebase hit conflicts and the script exited, the throwaway probe worktree was never removed. `gx doctor` sweeps against stalled branches accumulated one new probe per run.
+- The cleanup trap is now installed immediately after probe creation, and aborts any in-progress `rebase`/`merge` before `worktree remove --force` so conflict-stuck probes are cleaned up reliably.
+
+### v7.0.1
+
+- Maintenance release.
+
 ### v7.0.0
 
 - **Breaking (soft).** Consolidated 17 commands into 12 visible commands with flag-based subcommands. Five removed names (`init`, `install`, `fix`, `scan`, `copy-prompt`, `copy-commands`, `print-agents-snippet`, `review`) still work but print a one-line deprecation notice on stderr and will be removed in v8. See the migration table in "Copy-paste: common commands" above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.1",
+  "version": "7.0.3",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,

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

@@ -194,6 +194,20 @@ is_clean_worktree() {
 source_worktree="$(get_worktree_for_branch "$SOURCE_BRANCH")"
 created_source_probe=0
 source_probe_path=""
+integration_worktree=""
+
+cleanup() {
+  if [[ -n "$integration_worktree" && -d "$integration_worktree" ]]; then
+    git -C "$repo_root" worktree remove "$integration_worktree" --force >/dev/null 2>&1 || true
+  fi
+  if [[ "$created_source_probe" -eq 1 && -n "$source_probe_path" && -d "$source_probe_path" ]]; then
+    # Abort any in-progress git op so `worktree remove --force` succeeds on conflict-stuck probes.
+    git -C "$source_probe_path" rebase --abort >/dev/null 2>&1 || true
+    git -C "$source_probe_path" merge --abort >/dev/null 2>&1 || true
+    git -C "$repo_root" worktree remove "$source_probe_path" --force >/dev/null 2>&1 || true
+  fi
+}
+trap cleanup EXIT
 
 if [[ -z "$source_worktree" ]]; then
   source_probe_path="${agent_worktree_root}/__source-probe-${SOURCE_BRANCH//\//__}-$(date +%Y%m%d-%H%M%S)"
@@ -261,16 +275,6 @@ mkdir -p "$(dirname "$integration_worktree")"
 git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
 git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
 
-cleanup() {
-  if [[ -d "$integration_worktree" ]]; then
-    git -C "$repo_root" worktree remove "$integration_worktree" --force >/dev/null 2>&1 || true
-  fi
-  if [[ "$created_source_probe" -eq 1 && -n "$source_probe_path" && -d "$source_probe_path" ]]; then
-    git -C "$repo_root" worktree remove "$source_probe_path" --force >/dev/null 2>&1 || true
-  fi
-}
-trap cleanup EXIT
-
 if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
   git -C "$source_worktree" fetch origin "$BASE_BRANCH" --quiet
 

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

@@ -10,6 +10,7 @@ OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
+PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
 while [[ $# -gt 0 ]]; do
@@ -27,6 +28,15 @@ while [[ $# -gt 0 ]]; do
       BASE_BRANCH_EXPLICIT=1
       shift 2
       ;;
+    --print-name-only)
+      PRINT_NAME_ONLY=1
+      shift
+      ;;
+    --tier)
+      # Accepted for CLAUDE.md compatibility; scaffold size is not yet wired
+      # through this script. Consume the value so callers can pass it.
+      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
@@ -46,7 +56,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     -*)
       echo "[agent-branch-start] Unknown option: $1" >&2
-      echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>]" >&2
+      echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>] [--print-name-only]" >&2
       exit 1
       ;;
     *)
@@ -86,16 +96,6 @@ sanitize_slug() {
   printf '%s' "$slug"
 }
 
-sanitize_optional_slug() {
-  local raw="$1"
-  local fallback="${2:-snapshot}"
-  if [[ -z "$raw" ]]; then
-    printf ''
-    return 0
-  fi
-  sanitize_slug "$raw" "$fallback"
-}
-
 normalize_positive_int() {
   local raw="$1"
   local fallback="$2"
@@ -123,29 +123,58 @@ shorten_slug() {
   printf '%s' "$shortened"
 }
 
-checksum_slug_suffix() {
-  local raw="$1"
-  local checksum
-  checksum="$(printf '%s' "$raw" | cksum | awk '{print $1}')"
-  printf '%s' "${checksum:0:6}"
+# Collapse arbitrary agent identifiers to a clean role token: claude | codex |
+# <other-kebab>. Priority: GUARDEX_AGENT_TYPE env override, then the raw
+# AGENT_NAME (if it contains 'claude' or 'codex'), then CLAUDECODE=1 sentinel
+# (set by Claude Code CLI), else fall back to 'codex'. Any other role name
+# (integrator, executor, rust-port, etc.) is preserved as-is after slug
+# sanitization.
+normalize_role() {
+  local raw_agent="$1"
+  local override="${GUARDEX_AGENT_TYPE:-}"
+  if [[ -n "$override" ]]; then
+    sanitize_slug "$override" "agent"
+    return 0
+  fi
+  local lowered
+  lowered="$(printf '%s' "$raw_agent" | tr '[:upper:]' '[:lower:]')"
+  if [[ "$lowered" == *claude* ]]; then
+    printf 'claude'
+    return 0
+  fi
+  if [[ "$lowered" == *codex* ]]; then
+    printf 'codex'
+    return 0
+  fi
+  if [[ -n "${CLAUDECODE:-}" && "${CLAUDECODE}" != "0" && "${CLAUDECODE}" != "false" ]]; then
+    printf 'claude'
+    return 0
+  fi
+  # Unrecognized raw name (rust-port-lead, some-worker, empty, ...): default to
+  # codex. To get a different role (integrator, executor, ...) pass the role
+  # explicitly via GUARDEX_AGENT_TYPE, handled above.
+  printf 'codex'
 }
 
-compose_branch_descriptor() {
-  local snapshot_slug="$1"
-  local task_slug="$2"
-  local snapshot_max task_max task_part snapshot_part checksum_input checksum_part
-  snapshot_max="$(normalize_positive_int "${GUARDEX_BRANCH_SNAPSHOT_SLUG_MAX:-18}" "18")"
-  task_max="$(normalize_positive_int "${GUARDEX_BRANCH_TASK_SLUG_MAX:-36}" "36")"
-  task_part="$(shorten_slug "$task_slug" "$task_max")"
-  if [[ -n "$snapshot_slug" ]]; then
-    snapshot_part="$(shorten_slug "$snapshot_slug" "$snapshot_max")"
-    checksum_input="${snapshot_slug}--${task_slug}"
-    checksum_part="$(checksum_slug_suffix "$checksum_input")"
-    printf '%s-%s-%s' "$snapshot_part" "$task_part" "$checksum_part"
+# Timestamp the branch/worktree/openspec slug so parallel agents never collide
+# and names sort chronologically. Format: YYYY-MM-DD-HH-MM (local time).
+# Colons are illegal in git refs, so the HH:MM the user sees is stored as
+# HH-MM in the slug. Can be overridden for tests via GUARDEX_BRANCH_TIMESTAMP.
+compose_branch_timestamp() {
+  if [[ -n "${GUARDEX_BRANCH_TIMESTAMP:-}" ]]; then
+    printf '%s' "$GUARDEX_BRANCH_TIMESTAMP"
     return 0
   fi
-  checksum_part="$(checksum_slug_suffix "$task_slug")"
-  printf '%s-%s' "$task_part" "$checksum_part"
+  date +%Y-%m-%d-%H-%M
+}
+
+compose_branch_descriptor() {
+  local task_slug="$1"
+  local stamp="$2"
+  local task_max task_part
+  task_max="$(normalize_positive_int "${GUARDEX_BRANCH_TASK_SLUG_MAX:-40}" "40")"
+  task_part="$(shorten_slug "$task_slug" "$task_max")"
+  printf '%s-%s' "$task_part" "$stamp"
 }
 
 normalize_bool() {
@@ -192,24 +221,6 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
-resolve_active_codex_snapshot_name() {
-  local override="${GUARDEX_CODEX_AUTH_SNAPSHOT:-}"
-  if [[ -n "$override" ]]; then
-    printf '%s' "$override"
-    return 0
-  fi
-
-  local codex_auth_bin="${GUARDEX_CODEX_AUTH_BIN:-codex-auth}"
-  if ! command -v "$codex_auth_bin" >/dev/null 2>&1; then
-    return 0
-  fi
-
-  "$codex_auth_bin" list 2>/dev/null \
-    | sed -n 's/^[[:space:]]*\*[[:space:]]\+//p' \
-    | head -n 1 \
-    | tr -d '\r' || true
-}
-
 has_local_changes() {
   local root="$1"
   if ! git -C "$root" diff --quiet; then
@@ -383,6 +394,18 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   exit 1
 fi
 
+task_slug="$(sanitize_slug "$TASK_NAME" "task")"
+agent_slug="$(normalize_role "$AGENT_NAME")"
+branch_timestamp="$(compose_branch_timestamp)"
+branch_descriptor="$(compose_branch_descriptor "$task_slug" "$branch_timestamp")"
+branch_name_base="agent/${agent_slug}/${branch_descriptor}"
+
+branch_name="$branch_name_base"
+if [[ "$PRINT_NAME_ONLY" -eq 1 ]]; then
+  printf '%s\n' "$branch_name"
+  exit 0
+fi
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
   current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
   protected_branches_raw="$(resolve_protected_branches "$repo_root")"
@@ -411,16 +434,7 @@ else
   start_ref="${BASE_BRANCH}"
 fi
 
-task_slug="$(sanitize_slug "$TASK_NAME" "task")"
-agent_slug_raw="$(sanitize_slug "$AGENT_NAME" "agent")"
-agent_slug="$(shorten_slug "$agent_slug_raw" "${GUARDEX_BRANCH_AGENT_SLUG_MAX:-24}")"
-snapshot_name="$(resolve_active_codex_snapshot_name)"
-snapshot_slug="$(sanitize_optional_slug "$snapshot_name" "snapshot")"
-branch_descriptor="$(compose_branch_descriptor "$snapshot_slug" "$task_slug")"
 timestamp="$(date +%Y%m%d-%H%M%S)"
-branch_name_base="agent/${agent_slug}/${branch_descriptor}"
-
-branch_name="$branch_name_base"
 branch_suffix=2
 while git show-ref --verify --quiet "refs/heads/${branch_name}"; do
   branch_name="${branch_name_base}-${branch_suffix}"