@imdeadpool/guardex 7.0.41 → 7.1.0

package/src/context.js

@@ -21,7 +21,14 @@ const GLOBAL_INSTALL_COMMAND = `npm i -g ${packageJson.name}`;
 const OPENSPEC_PACKAGE = '@fission-ai/openspec';
 const OMC_PACKAGE = 'oh-my-claude-sisyphus';
 const OMC_REPO_URL = 'https://github.com/Yeachan-Heo/oh-my-claudecode';
-const COLONY_PACKAGE = '@imdeadpool/colony-cli';
+// Colony was published under @imdeadpool/colony-cli historically; the new
+// canonical npm name is `colonyq`. The companion-install prompt that
+// gx status / gx setup show now reads `npm i -g colonyq`. Post-install
+// setup the user runs themselves (gitguardex only owns the `npm i -g` step):
+//   colony install --ide codex
+//   npx skills add recodeee/colony/skills/colony-mcp
+//   colony health
+const COLONY_PACKAGE = 'colonyq';
 const NPX_BIN = process.env.GUARDEX_NPX_BIN || 'npx';
 const GUARDEX_HOME_DIR = path.resolve(process.env.GUARDEX_HOME_DIR || os.homedir());
 const GLOBAL_TOOLCHAIN_SERVICES = [
@@ -61,14 +68,34 @@ const OPTIONAL_LOCAL_COMPANION_TOOLS = [
     installArgs: ['skills', 'add', 'JuliusBrussee/caveman'],
   },
 ];
-const GH_BIN = process.env.GUARDEX_GH_BIN || 'gh';
+function commandAvailable(command) {
+  const result = cp.spawnSync(command, ['--version'], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function resolveGithubCliBin(env = process.env) {
+  const explicit = String(env.GUARDEX_GH_BIN || '').trim();
+  if (explicit) {
+    return explicit;
+  }
+  return commandAvailable('ghx') ? 'ghx' : 'gh';
+}
+
+const GH_BIN = resolveGithubCliBin();
+const RTK_BIN = process.env.GUARDEX_RTK_BIN || 'rtk';
 const REQUIRED_SYSTEM_TOOLS = [
   {
     name: 'gh',
-    displayName: 'GitHub (gh)',
+    displayName: GH_BIN === 'ghx' ? 'GitHub (ghx proxy)' : 'GitHub (gh)',
     command: GH_BIN,
     installHint: 'https://cli.github.com/',
   },
+  {
+    name: 'rtk',
+    displayName: 'RTK (rtk)',
+    command: RTK_BIN,
+    installHint: 'Install RTK and ensure `rtk` is on PATH.',
+  },
 ];
 const MAINTAINER_RELEASE_REPO = path.resolve(
   process.env.GUARDEX_RELEASE_REPO || PACKAGE_ROOT,
@@ -111,51 +138,41 @@ function toDestinationPath(relativeTemplatePath) {
   if (relativeTemplatePath.startsWith('github/')) {
     return `.${relativeTemplatePath}`;
   }
-  if (relativeTemplatePath.startsWith('vscode/')) {
-    return relativeTemplatePath;
-  }
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 
+// scripts/ ↔ templates/scripts/ layout convention (single source of truth):
+//
+// 1. PAIRED files (10): tracked on both sides; scripts/<file> is a symlink
+//    to ../templates/scripts/<file> per PR #548. See
+//    scripts/check-script-symlinks.sh for the exact list. CI + the
+//    .githooks/pre-commit shim both enforce that no symlink is ever
+//    replaced with a regular file. Edit only the templates/scripts/ copy;
+//    the symlink propagates.
+//
+// 2. SCAFFOLD-ONLY files (the 3 below + workflows):
+//    tracked only under templates/; scaffolded into gitignored
+//    scripts/<file> (or .githooks/<file>, etc.) by `gx setup`. Consumer
+//    repos receive a regular file copy at the destination; gitguardex
+//    itself receives the same copy and ignores it via the
+//    multiagent-safety .gitignore block. Edit only the templates/ copy.
+//
+// If a file you're about to add fits pattern (1), also add it to
+// scripts/check-script-symlinks.sh's required_symlinks list. If it fits
+// pattern (2), append the destination path to .gitignore's multiagent-
+// safety block (auto-managed by syncManagedGitignoreLines below).
 const TEMPLATE_FILES = [
-  'scripts/agent-session-state.js',
+  'scripts/agent-preflight.sh',
   'scripts/guardex-docker-loader.sh',
   'scripts/guardex-env.sh',
-  'scripts/install-vscode-active-agents-extension.js',
   'github/pull.yml.example',
+  'github/workflows/ci.yml',
+  'github/workflows/ci-full.yml',
   'github/workflows/cr.yml',
-  'vscode/guardex-active-agents/package.json',
-  'vscode/guardex-active-agents/extension.js',
-  'vscode/guardex-active-agents/session-schema.js',
-  'vscode/guardex-active-agents/README.md',
-  'vscode/guardex-active-agents/icon.png',
-  'vscode/guardex-active-agents/fileicons/gitguardex-fileicons.json',
-  'vscode/guardex-active-agents/fileicons/icons/agent.svg',
-  'vscode/guardex-active-agents/fileicons/icons/branch.svg',
-  'vscode/guardex-active-agents/fileicons/icons/config.svg',
-  'vscode/guardex-active-agents/fileicons/icons/hook.svg',
-  'vscode/guardex-active-agents/fileicons/icons/openspec.svg',
-  'vscode/guardex-active-agents/fileicons/icons/plan.svg',
-  'vscode/guardex-active-agents/fileicons/icons/spec.svg',
+  'github/workflows/README.md',
 ];
 
-const PACKAGE_ROOT_SOURCE_OVERRIDES = new Set([
-  'scripts/agent-session-state.js',
-  'scripts/install-vscode-active-agents-extension.js',
-  'vscode/guardex-active-agents/package.json',
-  'vscode/guardex-active-agents/extension.js',
-  'vscode/guardex-active-agents/session-schema.js',
-  'vscode/guardex-active-agents/README.md',
-  'vscode/guardex-active-agents/icon.png',
-  'vscode/guardex-active-agents/fileicons/gitguardex-fileicons.json',
-  'vscode/guardex-active-agents/fileicons/icons/agent.svg',
-  'vscode/guardex-active-agents/fileicons/icons/branch.svg',
-  'vscode/guardex-active-agents/fileicons/icons/config.svg',
-  'vscode/guardex-active-agents/fileicons/icons/hook.svg',
-  'vscode/guardex-active-agents/fileicons/icons/openspec.svg',
-  'vscode/guardex-active-agents/fileicons/icons/plan.svg',
-  'vscode/guardex-active-agents/fileicons/icons/spec.svg',
-]);
+const PACKAGE_ROOT_SOURCE_OVERRIDES = new Set();
 
 const LEGACY_WORKFLOW_SHIM_SPECS = [
   { relativePath: 'scripts/agent-branch-start.sh', kind: 'shell', command: ['branch', 'start'] },
@@ -178,9 +195,7 @@ const MANAGED_TEMPLATE_SCRIPT_FILES = MANAGED_TEMPLATE_DESTINATIONS.filter((entr
 
 const LEGACY_MANAGED_REPO_FILES = [
   ...LEGACY_WORKFLOW_SHIMS,
-  'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',
-  'scripts/install-vscode-active-agents-extension.js',
   'scripts/guardex-env.sh',
   'scripts/install-agent-git-hooks.sh',
   '.githooks/pre-commit',
@@ -229,7 +244,6 @@ const PACKAGE_SCRIPT_ASSETS = {
   branchMerge: path.join(TEMPLATE_ROOT, 'scripts', 'agent-branch-merge.sh'),
   codexAgent: path.join(TEMPLATE_ROOT, 'scripts', 'codex-agent.sh'),
   reviewBot: path.join(TEMPLATE_ROOT, 'scripts', 'review-bot-watch.sh'),
-  sessionState: path.join(TEMPLATE_ROOT, 'scripts', 'agent-session-state.js'),
   worktreePrune: path.join(TEMPLATE_ROOT, 'scripts', 'agent-worktree-prune.sh'),
   lockTool: path.join(TEMPLATE_ROOT, 'scripts', 'agent-file-locks.py'),
   planInit: path.join(TEMPLATE_ROOT, 'scripts', 'openspec', 'init-plan-workspace.sh'),
@@ -266,6 +280,8 @@ const LOCK_FILE_RELATIVE = '.omx/state/agent-file-locks.json';
 const AGENTS_BOTS_STATE_RELATIVE = '.omx/state/agents-bots.json';
 const AGENTS_MARKER_START = '<!-- multiagent-safety:START -->';
 const AGENTS_MARKER_END = '<!-- multiagent-safety:END -->';
+const MONOREPO_MARKER_START = '<!-- monorepo-apps:START -->';
+const MONOREPO_MARKER_END = '<!-- monorepo-apps:END -->';
 const GITIGNORE_MARKER_START = '# multiagent-safety:START';
 const GITIGNORE_MARKER_END = '# multiagent-safety:END';
 const CODEX_WORKTREE_RELATIVE_DIR = path.join('.omx', 'agent-worktrees');
@@ -289,13 +305,12 @@ const MANAGED_REPO_SCAN_IGNORED_FOLDERS = [
 const MANAGED_GITIGNORE_PATHS = [
   '.omx/',
   '.omc/',
+  '.codex/',
   '!.vscode/',
   '.vscode/*',
   '!.vscode/settings.json',
-  'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',
   'scripts/guardex-env.sh',
-  'scripts/install-vscode-active-agents-extension.js',
   '.githooks',
   'oh-my-codex/',
   LOCK_FILE_RELATIVE,
@@ -345,6 +360,7 @@ const SUGGESTIBLE_COMMANDS = [
   'hook',
   'migrate',
   'install-agent-skills',
+  'cockpit',
   'agents',
   'merge',
   'finish',
@@ -364,6 +380,9 @@ const SUGGESTIBLE_COMMANDS = [
   'copy-commands',
   'print-agents-snippet',
   'release',
+  'budget',
+  'ci-init',
+  'speckit',
 ];
 // CLI_COMMAND_GROUPS is the grouped source of truth the `gx --help` /
 // `gx` no-args renderer uses. Each group is ordered roughly by how often a
@@ -409,7 +428,10 @@ const CLI_COMMAND_GROUPS = [
     description: 'Review / cleanup bots, AI setup prompts, and safety reports.',
     commands: [
       ['agents', 'Start/stop repo-scoped review + cleanup bots'],
+      ['pr-review', 'Run local Codex/Claude PR review and post inline GitHub comments or write an artifact'],
+      ['cockpit', 'Create or attach to a repo tmux cockpit session'],
       ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
+      ['speckit', 'Install Spec Kit (specify-cli) SDD slash skills (/speckit-specify, /speckit-plan, ...) into the current repo'],
       ['prompt', 'Print AI setup checklist or named slices (--exec, --part, --list-parts, --snippet)'],
       ['report', 'Security/safety reports (e.g. OpenSSF scorecard, session severity)'],
       ['release', 'Create or update the current GitHub release with README-generated notes'],
@@ -449,6 +471,9 @@ const DOCTOR_AUTO_FINISH_MESSAGE_MAX = 160;
 const AI_SETUP_PART_ALIASES = new Map([
   ['task', 'task-loop'],
   ['loop', 'task-loop'],
+  ['compact-commands', 'rtk'],
+  ['command-compression', 'rtk'],
+  ['token-commands', 'rtk'],
   ['reviewbot', 'review-bot'],
   ['forksync', 'fork-sync'],
 ]);
@@ -500,6 +525,18 @@ const AI_SETUP_PARTS = [
       'gx locks claim --branch "<agent-branch>" <file...>',
     ],
   },
+  {
+    name: 'rtk',
+    label: 'RTK command compression',
+    promptLines: [
+      'Prefer RTK wrappers for noisy shell discovery and verification when `rtk` is available; fall back to raw commands when missing.',
+      'Files: `rtk ls .`, `rtk read <file>`, `rtk read <file> -l aggressive`, `rtk smart <file>`, `rtk find "<glob>" .`, `rtk grep "<pattern>" .`, `rtk diff <a> <b>`.',
+      'Git/GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view <id>`.',
+      'Tests/build: `rtk test <cmd>`, `rtk err <cmd>`, `rtk jest`, `rtk vitest`, `rtk playwright test`, `rtk pytest`, `rtk cargo test`, `rtk tsc`, `rtk lint`.',
+      'Use `rtk gain`, `rtk discover`, and `rtk session` to audit savings; use `rtk proxy <command>` only when raw passthrough is required.',
+      'Do not wrap machine-readable commands with RTK when code parses stdout (`--porcelain`, `--json`, NUL-delimited output, or exact stdout contracts).',
+    ],
+  },
   {
     name: 'integrate',
     label: 'Integrate',
@@ -658,11 +695,232 @@ const SCORECARD_RISK_BY_CHECK = {
   License: 'Low',
 };
 
+// ---------------------------------------------------------------------------
+// Process-scoped memoization for idempotent git/gh probes.
+//
+// Many gx commands (notably `gx doctor`, `gx status`, preflight checks) ask
+// git/gh the same read-only questions multiple times within a single Node
+// process (current branch, remote URL, worktree list, config values, PR
+// state). spawnSync is cheap individually but adds up across 20+ probes.
+//
+// Rules:
+//   * Cache only idempotent reads. Strict allowlist below.
+//   * Never cache writes, network mutations, or anything passing stdin.
+//   * Lifetime = this Node process only (no disk cache, no TTL beyond the
+//     process). A fresh `gx ...` invocation always starts cold.
+//   * Honors GUARDEX_PROBE_TRACE=1 to print `[probe]` / `[probe-hit]` lines
+//     on stderr so duplicate calls are observable.
+//   * Honors GUARDEX_PROBE_CACHE=0 to disable the cache entirely
+//     (escape hatch).
+// ---------------------------------------------------------------------------
+
+const PROBE_CACHE = new Map();
+const PROBE_TRACE_ENABLED = (() => {
+  const raw = String(process.env.GUARDEX_PROBE_TRACE || '').trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+})();
+const PROBE_CACHE_DISABLED = (() => {
+  const raw = String(process.env.GUARDEX_PROBE_CACHE || '').trim().toLowerCase();
+  return raw === '0' || raw === 'false' || raw === 'no' || raw === 'off';
+})();
+
+// Env vars that, if they differ between calls, must invalidate cache (because
+// they change git/gh's actual answer). Most env doesn't matter for read probes
+// so we deliberately key only on a small slice to keep cache hits high.
+const PROBE_CACHE_ENV_KEYS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_COMMON_DIR',
+  'GIT_INDEX_FILE',
+  'GITHUB_TOKEN',
+  'GH_TOKEN',
+  'GH_HOST',
+];
+
+function envSubsetKey(envOverride) {
+  const env = envOverride || process.env;
+  const parts = [];
+  for (const key of PROBE_CACHE_ENV_KEYS) {
+    if (env[key] !== undefined) parts.push(`${key}=${env[key]}`);
+  }
+  return parts.join('');
+}
+
+// Strip a leading `-C <path>` (or `-c key=value`) pair from git args so we
+// look at the real verb after global options.
+function gitVerbAndRest(args) {
+  if (!Array.isArray(args) || args.length === 0) return { verb: '', rest: [] };
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === '-C' && i + 1 < args.length) {
+      i += 2;
+      continue;
+    }
+    if (a === '-c' && i + 1 < args.length) {
+      i += 2;
+      continue;
+    }
+    if (typeof a === 'string' && a.startsWith('-c') && a !== '-c') {
+      i += 1;
+      continue;
+    }
+    break;
+  }
+  return { verb: args[i] || '', rest: args.slice(i + 1) };
+}
+
+// A git command is cacheable only if its answer is invariant for the lifetime
+// of the process under our own commands' behavior. Many git "reads"
+// (`status`, `diff`, `for-each-ref`, `rev-list`, `ls-files`, `worktree list`,
+// `branch --show-current`, `merge-base --is-ancestor`) can change mid-run
+// because gx itself writes (commits, branch ops, worktree add/remove, config
+// writes). Caching those would feed callers stale answers and break command
+// flows. The narrow allowlist below intentionally covers only:
+//   * filesystem geometry that git itself treats as fixed for a given repo
+//     checkout (`rev-parse --show-toplevel|--git-common-dir|--git-dir|
+//     --show-cdup|--show-superproject-working-tree|--is-inside-work-tree|
+//     --is-bare-repository`)
+//   * tool version banners (`--version`)
+// Everything else falls through to a real spawn each time.
+function gitIsCacheableRead(args) {
+  const { verb, rest } = gitVerbAndRest(args);
+  if (!verb) return false;
+
+  if (verb === '--version' || verb === 'version') return true;
+
+  if (verb === 'rev-parse') {
+    // Allow ONLY the geometry-probe forms whose answer never depends on the
+    // working-tree, ref state, or config. Concrete ref resolution
+    // (`rev-parse HEAD`, `rev-parse --verify <ref>`) is intentionally NOT
+    // cached because gx writes refs.
+    for (const a of rest) {
+      if (typeof a !== 'string') continue;
+      if (a.startsWith('-')) {
+        if (
+          a === '--show-toplevel' ||
+          a === '--git-common-dir' ||
+          a === '--git-dir' ||
+          a === '--show-cdup' ||
+          a === '--show-superproject-working-tree' ||
+          a === '--is-inside-work-tree' ||
+          a === '--is-inside-git-dir' ||
+          a === '--is-bare-repository' ||
+          a === '--show-prefix'
+        ) {
+          // continue scanning to make sure no ref-probe is also present
+          continue;
+        }
+        // Any other flag (--verify, --short, --abbrev-ref, etc.) means we're
+        // resolving a ref, which is mutable.
+        return false;
+      }
+      // Bare positional (e.g. a ref name) -> ref resolution, mutable.
+      return false;
+    }
+    return rest.length > 0;
+  }
+  return false;
+}
+
+// gh probes that ARE safe to cache within a single process: only the version
+// banner. Auth state can change (login/logout in another shell), PR state
+// can change (a merge can land mid-poll). The instruction's allowlist
+// included `gh auth status`, `gh api -X GET`, `gh pr view --json`, etc.;
+// those are read-only from gh's side but their underlying truth shifts under
+// gx's own writes (`gh pr create`, `gh pr merge`, `gh auth refresh`, server
+// state). Within a single doctor sweep we explicitly want to re-query auth
+// and PR state, so caching them would mask freshly-changed reality.
+function ghIsCacheableRead(args) {
+  if (!Array.isArray(args) || args.length === 0) return false;
+  const verb = args[0] || '';
+  if (verb === '--version' || verb === 'version') return true;
+  return false;
+}
+
+function isCacheableSpawn(cmd, args, options) {
+  if (PROBE_CACHE_DISABLED) return false;
+  if (!cmd || typeof cmd !== 'string') return false;
+  if (options && options.input !== undefined && options.input !== null) return false;
+  // Pass-through if stdio is anything other than fully pipe/ignore (callers
+  // that inherit stdio need the real child to print, not a cached payload).
+  if (options && options.stdio && options.stdio !== 'pipe' && options.stdio !== 'ignore') {
+    if (Array.isArray(options.stdio)) {
+      for (const leg of options.stdio) {
+        if (leg && leg !== 'pipe' && leg !== 'ignore' && leg !== null) return false;
+      }
+    } else {
+      return false;
+    }
+  }
+  const base = path.basename(cmd);
+  if (base === 'git') return gitIsCacheableRead(args || []);
+  if (base === 'gh' || base === 'ghx') return ghIsCacheableRead(args || []);
+  if (base === 'which' || base === 'command' || base === 'type') {
+    return Array.isArray(args) && args.length >= 1;
+  }
+  return false;
+}
+
+function probeTrace(prefix, cmd, args) {
+  if (!PROBE_TRACE_ENABLED) return;
+  try {
+    process.stderr.write(`[${prefix}] ${cmd} ${(args || []).join(' ')}\n`);
+  } catch {
+    // Tracing must never break the probe.
+  }
+}
+
+function cachedSpawn(cmd, args, options) {
+  const cacheable = isCacheableSpawn(cmd, args, options);
+  if (!cacheable) {
+    probeTrace('probe', cmd, args);
+    return cp.spawnSync(cmd, args, options);
+  }
+  const cwdKey = (options && options.cwd) || process.cwd();
+  const envKey = options && options.env
+    ? envSubsetKey({ ...process.env, ...options.env })
+    : envSubsetKey(process.env);
+  const key = `${cmd} ${JSON.stringify(args || [])} ${cwdKey} ${envKey}`;
+  const cached = PROBE_CACHE.get(key);
+  if (cached) {
+    probeTrace('probe-hit', cmd, args);
+    // Clone so callers that mutate the result don't poison the cache.
+    return {
+      pid: cached.pid,
+      status: cached.status,
+      signal: cached.signal,
+      stdout: cached.stdout,
+      stderr: cached.stderr,
+      output: cached.output ? cached.output.slice() : cached.output,
+      error: cached.error,
+    };
+  }
+  probeTrace('probe', cmd, args);
+  const result = cp.spawnSync(cmd, args, options);
+  // Don't cache spawn errors (ENOENT etc.) — they may resolve on retry with a
+  // different binary path.
+  if (result && result.error) {
+    return result;
+  }
+  PROBE_CACHE.set(key, {
+    pid: result && result.pid,
+    status: result && result.status,
+    signal: result && result.signal,
+    stdout: result && result.stdout,
+    stderr: result && result.stderr,
+    output: result && result.output,
+    error: result && result.error,
+  });
+  return result;
+}
+
 module.exports = {
   fs,
   os,
   path,
   cp,
+  cachedSpawn,
   PACKAGE_ROOT,
   CLI_ENTRY_PATH,
   packageJsonPath,
@@ -680,6 +938,7 @@ module.exports = {
   GLOBAL_TOOLCHAIN_SERVICES,
   GLOBAL_TOOLCHAIN_PACKAGES,
   OPTIONAL_LOCAL_COMPANION_TOOLS,
+  resolveGithubCliBin,
   GH_BIN,
   REQUIRED_SYSTEM_TOOLS,
   MAINTAINER_RELEASE_REPO,
@@ -715,6 +974,8 @@ module.exports = {
   AGENTS_BOTS_STATE_RELATIVE,
   AGENTS_MARKER_START,
   AGENTS_MARKER_END,
+  MONOREPO_MARKER_START,
+  MONOREPO_MARKER_END,
   GITIGNORE_MARKER_START,
   GITIGNORE_MARKER_END,
   CODEX_WORKTREE_RELATIVE_DIR,

package/src/core/runtime.js

@@ -1,6 +1,7 @@
 const {
   fs,
   path,
+  cachedSpawn,
   CLI_ENTRY_PATH,
   PACKAGE_SCRIPT_ASSETS,
 } = require('../context');
@@ -13,8 +14,12 @@ function requireValue(rawArgs, index, flagName) {
   return value;
 }
 
+// Route reads through the process-scoped probe cache. cachedSpawn caches ONLY a
+// strict allowlist (git geometry probes, git/gh `--version`, `which`) and falls
+// through to a real spawn for everything else — writes, ref resolution, npm,
+// gh auth/pr — so observable behavior is unchanged, only redundant probes drop.
 function run(cmd, args, options = {}) {
-  return require('node:child_process').spawnSync(cmd, args, {
+  return cachedSpawn(cmd, args, {
     encoding: 'utf8',
     stdio: options.stdio || 'pipe',
     cwd: options.cwd,

package/src/doctor/index.js

@@ -1,8 +1,10 @@
 const {
   fs,
   path,
+  cachedSpawn,
   TOOL_NAME,
   SHORT_TOOL_NAME,
+  GH_BIN,
   LOCK_FILE_RELATIVE,
   REQUIRED_MANAGED_REPO_FILES,
   OMX_SCAFFOLD_DIRECTORIES,
@@ -10,7 +12,23 @@ const {
   AGENT_WORKTREE_RELATIVE_DIRS,
   defaultAgentWorktreeRelativeDir,
 } = require('../context');
-const { run, runPackageAsset } = require('../core/runtime');
+const { runPackageAsset } = require('../core/runtime');
+
+// Route doctor probe-running calls through the process-scoped probe cache.
+// cachedSpawn falls through to cp.spawnSync for any non-allowlisted call
+// (git commit/push/stash/checkout, gh auth login, etc.), so writes are never
+// cached. Doctor fires the same read questions many times within one run
+// (current branch, remote URL, worktree list, gh auth status) — caching
+// those is a pure perf win.
+function run(cmd, args, options = {}) {
+  return cachedSpawn(cmd, args, {
+    encoding: 'utf8',
+    stdio: options.stdio || 'pipe',
+    cwd: options.cwd,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    timeout: options.timeout,
+  });
+}
 const {
   currentBranchName,
   gitRefExists,
@@ -30,7 +48,7 @@ const {
   cleanupProtectedBaseSandbox,
 } = require('../sandbox');
 const { ensureOmxScaffold, configureHooks } = require('../scaffold');
-const { detectRecoverableAutoFinishConflict, printAutoFinishSummary } = require('../output');
+const { detectRecoverableAutoFinishConflict, printAutoFinishSummary, isTerseMode } = require('../output');
 const { autoCommitWorktreeForFinish } = require('../finish');
 
 /**
@@ -100,6 +118,7 @@ function buildSandboxDoctorArgs(options, sandboxTarget) {
   if (options.skipAgents) args.push('--skip-agents');
   if (options.skipPackageJson) args.push('--skip-package-json');
   if (options.skipGitignore) args.push('--no-gitignore');
+  if (options.contract) args.push('--contract');
   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');
@@ -442,7 +461,7 @@ function finishDoctorSandboxBranch(blocked, metadata, options = {}) {
     };
   }
 
-  const ghBin = process.env.GUARDEX_GH_BIN || 'gh';
+  const ghBin = GH_BIN;
   if (!isCommandAvailable(ghBin)) {
     return {
       status: 'skipped',
@@ -890,7 +909,7 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
 
   const originAvailable = hasOriginRemote(repoRoot);
   const explicitGhBin = Boolean(String(process.env.GUARDEX_GH_BIN || '').trim());
-  const ghBin = process.env.GUARDEX_GH_BIN || 'gh';
+  const ghBin = GH_BIN;
   const ghAvailable =
     originAvailable &&
     (explicitGhBin || originRemoteLooksLikeGithub(repoRoot)) &&
@@ -1151,6 +1170,7 @@ function emitDoctorSandboxJsonOutput(nestedResult, execution) {
 }
 
 function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult, nestedResult, execution) {
+  const terse = isTerseMode();
   console.log(
     `[${TOOL_NAME}] doctor detected protected branch '${blocked.branch}'. ` +
     `Running repairs in sandbox branch '${metadata.branch || 'agent/<auto>'}'.`,
@@ -1163,6 +1183,10 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
     return;
   }
 
+  // Terse mode: drop "[OK] X skipped because of Y" / "already in sync"
+  // confirmations. Keep committed/failed/pending/merged states verbose so
+  // operators still see action-required hints, PR URLs, branch names, and
+  // file paths.
   if (execution.autoCommit.status === 'committed') {
     console.log(
       `[${TOOL_NAME}] Auto-committed doctor repairs in sandbox branch '${metadata.branch}'.`,
@@ -1171,22 +1195,24 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
     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 {
+  } else if (!terse) {
     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}.`);
+  } else if (!terse) {
+    if (execution.protectedBaseRepairSync.status === 'unchanged') {
+      console.log(`[${TOOL_NAME}] Protected branch workspace already had the tracked doctor repairs.`);
+    } else {
+      console.log(`[${TOOL_NAME}] Protected branch tracked repair merge skipped: ${execution.protectedBaseRepairSync.note}.`);
+    }
   }
 
   if (execution.lockSync.status === 'synced') {
@@ -1194,8 +1220,10 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
       `[${TOOL_NAME}] Synced repaired lock registry back to protected branch workspace (${LOCK_FILE_RELATIVE}).`,
     );
   } else if (execution.lockSync.status === 'unchanged') {
+    // Kept verbose in terse mode too: downstream consumers (and tests) rely
+    // on seeing the lock-registry sync stage reach a terminal state line.
     console.log(`[${TOOL_NAME}] Lock registry already synced in protected branch workspace.`);
-  } else {
+  } else if (!terse) {
     console.log(`[${TOOL_NAME}] Lock registry sync skipped: ${execution.lockSync.note}.`);
   }
 
@@ -1216,7 +1244,7 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
     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 {
+  } else if (!terse) {
     console.log(`[${TOOL_NAME}] Auto-finish skipped: ${execution.finish.note}.`);
   }
 
@@ -1226,12 +1254,14 @@ function emitDoctorSandboxConsoleOutput(options, blocked, metadata, startResult,
   });
   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}.`);
+  } else if (!terse) {
+    if (execution.omxScaffoldSync.status === 'unchanged') {
+      console.log(`[${TOOL_NAME}] .omx scaffold already aligned in protected branch workspace.`);
+    } else {
+      console.log(`[${TOOL_NAME}] .omx scaffold sync skipped: ${execution.omxScaffoldSync.note}.`);
+    }
   }
 }