@imdeadpool/guardex 5.0.4 → 5.0.7

package/README.md

@@ -110,7 +110,7 @@ gx sync
 # continuously monitor open PRs targeting current branch and dispatch codex-agent review/merge tasks
 bash scripts/review-bot-watch.sh --interval 30
 
-# cleanup merged agent branches/worktrees
+# cleanup merged agent branches and hide clean stale agent worktrees
 gx cleanup
 
 # scan/report
@@ -143,7 +143,8 @@ Note: the monitor dispatches Codex through explicit `--task/--agent/--base` flag
 - `gx setup` checks GitHub CLI (`gh`) and prints install guidance if missing.
 - Interactive self-update prompt defaults to **No** (`[y/N]`).
 - In initialized repos, `setup`/`install`/`fix` block protected-base writes unless explicitly overridden.
-- In VS Code Source Control, manual (non-Codex) commits/pushes to protected branches are allowed by default.
+- Direct commits/pushes to protected branches are blocked by default (including VS Code Source Control).
+- Optional repo override for manual VS Code protected-branch writes: `git config multiagent.allowVscodeProtectedBranchWrites true`.
 - Codex/agent sessions stay blocked on protected branches and must use `agent/*` branch + PR workflow.
 - On protected `main`, `gx doctor` auto-runs in a sandbox agent branch/worktree.
 - `scripts/agent-branch-start.sh` hydrates `scripts/codex-agent.sh` into new sandbox worktrees when missing, so auto-finish launcher flow stays available.
@@ -238,6 +239,20 @@ npm pack --dry-run
 
 ## Release notes
 
+### v5.0.7
+
+- Bumped package version from `5.0.6` to `5.0.7` to stay one patch ahead for the next npm publish.
+
+### v5.0.6
+
+- `gx cleanup` and auto-finish cleanup now prune clean agent worktrees by default, so VS Code Source Control focuses on your local branch plus worktrees with active changes.
+- Added `gx cleanup --keep-clean-worktrees` to opt out and keep clean worktrees visible.
+- Bumped package version from `5.0.5` to `5.0.6` for the next npm publish.
+
+### v5.0.5
+
+- Bumped package version from `5.0.4` to `5.0.5` so npm publish can proceed with the next patch release.
+
 ### v5.0.4
 
 - Bumped package version from `5.0.3` to `5.0.4` to stay one patch ahead of the current npm published version.

package/bin/multiagent-safety.js

@@ -79,6 +79,7 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
 
 const LOCK_FILE_RELATIVE = '.omx/state/agent-file-locks.json';
 const AGENTS_MARKER_START = '<!-- multiagent-safety:START -->';
+const AGENTS_MARKER_END = '<!-- multiagent-safety:END -->';
 const GITIGNORE_MARKER_START = '# multiagent-safety:START';
 const GITIGNORE_MARKER_END = '# multiagent-safety:END';
 const MANAGED_GITIGNORE_PATHS = [
@@ -147,6 +148,10 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['help', 'Show this help output'],
   ['version', 'Print GuardeX version'],
 ];
+const AGENT_BOT_DESCRIPTIONS = [
+  ['review', 'Monitor open PRs targeting current branch and dispatch codex-agent review flow'],
+  ['start', 'bash scripts/review-bot-watch.sh --interval 30'],
+];
 
 const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-Rex for your repo) in this repository for Codex or Claude.
 
@@ -261,9 +266,20 @@ function commandCatalogLines(indent = '  ') {
   );
 }
 
+function agentBotCatalogLines(indent = '  ') {
+  const maxCommandLength = AGENT_BOT_DESCRIPTIONS.reduce(
+    (max, [command]) => Math.max(max, command.length),
+    0,
+  );
+  return AGENT_BOT_DESCRIPTIONS.map(
+    ([command, description]) => `${indent}${command.padEnd(maxCommandLength + 2)}${description}`,
+  );
+}
+
 function printToolLogsSummary() {
   const usageLine = `    $ ${SHORT_TOOL_NAME} <command> [options]`;
   const commandDetails = commandCatalogLines('    ');
+  const agentBotDetails = agentBotCatalogLines('    ');
 
   if (!supportsAnsiColors()) {
     console.log(`${TOOL_NAME}-tools logs:`);
@@ -273,12 +289,17 @@ function printToolLogsSummary() {
     for (const line of commandDetails) {
       console.log(line);
     }
+    console.log('  AGENT BOT');
+    for (const line of agentBotDetails) {
+      console.log(line);
+    }
     return;
   }
 
   const title = colorize(`${TOOL_NAME}-tools logs`, '1;36');
   const usageHeader = colorize('USAGE', '1');
   const commandsHeader = colorize('COMMANDS', '1');
+  const agentBotHeader = colorize('AGENT BOT', '1');
   const pipe = colorize('│', '90');
   const tee = colorize('├', '90');
   const corner = colorize('└', '90');
@@ -294,6 +315,14 @@ function printToolLogsSummary() {
     }
     console.log(`  ${pipe}${line.slice(2)}`);
   }
+  console.log(`  ${tee}─ ${agentBotHeader}`);
+  for (const line of agentBotDetails) {
+    if (!line) {
+      console.log(`  ${pipe}`);
+      continue;
+    }
+    console.log(`  ${pipe}${line.slice(2)}`);
+  }
   console.log(`  ${corner}─ ${colorize(`Try '${TOOL_NAME} doctor' for one-step repair + verification.`, '2')}`);
 }
 
@@ -311,6 +340,9 @@ USAGE
 COMMANDS
 ${commandCatalogLines().join('\n')}
 
+AGENT BOT
+${agentBotCatalogLines().join('\n')}
+
 NOTES
   - Running ${TOOL_NAME} with no command defaults to: ${SHORT_TOOL_NAME} status
   - Short alias: ${SHORT_TOOL_NAME}
@@ -577,6 +609,10 @@ function ensurePackageScripts(repoRoot, dryRun) {
 function ensureAgentsSnippet(repoRoot, dryRun) {
   const agentsPath = path.join(repoRoot, 'AGENTS.md');
   const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, 'AGENTS.multiagent-safety.md'), 'utf8').trimEnd();
+  const managedRegex = new RegExp(
+    `${AGENTS_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${AGENTS_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+    'm',
+  );
 
   if (!fs.existsSync(agentsPath)) {
     if (!dryRun) {
@@ -586,8 +622,19 @@ function ensureAgentsSnippet(repoRoot, dryRun) {
   }
 
   const existing = fs.readFileSync(agentsPath, 'utf8');
+  if (managedRegex.test(existing)) {
+    const next = existing.replace(managedRegex, snippet);
+    if (next === existing) {
+      return { status: 'unchanged', file: 'AGENTS.md' };
+    }
+    if (!dryRun) {
+      fs.writeFileSync(agentsPath, next, 'utf8');
+    }
+    return { status: 'updated', file: 'AGENTS.md', note: 'refreshed guardex-managed block' };
+  }
+
   if (existing.includes(AGENTS_MARKER_START)) {
-    return { status: 'unchanged', file: 'AGENTS.md' };
+    return { status: 'unchanged', file: 'AGENTS.md', note: 'existing marker found without managed end marker' };
   }
 
   const separator = existing.endsWith('\n') ? '\n' : '\n\n';
@@ -1038,6 +1085,19 @@ function isCommandAvailable(commandName) {
   return run('which', [commandName]).status === 0;
 }
 
+function extractAgentBranchFinishPrUrl(output) {
+  const match = String(output || '').match(/\[agent-branch-finish\] PR:\s*(\S+)/);
+  return match ? match[1] : '';
+}
+
+function doctorFinishFlowIsPending(output) {
+  return (
+    /\[agent-branch-finish\] PR merge not completed yet; leaving PR open\./.test(output) ||
+    /\[agent-branch-finish\] Merge pending review\/check policy\. Branch cleanup skipped for now\./.test(output) ||
+    /\[agent-branch-finish\] PR auto-merge enabled; waiting for required checks\/reviews\./.test(output)
+  );
+}
+
 function finishDoctorSandboxBranch(blocked, metadata) {
   const finishScript = path.join(metadata.worktreePath, 'scripts', 'agent-branch-finish.sh');
   if (!fs.existsSync(finishScript)) {
@@ -1091,6 +1151,17 @@ function finishDoctorSandboxBranch(blocked, metadata) {
     };
   }
 
+  const combinedOutput = `${finishResult.stdout || ''}\n${finishResult.stderr || ''}`;
+  if (doctorFinishFlowIsPending(combinedOutput)) {
+    return {
+      status: 'pending',
+      note: 'PR created and waiting for merge policy/checks',
+      prUrl: extractAgentBranchFinishPrUrl(combinedOutput),
+      stdout: finishResult.stdout || '',
+      stderr: finishResult.stderr || '',
+    };
+  }
+
   return {
     status: 'completed',
     note: 'doctor sandbox finish flow completed',
@@ -1235,6 +1306,15 @@ function runDoctorInSandbox(options, blocked) {
         console.log(`[${TOOL_NAME}] Auto-finish flow completed for sandbox branch '${metadata.branch}'.`);
         if (finishResult.stdout) process.stdout.write(finishResult.stdout);
         if (finishResult.stderr) process.stderr.write(finishResult.stderr);
+      } else if (finishResult.status === 'pending') {
+        console.log(
+          `[${TOOL_NAME}] Auto-finish pending for sandbox branch '${metadata.branch}': ${finishResult.note}.`,
+        );
+        if (finishResult.prUrl) {
+          console.log(`[${TOOL_NAME}] PR: ${finishResult.prUrl}`);
+        }
+        if (finishResult.stdout) process.stdout.write(finishResult.stdout);
+        if (finishResult.stderr) process.stderr.write(finishResult.stderr);
       } else if (finishResult.status === 'failed') {
         console.log(`[${TOOL_NAME}] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
         if (finishResult.stdout) process.stdout.write(finishResult.stdout);
@@ -1499,6 +1579,88 @@ function uniquePreserveOrder(items) {
   return result;
 }
 
+function readConfiguredProtectedBranches(repoRoot) {
+  const result = gitRun(repoRoot, ['config', '--get', GIT_PROTECTED_BRANCHES_KEY], { allowFailure: true });
+  if (result.status !== 0) {
+    return null;
+  }
+  const parsed = uniquePreserveOrder(parseBranchList(result.stdout.trim()));
+  if (parsed.length === 0) {
+    return null;
+  }
+  return parsed;
+}
+
+function listLocalUserBranches(repoRoot) {
+  const result = gitRun(repoRoot, ['for-each-ref', '--format=%(refname:short)', 'refs/heads'], { allowFailure: true });
+  const branchNames = result.status === 0
+    ? uniquePreserveOrder(
+      String(result.stdout || '')
+        .split('\n')
+        .map((item) => item.trim())
+        .filter(Boolean),
+    )
+    : [];
+
+  const additionalUserBranches = branchNames.filter(
+    (branchName) =>
+      !branchName.startsWith('agent/') &&
+      !DEFAULT_PROTECTED_BRANCHES.includes(branchName),
+  );
+  if (additionalUserBranches.length > 0) {
+    return additionalUserBranches;
+  }
+
+  const current = gitRun(repoRoot, ['branch', '--show-current'], { allowFailure: true });
+  if (current.status !== 0) {
+    return [];
+  }
+
+  const branchName = String(current.stdout || '').trim();
+  if (
+    !branchName ||
+    branchName.startsWith('agent/') ||
+    DEFAULT_PROTECTED_BRANCHES.includes(branchName)
+  ) {
+    return [];
+  }
+
+  return [branchName];
+}
+
+function ensureSetupProtectedBranches(repoRoot, dryRun) {
+  const localUserBranches = listLocalUserBranches(repoRoot);
+  if (localUserBranches.length === 0) {
+    return {
+      status: 'unchanged',
+      file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
+      note: 'no additional local user branches detected',
+    };
+  }
+
+  const configured = readConfiguredProtectedBranches(repoRoot);
+  const currentBranches = configured || [...DEFAULT_PROTECTED_BRANCHES];
+  const missingBranches = localUserBranches.filter((branchName) => !currentBranches.includes(branchName));
+  if (missingBranches.length === 0) {
+    return {
+      status: 'unchanged',
+      file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
+      note: 'local user branches already protected',
+    };
+  }
+
+  const nextBranches = uniquePreserveOrder([...currentBranches, ...missingBranches]);
+  if (!dryRun) {
+    writeProtectedBranches(repoRoot, nextBranches);
+  }
+
+  return {
+    status: dryRun ? 'would-update' : 'updated',
+    file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
+    note: `added local user branch(es): ${missingBranches.join(', ')}`,
+  };
+}
+
 function readProtectedBranches(repoRoot) {
   const result = gitRun(repoRoot, ['config', '--get', GIT_PROTECTED_BRANCHES_KEY], { allowFailure: true });
   if (result.status !== 0) {
@@ -1705,6 +1867,7 @@ function parseCleanupArgs(rawArgs) {
     dryRun: false,
     forceDirty: false,
     keepRemote: false,
+    keepCleanWorktrees: false,
   };
 
   for (let index = 0; index < rawArgs.length; index += 1) {
@@ -1748,6 +1911,10 @@ function parseCleanupArgs(rawArgs) {
       options.keepRemote = true;
       continue;
     }
+    if (arg === '--keep-clean-worktrees') {
+      options.keepCleanWorktrees = true;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 
@@ -2768,6 +2935,7 @@ function setup(rawArgs) {
 
   assertProtectedMainWriteAllowed(options, 'setup');
   const installPayload = runInstallInternal(options);
+  installPayload.operations.push(ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(options.dryRun)));
   printOperations('Setup/install', installPayload, options.dryRun);
 
   const fixPayload = runFixInternal({
@@ -2882,6 +3050,9 @@ function cleanup(rawArgs) {
   if (options.dryRun) {
     args.push('--dry-run');
   }
+  if (!options.keepCleanWorktrees) {
+    args.push('--only-dirty-worktrees');
+  }
   args.push('--delete-branches');
   if (!options.keepRemote) {
     args.push('--delete-remote-branches');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.4",
+  "version": "5.0.7",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,
@@ -28,7 +28,8 @@
     "agent:safety:setup": "gx setup",
     "agent:safety:scan": "gx scan",
     "agent:safety:fix": "gx fix",
-    "agent:safety:doctor": "gx doctor"
+    "agent:safety:doctor": "gx doctor",
+    "agent:review:watch": "bash ./scripts/review-bot-watch.sh"
   },
   "engines": {
     "node": ">=18"

package/templates/AGENTS.multiagent-safety.md

@@ -17,7 +17,8 @@
 - If codex-agent auto-finish cannot complete, immediately run `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge` and keep the branch open until checks/review pass.
 - If merge/rebase conflicts block auto-finish, run a conflict-resolution review pass in that sandbox branch, then rerun `agent-branch-finish.sh --via-pr` until merged.
 - Completion is not valid until these are true: commit exists on the agent branch, branch is pushed to `origin`, and PR/merge status is produced by `agent-branch-finish.sh` or `codex-agent`.
-- 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.
+- For every new task, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch; otherwise create a fresh one from the current local base snapshot with `scripts/agent-branch-start.sh`.
+- Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 - If the change publishes or bumps a version, the same change must also update release notes/changelog entries.
 
 1. Explicit ownership before edits

package/templates/githooks/pre-commit

@@ -28,6 +28,19 @@ if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n
   is_vscode_git_context=1
 fi
 
+allow_vscode_protected_raw="${MUSAFETY_ALLOW_VSCODE_PROTECTED_BRANCH_WRITES:-$(git config --get multiagent.allowVscodeProtectedBranchWrites || true)}"
+if [[ -z "$allow_vscode_protected_raw" ]]; then
+  allow_vscode_protected_raw="false"
+fi
+allow_vscode_protected="$(printf '%s' "$allow_vscode_protected_raw" | tr '[:upper:]' '[:lower:]')"
+
+allow_vscode_protected_branch_writes=0
+case "$allow_vscode_protected" in
+  1|true|yes|on) allow_vscode_protected_branch_writes=1 ;;
+  0|false|no|off) allow_vscode_protected_branch_writes=0 ;;
+  *) allow_vscode_protected_branch_writes=0 ;;
+esac
+
 protected_branches_raw="${MUSAFETY_PROTECTED_BRANCHES:-$(git config --get multiagent.protectedBranches || true)}"
 if [[ -z "$protected_branches_raw" ]]; then
   protected_branches_raw="dev main master"
@@ -111,7 +124,7 @@ MSG
 fi
 
 if [[ "$is_protected_branch" == "1" ]]; then
-  if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" ]]; then
+  if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" && "$allow_vscode_protected_branch_writes" == "1" ]]; then
     exit 0
   fi
 
@@ -131,6 +144,9 @@ Use an agent branch first:
 After finishing work:
   bash scripts/agent-branch-finish.sh
 
+Optional repo override for manual VS Code protected-branch commits:
+  git config multiagent.allowVscodeProtectedBranchWrites true
+
 Temporary bypass (not recommended):
   ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
 MSG

package/templates/githooks/pre-push

@@ -10,6 +10,19 @@ if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n
   is_vscode_git_context=1
 fi
 
+allow_vscode_protected_raw="${MUSAFETY_ALLOW_VSCODE_PROTECTED_BRANCH_WRITES:-$(git config --get multiagent.allowVscodeProtectedBranchWrites || true)}"
+if [[ -z "$allow_vscode_protected_raw" ]]; then
+  allow_vscode_protected_raw="false"
+fi
+allow_vscode_protected="$(printf '%s' "$allow_vscode_protected_raw" | tr '[:upper:]' '[:lower:]')"
+
+allow_vscode_protected_branch_writes=0
+case "$allow_vscode_protected" in
+  1|true|yes|on) allow_vscode_protected_branch_writes=1 ;;
+  0|false|no|off) allow_vscode_protected_branch_writes=0 ;;
+  *) allow_vscode_protected_branch_writes=0 ;;
+esac
+
 is_codex_session=0
 if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}" == "1" ]]; then
   is_codex_session=1
@@ -56,14 +69,16 @@ if [[ "${#blocked_refs[@]}" -gt 0 ]]; then
     exit 1
   fi
 
-  if [[ "$is_vscode_git_context" == "1" ]]; then
+  if [[ "$is_vscode_git_context" == "1" && "$allow_vscode_protected_branch_writes" == "1" ]]; then
     exit 0
   fi
 
   {
-    echo "[agent-branch-guard] Push to protected branch blocked outside VS Code Git context."
+    echo "[agent-branch-guard] Push to protected branch blocked."
     echo "[agent-branch-guard] Protected target(s): ${blocked_refs[*]}"
-    echo "[agent-branch-guard] Use VS Code Source Control for protected-branch push, or push from an agent branch and merge via PR."
+    echo "[agent-branch-guard] Use an agent branch and merge via PR."
+    echo "[agent-branch-guard] Optional VS Code override:"
+    echo "  git config multiagent.allowVscodeProtectedBranchWrites true"
     echo
     echo "Temporary bypass (not recommended):"
     echo "  ALLOW_PUSH_ON_PROTECTED_BRANCH=1 git push ..."

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

@@ -545,7 +545,7 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
   fi
 
   if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
-    prune_args=(--base "$BASE_BRANCH" --delete-branches)
+    prune_args=(--base "$BASE_BRANCH" --only-dirty-worktrees --delete-branches)
     if [[ "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
       prune_args+=(--delete-remote-branches)
     fi

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

@@ -7,6 +7,7 @@ DRY_RUN=0
 FORCE_DIRTY=0
 DELETE_BRANCHES=0
 DELETE_REMOTE_BRANCHES=0
+ONLY_DIRTY_WORKTREES=0
 TARGET_BRANCH=""
 
 if [[ -n "$BASE_BRANCH" ]]; then
@@ -36,13 +37,17 @@ while [[ $# -gt 0 ]]; do
       DELETE_REMOTE_BRANCHES=1
       shift
       ;;
+    --only-dirty-worktrees)
+      ONLY_DIRTY_WORKTREES=1
+      shift
+      ;;
     --branch)
       TARGET_BRANCH="${2:-}"
       shift 2
       ;;
     *)
       echo "[agent-worktree-prune] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--branch <agent/...>]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--branch <agent/...>]" >&2
       exit 1
       ;;
   esac
@@ -56,6 +61,11 @@ fi
 repo_root="$(git rev-parse --show-toplevel)"
 current_pwd="$(pwd -P)"
 worktree_root="${repo_root}/.omx/agent-worktrees"
+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 } }'
+)"
+repo_common_dir="$(cd "$repo_common_dir" && pwd -P)"
 
 resolve_base_branch() {
   local configured=""
@@ -127,11 +137,98 @@ is_clean_worktree() {
     && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard)" ]]
 }
 
+resolve_worktree_common_dir() {
+  local wt="$1"
+  local common_dir=""
+  common_dir="$(git -C "$wt" rev-parse --git-common-dir 2>/dev/null || true)"
+  if [[ -z "$common_dir" ]]; then
+    return 1
+  fi
+  if [[ "$common_dir" == /* ]]; then
+    common_dir="$(cd "$common_dir" 2>/dev/null && pwd -P || true)"
+  else
+    common_dir="$(cd "$wt/$common_dir" 2>/dev/null && pwd -P || true)"
+  fi
+  if [[ -z "$common_dir" ]]; then
+    return 1
+  fi
+  printf '%s' "$common_dir"
+}
+
+select_unique_worktree_path() {
+  local root="$1"
+  local name="$2"
+  local candidate="${root}/${name}"
+  local suffix=2
+  while [[ -e "$candidate" ]]; do
+    candidate="${root}/${name}-${suffix}"
+    suffix=$((suffix + 1))
+  done
+  printf '%s' "$candidate"
+}
+
+relocated_foreign=0
+skipped_foreign=0
+
+relocate_foreign_worktree_entries() {
+  [[ -d "$worktree_root" ]] || return 0
+
+  local entry=""
+  for entry in "${worktree_root}"/*; do
+    [[ -d "$entry" ]] || continue
+    if ! git -C "$entry" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      continue
+    fi
+
+    local entry_common_dir=""
+    entry_common_dir="$(resolve_worktree_common_dir "$entry" || true)"
+    [[ -n "$entry_common_dir" ]] || continue
+
+    if [[ "$entry_common_dir" == "$repo_common_dir" ]]; then
+      continue
+    fi
+
+    if [[ "$(basename "$entry_common_dir")" != ".git" ]]; then
+      skipped_foreign=$((skipped_foreign + 1))
+      echo "[agent-worktree-prune] Skipping foreign worktree with unsupported git common dir: ${entry}"
+      continue
+    fi
+
+    local owner_repo_root
+    owner_repo_root="$(dirname "$entry_common_dir")"
+    local owner_worktree_root="${owner_repo_root}/.omx/agent-worktrees"
+    local target_path
+    target_path="$(select_unique_worktree_path "$owner_worktree_root" "$(basename "$entry")")"
+
+    if [[ "$entry" == "$current_pwd" || "$current_pwd" == "${entry}"/* ]]; then
+      skipped_foreign=$((skipped_foreign + 1))
+      echo "[agent-worktree-prune] Skipping active foreign worktree: ${entry}"
+      continue
+    fi
+
+    echo "[agent-worktree-prune] Relocating foreign worktree to owning repo: ${entry} -> ${target_path}"
+    if [[ "$DRY_RUN" -eq 1 ]]; then
+      relocated_foreign=$((relocated_foreign + 1))
+      continue
+    fi
+
+    mkdir -p "$owner_worktree_root"
+    if git -C "$owner_repo_root" worktree move "$entry" "$target_path" >/dev/null 2>&1; then
+      relocated_foreign=$((relocated_foreign + 1))
+    else
+      skipped_foreign=$((skipped_foreign + 1))
+      echo "[agent-worktree-prune] Failed to relocate foreign worktree: ${entry}" >&2
+    fi
+  done
+}
+
 removed_worktrees=0
 removed_branches=0
 skipped_active=0
 skipped_dirty=0
 
+relocate_foreign_worktree_entries
+
 process_entry() {
   local wt="$1"
   local branch_ref="$2"
@@ -165,6 +262,8 @@ process_entry() {
       if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
         remove_reason="merged-agent-branch"
       fi
+    elif [[ "$ONLY_DIRTY_WORKTREES" -eq 1 ]] && is_clean_worktree "$wt"; then
+      remove_reason="clean-agent-worktree"
     fi
   elif [[ "$branch" == __agent_integrate_* || "$branch" == __source-probe-* ]]; then
     remove_reason="temporary-worktree"
@@ -258,6 +357,9 @@ fi
 run_cmd git -C "$repo_root" worktree prune
 
 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 [[ "$relocated_foreign" -gt 0 || "$skipped_foreign" -gt 0 ]]; then
+  echo "[agent-worktree-prune] Foreign routing: relocated=${relocated_foreign}, skipped=${skipped_foreign}"
+fi
 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

package/templates/scripts/codex-agent.sh

@@ -285,13 +285,84 @@ auto_commit_worktree_changes() {
 
   local default_message="Auto-finish: ${TASK_NAME}"
   local commit_message="${MUSAFETY_CODEX_AUTO_COMMIT_MESSAGE:-$default_message}"
+  local commit_output=""
 
-  if ! git -C "$wt" commit -m "$commit_message" >/dev/null 2>&1; then
-    echo "[codex-agent] Auto-commit failed in sandbox. Keeping branch for manual review: $branch" >&2
+  if commit_output="$(git -C "$wt" commit -m "$commit_message" 2>&1)"; then
+    echo "[codex-agent] Auto-committed sandbox changes on '${branch}'."
+    return 0
+  fi
+
+  if auto_sync_for_commit_retry "$wt" "$branch"; then
+    claim_changed_files "$wt" "$branch"
+    git -C "$wt" add -A
+    if commit_output="$(git -C "$wt" commit -m "$commit_message" 2>&1)"; then
+      echo "[codex-agent] Auto-committed sandbox changes on '${branch}' after sync retry."
+      return 0
+    fi
+  fi
+
+  echo "[codex-agent] Auto-commit failed in sandbox. Keeping branch for manual review: $branch" >&2
+  if [[ -n "$commit_output" ]]; then
+    printf '%s\n' "$commit_output" >&2
+  fi
+  return 1
+}
+
+auto_sync_for_commit_retry() {
+  local wt="$1"
+  local branch="$2"
+
+  if ! has_origin_remote; then
+    return 1
+  fi
+
+  local base_branch
+  base_branch="$(resolve_worktree_base_branch "$wt")"
+  if [[ -z "$base_branch" ]]; then
     return 1
   fi
 
-  echo "[codex-agent] Auto-committed sandbox changes on '${branch}'."
+  if ! git -C "$wt" fetch origin "$base_branch" --quiet; then
+    return 1
+  fi
+
+  if ! git -C "$wt" show-ref --verify --quiet "refs/remotes/origin/${base_branch}"; then
+    return 1
+  fi
+
+  local behind_count
+  behind_count="$(git -C "$wt" rev-list --left-right --count "HEAD...origin/${base_branch}" 2>/dev/null | awk '{print $2}')"
+  behind_count="${behind_count:-0}"
+  if [[ "$behind_count" -le 0 ]]; then
+    return 1
+  fi
+
+  echo "[codex-agent] Auto-commit retry: '${branch}' is behind origin/${base_branch} by ${behind_count} commit(s). Syncing and retrying..."
+
+  local stash_ref=""
+  local stash_output=""
+  if worktree_has_changes "$wt"; then
+    if ! stash_output="$(git -C "$wt" stash push --include-untracked -m "codex-agent-autocommit-sync-${branch}-$(date +%s)" 2>&1)"; then
+      return 1
+    fi
+    stash_ref="$(printf '%s\n' "$stash_output" | grep -o 'stash@{[0-9]\+}' | head -n 1 || true)"
+  fi
+
+  if ! git -C "$wt" rebase "origin/${base_branch}" >/dev/null 2>&1; then
+    git -C "$wt" rebase --abort >/dev/null 2>&1 || true
+    if [[ -n "$stash_ref" ]]; then
+      git -C "$wt" stash pop "$stash_ref" >/dev/null 2>&1 || true
+    fi
+    return 1
+  fi
+
+  if [[ -n "$stash_ref" ]]; then
+    if ! git -C "$wt" stash pop "$stash_ref" >/dev/null 2>&1; then
+      echo "[codex-agent] Auto-commit retry could not re-apply local changes after sync. Manual resolution required in: $wt" >&2
+      return 1
+    fi
+  fi
+
   return 0
 }
 
@@ -419,7 +490,7 @@ if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
     prune_args+=(--base "$BASE_BRANCH")
   fi
   if [[ "$AUTO_CLEANUP" -eq 1 && "$auto_finish_completed" -eq 1 ]]; then
-    prune_args+=(--delete-branches --delete-remote-branches)
+    prune_args+=(--only-dirty-worktrees --delete-branches --delete-remote-branches)
   fi
   if ! bash "${repo_root}/scripts/agent-worktree-prune.sh" "${prune_args[@]}"; then
     echo "[codex-agent] Warning: automatic worktree cleanup failed." >&2