@counterfact-labs/cli 0.2.5 → 0.2.7

package/dist/cli/relay-check.js

@@ -1,8 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { disabledSetupPings } from "../setup-pings/client.js";
-import { saveCompletion, loadCompletion } from "../adapters/completion.js";
+import { 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";
@@ -10,7 +12,7 @@ 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, FINISH_FAILURE_MESSAGE, RESULTS_TOO_LARGE_MESSAGE, refusalExitCode } from "../contract/cli-refusals.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 +21,16 @@ 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";
 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 +40,53 @@ 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 };
     let client, reservationId, projectId;
     let connection = existing?.connection;
-    let identity;
     let completedPayload;
     let displayFindings;
-    let completionOrigin;
+    let completionOrigin, completionRecordPath;
+    let completionTiming = {};
     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`);
+        stdout(result.analysisId ? `Saved analysis ${result.analysisId}: ${url}\n` : `Full results: ${url}\n`);
     };
     try {
         if (!config.CF_CONSOLE_URL || !existing && (!config.CF_RELAY_URL || !config.CF_CONSOLE_TOKEN)) {
@@ -101,39 +98,54 @@ 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);
+        selection = await resolveRunSelection(folder, options.cwd ?? process.cwd(), settings, options);
+        folder = selection?.outputAnchor ?? await resolveFolderPath(folder);
+        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;
             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);
             showSaved(saved);
             return 0;
         }
@@ -141,13 +153,17 @@ async function runRelayLifecycle(folder, options, existing) {
         if (options.retryUpload)
             throw new Error("The saved completion record is missing. Keep the local report and check the output directory.");
         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, selection, signal, expectedCommit: existing?.expectedCommit, expectedFiles: existing?.expectedFiles }, validated);
+        const { source, provenance, plan, start, startMetadata } = prepared;
+        membership = prepared.membership;
+        const includedPaths = Object.keys(source.files);
+        selectedPaths = includedPaths;
         let reservation = existing?.reservation;
         if (!reservation) {
             const started = await client.start(start, startMetadata);
@@ -155,7 +171,6 @@ async function runRelayLifecycle(folder, options, existing) {
             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,17 +195,27 @@ 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. */ }
+        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();
+        const saveReports = async () => {
+            const paths = await saveLocalResults(folder, report, source.skippedFiles, outputDir, { ...summaryOptions, settings,
+                ...analysisSaveOptions(selection, options.outputDir), selection: membership, includedPaths });
+            try {
+                options.onLocalSaved?.(paths);
+                if (paths.ignoreAdded)
+                    stderr(GITIGNORE_OUTPUT_NOTICE);
+            }
+            catch { /* Output failure must not change a server outcome. */ }
+            return paths;
+        };
+        let paths = retainUnsaved ? undefined : await saveReports();
         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 => {
@@ -207,54 +232,94 @@ 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);
+        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);
+        }
         stdout(formatSummary(report, 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" }, {
+            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 });
+                showSaved(savedResult ?? { projectId: status.projectId, analysisId: status.analysisId, findingIds: status.findingIds, findings: status.findings });
             }
             catch { /* Output failure must not change a server outcome. */ }
-            return 0;
-        }
-        const recovery = completionRecoveryDecision({ statusSucceeded: status !== undefined, status, completedPayload });
-        if (completedPayload && recovery.finished) {
+            if (!failure.message)
+                return 0;
             try {
-                await saveCompletion(folder, completedPayload, completionOrigin, false, true);
+                options.onError?.({ reason: failure.reason, message: failure.message });
+                stderr(`${failure.message}\n`);
             }
-            catch { /* Keep the pending record if the durable write cannot be confirmed. */ }
+            catch { /* Reporting failure cannot undo saved results. */ }
+            return 1;
         }
-        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, message,
+            options.onError?.({ code: error instanceof ConsoleError ? error.code : undefined, reason: failure.reason, message: failure.message,
                 ...(error instanceof AgentChoiceError ? { agentChoice: error.agentChoice } : {}) });
-            stderr(`${message}\n`);
+            stderr(`${failure.message}\n`);
             if (status && !(error instanceof ConsoleError && error.code === "low_balance"))
                 stderr(stateLine(status));
         }
@@ -264,6 +329,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, RESULTS_TOO_LARGE_MESSAGE } from "../contract/cli-refusals.js";
+import { isSelectionRefusal } 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 ?? (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, reason };
+}

package/dist/cli/relay-preparation.js

@@ -6,9 +6,11 @@ import { readLocalFolder } from "../adapters/files.js";
 import { snapshotProvenance, sameFileHashes } from "../adapters/snapshot.js";
 import { validateClientRelease } from "../adapters/release.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";
 import { INVALID_PROPOSAL_MESSAGE } from "../contract/agent-proposal.js";
+import { selectionStartIdentity } from "../contract/selection-metadata.js";
 import { repositoryFacts } from "./git.js";
 /** Absolute checkout paths stay local; repository facts own the start's commit. */
 export function buildRelayStartPayload(facts, files) {
@@ -20,14 +22,22 @@ export function committedFilesOnly(settings) {
 }
 /** Recovery can reuse signature validation without reading the folder again. */
 export async function prepareRelayCheck(folder, options, validated = validateClientRelease(options.release, options.settings)) {
-    const { bundle, tools, settings } = validated;
+    const { bundle, tools } = validated;
     options.signal?.throwIfAborted();
     // Discovery must agree with Git before publishing repository-relative captures.
-    const earlyFacts = outsideLoadersEnabled(options.settings) ? await (options.facts ?? repositoryFacts)(folder) : undefined;
-    options.signal?.throwIfAborted();
-    const read = await readLocalFolder(options.settings, folder, options.trialAdmission, { captureSnapshot: true,
-        proposal: options.proposal,
-        ...(earlyFacts ? { expectedRepositoryRoot: earlyFacts.repoRoot ?? null } : {}) });
+    const selection = options.selection;
+    const factsFolder = selection?.factsFolder ?? folder;
+    let earlyFacts;
+    const { source: read, membership } = await readAnalysisSource(options.settings, folder, {
+        selection, provider: options.selectionProvider, proposal: options.proposal, admission: options.trialAdmission, signal: options.signal,
+        readFolder: async () => {
+            if (outsideLoadersEnabled(options.settings))
+                earlyFacts = await (options.facts ?? repositoryFacts)(factsFolder);
+            options.signal?.throwIfAborted();
+            return readLocalFolder(options.settings, folder, options.trialAdmission, { captureSnapshot: true, proposal: options.proposal,
+                ...(earlyFacts ? { expectedRepositoryRoot: earlyFacts.repoRoot ?? null } : {}) });
+        },
+    });
     if (read.proposalCounts?.fromProposal === 0 && read.proposalCounts.rejected > 0)
         throw new Error(INVALID_PROPOSAL_MESSAGE);
     if (read.agentChoice) {
@@ -40,17 +50,20 @@ export async function prepareRelayCheck(folder, options, validated = validateCli
         });
     }
     const source = { ...read, files: Object.freeze({ ...read.files }) };
-    const provenance = await snapshotProvenance(source.sourceBase ?? folder, source.snapshot, { selectionFolder: folder, committedOnly: committedFilesOnly(options.settings) });
+    const provenance = await snapshotProvenance(selection?.kind === "file" ? selection.launchRoot : source.sourceBase ?? folder, source.snapshot, { selectionFolder: factsFolder, committedOnly: committedFilesOnly(options.settings) });
     if (options.expectedCommit === null) {
         if (!sameFileHashes(options.expectedFiles ?? [], source.snapshot))
             throw new Error(COMMITTED_FILES_MESSAGE);
     }
     else if (options.expectedCommit !== undefined && provenance.commit !== options.expectedCommit)
         throw new Error(COMMITTED_FILES_MESSAGE);
-    const { plan, files } = prepareRelayPlan({ bundle, tools, 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)(folder);
+    const facts = earlyFacts ?? await (options.facts ?? repositoryFacts)(factsFolder);
     options.signal?.throwIfAborted();
-    const startMetadata = { analysisSize: source.analysisSize, startAttempt: randomUUID() };
-    return { source, provenance, plan, start: buildRelayStartPayload(source.sourceBase ? { ...facts, relPath: "" } : facts, files), startMetadata };
+    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,
+        ...(membership ? { membership } : {}) };
 }

package/dist/cli/results-upload.js

@@ -0,0 +1,131 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { ConsoleError } from "../gatekeeper/console.js";
+import { completionRecoveryDecision, completionRetryDeadline, observedCompletionTiming, matchesCheck } from "./completion-recovery.js";
+export 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");
+}
+/** Carry the owner's answer so cleanup cannot turn a definite refusal into an endless retry. */
+export class ResultsUploadError extends ConsoleError {
+    decision;
+    timing;
+    outcome;
+    constructor(error, decision, timing, httpStatus = error instanceof ConsoleError ? error.httpStatus : undefined) {
+        super(error instanceof ConsoleError ? error.code : "unavailable", "intake", error instanceof ConsoleError ? { localReason: error.localReason, responseCode: error.responseCode, httpStatus: error.httpStatus } : {});
+        this.decision = decision;
+        this.timing = timing;
+        this.outcome = { kind: "decided", decision, ...(httpStatus === undefined ? {} : { httpStatus }) };
+        if (error instanceof Error)
+            this.name = error.name;
+        if (error instanceof ConsoleError)
+            this.message = error.message;
+    }
+}
+export const uploadFailure = (error) => {
+    if (!(error instanceof ConsoleError))
+        return { kind: "refused", code: "unavailable", transportFailure: true };
+    return { kind: "refused", code: error.responseCode ?? error.code, httpStatus: error.httpStatus };
+};
+const committed = (value) => ({ checkId: value.checkId, projectId: value.projectId,
+    analysisId: value.analysisId, findingIds: value.findingIds,
+    ...(value.findings ? { findings: value.findings } : {}), settlement: value.settlement });
+/** Status confirms committed identity; intake owns whether a completed payload can still be saved. */
+export async function submitResults(client, payload, signal, options) {
+    const now = options.now ?? Date.now;
+    const wait = options.wait ?? ((ms, signal) => sleep(ms, undefined, { signal }));
+    let timing = { ...options.timing, completedAt: options.timing?.completedAt ?? now(), retryStartedAt: now() };
+    let lookup = { kind: "skipped" };
+    let outcome = { kind: options.retry && options.alreadySaved ? "saved" : "pending" };
+    const uploadHttpStatus = () => "httpStatus" in outcome ? outcome.httpStatus : undefined;
+    const failure = (error, decision) => new ResultsUploadError(error, decision, timing, uploadHttpStatus());
+    const deadline = () => completionRetryDeadline(timing, lookup, payload, outcome);
+    const receipt = (value) => value && matchesCheck(value, payload) && value.uploadState === "saved"
+        ? committed(value) : { checkId: payload.checkId, projectId: payload.projectId };
+    const decide = () => completionRecoveryDecision({ retryEnabled: options.retry, payload, statusLookup: lookup, uploadOutcome: outcome, timing, now: now() });
+    const status = async () => {
+        try {
+            const value = await client.status(payload.reservationId);
+            lookup = { kind: "found", status: value };
+            timing = observedCompletionTiming(timing, lookup, payload);
+            return value;
+        }
+        catch (error) {
+            lookup = { ...uploadFailure(error), kind: "failed" };
+            throw error;
+        }
+    };
+    try {
+        signal.throwIfAborted();
+        const before = await status().catch(error => {
+            const decision = decide();
+            if (options.retry && decision.action === "saved")
+                return undefined;
+            if (!options.retry)
+                throw error;
+            return undefined;
+        });
+        const initial = decide();
+        if (initial.action === "saved")
+            return receipt(before);
+        if (options.retry && initial.action === "give-up")
+            throw failure(new ConsoleError(initial.code === "check_conflict" ? "check_conflict" : initial.code === "reservation_expired" ? "reservation_expired" : "reservation_closed", "intake"), initial);
+        if (before && !options.retry) {
+            if (!matchesCheck(before, payload))
+                throw new ConsoleError("check_conflict");
+            requireIntakeReservation(before);
+        }
+        if (options.retry && now() >= deadline())
+            throw failure(new ConsoleError(), initial);
+        let delay = 1000;
+        for (;;) {
+            signal.throwIfAborted();
+            try {
+                const saved = await client.intake(payload, { acceptAnySuccess: options.retry });
+                outcome = { kind: "saved" };
+                decide();
+                return saved;
+            }
+            catch (error) {
+                outcome = uploadFailure(error);
+                // A lost response may have committed; confirm it before retrying the same payload.
+                const after = await status().catch(() => undefined);
+                const decision = decide();
+                if (decision.action === "saved")
+                    return receipt(after);
+                if (!options.retry) {
+                    if (after && !matchesCheck(after, payload))
+                        throw new ConsoleError("check_conflict");
+                    if (error instanceof ConsoleError && error.code === "unavailable" && after) {
+                        requireIntakeReservation(after);
+                        signal.throwIfAborted();
+                        return await client.intake(payload, { acceptAnySuccess: options.retry });
+                    }
+                    throw error;
+                }
+                const remaining = deadline() - now();
+                if (decision.action !== "retry" || !decision.automatic || remaining <= 0)
+                    throw failure(error, decision);
+                await wait(Math.min(delay, remaining), signal);
+                signal.throwIfAborted();
+                if (now() >= deadline())
+                    throw failure(error, decide());
+                delay = Math.min(delay * 2, 30_000);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ResultsUploadError)
+            throw error;
+        if (signal.aborted && outcome.kind !== "saved")
+            outcome = { kind: "cancelled", httpStatus: uploadHttpStatus() };
+        const decision = decide();
+        if (decision.action === "saved")
+            return receipt();
+        throw failure(error, decision);
+    }
+}