@counterfact-labs/cli 0.2.9 → 0.2.11

package/dist/cli/git.js

@@ -1,3 +1,4 @@
+import { realpath } from "node:fs/promises";
 import { basename, relative, resolve, sep } from "node:path";
 import { gitRepositoryRoot } from "../adapters/repository-root.js";
 import { runGit } from "../adapters/git.js";
@@ -10,7 +11,9 @@ export async function userEmail(folder, git = async (args) => (await runGit(fold
     }
 }
 export async function repositoryFacts(root, git = async (args) => (await runGit(root, args)).toString("utf8")) {
-    const folderName = basename(resolve(root));
+    // Git reports the physical checkout root, so resolve aliases before deriving its selected folder.
+    const selected = await realpath(root).catch(() => resolve(root));
+    const folderName = basename(selected);
     const repoRoot = await gitRepositoryRoot(git);
     if (repoRoot === null)
         return { remoteUrl: null, relPath: "", folderName, branch: null, commit: null, dirty: null };
@@ -34,6 +37,6 @@ export async function repositoryFacts(root, git = async (args) => (await runGit(
         // Include new files even when Git hides them, and exclude sibling folders.
         read(["status", "--porcelain=v2", "--no-renames", "--ignore-submodules=all", "--untracked-files=normal", "--", "."]),
     ]);
-    return { repoRoot, remoteUrl, relPath: relative(repoRoot, root).split(sep).join("/"), folderName,
+    return { repoRoot, remoteUrl, relPath: relative(repoRoot, selected).split(sep).join("/"), folderName,
         branch: branch === "HEAD" ? null : branch || null, commit: commit || null, dirty: status === null ? null : status.length > 0 };
 }

package/dist/cli/intake-payload.js

@@ -38,8 +38,7 @@ export function buildIntakePayload(identity, agent, report, options = {}) {
             delete legacy.activity;
             return legacy;
         });
-    const architecture = options.consoleSupportsArchitecture === true && options.settings?.CF_LOCAL_ARCHITECTURE === "1"
-        ? projectArchitecture(report.graph) : undefined;
+    const architecture = options.settings?.CF_LOCAL_ARCHITECTURE === "1" ? projectArchitecture(report.graph) : undefined;
     let result = localFindingsPayloadSchema.safeParse({ ...identity, agent, findings, ...metadata, ...(architecture ? { architecture } : {}) });
     // Optional map metadata must not crowd otherwise valid findings out of the total upload allowance.
     if (!result.success && architecture)

package/dist/cli/main.js

@@ -14,6 +14,8 @@ import { folderPartsEnabled, skippedFilesEnabled } from "../analysis-core/settin
 import { loadAnalysisScope } from "./scope-choices.js";
 import { FILE_SCOPE_PUBLIC_USAGE } from "../contract/scope-choice.js";
 export async function run(args, options = {}) {
+    const previewEnabled = (options.startup?.transport ?? options.env ?? process.env).CF_FILES_PREVIEW !== "0";
+    const previewUsage = previewEnabled ? "       counterfact-labs analyze [path] --preview\n" : "";
     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`;
@@ -28,7 +30,7 @@ export async function run(args, options = {}) {
         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,
+                    CF_FILE_SCOPE: undefined, CF_SCOPE_CHOICES: undefined, CF_LOCAL_IMPORT_RESOLUTION: undefined, CF_MULTI_ENTRY: undefined, CF_PYTHON_SRC_IMPORTS: undefined,
                 }) } };
         const choices = scopeChoicesEnabled(selectionSettings);
         const scopeUsage = choices ? FILE_SCOPE_PUBLIC_USAGE : usage;
@@ -37,6 +39,10 @@ export async function run(args, options = {}) {
         let commandUsage = choices && firstLineEnd > 0
             ? `${scopeUsage.slice(0, firstLineEnd)}${skippedUsage}${scopeUsage.slice(firstLineEnd)}`
             : scopeUsage;
+        if (previewUsage) {
+            const end = commandUsage.indexOf("\n") + 1;
+            commandUsage = commandUsage.slice(0, end) + previewUsage + commandUsage.slice(end);
+        }
         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) {
@@ -46,7 +52,7 @@ export async function run(args, options = {}) {
         if (command === "analyze") {
             let parsed;
             try {
-                parsed = parseAnalyzeOptions(rest, choices, multiEntryEnabled(selectionSettings));
+                parsed = parseAnalyzeOptions(rest, choices, multiEntryEnabled(selectionSettings), previewEnabled);
             }
             catch {
                 throw new Error(commandUsage.trimEnd());

package/dist/cli/mcp.js

@@ -20,6 +20,7 @@ import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
 import { EMAIL_SIGN_IN_TERMS, normalizeSignInEmail, validSignInCode, startEmailSignIn, signInWithCode } from "./email-sign-in.js";
 import { resolveAgentFolder, resolveMcpAgentFolder } from "./agent-folder.js";
 import { suggestedEmail } from "./suggested-email.js";
+import { checkSignInVersion } from "./compatibility.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";
@@ -95,10 +96,12 @@ 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 retryAfterFailure = (options.env ?? process.env).CF_MCP_RETRY_AFTER_FAILURE !== "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 startupSettings = options.startup?.settings ?? options.env ?? process.env;
+    const scanPriority = startupSettings.CF_CODE_SCAN_PRIORITY;
     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) });
@@ -108,10 +111,12 @@ export async function serveMcp(input, output, options = {}) {
     const analysisFindings = new Map();
     const { numbersEnabled, fixesEnabled, agentReadableResults } = findingSettings;
     const analysisSwitches = readSelectionSettings(startupSettings);
+    const signInSettings = Object.freeze({ CF_CLI_SIGN_IN_VERSION_CHECK: options.startup
+            ? options.startup.signInVersionCheck ? "1" : "0" : (options.env ?? process.env).CF_CLI_SIGN_IN_VERSION_CHECK });
     const choicesEnabled = scopeChoicesEnabled(analysisSwitches);
     const selectionEnabled = selectionModeEnabled(analysisSwitches);
     const multipleEnabled = multiEntryEnabled(analysisSwitches);
-    const analysisEnv = selectionEnabled ? { ...(options.env ?? process.env), ...analysisSwitches } : undefined;
+    const analysisEnv = selectionEnabled ? { ...(options.env ?? process.env), ...analysisSwitches, ...signInSettings } : undefined;
     let analysisStartup = options.startup;
     const references = new FindingReferences();
     const emailEnv = analysisEnv && Object.hasOwn(analysisEnv, "CF_EMAIL_SIGN_IN") ? analysisEnv : options.env;
@@ -218,19 +223,27 @@ export async function serveMcp(input, output, options = {}) {
             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); },
+            const ctx = commandContext({ ...options, ...(analysisStartup ? { startup: analysisStartup } : {}), env: { ...(analysisEnv ?? options.env ?? process.env), ...analysisSwitches, ...skippedSettings, ...partSettings, ...signInSettings, CF_CODE_SCAN_PRIORITY: scanPriority, CF_FINDING_AUDIENCE: audienceChoice },
+                onCheckFailure: failure => {
+                    reason = failure.reason;
+                    if (guarded && retryAfterFailure && analysisFolder && failure.charged && !url) {
+                        lastAnalysis.set(analysisFolder, { at: ctx.now(), charged: true });
+                    }
+                    options.onCheckFailure?.(failure);
+                },
                 emailSignIn, findingSettings, signal, onCheckStart: () => {
                     started = true;
-                    if (guarded && analysisFolder)
-                        lastAnalysis.set(analysisFolder, ctx.now());
+                    if (guarded && !retryAfterFailure && analysisFolder)
+                        lastAnalysis.set(analysisFolder, { at: ctx.now() });
                     options.onCheckStart?.();
                 }, onScopeChoice: choice => {
                     scopeChoice = choice;
-                    if (guarded && analysisFolder)
+                    if (guarded && !retryAfterFailure && analysisFolder)
                         lastAnalysis.delete(analysisFolder);
                     options.onScopeChoice?.(choice);
                 }, onAgentChoice: choice => { agentChoice = choice; options.onAgentChoice?.(choice); }, onCheckComplete: result => {
+                    if (guarded && analysisFolder && retryAfterFailure)
+                        lastAnalysis.set(analysisFolder, { at: ctx.now(), url: result.url });
                     findingIds = result.findingIds ?? [];
                     topFindingIds = result.topFindingIds;
                     if (skippedEnabled && result.skippedFiles)
@@ -266,6 +279,8 @@ export async function serveMcp(input, output, options = {}) {
                     if (!chunk.startsWith("\r"))
                         text += chunk;
                 } });
+            if (name === "sign_in_status" || name === "sign_in" || name === "sign_in_with_code")
+                await checkSignInVersion(ctx);
             if (name === "waiting_fixes") {
                 const waiting = await waitingFixes(ctx.api);
                 fixRequests = waiting;
@@ -303,9 +318,11 @@ export async function serveMcp(input, output, options = {}) {
                 const pending = pendingSignIn;
                 const allowed = await analyzeToolAllowed(ctx.homeDir, cwd);
                 if (args.wait === true && pending) {
+                    let completed = false;
                     if (pending.flow.retryEnabled) {
                         try {
                             await waitForSignIn(pending.flow, signal);
+                            completed = true;
                         }
                         catch (error) {
                             if (signal.aborted)
@@ -320,13 +337,19 @@ export async function serveMcp(input, output, options = {}) {
                             if (signal.aborted)
                                 cancel();
                             await pending.flow.done;
+                            completed = true;
                         }
                         finally {
                             signal.removeEventListener("abort", cancel);
                         }
                     }
+                    if (completed)
+                        await checkSignInVersion(ctx);
                 }
                 signIn = { ...await signInStatus(ctx), analyzeToolAllowed: allowed };
+                // The browser flow may finish and clear itself while the initial unsigned probe is in flight.
+                if (args.wait === true && !pending && signIn.signedIn)
+                    await checkSignInVersion(ctx);
                 if (fixesEnabled)
                     waitingCount = signIn.signedIn ? await waitingFixCount(ctx.api) : 0;
                 text = signIn.signedIn ? "Signed in." : "Not signed in.";
@@ -359,6 +382,7 @@ export async function serveMcp(input, output, options = {}) {
                 }
                 else {
                     await signInWithCode(ctx, email, args.code);
+                    await checkSignInVersion(ctx);
                     signInFailure = undefined;
                     signIn = { signedIn: true };
                     text = "Signed in.";
@@ -421,8 +445,9 @@ export async function serveMcp(input, output, options = {}) {
                 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");
+                if (name === ANALYZE_TOOL_NAME && guarded && last !== undefined && ctx.now() - last.at < 10 * 60 * 1000) {
+                    throw new CliRefusalError("repeat_too_soon", retryAfterFailure
+                        ? { retryAt: last.at + 10 * 60 * 1000, url: last.url, charged: last.charged } : undefined);
                 }
                 analysisFolder = key;
                 try {
@@ -432,8 +457,8 @@ export async function serveMcp(input, output, options = {}) {
                 finally {
                     if (reason === "results_pending")
                         lastAnalysis.delete(key);
-                    else if (guarded && started && !scopeChoice)
-                        lastAnalysis.set(key, ctx.now());
+                    else if (!retryAfterFailure && guarded && started && !scopeChoice)
+                        lastAnalysis.set(key, { at: ctx.now() });
                 }
             }
         }

package/dist/cli/prior-completion.js

@@ -22,7 +22,7 @@ export async function priorCompletion(folder, options) {
             continue;
         }
         if (localMismatch && decision.action === "give-up") {
-            await discardCompletion(folder, item.path, options.identity);
+            await discardCompletion(folder, item.path, options.identity, { keepCopy: false });
             if (decision.message)
                 notices.add(decision.message);
             continue;

package/dist/cli/relay-check.js

@@ -1,3 +1,4 @@
+import { countForm } from "../analysis-core/wording.js";
 import { skippedFilesEnabled } from "../analysis-core/settings.js";
 import { analysisSkippedFiles, sizeSkippedFiles } from "../analysis-core/analysis/code-agents/skipped-files.js";
 import { loadAnalysisResults, loadPublicReport, saveAnalysisContext, settleAnalysisContext } from "../adapters/analysis-results.js";
@@ -7,17 +8,18 @@ import { randomUUID } from "node:crypto";
 import { disabledSetupPings } from "../setup-pings/client.js";
 import { fileScopeEnabled, scopeChoicesEnabled } from "../adapters/settings.js";
 import { saveCompletion, discardCompletion, lockCompletion } from "../adapters/completion.js";
+import { CompletionBusyError } from "../adapters/completion-lock.js";
 import { saveLocalResults } from "../adapters/results.js";
-import { GITIGNORE_OUTPUT_NOTICE } from "../adapters/gitignore-output.js";
+import { loadResultReceipt, saveResultReceipt, readResultReceipt, verifiedResultPaths } from "../adapters/result-receipt.js";
 import { priorCompletion } from "./prior-completion.js";
-import { OutputPathError, outputPaths } from "../adapters/output-paths.js";
+import { outputPaths, reportOutputDirectory } from "../adapters/output-paths.js";
 import { validateClientRelease } from "../adapters/release.js";
 import { selectAnalysisExecution } from "../adapters/models.js";
 import { resolveFolderPath } from "../adapters/folder-path.js";
 import { AgentChoiceError } from "../contract/agent-choice.js";
 import { savedAnalysisUrl, savedArchitectureUrl } from "../contract/console-url.js";
 import { prepareRelayCheck, prepareFolderChoice } from "./relay-preparation.js";
-import { cliRefusals, refusalExitCode } from "../contract/cli-refusals.js";
+import { cliRefusals, failureReason, refusalExitCode } from "../contract/cli-refusals.js";
 import { ConsoleClient, ConsoleError } from "../gatekeeper/console.js";
 import { GatekeeperClient } from "../gatekeeper/client.js";
 import { connectRelay, relayOrigin } from "../gatekeeper/connection.js";
@@ -37,6 +39,7 @@ import { SCOPE_CHOICE_EXIT_CODE, progressLine } from "../contract/scope-choice.j
 import { ScopeChoiceError, scopeChoiceRefusal, selectionScopeChoices } from "../contract/selection-offer.js";
 import { fileScopeOf } from "../analysis-core/analysis/file-analysis-plan.js";
 const stateLine = (status) => `Reservation ${status.state}; settlement ${status.settlement}; lease ${new Date(status.expiresAt).toLocaleString("en-US", { timeZone: "America/Los_Angeles", timeZoneName: "short" })}.\n`;
+const reservationExpiredError = () => Object.assign(new Error(), { reason: "reservation_expired" });
 export function runRelayCheck(folder, options) {
     return runRelayLifecycle(folder, options);
 }
@@ -47,10 +50,12 @@ export function runReservedRelayCheck(folder, options) {
 async function runRelayLifecycle(folder, options, existing) {
     const { config, stdout, stderr } = options;
     const retainUnsaved = config.CF_LOCAL_RESULTS_RETRY !== "0";
+    const keepLocalResults = config.CF_LOCAL_RESULTS_KEEP !== "0";
     let settings = options.settings;
     const summaryOptions = { audienceEnabled: false, notActiveEnabled: false, skippedFilesEnabled: skippedFilesEnabled(settings), skippedOffer: !options.addToAnalysisId, analyzedFolder: options.analyzedFolder ?? folder };
     let skippedFiles = [];
     let client, reservationId, projectId;
+    let consoleSupportsFailureReason = options.consoleSupportsFailureReason ?? false;
     let connection = existing?.connection;
     let completedPayload;
     let displayFindings;
@@ -67,6 +72,10 @@ async function runRelayLifecycle(folder, options, existing) {
     let releaseCompletion;
     let localErrorMessage;
     let completionStored = false, lostCompletionLock = false;
+    let localPaths;
+    let localReportReceipt;
+    let retainedPath;
+    let internalAbortCause;
     let uploadOutcome;
     let savedResult;
     const controller = new AbortController();
@@ -75,11 +84,17 @@ async function runRelayLifecycle(folder, options, existing) {
     const uploadSignal = retainUnsaved ? options.signal ?? new AbortController().signal : signal;
     const persist = async (payload, origin, uploaded = false, finished = false) => {
         if (lostCompletionLock)
-            throw new OutputPathError();
+            throw new CompletionBusyError();
         const path = await saveCompletion(folder, payload, origin, { uploaded, finished, completedAt: completionTiming.completedAt,
             absoluteExpiresAt: completionTiming.absoluteExpiresAt, retainUnsaved, identity: completionIdentity });
         completionStored = true;
         completionRecordPath = path;
+        if (localReportReceipt) {
+            try {
+                await saveResultReceipt(path, payload.checkId, localReportReceipt);
+            }
+            catch { /* A receipt is optional; the pending payload already preserves the results. */ }
+        }
         return path;
     };
     const submit = (payload, alreadySaved = false) => {
@@ -144,14 +159,18 @@ async function runRelayLifecycle(folder, options, existing) {
                 Object.assign(error, { localOperation: "read" });
             throw error;
         });
-        outputDir ??= selection?.outputDir;
+        outputDir = await reportOutputDirectory(folder, outputDir ?? selection?.outputDir);
         if (selection?.kind === "file")
             completionIdentity = {
                 consoleOrigin: new URL(config.CF_CONSOLE_URL).origin, selectionKey: selection.selectionKey,
             };
         signal.throwIfAborted();
         if (retainUnsaved)
-            releaseCompletion = await lockCompletion(folder, () => { lostCompletionLock = true; controller.abort(); }, completionIdentity);
+            releaseCompletion = await lockCompletion(folder, () => {
+                lostCompletionLock = true;
+                internalAbortCause = new CompletionBusyError();
+                controller.abort();
+            }, completionIdentity);
         const recovery = await priorCompletion(folder, { retryEnabled: retainUnsaved,
             consoleOrigin: new URL(config.CF_CONSOLE_URL).origin, projectId: existing?.expectedProjectId, retryUpload: options.retryUpload,
             identity: completionIdentity });
@@ -173,6 +192,17 @@ async function runRelayLifecycle(folder, options, existing) {
             completedPayload = prior.payload;
             skippedFiles = prior.payload.coverage?.skippedFiles ?? [];
             completionOrigin = prior.consoleOrigin;
+            if (keepLocalResults) {
+                try {
+                    const receipt = await loadResultReceipt(path, prior.payload.checkId);
+                    if (receipt) {
+                        localPaths = await verifiedResultPaths(folder, receipt);
+                        if (localPaths)
+                            localReportReceipt = receipt;
+                    }
+                }
+                catch { /* Missing or changed reports cannot justify deleting the pending payload. */ }
+            }
             completionTiming = { completedAt: prior.completedAt, absoluteExpiresAt: prior.absoluteExpiresAt };
             uploaded = prior.uploaded ?? false;
             reservationId = prior.payload.reservationId;
@@ -187,12 +217,14 @@ async function runRelayLifecycle(folder, options, existing) {
         signal.throwIfAborted();
         if (options.retryUpload)
             throw new Error("The saved completion record is missing. Keep the local report and check the output directory.");
-        // Negotiate once before paid work: older strict intake schemas cannot accept optional metadata.
-        const capabilities = skippedFilesEnabled(settings) && options.skippedFilesSupported === undefined
-            || settings.CF_LOCAL_ARCHITECTURE === "1" && options.consoleSupportsArchitecture === undefined
-            ? await client.capabilities() : undefined;
-        const consoleSupportsArchitecture = options.consoleSupportsArchitecture ?? capabilities?.architecture ?? false;
-        if (skippedFilesEnabled(settings) && !(options.skippedFilesSupported ?? capabilities?.skippedFiles)) {
+        // Negotiate before paid work: older strict intake schemas cannot accept coverage or additions.
+        if (options.consoleSupportsFailureReason === undefined) {
+            try {
+                consoleSupportsFailureReason = await client.supportsFailureReason();
+            }
+            catch { /* Older consoles omit optional metadata. */ }
+        }
+        if (skippedFilesEnabled(settings) && !(options.skippedFilesSupported ?? await client.supportsSkippedFiles())) {
             if (options.addToAnalysisId || fileScopeOf(settings) !== undefined)
                 throw new ConsoleError("unavailable", "start");
             settings = Object.freeze({ ...settings, CF_SKIPPED_FILES: "0" });
@@ -233,10 +265,17 @@ async function runRelayLifecycle(folder, options, existing) {
             if (renewal)
                 return;
             renewal = activeClient.heartbeat(activeId).then(status => {
-                if (status.state !== "reserved")
-                    throw new Error();
-                lease = status;
-            }).catch(() => { controller.abort(); }).finally(() => { renewal = undefined; });
+                if (status.state !== "reserved") {
+                    internalAbortCause = reservationExpiredError();
+                    controller.abort();
+                }
+                else
+                    lease = status;
+            }).catch(error => {
+                const expired = error instanceof ConsoleError && [401, 403, 404, 409].includes(error.httpStatus ?? 0);
+                internalAbortCause = expired ? reservationExpiredError() : new Error();
+                controller.abort();
+            }).finally(() => { renewal = undefined; });
         }, 60000);
         heartbeat.unref();
         const execution = await selectAnalysisExecution(config, () => { throw new Error(); }, {
@@ -252,6 +291,8 @@ async function runRelayLifecycle(folder, options, existing) {
         const priorResults = options.addToAnalysisId ? await loadAnalysisResults(folder, outputDir) : undefined;
         const assessments = combineAssessments(priorResults?.context.assessments ?? [], report.findingCheck.qualityAudit?.assessments ?? []);
         completionTiming = observedCompletionTiming({ completedAt: Date.now() }, { kind: "found", status: reservation }, reservation);
+        // A final optional call can drain successfully after an internal abort.
+        controller.signal.throwIfAborted();
         // The 30-minute lease covers upload retries; renewal failure must not cancel completed results.
         if (retainUnsaved)
             clearInterval(heartbeat);
@@ -260,12 +301,18 @@ async function runRelayLifecycle(folder, options, existing) {
         let saveContext;
         const saveReports = async () => {
             const paths = await saveLocalResults(folder, report, skippedFiles, outputDir, { ...summaryOptions, settings,
-                ...analysisSaveOptions(selection, options.outputDir), selection: membership, includedPaths,
+                ...analysisSaveOptions(selection), selection: membership, includedPaths,
                 ...(options.addToAnalysisId ? { append: { readPaths: includedPaths, assessments } } : {}) });
+            localPaths = paths;
+            if (retainUnsaved && keepLocalResults && completedPayload && !savedResult) {
+                try {
+                    localReportReceipt = (await readResultReceipt(folder, outputDir)).receipt;
+                    await persist(completedPayload, completionOrigin);
+                }
+                catch { /* A missing receipt cannot undo reports already written in this invocation. */ }
+            }
             try {
                 options.onLocalSaved?.(paths);
-                if (paths.ignoreAdded)
-                    stderr(GITIGNORE_OUTPUT_NOTICE);
             }
             catch { /* Output failure must not change a server outcome. */ }
             await saveContext?.();
@@ -274,7 +321,7 @@ async function runRelayLifecycle(folder, options, existing) {
         // The retry off path saves the full report even when intake validation refuses it.
         let paths = retainUnsaved ? undefined : await saveReports();
         const { payload, resultCheck, findingIndexes, findingActivities } = buildIntakePayload({ checkId: reservation.checkId, projectId: projectId, reservationId,
-            bundleVersion: bundle.version, relayVersion: options.release.relayVersion, counterfactLocalVersion: options.release.localVersion }, provenance, report, { settings, files: source.snapshot, consoleSupportsActivity: options.consoleSupportsActivity, consoleSupportsArchitecture,
+            bundleVersion: bundle.version, relayVersion: options.release.relayVersion, counterfactLocalVersion: options.release.localVersion }, provenance, report, { settings, files: source.snapshot, consoleSupportsActivity: options.consoleSupportsActivity,
             ...(!skippedFilesEnabled(settings) || !options.addToAnalysisId && !sizeSkippedFiles(skippedFiles).length ? {} : { coverage: { skippedFiles: sizeSkippedFiles(skippedFiles), readPaths: includedPaths },
                 addToAnalysisId: options.addToAnalysisId, findingAssessments: report.findingCheck.qualityAudit?.assessments ?? [] }) });
         displayFindings = findingIndexes.map((index, acceptedIndex) => {
@@ -297,9 +344,9 @@ async function runRelayLifecycle(folder, options, existing) {
         if (resultCheck?.droppedFindings) {
             const count = resultCheck.droppedFindings;
             const reason = resultCheck.schemaDroppedFindings || resultCheck.capDroppedFindings
-                ? `${count === 1 ? "it was" : "they were"} too long or not in the expected format` : `${count === 1 ? "its" : "their"} quotes did not match your files`;
+                ? `${countForm(count, "it was", "they were")} too long or not in the expected format` : `${countForm(count, "its", "their")} quotes did not match your files`;
             try {
-                stderr(`${count} ${count === 1 ? "finding was" : "findings were"} not uploaded because ${reason}.\n`);
+                stderr(`${count} ${countForm(count, "finding was", "findings were")} not uploaded because ${reason}.\n`);
             }
             catch { /* Output failure must not change a server outcome. */ }
         }
@@ -335,12 +382,13 @@ async function runRelayLifecycle(folder, options, existing) {
         return 0;
     }
     catch (caught) {
-        let error = caught;
+        // Reading passes can sanitize errors; this lifecycle owns internal abort causes.
+        let error = !completed && internalAbortCause && !options.signal?.aborted ? internalAbortCause : caught;
         let status;
         let statusLookup = { kind: "skipped" };
         if (client && reservationId) {
             try {
-                status = await (completed || uploaded ? client.status(reservationId) : client.fail(reservationId));
+                status = await (completed || uploaded ? client.status(reservationId) : client.fail(reservationId, consoleSupportsFailureReason && !(error instanceof AgentChoiceError) ? failureReason(error) : undefined));
                 statusLookup = { kind: "found", status };
             }
             catch (statusError) {
@@ -368,12 +416,18 @@ async function runRelayLifecycle(folder, options, existing) {
         }
         if (error instanceof ResultsUploadError)
             completionTiming = error.timing ?? completionTiming;
-        const failure = await recoverRelayFailure({ error, retryEnabled: retainUnsaved, payload: completedPayload, completed,
-            timing: completionTiming, statusLookup, uploadOutcome, savedResult,
-            canWrite: !lostCompletionLock, completionStored, localErrorMessage, fileSelection: selection?.kind === "file", fileMode: fileScopeEnabled(settings) }, {
+        const failure = await recoverRelayFailure({ error, cancelled: options.signal?.aborted, retryEnabled: retainUnsaved, payload: completedPayload, completed,
+            timing: completionTiming, statusLookup, reservationId, uploadOutcome, savedResult,
+            canWrite: !lostCompletionLock, completionStored, reportStored: localPaths !== undefined,
+            keepLocalResults, localErrorMessage, fileSelection: selection?.kind === "file", fileMode: fileScopeEnabled(settings) }, {
             markUploaded: () => persist(completedPayload, completionOrigin, true),
             keepPending: timing => { completionTiming = timing; return persist(completedPayload, completionOrigin); },
-            retire: () => retainUnsaved ? completionRecordPath ? discardCompletion(folder, completionRecordPath, completionIdentity) : Promise.resolve() : persist(completedPayload, completionOrigin, false, true),
+            retire: async () => {
+                if (!retainUnsaved)
+                    return persist(completedPayload, completionOrigin, false, true);
+                if (completionRecordPath)
+                    retainedPath = await discardCompletion(folder, completionRecordPath, completionIdentity, { keepCopy: keepLocalResults, reportStored: localPaths !== undefined });
+            },
         });
         if (failure.saved) {
             try {
@@ -400,10 +454,14 @@ async function runRelayLifecycle(folder, options, existing) {
             }
             catch { /* A failed local plan preserves the console's authoritative refusal. */ }
         }
+        const savedPaths = localPaths ? [localPaths.findingsPath, localPaths.summaryPath] : retainedPath ? [retainedPath]
+            : completionStored && !lostCompletionLock && completionRecordPath ? [completionRecordPath] : [];
+        const message = failure.kept && savedPaths.length
+            ? `${failure.message}\n${savedPaths.map(path => `Saved ${path}`).join("\n")}` : failure.message;
         try {
-            options.onError?.({ code: error instanceof ConsoleError ? error.code : undefined, reason: failure.reason, message: scopeChoice?.message ?? failure.message,
+            options.onError?.({ code: error instanceof ConsoleError ? error.code : undefined, reason: failure.reason, message: scopeChoice?.message ?? message, ...(failure.charged ? { charged: true } : {}),
                 ...(scopeChoice ? { agentChoice: scopeChoice.agentChoice } : error instanceof AgentChoiceError ? { agentChoice: error.agentChoice } : {}) });
-            stderr(`${scopeChoice?.message ?? failure.message}\n`);
+            stderr(`${scopeChoice?.message ?? message}\n`);
             if (status && !(error instanceof ConsoleError && error.code === "low_balance"))
                 stderr(stateLine(status));
         }

package/dist/cli/relay-failure.js

@@ -2,7 +2,7 @@ import { CompletionBusyError } from "../adapters/completion-lock.js";
 import { OutputPathError } from "../adapters/output-paths.js";
 import { AgentChoiceError } from "../contract/agent-choice.js";
 import { INVALID_PROPOSAL_MESSAGE } from "../contract/agent-proposal.js";
-import { cliRefusals, COMMITTED_FILES_MESSAGE, failureReason, FINISH_FAILURE_MESSAGE, localFailure, RESULTS_TOO_LARGE_MESSAGE } from "../contract/cli-refusals.js";
+import { analysisFailureDetails, CliRefusalError, cliRefusals, COMMITTED_FILES_MESSAGE, failureReason, FINISH_FAILURE_MESSAGE, START_FAILURE_MESSAGE, relayChargeStatus, RESULTS_TOO_LARGE_MESSAGE } from "../contract/cli-refusals.js";
 import { isSelectionRefusal, selectionRefusalMessage } from "../contract/scope-choice.js";
 import { ConsoleError } from "../gatekeeper/console.js";
 import { recoverCompletedResults } from "./completion-delivery.js";
@@ -15,18 +15,26 @@ export async function recoverRelayFailure(input, operations) {
     const recovery = input.payload && input.completed ? await recoverCompletedResults({
         retryEnabled, payload: input.payload, timing: input.timing, statusLookup: input.statusLookup,
         uploadOutcome: retryEnabled && input.savedResult ? { kind: "saved" } : carried ?? { kind: "cancelled" },
-        canWrite: input.canWrite, completionStored: input.completionStored, localErrorMessage: input.localErrorMessage,
+        canWrite: input.canWrite, completionStored: input.completionStored, reportStored: input.reportStored,
+        keepLocalResults: input.keepLocalResults, localErrorMessage: input.localErrorMessage,
     }, operations) : undefined;
     if (recovery?.decision.action === "saved")
-        return { saved: true, message: recovery.message, reason: "results_saved_report_failed" };
-    const known = error instanceof AgentChoiceError || error instanceof ConsoleError || error instanceof OutputPathError
-        || isSelectionRefusal(error, input.fileSelection ?? false)
-        || error instanceof CompletionBusyError || error instanceof CompletionSettingsMismatchError || error instanceof Error
+        return { saved: true,
+            message: error instanceof CompletionBusyError ? error.message : recovery.message, reason: "results_saved_report_failed" };
+    const selectionRefusal = isSelectionRefusal(error, input.fileSelection ?? false);
+    const known = error instanceof CliRefusalError || error instanceof AgentChoiceError || error instanceof ConsoleError || error instanceof OutputPathError
+        || selectionRefusal || error instanceof CompletionBusyError || error instanceof CompletionSettingsMismatchError || error instanceof Error
         && ([cliRefusals.release_unavailable, COMMITTED_FILES_MESSAGE, RESULTS_TOO_LARGE_MESSAGE, INVALID_PROPOSAL_MESSAGE].includes(error.message)
             || error.message.startsWith("The saved completion"));
-    const message = recovery?.message ?? input.localErrorMessage ?? localFailure(error)?.message ?? (known ? error.message : FINISH_FAILURE_MESSAGE);
-    const reason = !retryEnabled ? failureReason(error)
-        : recovery?.decision.action === "retry" && input.completionStored ? "results_pending"
-            : recovery?.decision.action === "give-up" ? "results_discarded" : failureReason(error);
-    return { saved: false, message: selectionRefusalMessage(message, input.fileMode ?? true), reason };
+    const status = input.statusLookup.kind === "found" ? input.statusLookup.status : undefined;
+    const charge = relayChargeStatus(status, !input.reservationId && input.statusLookup.kind === "skipped");
+    const failure = error instanceof ConsoleError ? undefined : analysisFailureDetails(error, charge, { cancelled: input.cancelled, noReservation: !input.reservationId });
+    const knownMessage = known ? error.message : undefined;
+    const failureMessage = failure?.reason === "request_failed" ? knownMessage ?? failure.message : failure?.message;
+    const message = recovery?.message ?? input.localErrorMessage ?? failureMessage ?? knownMessage ?? (!input.reservationId && !input.completed ? START_FAILURE_MESSAGE : FINISH_FAILURE_MESSAGE);
+    const originalReason = failure?.reason ?? failureReason(error);
+    const reason = recovery && "reason" in recovery.decision ? recovery.decision.reason ?? originalReason : originalReason;
+    return { saved: false, message: selectionRefusalMessage(message, input.fileMode ?? true), reason,
+        ...(recovery?.decision.action === "give-up" && recovery.decision.kept ? { kept: true } : {}),
+        ...(reason !== "results_pending" && (charge === "charged" || charge === "free_used") ? { charged: true } : {}) };
 }

package/dist/cli/relay-preparation.js

@@ -7,7 +7,7 @@ import { resolveFolderPath } from "../adapters/folder-path.js";
 import { readLocalFolder } from "../adapters/files.js";
 import { snapshotProvenance, sameFileHashes } from "../adapters/snapshot.js";
 import { validateClientRelease } from "../adapters/release.js";
-import { prepareRelayPlan } from "../adapters/source-relay-plan.js";
+import { prepareRelayPlan } from "../adapters/relay-plan.js";
 import { readAnalysisSource } from "../adapters/selection.js";
 import { AgentChoiceError } from "../contract/agent-choice.js";
 import { COMMITTED_FILES_MESSAGE } from "../contract/cli-refusals.js";
@@ -16,9 +16,12 @@ import { selectionStartIdentity } from "../contract/selection-metadata.js";
 import { repositoryFacts } from "./git.js";
 import { proposalWhollyRefused } from "../analysis-core/index.js";
 /** Absolute checkout paths stay local; repository facts own the start's commit. */
-export function buildRelayStartPayload(facts, files) {
+export function buildRelayStartPayload(facts, files, coordinates = {}) {
     const { remoteUrl, relPath, folderName, branch, commit, dirty } = facts;
-    return { execution: "local", remoteUrl, relPath, folderName, branch, commit, dirty, files };
+    // Older consoles placed repository-relative results under an empty selected folder.
+    const legacy = process.env.CF_CLI_RELPATH === "0";
+    const folder = legacy && coordinates.resultBase && coordinates.resultBase !== coordinates.readRoot ? "" : relPath;
+    return { execution: "local", remoteUrl, relPath: folder, folderName, branch, commit, dirty, files };
 }
 export function committedFilesOnly(settings) {
     return settings.CF_LOCAL_COMMITTED_ONLY === "1";
@@ -66,7 +69,7 @@ export async function prepareFolderChoice(folder, options) {
 }
 /** Recovery can reuse signature validation without reading the folder again. */
 export async function prepareRelayCheck(folder, options, validated = validateClientRelease(options.release, options.settings)) {
-    const { bundle } = validated;
+    const { bundle, tools } = validated;
     options.signal?.throwIfAborted();
     // Discovery must agree with Git before publishing repository-relative captures.
     const selection = options.selection;
@@ -95,13 +98,13 @@ export async function prepareRelayCheck(folder, options, validated = validateCli
     }
     else if (options.expectedCommit !== undefined && provenance.commit !== options.expectedCommit)
         throw new Error(COMMITTED_FILES_MESSAGE);
-    const { plan, files } = prepareRelayPlan({ bundle, settings: validated.settings, relayVersion: options.release.relayVersion, source });
+    const { plan, files } = prepareRelayPlan({ bundle, tools, settings: validated.settings, relayVersion: options.release.relayVersion, source });
     options.signal?.throwIfAborted();
     const facts = earlyFacts ?? await (options.facts ?? repositoryFacts)(factsFolder);
     options.signal?.throwIfAborted();
     const startMetadata = { analysisSize: source.analysisSize, startAttempt: randomUUID(),
         ...(selection?.kind === "file" && membership
             ? { selection: selectionStartIdentity(selection.selectionKey, membership.snapshot) } : {}) };
-    return { source, provenance, plan, start: buildRelayStartPayload(source.sourceBase && selection?.kind !== "file" ? { ...facts, relPath: "" } : facts, files), startMetadata,
+    return { source, provenance, plan, start: buildRelayStartPayload(facts, files, { resultBase: selection?.kind !== "file" ? source.sourceBase : undefined, readRoot: folder }), startMetadata,
         ...(membership ? { membership } : {}) };
 }

package/dist/cli/scope-choices.js

@@ -1,6 +1,6 @@
 import { readdir, readFile, unlink } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { outputPaths, writeOutputFiles } from "../adapters/output-paths.js";
+import { outputPaths, reportOutputDirectory, writeReportFiles } from "../adapters/output-paths.js";
 import { analysisScopeSchema, chooseScopeResultSchema, INCLUDED_FILES_CAPTION, OMITTED_IMPORTS_CAPTION, OMITTED_FILES_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";
@@ -45,13 +45,14 @@ export function scopeChoiceText(value, retryPaths = {}) {
 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 outputDir = await reportOutputDirectory(anchor.outputAnchor, anchor.outputDir);
+    const [probe] = await outputPaths(anchor.outputAnchor, ["scope-1.json"], outputDir, true);
     const old = (await readdir(dirname(probe))).filter(name => /^scope-.*\.json$/.test(name));
-    await outputPaths(anchor.outputAnchor, old, anchor.outputDir);
+    await outputPaths(anchor.outputAnchor, old, 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);
+    const paths = await writeReportFiles(anchor.outputAnchor, files, outputDir);
     return scopeChoiceText(result, Object.fromEntries(runnable.map(({ index }, position) => [index, paths[position]])));
 }