@imdeadpool/guardex 7.0.16 → 7.0.19

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.16",
-  "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
+  "version": "7.0.19",
+  "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,
   "bin": {

package/templates/AGENTS.multiagent-safety.md

@@ -7,22 +7,25 @@
 `GUARDEX_ON=0` disables Guardex for that repo.
 `GUARDEX_ON=1` explicitly enables Guardex for that repo again.
 
-**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `scripts/agent-branch-start.sh "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
+**Task-size routing.** Small tasks stay in direct caveman-only mode. For typos, single-file tweaks, one-liners, version bumps, or similarly bounded asks, solve directly and do not escalate into heavy OMX orchestration just because a keyword appears. Treat `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches.
+Promote to OMX orchestration only when the task is medium/large: multi-file behavior changes, API/schema work, refactors, migrations, architecture, cross-cutting scope, or long prompts. Heavy OMX modes (`ralph`, `autopilot`, `team`, `ultrawork`, `swarm`, `ralplan`) are for that larger scope. If the task grows while working, upgrade then.
+
+**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope.
 Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 
-**Ownership.** Before editing, claim files: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
+**Ownership.** Before editing, claim files: `gx locks claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
 
 **Handoff gate.** Post a one-line handoff note (plan/change, owned scope, intended action) before editing. Re-read the latest handoffs before replacing others' code.
 
-**Completion.** Finish with `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`). Task is only complete when: commit pushed, PR URL recorded, state = `MERGED`, sandbox worktree pruned. If anything blocks, append a `BLOCKED:` note and stop - don't half-finish.
+**Completion.** Finish with `gx branch finish --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`). Task is only complete when: commit pushed, PR URL recorded, state = `MERGED`, sandbox worktree pruned. If anything blocks, append a `BLOCKED:` note and stop - don't half-finish.
 OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete.
 
 **Parallel safety.** Assume other agents edit nearby. Never revert unrelated changes. Report conflicts in the handoff.
 
 **Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
 
-**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `scripts/agent-branch-finish.sh ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
+**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
 <!-- multiagent-safety:END -->

package/templates/codex/skills/gitguardex/SKILL.md

@@ -8,4 +8,4 @@ Use when repo safety may be broken.
 `gx status` -> `gx doctor` -> `gx status --strict`
 
 Bootstrap: `gx setup`
-Ops: `bash scripts/codex-agent.sh "<task>" "<agent>"`, `gx finish --all`, `gx cleanup`
+Ops: `gx branch start "<task>" "<agent>"`, `gx locks claim --branch "<agent-branch>" <file...>`, `gx branch finish --branch "<agent-branch>" --base <base> --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup`

package/templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md

@@ -24,7 +24,7 @@ echo "$BASE_BRANCH"
 2. Start a dedicated integration sandbox from base:
 
 ```sh
-bash scripts/agent-branch-start.sh "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANCH"
+gx branch start "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANCH"
 ```
 
 3. Enter the sandbox worktree printed by the command above.
@@ -48,11 +48,11 @@ git diff --name-only
 ```sh
 git add .codex/skills templates/codex/skills
 git commit -m "Merge skill file updates into ${BASE_BRANCH}"
-bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup
+gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup
 ```
 
 ## Notes
 
 - If a source branch has non-skill changes, this runbook keeps them out of the merge.
-- If merge conflicts occur, resolve only within the skill files, then rerun `agent-branch-finish.sh`.
+- If merge conflicts occur, resolve only within the skill files, then rerun `gx branch finish`.
 - Do not commit directly on `dev`/`main`; always merge through an agent branch/worktree.

package/templates/githooks/post-checkout

@@ -64,7 +64,7 @@ echo "[agent-primary-branch-guard] Primary checkout switched branches." >&2
 echo "[agent-primary-branch-guard]   from: $prev_branch (protected)" >&2
 echo "[agent-primary-branch-guard]   to:   $new_branch" >&2
 echo "[agent-primary-branch-guard] The primary working tree must stay on its base/protected branch." >&2
-echo "[agent-primary-branch-guard] Use 'git worktree add' (or scripts/agent-branch-start.sh) for feature work." >&2
+echo "[agent-primary-branch-guard] Use 'git worktree add' (or gx branch start) for feature work." >&2
 
 if [[ "$is_agent" == "1" ]]; then
   echo "[agent-primary-branch-guard] Agent session detected — reverting to '$prev_branch'." >&2

package/templates/githooks/post-merge

@@ -32,17 +32,30 @@ if [[ "$branch" != "$base_branch" ]]; then
   exit 0
 fi
 
-cli_path="$repo_root/bin/multiagent-safety.js"
-if [[ ! -f "$cli_path" ]]; then
+if [[ -n "${GUARDEX_CLI_ENTRY:-}" ]]; then
+  node_bin="${GUARDEX_NODE_BIN:-node}"
+  if command -v "$node_bin" >/dev/null 2>&1; then
+    "$node_bin" "$GUARDEX_CLI_ENTRY" cleanup \
+      --target "$repo_root" \
+      --base "$base_branch" \
+      --include-pr-merged \
+      --keep-clean-worktrees >/dev/null 2>&1 || true
+  fi
   exit 0
 fi
 
-node_bin="${GUARDEX_NODE_BIN:-node}"
-if ! command -v "$node_bin" >/dev/null 2>&1; then
-  exit 0
+cli_bin="${GUARDEX_CLI_BIN:-}"
+if [[ -z "$cli_bin" ]]; then
+  if command -v gx >/dev/null 2>&1; then
+    cli_bin="gx"
+  elif command -v gitguardex >/dev/null 2>&1; then
+    cli_bin="gitguardex"
+  else
+    exit 0
+  fi
 fi
 
-"$node_bin" "$cli_path" cleanup \
+"$cli_bin" cleanup \
   --target "$repo_root" \
   --base "$base_branch" \
   --include-pr-merged \

package/templates/githooks/pre-commit

@@ -13,6 +13,8 @@ repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 if [[ -z "$repo_root" ]]; then
   exit 0
 fi
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
 if [[ -f "$guardex_env_helper" ]]; then
   # shellcheck source=/dev/null
@@ -22,6 +24,23 @@ if declare -F guardex_repo_is_enabled >/dev/null 2>&1 && ! guardex_repo_is_enabl
   exit 0
 fi
 
+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 "[agent-branch-guard] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 if [[ "${ALLOW_COMMIT_ON_PROTECTED_BRANCH:-0}" == "1" ]]; then
   exit 0
 fi
@@ -116,11 +135,11 @@ if [[ "$should_require_codex_agent_branch" == "1" && "${GUARDEX_ALLOW_CODEX_ON_N
 
       cat >&2 <<'MSG'
 [guardex-preedit-guard] Codex edit/commit detected on a protected branch.
-GuardeX requires Codex work to run from an isolated agent/* branch.
+GitGuardex requires Codex work to run from an isolated agent/* branch.
 Start the sub-branch/worktree with:
-  bash scripts/codex-agent.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Or manually:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit from the created agent/* branch.
 
 Temporary bypass (not recommended):
@@ -132,7 +151,7 @@ MSG
     cat >&2 <<'MSG'
 [codex-branch-guard] Codex agent commit blocked on non-agent branch.
 Use isolated branch/worktree first:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit from the created agent/* branch.
 
 Temporary bypass (not recommended):
@@ -163,9 +182,9 @@ if [[ "$is_protected_branch" == "1" ]]; then
   cat >&2 <<'MSG'
 [agent-branch-guard] Direct commits on protected branches are blocked.
 Use an agent branch first:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 After finishing work:
-  bash scripts/agent-branch-finish.sh
+  gx branch finish
 
 Temporary bypass (not recommended):
   ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
@@ -177,7 +196,7 @@ 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:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit on that branch.
 
 Temporary bypass (not recommended):
@@ -191,15 +210,15 @@ if [[ "$branch" == agent/* ]]; then
     while IFS= read -r staged_file; do
       [[ -z "$staged_file" ]] && continue
       [[ "$staged_file" == ".omx/state/agent-file-locks.json" ]] && continue
-      python3 scripts/agent-file-locks.py claim --branch "$branch" "$staged_file" >/dev/null 2>&1 || true
+      run_guardex_cli locks claim --branch "$branch" "$staged_file" >/dev/null 2>&1 || true
     done < <(git diff --cached --name-only --diff-filter=ACMRDTUXB)
   fi
 
-  if ! python3 scripts/agent-file-locks.py validate --branch "$branch" --staged; then
+  if ! run_guardex_cli locks validate --branch "$branch" --staged; then
     cat >&2 <<'MSG'
 [agent-branch-guard] Agent branch commits require file ownership locks.
 Claim files first:
-  python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
+  gx locks claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
 MSG
     exit 1
   fi

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

@@ -9,11 +9,30 @@ DELETE_REMOTE_BRANCH=0
 DELETE_REMOTE_BRANCH_EXPLICIT=0
 MERGE_MODE="auto"
 GH_BIN="${GUARDEX_GH_BIN:-gh}"
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 CLEANUP_AFTER_MERGE_RAW="${GUARDEX_FINISH_CLEANUP:-false}"
 WAIT_FOR_MERGE_RAW="${GUARDEX_FINISH_WAIT_FOR_MERGE:-false}"
 WAIT_TIMEOUT_SECONDS_RAW="${GUARDEX_FINISH_WAIT_TIMEOUT_SECONDS:-1800}"
 WAIT_POLL_SECONDS_RAW="${GUARDEX_FINISH_WAIT_POLL_SECONDS:-10}"
 
+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 "[agent-branch-finish] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 normalize_bool() {
   local raw="${1:-}"
   local fallback="${2:-0}"
@@ -431,7 +450,7 @@ run_pr_flow() {
   if [[ -z "$pr_title" ]]; then
     pr_title="Merge ${SOURCE_BRANCH} into ${BASE_BRANCH}"
   fi
-  pr_body="Automated by scripts/agent-branch-finish.sh (PR flow)."
+  pr_body="Automated by gx branch finish (PR flow)."
 
   "$GH_BIN" pr create \
     --base "$BASE_BRANCH" \
@@ -517,9 +536,7 @@ if [[ "$PUSH_ENABLED" -eq 1 ]]; then
   fi
 fi
 
-if [[ -x "${repo_root}/scripts/agent-file-locks.py" ]]; then
-  python3 "${repo_root}/scripts/agent-file-locks.py" release --branch "$SOURCE_BRANCH" >/dev/null 2>&1 || true
-fi
+run_guardex_cli locks release --branch "$SOURCE_BRANCH" >/dev/null 2>&1 || true
 
 base_worktree="$(get_worktree_for_branch "$BASE_BRANCH")"
 if [[ -n "$base_worktree" ]] && is_clean_worktree "$base_worktree" && [[ "$PUSH_ENABLED" -eq 1 ]]; then
@@ -555,29 +572,25 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
     fi
   fi
 
-  if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-    prune_args=(--base "$BASE_BRANCH" --only-dirty-worktrees --delete-branches)
-    if [[ "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
-      prune_args+=(--delete-remote-branches)
-    fi
-    if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" "${prune_args[@]}"; then
-      echo "[agent-branch-finish] Warning: automatic worktree prune failed." >&2
-      echo "[agent-branch-finish] You can run manual cleanup: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches" >&2
-    fi
+  prune_args=(--base "$BASE_BRANCH" --only-dirty-worktrees --delete-branches)
+  if [[ "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
+    prune_args+=(--delete-remote-branches)
+  fi
+  if ! run_guardex_cli worktree prune "${prune_args[@]}"; then
+    echo "[agent-branch-finish] Warning: automatic worktree prune failed." >&2
+    echo "[agent-branch-finish] You can run manual cleanup: gx cleanup --base ${BASE_BRANCH}" >&2
   fi
 
   echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and cleaned source branch/worktree."
   if [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${agent_worktree_root}"/* ]]; then
     echo "[agent-branch-finish] Current worktree '${source_worktree}' still exists because it is the active shell cwd." >&2
-    echo "[agent-branch-finish] Leave this directory, then run: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches" >&2
+    echo "[agent-branch-finish] Leave this directory, then run: gx cleanup --base ${BASE_BRANCH}" >&2
   fi
 else
-  if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-    if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" --base "$BASE_BRANCH"; then
-      echo "[agent-branch-finish] Warning: temporary worktree prune failed." >&2
-    fi
+  if ! run_guardex_cli worktree prune --base "$BASE_BRANCH"; then
+    echo "[agent-branch-finish] Warning: temporary worktree prune failed." >&2
   fi
 
   echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and kept source branch/worktree."
-  echo "[agent-branch-finish] Cleanup later with: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH} --delete-branches --delete-remote-branches"
+  echo "[agent-branch-finish] Cleanup later with: gx cleanup --base ${BASE_BRANCH}"
 fi

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

@@ -6,18 +6,37 @@ BASE_BRANCH_EXPLICIT=0
 TARGET_BRANCH=""
 TASK_NAME=""
 AGENT_NAME="${GUARDEX_MERGE_AGENT_NAME:-codex}"
+NODE_BIN="${GUARDEX_NODE_BIN:-node}"
+CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}"
 declare -a SOURCE_BRANCHES=()
 
 usage() {
   cat <<'EOF'
-Usage: scripts/agent-branch-merge.sh --branch <agent/...> [--branch <agent/...> ...] [--into <agent/...>] [--task <task>] [--agent <agent>] [--base <branch>]
+Usage: gx branch merge --branch <agent/...> [--branch <agent/...> ...] [--into <agent/...>] [--task <task>] [--agent <agent>] [--base <branch>]
 
 Examples:
-  bash scripts/agent-branch-merge.sh --branch agent/codex/ui-a --branch agent/codex/ui-b
-  bash scripts/agent-branch-merge.sh --into agent/codex/owner-lane --branch agent/codex/helper-a --branch agent/codex/helper-b
+  gx branch merge --branch agent/codex/ui-a --branch agent/codex/ui-b
+  gx branch merge --into agent/codex/owner-lane --branch agent/codex/helper-a --branch agent/codex/helper-b
 EOF
 }
 
+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 "[agent-branch-merge] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 sanitize_slug() {
   local raw="$1"
   local fallback="${2:-merge-agent-branches}"
@@ -262,7 +281,7 @@ if [[ -z "$TARGET_BRANCH" ]]; then
   start_output=""
   if ! start_output="$(
     cd "$repo_root"
-    env GUARDEX_OPENSPEC_AUTO_INIT=1 bash "scripts/agent-branch-start.sh" "$TASK_NAME" "$AGENT_NAME" "$BASE_BRANCH" 2>&1
+    GUARDEX_OPENSPEC_AUTO_INIT=1 run_guardex_cli branch start "$TASK_NAME" "$AGENT_NAME" "$BASE_BRANCH" 2>&1
   )"; then
     printf '%s\n' "$start_output" >&2
     exit 1
@@ -418,4 +437,4 @@ echo "[agent-branch-merge] Merge sequence complete for '${TARGET_BRANCH}'."
 if [[ "$target_created" -eq 1 ]]; then
   echo "[agent-branch-merge] Review and verify in '${target_worktree}', then finish the integration branch when ready."
 fi
-echo "[agent-branch-merge] Next step: bash scripts/agent-branch-finish.sh --branch \"${TARGET_BRANCH}\" --base \"${BASE_BRANCH}\" --via-pr --wait-for-merge --cleanup"
+echo "[agent-branch-merge] Next step: gx branch finish --branch \"${TARGET_BRANCH}\" --base \"${BASE_BRANCH}\" --via-pr --wait-for-merge --cleanup"

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

@@ -7,6 +7,8 @@ BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=0
 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_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
@@ -15,6 +17,23 @@ OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
+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 "[agent-branch-start] Guardex CLI entrypoint unavailable; rerun via gx." >&2
+  return 127
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --task)
@@ -385,26 +404,14 @@ initialize_openspec_plan_workspace() {
   local worktree="$2"
   local plan_slug="$3"
 
-  hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-plan-workspace.sh"
-
   if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
     return 0
   fi
 
-  local openspec_script="${worktree}/scripts/openspec/init-plan-workspace.sh"
-  if [[ ! -f "$openspec_script" ]]; then
-    echo "[agent-branch-start] OpenSpec init script is missing in sandbox worktree." >&2
-    echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2
-    return 1
-  fi
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
   local init_output=""
   if ! init_output="$(
     cd "$worktree"
-    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 "[agent-branch-start] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2
@@ -423,26 +430,14 @@ initialize_openspec_change_workspace() {
   local change_slug="$3"
   local capability_slug="$4"
 
-  hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-change-workspace.sh"
-
   if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
     return 0
   fi
 
-  local openspec_script="${worktree}/scripts/openspec/init-change-workspace.sh"
-  if [[ ! -f "$openspec_script" ]]; then
-    echo "[agent-branch-start] OpenSpec change init script is missing in sandbox worktree." >&2
-    echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2
-    return 1
-  fi
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
   local init_output=""
   if ! init_output="$(
     cd "$worktree"
-    bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1
+    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
@@ -592,7 +587,6 @@ if [[ -n "$auto_transfer_stash_ref" ]]; then
   fi
 fi
 
-hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-agent.sh"
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "node_modules"
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/frontend/node_modules"
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/backend/node_modules"
@@ -609,6 +603,6 @@ echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_s
 echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
 echo "[agent-branch-start] Next steps:"
 echo "  cd \"${worktree_path}\""
-echo "  python3 scripts/agent-file-locks.py claim --branch \"${branch_name}\" <file...>"
+echo "  gx locks claim --branch \"${branch_name}\" <file...>"
 echo "  # implement + commit"
-echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge"
+echo "  gx branch finish --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge"

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/agent-session-state.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function resolveSessionSchemaModule() {
+  const candidates = [
+    path.resolve(__dirname, '..', 'vscode', 'guardex-active-agents', 'session-schema.js'),
+    path.resolve(__dirname, '..', 'templates', 'vscode', 'guardex-active-agents', 'session-schema.js'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return require(candidate);
+    }
+  }
+
+  throw new Error('Could not resolve Guardex active-agent session schema module.');
+}
+
+const sessionSchema = resolveSessionSchemaModule();
+
+function usage() {
+  return (
+    'Usage:\n' +
+    '  node scripts/agent-session-state.js start --repo <path> --branch <name> --task <task> --agent <agent> --worktree <path> --pid <pid> --cli <name>\n' +
+    '  node scripts/agent-session-state.js stop --repo <path> --branch <name>\n'
+  );
+}
+
+function parseOptions(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${token}`);
+    }
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new Error(`Missing value for --${key}`);
+    }
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function requireOption(options, key) {
+  const value = options[key];
+  if (!value) {
+    throw new Error(`Missing required option --${key}`);
+  }
+  return value;
+}
+
+function writeSessionRecord(options) {
+  const repoRoot = requireOption(options, 'repo');
+  const branch = requireOption(options, 'branch');
+  const record = sessionSchema.buildSessionRecord({
+    repoRoot,
+    branch,
+    taskName: requireOption(options, 'task'),
+    agentName: requireOption(options, 'agent'),
+    worktreePath: requireOption(options, 'worktree'),
+    pid: requireOption(options, 'pid'),
+    cliName: requireOption(options, 'cli'),
+  });
+
+  const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+}
+
+function removeSessionRecord(options) {
+  const repoRoot = requireOption(options, 'repo');
+  const branch = requireOption(options, 'branch');
+  const targetPath = sessionSchema.sessionFilePathForBranch(repoRoot, branch);
+  if (fs.existsSync(targetPath)) {
+    fs.unlinkSync(targetPath);
+  }
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || ['-h', '--help', 'help'].includes(command)) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const options = parseOptions(rest);
+  if (command === 'start') {
+    writeSessionRecord(options);
+    return;
+  }
+  if (command === 'stop') {
+    removeSessionRecord(options);
+    return;
+  }
+
+  throw new Error(`Unknown subcommand: ${command}`);
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`[guardex-active-session] ${error.message}\n`);
+  process.stderr.write(usage());
+  process.exitCode = 1;
+}