@imdeadpool/guardex 5.0.2 → 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',
 );
@@ -141,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
@@ -176,6 +186,7 @@ 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"
@@ -297,8 +308,9 @@ 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
+  - ${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-starts a sandbox agent branch/worktree when run on protected main
+  - 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(', ')}`);
@@ -699,13 +711,13 @@ function hasGuardexBootstrapFiles(repoRoot) {
   return required.every((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
 }
 
-function protectedBaseWriteBlock(options) {
+function protectedBaseWriteBlock(options, { requireBootstrap = true } = {}) {
   if (options.dryRun || options.allowProtectedBaseWrite) {
     return null;
   }
 
   const repoRoot = resolveRepoRoot(options.target);
-  if (!hasGuardexBootstrapFiles(repoRoot)) {
+  if (requireBootstrap && !hasGuardexBootstrapFiles(repoRoot)) {
     return null;
   }
 
@@ -771,13 +783,96 @@ function buildSandboxDoctorArgs(options, sandboxTarget) {
   return args;
 }
 
-function runDoctorInSandbox(options, blocked) {
+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)) {
-    throw new Error(
-      `doctor sandbox fallback is unavailable because '${startScript}' is missing.\n` +
-      `Run '${SHORT_TOOL_NAME} setup --allow-protected-base-write' once to restore branch-start tooling.`,
-    );
+    return startDoctorSandboxFallback(blocked);
   }
 
   const startResult = run('bash', [
@@ -789,7 +884,7 @@ function runDoctorInSandbox(options, blocked) {
     '--base',
     blocked.branch,
   ], { cwd: blocked.repoRoot });
-  if (startResult.error) {
+  if (isSpawnFailure(startResult)) {
     throw startResult.error;
   }
   if (startResult.status !== 0) {
@@ -801,18 +896,308 @@ function runDoctorInSandbox(options, blocked) {
     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 (nestedResult.error) {
+  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) process.stdout.write(nestedResult.stdout);
+    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(
@@ -823,6 +1208,41 @@ function runDoctorInSandbox(options, blocked) {
     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') {
@@ -1361,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);
@@ -1369,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;
     }
 
@@ -1513,9 +1947,8 @@ function maybeSelfUpdateBeforeStatus() {
   }
 
   const shouldUpdate = interactive
-    ? promptYesNo(
+    ? promptYesNoStrict(
       `Update now? (${NPM_BIN} i -g ${packageJson.name}@latest)`,
-      false,
     )
     : autoApproval;
 
@@ -1608,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) {
@@ -1937,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' };
     }
@@ -1946,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);
@@ -1993,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(
@@ -2084,7 +2554,7 @@ function doctor(rawArgs) {
     allowProtectedBaseWrite: false,
   });
 
-  const blocked = protectedBaseWriteBlock(options);
+  const blocked = protectedBaseWriteBlock(options, { requireBootstrap: false });
   if (blocked) {
     runDoctorInSandbox(options, blocked);
     return;
@@ -2093,7 +2563,8 @@ function doctor(rawArgs) {
   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(
@@ -2101,6 +2572,7 @@ function doctor(rawArgs) {
         {
           repoRoot: scanResult.repoRoot,
           branch: scanResult.branch,
+          safe,
           musafe,
           fix: {
             operations: fixPayload.operations,
@@ -2123,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);
@@ -2243,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` +
@@ -2256,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);