@imdeadpool/guardex 7.0.21 → 7.0.22

package/src/cli/main.js

@@ -3,7 +3,8 @@
 const hooksModule = require('../hooks');
 const sandboxModule = require('../sandbox');
 const toolchainModule = require('../toolchain');
-const finishModule = require('../finish');
+const finishCommands = require('../finish');
+const doctorModule = require('../doctor');
 const {
   fs,
   path,
@@ -60,6 +61,9 @@ const {
   DEPRECATED_COMMAND_ALIASES,
   envFlagIsTruthy,
   defaultAgentWorktreeRelativeDir,
+  listAiSetupPartNames,
+  parseAiSetupPartNames,
+  renderAiSetupPrompt,
   AI_SETUP_PROMPT,
   AI_SETUP_COMMANDS,
   SCORECARD_RISK_BY_CHECK,
@@ -69,6 +73,37 @@ const {
   resolveRepoRoot,
   isGitRepo,
   discoverNestedGitRepos,
+  uniquePreserveOrder,
+  listLocalUserBranches,
+  listLocalAgentBranches,
+  mapWorktreePathsByBranch,
+  gitRefExists,
+  hasSignificantWorkingTreeChanges,
+  readConfiguredProtectedBranches,
+  readProtectedBranches,
+  ensureSetupProtectedBranches,
+  writeProtectedBranches,
+  readGitConfig,
+  resolveBaseBranch,
+  resolveSyncStrategy,
+  currentBranchName,
+  repoHasHeadCommit,
+  readBranchDisplayName,
+  hasOriginRemote: repoHasOriginRemote,
+  detectComposeHintFiles,
+  printSetupRepoHints,
+  ensureRepoBranch,
+  ensureOriginBaseRef,
+  workingTreeIsDirty,
+  aheadBehind,
+  lockRegistryStatus,
+  listAgentWorktrees,
+  listLocalAgentBranchesForFinish,
+  worktreeHasLocalChanges,
+  branchExists,
+  resolveFinishBaseBranch,
+  branchMergedIntoBase,
+  syncOperation,
 } = require('../git');
 const {
   run,
@@ -119,94 +154,30 @@ const {
   renderShellDispatchShim,
   renderPythonDispatchShim,
   managedForceConflictMessage,
+  renderManagedFile,
+  ensureGeneratedScriptShim,
+  ensureHookShim,
+  copyTemplateFile,
+  ensureTemplateFilePresent,
+  ensureOmxScaffold,
+  ensureLockRegistry,
+  lockStateOrError,
+  writeLockState,
+  removeLegacyPackageScripts,
+  installUserLevelAsset,
+  removeLegacyManagedRepoFile,
+  ensureAgentsSnippet,
+  ensureManagedGitignore,
+  stripJsonComments,
+  stripJsonTrailingCommas,
+  parseJsonObjectLikeFile,
+  buildRepoVscodeSettings,
+  ensureRepoVscodeSettings,
+  configureHooks,
   printOperations,
   printStandaloneOperations,
 } = require('../scaffold');
 
-let sandboxApi;
-let toolchainApi;
-let finishApi;
-
-function getSandboxApi() {
-  if (!sandboxApi) {
-    sandboxApi = sandboxModule.createSandboxApi({
-      protectedBaseWriteBlock,
-      runInstallInternal,
-      ensureSetupProtectedBranches,
-      ensureParentWorkspaceView,
-      buildParentWorkspaceView,
-      runFixInternal,
-    });
-  }
-  return sandboxApi;
-}
-
-function getToolchainApi() {
-  if (!toolchainApi) {
-    toolchainApi = toolchainModule.createToolchainApi({
-      TOOL_NAME,
-      NPM_BIN,
-      NPX_BIN,
-      packageJson,
-      OPENSPEC_PACKAGE,
-      OPENSPEC_BIN,
-      GLOBAL_TOOLCHAIN_PACKAGES,
-      parseAutoApproval,
-      isInteractiveTerminal,
-      promptYesNoStrict,
-      run,
-      checkForGuardexUpdate,
-      printUpdateAvailableBanner,
-      readInstalledGuardexVersion,
-      restartIntoUpdatedGuardex,
-      checkForOpenSpecPackageUpdate,
-      printOpenSpecUpdateAvailableBanner,
-      resolveGlobalInstallApproval,
-      detectGlobalToolchainPackages,
-      detectOptionalLocalCompanionTools,
-      formatGlobalToolchainServiceName,
-      askGlobalInstallForMissing,
-    });
-  }
-  return toolchainApi;
-}
-
-function getFinishApi() {
-  if (!finishApi) {
-    finishApi = finishModule.createFinishApi({
-      TOOL_NAME,
-      LOCK_FILE_RELATIVE,
-      path,
-      fs,
-      run,
-      runPackageAsset,
-      resolveRepoRoot,
-      parseCleanupArgs,
-      parseMergeArgs,
-      parseFinishArgs,
-      parseSyncArgs,
-      listAgentWorktrees,
-      listLocalAgentBranchesForFinish,
-      uniquePreserveOrder,
-      branchExists,
-      resolveFinishBaseBranch,
-      worktreeHasLocalChanges,
-      branchMergedIntoBase,
-      autoCommitWorktreeForFinish,
-      resolveBaseBranch,
-      resolveSyncStrategy,
-      ensureOriginBaseRef,
-      gitRun,
-      currentBranchName,
-      workingTreeIsDirty,
-      aheadBehind,
-      lockRegistryStatus,
-      syncOperation,
-    });
-  }
-  return finishApi;
-}
-
 /**
  * @typedef {Object} AutoFinishSummary
  * @property {boolean} [enabled]
@@ -261,116 +232,27 @@ function getFinishApi() {
  * @property {AutoFinishSummary} autoFinish
  * @property {string | null} sandboxLockContent
  */
-function renderManagedFile(repoRoot, relativePath, content, options = {}) {
-  const destinationPath = path.join(repoRoot, relativePath);
-  const destinationExists = fs.existsSync(destinationPath);
-  const force = Boolean(options.force);
-  const dryRun = Boolean(options.dryRun);
-
-  if (destinationExists) {
-    const existingContent = fs.readFileSync(destinationPath, 'utf8');
-    if (existingContent === content) {
-      ensureExecutable(destinationPath, relativePath, dryRun);
-      return { status: 'unchanged', file: relativePath };
-    }
-    if (!force && !isCriticalGuardrailPath(relativePath)) {
-      throw new Error(managedForceConflictMessage(relativePath));
-    }
-  }
-
-  ensureParentDir(repoRoot, destinationPath, dryRun);
-  if (!dryRun) {
-    fs.writeFileSync(destinationPath, content, 'utf8');
-    ensureExecutable(destinationPath, relativePath, dryRun);
-  }
-
-  if (destinationExists && !force && isCriticalGuardrailPath(relativePath)) {
-    return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: relativePath };
-  }
-
-  return { status: destinationExists ? 'overwritten' : 'created', file: relativePath };
-}
-
-function ensureGeneratedScriptShim(repoRoot, spec, options = {}) {
-  const content = spec.kind === 'python'
-    ? renderPythonDispatchShim(spec.command)
-    : renderShellDispatchShim(spec.command);
-  return renderManagedFile(repoRoot, spec.relativePath, content, options);
-}
-
-function ensureHookShim(repoRoot, hookName, options = {}) {
-  return renderManagedFile(
-    repoRoot,
-    path.posix.join('.githooks', hookName),
-    renderShellDispatchShim(['hook', 'run', hookName]),
-    options,
-  );
-}
-
-function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
-  const sourcePath = path.join(TEMPLATE_ROOT, relativeTemplatePath);
-  const destinationRelativePath = toDestinationPath(relativeTemplatePath);
-  const destinationPath = path.join(repoRoot, destinationRelativePath);
-
-  const sourceContent = fs.readFileSync(sourcePath, 'utf8');
-  const destinationExists = fs.existsSync(destinationPath);
-
-  if (destinationExists) {
-    const existingContent = fs.readFileSync(destinationPath, 'utf8');
-    if (existingContent === sourceContent) {
-      ensureExecutable(destinationPath, destinationRelativePath, dryRun);
-      return { status: 'unchanged', file: destinationRelativePath };
-    }
-    if (!force && !isCriticalGuardrailPath(destinationRelativePath)) {
-      throw new Error(managedForceConflictMessage(destinationRelativePath));
-    }
-  }
 
-  ensureParentDir(repoRoot, destinationPath, dryRun);
-  if (!dryRun) {
-    fs.writeFileSync(destinationPath, sourceContent, 'utf8');
-    ensureExecutable(destinationPath, destinationRelativePath, dryRun);
+function appendForceArgs(args, options) {
+  if (!options.force) {
+    return;
   }
-
-  if (destinationExists && !force && isCriticalGuardrailPath(destinationRelativePath)) {
-    return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
+  args.push('--force');
+  for (const managedPath of options.forceManagedPaths || []) {
+    args.push(managedPath);
   }
-
-  return { status: destinationExists ? 'overwritten' : 'created', file: destinationRelativePath };
 }
 
-function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
-  const sourcePath = path.join(TEMPLATE_ROOT, relativeTemplatePath);
-  const destinationRelativePath = toDestinationPath(relativeTemplatePath);
-  const destinationPath = path.join(repoRoot, destinationRelativePath);
-  const sourceContent = fs.readFileSync(sourcePath, 'utf8');
-
-  if (fs.existsSync(destinationPath)) {
-    const existingContent = fs.readFileSync(destinationPath, 'utf8');
-    if (existingContent === sourceContent) {
-      ensureExecutable(destinationPath, destinationRelativePath, dryRun);
-      return { status: 'unchanged', file: destinationRelativePath };
-    }
-
-    if (isCriticalGuardrailPath(destinationRelativePath)) {
-      if (!dryRun) {
-        fs.writeFileSync(destinationPath, sourceContent, 'utf8');
-        ensureExecutable(destinationPath, destinationRelativePath, dryRun);
-      }
-      return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
-    }
-
-    // In fix mode, avoid silently replacing local customizations.
-    return { status: 'skipped-conflict', file: destinationRelativePath };
+function shouldForceManagedPath(options, relativePath) {
+  if (!options.force) {
+    return false;
   }
-
-  ensureParentDir(repoRoot, destinationPath, dryRun);
-  if (!dryRun) {
-    fs.writeFileSync(destinationPath, sourceContent, 'utf8');
-    ensureExecutable(destinationPath, destinationRelativePath, dryRun);
+  const targetedPaths = Array.isArray(options.forceManagedPaths) ? options.forceManagedPaths : [];
+  if (targetedPaths.length === 0) {
+    return true;
   }
-
-  return { status: 'created', file: destinationRelativePath };
+  const normalized = normalizeManagedForcePath(relativePath);
+  return normalized !== null && targetedPaths.includes(normalized);
 }
 
 function ensureTargetedLegacyWorkflowShims(repoRoot, options) {
@@ -389,2718 +271,595 @@ function ensureTargetedLegacyWorkflowShims(repoRoot, options) {
   return operations;
 }
 
-function lockFilePath(repoRoot) {
-  return path.join(repoRoot, LOCK_FILE_RELATIVE);
+function normalizeWorkspacePath(relativePath) {
+  return String(relativePath || '.').replace(/\\/g, '/');
 }
 
-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 });
-  }
+function isCommandAvailable(commandName) {
+  return run('which', [commandName]).status === 0;
+}
 
-  for (const relativeDir of OMX_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;
-    }
+function buildParentWorkspaceView(repoRoot) {
+  const parentDir = path.dirname(repoRoot);
+  const workspaceFileName = `${path.basename(repoRoot)}-branches.code-workspace`;
+  const workspacePath = path.join(parentDir, workspaceFileName);
+  const repoRelativePath = normalizeWorkspacePath(path.relative(parentDir, repoRoot) || '.');
 
-    if (!dryRun) {
-      fs.mkdirSync(absoluteDir, { recursive: true });
-    }
-    operations.push({ status: 'created', file: relativeDir });
-  }
+  return {
+    workspacePath,
+    payload: {
+      folders: [
+        { path: repoRelativePath },
+        ...AGENT_WORKTREE_RELATIVE_DIRS.map((relativeDir) => ({
+          path: normalizeWorkspacePath(path.join(repoRelativePath === '.' ? '' : repoRelativePath, relativeDir)),
+        })),
+      ],
+      settings: {
+        'scm.alwaysShowRepositories': true,
+      },
+    },
+  };
+}
 
-  for (const [relativeFile, defaultContent] of OMX_SCAFFOLD_FILES.entries()) {
-    const absoluteFile = path.join(repoRoot, relativeFile);
-    if (fs.existsSync(absoluteFile)) {
-      if (!fs.statSync(absoluteFile).isFile()) {
-        throw new Error(`Expected file at ${relativeFile} but found a directory.`);
-      }
-      operations.push({ status: 'unchanged', file: relativeFile });
-      continue;
-    }
+function ensureParentWorkspaceView(repoRoot, dryRun) {
+  const { workspacePath, payload } = buildParentWorkspaceView(repoRoot);
+  const operationFile = path.relative(repoRoot, workspacePath) || path.basename(workspacePath);
+  const nextContent = `${JSON.stringify(payload, null, 2)}\n`;
+  const note = 'parent VS Code workspace view';
 
+  if (!fs.existsSync(workspacePath)) {
     if (!dryRun) {
-      fs.mkdirSync(path.dirname(absoluteFile), { recursive: true });
-      fs.writeFileSync(absoluteFile, defaultContent, 'utf8');
+      fs.writeFileSync(workspacePath, nextContent, 'utf8');
     }
-    operations.push({ status: 'created', file: relativeFile });
+    return { status: dryRun ? 'would-create' : 'created', file: operationFile, note };
   }
 
-  return operations;
-}
-
-function ensureLockRegistry(repoRoot, dryRun) {
-  const absolutePath = lockFilePath(repoRoot);
-  if (fs.existsSync(absolutePath)) {
-    return { status: 'unchanged', file: LOCK_FILE_RELATIVE };
+  const currentContent = fs.readFileSync(workspacePath, 'utf8');
+  if (currentContent === nextContent) {
+    return { status: 'unchanged', file: operationFile, note };
   }
 
   if (!dryRun) {
-    fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-    fs.writeFileSync(absolutePath, JSON.stringify({ locks: {} }, null, 2) + '\n', 'utf8');
-  }
-
-  return { status: 'created', file: LOCK_FILE_RELATIVE };
-}
-
-function lockStateOrError(repoRoot) {
-  const lockPath = lockFilePath(repoRoot);
-  if (!fs.existsSync(lockPath)) {
-    return { ok: false, error: `${LOCK_FILE_RELATIVE} is missing` };
-  }
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
-    if (!parsed || typeof parsed !== 'object' || typeof parsed.locks !== 'object' || parsed.locks === null) {
-      return { ok: false, error: `${LOCK_FILE_RELATIVE} has invalid schema (expected { locks: {} })` };
-    }
-
-    // Normalize older schema entries.
-    for (const [filePath, entry] of Object.entries(parsed.locks)) {
-      if (!entry || typeof entry !== 'object') {
-        parsed.locks[filePath] = { branch: '', claimed_at: '', allow_delete: false };
-        continue;
-      }
-      if (!Object.prototype.hasOwnProperty.call(entry, 'allow_delete')) {
-        entry.allow_delete = false;
-      }
-    }
-
-    return { ok: true, raw: parsed, locks: parsed.locks };
-  } catch (error) {
-    return { ok: false, error: `${LOCK_FILE_RELATIVE} is invalid JSON: ${error.message}` };
+    fs.writeFileSync(workspacePath, nextContent, 'utf8');
   }
+  return { status: dryRun ? 'would-update' : 'updated', file: operationFile, note };
 }
 
-function writeLockState(repoRoot, payload, dryRun) {
-  if (dryRun) return;
-  const lockPath = lockFilePath(repoRoot);
-  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-  fs.writeFileSync(lockPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+function hasGuardexBootstrapFiles(repoRoot) {
+  const required = [
+    'AGENTS.md',
+    '.githooks/pre-commit',
+    '.githooks/pre-push',
+    LOCK_FILE_RELATIVE,
+  ];
+  return required.every((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
 }
 
-function removeLegacyPackageScripts(repoRoot, dryRun) {
-  const packagePath = path.join(repoRoot, 'package.json');
-  if (!fs.existsSync(packagePath)) {
-    return { status: 'skipped', file: 'package.json', note: 'package.json not found' };
+function protectedBaseWriteBlock(options, { requireBootstrap = true } = {}) {
+  if (options.dryRun || options.allowProtectedBaseWrite) {
+    return null;
   }
 
-  let pkg;
-  try {
-    pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
-  } catch (error) {
-    throw new Error(`Unable to parse package.json in target repo: ${error.message}`);
+  const repoRoot = resolveRepoRoot(options.target);
+  if (requireBootstrap && !hasGuardexBootstrapFiles(repoRoot)) {
+    return null;
   }
 
-  const existingScripts = pkg.scripts && typeof pkg.scripts === 'object'
-    ? pkg.scripts
-    : {};
-  pkg.scripts = existingScripts;
-  let changed = false;
-  for (const [key, value] of Object.entries(LEGACY_MANAGED_PACKAGE_SCRIPTS)) {
-    if (existingScripts[key] === value) {
-      delete existingScripts[key];
-      changed = true;
-    }
+  const branch = currentBranchName(repoRoot);
+  if (branch !== 'main') {
+    return null;
   }
 
-  if (!changed) {
-    return { status: 'unchanged', file: 'package.json', note: 'no Guardex-managed agent:* scripts found' };
+  const protectedBranches = readProtectedBranches(repoRoot);
+  if (!protectedBranches.includes(branch)) {
+    return null;
   }
 
-  if (!dryRun) {
-    fs.writeFileSync(packagePath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
-  }
+  return {
+    repoRoot,
+    branch,
+  };
+}
 
-  return { status: dryRun ? 'would-update' : 'updated', file: 'package.json', note: 'removed Guardex-managed agent:* scripts' };
+function assertProtectedMainWriteAllowed(options, commandName) {
+  return sandboxModule.assertProtectedMainWriteAllowed(options, commandName);
 }
 
-function installUserLevelAsset(asset, options = {}) {
-  const dryRun = Boolean(options.dryRun);
-  const force = Boolean(options.force);
-  const destinationPath = path.join(GUARDEX_HOME_DIR, asset.destination);
-  const sourceContent = fs.readFileSync(asset.source, 'utf8');
-  const destinationExists = fs.existsSync(destinationPath);
-
-  if (destinationExists) {
-    const existingContent = fs.readFileSync(destinationPath, 'utf8');
-    if (existingContent === sourceContent) {
-      return { status: 'unchanged', file: asset.destination };
-    }
-    if (!force) {
-      return { status: 'skipped-conflict', file: asset.destination };
+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);
     }
   }
 
-  if (!dryRun) {
-    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
-    fs.writeFileSync(destinationPath, sourceContent, 'utf8');
-  }
-  return { status: destinationExists ? (dryRun ? 'would-update' : 'updated') : 'created', file: asset.destination };
+  const fixPayload = runFixInternal({
+    target: installPayload.repoRoot,
+    dryRun: options.dryRun,
+    force: options.force,
+    forceManagedPaths: options.forceManagedPaths,
+    dropStaleLocks: true,
+    skipAgents: options.skipAgents,
+    skipPackageJson: options.skipPackageJson,
+    skipGitignore: options.skipGitignore,
+    allowProtectedBaseWrite: options.allowProtectedBaseWrite,
+  });
+
+  return {
+    installPayload,
+    fixPayload,
+    parentWorkspace,
+  };
 }
 
-function removeLegacyManagedRepoFile(repoRoot, relativePath, options = {}) {
-  const dryRun = Boolean(options.dryRun);
-  const force = Boolean(options.force);
-  const absolutePath = path.join(repoRoot, relativePath);
-  if (!fs.existsSync(absolutePath)) {
-    return { status: 'unchanged', file: relativePath, note: 'not present' };
-  }
-  if (!fs.statSync(absolutePath).isFile()) {
-    return { status: 'skipped-conflict', file: relativePath, note: 'not a regular file' };
-  }
+function extractAgentBranchStartMetadata(output) {
+  const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
+  const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
+  return {
+    branch: branchMatch ? branchMatch[1].trim() : '',
+    worktreePath: worktreeMatch ? worktreeMatch[1].trim() : '',
+  };
+}
 
-  const skillAsset = USER_LEVEL_SKILL_ASSETS.find((asset) => asset.destination === relativePath);
-  if (skillAsset) {
-    const userLevelPath = path.join(GUARDEX_HOME_DIR, skillAsset.destination);
-    if (!fs.existsSync(userLevelPath)) {
-      return { status: 'skipped', file: relativePath, note: 'user-level replacement not installed' };
-    }
+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(`sandbox target must stay inside repo root: ${resolvedTarget}`);
   }
-
-  const templateRelative = skillAsset
-    ? skillAsset.source.slice(TEMPLATE_ROOT.length + 1)
-    : relativePath.replace(/^\./, '');
-  const sourcePath = path.join(TEMPLATE_ROOT, templateRelative);
-  if (!fs.existsSync(sourcePath)) {
-    return { status: 'skipped', file: relativePath, note: 'template source missing' };
+  if (!relativeTarget || relativeTarget === '.') {
+    return worktreePath;
   }
+  return path.join(worktreePath, relativeTarget);
+}
 
-  const sourceContent = fs.readFileSync(sourcePath, 'utf8');
-  const existingContent = fs.readFileSync(absolutePath, 'utf8');
-  if (existingContent !== sourceContent && !force) {
-    return { status: 'skipped-conflict', file: relativePath, note: 'local edits differ from managed template' };
-  }
+function buildSandboxSetupArgs(options, sandboxTarget) {
+  const args = ['setup', '--target', sandboxTarget, '--no-global-install', '--no-recursive'];
+  appendForceArgs(args, options);
+  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;
+}
 
-  if (!dryRun) {
-    fs.rmSync(absolutePath, { force: true });
-  }
-  return { status: dryRun ? 'would-remove' : 'removed', file: relativePath };
+function isSpawnFailure(result) {
+  return Boolean(result?.error) && typeof result?.status !== 'number';
 }
 
-function ensureAgentsSnippet(repoRoot, dryRun, options = {}) {
-  const agentsPath = path.join(repoRoot, 'AGENTS.md');
-  const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, 'AGENTS.multiagent-safety.md'), 'utf8').trimEnd();
-  const managedRegex = new RegExp(
-    `${AGENTS_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${AGENTS_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
-    'm',
-  );
+function protectedBaseSandboxBranchPrefix() {
+  const now = new Date();
+  const stamp = [
+    now.getUTCFullYear(),
+    String(now.getUTCMonth() + 1).padStart(2, '0'),
+    String(now.getUTCDate()).padStart(2, '0'),
+  ].join('') + '-' + [
+    String(now.getUTCHours()).padStart(2, '0'),
+    String(now.getUTCMinutes()).padStart(2, '0'),
+    String(now.getUTCSeconds()).padStart(2, '0'),
+  ].join('');
+  return `agent/gx/${stamp}`;
+}
 
-  if (!fs.existsSync(agentsPath)) {
-    if (!dryRun) {
-      fs.writeFileSync(agentsPath, `# AGENTS\n\n${snippet}\n`, 'utf8');
-    }
-    return { status: 'created', file: 'AGENTS.md' };
-  }
+function protectedBaseSandboxWorktreePath(repoRoot, branchName) {
+  return path.join(repoRoot, defaultAgentWorktreeRelativeDir(), branchName.replace(/\//g, '__'));
+}
 
-  const existing = fs.readFileSync(agentsPath, 'utf8');
-  if (managedRegex.test(existing)) {
-    const next = existing.replace(managedRegex, snippet);
-    if (next === existing) {
-      return { status: 'unchanged', file: 'AGENTS.md' };
-    }
-    if (!dryRun) {
-      fs.writeFileSync(agentsPath, next, 'utf8');
-    }
-    return { status: 'updated', file: 'AGENTS.md', note: 'refreshed gitguardex-managed block' };
+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}`;
   }
-
-  if (existing.includes(AGENTS_MARKER_START)) {
-    return { status: 'unchanged', file: 'AGENTS.md', note: 'existing marker found without managed end marker' };
+  if (gitRefExists(repoRoot, `refs/heads/${baseBranch}`)) {
+    return baseBranch;
   }
-
-  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
-  if (!dryRun) {
-    fs.writeFileSync(agentsPath, `${existing}${separator}${snippet}\n`, 'utf8');
+  if (currentBranchName(repoRoot) === baseBranch) {
+    return null;
   }
-
-  return { status: 'updated', file: 'AGENTS.md' };
+  throw new Error(`Unable to find base ref for sandbox bootstrap: ${baseBranch}`);
 }
 
-function ensureManagedGitignore(repoRoot, dryRun) {
-  const gitignorePath = path.join(repoRoot, '.gitignore');
-  const managedBlock = [
-    GITIGNORE_MARKER_START,
-    ...MANAGED_GITIGNORE_PATHS,
-    GITIGNORE_MARKER_END,
-  ].join('\n');
-  const managedRegex = new RegExp(
-    `${GITIGNORE_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${GITIGNORE_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
-    'm',
-  );
-
-  if (!fs.existsSync(gitignorePath)) {
-    if (!dryRun) {
-      fs.writeFileSync(gitignorePath, `${managedBlock}\n`, 'utf8');
-    }
-    return { status: 'created', file: '.gitignore', note: 'added gitguardex-managed entries' };
-  }
-
-  const existing = fs.readFileSync(gitignorePath, 'utf8');
-  if (managedRegex.test(existing)) {
-    const next = existing.replace(managedRegex, managedBlock);
-    if (next === existing) {
-      return { status: 'unchanged', file: '.gitignore' };
-    }
-    if (!dryRun) {
-      fs.writeFileSync(gitignorePath, next, 'utf8');
-    }
-    return { status: 'updated', file: '.gitignore', note: 'refreshed gitguardex-managed entries' };
-  }
-
-  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
-  if (!dryRun) {
-    fs.writeFileSync(gitignorePath, `${existing}${separator}${managedBlock}\n`, 'utf8');
-  }
-  return { status: 'updated', file: '.gitignore', note: 'appended gitguardex-managed entries' };
-}
-
-function stripJsonComments(source) {
-  let result = '';
-  let inString = false;
-  let escapeNext = false;
-  let inLineComment = false;
-  let inBlockComment = false;
-
-  for (let index = 0; index < source.length; index += 1) {
-    const current = source[index];
-    const next = source[index + 1];
-
-    if (inLineComment) {
-      if (current === '\n' || current === '\r') {
-        inLineComment = false;
-        result += current;
-      }
-      continue;
-    }
-
-    if (inBlockComment) {
-      if (current === '*' && next === '/') {
-        inBlockComment = false;
-        index += 1;
-        continue;
-      }
-      if (current === '\n' || current === '\r') {
-        result += current;
-      }
-      continue;
-    }
-
-    if (inString) {
-      result += current;
-      if (escapeNext) {
-        escapeNext = false;
-      } else if (current === '\\') {
-        escapeNext = true;
-      } else if (current === '"') {
-        inString = false;
-      }
-      continue;
-    }
-
-    if (current === '"') {
-      inString = true;
-      result += current;
-      continue;
-    }
-
-    if (current === '/' && next === '/') {
-      inLineComment = true;
-      index += 1;
-      continue;
-    }
-
-    if (current === '/' && next === '*') {
-      inBlockComment = true;
-      index += 1;
-      continue;
-    }
-
-    result += current;
-  }
-
-  return result;
-}
-
-function stripJsonTrailingCommas(source) {
-  let result = '';
-  let inString = false;
-  let escapeNext = false;
-
-  for (let index = 0; index < source.length; index += 1) {
-    const current = source[index];
-
-    if (inString) {
-      result += current;
-      if (escapeNext) {
-        escapeNext = false;
-      } else if (current === '\\') {
-        escapeNext = true;
-      } else if (current === '"') {
-        inString = false;
-      }
-      continue;
-    }
-
-    if (current === '"') {
-      inString = true;
-      result += current;
-      continue;
-    }
-
-    if (current === ',') {
-      let lookahead = index + 1;
-      while (lookahead < source.length && /\s/.test(source[lookahead])) {
-        lookahead += 1;
-      }
-      if (source[lookahead] === '}' || source[lookahead] === ']') {
-        continue;
-      }
-    }
-
-    result += current;
-  }
-
-  return result;
-}
-
-function parseJsonObjectLikeFile(source, relativePath) {
-  let parsed;
-  try {
-    parsed = JSON.parse(stripJsonTrailingCommas(stripJsonComments(source)));
-  } catch (error) {
-    throw new Error(`Unable to parse ${relativePath} as JSON or JSONC: ${error.message}`);
-  }
-
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error(`${relativePath} must contain a top-level object.`);
-  }
-
-  return parsed;
-}
-
-function uniqueStringList(values) {
-  const seen = new Set();
-  const result = [];
-
-  for (const value of values) {
-    if (typeof value !== 'string' || seen.has(value)) {
-      continue;
-    }
-    seen.add(value);
-    result.push(value);
-  }
-
-  return result;
-}
-
-function buildRepoVscodeSettings(existingSettings = {}) {
-  const nextSettings = { ...existingSettings };
-  const existingIgnoredFolders = Array.isArray(existingSettings[REPO_SCAN_IGNORED_FOLDERS_SETTING])
-    ? existingSettings[REPO_SCAN_IGNORED_FOLDERS_SETTING]
-    : [];
-
-  nextSettings[REPO_SCAN_IGNORED_FOLDERS_SETTING] = uniqueStringList([
-    ...existingIgnoredFolders,
-    ...MANAGED_REPO_SCAN_IGNORED_FOLDERS,
-  ]);
-
-  return nextSettings;
-}
-
-function ensureRepoVscodeSettings(repoRoot, dryRun) {
-  const settingsPath = path.join(repoRoot, SHARED_VSCODE_SETTINGS_RELATIVE);
-  const destinationExists = fs.existsSync(settingsPath);
-  const existingContent = destinationExists ? fs.readFileSync(settingsPath, 'utf8') : '';
-  const existingSettings = destinationExists
-    ? parseJsonObjectLikeFile(existingContent, SHARED_VSCODE_SETTINGS_RELATIVE)
-    : {};
-  const nextContent = `${JSON.stringify(buildRepoVscodeSettings(existingSettings), null, 2)}\n`;
-
-  if (destinationExists && existingContent === nextContent) {
-    return { status: 'unchanged', file: SHARED_VSCODE_SETTINGS_RELATIVE };
-  }
-
-  ensureParentDir(repoRoot, settingsPath, dryRun);
-  if (!dryRun) {
-    fs.writeFileSync(settingsPath, nextContent, 'utf8');
-  }
-
-  return {
-    status: destinationExists ? 'updated' : 'created',
-    file: SHARED_VSCODE_SETTINGS_RELATIVE,
-    note: 'shared VS Code repo scan ignores for Guardex worktrees',
-  };
-}
-
-function configureHooks(repoRoot, dryRun) {
-  if (dryRun) {
-    return { status: 'would-set', key: 'core.hooksPath', value: '.githooks' };
-  }
-
-  const result = run('git', ['-C', repoRoot, 'config', 'core.hooksPath', '.githooks']);
-  if (result.status !== 0) {
-    throw new Error(`Failed to set git hooksPath: ${(result.stderr || '').trim()}`);
-  }
-
-  return { status: 'set', key: 'core.hooksPath', value: '.githooks' };
-}
-
-function appendForceArgs(args, options) {
-  if (!options.force) {
-    return;
-  }
-  args.push('--force');
-  for (const managedPath of options.forceManagedPaths || []) {
-    args.push(managedPath);
-  }
-}
-
-function shouldForceManagedPath(options, relativePath) {
-  if (!options.force) {
-    return false;
-  }
-  const targetedPaths = Array.isArray(options.forceManagedPaths) ? options.forceManagedPaths : [];
-  if (targetedPaths.length === 0) {
-    return true;
-  }
-  const normalized = normalizeManagedForcePath(relativePath);
-  return normalized !== null && targetedPaths.includes(normalized);
-}
-
-function normalizeWorkspacePath(relativePath) {
-  return String(relativePath || '.').replace(/\\/g, '/');
-}
-
-function buildParentWorkspaceView(repoRoot) {
-  const parentDir = path.dirname(repoRoot);
-  const workspaceFileName = `${path.basename(repoRoot)}-branches.code-workspace`;
-  const workspacePath = path.join(parentDir, workspaceFileName);
-  const repoRelativePath = normalizeWorkspacePath(path.relative(parentDir, repoRoot) || '.');
-
-  return {
-    workspacePath,
-    payload: {
-      folders: [
-        { path: repoRelativePath },
-        ...AGENT_WORKTREE_RELATIVE_DIRS.map((relativeDir) => ({
-          path: normalizeWorkspacePath(path.join(repoRelativePath === '.' ? '' : repoRelativePath, relativeDir)),
-        })),
-      ],
-      settings: {
-        'scm.alwaysShowRepositories': true,
-      },
-    },
-  };
-}
-
-function ensureParentWorkspaceView(repoRoot, dryRun) {
-  const { workspacePath, payload } = buildParentWorkspaceView(repoRoot);
-  const operationFile = path.relative(repoRoot, workspacePath) || path.basename(workspacePath);
-  const nextContent = `${JSON.stringify(payload, null, 2)}\n`;
-  const note = 'parent VS Code workspace view';
-
-  if (!fs.existsSync(workspacePath)) {
-    if (!dryRun) {
-      fs.writeFileSync(workspacePath, nextContent, 'utf8');
-    }
-    return { status: dryRun ? 'would-create' : 'created', file: operationFile, note };
-  }
-
-  const currentContent = fs.readFileSync(workspacePath, 'utf8');
-  if (currentContent === nextContent) {
-    return { status: 'unchanged', file: operationFile, note };
-  }
-
-  if (!dryRun) {
-    fs.writeFileSync(workspacePath, nextContent, 'utf8');
-  }
-  return { status: dryRun ? 'would-update' : 'updated', file: operationFile, note };
-}
-
-function hasGuardexBootstrapFiles(repoRoot) {
-  const required = [
-    'AGENTS.md',
-    '.githooks/pre-commit',
-    '.githooks/pre-push',
-    LOCK_FILE_RELATIVE,
-  ];
-  return required.every((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
-}
-
-function protectedBaseWriteBlock(options, { requireBootstrap = true } = {}) {
-  if (options.dryRun || options.allowProtectedBaseWrite) {
-    return null;
-  }
-
-  const repoRoot = resolveRepoRoot(options.target);
-  if (requireBootstrap && !hasGuardexBootstrapFiles(repoRoot)) {
-    return null;
-  }
-
-  const branch = currentBranchName(repoRoot);
-  if (branch !== 'main') {
-    return null;
-  }
-
-  const protectedBranches = readProtectedBranches(repoRoot);
-  if (!protectedBranches.includes(branch)) {
-    return null;
-  }
-
-  return {
-    repoRoot,
-    branch,
-  };
-}
-
-function assertProtectedMainWriteAllowed(options, commandName) {
-  return getSandboxApi().assertProtectedMainWriteAllowed(options, commandName);
-}
-
-function runSetupBootstrapInternal(options) {
-  return getSandboxApi().runSetupBootstrapInternal(options);
-}
-
-function extractAgentBranchStartMetadata(output) {
-  const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
-  const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
-  return {
-    branch: branchMatch ? branchMatch[1].trim() : '',
-    worktreePath: worktreeMatch ? worktreeMatch[1].trim() : '',
-  };
-}
-
-function resolveSandboxTarget(repoRoot, worktreePath, targetPath) {
-  const resolvedTarget = path.resolve(targetPath);
-  const relativeTarget = path.relative(repoRoot, resolvedTarget);
-  if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
-    throw new Error(`sandbox target must stay inside repo root: ${resolvedTarget}`);
-  }
-  if (!relativeTarget || relativeTarget === '.') {
-    return worktreePath;
-  }
-  return path.join(worktreePath, relativeTarget);
-}
-
-function buildSandboxSetupArgs(options, sandboxTarget) {
-  const args = ['setup', '--target', sandboxTarget, '--no-global-install', '--no-recursive'];
-  appendForceArgs(args, options);
-  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');
-  appendForceArgs(args, options);
-  if (options.skipAgents) args.push('--skip-agents');
-  if (options.skipPackageJson) args.push('--skip-package-json');
-  if (options.skipGitignore) args.push('--no-gitignore');
-  if (!options.dropStaleLocks) args.push('--keep-stale-locks');
-  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;
-}
-
-function isSpawnFailure(result) {
-  return Boolean(result?.error) && typeof result?.status !== 'number';
-}
-
-function ensureRepoBranch(repoRoot, branch) {
-  const current = currentBranchName(repoRoot);
-  if (current === branch) {
-    return { ok: true, changed: false };
-  }
-
-  const checkoutResult = run('git', ['-C', repoRoot, 'checkout', branch], { timeout: 20_000 });
-  if (isSpawnFailure(checkoutResult)) {
-    return {
-      ok: false,
-      changed: false,
-      stdout: checkoutResult.stdout || '',
-      stderr: checkoutResult.stderr || '',
-    };
-  }
-  if (checkoutResult.status !== 0) {
-    return {
-      ok: false,
-      changed: false,
-      stdout: checkoutResult.stdout || '',
-      stderr: checkoutResult.stderr || '',
-    };
-  }
-
-  return { ok: true, changed: true };
-}
-
-function protectedBaseSandboxBranchPrefix() {
-  const now = new Date();
-  const stamp = [
-    now.getUTCFullYear(),
-    String(now.getUTCMonth() + 1).padStart(2, '0'),
-    String(now.getUTCDate()).padStart(2, '0'),
-  ].join('') + '-' + [
-    String(now.getUTCHours()).padStart(2, '0'),
-    String(now.getUTCMinutes()).padStart(2, '0'),
-    String(now.getUTCSeconds()).padStart(2, '0'),
-  ].join('');
-  return `agent/gx/${stamp}`;
-}
-
-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 resolveProtectedBaseSandboxStartRef(repoRoot, baseBranch) {
-  run('git', ['-C', repoRoot, 'fetch', 'origin', baseBranch, '--quiet'], { timeout: 20_000 });
-  if (gitRefExists(repoRoot, `refs/remotes/origin/${baseBranch}`)) {
-    return `origin/${baseBranch}`;
-  }
-  if (gitRefExists(repoRoot, `refs/heads/${baseBranch}`)) {
-    return baseBranch;
-  }
-  if (currentBranchName(repoRoot) === baseBranch) {
-    return null;
-  }
-  throw new Error(`Unable to find base ref for sandbox bootstrap: ${baseBranch}`);
-}
-
-function startProtectedBaseSandboxFallback(blocked, sandboxSuffix) {
-  const branchPrefix = protectedBaseSandboxBranchPrefix();
-  let selectedBranch = '';
-  let selectedWorktreePath = '';
-
-  for (let attempt = 0; attempt < 30; attempt += 1) {
-    const suffix = attempt === 0 ? sandboxSuffix : `${attempt + 1}-${sandboxSuffix}`;
-    const candidateBranch = `${branchPrefix}-${suffix}`;
-    const candidateWorktreePath = protectedBaseSandboxWorktreePath(blocked.repoRoot, candidateBranch);
-    if (gitRefExists(blocked.repoRoot, `refs/heads/${candidateBranch}`)) {
-      continue;
-    }
-    if (fs.existsSync(candidateWorktreePath)) {
-      continue;
-    }
-    selectedBranch = candidateBranch;
-    selectedWorktreePath = candidateWorktreePath;
-    break;
-  }
-
-  if (!selectedBranch || !selectedWorktreePath) {
-    throw new Error('Unable to allocate unique sandbox branch/worktree');
-  }
-
-  fs.mkdirSync(path.dirname(selectedWorktreePath), { recursive: true });
-  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 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 {
-    metadata: {
-      branch: selectedBranch,
-      worktreePath: selectedWorktreePath,
-    },
-    stdout:
-      `[agent-branch-start] Created branch: ${selectedBranch}\n` +
-      `[agent-branch-start] Worktree: ${selectedWorktreePath}\n`,
-    stderr: addResult.stderr || '',
-  };
-}
-
-function startProtectedBaseSandbox(blocked, { taskName, sandboxSuffix }) {
-  if (sandboxSuffix === 'gx-doctor') {
-    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
-  }
-
-  const startResult = runPackageAsset('branchStart', [
-    '--task',
-    taskName,
-    '--agent',
-    SHORT_TOOL_NAME,
-    '--base',
-    blocked.branch,
-  ], { cwd: blocked.repoRoot });
-  if (isSpawnFailure(startResult)) {
-    throw startResult.error;
-  }
-  if (startResult.status !== 0) {
-    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
-  }
-
-  const metadata = extractAgentBranchStartMetadata(startResult.stdout);
-  const currentBranch = currentBranchName(blocked.repoRoot);
-  const worktreePath = metadata.worktreePath ? path.resolve(metadata.worktreePath) : '';
-  const repoRootPath = path.resolve(blocked.repoRoot);
-  const hasSafeWorktree = Boolean(worktreePath) && worktreePath !== repoRootPath;
-  const branchChanged = Boolean(currentBranch) && currentBranch !== blocked.branch;
-
-  if (!hasSafeWorktree || branchChanged) {
-    const restoreResult = ensureRepoBranch(blocked.repoRoot, blocked.branch);
-    if (!restoreResult.ok) {
-      const detail = [restoreResult.stderr, restoreResult.stdout].filter(Boolean).join('\n').trim();
-      throw new Error(
-        `sandbox startup switched protected base checkout and could not restore '${blocked.branch}'.` +
-        (detail ? `\n${detail}` : ''),
-      );
-    }
-    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
-  }
-
-  return {
-    metadata,
-    stdout: startResult.stdout || '',
-    stderr: startResult.stderr || '',
-  };
-}
-
-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')
-    .map((line) => line.trim())
-    .filter((line) => line && line !== LOCK_FILE_RELATIVE);
-}
-
-function collectDoctorChangedPaths(worktreePath) {
-  const changed = 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)) {
-      changed.add(filePath);
-    }
-  }
-  return Array.from(changed);
-}
-
-function collectDoctorDeletedPaths(worktreePath) {
-  const deleted = new Set();
-  const commands = [
-    ['diff', '--name-only', '--diff-filter=D'],
-    ['diff', '--cached', '--name-only', '--diff-filter=D'],
-  ];
-  for (const gitArgs of commands) {
-    const result = run('git', ['-C', worktreePath, ...gitArgs], { timeout: 20_000 });
-    for (const filePath of parseGitPathList(result.stdout)) {
-      deleted.add(filePath);
-    }
-  }
-  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 REQUIRED_MANAGED_REPO_FILES
-    .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) {
-  if (!metadata.branch) {
-    return {
-      status: 'skipped',
-      note: 'missing sandbox branch metadata',
-      changedCount: 0,
-      deletedCount: 0,
-    };
-  }
-
-  const changedPaths = Array.from(new Set([
-    ...collectDoctorChangedPaths(metadata.worktreePath),
-    ...collectDoctorForceAddPaths(metadata.worktreePath),
-  ]));
-  const deletedPaths = collectDoctorDeletedPaths(metadata.worktreePath);
-  if (changedPaths.length > 0) {
-    runPackageAsset('lockTool', ['claim', '--branch', metadata.branch, ...changedPaths], {
-      cwd: metadata.worktreePath,
-      timeout: 30_000,
-    });
-  }
-  if (deletedPaths.length > 0) {
-    runPackageAsset('lockTool', ['allow-delete', '--branch', metadata.branch, ...deletedPaths], {
-      cwd: metadata.worktreePath,
-      timeout: 30_000,
-    });
-  }
-
-  return {
-    status: 'claimed',
-    note: 'claimed locks for doctor auto-commit',
-    changedCount: changedPaths.length,
-    deletedCount: deletedPaths.length,
-  };
-}
-
-function autoCommitDoctorSandboxChanges(metadata) {
-  if (!metadata.worktreePath || !metadata.branch) {
-    return {
-      status: 'skipped',
-      note: 'missing sandbox branch metadata',
-    };
-  }
-
-  claimDoctorChangedLocks(metadata);
-  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}`],
-    { timeout: 20_000 },
-  );
-  const stagedFiles = parseGitPathList(staged.stdout);
-  if (stagedFiles.length === 0) {
-    return {
-      status: 'no-changes',
-      note: 'no committable doctor changes found in sandbox',
-    };
-  }
-
-  const commitResult = run(
-    'git',
-    ['-C', metadata.worktreePath, 'commit', '-m', 'Auto-finish: gx doctor repairs'],
-    { timeout: 30_000 },
-  );
-  if (commitResult.status !== 0) {
-    return {
-      status: 'failed',
-      note: 'doctor sandbox auto-commit failed',
-      stdout: commitResult.stdout || '',
-      stderr: commitResult.stderr || '',
-    };
-  }
-
-  return {
-    status: 'committed',
-    note: 'doctor sandbox repairs committed',
-    commitMessage: 'Auto-finish: gx doctor repairs',
-    stagedFiles,
-  };
-}
-
-function hasOriginRemote(repoRoot) {
-  return run('git', ['-C', repoRoot, 'remote', 'get-url', 'origin']).status === 0;
-}
-
-function originRemoteLooksLikeGithub(repoRoot) {
-  const originUrl = readGitConfig(repoRoot, 'remote.origin.url');
-  if (!originUrl) {
-    return false;
-  }
-  return /github\.com[:/]/i.test(originUrl);
-}
-
-function isCommandAvailable(commandName) {
-  return run('which', [commandName]).status === 0;
-}
-
-function extractAgentBranchFinishPrUrl(output) {
-  const match = String(output || '').match(/\[agent-branch-finish\] PR:\s*(\S+)/);
-  return match ? match[1] : '';
-}
-
-function doctorFinishFlowIsPending(output) {
-  return (
-    /\[agent-branch-finish\] PR merge not completed yet; leaving PR open\./.test(output) ||
-    /\[agent-branch-finish\] Merge pending review\/check policy\. Branch cleanup skipped for now\./.test(output) ||
-    /\[agent-branch-finish\] PR auto-merge enabled; waiting for required checks\/reviews\./.test(output)
-  );
-}
-
-function finishDoctorSandboxBranch(blocked, metadata, options = {}) {
-  if (!hasOriginRemote(blocked.repoRoot)) {
-    return {
-      status: 'skipped',
-      note: 'origin remote missing; skipped auto-finish',
-    };
-  }
-  const explicitGhBin = Boolean(String(process.env.GUARDEX_GH_BIN || '').trim());
-  if (!explicitGhBin && !originRemoteLooksLikeGithub(blocked.repoRoot)) {
-    return {
-      status: 'skipped',
-      note: 'origin remote is not GitHub; skipped auto-finish PR flow',
-    };
-  }
-
-  const ghBin = process.env.GUARDEX_GH_BIN || 'gh';
-  if (!isCommandAvailable(ghBin)) {
-    return {
-      status: 'skipped',
-      note: `'${ghBin}' not available; skipped auto-finish PR flow`,
-    };
-  }
-  const ghAuthStatus = run(ghBin, ['auth', 'status'], { timeout: 20_000 });
-  if (ghAuthStatus.status !== 0) {
-    return {
-      status: 'skipped',
-      note: `'${ghBin}' auth unavailable; skipped auto-finish PR flow`,
-      stderr: ghAuthStatus.stderr || '',
-    };
-  }
-
-  const rawWaitTimeoutSeconds = Number.parseInt(process.env.GUARDEX_FINISH_WAIT_TIMEOUT_SECONDS || '1800', 10);
-  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 = runPackageAsset(
-    'branchFinish',
-    ['--branch', metadata.branch, '--base', blocked.branch, '--via-pr', waitForMergeArg, '--cleanup'],
-    { cwd: metadata.worktreePath, timeout: finishTimeoutMs },
-  );
-  if (isSpawnFailure(finishResult)) {
-    return {
-      status: 'failed',
-      note: 'doctor sandbox finish flow errored',
-      stdout: finishResult.stdout || '',
-      stderr: finishResult.stderr || '',
-    };
-  }
-  if (finishResult.status !== 0) {
-    return {
-      status: 'failed',
-      note: 'doctor sandbox finish flow failed',
-      stdout: finishResult.stdout || '',
-      stderr: finishResult.stderr || '',
-    };
-  }
-
-  const combinedOutput = `${finishResult.stdout || ''}\n${finishResult.stderr || ''}`;
-  if (doctorFinishFlowIsPending(combinedOutput)) {
-    return {
-      status: 'pending',
-      note: 'PR created and waiting for merge policy/checks',
-      prUrl: extractAgentBranchFinishPrUrl(combinedOutput),
-      stdout: finishResult.stdout || '',
-      stderr: finishResult.stderr || '',
-    };
-  }
-
-  return {
-    status: 'completed',
-    note: 'doctor sandbox finish flow completed',
-    stdout: finishResult.stdout || '',
-    stderr: finishResult.stderr || '',
-  };
-}
-
-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()),
-    ...REQUIRED_MANAGED_REPO_FILES,
-    '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,
-  };
-}
-
-/**
- * @param {string} [note]
- * @returns {OperationResult}
- */
-function createDoctorSkippedOperation(note = 'sandbox doctor did not complete successfully') {
-  return {
-    status: 'skipped',
-    note,
-  };
-}
-
-/**
- * @param {string} [note]
- * @returns {AutoFinishSummary}
- */
-function createSkippedDoctorAutoFinishSummary(note = 'sandbox doctor did not complete successfully') {
-  return {
-    enabled: false,
-    attempted: 0,
-    completed: 0,
-    skipped: 0,
-    failed: 0,
-    details: [`Skipped auto-finish sweep (${note}).`],
-  };
-}
-
-/**
- * Default the lifecycle to skipped states until the nested doctor run succeeds.
- *
- * @param {string} [note]
- * @returns {DoctorSandboxExecution}
- */
-function createDoctorSandboxExecutionState(note = 'sandbox doctor did not complete successfully') {
-  return {
-    autoCommit: createDoctorSkippedOperation(note),
-    finish: createDoctorSkippedOperation(note),
-    protectedBaseRepairSync: createDoctorSkippedOperation(note),
-    lockSync: createDoctorSkippedOperation(note),
-    omxScaffoldSync: createDoctorSkippedOperation(note),
-    autoFinish: createSkippedDoctorAutoFinishSummary(note),
-    sandboxLockContent: null,
-  };
-}
-
-/**
- * @param {string} repoRoot
- * @param {boolean} dryRun
- * @returns {OperationResult}
- */
-function summarizeDoctorOmxScaffoldSync(repoRoot, dryRun) {
-  const omxScaffoldOps = ensureOmxScaffold(repoRoot, dryRun);
-  const changedOmxPaths = omxScaffoldOps.filter((operation) => operation.status !== 'unchanged');
-  if (changedOmxPaths.length === 0) {
-    return {
-      status: 'unchanged',
-      note: '.omx scaffold already in sync',
-      operations: omxScaffoldOps,
-    };
-  }
-  return {
-    status: dryRun ? 'would-sync' : 'synced',
-    note: `${dryRun ? 'would sync' : 'synced'} ${changedOmxPaths.length} .omx path(s)`,
-    operations: omxScaffoldOps,
-  };
-}
-
-/**
- * @param {string} repoRoot
- * @param {SandboxMetadata} metadata
- * @returns {DoctorLockSyncState}
- */
-function syncDoctorLockRegistryBeforeMerge(repoRoot, metadata) {
-  const sandboxLockPath = path.join(metadata.worktreePath, LOCK_FILE_RELATIVE);
-  const baseLockPath = path.join(repoRoot, LOCK_FILE_RELATIVE);
-  if (!fs.existsSync(baseLockPath)) {
-    return {
-      result: {
-        status: 'skipped',
-        note: `${LOCK_FILE_RELATIVE} missing in protected base workspace`,
-      },
-      sandboxLockContent: null,
-    };
-  }
-  if (!fs.existsSync(sandboxLockPath)) {
-    return {
-      result: {
-        status: 'skipped',
-        note: `${LOCK_FILE_RELATIVE} missing in sandbox worktree`,
-      },
-      sandboxLockContent: null,
-    };
-  }
-
-  const sourceContent = stripDoctorSandboxLocks(
-    fs.readFileSync(sandboxLockPath, 'utf8'),
-    metadata.branch,
-  );
-  const destinationContent = fs.readFileSync(baseLockPath, 'utf8');
-  if (sourceContent === destinationContent) {
-    return {
-      result: {
-        status: 'unchanged',
-        note: `${LOCK_FILE_RELATIVE} already in sync`,
-      },
-      sandboxLockContent: sourceContent,
-    };
-  }
-
-  fs.mkdirSync(path.dirname(baseLockPath), { recursive: true });
-  fs.writeFileSync(baseLockPath, sourceContent, 'utf8');
-  return {
-    result: {
-      status: 'synced',
-      note: `${LOCK_FILE_RELATIVE} synced from sandbox`,
-    },
-    sandboxLockContent: sourceContent,
-  };
-}
-
-/**
- * @param {string} repoRoot
- * @param {string | null} sandboxLockContent
- * @returns {OperationResult}
- */
-function syncDoctorLockRegistryAfterMerge(repoRoot, sandboxLockContent) {
-  if (sandboxLockContent === null) {
-    return {
-      status: 'skipped',
-      note: `${LOCK_FILE_RELATIVE} missing in sandbox worktree`,
-    };
-  }
-
-  const baseLockPath = path.join(repoRoot, LOCK_FILE_RELATIVE);
-  if (!fs.existsSync(baseLockPath)) {
-    fs.mkdirSync(path.dirname(baseLockPath), { recursive: true });
-    fs.writeFileSync(baseLockPath, sandboxLockContent, 'utf8');
-    return {
-      status: 'synced',
-      note: `${LOCK_FILE_RELATIVE} recreated from sandbox`,
-    };
-  }
-
-  const destinationContent = fs.readFileSync(baseLockPath, 'utf8');
-  if (sandboxLockContent === destinationContent) {
-    return {
-      status: 'unchanged',
-      note: `${LOCK_FILE_RELATIVE} already in sync`,
-    };
-  }
-
-  fs.mkdirSync(path.dirname(baseLockPath), { recursive: true });
-  fs.writeFileSync(baseLockPath, sandboxLockContent, 'utf8');
-  return {
-    status: 'synced',
-    note: `${LOCK_FILE_RELATIVE} synced from sandbox`,
-  };
-}
-
-/**
- * @param {object} options
- * @param {{ repoRoot: string, branch: string }} blocked
- * @param {SandboxMetadata} metadata
- * @returns {DoctorSandboxExecution}
- */
-function executeDoctorSandboxLifecycle(options, blocked, metadata) {
-  const execution = createDoctorSandboxExecutionState();
-  const dryRun = Boolean(options.dryRun);
-
-  execution.omxScaffoldSync = summarizeDoctorOmxScaffoldSync(blocked.repoRoot, dryRun);
-
-  if (!dryRun) {
-    execution.autoCommit = autoCommitDoctorSandboxChanges(metadata);
-    if (execution.autoCommit.status === 'committed') {
-      execution.finish = finishDoctorSandboxBranch(blocked, metadata, options);
-    } else if (execution.autoCommit.status === 'no-changes') {
-      execution.finish = createDoctorSkippedOperation('no doctor changes to auto-finish');
-    } else if (execution.autoCommit.status !== 'failed') {
-      execution.finish = createDoctorSkippedOperation('auto-commit did not run');
-    }
-  } else {
-    execution.autoCommit = createDoctorSkippedOperation('dry-run skips doctor sandbox auto-commit');
-    execution.finish = createDoctorSkippedOperation('dry-run skips doctor sandbox finish flow');
-  }
-
-  const lockSyncState = syncDoctorLockRegistryBeforeMerge(blocked.repoRoot, metadata);
-  execution.lockSync = lockSyncState.result;
-  execution.sandboxLockContent = lockSyncState.sandboxLockContent;
-
-  execution.protectedBaseRepairSync = mergeDoctorSandboxRepairsBackToProtectedBase(
-    options,
-    blocked,
-    metadata,
-    execution.autoCommit,
-    execution.finish,
-  );
-
-  execution.omxScaffoldSync = summarizeDoctorOmxScaffoldSync(blocked.repoRoot, dryRun);
-  execution.lockSync = syncDoctorLockRegistryAfterMerge(
-    blocked.repoRoot,
-    execution.sandboxLockContent,
-  );
-  execution.autoFinish = autoFinishReadyAgentBranches(blocked.repoRoot, {
-    baseBranch: blocked.branch,
-    dryRun: options.dryRun,
-    waitForMerge: options.waitForMerge,
-    excludeBranches: [metadata.branch],
-  });
-
-  return execution;
-}
-
-function emitDoctorSandboxJsonOutput(nestedResult, execution) {
-  if (nestedResult.stdout) {
-    if (nestedResult.status === 0) {
-      try {
-        const parsed = JSON.parse(nestedResult.stdout);
-        process.stdout.write(
-          JSON.stringify(
-            {
-              ...parsed,
-              protectedBaseRepairSync: execution.protectedBaseRepairSync,
-              sandboxOmxScaffoldSync: execution.omxScaffoldSync,
-              sandboxLockSync: execution.lockSync,
-              sandboxAutoCommit: execution.autoCommit,
-              sandboxFinish: execution.finish,
-              autoFinish: execution.autoFinish,
-            },
-            null,
-            2,
-          ) + '\n',
-        );
-      } catch {
-        process.stdout.write(nestedResult.stdout);
-      }
-    } else {
-      process.stdout.write(nestedResult.stdout);
-    }
-  }
-  if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
-}
-
-/**
- * @param {object} options
- * @param {{ branch: string }} blocked
- * @param {SandboxMetadata} metadata
- * @param {SandboxStartResult} startResult
- * @param {any} nestedResult
- * @param {DoctorSandboxExecution} execution
- */
-function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult, nestedResult, execution) {
-  console.log(
-    `[${TOOL_NAME}] doctor detected protected branch '${blocked.branch}'. ` +
-    `Running repairs in sandbox branch '${metadata.branch || 'agent/<auto>'}'.`,
-  );
-  if (startResult.stdout) process.stdout.write(startResult.stdout);
-  if (startResult.stderr) process.stderr.write(startResult.stderr);
-  if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
-  if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
-  if (nestedResult.status !== 0) {
-    return;
-  }
-
-  if (execution.autoCommit.status === 'committed') {
-    console.log(
-      `[${TOOL_NAME}] Auto-committed doctor repairs in sandbox branch '${metadata.branch}'.`,
-    );
-  } else if (execution.autoCommit.status === 'failed') {
-    console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit failed; branch left for manual follow-up.`);
-    if (execution.autoCommit.stdout) process.stdout.write(execution.autoCommit.stdout);
-    if (execution.autoCommit.stderr) process.stderr.write(execution.autoCommit.stderr);
-  } else {
-    console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit skipped: ${execution.autoCommit.note}.`);
-  }
-
-  if (execution.protectedBaseRepairSync.status === 'merged') {
-    console.log(`[${TOOL_NAME}] Fast-forwarded tracked doctor repairs into the protected branch workspace.`);
-  } else if (execution.protectedBaseRepairSync.status === 'unchanged') {
-    console.log(`[${TOOL_NAME}] Protected branch workspace already had the tracked doctor repairs.`);
-  } else if (execution.protectedBaseRepairSync.status === 'would-merge') {
-    console.log(`[${TOOL_NAME}] Dry run: would fast-forward tracked doctor repairs into the protected branch workspace.`);
-  } else if (execution.protectedBaseRepairSync.status === 'failed') {
-    console.log(`[${TOOL_NAME}] Protected branch tracked repair merge failed: ${execution.protectedBaseRepairSync.note}.`);
-    if (execution.protectedBaseRepairSync.stdout) process.stdout.write(execution.protectedBaseRepairSync.stdout);
-    if (execution.protectedBaseRepairSync.stderr) process.stderr.write(execution.protectedBaseRepairSync.stderr);
-  } else {
-    console.log(`[${TOOL_NAME}] Protected branch tracked repair merge skipped: ${execution.protectedBaseRepairSync.note}.`);
-  }
-
-  if (execution.lockSync.status === 'synced') {
-    console.log(
-      `[${TOOL_NAME}] Synced repaired lock registry back to protected branch workspace (${LOCK_FILE_RELATIVE}).`,
-    );
-  } else if (execution.lockSync.status === 'unchanged') {
-    console.log(`[${TOOL_NAME}] Lock registry already synced in protected branch workspace.`);
-  } else {
-    console.log(`[${TOOL_NAME}] Lock registry sync skipped: ${execution.lockSync.note}.`);
-  }
-
-  if (execution.finish.status === 'completed') {
-    console.log(`[${TOOL_NAME}] Auto-finish flow completed for sandbox branch '${metadata.branch}'.`);
-    if (execution.finish.stdout) process.stdout.write(execution.finish.stdout);
-    if (execution.finish.stderr) process.stderr.write(execution.finish.stderr);
-  } else if (execution.finish.status === 'pending') {
-    console.log(
-      `[${TOOL_NAME}] Auto-finish pending for sandbox branch '${metadata.branch}': ${execution.finish.note}.`,
-    );
-    if (execution.finish.prUrl) {
-      console.log(`[${TOOL_NAME}] PR: ${execution.finish.prUrl}`);
-    }
-    if (execution.finish.stdout) process.stdout.write(execution.finish.stdout);
-    if (execution.finish.stderr) process.stderr.write(execution.finish.stderr);
-  } else if (execution.finish.status === 'failed') {
-    console.log(`[${TOOL_NAME}] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
-    if (execution.finish.stdout) process.stdout.write(execution.finish.stdout);
-    if (execution.finish.stderr) process.stderr.write(execution.finish.stderr);
-  } else {
-    console.log(`[${TOOL_NAME}] Auto-finish skipped: ${execution.finish.note}.`);
-  }
-
-  printAutoFinishSummary(execution.autoFinish, {
-    baseBranch: blocked.branch,
-    verbose: options.verboseAutoFinish,
-  });
-  if (execution.omxScaffoldSync.status === 'synced') {
-    console.log(`[${TOOL_NAME}] Synced .omx scaffold back to protected branch workspace.`);
-  } else if (execution.omxScaffoldSync.status === 'unchanged') {
-    console.log(`[${TOOL_NAME}] .omx scaffold already aligned in protected branch workspace.`);
-  } else if (execution.omxScaffoldSync.status === 'would-sync') {
-    console.log(`[${TOOL_NAME}] Dry run: would sync .omx scaffold back to protected branch workspace.`);
-  } else {
-    console.log(`[${TOOL_NAME}] .omx scaffold sync skipped: ${execution.omxScaffoldSync.note}.`);
-  }
-}
-
-function setDoctorSandboxExitCode(nestedResult, execution) {
-  if (typeof nestedResult.status === 'number') {
-    let exitCode = nestedResult.status;
-    if (exitCode === 0 && execution.autoCommit.status === 'failed') {
-      exitCode = 1;
-    }
-    if (
-      exitCode === 0 &&
-      execution.autoCommit.status === 'committed' &&
-      (execution.finish.status === 'failed' || execution.finish.status === 'pending')
-    ) {
-      exitCode = 1;
-    }
-    if (exitCode === 0 && execution.protectedBaseRepairSync.status === 'failed') {
-      exitCode = 1;
-    }
-    process.exitCode = exitCode;
-    return;
-  }
-  process.exitCode = 1;
-}
-
-function runDoctorInSandbox(options, blocked) {
-  /** @type {SandboxStartResult} */
-  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);
-  const nestedResult = run(
-    process.execPath,
-    [__filename, ...buildSandboxDoctorArgs(options, sandboxTarget)],
-    { cwd: metadata.worktreePath },
-  );
-  if (isSpawnFailure(nestedResult)) {
-    throw nestedResult.error;
-  }
-
-  const execution = nestedResult.status === 0
-    ? executeDoctorSandboxLifecycle(options, blocked, metadata)
-    : createDoctorSandboxExecutionState();
-
-  if (options.json) {
-    emitDoctorSandboxJsonOutput(nestedResult, execution);
-  } else {
-    emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult, nestedResult, execution);
-  }
-
-  setDoctorSandboxExitCode(nestedResult, execution);
-}
-
-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 todayDateStamp() {
-  return new Date().toISOString().slice(0, 10);
-}
-
-function inferGithubRepoFromOrigin(repoRoot) {
-  const rawOrigin = readGitConfig(repoRoot, 'remote.origin.url');
-  if (!rawOrigin) return '';
-
-  const httpsMatch = rawOrigin.match(/github\.com[:/](.+?)(?:\.git)?$/i);
-  if (!httpsMatch) return '';
-  const slug = (httpsMatch[1] || '').replace(/^\/+/, '').trim();
-  if (!slug || !slug.includes('/')) return '';
-  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();
-  }
-  const inferred = inferGithubRepoFromOrigin(repoRoot);
-  if (inferred) return inferred;
-  throw new Error(
-    'Unable to infer GitHub repo from origin remote. Pass --repo github.com/<owner>/<repo>.',
-  );
-}
-
-function runScorecardJson(repo) {
-  const result = run(SCORECARD_BIN, ['--repo', repo, '--format', 'json'], { allowFailure: true });
-  if (result.status !== 0) {
-    const details = (result.stderr || result.stdout || '').trim();
-    throw new Error(
-      `Failed to run scorecard CLI ('${SCORECARD_BIN} --repo ${repo} --format json').${details ? `\n${details}` : ''}`,
-    );
-  }
-
-  try {
-    return JSON.parse(result.stdout || '{}');
-  } catch (error) {
-    throw new Error(`Unable to parse scorecard JSON output: ${error.message}`);
-  }
-}
-
-function readScorecardJsonFile(filePath) {
-  const absolute = path.resolve(filePath);
-  if (!fs.existsSync(absolute)) {
-    throw new Error(`scorecard JSON file not found: ${absolute}`);
-  }
-  try {
-    return JSON.parse(fs.readFileSync(absolute, 'utf8'));
-  } catch (error) {
-    throw new Error(`Unable to parse scorecard JSON file: ${error.message}`);
-  }
-}
-
-function normalizeScorecardChecks(payload) {
-  const rawChecks = Array.isArray(payload?.checks) ? payload.checks : [];
-  return rawChecks.map((check) => {
-    const name = String(check?.name || 'Unknown');
-    const rawScore = Number(check?.score);
-    const score = Number.isFinite(rawScore) ? rawScore : 0;
-    return {
-      name,
-      score,
-      risk: SCORECARD_RISK_BY_CHECK[name] || 'Unknown',
-    };
-  });
-}
-
-function renderScorecardBaselineMarkdown({ repo, score, checks, capturedAt, scorecardVersion, reportDate }) {
-  const rows = checks
-    .map((item) => `| ${item.name} | ${item.score} | ${item.risk} |`)
-    .join('\n');
-
-  return [
-    '# OpenSSF Scorecard Baseline Report',
-    '',
-    `- **Repository:** \`${repo}\``,
-    '- **Source:** generated by `gx report scorecard`',
-    `- **Captured at:** ${capturedAt}`,
-    `- **Scorecard version:** \`${scorecardVersion}\``,
-    `- **Overall score:** **${score} / 10**`,
-    '',
-    '## Check breakdown',
-    '',
-    '| Check | Score | Risk |',
-    '|---|---:|---|',
-    rows || '| (none) | 0 | Unknown |',
-    '',
-    `## Report date`,
-    '',
-    `- ${reportDate}`,
-    '',
-  ].join('\n');
-}
-
-function renderScorecardRemediationPlanMarkdown({ baselineRelativePath, checks }) {
-  const failing = checks.filter((item) => item.score < 10);
-  const failingRows = failing
-    .sort((a, b) => a.score - b.score || a.name.localeCompare(b.name))
-    .map((item) => `| ${item.name} | ${item.score} | ${item.risk} |`)
-    .join('\n');
-
-  return [
-    '# OpenSSF Scorecard Remediation Plan',
-    '',
-    `Based on baseline report: \`${baselineRelativePath}\`.`,
-    '',
-    '## Failing checks',
-    '',
-    '| Check | Score | Risk |',
-    '|---|---:|---|',
-    (failingRows || '| None | 10 | N/A |'),
-    '',
-    '## Priority order',
-    '',
-    '1. Fix **High** risk checks first (especially score 0 items).',
-    '2. Then close **Medium** risk checks with score < 10.',
-    '3. Finally address **Low** risk ecosystem/process checks.',
-    '',
-    '## Verification loop',
-    '',
-    '1. Run scorecard again.',
-    '2. Re-generate baseline + remediation files.',
-    '3. Compare score deltas and track improved checks.',
-    '',
-  ].join('\n');
-}
-
-function parseBranchList(rawValue) {
-  return String(rawValue || '')
-    .split(/[\s,]+/)
-    .map((item) => item.trim())
-    .filter(Boolean);
-}
-
-function uniquePreserveOrder(items) {
-  const seen = new Set();
-  const result = [];
-  for (const item of items) {
-    if (seen.has(item)) continue;
-    seen.add(item);
-    result.push(item);
-  }
-  return result;
-}
-
-function readConfiguredProtectedBranches(repoRoot) {
-  const result = gitRun(repoRoot, ['config', '--get', GIT_PROTECTED_BRANCHES_KEY], { allowFailure: true });
-  if (result.status !== 0) {
-    return null;
-  }
-  const parsed = uniquePreserveOrder(parseBranchList(result.stdout.trim()));
-  if (parsed.length === 0) {
-    return null;
-  }
-  return parsed;
-}
-
-function listLocalUserBranches(repoRoot) {
-  const result = gitRun(repoRoot, ['for-each-ref', '--format=%(refname:short)', 'refs/heads'], { allowFailure: true });
-  const branchNames = result.status === 0
-    ? uniquePreserveOrder(
-      String(result.stdout || '')
-        .split('\n')
-        .map((item) => item.trim())
-        .filter(Boolean),
-    )
-    : [];
-
-  const additionalUserBranches = branchNames.filter(
-    (branchName) =>
-      !branchName.startsWith('agent/') &&
-      !DEFAULT_PROTECTED_BRANCHES.includes(branchName),
-  );
-  if (additionalUserBranches.length > 0) {
-    return additionalUserBranches;
-  }
-
-  const current = gitRun(repoRoot, ['branch', '--show-current'], { allowFailure: true });
-  if (current.status !== 0) {
-    return [];
-  }
-
-  const branchName = String(current.stdout || '').trim();
-  if (
-    !branchName ||
-    branchName.startsWith('agent/') ||
-    DEFAULT_PROTECTED_BRANCHES.includes(branchName)
-  ) {
-    return [];
-  }
-
-  return [branchName];
-}
-
-function listLocalAgentBranches(repoRoot) {
-  const result = gitRun(
-    repoRoot,
-    ['for-each-ref', '--format=%(refname:short)', 'refs/heads/agent/'],
-    { allowFailure: true },
-  );
-  if (result.status !== 0) {
-    return [];
-  }
-  return uniquePreserveOrder(
-    String(result.stdout || '')
-      .split('\n')
-      .map((item) => item.trim())
-      .filter(Boolean),
-  );
-}
-
-function mapWorktreePathsByBranch(repoRoot) {
-  const result = gitRun(repoRoot, ['worktree', 'list', '--porcelain'], { allowFailure: true });
-  const map = new Map();
-  if (result.status !== 0) {
-    return map;
-  }
+function startProtectedBaseSandboxFallback(blocked, sandboxSuffix) {
+  const branchPrefix = protectedBaseSandboxBranchPrefix();
+  let selectedBranch = '';
+  let selectedWorktreePath = '';
 
-  const lines = String(result.stdout || '').split('\n');
-  let currentWorktree = '';
-  for (const line of lines) {
-    if (line.startsWith('worktree ')) {
-      currentWorktree = line.slice('worktree '.length).trim();
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    const suffix = attempt === 0 ? sandboxSuffix : `${attempt + 1}-${sandboxSuffix}`;
+    const candidateBranch = `${branchPrefix}-${suffix}`;
+    const candidateWorktreePath = protectedBaseSandboxWorktreePath(blocked.repoRoot, candidateBranch);
+    if (gitRefExists(blocked.repoRoot, `refs/heads/${candidateBranch}`)) {
       continue;
     }
-    if (line.startsWith('branch refs/heads/')) {
-      const branchName = line.slice('branch refs/heads/'.length).trim();
-      if (currentWorktree && branchName) {
-        map.set(branchName, currentWorktree);
-      }
+    if (fs.existsSync(candidateWorktreePath)) {
+      continue;
     }
-  }
-  return map;
-}
-
-function hasSignificantWorkingTreeChanges(worktreePath) {
-  const result = run('git', [
-    '-C',
-    worktreePath,
-    'status',
-    '--porcelain',
-    '--untracked-files=normal',
-    '--',
-  ]);
-  if (result.status !== 0) {
-    return true;
-  }
-
-  const lines = String(result.stdout || '')
-    .split('\n')
-    .map((line) => line.trimEnd())
-    .filter((line) => line.length > 0);
-
-  for (const line of lines) {
-    const pathPart = (line.length > 3 ? line.slice(3) : '').trim();
-    if (!pathPart) continue;
-    if (pathPart === LOCK_FILE_RELATIVE) continue;
-    if (pathPart.startsWith(`${LOCK_FILE_RELATIVE} -> `)) continue;
-    if (pathPart.endsWith(` -> ${LOCK_FILE_RELATIVE}`)) continue;
-    return true;
-  }
-  return false;
-}
-
-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)
-      : [],
-  );
-
-  const summary = {
-    enabled: true,
-    baseBranch,
-    attempted: 0,
-    completed: 0,
-    skipped: 0,
-    failed: 0,
-    details: [],
-  };
-
-  if (!baseBranch || baseBranch === 'HEAD' || baseBranch.startsWith('agent/')) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (base branch is missing or not a non-agent local branch).');
-    return summary;
-  }
-
-  if (String(process.env.GUARDEX_DOCTOR_SANDBOX || '') === '1') {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep inside doctor sandbox pass.');
-    return summary;
-  }
-
-  if (String(process.env.GUARDEX_SKIP_AUTO_FINISH_READY_BRANCHES || '') === '1') {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (GUARDEX_SKIP_AUTO_FINISH_READY_BRANCHES=1).');
-    return summary;
-  }
-
-  if (dryRun) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep in dry-run mode.');
-    return summary;
+    selectedBranch = candidateBranch;
+    selectedWorktreePath = candidateWorktreePath;
+    break;
   }
 
-  const hasOrigin = gitRun(repoRoot, ['remote', 'get-url', 'origin'], { allowFailure: true }).status === 0;
-  if (!hasOrigin) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (origin remote missing).');
-    return summary;
-  }
-  const explicitGhBin = Boolean(String(process.env.GUARDEX_GH_BIN || '').trim());
-  if (!explicitGhBin && !originRemoteLooksLikeGithub(repoRoot)) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (origin remote is not GitHub).');
-    return summary;
+  if (!selectedBranch || !selectedWorktreePath) {
+    throw new Error('Unable to allocate unique sandbox branch/worktree');
   }
 
-  const ghBin = process.env.GUARDEX_GH_BIN || 'gh';
-  if (run(ghBin, ['--version']).status !== 0) {
-    summary.enabled = false;
-    summary.details.push(`Skipped auto-finish sweep (${ghBin} not available).`);
-    return summary;
+  fs.mkdirSync(path.dirname(selectedWorktreePath), { recursive: true });
+  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;
   }
-
-  const branchWorktrees = mapWorktreePathsByBranch(repoRoot);
-  const agentBranches = listLocalAgentBranches(repoRoot);
-  if (agentBranches.length === 0) {
-    summary.enabled = false;
-    summary.details.push('No local agent branches found for auto-finish sweep.');
-    return summary;
+  if (addResult.status !== 0) {
+    throw new Error((addResult.stderr || addResult.stdout || 'failed to create sandbox').trim());
   }
 
-  for (const branch of agentBranches) {
-    if (excludedBranches.has(branch)) {
-      summary.skipped += 1;
-      summary.details.push(`[skip] ${branch}: excluded from this auto-finish sweep.`);
-      continue;
-    }
-
-    if (branch === baseBranch) {
-      summary.skipped += 1;
-      summary.details.push(`[skip] ${branch}: source branch equals base branch.`);
-      continue;
-    }
-
-    let counts;
-    try {
-      counts = aheadBehind(repoRoot, branch, baseBranch);
-    } catch (error) {
-      summary.failed += 1;
-      summary.details.push(`[fail] ${branch}: unable to compute ahead/behind (${error.message}).`);
-      continue;
-    }
-
-    if (counts.ahead <= 0) {
-      summary.skipped += 1;
-      summary.details.push(`[skip] ${branch}: already merged into ${baseBranch}.`);
-      continue;
-    }
-
-    const branchWorktree = branchWorktrees.get(branch) || '';
-    if (branchWorktree && hasSignificantWorkingTreeChanges(branchWorktree)) {
-      summary.skipped += 1;
-      summary.details.push(`[skip] ${branch}: dirty worktree (${branchWorktree}).`);
-      continue;
-    }
-
-    summary.attempted += 1;
-    const finishArgs = [
-      '--branch',
-      branch,
-      '--base',
-      baseBranch,
-      '--via-pr',
-      waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
-      '--cleanup',
-    ];
-    const finishResult = runPackageAsset('branchFinish', finishArgs, { cwd: repoRoot });
-    const combinedOutput = [finishResult.stdout || '', finishResult.stderr || ''].join('\n').trim();
-
-    if (finishResult.status === 0) {
-      summary.completed += 1;
-      summary.details.push(`[done] ${branch}: auto-finish completed.`);
-      continue;
+  if (!startRef) {
+    const renameResult = run(
+      'git',
+      ['-C', selectedWorktreePath, 'branch', '-m', selectedBranch],
+      { timeout: 20_000 },
+    );
+    if (isSpawnFailure(renameResult)) {
+      throw renameResult.error;
     }
-
-    const recoverableConflict = detectRecoverableAutoFinishConflict(combinedOutput);
-    if (recoverableConflict) {
-      summary.skipped += 1;
-      const tail = combinedOutput ? ` ${combinedOutput.split('\n').slice(-2).join(' | ')}` : '';
-      summary.details.push(`[skip] ${branch}: ${recoverableConflict.rawLabel}${tail}`);
-      continue;
+    if (renameResult.status !== 0) {
+      throw new Error(
+        (renameResult.stderr || renameResult.stdout || 'failed to name orphan sandbox branch').trim(),
+      );
     }
-
-    summary.failed += 1;
-    const tail = combinedOutput ? ` ${combinedOutput.split('\n').slice(-2).join(' | ')}` : '';
-    summary.details.push(`[fail] ${branch}: auto-finish failed.${tail}`);
-  }
-
-  return summary;
-}
-
-function ensureSetupProtectedBranches(repoRoot, dryRun) {
-  const localUserBranches = listLocalUserBranches(repoRoot);
-  if (localUserBranches.length === 0) {
-    return {
-      status: 'unchanged',
-      file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
-      note: 'no additional local user branches detected',
-    };
-  }
-
-  const configured = readConfiguredProtectedBranches(repoRoot);
-  const currentBranches = configured || [...DEFAULT_PROTECTED_BRANCHES];
-  const missingBranches = localUserBranches.filter((branchName) => !currentBranches.includes(branchName));
-  if (missingBranches.length === 0) {
-    return {
-      status: 'unchanged',
-      file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
-      note: 'local user branches already protected',
-    };
-  }
-
-  const nextBranches = uniquePreserveOrder([...currentBranches, ...missingBranches]);
-  if (!dryRun) {
-    writeProtectedBranches(repoRoot, nextBranches);
   }
 
   return {
-    status: dryRun ? 'would-update' : 'updated',
-    file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
-    note: `added local user branch(es): ${missingBranches.join(', ')}`,
+    metadata: {
+      branch: selectedBranch,
+      worktreePath: selectedWorktreePath,
+    },
+    stdout:
+      `[agent-branch-start] Created branch: ${selectedBranch}\n` +
+      `[agent-branch-start] Worktree: ${selectedWorktreePath}\n`,
+    stderr: addResult.stderr || '',
   };
 }
 
-function readProtectedBranches(repoRoot) {
-  const result = gitRun(repoRoot, ['config', '--get', GIT_PROTECTED_BRANCHES_KEY], { allowFailure: true });
-  if (result.status !== 0) {
-    return [...DEFAULT_PROTECTED_BRANCHES];
-  }
-
-  const parsed = uniquePreserveOrder(parseBranchList(result.stdout.trim()));
-  if (parsed.length === 0) {
-    return [...DEFAULT_PROTECTED_BRANCHES];
-  }
-  return parsed;
-}
-
-function writeProtectedBranches(repoRoot, branches) {
-  if (branches.length === 0) {
-    gitRun(repoRoot, ['config', '--unset-all', GIT_PROTECTED_BRANCHES_KEY], { allowFailure: true });
-    return;
-  }
-  gitRun(repoRoot, ['config', GIT_PROTECTED_BRANCHES_KEY, branches.join(' ')]);
-}
-
-function readGitConfig(repoRoot, key) {
-  const result = gitRun(repoRoot, ['config', '--get', key], { allowFailure: true });
-  if (result.status !== 0) {
-    return '';
-  }
-  return (result.stdout || '').trim();
-}
-
-function resolveBaseBranch(repoRoot, explicitBase) {
-  if (explicitBase) {
-    return explicitBase;
-  }
-  const configured = readGitConfig(repoRoot, GIT_BASE_BRANCH_KEY);
-  return configured || DEFAULT_BASE_BRANCH;
-}
-
-function resolveSyncStrategy(repoRoot, explicitStrategy) {
-  const strategy = (explicitStrategy || readGitConfig(repoRoot, GIT_SYNC_STRATEGY_KEY) || DEFAULT_SYNC_STRATEGY)
-    .trim()
-    .toLowerCase();
-  if (strategy !== 'rebase' && strategy !== 'merge') {
-    throw new Error(`Invalid sync strategy '${strategy}' (expected: rebase or merge)`);
+function startProtectedBaseSandbox(blocked, { taskName, sandboxSuffix }) {
+  if (sandboxSuffix === 'gx-doctor') {
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
-  return strategy;
-}
 
-function currentBranchName(repoRoot) {
-  const result = gitRun(repoRoot, ['branch', '--show-current'], { allowFailure: true });
-  if (result.status !== 0) {
-    throw new Error('Unable to detect current branch');
+  const startResult = runPackageAsset('branchStart', [
+    '--task',
+    taskName,
+    '--agent',
+    SHORT_TOOL_NAME,
+    '--base',
+    blocked.branch,
+  ], { cwd: blocked.repoRoot });
+  if (isSpawnFailure(startResult)) {
+    throw startResult.error;
   }
-  const branch = (result.stdout || '').trim();
-  if (!branch) {
-    throw new Error('Detached HEAD is not supported for sync operations');
+  if (startResult.status !== 0) {
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
-  return branch;
-}
 
-function repoHasHeadCommit(repoRoot) {
-  return gitRun(repoRoot, ['rev-parse', '--verify', 'HEAD'], { allowFailure: true }).status === 0;
-}
+  const metadata = extractAgentBranchStartMetadata(startResult.stdout);
+  const currentBranch = currentBranchName(blocked.repoRoot);
+  const worktreePath = metadata.worktreePath ? path.resolve(metadata.worktreePath) : '';
+  const repoRootPath = path.resolve(blocked.repoRoot);
+  const hasSafeWorktree = Boolean(worktreePath) && worktreePath !== repoRootPath;
+  const branchChanged = Boolean(currentBranch) && currentBranch !== blocked.branch;
 
-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)';
+  if (!hasSafeWorktree || branchChanged) {
+    const restoreResult = ensureRepoBranch(blocked.repoRoot, blocked.branch);
+    if (!restoreResult.ok) {
+      const detail = [restoreResult.stderr, restoreResult.stdout].filter(Boolean).join('\n').trim();
+      throw new Error(
+        `sandbox startup switched protected base checkout and could not restore '${blocked.branch}'.` +
+        (detail ? `\n${detail}` : ''),
+      );
     }
-    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 startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
-  return '(unknown)';
-}
 
-function repoHasOriginRemote(repoRoot) {
-  return gitRun(repoRoot, ['remote', 'get-url', 'origin'], { allowFailure: true }).status === 0;
+  return {
+    metadata,
+    stdout: startResult.stdout || '',
+    stderr: startResult.stderr || '',
+  };
 }
 
-function detectComposeHintFiles(repoRoot) {
-  return COMPOSE_HINT_FILES.filter((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
-}
+function cleanupProtectedBaseSandbox(repoRoot, metadata) {
+  const result = {
+    worktree: 'skipped',
+    branch: 'skipped',
+    note: 'missing sandbox metadata',
+  };
 
-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;
+  if (!metadata?.worktreePath || !metadata?.branch) {
+    return result;
   }
 
-  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}: ` +
-      `gx branch start "<task>" "codex" -> ` +
-      `gx locks claim --branch "$(git branch --show-current)" <file...> -> ` +
-      `gx branch finish --branch "$(git branch --show-current)" --base ${baseBranch} --via-pr --wait-for-merge`,
+  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 (!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...>'.`,
+
+  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 workingTreeIsDirty(repoRoot) {
-  const result = gitRun(repoRoot, ['status', '--porcelain'], { allowFailure: true });
-  if (result.status !== 0) {
-    throw new Error('Unable to inspect git working tree status');
-  }
-  const lines = (result.stdout || '').split('\n').filter((line) => line.length > 0);
-  const significant = lines.filter((line) => {
-    const pathPart = (line.length > 3 ? line.slice(3) : '').trim();
-    if (!pathPart) return false;
-    if (pathPart === LOCK_FILE_RELATIVE) return false;
-    if (pathPart.startsWith(`${LOCK_FILE_RELATIVE} -> `)) return false;
-    if (pathPart.endsWith(` -> ${LOCK_FILE_RELATIVE}`)) return false;
-    return true;
+function runSetupInSandbox(options, blocked, repoLabel = '') {
+  const startResult = startProtectedBaseSandbox(blocked, {
+    taskName: `${SHORT_TOOL_NAME}-setup`,
+    sandboxSuffix: 'gx-setup',
   });
-  return significant.length > 0;
-}
+  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.',
+  );
 
-function ensureOriginBaseRef(repoRoot, baseBranch) {
-  const fetch = gitRun(repoRoot, ['fetch', 'origin', baseBranch, '--quiet'], { allowFailure: true });
-  if (fetch.status !== 0) {
+  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(
-      `Unable to fetch origin/${baseBranch}. Ensure remote 'origin' exists and branch '${baseBranch}' is available.`,
+      `sandboxed setup failed for protected branch '${blocked.branch}'. ` +
+      `Inspect sandbox at ${metadata.worktreePath}`,
     );
   }
-  const hasRemoteBase = gitRun(repoRoot, ['show-ref', '--verify', '--quiet', `refs/remotes/origin/${baseBranch}`], {
-    allowFailure: true,
-  });
-  if (hasRemoteBase.status !== 0) {
-    throw new Error(`Remote base branch not found: origin/${baseBranch}`);
+
+  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}`);
   }
-}
 
-function aheadBehind(repoRoot, branchRef, baseRef) {
-  const result = gitRun(repoRoot, ['rev-list', '--left-right', '--count', `${branchRef}...${baseRef}`], {
-    allowFailure: true,
+  const scanResult = runScanInternal({ target: blocked.repoRoot, json: false });
+  const currentBaseBranch = currentBranchName(scanResult.repoRoot);
+  const autoFinishSummary = doctorModule.autoFinishReadyAgentBranches(scanResult.repoRoot, {
+    baseBranch: currentBaseBranch,
+    dryRun: syncOptions.dryRun,
   });
-  if (result.status !== 0) {
-    throw new Error(`Unable to compute ahead/behind for ${branchRef} vs ${baseRef}`);
+  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 parts = (result.stdout || '').trim().split(/\s+/).filter(Boolean);
-  const ahead = Number.parseInt(parts[0] || '0', 10);
-  const behind = Number.parseInt(parts[1] || '0', 10);
-  return { ahead: Number.isFinite(ahead) ? ahead : 0, behind: Number.isFinite(behind) ? behind : 0 };
-}
 
-function lockRegistryStatus(repoRoot) {
-  const result = gitRun(repoRoot, ['status', '--porcelain', '--', LOCK_FILE_RELATIVE], { allowFailure: true });
-  if (result.status !== 0) {
-    return { dirty: false, untracked: false };
-  }
-  const lines = (result.stdout || '').split('\n').filter((line) => line.length > 0);
-  if (lines.length === 0) {
-    return { dirty: false, untracked: false };
-  }
-  const untracked = lines.some((line) => line.startsWith('??'));
-  return { dirty: true, untracked };
+  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 listAgentWorktrees(repoRoot) {
-  const result = gitRun(repoRoot, ['worktree', 'list', '--porcelain'], { allowFailure: true });
-  if (result.status !== 0) {
-    throw new Error('Unable to list git worktrees for finish command');
-  }
+function todayDateStamp() {
+  return new Date().toISOString().slice(0, 10);
+}
 
-  const entries = [];
-  let currentPath = '';
-  let currentBranchRef = '';
-  const lines = String(result.stdout || '').split('\n');
-  for (const line of lines) {
-    if (!line.trim()) {
-      if (currentPath && currentBranchRef.startsWith('refs/heads/agent/')) {
-        entries.push({
-          worktreePath: currentPath,
-          branch: currentBranchRef.replace(/^refs\/heads\//, ''),
-        });
-      }
-      currentPath = '';
-      currentBranchRef = '';
-      continue;
-    }
-    if (line.startsWith('worktree ')) {
-      currentPath = line.slice('worktree '.length).trim();
-      continue;
-    }
-    if (line.startsWith('branch ')) {
-      currentBranchRef = line.slice('branch '.length).trim();
-      continue;
-    }
-  }
-  if (currentPath && currentBranchRef.startsWith('refs/heads/agent/')) {
-    entries.push({
-      worktreePath: currentPath,
-      branch: currentBranchRef.replace(/^refs\/heads\//, ''),
-    });
-  }
+function inferGithubRepoFromOrigin(repoRoot) {
+  const rawOrigin = readGitConfig(repoRoot, 'remote.origin.url');
+  if (!rawOrigin) return '';
 
-  return entries;
+  const httpsMatch = rawOrigin.match(/github\.com[:/](.+?)(?:\.git)?$/i);
+  if (!httpsMatch) return '';
+  const slug = (httpsMatch[1] || '').replace(/^\/+/, '').trim();
+  if (!slug || !slug.includes('/')) return '';
+  return `github.com/${slug}`;
 }
 
-function listLocalAgentBranchesForFinish(repoRoot) {
-  const result = gitRun(
-    repoRoot,
-    ['for-each-ref', '--format=%(refname:short)', 'refs/heads/agent/'],
-    { allowFailure: true },
-  );
-  if (result.status !== 0) {
-    throw new Error('Unable to list local agent branches');
-  }
-  return uniquePreserveOrder(
-    String(result.stdout || '')
-      .split('\n')
-      .map((line) => line.trim())
-      .filter((line) => line.startsWith('agent/')),
-  );
+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 gitQuietChangeResult(worktreePath, args) {
-  const result = run('git', ['-C', worktreePath, ...args], { stdio: 'pipe' });
-  if (result.status === 0) {
-    return false;
-  }
-  if (result.status === 1) {
-    return true;
+function resolveScorecardRepo(repoRoot, explicitRepo) {
+  if (explicitRepo) {
+    return explicitRepo.trim();
   }
+  const inferred = inferGithubRepoFromOrigin(repoRoot);
+  if (inferred) return inferred;
   throw new Error(
-    `git ${args.join(' ')} failed in ${worktreePath}: ${(
-      result.stderr || result.stdout || ''
-    ).trim()}`,
+    'Unable to infer GitHub repo from origin remote. Pass --repo github.com/<owner>/<repo>.',
   );
 }
 
-function worktreeHasLocalChanges(worktreePath) {
-  const hasUnstaged = gitQuietChangeResult(worktreePath, [
-    'diff',
-    '--quiet',
-    '--',
-    '.',
-    ':(exclude).omx/state/agent-file-locks.json',
-  ]);
-  if (hasUnstaged) {
-    return true;
-  }
-
-  const hasStaged = gitQuietChangeResult(worktreePath, [
-    'diff',
-    '--cached',
-    '--quiet',
-    '--',
-    '.',
-    ':(exclude).omx/state/agent-file-locks.json',
-  ]);
-  if (hasStaged) {
-    return true;
-  }
-
-  const untracked = run('git', ['-C', worktreePath, 'ls-files', '--others', '--exclude-standard'], {
-    stdio: 'pipe',
-  });
-  if (untracked.status !== 0) {
-    throw new Error(`Unable to inspect untracked files in ${worktreePath}`);
-  }
-  return String(untracked.stdout || '').trim().length > 0;
-}
-
-function gitOutputLines(worktreePath, args) {
-  const result = run('git', ['-C', worktreePath, ...args], { stdio: 'pipe' });
+function runScorecardJson(repo) {
+  const result = run(SCORECARD_BIN, ['--repo', repo, '--format', 'json'], { allowFailure: true });
   if (result.status !== 0) {
+    const details = (result.stderr || result.stdout || '').trim();
     throw new Error(
-      `git ${args.join(' ')} failed in ${worktreePath}: ${(
-        result.stderr || result.stdout || ''
-      ).trim()}`,
+      `Failed to run scorecard CLI ('${SCORECARD_BIN} --repo ${repo} --format json').${details ? `\n${details}` : ''}`,
     );
   }
-  return String(result.stdout || '')
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean);
-}
-
-function claimLocksForAutoCommit(repoRoot, worktreePath, branch) {
-  const changedFiles = uniquePreserveOrder([
-    ...gitOutputLines(worktreePath, ['diff', '--name-only', '--', '.', ':(exclude).omx/state/agent-file-locks.json']),
-    ...gitOutputLines(worktreePath, ['diff', '--cached', '--name-only', '--', '.', ':(exclude).omx/state/agent-file-locks.json']),
-    ...gitOutputLines(worktreePath, ['ls-files', '--others', '--exclude-standard']),
-  ]);
-
-  if (changedFiles.length > 0) {
-    const claim = runPackageAsset('lockTool', ['claim', '--branch', branch, ...changedFiles], {
-      cwd: repoRoot,
-      stdio: 'pipe',
-    });
-    if (claim.status !== 0) {
-      throw new Error(
-        `Lock claim failed for ${branch}: ${(
-          claim.stderr || claim.stdout || ''
-        ).trim()}`,
-      );
-    }
-  }
 
-  const deletedFiles = uniquePreserveOrder([
-    ...gitOutputLines(worktreePath, [
-      'diff',
-      '--name-only',
-      '--diff-filter=D',
-      '--',
-      '.',
-      ':(exclude).omx/state/agent-file-locks.json',
-    ]),
-    ...gitOutputLines(worktreePath, [
-      'diff',
-      '--cached',
-      '--name-only',
-      '--diff-filter=D',
-      '--',
-      '.',
-      ':(exclude).omx/state/agent-file-locks.json',
-    ]),
-  ]);
-
-  if (deletedFiles.length > 0) {
-    const allowDelete = runPackageAsset('lockTool', ['allow-delete', '--branch', branch, ...deletedFiles], {
-      cwd: repoRoot,
-      stdio: 'pipe',
-    });
-    if (allowDelete.status !== 0) {
-      throw new Error(
-        `Delete-lock grant failed for ${branch}: ${(
-          allowDelete.stderr || allowDelete.stdout || ''
-        ).trim()}`,
-      );
-    }
+  try {
+    return JSON.parse(result.stdout || '{}');
+  } catch (error) {
+    throw new Error(`Unable to parse scorecard JSON output: ${error.message}`);
   }
 }
 
-function branchExists(repoRoot, branch) {
-  const result = gitRun(repoRoot, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], {
-    allowFailure: true,
-  });
-  return result.status === 0;
-}
-
-function resolveFinishBaseBranch(repoRoot, _sourceBranch, explicitBase) {
-  if (explicitBase) {
-    return explicitBase;
+function readScorecardJsonFile(filePath) {
+  const absolute = path.resolve(filePath);
+  if (!fs.existsSync(absolute)) {
+    throw new Error(`scorecard JSON file not found: ${absolute}`);
   }
-
-  const configured = readGitConfig(repoRoot, GIT_BASE_BRANCH_KEY);
-  if (configured) {
-    return configured;
+  try {
+    return JSON.parse(fs.readFileSync(absolute, 'utf8'));
+  } catch (error) {
+    throw new Error(`Unable to parse scorecard JSON file: ${error.message}`);
   }
-
-  return DEFAULT_BASE_BRANCH;
 }
 
-function branchMergedIntoBase(repoRoot, branch, baseBranch) {
-  if (!branchExists(repoRoot, baseBranch)) {
-    return false;
-  }
-  const result = gitRun(repoRoot, ['merge-base', '--is-ancestor', branch, baseBranch], {
-    allowFailure: true,
+function normalizeScorecardChecks(payload) {
+  const rawChecks = Array.isArray(payload?.checks) ? payload.checks : [];
+  return rawChecks.map((check) => {
+    const name = String(check?.name || 'Unknown');
+    const rawScore = Number(check?.score);
+    const score = Number.isFinite(rawScore) ? rawScore : 0;
+    return {
+      name,
+      score,
+      risk: SCORECARD_RISK_BY_CHECK[name] || 'Unknown',
+    };
   });
-  if (result.status === 0) {
-    return true;
-  }
-  if (result.status === 1) {
-    return false;
-  }
-  throw new Error(`Unable to determine merge status for ${branch} -> ${baseBranch}`);
 }
 
-function autoCommitWorktreeForFinish(repoRoot, worktreePath, branch, options) {
-  const hasChanges = worktreeHasLocalChanges(worktreePath);
-  if (!hasChanges) {
-    return { changed: false, committed: false };
-  }
-
-  if (options.noAutoCommit) {
-    throw new Error(
-      `Branch '${branch}' has local changes in ${worktreePath}. Re-run without --no-auto-commit or commit manually first.`,
-    );
-  }
-
-  if (options.dryRun) {
-    return { changed: true, committed: false, dryRun: true };
-  }
-
-  claimLocksForAutoCommit(repoRoot, worktreePath, branch);
-
-  const addResult = run('git', ['-C', worktreePath, 'add', '-A'], { stdio: 'pipe' });
-  if (addResult.status !== 0) {
-    throw new Error(`git add failed in ${worktreePath}: ${(addResult.stderr || addResult.stdout || '').trim()}`);
-  }
+function renderScorecardBaselineMarkdown({ repo, score, checks, capturedAt, scorecardVersion, reportDate }) {
+  const rows = checks
+    .map((item) => `| ${item.name} | ${item.score} | ${item.risk} |`)
+    .join('\n');
 
-  const stagedHasChanges = gitQuietChangeResult(worktreePath, [
-    'diff',
-    '--cached',
-    '--quiet',
-    '--',
-    '.',
-    ':(exclude).omx/state/agent-file-locks.json',
-  ]);
-  if (!stagedHasChanges) {
-    return { changed: true, committed: false };
-  }
+  return [
+    '# OpenSSF Scorecard Baseline Report',
+    '',
+    `- **Repository:** \`${repo}\``,
+    '- **Source:** generated by `gx report scorecard`',
+    `- **Captured at:** ${capturedAt}`,
+    `- **Scorecard version:** \`${scorecardVersion}\``,
+    `- **Overall score:** **${score} / 10**`,
+    '',
+    '## Check breakdown',
+    '',
+    '| Check | Score | Risk |',
+    '|---|---:|---|',
+    rows || '| (none) | 0 | Unknown |',
+    '',
+    `## Report date`,
+    '',
+    `- ${reportDate}`,
+    '',
+  ].join('\n');
+}
 
-  const commitMessage = options.commitMessage || `Auto-finish: ${branch}`;
-  const commitResult = run('git', ['-C', worktreePath, 'commit', '-m', commitMessage], { stdio: 'pipe' });
-  if (commitResult.status !== 0) {
-    throw new Error(
-      `Auto-commit failed on '${branch}': ${(
-        commitResult.stderr || commitResult.stdout || ''
-      ).trim()}`,
-    );
-  }
+function renderScorecardRemediationPlanMarkdown({ baselineRelativePath, checks }) {
+  const failing = checks.filter((item) => item.score < 10);
+  const failingRows = failing
+    .sort((a, b) => a.score - b.score || a.name.localeCompare(b.name))
+    .map((item) => `| ${item.name} | ${item.score} | ${item.risk} |`)
+    .join('\n');
 
-  return { changed: true, committed: true, message: commitMessage };
+  return [
+    '# OpenSSF Scorecard Remediation Plan',
+    '',
+    `Based on baseline report: \`${baselineRelativePath}\`.`,
+    '',
+    '## Failing checks',
+    '',
+    '| Check | Score | Risk |',
+    '|---|---:|---|',
+    (failingRows || '| None | 10 | N/A |'),
+    '',
+    '## Priority order',
+    '',
+    '1. Fix **High** risk checks first (especially score 0 items).',
+    '2. Then close **Medium** risk checks with score < 10.',
+    '3. Finally address **Low** risk ecosystem/process checks.',
+    '',
+    '## Verification loop',
+    '',
+    '1. Run scorecard again.',
+    '2. Re-generate baseline + remediation files.',
+    '3. Compare score deltas and track improved checks.',
+    '',
+  ].join('\n');
 }
 
-function syncOperation(repoRoot, strategy, baseRef, ffOnly) {
-  if (strategy === 'rebase') {
-    if (ffOnly) {
-      throw new Error('--ff-only is only supported with --strategy merge');
-    }
-    const rebased = run('git', ['-C', repoRoot, 'rebase', baseRef], { stdio: 'pipe' });
-    if (rebased.status !== 0) {
-      const details = (rebased.stderr || rebased.stdout || '').trim();
-      const gitDir = path.join(repoRoot, '.git');
-      const rebaseActive = fs.existsSync(path.join(gitDir, 'rebase-merge')) || fs.existsSync(path.join(gitDir, 'rebase-apply'));
-      const help = rebaseActive
-        ? '\nResolve conflicts, then run: git rebase --continue\nOr abort: git rebase --abort'
-        : '';
-      throw new Error(`Sync failed during rebase onto ${baseRef}.${details ? `\n${details}` : ''}${help}`);
-    }
-    return;
-  }
+function parseBranchList(rawValue) {
+  return String(rawValue || '')
+    .split(/[\s,]+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
 
-  const mergeArgs = ['-C', repoRoot, 'merge', '--no-edit'];
-  if (ffOnly) {
-    mergeArgs.push('--ff-only');
-  }
-  mergeArgs.push(baseRef);
-  const merged = run('git', mergeArgs, { stdio: 'pipe' });
-  if (merged.status !== 0) {
-    const details = (merged.stderr || merged.stdout || '').trim();
-    const gitDir = path.join(repoRoot, '.git');
-    const mergeActive = fs.existsSync(path.join(gitDir, 'MERGE_HEAD'));
-    const help = mergeActive ? '\nResolve conflicts, then run: git commit\nOr abort: git merge --abort' : '';
-    throw new Error(`Sync failed during merge from ${baseRef}.${details ? `\n${details}` : ''}${help}`);
+function originRemoteLooksLikeGithub(repoRoot) {
+  const originUrl = readGitConfig(repoRoot, 'remote.origin.url');
+  if (!originUrl) {
+    return false;
   }
+  return /github\.com[:/]/i.test(originUrl);
 }
 
 function isInteractiveTerminal() {
@@ -3308,7 +1067,7 @@ function printUpdateAvailableBanner(current, latest) {
 }
 
 function maybeSelfUpdateBeforeStatus() {
-  return getToolchainApi().maybeSelfUpdateBeforeStatus();
+  return toolchainModule.maybeSelfUpdateBeforeStatus();
 }
 
 function readInstalledGuardexVersion() {
@@ -3443,7 +1202,7 @@ function printOpenSpecUpdateAvailableBanner(current, latest) {
 }
 
 function maybeOpenSpecUpdateBeforeStatus() {
-  return getToolchainApi().maybeOpenSpecUpdateBeforeStatus();
+  return toolchainModule.maybeOpenSpecUpdateBeforeStatus();
 }
 
 function promptYesNoStrict(question) {
@@ -3622,7 +1381,7 @@ function askGlobalInstallForMissing(options, missingPackages, missingLocalTools)
 }
 
 function installGlobalToolchain(options) {
-  return getToolchainApi().installGlobalToolchain(options);
+  return toolchainModule.installGlobalToolchain(options);
 }
 
 function findStaleLockPaths(repoRoot, locks) {
@@ -3982,9 +1741,9 @@ function status(rawArgs) {
     json: false,
   });
 
-  const toolchain = detectGlobalToolchainPackages();
+  const toolchain = toolchainModule.detectGlobalToolchainPackages();
   const npmServices = GLOBAL_TOOLCHAIN_PACKAGES.map((pkg) => {
-    const service = getGlobalToolchainService(pkg);
+    const service = toolchainModule.getGlobalToolchainService(pkg);
     if (!toolchain.ok) {
       return {
         name: service.name,
@@ -4002,12 +1761,12 @@ function status(rawArgs) {
       status: toolchain.installed.includes(pkg) ? 'active' : 'inactive',
     };
   });
-  const localCompanionServices = detectOptionalLocalCompanionTools().map((tool) => ({
+  const localCompanionServices = toolchainModule.detectOptionalLocalCompanionTools().map((tool) => ({
     name: tool.name,
     displayName: tool.displayName || tool.name,
     status: tool.status,
   }));
-  const requiredSystemTools = detectRequiredSystemTools();
+  const requiredSystemTools = toolchainModule.detectRequiredSystemTools();
   const services = [
     ...npmServices,
     ...localCompanionServices,
@@ -4076,7 +1835,7 @@ function status(rawArgs) {
     console.log(
       `[${TOOL_NAME}] Optional companion tools inactive: ${inactiveOptionalCompanions.join(', ')}`,
     );
-    for (const warning of describeMissingGlobalDependencyWarnings(
+    for (const warning of toolchainModule.describeMissingGlobalDependencyWarnings(
       npmServices
         .filter((service) => service.status === 'inactive')
         .map((service) => service.packageName),
@@ -4333,7 +2092,13 @@ function doctor(rawArgs) {
 
   const blocked = protectedBaseWriteBlock(singleRepoOptions, { requireBootstrap: false });
   if (blocked) {
-    runDoctorInSandbox(singleRepoOptions, blocked);
+    doctorModule.runDoctorInSandbox(singleRepoOptions, blocked, {
+      startProtectedBaseSandbox,
+      cleanupProtectedBaseSandbox,
+      ensureOmxScaffold,
+      configureHooks,
+      autoFinishReadyAgentBranches: doctorModule.autoFinishReadyAgentBranches,
+    });
     return;
   }
 
@@ -4350,7 +2115,7 @@ function doctor(rawArgs) {
       failed: 0,
       details: [],
     }
-    : autoFinishReadyAgentBranches(scanResult.repoRoot, {
+    : doctorModule.autoFinishReadyAgentBranches(scanResult.repoRoot, {
       baseBranch: currentBaseBranch,
       dryRun: singleRepoOptions.dryRun,
       waitForMerge: singleRepoOptions.waitForMerge,
@@ -4806,7 +2571,7 @@ function setup(rawArgs) {
     allowProtectedBaseWrite: false,
   });
 
-  const globalInstallStatus = installGlobalToolchain(options);
+  const globalInstallStatus = toolchainModule.installGlobalToolchain(options);
   if (globalInstallStatus.status === 'installed') {
     console.log(
       `[${TOOL_NAME}] ✅ Companion tools installed (${(globalInstallStatus.packages || []).join(', ')}).`,
@@ -4814,7 +2579,7 @@ function setup(rawArgs) {
   } else if (globalInstallStatus.status === 'already-installed') {
     console.log(`[${TOOL_NAME}] ✅ Companion tools already installed. Skipping.`);
   } else if (globalInstallStatus.status === 'failed') {
-    const installCommands = describeCompanionInstallCommands(
+    const installCommands = toolchainModule.describeCompanionInstallCommands(
       GLOBAL_TOOLCHAIN_PACKAGES,
       OPTIONAL_LOCAL_COMPANION_TOOLS,
     );
@@ -4830,13 +2595,13 @@ function setup(rawArgs) {
     );
   } else if (globalInstallStatus.status === 'skipped') {
     console.log(`[${TOOL_NAME}] ⚠️ Companion installs skipped by user choice.`);
-    for (const warning of describeMissingGlobalDependencyWarnings(
+    for (const warning of toolchainModule.describeMissingGlobalDependencyWarnings(
       globalInstallStatus.missingPackages || [],
     )) {
       console.log(`[${TOOL_NAME}] ⚠️ ${warning}`);
     }
   }
-  const requiredSystemTools = detectRequiredSystemTools();
+  const requiredSystemTools = toolchainModule.detectRequiredSystemTools();
   const missingSystemTools = requiredSystemTools.filter((tool) => tool.status !== 'active');
   if (missingSystemTools.length === 0) {
     console.log(`[${TOOL_NAME}] ✅ Required system tools available (${requiredSystemTools.map((tool) => tool.name).join(', ')}).`);
@@ -4904,7 +2669,7 @@ function setup(rawArgs) {
 
     const scanResult = runScanInternal({ target: repoPath, json: false });
     const currentBaseBranch = currentBranchName(scanResult.repoRoot);
-    const autoFinishSummary = autoFinishReadyAgentBranches(scanResult.repoRoot, {
+    const autoFinishSummary = doctorModule.autoFinishReadyAgentBranches(scanResult.repoRoot, {
       baseBranch: currentBaseBranch,
       dryRun: perRepoOptions.dryRun,
     });
@@ -5226,26 +2991,59 @@ function copyCommands() {
 function prompt(rawArgs) {
   const args = Array.isArray(rawArgs) ? rawArgs : [];
   let variant = 'prompt';
-  for (const arg of args) {
+  let listParts = false;
+  const selectedParts = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
     if (arg === '--exec' || arg === '--commands') variant = 'exec';
     else if (arg === '--snippet' || arg === '--agents') variant = 'snippet';
     else if (arg === '--prompt' || arg === '--full') variant = 'prompt';
+    else if (arg === '--list-parts') listParts = true;
+    else if (arg === '--part' || arg === '--parts') {
+      const rawValue = args[index + 1];
+      if (!rawValue || rawValue.startsWith('--')) {
+        throw new Error(`${arg} requires a value`);
+      }
+      selectedParts.push(...parseAiSetupPartNames(rawValue));
+      index += 1;
+    } else if (arg.startsWith('--part=')) {
+      selectedParts.push(...parseAiSetupPartNames(arg.slice('--part='.length)));
+    } else if (arg.startsWith('--parts=')) {
+      selectedParts.push(...parseAiSetupPartNames(arg.slice('--parts='.length)));
+    }
     else if (arg === '-h' || arg === '--help') variant = 'help';
     else throw new Error(`Unknown option: ${arg}`);
   }
   if (variant === 'help') {
     console.log(
       `${SHORT_TOOL_NAME} prompt commands:\n` +
-      `  ${SHORT_TOOL_NAME} prompt           Print AI setup checklist\n` +
-      `  ${SHORT_TOOL_NAME} prompt --exec    Print setup commands only (shell-ready)\n` +
-      `  ${SHORT_TOOL_NAME} prompt --snippet Print the AGENTS.md managed-block template`,
+      `  ${SHORT_TOOL_NAME} prompt                             Print AI setup checklist\n` +
+      `  ${SHORT_TOOL_NAME} prompt --exec                      Print setup commands only (shell-ready)\n` +
+      `  ${SHORT_TOOL_NAME} prompt --part <name>              Print only the named checklist slice(s)\n` +
+      `  ${SHORT_TOOL_NAME} prompt --exec --part <name>       Print only the named exec-capable slice(s)\n` +
+      `  ${SHORT_TOOL_NAME} prompt --list-parts               List prompt part names\n` +
+      `  ${SHORT_TOOL_NAME} prompt --exec --list-parts        List exec-capable prompt part names\n` +
+      `  ${SHORT_TOOL_NAME} prompt --snippet                  Print the AGENTS.md managed-block template`,
     );
     process.exitCode = 0;
     return;
   }
-  if (variant === 'exec') return copyCommands();
-  if (variant === 'snippet') return printAgentsSnippet();
-  return copyPrompt();
+  if (variant === 'snippet') {
+    if (listParts || selectedParts.length > 0) {
+      throw new Error('--snippet does not support --list-parts or --part');
+    }
+    return printAgentsSnippet();
+  }
+  if (listParts) {
+    if (selectedParts.length > 0) {
+      throw new Error('--list-parts does not support --part');
+    }
+    process.stdout.write(`${listAiSetupPartNames({ execOnly: variant === 'exec' }).join('\n')}\n`);
+    process.exitCode = 0;
+    return;
+  }
+  process.stdout.write(renderAiSetupPrompt({ exec: variant === 'exec', parts: selectedParts }));
+  process.exitCode = 0;
 }
 
 function branch(rawArgs) {
@@ -5376,19 +3174,19 @@ function migrate(rawArgs) {
 }
 
 function cleanup(rawArgs) {
-  return getFinishApi().cleanup(rawArgs);
+  return finishCommands.cleanup(rawArgs);
 }
 
 function merge(rawArgs) {
-  return getFinishApi().merge(rawArgs);
+  return finishCommands.merge(rawArgs);
 }
 
 function finish(rawArgs, defaults = {}) {
-  return getFinishApi().finish(rawArgs, defaults);
+  return finishCommands.finish(rawArgs, defaults);
 }
 
 function sync(rawArgs) {
-  return getFinishApi().sync(rawArgs);
+  return finishCommands.sync(rawArgs);
 }
 
 function protect(rawArgs) {
@@ -5473,8 +3271,8 @@ function main() {
   const args = process.argv.slice(2);
 
   if (args.length === 0) {
-    maybeSelfUpdateBeforeStatus();
-    maybeOpenSpecUpdateBeforeStatus();
+    toolchainModule.maybeSelfUpdateBeforeStatus();
+    toolchainModule.maybeOpenSpecUpdateBeforeStatus();
     status([]);
     return;
   }
@@ -5488,7 +3286,7 @@ function main() {
   }
 
   if (command === '--version' || command === '-v' || command === 'version') {
-    maybeSelfUpdateBeforeStatus();
+    toolchainModule.maybeSelfUpdateBeforeStatus();
     console.log(packageJson.version);
     return;
   }