@cantinasecurity/apex-cli 0.1.23 → 0.1.25

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

@@ -28,6 +28,9 @@ transport/connection failure or interrupted/missing response with no typed
 server error may you retry that exact same command once on the same machine,
 HOME, and repository root. Never retry a typed server rejection or make more
 than one recovery retry. Continue only for `redeemed` or `idempotent` outcomes.
+Parse the JSON from stdout only; do not merge stderr into stdout, because npm
+may write warnings to stderr. `idempotent` means the existing guest session
+resumed and it may already own a workspace.
 
 Recommended workflow:
 
@@ -47,6 +50,7 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 
 - Prefer scripted commands over the interactive shell.
 - A trial redeem with an ambiguous transport or response-loss failure may be retried exactly once with the same code, machine, HOME, and repository root. Never retry a typed server rejection or use `--replace` for response-loss recovery.
+- Guest standard scans validate the complete local archive before resolving or reserving a workspace. For an unbound renamed checkout, Apex may recover only the sole empty guest workspace when no explicit workspace name was supplied.
 - 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.
 - `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.
@@ -61,7 +65,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` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
+- `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.
 - 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 or GitLab 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.23"
+    "version": "0.1.25"
   },
   "plugins": [
     {
@@ -14,10 +14,10 @@
       "source": {
         "source": "npm",
         "package": "@cantinasecurity/apex-cli",
-        "version": "0.1.23"
+        "version": "0.1.25"
       },
       "description": "Run Apex security scans and review findings from Claude Code.",
-      "version": "0.1.23",
+      "version": "0.1.25",
       "author": {
         "name": "Cantina",
         "email": "support@cantina.xyz"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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.23",
+  "version": "0.1.25",
   "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.23",
+        "@cantinasecurity/apex-cli@0.1.25",
         "apex-mcp"
       ],
       "env": {

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.23",
+      "@cantinasecurity/apex-cli@0.1.25",
       "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.23 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.25 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -135,6 +135,13 @@ is idempotent while the guest session remains active. A different active trial
 requires the explicit `--replace` flag, which revokes the outgoing guest
 session before redeeming the new code.
 
+Guest standard scans validate the complete local archive before resolving or
+reserving a workspace. `apex doctor` is read-only for guest sessions. For an
+unbound renamed checkout, Apex may recover only the sole empty guest workspace
+when no explicit workspace name was supplied; it will not silently switch an
+explicit workspace selection or reuse a workspace that already contains scan
+history.
+
 Logging out of an active guest trial, or discarding a proof-only trial stub,
 requires explicit confirmation (`apex logout --force` in non-interactive
 flows). Apex first attempts a proof-bound server revoke; an explicitly
@@ -145,30 +152,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.23 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.25 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.23 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.25 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.23 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. Continue when the command exits 0 and stdout is JSON with `redeemed: true` and `outcome` equal to `redeemed` or `idempotent`. 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.
+     npx -y -p @cantinasecurity/apex-cli@0.1.25 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.23 apex scan --mode standard --non-interactive --no-open --json
-   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.
+     npx -y -p @cantinasecurity/apex-cli@0.1.25 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.23 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.25 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.23 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.25 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.23 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.25 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.
@@ -421,14 +428,16 @@ codex mcp add apex \
 For Claude Code:
 
 ```bash
-claude mcp add --scope user \
+claude mcp add apex \
+  --scope user \
   -e APEX_MCP_CLIENT=claude \
   -e APEX_CLIENT_INTEGRATION=claude \
-  -- apex apex-mcp
+  -- apex-mcp
 ```
 
-`apex setup claude` checks whether the installed Claude CLI supports
-`--scope user`. On older Claude versions that reject that option, setup safely
+`apex setup claude` uses Claude's name-first stdio command syntax and checks
+whether the installed Claude CLI supports `--scope user`. If a Claude build
+omits that option or advertises it but rejects it at runtime, setup safely
 merges the same user-level `mcpServers.apex` entry into `~/.claude.json`
 without replacing other settings or servers.
 
@@ -567,7 +576,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.23",
+      "cliVersion": "0.1.25",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -598,7 +607,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.23 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.25 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/api-client.js

@@ -83,7 +83,7 @@ function getFriendlyApiErrorMessage(error) {
         case "GUEST_MODE_UNSUPPORTED":
             return "Guest trials support standard scans only. Run `apex claim` before starting another scan mode.";
         case "GUEST_WORKSPACE_LIMIT":
-            return "This guest trial has reached its workspace limit. Run `apex claim` to continue with your account.";
+            return "This guest trial already has a workspace. Run `apex workspaces` and `apex workspace use <workspace>` to reuse it, or run `apex claim` to continue with your Cantina account.";
         case "GUEST_CLAIM_REQUIRED":
             return "This action requires an account. Run `apex claim`, then retry it.";
         case "CLAIM_EXPIRED":

package/dist/commands.js

@@ -5,13 +5,13 @@ import { openInBrowser } from "./browser.js";
 import { getClaimProofState, isClaimProofAvailable, parseClaimDeadlineMs, } from "./claim-proof.js";
 import { loadConfig, updateConfig } from "./config.js";
 import { createFindingComment, fetchScanExport, fetchScanFindings, fetchWorkspaceFindings, isFindingUuid, normalizeFindingRef, resolveFindingSelection, resolveScanSelection, startFindingFixReviewScan, submitFindingFeedback, } from "./findings.js";
-import { prepareExplicitScanSources, supportsLegacyRemoteFlow, } from "./local-source-scan.js";
+import { prepareLocalSourceArchives, prepareExplicitScanSources, supportsLegacyRemoteFlow, } from "./local-source-scan.js";
 import { logLine, printJson, withLoadingIndicator } from "./output.js";
 import { claimOnboardingSession, isProofOnlyOnboardingCredentials, redeemOnboardingCode, revokeGuestOnboardingSession, } from "./onboarding.js";
 import { confirm } from "./prompt.js";
 import { cancelScan, fetchScanProgress, fetchWorkspaceScans, findMostRelevantActiveScan, getScanDisplayLabel, getScanDisplayId, getTrackedScanId, isActiveScanStatus, matchesScanId, selectDefaultScanToCancel, } from "./scan.js";
 import { createServiceApiKey, isServiceApiScope, listServiceApiKeys, revokeServiceApiKey, SERVICE_API_SCOPES, } from "./service-keys.js";
-import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, remediateMissingConnections, resolveWorkspaceSelection, resolveWorkspaceSelectionLegacy, resolveWorkspaceAllowingMissingConnections, selectWorkspaceTarget, } from "./session.js";
+import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, planGuestWorkspaceSelection, remediateMissingConnections, resolveWorkspaceSelection, resolveWorkspaceSelectionLegacy, resolveWorkspaceAllowingMissingConnections, selectWorkspaceTarget, } from "./session.js";
 import { createWorkspaceBindingFromSummary, fetchCompanyCredits, fetchCompanyWorkspaces, findWorkspaceByRef, } from "./workspaces.js";
 import { loadWorkspaceBinding, saveWorkspaceBinding } from "./workspace-binding.js";
 import { commandSetup as runCliSetup } from "./setup.js";
@@ -116,6 +116,47 @@ async function getCommandAuthState(client, me) {
             : null,
     };
 }
+async function resolveWorkspaceSelectionForScan(args) {
+    try {
+        return {
+            selection: args.selection,
+            result: await resolveWorkspaceSelection(args.client, args.selection),
+        };
+    }
+    catch (error) {
+        if (args.authKind !== "guest" ||
+            args.selection.workspaceNameWasExplicitlyChosen ||
+            args.selection.binding ||
+            getApiErrorCode(error) !== "GUEST_WORKSPACE_LIMIT") {
+            throw error;
+        }
+        let response;
+        try {
+            response = await fetchCompanyWorkspaces(args.client, args.selection.company.id);
+        }
+        catch {
+            throw error;
+        }
+        const recoverable = response.workspaces.filter((workspace) => workspace.scanCount === 0 && workspace.findingsCount === 0);
+        if (recoverable.length !== 1) {
+            throw error;
+        }
+        const workspace = recoverable[0];
+        const recoveredSelection = {
+            ...args.selection,
+            workspaceName: workspace.name,
+            binding: createWorkspaceBindingFromSummary({
+                companyId: args.selection.company.id,
+                workspace,
+                currentBinding: args.selection.binding,
+            }),
+        };
+        return {
+            selection: recoveredSelection,
+            result: await resolveWorkspaceSelection(args.client, recoveredSelection),
+        };
+    }
+}
 function logGuestScanFooter(authState, flags) {
     if (isJsonMode(flags) || !authState.guestCredentials)
         return;
@@ -945,8 +986,16 @@ export async function commandTelemetry(flags, target) {
 }
 export async function commandDoctor(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
+    const authState = await getCommandAuthState(client, me);
+    setTelemetryAuthKind(authState.authKind);
     try {
-        const result = await withLoadingIndicator("Inspecting this directory and checking Apex setup...", flags, () => resolveWorkspaceAllowingMissingConnections(client, cwd, me, flags));
+        const result = await withLoadingIndicator("Inspecting this directory and checking Apex setup...", flags, async () => {
+            if (authState.authKind === "guest") {
+                const selection = await selectWorkspaceTarget(cwd, me, flags);
+                return planGuestWorkspaceSelection(selection);
+            }
+            return resolveWorkspaceAllowingMissingConnections(client, cwd, me, flags);
+        });
         const localSnapshotCount = result.resolve.plannedSources.filter((source) => source.sourceKind === "local_archive").length;
         const payload = {
             authenticatedAs: me.user.username ?? me.user.id,
@@ -1040,14 +1089,42 @@ export async function commandScan(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
     const authState = await getCommandAuthState(client, me);
     setTelemetryAuthKind(authState.authKind);
-    const selection = await selectWorkspaceTarget(cwd, me, flags);
-    const result = await withLoadingIndicator("Resolving workspace and scan plan...", flags, () => resolveWorkspaceSelection(client, selection));
-    if (!result.resolve.workspaceId) {
-        throw new Error("Workspace resolution did not return a workspaceId.");
+    let selection = await selectWorkspaceTarget(cwd, me, flags);
+    let preparedArchives = null;
+    if (authState.authKind === "guest" && requestedMode === "standard") {
+        preparedArchives = await withLoadingIndicator("Preparing local source archive...", flags, () => prepareLocalSourceArchives({
+            client,
+            detectedSources: selection.sources,
+        }));
     }
-    const resolvedWorkspaceId = result.resolve.workspaceId;
-    const activeScan = await withLoadingIndicator("Checking for existing scans...", flags, () => findActiveWorkspaceScan(client, resolvedWorkspaceId, result.binding));
-    const forceRestart = await ensureScanRestartConfirmed(flags, activeScan);
+    const resolvedContext = await (async () => {
+        try {
+            const resolved = await withLoadingIndicator("Resolving workspace and scan plan...", flags, () => resolveWorkspaceSelectionForScan({
+                client,
+                selection,
+                authKind: authState.authKind,
+            }));
+            const result = resolved.result;
+            if (!result.resolve.workspaceId) {
+                throw new Error("Workspace resolution did not return a workspaceId.");
+            }
+            const resolvedWorkspaceId = result.resolve.workspaceId;
+            const activeScan = await withLoadingIndicator("Checking for existing scans...", flags, () => findActiveWorkspaceScan(client, resolvedWorkspaceId, result.binding));
+            const forceRestart = await ensureScanRestartConfirmed(flags, activeScan);
+            return {
+                selection: resolved.selection,
+                result,
+                resolvedWorkspaceId,
+                forceRestart,
+            };
+        }
+        catch (error) {
+            await preparedArchives?.cleanup();
+            throw error;
+        }
+    })();
+    selection = resolvedContext.selection;
+    const { result, resolvedWorkspaceId, forceRestart } = resolvedContext;
     let workspaceId = resolvedWorkspaceId;
     let scan;
     let prScanSource = null;
@@ -1105,22 +1182,28 @@ export async function commandScan(client, cwd, flags) {
         }));
     }
     else {
-        scan = await withLoadingIndicator("Starting scan...", flags, async () => {
-            const scanSources = await prepareExplicitScanSources({
-                client,
-                workspaceId: resolvedWorkspaceId,
-                plannedSources: result.resolve.plannedSources,
-                detectedSources: result.sources,
-            });
-            return client.request(`/api/cli/v2/local-workspaces/${encodeURIComponent(resolvedWorkspaceId)}/scan`, {
-                method: "POST",
-                json: {
-                    mode: requestedMode,
-                    force: forceRestart || flags.force === true,
-                    scanSources,
-                },
+        try {
+            scan = await withLoadingIndicator("Starting scan...", flags, async () => {
+                const scanSources = await prepareExplicitScanSources({
+                    client,
+                    workspaceId: resolvedWorkspaceId,
+                    plannedSources: result.resolve.plannedSources,
+                    detectedSources: result.sources,
+                    preparedArchives,
+                });
+                return client.request(`/api/cli/v2/local-workspaces/${encodeURIComponent(resolvedWorkspaceId)}/scan`, {
+                    method: "POST",
+                    json: {
+                        mode: requestedMode,
+                        force: forceRestart || flags.force === true,
+                        scanSources,
+                    },
+                });
             });
-        });
+        }
+        finally {
+            await preparedArchives?.cleanup();
+        }
     }
     const trackedScanId = getTrackedScanId(scan);
     const binding = {

package/dist/help.js

@@ -85,6 +85,8 @@ Tips:
   Trial codes go only to apex redeem. Never echo, log, save, telemeter, or send them through MCP.
   Trial redemption, claim, and revocation require https://ai.cantina.xyz and reject other APEX_BASE_URL origins before sending secrets.
   apex redeem never starts device login or opens a browser; apex claim is the only onboarding command that may open one.
+  Guest standard scans validate the local archive before reserving a workspace; apex doctor is read-only for guests.
+  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.
   Service-key commands require an existing login; run apex login first when needed.

package/dist/local-source-scan.js

@@ -317,7 +317,6 @@ async function createDeterministicArchive(params) {
         file: params.archivePath,
         gzip: true,
         portable: true,
-        noPax: true,
         mtime: FIXED_MTIME,
         follow: false,
         preservePaths: false,
@@ -343,6 +342,50 @@ async function createDeterministicArchive(params) {
         entryCount: observedArchive.entryCount,
     };
 }
+export async function prepareLocalSourceArchives(args) {
+    const capabilities = args.capabilities ?? (await fetchLocalSourceScanCapabilities(args.client));
+    if (!capabilities.localSourceScans) {
+        throw new Error("This Apex server does not support local source scans.");
+    }
+    if (args.detectedSources.length > capabilities.archive.maxSourcesPerScan) {
+        throw new Error(`This scan includes ${args.detectedSources.length} sources, but the server limit is ${capabilities.archive.maxSourcesPerScan}.`);
+    }
+    const tempDir = await mkdtemp(path.join(tmpdir(), "apex-local-source-"));
+    let cleaned = false;
+    const cleanup = async () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+    };
+    try {
+        const archivesByPath = new Map();
+        for (const [index, source] of args.detectedSources.entries()) {
+            const archivePath = path.join(tempDir, `source-${index + 1}.tar.gz`);
+            const manifest = await createDeterministicArchive({
+                source,
+                archivePath,
+                maxUncompressedBytes: capabilities.archive.maxUncompressedBytes,
+            });
+            if (manifest.compressedBytes > capabilities.archive.maxCompressedBytes) {
+                throw new Error(`Archive for ${source.displayName} exceeds the compressed upload limit.`);
+            }
+            if (manifest.uncompressedBytes > capabilities.archive.maxUncompressedBytes) {
+                throw new Error(`Archive for ${source.displayName} exceeds the uncompressed upload limit.`);
+            }
+            archivesByPath.set(source.path, { archivePath, manifest });
+        }
+        return {
+            capabilities,
+            archivesByPath,
+            cleanup,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
 export async function fetchLocalSourceScanCapabilities(client) {
     return client.request("/api/cli/v2/capabilities");
 }
@@ -369,7 +412,9 @@ async function uploadArchive(archivePath, uploadUrl, headers) {
     }
 }
 export async function prepareExplicitScanSources(args) {
-    const capabilities = await fetchLocalSourceScanCapabilities(args.client);
+    let preparation = args.preparedArchives ?? null;
+    let ownsPreparation = false;
+    const capabilities = preparation?.capabilities ?? (await fetchLocalSourceScanCapabilities(args.client));
     const localSources = args.plannedSources.filter((source) => source.sourceKind === "local_archive");
     if (args.plannedSources.length > capabilities.archive.maxSourcesPerScan) {
         throw new Error(`This scan includes ${args.plannedSources.length} sources, but the server limit is ${capabilities.archive.maxSourcesPerScan}.`);
@@ -386,37 +431,32 @@ export async function prepareExplicitScanSources(args) {
                 git: source.git,
             });
     }
-    const detectedByPath = new Map(args.detectedSources.map((source) => [source.path, source]));
-    const tempDir = await mkdtemp(path.join(tmpdir(), "apex-local-source-"));
     try {
+        if (!preparation) {
+            const localPaths = new Set(localSources.map((source) => source.path));
+            preparation = await prepareLocalSourceArchives({
+                client: args.client,
+                detectedSources: args.detectedSources.filter((source) => localPaths.has(source.path)),
+                capabilities,
+            });
+            ownsPreparation = true;
+        }
         const preparedUploads = [];
-        for (const [index, source] of localSources.entries()) {
-            const detectedSource = detectedByPath.get(source.path);
-            if (!detectedSource) {
+        for (const source of localSources) {
+            const preparedArchive = preparation.archivesByPath.get(source.path);
+            if (!preparedArchive) {
                 throw new Error(`Could not resolve local source path: ${source.path}`);
             }
-            const archivePath = path.join(tempDir, `source-${index + 1}.tar.gz`);
-            const manifest = await createDeterministicArchive({
-                source: detectedSource,
-                archivePath,
-                maxUncompressedBytes: capabilities.archive.maxUncompressedBytes,
-            });
-            if (manifest.compressedBytes > capabilities.archive.maxCompressedBytes) {
-                throw new Error(`Archive for ${source.displayName} exceeds the compressed upload limit.`);
-            }
-            if (manifest.uncompressedBytes > capabilities.archive.maxUncompressedBytes) {
-                throw new Error(`Archive for ${source.displayName} exceeds the uncompressed upload limit.`);
-            }
             preparedUploads.push({
                 plannedSource: source,
-                archivePath,
+                archivePath: preparedArchive.archivePath,
                 upload: {
                     displayName: source.displayName,
                     relativePath: source.relativePath,
                     archiveFormat: "tar.gz",
-                    sha256: manifest.sha256,
-                    compressedBytes: manifest.compressedBytes,
-                    uncompressedBytes: manifest.uncompressedBytes,
+                    sha256: preparedArchive.manifest.sha256,
+                    compressedBytes: preparedArchive.manifest.compressedBytes,
+                    uncompressedBytes: preparedArchive.manifest.uncompressedBytes,
                     git: source.git,
                 },
             });
@@ -475,6 +515,8 @@ export async function prepareExplicitScanSources(args) {
         });
     }
     finally {
-        await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+        if (ownsPreparation) {
+            await preparation?.cleanup();
+        }
     }
 }

package/dist/mcp.js

@@ -31,7 +31,9 @@ Notes:
 - 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 an MCP prompt or tool call.
 - HTTP-only serverless and cron integrations should use the hosted API documented at https://ai.cantina.xyz/docs/apex-api instead of launching this stdio server.
 - Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias. Use mode "lite" only for beta-enabled provider-backed Lite scans, and mode "pr" for GitHub pull request scans.
-- Doctor reports whether Apex will use remote materialization or a local snapshot upload for each source.`;
+- Doctor is read-only for guest sessions and reports the local snapshot plan without reserving a workspace.
+- Guest standard scans validate the complete local archive before resolving or reserving a workspace. For an unbound renamed checkout, Apex may recover only the sole empty guest workspace when no explicit workspace name was supplied.
+- When terminal redemption returns JSON, parse stdout only and keep stderr warnings separate. An idempotent outcome resumes the existing guest session, which may already own a workspace.`;
 const WORKSPACE_BINDING_ERROR = "This directory is not bound to an Apex workspace yet. Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";
 const MISSING_PROVIDER_CONNECTIONS_ERROR = "Missing provider connections. Re-run interactively or pre-connect providers.";
 const PR_MISSING_PROVIDER_CONNECTIONS_ERROR_PREFIX = "PR scans require connected provider access for ";

package/dist/session.js

@@ -61,17 +61,31 @@ export async function chooseCompany(me, flags, binding, options = {}) {
 async function chooseWorkspaceName(cwd, flags, binding) {
     const explicit = getFlagString(flags, "workspace-name");
     if (explicit) {
-        return explicit;
+        return {
+            workspaceName: explicit,
+            wasExplicitlyChosen: true,
+        };
     }
     if (binding?.workspaceName) {
-        return binding.workspaceName;
+        return {
+            workspaceName: binding.workspaceName,
+            wasExplicitlyChosen: false,
+        };
     }
     const suggested = path.basename(cwd);
     if (!canPromptInteractively(flags)) {
-        return suggested;
+        return {
+            workspaceName: suggested,
+            wasExplicitlyChosen: false,
+        };
     }
     const chosen = await promptText("Workspace name to use in Apex for this directory (press Enter to use the current folder name)", suggested);
-    return chosen.trim().length > 0 ? chosen.trim() : suggested;
+    return {
+        workspaceName: chosen.trim().length > 0 ? chosen.trim() : suggested,
+        // Accepting a value through the prompt is an explicit choice even when the
+        // user keeps the suggested folder name.
+        wasExplicitlyChosen: true,
+    };
 }
 function selectBindingForWorkspaceName(flags, binding, workspaceName) {
     const explicit = getFlagString(flags, "workspace-name");
@@ -132,6 +146,23 @@ function ensurePlannedSources(selection, resolve) {
         plannedSources: selection.sources.map((source) => buildFallbackLocalArchivePlan(source, selection.sourceMode)),
     };
 }
+export function planGuestWorkspaceSelection(selection) {
+    if (selection.sourceMode === "remote") {
+        throw new Error("Guest trials require local snapshot uploads. Remove `--source-mode remote` and retry.");
+    }
+    return {
+        company: selection.company,
+        workspaceName: selection.workspaceName,
+        binding: selection.binding,
+        sources: selection.sources,
+        legacyRepositories: selection.legacyRepositories,
+        resolve: {
+            workspaceId: selection.binding?.workspaceId ?? null,
+            workspaceCreated: false,
+            plannedSources: selection.sources.map((source) => buildFallbackLocalArchivePlan(source, selection.sourceMode)),
+        },
+    };
+}
 export async function ensureAuthenticated(client, flags) {
     const existing = await getMe(client);
     if (existing) {
@@ -153,7 +184,8 @@ export async function resolveWorkspace(client, cwd, me, flags) {
 export async function selectWorkspaceTarget(cwd, me, flags) {
     const loadedBinding = await loadWorkspaceBinding(cwd);
     const company = await chooseCompany(me, flags, loadedBinding);
-    const workspaceName = await chooseWorkspaceName(cwd, flags, loadedBinding);
+    const workspaceNameSelection = await chooseWorkspaceName(cwd, flags, loadedBinding);
+    const workspaceName = workspaceNameSelection.workspaceName;
     const binding = selectBindingForWorkspaceName(flags, loadedBinding, workspaceName);
     const sourceSelection = getFlagList(flags, "repo");
     const discovered = await discoverSources(cwd, sourceSelection);
@@ -163,6 +195,7 @@ export async function selectWorkspaceTarget(cwd, me, flags) {
     return {
         company,
         workspaceName,
+        workspaceNameWasExplicitlyChosen: workspaceNameSelection.wasExplicitlyChosen,
         binding,
         sources: discovered.sources,
         legacyRepositories: extractLegacyRepositories(discovered.sources),

package/dist/setup.js

@@ -55,6 +55,20 @@ async function tryExecText(command, args, cwd) {
         return null;
     }
 }
+function isUnknownClaudeScopeOption(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const processError = error;
+    const output = [
+        processError.message,
+        processError.stdout,
+        processError.stderr,
+    ]
+        .filter((value) => typeof value === "string")
+        .join("\n");
+    return /(?:unknown|unrecognized) option(?::)?\s+['"]?--scope['"]?/i.test(output);
+}
 async function resolveMcpLaunchSpec(packageRoot = PACKAGE_ROOT) {
     const repoLocalBinary = path.join(packageRoot, "bin", "apex-mcp");
     if ((await pathExists(path.join(packageRoot, ".git"))) &&
@@ -315,35 +329,52 @@ async function configureClaude(cwd, launch) {
     const existing = await readClaudeUserMcpConfig();
     const env = mcpClientEnv("claude");
     const supportsUserScope = await claudeSupportsUserScope();
+    let usedConfigFallback = supportsUserScope === false;
     const mcpStatus = existing === null
         ? "installed"
         : claudeConfigMatches(existing, launch)
             ? "unchanged"
             : "updated";
-    if (supportsUserScope === false) {
-        // Older Claude Code releases reject --scope. Merge the same stdio
-        // registration into the user config while preserving all other settings.
+    if (usedConfigFallback) {
         await writeClaudeUserMcpConfig(launch);
     }
     else {
-        if (existing) {
-            await execText("claude", ["mcp", "remove", "--scope", "user", MCP_SERVER_NAME]);
+        try {
+            if (existing) {
+                await execText("claude", [
+                    "mcp",
+                    "remove",
+                    MCP_SERVER_NAME,
+                    "--scope",
+                    "user",
+                ]);
+            }
+            // Keep the server name before `--`, which separates Claude options from
+            // the stdio command and its arguments.
+            await execText("claude", [
+                "mcp",
+                "add",
+                MCP_SERVER_NAME,
+                "--scope",
+                "user",
+                "-e",
+                `${MCP_CLIENT_ENV_NAME}=${env[MCP_CLIENT_ENV_NAME]}`,
+                "-e",
+                `${MCP_CLIENT_INTEGRATION_ENV_NAME}=${env[MCP_CLIENT_INTEGRATION_ENV_NAME]}`,
+                "--",
+                launch.command,
+                ...launch.args,
+            ]);
+        }
+        catch (error) {
+            if (!isUnknownClaudeScopeOption(error)) {
+                throw error;
+            }
+            // Some Claude Code builds advertise --scope in help but reject it when
+            // the command runs. Preserve the user-level registration directly.
+            await writeClaudeUserMcpConfig(launch);
+            usedConfigFallback = true;
         }
-        // Claude's variadic --env option consumes later tokens until `--`.
-        await execText("claude", [
-            "mcp",
-            "add",
-            "--scope",
-            "user",
-            "-e",
-            `${MCP_CLIENT_ENV_NAME}=${env[MCP_CLIENT_ENV_NAME]}`,
-            "-e",
-            `${MCP_CLIENT_INTEGRATION_ENV_NAME}=${env[MCP_CLIENT_INTEGRATION_ENV_NAME]}`,
-            "--",
-            MCP_SERVER_NAME,
-            launch.command,
-            ...launch.args,
-        ]);
     }
     const skillSource = path.join(PACKAGE_ROOT, ".claude", "skills", CODEX_SKILL_NAME, "SKILL.md");
     const skillTarget = path.join(cwd, ".claude", "skills", CODEX_SKILL_NAME, "SKILL.md");
@@ -355,8 +386,8 @@ async function configureClaude(cwd, launch) {
             kind: "mcp",
             status: mcpStatus,
             path: path.join(os.homedir(), ".claude.json"),
-            detail: supportsUserScope === false
-                ? `Registered ${MCP_SERVER_NAME} -> ${launch.label} in Claude Code user config (legacy CLI compatibility)`
+            detail: usedConfigFallback
+                ? `Registered ${MCP_SERVER_NAME} -> ${launch.label} in Claude Code user config (CLI compatibility fallback)`
                 : `Registered ${MCP_SERVER_NAME} -> ${launch.label} in Claude Code user config`,
         },
         {

package/package.json

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

package/skills/apex-cli/SKILL.md

@@ -27,7 +27,9 @@ than one recovery retry. Treat the code as a secret: pass it only to
 or tool result. Trial redemption, claim, and revocation are hosted-only; stop
 before passing the code when `APEX_BASE_URL` has any origin other than
 `https://ai.cantina.xyz`. Stop if the redeem outcome is not `redeemed` or
-`idempotent`.
+`idempotent`. Parse the JSON from stdout only; do not merge stderr into stdout,
+because npm may write warnings to stderr. `idempotent` means the existing guest
+session resumed and it may already own a workspace.
 
 Workflow:
 
@@ -47,6 +49,7 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 
 - Prefer scripted commands over the interactive shell.
 - A trial redeem with an ambiguous transport or response-loss failure may be retried exactly once with the same code, machine, HOME, and repository root. Never retry a typed server rejection or use `--replace` for response-loss recovery.
+- Guest standard scans validate the complete local archive before resolving or reserving a workspace. For an unbound renamed checkout, Apex may recover only the sole empty guest workspace when no explicit workspace name was supplied.
 - 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.
 - `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.
@@ -64,7 +67,7 @@ Guidelines:
 - Hosted 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 scan, use a new key.
 - `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` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
+- `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 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 or GitLab sources.
 - Lite scans use `mode: "lite"`, require Lite Scan beta access, and require provider-backed GitHub or GitLab sources without local snapshot fallback.