@imdeadpool/guardex 7.0.2 → 7.0.4

package/README.md

@@ -373,6 +373,28 @@ npm pack --dry-run
 
 ## Release notes
 
+### v7.0.4
+
+- **Fixed: publish collision on npm.** Advanced the package metadata from `7.0.3` to `7.0.4` so `npm publish` no longer targets an already published version.
+- **Changed: release-note sync for versioning rule.** Added this versioned entry in README in the same change as the package bump to keep publish metadata and release notes aligned.
+
+### 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.2",
+  "version": "7.0.4",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,

package/templates/githooks/pre-commit

@@ -23,6 +23,14 @@ if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}"
   is_codex_session=1
 fi
 
+# Superset of is_codex_session that also covers Claude Code sessions so the
+# protected-branch gate below only triggers for automated agents — humans stay
+# free to commit directly on main/dev/master.
+is_agent_session=$is_codex_session
+if [[ -n "${CLAUDECODE:-}" || -n "${CLAUDE_CODE_SESSION_ID:-}" ]]; then
+  is_agent_session=1
+fi
+
 is_vscode_git_context=0
 if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n "${VSCODE_IPC_HOOK_CLI:-}" ]]; then
   is_vscode_git_context=1
@@ -124,10 +132,10 @@ MSG
 fi
 
 if [[ "$is_protected_branch" == "1" ]]; then
-  if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" ]]; then
-    if [[ "$allow_vscode_protected_branch_writes" == "1" ]]; then
-      exit 0
-    fi
+  # Humans may commit directly on protected branches; only agent sessions
+  # (Codex / Claude Code / OMX) are blocked.
+  if [[ "$is_agent_session" != "1" ]]; then
+    exit 0
   fi
 
   if [[ "$is_unborn_branch" == "1" && "$is_codex_session" != "1" ]]; then
@@ -146,16 +154,13 @@ Use an agent branch first:
 After finishing work:
   bash scripts/agent-branch-finish.sh
 
-Optional repo opt-in for VS Code protected-branch commits:
-  git config multiagent.allowVscodeProtectedBranchWrites true
-
 Temporary bypass (not recommended):
   ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
 MSG
   exit 1
 fi
 
-if [[ "$is_agent_context" == "1" && "$branch" != agent/* ]]; then
+if [[ "$is_agent_session" == "1" && "$branch" != agent/* ]]; then
   cat >&2 <<'MSG'
 [agent-branch-guard] Agent commits must run on dedicated agent/* branches.
 Start an agent branch first:

package/templates/githooks/pre-push

@@ -28,6 +28,13 @@ if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}"
   is_codex_session=1
 fi
 
+# Superset covering Claude Code so only agents are blocked from pushing to
+# protected refs; humans push directly from their primary checkout.
+is_agent_session=$is_codex_session
+if [[ -n "${CLAUDECODE:-}" || -n "${CLAUDE_CODE_SESSION_ID:-}" ]]; then
+  is_agent_session=1
+fi
+
 protected_branches_raw="${GUARDEX_PROTECTED_BRANCHES:-$(git config --get multiagent.protectedBranches || true)}"
 if [[ -z "$protected_branches_raw" ]]; then
   protected_branches_raw="dev main master"
@@ -69,6 +76,11 @@ if [[ "${#blocked_refs[@]}" -gt 0 ]]; then
     exit 1
   fi
 
+  # Humans may push directly to protected branches; only agent sessions are blocked.
+  if [[ "$is_agent_session" != "1" ]]; then
+    exit 0
+  fi
+
   if [[ "$is_vscode_git_context" == "1" && "$allow_vscode_protected_branch_writes" == "1" ]]; then
     exit 0
   fi

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}"