@cantinasecurity/apex-cli 0.1.17 → 0.1.19

package/dist/local-source-scan.js

@@ -8,6 +8,8 @@ import { promisify } from "node:util";
 import ignore from "ignore";
 import * as tar from "tar";
 const execFileAsync = promisify(execFile);
+const MAX_ARCHIVE_ENTRIES = 100_000;
+const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
 const BUILTIN_IGNORE_PATTERNS = [
     ".git",
     ".git/**",
@@ -33,21 +35,76 @@ const BUILTIN_IGNORE_PATTERNS = [
 const FIXED_MTIME = new Date(0);
 async function runGit(cwd, args) {
     const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
-        encoding: "utf8",
+        encoding: "buffer",
+        // The 100k-entry archive limit can legitimately exceed Node's 1 MiB
+        // execFile default. Keep the inventory bounded without rejecting ordinary
+        // monorepos before the entry-count guard can inspect them.
+        maxBuffer: MAX_GIT_OUTPUT_BYTES,
+        env: {
+            ...process.env,
+            // Git's stable English diagnostics let us distinguish a directory that
+            // is positively no longer a worktree from every other command failure.
+            LANG: "C",
+            LC_ALL: "C",
+        },
     });
-    return stdout;
+    return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
 }
-function buildIgnoreMatcher(rootPath) {
+const strictUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
+function decodeUtf8Path(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return strictUtf8Decoder.decode(value);
+    }
+    catch {
+        throw new Error("Apex cannot archive a filename that is not valid UTF-8. Rename the entry and retry.");
+    }
+}
+function decodeNullSeparatedGitEntries(output) {
+    const entries = [];
+    let start = 0;
+    for (let index = 0; index <= output.length; index += 1) {
+        if (index < output.length && output[index] !== 0)
+            continue;
+        if (index > start) {
+            entries.push(decodeUtf8Path(output.subarray(start, index)));
+            if (entries.length > MAX_ARCHIVE_ENTRIES) {
+                throw new Error(`Apex local snapshots support at most ${MAX_ARCHIVE_ENTRIES.toLocaleString()} entries per source.`);
+            }
+        }
+        start = index + 1;
+    }
+    return entries;
+}
+async function buildIgnoreMatcher(rootPath) {
     const matcher = ignore().add(BUILTIN_IGNORE_PATTERNS);
-    return readFile(path.join(rootPath, ".apexignore"), "utf8")
-        .then((contents) => {
-        matcher.add(contents);
-        return matcher;
-    })
-        .catch(() => matcher);
+    try {
+        const contents = await readFile(path.join(rootPath, ".apexignore"));
+        let decoded;
+        try {
+            decoded = strictUtf8Decoder.decode(contents);
+        }
+        catch {
+            throw new Error(".apexignore is not valid UTF-8.");
+        }
+        matcher.add(decoded);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw new Error("Apex could not read .apexignore. Fix or remove it before scanning.", { cause: error });
+        }
+    }
+    return matcher;
 }
 function normalizeRelativeEntry(entryPath) {
-    return entryPath.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+    const normalizedSeparators = path.sep === "\\"
+        ? entryPath.replace(/\\/g, "/")
+        : entryPath;
+    return normalizedSeparators.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function compareArchivePaths(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
 }
 function ensureEntryWithinRoot(rootPath, relativePath, targetPath) {
     if (path.isAbsolute(targetPath)) {
@@ -61,22 +118,83 @@ function ensureEntryWithinRoot(rootPath, relativePath, targetPath) {
         throw new Error(`Refusing to archive path-escaping symlink in ${relativePath}`);
     }
 }
+async function hasGitMetadataAtOrAbove(rootPath) {
+    let currentPath = path.resolve(rootPath);
+    while (true) {
+        try {
+            await lstat(path.join(currentPath, ".git"));
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath)
+            return false;
+        currentPath = parentPath;
+    }
+}
 async function collectGitEntries(rootPath) {
-    const output = await runGit(rootPath, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]).catch(() => "");
-    return output
-        .split("\0")
+    // Source discovery intentionally keeps a nested worktree directory as a
+    // local archive. Detect enclosing Git metadata here so the archive still
+    // honors ignore rules inherited from the worktree root.
+    if (!(await hasGitMetadataAtOrAbove(rootPath))) {
+        return null;
+    }
+    try {
+        const worktreeState = decodeUtf8Path(await runGit(rootPath, ["rev-parse", "--is-inside-work-tree"])).trim();
+        if (worktreeState !== "true") {
+            throw new Error("The planned Git source is not a working tree.");
+        }
+    }
+    catch (error) {
+        // Once Git metadata is present, executable, permissions, ownership,
+        // corrupt metadata, and other failures must fail closed so ignored files
+        // cannot enter a raw directory fallback.
+        throw new Error("Apex could not verify the planned Git source. Fix the Git worktree and retry.", { cause: error });
+    }
+    let output;
+    try {
+        output = await runGit(rootPath, [
+            "ls-files",
+            "--cached",
+            "--others",
+            "--exclude-standard",
+            "-z",
+        ]);
+    }
+    catch (error) {
+        throw new Error("Apex could not inventory the Git source without risking ignored files. Fix the Git worktree and retry.", { cause: error });
+    }
+    // Decode after the command-error fallback so invalid Unix filename bytes
+    // fail explicitly instead of being replacement-decoded and silently lost.
+    return decodeNullSeparatedGitEntries(output)
         .map((entry) => normalizeRelativeEntry(entry))
         .filter((entry) => entry.length > 0);
 }
-async function collectDirectoryEntries(rootPath) {
+async function collectDirectoryEntries(rootPath, matcher) {
     const entries = [];
+    let visitedEntryCount = 0;
     async function walk(currentPath) {
-        const children = await readdir(currentPath, { withFileTypes: true });
+        const children = await readdir(currentPath, {
+            withFileTypes: true,
+            encoding: "buffer",
+        });
         for (const child of children) {
-            const childPath = path.join(currentPath, child.name);
+            const childName = decodeUtf8Path(child.name);
+            const childPath = path.join(currentPath, childName);
             const relativePath = normalizeRelativeEntry(path.relative(rootPath, childPath));
             if (!relativePath)
                 continue;
+            if (matcher.ignores(relativePath) || matcher.ignores(`${relativePath}/`)) {
+                continue;
+            }
+            visitedEntryCount += 1;
+            if (visitedEntryCount > MAX_ARCHIVE_ENTRIES) {
+                throw new Error(`Apex local snapshots support at most ${MAX_ARCHIVE_ENTRIES.toLocaleString()} entries per source.`);
+            }
             if (child.isDirectory()) {
                 entries.push(relativePath);
                 await walk(childPath);
@@ -90,12 +208,12 @@ async function collectDirectoryEntries(rootPath) {
 }
 async function collectArchiveEntries(source) {
     const matcher = await buildIgnoreMatcher(source.absolutePath);
-    const rawEntries = source.kind === "git_candidate"
-        ? await collectGitEntries(source.absolutePath)
-        : await collectDirectoryEntries(source.absolutePath);
+    const gitEntries = await collectGitEntries(source.absolutePath);
+    const rawEntries = gitEntries ??
+        await collectDirectoryEntries(source.absolutePath, matcher);
     const fileEntries = new Set();
     let uncompressedBytes = 0;
-    for (const entry of rawEntries.sort((left, right) => left.localeCompare(right))) {
+    for (const entry of rawEntries.sort(compareArchivePaths)) {
         if (!entry)
             continue;
         if (matcher.ignores(entry) || matcher.ignores(`${entry}/`))
@@ -108,7 +226,7 @@ async function collectArchiveEntries(source) {
             continue;
         }
         if (entryStats.isSymbolicLink()) {
-            const target = await readlink(absoluteEntryPath);
+            const target = decodeUtf8Path(await readlink(absoluteEntryPath, { encoding: "buffer" }));
             ensureEntryWithinRoot(source.absolutePath, entry, target);
             fileEntries.add(entry);
             uncompressedBytes += Buffer.byteLength(target);
@@ -121,7 +239,7 @@ async function collectArchiveEntries(source) {
         uncompressedBytes += entryStats.size;
     }
     return {
-        files: Array.from(fileEntries).sort((left, right) => left.localeCompare(right)),
+        files: Array.from(fileEntries).sort(compareArchivePaths),
         uncompressedBytes,
     };
 }
@@ -138,10 +256,62 @@ async function createArchiveManifest(archivePath) {
         sha256: hash.digest("hex"),
         compressedBytes: archiveStats.size,
         uncompressedBytes: 0,
+        entryCount: 0,
     };
 }
+async function inspectCreatedArchive(archivePath, sourceRoot, expectedFiles, displayName, maxUncompressedBytes) {
+    const expectedEntries = new Set(expectedFiles);
+    const observedEntries = new Set();
+    let entryCount = 0;
+    let uncompressedBytes = 0;
+    await tar.list({
+        file: archivePath,
+        onentry(entry) {
+            const entryPath = normalizeRelativeEntry(entry.path);
+            if (!entryPath ||
+                !expectedEntries.has(entryPath) ||
+                observedEntries.has(entryPath) ||
+                !["File", "OldFile", "ContiguousFile", "SymbolicLink", "Link"].includes(entry.type)) {
+                throw new Error(`Archive for ${displayName} changed while it was being prepared.`);
+            }
+            if (entry.type === "SymbolicLink") {
+                if (!entry.linkpath) {
+                    throw new Error(`Archive for ${displayName} changed while it was being prepared.`);
+                }
+                ensureEntryWithinRoot(sourceRoot, entryPath, entry.linkpath);
+            }
+            else if (entry.type === "Link") {
+                const linkedEntry = normalizeRelativeEntry(entry.linkpath ?? "");
+                if (!linkedEntry || !expectedEntries.has(linkedEntry)) {
+                    throw new Error(`Archive for ${displayName} changed while it was being prepared.`);
+                }
+            }
+            observedEntries.add(entryPath);
+            entryCount += 1;
+            const entrySize = Number(entry.size ?? 0);
+            if (!Number.isSafeInteger(entrySize) || entrySize < 0) {
+                throw new Error(`Archive for ${displayName} has an invalid entry size.`);
+            }
+            if (entrySize > 0) {
+                uncompressedBytes += entrySize;
+            }
+        },
+    });
+    if (observedEntries.size !== expectedEntries.size ||
+        entryCount > MAX_ARCHIVE_ENTRIES ||
+        uncompressedBytes > maxUncompressedBytes) {
+        throw new Error(`Archive for ${displayName} changed while it was being prepared and now exceeds a trial upload limit.`);
+    }
+    return { entryCount, uncompressedBytes };
+}
 async function createDeterministicArchive(params) {
     const { files, uncompressedBytes } = await collectArchiveEntries(params.source);
+    if (files.length > MAX_ARCHIVE_ENTRIES) {
+        throw new Error(`Apex local snapshots support at most ${MAX_ARCHIVE_ENTRIES.toLocaleString()} entries per source.`);
+    }
+    if (uncompressedBytes > params.maxUncompressedBytes) {
+        throw new Error(`Archive for ${params.source.displayName} exceeds the uncompressed upload limit.`);
+    }
     await tar.create({
         cwd: params.source.absolutePath,
         file: params.archivePath,
@@ -153,7 +323,10 @@ async function createDeterministicArchive(params) {
         preservePaths: false,
         jobs: 1,
         sync: false,
-        noDirRecurse: false,
+        // The inventory contains files and symlinks only. If one is replaced by
+        // a directory while the archive is built, never recurse into content
+        // that was not reviewed against the ignore rules and upload limits.
+        noDirRecurse: true,
         onWriteEntry(entry) {
             entry.mtime = FIXED_MTIME;
             entry.uid = 0;
@@ -162,10 +335,12 @@ async function createDeterministicArchive(params) {
             entry.gname = "root";
         },
     }, files);
+    const observedArchive = await inspectCreatedArchive(params.archivePath, params.source.absolutePath, files, params.source.displayName, params.maxUncompressedBytes);
     const manifest = await createArchiveManifest(params.archivePath);
     return {
         ...manifest,
-        uncompressedBytes,
+        uncompressedBytes: observedArchive.uncompressedBytes,
+        entryCount: observedArchive.entryCount,
     };
 }
 export async function fetchLocalSourceScanCapabilities(client) {
@@ -224,6 +399,7 @@ export async function prepareExplicitScanSources(args) {
             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.`);

package/dist/mcp.js

@@ -2,23 +2,27 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import path from "node:path";
 import { z } from "zod";
-import { getMe, logout, startDeviceLogin, waitForDeviceLoginApproval } from "./auth.js";
+import { getMe, logout, readStableDeviceLoginState, startDeviceLogin, waitForDeviceLoginApproval, } from "./auth.js";
 import { ApexApiClient, formatApiError } from "./api-client.js";
+import { getClaimProofState, isClaimProofAvailable, } from "./claim-proof.js";
 import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
+import { getLocalTrialStatus, isProofOnlyOnboardingCredentials, revokeGuestOnboardingSession, } from "./onboarding.js";
 import { createMcpServerTelemetryInvocation, createMcpTelemetryInvocation, emitInvocationCompleted, emitInvocationStarted, emitMcpServerStarted, withTelemetryContext, } from "./telemetry.js";
 import { APEX_CLI_VERSION } from "./version.js";
 const MCP_WORKFLOW_GUIDE = `Use Apex through these tools instead of shelling out to the CLI.
 
 Suggested workflow:
 1. Call apex-auth-status.
-2. If unauthenticated, call apex-auth-start and ask the user to approve the device login URL, then call apex-auth-wait.
-3. Call apex-doctor for the target repository cwd.
-4. If the directory is not bound to the right workspace, call apex-workspaces and apex-workspace-use.
-5. Start and monitor scans with apex-scan, apex-status, apex-scans, apex-findings, and apex-export-findings.
-6. For PR scans, call apex-scan with mode "pr" and one or more pullRequests.
-7. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
-8. To review a fix, call apex-finding-fix-review. Pass fixPrUrls for PR-based fix reviews, or omit them to review the current repository state when Bedrock has original scan repository context.
+2. Always call apex-trial-status next, even when account authentication succeeded. If claimAvailable is true, run \`apex claim\` in a terminal before starting another login or continuing with account work. If the claim deadline passed and claimAvailable is false, continue normal account authentication instead of steering to an expired claim.
+3. 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.
+4. Only when Apex is unauthenticated and no unexpired claim proof or trial code is available, call apex-auth-start and ask the user to approve the device login URL, then call apex-auth-wait with both the returned deviceCode and credentialGeneration.
+5. Call apex-doctor for the target repository cwd.
+6. If the directory is not bound to the right workspace, call apex-workspaces and apex-workspace-use.
+7. Start and monitor scans with apex-scan, apex-status, apex-scans, apex-findings, and apex-export-findings.
+8. For PR scans, call apex-scan with mode "pr" and one or more pullRequests.
+9. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
+10. To review a fix, call apex-finding-fix-review. Pass fixPrUrls for PR-based fix reviews, or omit them to review the current repository state when Bedrock has original scan repository context.
 
 Notes:
 - Pass cwd explicitly for repository-specific operations.
@@ -166,7 +170,11 @@ async function runTool(toolName, action, summary, input = {}) {
 async function requireAuthenticated(client) {
     const me = await getMe(client);
     if (!me) {
-        throw new Error("Not authenticated. Call `apex-auth-start`, ask the user to approve the device login, then call `apex-auth-wait`.");
+        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("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`.");
     }
     return me;
 }
@@ -210,30 +218,82 @@ function registerTools(server) {
             me,
         };
     }, (value) => (value.authenticated ? "Apex is authenticated." : "Apex is not authenticated.")));
+    server.registerTool("apex-trial-status", {
+        title: "Apex Trial Status",
+        description: "Read locally stored guest-trial status and deadlines without returning the claim token or requiring an authenticated API request.",
+    }, async () => runTool("apex-trial-status", async () => {
+        const client = new ApexApiClient();
+        return getLocalTrialStatus(await client.getCredentials());
+    }, (value) => value.guest || value.claimAvailable
+        ? "Local Apex guest-trial metadata loaded."
+        : "No local Apex guest trial is active."));
     server.registerTool("apex-auth-start", {
         title: "Start Apex Device Login",
-        description: "Start the Apex device login flow and return the verification URL and user code. This tool never opens a browser.",
+        description: "Start the Apex device login flow and return the verification URL and user code, unless a local trial claim proof requires `apex claim` first. This tool never opens a browser.",
     }, async () => runTool("apex-auth-start", async () => {
         const client = new ApexApiClient();
+        const loginState = await readStableDeviceLoginState(client);
+        const { me, credentials, credentialGeneration } = loginState;
+        if (me?.user.role?.trim().toLowerCase() === "guest") {
+            const claimState = getClaimProofState(credentials);
+            if (claimState !== "expired") {
+                return {
+                    authenticated: true,
+                    guestTrialActive: true,
+                    claimAvailable: claimState === "available",
+                    loginStarted: false,
+                    warning: claimState === "available"
+                        ? "An active guest trial is already authenticated. Do not start device login; finish the scan and run `apex claim` in a terminal."
+                        : "An active guest trial is already authenticated, but its local claim proof is missing. Do not start device login; run `apex redeem <code>` again on this machine to restore the proof before claiming.",
+                };
+            }
+        }
+        if (isClaimProofAvailable(credentials)) {
+            return {
+                authenticated: Boolean(me),
+                claimAvailable: true,
+                loginStarted: false,
+                warning: "A local guest-trial claim proof is available. Do not start another device login; run `apex claim` in a terminal first to keep the trial workspace, scans, and findings.",
+            };
+        }
+        if (me && me.user.role?.trim().toLowerCase() !== "guest") {
+            return {
+                authenticated: true,
+                guestTrialActive: false,
+                loginStarted: false,
+                warning: "A Cantina account is already authenticated.",
+            };
+        }
         const login = await startDeviceLogin(client);
         return {
             authenticated: false,
+            credentialGeneration,
             ...login,
         };
-    }, () => "Device login started. Ask the user to open the verification URL and enter the code."));
+    }, (value) => value.guestTrialActive
+        ? String(value.warning)
+        : value.claimAvailable
+            ? String(value.warning)
+            : value.authenticated
+                ? String(value.warning)
+                : "Device login started. Ask the user to open the verification URL and enter the code."));
     server.registerTool("apex-auth-wait", {
         title: "Wait For Apex Login Approval",
-        description: "Poll a previously started Apex device login until it is approved, still pending, or expired.",
+        description: "Poll a previously started Apex device login until it is approved, still pending, expired, or superseded. Pass the opaque credential generation returned by apex-auth-start.",
         inputSchema: {
             deviceCode: z.string().min(1),
+            credentialGeneration: z
+                .string()
+                .regex(/^v1:[0-9a-f]{64}$/),
             intervalSeconds: z.number().int().nonnegative().optional(),
             expiresAt: z.string().optional(),
             timeoutSeconds: z.number().int().positive().max(1800).optional(),
         },
-    }, async ({ deviceCode, intervalSeconds, expiresAt, timeoutSeconds }) => runTool("apex-auth-wait", async () => {
+    }, async ({ deviceCode, credentialGeneration, intervalSeconds, expiresAt, timeoutSeconds, }) => runTool("apex-auth-wait", async () => {
         const client = new ApexApiClient();
         const result = await waitForDeviceLoginApproval(client, {
             deviceCode,
+            credentialGeneration: credentialGeneration,
             intervalSeconds,
             expiresAt: expiresAt ?? null,
             timeoutMs: timeoutSeconds ? timeoutSeconds * 1000 : undefined,
@@ -249,16 +309,64 @@ function registerTools(server) {
         if (value.status === "expired") {
             return "Device login expired before approval.";
         }
+        if (value.status === "superseded") {
+            if (value.reason === "credential_operation_busy") {
+                return "Device login was approved, but another Apex credential operation was still in progress. Nothing was overwritten; check auth status after it finishes.";
+            }
+            return value.approvalReceived
+                ? "Device login was approved, but the current Apex credential state was kept instead. Check auth status before retrying."
+                : "Device login was superseded by a changed Apex credential state before polling. Check auth status before retrying.";
+        }
         return "Device login is still pending.";
     }, { deviceCode, intervalSeconds, expiresAt, timeoutSeconds }));
     server.registerTool("apex-logout", {
         title: "Log Out Of Apex",
-        description: "Clear the locally stored Apex session.",
-    }, async () => runTool("apex-logout", async () => {
-        const client = new ApexApiClient();
-        await logout(client);
-        return { ok: true };
-    }, () => "Logged out of Apex."));
+        description: "Clear the local Apex session. Guest trials require explicit confirmation because logout revokes the trial and queues unclaimed data for deletion.",
+        inputSchema: {
+            confirmGuestRevocation: z.boolean().optional(),
+        },
+    }, async (input) => {
+        const confirmGuestRevocation = input?.confirmGuestRevocation;
+        return runTool("apex-logout", async () => {
+            const client = new ApexApiClient();
+            const credentials = await client.getCredentials();
+            const proofOnly = isProofOnlyOnboardingCredentials(credentials);
+            const hasGuestLifecycle = credentials?.guest === true || proofOnly;
+            if (hasGuestLifecycle && confirmGuestRevocation !== true) {
+                return {
+                    ok: false,
+                    guestTrialRevoked: false,
+                    confirmationRequired: true,
+                    warning: "Guest logout is destructive: it revokes the trial and queues all unclaimed source, scans, and findings for deletion. Call again with confirmGuestRevocation=true only after the user confirms.",
+                };
+            }
+            const guestTrialRevoked = hasGuestLifecycle
+                ? await revokeGuestOnboardingSession(client, {
+                    clearLocalOnTerminal: true,
+                    expectedCredentials: credentials ?? undefined,
+                })
+                : false;
+            if (!hasGuestLifecycle) {
+                await logout(client, credentials);
+            }
+            return {
+                ok: true,
+                guestTrialRevoked,
+                ...(hasGuestLifecycle && !guestTrialRevoked
+                    ? { serverRevocationUnavailable: true }
+                    : {}),
+                proofOnly,
+            };
+        }, (value) => value.confirmationRequired
+            ? String(value.warning)
+            : value.guestTrialRevoked
+                ? "Guest trial revoked; unclaimed trial data is queued for deletion."
+                : value.serverRevocationUnavailable
+                    ? value.proofOnly
+                        ? "Guest trial proof cleared locally, but server revocation could not be confirmed."
+                        : "Guest access cleared locally, but the terminal server session could not be revoked."
+                    : "Logged out of Apex.");
+    });
     server.registerTool("apex-doctor", {
         title: "Run Apex Doctor",
         description: "Validate auth, local source detection, workspace binding, and the planned remote-vs-local materialization strategy.",
@@ -686,4 +794,5 @@ export const testing = {
     requireAuthenticated,
     resolveCwd,
     runTool,
+    workflowGuide: MCP_WORKFLOW_GUIDE,
 };