@imdeadpool/guardex 7.0.14 → 7.0.16

package/bin/multiagent-safety.js

@@ -64,7 +64,7 @@ const REQUIRED_SYSTEM_TOOLS = [
   },
 ];
 const MAINTAINER_RELEASE_REPO = path.resolve(
-  process.env.GUARDEX_RELEASE_REPO || '/tmp/multiagent-safety',
+  process.env.GUARDEX_RELEASE_REPO || path.resolve(__dirname, '..'),
 );
 const NPM_BIN = process.env.GUARDEX_NPM_BIN || 'npm';
 const OPENSPEC_BIN = process.env.GUARDEX_OPENSPEC_BIN || 'openspec';
@@ -77,13 +77,21 @@ const DEFAULT_PROTECTED_BRANCHES = ['dev', 'main', 'master'];
 const DEFAULT_BASE_BRANCH = 'dev';
 const DEFAULT_SYNC_STRATEGY = 'rebase';
 const DEFAULT_SHADOW_CLEANUP_IDLE_MINUTES = 60;
+const COMPOSE_HINT_FILES = [
+  'docker-compose.yml',
+  'docker-compose.yaml',
+  'compose.yml',
+  'compose.yaml',
+];
 
 const TEMPLATE_ROOT = path.resolve(__dirname, '..', 'templates');
 
 const TEMPLATE_FILES = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
   'scripts/codex-agent.sh',
+  'scripts/guardex-docker-loader.sh',
   'scripts/review-bot-watch.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
@@ -105,6 +113,8 @@ const TEMPLATE_FILES = [
 const REQUIRED_WORKFLOW_FILES = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
+  'scripts/guardex-docker-loader.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
   'scripts/guardex-env.sh',
@@ -118,6 +128,7 @@ const REQUIRED_PACKAGE_SCRIPTS = {
   '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:branch:merge': 'bash ./scripts/agent-branch-merge.sh',
   'agent:cleanup': 'gx cleanup',
   'agent:hooks:install': 'bash ./scripts/install-agent-git-hooks.sh',
   'agent:locks:claim': 'python3 ./scripts/agent-file-locks.py claim',
@@ -133,6 +144,7 @@ const REQUIRED_PACKAGE_SCRIPTS = {
   'agent:safety:scan': 'gx status --strict',
   'agent:safety:fix': 'gx setup --repair',
   'agent:safety:doctor': 'gx doctor',
+  'agent:docker:load': 'bash ./scripts/guardex-docker-loader.sh',
   'agent:review:watch': 'bash ./scripts/review-bot-watch.sh',
   'agent:finish': 'gx finish --all',
 };
@@ -140,7 +152,9 @@ const REQUIRED_PACKAGE_SCRIPTS = {
 const EXECUTABLE_RELATIVE_PATHS = new Set([
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
   'scripts/codex-agent.sh',
+  'scripts/guardex-docker-loader.sh',
   'scripts/review-bot-watch.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
@@ -161,6 +175,7 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
   '.githooks/post-checkout',
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/codex-agent.sh',
   'scripts/agent-file-locks.py',
@@ -173,10 +188,18 @@ 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 CODEX_WORKTREE_RELATIVE_DIR = path.join('.omx', 'agent-worktrees');
+const CLAUDE_WORKTREE_RELATIVE_DIR = path.join('.omc', 'agent-worktrees');
+const AGENT_WORKTREE_RELATIVE_DIRS = [
+  CODEX_WORKTREE_RELATIVE_DIR,
+  CLAUDE_WORKTREE_RELATIVE_DIR,
+];
 const MANAGED_GITIGNORE_PATHS = [
   '.omx/',
   '.omc/',
   'scripts/*',
+  'scripts/agent-branch-start.sh',
+  'scripts/agent-file-locks.py',
   '.githooks',
   'oh-my-codex/',
   '.codex/skills/gitguardex/SKILL.md',
@@ -190,7 +213,9 @@ const OMX_SCAFFOLD_DIRECTORIES = [
   '.omx/state',
   '.omx/logs',
   '.omx/plans',
-  '.omx/agent-worktrees',
+  CODEX_WORKTREE_RELATIVE_DIR,
+  '.omc',
+  CLAUDE_WORKTREE_RELATIVE_DIR,
 ];
 const OMX_SCAFFOLD_FILES = new Map([
   ['.omx/notepad.md', '\n\n## WORKING MEMORY\n'],
@@ -213,6 +238,7 @@ const SUGGESTIBLE_COMMANDS = [
   'setup',
   'doctor',
   'agents',
+  'merge',
   'finish',
   'report',
   'protect',
@@ -237,9 +263,11 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target)'],
   ['doctor', 'Repair drift + verify (auto-sandboxes on protected main)'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
+  ['merge', 'Create/reuse an integration lane and merge overlapping agent branches'],
   ['sync', 'Sync agent branches with origin/<base>'],
   ['finish', 'Commit + PR + merge completed agent branches (--all, --branch)'],
   ['cleanup', 'Prune merged/stale agent branches and worktrees'],
+  ['release', 'Create or update the current GitHub release with README-generated notes'],
   ['agents', 'Start/stop repo-scoped review + cleanup bots'],
   ['prompt', 'Print AI setup checklist (--exec, --snippet)'],
   ['report', 'Security/safety reports (e.g. OpenSSF scorecard)'],
@@ -259,6 +287,22 @@ const DEPRECATED_COMMAND_ALIASES = new Map([
 const AGENT_BOT_DESCRIPTIONS = [
   ['agents', 'Start/stop review + cleanup bots for this repo'],
 ];
+const DOCTOR_AUTO_FINISH_DETAIL_LIMIT = 6;
+const DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX = 72;
+const DOCTOR_AUTO_FINISH_MESSAGE_MAX = 160;
+
+function envFlagIsTruthy(raw) {
+  const lowered = String(raw || '').trim().toLowerCase();
+  return lowered === '1' || lowered === 'true' || lowered === 'yes' || lowered === 'on';
+}
+
+function isClaudeCodeSession(env = process.env) {
+  return envFlagIsTruthy(env.CLAUDECODE) || Boolean(env.CLAUDE_CODE_SESSION_ID);
+}
+
+function defaultAgentWorktreeRelativeDir(env = process.env) {
+  return isClaudeCodeSession(env) ? CLAUDE_WORKTREE_RELATIVE_DIR : CODEX_WORKTREE_RELATIVE_DIR;
+}
 
 const AI_SETUP_PROMPT = `GitGuardex (gx) setup checklist for Codex/Claude in this repo.
 
@@ -267,13 +311,14 @@ const AI_SETUP_PROMPT = `GitGuardex (gx) setup checklist for Codex/Claude in thi
 3) Repair:     gx doctor
 4) Task loop:  bash scripts/codex-agent.sh "<task>" "<agent>"
                or branch-start -> python3 scripts/agent-file-locks.py claim -> branch-finish
-5) Finish:     gx finish --all
-6) Cleanup:    gx cleanup
-7) OpenSpec:   /opsx:propose -> /opsx:apply -> /opsx:archive
-8) Optional:   gx protect add release staging
-9) Optional:   gx sync --check && gx sync
-10) Review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY
-11) Fork sync:  install https://github.com/apps/pull + cp .github/pull.yml.example .github/pull.yml
+5) Integrate:  gx merge --branch <agent-a> --branch <agent-b>
+6) Finish:     gx finish --all
+7) Cleanup:    gx cleanup
+8) OpenSpec:   /opsx:propose -> /opsx:apply -> /opsx:archive
+9) Optional:   gx protect add release staging
+10) Optional:  gx sync --check && gx sync
+11) Review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY
+12) Fork sync:  install https://github.com/apps/pull + cp .github/pull.yml.example .github/pull.yml
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
@@ -282,6 +327,7 @@ gx setup
 gx doctor
 bash scripts/codex-agent.sh "<task>" "<agent>"
 python3 scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>
+gx merge --branch "<agent-a>" --branch "<agent-b>"
 gx finish --all
 gx cleanup
 gx protect add release staging
@@ -470,6 +516,113 @@ function run(cmd, args, options = {}) {
   });
 }
 
+function formatElapsedDuration(ms) {
+  const durationMs = Number.isFinite(ms) ? Math.max(0, ms) : 0;
+  if (durationMs < 1000) {
+    return `${Math.round(durationMs)}ms`;
+  }
+  if (durationMs < 10_000) {
+    return `${(durationMs / 1000).toFixed(1)}s`;
+  }
+  return `${Math.round(durationMs / 1000)}s`;
+}
+
+function truncateMiddle(value, maxLength) {
+  const text = String(value || '');
+  const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
+  if (!limit || text.length <= limit) {
+    return text;
+  }
+
+  const visible = limit - 1;
+  const headLength = Math.ceil(visible / 2);
+  const tailLength = Math.floor(visible / 2);
+  return `${text.slice(0, headLength)}…${text.slice(text.length - tailLength)}`;
+}
+
+function truncateTail(value, maxLength) {
+  const text = String(value || '');
+  const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
+  if (!limit || text.length <= limit) {
+    return text;
+  }
+  return `${text.slice(0, limit - 1)}…`;
+}
+
+function compactAutoFinishPathSegments(message) {
+  return String(message || '').replace(/\((\/[^)]+)\)/g, (_, rawPath) => {
+    if (
+      rawPath.includes(`${path.sep}.omx${path.sep}agent-worktrees${path.sep}`) ||
+      rawPath.includes(`${path.sep}.omc${path.sep}agent-worktrees${path.sep}`)
+    ) {
+      return `(${path.basename(rawPath)})`;
+    }
+    return `(${truncateMiddle(rawPath, 72)})`;
+  });
+}
+
+function summarizeAutoFinishDetail(detail) {
+  const trimmed = String(detail || '').trim();
+  const match = trimmed.match(/^\[(\w+)\]\s+([^:]+):\s*(.*)$/);
+  if (!match) {
+    return truncateTail(compactAutoFinishPathSegments(trimmed), DOCTOR_AUTO_FINISH_MESSAGE_MAX);
+  }
+
+  const [, status, rawBranch, rawMessage] = match;
+  const branch = truncateMiddle(rawBranch, DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX);
+  let message = String(rawMessage || '').trim();
+
+  if (status === 'fail') {
+    message = message.replace(/^auto-finish failed\.?\s*/i, '');
+    if (/\[agent-sync-guard\]/.test(message) && /Resolve conflicts/i.test(message)) {
+      message = 'rebase conflict in finish flow; run rebase --continue or rebase --abort in the source-probe worktree';
+    } else if (/unable to compute ahead\/behind/i.test(message)) {
+      const aheadBehindMatch = message.match(/unable to compute ahead\/behind(?: \([^)]+\))?/i);
+      if (aheadBehindMatch) {
+        message = aheadBehindMatch[0];
+      }
+    } else if (/remote ref does not exist/i.test(message)) {
+      message = 'branch merged, but the remote ref was already removed during cleanup';
+    }
+  }
+
+  message = compactAutoFinishPathSegments(message)
+    .replace(/\s+\|\s+/g, '; ')
+    .trim();
+
+  return `[${status}] ${branch}: ${truncateTail(message, DOCTOR_AUTO_FINISH_MESSAGE_MAX)}`;
+}
+
+function printAutoFinishSummary(summary, options = {}) {
+  const enabled = Boolean(summary && summary.enabled);
+  const details = Array.isArray(summary && summary.details) ? summary.details : [];
+  const baseBranch = String(options.baseBranch || summary?.baseBranch || '').trim();
+  const verbose = Boolean(options.verbose);
+  const detailLimit = Number.isFinite(options.detailLimit)
+    ? Math.max(0, options.detailLimit)
+    : DOCTOR_AUTO_FINISH_DETAIL_LIMIT;
+
+  if (enabled) {
+    console.log(
+      `[${TOOL_NAME}] Auto-finish sweep (base=${baseBranch}): attempted=${summary.attempted}, completed=${summary.completed}, skipped=${summary.skipped}, failed=${summary.failed}`,
+    );
+    const visibleDetails = verbose ? details : details.slice(0, detailLimit).map(summarizeAutoFinishDetail);
+    for (const detail of visibleDetails) {
+      console.log(`[${TOOL_NAME}]   ${detail}`);
+    }
+    if (!verbose && details.length > detailLimit) {
+      console.log(
+        `[${TOOL_NAME}]   … ${details.length - detailLimit} more branch result(s). Re-run with --verbose-auto-finish for full details.`,
+      );
+    }
+    return;
+  }
+
+  if (details.length > 0) {
+    console.log(`[${TOOL_NAME}] ${verbose ? details[0] : summarizeAutoFinishDetail(details[0])}`);
+  }
+}
+
 function gitRun(repoRoot, args, { allowFailure = false } = {}) {
   const result = run('git', ['-C', repoRoot, ...args]);
   if (!allowFailure && result.status !== 0) {
@@ -509,8 +662,6 @@ const NESTED_REPO_DEFAULT_SKIP_DIRS = new Set([
   '.venv',
   '.pnpm-store',
 ]);
-const NESTED_REPO_WORKTREE_RELATIVE_DIR = path.join('.omx', 'agent-worktrees');
-
 function discoverNestedGitRepos(rootPath, opts = {}) {
   const maxDepth = Number.isFinite(opts.maxDepth) ? Math.max(1, opts.maxDepth) : NESTED_REPO_DEFAULT_MAX_DEPTH;
   const extraSkip = new Set(Array.isArray(opts.extraSkip) ? opts.extraSkip : []);
@@ -525,7 +676,7 @@ function discoverNestedGitRepos(rootPath, opts = {}) {
     return path.resolve(resolvedRoot, raw);
   })();
 
-  const workreeSkipAbsolute = path.join(resolvedRoot, NESTED_REPO_WORKTREE_RELATIVE_DIR);
+  const worktreeSkipAbsolutes = AGENT_WORKTREE_RELATIVE_DIRS.map((relativeDir) => path.join(resolvedRoot, relativeDir));
   const found = new Set();
   found.add(resolvedRoot);
 
@@ -557,7 +708,7 @@ function discoverNestedGitRepos(rootPath, opts = {}) {
 
       if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
       if (shouldSkipDir(entry.name)) continue;
-      if (entryPath === workreeSkipAbsolute) continue;
+      if (worktreeSkipAbsolutes.includes(entryPath)) continue;
       walk(entryPath, depth + 1);
     }
   }
@@ -1000,6 +1151,14 @@ function parseCommonArgs(rawArgs, defaults) {
       options.allowProtectedBaseWrite = true;
       continue;
     }
+    if (Object.prototype.hasOwnProperty.call(options, 'waitForMerge') && arg === '--wait-for-merge') {
+      options.waitForMerge = true;
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(options, 'waitForMerge') && arg === '--no-wait-for-merge') {
+      options.waitForMerge = false;
+      continue;
+    }
 
     throw new Error(`Unknown option: ${arg}`);
   }
@@ -1081,7 +1240,7 @@ function parseSetupArgs(rawArgs, defaults) {
 }
 
 function parseDoctorArgs(rawArgs) {
-  return parseRepoTraversalArgs(rawArgs, {
+  const doctorDefaults = {
     target: process.cwd(),
     dropStaleLocks: true,
     skipAgents: false,
@@ -1090,7 +1249,25 @@ function parseDoctorArgs(rawArgs) {
     dryRun: false,
     json: false,
     allowProtectedBaseWrite: false,
-  });
+    waitForMerge: true,
+    verboseAutoFinish: false,
+  };
+  const forwardedArgs = [];
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--verbose-auto-finish') {
+      doctorDefaults.verboseAutoFinish = true;
+      continue;
+    }
+    if (arg === '--compact-auto-finish') {
+      doctorDefaults.verboseAutoFinish = false;
+      continue;
+    }
+    forwardedArgs.push(arg);
+  }
+
+  return parseRepoTraversalArgs(forwardedArgs, doctorDefaults);
 }
 
 function normalizeWorkspacePath(relativePath) {
@@ -1102,16 +1279,15 @@ function buildParentWorkspaceView(repoRoot) {
   const workspaceFileName = `${path.basename(repoRoot)}-branches.code-workspace`;
   const workspacePath = path.join(parentDir, workspaceFileName);
   const repoRelativePath = normalizeWorkspacePath(path.relative(parentDir, repoRoot) || '.');
-  const worktreesRelativePath = normalizeWorkspacePath(
-    path.join(repoRelativePath === '.' ? '' : repoRelativePath, '.omx', 'agent-worktrees'),
-  );
 
   return {
     workspacePath,
     payload: {
       folders: [
         { path: repoRelativePath },
-        { path: worktreesRelativePath },
+        ...AGENT_WORKTREE_RELATIVE_DIRS.map((relativeDir) => ({
+          path: normalizeWorkspacePath(path.join(repoRelativePath === '.' ? '' : repoRelativePath, relativeDir)),
+        })),
       ],
       settings: {
         'scm.alwaysShowRepositories': true,
@@ -1195,6 +1371,40 @@ function assertProtectedMainWriteAllowed(options, commandName) {
   );
 }
 
+function runSetupBootstrapInternal(options) {
+  const installPayload = runInstallInternal(options);
+  installPayload.operations.push(
+    ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(options.dryRun)),
+  );
+
+  let parentWorkspace = null;
+  if (options.parentWorkspaceView) {
+    installPayload.operations.push(
+      ensureParentWorkspaceView(installPayload.repoRoot, Boolean(options.dryRun)),
+    );
+    if (!options.dryRun) {
+      parentWorkspace = buildParentWorkspaceView(installPayload.repoRoot);
+    }
+  }
+
+  const fixPayload = runFixInternal({
+    target: installPayload.repoRoot,
+    dryRun: options.dryRun,
+    force: options.force,
+    dropStaleLocks: true,
+    skipAgents: options.skipAgents,
+    skipPackageJson: options.skipPackageJson,
+    skipGitignore: options.skipGitignore,
+    allowProtectedBaseWrite: options.allowProtectedBaseWrite,
+  });
+
+  return {
+    installPayload,
+    fixPayload,
+    parentWorkspace,
+  };
+}
+
 function extractAgentBranchStartMetadata(output) {
   const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
   const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
@@ -1208,7 +1418,7 @@ 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}`);
+    throw new Error(`sandbox target must stay inside repo root: ${resolvedTarget}`);
   }
   if (!relativeTarget || relativeTarget === '.') {
     return worktreePath;
@@ -1216,6 +1426,16 @@ function resolveSandboxTarget(repoRoot, worktreePath, targetPath) {
   return path.join(worktreePath, relativeTarget);
 }
 
+function buildSandboxSetupArgs(options, sandboxTarget) {
+  const args = ['setup', '--target', sandboxTarget, '--no-global-install', '--no-recursive'];
+  if (options.force) args.push('--force');
+  if (options.skipAgents) args.push('--skip-agents');
+  if (options.skipPackageJson) args.push('--skip-package-json');
+  if (options.skipGitignore) args.push('--no-gitignore');
+  if (options.dryRun) args.push('--dry-run');
+  return args;
+}
+
 function buildSandboxDoctorArgs(options, sandboxTarget) {
   const args = ['doctor', '--target', sandboxTarget];
   if (options.dryRun) args.push('--dry-run');
@@ -1224,6 +1444,8 @@ function buildSandboxDoctorArgs(options, sandboxTarget) {
   if (options.skipPackageJson) args.push('--skip-package-json');
   if (options.skipGitignore) args.push('--no-gitignore');
   if (!options.dropStaleLocks) args.push('--keep-stale-locks');
+  args.push(options.waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge');
+  if (options.verboseAutoFinish) args.push('--verbose-auto-finish');
   if (options.json) args.push('--json');
   return args;
 }
@@ -1259,7 +1481,7 @@ function ensureRepoBranch(repoRoot, branch) {
   return { ok: true, changed: true };
 }
 
-function doctorSandboxBranchPrefix() {
+function protectedBaseSandboxBranchPrefix() {
   const now = new Date();
   const stamp = [
     now.getUTCFullYear(),
@@ -1273,15 +1495,15 @@ function doctorSandboxBranchPrefix() {
   return `agent/gx/${stamp}`;
 }
 
-function doctorSandboxWorktreePath(repoRoot, branchName) {
-  return path.join(repoRoot, '.omx', 'agent-worktrees', branchName.replace(/\//g, '__'));
+function protectedBaseSandboxWorktreePath(repoRoot, branchName) {
+  return path.join(repoRoot, defaultAgentWorktreeRelativeDir(), branchName.replace(/\//g, '__'));
 }
 
 function gitRefExists(repoRoot, ref) {
   return run('git', ['-C', repoRoot, 'show-ref', '--verify', '--quiet', ref]).status === 0;
 }
 
-function resolveDoctorSandboxStartRef(repoRoot, baseBranch) {
+function resolveProtectedBaseSandboxStartRef(repoRoot, baseBranch) {
   run('git', ['-C', repoRoot, 'fetch', 'origin', baseBranch, '--quiet'], { timeout: 20_000 });
   if (gitRefExists(repoRoot, `refs/remotes/origin/${baseBranch}`)) {
     return `origin/${baseBranch}`;
@@ -1289,18 +1511,21 @@ function resolveDoctorSandboxStartRef(repoRoot, baseBranch) {
   if (gitRefExists(repoRoot, `refs/heads/${baseBranch}`)) {
     return baseBranch;
   }
-  throw new Error(`Unable to find base ref for sandbox doctor: ${baseBranch}`);
+  if (currentBranchName(repoRoot) === baseBranch) {
+    return null;
+  }
+  throw new Error(`Unable to find base ref for sandbox bootstrap: ${baseBranch}`);
 }
 
-function startDoctorSandboxFallback(blocked) {
-  const branchPrefix = doctorSandboxBranchPrefix();
+function startProtectedBaseSandboxFallback(blocked, sandboxSuffix) {
+  const branchPrefix = protectedBaseSandboxBranchPrefix();
   let selectedBranch = '';
   let selectedWorktreePath = '';
 
   for (let attempt = 0; attempt < 30; attempt += 1) {
-    const suffix = attempt === 0 ? 'gx-doctor' : `${attempt + 1}-gx-doctor`;
+    const suffix = attempt === 0 ? sandboxSuffix : `${attempt + 1}-${sandboxSuffix}`;
     const candidateBranch = `${branchPrefix}-${suffix}`;
-    const candidateWorktreePath = doctorSandboxWorktreePath(blocked.repoRoot, candidateBranch);
+    const candidateWorktreePath = protectedBaseSandboxWorktreePath(blocked.repoRoot, candidateBranch);
     if (gitRefExists(blocked.repoRoot, `refs/heads/${candidateBranch}`)) {
       continue;
     }
@@ -1313,20 +1538,36 @@ function startDoctorSandboxFallback(blocked) {
   }
 
   if (!selectedBranch || !selectedWorktreePath) {
-    throw new Error('Unable to allocate unique sandbox branch/worktree for doctor');
+    throw new Error('Unable to allocate unique sandbox branch/worktree');
   }
 
   fs.mkdirSync(path.dirname(selectedWorktreePath), { recursive: true });
-  const startRef = resolveDoctorSandboxStartRef(blocked.repoRoot, blocked.branch);
-  const addResult = run(
-    'git',
-    ['-C', blocked.repoRoot, 'worktree', 'add', '-b', selectedBranch, selectedWorktreePath, startRef],
-  );
+  const startRef = resolveProtectedBaseSandboxStartRef(blocked.repoRoot, blocked.branch);
+  const addArgs = startRef
+    ? ['-C', blocked.repoRoot, 'worktree', 'add', '-b', selectedBranch, selectedWorktreePath, startRef]
+    : ['-C', blocked.repoRoot, 'worktree', 'add', '--orphan', selectedWorktreePath];
+  const addResult = run('git', addArgs);
   if (isSpawnFailure(addResult)) {
     throw addResult.error;
   }
   if (addResult.status !== 0) {
-    throw new Error((addResult.stderr || addResult.stdout || 'failed to create doctor sandbox').trim());
+    throw new Error((addResult.stderr || addResult.stdout || 'failed to create sandbox').trim());
+  }
+
+  if (!startRef) {
+    const renameResult = run(
+      'git',
+      ['-C', selectedWorktreePath, 'branch', '-m', selectedBranch],
+      { timeout: 20_000 },
+    );
+    if (isSpawnFailure(renameResult)) {
+      throw renameResult.error;
+    }
+    if (renameResult.status !== 0) {
+      throw new Error(
+        (renameResult.stderr || renameResult.stdout || 'failed to name orphan sandbox branch').trim(),
+      );
+    }
   }
 
   return {
@@ -1341,16 +1582,20 @@ function startDoctorSandboxFallback(blocked) {
   };
 }
 
-function startDoctorSandbox(blocked) {
+function startProtectedBaseSandbox(blocked, { taskName, sandboxSuffix }) {
+  if (sandboxSuffix === 'gx-doctor') {
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
+  }
+
   const startScript = path.join(blocked.repoRoot, 'scripts', 'agent-branch-start.sh');
   if (!fs.existsSync(startScript)) {
-    return startDoctorSandboxFallback(blocked);
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
   const startResult = run('bash', [
     startScript,
     '--task',
-    `${SHORT_TOOL_NAME}-doctor`,
+    taskName,
     '--agent',
     SHORT_TOOL_NAME,
     '--base',
@@ -1360,7 +1605,7 @@ function startDoctorSandbox(blocked) {
     throw startResult.error;
   }
   if (startResult.status !== 0) {
-    return startDoctorSandboxFallback(blocked);
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
   const metadata = extractAgentBranchStartMetadata(startResult.stdout);
@@ -1375,11 +1620,11 @@ function startDoctorSandbox(blocked) {
     if (!restoreResult.ok) {
       const detail = [restoreResult.stderr, restoreResult.stdout].filter(Boolean).join('\n').trim();
       throw new Error(
-        `doctor sandbox startup switched protected base checkout and could not restore '${blocked.branch}'.` +
+        `sandbox startup switched protected base checkout and could not restore '${blocked.branch}'.` +
         (detail ? `\n${detail}` : ''),
       );
     }
-    return startDoctorSandboxFallback(blocked);
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
   return {
@@ -1389,6 +1634,59 @@ function startDoctorSandbox(blocked) {
   };
 }
 
+function cleanupProtectedBaseSandbox(repoRoot, metadata) {
+  const result = {
+    worktree: 'skipped',
+    branch: 'skipped',
+    note: 'missing sandbox metadata',
+  };
+
+  if (!metadata?.worktreePath || !metadata?.branch) {
+    return result;
+  }
+
+  if (fs.existsSync(metadata.worktreePath)) {
+    const removeResult = run(
+      'git',
+      ['-C', repoRoot, 'worktree', 'remove', '--force', metadata.worktreePath],
+      { timeout: 30_000 },
+    );
+    if (isSpawnFailure(removeResult)) {
+      throw removeResult.error;
+    }
+    if (removeResult.status !== 0) {
+      throw new Error(
+        (removeResult.stderr || removeResult.stdout || 'failed to remove sandbox worktree').trim(),
+      );
+    }
+    result.worktree = 'removed';
+  } else {
+    result.worktree = 'missing';
+  }
+
+  if (gitRefExists(repoRoot, `refs/heads/${metadata.branch}`)) {
+    const branchDeleteResult = run(
+      'git',
+      ['-C', repoRoot, 'branch', '-D', metadata.branch],
+      { timeout: 20_000 },
+    );
+    if (isSpawnFailure(branchDeleteResult)) {
+      throw branchDeleteResult.error;
+    }
+    if (branchDeleteResult.status !== 0) {
+      throw new Error(
+        (branchDeleteResult.stderr || branchDeleteResult.stdout || 'failed to delete sandbox branch').trim(),
+      );
+    }
+    result.branch = 'deleted';
+  } else {
+    result.branch = 'missing';
+  }
+
+  result.note = 'sandbox worktree pruned';
+  return result;
+}
+
 function parseGitPathList(output) {
   return String(output || '')
     .split('\n')
@@ -1427,6 +1725,59 @@ function collectDoctorDeletedPaths(worktreePath) {
   return Array.from(deleted);
 }
 
+function collectWorktreeDirtyPaths(worktreePath) {
+  const dirty = new Set();
+  const commands = [
+    ['diff', '--name-only'],
+    ['diff', '--cached', '--name-only'],
+    ['ls-files', '--others', '--exclude-standard'],
+  ];
+  for (const gitArgs of commands) {
+    const result = run('git', ['-C', worktreePath, ...gitArgs], { timeout: 20_000 });
+    for (const filePath of parseGitPathList(result.stdout)) {
+      dirty.add(filePath);
+    }
+  }
+  return Array.from(dirty);
+}
+
+function collectDoctorForceAddPaths(worktreePath) {
+  return TEMPLATE_FILES
+    .map((entry) => toDestinationPath(entry))
+    .filter((relativePath) => relativePath.startsWith('scripts/') || relativePath.startsWith('.githooks/'))
+    .filter((relativePath) => fs.existsSync(path.join(worktreePath, relativePath)));
+}
+
+function stripDoctorSandboxLocks(rawContent, branchName) {
+  if (!rawContent || !branchName) {
+    return rawContent;
+  }
+  try {
+    const parsed = JSON.parse(rawContent);
+    const locks = parsed && typeof parsed === 'object' && parsed.locks && typeof parsed.locks === 'object'
+      ? parsed.locks
+      : null;
+    if (!locks) {
+      return rawContent;
+    }
+    let changed = false;
+    const filteredLocks = {};
+    for (const [filePath, lockInfo] of Object.entries(locks)) {
+      if (lockInfo && lockInfo.branch === branchName) {
+        changed = true;
+        continue;
+      }
+      filteredLocks[filePath] = lockInfo;
+    }
+    if (!changed) {
+      return rawContent;
+    }
+    return `${JSON.stringify({ ...parsed, locks: filteredLocks }, null, 2)}\n`;
+  } catch {
+    return rawContent;
+  }
+}
+
 function claimDoctorChangedLocks(metadata) {
   const lockScript = path.join(metadata.worktreePath, 'scripts', 'agent-file-locks.py');
   if (!fs.existsSync(lockScript) || !metadata.branch) {
@@ -1438,7 +1789,10 @@ function claimDoctorChangedLocks(metadata) {
     };
   }
 
-  const changedPaths = collectDoctorChangedPaths(metadata.worktreePath);
+  const changedPaths = Array.from(new Set([
+    ...collectDoctorChangedPaths(metadata.worktreePath),
+    ...collectDoctorForceAddPaths(metadata.worktreePath),
+  ]));
   const deletedPaths = collectDoctorDeletedPaths(metadata.worktreePath);
   if (changedPaths.length > 0) {
     run('python3', [lockScript, 'claim', '--branch', metadata.branch, ...changedPaths], {
@@ -1470,7 +1824,19 @@ function autoCommitDoctorSandboxChanges(metadata) {
   }
 
   claimDoctorChangedLocks(metadata);
-  run('git', ['-C', metadata.worktreePath, 'add', '-A'], { timeout: 20_000 });
+  run(
+    'git',
+    ['-C', metadata.worktreePath, 'add', '-A', '--', '.', `:(exclude)${LOCK_FILE_RELATIVE}`],
+    { timeout: 20_000 },
+  );
+  const forceAddPaths = collectDoctorForceAddPaths(metadata.worktreePath);
+  if (forceAddPaths.length > 0) {
+    run(
+      'git',
+      ['-C', metadata.worktreePath, 'add', '-f', '--', ...forceAddPaths],
+      { timeout: 20_000 },
+    );
+  }
   const staged = run(
     'git',
     ['-C', metadata.worktreePath, 'diff', '--cached', '--name-only', '--', '.', `:(exclude)${LOCK_FILE_RELATIVE}`],
@@ -1535,7 +1901,7 @@ function doctorFinishFlowIsPending(output) {
   );
 }
 
-function finishDoctorSandboxBranch(blocked, metadata) {
+function finishDoctorSandboxBranch(blocked, metadata, options = {}) {
   const finishScript = path.join(metadata.worktreePath, 'scripts', 'agent-branch-finish.sh');
   if (!fs.existsSync(finishScript)) {
     return {
@@ -1577,10 +1943,11 @@ function finishDoctorSandboxBranch(blocked, metadata) {
   const waitTimeoutSeconds =
     Number.isFinite(rawWaitTimeoutSeconds) && rawWaitTimeoutSeconds >= 30 ? rawWaitTimeoutSeconds : 1800;
   const finishTimeoutMs = Math.max(180_000, (waitTimeoutSeconds + 60) * 1000);
+  const waitForMergeArg = options.waitForMerge === false ? '--no-wait-for-merge' : '--wait-for-merge';
 
   const finishResult = run(
     'bash',
-    [finishScript, '--branch', metadata.branch, '--base', blocked.branch, '--via-pr', '--wait-for-merge'],
+    [finishScript, '--branch', metadata.branch, '--base', blocked.branch, '--via-pr', waitForMergeArg],
     { cwd: metadata.worktreePath, timeout: finishTimeoutMs },
   );
   if (isSpawnFailure(finishResult)) {
@@ -1619,35 +1986,186 @@ function finishDoctorSandboxBranch(blocked, metadata) {
   };
 }
 
-function syncProtectedBaseDoctorRepairs(options, blocked) {
-  const fixPayload = runFixInternal({
-    ...options,
-    target: blocked.repoRoot,
-    allowProtectedBaseWrite: true,
-  });
-  const changedOperations = fixPayload.operations.filter(
-    (operation) => !['unchanged', 'skipped'].includes(operation.status),
+function mergeDoctorSandboxRepairsBackToProtectedBase(options, blocked, metadata, autoCommitResult, finishResult) {
+  if (options.dryRun) {
+    return {
+      status: autoCommitResult.status === 'committed' ? 'would-merge' : 'skipped',
+      note: autoCommitResult.status === 'committed'
+        ? 'dry run: would fast-forward tracked doctor repairs into the protected base workspace'
+        : 'dry run skips tracked repair merge',
+    };
+  }
+
+  if (autoCommitResult.status !== 'committed') {
+    return {
+      status: autoCommitResult.status === 'no-changes' ? 'unchanged' : 'skipped',
+      note: autoCommitResult.status === 'no-changes'
+        ? 'no tracked doctor repairs needed in the protected base workspace'
+        : 'tracked doctor repair merge skipped',
+    };
+  }
+
+  if (finishResult.status !== 'skipped') {
+    return {
+      status: 'skipped',
+      note: finishResult.status === 'failed'
+        ? 'tracked doctor repairs remain in the sandbox after finish failure'
+        : 'tracked doctor repairs are being delivered through the sandbox finish flow',
+    };
+  }
+
+  const allowedPaths = new Set([
+    ...(autoCommitResult.stagedFiles || []),
+    ...OMX_SCAFFOLD_DIRECTORIES,
+    ...Array.from(OMX_SCAFFOLD_FILES.keys()),
+    ...TEMPLATE_FILES.map((entry) => toDestinationPath(entry)),
+    'bin',
+    'package.json',
+    '.gitignore',
+    'AGENTS.md',
+  ]);
+  const dirtyPaths = collectWorktreeDirtyPaths(blocked.repoRoot);
+  let stashRef = '';
+  if (dirtyPaths.length > 0) {
+    const unexpectedPaths = dirtyPaths.filter((filePath) => {
+      if (allowedPaths.has(filePath)) {
+        return false;
+      }
+      return !AGENT_WORKTREE_RELATIVE_DIRS.some(
+        (relativeDir) => filePath === relativeDir || filePath.startsWith(`${relativeDir}/`),
+      );
+    });
+    if (unexpectedPaths.length > 0) {
+      return {
+        status: 'failed',
+        note: `protected branch workspace has unrelated local changes: ${unexpectedPaths.join(', ')}`,
+      };
+    }
+    const stashMessage = `guardex-doctor-merge-${Date.now()}`;
+    const stashResult = run(
+      'git',
+      ['-C', blocked.repoRoot, 'stash', 'push', '--all', '--message', stashMessage],
+      { timeout: 30_000 },
+    );
+    if (isSpawnFailure(stashResult)) {
+      return {
+        status: 'failed',
+        note: 'could not stash protected branch doctor drift before merge',
+        stdout: stashResult.stdout || '',
+        stderr: stashResult.stderr || '',
+      };
+    }
+    if (stashResult.status !== 0) {
+      return {
+        status: 'failed',
+        note: 'stashing protected branch doctor drift failed',
+        stdout: stashResult.stdout || '',
+        stderr: stashResult.stderr || '',
+      };
+    }
+
+    const stashLookup = run(
+      'git',
+      ['-C', blocked.repoRoot, 'stash', 'list'],
+      { timeout: 20_000 },
+    );
+    stashRef = String(stashLookup.stdout || '')
+      .split('\n')
+      .find((line) => line.includes(stashMessage))
+      ?.split(':')[0]
+      ?.trim() || '';
+  }
+
+  const restoreResult = ensureRepoBranch(blocked.repoRoot, blocked.branch);
+  if (!restoreResult.ok) {
+    if (stashRef) {
+      run('git', ['-C', blocked.repoRoot, 'stash', 'apply', stashRef], { timeout: 30_000 });
+    }
+    return {
+      status: 'failed',
+      note: `could not restore protected branch '${blocked.branch}' before applying sandbox repairs`,
+      stdout: restoreResult.stdout || '',
+      stderr: restoreResult.stderr || '',
+    };
+  }
+
+  const mergeResult = run(
+    'git',
+    ['-C', blocked.repoRoot, 'merge', '--ff-only', metadata.branch],
+    { timeout: 30_000 },
   );
-  const hookChanged = fixPayload.hookResult?.status && fixPayload.hookResult.status !== 'unchanged';
-  const changedCount = changedOperations.length + (hookChanged ? 1 : 0);
+  if (isSpawnFailure(mergeResult)) {
+    if (stashRef) {
+      run('git', ['-C', blocked.repoRoot, 'stash', 'apply', stashRef], { timeout: 30_000 });
+    }
+    return {
+      status: 'failed',
+      note: 'tracked doctor repair merge errored',
+      stdout: mergeResult.stdout || '',
+      stderr: mergeResult.stderr || '',
+    };
+  }
+  if (mergeResult.status !== 0) {
+    if (stashRef) {
+      run('git', ['-C', blocked.repoRoot, 'stash', 'apply', stashRef], { timeout: 30_000 });
+    }
+    return {
+      status: 'failed',
+      note: 'tracked doctor repair merge failed',
+      stdout: mergeResult.stdout || '',
+      stderr: mergeResult.stderr || '',
+    };
+  }
+
+  let cleanupResult;
+  try {
+    cleanupResult = cleanupProtectedBaseSandbox(blocked.repoRoot, metadata);
+  } catch (error) {
+    return {
+      status: 'failed',
+      note: `tracked doctor repair merge succeeded but sandbox cleanup failed: ${error.message}`,
+      stdout: mergeResult.stdout || '',
+      stderr: mergeResult.stderr || '',
+    };
+  }
 
-  if (changedCount === 0) {
+  let hookRefreshResult;
+  try {
+    hookRefreshResult = configureHooks(blocked.repoRoot, false);
+  } catch (error) {
     return {
-      status: 'unchanged',
-      note: 'managed repair files already aligned in protected branch workspace',
-      fixPayload,
+      status: 'failed',
+      note: `tracked doctor repair merge succeeded but local hook refresh failed: ${error.message}`,
+      stdout: mergeResult.stdout || '',
+      stderr: mergeResult.stderr || '',
     };
   }
 
+  if (stashRef) {
+    run('git', ['-C', blocked.repoRoot, 'stash', 'drop', stashRef], { timeout: 20_000 });
+  }
+
   return {
-    status: options.dryRun ? 'would-sync' : 'synced',
-    note: `${options.dryRun ? 'would sync' : 'synced'} ${changedCount} managed repair item(s)`,
-    fixPayload,
+    status: 'merged',
+    note: 'fast-forwarded tracked doctor repairs into the protected base workspace',
+    stdout: mergeResult.stdout || '',
+    stderr: mergeResult.stderr || '',
+    cleanup: cleanupResult,
+    hookRefresh: hookRefreshResult,
   };
 }
 
+function syncDoctorLocalSupportFiles(repoRoot, dryRun) {
+  return TEMPLATE_FILES
+    .filter((entry) => entry.startsWith('codex/') || entry.startsWith('claude/'))
+    .map((entry) => ensureTemplateFilePresent(repoRoot, entry, dryRun));
+}
+
 function runDoctorInSandbox(options, blocked) {
-  const startResult = startDoctorSandbox(blocked);
+  const startResult = startProtectedBaseSandbox(blocked, {
+    taskName: `${SHORT_TOOL_NAME}-doctor`,
+    sandboxSuffix: 'gx-doctor',
+  });
   const metadata = startResult.metadata;
 
   const sandboxTarget = resolveSandboxTarget(blocked.repoRoot, metadata.worktreePath, options.target);
@@ -1677,6 +2195,7 @@ function runDoctorInSandbox(options, blocked) {
     status: 'skipped',
     note: 'sandbox doctor did not complete successfully',
   };
+  let sandboxLockContent = null;
   let postSandboxAutoFinishSummary = {
     enabled: false,
     attempted: 0,
@@ -1690,7 +2209,6 @@ function runDoctorInSandbox(options, blocked) {
     note: 'sandbox doctor did not complete successfully',
   };
   if (nestedResult.status === 0) {
-    protectedBaseRepairSyncResult = syncProtectedBaseDoctorRepairs(options, blocked);
     const omxScaffoldOps = ensureOmxScaffold(blocked.repoRoot, Boolean(options.dryRun));
     const changedOmxPaths = omxScaffoldOps.filter((operation) => operation.status !== 'unchanged');
     if (changedOmxPaths.length === 0) {
@@ -1710,7 +2228,7 @@ function runDoctorInSandbox(options, blocked) {
     if (!options.dryRun) {
       autoCommitResult = autoCommitDoctorSandboxChanges(metadata);
       if (autoCommitResult.status === 'committed') {
-        finishResult = finishDoctorSandboxBranch(blocked, metadata);
+        finishResult = finishDoctorSandboxBranch(blocked, metadata, options);
       } else if (autoCommitResult.status === 'no-changes') {
         finishResult = {
           status: 'skipped',
@@ -1746,7 +2264,11 @@ function runDoctorInSandbox(options, blocked) {
         note: `${LOCK_FILE_RELATIVE} missing in sandbox worktree`,
       };
     } else {
-      const sourceContent = fs.readFileSync(sandboxLockPath, 'utf8');
+      const sourceContent = stripDoctorSandboxLocks(
+        fs.readFileSync(sandboxLockPath, 'utf8'),
+        metadata.branch,
+      );
+      sandboxLockContent = sourceContent;
       const destinationContent = fs.readFileSync(baseLockPath, 'utf8');
       if (sourceContent === destinationContent) {
         lockSyncResult = {
@@ -1763,9 +2285,66 @@ function runDoctorInSandbox(options, blocked) {
       }
     }
 
+    protectedBaseRepairSyncResult = mergeDoctorSandboxRepairsBackToProtectedBase(
+      options,
+      blocked,
+      metadata,
+      autoCommitResult,
+      finishResult,
+    );
+
+    syncDoctorLocalSupportFiles(blocked.repoRoot, Boolean(options.dryRun));
+
+    const postMergeOmxScaffoldOps = ensureOmxScaffold(blocked.repoRoot, Boolean(options.dryRun));
+    const postMergeChangedOmxPaths = postMergeOmxScaffoldOps.filter((operation) => operation.status !== 'unchanged');
+    if (postMergeChangedOmxPaths.length === 0) {
+      omxScaffoldSyncResult = {
+        status: 'unchanged',
+        note: '.omx scaffold already in sync',
+        operations: postMergeOmxScaffoldOps,
+      };
+    } else {
+      omxScaffoldSyncResult = {
+        status: options.dryRun ? 'would-sync' : 'synced',
+        note: `${options.dryRun ? 'would sync' : 'synced'} ${postMergeChangedOmxPaths.length} .omx path(s)`,
+        operations: postMergeOmxScaffoldOps,
+      };
+    }
+
+    const postMergeBaseLockPath = path.join(blocked.repoRoot, LOCK_FILE_RELATIVE);
+    if (sandboxLockContent === null) {
+      lockSyncResult = {
+        status: 'skipped',
+        note: `${LOCK_FILE_RELATIVE} missing in sandbox worktree`,
+      };
+    } else if (!fs.existsSync(postMergeBaseLockPath)) {
+      fs.mkdirSync(path.dirname(postMergeBaseLockPath), { recursive: true });
+      fs.writeFileSync(postMergeBaseLockPath, sandboxLockContent, 'utf8');
+      lockSyncResult = {
+        status: 'synced',
+        note: `${LOCK_FILE_RELATIVE} recreated from sandbox`,
+      };
+    } else {
+      const destinationContent = fs.readFileSync(postMergeBaseLockPath, 'utf8');
+      if (sandboxLockContent === destinationContent) {
+        lockSyncResult = {
+          status: 'unchanged',
+          note: `${LOCK_FILE_RELATIVE} already in sync`,
+        };
+      } else {
+        fs.mkdirSync(path.dirname(postMergeBaseLockPath), { recursive: true });
+        fs.writeFileSync(postMergeBaseLockPath, sandboxLockContent, 'utf8');
+        lockSyncResult = {
+          status: 'synced',
+          note: `${LOCK_FILE_RELATIVE} synced from sandbox`,
+        };
+      }
+    }
+
     postSandboxAutoFinishSummary = autoFinishReadyAgentBranches(blocked.repoRoot, {
       baseBranch: blocked.branch,
       dryRun: options.dryRun,
+      waitForMerge: options.waitForMerge,
       excludeBranches: [metadata.branch],
     });
   }
@@ -1820,14 +2399,28 @@ function runDoctorInSandbox(options, blocked) {
         console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit skipped: ${autoCommitResult.note}.`);
       }
 
-      if (protectedBaseRepairSyncResult.status === 'synced') {
-        console.log(`[${TOOL_NAME}] Synced repaired managed files back to protected branch workspace.`);
+      if (protectedBaseRepairSyncResult.status === 'merged') {
+        console.log(`[${TOOL_NAME}] Fast-forwarded tracked doctor repairs into the protected branch workspace.`);
       } else if (protectedBaseRepairSyncResult.status === 'unchanged') {
-        console.log(`[${TOOL_NAME}] Protected branch workspace already had the repaired managed files.`);
-      } else if (protectedBaseRepairSyncResult.status === 'would-sync') {
-        console.log(`[${TOOL_NAME}] Dry run: would sync repaired managed files back to protected branch workspace.`);
+        console.log(`[${TOOL_NAME}] Protected branch workspace already had the tracked doctor repairs.`);
+      } else if (protectedBaseRepairSyncResult.status === 'would-merge') {
+        console.log(`[${TOOL_NAME}] Dry run: would fast-forward tracked doctor repairs into the protected branch workspace.`);
+      } else if (protectedBaseRepairSyncResult.status === 'failed') {
+        console.log(`[${TOOL_NAME}] Protected branch tracked repair merge failed: ${protectedBaseRepairSyncResult.note}.`);
+        if (protectedBaseRepairSyncResult.stdout) process.stdout.write(protectedBaseRepairSyncResult.stdout);
+        if (protectedBaseRepairSyncResult.stderr) process.stderr.write(protectedBaseRepairSyncResult.stderr);
+      } else {
+        console.log(`[${TOOL_NAME}] Protected branch tracked repair merge skipped: ${protectedBaseRepairSyncResult.note}.`);
+      }
+
+      if (lockSyncResult.status === 'synced') {
+        console.log(
+          `[${TOOL_NAME}] Synced repaired lock registry back to protected branch workspace (${LOCK_FILE_RELATIVE}).`,
+        );
+      } else if (lockSyncResult.status === 'unchanged') {
+        console.log(`[${TOOL_NAME}] Lock registry already synced in protected branch workspace.`);
       } else {
-        console.log(`[${TOOL_NAME}] Protected branch workspace repair sync skipped: ${protectedBaseRepairSyncResult.note}.`);
+        console.log(`[${TOOL_NAME}] Lock registry sync skipped: ${lockSyncResult.note}.`);
       }
 
       if (finishResult.status === 'completed') {
@@ -1845,32 +2438,17 @@ function runDoctorInSandbox(options, blocked) {
         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}'.`);
+        console.log(`[guardex] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
         if (finishResult.stdout) process.stdout.write(finishResult.stdout);
         if (finishResult.stderr) process.stderr.write(finishResult.stderr);
       } else {
         console.log(`[${TOOL_NAME}] Auto-finish skipped: ${finishResult.note}.`);
       }
 
-      if (lockSyncResult.status === 'synced') {
-        console.log(
-          `[${TOOL_NAME}] Synced repaired lock registry back to protected branch workspace (${LOCK_FILE_RELATIVE}).`,
-        );
-      } else if (lockSyncResult.status === 'unchanged') {
-        console.log(`[${TOOL_NAME}] Lock registry already synced in protected branch workspace.`);
-      } else {
-        console.log(`[${TOOL_NAME}] Lock registry sync skipped: ${lockSyncResult.note}.`);
-      }
-
-      if (postSandboxAutoFinishSummary.enabled) {
-        console.log(
-          `[${TOOL_NAME}] Auto-finish sweep (base=${blocked.branch}): attempted=${postSandboxAutoFinishSummary.attempted}, completed=${postSandboxAutoFinishSummary.completed}, skipped=${postSandboxAutoFinishSummary.skipped}, failed=${postSandboxAutoFinishSummary.failed}`,
-        );
-        for (const detail of postSandboxAutoFinishSummary.details) {
-          console.log(`[${TOOL_NAME}]   ${detail}`);
-        }
-      } else if (postSandboxAutoFinishSummary.details.length > 0) {
-        console.log(`[${TOOL_NAME}] ${postSandboxAutoFinishSummary.details[0]}`);
-      }
+      printAutoFinishSummary(postSandboxAutoFinishSummary, {
+        baseBranch: blocked.branch,
+        verbose: options.verboseAutoFinish,
+      });
       if (omxScaffoldSyncResult.status === 'synced') {
         console.log(`[${TOOL_NAME}] Synced .omx scaffold back to protected branch workspace.`);
       } else if (omxScaffoldSyncResult.status === 'unchanged') {
@@ -1883,22 +2461,99 @@ function runDoctorInSandbox(options, blocked) {
     }
   }
 
-  if (typeof nestedResult.status === 'number') {
-    let exitCode = nestedResult.status;
-    if (exitCode === 0 && autoCommitResult.status === 'failed') {
-      exitCode = 1;
-    }
-    if (
-      exitCode === 0 &&
-      autoCommitResult.status === 'committed' &&
-      (finishResult.status === 'failed' || finishResult.status === 'pending')
-    ) {
-      exitCode = 1;
+  if (typeof nestedResult.status === 'number') {
+    let exitCode = nestedResult.status;
+    if (exitCode === 0 && autoCommitResult.status === 'failed') {
+      exitCode = 1;
+    }
+    if (
+      exitCode === 0 &&
+      autoCommitResult.status === 'committed' &&
+      (finishResult.status === 'failed' || finishResult.status === 'pending')
+    ) {
+      exitCode = 1;
+    }
+    if (exitCode === 0 && protectedBaseRepairSyncResult.status === 'failed') {
+      exitCode = 1;
+    }
+    process.exitCode = exitCode;
+    return;
+  }
+  process.exitCode = 1;
+}
+
+function runSetupInSandbox(options, blocked, repoLabel = '') {
+  const startResult = startProtectedBaseSandbox(blocked, {
+    taskName: `${SHORT_TOOL_NAME}-setup`,
+    sandboxSuffix: 'gx-setup',
+  });
+  const metadata = startResult.metadata;
+
+  if (startResult.stdout) process.stdout.write(startResult.stdout);
+  if (startResult.stderr) process.stderr.write(startResult.stderr);
+  console.log(
+    `[${TOOL_NAME}] setup blocked on protected branch '${blocked.branch}' in an initialized repo; ` +
+    'refreshing through a sandbox worktree and syncing managed bootstrap files back locally.',
+  );
+
+  const sandboxTarget = resolveSandboxTarget(blocked.repoRoot, metadata.worktreePath, options.target);
+  const nestedResult = run(
+    process.execPath,
+    [__filename, ...buildSandboxSetupArgs(options, sandboxTarget)],
+    { cwd: metadata.worktreePath },
+  );
+  if (isSpawnFailure(nestedResult)) {
+    throw nestedResult.error;
+  }
+  if (nestedResult.status !== 0) {
+    if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
+    if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+    throw new Error(
+      `sandboxed setup failed for protected branch '${blocked.branch}'. ` +
+      `Inspect sandbox at ${metadata.worktreePath}`,
+    );
+  }
+
+  const syncOptions = {
+    ...options,
+    target: blocked.repoRoot,
+    recursive: false,
+    allowProtectedBaseWrite: true,
+  };
+  const { installPayload, fixPayload, parentWorkspace } = runSetupBootstrapInternal(syncOptions);
+  printOperations(`Setup/install${repoLabel}`, installPayload, syncOptions.dryRun);
+  printOperations(`Setup/fix${repoLabel}`, fixPayload, syncOptions.dryRun);
+  if (!syncOptions.dryRun && parentWorkspace) {
+    console.log(`[${TOOL_NAME}] Parent workspace view: ${parentWorkspace.workspacePath}`);
+  }
+
+  const scanResult = runScanInternal({ target: blocked.repoRoot, json: false });
+  const currentBaseBranch = currentBranchName(scanResult.repoRoot);
+  const autoFinishSummary = autoFinishReadyAgentBranches(scanResult.repoRoot, {
+    baseBranch: currentBaseBranch,
+    dryRun: syncOptions.dryRun,
+  });
+  printScanResult(scanResult, false);
+  if (autoFinishSummary.enabled) {
+    console.log(
+      `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
+    );
+    for (const detail of autoFinishSummary.details) {
+      console.log(`[${TOOL_NAME}]   ${detail}`);
     }
-    process.exitCode = exitCode;
-    return;
+  } else if (autoFinishSummary.details.length > 0) {
+    console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
   }
-  process.exitCode = 1;
+
+  const cleanupResult = cleanupProtectedBaseSandbox(blocked.repoRoot, metadata);
+  console.log(
+    `[${TOOL_NAME}] Protected-base setup sandbox cleanup: ${cleanupResult.note} ` +
+    `(worktree=${cleanupResult.worktree}, branch=${cleanupResult.branch}).`,
+  );
+
+  return {
+    scanResult,
+  };
 }
 
 function parseTargetFlag(rawArgs, defaultTarget = process.cwd()) {
@@ -2082,6 +2737,19 @@ function inferGithubRepoFromOrigin(repoRoot) {
   return `github.com/${slug}`;
 }
 
+function inferGithubRepoSlug(rawValue) {
+  const raw = String(rawValue || '').trim();
+  if (!raw) return '';
+  const match = raw.match(/github\.com[:/](.+?)(?:\.git)?$/i);
+  if (!match) return '';
+  const slug = String(match[1] || '')
+    .replace(/^\/+/, '')
+    .replace(/^github\.com\//i, '')
+    .trim();
+  if (!slug || !slug.includes('/')) return '';
+  return slug;
+}
+
 function resolveScorecardRepo(repoRoot, explicitRepo) {
   if (explicitRepo) {
     return explicitRepo.trim();
@@ -2335,6 +3003,7 @@ function hasSignificantWorkingTreeChanges(worktreePath) {
 function autoFinishReadyAgentBranches(repoRoot, options = {}) {
   const baseBranch = String(options.baseBranch || '').trim();
   const dryRun = Boolean(options.dryRun);
+  const waitForMerge = options.waitForMerge !== false;
   const excludedBranches = new Set(
     Array.isArray(options.excludeBranches)
       ? options.excludeBranches.map((branch) => String(branch || '').trim()).filter(Boolean)
@@ -2453,7 +3122,7 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       '--base',
       baseBranch,
       '--via-pr',
-      '--wait-for-merge',
+      waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
       '--cleanup',
     ];
     const finishResult = run('bash', finishArgs, { cwd: repoRoot });
@@ -2565,6 +3234,66 @@ function currentBranchName(repoRoot) {
   return branch;
 }
 
+function repoHasHeadCommit(repoRoot) {
+  return gitRun(repoRoot, ['rev-parse', '--verify', 'HEAD'], { allowFailure: true }).status === 0;
+}
+
+function readBranchDisplayName(repoRoot) {
+  const symbolic = gitRun(repoRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD'], { allowFailure: true });
+  if (symbolic.status === 0) {
+    const branch = String(symbolic.stdout || '').trim();
+    if (!branch) {
+      return '(unknown)';
+    }
+    return repoHasHeadCommit(repoRoot) ? branch : `${branch} (unborn; no commits yet)`;
+  }
+
+  const detached = gitRun(repoRoot, ['rev-parse', '--short', 'HEAD'], { allowFailure: true });
+  if (detached.status === 0) {
+    return `(detached at ${String(detached.stdout || '').trim()})`;
+  }
+  return '(unknown)';
+}
+
+function repoHasOriginRemote(repoRoot) {
+  return gitRun(repoRoot, ['remote', 'get-url', 'origin'], { allowFailure: true }).status === 0;
+}
+
+function detectComposeHintFiles(repoRoot) {
+  return COMPOSE_HINT_FILES.filter((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
+}
+
+function printSetupRepoHints(repoRoot, baseBranch, repoLabel = '') {
+  const branchDisplay = readBranchDisplayName(repoRoot);
+  const hasHeadCommit = repoHasHeadCommit(repoRoot);
+  const hasOrigin = repoHasOriginRemote(repoRoot);
+  const composeFiles = detectComposeHintFiles(repoRoot);
+  if (hasHeadCommit && hasOrigin && composeFiles.length === 0) {
+    return;
+  }
+
+  const label = repoLabel ? ` ${repoLabel}` : '';
+  if (!hasHeadCommit) {
+    console.log(`[${TOOL_NAME}] Fresh repo onboarding${label}: current branch is ${branchDisplay}.`);
+    console.log(`[${TOOL_NAME}] Bootstrap commit${label}: git add . && git commit -m "bootstrap gitguardex"`);
+    console.log(
+      `[${TOOL_NAME}] First agent flow${label}: ` +
+      `bash scripts/agent-branch-start.sh "<task>" "codex" -> ` +
+      `python3 scripts/agent-file-locks.py claim --branch "$(git branch --show-current)" <file...> -> ` +
+      `bash scripts/agent-branch-finish.sh --branch "$(git branch --show-current)" --base ${baseBranch} --via-pr --wait-for-merge`,
+    );
+  }
+  if (!hasOrigin) {
+    console.log(`[${TOOL_NAME}] No origin remote${label}: finish and auto-merge flows stay local until you add one.`);
+  }
+  if (composeFiles.length > 0) {
+    console.log(
+      `[${TOOL_NAME}] Docker Compose helper${label}: detected ${composeFiles.join(', ')}. ` +
+      `Set GUARDEX_DOCKER_SERVICE and run 'bash scripts/guardex-docker-loader.sh -- <command...>'.`,
+    );
+  }
+}
+
 function workingTreeIsDirty(repoRoot) {
   const result = gitRun(repoRoot, ['status', '--porcelain'], { allowFailure: true });
   if (result.status !== 0) {
@@ -2823,6 +3552,82 @@ function parseCleanupArgs(rawArgs) {
   return options;
 }
 
+function parseMergeArgs(rawArgs) {
+  const options = {
+    target: process.cwd(),
+    base: '',
+    into: '',
+    branches: [],
+    task: '',
+    agent: '',
+  };
+
+  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 === '--into') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--into requires an agent/* branch value');
+      }
+      options.into = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--branch') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--branch requires an agent/* branch value');
+      }
+      options.branches.push(next);
+      index += 1;
+      continue;
+    }
+    if (arg === '--task') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--task requires a task value');
+      }
+      options.task = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--agent') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--agent requires an agent value');
+      }
+      options.agent = next;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.branches.length === 0) {
+    throw new Error('merge requires at least one --branch <agent/*> input');
+  }
+
+  return options;
+}
+
 function parseFinishArgs(rawArgs) {
   const options = {
     target: process.cwd(),
@@ -3376,6 +4181,17 @@ function parseVersionString(version) {
   ];
 }
 
+function compareParsedVersions(left, right) {
+  if (!left || !right) return 0;
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const leftValue = left[index] || 0;
+    const rightValue = right[index] || 0;
+    if (leftValue > rightValue) return 1;
+    if (leftValue < rightValue) return -1;
+  }
+  return 0;
+}
+
 function isNewerVersion(latest, current) {
   const latestParts = parseVersionString(latest);
   const currentParts = parseVersionString(current);
@@ -3384,11 +4200,7 @@ function isNewerVersion(latest, current) {
     return String(latest || '').trim() !== String(current || '').trim();
   }
 
-  for (let index = 0; index < latestParts.length; index += 1) {
-    if (latestParts[index] > currentParts[index]) return true;
-    if (latestParts[index] < currentParts[index]) return false;
-  }
-  return false;
+  return compareParsedVersions(latestParts, currentParts) > 0;
 }
 
 function parseNpmVersionOutput(stdout) {
@@ -4078,8 +4890,7 @@ function runFixInternal(options) {
 function runScanInternal(options) {
   const repoRoot = resolveRepoRoot(options.target);
   const guardexToggle = resolveGuardexRepoToggle(repoRoot);
-  const currentBranchResult = gitRun(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFailure: true });
-  const branch = currentBranchResult.status === 0 ? currentBranchResult.stdout.trim() : '(unknown)';
+  const branch = readBranchDisplayName(repoRoot);
   if (!guardexToggle.enabled) {
     return {
       repoRoot,
@@ -4525,29 +5336,38 @@ function doctor(rawArgs) {
 
     const repoResults = [];
     let aggregateExitCode = 0;
-    for (const repoPath of discoveredRepos) {
+    for (let repoIndex = 0; repoIndex < discoveredRepos.length; repoIndex += 1) {
+      const repoPath = discoveredRepos[repoIndex];
+      const progressLabel = `${repoIndex + 1}/${discoveredRepos.length}`;
       if (!options.json) {
-        console.log(`[${TOOL_NAME}] ── Doctor target: ${repoPath} ──`);
+        console.log(`[${TOOL_NAME}] ── Doctor target: ${repoPath} [${progressLabel}] ──`);
       }
 
-      const nestedResult = run(
-        process.execPath,
-        [
-          path.resolve(__filename),
-          'doctor',
-          '--single-repo',
-          '--target',
-          repoPath,
-          ...(options.dropStaleLocks ? [] : ['--keep-stale-locks']),
-          ...(options.skipAgents ? ['--skip-agents'] : []),
-          ...(options.skipPackageJson ? ['--skip-package-json'] : []),
-          ...(options.skipGitignore ? ['--no-gitignore'] : []),
-          ...(options.dryRun ? ['--dry-run'] : []),
-          ...(options.json ? ['--json'] : []),
-          ...(options.allowProtectedBaseWrite ? ['--allow-protected-base-write'] : []),
-        ],
-        { cwd: topRepoRoot },
-      );
+      const childArgs = [
+        path.resolve(__filename),
+        'doctor',
+        '--single-repo',
+        '--target',
+        repoPath,
+        ...(options.dropStaleLocks ? [] : ['--keep-stale-locks']),
+        ...(options.skipAgents ? ['--skip-agents'] : []),
+        ...(options.skipPackageJson ? ['--skip-package-json'] : []),
+        ...(options.skipGitignore ? ['--no-gitignore'] : []),
+        ...(options.dryRun ? ['--dry-run'] : []),
+        // Recursive child doctor runs should report pending PR state immediately instead of blocking the parent loop.
+        '--no-wait-for-merge',
+        ...(options.verboseAutoFinish ? ['--verbose-auto-finish'] : []),
+        ...(options.json ? ['--json'] : []),
+        ...(options.allowProtectedBaseWrite ? ['--allow-protected-base-write'] : []),
+      ];
+      const startedAt = Date.now();
+      const nestedResult = options.json
+        ? run(process.execPath, childArgs, { cwd: topRepoRoot })
+        : cp.spawnSync(process.execPath, childArgs, {
+          cwd: topRepoRoot,
+          encoding: 'utf8',
+          stdio: 'inherit',
+        });
       if (isSpawnFailure(nestedResult)) {
         throw nestedResult.error;
       }
@@ -4577,9 +5397,12 @@ function doctor(rawArgs) {
             },
         );
       } else {
-        if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
-        if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
-        process.stdout.write('\n');
+        console.log(
+          `[${TOOL_NAME}] Doctor target complete: ${repoPath} [${progressLabel}] in ${formatElapsedDuration(Date.now() - startedAt)}.`,
+        );
+        if (repoIndex < discoveredRepos.length - 1) {
+          process.stdout.write('\n');
+        }
       }
     }
 
@@ -4628,6 +5451,7 @@ function doctor(rawArgs) {
     : autoFinishReadyAgentBranches(scanResult.repoRoot, {
       baseBranch: currentBaseBranch,
       dryRun: singleRepoOptions.dryRun,
+      waitForMerge: singleRepoOptions.waitForMerge,
     });
   const safe = scanResult.guardexEnabled === false || (scanResult.errors === 0 && scanResult.warnings === 0);
   const musafe = safe;
@@ -4662,23 +5486,17 @@ function doctor(rawArgs) {
     return;
   }
 
-  printOperations('Doctor/fix', fixPayload, singleRepoOptions.dryRun);
+  printOperations('Doctor/fix', fixPayload, options.dryRun);
   printScanResult(scanResult, false);
   if (scanResult.guardexEnabled === false) {
     console.log(`[${TOOL_NAME}] Repo-local Guardex enforcement is intentionally disabled.`);
     setExitCodeFromScan(scanResult);
     return;
   }
-  if (autoFinishSummary.enabled) {
-    console.log(
-      `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
-    );
-    for (const detail of autoFinishSummary.details) {
-      console.log(`[${TOOL_NAME}]   ${detail}`);
-    }
-  } else if (autoFinishSummary.details.length > 0) {
-    console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
-  }
+  printAutoFinishSummary(autoFinishSummary, {
+    baseBranch: currentBaseBranch,
+    verbose: singleRepoOptions.verboseAutoFinish,
+  });
   if (safe) {
     console.log(`[${TOOL_NAME}] ✅ Repo is fully safe.`);
   } else {
@@ -5171,31 +5989,24 @@ function setup(rawArgs) {
       console.log(`[${TOOL_NAME}] ── Setup target: ${repoPath} ──`);
     }
 
-    assertProtectedMainWriteAllowed(perRepoOptions, 'setup');
-    const installPayload = runInstallInternal(perRepoOptions);
-    installPayload.operations.push(ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(perRepoOptions.dryRun)));
-    if (perRepoOptions.parentWorkspaceView) {
-      installPayload.operations.push(ensureParentWorkspaceView(installPayload.repoRoot, Boolean(perRepoOptions.dryRun)));
+    const blocked = protectedBaseWriteBlock(perRepoOptions);
+    if (blocked) {
+      const sandboxResult = runSetupInSandbox(perRepoOptions, blocked, repoLabel);
+      aggregateErrors += sandboxResult.scanResult.errors;
+      aggregateWarnings += sandboxResult.scanResult.warnings;
+      lastScanResult = sandboxResult.scanResult;
+      continue;
     }
-    printOperations(`Setup/install${repoLabel}`, installPayload, perRepoOptions.dryRun);
 
-    const fixPayload = runFixInternal({
-      target: repoPath,
-      dryRun: perRepoOptions.dryRun,
-      force: perRepoOptions.force,
-      dropStaleLocks: true,
-      skipAgents: perRepoOptions.skipAgents,
-      skipPackageJson: perRepoOptions.skipPackageJson,
-      skipGitignore: perRepoOptions.skipGitignore,
-    });
+    const { installPayload, fixPayload, parentWorkspace } = runSetupBootstrapInternal(perRepoOptions);
+    printOperations(`Setup/install${repoLabel}`, installPayload, perRepoOptions.dryRun);
     printOperations(`Setup/fix${repoLabel}`, fixPayload, perRepoOptions.dryRun);
 
     if (perRepoOptions.dryRun) {
       continue;
     }
 
-    if (perRepoOptions.parentWorkspaceView) {
-      const parentWorkspace = buildParentWorkspaceView(installPayload.repoRoot);
+    if (parentWorkspace) {
       console.log(`[${TOOL_NAME}] Parent workspace view: ${parentWorkspace.workspacePath}`);
     }
 
@@ -5216,6 +6027,7 @@ function setup(rawArgs) {
     } else if (autoFinishSummary.details.length > 0) {
       console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
     }
+    printSetupRepoHints(scanResult.repoRoot, currentBaseBranch, repoLabel);
 
     aggregateErrors += scanResult.errors;
     aggregateWarnings += scanResult.warnings;
@@ -5275,6 +6087,156 @@ function ensureCleanWorkingTree(repoRoot) {
   }
 }
 
+function readReleaseRepoPackageJson(repoRoot) {
+  const manifestPath = path.join(repoRoot, 'package.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`Release blocked: package.json missing in ${repoRoot}`);
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Release blocked: unable to parse package.json in ${repoRoot}: ${error.message}`);
+  }
+}
+
+function resolveReleaseGithubRepo(repoRoot) {
+  const releasePackageJson = readReleaseRepoPackageJson(repoRoot);
+  const fromManifest = inferGithubRepoSlug(
+    releasePackageJson.repository &&
+      (releasePackageJson.repository.url || releasePackageJson.repository),
+  );
+  if (fromManifest) {
+    return fromManifest;
+  }
+
+  const fromOrigin = inferGithubRepoSlug(readGitConfig(repoRoot, 'remote.origin.url'));
+  if (fromOrigin) {
+    return fromOrigin;
+  }
+
+  throw new Error(
+    'Release blocked: unable to resolve GitHub repo from package.json repository URL or origin remote.',
+  );
+}
+
+function readRepoReadme(repoRoot) {
+  const readmePath = path.join(repoRoot, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    throw new Error(`Release blocked: README.md missing in ${repoRoot}`);
+  }
+  return fs.readFileSync(readmePath, 'utf8');
+}
+
+function parseReadmeReleaseEntries(readmeContent) {
+  const releaseNotesIndex = String(readmeContent || '').indexOf('## Release notes');
+  if (releaseNotesIndex < 0) {
+    throw new Error('Release blocked: README.md is missing the "## Release notes" section');
+  }
+
+  const releaseNotesContent = String(readmeContent || '').slice(releaseNotesIndex);
+  const entries = [];
+  const lines = releaseNotesContent.split(/\r?\n/);
+  let currentTag = '';
+  let currentLines = [];
+
+  function flushEntry() {
+    if (!currentTag) {
+      return;
+    }
+    const body = currentLines.join('\n').trim();
+    if (body) {
+      entries.push({ tag: currentTag, body, version: parseVersionString(currentTag) });
+    }
+    currentTag = '';
+    currentLines = [];
+  }
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^###\s+(v\d+\.\d+\.\d+)\s*$/);
+    if (headingMatch) {
+      flushEntry();
+      currentTag = headingMatch[1];
+      continue;
+    }
+
+    if (!currentTag) {
+      continue;
+    }
+
+    if (/^<\/details>\s*$/.test(line) || /^##\s+/.test(line)) {
+      flushEntry();
+      continue;
+    }
+
+    currentLines.push(line);
+  }
+
+  flushEntry();
+
+  if (entries.length === 0) {
+    throw new Error('Release blocked: README.md did not yield any versioned release-note sections');
+  }
+
+  return entries;
+}
+
+function resolvePreviousPublishedReleaseTag(repoSlug, currentTag) {
+  const result = run(GH_BIN, ['release', 'list', '--repo', repoSlug, '--limit', '20'], {
+    timeout: 20_000,
+  });
+  if (result.error) {
+    throw new Error(`Release blocked: unable to run '${GH_BIN} release list': ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const details = (result.stderr || result.stdout || '').trim();
+    throw new Error(`Release blocked: unable to list GitHub releases.${details ? `\n${details}` : ''}`);
+  }
+
+  const tags = String(result.stdout || '')
+    .split('\n')
+    .map((line) => line.split('\t')[0].trim())
+    .filter(Boolean);
+
+  return tags.find((tag) => tag !== currentTag) || '';
+}
+
+function selectReleaseEntriesForWindow(entries, currentTag, previousTag) {
+  const currentVersion = parseVersionString(currentTag);
+  if (!currentVersion) {
+    throw new Error(`Release blocked: invalid current version tag '${currentTag}'`);
+  }
+  const previousVersion = previousTag ? parseVersionString(previousTag) : null;
+
+  const selected = entries.filter((entry) => {
+    if (!entry.version) return false;
+    if (compareParsedVersions(entry.version, currentVersion) > 0) return false;
+    if (!previousVersion) return entry.tag === currentTag;
+    return compareParsedVersions(entry.version, previousVersion) > 0;
+  });
+
+  if (!selected.some((entry) => entry.tag === currentTag)) {
+    throw new Error(`Release blocked: README.md is missing release notes for ${currentTag}`);
+  }
+
+  return selected;
+}
+
+function renderGeneratedReleaseNotes(entries, currentTag, previousTag) {
+  const intro = previousTag ? `Changes since ${previousTag}.` : `Changes in ${currentTag}.`;
+  const sections = entries
+    .map((entry) => `### ${entry.tag}\n${entry.body}`)
+    .join('\n\n');
+  return `GitGuardex ${currentTag}\n\n${intro}\n\n${sections}`;
+}
+
+function buildReleaseNotesFromReadme(repoRoot, currentTag, previousTag) {
+  const readme = readRepoReadme(repoRoot);
+  const entries = parseReadmeReleaseEntries(readme);
+  const selected = selectReleaseEntriesForWindow(entries, currentTag, previousTag);
+  return renderGeneratedReleaseNotes(selected, currentTag, previousTag);
+}
+
 function release(rawArgs) {
   if (rawArgs.length > 0) {
     throw new Error(`Unknown option: ${rawArgs[0]}`);
@@ -5290,13 +6252,74 @@ function release(rawArgs) {
   ensureMainBranch(repoRoot);
   ensureCleanWorkingTree(repoRoot);
 
-  console.log(`[${TOOL_NAME}] Releasing ${packageJson.name}@${packageJson.version} from ${repoRoot}`);
-  const publishResult = run(NPM_BIN, ['publish'], { cwd: repoRoot, stdio: 'inherit' });
-  if (publishResult.status !== 0) {
-    throw new Error('npm publish failed');
+  if (!isCommandAvailable(GH_BIN)) {
+    throw new Error(`Release blocked: '${GH_BIN}' is not available`);
+  }
+
+  const ghAuthStatus = run(GH_BIN, ['auth', 'status'], { timeout: 20_000 });
+  if (ghAuthStatus.error) {
+    throw new Error(`Release blocked: unable to run '${GH_BIN} auth status': ${ghAuthStatus.error.message}`);
+  }
+  if (ghAuthStatus.status !== 0) {
+    const details = (ghAuthStatus.stderr || ghAuthStatus.stdout || '').trim();
+    throw new Error(`Release blocked: '${GH_BIN}' auth is unavailable.${details ? `\n${details}` : ''}`);
+  }
+
+  const releasePackageJson = readReleaseRepoPackageJson(repoRoot);
+  const repoSlug = resolveReleaseGithubRepo(repoRoot);
+  const currentTag = `v${releasePackageJson.version}`;
+  const previousTag = resolvePreviousPublishedReleaseTag(repoSlug, currentTag);
+  const notes = buildReleaseNotesFromReadme(repoRoot, currentTag, previousTag);
+  const headCommit = gitRun(repoRoot, ['rev-parse', 'HEAD']).stdout.trim();
+
+  const existingRelease = run(GH_BIN, ['release', 'view', currentTag, '--repo', repoSlug], {
+    timeout: 20_000,
+  });
+  if (existingRelease.error) {
+    throw new Error(`Release blocked: unable to run '${GH_BIN} release view': ${existingRelease.error.message}`);
+  }
+
+  const releaseArgs =
+    existingRelease.status === 0
+      ? ['release', 'edit', currentTag, '--repo', repoSlug, '--title', currentTag, '--notes', notes]
+      : [
+          'release',
+          'create',
+          currentTag,
+          '--repo',
+          repoSlug,
+          '--target',
+          headCommit,
+          '--title',
+          currentTag,
+          '--notes',
+          notes,
+        ];
+
+  console.log(
+    `[${TOOL_NAME}] ${existingRelease.status === 0 ? 'Updating' : 'Creating'} GitHub release ${currentTag} on ${repoSlug}`,
+  );
+  if (previousTag) {
+    console.log(`[${TOOL_NAME}] Aggregating README release notes newer than ${previousTag}.`);
+  } else {
+    console.log(`[${TOOL_NAME}] No earlier published GitHub release found; using only ${currentTag}.`);
+  }
+
+  const releaseResult = run(GH_BIN, releaseArgs, { cwd: repoRoot, timeout: 60_000 });
+  if (releaseResult.error) {
+    throw new Error(`Release blocked: unable to run '${GH_BIN} release': ${releaseResult.error.message}`);
+  }
+  if (releaseResult.status !== 0) {
+    const details = (releaseResult.stderr || releaseResult.stdout || '').trim();
+    throw new Error(`GitHub release command failed.${details ? `\n${details}` : ''}`);
+  }
+
+  const releaseUrl = String(releaseResult.stdout || '').trim();
+  if (releaseUrl) {
+    console.log(releaseUrl);
   }
 
-  console.log(`[${TOOL_NAME}] ✅ Publish complete.`);
+  console.log(`[${TOOL_NAME}] ✅ GitHub release ${currentTag} is synced to the README history.`);
   process.exitCode = 0;
 }
 
@@ -5649,6 +6672,46 @@ function cleanup(rawArgs) {
   process.exitCode = 0;
 }
 
+function merge(rawArgs) {
+  const options = parseMergeArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(options.target);
+  const mergeScript = path.join(repoRoot, 'scripts', 'agent-branch-merge.sh');
+
+  if (!fs.existsSync(mergeScript)) {
+    throw new Error(`Missing merge script: ${mergeScript}. Run '${SHORT_TOOL_NAME} setup' first.`);
+  }
+
+  const args = [mergeScript];
+  if (options.base) {
+    args.push('--base', options.base);
+  }
+  if (options.into) {
+    args.push('--into', options.into);
+  }
+  if (options.task) {
+    args.push('--task', options.task);
+  }
+  if (options.agent) {
+    args.push('--agent', options.agent);
+  }
+  for (const branch of options.branches) {
+    args.push('--branch', branch);
+  }
+
+  const mergeResult = run('bash', args, { cwd: repoRoot, stdio: 'pipe' });
+  if (mergeResult.stdout) {
+    process.stdout.write(mergeResult.stdout);
+  }
+  if (mergeResult.stderr) {
+    process.stderr.write(mergeResult.stderr);
+  }
+  if (mergeResult.status !== 0) {
+    throw new Error(`merge command failed with status ${mergeResult.status}`);
+  }
+
+  process.exitCode = 0;
+}
+
 function finish(rawArgs) {
   const options = parseFinishArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -6100,6 +7163,7 @@ function main() {
   }
 
   if (command === '--version' || command === '-v' || command === 'version') {
+    maybeSelfUpdateBeforeStatus();
     console.log(packageJson.version);
     return;
   }
@@ -6134,6 +7198,7 @@ function main() {
   if (command === 'prompt') return prompt(rest);
   if (command === 'doctor') return doctor(rest);
   if (command === 'agents') return agents(rest);
+  if (command === 'merge') return merge(rest);
   if (command === 'finish') return finish(rest);
   if (command === 'report') return report(rest);
   if (command === 'protect') return protect(rest);