@imdeadpool/guardex 7.0.11 → 7.0.13

package/README.md

@@ -1,7 +1,13 @@
 # GitGuardex — Guardian T-Rex for your repo
 
-[![npm version](https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?color=cb3837&logo=npm)](https://www.npmjs.com/package/@imdeadpool/guardex)
-[![CI](https://github.com/recodeee/gitguardex/actions/workflows/ci.yml/badge.svg)](https://github.com/recodeee/gitguardex/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@imdeadpool/guardex)
+[![npm downloads](https://img.shields.io/npm/dm/%40imdeadpool%2Fguardex?label=downloads&color=0b76c5)](https://www.npmjs.com/package/@imdeadpool/guardex)
+[![GitHub stars](https://img.shields.io/github/stars/recodeee/gitguardex?label=stars&color=d4ac0d)](https://github.com/recodeee/gitguardex/stargazers)
+[![License](https://img.shields.io/npm/l/%40imdeadpool%2Fguardex?label=License&color=97ca00)](./LICENSE)
+
+[![CI](https://img.shields.io/github/actions/workflow/status/recodeee/gitguardex/ci.yml?branch=main&label=CI)](https://github.com/recodeee/gitguardex/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/actions/workflow/status/recodeee/gitguardex/release.yml?label=Release)](https://github.com/recodeee/gitguardex/actions/workflows/release.yml)
+[![CodeQL](https://img.shields.io/github/actions/workflow/status/recodeee/gitguardex/codeql.yml?branch=main&label=CodeQL)](https://github.com/recodeee/gitguardex/actions/workflows/codeql.yml)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/recodeee/gitguardex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/recodeee/gitguardex)
 
 **GitGuardex is a safety layer for parallel agent work in git repos.** If you're running more than one Codex or Claude agent on the same codebase, this is what keeps them from deleting each other's work.
@@ -20,24 +26,28 @@ I was running ~30 Codex agents in parallel and hit a wall: they kept working on
 
 GitGuardex exists to stop that loop. Every agent gets its own worktree, claims the files it's touching, and can't clobber files another agent has claimed. Your local branch stays clean; agents stay in their lanes.
 
-![Multi-agent dashboard example](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/dashboard-multi-agent.png)
-
-Coming soon: [recodee.com](https://recodee.com) — live account health, usage, routing, and capacity in one place.
+### Solution
 
 ```mermaid
 flowchart LR
-    A[Agent A edits shared files] --> S[Same target surface]
-    B[Agent B edits shared files] --> S
-    C[Agent C edits shared files] --> S
-    D[Agent D edits shared files] --> S
-    E[Agent E edits shared files] --> S
-    S --> F[Conflict / overwrite churn]
-    F --> G[Deleted or lost code]
-    G --> H[Rework and confusion]
-    H --> I[Regression risk grows]
-    I --> F
+    A[Agent A adds assertions in a shared test] --> S[Several agents touch the same files]
+    B[Agent B rewrites the same test flow] --> S
+    C[Agent C updates the shared helper] --> S
+    D[Agent D deletes lines Agent A just added] --> S
+    E[Agent E saves an older snapshot of the file] --> S
+    S --> F[One agent overwrites another agent's edits]
+    F --> G[Another agent deletes code the others just added]
+    G --> H[Lost work, rework, and review confusion]
+    H --> I[Regression risk and flaky fixes grow]
+    I --> S
 ```
 
+### Dashboard
+
+![Multi-agent dashboard example](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/dashboard-multi-agent.png)
+
+Coming soon: [recodee.com](https://recodee.com) — live account health, usage, routing, and capacity in one place.
+
 ---
 
 ## What it does
@@ -122,7 +132,7 @@ gx finish --all
 
 This is the real Source Control shape Guardex is aiming for: isolated agent branches, clear OpenSpec artifacts, and no pile-up on one shared checkout.
 
-![Exact VS Code Source Control workflow screenshot](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/workflow-vscode-source-control-exact.png)
+![Guarded VS Code Source Control example](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/workflow-source-control-grouped.png)
 
 ---
 
@@ -237,7 +247,7 @@ A few things worth knowing up front:
 
 - Running `gx` with no command opens the status/health view.
 - `gx init` is just an alias for `gx setup`.
-- Setup/doctor can install missing global companion CLIs (OMC runtime, OpenSpec, cavemem, codex-auth) — but only with explicit Y/N confirmation.
+- Setup/doctor can install missing companion tooling (OMC runtime, OpenSpec, cavemem, codex-auth, caveman, cavekit) — but only with explicit Y/N confirmation.
 - Direct commits/pushes to protected branches are **blocked** by default. Agents must use the `agent/*` + PR flow.
 - **Exception:** VS Code Source Control commits are allowed on protected branches that exist only locally (no upstream, no remote branch).
 - On protected `main`, `gx doctor` auto-runs in a sandbox agent branch/worktree so it can't touch your real main.
@@ -255,13 +265,15 @@ git config multiagent.allowVscodeProtectedBranchWrites true
 
 ## Companion tools
 
-GitGuardex is designed to work alongside these. All optional — but if you're running many agents, you probably want them. `gx status` reports the machine-detectable global helpers; plugin/skills-first add-ons like `caveman` and `cavekit` are documented below for manual setup.
+GitGuardex is designed to work alongside these. All optional — but if you're running many agents, you probably want them. `gx status` reports the machine-detectable companion helpers, including local `caveman` / `cavekit` installs when their home-directory footprints are present.
 
 ```text
 ● oh-my-codex: active
 ● oh-my-claude-sisyphus: active
 ● @fission-ai/openspec: active
 ● cavemem: active
+● cavekit: active
+● caveman: active
 ● @imdeadpool/codex-account-switcher: active
 ● gh: active
 ```
@@ -275,6 +287,7 @@ npm i -g oh-my-codex
 ```
 
 Repo: <https://github.com/Yeachan-Heo/oh-my-codex>
+[![GitHub stars](https://img.shields.io/github/stars/Yeachan-Heo/oh-my-codex?style=social)](https://github.com/Yeachan-Heo/oh-my-codex)
 
 ### oh-my-claudecode — Claude Code equivalent
 
@@ -285,6 +298,7 @@ npm i -g oh-my-claude-sisyphus@latest
 ```
 
 Repo: <https://github.com/Yeachan-Heo/oh-my-claudecode>
+[![GitHub stars](https://img.shields.io/github/stars/Yeachan-Heo/oh-my-claudecode?style=social)](https://github.com/Yeachan-Heo/oh-my-claudecode)
 
 ### Caveman — output compression for long agent runs
 
@@ -295,6 +309,7 @@ npx skills add JuliusBrussee/caveman
 ```
 
 Repo: <https://github.com/JuliusBrussee/caveman>
+[![GitHub stars](https://img.shields.io/github/stars/JuliusBrussee/caveman?style=social)](https://github.com/JuliusBrussee/caveman)
 
 ### Cavemem — local persistent memory for agents
 
@@ -307,6 +322,7 @@ cavemem status
 ```
 
 Repo: <https://github.com/JuliusBrussee/cavemem>
+[![GitHub stars](https://img.shields.io/github/stars/JuliusBrussee/cavemem?style=social)](https://github.com/JuliusBrussee/cavemem)
 
 ### Cavekit — spec-driven build loop
 
@@ -317,6 +333,7 @@ npx skills add JuliusBrussee/cavekit
 ```
 
 Repo: <https://github.com/JuliusBrussee/cavekit>
+[![GitHub stars](https://img.shields.io/github/stars/JuliusBrussee/cavekit?style=social)](https://github.com/JuliusBrussee/cavekit)
 
 ### OpenSpec — spec-driven workflows
 
@@ -327,6 +344,7 @@ npm i -g @fission-ai/openspec
 ```
 
 Repo: <https://github.com/Fission-AI/OpenSpec>
+[![GitHub stars](https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=social)](https://github.com/Fission-AI/OpenSpec)
 
 ### codex-auth — multi-account switcher
 
@@ -342,6 +360,7 @@ codex-auth current
 ```
 
 Repo: [recodeecom/codex-account-switcher-cli](https://github.com/recodeecom/codex-account-switcher-cli)
+[![GitHub stars](https://img.shields.io/github/stars/recodeecom/codex-account-switcher-cli?style=social)](https://github.com/recodeecom/codex-account-switcher-cli)
 
 ### GitHub CLI (`gh`)
 
@@ -488,6 +507,16 @@ npm pack --dry-run
 <details>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.13
+- `gx status` and `gx setup` now present the Claude companion as `oh-my-claudecode` while still installing the published npm package `oh-my-claude-sisyphus`.
+- When that dependency is inactive or the user declines the optional install, Guardex now prints the upstream repo URL so the missing dependency is explicit instead of hidden behind the npm package name.
+- Bumped `@imdeadpool/guardex` from `7.0.12` → `7.0.13` after npm rejected a republish over the already-published `7.0.12`.
+
+### v7.0.12
+- Fixed the self-update handoff after `gx` installs a newer global package. When the on-disk install advances, GitGuardex now restarts into the installed CLI instead of continuing in the old process and printing the stale in-memory version.
+- This removes the confusing `Updated to latest published version` followed by `CLI: ...7.0.10` mismatch that happened when `7.0.11` finished installing during the same `gx` invocation.
+- Bumped `@imdeadpool/guardex` from `7.0.11` → `7.0.12`.
+
 ### v7.0.11
 - Fixed the npm release workflow trigger so publishes run from `release.published` or explicit manual dispatch, instead of double-firing on both the tag push and the release event.
 - This keeps the GitHub `npm` environment from collecting duplicate cancelled deploy cards for the same version and leaves one canonical release deployment to monitor.

package/bin/multiagent-safety.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const cp = require('node:child_process');
 
@@ -12,13 +13,46 @@ const SHORT_TOOL_NAME = 'gx';
 const LEGACY_NAMES = ['guardex', 'multiagent-safety'];
 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 CAVEMEM_PACKAGE = 'cavemem';
+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 = [
+  { name: 'oh-my-codex', packageName: 'oh-my-codex' },
+  {
+    name: 'oh-my-claudecode',
+    packageName: OMC_PACKAGE,
+    dependencyUrl: OMC_REPO_URL,
+  },
+  { name: OPENSPEC_PACKAGE, packageName: OPENSPEC_PACKAGE },
+  { name: CAVEMEM_PACKAGE, packageName: CAVEMEM_PACKAGE },
+  {
+    name: '@imdeadpool/codex-account-switcher',
+    packageName: '@imdeadpool/codex-account-switcher',
+  },
+];
 const GLOBAL_TOOLCHAIN_PACKAGES = [
-  'oh-my-codex',
-  OMC_PACKAGE,
-  OPENSPEC_PACKAGE,
-  CAVEMEM_PACKAGE,
-  '@imdeadpool/codex-account-switcher',
+  ...GLOBAL_TOOLCHAIN_SERVICES.map((service) => service.packageName),
+];
+const OPTIONAL_LOCAL_COMPANION_TOOLS = [
+  {
+    name: 'cavekit',
+    candidatePaths: [
+      '.cavekit/plugin.json',
+      '.codex/local-marketplaces/cavekit/.agents/plugins/marketplace.json',
+    ],
+    installCommand: `${NPX_BIN} skills add JuliusBrussee/cavekit`,
+    installArgs: ['skills', 'add', 'JuliusBrussee/cavekit'],
+  },
+  {
+    name: 'caveman',
+    candidatePaths: [
+      '.config/caveman/config.json',
+      '.cavekit/skills/caveman/SKILL.md',
+    ],
+    installCommand: `${NPX_BIN} skills add JuliusBrussee/caveman`,
+    installArgs: ['skills', 'add', 'JuliusBrussee/caveman'],
+  },
 ];
 const GH_BIN = process.env.GUARDEX_GH_BIN || 'gh';
 const REQUIRED_SYSTEM_TOOLS = [
@@ -3393,9 +3427,15 @@ function maybeSelfUpdateBeforeStatus() {
   }
 
   console.log(`[${TOOL_NAME}] ✅ Updated to latest published version.`);
+  restartIntoUpdatedGuardex(check.latest);
 }
 
 function readInstalledGuardexVersion() {
+  const installInfo = readInstalledGuardexInstallInfo();
+  return installInfo ? installInfo.version : null;
+}
+
+function readInstalledGuardexInstallInfo() {
   // Resolves the globally-installed package's on-disk version so we can
   // verify npm actually wrote new bytes. Uses `npm root -g` to locate the
   // global install root so we don't accidentally read the running source
@@ -3417,7 +3457,24 @@ function readInstalledGuardexVersion() {
     }
     const parsed = JSON.parse(fs.readFileSync(installedPkgPath, 'utf8'));
     if (parsed && typeof parsed.version === 'string') {
-      return parsed.version;
+      let binRelative = null;
+      if (typeof parsed.bin === 'string') {
+        binRelative = parsed.bin;
+      } else if (parsed.bin && typeof parsed.bin === 'object') {
+        const invokedName = path.basename(process.argv[1] || '');
+        binRelative =
+          parsed.bin[invokedName] ||
+          parsed.bin[SHORT_TOOL_NAME] ||
+          Object.values(parsed.bin).find((value) => typeof value === 'string') ||
+          null;
+      }
+      const packageRoot = path.dirname(installedPkgPath);
+      const binPath = binRelative ? path.join(packageRoot, binRelative) : null;
+      return {
+        version: parsed.version,
+        packageRoot,
+        binPath,
+      };
     }
   } catch (error) {
     return null;
@@ -3425,6 +3482,38 @@ function readInstalledGuardexVersion() {
   return null;
 }
 
+function restartIntoUpdatedGuardex(expectedVersion) {
+  const installInfo = readInstalledGuardexInstallInfo();
+  if (!installInfo || installInfo.version !== expectedVersion || installInfo.version === packageJson.version) {
+    return;
+  }
+  if (!installInfo.binPath || !fs.existsSync(installInfo.binPath)) {
+    console.log(`[${TOOL_NAME}] Restart required to use ${installInfo.version}. Rerun ${SHORT_TOOL_NAME}.`);
+    return;
+  }
+
+  console.log(`[${TOOL_NAME}] Restarting into ${installInfo.version}…`);
+  const restartResult = cp.spawnSync(
+    process.execPath,
+    [installInfo.binPath, ...process.argv.slice(2)],
+    {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        GUARDEX_SKIP_UPDATE_CHECK: '1',
+      },
+      stdio: 'inherit',
+    },
+  );
+  if (restartResult.error) {
+    console.log(
+      `[${TOOL_NAME}] Restart into ${installInfo.version} failed. Rerun ${SHORT_TOOL_NAME}.`,
+    );
+    return;
+  }
+  process.exit(restartResult.status == null ? 0 : restartResult.status);
+}
+
 function checkForOpenSpecPackageUpdate() {
   if (envFlagEnabled('GUARDEX_SKIP_OPENSPEC_UPDATE_CHECK')) {
     return { checked: false, reason: 'disabled' };
@@ -3551,6 +3640,36 @@ function resolveGlobalInstallApproval(options) {
   return { approved: true, source: 'prompt' };
 }
 
+function getGlobalToolchainService(packageName) {
+  const service = GLOBAL_TOOLCHAIN_SERVICES.find(
+    (candidate) => candidate.packageName === packageName,
+  );
+  return service || { name: packageName, packageName };
+}
+
+function formatGlobalToolchainServiceName(packageName) {
+  return getGlobalToolchainService(packageName).name;
+}
+
+function describeMissingGlobalDependencyWarnings(packageNames) {
+  return packageNames
+    .map((packageName) => getGlobalToolchainService(packageName))
+    .filter((service) => service.dependencyUrl)
+    .map(
+      (service) =>
+        `Guardex needs ${service.name} as a dependency: ${service.dependencyUrl}`,
+    );
+}
+
+function buildMissingCompanionInstallPrompt(missingPackages, missingLocalTools) {
+  const dependencyWarnings = describeMissingGlobalDependencyWarnings(missingPackages);
+  const installCommands = describeCompanionInstallCommands(missingPackages, missingLocalTools);
+  const dependencyPrefix = dependencyWarnings.length > 0
+    ? `${dependencyWarnings.join(' ')} `
+    : '';
+  return `${dependencyPrefix}Install missing companion tools now? (${installCommands.join(' && ')})`;
+}
+
 function detectGlobalToolchainPackages() {
   const result = run(NPM_BIN, ['list', '-g', '--depth=0', '--json']);
   if (result.status !== 0) {
@@ -3616,7 +3735,34 @@ function detectRequiredSystemTools() {
   return services;
 }
 
-function askGlobalInstallForMissing(options, missingPackages) {
+function detectOptionalLocalCompanionTools() {
+  return OPTIONAL_LOCAL_COMPANION_TOOLS.map((tool) => {
+    const detectedPath = tool.candidatePaths
+      .map((relativePath) => path.join(GUARDEX_HOME_DIR, relativePath))
+      .find((candidatePath) => fs.existsSync(candidatePath));
+    return {
+      name: tool.name,
+      displayName: tool.displayName || tool.name,
+      installCommand: tool.installCommand,
+      installArgs: [...tool.installArgs],
+      status: detectedPath ? 'active' : 'inactive',
+      detectedPath: detectedPath || null,
+    };
+  });
+}
+
+function describeCompanionInstallCommands(missingPackages, missingLocalTools) {
+  const commands = [];
+  if (missingPackages.length > 0) {
+    commands.push(`${NPM_BIN} i -g ${missingPackages.join(' ')}`);
+  }
+  for (const tool of missingLocalTools) {
+    commands.push(tool.installCommand);
+  }
+  return commands;
+}
+
+function askGlobalInstallForMissing(options, missingPackages, missingLocalTools) {
   const approval = resolveGlobalInstallApproval(options);
   if (!approval.approved) {
     return approval;
@@ -3624,7 +3770,7 @@ function askGlobalInstallForMissing(options, missingPackages) {
 
   if (approval.source === 'prompt') {
     const approved = promptYesNoStrict(
-      `Install missing global tools now? (npm i -g ${missingPackages.join(' ')})`,
+      buildMissingCompanionInstallPrompt(missingPackages, missingLocalTools),
     );
     return { approved, source: 'prompt' };
   }
@@ -3638,36 +3784,69 @@ function installGlobalToolchain(options) {
   }
 
   const detection = detectGlobalToolchainPackages();
+  const localCompanionTools = detectOptionalLocalCompanionTools();
   if (!detection.ok) {
     console.log(`[${TOOL_NAME}] ⚠️ Could not detect global packages: ${detection.error}`);
   } else {
     if (detection.installed.length > 0) {
-      console.log(`[${TOOL_NAME}] Already installed globally: ${detection.installed.join(', ')}`);
+      console.log(
+        `[${TOOL_NAME}] Already installed globally: ` +
+        `${detection.installed.map((pkg) => formatGlobalToolchainServiceName(pkg)).join(', ')}`,
+      );
+    }
+    const installedLocalTools = localCompanionTools
+      .filter((tool) => tool.status === 'active')
+      .map((tool) => tool.name);
+    if (installedLocalTools.length > 0) {
+      console.log(`[${TOOL_NAME}] Already installed locally: ${installedLocalTools.join(', ')}`);
     }
-    if (detection.missing.length === 0) {
+    if (detection.missing.length === 0 && localCompanionTools.every((tool) => tool.status === 'active')) {
       return { status: 'already-installed' };
     }
   }
 
   const missingPackages = detection.ok ? detection.missing : [...GLOBAL_TOOLCHAIN_PACKAGES];
-  const approval = askGlobalInstallForMissing(options, missingPackages);
+  const missingLocalTools = localCompanionTools.filter((tool) => tool.status !== 'active');
+  const approval = askGlobalInstallForMissing(options, missingPackages, missingLocalTools);
   if (!approval.approved) {
-    return { status: 'skipped', reason: approval.source };
-  }
-
-  console.log(
-    `[${TOOL_NAME}] Installing global toolchain: npm i -g ${missingPackages.join(' ')}`,
-  );
-  const result = run(NPM_BIN, ['i', '-g', ...missingPackages], { stdio: 'inherit' });
-  if (result.status !== 0) {
-    const stderr = (result.stderr || '').trim();
     return {
-      status: 'failed',
-      reason: stderr || 'npm global install failed',
+      status: 'skipped',
+      reason: approval.source,
+      missingPackages,
+      missingLocalTools,
     };
   }
 
-  return { status: 'installed', packages: missingPackages };
+  const installed = [];
+  if (missingPackages.length > 0) {
+    console.log(
+      `[${TOOL_NAME}] Installing global toolchain: npm i -g ${missingPackages.join(' ')}`,
+    );
+    const result = run(NPM_BIN, ['i', '-g', ...missingPackages], { stdio: 'inherit' });
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      return {
+        status: 'failed',
+        reason: stderr || 'npm global install failed',
+      };
+    }
+    installed.push(...missingPackages);
+  }
+
+  for (const tool of missingLocalTools) {
+    console.log(`[${TOOL_NAME}] Installing local companion tool: ${tool.installCommand}`);
+    const result = run(NPX_BIN, tool.installArgs, { stdio: 'inherit' });
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      return {
+        status: 'failed',
+        reason: stderr || `${tool.name} install failed`,
+      };
+    }
+    installed.push(tool.name);
+  }
+
+  return { status: 'installed', packages: installed };
 }
 
 function gitRefExists(repoRoot, refName) {
@@ -4010,17 +4189,33 @@ function status(rawArgs) {
 
   const toolchain = detectGlobalToolchainPackages();
   const npmServices = GLOBAL_TOOLCHAIN_PACKAGES.map((pkg) => {
+    const service = getGlobalToolchainService(pkg);
     if (!toolchain.ok) {
-      return { name: pkg, status: 'unknown' };
+      return {
+        name: service.name,
+        displayName: service.name,
+        packageName: pkg,
+        dependencyUrl: service.dependencyUrl || null,
+        status: 'unknown',
+      };
     }
     return {
-      name: pkg,
+      name: service.name,
+      displayName: service.name,
+      packageName: pkg,
+      dependencyUrl: service.dependencyUrl || null,
       status: toolchain.installed.includes(pkg) ? 'active' : 'inactive',
     };
   });
+  const localCompanionServices = detectOptionalLocalCompanionTools().map((tool) => ({
+    name: tool.name,
+    displayName: tool.displayName || tool.name,
+    status: tool.status,
+  }));
   const requiredSystemTools = detectRequiredSystemTools();
   const services = [
     ...npmServices,
+    ...localCompanionServices,
     ...requiredSystemTools.map((tool) => ({
       name: tool.name,
       displayName: tool.displayName || tool.name,
@@ -4079,6 +4274,24 @@ function status(rawArgs) {
     const serviceLabel = service.displayName || service.name;
     console.log(`  - ${statusDot(service.status)} ${serviceLabel}: ${service.status}`);
   }
+  const inactiveOptionalCompanions = [...npmServices, ...localCompanionServices]
+    .filter((service) => service.status !== 'active')
+    .map((service) => service.displayName || service.name);
+  if (inactiveOptionalCompanions.length > 0) {
+    console.log(
+      `[${TOOL_NAME}] Optional companion tools inactive: ${inactiveOptionalCompanions.join(', ')}`,
+    );
+    for (const warning of describeMissingGlobalDependencyWarnings(
+      npmServices
+        .filter((service) => service.status === 'inactive')
+        .map((service) => service.packageName),
+    )) {
+      console.log(`[${TOOL_NAME}] ${warning}`);
+    }
+    console.log(
+      `[${TOOL_NAME}] Run '${SHORT_TOOL_NAME} setup' to install missing companions with an explicit Y/N prompt.`,
+    );
+  }
   const missingSystemTools = requiredSystemTools.filter((tool) => tool.status !== 'active');
   if (missingSystemTools.length > 0) {
     const tools = missingSystemTools
@@ -4713,21 +4926,32 @@ function setup(rawArgs) {
   const globalInstallStatus = installGlobalToolchain(options);
   if (globalInstallStatus.status === 'installed') {
     console.log(
-      `[${TOOL_NAME}] ✅ Global tools installed (${(globalInstallStatus.packages || []).join(', ')}).`,
+      `[${TOOL_NAME}] ✅ Companion tools installed (${(globalInstallStatus.packages || []).join(', ')}).`,
     );
   } else if (globalInstallStatus.status === 'already-installed') {
-    console.log(`[${TOOL_NAME}] ✅ Companion npm global tools already installed. Skipping.`);
+    console.log(`[${TOOL_NAME}] ✅ Companion tools already installed. Skipping.`);
   } else if (globalInstallStatus.status === 'failed') {
+    const installCommands = describeCompanionInstallCommands(
+      GLOBAL_TOOLCHAIN_PACKAGES,
+      OPTIONAL_LOCAL_COMPANION_TOOLS,
+    );
     console.log(
       `[${TOOL_NAME}] ⚠️ Global install failed: ${globalInstallStatus.reason}\n` +
       `[${TOOL_NAME}] Continue with local safety setup. You can retry later with:\n` +
-      `  ${NPM_BIN} i -g ${GLOBAL_TOOLCHAIN_PACKAGES.join(' ')}`,
+      installCommands.map((command) => `  ${command}`).join('\n'),
     );
   } else if (globalInstallStatus.status === 'skipped' && globalInstallStatus.reason === 'non-interactive-default') {
     console.log(
-      `[${TOOL_NAME}] Skipping global installs (non-interactive mode). ` +
+      `[${TOOL_NAME}] Skipping companion installs (non-interactive mode). ` +
       `Use --yes-global-install to force or run interactively for Y/N prompt.`,
     );
+  } else if (globalInstallStatus.status === 'skipped') {
+    console.log(`[${TOOL_NAME}] ⚠️ Companion installs skipped by user choice.`);
+    for (const warning of describeMissingGlobalDependencyWarnings(
+      globalInstallStatus.missingPackages || [],
+    )) {
+      console.log(`[${TOOL_NAME}] ⚠️ ${warning}`);
+    }
   }
   const requiredSystemTools = detectRequiredSystemTools();
   const missingSystemTools = requiredSystemTools.filter((tool) => tool.status !== 'active');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.11",
+  "version": "7.0.13",
   "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
   "license": "MIT",
   "preferGlobal": true,