@imdeadpool/guardex 5.0.0 → 5.0.1

package/README.md

@@ -50,26 +50,29 @@ Related tools:
 
 - [oh-my-codex (OMX)](https://github.com/Yeachan-Heo/oh-my-codex)
 - [OpenSpec](https://github.com/Fission-AI/OpenSpec)
+- [codex-account-switcher-cli](https://github.com/recodeecom/codex-account-switcher-cli)
 
 ## Fast setup (recommended)
 
 ```sh
 # inside your repo
 gx setup
+# alias:
+gx init
 ```
 
 That one command runs:
 
-1. detects whether OMX/OpenSpec are already globally installed,
+1. detects whether OMX/OpenSpec/codex-auth are already globally installed,
 2. asks strict Y/N approval only if something is missing,
 3. installs guardrail scripts/hooks,
 4. repairs common safety problems,
 5. installs local Codex + Claude gx helper skill files if missing,
 6. scans and reports final status.
 
-## Setup screenshot
+## Setup behavior screenshot
 
-![gx setup success screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/setup-success.svg)
+![gx status/setup behavior screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/setup-success.svg)
 
 ## Status logs screenshot
 
@@ -217,10 +220,11 @@ Use this exact checklist to setup multi-agent safety in this repository for Code
 
 2) Bootstrap safety in this repo:
    gx setup
+   # alias: gx init
 
-   - Setup detects global OMX/OpenSpec first.
+   - Setup detects global OMX/OpenSpec/codex-auth first.
    - If one is missing and setup asks for approval, reply explicitly:
-     - y = run: npm i -g oh-my-codex @fission-ai/openspec (missing ones only)
+     - y = run: npm i -g oh-my-codex @fission-ai/openspec @imdeadpool/codex-account-switcher (missing ones only)
      - n = skip global installs
 
 3) If setup reports warnings/errors, repair + re-check:
@@ -231,6 +235,9 @@ Use this exact checklist to setup multi-agent safety in this repository for Code
    bash scripts/agent-branch-start.sh "task" "agent-name"
    python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
    bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)"
+   - For every new user message/task, repeat the same cycle:
+     start isolated agent branch/worktree -> claim file locks -> implement/verify ->
+     finish via PR/merge cleanup with scripts/agent-branch-finish.sh.
 
 5) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
@@ -250,8 +257,9 @@ Use this exact checklist to setup multi-agent safety in this repository for Code
 
 ```sh
 gx status [--target <path>] [--json]
-gx setup [--target <path>] [--dry-run] [--yes-global-install|--no-global-install] [--no-gitignore]
-gx doctor [--target <path>] [--dry-run] [--json] [--keep-stale-locks] [--no-gitignore]
+gx setup [--target <path>] [--dry-run] [--yes-global-install|--no-global-install] [--no-gitignore] [--allow-protected-base-write]
+gx init [--target <path>] [--dry-run] [--yes-global-install|--no-global-install] [--no-gitignore] [--allow-protected-base-write]
+gx doctor [--target <path>] [--dry-run] [--json] [--keep-stale-locks] [--no-gitignore] [--allow-protected-base-write]
 gx copy-prompt
 gx copy-commands
 gx protect list [--target <path>]
@@ -262,24 +270,28 @@ gx protect reset [--target <path>]
 gx sync --check [--target <path>] [--base <branch>] [--json]
 gx sync [--target <path>] [--base <branch>] [--strategy rebase|merge] [--ff-only]
 gx report scorecard [--target <path>] [--repo github.com/<owner>/<repo>] [--scorecard-json <file>] [--output-dir <path>] [--date YYYY-MM-DD]
-bash scripts/agent-worktree-prune.sh --base dev   # manual stale worktree cleanup
+bash scripts/agent-worktree-prune.sh   # manual stale worktree cleanup (auto base detection)
+bash scripts/agent-worktree-prune.sh --force-dirty   # remove stale dirty worktrees too
 bash scripts/openspec/init-plan-workspace.sh <plan-slug>   # optional OpenSpec plan scaffold
 ```
 
 No command defaults to `gx status` (non-mutating health/status view).
-`gx status` reports CLI/runtime info, global OMX/OpenSpec service status, and repo safety service state.
+`gx status` reports CLI/runtime info, global OMX/OpenSpec/codex-auth service status, and repo safety service state.
+`gx init` is an alias of `gx setup`.
 When run in an interactive terminal, default `GuardeX` checks npm for a newer version first
 and asks `[y/N]` whether to update immediately (default is `N`).
 
-- Interactive setup: prompts for Y/N approval before global OMX/OpenSpec install.
+- Interactive setup: prompts for Y/N approval before global OMX/OpenSpec/codex-auth install.
 - Interactive prompt is strict (`[y/n]`) and waits for explicit answer.
 - Non-interactive setup: skips global installs by default; use `--yes-global-install` to force.
+- In already-initialized repos, `setup` / `install` / `fix` / `doctor` block writes on protected `main` by default; start an agent branch first. Use `--allow-protected-base-write` only for emergency in-place maintenance.
+- `scripts/codex-agent.sh` now auto-runs worktree prune after a Codex session; clean sandbox branches are removed automatically, dirty ones are kept.
 
 ## Advanced commands
 
 ```sh
-gx install [--target <path>] [--force] [--skip-agents] [--skip-package-json] [--no-gitignore] [--dry-run]
-gx fix [--target <path>] [--dry-run] [--keep-stale-locks] [--no-gitignore]
+gx install [--target <path>] [--force] [--skip-agents] [--skip-package-json] [--no-gitignore] [--dry-run] [--allow-protected-base-write]
+gx fix [--target <path>] [--dry-run] [--keep-stale-locks] [--no-gitignore] [--allow-protected-base-write]
 gx scan [--target <path>] [--json]
 gx report help
 ```

package/bin/multiagent-safety.js

@@ -10,7 +10,11 @@ const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
 const TOOL_NAME = 'guardex';
 const SHORT_TOOL_NAME = 'gx';
 const LEGACY_NAMES = ['musafety', 'multiagent-safety'];
-const GLOBAL_TOOLCHAIN_PACKAGES = ['oh-my-codex', '@fission-ai/openspec'];
+const GLOBAL_TOOLCHAIN_PACKAGES = [
+  'oh-my-codex',
+  '@fission-ai/openspec',
+  '@imdeadpool/codex-account-switcher',
+];
 const MAINTAINER_RELEASE_REPO = path.resolve(
   process.env.MUSAFETY_RELEASE_REPO || '/tmp/multiagent-safety',
 );
@@ -80,6 +84,7 @@ const COMMAND_TYPO_ALIASES = new Map([
   ['realaese', 'release'],
   ['relase', 'release'],
   ['setpu', 'setup'],
+  ['inti', 'init'],
   ['intsall', 'install'],
   ['docter', 'doctor'],
   ['doctro', 'doctor'],
@@ -88,6 +93,7 @@ const COMMAND_TYPO_ALIASES = new Map([
 const SUGGESTIBLE_COMMANDS = [
   'status',
   'setup',
+  'init',
   'doctor',
   'report',
   'copy-prompt',
@@ -105,6 +111,7 @@ const SUGGESTIBLE_COMMANDS = [
 const CLI_COMMAND_DESCRIPTIONS = [
   ['status', 'Show GuardeX CLI + service health without modifying files'],
   ['setup', 'Install + repair guardrails in a git repo (supports --no-gitignore)'],
+  ['init', 'Alias of setup (bootstrap + repair guardrails in a git repo)'],
   ['doctor', 'Repair safety setup drift, then verify repo safety'],
   ['report', 'Generate security/safety reports (for example: OpenSSF scorecard)'],
   ['copy-prompt', 'Print the AI-ready setup checklist'],
@@ -127,10 +134,11 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
 
 2) Bootstrap safety in this repo:
    gx setup
+   # alias: gx init
 
-   - Setup detects global OMX/OpenSpec first.
+   - Setup detects global OMX/OpenSpec/codex-auth first.
    - If one is missing and setup asks for approval, reply explicitly:
-     - y = run: npm i -g oh-my-codex @fission-ai/openspec (missing ones only)
+     - y = run: npm i -g oh-my-codex @fission-ai/openspec @imdeadpool/codex-account-switcher (missing ones only)
      - n = skip global installs
 
 3) If setup reports warnings/errors, repair + re-check:
@@ -141,6 +149,9 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
    bash scripts/agent-branch-start.sh "task" "agent-name"
    python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
    bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)"
+   - For every new user message/task, repeat the same cycle:
+     start isolated agent branch/worktree -> claim file locks -> implement/verify ->
+     finish via PR/merge cleanup with scripts/agent-branch-finish.sh.
 
 5) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
@@ -151,6 +162,9 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
 7) Optional: sync your current agent branch with latest base branch:
    gx sync --check
    gx sync
+
+8) Optional (GitHub remote cleanup): enable:
+   Settings -> General -> Pull Requests -> Automatically delete head branches
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
@@ -272,7 +286,9 @@ ${commandCatalogLines().join('\n')}
 NOTES
   - Running ${TOOL_NAME} with no command defaults to: ${SHORT_TOOL_NAME} status
   - Short alias: ${SHORT_TOOL_NAME}
+  - ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup
   - ${TOOL_NAME} setup asks for Y/N approval before global installs
+  - In initialized repos, setup/install/fix/doctor block in-place writes on protected main by default
   - Legacy command aliases are still supported: ${LEGACY_NAMES.join(', ')}`);
 
   if (outsideGitRepo) {
@@ -473,7 +489,7 @@ function ensurePackageScripts(repoRoot, dryRun) {
     'agent:codex': 'bash ./scripts/codex-agent.sh',
     'agent:branch:start': 'bash ./scripts/agent-branch-start.sh',
     'agent:branch:finish': 'bash ./scripts/agent-branch-finish.sh',
-    'agent:cleanup': 'bash ./scripts/agent-worktree-prune.sh --base dev',
+    'agent:cleanup': 'bash ./scripts/agent-worktree-prune.sh',
     'agent:hooks:install': 'bash ./scripts/install-agent-git-hooks.sh',
     'agent:locks:claim': 'python3 ./scripts/agent-file-locks.py claim',
     'agent:locks:allow-delete': 'python3 ./scripts/agent-file-locks.py allow-delete',
@@ -630,6 +646,10 @@ function parseCommonArgs(rawArgs, defaults) {
       options.skipGitignore = true;
       continue;
     }
+    if (arg === '--allow-protected-base-write') {
+      options.allowProtectedBaseWrite = true;
+      continue;
+    }
 
     throw new Error(`Unknown option: ${arg}`);
   }
@@ -641,6 +661,44 @@ function parseCommonArgs(rawArgs, defaults) {
   return options;
 }
 
+function hasGuardexBootstrapFiles(repoRoot) {
+  const required = [
+    'AGENTS.md',
+    'scripts/agent-branch-start.sh',
+    '.githooks/pre-commit',
+    LOCK_FILE_RELATIVE,
+  ];
+  return required.every((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
+}
+
+function assertProtectedMainWriteAllowed(options, commandName) {
+  if (options.dryRun || options.allowProtectedBaseWrite) {
+    return;
+  }
+
+  const repoRoot = resolveRepoRoot(options.target);
+  if (!hasGuardexBootstrapFiles(repoRoot)) {
+    return;
+  }
+
+  const branch = currentBranchName(repoRoot);
+  if (branch !== 'main') {
+    return;
+  }
+
+  const protectedBranches = readProtectedBranches(repoRoot);
+  if (!protectedBranches.includes(branch)) {
+    return;
+  }
+
+  throw new Error(
+    `${commandName} blocked on protected branch '${branch}' in an initialized repo.\n` +
+    `Keep local '${branch}' pull-only: start an agent branch/worktree first:\n` +
+    `  bash scripts/agent-branch-start.sh "<task>" "codex"\n` +
+    `Override once only when intentional: --allow-protected-base-write`,
+  );
+}
+
 function parseTargetFlag(rawArgs, defaultTarget = process.cwd()) {
   const remaining = [];
   let target = defaultTarget;
@@ -1777,8 +1835,10 @@ function install(rawArgs) {
     skipPackageJson: false,
     skipGitignore: false,
     dryRun: false,
+    allowProtectedBaseWrite: false,
   });
 
+  assertProtectedMainWriteAllowed(options, 'install');
   const payload = runInstallInternal(options);
   printOperations('Install target', payload, options.dryRun);
 
@@ -1797,8 +1857,10 @@ function fix(rawArgs) {
     skipPackageJson: false,
     skipGitignore: false,
     dryRun: false,
+    allowProtectedBaseWrite: false,
   });
 
+  assertProtectedMainWriteAllowed(options, 'fix');
   const payload = runFixInternal(options);
   printOperations('Fix target', payload, options.dryRun);
 
@@ -1829,8 +1891,10 @@ function doctor(rawArgs) {
     skipGitignore: false,
     dryRun: false,
     json: false,
+    allowProtectedBaseWrite: false,
   });
 
+  assertProtectedMainWriteAllowed(options, 'doctor');
   const fixPayload = runFixInternal(options);
   const scanResult = runScanInternal({ target: options.target, json: false });
   const musafe = scanResult.errors === 0 && scanResult.warnings === 0;
@@ -1974,6 +2038,7 @@ function setup(rawArgs) {
     dryRun: false,
     yesGlobalInstall: false,
     noGlobalInstall: false,
+    allowProtectedBaseWrite: false,
   });
 
   const globalInstallStatus = installGlobalToolchain(options);
@@ -1982,7 +2047,7 @@ function setup(rawArgs) {
       `[${TOOL_NAME}] ✅ Global tools installed (${(globalInstallStatus.packages || []).join(', ')}).`,
     );
   } else if (globalInstallStatus.status === 'already-installed') {
-    console.log(`[${TOOL_NAME}] ✅ OMX/OpenSpec global tools already installed. Skipping.`);
+    console.log(`[${TOOL_NAME}] ✅ OMX/OpenSpec/codex-auth global tools already installed. Skipping.`);
   } else if (globalInstallStatus.status === 'failed') {
     console.log(
       `[${TOOL_NAME}] ⚠️ Global install failed: ${globalInstallStatus.reason}\n` +
@@ -1996,6 +2061,7 @@ function setup(rawArgs) {
     );
   }
 
+  assertProtectedMainWriteAllowed(options, 'setup');
   const installPayload = runInstallInternal(options);
   printOperations('Setup/install', installPayload, options.dryRun);
 
@@ -2403,7 +2469,7 @@ function main() {
     return;
   }
 
-  if (command === 'setup') {
+  if (command === 'setup' || command === 'init') {
     setup(rest);
     return;
   }

package/package.json

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

package/templates/AGENTS.multiagent-safety.md

@@ -10,7 +10,9 @@
 - Before deleting/replacing code, each agent must read the latest session comments/handoffs first and confirm the target code is in their owned scope.
 - If ownership is unclear or overlaps, stop that edit, post a blocker comment, and let the leader/integrator reassign scope.
 - For git isolation, each agent must start on a dedicated branch via `scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"`.
+- Treat the base branch (`main` or the user's current local base branch) as read-only while the agent branch is active.
 - Agent completion must use `scripts/agent-branch-finish.sh` (direct merge to base when allowed; auto PR fallback for protected bases, then cleanup after merge).
+- Per-message loop is mandatory: for every new user message/task, start a fresh agent branch/worktree, claim ownership locks, implement and verify, finish via PR/merge cleanup, then repeat for the next message/task.
 
 1. Explicit ownership before edits
 

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

@@ -19,6 +19,8 @@ If guardrails are missing entirely, run:
 
 ```sh
 gx setup
+# alias
+gx init
 ```
 
 Then verify:
@@ -32,5 +34,6 @@ gx scan
 
 - Prefer `gx doctor` for one-step repair + verification.
 - Keep agent work isolated (`agent/*` branches + lock claims).
+- For every new user message/task, restart the full loop on a fresh agent branch/worktree.
 - For one-command Codex sandbox startup, use `bash scripts/codex-agent.sh "<task>" "<agent-name>"`.
 - Do not bypass protected branch safeguards unless explicitly required.

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

@@ -1,22 +1,33 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-BASE_BRANCH="dev"
+BASE_BRANCH="${MUSAFETY_BASE_BRANCH:-}"
+BASE_BRANCH_EXPLICIT=0
 DRY_RUN=0
+FORCE_DIRTY=0
+
+if [[ -n "$BASE_BRANCH" ]]; then
+  BASE_BRANCH_EXPLICIT=1
+fi
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --base)
-      BASE_BRANCH="${2:-dev}"
+      BASE_BRANCH="${2:-}"
+      BASE_BRANCH_EXPLICIT=1
       shift 2
       ;;
     --dry-run)
       DRY_RUN=1
       shift
       ;;
+    --force-dirty)
+      FORCE_DIRTY=1
+      shift
+      ;;
     *)
       echo "[agent-worktree-prune] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--dry-run]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty]" >&2
       exit 1
       ;;
   esac
@@ -31,6 +42,46 @@ repo_root="$(git rev-parse --show-toplevel)"
 current_pwd="$(pwd -P)"
 worktree_root="${repo_root}/.omx/agent-worktrees"
 
+resolve_base_branch() {
+  local configured=""
+  local current=""
+
+  configured="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
+  if [[ -n "$configured" ]] && git -C "$repo_root" show-ref --verify --quiet "refs/heads/${configured}"; then
+    printf '%s' "$configured"
+    return 0
+  fi
+
+  current="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  if [[ -n "$current" && "$current" != "HEAD" ]] && git -C "$repo_root" show-ref --verify --quiet "refs/heads/${current}"; then
+    printf '%s' "$current"
+    return 0
+  fi
+
+  for fallback in main dev; do
+    if git -C "$repo_root" show-ref --verify --quiet "refs/heads/${fallback}"; then
+      printf '%s' "$fallback"
+      return 0
+    fi
+  done
+
+  printf '%s' ""
+}
+
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
+  echo "[agent-worktree-prune] --base requires a non-empty branch name." >&2
+  exit 1
+fi
+
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
+  BASE_BRANCH="$(resolve_base_branch)"
+fi
+
+if [[ -z "$BASE_BRANCH" ]]; then
+  echo "[agent-worktree-prune] Unable to infer base branch. Pass --base <branch>." >&2
+  exit 1
+fi
+
 if ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then
   echo "[agent-worktree-prune] Base branch not found: ${BASE_BRANCH}" >&2
   exit 1
@@ -49,9 +100,17 @@ branch_has_worktree() {
   git -C "$repo_root" worktree list --porcelain | grep -q "^branch refs/heads/${branch}$"
 }
 
+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)" ]]
+}
+
 removed_worktrees=0
 removed_branches=0
 skipped_active=0
+skipped_dirty=0
 
 process_entry() {
   local wt="$1"
@@ -89,6 +148,12 @@ process_entry() {
     return
   fi
 
+  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}"
+    return
+  fi
+
   echo "[agent-worktree-prune] Removing worktree (${remove_reason}): ${wt}"
   run_cmd git -C "$repo_root" worktree remove "$wt" --force
   removed_worktrees=$((removed_worktrees + 1))
@@ -149,7 +214,10 @@ done < <(git -C "$repo_root" for-each-ref --format='%(refname:short)' refs/heads
 
 run_cmd git -C "$repo_root" worktree prune
 
-echo "[agent-worktree-prune] Summary: removed_worktrees=${removed_worktrees}, removed_branches=${removed_branches}, skipped_active=${skipped_active}"
+echo "[agent-worktree-prune] Summary: base=${BASE_BRANCH}, removed_worktrees=${removed_worktrees}, removed_branches=${removed_branches}, skipped_active=${skipped_active}, skipped_dirty=${skipped_dirty}"
 if [[ "$skipped_active" -gt 0 ]]; then
   echo "[agent-worktree-prune] Tip: leave active agent worktree directories, then run this command again for full cleanup." >&2
 fi
+if [[ "$skipped_dirty" -gt 0 ]]; then
+  echo "[agent-worktree-prune] Tip: dirty worktrees were preserved. Clean/finish them first, or pass --force-dirty to remove anyway." >&2
+fi

package/templates/scripts/codex-agent.sh

@@ -65,7 +65,13 @@ if ! command -v "$CODEX_BIN" >/dev/null 2>&1; then
   exit 127
 fi
 
-if [[ ! -x "scripts/agent-branch-start.sh" ]]; then
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "[codex-agent] Not inside a git repository." >&2
+  exit 1
+fi
+repo_root="$(git rev-parse --show-toplevel)"
+
+if [[ ! -x "${repo_root}/scripts/agent-branch-start.sh" ]]; then
   echo "[codex-agent] Missing scripts/agent-branch-start.sh. Run: gx setup" >&2
   exit 1
 fi
@@ -75,7 +81,7 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
   start_args+=("$BASE_BRANCH")
 fi
 
-start_output="$(bash scripts/agent-branch-start.sh "${start_args[@]}")"
+start_output="$(bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}")"
 printf '%s\n' "$start_output"
 
 worktree_path="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Worktree: //p' | tail -n1)"
@@ -91,4 +97,32 @@ fi
 
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"
 cd "$worktree_path"
-exec "$CODEX_BIN" "$@"
+set +e
+"$CODEX_BIN" "$@"
+codex_exit="$?"
+set -e
+
+cd "$repo_root"
+
+if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
+  echo "[codex-agent] Session ended (exit=${codex_exit}). Running worktree cleanup..."
+  prune_args=()
+  if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
+    prune_args+=(--base "$BASE_BRANCH")
+  fi
+  if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" "${prune_args[@]}"; then
+    echo "[codex-agent] Warning: automatic worktree cleanup failed." >&2
+  fi
+fi
+
+if [[ ! -d "$worktree_path" ]]; then
+  echo "[codex-agent] Auto-cleaned sandbox worktree: $worktree_path"
+else
+  worktree_branch="$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  echo "[codex-agent] Sandbox worktree kept: $worktree_path"
+  if [[ -n "$worktree_branch" && "$worktree_branch" != "HEAD" ]]; then
+    echo "[codex-agent] If finished, merge + clean with: bash scripts/agent-branch-finish.sh --branch \"${worktree_branch}\""
+  fi
+fi
+
+exit "$codex_exit"