@imdeadpool/guardex 5.0.1 → 5.0.3

package/bin/multiagent-safety.js

@@ -15,6 +15,14 @@ const GLOBAL_TOOLCHAIN_PACKAGES = [
   '@fission-ai/openspec',
   '@imdeadpool/codex-account-switcher',
 ];
+const GH_BIN = process.env.MUSAFETY_GH_BIN || 'gh';
+const REQUIRED_SYSTEM_TOOLS = [
+  {
+    name: 'gh',
+    command: GH_BIN,
+    installHint: 'https://cli.github.com/',
+  },
+];
 const MAINTAINER_RELEASE_REPO = path.resolve(
   process.env.MUSAFETY_RELEASE_REPO || '/tmp/multiagent-safety',
 );
@@ -58,6 +66,8 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
   '.githooks/pre-commit',
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-worktree-prune.sh',
+  'scripts/codex-agent.sh',
   'scripts/agent-file-locks.py',
 ]);
 
@@ -88,6 +98,7 @@ const COMMAND_TYPO_ALIASES = new Map([
   ['intsall', 'install'],
   ['docter', 'doctor'],
   ['doctro', 'doctor'],
+  ['cleunup', 'cleanup'],
   ['scna', 'scan'],
 ]);
 const SUGGESTIBLE_COMMANDS = [
@@ -100,6 +111,7 @@ const SUGGESTIBLE_COMMANDS = [
   'copy-commands',
   'protect',
   'sync',
+  'cleanup',
   'release',
   'install',
   'fix',
@@ -118,6 +130,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['copy-commands', 'Print setup checklist as executable commands only'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
   ['sync', 'Check or sync agent branches with origin/<base>'],
+  ['cleanup', 'Cleanup merged agent branches/worktrees (local + remote)'],
   ['install', 'Install templates/locks/hooks without running full setup (supports --no-gitignore)'],
   ['fix', 'Repair broken or missing guardrail files/config (supports --no-gitignore)'],
   ['scan', 'Report safety issues and exit non-zero on findings'],
@@ -136,10 +149,12 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
    gx setup
    # alias: gx init
 
-   - Setup detects global OMX/OpenSpec/codex-auth first.
+   - Setup detects global OMX/OpenSpec/codex-auth npm packages first.
    - If one is missing and setup asks for approval, reply explicitly:
      - y = run: npm i -g oh-my-codex @fission-ai/openspec @imdeadpool/codex-account-switcher (missing ones only)
      - n = skip global installs
+   - Setup also checks GitHub CLI (gh), required for PR/merge automation.
+   - If gh is missing: install it from https://cli.github.com/ and rerun gx setup.
 
 3) If setup reports warnings/errors, repair + re-check:
    gx doctor
@@ -152,6 +167,9 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
    - For every new user message/task, repeat the same cycle:
      start isolated agent branch/worktree -> claim file locks -> implement/verify ->
      finish via PR/merge cleanup with scripts/agent-branch-finish.sh.
+   - Finished branches stay available by default for audit/follow-up.
+     Remove them explicitly when done:
+     gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 
 5) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
@@ -168,12 +186,14 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
+gh --version
 gx setup
 gx doctor
 bash scripts/codex-agent.sh "task" "agent-name"
 bash scripts/agent-branch-start.sh "task" "agent-name"
 python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
 bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)"
+gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
 gx protect add release staging
 gx sync --check
@@ -288,7 +308,11 @@ NOTES
   - Short alias: ${SHORT_TOOL_NAME}
   - ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup
   - ${TOOL_NAME} setup asks for Y/N approval before global installs
-  - In initialized repos, setup/install/fix/doctor block in-place writes on protected main by default
+  - ${TOOL_NAME} setup checks GitHub CLI (gh) and prints install guidance if missing
+  - In initialized repos, setup/install/fix block in-place writes on protected main by default
+  - doctor auto-runs in a sandbox agent branch/worktree on protected main and tries auto-finish PR flow
+  - agent-branch-finish merges by default and keeps agent branches/worktrees until explicit cleanup
+  - use '${SHORT_TOOL_NAME} cleanup' to remove merged agent branches/worktrees (optionally remote refs too)
   - Legacy command aliases are still supported: ${LEGACY_NAMES.join(', ')}`);
 
   if (outsideGitRepo) {
@@ -362,6 +386,10 @@ function ensureExecutable(destinationPath, relativePath, dryRun) {
   }
 }
 
+function isCriticalGuardrailPath(relativePath) {
+  return CRITICAL_GUARDRAIL_PATHS.has(relativePath);
+}
+
 function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
   const sourcePath = path.join(TEMPLATE_ROOT, relativeTemplatePath);
   const destinationRelativePath = toDestinationPath(relativeTemplatePath);
@@ -376,7 +404,7 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
       ensureExecutable(destinationPath, destinationRelativePath, dryRun);
       return { status: 'unchanged', file: destinationRelativePath };
     }
-    if (!force) {
+    if (!force && !isCriticalGuardrailPath(destinationRelativePath)) {
       throw new Error(
         `Refusing to overwrite existing file without --force: ${destinationRelativePath}`,
       );
@@ -389,6 +417,10 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
   }
 
+  if (destinationExists && !force && isCriticalGuardrailPath(destinationRelativePath)) {
+    return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
+  }
+
   return { status: destinationExists ? 'overwritten' : 'created', file: destinationRelativePath };
 }
 
@@ -405,6 +437,14 @@ function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
       return { status: 'unchanged', file: destinationRelativePath };
     }
 
+    if (isCriticalGuardrailPath(destinationRelativePath)) {
+      if (!dryRun) {
+        fs.writeFileSync(destinationPath, sourceContent, 'utf8');
+        ensureExecutable(destinationPath, destinationRelativePath, dryRun);
+      }
+      return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
+    }
+
     // In fix mode, avoid silently replacing local customizations.
     return { status: 'skipped-conflict', file: destinationRelativePath };
   }
@@ -489,7 +529,7 @@ function ensurePackageScripts(repoRoot, dryRun) {
     'agent:codex': 'bash ./scripts/codex-agent.sh',
     'agent:branch:start': 'bash ./scripts/agent-branch-start.sh',
     'agent:branch:finish': 'bash ./scripts/agent-branch-finish.sh',
-    'agent:cleanup': 'bash ./scripts/agent-worktree-prune.sh',
+    'agent:cleanup': `${SHORT_TOOL_NAME} cleanup`,
     'agent:hooks:install': 'bash ./scripts/install-agent-git-hooks.sh',
     'agent:locks:claim': 'python3 ./scripts/agent-file-locks.py claim',
     'agent:locks:allow-delete': 'python3 ./scripts/agent-file-locks.py allow-delete',
@@ -671,34 +711,547 @@ function hasGuardexBootstrapFiles(repoRoot) {
   return required.every((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
 }
 
-function assertProtectedMainWriteAllowed(options, commandName) {
+function protectedBaseWriteBlock(options, { requireBootstrap = true } = {}) {
   if (options.dryRun || options.allowProtectedBaseWrite) {
-    return;
+    return null;
   }
 
   const repoRoot = resolveRepoRoot(options.target);
-  if (!hasGuardexBootstrapFiles(repoRoot)) {
-    return;
+  if (requireBootstrap && !hasGuardexBootstrapFiles(repoRoot)) {
+    return null;
   }
 
   const branch = currentBranchName(repoRoot);
   if (branch !== 'main') {
-    return;
+    return null;
   }
 
   const protectedBranches = readProtectedBranches(repoRoot);
   if (!protectedBranches.includes(branch)) {
+    return null;
+  }
+
+  return {
+    repoRoot,
+    branch,
+  };
+}
+
+function assertProtectedMainWriteAllowed(options, commandName) {
+  const blocked = protectedBaseWriteBlock(options);
+  if (!blocked) {
     return;
   }
 
   throw new Error(
-    `${commandName} blocked on protected branch '${branch}' in an initialized repo.\n` +
-    `Keep local '${branch}' pull-only: start an agent branch/worktree first:\n` +
+    `${commandName} blocked on protected branch '${blocked.branch}' in an initialized repo.\n` +
+    `Keep local '${blocked.branch}' pull-only: start an agent branch/worktree first:\n` +
     `  bash scripts/agent-branch-start.sh "<task>" "codex"\n` +
     `Override once only when intentional: --allow-protected-base-write`,
   );
 }
 
+function extractAgentBranchStartMetadata(output) {
+  const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
+  const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
+  return {
+    branch: branchMatch ? branchMatch[1].trim() : '',
+    worktreePath: worktreeMatch ? worktreeMatch[1].trim() : '',
+  };
+}
+
+function resolveSandboxTarget(repoRoot, worktreePath, targetPath) {
+  const resolvedTarget = path.resolve(targetPath);
+  const relativeTarget = path.relative(repoRoot, resolvedTarget);
+  if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
+    throw new Error(`doctor target must stay inside repo root when sandboxing: ${resolvedTarget}`);
+  }
+  if (!relativeTarget || relativeTarget === '.') {
+    return worktreePath;
+  }
+  return path.join(worktreePath, relativeTarget);
+}
+
+function buildSandboxDoctorArgs(options, sandboxTarget) {
+  const args = ['doctor', '--target', sandboxTarget];
+  if (options.dryRun) args.push('--dry-run');
+  if (options.skipAgents) args.push('--skip-agents');
+  if (options.skipPackageJson) args.push('--skip-package-json');
+  if (options.skipGitignore) args.push('--no-gitignore');
+  if (!options.dropStaleLocks) args.push('--keep-stale-locks');
+  if (options.json) args.push('--json');
+  return args;
+}
+
+function isSpawnFailure(result) {
+  return Boolean(result?.error) && typeof result?.status !== 'number';
+}
+
+function doctorSandboxBranchPrefix() {
+  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 doctorSandboxWorktreePath(repoRoot, branchName) {
+  return path.join(repoRoot, '.omx', 'agent-worktrees', branchName.replace(/\//g, '__'));
+}
+
+function gitRefExists(repoRoot, ref) {
+  return run('git', ['-C', repoRoot, 'show-ref', '--verify', '--quiet', ref]).status === 0;
+}
+
+function resolveDoctorSandboxStartRef(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;
+  }
+  throw new Error(`Unable to find base ref for sandbox doctor: ${baseBranch}`);
+}
+
+function startDoctorSandboxFallback(blocked) {
+  const branchPrefix = doctorSandboxBranchPrefix();
+  let selectedBranch = '';
+  let selectedWorktreePath = '';
+
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    const suffix = attempt === 0 ? 'gx-doctor' : `${attempt + 1}-gx-doctor`;
+    const candidateBranch = `${branchPrefix}-${suffix}`;
+    const candidateWorktreePath = doctorSandboxWorktreePath(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 for doctor');
+  }
+
+  fs.mkdirSync(path.dirname(selectedWorktreePath), { recursive: true });
+  const startRef = resolveDoctorSandboxStartRef(blocked.repoRoot, blocked.branch);
+  const addResult = run(
+    'git',
+    ['-C', blocked.repoRoot, 'worktree', 'add', '-b', selectedBranch, selectedWorktreePath, startRef],
+  );
+  if (isSpawnFailure(addResult)) {
+    throw addResult.error;
+  }
+  if (addResult.status !== 0) {
+    throw new Error((addResult.stderr || addResult.stdout || 'failed to create doctor sandbox').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 startDoctorSandbox(blocked) {
+  const startScript = path.join(blocked.repoRoot, 'scripts', 'agent-branch-start.sh');
+  if (!fs.existsSync(startScript)) {
+    return startDoctorSandboxFallback(blocked);
+  }
+
+  const startResult = run('bash', [
+    startScript,
+    '--task',
+    `${SHORT_TOOL_NAME}-doctor`,
+    '--agent',
+    SHORT_TOOL_NAME,
+    '--base',
+    blocked.branch,
+  ], { cwd: blocked.repoRoot });
+  if (isSpawnFailure(startResult)) {
+    throw startResult.error;
+  }
+  if (startResult.status !== 0) {
+    throw new Error((startResult.stderr || startResult.stdout || 'failed to start doctor sandbox').trim());
+  }
+
+  const metadata = extractAgentBranchStartMetadata(startResult.stdout);
+  if (!metadata.worktreePath) {
+    throw new Error(`Failed to parse sandbox worktree from agent-branch-start output:\n${startResult.stdout}`);
+  }
+
+  return {
+    metadata,
+    stdout: startResult.stdout || '',
+    stderr: startResult.stderr || '',
+  };
+}
+
+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 claimDoctorChangedLocks(metadata) {
+  const lockScript = path.join(metadata.worktreePath, 'scripts', 'agent-file-locks.py');
+  if (!fs.existsSync(lockScript) || !metadata.branch) {
+    return {
+      status: 'skipped',
+      note: 'lock helper unavailable in sandbox',
+      changedCount: 0,
+      deletedCount: 0,
+    };
+  }
+
+  const changedPaths = collectDoctorChangedPaths(metadata.worktreePath);
+  const deletedPaths = collectDoctorDeletedPaths(metadata.worktreePath);
+  if (changedPaths.length > 0) {
+    run('python3', [lockScript, 'claim', '--branch', metadata.branch, ...changedPaths], {
+      cwd: metadata.worktreePath,
+      timeout: 30_000,
+    });
+  }
+  if (deletedPaths.length > 0) {
+    run('python3', [lockScript, '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'], { 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 isCommandAvailable(commandName) {
+  return run('which', [commandName]).status === 0;
+}
+
+function finishDoctorSandboxBranch(blocked, metadata) {
+  const finishScript = path.join(metadata.worktreePath, 'scripts', 'agent-branch-finish.sh');
+  if (!fs.existsSync(finishScript)) {
+    return {
+      status: 'skipped',
+      note: `${path.relative(metadata.worktreePath, finishScript)} missing in sandbox`,
+    };
+  }
+  if (!hasOriginRemote(blocked.repoRoot)) {
+    return {
+      status: 'skipped',
+      note: 'origin remote missing; skipped auto-finish',
+    };
+  }
+
+  const ghBin = process.env.MUSAFETY_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 finishResult = run(
+    'bash',
+    [finishScript, '--branch', metadata.branch, '--via-pr'],
+    { cwd: metadata.worktreePath, timeout: 180_000 },
+  );
+  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 || '',
+    };
+  }
+
+  return {
+    status: 'completed',
+    note: 'doctor sandbox finish flow completed',
+    stdout: finishResult.stdout || '',
+    stderr: finishResult.stderr || '',
+  };
+}
+
+function runDoctorInSandbox(options, blocked) {
+  const startResult = startDoctorSandbox(blocked);
+  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;
+  }
+
+  let autoCommitResult = {
+    status: 'skipped',
+    note: 'sandbox doctor did not complete successfully',
+  };
+  let finishResult = {
+    status: 'skipped',
+    note: 'sandbox doctor did not complete successfully',
+  };
+
+  let lockSyncResult = {
+    status: 'skipped',
+    note: 'sandbox doctor did not complete successfully',
+  };
+  if (nestedResult.status === 0) {
+    if (!options.dryRun) {
+      autoCommitResult = autoCommitDoctorSandboxChanges(metadata);
+      if (autoCommitResult.status === 'committed') {
+        finishResult = finishDoctorSandboxBranch(blocked, metadata);
+      } else if (autoCommitResult.status === 'no-changes') {
+        finishResult = {
+          status: 'skipped',
+          note: 'no doctor changes to auto-finish',
+        };
+      } else if (autoCommitResult.status !== 'failed') {
+        finishResult = {
+          status: 'skipped',
+          note: 'auto-commit did not run',
+        };
+      }
+    } else {
+      autoCommitResult = {
+        status: 'skipped',
+        note: 'dry-run skips doctor sandbox auto-commit',
+      };
+      finishResult = {
+        status: 'skipped',
+        note: 'dry-run skips doctor sandbox finish flow',
+      };
+    }
+
+    const sandboxLockPath = path.join(metadata.worktreePath, LOCK_FILE_RELATIVE);
+    const baseLockPath = path.join(blocked.repoRoot, LOCK_FILE_RELATIVE);
+    if (!fs.existsSync(baseLockPath)) {
+      lockSyncResult = {
+        status: 'skipped',
+        note: `${LOCK_FILE_RELATIVE} missing in protected base workspace`,
+      };
+    } else if (!fs.existsSync(sandboxLockPath)) {
+      lockSyncResult = {
+        status: 'skipped',
+        note: `${LOCK_FILE_RELATIVE} missing in sandbox worktree`,
+      };
+    } else {
+      const sourceContent = fs.readFileSync(sandboxLockPath, 'utf8');
+      const destinationContent = fs.readFileSync(baseLockPath, 'utf8');
+      if (sourceContent === destinationContent) {
+        lockSyncResult = {
+          status: 'unchanged',
+          note: `${LOCK_FILE_RELATIVE} already in sync`,
+        };
+      } else {
+        fs.mkdirSync(path.dirname(baseLockPath), { recursive: true });
+        fs.writeFileSync(baseLockPath, sourceContent, 'utf8');
+        lockSyncResult = {
+          status: 'synced',
+          note: `${LOCK_FILE_RELATIVE} synced from sandbox`,
+        };
+      }
+    }
+  }
+
+  if (options.json) {
+    if (nestedResult.stdout) {
+      if (nestedResult.status === 0) {
+        try {
+          const parsed = JSON.parse(nestedResult.stdout);
+          process.stdout.write(
+            JSON.stringify(
+              {
+                ...parsed,
+                sandboxLockSync: lockSyncResult,
+                sandboxAutoCommit: autoCommitResult,
+                sandboxFinish: finishResult,
+              },
+              null,
+              2,
+            ) + '\n',
+          );
+        } catch {
+          process.stdout.write(nestedResult.stdout);
+        }
+      } else {
+        process.stdout.write(nestedResult.stdout);
+      }
+    }
+    if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+  } else {
+    console.log(
+      `[${TOOL_NAME}] doctor detected protected branch '${blocked.branch}'. ` +
+      `Running repairs in sandbox branch '${metadata.branch || 'agent/<auto>'}'.`,
+    );
+    if (startResult.stdout) process.stdout.write(startResult.stdout);
+    if (startResult.stderr) process.stderr.write(startResult.stderr);
+    if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
+    if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+    if (nestedResult.status === 0) {
+      if (autoCommitResult.status === 'committed') {
+        console.log(
+          `[${TOOL_NAME}] Auto-committed doctor repairs in sandbox branch '${metadata.branch}'.`,
+        );
+      } else if (autoCommitResult.status === 'failed') {
+        console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit failed; branch left for manual follow-up.`);
+        if (autoCommitResult.stdout) process.stdout.write(autoCommitResult.stdout);
+        if (autoCommitResult.stderr) process.stderr.write(autoCommitResult.stderr);
+      } else {
+        console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit skipped: ${autoCommitResult.note}.`);
+      }
+
+      if (finishResult.status === 'completed') {
+        console.log(`[${TOOL_NAME}] Auto-finish flow completed for sandbox branch '${metadata.branch}'.`);
+        if (finishResult.stdout) process.stdout.write(finishResult.stdout);
+        if (finishResult.stderr) process.stderr.write(finishResult.stderr);
+      } else if (finishResult.status === 'failed') {
+        console.log(`[${TOOL_NAME}] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
+        if (finishResult.stdout) process.stdout.write(finishResult.stdout);
+        if (finishResult.stderr) process.stderr.write(finishResult.stderr);
+      } else {
+        console.log(`[${TOOL_NAME}] Auto-finish skipped: ${finishResult.note}.`);
+      }
+
+      if (lockSyncResult.status === 'synced') {
+        console.log(
+          `[${TOOL_NAME}] Synced repaired lock registry back to protected branch workspace (${LOCK_FILE_RELATIVE}).`,
+        );
+      } else if (lockSyncResult.status === 'unchanged') {
+        console.log(`[${TOOL_NAME}] Lock registry already synced in protected branch workspace.`);
+      } else {
+        console.log(`[${TOOL_NAME}] Lock registry sync skipped: ${lockSyncResult.note}.`);
+      }
+    }
+  }
+
+  if (typeof nestedResult.status === 'number') {
+    process.exitCode = nestedResult.status;
+    return;
+  }
+  process.exitCode = 1;
+}
+
 function parseTargetFlag(rawArgs, defaultTarget = process.cwd()) {
   const remaining = [];
   let target = defaultTarget;
@@ -1134,6 +1687,63 @@ function parseSyncArgs(rawArgs) {
   return options;
 }
 
+function parseCleanupArgs(rawArgs) {
+  const options = {
+    target: process.cwd(),
+    base: '',
+    branch: '',
+    dryRun: false,
+    forceDirty: false,
+    keepRemote: false,
+  };
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--target') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--target requires a path value');
+      }
+      options.target = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--base') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--base requires a branch value');
+      }
+      options.base = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--branch') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--branch requires an agent branch value');
+      }
+      options.branch = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === '--force-dirty') {
+      options.forceDirty = true;
+      continue;
+    }
+    if (arg === '--keep-remote') {
+      options.keepRemote = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return options;
+}
+
 function syncOperation(repoRoot, strategy, baseRef, ffOnly) {
   if (strategy === 'rebase') {
     if (ffOnly) {
@@ -1171,6 +1781,12 @@ function isInteractiveTerminal() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 
+const stdinWaitArray = new Int32Array(new SharedArrayBuffer(4));
+
+function sleepSyncMs(milliseconds) {
+  Atomics.wait(stdinWaitArray, 0, 0, milliseconds);
+}
+
 function readSingleLineFromStdin() {
   let input = '';
   const buffer = Buffer.alloc(1);
@@ -1179,11 +1795,19 @@ function readSingleLineFromStdin() {
     let bytesRead = 0;
     try {
       bytesRead = fs.readSync(process.stdin.fd, buffer, 0, 1);
-    } catch {
+    } catch (error) {
+      if (error && ['EAGAIN', 'EWOULDBLOCK', 'EINTR'].includes(error.code)) {
+        sleepSyncMs(15);
+        continue;
+      }
       return input;
     }
 
     if (bytesRead === 0) {
+      if (process.stdin.isTTY) {
+        sleepSyncMs(15);
+        continue;
+      }
       return input;
     }
 
@@ -1323,9 +1947,8 @@ function maybeSelfUpdateBeforeStatus() {
   }
 
   const shouldUpdate = interactive
-    ? promptYesNo(
+    ? promptYesNoStrict(
       `Update now? (${NPM_BIN} i -g ${packageJson.name}@latest)`,
-      false,
     )
     : autoApproval;
 
@@ -1418,6 +2041,26 @@ function detectGlobalToolchainPackages() {
   return { ok: true, installed, missing };
 }
 
+function detectRequiredSystemTools() {
+  const services = [];
+  for (const tool of REQUIRED_SYSTEM_TOOLS) {
+    const result = run(tool.command, ['--version']);
+    const active = result.status === 0;
+    const rawReason = result.error && result.error.code
+      ? result.error.code
+      : (result.stderr || '').trim();
+    const reason = rawReason.split('\n')[0] || '';
+    services.push({
+      name: tool.name,
+      command: tool.command,
+      installHint: tool.installHint,
+      status: active ? 'active' : 'inactive',
+      reason,
+    });
+  }
+  return services;
+}
+
 function askGlobalInstallForMissing(options, missingPackages) {
   const approval = resolveGlobalInstallApproval(options);
   if (!approval.approved) {
@@ -1747,7 +2390,7 @@ function status(rawArgs) {
   });
 
   const toolchain = detectGlobalToolchainPackages();
-  const services = GLOBAL_TOOLCHAIN_PACKAGES.map((pkg) => {
+  const npmServices = GLOBAL_TOOLCHAIN_PACKAGES.map((pkg) => {
     if (!toolchain.ok) {
       return { name: pkg, status: 'unknown' };
     }
@@ -1756,6 +2399,14 @@ function status(rawArgs) {
       status: toolchain.installed.includes(pkg) ? 'active' : 'inactive',
     };
   });
+  const requiredSystemTools = detectRequiredSystemTools();
+  const services = [
+    ...npmServices,
+    ...requiredSystemTools.map((tool) => ({
+      name: tool.name,
+      status: tool.status,
+    })),
+  ];
 
   const targetPath = path.resolve(options.target);
   const inGitRepo = isGitRepo(targetPath);
@@ -1803,6 +2454,15 @@ function status(rawArgs) {
   for (const service of services) {
     console.log(`  - ${statusDot(service.status)} ${service.name}: ${service.status}`);
   }
+  const missingSystemTools = requiredSystemTools.filter((tool) => tool.status !== 'active');
+  if (missingSystemTools.length > 0) {
+    const tools = missingSystemTools.map((tool) => tool.name).join(', ');
+    console.log(`[${TOOL_NAME}] ⚠️ Missing required system tool(s): ${tools}`);
+    for (const tool of missingSystemTools) {
+      const reasonText = tool.reason ? ` (${tool.reason})` : '';
+      console.log(`  - install ${tool.name}: ${tool.installHint}${reasonText}`);
+    }
+  }
 
   if (!scanResult) {
     console.log(
@@ -1894,10 +2554,17 @@ function doctor(rawArgs) {
     allowProtectedBaseWrite: false,
   });
 
+  const blocked = protectedBaseWriteBlock(options, { requireBootstrap: false });
+  if (blocked) {
+    runDoctorInSandbox(options, blocked);
+    return;
+  }
+
   assertProtectedMainWriteAllowed(options, 'doctor');
   const fixPayload = runFixInternal(options);
   const scanResult = runScanInternal({ target: options.target, json: false });
-  const musafe = scanResult.errors === 0 && scanResult.warnings === 0;
+  const safe = scanResult.errors === 0 && scanResult.warnings === 0;
+  const musafe = safe;
 
   if (options.json) {
     process.stdout.write(
@@ -1905,6 +2572,7 @@ function doctor(rawArgs) {
         {
           repoRoot: scanResult.repoRoot,
           branch: scanResult.branch,
+          safe,
           musafe,
           fix: {
             operations: fixPayload.operations,
@@ -1927,11 +2595,11 @@ function doctor(rawArgs) {
 
   printOperations('Doctor/fix', fixPayload, options.dryRun);
   printScanResult(scanResult, false);
-  if (musafe) {
-    console.log(`[${TOOL_NAME}] ✅ Repo is correctly musafe.`);
+  if (safe) {
+    console.log(`[${TOOL_NAME}] ✅ Repo is fully safe.`);
   } else {
     console.log(
-      `[${TOOL_NAME}] ⚠️ Repo is not fully musafe yet (${scanResult.errors} error(s), ${scanResult.warnings} warning(s)).`,
+      `[${TOOL_NAME}] ⚠️ Repo is not fully safe yet (${scanResult.errors} error(s), ${scanResult.warnings} warning(s)).`,
     );
   }
   setExitCodeFromScan(scanResult);
@@ -2047,7 +2715,7 @@ function setup(rawArgs) {
       `[${TOOL_NAME}] ✅ Global tools installed (${(globalInstallStatus.packages || []).join(', ')}).`,
     );
   } else if (globalInstallStatus.status === 'already-installed') {
-    console.log(`[${TOOL_NAME}] ✅ OMX/OpenSpec/codex-auth global tools already installed. Skipping.`);
+    console.log(`[${TOOL_NAME}] ✅ OMX/OpenSpec/codex-auth npm global tools already installed. Skipping.`);
   } else if (globalInstallStatus.status === 'failed') {
     console.log(
       `[${TOOL_NAME}] ⚠️ Global install failed: ${globalInstallStatus.reason}\n` +
@@ -2060,6 +2728,18 @@ function setup(rawArgs) {
       `Use --yes-global-install to force or run interactively for Y/N prompt.`,
     );
   }
+  const requiredSystemTools = 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(', ')}).`);
+  } else {
+    const names = missingSystemTools.map((tool) => tool.name).join(', ');
+    console.log(`[${TOOL_NAME}] ⚠️ Missing required system tool(s): ${names}`);
+    for (const tool of missingSystemTools) {
+      const reasonText = tool.reason ? ` (${tool.reason})` : '';
+      console.log(`[${TOOL_NAME}] Install ${tool.name}: ${tool.installHint}${reasonText}`);
+    }
+  }
 
   assertProtectedMainWriteAllowed(options, 'setup');
   const installPayload = runInstallInternal(options);
@@ -2156,6 +2836,39 @@ function copyCommands() {
   process.exitCode = 0;
 }
 
+function cleanup(rawArgs) {
+  const options = parseCleanupArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(options.target);
+  const pruneScript = path.join(repoRoot, 'scripts', 'agent-worktree-prune.sh');
+  if (!fs.existsSync(pruneScript)) {
+    throw new Error(`Missing cleanup script: ${pruneScript}. Run '${SHORT_TOOL_NAME} setup' first.`);
+  }
+
+  const args = [pruneScript];
+  if (options.base) {
+    args.push('--base', options.base);
+  }
+  if (options.branch) {
+    args.push('--branch', options.branch);
+  }
+  if (options.forceDirty) {
+    args.push('--force-dirty');
+  }
+  if (options.dryRun) {
+    args.push('--dry-run');
+  }
+  args.push('--delete-branches');
+  if (!options.keepRemote) {
+    args.push('--delete-remote-branches');
+  }
+
+  const runResult = run('bash', args, { cwd: repoRoot, stdio: 'inherit' });
+  if (runResult.status !== 0) {
+    throw new Error('Cleanup command failed');
+  }
+  process.exitCode = 0;
+}
+
 function sync(rawArgs) {
   const options = parseSyncArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -2504,6 +3217,11 @@ function main() {
     return;
   }
 
+  if (command === 'cleanup') {
+    cleanup(rest);
+    return;
+  }
+
   if (command === 'release') {
     release(rest);
     return;