@counterfact-labs/cli 0.2.6 → 0.2.9

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 { fileScopeEnabled, readEmailSignIn, readSelectionSettings, scopeChoicesEnabled, multiEntryEnabled } 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,52 @@ import { balance } from "./commands/balance.js";
 import { login, parseLoginOptions } from "./commands/login.js";
 import { logout } from "./commands/logout.js";
 import { serveMcp } from "./mcp.js";
-const usage = "Usage: counterfact-labs analyze [path] [--proposal <json-file>]\n       counterfact-labs finding <id>\n       counterfact-labs balance | login | logout | mcp\n";
+import { folderPartsEnabled, skippedFilesEnabled } from "../analysis-core/settings.js";
+import { loadAnalysisScope } from "./scope-choices.js";
+import { FILE_SCOPE_PUBLIC_USAGE } from "../contract/scope-choice.js";
 export async function run(args, options = {}) {
+    const skippedUsage = skippedFilesEnabled(options.startup?.settings ?? options.env ?? process.env)
+        ? "       counterfact-labs analyze [path] [--show-skipped | --skipped-plan | --skipped]\n" : "";
+    const usage = `Usage: counterfact-labs analyze [path] [--proposal <json-file>]\n${skippedUsage}       counterfact-labs finding <id>\n       counterfact-labs balance | login | logout | mcp\n`;
     const write = options.write ?? (text => { process.stdout.write(text); });
     const emailSignIn = options.emailSignIn ?? readEmailSignIn(options.env);
-    const commandOptions = { ...options, emailSignIn };
+    let fileMode = false;
     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" });
+        fileMode = fileScopeEnabled(selectionSettings);
+        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, CF_MULTI_ENTRY: undefined,
+                }) } };
+        const choices = scopeChoicesEnabled(selectionSettings);
+        const scopeUsage = choices ? FILE_SCOPE_PUBLIC_USAGE : usage;
+        // Insert the skipped-files usage line after the first usage line.
+        const firstLineEnd = scopeUsage.indexOf("\n") + 1;
+        let commandUsage = choices && firstLineEnd > 0
+            ? `${scopeUsage.slice(0, firstLineEnd)}${skippedUsage}${scopeUsage.slice(firstLineEnd)}`
+            : scopeUsage;
+        if (folderPartsEnabled(env))
+            commandUsage = commandUsage.replace(choices ? "[--scope <json-file>]" : "[--proposal <json-file>]", choices ? "[--scope <json-file | json-list>]" : "[--proposal <json-file>] [--scope <json-list>]");
         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, multiEntryEnabled(selectionSettings));
             }
             catch {
-                throw new Error(usage.trimEnd());
+                throw new Error(commandUsage.trimEnd());
             }
-            return await analyze(parsed.path, parsed.options, commandContext(commandOptions));
+            const ctx = commandContext(commandOptions);
+            if (Array.isArray(parsed.options.scope) && !folderPartsEnabled(ctx.startup.settings))
+                throw new Error(commandUsage.trimEnd());
+            const scope = Array.isArray(parsed.options.scope) ? parsed.options.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 +65,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,10 +81,10 @@ 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");
+        write(errorText(error, fileMode) + "\n");
         return errorCode(error);
     }
 }

package/dist/cli/mcp-failure.js

@@ -1,8 +1,9 @@
 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);
+import { cliApiMessages } from "../contract/cli-api-messages.js";
+import { errorText, SavedSignInError } from "./api.js";
+export function mcpFailure(error, enabled, fileMode = true) {
+    const message = error instanceof SavedSignInError ? cliApiMessages.unreadable_sign_in
+        : !enabled && !fileMode && error instanceof CliRefusalError && error.code === "outside_project"
+            ? START_FAILURE_MESSAGE : errorText(error, fileMode);
     return { message, ...(enabled ? { reason: failureReason(error) } : {}) };
 }

package/dist/cli/mcp.js

@@ -1,11 +1,15 @@
+import { folderPartsEnabled, skippedFilesEnabled } from "../analysis-core/settings.js";
+import { readSkippedFilesSetting, readFolderPartsSetting } from "../adapters/settings.js";
 import { createInterface } from "node:readline";
 import { once } from "node:events";
 import { resolveFolderPath } from "../adapters/folder-path.js";
-import { CliRefusalError, failureReason } from "../contract/cli-refusals.js";
+import { cliRefusals, CliRefusalError, failureReason } from "../contract/cli-refusals.js";
 import { mcpFailure } from "./mcp-failure.js";
+import { agentChoiceMessage } from "../contract/agent-choice.js";
 import { errorCode } from "./api.js";
 import { commandContext } from "./context.js";
 import { analyze } from "./commands/analyze.js";
+import { skipped } from "./commands/skipped.js";
 import { CLI_VERSION } from "../contract/cli-version.js";
 import { finding } from "./commands/finding.js";
 import { balance } from "./commands/balance.js";
@@ -19,8 +23,48 @@ import { suggestedEmail } from "./suggested-email.js";
 import { agentProposalInputSchema } from "../contract/agent-proposal.js";
 import { fixRequestTools, waitingFixes, waitingFixCount, claimFix, FIX_DISCOVERY_TIMEOUT_MS } from "./fix-requests.js";
 import { FINDING_PROJECT_MESSAGE, FindingReferences, numberedFindingInputSchema } from "./finding-lookup.js";
-import { findingDisplayRows, formatFindingNumber, formatWaitingFixes } from "./finding-display.js";
+import { formatFindingNumber, formatWaitingFixes, formatFindingActivity, presentSavedFindings, findingDetailReference, formatFindingContinuation } from "./finding-display.js";
+import { groupByActivity } from "../analysis-core/analysis/schemas.js";
 import { readFindingSettings } from "./finding-settings.js";
+import { sizeSkippedFiles } from "../analysis-core/analysis/code-agents/skipped-files.js";
+import { z } from "zod";
+import { fileScopeEnabled, readCliSettings, readSelectionSettings, selectionModeEnabled, scopeChoicesEnabled, multiEntryEnabled } 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.";
+const multiAnalysisDescription = "Analyze an agent folder, one agent file, or several agent files on this computer. Pass path for one folder or file, or paths for several files inside the launch folder. Counterfact includes each file's project imports and reads shared files once. Up to 5 agent files run as one analysis with one result list and one charge unless a free analysis is available. If the selection is too large or has more than 5 agent files, Counterfact returns scope choices. Call 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 multiPathsDescription = "Optional: several agent file paths inside the launch folder, analyzed together. Use either path or paths. Folders cannot be mixed into paths.";
+const partChoiceDescription = " If parts are returned, ask the user to choose one, then call analyze_agent again with that part's files as scope.";
+const partScopeSchema = { type: "array", items: { type: "string" }, minItems: 1,
+    description: "The files in the part the user chose. Ask the user to pick a returned part before supplying scope." };
+function fileAnalysisTool(choices, parts, multiple) {
+    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;
+    if (!multiple && scope.properties)
+        delete scope.properties.entries;
+    const scopeSchema = parts && choices ? { anyOf: [scope, partScopeSchema] } : parts ? partScopeSchema : scope;
+    return { name: ANALYZE_TOOL_NAME,
+        description: [multiple ? multiAnalysisDescription : fileAnalysisDescription, ...(choices ? [scopeChoiceDescription] : []), fileAnalysisEnding].join(" ") + (parts ? partChoiceDescription : ""),
+        inputSchema: { type: "object", properties: { path: { type: "string", description: filePathDescription },
+                ...(multiple ? { paths: { type: "array", items: { type: "string" }, minItems: 1, description: multiPathsDescription } } : {}),
+                proposal: { ...proposal, description: fileProposalDescription }, ...(choices || parts ? { scope: { ...scopeSchema, description: choices && parts
+                            ? `${fileScopeDescription} ${partScopeSchema.description}` : parts ? partScopeSchema.description : fileScopeDescription } } : {}) },
+            ...(multiple ? {} : { required: ["path"] }), additionalProperties: false } };
+}
 const legacyTools = [
     {
         name: ANALYZE_TOOL_NAME,
@@ -32,6 +76,12 @@ const legacyTools = [
     { 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 } },
 ];
+const skippedTool = {
+    name: "analyze_skipped_files",
+    description: "Handle files skipped by the saved analysis of a local folder. Use action files to list their names, or plan to find the fewest analyses that fit, including imported files. Tell the user that count before starting. Use action analyze only after the user accepts the offer to analyze the skipped files. Findings are added to the same results.",
+    inputSchema: { type: "object", properties: { path: { type: "string", description: "The original agent folder on this computer." },
+            action: { type: "string", enum: ["files", "plan", "analyze"] } }, required: ["path", "action"], additionalProperties: false },
+};
 class ProtocolError extends Error {
     code;
     constructor(code, message) {
@@ -39,6 +89,7 @@ class ProtocolError extends Error {
         this.code = code;
     }
 }
+const MAX_ANALYSIS_FINDING_HISTORY = 5;
 function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
 export async function serveMcp(input, output, options = {}) {
     const audienceChoice = (options.env ?? process.env).CF_FINDING_AUDIENCE;
@@ -47,10 +98,24 @@ export async function serveMcp(input, output, options = {}) {
     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 { numbersEnabled, fixesEnabled } = findingSettings;
+    const startupSettings = options.startup?.settings ?? options.env ?? process.env;
+    const skippedSettings = Object.freeze({ CF_SKIPPED_FILES: readSkippedFilesSetting(startupSettings.CF_SKIPPED_FILES) });
+    const skippedEnabled = skippedFilesEnabled(skippedSettings);
+    const partSettings = Object.freeze({ CF_FOLDER_PARTS: readFolderPartsSetting(startupSettings.CF_FOLDER_PARTS) });
+    const scopeEnabled = folderPartsEnabled({ ...skippedSettings, ...partSettings });
+    const findingSettings = options.findingSettings ?? readFindingSettings(options.env);
+    const notActiveFindings = new Map();
+    const analysisFindings = new Map();
+    const { numbersEnabled, fixesEnabled, agentReadableResults } = findingSettings;
+    const analysisSwitches = readSelectionSettings(startupSettings);
+    const choicesEnabled = scopeChoicesEnabled(analysisSwitches);
+    const selectionEnabled = selectionModeEnabled(analysisSwitches);
+    const multipleEnabled = multiEntryEnabled(analysisSwitches);
+    const analysisEnv = selectionEnabled ? { ...(options.env ?? process.env), ...analysisSwitches } : undefined;
+    let analysisStartup = options.startup;
     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",
@@ -76,9 +141,19 @@ export async function serveMcp(input, output, options = {}) {
                 }, required: ["email", "code"], additionalProperties: false },
         },
     ] : legacyTools;
-    const tools = signInTools.map(tool => tool.name === "get_finding" && numbersEnabled ? {
-        ...tool, inputSchema: numberedFindingInputSchema,
-    } : tool).concat(fixesEnabled ? fixRequestTools : []);
+    const tools = [...signInTools.map(tool => {
+            if (tool.name === ANALYZE_TOOL_NAME) {
+                if (selectionEnabled)
+                    return fileAnalysisTool(choicesEnabled, scopeEnabled, multipleEnabled);
+                if (scopeEnabled)
+                    return { ...tool,
+                        description: tool.description + partChoiceDescription,
+                        inputSchema: { ...tool.inputSchema, properties: { ...tool.inputSchema.properties, scope: partScopeSchema } } };
+            }
+            return tool;
+        }).map(tool => tool.name === "get_finding" && numbersEnabled ? {
+            ...tool, inputSchema: numberedFindingInputSchema,
+        } : tool), ...(fixesEnabled ? fixRequestTools : []), ...(skippedEnabled ? [skippedTool] : [])];
     let pendingSignIn;
     let signInFailure;
     const requests = new Map();
@@ -91,14 +166,21 @@ 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_skipped_files" ? ["path", "action"] : name === ANALYZE_TOOL_NAME ? ["path", "proposal", ...(multipleEnabled ? ["paths"] : []), ...((scopeEnabled || 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"] : [];
         if (!tools.some(tool => tool.name === name) || Object.keys(args).some(key => !allowed.includes(key)))
             throw new ProtocolError(-32602, "Unknown tool or argument.");
-        if (name === ANALYZE_TOOL_NAME && (typeof args.path !== "string" || !args.path.trim()))
+        if (name === ANALYZE_TOOL_NAME && (args.paths === undefined
+            ? typeof args.path !== "string" || !args.path.trim()
+            : args.path !== undefined || !Array.isArray(args.paths) || !args.paths.length || args.paths.some(path => typeof path !== "string" || !path.trim()))) {
+            throw new ProtocolError(-32602, "Provide a path.");
+        }
+        if (name === "analyze_skipped_files" && (typeof args.path !== "string" || !args.path.trim()))
             throw new ProtocolError(-32602, "Provide a path.");
+        if (name === "analyze_skipped_files" && !["files", "plan", "analyze"].includes(args.action))
+            throw new ProtocolError(-32602, "Choose files, plan, or analyze.");
         if (name === "get_finding" && (typeof args.id !== "string" || !args.id.trim()))
             throw new ProtocolError(-32602, "Provide a finding id.");
         if (name === "get_finding" && args.projectId !== undefined && (typeof args.projectId !== "string" || !args.projectId.trim()))
@@ -117,27 +199,63 @@ export async function serveMcp(input, output, options = {}) {
         let reason;
         let freeAnalysisAvailable = false;
         let agentChoice;
+        let scopeChoice;
         let findingIds;
         let findings, projectId;
+        let skippedFilesCount;
+        let topFindingIds;
+        let notActiveCount, analysisId;
+        let nextFinding;
         let loadedFinding;
+        let notActiveHint = "";
         let fixRequests, claimed;
         let waitingCount;
         let url, analysisFolder;
         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, ...skippedSettings, ...partSettings, 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 ?? [];
+                    topFindingIds = result.topFindingIds;
+                    if (skippedEnabled && result.skippedFiles)
+                        skippedFilesCount = sizeSkippedFiles(result.skippedFiles).length;
+                    const groups = groupByActivity(result.findings ?? [], result.notActiveEnabled);
+                    notActiveFindings.set(result.projectId, groups.notActive);
+                    if (groups.notActive.length) {
+                        notActiveCount = groups.notActive.length;
+                        analysisId = result.analysisId;
+                        const ids = groups.notActive.map(finding => numbersEnabled && finding.seq !== undefined ? formatFindingNumber(finding.seq) : finding.id);
+                        notActiveHint = `Not active details: use get_finding for ${ids.join(", ")}.\n`;
+                    }
                     if (numbersEnabled) {
-                        findings = findingDisplayRows(result.findings ?? [], { numbersEnabled,
-                            audienceEnabled: result.audienceEnabled, labels: "reference" }).map(row => row.finding);
+                        const displayed = presentSavedFindings(result, { numbersEnabled, agentReadableResults,
+                            audienceEnabled: result.audienceEnabled, notActiveEnabled: result.notActiveEnabled, projectId: result.projectId, surface: "mcp" });
+                        findings = displayed.findings;
+                        findingIds = displayed.findingIds;
+                        nextFinding = displayed.nextFinding;
+                        if (agentReadableResults && result.analysisId !== undefined) {
+                            analysisFindings.delete(result.analysisId);
+                            analysisFindings.set(result.analysisId, { projectId: result.projectId, findings: displayed.orderedReferences });
+                            // Older details remain available from the console without keeping every chain in memory.
+                            if (analysisFindings.size > MAX_ANALYSIS_FINDING_HISTORY)
+                                analysisFindings.delete(analysisFindings.keys().next().value);
+                        }
                         projectId = result.projectId;
                         references.remember(result.projectId);
                     }
@@ -161,9 +279,23 @@ export async function serveMcp(input, output, options = {}) {
             else if (name === "get_finding") {
                 const project = numbersEnabled ? await references.resolve(args.id, args.projectId, fixesEnabled ? () => waitingFixes(ctx.api, { timeoutMs: FIX_DISCOVERY_TIMEOUT_MS }) : undefined) : undefined;
                 await finding(args.id, ctx, { projectId: project, numbers: numbersEnabled, onLoaded: value => {
-                        if (numbersEnabled)
-                            loadedFinding = { ...value, ...(value.seq !== undefined ? { number: formatFindingNumber(value.seq) } : {}) };
+                        // Older consoles retain the finding and fixes but may not store its activity yet.
+                        const activity = [...notActiveFindings.values()].flat().find(saved => saved.id === value.id)?.activity;
+                        if (activity)
+                            ctx.write(formatFindingActivity(activity));
+                        if (numbersEnabled || activity)
+                            loadedFinding = { ...value, ...(activity ? { activity } : {}),
+                                ...(numbersEnabled && value.seq !== undefined ? { number: formatFindingNumber(value.seq) } : {}) };
+                        if (agentReadableResults && numbersEnabled) {
+                            for (const { projectId, findings } of analysisFindings.values()) {
+                                const index = findings.findIndex(item => item.id === value.id);
+                                if (index >= 0 && findings[index + 1])
+                                    nextFinding = findingDetailReference(findings[index + 1], projectId);
+                            }
+                        }
                     } });
+                if (nextFinding)
+                    text += formatFindingContinuation(nextFinding);
             }
             else if (name === "get_balance")
                 await balance(ctx, { onLoaded: value => { freeAnalysisAvailable = value.freeAnalysisAvailable; } });
@@ -208,7 +340,7 @@ export async function serveMcp(input, output, options = {}) {
                 const failure = signInFailure;
                 signInFailure = undefined;
                 if (failure && !signIn.signedIn) {
-                    const shown = mcpFailure(failure.error, failureReasons);
+                    const shown = mcpFailure(failure.error, failureReasons, fileScopeEnabled(analysisSwitches));
                     text = (failure.error instanceof SignInExpiredError
                         ? emailSignInMessages.mcp_expired : failure.error instanceof SignInDeniedError
                         ? emailSignInMessages.mcp_cancelled : shown.message) + "\n";
@@ -244,7 +376,7 @@ export async function serveMcp(input, output, options = {}) {
                         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;
@@ -272,34 +404,67 @@ export async function serveMcp(input, output, options = {}) {
                 const launchFolder = await launch;
                 if (guarded && !launchFolder)
                     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) {
+                const partScope = Array.isArray(args.scope) ? args.scope : undefined;
+                if (partScope && (!scopeEnabled || args.proposal !== undefined))
+                    throw new Error(cliRefusals.invalid_body);
+                const scope = partScope ? undefined : await loadAnalysisScope({ scope: args.scope }, cwd, analysisSettings);
+                const selection = selectionEnabled ? await resolveAnalysisSelection((args.paths ?? 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 request = selection?.request;
+                const originalEntries = request?.kind === "file" ? request.entries ?? [request.entry] : undefined;
+                const chosen = request?.kind === "file" ? request.scope : undefined;
+                const includedEntries = originalEntries && (request?.kind === "file" && request.entries && chosen && chosen.imports !== "all"
+                    ? originalEntries.filter(entry => entry === chosen.entry || Array.isArray(chosen.imports) && chosen.imports.includes(entry))
+                    : originalEntries);
+                const key = selection ? includedEntries
+                    ? JSON.stringify([selection.launchRoot, [...includedEntries].sort()]) : JSON.stringify([selection.launchRoot, selection.path]) : folder;
+                const last = lastAnalysis.get(key);
+                if (name === ANALYZE_TOOL_NAME && guarded && last !== undefined && ctx.now() - last < 10 * 60 * 1000) {
                     throw new CliRefusalError("repeat_too_soon");
                 }
-                analysisFolder = folder;
+                analysisFolder = key;
                 try {
-                    exitCode = await analyze(folder, { proposal: args.proposal }, ctx);
+                    exitCode = name === "analyze_skipped_files" ? await skipped(folder, args.action, ctx, analyze, "mcp")
+                        : await analyze(folder, { proposal: args.proposal, scope: partScope ?? scope, selection, surface: "mcp", analyzedFolder: args.path }, 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) {
-            const failure = mcpFailure(error, failureReasons);
+            const failure = mcpFailure(error, failureReasons, fileScopeEnabled(analysisSwitches));
             text += failure.message + "\n";
             reason = failure.reason;
             exitCode = errorCode(error);
         }
+        // Choices return before other output today; replace the terminal command list with the names-only MCP list.
+        if (agentChoice?.kind === "choose_scope")
+            text = agentChoiceMessage(agentChoice, "mcp") + "\n";
+        text += notActiveHint;
+        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 } : {}),
+                ...(skippedFilesCount ? { skippedFilesCount } : {}),
+                ...(topFindingIds ? { topFindingIds } : {}),
+                ...(notActiveCount === undefined ? {} : { notActiveCount }), ...(analysisId === undefined ? {} : { analysisId }),
+                ...(findings ? { findings, projectId } : {}), ...(nextFinding ? { nextFinding } : {}), ...(loadedFinding ? { finding: loadedFinding } : {}),
                 ...(fixRequests ? { fixRequests } : {}), ...claimed, ...(waitingCount !== undefined ? { waitingFixes: waitingCount } : {}) } };
     }
     async function respond(message, id, signal) {

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] };
+}