@imdeadpool/guardex 5.0.1 → 5.0.2

package/README.md

@@ -238,6 +238,10 @@ Use this exact checklist to setup multi-agent safety in this repository for Code
    - 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.
+   - `scripts/codex-agent.sh` now auto-runs this finish flow after Codex exits:
+     auto-commit changed files -> push/create PR -> merge attempt -> keep branch/worktree for follow-up.
+   - Remove merged branches when you are done reviewing:
+     gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 
 5) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
@@ -269,9 +273,11 @@ gx protect set <branch...> [--target <path>]
 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 cleanup [--target <path>] [--base <branch>] [--branch <agent/...>] [--dry-run] [--force-dirty] [--keep-remote]
 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   # manual stale worktree cleanup (auto base detection)
-bash scripts/agent-worktree-prune.sh --force-dirty   # remove stale dirty worktrees too
+bash scripts/agent-worktree-prune.sh   # prune temporary worktrees only (keeps merged agent branches by default)
+bash scripts/agent-worktree-prune.sh --delete-branches --delete-remote-branches   # full merged-branch cleanup
+bash scripts/agent-worktree-prune.sh --force-dirty --delete-branches   # force-remove dirty merged worktrees too
 bash scripts/openspec/init-plan-workspace.sh <plan-slug>   # optional OpenSpec plan scaffold
 ```
 
@@ -284,8 +290,14 @@ and asks `[y/N]` whether to update immediately (default is `N`).
 - 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.
+- In already-initialized repos, `setup` / `install` / `fix` block writes on protected `main` by default; start an agent branch first. Use `--allow-protected-base-write` only for emergency in-place maintenance.
+- `gx doctor` on protected `main` auto-starts an isolated `agent/gx/...-gx-doctor` worktree branch and applies repairs there.
+- `gx setup` and `gx doctor` always refresh `.githooks/pre-commit` from templates, so Codex sub-branch enforcement stays repaired.
+- `scripts/codex-agent.sh` now auto-runs finish automation after a Codex session when `origin` exists:
+  auto-commit changed files, run PR/merge automation, and keep merged agent branches/worktrees by default.
+  It also auto-syncs each sandbox branch against the latest base branch before task execution.
+  If conflicts remain, it keeps the sandbox and prompts for a conflict-resolution review pass.
+- use `gx cleanup` (or `gx cleanup --branch <agent/...>`) to remove merged branches/worktrees when done.
 
 ## Advanced commands
 
@@ -362,7 +374,7 @@ multiagent.protectedBranches
 ## What is protected
 
 - direct commits to protected branches (defaults: `dev`, `main`, `master`; configurable via `gx protect ...`)
-- protected-branch commits are blocked regardless of commit client (including VS Code Source Control)
+- protected-branch commits are blocked by default for all clients; Codex sessions only may commit protected branches when staged files are strictly `AGENTS.md` and/or `.gitignore`
 - Codex-session commits on non-`agent/*` branches are blocked by default (`multiagent.codexRequireAgentBranch=true`)
 - Codex commits attempted on protected branches trigger `guardex-preedit-guard` and require starting work via `scripts/codex-agent.sh`
 - overlapping file ownership between agents

package/bin/multiagent-safety.js

@@ -58,6 +58,8 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
   '.githooks/pre-commit',
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-worktree-prune.sh',
+  'scripts/codex-agent.sh',
   'scripts/agent-file-locks.py',
 ]);
 
@@ -88,6 +90,7 @@ const COMMAND_TYPO_ALIASES = new Map([
   ['intsall', 'install'],
   ['docter', 'doctor'],
   ['doctro', 'doctor'],
+  ['cleunup', 'cleanup'],
   ['scna', 'scan'],
 ]);
 const SUGGESTIBLE_COMMANDS = [
@@ -100,6 +103,7 @@ const SUGGESTIBLE_COMMANDS = [
   'copy-commands',
   'protect',
   'sync',
+  'cleanup',
   'release',
   'install',
   'fix',
@@ -118,6 +122,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['copy-commands', 'Print setup checklist as executable commands only'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
   ['sync', 'Check or sync agent branches with origin/<base>'],
+  ['cleanup', 'Cleanup merged agent branches/worktrees (local + remote)'],
   ['install', 'Install templates/locks/hooks without running full setup (supports --no-gitignore)'],
   ['fix', 'Repair broken or missing guardrail files/config (supports --no-gitignore)'],
   ['scan', 'Report safety issues and exit non-zero on findings'],
@@ -152,6 +157,9 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
    - 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.
+   - Finished branches stay available by default for audit/follow-up.
+     Remove them explicitly when done:
+     gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 
 5) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
@@ -174,6 +182,7 @@ bash scripts/codex-agent.sh "task" "agent-name"
 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)"
+gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
 gx protect add release staging
 gx sync --check
@@ -288,7 +297,10 @@ NOTES
   - 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
+  - In initialized repos, setup/install/fix block in-place writes on protected main by default
+  - doctor auto-starts a sandbox agent branch/worktree when run on protected main
+  - agent-branch-finish merges by default and keeps agent branches/worktrees until explicit cleanup
+  - use '${SHORT_TOOL_NAME} cleanup' to remove merged agent branches/worktrees (optionally remote refs too)
   - Legacy command aliases are still supported: ${LEGACY_NAMES.join(', ')}`);
 
   if (outsideGitRepo) {
@@ -362,6 +374,10 @@ function ensureExecutable(destinationPath, relativePath, dryRun) {
   }
 }
 
+function isCriticalGuardrailPath(relativePath) {
+  return CRITICAL_GUARDRAIL_PATHS.has(relativePath);
+}
+
 function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
   const sourcePath = path.join(TEMPLATE_ROOT, relativeTemplatePath);
   const destinationRelativePath = toDestinationPath(relativeTemplatePath);
@@ -376,7 +392,7 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
       ensureExecutable(destinationPath, destinationRelativePath, dryRun);
       return { status: 'unchanged', file: destinationRelativePath };
     }
-    if (!force) {
+    if (!force && !isCriticalGuardrailPath(destinationRelativePath)) {
       throw new Error(
         `Refusing to overwrite existing file without --force: ${destinationRelativePath}`,
       );
@@ -389,6 +405,10 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
   }
 
+  if (destinationExists && !force && isCriticalGuardrailPath(destinationRelativePath)) {
+    return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
+  }
+
   return { status: destinationExists ? 'overwritten' : 'created', file: destinationRelativePath };
 }
 
@@ -405,6 +425,14 @@ function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
       return { status: 'unchanged', file: destinationRelativePath };
     }
 
+    if (isCriticalGuardrailPath(destinationRelativePath)) {
+      if (!dryRun) {
+        fs.writeFileSync(destinationPath, sourceContent, 'utf8');
+        ensureExecutable(destinationPath, destinationRelativePath, dryRun);
+      }
+      return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
+    }
+
     // In fix mode, avoid silently replacing local customizations.
     return { status: 'skipped-conflict', file: destinationRelativePath };
   }
@@ -489,7 +517,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',
+    'agent:cleanup': `${SHORT_TOOL_NAME} cleanup`,
     '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',
@@ -671,34 +699,139 @@ function hasGuardexBootstrapFiles(repoRoot) {
   return required.every((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
 }
 
-function assertProtectedMainWriteAllowed(options, commandName) {
+function protectedBaseWriteBlock(options) {
   if (options.dryRun || options.allowProtectedBaseWrite) {
-    return;
+    return null;
   }
 
   const repoRoot = resolveRepoRoot(options.target);
   if (!hasGuardexBootstrapFiles(repoRoot)) {
-    return;
+    return null;
   }
 
   const branch = currentBranchName(repoRoot);
   if (branch !== 'main') {
-    return;
+    return null;
   }
 
   const protectedBranches = readProtectedBranches(repoRoot);
   if (!protectedBranches.includes(branch)) {
+    return null;
+  }
+
+  return {
+    repoRoot,
+    branch,
+  };
+}
+
+function assertProtectedMainWriteAllowed(options, commandName) {
+  const blocked = protectedBaseWriteBlock(options);
+  if (!blocked) {
     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` +
+    `${commandName} blocked on protected branch '${blocked.branch}' in an initialized repo.\n` +
+    `Keep local '${blocked.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 extractAgentBranchStartMetadata(output) {
+  const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
+  const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
+  return {
+    branch: branchMatch ? branchMatch[1].trim() : '',
+    worktreePath: worktreeMatch ? worktreeMatch[1].trim() : '',
+  };
+}
+
+function resolveSandboxTarget(repoRoot, worktreePath, targetPath) {
+  const resolvedTarget = path.resolve(targetPath);
+  const relativeTarget = path.relative(repoRoot, resolvedTarget);
+  if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
+    throw new Error(`doctor target must stay inside repo root when sandboxing: ${resolvedTarget}`);
+  }
+  if (!relativeTarget || relativeTarget === '.') {
+    return worktreePath;
+  }
+  return path.join(worktreePath, relativeTarget);
+}
+
+function buildSandboxDoctorArgs(options, sandboxTarget) {
+  const args = ['doctor', '--target', sandboxTarget];
+  if (options.dryRun) args.push('--dry-run');
+  if (options.skipAgents) args.push('--skip-agents');
+  if (options.skipPackageJson) args.push('--skip-package-json');
+  if (options.skipGitignore) args.push('--no-gitignore');
+  if (!options.dropStaleLocks) args.push('--keep-stale-locks');
+  if (options.json) args.push('--json');
+  return args;
+}
+
+function runDoctorInSandbox(options, blocked) {
+  const startScript = path.join(blocked.repoRoot, 'scripts', 'agent-branch-start.sh');
+  if (!fs.existsSync(startScript)) {
+    throw new Error(
+      `doctor sandbox fallback is unavailable because '${startScript}' is missing.\n` +
+      `Run '${SHORT_TOOL_NAME} setup --allow-protected-base-write' once to restore branch-start tooling.`,
+    );
+  }
+
+  const startResult = run('bash', [
+    startScript,
+    '--task',
+    `${SHORT_TOOL_NAME}-doctor`,
+    '--agent',
+    SHORT_TOOL_NAME,
+    '--base',
+    blocked.branch,
+  ], { cwd: blocked.repoRoot });
+  if (startResult.error) {
+    throw startResult.error;
+  }
+  if (startResult.status !== 0) {
+    throw new Error((startResult.stderr || startResult.stdout || 'failed to start doctor sandbox').trim());
+  }
+
+  const metadata = extractAgentBranchStartMetadata(startResult.stdout);
+  if (!metadata.worktreePath) {
+    throw new Error(`Failed to parse sandbox worktree from agent-branch-start output:\n${startResult.stdout}`);
+  }
+
+  const sandboxTarget = resolveSandboxTarget(blocked.repoRoot, metadata.worktreePath, options.target);
+  const nestedResult = run(
+    process.execPath,
+    [__filename, ...buildSandboxDoctorArgs(options, sandboxTarget)],
+    { cwd: metadata.worktreePath },
+  );
+  if (nestedResult.error) {
+    throw nestedResult.error;
+  }
+
+  if (options.json) {
+    if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
+    if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+  } else {
+    console.log(
+      `[${TOOL_NAME}] doctor detected protected branch '${blocked.branch}'. ` +
+      `Running repairs in sandbox branch '${metadata.branch || 'agent/<auto>'}'.`,
+    );
+    if (startResult.stdout) process.stdout.write(startResult.stdout);
+    if (startResult.stderr) process.stderr.write(startResult.stderr);
+    if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
+    if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+  }
+
+  if (typeof nestedResult.status === 'number') {
+    process.exitCode = nestedResult.status;
+    return;
+  }
+  process.exitCode = 1;
+}
+
 function parseTargetFlag(rawArgs, defaultTarget = process.cwd()) {
   const remaining = [];
   let target = defaultTarget;
@@ -1134,6 +1267,63 @@ function parseSyncArgs(rawArgs) {
   return options;
 }
 
+function parseCleanupArgs(rawArgs) {
+  const options = {
+    target: process.cwd(),
+    base: '',
+    branch: '',
+    dryRun: false,
+    forceDirty: false,
+    keepRemote: false,
+  };
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--target') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--target requires a path value');
+      }
+      options.target = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--base') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--base requires a branch value');
+      }
+      options.base = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--branch') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--branch requires an agent branch value');
+      }
+      options.branch = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === '--force-dirty') {
+      options.forceDirty = true;
+      continue;
+    }
+    if (arg === '--keep-remote') {
+      options.keepRemote = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return options;
+}
+
 function syncOperation(repoRoot, strategy, baseRef, ffOnly) {
   if (strategy === 'rebase') {
     if (ffOnly) {
@@ -1894,6 +2084,12 @@ function doctor(rawArgs) {
     allowProtectedBaseWrite: false,
   });
 
+  const blocked = protectedBaseWriteBlock(options);
+  if (blocked) {
+    runDoctorInSandbox(options, blocked);
+    return;
+  }
+
   assertProtectedMainWriteAllowed(options, 'doctor');
   const fixPayload = runFixInternal(options);
   const scanResult = runScanInternal({ target: options.target, json: false });
@@ -2156,6 +2352,39 @@ function copyCommands() {
   process.exitCode = 0;
 }
 
+function cleanup(rawArgs) {
+  const options = parseCleanupArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(options.target);
+  const pruneScript = path.join(repoRoot, 'scripts', 'agent-worktree-prune.sh');
+  if (!fs.existsSync(pruneScript)) {
+    throw new Error(`Missing cleanup script: ${pruneScript}. Run '${SHORT_TOOL_NAME} setup' first.`);
+  }
+
+  const args = [pruneScript];
+  if (options.base) {
+    args.push('--base', options.base);
+  }
+  if (options.branch) {
+    args.push('--branch', options.branch);
+  }
+  if (options.forceDirty) {
+    args.push('--force-dirty');
+  }
+  if (options.dryRun) {
+    args.push('--dry-run');
+  }
+  args.push('--delete-branches');
+  if (!options.keepRemote) {
+    args.push('--delete-remote-branches');
+  }
+
+  const runResult = run('bash', args, { cwd: repoRoot, stdio: 'inherit' });
+  if (runResult.status !== 0) {
+    throw new Error('Cleanup command failed');
+  }
+  process.exitCode = 0;
+}
+
 function sync(rawArgs) {
   const options = parseSyncArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -2504,6 +2733,11 @@ function main() {
     return;
   }
 
+  if (command === 'cleanup') {
+    cleanup(rest);
+    return;
+  }
+
   if (command === 'release') {
     release(rest);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "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

@@ -11,7 +11,11 @@
 - 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).
+- Agent completion defaults to `scripts/codex-agent.sh`, which auto-finishes the branch (auto-commit changed files, push/create PR, attempt merge, and pull the local base branch after merge).
+- Auto-finish keeps the sandbox branch/worktree by default so conflict follow-ups and audits stay reproducible.
+- Use explicit cleanup when done: `gx cleanup --branch "<agent-branch>"` (or `gx cleanup` for all merged agent branches).
+- If codex-agent auto-finish cannot complete, immediately run `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr` 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.
 - 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

@@ -36,4 +36,6 @@ gx scan
 - 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>"`.
+- `scripts/codex-agent.sh` auto-syncs the sandbox branch against base before each task and auto-finishes merge/PR flow after Codex exits.
+- Auto-finish keeps the branch/worktree by default; remove merged branches explicitly with `gx cleanup` (or `gx cleanup --branch "<agent-branch>"`).
 - Do not bypass protected branch safeguards unless explicitly required.

package/templates/githooks/pre-commit

@@ -50,9 +50,31 @@ case "$codex_require_agent_branch" in
   *) should_require_codex_agent_branch=1 ;;
 esac
 
+is_codex_managed_only_commit_on_protected=0
+if [[ "$is_codex_session" == "1" && "$is_protected_branch" == "1" ]]; then
+  deleted_paths="$(git diff --cached --name-only --diff-filter=D)"
+  staged_paths="$(git diff --cached --name-only --diff-filter=ACMRTUXB)"
+  if [[ -z "$deleted_paths" && -n "$staged_paths" ]]; then
+    managed_only=1
+    while IFS= read -r staged_path; do
+      case "$staged_path" in
+        AGENTS.md|.gitignore) ;;
+        *) managed_only=0; break ;;
+      esac
+    done <<< "$staged_paths"
+    if [[ "$managed_only" == "1" ]]; then
+      is_codex_managed_only_commit_on_protected=1
+    fi
+  fi
+fi
+
 if [[ "$should_require_codex_agent_branch" == "1" && "${MUSAFETY_ALLOW_CODEX_ON_NON_AGENT:-0}" != "1" ]]; then
   if [[ "$is_codex_session" == "1" && "$branch" != agent/* ]]; then
     if [[ "$is_protected_branch" == "1" ]]; then
+      if [[ "$is_codex_managed_only_commit_on_protected" == "1" ]]; then
+        exit 0
+      fi
+
       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.

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

@@ -5,9 +5,26 @@ BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=0
 SOURCE_BRANCH=""
 PUSH_ENABLED=1
-DELETE_REMOTE_BRANCH=1
+DELETE_REMOTE_BRANCH=0
+DELETE_REMOTE_BRANCH_EXPLICIT=0
 MERGE_MODE="auto"
 GH_BIN="${MUSAFETY_GH_BIN:-gh}"
+CLEANUP_AFTER_MERGE_RAW="${MUSAFETY_FINISH_CLEANUP:-false}"
+
+normalize_bool() {
+  local raw="${1:-}"
+  local fallback="${2:-0}"
+  local lowered
+  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
+  case "$lowered" in
+    1|true|yes|on) printf '1' ;;
+    0|false|no|off) printf '0' ;;
+    '') printf '%s' "$fallback" ;;
+    *) printf '%s' "$fallback" ;;
+  esac
+}
+
+CLEANUP_AFTER_MERGE="$(normalize_bool "$CLEANUP_AFTER_MERGE_RAW" "0")"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -26,6 +43,20 @@ while [[ $# -gt 0 ]]; do
       ;;
     --keep-remote-branch)
       DELETE_REMOTE_BRANCH=0
+      DELETE_REMOTE_BRANCH_EXPLICIT=1
+      shift
+      ;;
+    --delete-remote-branch)
+      DELETE_REMOTE_BRANCH=1
+      DELETE_REMOTE_BRANCH_EXPLICIT=1
+      shift
+      ;;
+    --cleanup)
+      CLEANUP_AFTER_MERGE=1
+      shift
+      ;;
+    --no-cleanup)
+      CLEANUP_AFTER_MERGE=0
       shift
       ;;
     --mode)
@@ -42,12 +73,16 @@ while [[ $# -gt 0 ]]; do
       ;;
     *)
       echo "[agent-branch-finish] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--branch <branch>] [--no-push] [--keep-remote-branch] [--mode auto|direct|pr|--via-pr|--direct-only]" >&2
+      echo "Usage: $0 [--base <branch>] [--branch <branch>] [--no-push] [--cleanup|--no-cleanup] [--keep-remote-branch|--delete-remote-branch] [--mode auto|direct|pr|--via-pr|--direct-only]" >&2
       exit 1
       ;;
   esac
 done
 
+if [[ "$CLEANUP_AFTER_MERGE" -eq 1 && "$DELETE_REMOTE_BRANCH_EXPLICIT" -eq 0 ]]; then
+  DELETE_REMOTE_BRANCH=1
+fi
+
 case "$MERGE_MODE" in
   auto|direct|pr) ;;
   *)
@@ -347,43 +382,58 @@ 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
 
-if [[ "$source_worktree" == "$repo_root" ]]; then
-  if is_clean_worktree "$source_worktree"; then
-    git -C "$source_worktree" checkout "$BASE_BRANCH" >/dev/null 2>&1 || true
-    if [[ "$PUSH_ENABLED" -eq 1 ]] && git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
-      git -C "$source_worktree" pull --ff-only origin "$BASE_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
+  git -C "$base_worktree" pull --ff-only origin "$BASE_BRANCH" >/dev/null 2>&1 || true
+fi
+
+if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
+  if [[ "$source_worktree" == "$repo_root" ]]; then
+    if is_clean_worktree "$source_worktree"; then
+      git -C "$source_worktree" checkout "$BASE_BRANCH" >/dev/null 2>&1 || true
+      if [[ "$PUSH_ENABLED" -eq 1 ]] && git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+        git -C "$source_worktree" pull --ff-only origin "$BASE_BRANCH" >/dev/null 2>&1 || true
+      fi
     fi
+  elif [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${repo_root}/.omx/agent-worktrees"/* ]]; then
+    git -C "$source_worktree" checkout --detach >/dev/null 2>&1 || true
   fi
-elif [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${repo_root}/.omx/agent-worktrees"/* ]]; then
-  git -C "$source_worktree" checkout --detach >/dev/null 2>&1 || true
-fi
 
-if [[ "$source_worktree" != "$current_worktree" && "$source_worktree" == "${repo_root}/.omx/agent-worktrees"/* ]]; then
-  git -C "$repo_root" worktree remove "$source_worktree" --force >/dev/null 2>&1 || true
-fi
+  if [[ "$source_worktree" != "$current_worktree" && "$source_worktree" == "${repo_root}/.omx/agent-worktrees"/* ]]; then
+    git -C "$repo_root" worktree remove "$source_worktree" --force >/dev/null 2>&1 || true
+  fi
 
-git -C "$repo_root" branch -d "$SOURCE_BRANCH"
+  git -C "$repo_root" branch -d "$SOURCE_BRANCH"
 
-if [[ "$PUSH_ENABLED" -eq 1 && "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
-  if git -C "$repo_root" ls-remote --exit-code --heads origin "$SOURCE_BRANCH" >/dev/null 2>&1; then
-    git -C "$repo_root" push origin --delete "$SOURCE_BRANCH"
+  if [[ "$PUSH_ENABLED" -eq 1 && "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
+    if git -C "$repo_root" ls-remote --exit-code --heads origin "$SOURCE_BRANCH" >/dev/null 2>&1; then
+      git -C "$repo_root" push origin --delete "$SOURCE_BRANCH"
+    fi
   fi
-fi
 
-base_worktree="$(get_worktree_for_branch "$BASE_BRANCH")"
-if [[ -n "$base_worktree" ]] && is_clean_worktree "$base_worktree" && [[ "$PUSH_ENABLED" -eq 1 ]]; then
-  git -C "$base_worktree" pull --ff-only origin "$BASE_BRANCH" >/dev/null 2>&1 || true
-fi
+  if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
+    prune_args=(--base "$BASE_BRANCH" --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
+  fi
 
-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: automatic worktree prune failed." >&2
-    echo "[agent-branch-finish] You can run manual cleanup: bash scripts/agent-worktree-prune.sh --base ${BASE_BRANCH}" >&2
+  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" == "${repo_root}/.omx/agent-worktrees"/* ]]; 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
+  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
   fi
-fi
 
-echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and removed branch."
-if [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${repo_root}/.omx/agent-worktrees"/* ]]; 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}" >&2
+  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"
 fi

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

@@ -5,6 +5,9 @@ BASE_BRANCH="${MUSAFETY_BASE_BRANCH:-}"
 BASE_BRANCH_EXPLICIT=0
 DRY_RUN=0
 FORCE_DIRTY=0
+DELETE_BRANCHES=0
+DELETE_REMOTE_BRANCHES=0
+TARGET_BRANCH=""
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -25,9 +28,21 @@ while [[ $# -gt 0 ]]; do
       FORCE_DIRTY=1
       shift
       ;;
+    --delete-branches)
+      DELETE_BRANCHES=1
+      shift
+      ;;
+    --delete-remote-branches)
+      DELETE_REMOTE_BRANCHES=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]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--branch <agent/...>]" >&2
       exit 1
       ;;
   esac
@@ -73,6 +88,11 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   exit 1
 fi
 
+if [[ -n "$TARGET_BRANCH" && "$TARGET_BRANCH" != agent/* ]]; then
+  echo "[agent-worktree-prune] --branch must reference an agent/* branch: ${TARGET_BRANCH}" >&2
+  exit 1
+fi
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
   BASE_BRANCH="$(resolve_base_branch)"
 fi
@@ -124,6 +144,10 @@ process_entry() {
     branch="${branch_ref#refs/heads/}"
   fi
 
+  if [[ -n "$TARGET_BRANCH" && "$branch" != "$TARGET_BRANCH" ]]; then
+    return
+  fi
+
   if [[ "$wt" == "$current_pwd" ]]; then
     skipped_active=$((skipped_active + 1))
     echo "[agent-worktree-prune] Skipping active cwd worktree: ${wt}"
@@ -138,7 +162,9 @@ process_entry() {
     remove_reason="missing-branch"
   elif [[ "$branch" == agent/* ]]; then
     if git -C "$repo_root" merge-base --is-ancestor "$branch" "$BASE_BRANCH"; then
-      remove_reason="merged-agent-branch"
+      if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
+        remove_reason="merged-agent-branch"
+      fi
     fi
   elif [[ "$branch" == __agent_integrate_* || "$branch" == __source-probe-* ]]; then
     remove_reason="temporary-worktree"
@@ -163,10 +189,16 @@ process_entry() {
   fi
 
   if git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}" && ! branch_has_worktree "$branch"; then
-    if [[ "$branch" == agent/* ]]; then
+    if [[ "$branch" == agent/* && "$DELETE_BRANCHES" -eq 1 ]]; then
       if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
         removed_branches=$((removed_branches + 1))
         echo "[agent-worktree-prune] Deleted merged branch: ${branch}"
+        if [[ "$DELETE_REMOTE_BRANCHES" -eq 1 ]]; then
+          if git -C "$repo_root" ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
+            run_cmd git -C "$repo_root" push origin --delete "$branch" >/dev/null 2>&1 || true
+            echo "[agent-worktree-prune] Deleted merged remote branch: ${branch}"
+          fi
+        fi
       fi
     elif [[ "$branch" == __agent_integrate_* || "$branch" == __source-probe-* ]]; then
       run_cmd git -C "$repo_root" branch -D "$branch" >/dev/null 2>&1 || true
@@ -199,18 +231,29 @@ done < <(git -C "$repo_root" worktree list --porcelain)
 
 process_entry "$current_wt" "$current_branch_ref"
 
-while IFS= read -r branch; do
-  [[ -z "$branch" ]] && continue
-  if branch_has_worktree "$branch"; then
-    continue
-  fi
-  if git -C "$repo_root" merge-base --is-ancestor "$branch" "$BASE_BRANCH"; then
-    if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
-      removed_branches=$((removed_branches + 1))
-      echo "[agent-worktree-prune] Deleted stale merged branch: ${branch}"
+if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
+  while IFS= read -r branch; do
+    [[ -z "$branch" ]] && continue
+    if [[ -n "$TARGET_BRANCH" && "$branch" != "$TARGET_BRANCH" ]]; then
+      continue
     fi
-  fi
-done < <(git -C "$repo_root" for-each-ref --format='%(refname:short)' refs/heads/agent)
+    if branch_has_worktree "$branch"; then
+      continue
+    fi
+    if git -C "$repo_root" merge-base --is-ancestor "$branch" "$BASE_BRANCH"; then
+      if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
+        removed_branches=$((removed_branches + 1))
+        echo "[agent-worktree-prune] Deleted stale merged branch: ${branch}"
+        if [[ "$DELETE_REMOTE_BRANCHES" -eq 1 ]]; then
+          if git -C "$repo_root" ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
+            run_cmd git -C "$repo_root" push origin --delete "$branch" >/dev/null 2>&1 || true
+            echo "[agent-worktree-prune] Deleted stale merged remote branch: ${branch}"
+          fi
+        fi
+      fi
+    fi
+  done < <(git -C "$repo_root" for-each-ref --format='%(refname:short)' refs/heads/agent)
+fi
 
 run_cmd git -C "$repo_root" worktree prune
 

package/templates/scripts/codex-agent.sh

@@ -6,6 +6,26 @@ AGENT_NAME="${MUSAFETY_AGENT_NAME:-agent}"
 BASE_BRANCH="${MUSAFETY_BASE_BRANCH:-}"
 BASE_BRANCH_EXPLICIT=0
 CODEX_BIN="${MUSAFETY_CODEX_BIN:-codex}"
+AUTO_FINISH_RAW="${MUSAFETY_CODEX_AUTO_FINISH:-true}"
+AUTO_REVIEW_ON_CONFLICT_RAW="${MUSAFETY_CODEX_AUTO_REVIEW_ON_CONFLICT:-true}"
+AUTO_CLEANUP_RAW="${MUSAFETY_CODEX_AUTO_CLEANUP:-false}"
+
+normalize_bool() {
+  local raw="${1:-}"
+  local fallback="${2:-0}"
+  local lowered
+  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
+  case "$lowered" in
+    1|true|yes|on) printf '1' ;;
+    0|false|no|off) printf '0' ;;
+    '') printf '%s' "$fallback" ;;
+    *) printf '%s' "$fallback" ;;
+  esac
+}
+
+AUTO_FINISH="$(normalize_bool "$AUTO_FINISH_RAW" "1")"
+AUTO_REVIEW_ON_CONFLICT="$(normalize_bool "$AUTO_REVIEW_ON_CONFLICT_RAW" "1")"
+AUTO_CLEANUP="$(normalize_bool "$AUTO_CLEANUP_RAW" "0")"
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -30,6 +50,30 @@ while [[ $# -gt 0 ]]; do
       CODEX_BIN="${2:-$CODEX_BIN}"
       shift 2
       ;;
+    --auto-finish)
+      AUTO_FINISH=1
+      shift
+      ;;
+    --no-auto-finish)
+      AUTO_FINISH=0
+      shift
+      ;;
+    --auto-review-on-conflict)
+      AUTO_REVIEW_ON_CONFLICT=1
+      shift
+      ;;
+    --no-auto-review-on-conflict)
+      AUTO_REVIEW_ON_CONFLICT=0
+      shift
+      ;;
+    --cleanup)
+      AUTO_CLEANUP=1
+      shift
+      ;;
+    --no-cleanup)
+      AUTO_CLEANUP=0
+      shift
+      ;;
     --)
       shift
       break
@@ -95,6 +139,221 @@ if [[ ! -d "$worktree_path" ]]; then
   exit 1
 fi
 
+has_origin_remote() {
+  git -C "$repo_root" remote get-url origin >/dev/null 2>&1
+}
+
+resolve_worktree_base_branch() {
+  local wt="$1"
+  if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -n "$BASE_BRANCH" ]]; then
+    printf '%s' "$BASE_BRANCH"
+    return 0
+  fi
+
+  local branch
+  branch="$(git -C "$wt" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  if [[ -z "$branch" || "$branch" == "HEAD" ]]; then
+    return 0
+  fi
+
+  local stored_base
+  stored_base="$(git -C "$repo_root" config --get "branch.${branch}.musafetyBase" || true)"
+  if [[ -n "$stored_base" ]]; then
+    printf '%s' "$stored_base"
+    return 0
+  fi
+
+  local configured_base
+  configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
+  if [[ -n "$configured_base" ]]; then
+    printf '%s' "$configured_base"
+  fi
+}
+
+sync_worktree_with_base() {
+  local wt="$1"
+  if ! has_origin_remote; then
+    return 0
+  fi
+
+  local base_branch
+  base_branch="$(resolve_worktree_base_branch "$wt")"
+  if [[ -z "$base_branch" ]]; then
+    return 0
+  fi
+
+  if ! git -C "$wt" fetch origin "$base_branch" --quiet; then
+    echo "[codex-agent] Warning: could not fetch origin/${base_branch} before task start." >&2
+    return 0
+  fi
+
+  if ! git -C "$wt" show-ref --verify --quiet "refs/remotes/origin/${base_branch}"; then
+    return 0
+  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 0
+  fi
+
+  local branch
+  branch="$(git -C "$wt" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  echo "[codex-agent] Task sync: '${branch}' is behind origin/${base_branch} by ${behind_count} commit(s). Rebasing before launch..."
+  if ! git -C "$wt" rebase "origin/${base_branch}"; then
+    echo "[codex-agent] Task sync failed. Resolve and continue in sandbox:" >&2
+    echo "  git -C \"$wt\" rebase --continue" >&2
+    echo "  # or abort" >&2
+    echo "  git -C \"$wt\" rebase --abort" >&2
+    return 1
+  fi
+  echo "[codex-agent] Task sync complete."
+  return 0
+}
+
+worktree_has_changes() {
+  local wt="$1"
+  if ! git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json"; then
+    return 0
+  fi
+  if ! git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json"; then
+    return 0
+  fi
+  if [[ -n "$(git -C "$wt" ls-files --others --exclude-standard)" ]]; then
+    return 0
+  fi
+  return 1
+}
+
+claim_changed_files() {
+  local wt="$1"
+  local branch="$2"
+  local lock_script="${repo_root}/scripts/agent-file-locks.py"
+
+  if [[ ! -x "$lock_script" ]]; then
+    return 0
+  fi
+
+  local changed_raw deleted_raw
+  changed_raw="$({
+    git -C "$wt" diff --name-only -- . ":(exclude).omx/state/agent-file-locks.json";
+    git -C "$wt" diff --cached --name-only -- . ":(exclude).omx/state/agent-file-locks.json";
+    git -C "$wt" ls-files --others --exclude-standard;
+  } | sed '/^$/d' | sort -u)"
+
+  if [[ -n "$changed_raw" ]]; then
+    mapfile -t changed_files < <(printf '%s\n' "$changed_raw")
+    python3 "$lock_script" claim --branch "$branch" "${changed_files[@]}" >/dev/null 2>&1 || true
+  fi
+
+  deleted_raw="$({
+    git -C "$wt" diff --name-only --diff-filter=D -- . ":(exclude).omx/state/agent-file-locks.json";
+    git -C "$wt" diff --cached --name-only --diff-filter=D -- . ":(exclude).omx/state/agent-file-locks.json";
+  } | sed '/^$/d' | sort -u)"
+
+  if [[ -n "$deleted_raw" ]]; then
+    mapfile -t deleted_files < <(printf '%s\n' "$deleted_raw")
+    python3 "$lock_script" allow-delete --branch "$branch" "${deleted_files[@]}" >/dev/null 2>&1 || true
+  fi
+}
+
+auto_commit_worktree_changes() {
+  local wt="$1"
+  local branch="$2"
+
+  if ! worktree_has_changes "$wt"; then
+    return 0
+  fi
+
+  claim_changed_files "$wt" "$branch"
+  git -C "$wt" add -A
+
+  if git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json"; then
+    return 0
+  fi
+
+  local default_message="Auto-finish: ${TASK_NAME}"
+  local commit_message="${MUSAFETY_CODEX_AUTO_COMMIT_MESSAGE:-$default_message}"
+
+  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
+    return 1
+  fi
+
+  echo "[codex-agent] Auto-committed sandbox changes on '${branch}'."
+  return 0
+}
+
+looks_like_conflict_failure() {
+  local output="$1"
+  if grep -qiE 'preflight conflict detected|merge conflict detected|auto-sync failed while rebasing|rebase --continue|rebase --abort' <<< "$output"; then
+    return 0
+  fi
+  return 1
+}
+
+run_finish_flow() {
+  local wt="$1"
+  local branch="$2"
+  local finish_output=""
+  local -a finish_args
+
+  finish_args=(--branch "$branch")
+  if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
+    finish_args+=(--base "$BASE_BRANCH")
+  fi
+  if [[ "$AUTO_CLEANUP" -eq 1 ]]; then
+    finish_args+=(--cleanup)
+  fi
+
+  if has_origin_remote; then
+    if command -v gh >/dev/null 2>&1 || command -v "${MUSAFETY_GH_BIN:-gh}" >/dev/null 2>&1; then
+      finish_args+=(--via-pr)
+    fi
+  else
+    echo "[codex-agent] No origin remote detected; skipping auto-finish merge/PR pipeline." >&2
+    return 2
+  fi
+
+  if finish_output="$(bash "${repo_root}/scripts/agent-branch-finish.sh" "${finish_args[@]}" 2>&1)"; then
+    printf '%s\n' "$finish_output"
+    return 0
+  fi
+
+  printf '%s\n' "$finish_output" >&2
+
+  if [[ "$AUTO_REVIEW_ON_CONFLICT" -eq 1 ]] && looks_like_conflict_failure "$finish_output"; then
+    echo "[codex-agent] Auto-finish hit conflicts. Launching Codex conflict-review pass in sandbox..." >&2
+    local review_prompt
+    review_prompt="Resolve git conflicts for branch ${branch} against ${BASE_BRANCH:-base branch}, then commit the resolution in this sandbox worktree and exit."
+
+    (
+      cd "$wt"
+      set +e
+      "$CODEX_BIN" "$review_prompt"
+      review_exit="$?"
+      set -e
+      if [[ "$review_exit" -ne 0 ]]; then
+        echo "[codex-agent] Conflict-review Codex pass exited with status ${review_exit}." >&2
+      fi
+    )
+
+    if finish_output="$(bash "${repo_root}/scripts/agent-branch-finish.sh" "${finish_args[@]}" 2>&1)"; then
+      printf '%s\n' "$finish_output"
+      return 0
+    fi
+
+    printf '%s\n' "$finish_output" >&2
+  fi
+
+  return 1
+}
+
+if ! sync_worktree_with_base "$worktree_path"; then
+  exit 1
+fi
+
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"
 cd "$worktree_path"
 set +e
@@ -103,6 +362,38 @@ codex_exit="$?"
 set -e
 
 cd "$repo_root"
+final_exit="$codex_exit"
+auto_finish_completed=0
+
+worktree_branch="$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+
+if [[ "$AUTO_FINISH" -eq 1 && -n "$worktree_branch" && "$worktree_branch" != "HEAD" ]]; then
+  if [[ "$AUTO_CLEANUP" -eq 1 ]]; then
+    echo "[codex-agent] Auto-finish enabled: commit -> push/PR -> merge -> cleanup."
+  else
+    echo "[codex-agent] Auto-finish enabled: commit -> push/PR -> merge (keep branch/worktree)."
+  fi
+  if auto_commit_worktree_changes "$worktree_path" "$worktree_branch"; then
+    if run_finish_flow "$worktree_path" "$worktree_branch"; then
+      auto_finish_completed=1
+      echo "[codex-agent] Auto-finish completed for '${worktree_branch}'."
+    else
+      finish_status="$?"
+      if [[ "$finish_status" -eq 2 ]]; then
+        echo "[codex-agent] Auto-finish skipped for '${worktree_branch}' (no mergeable remote context)." >&2
+      else
+        echo "[codex-agent] Auto-finish did not complete; keeping sandbox for manual review: $worktree_path" >&2
+        if [[ "$final_exit" -eq 0 ]]; then
+          final_exit=1
+        fi
+      fi
+    fi
+  else
+    if [[ "$final_exit" -eq 0 ]]; then
+      final_exit=1
+    fi
+  fi
+fi
 
 if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
   echo "[codex-agent] Session ended (exit=${codex_exit}). Running worktree cleanup..."
@@ -110,6 +401,9 @@ if [[ -x "${repo_root}/scripts/agent-worktree-prune.sh" ]]; then
   if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
     prune_args+=(--base "$BASE_BRANCH")
   fi
+  if [[ "$AUTO_CLEANUP" -eq 1 ]]; then
+    prune_args+=(--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
   fi
@@ -121,8 +415,13 @@ 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}\""
+    if [[ "$auto_finish_completed" -eq 1 ]]; then
+      echo "[codex-agent] Branch kept intentionally. Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
+    else
+      echo "[codex-agent] If finished, merge with: bash scripts/agent-branch-finish.sh --branch \"${worktree_branch}\" --via-pr"
+      echo "[codex-agent] Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
+    fi
   fi
 fi
 
-exit "$codex_exit"
+exit "$final_exit"