@cantinasecurity/apex-cli 0.1.42 → 0.1.44

package/.claude/skills/apex-cli/SKILL.md

@@ -62,6 +62,8 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - `apex-trial-status` is MCP-only; do not invoke it as a CLI command. In a CLI-only flow, use the `claimDeadline` returned by `apex redeem <code> --json` without repeating or persisting the secret code.
 - After a guest scan, tell the user to run `apex claim` on the same machine before that returned claim deadline. If the deadline is unavailable or uncertain, do not guess or start a replacement login; run `apex claim` and let the server validate the proof.
 - Claim moves the guest workspace, scans, and findings into the currently selected Cantina workspace when the account can run scans there. Personal workspace owners receive the trial in their existing workspace instead of a duplicate. If the selected workspace cannot run scans, tell the user to switch to one that can and retry before the claim deadline.
+- Cantina company access requires current, activated membership; pending invitations and removed or disabled memberships do not grant access. After membership changes, refresh the account with `apex login` in a terminal, checking `apex-trial-status` first and preserving the claim-first workflow above. For temporary company-access verification failures, keep credentials and retry after recovery.
+- For GitHub connection, use `apex-connect-provider` with `provider: "github"` and pass the returned URL unchanged to the user. They must open it in the browser signed in to the same Cantina account as the CLI and complete GitHub authorization. After an organization owner approves an installation request, call the tool again to finish company linking. CLI fallback: `apex connect github`. Automation must not assume the returned URL is hosted on github.com.
 - Service-key creation, listing, and revocation have no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in a tool argument, tool result, source file, or log. Hosted MCP clients may read it from a secret-backed environment variable for the HTTP Authorization header.
 - If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to query credit availability or trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
 - For a hosted MCP client, connect to `https://ai.cantina.xyz/mcp` and send `APEX_SERVICE_KEY` as a Bearer header. The service key authenticates hosted MCP, but not the local CLI or stdio MCP; those use device login.
@@ -74,7 +76,7 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - `apex credits` reports standard credits plus audit, fix review, and Lite scan entitlements when Bedrock returns those balances.
 - Work from the target repository directory so Apex can resolve `.apex/workspace.json`.
 - `apex scan` scans the current working directory by default; pass `--repo` only when the user asks to scan explicit alternate roots.
-- `apex-doctor` is read-only for guest sessions and reports the local snapshot plan without reserving a workspace. For account sessions it reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
+- `apex-doctor` reports the running CLI version and detects conflicting npm/pnpm global installations. It is read-only for guest sessions and reports the local snapshot plan without reserving a workspace. For account sessions it reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Plain local directories and dirty git worktrees can scan through local snapshot uploads without provider access.
 - Audit scans use `--mode audit` in user-facing CLI calls and request payloads. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub, GitLab or company-enabled Forgejo sources.
 - Lite scans use `--mode lite` in CLI calls or `mode: "lite"` in MCP, require Lite Scan beta access, and require provider-backed GitHub or GitLab sources without local snapshot fallback.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Cantina agent plugins for security review workflows.",
-    "version": "0.1.42"
+    "version": "0.1.44"
   },
   "plugins": [
     {
@@ -14,10 +14,10 @@
       "source": {
         "source": "npm",
         "package": "@cantinasecurity/apex-cli",
-        "version": "0.1.42"
+        "version": "0.1.44"
       },
       "description": "Run Apex security scans and review findings from Claude Code.",
-      "version": "0.1.42",
+      "version": "0.1.44",
       "author": {
         "name": "Cantina",
         "email": "support@cantina.xyz"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "Run Apex security scans and review findings from Claude Code.",
   "author": {
     "name": "Cantina",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "Run Apex security scans and review findings from Codex.",
   "author": {
     "name": "Cantina",

package/.mcp.claude.json

@@ -5,7 +5,7 @@
       "args": [
         "-y",
         "-p",
-        "@cantinasecurity/apex-cli@0.1.42",
+        "@cantinasecurity/apex-cli@0.1.44",
         "apex-mcp"
       ],
       "env": {

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.42",
+      "@cantinasecurity/apex-cli@0.1.44",
       "apex-mcp"
     ],
     "env": {

package/MARKETPLACE.md

@@ -13,7 +13,7 @@ This package is prepared as both a Claude Code plugin and a Codex plugin. The pu
 The plugin MCP configs launch the pinned npm CLI package with:
 
 ```bash
-npx -y -p @cantinasecurity/apex-cli@0.1.42 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.44 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -66,6 +66,14 @@ cannot adopt the new merge and generation-safety rules until it restarts.
 
 When `apex` is run in an interactive terminal, it checks for updates periodically and offers to install them.
 
+`apex update` updates the package-manager installation that owns the running
+executable and verifies that installation actually changed before reporting
+success. `apex doctor` reports the running version and package manager. If npm
+and pnpm contain different global Apex versions, doctor identifies the stale
+active copy and prints the command that repairs it. The same installation
+diagnostic is included in `apex doctor --json`, including when another doctor
+check fails.
+
 ## Local Development
 
 1. Install dependencies:
@@ -158,30 +166,30 @@ unclaimed local trial proof so `apex claim` can still use it.
 Agent-safe copy/paste prompt (substitute the issued code):
 
 ```text
-Install and run Cantina Apex CLI 0.1.42 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.44 to start one free standard security scan of this repository immediately.
 
 Use this trial code only where <TRIAL_CODE> appears below: SPBT-DEVREL-XXXXXXXX
 
 Run the commands yourself from the repository root; do not stop after setup or only explain the steps. Use terminal CLI commands only. Do not use an Apex MCP tool or run `apex setup`, `apex mcp`, `apex login`, `apex-auth-start`, or `apex-auth-wait`. Never use `--replace` or `--force`.
 
 Use this exact command prefix for every Apex command:
-  npx -y -p @cantinasecurity/apex-cli@0.1.42 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.44 apex
 
 1. Before redeeming, confirm every command will use the same persistent, user-accessible machine or container, HOME, filesystem, and repository root. Confirm Node.js 20+ and npx are available. If `APEX_BASE_URL` is set, continue only when its origin is `https://ai.cantina.xyz`. Run the exact prefix with `--help` and continue only if help lists both `redeem` and `claim`. If any check fails, STOP before sending the code; do not install system packages.
 2. Redeem, with at most one response-loss recovery retry:
-     npx -y -p @cantinasecurity/apex-cli@0.1.42 apex redeem <TRIAL_CODE> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.44 apex redeem <TRIAL_CODE> --json
    This terminal command is the only allowed tool call containing the code. Never echo or restate the code, store it in a file or environment variable, put it in a URL or MCP call, or include it in your response. Parse the JSON from stdout only; do not merge stderr into stdout, because npm may write warnings to stderr. Continue when the command exits 0 and stdout is JSON with `redeemed: true` and `outcome` equal to `redeemed` or `idempotent`. `idempotent` means the existing guest session resumed and it may already own a workspace. If and only if the first attempt ends with an ambiguous transport/connection failure or an interrupted/missing response and no typed server error code, retry this exact same command once on the same machine, HOME, and repository root. Never retry a typed server rejection and never make more than one recovery retry. If the allowed retry does not return a successful JSON outcome, STOP.
 3. Immediately start exactly one scan; do not wait for another instruction:
-     npx -y -p @cantinasecurity/apex-cli@0.1.42 apex scan --mode standard --non-interactive --no-open --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.44 apex scan --mode standard --non-interactive --no-open --json
    The CLI validates the complete guest local archive before it reserves a workspace. An unbound renamed checkout may recover only the sole empty guest workspace when no explicit workspace name was supplied. On any error or nonzero exit, STOP. After a successful scan JSON response, inspect `localPersistence.workspaceBindingSaved`. If it is `false`, the server scan already started: capture and report `binding.lastScanId`, then STOP; do not run status or findings until local repository permissions are repaired. Otherwise capture `binding.lastScanId` from the JSON as <SCAN_ID>; if it is absent, STOP.
 4. About every 60 seconds, poll that exact scan:
-     npx -y -p @cantinasecurity/apex-cli@0.1.42 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.44 apex status --scan <SCAN_ID> --json
    Read `progress.progress.status`. Wait while it is `created`, `pending`, `queued`, `starting`, `running`, `in_progress`, or `processing`. Continue on `completed`. STOP on `failed`, `cancelled`, a missing or unknown status, or a command failure.
 5. Fetch that exact scan's findings:
-     npx -y -p @cantinasecurity/apex-cli@0.1.42 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.44 apex findings --scan <SCAN_ID> --json
    On success, summarize findings by severity, most severe first, including identifier, title, status, and confidence. This command does not return file locations, so do not invent them. On failure, STOP.
 6. Do not claim automatically. Tell me the claim deadline from step 2 and remind me to run this exact command myself from the same repository root, machine, and HOME:
-     npx -y -p @cantinasecurity/apex-cli@0.1.42 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.44 apex claim
    It may open a browser so I can create or sign in to a Cantina account and keep the results. Claim moves the trial into the currently selected Cantina workspace when I can run scans there, or into my existing personal workspace. If the selected workspace cannot run scans, tell me to switch to one that can and retry before the claim deadline.
 
 Never paste raw command transcripts. For any failure, report only the step, exit code, and sanitized error. Redact the trial code and every `apex_at_`, `apex_rt_`, or `apex_ct_` value from all reports.
@@ -495,6 +503,19 @@ Useful flags:
 
 Unauthenticated `--json`, `--non-interactive`, and non-TTY commands fail immediately with `apex login` guidance. Run login explicitly before automation. Temporary refresh/network failures preserve credentials; retry after the service recovers. Provider connection commands return URLs without opening browsers in automation.
 
+Cantina company access requires a current, activated membership. Removed or
+disabled members and pending invitations do not grant access. After membership
+changes, run `apex login` again to refresh the company snapshot. If company-access
+verification is temporarily unavailable, keep the saved credentials and retry
+after the service recovers.
+
+For `apex connect github`, open the returned URL in a browser signed in to the
+same Cantina account as the CLI, then complete GitHub authorization. After an
+organization owner approves an installation request, run `apex connect github`
+again to finish linking the installation to the selected company. Local MCP
+users repeat `apex-connect-provider` with `provider: "github"` to obtain the new
+URL; automation must not assume the URL points directly to github.com.
+
 `auto` is the default. `remote` requires Apex to materialize from a remote repository. `local` forces a local snapshot upload even when a clean remote path is available.
 
 Audit scans use `audit` as the scan mode and still require provider-backed GitHub, GitLab or company-enabled Forgejo repositories that Apex can materialize remotely without a local snapshot fallback. `ultra` remains accepted as a backwards-compatible alias.
@@ -687,7 +708,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.42",
+      "cliVersion": "0.1.44",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -718,7 +739,7 @@ The npm package also includes marketplace-ready plugin artifacts:
 - `.claude-plugin/plugin.json` and `.mcp.claude.json` for Claude Code plugin installs
 - `.claude-plugin/marketplace.json` for a Claude marketplace entry backed by the public npm package
 
-These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.42 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
+These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.44 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
 
 The repository also includes `.agents/plugins/marketplace.json` for local Codex marketplace testing from a checkout.
 

package/dist/commands.js

@@ -19,11 +19,11 @@ import { createWorkspaceBindingFromSummary, fetchCompanyCredits, fetchCompanyWor
 import { loadWorkspaceBinding, saveWorkspaceBinding } from "./workspace-binding.js";
 import { commandSetup as runCliSetup } from "./setup.js";
 import { getTelemetryStatus, setTelemetryAuthKind, setTelemetryEnabled, setTelemetryOnboardingOutcome, } from "./telemetry.js";
-import { commandUpdate as runCliUpdate } from "./update.js";
+import { commandUpdate as runCliUpdate, getCliInstallDiagnostics, } from "./update.js";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-function getRequestedWorkspaceSrDoctorPayload(me, flags) {
+function getRequestedWorkspaceSrDoctorPayload(me, flags, cliInstallation) {
     const requested = getFlagString(flags, "company")?.trim().toLowerCase();
     if (!requested)
         return null;
@@ -48,6 +48,7 @@ function getRequestedWorkspaceSrDoctorPayload(me, flags) {
     const company = scopes[0];
     const workspaceIds = [...new Set(scopes.map((scope) => scope.workspaceId))];
     return {
+        cliInstallation,
         authenticatedAs: me.user.username ?? me.user.id,
         accessMode: "workspace_sr",
         company: {
@@ -1035,6 +1036,21 @@ export async function commandTelemetry(flags, target) {
     return payload;
 }
 export async function commandDoctor(client, cwd, flags) {
+    const cliInstallation = await getCliInstallDiagnostics().catch(() => null);
+    if (!isJsonMode(flags) && cliInstallation) {
+        const manager = cliInstallation.packageManager
+            ? ` via ${cliInstallation.packageManager}`
+            : cliInstallation.installKind === "git-checkout"
+                ? " from a Git checkout"
+                : "";
+        logLine(`CLI: ${escapeTerminalControlCharacters(cliInstallation.currentVersion)}${manager}`, flags);
+        if (cliInstallation.warning) {
+            logLine(`CLI installation warning: ${escapeTerminalControlCharacters(cliInstallation.warning)}`, flags);
+        }
+        if (cliInstallation.repairCommand) {
+            logLine(`Repair: ${escapeTerminalControlCharacters(cliInstallation.repairCommand)}`, flags);
+        }
+    }
     try {
         const serviceKeyGuidance = getServiceKeyCliAuthGuidance();
         const existingMe = serviceKeyGuidance ? await getMe(client) : null;
@@ -1044,7 +1060,7 @@ export async function commandDoctor(client, cwd, flags) {
         const me = existingMe ?? (await ensureAuthenticated(client, flags));
         const authState = await getCommandAuthState(client, me);
         setTelemetryAuthKind(authState.authKind);
-        const workspaceSrPayload = getRequestedWorkspaceSrDoctorPayload(me, flags);
+        const workspaceSrPayload = getRequestedWorkspaceSrDoctorPayload(me, flags, cliInstallation);
         if (workspaceSrPayload) {
             if (isJsonMode(flags)) {
                 printJson(workspaceSrPayload);
@@ -1069,6 +1085,7 @@ export async function commandDoctor(client, cwd, flags) {
         });
         const localSnapshotCount = result.resolve.plannedSources.filter((source) => source.sourceKind === "local_archive").length;
         const payload = {
+            cliInstallation,
             authenticatedAs: me.user.username ?? me.user.id,
             accessMode: "company",
             company: result.company,
@@ -1089,10 +1106,14 @@ export async function commandDoctor(client, cwd, flags) {
         return payload;
     }
     catch (error) {
+        if (error instanceof Error) {
+            error.cliInstallation = cliInstallation;
+        }
         if (isJsonMode(flags)) {
             const payload = {
                 ok: false,
                 error: formatApiError(error),
+                cliInstallation,
             };
             printJson(payload);
             if (error instanceof Error) {

package/dist/help.js

@@ -27,7 +27,7 @@ export const CLI_HELP_TEXT = `Usage:
                                     Bind this directory to an existing Apex workspace
   apex cancel-scan [scan-id]        Cancel a running scan
   apex status                       Show progress for the latest or selected scan
-  apex doctor                       Validate auth, repos, connections, and workspace binding
+  apex doctor                       Validate CLI installation, auth, repos, connections, and workspace binding
   apex login                        Sign in to Apex
   apex redeem <code>                Redeem a Standard-scan code without device login
   apex claim                        Link a guest workspace and findings to a Cantina account
@@ -104,6 +104,8 @@ Tips:
   An unbound renamed checkout may recover only the sole empty guest workspace unless you pass --workspace-name.
   After a guest scan, run apex claim on the same machine within the displayed claim deadline to keep the results.
   Claim moves trial results into the selected Cantina workspace when you can run scans there, or into your existing personal workspace.
+  Cantina company access requires current, activated membership. After membership changes, run apex login again.
+  For GitHub connection, use the same Cantina account in the browser. After owner approval, rerun apex connect github to finish linking.
   Service-key commands require an existing login; run apex login first when needed.
   APEX_SERVICE_KEY authenticates https://ai.cantina.xyz/mcp and hosted REST; it does not replace apex login for local CLI or stdio MCP commands.
   Apex automatically selects your company when only one is available. With multiple companies, choose one interactively or pass --company.
@@ -178,7 +180,7 @@ Commands:
   /workspaces             List accessible workspaces for the active company
   /cancel-scan [scan-id]  Cancel a running or most recent scan
   /status [scan-id]       Show progress for the most recent or selected scan
-  /doctor                 Validate auth, repos, connections, and workspace binding
+  /doctor                 Validate CLI installation, auth, repos, connections, and workspace binding
   /telemetry [status|enable|disable]
                           Show or change local anonymous usage telemetry settings
   /update                 Update the local Apex CLI install and exit the shell

package/dist/mcp.js

@@ -30,6 +30,8 @@ Suggested workflow:
 Notes:
 - Pass cwd explicitly for repository-specific operations. repoPaths accepts exact files, directories, or HTTPS repository URLs; remote URLs never fall back to uploading cwd. Use Standard for local changes and unconnected public repositories.
 - Tool calls are always non-interactive and never auto-open a browser.
+- Cantina company access requires current, activated membership. After membership changes, check apex-trial-status and preserve the claim-first workflow before refreshing account login. Temporary membership-verification failures should be retried after recovery without discarding credentials.
+- For GitHub, return the apex-connect-provider URL unchanged. The user must open it in the browser signed in to the same Cantina account as the CLI and complete GitHub authorization. After an organization owner approves an installation request, call apex-connect-provider again to finish company linking.
 - Finding write tools use the same Apex device-login credentials as read tools. Never ask for browser cookies or CANTINA_AUTH_TOKEN. An error requiring CANTINA_AUTH_TOKEN proves the MCP server is outdated; update Apex CLI, re-run apex setup for this client, restart it, and retry.
 - Organization service-key creation, listing, and revocation are intentionally scripted-CLI-only and are not exposed as MCP tools. Never ask a user to paste a service key into a prompt or tool argument. A hosted MCP client supplies it only as the HTTP Authorization header.
 - Production agents that do not need local filesystem access can connect to https://ai.cantina.xyz/mcp over Streamable HTTP with Authorization: Bearer <service-key>. Serverless and cron applications can instead use the REST API documented at https://ai.cantina.xyz/docs/apex-api. This local stdio server continues to use device login.
@@ -56,6 +58,11 @@ const PR_MISSING_PROVIDER_CONNECTIONS_ERROR_PREFIX = "PR scans require connected
 const MULTIPLE_ACTIVE_SCANS_ERROR = "Multiple active scans are running. Run `apex scans` to list scan IDs, then re-run `apex cancel-scan <scan-id>`.";
 const DUPLICATE_SCAN_FORCE_GUIDANCE = "Re-run with --force to start another scan.";
 const MULTIPLE_COMPANIES_ERROR = "Multiple companies available. Re-run with --company <id-or-handle>.";
+const LOCAL_NOT_AUTHENTICATED_ERROR = "Apex is not authenticated. Run `apex login` explicitly, then retry this command.";
+const LOCAL_CLAIM_PROOF_ERROR = "Your guest trial session is no longer available, but its claim proof is stored on this machine. Run `apex claim` to keep the trial results.";
+const SERVICE_KEY_LOCAL_AUTH_GUIDANCE = "service keys authenticate the hosted MCP and REST endpoints, not the local Apex CLI";
+const MCP_NOT_AUTHENTICATED_ERROR = "Not authenticated. If the user supplied a Cantina trial code, run `apex redeem <code>` in a terminal instead of starting device login; never put the code in an MCP tool call. Otherwise call `apex-auth-start`, ask the user to approve the device login, then call `apex-auth-wait`.";
+const MCP_CLAIM_PROOF_ERROR = "Your guest trial session is no longer available, but its claim proof is stored on this machine. Run `apex claim` in a terminal to keep the trial results before starting another login; claim is intentionally not exposed through MCP.";
 function resolveCwd(cwd) {
     return path.resolve(cwd && cwd.trim().length > 0 ? cwd : process.cwd());
 }
@@ -143,6 +150,15 @@ function successResult(summary, value) {
 }
 function formatMcpErrorMessage(toolName, error) {
     const message = formatApiError(error);
+    if (message === LOCAL_NOT_AUTHENTICATED_ERROR) {
+        return MCP_NOT_AUTHENTICATED_ERROR;
+    }
+    if (message === LOCAL_CLAIM_PROOF_ERROR) {
+        return MCP_CLAIM_PROOF_ERROR;
+    }
+    if (message.includes(SERVICE_KEY_LOCAL_AUTH_GUIDANCE)) {
+        return `${message} ${MCP_NOT_AUTHENTICATED_ERROR}`;
+    }
     if (message === WORKSPACE_BINDING_ERROR) {
         return "No workspace is bound to this directory. Call `apex-workspace-use` to bind an existing workspace, or call `apex-scan` to create or resolve one first.";
     }
@@ -165,16 +181,23 @@ function formatMcpErrorMessage(toolName, error) {
 }
 function errorResult(toolName, error) {
     const message = formatMcpErrorMessage(toolName, error);
+    const cliInstallation = error instanceof Error && "cliInstallation" in error
+        ? error.cliInstallation
+        : undefined;
+    const diagnosis = cliInstallation
+        ? `\n\nCLI installation diagnosis:\n${JSON.stringify(cliInstallation, null, 2)}`
+        : "";
     return {
         content: [
             {
                 type: "text",
-                text: message,
+                text: `${message}${diagnosis}`,
             },
         ],
         structuredContent: {
             ok: false,
             error: message,
+            ...(cliInstallation ? { cliInstallation } : {}),
         },
         isError: true,
     };
@@ -199,9 +222,9 @@ async function requireAuthenticated(client) {
     if (!me) {
         const credentials = await client.getCredentials();
         if (isClaimProofAvailable(credentials)) {
-            throw new Error("Your guest trial session is no longer available, but its claim proof is stored on this machine. Run `apex claim` in a terminal to keep the trial results before starting another login; claim is intentionally not exposed through MCP.");
+            throw new Error(MCP_CLAIM_PROOF_ERROR);
         }
-        throw new Error("Not authenticated. If the user supplied a Cantina trial code, run `apex redeem <code>` in a terminal instead of starting device login; never put the code in an MCP tool call. Otherwise call `apex-auth-start`, ask the user to approve the device login, then call `apex-auth-wait`.");
+        throw new Error(MCP_NOT_AUTHENTICATED_ERROR);
     }
     return me;
 }
@@ -396,7 +419,7 @@ function registerTools(server, auditSetupEnabled = false) {
     });
     server.registerTool("apex-doctor", {
         title: "Run Apex Doctor",
-        description: "Validate auth, local source detection, workspace binding, and the planned remote-vs-local materialization strategy.",
+        description: "Validate the CLI installation, auth, local source detection, workspace binding, and the planned remote-vs-local materialization strategy.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),
@@ -406,7 +429,6 @@ function registerTools(server, auditSetupEnabled = false) {
         },
     }, async ({ cwd, company, workspaceName, repoPaths, sourceMode }) => runTool("apex-doctor", async () => {
         const client = new ApexApiClient();
-        await requireAuthenticated(client);
         const targetCwd = resolveCwd(cwd);
         const payload = await commandDoctor(client, targetCwd, buildFlags({
             company,
@@ -885,7 +907,7 @@ function registerTools(server, auditSetupEnabled = false) {
     }));
     server.registerTool("apex-connect-provider", {
         title: "Get Apex Provider Connection URL",
-        description: "Return the browser URL a user needs to connect GitHub, GitLab or company-enabled Forgejo access for Apex. This tool never opens a browser.",
+        description: "Return the browser URL a user needs to connect GitHub, GitLab or company-enabled Forgejo access for Apex. This tool never opens a browser. For GitHub, use the same Cantina account as the CLI in the browser and repeat this tool after organization-owner approval to finish linking.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),

package/dist/update.js

@@ -1,5 +1,5 @@
 import { execFile as execFileCallback, spawn } from "node:child_process";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -51,19 +51,23 @@ async function readPackageVersion(packageRoot) {
     }
     return parsed.version.trim();
 }
-async function execText(command, args, cwd) {
+async function canonicalPath(targetPath) {
+    return realpath(targetPath).catch(() => path.resolve(targetPath));
+}
+async function execText(command, args, cwd, timeout) {
     const result = await execFile(command, args, {
         cwd,
         encoding: "utf8",
+        timeout,
     });
     return {
         stdout: result.stdout.trim(),
         stderr: result.stderr.trim(),
     };
 }
-async function tryExecText(command, args, cwd) {
+async function tryExecText(command, args, cwd, timeout) {
     try {
-        return await execText(command, args, cwd);
+        return await execText(command, args, cwd, timeout);
     }
     catch {
         return null;
@@ -93,25 +97,121 @@ async function detectProjectPackageManager(packageRoot) {
     }
     return null;
 }
-async function detectGlobalInstaller() {
-    if (await tryExecText("pnpm", ["--version"])) {
+function globalInstallCommand(packageManager, packageSpec = REPO_SPEC) {
+    if (packageManager === "pnpm") {
         return {
             command: "pnpm",
-            args: ["add", "-g", REPO_SPEC],
-            label: `pnpm add -g ${REPO_SPEC}`,
+            args: ["add", "-g", packageSpec],
+            label: `pnpm add -g ${packageSpec}`,
         };
     }
-    if (await tryExecText("npm", ["--version"])) {
+    return {
+        command: "npm",
+        args: ["install", "-g", packageSpec],
+        label: `npm install -g ${packageSpec}`,
+    };
+}
+function globalRemoveCommand(packageManager) {
+    if (packageManager === "pnpm") {
         return {
-            command: "npm",
-            args: ["install", "-g", REPO_SPEC],
-            label: `npm install -g ${REPO_SPEC}`,
+            command: "pnpm",
+            args: ["remove", "-g", REPO_SPEC],
+            label: `pnpm remove -g ${REPO_SPEC}`,
         };
     }
     return {
-        command: "pnpm",
-        args: ["add", "-g", REPO_SPEC],
-        label: `pnpm add -g ${REPO_SPEC}`,
+        command: "npm",
+        args: ["uninstall", "-g", REPO_SPEC],
+        label: `npm uninstall -g ${REPO_SPEC}`,
+    };
+}
+async function getGlobalPackageManagerRoots() {
+    const candidates = await Promise.all(["pnpm", "npm"].map(async (packageManager) => {
+        const result = await tryExecText(packageManager, ["root", "-g"], undefined, 2_000);
+        if (!result?.stdout)
+            return null;
+        return { packageManager, root: path.resolve(result.stdout) };
+    }));
+    return candidates.filter((candidate) => candidate !== null);
+}
+async function inspectGlobalInstallations(packageRoot) {
+    const [activeRoot, roots] = await Promise.all([
+        canonicalPath(packageRoot),
+        getGlobalPackageManagerRoots(),
+    ]);
+    const installations = (await Promise.all(roots.map(async ({ packageManager, root }) => {
+        const candidateRoot = path.join(root, ...PACKAGE_NAME.split("/"));
+        const version = await readPackageVersion(candidateRoot).catch(() => null);
+        if (!version)
+            return null;
+        const resolvedCandidateRoot = await canonicalPath(candidateRoot);
+        return {
+            packageManager,
+            version,
+            packageRoot: candidateRoot,
+            active: resolvedCandidateRoot === activeRoot,
+        };
+    }))).filter((installation) => installation !== null);
+    return { roots, installations };
+}
+async function detectGlobalInstaller(packageRoot) {
+    const { installations } = await inspectGlobalInstallations(packageRoot);
+    const owner = installations.find((installation) => installation.active);
+    if (owner) {
+        return {
+            ...globalInstallCommand(owner.packageManager),
+            packageRoot: owner.packageRoot,
+        };
+    }
+    throw new Error("Apex could not determine which package manager owns this installation. Run `npm install -g @cantinasecurity/apex-cli` or `pnpm add -g @cantinasecurity/apex-cli` explicitly.");
+}
+export async function getCliInstallDiagnostics(packageRoot = PACKAGE_ROOT) {
+    const currentVersion = await readPackageVersion(packageRoot);
+    const gitCheckout = await pathExists(path.join(packageRoot, ".git"));
+    if (gitCheckout) {
+        return {
+            currentVersion,
+            installKind: "git-checkout",
+            packageManager: null,
+            healthy: true,
+            installations: [],
+            warning: null,
+            repairCommand: null,
+        };
+    }
+    const { installations } = await inspectGlobalInstallations(packageRoot);
+    const active = installations.find((installation) => installation.active) ?? null;
+    const duplicates = installations.filter((installation) => !installation.active);
+    const newerDuplicate = duplicates.find((installation) => compareVersions(currentVersion, installation.version) < 0);
+    const mismatchedTransientCopies = active
+        ? []
+        : installations.filter((installation) => installation.version !== currentVersion);
+    const warning = active && newerDuplicate
+        ? `This process is Apex CLI ${currentVersion}, but ${newerDuplicate.packageManager} also has newer Apex CLI ${newerDuplicate.version}. Your shell is resolving the older installation.`
+        : active && duplicates.length > 0
+            ? `Multiple global Apex CLI installations were found (${installations.map((installation) => `${installation.packageManager} ${installation.version}`).join(", ")}). They can drift and cause the shell and MCP clients to run different versions.`
+            : mismatchedTransientCopies.length > 0
+                ? `This process is Apex CLI ${currentVersion} from a temporary package, but global Apex installations use ${installations.map((installation) => `${installation.packageManager} ${installation.version}`).join(", ")}. Terminal commands may resolve a different version.`
+                : null;
+    const repairCommand = active && duplicates.length > 0
+        ? [
+            globalInstallCommand(active.packageManager, `${REPO_SPEC}@latest`).label,
+            ...duplicates.map((installation) => globalRemoveCommand(installation.packageManager).label),
+        ].join(" && ")
+        : mismatchedTransientCopies.length > 0
+            ? installations
+                .map((installation) => globalInstallCommand(installation.packageManager, `${REPO_SPEC}@latest`).label)
+                .join(" && ")
+            : null;
+    const publicInstallations = installations.map(({ packageRoot: _packageRoot, ...installation }) => installation);
+    return {
+        currentVersion,
+        installKind: "package-install",
+        packageManager: active?.packageManager ?? null,
+        healthy: warning === null,
+        installations: publicInstallations,
+        warning,
+        repairCommand,
     };
 }
 async function resolveInstallContext(packageRoot = PACKAGE_ROOT) {
@@ -146,23 +246,27 @@ async function resolveInstallContext(packageRoot = PACKAGE_ROOT) {
                 upstreamRef: upstream?.stdout ?? null,
                 updateCommands,
                 updateCommand: display.join(" && "),
+                verificationPackageRoot: null,
             };
         }
     }
-    const installer = await detectGlobalInstaller();
+    const installer = await detectGlobalInstaller(packageRoot).catch(() => null);
     return {
         packageRoot,
         currentVersion,
         currentRevision: null,
         installKind: "package-install",
         upstreamRef: null,
-        updateCommands: [
-            {
-                command: installer.command,
-                args: installer.args,
-            },
-        ],
-        updateCommand: installer.label,
+        updateCommands: installer
+            ? [
+                {
+                    command: installer.command,
+                    args: installer.args,
+                },
+            ]
+            : [],
+        updateCommand: installer?.label ?? null,
+        verificationPackageRoot: installer?.packageRoot ?? null,
     };
 }
 async function loadUpdateState() {
@@ -431,7 +535,7 @@ export async function commandUpdate(flags, packageRoot = PACKAGE_ROOT) {
         return status;
     }
     if (!context.updateCommand || context.updateCommands.length === 0) {
-        throw new Error("No update command is available for this Apex CLI installation.");
+        throw new Error("Apex could not determine which package manager owns this installation. Run `npm install -g @cantinasecurity/apex-cli` or `pnpm add -g @cantinasecurity/apex-cli` explicitly.");
     }
     await ensureCleanGitCheckout(context);
     if (!isJsonMode(flags)) {
@@ -445,13 +549,24 @@ export async function commandUpdate(flags, packageRoot = PACKAGE_ROOT) {
             ...(await getUpdateStatus(packageRoot, true)),
             updated: true,
         }
-        : {
-            ...status,
-            currentVersion: status.latestVersion ?? status.currentVersion,
-            currentRevision: status.latestRevision ?? status.currentRevision,
-            available: false,
-            updated: true,
-        };
+        : await (async () => {
+            const installedVersion = await readPackageVersion(context.verificationPackageRoot ?? packageRoot);
+            if (status.latestVersion &&
+                compareVersions(installedVersion, status.latestVersion) < 0) {
+                const diagnostics = await getCliInstallDiagnostics(packageRoot).catch(() => null);
+                const repair = diagnostics?.repairCommand
+                    ? ` Run \`${diagnostics.repairCommand}\` to update the installation used by this shell.`
+                    : " Update the package-manager installation selected by `which apex`.";
+                throw new Error(`The installer finished, but this Apex executable is still ${installedVersion}; expected ${status.latestVersion}.${repair}`);
+            }
+            return {
+                ...status,
+                currentVersion: installedVersion,
+                currentRevision: status.latestRevision ?? status.currentRevision,
+                available: false,
+                updated: true,
+            };
+        })();
     if (isJsonMode(flags)) {
         printJson(payload);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",

package/skills/apex-cli/SKILL.md

@@ -67,6 +67,8 @@ Guidelines:
 - Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
 - The MCP-only `apex-trial-status` tool may report local guest and claim deadlines, but it must never return a trial code or claim token. `claimAvailable` becomes false at a known passed deadline; missing or invalid local deadline metadata remains conservative and server-authoritative. There is intentionally no MCP redemption or claim tool.
 - When MCP remains available after a guest scan, remind the user to run `apex claim` on the same machine while `claimAvailable` is true; after a known passed deadline, continue with normal account login.
+- Cantina company access requires current, activated membership; pending invitations and removed or disabled memberships do not grant access. After membership changes, refresh the account with `apex login` in a terminal, checking `apex-trial-status` first and preserving the claim-first workflow above. For temporary company-access verification failures, keep credentials and retry after recovery.
+- For GitHub connection, use `apex-connect-provider` with `provider: "github"` and pass the returned URL unchanged to the user. They must open it in the browser signed in to the same Cantina account as the CLI and complete GitHub authorization. After an organization owner approves an installation request, call the tool again to finish company linking. CLI fallback: `apex connect github`. Automation must not assume the returned URL is hosted on github.com.
 - Service-key creation, listing, and revocation have no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in a tool argument, tool result, source file, or log. Hosted MCP clients may read it from a secret-backed environment variable for the HTTP Authorization header.
 - If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to query credit availability or trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
 - For a hosted MCP client, connect to `https://ai.cantina.xyz/mcp` and send `APEX_SERVICE_KEY` as a Bearer header. The service key authenticates hosted MCP, but not the local CLI or stdio MCP; those use device login.
@@ -76,7 +78,7 @@ Guidelines:
 - Hosted repository scan triggers require `Idempotency-Key`. Reuse one stable key only for an identical transport/timeout/5xx retry. After correcting a definitive 4xx response, or for any new intended repository scan, use a new key. Apex Black stored start failures follow the support escalation rule above; never change keys to bypass them.
 - `apex-credits` reports standard credits plus audit, fix review, and Lite scan entitlements when Bedrock returns those balances.
 - `apex-scan` scans the provided `cwd` by default; pass `repoPaths` only when the user asks to scan explicit alternate roots.
-- `apex-doctor` is read-only for guest sessions and reports the local snapshot plan without reserving a workspace. For account sessions it reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
+- `apex-doctor` reports the running CLI version and detects conflicting npm/pnpm global installations. It is read-only for guest sessions and reports the local snapshot plan without reserving a workspace. For account sessions it reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Apex can scan plain local directories and dirty git worktrees without provider connections by using local snapshot uploads.
 - Audit scans use `mode: "audit"` in user-facing instructions and request payloads. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub, GitLab or company-enabled Forgejo sources.
 - Lite scans use `mode: "lite"`, require Lite Scan beta access, and require provider-backed GitHub or GitLab sources without local snapshot fallback.