@counterfact-labs/cli 0.1.2 → 0.2.3

package/dist/cli/mcp.js

@@ -0,0 +1,297 @@
+import { createInterface } from "node:readline";
+import { once } from "node:events";
+import { resolveFolderPath } from "../adapters/folder-path.js";
+import { FINISH_FAILURE_MESSAGE, START_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
+import { errorCode, errorText } from "./api.js";
+import { commandContext } from "./context.js";
+import { analyze } from "./commands/analyze.js";
+import { CLI_VERSION } from "../contract/cli-version.js";
+import { finding } from "./commands/finding.js";
+import { balance } from "./commands/balance.js";
+import { ANALYZE_TOOL_NAME, analyzeToolAllowed } from "./claude-code-permission.js";
+import { signInStatus, startSignIn } from "./sign-in.js";
+import { readEmailSignIn } from "../adapters/settings.js";
+import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
+import { EMAIL_SIGN_IN_TERMS, normalizeSignInEmail, validSignInCode, startEmailSignIn, signInWithCode } from "./email-sign-in.js";
+import { resolveAgentFolder, resolveMcpAgentFolder } from "./agent-folder.js";
+import { suggestedEmail } from "./suggested-email.js";
+const legacyTools = [
+    {
+        name: ANALYZE_TOOL_NAME,
+        description: "Analyze the agent in a folder on this computer. Each call runs one analysis and charges the user's balance, so call it only when the user asks for an analysis. After edits, suggest an analysis and wait for the user to ask. Prices are listed on the top-up page and website. If the balance doesn't cover the analysis, show the returned message and top-up link.",
+        inputSchema: { type: "object", properties: { path: { type: "string", description: "The agent folder on this computer." } }, required: ["path"], additionalProperties: false },
+    },
+    { name: "get_finding", description: "Get a finding's explanation, quoted lines, and suggested fixes.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false } },
+    { name: "get_balance", description: "Get the balance and top-up link.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+    { name: "sign_in_status", description: "Check whether this computer is signed in to Counterfact, and whether the user has allowed the analysis tool in Claude Code. With wait: true, first wait for a sign-in started by sign_in to finish.", inputSchema: { type: "object", properties: { wait: { type: "boolean" } }, additionalProperties: false } },
+    { name: "sign_in", description: "Open the Counterfact sign-in page in the user's browser. Then call sign_in_status with wait: true.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+];
+class ProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+export async function serveMcp(input, output, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const guarded = (options.env ?? process.env).CF_MCP_PATH_GUARD !== "0";
+    const launch = guarded ? resolveFolderPath(cwd).catch(() => null) : Promise.resolve(cwd);
+    const lastAnalysis = new Map();
+    const emailSignIn = options.emailSignIn ?? readEmailSignIn(options.env);
+    const tools = emailSignIn ? [...legacyTools.slice(0, 3),
+        {
+            name: "sign_in_status",
+            description: "Check whether this computer is signed in to Counterfact and whether the user has allowed the analysis tool in Claude Code. Use path only to choose the agent folder for the local git email suggestion; otherwise use the launch folder. Analysis permission is always checked in the launch folder. A valid local git email is returned as suggestedEmail. Prefer the signed-in user's email already in your context; otherwise offer suggestedEmail. Ask the user to confirm an address before sending a code. With wait: true, wait only for browser sign-in to finish.",
+            inputSchema: { type: "object", properties: {
+                    wait: { type: "boolean" },
+                    path: { type: "string", description: "The chosen agent folder for the local git email suggestion. Defaults to the launch folder; does not change the analysis permission check." },
+                }, additionalProperties: false },
+        },
+        {
+            name: "sign_in",
+            description: `With email, send a Counterfact sign-in code only after the user confirms that address. Before calling, show: ${EMAIL_SIGN_IN_TERMS} Then ask the user for the code from their email and call sign_in_with_code. Without email, open the Counterfact sign-in page in the user's browser, show the returned link and code, then call sign_in_status with wait: true.`,
+            inputSchema: { type: "object", properties: {
+                    email: { type: "string", description: "The email address confirmed by the user." },
+                }, additionalProperties: false },
+        },
+        {
+            name: "sign_in_with_code",
+            description: "Complete Counterfact email sign-in with the confirmed email address and the code supplied by the user. Save the sign-in on this computer. Never repeat the code in messages, logs, or reports. Do not request another code automatically.",
+            inputSchema: { type: "object", properties: {
+                    email: { type: "string", description: "The email address confirmed by the user." },
+                    code: { type: "string", description: "The sign-in code supplied by the user from their email." },
+                }, required: ["email", "code"], additionalProperties: false },
+        },
+    ] : legacyTools;
+    let pendingSignIn;
+    const requests = new Map();
+    let queue = Promise.resolve();
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    async function toolCall(params, signal) {
+        if (!object(params) || typeof params.name !== "string")
+            throw new ProtocolError(-32602, "Choose a tool and its arguments.");
+        const args = params.arguments ?? {};
+        if (!object(args))
+            throw new ProtocolError(-32602, "Tool arguments must be an object.");
+        const name = params.name;
+        const allowed = name === ANALYZE_TOOL_NAME ? ["path"] : name === "get_finding" ? ["id"]
+            : name === "sign_in_status" ? (emailSignIn ? ["wait", "path"] : ["wait"])
+                : emailSignIn && name === "sign_in" ? ["email"] : emailSignIn && name === "sign_in_with_code" ? ["email", "code"] : [];
+        if (!tools.some(tool => tool.name === name) || Object.keys(args).some(key => !allowed.includes(key)))
+            throw new ProtocolError(-32602, "Unknown tool or argument.");
+        if (name === ANALYZE_TOOL_NAME && (typeof args.path !== "string" || !args.path.trim()))
+            throw new ProtocolError(-32602, "Provide a path.");
+        if (name === "get_finding" && (typeof args.id !== "string" || !args.id.trim()))
+            throw new ProtocolError(-32602, "Provide a finding id.");
+        if (name === "sign_in_status" && args.wait !== undefined && typeof args.wait !== "boolean")
+            throw new ProtocolError(-32602, "Provide an optional boolean wait.");
+        if (name === "sign_in_status" && "path" in args && (typeof args.path !== "string" || !args.path.trim()))
+            throw new ProtocolError(-32602, "Provide a path.");
+        const emailFlow = name === "sign_in_with_code" || (name === "sign_in" && "email" in args);
+        const email = emailFlow ? normalizeSignInEmail(args.email) : undefined;
+        if (emailFlow && !email)
+            throw new ProtocolError(-32602, emailSignInMessages.invalid_email);
+        if (name === "sign_in_with_code" && !validSignInCode(args.code))
+            throw new ProtocolError(-32602, emailSignInMessages.invalid_code);
+        let text = "", exitCode = 0;
+        let findingIds;
+        let url;
+        let signIn;
+        try {
+            const ctx = commandContext({ ...options, emailSignIn, signal, onCheckComplete: result => {
+                    findingIds = result.findingIds ?? [];
+                    url = result.url;
+                    options.onCheckComplete?.(result);
+                }, write: chunk => {
+                    // Progress is transient terminal text; only the final lines belong in a tool response.
+                    if (!chunk.startsWith("\r"))
+                        text += chunk;
+                } });
+            if (name === "get_finding")
+                await finding(args.id, ctx);
+            else if (name === "get_balance")
+                await balance(ctx);
+            else if (name === "sign_in_status") {
+                const pending = pendingSignIn;
+                const allowed = await analyzeToolAllowed(ctx.homeDir, cwd);
+                if (args.wait === true && pending) {
+                    const cancel = () => pending.controller.abort();
+                    signal.addEventListener("abort", cancel, { once: true });
+                    try {
+                        if (signal.aborted)
+                            cancel();
+                        await pending.flow.done;
+                    }
+                    finally {
+                        signal.removeEventListener("abort", cancel);
+                    }
+                }
+                signIn = { ...await signInStatus(ctx), analyzeToolAllowed: allowed };
+                text = signIn.signedIn ? "Signed in." : "Not signed in.";
+                if (emailSignIn) {
+                    const suggestion = await suggestedEmail(resolveAgentFolder(args.path ?? ".", cwd), ctx.readEmail);
+                    if (suggestion)
+                        signIn.suggestedEmail = suggestion;
+                }
+            }
+            else if (emailFlow) {
+                if (pendingSignIn)
+                    throw new Error(emailSignInMessages.browser_sign_in_pending);
+                if (name === "sign_in") {
+                    const start = await startEmailSignIn(ctx, email);
+                    signIn = { email: email, expiresIn: start.expiresIn };
+                    text = `We sent a sign-in code to ${email}. Ask the user for the code from their email, then call sign_in_with_code with the same email and their code. Do not repeat the code.`;
+                }
+                else {
+                    await signInWithCode(ctx, email, args.code);
+                    signIn = { signedIn: true };
+                    text = "Signed in.";
+                }
+            }
+            else if (name === "sign_in") {
+                if ((await signInStatus(ctx)).signedIn)
+                    text = "Already signed in.";
+                else {
+                    let pending = pendingSignIn;
+                    if (!pending) {
+                        // The flow outlives this call; a later wait call can cancel its polling.
+                        const controller = new AbortController();
+                        const cancel = () => controller.abort();
+                        signal.addEventListener("abort", cancel, { once: true });
+                        try {
+                            signal.throwIfAborted();
+                            const flow = await startSignIn(commandContext({ ...options, emailSignIn, homeDir: ctx.homeDir, baseUrl: ctx.api.baseUrl, signal: controller.signal }));
+                            pending = { flow, controller, opened: false };
+                            pendingSignIn = pending;
+                            const current = pending;
+                            const clear = () => { if (pendingSignIn === current)
+                                pendingSignIn = undefined; };
+                            // Handle background failures even when the client never calls wait.
+                            void flow.done.then(clear, clear);
+                            pending.opened = await ctx.openBrowser(flow.pageUrl);
+                        }
+                        finally {
+                            signal.removeEventListener("abort", cancel);
+                        }
+                    }
+                    signIn = { pageUrl: pending.flow.pageUrl, userCode: pending.flow.userCode };
+                    text = pending.opened ? `Opening your browser… If nothing opens, go to ${signIn.pageUrl} on any device and enter ${signIn.userCode}.`
+                        : `Go to ${signIn.pageUrl} on any device and enter ${signIn.userCode}.`;
+                }
+            }
+            else {
+                const launchFolder = await launch;
+                if (guarded && !launchFolder)
+                    throw new Error(START_FAILURE_MESSAGE);
+                const folder = guarded ? await resolveMcpAgentFolder(args.path, launchFolder, ctx.homeDir) : resolveAgentFolder(args.path, cwd);
+                const last = lastAnalysis.get(folder);
+                if (guarded && last !== undefined && ctx.now() - last < 10 * 60 * 1000) {
+                    throw new Error(FINISH_FAILURE_MESSAGE);
+                }
+                let started = false;
+                try {
+                    exitCode = await analyze(folder, {}, { ...ctx, onCheckStart: () => {
+                            started = true;
+                            if (guarded)
+                                lastAnalysis.set(folder, ctx.now());
+                            ctx.onCheckStart?.();
+                        } });
+                }
+                finally {
+                    if (guarded && started)
+                        lastAnalysis.set(folder, ctx.now());
+                }
+            }
+        }
+        catch (error) {
+            text += errorText(error) + "\n";
+            exitCode = errorCode(error);
+        }
+        // Some clients (Claude Code among them) give the model only the structured result when one is present, so it
+        // repeats the text: without it the model cannot read the result.
+        return { content: [{ type: "text", text }], isError: exitCode !== 0,
+            structuredContent: { text, exitCode, ...(findingIds ? { findingIds } : {}), ...(url ? { url } : {}), ...signIn } };
+    }
+    async function respond(message, id, signal) {
+        if (signal.aborted)
+            return;
+        let reply;
+        try {
+            let result;
+            if (message.method === "initialize") {
+                const requested = object(message.params) ? message.params.protocolVersion : undefined;
+                result = { protocolVersion: ["2024-11-05", "2025-03-26", "2025-06-18"].includes(requested) ? requested : "2025-06-18",
+                    capabilities: { tools: {} }, serverInfo: { name: "counterfact-labs", version: CLI_VERSION } };
+            }
+            else if (message.method === "ping")
+                result = {};
+            else if (message.method === "tools/list")
+                result = { tools };
+            else if (message.method === "tools/call")
+                result = await toolCall(message.params, signal);
+            else
+                throw new ProtocolError(-32601, "Method not found.");
+            reply = { jsonrpc: "2.0", id, result };
+        }
+        catch (error) {
+            reply = errorReply(id, error);
+        }
+        // The caller stopped waiting; a late result must not look like a completed call.
+        // The output is an MCP stdio Writable carrying JSON-RPC, not an HTML HTTP response.
+        // nosemgrep: javascript.express.security.audit.xss.direct-response-write.direct-response-write
+        if (!signal.aborted && !output.write(JSON.stringify(reply) + "\n"))
+            await once(output, "drain");
+    }
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        let id = null;
+        let reply;
+        try {
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                throw new ProtocolError(-32700, "Invalid JSON.");
+            }
+            if (!object(message) || message.jsonrpc !== "2.0" || typeof message.method !== "string"
+                || (message.id !== undefined && typeof message.id !== "string" && typeof message.id !== "number" && message.id !== null))
+                throw new ProtocolError(-32600, "Invalid request.");
+            if (message.id === undefined) {
+                if (message.method === "notifications/cancelled" && object(message.params)) {
+                    const requestId = message.params.requestId;
+                    if (typeof requestId === "string" || typeof requestId === "number")
+                        requests.get(requestId)?.abort();
+                }
+                continue;
+            }
+            id = message.id;
+            const controller = new AbortController();
+            requests.set(id, controller);
+            // Keep tool requests in order while still reading cancellation notifications.
+            const request = message;
+            queue = queue.then(() => respond(request, id, controller.signal)).finally(() => { requests.delete(id); });
+            continue;
+        }
+        catch (error) {
+            reply = errorReply(id, error);
+        }
+        if (!output.write(JSON.stringify(reply) + "\n"))
+            await once(output, "drain");
+    }
+    try {
+        await queue;
+    }
+    finally {
+        pendingSignIn?.controller.abort();
+    }
+}
+function errorReply(id, error) {
+    return { jsonrpc: "2.0", id, error: {
+            code: error instanceof ProtocolError ? error.code : -32603,
+            message: error instanceof ProtocolError ? error.message : "The request could not be completed.",
+        } };
+}

package/dist/cli/output.js

@@ -0,0 +1,10 @@
+export function money(micro) {
+    const cents = Math.round(micro / 10_000);
+    const whole = Math.trunc(cents / 100);
+    const fraction = Math.abs(cents % 100);
+    return `${cents < 0 ? "-" : ""}$${Math.abs(whole)}${fraction ? `.${String(fraction).padStart(2, "0")}` : ""}`;
+}
+export function tasteText(taste, findingIds) {
+    return [taste.headline, ...taste.lines.map(line => `  ${line}`),
+        ...(findingIds.length ? [`Finding ids: ${findingIds.join(", ")}`] : []), `Full results: ${taste.url}`, ""].join("\n");
+}

package/dist/cli/relay-check.js

@@ -0,0 +1,239 @@
+import { resolveFolderPath } from "../adapters/folder-path.js";
+import { savedAnalysisUrl } from "../contract/console-url.js";
+import { randomUUID } from "node:crypto";
+import { disabledSetupPings } from "../setup-pings/client.js";
+import { saveCompletion, loadCompletion } from "../adapters/completion.js";
+import { saveLocalResults } from "../adapters/results.js";
+import { OutputPathError, outputPaths } from "../adapters/output-paths.js";
+import { validateClientRelease } from "../adapters/release.js";
+import { selectAnalysisExecution } from "../adapters/models.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 { ConsoleClient, ConsoleError } from "../gatekeeper/console.js";
+import { GatekeeperClient } from "../gatekeeper/client.js";
+import { connectRelay, relayOrigin } from "../gatekeeper/connection.js";
+import productionTrust from "../gatekeeper/trust/production.json" with { type: "json" };
+import { runAnalysisToEnd } from "../core/analysis/run-to-end.js";
+import { formatSummary } from "./summary.js";
+import { buildIntakePayload } from "./intake-payload.js";
+import { completionRecoveryDecision, COMPLETION_SETTINGS_MISMATCH_MESSAGE, matchesCheck } from "./completion-recovery.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, 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);
+}
+/** The caller supplies the paid reservation; this runner owns its connection through cleanup. */
+export function runReservedRelayCheck(folder, options) {
+    return runRelayLifecycle(folder, options, options);
+}
+async function runRelayLifecycle(folder, options, existing) {
+    const { config, settings, stdout, stderr } = options;
+    let client, reservationId, projectId;
+    let connection = existing?.connection;
+    let identity;
+    let completedPayload;
+    let completionOrigin;
+    let completed = false, uploaded = false, heartbeat;
+    let renewal;
+    const controller = new AbortController();
+    const signal = options.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
+    const showSaved = (result) => {
+        const url = savedAnalysisUrl(result.projectId, config.CF_CONSOLE_URL);
+        options.onSaved?.({ ...result, url });
+        stdout(`Saved analysis ${result.analysisId}: ${url}\n`);
+    };
+    try {
+        if (!config.CF_CONSOLE_URL || !existing && (!config.CF_RELAY_URL || !config.CF_CONSOLE_TOKEN)) {
+            throw new Error(cliRefusals.release_unavailable);
+        }
+        if (existing) {
+            requireIntakeReservation(existing.reservation);
+            if (existing.reservation.projectId !== existing.expectedProjectId)
+                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.
+        const validated = validateClientRelease(options.release, settings);
+        const { bundle } = validated;
+        folder = await resolveFolderPath(folder);
+        signal.throwIfAborted();
+        const prior = await loadCompletion(folder);
+        if (prior && (!prior.uploaded && !prior.finished || options.retryUpload)) {
+            // 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");
+            }
+            completedPayload = prior.payload;
+            completionOrigin = prior.consoleOrigin;
+            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);
+            uploaded = true;
+            await saveCompletion(folder, prior.payload, prior.consoleOrigin, true);
+            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.");
+        try {
+            await outputPaths(folder, ["findings.json", "summary.md"], options.outputDir);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const { source, provenance, plan, start } = await prepareRelayCheck(folder, { ...options, signal, expectedCommit: existing?.expectedCommit }, validated);
+        let reservation = existing?.reservation;
+        if (!reservation) {
+            const started = await client.start(start);
+            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);
+            signal.throwIfAborted();
+            reservation = await client.reserve({ reservationId });
+        }
+        const activeClient = client, activeId = reservationId;
+        let lease = reservation;
+        heartbeat = setInterval(() => {
+            if (renewal)
+                return;
+            renewal = activeClient.heartbeat(activeId).then(status => {
+                if (status.state !== "reserved")
+                    throw new Error();
+                lease = status;
+            }).catch(() => { controller.abort(); }).finally(() => { renewal = undefined; });
+        }, 60000);
+        heartbeat.unref();
+        const execution = await selectAnalysisExecution(config, () => { throw new Error(); }, {
+            client: new GatekeeperClient({ mode: "production", connection: connection,
+                deadlineMs: () => Math.min(Date.parse(lease.expiresAt), lease.absoluteExpiresAt ? Date.parse(lease.absoluteExpiresAt) : Infinity), }), bundleVersion: bundle.version,
+            reservationId: activeId, reservationToken: reservation.reservationToken, instructions: { bundle, verificationKey: options.release.verificationKey }, signal,
+        });
+        options.onStart?.();
+        stderr("Reading the folder and running analysis.\n");
+        (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);
+        const payload = buildIntakePayload({ checkId: reservation.checkId, projectId: projectId, reservationId,
+            bundleVersion: bundle.version, relayVersion: options.release.relayVersion, counterfactLocalVersion: options.release.localVersion }, provenance, report);
+        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));
+        stdout(`\nSaved ${paths.findingsPath}\nSaved ${paths.summaryPath}\n`);
+        showSaved(saved);
+        return 0;
+    }
+    catch (error) {
+        let status;
+        if (client && reservationId) {
+            try {
+                status = await (completed || uploaded ? client.status(reservationId) : client.fail(reservationId));
+            }
+            catch {
+                // An uncertain server outcome cannot prove a refund.
+            }
+        }
+        if (status?.uploadState === "saved" && identity && matchesCheck(status, identity)) {
+            if (completedPayload) {
+                try {
+                    await saveCompletion(folder, completedPayload, completionOrigin, true);
+                }
+                catch { /* Committed server state still survives a local write failure. */ }
+            }
+            try {
+                showSaved({ projectId: status.projectId, analysisId: status.analysisId, findingIds: status.findingIds });
+            }
+            catch { /* Output failure must not change a server outcome. */ }
+            return 0;
+        }
+        const recovery = completionRecoveryDecision({ statusSucceeded: status !== undefined, status, completedPayload });
+        if (completedPayload && recovery.finished) {
+            try {
+                await saveCompletion(folder, completedPayload, completionOrigin, false, true);
+            }
+            catch { /* Keep the pending record if the durable write cannot be confirmed. */ }
+        }
+        const known = error instanceof ConsoleError || error instanceof OutputPathError || error instanceof Error && ([cliRefusals.release_unavailable, COMMITTED_FILES_MESSAGE, RESULTS_TOO_LARGE_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 });
+            stderr(`${message}\n`);
+            if (status && !(error instanceof ConsoleError && error.code === "low_balance"))
+                stderr(stateLine(status));
+        }
+        catch { /* Output failure must not change a server outcome. */ }
+        return refusalExitCode(error instanceof ConsoleError ? error.code : undefined);
+    }
+    finally {
+        clearInterval(heartbeat);
+        await renewal;
+        try {
+            connection?.close();
+        }
+        catch { /* A committed intake is already authoritative. */ }
+    }
+}

package/dist/cli/relay-preparation.js

@@ -0,0 +1,31 @@
+import { outsideLoadersEnabled } from "../analysis-core/settings.js";
+import { readLocalFolder } from "../adapters/files.js";
+import { snapshotProvenance } from "../adapters/snapshot.js";
+import { validateClientRelease } from "../adapters/release.js";
+import { prepareRelayPlan } from "../adapters/relay-plan.js";
+import { COMMITTED_FILES_MESSAGE } from "../contract/cli-refusals.js";
+import { repositoryFacts } from "./git.js";
+/** Absolute checkout paths stay local; repository facts own the start's commit. */
+export function buildRelayStartPayload(facts, files) {
+    const { remoteUrl, relPath, folderName, branch, commit, dirty } = facts;
+    return { execution: "local", remoteUrl, relPath, folderName, branch, commit, dirty, files };
+}
+/** 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 } = 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,
+        ...(earlyFacts ? { expectedRepositoryRoot: earlyFacts.repoRoot ?? null } : {}) });
+    const source = { ...read, files: Object.freeze({ ...read.files }) };
+    const provenance = await snapshotProvenance(source.sourceBase ?? folder, source.snapshot, source.sourceBase ? { selectionFolder: folder } : undefined);
+    if (options.expectedCommit !== undefined && provenance.commit !== options.expectedCommit)
+        throw new Error(COMMITTED_FILES_MESSAGE);
+    const { plan, files } = prepareRelayPlan({ bundle, tools, settings: options.settings, relayVersion: options.release.relayVersion, source });
+    options.signal?.throwIfAborted();
+    const facts = earlyFacts ?? await (options.facts ?? repositoryFacts)(folder);
+    options.signal?.throwIfAborted();
+    return { source, provenance, plan, start: buildRelayStartPayload(source.sourceBase ? { ...facts, relPath: "" } : facts, files) };
+}