@imdeadpool/guardex 7.0.13 → 7.0.15

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,6 +77,12 @@ 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');
 
@@ -84,6 +90,7 @@ const TEMPLATE_FILES = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.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 +112,7 @@ const TEMPLATE_FILES = [
 const REQUIRED_WORKFLOW_FILES = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/guardex-docker-loader.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
   'scripts/guardex-env.sh',
@@ -115,21 +123,34 @@ const REQUIRED_WORKFLOW_FILES = [
 ];
 
 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:cleanup': 'bash ./scripts/agent-worktree-prune.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',
+  'agent:locks:allow-delete': 'python3 ./scripts/agent-file-locks.py allow-delete',
   'agent:locks:release': 'python3 ./scripts/agent-file-locks.py release',
   'agent:locks:status': 'python3 ./scripts/agent-file-locks.py status',
   'agent:plan:init': 'bash ./scripts/openspec/init-plan-workspace.sh',
   'agent:change:init': 'bash ./scripts/openspec/init-change-workspace.sh',
+  'agent:protect:list': 'gx protect list',
+  'agent:branch:sync': 'gx sync',
+  'agent:branch:sync:check': 'gx sync --check',
+  'agent:safety:setup': 'gx setup',
+  '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',
 };
 
 const EXECUTABLE_RELATIVE_PATHS = new Set([
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.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',
@@ -162,35 +183,34 @@ 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-branch-finish.sh',
-  'scripts/codex-agent.sh',
-  'scripts/review-bot-watch.sh',
-  'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
-  'scripts/guardex-env.sh',
-  'scripts/install-agent-git-hooks.sh',
-  'scripts/openspec/init-plan-workspace.sh',
-  'scripts/openspec/init-change-workspace.sh',
-  '.githooks/pre-commit',
-  '.githooks/pre-push',
-  '.githooks/post-merge',
-  '.githooks/post-checkout',
+  '.githooks',
   'oh-my-codex/',
   '.codex/skills/gitguardex/SKILL.md',
   '.codex/skills/guardex-merge-skills-to-dev/SKILL.md',
   '.claude/commands/gitguardex.md',
   LOCK_FILE_RELATIVE,
 ];
+const REPO_SCAFFOLD_DIRECTORIES = ['bin'];
 const OMX_SCAFFOLD_DIRECTORIES = [
   '.omx',
   '.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'],
@@ -240,6 +260,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['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)'],
@@ -260,20 +281,33 @@ const AGENT_BOT_DESCRIPTIONS = [
   ['agents', 'Start/stop review + cleanup bots for this repo'],
 ];
 
+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.
 
 1) Install:    npm i -g @imdeadpool/guardex && gh --version
 2) Bootstrap:  gx setup
 3) Repair:     gx doctor
 4) Task loop:  bash scripts/codex-agent.sh "<task>" "<agent>"
-               or branch-start -> claim -> branch-finish
+               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:  cp .github/pull.yml.example .github/pull.yml
+11) 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
@@ -281,6 +315,7 @@ gh --version
 gx setup
 gx doctor
 bash scripts/codex-agent.sh "<task>" "<agent>"
+python3 scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>
 gx finish --all
 gx cleanup
 gx protect add release staging
@@ -508,8 +543,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 : []);
@@ -524,7 +557,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);
 
@@ -556,7 +589,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);
     }
   }
@@ -598,9 +631,27 @@ function toDestinationPath(relativeTemplatePath) {
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 
-function ensureParentDir(filePath, dryRun) {
+function ensureParentDir(repoRoot, filePath, dryRun) {
   if (dryRun) return;
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const parentDir = path.dirname(filePath);
+  const relativeParentDir = path.relative(repoRoot, parentDir);
+  const segments = relativeParentDir.split(path.sep).filter(Boolean);
+  let currentPath = repoRoot;
+
+  for (const segment of segments) {
+    currentPath = path.join(currentPath, segment);
+    if (fs.existsSync(currentPath) && !fs.statSync(currentPath).isDirectory()) {
+      const blockingPath = path.relative(repoRoot, currentPath) || path.basename(currentPath);
+      const targetPath = path.relative(repoRoot, filePath) || path.basename(filePath);
+      throw new Error(
+        `Path conflict: ${blockingPath} exists as a file, but ${targetPath} needs it to be a directory. ` +
+        `Remove or rename ${blockingPath} and rerun '${SHORT_TOOL_NAME} setup'.`,
+      );
+    }
+  }
+
+  fs.mkdirSync(parentDir, { recursive: true });
 }
 
 function ensureExecutable(destinationPath, relativePath, dryRun) {
@@ -635,7 +686,7 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
     }
   }
 
-  ensureParentDir(destinationPath, dryRun);
+  ensureParentDir(repoRoot, destinationPath, dryRun);
   if (!dryRun) {
     fs.writeFileSync(destinationPath, sourceContent, 'utf8');
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
@@ -673,7 +724,7 @@ function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
     return { status: 'skipped-conflict', file: destinationRelativePath };
   }
 
-  ensureParentDir(destinationPath, dryRun);
+  ensureParentDir(repoRoot, destinationPath, dryRun);
   if (!dryRun) {
     fs.writeFileSync(destinationPath, sourceContent, 'utf8');
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
@@ -689,6 +740,22 @@ function lockFilePath(repoRoot) {
 function ensureOmxScaffold(repoRoot, dryRun) {
   const operations = [];
 
+  for (const relativeDir of REPO_SCAFFOLD_DIRECTORIES) {
+    const absoluteDir = path.join(repoRoot, relativeDir);
+    if (fs.existsSync(absoluteDir)) {
+      if (!fs.statSync(absoluteDir).isDirectory()) {
+        throw new Error(`Expected directory at ${relativeDir} but found a file.`);
+      }
+      operations.push({ status: 'unchanged', file: relativeDir });
+      continue;
+    }
+
+    if (!dryRun) {
+      fs.mkdirSync(absoluteDir, { recursive: true });
+    }
+    operations.push({ status: 'created', file: relativeDir });
+  }
+
   for (const relativeDir of OMX_SCAFFOLD_DIRECTORIES) {
     const absoluteDir = path.join(repoRoot, relativeDir);
     if (fs.existsSync(absoluteDir)) {
@@ -965,6 +1032,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}`);
   }
@@ -976,10 +1051,9 @@ function parseCommonArgs(rawArgs, defaults) {
   return options;
 }
 
-function parseSetupArgs(rawArgs, defaults) {
-  const setupDefaults = {
+function parseRepoTraversalArgs(rawArgs, defaults) {
+  const traversalDefaults = {
     ...defaults,
-    parentWorkspaceView: false,
     recursive: true,
     nestedMaxDepth: NESTED_REPO_DEFAULT_MAX_DEPTH,
     nestedSkipDirs: [],
@@ -989,20 +1063,12 @@ function parseSetupArgs(rawArgs, defaults) {
 
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
-    if (arg === '--parent-workspace-view') {
-      setupDefaults.parentWorkspaceView = true;
-      continue;
-    }
-    if (arg === '--no-parent-workspace-view') {
-      setupDefaults.parentWorkspaceView = false;
-      continue;
-    }
     if (arg === '--no-recursive' || arg === '--no-nested' || arg === '--single-repo') {
-      setupDefaults.recursive = false;
+      traversalDefaults.recursive = false;
       continue;
     }
     if (arg === '--recursive' || arg === '--nested') {
-      setupDefaults.recursive = true;
+      traversalDefaults.recursive = true;
       continue;
     }
     if (arg === '--max-depth') {
@@ -1011,47 +1077,61 @@ function parseSetupArgs(rawArgs, defaults) {
       if (!Number.isFinite(parsed) || parsed < 1) {
         throw new Error('--max-depth requires a positive integer');
       }
-      setupDefaults.nestedMaxDepth = parsed;
+      traversalDefaults.nestedMaxDepth = parsed;
       index += 1;
       continue;
     }
     if (arg === '--skip-nested') {
       const raw = requireValue(rawArgs, index, '--skip-nested');
-      setupDefaults.nestedSkipDirs.push(raw);
+      traversalDefaults.nestedSkipDirs.push(raw);
       index += 1;
       continue;
     }
     if (arg === '--include-submodules') {
-      setupDefaults.includeSubmodules = true;
+      traversalDefaults.includeSubmodules = true;
       continue;
     }
     forwardedArgs.push(arg);
   }
 
-  return parseCommonArgs(forwardedArgs, setupDefaults);
+  return parseCommonArgs(forwardedArgs, traversalDefaults);
 }
 
-function parseDoctorArgs(rawArgs) {
-  const options = {
-    target: process.cwd(),
-    strict: false,
+function parseSetupArgs(rawArgs, defaults) {
+  const setupDefaults = {
+    ...defaults,
+    parentWorkspaceView: false,
   };
+  const forwardedArgs = [];
 
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
-    if (arg === '--target' || arg === '-t') {
-      options.target = requireValue(rawArgs, index, '--target');
-      index += 1;
+    if (arg === '--parent-workspace-view') {
+      setupDefaults.parentWorkspaceView = true;
       continue;
     }
-    if (arg === '--strict') {
-      options.strict = true;
+    if (arg === '--no-parent-workspace-view') {
+      setupDefaults.parentWorkspaceView = false;
       continue;
     }
-    throw new Error(`Unknown option: ${arg}`);
+    forwardedArgs.push(arg);
   }
 
-  return options;
+  return parseRepoTraversalArgs(forwardedArgs, setupDefaults);
+}
+
+function parseDoctorArgs(rawArgs) {
+  return parseRepoTraversalArgs(rawArgs, {
+    target: process.cwd(),
+    dropStaleLocks: true,
+    skipAgents: false,
+    skipPackageJson: false,
+    skipGitignore: false,
+    dryRun: false,
+    json: false,
+    allowProtectedBaseWrite: false,
+    waitForMerge: true,
+  });
 }
 
 function normalizeWorkspacePath(relativePath) {
@@ -1063,16 +1143,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,
@@ -1156,6 +1235,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);
@@ -1169,7 +1282,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;
@@ -1177,6 +1290,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');
@@ -1185,6 +1308,7 @@ 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.json) args.push('--json');
   return args;
 }
@@ -1220,7 +1344,7 @@ function ensureRepoBranch(repoRoot, branch) {
   return { ok: true, changed: true };
 }
 
-function doctorSandboxBranchPrefix() {
+function protectedBaseSandboxBranchPrefix() {
   const now = new Date();
   const stamp = [
     now.getUTCFullYear(),
@@ -1234,15 +1358,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}`;
@@ -1250,18 +1374,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;
     }
@@ -1274,20 +1401,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 {
@@ -1302,16 +1445,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',
@@ -1321,7 +1468,7 @@ function startDoctorSandbox(blocked) {
     throw startResult.error;
   }
   if (startResult.status !== 0) {
-    return startDoctorSandboxFallback(blocked);
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
   const metadata = extractAgentBranchStartMetadata(startResult.stdout);
@@ -1336,11 +1483,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 {
@@ -1350,6 +1497,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')
@@ -1388,6 +1588,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) {
@@ -1399,7 +1652,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], {
@@ -1431,7 +1687,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}`],
@@ -1496,7 +1764,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 {
@@ -1538,10 +1806,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, '--via-pr', '--wait-for-merge'],
+    [finishScript, '--branch', metadata.branch, '--base', blocked.branch, '--via-pr', waitForMergeArg],
     { cwd: metadata.worktreePath, timeout: finishTimeoutMs },
   );
   if (isSpawnFailure(finishResult)) {
@@ -1580,8 +1849,186 @@ function finishDoctorSandboxBranch(blocked, metadata) {
   };
 }
 
+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 },
+  );
+  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 || '',
+    };
+  }
+
+  let hookRefreshResult;
+  try {
+    hookRefreshResult = configureHooks(blocked.repoRoot, false);
+  } catch (error) {
+    return {
+      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: '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);
@@ -1603,10 +2050,15 @@ function runDoctorInSandbox(options, blocked) {
     note: 'sandbox doctor did not complete successfully',
   };
 
+  let protectedBaseRepairSyncResult = {
+    status: 'skipped',
+    note: 'sandbox doctor did not complete successfully',
+  };
   let lockSyncResult = {
     status: 'skipped',
     note: 'sandbox doctor did not complete successfully',
   };
+  let sandboxLockContent = null;
   let postSandboxAutoFinishSummary = {
     enabled: false,
     attempted: 0,
@@ -1639,7 +2091,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',
@@ -1675,7 +2127,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 = {
@@ -1692,6 +2148,62 @@ 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,
@@ -1708,6 +2220,7 @@ function runDoctorInSandbox(options, blocked) {
             JSON.stringify(
               {
                 ...parsed,
+                protectedBaseRepairSync: protectedBaseRepairSyncResult,
                 sandboxOmxScaffoldSync: omxScaffoldSyncResult,
                 sandboxLockSync: lockSyncResult,
                 sandboxAutoCommit: autoCommitResult,
@@ -1738,14 +2251,38 @@ function runDoctorInSandbox(options, blocked) {
     if (nestedResult.status === 0) {
       if (autoCommitResult.status === 'committed') {
         console.log(
-          `[${TOOL_NAME}] Auto-committed doctor repairs in sandbox branch '${metadata.branch}'.`,
+          `[${TOOL_NAME}] Auto-committed doctor repairs in sandbox branch '${metadata.branch}'.`,
+        );
+      } else if (autoCommitResult.status === 'failed') {
+        console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit failed; branch left for manual follow-up.`);
+        if (autoCommitResult.stdout) process.stdout.write(autoCommitResult.stdout);
+        if (autoCommitResult.stderr) process.stderr.write(autoCommitResult.stderr);
+      } else {
+        console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit skipped: ${autoCommitResult.note}.`);
+      }
+
+      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 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 (autoCommitResult.status === 'failed') {
-        console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit failed; branch left for manual follow-up.`);
-        if (autoCommitResult.stdout) process.stdout.write(autoCommitResult.stdout);
-        if (autoCommitResult.stderr) process.stderr.write(autoCommitResult.stderr);
+      } else if (lockSyncResult.status === 'unchanged') {
+        console.log(`[${TOOL_NAME}] Lock registry already synced in protected branch workspace.`);
       } else {
-        console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit skipped: ${autoCommitResult.note}.`);
+        console.log(`[${TOOL_NAME}] Lock registry sync skipped: ${lockSyncResult.note}.`);
       }
 
       if (finishResult.status === 'completed') {
@@ -1763,22 +2300,13 @@ 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}`,
@@ -1813,12 +2341,89 @@ function runDoctorInSandbox(options, blocked) {
     ) {
       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}`);
+    }
+  } else if (autoFinishSummary.details.length > 0) {
+    console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
+  }
+
+  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()) {
   const remaining = [];
   let target = defaultTarget;
@@ -2000,6 +2605,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();
@@ -2483,6 +3101,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) {
@@ -3294,6 +3972,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);
@@ -3302,11 +3991,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) {
@@ -3897,6 +4582,10 @@ function runInstallInternal(options) {
   }
   const operations = [];
 
+  if (!options.skipGitignore) {
+    operations.push(ensureManagedGitignore(repoRoot, Boolean(options.dryRun)));
+  }
+
   operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
 
   for (const templateFile of TEMPLATE_FILES) {
@@ -3904,9 +4593,6 @@ function runInstallInternal(options) {
   }
 
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
-  if (!options.skipGitignore) {
-    operations.push(ensureManagedGitignore(repoRoot, Boolean(options.dryRun)));
-  }
 
   if (!options.skipPackageJson) {
     operations.push(ensurePackageScripts(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
@@ -3941,6 +4627,10 @@ function runFixInternal(options) {
   }
   const operations = [];
 
+  if (!options.skipGitignore) {
+    operations.push(ensureManagedGitignore(repoRoot, Boolean(options.dryRun)));
+  }
+
   operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
 
   for (const templateFile of TEMPLATE_FILES) {
@@ -3948,9 +4638,6 @@ function runFixInternal(options) {
   }
 
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
-  if (!options.skipGitignore) {
-    operations.push(ensureManagedGitignore(repoRoot, Boolean(options.dryRun)));
-  }
 
   const lockState = lockStateOrError(repoRoot);
   if (!lockState.ok) {
@@ -3994,8 +4681,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,
@@ -4421,26 +5107,118 @@ function scan(rawArgs) {
 }
 
 function doctor(rawArgs) {
-  const options = parseCommonArgs(rawArgs, {
-    target: process.cwd(),
-    dropStaleLocks: true,
-    skipAgents: false,
-    skipPackageJson: false,
-    skipGitignore: false,
-    dryRun: false,
-    json: false,
-    allowProtectedBaseWrite: false,
-  });
+  const options = parseDoctorArgs(rawArgs);
+  const topRepoRoot = resolveRepoRoot(options.target);
+  const discoveredRepos = options.recursive
+    ? discoverNestedGitRepos(topRepoRoot, {
+      maxDepth: options.nestedMaxDepth,
+      extraSkip: options.nestedSkipDirs,
+      includeSubmodules: options.includeSubmodules,
+    })
+    : [topRepoRoot];
+
+  if (discoveredRepos.length > 1) {
+    if (!options.json) {
+      console.log(
+        `[${TOOL_NAME}] Detected ${discoveredRepos.length} git repos under ${topRepoRoot}. ` +
+        `Repairing each with doctor (use --single-repo to limit to the target).`,
+      );
+    }
+
+    const repoResults = [];
+    let aggregateExitCode = 0;
+    for (const repoPath of discoveredRepos) {
+      if (!options.json) {
+        console.log(`[${TOOL_NAME}] ── Doctor target: ${repoPath} ──`);
+      }
+
+      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'] : []),
+          // Recursive child doctor runs should report pending PR state immediately instead of blocking the parent loop.
+          '--no-wait-for-merge',
+          ...(options.json ? ['--json'] : []),
+          ...(options.allowProtectedBaseWrite ? ['--allow-protected-base-write'] : []),
+        ],
+        { cwd: topRepoRoot },
+      );
+      if (isSpawnFailure(nestedResult)) {
+        throw nestedResult.error;
+      }
+
+      const exitCode = typeof nestedResult.status === 'number' ? nestedResult.status : 1;
+      if (exitCode !== 0 && aggregateExitCode === 0) {
+        aggregateExitCode = exitCode;
+      }
+
+      if (options.json) {
+        let parsedResult = null;
+        if (nestedResult.stdout) {
+          try {
+            parsedResult = JSON.parse(nestedResult.stdout);
+          } catch {
+            parsedResult = null;
+          }
+        }
+        repoResults.push(
+          parsedResult
+            ? { repoRoot: repoPath, exitCode, result: parsedResult }
+            : {
+              repoRoot: repoPath,
+              exitCode,
+              stdout: nestedResult.stdout || '',
+              stderr: nestedResult.stderr || '',
+            },
+        );
+      } else {
+        if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
+        if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+        process.stdout.write('\n');
+      }
+    }
+
+    if (options.json) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            repoRoot: topRepoRoot,
+            recursive: true,
+            repos: repoResults,
+          },
+          null,
+          2,
+        ) + '\n',
+      );
+    }
+
+    process.exitCode = aggregateExitCode;
+    return;
+  }
+
+  const singleRepoOptions = {
+    ...options,
+    target: topRepoRoot,
+  };
 
-  const blocked = protectedBaseWriteBlock(options, { requireBootstrap: false });
+  const blocked = protectedBaseWriteBlock(singleRepoOptions, { requireBootstrap: false });
   if (blocked) {
-    runDoctorInSandbox(options, blocked);
+    runDoctorInSandbox(singleRepoOptions, blocked);
     return;
   }
 
-  assertProtectedMainWriteAllowed(options, 'doctor');
-  const fixPayload = runFixInternal(options);
-  const scanResult = runScanInternal({ target: options.target, json: false });
+  assertProtectedMainWriteAllowed(singleRepoOptions, 'doctor');
+  const fixPayload = runFixInternal(singleRepoOptions);
+  const scanResult = runScanInternal({ target: singleRepoOptions.target, json: false });
   const currentBaseBranch = currentBranchName(scanResult.repoRoot);
   const autoFinishSummary = scanResult.guardexEnabled === false
     ? {
@@ -4453,12 +5231,12 @@ function doctor(rawArgs) {
     }
     : autoFinishReadyAgentBranches(scanResult.repoRoot, {
       baseBranch: currentBaseBranch,
-      dryRun: options.dryRun,
+      dryRun: singleRepoOptions.dryRun,
     });
   const safe = scanResult.guardexEnabled === false || (scanResult.errors === 0 && scanResult.warnings === 0);
   const musafe = safe;
 
-  if (options.json) {
+  if (singleRepoOptions.json) {
     process.stdout.write(
       JSON.stringify(
         {
@@ -4469,7 +5247,7 @@ function doctor(rawArgs) {
           fix: {
             operations: fixPayload.operations,
             hookResult: fixPayload.hookResult,
-            dryRun: Boolean(options.dryRun),
+            dryRun: Boolean(singleRepoOptions.dryRun),
           },
           scan: {
             guardexEnabled: scanResult.guardexEnabled !== false,
@@ -4997,31 +5775,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}`);
     }
 
@@ -5042,6 +5813,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;
@@ -5101,6 +5873,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]}`);
@@ -5116,13 +6038,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;
 }
 
@@ -5926,6 +6909,7 @@ function main() {
   }
 
   if (command === '--version' || command === '-v' || command === 'version') {
+    maybeSelfUpdateBeforeStatus();
     console.log(packageJson.version);
     return;
   }