@counterfact-labs/cli 0.2.6 → 0.2.9

package/dist/cli/relay-check.js

@@ -1,16 +1,23 @@
+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";
+import { fingerprintOf } from "../analysis-core/analysis/finding-identity.js";
+import { combineAssessments } from "../adapters/combined-results.js";
 import { randomUUID } from "node:crypto";
 import { disabledSetupPings } from "../setup-pings/client.js";
-import { saveCompletion, loadCompletion } from "../adapters/completion.js";
+import { fileScopeEnabled, scopeChoicesEnabled } from "../adapters/settings.js";
+import { saveCompletion, discardCompletion, lockCompletion } from "../adapters/completion.js";
 import { saveLocalResults } from "../adapters/results.js";
 import { GITIGNORE_OUTPUT_NOTICE } from "../adapters/gitignore-output.js";
+import { priorCompletion } from "./prior-completion.js";
 import { OutputPathError, outputPaths } 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 } from "../contract/console-url.js";
-import { prepareRelayCheck } from "./relay-preparation.js";
-import { cliRefusals, COMMITTED_FILES_MESSAGE, failureReason, FINISH_FAILURE_MESSAGE, RESULTS_TOO_LARGE_MESSAGE, refusalExitCode } from "../contract/cli-refusals.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 { ConsoleClient, ConsoleError } from "../gatekeeper/console.js";
 import { GatekeeperClient } from "../gatekeeper/client.js";
 import { connectRelay, relayOrigin } from "../gatekeeper/connection.js";
@@ -19,51 +26,17 @@ import { runAnalysisToEnd } from "../core/analysis/run-to-end.js";
 import { findingPresentation } from "../analysis-core/findings/presentation.js";
 import { formatSummary } from "./summary.js";
 import { buildIntakePayload } from "./intake-payload.js";
-import { completionRecoveryDecision, COMPLETION_SETTINGS_MISMATCH_MESSAGE, matchesCheck } from "./completion-recovery.js";
+import { matchesCheck, observedCompletionTiming } from "./completion-recovery.js";
 import { savedFindings } from "./finding-display.js";
-import { INVALID_PROPOSAL_MESSAGE } from "../contract/agent-proposal.js";
 import { readFindingSettings } from "./finding-settings.js";
+import { deliverCompletedResults } from "./completion-delivery.js";
+import { requireIntakeReservation, ResultsUploadError, submitResults, uploadFailure } from "./results-upload.js";
+import { recoverRelayFailure } from "./relay-failure.js";
+import { analysisSaveOptions, resolveRunSelection } from "./analysis-selection.js";
+import { SCOPE_CHOICE_EXIT_CODE, progressLine } from "../contract/scope-choice.js";
+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`;
-function requireIntakeReservation(status) {
-    if (status.state === "reserved")
-        return;
-    if (status.state === "closing")
-        throw new ConsoleError("reservation_closing");
-    if (status.state === "closed")
-        throw new ConsoleError("reservation_closed");
-    throw new ConsoleError("reservation_expired", "intake");
-}
-/** Retry an exact completed payload; a lost intake response must never purchase another analysis. */
-async function submit(client, payload, signal) {
-    signal.throwIfAborted();
-    const status = await client.status(payload.reservationId);
-    const committed = (value) => ({ checkId: value.checkId, projectId: value.projectId, analysisId: value.analysisId, findingIds: value.findingIds,
-        ...(value.findings ? { findings: value.findings } : {}), settlement: value.settlement });
-    if (!matchesCheck(status, payload))
-        throw new ConsoleError("check_conflict");
-    if (status.uploadState === "saved")
-        return committed(status);
-    requireIntakeReservation(status);
-    signal.throwIfAborted();
-    try {
-        return await client.intake(payload);
-    }
-    catch (error) {
-        // Keep the refusal for display; giving up the saved payload requires confirmed recovery status.
-        const after = await client.status(payload.reservationId).catch(() => { throw error; });
-        if (!matchesCheck(after, payload))
-            throw new ConsoleError("check_conflict");
-        if (after.uploadState === "saved")
-            return committed(after);
-        // Exact idempotent retry only; a second uncertainty leaves the completion record for restart.
-        if (error instanceof ConsoleError && error.code === "unavailable") {
-            requireIntakeReservation(after);
-            signal.throwIfAborted();
-            return client.intake(payload);
-        }
-        throw error;
-    }
-}
 export function runRelayCheck(folder, options) {
     return runRelayLifecycle(folder, options);
 }
@@ -73,23 +46,73 @@ export function runReservedRelayCheck(folder, options) {
 }
 async function runRelayLifecycle(folder, options, existing) {
     const { config, stdout, stderr } = options;
+    const retainUnsaved = config.CF_LOCAL_RESULTS_RETRY !== "0";
     let settings = options.settings;
-    const summaryOptions = { audienceEnabled: false };
+    const summaryOptions = { audienceEnabled: false, notActiveEnabled: false, skippedFilesEnabled: skippedFilesEnabled(settings), skippedOffer: !options.addToAnalysisId, analyzedFolder: options.analyzedFolder ?? folder };
+    let skippedFiles = [];
     let client, reservationId, projectId;
     let connection = existing?.connection;
-    let identity;
     let completedPayload;
     let displayFindings;
-    let completionOrigin;
+    let completionOrigin, completionRecordPath;
+    let completionTiming = {};
+    let combinedFindings;
+    let topFindingIds;
+    let refusedCalls;
     let completed = false, uploaded = false, heartbeat;
+    let selection, membership;
+    let selectedPaths, completionIdentity;
+    let outputDir = options.outputDir;
     let renewal;
+    let releaseCompletion;
+    let localErrorMessage;
+    let completionStored = false, lostCompletionLock = false;
+    let uploadOutcome;
+    let savedResult;
     const controller = new AbortController();
     const signal = options.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
+    // A completed upload must survive the analysis lease closing during local report writes.
+    const uploadSignal = retainUnsaved ? options.signal ?? new AbortController().signal : signal;
+    const persist = async (payload, origin, uploaded = false, finished = false) => {
+        if (lostCompletionLock)
+            throw new OutputPathError();
+        const path = await saveCompletion(folder, payload, origin, { uploaded, finished, completedAt: completionTiming.completedAt,
+            absoluteExpiresAt: completionTiming.absoluteExpiresAt, retainUnsaved, identity: completionIdentity });
+        completionStored = true;
+        completionRecordPath = path;
+        return path;
+    };
+    const submit = (payload, alreadySaved = false) => {
+        if (retainUnsaved) {
+            try {
+                options.onSaving?.();
+                stderr("Saving the results…\n");
+            }
+            catch { /* Progress output must not prevent saving completed work. */ }
+        }
+        return submitResults(client, payload, uploadSignal, { retry: retainUnsaved, alreadySaved, timing: completionTiming }).then(result => { savedResult = result; return result; });
+    };
     const showSaved = (result) => {
         const url = savedAnalysisUrl(result.projectId, config.CF_CONSOLE_URL);
-        const findings = savedFindings({ findingIds: result.findingIds ?? [], findings: result.findings }, displayFindings ?? completedPayload?.findings ?? []);
-        options.onSaved?.({ ...result, findings, url, audienceEnabled: summaryOptions.audienceEnabled });
-        stdout(`Saved analysis ${result.analysisId}: ${url}\n`);
+        const architectureUrl = completedPayload?.architecture ? savedArchitectureUrl(result.projectId, config.CF_CONSOLE_URL) : undefined;
+        const findings = combinedFindings ?? savedFindings({ findingIds: result.findingIds ?? [], findings: result.findings }, displayFindings ?? completedPayload?.findings ?? []);
+        options.onSaved?.({ ...result, ...(combinedFindings ? { findingIds: combinedFindings.map(f => f.id), topFindingIds } : {}), ...(!skippedFilesEnabled(settings) ? {} : { skippedFiles }), findings, url, ...(architectureUrl ? { architectureUrl } : {}), ...summaryOptions });
+        stdout(result.analysisId ? `Saved analysis ${result.analysisId}: ${url}\n` : `Full results: ${url}\n`);
+        if (architectureUrl)
+            stdout(`Architecture: ${architectureUrl}\n`);
+    };
+    const settleSaved = async (result) => {
+        const payload = completedPayload;
+        if (!result.analysisId || !skippedFilesEnabled(settings) || !payload?.coverage || !payload.addToAnalysisId && !sizeSkippedFiles(payload.coverage.skippedFiles).length)
+            return;
+        const context = await settleAnalysisContext(folder, { ...result, analysisId: result.analysisId, findingIds: result.findingIds ?? [] }, payload.checkId, payload.addToAnalysisId, outputDir);
+        const { report } = await loadAnalysisResults(folder, outputDir);
+        skippedFiles = report.refusedFiles;
+        if (payload.addToAnalysisId) {
+            topFindingIds = context.topFindingIds;
+            const references = new Map(context.findings?.map(f => [f.fingerprint, f]));
+            combinedFindings = report.findings.flatMap(finding => { const saved = references.get(fingerprintOf(finding)); return saved ? [saved] : []; });
+        }
     };
     try {
         if (!config.CF_CONSOLE_URL || !existing && (!config.CF_RELAY_URL || !config.CF_CONSOLE_TOKEN)) {
@@ -101,61 +124,103 @@ async function runRelayLifecycle(folder, options, existing) {
                 throw new ConsoleError("check_conflict");
             reservationId = existing.reservation.reservationId;
             projectId = existing.reservation.projectId;
-            identity = existing.reservation;
             client = existing.client;
         }
         else {
             relayOrigin(config.CF_RELAY_URL);
             client = new ConsoleClient({ url: config.CF_CONSOLE_URL, token: config.CF_CONSOLE_TOKEN });
         }
-        // Signature verification precedes all folder reads, status calls and spending.
+        // Signature verification precedes all file content reads, status calls and spending.
         const validated = validateClientRelease(options.release, settings);
         const { bundle } = validated;
         settings = validated.settings;
-        summaryOptions.audienceEnabled = readFindingSettings(settings).audienceEnabled;
-        folder = await resolveFolderPath(folder);
+        const findingSettings = readFindingSettings(settings);
+        summaryOptions.audienceEnabled = findingSettings.audienceEnabled;
+        summaryOptions.notActiveEnabled = findingSettings.notActiveEnabled;
+        selection = await resolveRunSelection(folder, options.cwd ?? process.cwd(), settings, options);
+        // Verify the selected folder before output and recovery operations can fail for their own reasons.
+        folder = await resolveFolderPath(selection?.outputAnchor ?? folder).catch(error => {
+            if (error instanceof Error)
+                Object.assign(error, { localOperation: "read" });
+            throw error;
+        });
+        outputDir ??= selection?.outputDir;
+        if (selection?.kind === "file")
+            completionIdentity = {
+                consoleOrigin: new URL(config.CF_CONSOLE_URL).origin, selectionKey: selection.selectionKey,
+            };
         signal.throwIfAborted();
-        const prior = await loadCompletion(folder);
-        if (prior && (!prior.uploaded && !prior.finished || options.retryUpload)) {
+        if (retainUnsaved)
+            releaseCompletion = await lockCompletion(folder, () => { lostCompletionLock = true; 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 });
+        for (const notice of recovery.notices) {
+            try {
+                options.onNotice?.(notice);
+                stderr(`${notice}\n`);
+            }
+            catch { /* Notices must not prevent saving the current setup's results. */ }
+        }
+        if (recovery.prior) {
+            const { record: prior, path } = recovery.prior;
             // Recovering another check would leave the caller's paid reservation unexecuted.
             if (existing && (prior.payload.reservationId !== reservationId || !matchesCheck(prior.payload, existing.reservation))) {
                 throw new ConsoleError("check_conflict");
             }
+            completionStored = true;
+            completionRecordPath = path;
             completedPayload = prior.payload;
+            skippedFiles = prior.payload.coverage?.skippedFiles ?? [];
             completionOrigin = prior.consoleOrigin;
+            completionTiming = { completedAt: prior.completedAt, absoluteExpiresAt: prior.absoluteExpiresAt };
             uploaded = prior.uploaded ?? false;
-            const recovery = completionRecoveryDecision({ statusSucceeded: false,
-                localMismatch: prior.consoleOrigin !== new URL(config.CF_CONSOLE_URL).origin });
-            if (recovery.message)
-                throw new Error(recovery.message);
             reservationId = prior.payload.reservationId;
-            identity = prior.payload;
             completed = true;
-            const saved = await submit(client, prior.payload, signal);
+            const saved = await submit(prior.payload, retainUnsaved && uploaded);
             uploaded = true;
-            await saveCompletion(folder, prior.payload, prior.consoleOrigin, true);
+            await persist(prior.payload, prior.consoleOrigin, true);
+            await settleSaved(saved);
             showSaved(saved);
             return 0;
         }
         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)) {
+            if (options.addToAnalysisId || fileScopeOf(settings) !== undefined)
+                throw new ConsoleError("unavailable", "start");
+            settings = Object.freeze({ ...settings, CF_SKIPPED_FILES: "0" });
+            summaryOptions.skippedFilesEnabled = false;
+        }
         try {
-            await outputPaths(folder, ["findings.json", "summary.md"], options.outputDir);
+            await outputPaths(folder, ["findings.json", "summary.md", ...(selection?.kind === "file" ? ["selection.json"] : [])], outputDir);
         }
         catch (error) {
             if (error.code !== "ENOENT")
                 throw error;
         }
-        const { source, provenance, plan, start, startMetadata } = await prepareRelayCheck(folder, { ...options, signal, expectedCommit: existing?.expectedCommit, expectedFiles: existing?.expectedFiles }, validated);
+        const prepared = await prepareRelayCheck(selection?.path ?? folder, { ...options, settings, selection, signal, expectedCommit: existing?.expectedCommit, expectedFiles: existing?.expectedFiles }, { ...validated, settings });
+        const { source, provenance, plan, start, startMetadata } = prepared;
+        membership = prepared.membership;
+        const includedPaths = Object.keys(source.files);
+        selectedPaths = includedPaths;
+        refusedCalls = plan.calls;
+        skippedFiles = source.skippedFiles;
         let reservation = existing?.reservation;
         if (!reservation) {
-            const started = await client.start(start, startMetadata);
+            const started = await client.start(start, { ...startMetadata, ...(options.addToAnalysisId ? { addToAnalysisId: options.addToAnalysisId } : {}) });
+            if (options.expectedProjectId && started.projectId !== options.expectedProjectId)
+                throw new ConsoleError("check_conflict");
             projectId = started.projectId;
             signal.throwIfAborted();
             const created = await client.create({ ...started, checkId: randomUUID(), plan });
             reservationId = created.reservationId;
-            identity = created;
             signal.throwIfAborted();
             // Attestation contains no source and precedes reserve, so a bad relay never starts paid work.
             connection = await (options.connect ?? (url => connectRelay(url, { trust: productionTrust })))(config.CF_RELAY_URL);
@@ -180,23 +245,55 @@ async function runRelayLifecycle(folder, options, existing) {
             reservationId: activeId, reservationToken: reservation.reservationToken, instructions: { bundle, verificationKey: options.release.verificationKey }, signal,
         });
         options.onStart?.();
-        stderr("Reading the folder and running analysis.\n");
+        stderr(progressLine(selection));
         (options.setupPings ?? disabledSetupPings).ping("first_analysis_started");
-        const report = await runAnalysisToEnd(source, execution.model, settings, { execution });
-        signal.throwIfAborted();
-        const paths = await saveLocalResults(folder, report, source.skippedFiles, options.outputDir, { ...summaryOptions, settings });
-        try {
-            options.onLocalSaved?.(paths);
-            if (paths.ignoreAdded)
-                stderr(GITIGNORE_OUTPUT_NOTICE);
-        }
-        catch { /* Output failure must not change a server outcome. */ }
-        const { payload, resultCheck, findingIndexes } = buildIntakePayload({ checkId: reservation.checkId, projectId: projectId, reservationId,
-            bundleVersion: bundle.version, relayVersion: options.release.relayVersion, counterfactLocalVersion: options.release.localVersion }, provenance, report, { settings, files: source.snapshot });
-        displayFindings = findingIndexes.map(index => {
+        const report = await runAnalysisToEnd(source, execution.model, settings, { execution, ...(options.addToAnalysisId ? { findingsOnly: true } : {}) });
+        skippedFiles = !skippedFilesEnabled(settings) ? source.skippedFiles : analysisSkippedFiles(source.skippedFiles, report.skippedFiles);
+        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);
+        // The 30-minute lease covers upload retries; renewal failure must not cancel completed results.
+        if (retainUnsaved)
+            clearInterval(heartbeat);
+        else
+            signal.throwIfAborted();
+        let saveContext;
+        const saveReports = async () => {
+            const paths = await saveLocalResults(folder, report, skippedFiles, outputDir, { ...summaryOptions, settings,
+                ...analysisSaveOptions(selection, options.outputDir), selection: membership, includedPaths,
+                ...(options.addToAnalysisId ? { append: { readPaths: includedPaths, assessments } } : {}) });
+            try {
+                options.onLocalSaved?.(paths);
+                if (paths.ignoreAdded)
+                    stderr(GITIGNORE_OUTPUT_NOTICE);
+            }
+            catch { /* Output failure must not change a server outcome. */ }
+            await saveContext?.();
+            return paths;
+        };
+        // 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,
+            ...(!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) => {
             const finding = report.findings[index];
-            return { title: findingPresentation(finding).displayTitle, audience: finding.audience };
+            const activity = findingActivities[acceptedIndex];
+            return { title: findingPresentation(finding).displayTitle, audience: finding.audience,
+                severity: finding.severity, site: finding.site, fixes: finding.fixes,
+                ...(activity === undefined ? {} : { activity }) };
         });
+        if (skippedFilesEnabled(settings) && (options.addToAnalysisId || sizeSkippedFiles(skippedFiles).length)) {
+            saveContext = async () => {
+                await saveAnalysisContext(folder, { projectId: projectId, analysisId: options.addToAnalysisId ?? reservation.checkId,
+                    settings: priorResults?.context.settings ?? settings, assessments,
+                    ...(priorResults?.context.findings ? { findings: priorResults.context.findings } : {}),
+                    pending: { checkId: reservation.checkId, fingerprints: findingIndexes.map(index => fingerprintOf(report.findings[index])), titles: [...displayFindings] } }, outputDir);
+            };
+            if (paths)
+                await saveContext();
+        }
         if (resultCheck?.droppedFindings) {
             const count = resultCheck.droppedFindings;
             const reason = resultCheck.schemaDroppedFindings || resultCheck.capDroppedFindings
@@ -207,54 +304,106 @@ async function runRelayLifecycle(folder, options, existing) {
             catch { /* Output failure must not change a server outcome. */ }
         }
         completionOrigin = new URL(config.CF_CONSOLE_URL).origin;
-        await saveCompletion(folder, payload, completionOrigin);
-        completedPayload = payload;
-        completed = true;
-        const saved = await submit(client, payload, signal);
-        uploaded = true;
-        await saveCompletion(folder, payload, completionOrigin, true);
-        stdout(formatSummary(report, summaryOptions));
+        let saved;
+        if (retainUnsaved) {
+            completedPayload = payload;
+            completed = true;
+            const delivery = await deliverCompletedResults({ persist: uploaded => persist(payload, completionOrigin, uploaded),
+                submit: () => submit(payload), saveReports });
+            uploaded = delivery.uploaded;
+            saved = delivery.saved;
+            paths = delivery.paths;
+            localErrorMessage = delivery.localErrorMessage;
+            uploadOutcome = delivery.outcome;
+            completionTiming = delivery.timing ?? completionTiming;
+            if (delivery.error)
+                throw delivery.error;
+        }
+        else {
+            await persist(payload, completionOrigin);
+            completedPayload = payload;
+            completed = true;
+            paths ??= await saveReports();
+            saved = await submit(payload);
+            uploaded = true;
+            await persist(payload, completionOrigin, true);
+        }
+        await settleSaved(saved);
+        stdout(formatSummary(options.addToAnalysisId ? await loadPublicReport(folder, outputDir) : { ...report, refusedFiles: skippedFiles }, summaryOptions));
         stdout(`\nSaved ${paths.findingsPath}\nSaved ${paths.summaryPath}\n`);
         showSaved(saved);
         return 0;
     }
-    catch (error) {
+    catch (caught) {
+        let error = caught;
         let status;
+        let statusLookup = { kind: "skipped" };
         if (client && reservationId) {
             try {
                 status = await (completed || uploaded ? client.status(reservationId) : client.fail(reservationId));
+                statusLookup = { kind: "found", status };
             }
-            catch {
-                // An uncertain server outcome cannot prove a refund.
+            catch (statusError) {
+                statusLookup = { ...uploadFailure(statusError), kind: "failed" };
             }
         }
-        if (status?.uploadState === "saved" && identity && matchesCheck(status, identity)) {
-            if (completedPayload) {
-                try {
-                    await saveCompletion(folder, completedPayload, completionOrigin, true);
+        const sizeRefusal = error instanceof ConsoleError && ["plan_over_limit", "folder_too_large"].includes(error.code);
+        const closed = !reservationId || status && (status.state === "closed" || status.state === "expired");
+        if (scopeChoicesEnabled(settings) && !completedPayload && closed) {
+            const choice = error instanceof ScopeChoiceError ? error.choice
+                : sizeRefusal && membership ? selectionScopeChoices(membership, { currentPaths: selectedPaths,
+                    oversizedPaths: membership.kind === "file" && selectedPaths?.length === 1 && selectedPaths[0] === membership.entry
+                        ? [membership.entry] : undefined }) : undefined;
+            if (choice) {
+                const refusal = scopeChoiceRefusal(choice);
+                if (refusal)
+                    error = new Error(refusal);
+                else {
+                    options.onScopeChoice?.(choice);
+                    if (!options.onScopeChoice)
+                        stderr(`${choice.text}\n`);
+                    return SCOPE_CHOICE_EXIT_CODE;
                 }
-                catch { /* Committed server state still survives a local write failure. */ }
             }
+        }
+        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) }, {
+            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),
+        });
+        if (failure.saved) {
             try {
-                showSaved({ projectId: status.projectId, analysisId: status.analysisId, findingIds: status.findingIds, findings: status.findings });
+                const saved = savedResult ?? { projectId: status.projectId, analysisId: status.analysisId, findingIds: status.findingIds, findings: status.findings };
+                await settleSaved(saved);
+                showSaved(saved);
             }
             catch { /* Output failure must not change a server outcome. */ }
-            return 0;
+            if (!failure.message)
+                return 0;
+            try {
+                options.onError?.({ reason: failure.reason, message: failure.message });
+                stderr(`${failure.message}\n`);
+            }
+            catch { /* Reporting failure cannot undo saved results. */ }
+            return 1;
         }
-        const recovery = completionRecoveryDecision({ statusSucceeded: status !== undefined, status, completedPayload });
-        if (completedPayload && recovery.finished) {
+        let scopeChoice;
+        if (!reservationId && !existing && error instanceof ConsoleError && (error.code === "folder_too_large" || error.code === "plan_over_limit")) {
             try {
-                await saveCompletion(folder, completedPayload, completionOrigin, false, true);
+                const choice = await prepareFolderChoice(folder, { ...options, settings, signal, limit: error.code, refusedCalls });
+                if (choice)
+                    scopeChoice = new AgentChoiceError(choice);
             }
-            catch { /* Keep the pending record if the durable write cannot be confirmed. */ }
+            catch { /* A failed local plan preserves the console's authoritative refusal. */ }
         }
-        const known = error instanceof AgentChoiceError || error instanceof ConsoleError || error instanceof OutputPathError || 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") || error.message === COMPLETION_SETTINGS_MISMATCH_MESSAGE);
-        const message = known ? error.message : FINISH_FAILURE_MESSAGE;
         try {
-            options.onError?.({ code: error instanceof ConsoleError ? error.code : undefined, reason: failureReason(error), message,
-                ...(error instanceof AgentChoiceError ? { agentChoice: error.agentChoice } : {}) });
-            stderr(`${message}\n`);
+            options.onError?.({ code: error instanceof ConsoleError ? error.code : undefined, reason: failure.reason, message: scopeChoice?.message ?? failure.message,
+                ...(scopeChoice ? { agentChoice: scopeChoice.agentChoice } : error instanceof AgentChoiceError ? { agentChoice: error.agentChoice } : {}) });
+            stderr(`${scopeChoice?.message ?? failure.message}\n`);
             if (status && !(error instanceof ConsoleError && error.code === "low_balance"))
                 stderr(stateLine(status));
         }
@@ -264,6 +413,7 @@ async function runRelayLifecycle(folder, options, existing) {
     finally {
         clearInterval(heartbeat);
         await renewal;
+        await releaseCompletion?.().catch(() => { });
         try {
             connection?.close();
         }

package/dist/cli/relay-failure.js

@@ -0,0 +1,32 @@
+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 { isSelectionRefusal, selectionRefusalMessage } from "../contract/scope-choice.js";
+import { ConsoleError } from "../gatekeeper/console.js";
+import { recoverCompletedResults } from "./completion-delivery.js";
+import { CompletionSettingsMismatchError } from "./prior-completion.js";
+import { ResultsUploadError } from "./results-upload.js";
+/** Cleanup reports the recovery owner's decision without exposing private diagnostics. */
+export async function recoverRelayFailure(input, operations) {
+    const { error, retryEnabled } = input;
+    const carried = retryEnabled ? input.uploadOutcome ?? (error instanceof ResultsUploadError ? error.outcome : undefined) : undefined;
+    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,
+    }, 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
+        && ([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 };
+}