@counterfact-labs/cli 0.2.5 → 0.2.7

package/dist/cli/context.js

@@ -8,7 +8,7 @@ import { userEmail } from "./git.js";
 import { terminalSignInInput } from "./sign-in-input.js";
 import { readFindingSettings } from "./finding-settings.js";
 export function commandContext(options = {}) {
-    const startup = readCliSettings(options.env, options.emailSignIn);
+    const startup = options.startup ?? readCliSettings(options.env, options.emailSignIn);
     const homeDir = options.homeDir ?? homedir();
     const baseUrl = (options.baseUrl ?? startup.baseUrl ?? DEFAULT_URL).replace(/\/+$/, "");
     const api = new ApiClient(baseUrl, () => readCredentials(homeDir, api.baseUrl), undefined, options.signal);
@@ -16,8 +16,11 @@ 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,
+        onScopeChoice: options.onScopeChoice,
         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/main.js

@@ -2,7 +2,7 @@
 import { pathToFileURL } from "node:url";
 import { realpath } from "node:fs/promises";
 import { errorCode, errorText } from "./api.js";
-import { readEmailSignIn } from "../adapters/settings.js";
+import { readEmailSignIn, readSelectionSettings, scopeChoicesEnabled } from "../adapters/settings.js";
 import { commandContext } from "./context.js";
 import { analyze, parseAnalyzeOptions } from "./commands/analyze.js";
 import { finding } from "./commands/finding.js";
@@ -10,26 +10,38 @@ import { balance } from "./commands/balance.js";
 import { login, parseLoginOptions } from "./commands/login.js";
 import { logout } from "./commands/logout.js";
 import { serveMcp } from "./mcp.js";
+import { loadAnalysisScope } from "./scope-choices.js";
+import { FILE_SCOPE_PUBLIC_USAGE } from "../contract/scope-choice.js";
 const usage = "Usage: counterfact-labs analyze [path] [--proposal <json-file>]\n       counterfact-labs finding <id>\n       counterfact-labs balance | login | logout | mcp\n";
 export async function run(args, options = {}) {
     const write = options.write ?? (text => { process.stdout.write(text); });
     const emailSignIn = options.emailSignIn ?? readEmailSignIn(options.env);
-    const commandOptions = { ...options, emailSignIn };
     try {
         const [command, ...rest] = args;
+        const env = options.startup?.settings ?? options.env ?? process.env;
+        // Help follows the CLI defaults without validating unrelated commands' analysis switches.
+        const selectionSettings = readSelectionSettings(env, { validate: command === "analyze" || command === "mcp" });
+        const commandOptions = { ...options, emailSignIn, env: { ...(options.env ?? process.env), ...selectionSettings,
+                ...(command === "analyze" || command === "mcp" ? {} : {
+                    CF_FILE_SCOPE: undefined, CF_SCOPE_CHOICES: undefined, CF_LOCAL_IMPORT_RESOLUTION: undefined,
+                }) } };
+        const choices = scopeChoicesEnabled(selectionSettings);
+        const commandUsage = choices ? FILE_SCOPE_PUBLIC_USAGE : usage;
         if (["--help", "-h", "help"].includes(command) || !command) {
-            write(usage);
+            write(commandUsage);
             return 0;
         }
         if (command === "analyze") {
             let parsed;
             try {
-                parsed = parseAnalyzeOptions(rest);
+                parsed = parseAnalyzeOptions(rest, choices);
             }
             catch {
-                throw new Error(usage.trimEnd());
+                throw new Error(commandUsage.trimEnd());
             }
-            return await analyze(parsed.path, parsed.options, commandContext(commandOptions));
+            const ctx = commandContext(commandOptions);
+            const scope = await loadAnalysisScope(parsed.options, ctx.cwd ?? process.cwd(), ctx.startup.settings);
+            return await analyze(parsed.path, { ...parsed.options, scope }, ctx);
         }
         if (command === "finding" && rest.length === 1 && !rest[0].startsWith("-"))
             return await finding(rest[0], commandContext(commandOptions));
@@ -39,12 +51,12 @@ export async function run(args, options = {}) {
                 parsed = parseLoginOptions(rest);
             }
             catch {
-                throw new Error(usage.trimEnd());
+                throw new Error(commandUsage.trimEnd());
             }
             return await login(commandContext(commandOptions), parsed);
         }
         if (rest.length)
-            throw new Error(usage.trimEnd());
+            throw new Error(commandUsage.trimEnd());
         if (command === "balance")
             return await balance(commandContext(commandOptions));
         if (command === "login")
@@ -55,7 +67,7 @@ export async function run(args, options = {}) {
             await serveMcp(process.stdin, process.stdout, options);
             return 0;
         }
-        throw new Error(usage.trimEnd());
+        throw new Error(commandUsage.trimEnd());
     }
     catch (error) {
         write(errorText(error) + "\n");

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";
@@ -20,14 +21,42 @@ import { fixRequestTools, waitingFixes, waitingFixCount, claimFix, FIX_DISCOVERY
 import { FINDING_PROJECT_MESSAGE, FindingReferences, numberedFindingInputSchema } from "./finding-lookup.js";
 import { findingDisplayRows, formatFindingNumber, formatWaitingFixes } from "./finding-display.js";
 import { readFindingSettings } from "./finding-settings.js";
+import { z } from "zod";
+import { readCliSettings, readSelectionSettings, selectionModeEnabled, scopeChoicesEnabled } from "../adapters/settings.js";
+import { resolveAnalysisSelection } from "./analysis-selection.js";
+import { analysisScopeSchema, chooseScopeMcpResultSchema } from "../contract/scope-choice.js";
+import { scopeChoiceRefusal } from "../contract/selection-offer.js";
+import { loadAnalysisScope, scopeChoiceText } from "./scope-choices.js";
+const fileAnalysisDescription = "Analyze an agent folder or one agent file on this computer. For a file, Counterfact reads that file and the project files it imports inside the launch folder. Each call that runs an analysis 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.";
+const scopeChoiceDescription = "If Counterfact returns scope choices, show what each includes and ask the user to choose before calling again with that scope, unless the user already chose it. Do not run all choices automatically.";
+const fileAnalysisEnding = "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.";
+const filePathDescription = "The agent folder or agent file on this computer, inside the launch folder.";
+const fileScopeDescription = "Optional: a scope returned by Counterfact, using the same snapshot and selected file. Include all imports, no imports, or the listed imports chosen by the user.";
+const fileProposalDescription = "Optional: the files you believe make up the agent, with each file's role. For a folder, paths are relative to that folder. For a file, paths are relative to the launch folder and must belong to the selected file's import scope.";
+const fileProposalPathDescription = "Paths are relative to the selected folder, or to the launch folder when selecting a file.";
+function fileAnalysisTool(choices) {
+    const proposal = structuredClone(agentProposalInputSchema);
+    if (typeof proposal.properties?.files === "object" && proposal.properties.files && "items" in proposal.properties.files) {
+        const files = proposal.properties.files.items;
+        if (files && !Array.isArray(files) && typeof files === "object" && typeof files.properties?.path === "object")
+            files.properties.path.description = fileProposalPathDescription;
+    }
+    const scope = z.toJSONSchema(analysisScopeSchema);
+    delete scope.$schema;
+    return { name: ANALYZE_TOOL_NAME,
+        description: [fileAnalysisDescription, ...(choices ? [scopeChoiceDescription] : []), fileAnalysisEnding].join(" "),
+        inputSchema: { type: "object", properties: { path: { type: "string", description: filePathDescription },
+                proposal: { ...proposal, description: fileProposalDescription }, ...(choices ? { scope: { ...scope, description: fileScopeDescription } } : {}) },
+            required: ["path"], additionalProperties: false } };
+}
 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,12 +72,19 @@ 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);
+    const analysisSwitches = readSelectionSettings(options.startup?.settings ?? options.env ?? process.env);
+    const choicesEnabled = scopeChoicesEnabled(analysisSwitches);
+    const selectionEnabled = selectionModeEnabled(analysisSwitches);
+    const analysisEnv = selectionEnabled ? { ...(options.env ?? process.env), ...analysisSwitches } : undefined;
+    let analysisStartup = options.startup;
     const { numbersEnabled, fixesEnabled } = findingSettings;
     const references = new FindingReferences();
-    const emailSignIn = options.emailSignIn ?? readEmailSignIn(options.env);
+    const emailEnv = analysisEnv && Object.hasOwn(analysisEnv, "CF_EMAIL_SIGN_IN") ? analysisEnv : options.env;
+    const emailSignIn = options.emailSignIn ?? readEmailSignIn(emailEnv);
     const signInTools = emailSignIn ? [...legacyTools.slice(0, 3),
         {
             name: "sign_in_status",
@@ -74,10 +110,11 @@ export async function serveMcp(input, output, options = {}) {
                 }, required: ["email", "code"], additionalProperties: false },
         },
     ] : legacyTools;
-    const tools = signInTools.map(tool => tool.name === "get_finding" && numbersEnabled ? {
+    const tools = signInTools.map(tool => tool.name === ANALYZE_TOOL_NAME && selectionEnabled ? fileAnalysisTool(choicesEnabled) : tool).map(tool => tool.name === "get_finding" && numbersEnabled ? {
         ...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 });
@@ -88,7 +125,7 @@ export async function serveMcp(input, output, options = {}) {
         if (!object(args))
             throw new ProtocolError(-32602, "Tool arguments must be an object.");
         const name = params.name;
-        const allowed = name === ANALYZE_TOOL_NAME ? ["path", "proposal"] : name === "get_finding" ? (numbersEnabled ? Object.keys(numberedFindingInputSchema.properties) : ["id"])
+        const allowed = name === ANALYZE_TOOL_NAME ? ["path", "proposal", ...(choicesEnabled ? ["scope"] : [])] : name === "get_finding" ? (numbersEnabled ? Object.keys(numberedFindingInputSchema.properties) : ["id"])
             : name === "claim_fix" ? ["id"]
                 : name === "sign_in_status" ? (emailSignIn ? ["wait", "path"] : ["wait"])
                     : emailSignIn && name === "sign_in" ? ["email"] : emailSignIn && name === "sign_in_with_code" ? ["email", "code"] : [];
@@ -111,7 +148,10 @@ 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 scopeChoice;
         let findingIds;
         let findings, projectId;
         let loadedFinding;
@@ -121,12 +161,22 @@ export async function serveMcp(input, output, options = {}) {
         let started = false;
         let signIn;
         try {
-            const ctx = commandContext({ ...options, env: { ...(options.env ?? process.env), CF_FINDING_AUDIENCE: audienceChoice },
+            // Listing tools must not validate settings used only when a tool runs.
+            if (selectionEnabled)
+                analysisStartup ??= readCliSettings(analysisEnv, emailSignIn);
+            const analysisSettings = analysisStartup?.settings ?? {};
+            const ctx = commandContext({ ...options, ...(analysisStartup ? { startup: analysisStartup } : {}), env: { ...(analysisEnv ?? options.env ?? process.env), ...analysisSwitches, CF_FINDING_AUDIENCE: audienceChoice },
+                onCheckFailure: failure => { reason = failure.reason; options.onCheckFailure?.(failure); },
                 emailSignIn, findingSettings, signal, onCheckStart: () => {
                     started = true;
                     if (guarded && analysisFolder)
                         lastAnalysis.set(analysisFolder, ctx.now());
                     options.onCheckStart?.();
+                }, onScopeChoice: choice => {
+                    scopeChoice = choice;
+                    if (guarded && analysisFolder)
+                        lastAnalysis.delete(analysisFolder);
+                    options.onScopeChoice?.(choice);
                 }, onAgentChoice: choice => { agentChoice = choice; options.onAgentChoice?.(choice); }, onCheckComplete: result => {
                     findingIds = result.findingIds ?? [];
                     if (numbersEnabled) {
@@ -160,20 +210,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 +247,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,20 +282,25 @@ 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 });
                         try {
                             signal.throwIfAborted();
-                            const flow = await startSignIn(commandContext({ ...options, emailSignIn, findingSettings, homeDir: ctx.homeDir, baseUrl: ctx.api.baseUrl, signal: controller.signal }));
+                            const flow = await startSignIn(commandContext({ ...options, startup: ctx.startup, 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,30 +315,49 @@ export async function serveMcp(input, output, options = {}) {
             else {
                 const launchFolder = await launch;
                 if (guarded && !launchFolder)
-                    throw new Error(START_FAILURE_MESSAGE);
-                const folder = guarded ? await resolveMcpAgentFolder(args.path, launchFolder, ctx.homeDir) : resolveAgentFolder(args.path, cwd);
-                const last = lastAnalysis.get(folder);
+                    throw new CliRefusalError("launch_folder_unavailable");
+                const scope = await loadAnalysisScope({ scope: args.scope }, cwd, analysisSettings);
+                const selection = selectionEnabled ? await resolveAnalysisSelection(args.path, launchFolder ?? cwd, analysisSettings, scope) : undefined;
+                if (guarded && selection?.kind === "folder")
+                    await resolveMcpAgentFolder(selection.path, launchFolder, ctx.homeDir);
+                const folder = selection?.path ?? (guarded ? await resolveMcpAgentFolder(args.path, launchFolder, ctx.homeDir) : resolveAgentFolder(args.path, cwd));
+                const key = selection ? JSON.stringify([selection.launchRoot, selection.path]) : folder;
+                const last = lastAnalysis.get(key);
                 if (guarded && last !== undefined && ctx.now() - last < 10 * 60 * 1000) {
-                    throw new Error(FINISH_FAILURE_MESSAGE);
+                    throw new CliRefusalError("repeat_too_soon");
                 }
-                analysisFolder = folder;
+                analysisFolder = key;
                 try {
-                    exitCode = await analyze(folder, { proposal: args.proposal }, ctx);
+                    exitCode = await analyze(folder, { proposal: args.proposal, scope, selection }, ctx);
                 }
                 finally {
-                    if (guarded && started)
-                        lastAnalysis.set(folder, ctx.now());
+                    if (reason === "results_pending")
+                        lastAnalysis.delete(key);
+                    else if (guarded && started && !scopeChoice)
+                        lastAnalysis.set(key, ctx.now());
                 }
             }
         }
         catch (error) {
-            text += errorText(error) + "\n";
+            const failure = mcpFailure(error, failureReasons);
+            text += failure.message + "\n";
+            reason = failure.reason;
             exitCode = errorCode(error);
         }
+        if (scopeChoice) {
+            const refusal = scopeChoiceRefusal(scopeChoice);
+            if (!refusal)
+                return chooseScopeMcpResultSchema.parse({ content: [{ type: "text", text: scopeChoiceText(scopeChoice) }], isError: false,
+                    structuredContent: { ...scopeChoice, exitCode: 0 } });
+            text = refusal + "\n";
+            exitCode = 1;
+        }
         // 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/prior-completion.js

@@ -0,0 +1,35 @@
+import { discardCompletion, loadCompletions, matchesCompletionSetup } from "../adapters/completion.js";
+import { completionRecoveryDecision } from "./completion-recovery.js";
+export class CompletionSettingsMismatchError extends Error {
+    reason = "completion_settings_mismatch";
+}
+/** Leave other setups alone before the runner assigns any reservation or recovery state. */
+export async function priorCompletion(folder, options) {
+    const records = await loadCompletions(folder, { retainUnsaved: options.retryEnabled,
+        consoleOrigin: options.consoleOrigin, projectId: options.projectId, identity: options.identity });
+    const notices = new Set();
+    let prior;
+    for (const item of records) {
+        const { record } = item;
+        if ((record.uploaded || record.finished) && !options.retryUpload)
+            continue;
+        const localMismatch = !matchesCompletionSetup(record, options);
+        const decision = completionRecoveryDecision({ retryEnabled: options.retryEnabled, payload: record.payload,
+            localMismatch, timing: { completedAt: record.completedAt, absoluteExpiresAt: record.absoluteExpiresAt },
+            now: (options.now ?? Date.now)(), statusLookup: { kind: "skipped" }, uploadOutcome: { kind: record.uploaded ? "saved" : "pending" } });
+        if (decision.action === "leave") {
+            notices.add(decision.message);
+            continue;
+        }
+        if (localMismatch && decision.action === "give-up") {
+            await discardCompletion(folder, item.path, options.identity);
+            if (decision.message)
+                notices.add(decision.message);
+            continue;
+        }
+        if (localMismatch)
+            throw new CompletionSettingsMismatchError("message" in decision ? decision.message : undefined);
+        prior ??= item;
+    }
+    return { prior, notices: [...notices] };
+}