@counterfact-labs/cli 0.2.5 → 0.2.6

package/bundle/client-release.json

@@ -1,7 +1,7 @@
 {
   "verificationKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAbBab1PYdmBKXxCvoJ47toJhQvxPevo9nlZnb0zbDWoc=\n-----END PUBLIC KEY-----\n",
   "relayVersion": "relay-1.0.1",
-  "localVersion": "0.2.5",
+  "localVersion": "0.2.6",
   "relayUrl": "https://relay.counterfactlabs.com:8443",
   "projectContext": "checks"
 }

package/dist/cli/agent-folder.js

@@ -1,5 +1,5 @@
 import { resolveFolderPath } from "../adapters/folder-path.js";
-import { START_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
+import { CliRefusalError } from "../contract/cli-refusals.js";
 import { isAbsolute, parse, relative, resolve, sep } from "node:path";
 export function resolveAgentFolder(path, cwd) {
     return resolve(cwd ?? process.cwd(), path);
@@ -8,10 +8,10 @@ export function resolveAgentFolder(path, cwd) {
 export async function resolveMcpAgentFolder(path, cwd, homeDir) {
     const [folder, launch, home] = await Promise.all([
         resolveFolderPath(resolveAgentFolder(path, cwd)), resolveFolderPath(cwd), resolveFolderPath(homeDir),
-    ]).catch(() => { throw new Error(START_FAILURE_MESSAGE); });
+    ]).catch(() => { throw new CliRefusalError("folder_unavailable"); });
     const rel = relative(launch, folder);
     if (folder === parse(folder).root || folder === home || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-        throw new Error(START_FAILURE_MESSAGE);
+        throw new CliRefusalError("outside_project");
     }
     return folder;
 }

package/dist/cli/commands/analyze.js

@@ -56,10 +56,10 @@ export async function analyze(path, options, ctx) {
     const development = startup.transport.CF_RELAY_DEV === "1" ? await loadDevelopmentRelay(startup.transport) : undefined;
     const release = development?.release ?? ctx.relayRuntime?.release ?? await loadInstalledRelease();
     if (release.projectContext !== "checks")
-        throw new Error(unavailable);
+        throw new ApiError(503, "unavailable", unavailable);
     const token = await ctx.token?.();
     if (!token)
-        throw new Error("Not signed in. Run counterfact-labs login.");
+        throw new ApiError(401, "unauthorized", cliApiMessages.unauthorized);
     const folder = resolveAgentFolder(path, ctx.cwd);
     const config = Object.freeze({ ...startup.transport, CF_RELAY_URL: startup.transport.CF_RELAY_URL ?? release.relayUrl,
         CF_LOCAL_RELAY: "1", CF_CONSOLE_URL: ctx.api.baseUrl, CF_CONSOLE_TOKEN: token });
@@ -86,6 +86,7 @@ export async function analyze(path, options, ctx) {
                 }
             },
             onError: failure => {
+                ctx.onCheckFailure?.(failure);
                 if (failure.agentChoice)
                     ctx.onAgentChoice?.(failure.agentChoice);
                 clearProgress();

package/dist/cli/commands/balance.js

@@ -1,6 +1,9 @@
 import { money } from "../output.js";
-export async function balance(ctx) {
-    const value = await ctx.api.request("balance");
-    ctx.write(`Balance: ${money(value.balanceMicro)}\nTop up: ${value.topUpUrl}\n`);
+export async function balance(ctx, options = {}) {
+    const response = await ctx.api.request("balance");
+    const value = { ...response, freeAnalysisAvailable: response.freeAnalysisAvailable ?? false };
+    options.onLoaded?.(value);
+    const freeAnalysis = value.freeAnalysisAvailable ? "Your first analysis is free.\n" : "";
+    ctx.write(`Balance: ${money(value.balanceMicro)}\n${freeAnalysis}Top up: ${value.topUpUrl}\n`);
     return 0;
 }

package/dist/cli/context.js

@@ -16,8 +16,10 @@ export function commandContext(options = {}) {
     const findingSettings = options.findingSettings ?? readFindingSettings(options.env);
     return {
         findingNumbers: findingSettings.numbersEnabled,
+        signInRetry: (options.env ?? process.env).CF_SIGN_IN_RETRY !== "0",
         startup, signal: options.signal, relayRuntime: options.relayRuntime, cwd: options.cwd ?? process.cwd(),
         token: () => readCredentials(homeDir, api.baseUrl), onCheckComplete: options.onCheckComplete, onCheckStart: options.onCheckStart, onAgentChoice: options.onAgentChoice,
+        onCheckFailure: options.onCheckFailure,
         api, homeDir, write, openBrowser: options.openBrowser ?? openBrowser,
         signInInput: options.signInInput ?? terminalSignInInput(), readEmail: options.readEmail ?? userEmail,
         sleep: options.sleep ?? (async (ms) => { await delay(ms, undefined, { signal: options.signal }); }), now: options.now ?? Date.now,

package/dist/cli/mcp-failure.js

@@ -0,0 +1,8 @@
+import { CliRefusalError, failureReason, START_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
+import { errorText } from "./api.js";
+export function mcpFailure(error, enabled) {
+    // Only outside_project changed its sentence; the other local refusals already use the old sentences.
+    const message = !enabled && error instanceof CliRefusalError && error.code === "outside_project" ? START_FAILURE_MESSAGE
+        : errorText(error);
+    return { message, ...(enabled ? { reason: failureReason(error) } : {}) };
+}

package/dist/cli/mcp.js

@@ -1,15 +1,16 @@
 import { createInterface } from "node:readline";
 import { once } from "node:events";
 import { resolveFolderPath } from "../adapters/folder-path.js";
-import { FINISH_FAILURE_MESSAGE, START_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
-import { errorCode, errorText } from "./api.js";
+import { CliRefusalError, failureReason } from "../contract/cli-refusals.js";
+import { mcpFailure } from "./mcp-failure.js";
+import { errorCode } from "./api.js";
 import { commandContext } from "./context.js";
 import { analyze } from "./commands/analyze.js";
 import { CLI_VERSION } from "../contract/cli-version.js";
 import { finding } from "./commands/finding.js";
 import { balance } from "./commands/balance.js";
 import { ANALYZE_TOOL_NAME, analyzeToolAllowed } from "./claude-code-permission.js";
-import { signInStatus, startSignIn } from "./sign-in.js";
+import { signInStatus, startSignIn, waitForSignIn, SignInExpiredError, SignInDeniedError } from "./sign-in.js";
 import { readEmailSignIn } from "../adapters/settings.js";
 import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
 import { EMAIL_SIGN_IN_TERMS, normalizeSignInEmail, validSignInCode, startEmailSignIn, signInWithCode } from "./email-sign-in.js";
@@ -23,11 +24,11 @@ import { readFindingSettings } from "./finding-settings.js";
 const legacyTools = [
     {
         name: ANALYZE_TOOL_NAME,
-        description: "Analyze the agent in a folder on this computer. Each call runs one analysis and charges the user's balance, so call it only when the user asks for an analysis. After edits, suggest an analysis and wait for the user to ask. Prices are listed on the top-up page and website. If the balance doesn't cover the analysis, show the returned message and top-up link.",
+        description: "Analyze the agent in a folder on this computer. Each call runs one analysis and charges the user's balance unless a free analysis is available, so call it only when the user asks for an analysis. A free first analysis needs no top-up. After edits, suggest an analysis and wait for the user to ask. Prices are listed on the top-up page and website. If the balance doesn't cover the analysis, show the returned message and top-up link.",
         inputSchema: { type: "object", properties: { path: { type: "string", description: "The agent folder on this computer." }, proposal: { ...agentProposalInputSchema, description: "Optional: the files you believe make up the agent, with each file's role. Paths are relative to the agent folder." } }, required: ["path"], additionalProperties: false },
     },
     { name: "get_finding", description: "Get a finding's explanation, quoted lines, and suggested fixes.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false } },
-    { name: "get_balance", description: "Get the balance and top-up link.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+    { name: "get_balance", description: "Get the balance and top-up link, and whether a free first analysis is available. A free first analysis needs no top-up.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
     { name: "sign_in_status", description: "Check whether this computer is signed in to Counterfact, and whether the user has allowed the analysis tool in Claude Code. With wait: true, first wait for a sign-in started by sign_in to finish.", inputSchema: { type: "object", properties: { wait: { type: "boolean" } }, additionalProperties: false } },
     { name: "sign_in", description: "Open the Counterfact sign-in page in the user's browser. Then call sign_in_status with wait: true.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
 ];
@@ -43,6 +44,7 @@ export async function serveMcp(input, output, options = {}) {
     const audienceChoice = (options.env ?? process.env).CF_FINDING_AUDIENCE;
     const cwd = options.cwd ?? process.cwd();
     const guarded = (options.env ?? process.env).CF_MCP_PATH_GUARD !== "0";
+    const failureReasons = (options.env ?? process.env).CF_MCP_FAILURE_REASONS !== "0";
     const launch = guarded ? resolveFolderPath(cwd).catch(() => null) : Promise.resolve(cwd);
     const lastAnalysis = new Map();
     const findingSettings = readFindingSettings(options.env);
@@ -78,6 +80,7 @@ export async function serveMcp(input, output, options = {}) {
         ...tool, inputSchema: numberedFindingInputSchema,
     } : tool).concat(fixesEnabled ? fixRequestTools : []);
     let pendingSignIn;
+    let signInFailure;
     const requests = new Map();
     let queue = Promise.resolve();
     const lines = createInterface({ input, crlfDelay: Infinity });
@@ -111,6 +114,8 @@ export async function serveMcp(input, output, options = {}) {
         if (name === "sign_in_with_code" && !validSignInCode(args.code))
             throw new ProtocolError(-32602, emailSignInMessages.invalid_code);
         let text = "", exitCode = 0;
+        let reason;
+        let freeAnalysisAvailable = false;
         let agentChoice;
         let findingIds;
         let findings, projectId;
@@ -122,6 +127,7 @@ export async function serveMcp(input, output, options = {}) {
         let signIn;
         try {
             const ctx = commandContext({ ...options, env: { ...(options.env ?? process.env), CF_FINDING_AUDIENCE: audienceChoice },
+                onCheckFailure: failure => { reason = failure.reason; options.onCheckFailure?.(failure); },
                 emailSignIn, findingSettings, signal, onCheckStart: () => {
                     started = true;
                     if (guarded && analysisFolder)
@@ -160,20 +166,32 @@ export async function serveMcp(input, output, options = {}) {
                     } });
             }
             else if (name === "get_balance")
-                await balance(ctx);
+                await balance(ctx, { onLoaded: value => { freeAnalysisAvailable = value.freeAnalysisAvailable; } });
             else if (name === "sign_in_status") {
                 const pending = pendingSignIn;
                 const allowed = await analyzeToolAllowed(ctx.homeDir, cwd);
                 if (args.wait === true && pending) {
-                    const cancel = () => pending.controller.abort();
-                    signal.addEventListener("abort", cancel, { once: true });
-                    try {
-                        if (signal.aborted)
-                            cancel();
-                        await pending.flow.done;
+                    if (pending.flow.retryEnabled) {
+                        try {
+                            await waitForSignIn(pending.flow, signal);
+                        }
+                        catch (error) {
+                            if (signal.aborted)
+                                throw error;
+                            // The flow stores its failure; collect the usual status fields before reporting it.
+                        }
                     }
-                    finally {
-                        signal.removeEventListener("abort", cancel);
+                    else {
+                        const cancel = () => pending.controller.abort();
+                        signal.addEventListener("abort", cancel, { once: true });
+                        try {
+                            if (signal.aborted)
+                                cancel();
+                            await pending.flow.done;
+                        }
+                        finally {
+                            signal.removeEventListener("abort", cancel);
+                        }
                     }
                 }
                 signIn = { ...await signInStatus(ctx), analyzeToolAllowed: allowed };
@@ -185,17 +203,31 @@ export async function serveMcp(input, output, options = {}) {
                     if (suggestion)
                         signIn.suggestedEmail = suggestion;
                 }
+                if (signInFailure)
+                    signal.throwIfAborted();
+                const failure = signInFailure;
+                signInFailure = undefined;
+                if (failure && !signIn.signedIn) {
+                    const shown = mcpFailure(failure.error, failureReasons);
+                    text = (failure.error instanceof SignInExpiredError
+                        ? emailSignInMessages.mcp_expired : failure.error instanceof SignInDeniedError
+                        ? emailSignInMessages.mcp_cancelled : shown.message) + "\n";
+                    exitCode = errorCode(failure.error);
+                    reason = shown.reason;
+                }
             }
             else if (emailFlow) {
                 if (pendingSignIn)
                     throw new Error(emailSignInMessages.browser_sign_in_pending);
                 if (name === "sign_in") {
                     const start = await startEmailSignIn(ctx, email);
+                    signInFailure = undefined;
                     signIn = { email: email, expiresIn: start.expiresIn };
                     text = `We sent a sign-in code to ${email}. Ask the user for the code from their email, then call sign_in_with_code with the same email and their code. Do not repeat the code.`;
                 }
                 else {
                     await signInWithCode(ctx, email, args.code);
+                    signInFailure = undefined;
                     signIn = { signedIn: true };
                     text = "Signed in.";
                 }
@@ -206,7 +238,7 @@ export async function serveMcp(input, output, options = {}) {
                 else {
                     let pending = pendingSignIn;
                     if (!pending) {
-                        // The flow outlives this call; a later wait call can cancel its polling.
+                        // With retry on, the browser flow belongs to the session, so a cancelled status wait leaves it running.
                         const controller = new AbortController();
                         const cancel = () => controller.abort();
                         signal.addEventListener("abort", cancel, { once: true });
@@ -215,11 +247,16 @@ export async function serveMcp(input, output, options = {}) {
                             const flow = await startSignIn(commandContext({ ...options, emailSignIn, findingSettings, homeDir: ctx.homeDir, baseUrl: ctx.api.baseUrl, signal: controller.signal }));
                             pending = { flow, controller, opened: false };
                             pendingSignIn = pending;
+                            signInFailure = undefined;
                             const current = pending;
                             const clear = () => { if (pendingSignIn === current)
                                 pendingSignIn = undefined; };
                             // Handle background failures even when the client never calls wait.
-                            void flow.done.then(clear, clear);
+                            void flow.done.then(clear, error => {
+                                if (flow.retryEnabled && pendingSignIn === current && !current.controller.signal.aborted)
+                                    signInFailure = { error };
+                                clear();
+                            });
                             pending.opened = await ctx.openBrowser(flow.pageUrl);
                         }
                         finally {
@@ -234,11 +271,11 @@ export async function serveMcp(input, output, options = {}) {
             else {
                 const launchFolder = await launch;
                 if (guarded && !launchFolder)
-                    throw new Error(START_FAILURE_MESSAGE);
+                    throw new CliRefusalError("launch_folder_unavailable");
                 const folder = guarded ? await resolveMcpAgentFolder(args.path, launchFolder, ctx.homeDir) : resolveAgentFolder(args.path, cwd);
                 const last = lastAnalysis.get(folder);
                 if (guarded && last !== undefined && ctx.now() - last < 10 * 60 * 1000) {
-                    throw new Error(FINISH_FAILURE_MESSAGE);
+                    throw new CliRefusalError("repeat_too_soon");
                 }
                 analysisFolder = folder;
                 try {
@@ -251,13 +288,17 @@ export async function serveMcp(input, output, options = {}) {
             }
         }
         catch (error) {
-            text += errorText(error) + "\n";
+            const failure = mcpFailure(error, failureReasons);
+            text += failure.message + "\n";
+            reason = failure.reason;
             exitCode = errorCode(error);
         }
         // Some clients (Claude Code among them) give the model only the structured result when one is present, so it
         // repeats the text: without it the model cannot read the result.
         return { content: [{ type: "text", text }], isError: exitCode !== 0,
             structuredContent: { text, exitCode, ...agentChoice, ...(findingIds ? { findingIds } : {}), ...(url ? { url } : {}), ...signIn,
+                ...(exitCode !== 0 && failureReasons ? { reason: reason ?? failureReason(undefined) } : {}),
+                ...(freeAnalysisAvailable ? { freeAnalysisAvailable } : {}),
                 ...(findings ? { findings, projectId } : {}), ...(loadedFinding ? { finding: loadedFinding } : {}),
                 ...(fixRequests ? { fixRequests } : {}), ...claimed, ...(waitingCount !== undefined ? { waitingFixes: waitingCount } : {}) } };
     }

package/dist/cli/relay-check.js

@@ -10,7 +10,7 @@ import { resolveFolderPath } from "../adapters/folder-path.js";
 import { AgentChoiceError } from "../contract/agent-choice.js";
 import { savedAnalysisUrl } from "../contract/console-url.js";
 import { prepareRelayCheck } from "./relay-preparation.js";
-import { cliRefusals, COMMITTED_FILES_MESSAGE, FINISH_FAILURE_MESSAGE, RESULTS_TOO_LARGE_MESSAGE, refusalExitCode } from "../contract/cli-refusals.js";
+import { cliRefusals, COMMITTED_FILES_MESSAGE, failureReason, FINISH_FAILURE_MESSAGE, RESULTS_TOO_LARGE_MESSAGE, refusalExitCode } from "../contract/cli-refusals.js";
 import { ConsoleClient, ConsoleError } from "../gatekeeper/console.js";
 import { GatekeeperClient } from "../gatekeeper/client.js";
 import { connectRelay, relayOrigin } from "../gatekeeper/connection.js";
@@ -252,7 +252,7 @@ async function runRelayLifecycle(folder, options, existing) {
             || error.message.startsWith("The saved completion") || error.message === COMPLETION_SETTINGS_MISMATCH_MESSAGE);
         const message = known ? error.message : FINISH_FAILURE_MESSAGE;
         try {
-            options.onError?.({ code: error instanceof ConsoleError ? error.code : undefined, message,
+            options.onError?.({ code: error instanceof ConsoleError ? error.code : undefined, reason: failureReason(error), message,
                 ...(error instanceof AgentChoiceError ? { agentChoice: error.agentChoice } : {}) });
             stderr(`${message}\n`);
             if (status && !(error instanceof ConsoleError && error.code === "low_balance"))

package/dist/cli/sign-in.js

@@ -1,6 +1,13 @@
 import { ApiError } from "./api.js";
 import { readCredentials, saveCredentials } from "./credentials.js";
 import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
+import { cliApiMessages } from "../contract/cli-api-messages.js";
+export class SignInExpiredError extends ApiError {
+    constructor() { super(400, "expired", emailSignInMessages.browser_expired); }
+}
+export class SignInDeniedError extends Error {
+    constructor() { super(emailSignInMessages.cancelled); }
+}
 async function pollSignIn(ctx, device) {
     const until = ctx.now() + device.expiresIn * 1000;
     while (ctx.now() < until) {
@@ -15,12 +22,64 @@ async function pollSignIn(ctx, device) {
         if (poll.status === "denied")
             throw new Error(emailSignInMessages.cancelled);
     }
-    throw new Error("The sign-in code expired. Run counterfact-labs login to try again.");
+    throw new SignInExpiredError();
+}
+async function pollSignInWithRetry(ctx, device) {
+    const until = ctx.now() + device.expiresIn * 1000;
+    const interval = device.interval * 1000;
+    let delay = interval;
+    while (ctx.now() < until) {
+        await ctx.sleep(Math.min(delay, until - ctx.now()));
+        if (ctx.now() >= until)
+            break;
+        let poll;
+        try {
+            poll = await ctx.api.request("device/token", { deviceCode: device.deviceCode }, false, { timeoutMs: Math.min(120_000, until - ctx.now()) });
+        }
+        catch (error) {
+            ctx.signal?.throwIfAborted();
+            if (!(error instanceof ApiError) || !(error.status === 0 || error.status === 408 || error.status === 429
+                || (error.status >= 500 && error.status < 600)))
+                throw error;
+            // A temporary failure cannot tell us whether the user approved the code.
+            delay = Math.max(interval, error.retryAfterMs);
+            continue;
+        }
+        delay = interval;
+        if (!poll)
+            throw new Error(cliApiMessages.invalid_response);
+        if (poll.status === "ok") {
+            // The server has consumed the code, so keep its token even after local expiry.
+            await saveCredentials(ctx.homeDir, ctx.api.baseUrl, poll.token);
+            return "signed_in";
+        }
+        if (poll.status === "expired")
+            break;
+        if (poll.status === "denied")
+            throw new SignInDeniedError();
+    }
+    throw new SignInExpiredError();
 }
 export async function startSignIn(ctx) {
     const device = await ctx.api.request("device", {}, false);
     return { userCode: device.userCode, verificationUri: device.verificationUri,
-        pageUrl: `${device.verificationUri}?code=${encodeURIComponent(device.userCode)}`, done: pollSignIn(ctx, device) };
+        pageUrl: `${device.verificationUri}?code=${encodeURIComponent(device.userCode)}`, retryEnabled: ctx.signInRetry,
+        done: ctx.signInRetry ? pollSignInWithRetry(ctx, device) : pollSignIn(ctx, device) };
+}
+export async function waitForSignIn(flow, signal) {
+    signal.throwIfAborted();
+    let cancel;
+    const cancelled = new Promise((_resolve, reject) => {
+        cancel = () => reject(signal.reason);
+        signal.addEventListener("abort", cancel, { once: true });
+    });
+    // A cancelled tool wait must leave the shared browser sign-in running.
+    try {
+        return await Promise.race([flow.done, cancelled]);
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+    }
 }
 export async function signInStatus(ctx) {
     if (!await readCredentials(ctx.homeDir, ctx.api.baseUrl))

package/dist/contract/cli-api-messages.js

@@ -2,4 +2,6 @@ export const cliApiMessages = Object.freeze({
     unreachable: "Can't reach Counterfact. Try again shortly.",
     invalid_response: "Counterfact returned an invalid response. Try again shortly.",
     request_failed: "The request could not be completed. Try again shortly.",
+    unauthorized: "Not signed in. Run counterfact-labs login.",
+    invalid_console_url: "COUNTERFACT_URL must be an HTTP or HTTPS address without credentials or query fields.",
 });

package/dist/contract/cli-refusals.js

@@ -1,4 +1,6 @@
 import { FOLDER_TOO_LARGE_MESSAGE } from "../analysis-core/errors.js";
+import { cliApiMessages } from "./cli-api-messages.js";
+import { emailSignInMessages } from "./email-sign-in-messages.js";
 export const START_FAILURE_MESSAGE = "This couldn't start. Try again.";
 export const RESERVATION_EXPIRED_MESSAGE = "This reservation expired. Start a new analysis.";
 export const FINISH_FAILURE_MESSAGE = "The analysis couldn't finish. Try again.";
@@ -7,7 +9,13 @@ export const COMMITTED_FILES_MESSAGE = "Counterfact analyzes the committed versi
 const unsupportedVersion = "This version of Counterfact can't run analyses. Update it: npm install -g @counterfact-labs/cli@latest.";
 // The console separates over-limit costs from version or route mismatches, so each code gets its own recovery guidance.
 const analysisTooLarge = "This analysis is too large to run at once. Choose a smaller folder, such as one agent's folder.";
-/** Shared public refusals keep mode admission and reservation errors consistent. */
+export const localRefusals = {
+    outside_project: "Choose a folder inside this project, or start Claude Code or Codex in the folder you want to analyze.",
+    launch_folder_unavailable: START_FAILURE_MESSAGE,
+    folder_unavailable: START_FAILURE_MESSAGE,
+    repeat_too_soon: FINISH_FAILURE_MESSAGE,
+};
+/** Both console clients use the same public messages for server refusals. */
 export const cliRefusals = {
     folder_too_large: FOLDER_TOO_LARGE_MESSAGE,
     low_balance: "Your balance doesn't cover this analysis. Add credit at https://app.counterfactlabs.com/account?status=low_balance#balance",
@@ -25,3 +33,60 @@ export const cliRefusals = {
     stale_quote: START_FAILURE_MESSAGE,
 };
 export function refusalExitCode(code) { return code === "low_balance" ? 2 : 1; }
+export class CliRefusalError extends Error {
+    code;
+    constructor(code) {
+        super(Object.hasOwn(localRefusals, code) ? localRefusals[code] : cliRefusals[code]);
+        this.code = code;
+    }
+}
+const otherReasons = {
+    unavailable: "console_unavailable",
+    invalid_configuration: "invalid_configuration",
+    invalid_request: "invalid_request",
+    unauthorized: "unauthorized",
+    not_allowed: "not_allowed",
+    not_found: "not_found",
+    rate_limited: "rate_limited",
+    reservation_closed: "reservation_closed",
+    reservation_closing: "reservation_closing",
+    delivery_incomplete: "delivery_incomplete",
+    check_conflict: "check_conflict",
+    invalid_email: "invalid_email",
+    wrong_code: "wrong_code",
+    expired: "expired",
+    too_many_attempts: "too_many_attempts",
+    email_unavailable: "email_unavailable",
+    request_failed: "request_failed",
+};
+const messageReasons = {
+    [cliRefusals.release_unavailable]: "release_unavailable",
+    [cliApiMessages.invalid_response]: "invalid_response",
+    [emailSignInMessages.browser_sign_in_pending]: "browser_sign_in_pending",
+    [emailSignInMessages.cancelled]: "cancelled",
+};
+const reasonValues = [
+    ...Object.keys(cliRefusals),
+    ...Object.keys(localRefusals),
+    ...Object.values(otherReasons), ...Object.values(messageReasons),
+    "console_unreachable", "invalid_console_url", "relay_unreachable", "results_not_saved",
+];
+const ownedReasons = new Set(reasonValues);
+/** Only fixed reasons may cross the MCP boundary; diagnostics can contain customer data. */
+export function failureReason(error) {
+    if (!(error instanceof Error))
+        return "request_failed";
+    if (error instanceof CliRefusalError)
+        return error.code;
+    if ("reason" in error && typeof error.reason === "string" && ownedReasons.has(error.reason))
+        return error.reason;
+    const code = "code" in error ? error.code : undefined;
+    if (typeof code === "string") {
+        if (Object.hasOwn(cliRefusals, code))
+            return code;
+        if (Object.hasOwn(otherReasons, code))
+            return otherReasons[code];
+        return "request_failed";
+    }
+    return Object.hasOwn(messageReasons, error.message) ? messageReasons[error.message] : "request_failed";
+}

package/dist/contract/cli-version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.2.5";
+export const CLI_VERSION = "0.2.6";

package/dist/contract/email-sign-in-messages.js

@@ -1,5 +1,6 @@
 import { cliApiMessages } from "./cli-api-messages.js";
 const rateLimited = "Too many sign-in requests. Try again later.";
+// Holds the sentences both sign-in flows share, so browser expiry lives here too.
 export const emailSignInMessages = Object.freeze({
     invalid_email: "Enter a valid email address.",
     invalid_code: "Enter the code from your email.",
@@ -11,8 +12,11 @@ export const emailSignInMessages = Object.freeze({
         : `Too many sign-in requests. Try again in ${seconds} ${seconds === 1 ? "second" : "seconds"}.`,
     email_unavailable: "Email sign-in isn't available. Use browser sign-in instead.",
     browser_sign_in_pending: "A browser sign-in is still in progress. Finish it before starting email sign-in.",
+    browser_expired: "The sign-in code expired. Run counterfact-labs login to try again.",
     unreachable: cliApiMessages.unreachable,
     invalid_response: cliApiMessages.invalid_response,
     request_failed: cliApiMessages.request_failed,
     cancelled: "Sign-in was cancelled. Run counterfact-labs login to try again.",
+    mcp_expired: "The sign-in code expired. Call sign_in to try again.",
+    mcp_cancelled: "Sign-in was cancelled. Call sign_in to try again.",
 });

package/dist/gatekeeper/cli-api.js

@@ -11,11 +11,13 @@ export class ApiError extends Error {
     status;
     code;
     retryAfterMs;
-    constructor(status, code, message, retryAfterMs = 0) {
+    reason;
+    constructor(status, code, message, retryAfterMs = 0, reason) {
         super(message);
         this.status = status;
         this.code = code;
         this.retryAfterMs = retryAfterMs;
+        this.reason = reason;
     }
 }
 const emailRoutes = {
@@ -100,9 +102,16 @@ export class ApiClient {
         this.token = token;
         this.fetcher = fetcher;
         this.signal = signal;
-        const url = new URL(baseUrl);
-        if (!consoleSchemeAllowed(url) || url.username || url.password || url.search || url.hash)
-            throw new Error("COUNTERFACT_URL must be an HTTP or HTTPS address without credentials or query fields.");
+        let url;
+        try {
+            url = new URL(baseUrl);
+        }
+        catch (error) {
+            throw new ApiError(0, "invalid_console_url", errorText(error), 0, "invalid_console_url");
+        }
+        if (!consoleSchemeAllowed(url) || url.username || url.password || url.search || url.hash) {
+            throw new ApiError(0, "invalid_console_url", cliApiMessages.invalid_console_url, 0, "invalid_console_url");
+        }
         this.baseUrl = url.href.replace(/\/+$/, "");
     }
     async request(path, body, authenticated = true, options = {}) {
@@ -118,7 +127,7 @@ export class ApiClient {
         if (authenticated) {
             const token = await this.token();
             if (!token)
-                throw new Error("Not signed in. Run counterfact-labs login.");
+                throw new ApiError(401, "unauthorized", cliApiMessages.unauthorized);
             headers.authorization = `Bearer ${token}`;
         }
         if (body !== undefined)
@@ -144,7 +153,7 @@ export class ApiClient {
             }
             catch {
                 throwIfAborted();
-                throw new ApiError(0, "unreachable", cliApiMessages.unreachable);
+                throw new ApiError(0, "unreachable", cliApiMessages.unreachable, 0, "console_unreachable");
             }
             throwIfAborted();
             if (emailRoute && response.ok && response.status !== emailRoute.successStatus) {
@@ -161,7 +170,7 @@ export class ApiClient {
                 if (response.ok) {
                     if (error instanceof SyntaxError)
                         throw new Error(cliApiMessages.invalid_response);
-                    throw new ApiError(0, "unreachable", cliApiMessages.unreachable);
+                    throw new ApiError(0, "unreachable", cliApiMessages.unreachable, 0, "console_unreachable");
                 }
             }
             throwIfAborted();

package/dist/gatekeeper/connection-exchange.js

@@ -2,6 +2,7 @@ import { RELAY_MAX_FRAME_BYTES, deliveryReceipt, relayAnswer, relayAnswerFrame,
 import { unredactedAnswer } from "../contract/public-report.js";
 export class RelayConnectionError extends Error {
     name = "RelayConnectionError";
+    reason = "relay_unreachable";
     constructor() { super("Relay connection failed"); }
 }
 /** Both carriers retry the same confirmation, never another paid request. */

package/dist/gatekeeper/console.js

@@ -6,7 +6,7 @@ import { cliRefusals, FINISH_FAILURE_MESSAGE, RESERVATION_EXPIRED_MESSAGE, RESUL
 import { cliRelayReservationRequestSchema, consoleCreatedSchema, consoleIntakeResultSchema, consoleReservationSchema, consoleStatusSchema, LOCAL_FINDINGS_BODY_LIMIT, localFindingsPayloadSchema, LOCAL_START_BODY_LIMIT, LOCAL_START_EXECUTION_HEADER, localStartRequestSchema, localStartResponseSchema, serializeLocalStartMetadata } from "../contract/console.js";
 const RESPONSE_LIMIT = 64 * 1024;
 const RESERVATION_BODY_LIMIT = 64 * 1024;
-const messages = {
+export const consoleErrorMessages = {
     ...cliRefusals,
     invalid_configuration: START_FAILURE_MESSAGE,
     invalid_request: FINISH_FAILURE_MESSAGE,
@@ -22,13 +22,24 @@ const messages = {
 };
 export class ConsoleError extends Error {
     code;
-    constructor(code = "unavailable", context) {
-        super(context === "start" && (code === "unavailable" || code === "invalid_request" || code === "not_found") ? START_FAILURE_MESSAGE
-            : context === "intake" && code === "reservation_expired" ? RESERVATION_EXPIRED_MESSAGE
-                // Only saving results can be too large; a rejected status, heartbeat or fail request just could not finish.
-                : context === "intake" && code === "invalid_request" ? RESULTS_TOO_LARGE_MESSAGE : messages[code]);
+    reason;
+    constructor(code = "unavailable", context, localReason) {
+        let message = consoleErrorMessages[code];
+        let reason = code === "unavailable" ? "results_not_saved" : code;
+        if (context === "start" && (code === "unavailable" || code === "invalid_request" || code === "not_found")) {
+            message = START_FAILURE_MESSAGE;
+            if (code === "unavailable")
+                reason = "console_unavailable";
+        }
+        else if (context === "intake" && code === "reservation_expired")
+            message = RESERVATION_EXPIRED_MESSAGE;
+        // Only saving results can be too large; a rejected status, heartbeat or fail request just could not finish.
+        else if (context === "intake" && code === "invalid_request")
+            message = RESULTS_TOO_LARGE_MESSAGE;
+        super(message);
         this.name = "ConsoleError";
         this.code = code;
+        this.reason = localReason ?? reason;
     }
 }
 export const isConsoleToken = (token) => /^[\x21-\x7e]{1,4096}$/.test(token);
@@ -38,21 +49,24 @@ export class ConsoleClient {
     #token;
     #timeoutMs;
     constructor(options) {
+        let url;
         try {
-            const url = new URL(options.url);
-            const timeout = options.timeoutMs ?? 15_000;
+            url = new URL(options.url);
             if (!consoleSchemeAllowed(url)
-                || url.username || url.password || url.pathname !== "/" || url.search || url.hash
-                || !isConsoleToken(options.token)
-                || !Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 120_000)
-                throw new ConsoleError("invalid_configuration");
-            this.#url = url;
-            this.#token = options.token;
-            this.#timeoutMs = timeout;
+                || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+                throw new ConsoleError("invalid_configuration", undefined, "invalid_console_url");
+            }
         }
         catch {
-            throw new ConsoleError("invalid_configuration");
+            throw new ConsoleError("invalid_configuration", undefined, "invalid_console_url");
+        }
+        const timeout = options.timeoutMs ?? 15_000;
+        if (!isConsoleToken(options.token) || !Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 120_000) {
+            throw new ConsoleError("invalid_configuration", undefined, "request_failed");
         }
+        this.#url = url;
+        this.#token = options.token;
+        this.#timeoutMs = timeout;
     }
     async start(input, metadata) {
         let headers;
@@ -152,7 +166,7 @@ export class ConsoleClient {
                         const decoded = JSON.parse(Buffer.concat(chunks).toString("utf8"));
                         if (!(options.statuses ?? [200]).includes(status)) {
                             const code = decoded && typeof decoded === "object" && "code" in decoded ? decoded.code : undefined;
-                            throw new ConsoleError(typeof code === "string" && Object.hasOwn(messages, code) ? code : "unavailable");
+                            throw new ConsoleError(typeof code === "string" && Object.hasOwn(consoleErrorMessages, code) ? code : "unavailable");
                         }
                         const result = responseSchema.parse(decoded);
                         for (const [field, expected] of Object.entries(identities)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@counterfact-labs/cli",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "homepage": "https://counterfactlabs.com",
   "relaySource": "https://github.com/counterfact-labs/sealed-relay",
   "type": "module",