@counterfact-labs/cli 0.2.6 → 0.2.7

package/dist/cli/scope-choices.js

@@ -0,0 +1,57 @@
+import { readdir, readFile, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { outputPaths, writeOutputFiles } from "../adapters/output-paths.js";
+import { analysisScopeSchema, chooseScopeResultSchema, CHOOSE_SCOPE_MESSAGE, INCLUDED_FILES_CAPTION, OMITTED_IMPORTS_CAPTION, SCOPE_CHOICE_INSTRUCTION, INCOMPLETE_IMPORTS_MESSAGE, IMPORT_DISCOVERY_LIMIT_MESSAGE, INVALID_SCOPE_MESSAGE, SCOPE_RETRY_TEMPLATE } from "../contract/scope-choice.js";
+import { scopeChoiceRefusal } from "../contract/selection-offer.js";
+import { scopeChoicesEnabled } from "../adapters/settings.js";
+export async function loadAnalysisScope(options, cwd, settings) {
+    if (options.scope === undefined && options.scopeFile === undefined)
+        return undefined;
+    if (!scopeChoicesEnabled(settings))
+        throw new Error(INVALID_SCOPE_MESSAGE);
+    try {
+        const value = options.scopeFile === undefined ? options.scope : JSON.parse(await readFile(resolve(cwd, options.scopeFile), "utf8"));
+        return analysisScopeSchema.parse(value);
+    }
+    catch {
+        throw new Error(INVALID_SCOPE_MESSAGE);
+    }
+}
+export function shellQuote(value) { return `'${value.replaceAll("'", `'"'"'`)}'`; }
+/** MCP and terminal output share the same file coverage; only the terminal adds retry commands. */
+export function scopeChoiceText(value, retryPaths = {}) {
+    const result = chooseScopeResultSchema.parse(value);
+    const refusal = scopeChoiceRefusal(result);
+    if (refusal)
+        return refusal + "\n";
+    const lines = [CHOOSE_SCOPE_MESSAGE];
+    if (!result.coverageComplete && result.refusedEdges.length > 0)
+        lines.push(INCOMPLETE_IMPORTS_MESSAGE);
+    if (!result.coverageComplete && result.frontierCount > 0)
+        lines.push(IMPORT_DISCOVERY_LIMIT_MESSAGE);
+    result.choices.forEach((choice, index) => {
+        lines.push(`${index + 1}. ${choice.label}`, choice.description, INCLUDED_FILES_CAPTION, ...choice.includes.map(path => `  ${path}`));
+        if (choice.omitted.length > 0)
+            lines.push(OMITTED_IMPORTS_CAPTION, ...choice.omitted.map(path => `  ${path}`));
+        if (choice.fits !== false && retryPaths[index]) {
+            const entry = choice.scope.entry.startsWith("-") ? `./${choice.scope.entry}` : choice.scope.entry;
+            lines.push(SCOPE_RETRY_TEMPLATE.replace("{quoted-entry}", () => shellQuote(entry))
+                .replace("{quoted-scope-file}", () => shellQuote(retryPaths[index])));
+        }
+    });
+    lines.push(SCOPE_CHOICE_INSTRUCTION);
+    return lines.join("\n") + "\n";
+}
+export async function renderScopeChoices(value, anchor) {
+    const result = chooseScopeResultSchema.parse(value);
+    // Validate the output directory and old entries before removing only generated scope files.
+    const [probe] = await outputPaths(anchor.outputAnchor, ["scope-1.json"], anchor.outputDir, true);
+    const old = (await readdir(dirname(probe))).filter(name => /^scope-.*\.json$/.test(name));
+    await outputPaths(anchor.outputAnchor, old, anchor.outputDir);
+    for (const name of old)
+        await unlink(join(dirname(probe), name));
+    const runnable = result.choices.flatMap((choice, index) => choice.fits === false ? [] : [{ choice, index }]);
+    const files = Object.fromEntries(runnable.map(({ choice, index }) => [`scope-${index + 1}.json`, JSON.stringify(choice.scope, null, 2) + "\n"]));
+    const paths = await writeOutputFiles(anchor.outputAnchor, files, anchor.outputDir);
+    return scopeChoiceText(result, Object.fromEntries(runnable.map(({ index }, position) => [index, paths[position]])));
+}

package/dist/contract/cli-refusals.js

@@ -4,6 +4,12 @@ import { emailSignInMessages } from "./email-sign-in-messages.js";
 export const START_FAILURE_MESSAGE = "This couldn't start. Try again.";
 export const RESERVATION_EXPIRED_MESSAGE = "This reservation expired. Start a new analysis.";
 export const FINISH_FAILURE_MESSAGE = "The analysis couldn't finish. Try again.";
+export const NOT_ALLOWED_MESSAGE = "Your account can't run analyses. Ask Counterfact for access.";
+export const SIGN_IN_EXPIRED_MESSAGE = "Your sign-in has expired. Run counterfact-labs login, then try again.";
+export const FOLDER_BUSY_MESSAGE = "Another analysis is running on this folder. Try again when it finishes.";
+export const CHECK_CONFLICT_MESSAGE = "Saved results from an earlier run don't match this analysis. Start a new analysis.";
+export const UNSAVED_RESULTS_MESSAGE = "The analysis ended before its results were saved. Start a new analysis.";
+export const PENDING_RESULTS_MESSAGE = "Your results are kept on this computer. Run the same command on the same folder again to save them at no extra charge.";
 export const RESULTS_TOO_LARGE_MESSAGE = "The results were too large to save. Try again.";
 export const COMMITTED_FILES_MESSAGE = "Counterfact analyzes the committed version of the agent's files. Commit your changes, then try again.";
 const unsupportedVersion = "This version of Counterfact can't run analyses. Update it: npm install -g @counterfact-labs/cli@latest.";
@@ -70,6 +76,8 @@ const reasonValues = [
     ...Object.keys(localRefusals),
     ...Object.values(otherReasons), ...Object.values(messageReasons),
     "console_unreachable", "invalid_console_url", "relay_unreachable", "results_not_saved",
+    "results_saved_report_failed", "results_pending", "results_discarded",
+    "folder_busy", "completion_settings_mismatch",
 ];
 const ownedReasons = new Set(reasonValues);
 /** Only fixed reasons may cross the MCP boundary; diagnostics can contain customer data. */

package/dist/contract/cli-version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.2.6";
+export const CLI_VERSION = "0.2.7";

package/dist/contract/console.js

@@ -5,6 +5,7 @@ import { sourceNotesSchema } from "../analysis-core/analysis/source-notes/types.
 import { parseAnalysisSize } from "../analysis-core/conventions/analysis-fit.js";
 import { canonicalUuidSchema as uuid, matchingFindingNumbers, numberedFindingsSchema } from "./findings.js";
 import { RESULT_CHECK_LIMITS, validIntakeText } from "../analysis-core/contracts/relay-analysis.js";
+import { selectionStartIdentitySchema } from "./selection-metadata.js";
 export const id = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/);
 const money = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
 const count = (max) => z.number().int().positive().max(max);
@@ -13,13 +14,15 @@ export const LOCAL_START_EXECUTION_HEADER = { name: "x-counterfact-execution", v
 export const LOCAL_START_BODY_LIMIT = 2 * 1024 * 1024;
 export const ANALYSIS_SIZE_HEADER = "x-counterfact-analysis-size";
 export const START_ATTEMPT_HEADER = "x-counterfact-start-attempt";
+export const SELECTION_IDENTITY_HEADER = "x-counterfact-selection";
 export const ANALYSIS_SIZE_HEADER_LIMIT = 256;
 /** Additive headers let older consoles keep accepting the unchanged, strict start body. */
 export function serializeLocalStartMetadata(metadata) {
     const size = JSON.stringify(parseAnalysisSize(metadata.analysisSize));
     if (Buffer.byteLength(size, "utf8") > ANALYSIS_SIZE_HEADER_LIMIT)
         throw new Error("Invalid analysis size header");
-    return { [ANALYSIS_SIZE_HEADER]: size, [START_ATTEMPT_HEADER]: uuid.parse(metadata.startAttempt) };
+    return { [ANALYSIS_SIZE_HEADER]: size, [START_ATTEMPT_HEADER]: uuid.parse(metadata.startAttempt),
+        ...(metadata.selection === undefined ? {} : { [SELECTION_IDENTITY_HEADER]: JSON.stringify(selectionStartIdentitySchema.parse(metadata.selection)) }) };
 }
 /** Missing measurements preserve old clients; present measurements must be complete. */
 export function parseLocalStartMetadata(headers) {
@@ -28,7 +31,9 @@ export function parseLocalStartMetadata(headers) {
         return undefined;
     if (Buffer.byteLength(raw, "utf8") > ANALYSIS_SIZE_HEADER_LIMIT)
         throw new Error("Invalid analysis size header");
-    return { analysisSize: parseAnalysisSize(JSON.parse(raw)), startAttempt: uuid.parse(headers.get(START_ATTEMPT_HEADER)) };
+    const selection = headers.get(SELECTION_IDENTITY_HEADER);
+    return { analysisSize: parseAnalysisSize(JSON.parse(raw)), startAttempt: uuid.parse(headers.get(START_ATTEMPT_HEADER)),
+        ...(selection === null ? {} : { selection: selectionStartIdentitySchema.parse(JSON.parse(z.string().max(256).parse(selection))) }) };
 }
 const localStartPath = z.string().min(1).max(4096).refine(value => !value.includes("\\") && !value.includes("\0") && !value.startsWith("/")
     && value.split("/").every(part => part !== ".." && part !== "." && part !== ""));

package/dist/contract/scope-choice.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { ANALYSIS_SELECTION_LIMITS, provenScopeChoiceSchema } from "../analysis-core/contracts/analysis-selection.js";
+import { refusedImportSchema } from "../analysis-core/contracts/module-resolution.js";
+import { selectionPathSchema, snapshotIdSchema } from "../analysis-core/contracts/selection-paths.js";
+import { FileReadRefusal } from "../analysis-core/conventions/file-admission.js";
+export { analysisScopeSchema } from "../analysis-core/contracts/analysis-selection.js";
+// Proposed copy stays here so wiring the CLI and MCP cannot create different promises about coverage.
+export const CHOOSE_SCOPE_MESSAGE = "This analysis is too large to run at once. Choose what Counterfact should read.";
+export const ENTRY_ONLY_LABEL = "Only the selected file";
+export const ENTRY_ONLY_DESCRIPTION = "Read {entry}. Leave its imports out of this analysis.";
+export const SELECTED_IMPORTS_LABEL = "The selected file and some imports";
+export const SELECTED_IMPORTS_DESCRIPTION = "Read {entry} and the imports listed below. Leave the other imports out of this analysis.";
+export const ENTRY_IMPORTS_LABEL = "One agent file and its imports";
+export const ENTRY_IMPORTS_DESCRIPTION = "Read {entry} and its project imports inside the launch folder.";
+export const SINGLE_FILE_TOO_LARGE_MESSAGE = "This file is too large to analyze on its own. Choose another agent file or split this file into smaller files.";
+export const INVALID_SELECTION_MESSAGE = "Choose an agent file or folder inside the launch folder.";
+export const INVALID_SCOPE_MESSAGE = "This scope could not be used. Choose one of the returned scopes and try again.";
+export const STALE_SCOPE_MESSAGE = "The selected files changed. Run the analysis again to get updated scope choices.";
+export const SCOPE_PROPOSAL_CONFLICT_MESSAGE = "The selected scope and proposed files do not match. Keep the selected file and only its listed imports.";
+export const SELECTION_REFUSAL_MESSAGES = Object.freeze([
+    INVALID_SELECTION_MESSAGE, INVALID_SCOPE_MESSAGE, STALE_SCOPE_MESSAGE, SCOPE_PROPOSAL_CONFLICT_MESSAGE,
+    SINGLE_FILE_TOO_LARGE_MESSAGE,
+]);
+export function isSelectionRefusal(error, fileMode) {
+    return error instanceof Error && (SELECTION_REFUSAL_MESSAGES.includes(error.message)
+        || fileMode && error instanceof FileReadRefusal);
+}
+export const INCLUDED_FILES_CAPTION = "Included files:";
+export const OMITTED_IMPORTS_CAPTION = "Imports left out:";
+export const SCOPE_CHOICE_INSTRUCTION = "Choose a scope, then run the analysis again with that scope.";
+export const INCOMPLETE_IMPORTS_MESSAGE = "Some imports could not be resolved. This analysis covers only the files listed below.";
+export const IMPORT_DISCOVERY_LIMIT_MESSAGE = "Counterfact reached the import discovery limit. The list of imports is incomplete.";
+export const SELECTED_FILES_PROGRESS = "Reading the selected files and running analysis.\n";
+export const SELECTED_PATH_FAILURE = "Analysis could not finish. Check the selected path, provider key and connection.";
+export function progressLine(selection, surface = "source") {
+    return selection?.kind === "file" ? SELECTED_FILES_PROGRESS
+        : surface === "terminal" ? "Analyzing the agent…" : "Reading the folder and running analysis.\n";
+}
+export function failureLine(selection) {
+    return selection?.kind === "file" ? SELECTED_PATH_FAILURE : "Analysis could not finish. Check the folder, provider key and connection.";
+}
+export const SELECTION_COVERAGE_DESCRIPTION = "This analysis covers {entry} and {count} selected imports. Other imports were left out.";
+export const SCOPE_RETRY_TEMPLATE = "Run again: counterfact-labs analyze {quoted-entry} --scope {quoted-scope-file}";
+export const FILE_SCOPE_PUBLIC_USAGE = "Usage: counterfact-labs analyze [path] [--proposal <json-file>] [--scope <json-file>]\n       counterfact-labs finding <id>\n       counterfact-labs balance | login | logout | mcp\n";
+export const FILE_SCOPE_SOURCE_USAGE = "Usage: npx tsx cli/check.ts <path> [--output <directory>] [--scope <json-file>]\n";
+export const scopeChoiceSchema = provenScopeChoiceSchema.safeExtend({
+    label: z.enum([ENTRY_ONLY_LABEL, SELECTED_IMPORTS_LABEL, ENTRY_IMPORTS_LABEL]),
+    description: z.string().min(1).max(8192),
+    // Fewer files do not prove admission; only the ordinary run checks can set true.
+    fits: z.union([z.boolean(), z.literal("unknown")]),
+}).refine(choice => {
+    const imports = choice.scope.imports;
+    const entryOnly = imports === "none" || Array.isArray(imports) && imports.length === 0;
+    const label = entryOnly ? ENTRY_ONLY_LABEL : imports === "all" ? ENTRY_IMPORTS_LABEL : SELECTED_IMPORTS_LABEL;
+    const description = entryOnly && choice.fits === false ? SINGLE_FILE_TOO_LARGE_MESSAGE
+        : (entryOnly ? ENTRY_ONLY_DESCRIPTION : imports === "all" ? ENTRY_IMPORTS_DESCRIPTION : SELECTED_IMPORTS_DESCRIPTION)
+            .replace("{entry}", () => choice.scope.entry);
+    return choice.label === label && choice.description === description;
+});
+export const chooseScopeResultSchema = z.strictObject({
+    kind: z.literal("choose_scope"), text: z.literal(CHOOSE_SCOPE_MESSAGE), snapshot: snapshotIdSchema,
+    entry: selectionPathSchema.nullable(), coverageComplete: z.boolean(),
+    frontierCount: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    choices: z.array(scopeChoiceSchema).min(1).max(ANALYSIS_SELECTION_LIMITS.choices),
+    imports: z.array(z.strictObject({ path: selectionPathSchema, role: z.literal("imported-helper"),
+        importedBy: z.array(selectionPathSchema).min(1).max(ANALYSIS_SELECTION_LIMITS.files)
+            .refine(paths => new Set(paths).size === paths.length) })).max(ANALYSIS_SELECTION_LIMITS.files),
+    refusedEdges: z.array(refusedImportSchema).max(ANALYSIS_SELECTION_LIMITS.edges),
+}).refine(value => (!value.coverageComplete || value.frontierCount === 0 && value.refusedEdges.every(edge => edge.reason === "external"))
+    && new Set(value.choices.map(choice => choice.id)).size === value.choices.length
+    && new Set(value.imports.map(file => file.path)).size === value.imports.length
+    && value.choices.every(choice => choice.scope.snapshot === value.snapshot && (value.entry === null || choice.scope.entry === value.entry
+        && (choice.scope.imports !== "all" || choice.omitted.length === 0))));
+export const chooseScopeMcpResultSchema = z.strictObject({
+    content: z.tuple([z.strictObject({ type: z.literal("text"), text: z.string().startsWith(CHOOSE_SCOPE_MESSAGE) })]),
+    isError: z.literal(false), structuredContent: chooseScopeResultSchema.safeExtend({ exitCode: z.literal(0) }),
+});
+export const SCOPE_CHOICE_EXIT_CODE = 3;

package/dist/contract/selection-metadata.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+export const selectionStartIdentitySchema = z.strictObject({ version: z.literal(1), key: digest, snapshot: digest });
+/** The console can distinguish selected runs without receiving local coordinates or snapshot contents. */
+export function selectionStartIdentity(key, snapshot) {
+    const hash = (value) => createHash("sha256").update(value).digest("hex");
+    return { version: 1, key: hash(key), snapshot: hash(snapshot) };
+}

package/dist/contract/selection-offer.js

@@ -0,0 +1,43 @@
+import { CHOOSE_SCOPE_MESSAGE, ENTRY_IMPORTS_DESCRIPTION, ENTRY_IMPORTS_LABEL, ENTRY_ONLY_DESCRIPTION, ENTRY_ONLY_LABEL, SELECTED_IMPORTS_DESCRIPTION, SELECTED_IMPORTS_LABEL, SINGLE_FILE_TOO_LARGE_MESSAGE } from "./scope-choice.js";
+export class ScopeChoiceError extends Error {
+    choice;
+    constructor(choice) {
+        super(choice.text);
+        this.choice = choice;
+    }
+}
+/** A known nonfitting choice must never invite another paid attempt. */
+export function scopeChoiceRefusal(choice) {
+    return choice.choices.every(option => option.fits === false) ? SINGLE_FILE_TOO_LARGE_MESSAGE : undefined;
+}
+/** Membership choices are proven by core; fewer files alone never prove that a run fits. */
+export function selectionScopeChoices(membership, options = {}) {
+    const current = new Set(options.currentPaths ?? membership.files.map(file => file.path));
+    const oversized = new Set(options.oversizedPaths ?? []);
+    const seen = new Set();
+    const choices = membership.choices.flatMap(choice => {
+        const entryOnly = choice.scope.imports === "none" || Array.isArray(choice.scope.imports) && choice.scope.imports.length === 0;
+        const knownOversized = entryOnly && oversized.has(choice.scope.entry);
+        const identical = choice.includes.length === current.size && choice.includes.every(path => current.has(path));
+        const key = JSON.stringify([...choice.includes].sort());
+        if (seen.has(key) || choice.includes.some(path => !current.has(path)) || identical && !knownOversized)
+            return [];
+        seen.add(key);
+        const label = entryOnly ? ENTRY_ONLY_LABEL : choice.scope.imports === "all" ? ENTRY_IMPORTS_LABEL : SELECTED_IMPORTS_LABEL;
+        const description = knownOversized ? SINGLE_FILE_TOO_LARGE_MESSAGE
+            : (entryOnly ? ENTRY_ONLY_DESCRIPTION : choice.scope.imports === "all" ? ENTRY_IMPORTS_DESCRIPTION : SELECTED_IMPORTS_DESCRIPTION)
+                .replace("{entry}", () => choice.scope.entry);
+        return [{ ...choice, label, description, fits: knownOversized ? false : "unknown" }];
+    });
+    if (!choices.length)
+        return undefined;
+    const imports = membership.files.flatMap(file => {
+        if (file.role !== "imported-helper")
+            return [];
+        const importedBy = [...new Set(membership.edges.filter(edge => edge.path === file.path).map(edge => edge.from))];
+        return importedBy.length ? [{ path: file.path, role: "imported-helper", importedBy }] : [];
+    });
+    return { kind: "choose_scope", text: CHOOSE_SCOPE_MESSAGE, snapshot: membership.snapshot,
+        entry: membership.kind === "file" ? membership.entry : null, coverageComplete: membership.completeness.complete,
+        frontierCount: membership.completeness.frontierCount, choices, imports, refusedEdges: membership.refusedEdges };
+}

package/dist/gatekeeper/console.js

@@ -2,7 +2,7 @@ import { consoleSchemeAllowed } from "../contract/console-url.js";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { CLI_VERSION } from "../contract/cli-version.js";
-import { cliRefusals, FINISH_FAILURE_MESSAGE, RESERVATION_EXPIRED_MESSAGE, RESULTS_TOO_LARGE_MESSAGE, START_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
+import { cliRefusals, NOT_ALLOWED_MESSAGE, SIGN_IN_EXPIRED_MESSAGE, CHECK_CONFLICT_MESSAGE, UNSAVED_RESULTS_MESSAGE, FINISH_FAILURE_MESSAGE, RESERVATION_EXPIRED_MESSAGE, RESULTS_TOO_LARGE_MESSAGE, START_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
 import { cliRelayReservationRequestSchema, consoleCreatedSchema, consoleIntakeResultSchema, consoleReservationSchema, consoleStatusSchema, LOCAL_FINDINGS_BODY_LIMIT, localFindingsPayloadSchema, LOCAL_START_BODY_LIMIT, LOCAL_START_EXECUTION_HEADER, localStartRequestSchema, localStartResponseSchema, serializeLocalStartMetadata } from "../contract/console.js";
 const RESPONSE_LIMIT = 64 * 1024;
 const RESERVATION_BODY_LIMIT = 64 * 1024;
@@ -11,19 +11,22 @@ export const consoleErrorMessages = {
     invalid_configuration: START_FAILURE_MESSAGE,
     invalid_request: FINISH_FAILURE_MESSAGE,
     unavailable: "The results couldn't be saved yet. Run the analysis on the same folder again to save them; you won't be charged again.",
-    unauthorized: "Your sign-in has expired. Run counterfact-labs login, then try again.",
-    not_allowed: "Your account can't run analyses. Ask Counterfact for access.",
+    unauthorized: SIGN_IN_EXPIRED_MESSAGE,
+    not_allowed: NOT_ALLOWED_MESSAGE,
     not_found: "Counterfact couldn't find this analysis. Start a new analysis.",
     rate_limited: "Counterfact is busy. Try again in a minute.",
-    reservation_closed: "The analysis ended before its results were saved. Start a new analysis.",
+    reservation_closed: UNSAVED_RESULTS_MESSAGE,
     reservation_closing: "The results are still being saved. Run the analysis on the same folder again in a minute.",
-    delivery_incomplete: "The analysis ended before its results were saved. Start a new analysis.",
-    check_conflict: "Saved results from an earlier run don't match this analysis. Start a new analysis.",
+    delivery_incomplete: UNSAVED_RESULTS_MESSAGE,
+    check_conflict: CHECK_CONFLICT_MESSAGE,
 };
 export class ConsoleError extends Error {
     code;
     reason;
-    constructor(code = "unavailable", context, localReason) {
+    localReason;
+    responseCode;
+    httpStatus;
+    constructor(code = "unavailable", context, options = {}) {
         let message = consoleErrorMessages[code];
         let reason = code === "unavailable" ? "results_not_saved" : code;
         if (context === "start" && (code === "unavailable" || code === "invalid_request" || code === "not_found")) {
@@ -39,7 +42,10 @@ export class ConsoleError extends Error {
         super(message);
         this.name = "ConsoleError";
         this.code = code;
-        this.reason = localReason ?? reason;
+        this.reason = options.localReason ?? reason;
+        this.localReason = options.localReason;
+        this.responseCode = options.responseCode;
+        this.httpStatus = options.httpStatus;
     }
 }
 export const isConsoleToken = (token) => /^[\x21-\x7e]{1,4096}$/.test(token);
@@ -54,15 +60,15 @@ export class ConsoleClient {
             url = new URL(options.url);
             if (!consoleSchemeAllowed(url)
                 || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
-                throw new ConsoleError("invalid_configuration", undefined, "invalid_console_url");
+                throw new ConsoleError("invalid_configuration", undefined, { localReason: "invalid_console_url" });
             }
         }
         catch {
-            throw new ConsoleError("invalid_configuration", undefined, "invalid_console_url");
+            throw new ConsoleError("invalid_configuration", undefined, { localReason: "invalid_console_url" });
         }
         const timeout = options.timeoutMs ?? 15_000;
         if (!isConsoleToken(options.token) || !Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 120_000) {
-            throw new ConsoleError("invalid_configuration", undefined, "request_failed");
+            throw new ConsoleError("invalid_configuration", undefined, { localReason: "request_failed" });
         }
         this.#url = url;
         this.#token = options.token;
@@ -93,8 +99,8 @@ export class ConsoleClient {
     fail(reservationId) {
         return this.#lifecycle({ action: "fail", reservationId }, consoleStatusSchema);
     }
-    intake(input) {
-        return this.#send("/api/cli/checks/local", input, localFindingsPayloadSchema, consoleIntakeResultSchema, LOCAL_FINDINGS_BODY_LIMIT, { statuses: [200, 201], context: "intake" });
+    intake(input, options = {}) {
+        return this.#send("/api/cli/checks/local", input, localFindingsPayloadSchema, consoleIntakeResultSchema, LOCAL_FINDINGS_BODY_LIMIT, { statuses: [200, 201], context: "intake", ...options });
     }
     #lifecycle(input, response) {
         // Starting work has no saved results to retry; recovery keeps its saving guidance.
@@ -120,7 +126,8 @@ export class ConsoleClient {
             throw new ConsoleError("invalid_request", options.context);
         }
         return new Promise((resolve, reject) => {
-            let settled = false;
+            let settled = false, responseStatus;
+            const interrupted = () => new ConsoleError("unavailable", undefined, { httpStatus: responseStatus });
             const finish = (error, result) => {
                 if (settled)
                     return;
@@ -139,12 +146,16 @@ export class ConsoleClient {
                     ...options.headers },
             }, response => {
                 const status = response.statusCode ?? 0;
+                responseStatus = status;
+                const accepted = options.acceptAnySuccess ? status >= 200 && status < 300 : (options.statuses ?? [200]).includes(status);
+                // Keep delivery status separate from validated receipt details.
+                const responseError = (code) => new ConsoleError(typeof code === "string" && Object.hasOwn(consoleErrorMessages, code) ? code : "unavailable", undefined, { responseCode: typeof code === "string" ? code : undefined, httpStatus: status });
                 const declared = response.headers["content-length"];
                 const contentType = response.headers["content-type"] ?? "";
                 if (status >= 300 && status < 400 || !/^application\/json(?:\s*;|$)/i.test(contentType)
                     || response.headers["content-encoding"] && response.headers["content-encoding"] !== "identity"
                     || declared && (!/^\d+$/.test(declared) || Number(declared) > RESPONSE_LIMIT)) {
-                    finish(new ConsoleError());
+                    finish(responseError());
                     response.destroy();
                     return;
                 }
@@ -153,37 +164,37 @@ export class ConsoleClient {
                 response.on("data", (chunk) => {
                     size += chunk.length;
                     if (size > RESPONSE_LIMIT) {
-                        finish(new ConsoleError());
+                        finish(responseError());
                         response.destroy();
                     }
                     else
                         chunks.push(chunk);
                 });
-                response.on("error", () => finish(new ConsoleError()));
-                response.on("aborted", () => finish(new ConsoleError()));
+                response.on("error", () => finish(interrupted()));
+                response.on("aborted", () => finish(interrupted()));
                 response.on("end", () => {
                     try {
                         const decoded = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-                        if (!(options.statuses ?? [200]).includes(status)) {
+                        if (!accepted) {
                             const code = decoded && typeof decoded === "object" && "code" in decoded ? decoded.code : undefined;
-                            throw new ConsoleError(typeof code === "string" && Object.hasOwn(consoleErrorMessages, code) ? code : "unavailable");
+                            throw responseError(code);
                         }
                         const result = responseSchema.parse(decoded);
                         for (const [field, expected] of Object.entries(identities)) {
                             if (result[field] !== expected)
-                                throw new ConsoleError();
+                                throw responseError();
                         }
                         finish(undefined, result);
                     }
                     catch (error) {
-                        finish(error instanceof ConsoleError ? error : new ConsoleError());
+                        finish(error instanceof ConsoleError ? error : responseError());
                     }
                 });
             });
             // Use one wall-clock deadline: an idle timeout alone lets a trickling response run forever.
-            const timer = setTimeout(() => { finish(new ConsoleError()); request.destroy(); }, this.#timeoutMs);
-            request.on("error", () => finish(new ConsoleError()));
+            const timer = setTimeout(() => { finish(interrupted()); request.destroy(); }, this.#timeoutMs);
+            request.on("error", () => finish(interrupted()));
             request.end(body);
-        }).catch(error => { throw new ConsoleError(error instanceof ConsoleError ? error.code : "unavailable", options.context); });
+        }).catch(error => { throw new ConsoleError(error instanceof ConsoleError ? error.code : "unavailable", options.context, error instanceof ConsoleError ? { localReason: error.localReason, responseCode: error.responseCode, httpStatus: error.httpStatus } : {}); });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@counterfact-labs/cli",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "homepage": "https://counterfactlabs.com",
   "relaySource": "https://github.com/counterfact-labs/sealed-relay",
   "type": "module",
@@ -20,7 +20,7 @@
     "bench:replay": "tsx bench/replay.ts",
     "bench:importer": "tsx bench/importer-coverage.ts",
     "typecheck": "tsc --noEmit",
-    "test": "tsx --test ${TEST_SHARD:+--test-shard=$TEST_SHARD} --test-concurrency=4 --test-timeout=600000 \"core/**/*.test.ts\" \"adapters/**/*.test.ts\" \"cli/**/*.test.ts\" \"bench/**/*.test.ts\" \"bundle/**/*.test.ts\" \"contract/**/*.test.ts\" \"gatekeeper/**/*.test.ts\" \"relay/**/*.test.ts\" \"transport/**/*.test.ts\" \"packages/core/src/**/*.test.ts\" \"packages/core/*.test.ts\" \"packages/setup-pings/src/**/*.test.ts\" \"scripts/**/*.test.ts\"",
+    "test": "tsx --test ${TEST_SHARD:+--test-shard=$TEST_SHARD} --test-concurrency=4 --test-timeout=600000 \"core/**/*.test.ts\" \"adapters/**/*.test.ts\" \"cli/**/*.test.ts\" \"bench/**/*.test.ts\" \"bundle/**/*.test.ts\" \"contract/**/*.test.ts\" \"gatekeeper/**/*.test.ts\" \"relay/**/*.test.ts\" \"transport/**/*.test.ts\" \"packages/core/src/**/*.test.ts\" \"packages/core/*.test.ts\" \"packages/setup-pings/src/**/*.test.ts\" \"scripts/**/*.test.ts\" \".github/scripts/*.test.ts\"",
     "build:core": "npm run build --workspace @counterfact-labs/analysis-core",
     "build:setup-pings": "npm run build --workspace @counterfact-labs/setup-pings",
     "pretest": "npm run build:core && npm run build:setup-pings",