@counterfact-labs/cli 0.2.5 → 0.2.7

package/dist/cli/scope-choices.js

@@ -0,0 +1,57 @@
+import { readdir, readFile, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { outputPaths, writeOutputFiles } from "../adapters/output-paths.js";
+import { analysisScopeSchema, chooseScopeResultSchema, CHOOSE_SCOPE_MESSAGE, INCLUDED_FILES_CAPTION, OMITTED_IMPORTS_CAPTION, SCOPE_CHOICE_INSTRUCTION, INCOMPLETE_IMPORTS_MESSAGE, IMPORT_DISCOVERY_LIMIT_MESSAGE, INVALID_SCOPE_MESSAGE, SCOPE_RETRY_TEMPLATE } from "../contract/scope-choice.js";
+import { scopeChoiceRefusal } from "../contract/selection-offer.js";
+import { scopeChoicesEnabled } from "../adapters/settings.js";
+export async function loadAnalysisScope(options, cwd, settings) {
+    if (options.scope === undefined && options.scopeFile === undefined)
+        return undefined;
+    if (!scopeChoicesEnabled(settings))
+        throw new Error(INVALID_SCOPE_MESSAGE);
+    try {
+        const value = options.scopeFile === undefined ? options.scope : JSON.parse(await readFile(resolve(cwd, options.scopeFile), "utf8"));
+        return analysisScopeSchema.parse(value);
+    }
+    catch {
+        throw new Error(INVALID_SCOPE_MESSAGE);
+    }
+}
+export function shellQuote(value) { return `'${value.replaceAll("'", `'"'"'`)}'`; }
+/** MCP and terminal output share the same file coverage; only the terminal adds retry commands. */
+export function scopeChoiceText(value, retryPaths = {}) {
+    const result = chooseScopeResultSchema.parse(value);
+    const refusal = scopeChoiceRefusal(result);
+    if (refusal)
+        return refusal + "\n";
+    const lines = [CHOOSE_SCOPE_MESSAGE];
+    if (!result.coverageComplete && result.refusedEdges.length > 0)
+        lines.push(INCOMPLETE_IMPORTS_MESSAGE);
+    if (!result.coverageComplete && result.frontierCount > 0)
+        lines.push(IMPORT_DISCOVERY_LIMIT_MESSAGE);
+    result.choices.forEach((choice, index) => {
+        lines.push(`${index + 1}. ${choice.label}`, choice.description, INCLUDED_FILES_CAPTION, ...choice.includes.map(path => `  ${path}`));
+        if (choice.omitted.length > 0)
+            lines.push(OMITTED_IMPORTS_CAPTION, ...choice.omitted.map(path => `  ${path}`));
+        if (choice.fits !== false && retryPaths[index]) {
+            const entry = choice.scope.entry.startsWith("-") ? `./${choice.scope.entry}` : choice.scope.entry;
+            lines.push(SCOPE_RETRY_TEMPLATE.replace("{quoted-entry}", () => shellQuote(entry))
+                .replace("{quoted-scope-file}", () => shellQuote(retryPaths[index])));
+        }
+    });
+    lines.push(SCOPE_CHOICE_INSTRUCTION);
+    return lines.join("\n") + "\n";
+}
+export async function renderScopeChoices(value, anchor) {
+    const result = chooseScopeResultSchema.parse(value);
+    // Validate the output directory and old entries before removing only generated scope files.
+    const [probe] = await outputPaths(anchor.outputAnchor, ["scope-1.json"], anchor.outputDir, true);
+    const old = (await readdir(dirname(probe))).filter(name => /^scope-.*\.json$/.test(name));
+    await outputPaths(anchor.outputAnchor, old, anchor.outputDir);
+    for (const name of old)
+        await unlink(join(dirname(probe), name));
+    const runnable = result.choices.flatMap((choice, index) => choice.fits === false ? [] : [{ choice, index }]);
+    const files = Object.fromEntries(runnable.map(({ choice, index }) => [`scope-${index + 1}.json`, JSON.stringify(choice.scope, null, 2) + "\n"]));
+    const paths = await writeOutputFiles(anchor.outputAnchor, files, anchor.outputDir);
+    return scopeChoiceText(result, Object.fromEntries(runnable.map(({ index }, position) => [index, paths[position]])));
+}

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,13 +1,27 @@
 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.";
+export const NOT_ALLOWED_MESSAGE = "Your account can't run analyses. Ask Counterfact for access.";
+export const SIGN_IN_EXPIRED_MESSAGE = "Your sign-in has expired. Run counterfact-labs login, then try again.";
+export const FOLDER_BUSY_MESSAGE = "Another analysis is running on this folder. Try again when it finishes.";
+export const CHECK_CONFLICT_MESSAGE = "Saved results from an earlier run don't match this analysis. Start a new analysis.";
+export const UNSAVED_RESULTS_MESSAGE = "The analysis ended before its results were saved. Start a new analysis.";
+export const PENDING_RESULTS_MESSAGE = "Your results are kept on this computer. Run the same command on the same folder again to save them at no extra charge.";
 export const RESULTS_TOO_LARGE_MESSAGE = "The results were too large to save. Try again.";
 export const COMMITTED_FILES_MESSAGE = "Counterfact analyzes the committed version of the agent's files. Commit your changes, then try again.";
 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 +39,62 @@ 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",
+    "results_saved_report_failed", "results_pending", "results_discarded",
+    "folder_busy", "completion_settings_mismatch",
+];
+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.7";

package/dist/contract/console.js

@@ -5,6 +5,7 @@ import { sourceNotesSchema } from "../analysis-core/analysis/source-notes/types.
 import { parseAnalysisSize } from "../analysis-core/conventions/analysis-fit.js";
 import { canonicalUuidSchema as uuid, matchingFindingNumbers, numberedFindingsSchema } from "./findings.js";
 import { RESULT_CHECK_LIMITS, validIntakeText } from "../analysis-core/contracts/relay-analysis.js";
+import { selectionStartIdentitySchema } from "./selection-metadata.js";
 export const id = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/);
 const money = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
 const count = (max) => z.number().int().positive().max(max);
@@ -13,13 +14,15 @@ export const LOCAL_START_EXECUTION_HEADER = { name: "x-counterfact-execution", v
 export const LOCAL_START_BODY_LIMIT = 2 * 1024 * 1024;
 export const ANALYSIS_SIZE_HEADER = "x-counterfact-analysis-size";
 export const START_ATTEMPT_HEADER = "x-counterfact-start-attempt";
+export const SELECTION_IDENTITY_HEADER = "x-counterfact-selection";
 export const ANALYSIS_SIZE_HEADER_LIMIT = 256;
 /** Additive headers let older consoles keep accepting the unchanged, strict start body. */
 export function serializeLocalStartMetadata(metadata) {
     const size = JSON.stringify(parseAnalysisSize(metadata.analysisSize));
     if (Buffer.byteLength(size, "utf8") > ANALYSIS_SIZE_HEADER_LIMIT)
         throw new Error("Invalid analysis size header");
-    return { [ANALYSIS_SIZE_HEADER]: size, [START_ATTEMPT_HEADER]: uuid.parse(metadata.startAttempt) };
+    return { [ANALYSIS_SIZE_HEADER]: size, [START_ATTEMPT_HEADER]: uuid.parse(metadata.startAttempt),
+        ...(metadata.selection === undefined ? {} : { [SELECTION_IDENTITY_HEADER]: JSON.stringify(selectionStartIdentitySchema.parse(metadata.selection)) }) };
 }
 /** Missing measurements preserve old clients; present measurements must be complete. */
 export function parseLocalStartMetadata(headers) {
@@ -28,7 +31,9 @@ export function parseLocalStartMetadata(headers) {
         return undefined;
     if (Buffer.byteLength(raw, "utf8") > ANALYSIS_SIZE_HEADER_LIMIT)
         throw new Error("Invalid analysis size header");
-    return { analysisSize: parseAnalysisSize(JSON.parse(raw)), startAttempt: uuid.parse(headers.get(START_ATTEMPT_HEADER)) };
+    const selection = headers.get(SELECTION_IDENTITY_HEADER);
+    return { analysisSize: parseAnalysisSize(JSON.parse(raw)), startAttempt: uuid.parse(headers.get(START_ATTEMPT_HEADER)),
+        ...(selection === null ? {} : { selection: selectionStartIdentitySchema.parse(JSON.parse(z.string().max(256).parse(selection))) }) };
 }
 const localStartPath = z.string().min(1).max(4096).refine(value => !value.includes("\\") && !value.includes("\0") && !value.startsWith("/")
     && value.split("/").every(part => part !== ".." && part !== "." && part !== ""));

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/contract/scope-choice.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { ANALYSIS_SELECTION_LIMITS, provenScopeChoiceSchema } from "../analysis-core/contracts/analysis-selection.js";
+import { refusedImportSchema } from "../analysis-core/contracts/module-resolution.js";
+import { selectionPathSchema, snapshotIdSchema } from "../analysis-core/contracts/selection-paths.js";
+import { FileReadRefusal } from "../analysis-core/conventions/file-admission.js";
+export { analysisScopeSchema } from "../analysis-core/contracts/analysis-selection.js";
+// Proposed copy stays here so wiring the CLI and MCP cannot create different promises about coverage.
+export const CHOOSE_SCOPE_MESSAGE = "This analysis is too large to run at once. Choose what Counterfact should read.";
+export const ENTRY_ONLY_LABEL = "Only the selected file";
+export const ENTRY_ONLY_DESCRIPTION = "Read {entry}. Leave its imports out of this analysis.";
+export const SELECTED_IMPORTS_LABEL = "The selected file and some imports";
+export const SELECTED_IMPORTS_DESCRIPTION = "Read {entry} and the imports listed below. Leave the other imports out of this analysis.";
+export const ENTRY_IMPORTS_LABEL = "One agent file and its imports";
+export const ENTRY_IMPORTS_DESCRIPTION = "Read {entry} and its project imports inside the launch folder.";
+export const SINGLE_FILE_TOO_LARGE_MESSAGE = "This file is too large to analyze on its own. Choose another agent file or split this file into smaller files.";
+export const INVALID_SELECTION_MESSAGE = "Choose an agent file or folder inside the launch folder.";
+export const INVALID_SCOPE_MESSAGE = "This scope could not be used. Choose one of the returned scopes and try again.";
+export const STALE_SCOPE_MESSAGE = "The selected files changed. Run the analysis again to get updated scope choices.";
+export const SCOPE_PROPOSAL_CONFLICT_MESSAGE = "The selected scope and proposed files do not match. Keep the selected file and only its listed imports.";
+export const SELECTION_REFUSAL_MESSAGES = Object.freeze([
+    INVALID_SELECTION_MESSAGE, INVALID_SCOPE_MESSAGE, STALE_SCOPE_MESSAGE, SCOPE_PROPOSAL_CONFLICT_MESSAGE,
+    SINGLE_FILE_TOO_LARGE_MESSAGE,
+]);
+export function isSelectionRefusal(error, fileMode) {
+    return error instanceof Error && (SELECTION_REFUSAL_MESSAGES.includes(error.message)
+        || fileMode && error instanceof FileReadRefusal);
+}
+export const INCLUDED_FILES_CAPTION = "Included files:";
+export const OMITTED_IMPORTS_CAPTION = "Imports left out:";
+export const SCOPE_CHOICE_INSTRUCTION = "Choose a scope, then run the analysis again with that scope.";
+export const INCOMPLETE_IMPORTS_MESSAGE = "Some imports could not be resolved. This analysis covers only the files listed below.";
+export const IMPORT_DISCOVERY_LIMIT_MESSAGE = "Counterfact reached the import discovery limit. The list of imports is incomplete.";
+export const SELECTED_FILES_PROGRESS = "Reading the selected files and running analysis.\n";
+export const SELECTED_PATH_FAILURE = "Analysis could not finish. Check the selected path, provider key and connection.";
+export function progressLine(selection, surface = "source") {
+    return selection?.kind === "file" ? SELECTED_FILES_PROGRESS
+        : surface === "terminal" ? "Analyzing the agent…" : "Reading the folder and running analysis.\n";
+}
+export function failureLine(selection) {
+    return selection?.kind === "file" ? SELECTED_PATH_FAILURE : "Analysis could not finish. Check the folder, provider key and connection.";
+}
+export const SELECTION_COVERAGE_DESCRIPTION = "This analysis covers {entry} and {count} selected imports. Other imports were left out.";
+export const SCOPE_RETRY_TEMPLATE = "Run again: counterfact-labs analyze {quoted-entry} --scope {quoted-scope-file}";
+export const FILE_SCOPE_PUBLIC_USAGE = "Usage: counterfact-labs analyze [path] [--proposal <json-file>] [--scope <json-file>]\n       counterfact-labs finding <id>\n       counterfact-labs balance | login | logout | mcp\n";
+export const FILE_SCOPE_SOURCE_USAGE = "Usage: npx tsx cli/check.ts <path> [--output <directory>] [--scope <json-file>]\n";
+export const scopeChoiceSchema = provenScopeChoiceSchema.safeExtend({
+    label: z.enum([ENTRY_ONLY_LABEL, SELECTED_IMPORTS_LABEL, ENTRY_IMPORTS_LABEL]),
+    description: z.string().min(1).max(8192),
+    // Fewer files do not prove admission; only the ordinary run checks can set true.
+    fits: z.union([z.boolean(), z.literal("unknown")]),
+}).refine(choice => {
+    const imports = choice.scope.imports;
+    const entryOnly = imports === "none" || Array.isArray(imports) && imports.length === 0;
+    const label = entryOnly ? ENTRY_ONLY_LABEL : imports === "all" ? ENTRY_IMPORTS_LABEL : SELECTED_IMPORTS_LABEL;
+    const description = entryOnly && choice.fits === false ? SINGLE_FILE_TOO_LARGE_MESSAGE
+        : (entryOnly ? ENTRY_ONLY_DESCRIPTION : imports === "all" ? ENTRY_IMPORTS_DESCRIPTION : SELECTED_IMPORTS_DESCRIPTION)
+            .replace("{entry}", () => choice.scope.entry);
+    return choice.label === label && choice.description === description;
+});
+export const chooseScopeResultSchema = z.strictObject({
+    kind: z.literal("choose_scope"), text: z.literal(CHOOSE_SCOPE_MESSAGE), snapshot: snapshotIdSchema,
+    entry: selectionPathSchema.nullable(), coverageComplete: z.boolean(),
+    frontierCount: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    choices: z.array(scopeChoiceSchema).min(1).max(ANALYSIS_SELECTION_LIMITS.choices),
+    imports: z.array(z.strictObject({ path: selectionPathSchema, role: z.literal("imported-helper"),
+        importedBy: z.array(selectionPathSchema).min(1).max(ANALYSIS_SELECTION_LIMITS.files)
+            .refine(paths => new Set(paths).size === paths.length) })).max(ANALYSIS_SELECTION_LIMITS.files),
+    refusedEdges: z.array(refusedImportSchema).max(ANALYSIS_SELECTION_LIMITS.edges),
+}).refine(value => (!value.coverageComplete || value.frontierCount === 0 && value.refusedEdges.every(edge => edge.reason === "external"))
+    && new Set(value.choices.map(choice => choice.id)).size === value.choices.length
+    && new Set(value.imports.map(file => file.path)).size === value.imports.length
+    && value.choices.every(choice => choice.scope.snapshot === value.snapshot && (value.entry === null || choice.scope.entry === value.entry
+        && (choice.scope.imports !== "all" || choice.omitted.length === 0))));
+export const chooseScopeMcpResultSchema = z.strictObject({
+    content: z.tuple([z.strictObject({ type: z.literal("text"), text: z.string().startsWith(CHOOSE_SCOPE_MESSAGE) })]),
+    isError: z.literal(false), structuredContent: chooseScopeResultSchema.safeExtend({ exitCode: z.literal(0) }),
+});
+export const SCOPE_CHOICE_EXIT_CODE = 3;

package/dist/contract/selection-metadata.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+export const selectionStartIdentitySchema = z.strictObject({ version: z.literal(1), key: digest, snapshot: digest });
+/** The console can distinguish selected runs without receiving local coordinates or snapshot contents. */
+export function selectionStartIdentity(key, snapshot) {
+    const hash = (value) => createHash("sha256").update(value).digest("hex");
+    return { version: 1, key: hash(key), snapshot: hash(snapshot) };
+}

package/dist/contract/selection-offer.js

@@ -0,0 +1,43 @@
+import { CHOOSE_SCOPE_MESSAGE, ENTRY_IMPORTS_DESCRIPTION, ENTRY_IMPORTS_LABEL, ENTRY_ONLY_DESCRIPTION, ENTRY_ONLY_LABEL, SELECTED_IMPORTS_DESCRIPTION, SELECTED_IMPORTS_LABEL, SINGLE_FILE_TOO_LARGE_MESSAGE } from "./scope-choice.js";
+export class ScopeChoiceError extends Error {
+    choice;
+    constructor(choice) {
+        super(choice.text);
+        this.choice = choice;
+    }
+}
+/** A known nonfitting choice must never invite another paid attempt. */
+export function scopeChoiceRefusal(choice) {
+    return choice.choices.every(option => option.fits === false) ? SINGLE_FILE_TOO_LARGE_MESSAGE : undefined;
+}
+/** Membership choices are proven by core; fewer files alone never prove that a run fits. */
+export function selectionScopeChoices(membership, options = {}) {
+    const current = new Set(options.currentPaths ?? membership.files.map(file => file.path));
+    const oversized = new Set(options.oversizedPaths ?? []);
+    const seen = new Set();
+    const choices = membership.choices.flatMap(choice => {
+        const entryOnly = choice.scope.imports === "none" || Array.isArray(choice.scope.imports) && choice.scope.imports.length === 0;
+        const knownOversized = entryOnly && oversized.has(choice.scope.entry);
+        const identical = choice.includes.length === current.size && choice.includes.every(path => current.has(path));
+        const key = JSON.stringify([...choice.includes].sort());
+        if (seen.has(key) || choice.includes.some(path => !current.has(path)) || identical && !knownOversized)
+            return [];
+        seen.add(key);
+        const label = entryOnly ? ENTRY_ONLY_LABEL : choice.scope.imports === "all" ? ENTRY_IMPORTS_LABEL : SELECTED_IMPORTS_LABEL;
+        const description = knownOversized ? SINGLE_FILE_TOO_LARGE_MESSAGE
+            : (entryOnly ? ENTRY_ONLY_DESCRIPTION : choice.scope.imports === "all" ? ENTRY_IMPORTS_DESCRIPTION : SELECTED_IMPORTS_DESCRIPTION)
+                .replace("{entry}", () => choice.scope.entry);
+        return [{ ...choice, label, description, fits: knownOversized ? false : "unknown" }];
+    });
+    if (!choices.length)
+        return undefined;
+    const imports = membership.files.flatMap(file => {
+        if (file.role !== "imported-helper")
+            return [];
+        const importedBy = [...new Set(membership.edges.filter(edge => edge.path === file.path).map(edge => edge.from))];
+        return importedBy.length ? [{ path: file.path, role: "imported-helper", importedBy }] : [];
+    });
+    return { kind: "choose_scope", text: CHOOSE_SCOPE_MESSAGE, snapshot: membership.snapshot,
+        entry: membership.kind === "file" ? membership.entry : null, coverageComplete: membership.completeness.complete,
+        frontierCount: membership.completeness.frontierCount, choices, imports, refusedEdges: membership.refusedEdges };
+}

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. */